Local Extension Marketplace

Build a schema-v2 Catalog

Export one defineCatalog({ id, label, summary?, extensions }) value from the single module declared in the author package's package.json. Entries are versionless literal Extensions or packageExtension({ kind, target }, extensionId) descriptors for npm, Git, and local targets.

{
  "ctxindex": {
    "extensions": ["./catalog.ts"]
  }
}

import { defineCatalog, packageExtension } from '@ctxindex/extension-sdk'

export default defineCatalog({
  id: 'community.catalog',
  label: 'Community',
  extensions: [
    packageExtension(
      { kind: 'git', target: 'git+https://example.com/mail.git#main' },
      'community.mail',
    ),
    packageExtension(
      { kind: 'local', target: './extensions/calendar' },
      'community.calendar',
    ),
  ],
})

Build trust is required before ctxindex acquires packages, invokes Bun, or imports the author module. The package does not need to be published to npm.

ctxindex extensions catalog build ./community-author \
  --catalog community.catalog \
  --output ./dist/ctxindex-catalog.json \
  --trust \
  --json

Add and search a Git Catalog

Adding a repository has its own trust acknowledgement:

ctxindex extensions catalog add community https://example.com/catalog.git \
  --ref refs/heads/main \
  --trust \
  --json

ctxindex extensions search mail --json
ctxindex extensions catalog show community community.mail --json

Marketplace search retains matching curation rows from every configured Catalog, including duplicate stable ids across Catalogs. Search, list, and show refresh by default. Use stored state deliberately with --no-refresh; offline output reports the stored snapshot age.

ctxindex extensions search mail --no-refresh --json
ctxindex extensions catalog list --no-refresh --json
ctxindex extensions catalog show community --no-refresh --json

Install and remove

Installing executable code requires trust independently of authoring and repository acquisition. Select the configured Catalog and stable, versionless Extension id:

ctxindex extensions install community community.mail --trust --json
ctxindex extensions list --json

Install refreshes only the selected Catalog by default. Add --no-refresh to install from its stored snapshot. On success, exact replayed bytes are published to generic content-addressed storage. Startup and listing then use only that installed record and managed materialization, without the network, Bun package execution, Catalog checkout, or author checkout.

A later trusted install may replace the record only when its configured Catalog name and Catalog id match. Collisions with a direct install, another Catalog, a built-in, or an explicit path require uninstalling the existing Extension first.

Uninstall works the same for direct and Catalog-curated records and does not require Catalog availability:

ctxindex extensions uninstall community.mail --json
ctxindex extensions catalog remove community --json

Uninstall is blocked while configured Sources require the Extension's Adapter unless --force is supplied; forced removal preserves those Sources and their data as unavailable. Catalog removal is blocked until no installed record cites that configured Catalog.