Author a Catalog

A Catalog is optional curation. It can export literal Extension values from the author package and descriptors pointing to npm, Git, or contained local packages.

See the runnable barisgit.ctxindex-extensions Catalog and its committed ctxindex-catalog.json before authoring your own.

import {
  defineCatalog,
  packageExtension,
} from '@ctxindex/extension-sdk'
import localNotes from './local-notes'

export default defineCatalog({
  id: 'acme.catalog',
  label: 'Acme context',
  summary: 'Reviewed Acme Extensions.',
  entrySummaries: {
    'acme.local-notes': 'Index local Acme notes.',
    'acme.mail': 'Search Acme mail.',
  },
  extensions: [
    localNotes,
    packageExtension(
      { kind: 'npm', target: '@acme/ctxindex-mail@^2' },
      'acme.mail',
    ),
    packageExtension(
      { kind: 'git', target: 'git+https://github.com/acme/tasks.git#main' },
      'acme.tasks',
    ),
    packageExtension(
      { kind: 'local', target: './packages/calendar' },
      'acme.calendar',
    ),
  ],
})

Catalogs do not nest. A Catalog entry is a literal Extension or one packageExtension(source, extensionId) descriptor—not another Catalog or a textual dependency reference.

Build and trust

ctxindex extension catalog build . \
  --catalog acme.catalog \
  --output ./dist/ctxindex-catalog.json \
  --trust \
  --format json

Build trust covers author-controlled module import, package acquisition, and Bun execution. The deterministic snapshot contains bounded inert metadata and replay-locked artifacts. Catalog add/refresh/list/show/search parse data and never import Catalog modules.

Install has a second trust gate because it exactly replays and activates the selected Extension. Catalog refresh does not silently update installed bytes.

Use a Catalog when curated discovery is valuable. Direct npm/Git/local installation remains the lower-friction distribution path for many Extensions.

Verify the user path

Test the exact repository URL and ref a user will add:

ctxindex extension catalog add community \
  https://github.com/barisgit/ctxindex-extensions.git \
  --ref refs/heads/main \
  --trust
ctxindex extension catalog show community --format json
ctxindex extension catalog search github --format json
ctxindex extension install catalog community barisgit.github-issues --format json

Search and install refresh the involved Catalog by default. --no-refresh deliberately uses the stored snapshot and reports its age. Startup never refreshes Catalogs or silently updates installed Extension bytes.