ctxindex extensions

Extensions bundle Profiles, Providers, OAuth Apps, and Source Adapters. External Extensions are trusted code loaded from explicit paths, installed directly from npm, Git, or local packages, or selected from explicitly added Git Catalogs. Catalogs form one local Marketplace; ctxindex does not operate a hosted marketplace.

Usage

ctxindex extensions list [--json]
ctxindex extensions search [query] [--no-refresh] [--json]
ctxindex extensions catalog build <package-root> [--catalog <id>] [--output <manifest-path>] --trust [--json]
ctxindex extensions catalog add <name> <repository> --ref <full-ref-or-oid> --trust [--json]
ctxindex extensions catalog list [--no-refresh] [--json]
ctxindex extensions catalog show <name> [<extension-id>] [--no-refresh] [--json]
ctxindex extensions catalog refresh <name> [--json]
ctxindex extensions catalog remove <name> [--json]
ctxindex extensions install <catalog> <extension-id> --trust [--no-refresh] [--json]
ctxindex extensions install <npm|git|local> <target> --extension <id> [--json]
ctxindex extensions update <id> [--json]
ctxindex extensions uninstall <id> [--force] [--json]

Author a Catalog

A Catalog is a plain SDK value containing literal Extensions, package-backed entries, or both:

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

const localNotes = defineExtension({ id: 'example.local-notes' })

export default defineCatalog({
  id: 'example.catalog',
  label: 'Example Catalog',
  summary: 'A mixed local Catalog.',
  extensions: [
    localNotes,
    packageExtension(
      { kind: 'npm', target: '@example/mail@^2' },
      'example.mail',
    ),
    packageExtension(
      { kind: 'git', target: 'git+https://example.com/tasks.git#main' },
      'example.tasks',
    ),
    packageExtension(
      { kind: 'local', target: './packages/calendar' },
      'example.calendar',
    ),
  ],
})

The author package declares exactly one ctxindex entry module:

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

Build a deterministic schema-v2 snapshot from that package:

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

Build trust covers author-controlled module import, package acquisition, and Bun execution. The author package and local package targets may remain local; publishing them to npm is not required.

Discover and install

catalog add --trust separately acknowledges acquiring and reading a credential-free public HTTPS or absolute local Git repository. Catalog list, show, Marketplace search, and install refresh their relevant configured Catalogs by default. A refresh failure is reported instead of silently falling back to stale data.

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

Use --no-refresh to read a stored snapshot deliberately; stored output reports snapshot age. Marketplace search only reads validated snapshot metadata and does not execute Extension code.

ctxindex extensions search mail --no-refresh --json
ctxindex extensions catalog show community --no-refresh --json
ctxindex extensions install community example.mail --trust --no-refresh --json

Install trust is independent of build and repository trust. It permits exact replay, import, complete-registry validation, and in-process execution of the selected Extension.

Installed state and removal

Direct and Catalog-selected installs share one generic installation record and immutable managed materialization. Startup and extensions list load those managed bytes offline; they do not refresh a Catalog, contact npm or Git, invoke a package manager, or read the original author/local checkout. Listing reports the exact installed source and, when curated, the stored Catalog name, id, commit, and source locator.

Reinstalling from the same configured Catalog name and Catalog id may atomically replace that Catalog's existing record. A direct install, another Catalog, a built-in, or an explicit path with the same stable id requires uninstalling the existing origin first.

Uninstall is origin-neutral:

ctxindex extensions uninstall example.mail --json

Normal uninstall is blocked while configured Sources require the Extension's Adapter. --force removes activation while preserving those Sources and their data in an unavailable state. Removing a Catalog registration is separately blocked while any installed record still cites that configured Catalog:

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

JSON and failures

All commands above accept --json; loading and acquisition diagnostics are written separately from stdout. A failed build, install, update, replacement, or uninstall guard preserves the prior authoritative record, managed bytes, active definitions, Sources, and Source-owned data.