@frontera-sdk/cli 1.44.1 → 1.45.1

package/src/commands/setup.ts

@@ -0,0 +1,248 @@
+import { spawnSync } from 'node:child_process'
+import { join } from 'node:path'
+
+import { CliError, UsageError } from '../errors'
+import { KIT, materializedVersion, materializeMarketplace } from '../kit'
+import { dataDir } from '../paths'
+import { flagBool, type Command } from './types'
+
+/**
+ * Install the Frontera plugin into a coding host.
+ *
+ * The distribution problem this solves: both Codex and Claude Code install
+ * plugins from a marketplace, and every documented marketplace is a git
+ * repository or a public directory listing. For a tool that only works against
+ * a customer's own deployment, publishing one is the wrong shape — it puts an
+ * internal harness in a public index to solve a local installation problem.
+ *
+ * So the CLI is the marketplace. It already carries every byte of the kit,
+ * pinned at build time, and both hosts accept a local DIRECTORY as a
+ * marketplace source. `frontera setup` writes one under the user's data
+ * directory and points the host at it: nothing published, nothing hosted,
+ * nothing leaving the machine, and no network required.
+ *
+ * Registration goes through each host's OWN CLI rather than by editing its
+ * settings file. Writing another tool's configuration is a thing that works
+ * until their next release; asking the tool to do it is a thing that keeps
+ * working.
+ */
+
+type HostId = 'codex' | 'claude'
+
+interface Host {
+  id: HostId
+  label: string
+  bin: string
+  /** Verbs differ: Codex `plugin add`, Claude `plugin install`. */
+  install: string[]
+  marketplaceList: string[]
+  installHint: string
+}
+
+const HOSTS: Record<HostId, Host> = {
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    bin: 'codex',
+    install: ['plugin', 'add', 'frontera@frontera'],
+    marketplaceList: ['plugin', 'marketplace', 'list'],
+    installHint: 'install Codex first — https://developers.openai.com/codex',
+  },
+  claude: {
+    id: 'claude',
+    label: 'Claude Code',
+    bin: 'claude',
+    install: ['plugin', 'install', 'frontera@frontera'],
+    marketplaceList: ['plugin', 'marketplace', 'list'],
+    installHint: 'install Claude Code first — https://claude.com/claude-code',
+  },
+}
+
+const ALIASES: Record<string, HostId> = {
+  codex: 'codex',
+  claude: 'claude',
+  'claude-code': 'claude',
+  claudecode: 'claude',
+}
+
+function run(bin: string, args: string[]): { ok: boolean; out: string; missing: boolean } {
+  const res = spawnSync(bin, args, { encoding: 'utf8' })
+  // ENOENT is "the host is not installed", which is a different answer from
+  // "the host refused" and gets a different message.
+  if (res.error && (res.error as NodeJS.ErrnoException).code === 'ENOENT') {
+    return { ok: false, out: '', missing: true }
+  }
+  const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.trim()
+  return { ok: res.status === 0, out, missing: false }
+}
+
+function isInstalled(host: Host): boolean {
+  return !run(host.bin, ['--version']).missing
+}
+
+/**
+ * Where a marketplace named `frontera` currently points, if one is registered.
+ *
+ * Worth asking, because `plugin marketplace add` on an existing NAME silently
+ * repoints it — verified against Claude Code, which replaced a checkout path
+ * with this one without a word. Someone developing the plugin from a checkout
+ * would find their edits stop being read and nothing would have told them.
+ */
+function registeredMarketplace(host: Host): string | null {
+  if (host.id === 'claude') {
+    const listed = run(host.bin, ['plugin', 'marketplace', 'list', '--json'])
+    if (!listed.ok) return null
+    try {
+      const rows = JSON.parse(listed.out) as Array<{ name?: string; path?: string; repo?: string }>
+      const row = rows.find((r) => r.name === 'frontera')
+      return row?.path ?? row?.repo ?? null
+    } catch {
+      return null
+    }
+  }
+
+  // Codex prints the manifest path on the line after the marketplace header.
+  const listed = run(host.bin, host.marketplaceList)
+  if (!listed.ok) return null
+  const lines = listed.out.split('\n')
+  const header = lines.findIndex((l) => l.includes('Marketplace `frontera`'))
+  if (header === -1) return null
+  const manifest = lines[header + 1]?.trim()
+  if (!manifest) return null
+  // Back out of `.agents/plugins/marketplace.json` to the marketplace root.
+  return manifest.replace(/\/(\.agents\/plugins|\.claude-plugin)\/marketplace\.json$/, '')
+}
+
+export const setupCommand: Command = {
+  meta: {
+    noun: 'setup',
+    verb: '',
+    args: [
+      {
+        name: 'host',
+        required: false,
+        description: 'coding host to set up: codex or claude (default: every one installed)',
+      },
+    ],
+    flags: { force: 'boolean' },
+    summary: 'Install the Frontera plugin into Codex or Claude Code',
+    examples: ['frontera setup', 'frontera setup codex', 'frontera setup claude --force'],
+    // It configures a coding host. No credential is involved, and requiring one
+    // would make this impossible to run before `auth add`.
+    offline: true,
+  },
+
+  async run(ctx) {
+    const [named] = ctx.positional
+    if (named && !ALIASES[named.toLowerCase()]) {
+      throw new UsageError(
+        `unknown host: ${named}`,
+        'pass `codex` or `claude`, or run `frontera setup` on its own to set up every host installed here',
+      )
+    }
+
+    const requested: HostId[] = named
+      ? [ALIASES[named.toLowerCase()]!]
+      : (Object.keys(HOSTS) as HostId[]).filter((id) => isInstalled(HOSTS[id]))
+
+    if (requested.length === 0) {
+      throw new CliError('no supported coding host is installed here', {
+        code: 'NOT_FOUND',
+        hint: 'install Codex or Claude Code, then run `frontera setup` again',
+      })
+    }
+
+    const root = join(dataDir(), 'harness')
+    const before = materializedVersion(root)
+    const stale = before !== KIT.kitVersion
+    if (stale || flagBool(ctx, 'force')) materializeMarketplace(root)
+
+    const results: Array<{
+      host: HostId
+      installed: boolean
+      marketplace: string
+      error?: string
+    }> = []
+
+    for (const id of requested) {
+      const host = HOSTS[id]
+
+      if (!isInstalled(host)) {
+        // Named explicitly, so silence would be wrong — the person asked for
+        // this host by name.
+        throw new CliError(`${host.label} is not installed`, {
+          code: 'NOT_FOUND',
+          hint: host.installHint,
+        })
+      }
+
+      /**
+       * Refuse to take a name someone else is using.
+       *
+       * The host would repoint it silently, which is the wrong default when the
+       * other source is almost always a deliberate checkout of the authoring
+       * repository. `--force` is how you say you meant it.
+       */
+      const existing = registeredMarketplace(host)
+      if (existing && existing !== root && !flagBool(ctx, 'force')) {
+        throw new CliError(
+          `${host.label} already has a \`frontera\` marketplace, pointing at ${existing}`,
+          {
+            code: 'USAGE',
+            hint:
+              `re-run with --force to point it at ${root}, `
+              + `or keep the existing one and skip this — it already provides the plugin`,
+          },
+        )
+      }
+
+      const added = run(host.bin, ['plugin', 'marketplace', 'add', root])
+      if (!added.ok) {
+        results.push({ host: id, installed: false, marketplace: root, error: added.out })
+        continue
+      }
+
+      // Refresh, because `add` on an already-registered marketplace is a no-op
+      // and the tree underneath it may have just been rewritten by a CLI
+      // upgrade. Not every host has this verb; a failure here is not fatal.
+      run(host.bin, ['plugin', 'marketplace', 'update', 'frontera'])
+
+      const installed = run(host.bin, host.install)
+      results.push({
+        host: id,
+        installed: installed.ok,
+        marketplace: root,
+        ...(installed.ok ? {} : { error: installed.out }),
+      })
+    }
+
+    const failed = results.filter((r) => !r.installed)
+    const data = {
+      kitVersion: KIT.kitVersion,
+      marketplace: root,
+      rematerialized: stale || flagBool(ctx, 'force'),
+      previousKitVersion: before,
+      hosts: results,
+    }
+
+    if (failed.length === requested.length) {
+      throw new CliError(`could not install the plugin into ${failed.map((f) => HOSTS[f.host].label).join(' or ')}`, {
+        code: 'INTERNAL_ERROR',
+        hint: failed[0]?.error?.split('\n')[0] ?? 'run the host’s own `plugin install` to see why',
+      })
+    }
+
+    const lines = [
+      `Frontera plugin ${KIT.kitVersion} — ${Object.keys(KIT.assets).length} skill files`,
+      `  marketplace ${root}`,
+      ...results.map((r) =>
+        r.installed
+          ? `  + ${HOSTS[r.host].label}`
+          : `  · ${HOSTS[r.host].label} failed — ${r.error?.split('\n')[0] ?? 'unknown'}`,
+      ),
+      '  restart the host to pick it up',
+    ]
+
+    return { data, text: lines.join('\n') }
+  },
+}

package/src/commands/source/index-commands.ts

@@ -0,0 +1,446 @@
+import { readFileSync } from 'node:fs'
+
+import { DatasetApi } from '../../api/dataset-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagString, type Command } from '../types'
+
+/**
+ * Connected Sources — where a Dataset's rows come from.
+ *
+ * `dataset create --from-source` names one, and until now nothing could make
+ * one, so a scripted organization stand-up always broke at the same step: open
+ * the Console, provision the Source by hand, come back. `dataset sources` and
+ * `dataset test-source` still work and still list and test; everything that
+ * WRITES a Source lives here.
+ *
+ * Two rules the service imposes and this noun surfaces rather than hides:
+ *
+ *   The password never travels in the definition file. It is read from stdin
+ *   with `--password-from -`, for the reason `secret set` gives: a credential
+ *   written into a committed file is a credential in the repository. The
+ *   definition file carries everything else.
+ *
+ *   Writes are optimistically concurrent. `update`, `revise` and `disable` all
+ *   take a token from `source get` and are refused if the Source moved, which
+ *   exits 3 — re-read, reapply, retry. Never force; there is no force.
+ */
+
+interface SourceFile {
+  displayName?: unknown
+  description?: unknown
+  config?: unknown
+  datasets?: unknown
+}
+
+/** The definition file, minus the one field it is not allowed to carry. */
+function readSourceFile(path: string): SourceFile {
+  const raw = path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (e) {
+    throw new CliError(`${path === '-' ? 'stdin' : path} is not valid JSON: ${(e as Error).message}`, {
+      code: 'USAGE',
+      hint: 'the file holds { displayName, config, datasets } — see `frontera source get <id> --json`',
+    })
+  }
+  const doc = parsed as SourceFile
+  const config = doc.config as Record<string, unknown> | undefined
+
+  // Refused, not stripped. Silently dropping it would leave a caller believing
+  // the file is the whole story, and the next person to read the repo would
+  // find a password sitting in it.
+  if (config && 'password' in config) {
+    throw new CliError('the definition file carries `config.password`', {
+      code: 'USAGE',
+      hint: 'remove it and pass the value with --password-from - (stdin) or --password-from ./file',
+    })
+  }
+  return doc
+}
+
+/**
+ * Both the definition and the password can come from stdin — but not at once.
+ *
+ * There is one stdin. `--file - --password-from -` reads the whole stream into
+ * the definition and leaves the password read with nothing, which surfaces as
+ * "the password is empty" and sends the caller looking at their password
+ * instead of at the two dashes.
+ */
+function refuseSharedStdin(file: string | undefined, passwordFrom: string): void {
+  if (file === '-' && passwordFrom === '-') {
+    throw new CliError('--file and --password-from cannot both read stdin', {
+      code: 'USAGE',
+      hint: 'keep --password-from - and pass the definition as a path, or the other way round',
+    })
+  }
+}
+
+/** stdin or a file. Never an inline value — same rule as `secret set`. */
+function readPassword(from: string): string {
+  const raw = from === '-' ? readFileSync(0, 'utf8') : readFileSync(from, 'utf8')
+  // Trailing newline is what `echo` adds and what nobody means to include.
+  const value = raw.replace(/\r?\n$/, '')
+  if (!value) {
+    throw new CliError('the password is empty', {
+      code: 'USAGE',
+      hint: from === '-' ? 'pipe it in: `printf %s "$PW" | frontera source create …`' : `${from} has no content`,
+    })
+  }
+  return value
+}
+
+/**
+ * Check the dataset definitions before sending them.
+ *
+ * The service's refusal for this body is actively misleading. `strictJsonBody`
+ * validates first and, on failure, substitutes a SENTINEL body — which omits
+ * `mode` — and Elysia then validates the sentinel, so a definition missing
+ * `nullable` on a column comes back as "Expected 'virtual' at
+ * /datasets/0/mode": a field the caller set correctly, named as the fault.
+ *
+ * So these are checked here, where the message can name the real field. Same
+ * reason `dataset create` validates its own columns rather than relying on the
+ * round trip.
+ */
+export function validateDatasets(datasets: unknown[], path: string): void {
+  datasets.forEach((entry, index) => {
+    const where = `${path}: datasets[${index}]`
+    const dataset = entry as Record<string, unknown>
+    if (!dataset || typeof dataset !== 'object') {
+      throw new CliError(`${where} is not a mapping.`, {
+        code: 'USAGE',
+        hint: '{ apiName, displayName, mode, definition, deterministicKeyConfirmed }',
+      })
+    }
+    if (dataset.mode !== 'virtual') {
+      throw new CliError(`${where} has mode ${JSON.stringify(dataset.mode)}.`, {
+        code: 'USAGE',
+        // `managed` exists in the domain but cannot be asked for — the service
+        // reserves it for a later ingestion slice.
+        hint: 'mode must be "virtual"; `managed` is not creatable',
+      })
+    }
+    if (typeof dataset.deterministicKeyConfirmed !== 'boolean') {
+      throw new CliError(`${where} does not set \`deterministicKeyConfirmed\`.`, {
+        code: 'USAGE',
+        hint: 'true asserts the primary key uniquely identifies a row; it is not defaulted',
+      })
+    }
+    const definition = dataset.definition as Record<string, unknown> | undefined
+    const columns = definition?.columns
+    if (!Array.isArray(columns) || columns.length === 0) {
+      throw new CliError(`${where} declares no \`definition.columns\`.`, {
+        code: 'USAGE',
+        hint: 'columns: [{ name, ordinal, databaseType, nullable }] — at least one',
+      })
+    }
+    columns.forEach((raw, position) => {
+      const column = raw as Record<string, unknown>
+      const at = `${where}: definition.columns[${position}]`
+      for (const [field, ok] of [
+        ['name', typeof column?.name === 'string' && column.name.length > 0],
+        ['ordinal', Number.isInteger(column?.ordinal) && (column.ordinal as number) >= 1],
+        ['databaseType', typeof column?.databaseType === 'string' && column.databaseType.length > 0],
+        // The one that produced the misleading error, and the easiest to omit:
+        // it is a boolean with no sensible default, and a Blueprint `required`
+        // property may not read a nullable column.
+        ['nullable', typeof column?.nullable === 'boolean'],
+      ] as const) {
+        if (!ok) {
+          throw new CliError(`${at} has no usable \`${field}\`.`, {
+            code: 'USAGE',
+            hint: 'each column needs { name, ordinal (1-based), databaseType, nullable }',
+          })
+        }
+      }
+    })
+    if (!Array.isArray(definition?.primaryKey) || definition.primaryKey.length === 0) {
+      throw new CliError(`${where} declares no \`definition.primaryKey\`.`, {
+        code: 'USAGE',
+        hint: 'primaryKey: ["<column>"] — at least one column name',
+      })
+    }
+  })
+}
+
+function requireConfig(doc: SourceFile, path: string): Record<string, unknown> {
+  if (!doc.config || typeof doc.config !== 'object') {
+    throw new CliError(`${path} declares no \`config\`.`, {
+      code: 'USAGE',
+      hint: 'config: { kind: "postgres", host, port, database, username, sslMode, connectTimeoutMs }',
+    })
+  }
+  return doc.config as Record<string, unknown>
+}
+
+const list: Command = {
+  meta: {
+    noun: 'source',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List the connected Sources in this organization',
+    examples: ['frontera source list', 'frontera source list --json'],
+  },
+  async run(ctx) {
+    const rows = await new DatasetApi(ctx.apiUrl, ctx.token).listSources()
+    return {
+      data: rows,
+      text: rows.length === 0
+        ? 'No connected Sources.\n  `frontera source create --file ./source.json --password-from -`'
+        : table(
+            ['displayName', 'connector', 'status', 'id'],
+            rows.map((s) => [
+              s.displayName ?? '?',
+              s.connectorType ?? '',
+              s.status ?? '',
+              s.id ?? '',
+            ]),
+            [30, 14, 14, undefined],
+          ),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'source',
+    verb: 'get',
+    args: [{ name: 'source', required: true, description: 'Source id, from `frontera source list`' }],
+    flags: {},
+    summary: 'Show one Source, with the tokens a write to it needs',
+    examples: ['frontera source get <sourceId>', 'frontera source get <sourceId> --json'],
+  },
+  async run(ctx) {
+    const sourceId = ctx.positional[0]
+    if (!sourceId) throw new UsageError('missing <source>', 'frontera source list')
+
+    const source = await new DatasetApi(ctx.apiUrl, ctx.token).getSource(sourceId)
+    return {
+      data: source,
+      // `updatedAt` and the current revision are printed with everything else
+      // because they are the inputs to `update`, `revise` and `disable` — a
+      // caller reads them here or guesses them nowhere.
+      text: table(
+        ['field', 'value'],
+        Object.entries(source).map(([k, v]) => [
+          k,
+          v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
+        ]),
+        [undefined, 70],
+      ),
+    }
+  },
+}
+
+const create: Command = {
+  meta: {
+    noun: 'source',
+    verb: 'create',
+    args: [],
+    flags: { file: 'string', 'password-from': 'string' },
+    aliases: { f: 'file' },
+    summary: 'Provision a Source and the Datasets it carries',
+    examples: [
+      'frontera source create --file ./source.json --password-from -',
+      'frontera source create -f ./source.json --password-from ./pw.txt',
+    ],
+  },
+  async run(ctx) {
+    const file = flagString(ctx, 'file')
+    if (!file) {
+      throw new UsageError(
+        'missing --file',
+        'the definition holds { displayName, config, datasets }; the password comes from --password-from',
+      )
+    }
+    const passwordFrom = flagString(ctx, 'password-from')
+    if (!passwordFrom) {
+      throw new UsageError(
+        'missing --password-from',
+        'pass `-` to read the password from stdin, or a file path. Never an inline value',
+      )
+    }
+
+    refuseSharedStdin(file, passwordFrom)
+    const doc = readSourceFile(file)
+    if (typeof doc.displayName !== 'string' || !doc.displayName) {
+      throw new CliError(`${file} declares no \`displayName\`.`, {
+        code: 'USAGE',
+        hint: 'displayName is what `frontera source list` shows',
+      })
+    }
+    if (!Array.isArray(doc.datasets) || doc.datasets.length === 0) {
+      throw new CliError(`${file} declares no \`datasets\`.`, {
+        code: 'USAGE',
+        // Not optional at the service either — a Source with no Dataset reads
+        // nothing, so provisioning one would create an object with no purpose.
+        hint: 'at least one: { apiName, displayName, mode, definition, deterministicKeyConfirmed }',
+      })
+    }
+
+    validateDatasets(doc.datasets, file)
+
+    const config = requireConfig(doc, file)
+    const result = await new DatasetApi(ctx.apiUrl, ctx.token).provisionSource({
+      displayName: doc.displayName,
+      ...(typeof doc.description === 'string' ? { description: doc.description } : {}),
+      connectorType: 'postgres',
+      config: { ...config, password: readPassword(passwordFrom) },
+      datasets: doc.datasets,
+    })
+
+    const id = (result as { id?: string; source?: { id?: string } }).source?.id
+      ?? (result as { id?: string }).id
+    return {
+      data: result,
+      text:
+        `Provisioned ${doc.displayName}${id ? `  ${id}` : ''}.\n`
+        + `  ${doc.datasets.length} dataset(s) created with it — \`frontera dataset list\`.\n`
+        + `  \`frontera source get ${id ?? '<sourceId>'}\` — confirm it connected.`,
+    }
+  },
+}
+
+const update: Command = {
+  meta: {
+    noun: 'source',
+    verb: 'update',
+    args: [{ name: 'source', required: true, description: 'Source id, from `frontera source list`' }],
+    flags: { file: 'string', 'password-from': 'string' },
+    aliases: { f: 'file' },
+    summary: 'Replace a Source’s connection, and add Datasets to it',
+    examples: ['frontera source update <sourceId> --file ./source.json --password-from -'],
+  },
+  async run(ctx) {
+    const sourceId = ctx.positional[0]
+    if (!sourceId) throw new UsageError('missing <source>', 'frontera source list')
+    const file = flagString(ctx, 'file')
+    if (!file) throw new UsageError('missing --file', `frontera source get ${sourceId} --json > source.json`)
+    const passwordFrom = flagString(ctx, 'password-from')
+    if (!passwordFrom) {
+      throw new UsageError('missing --password-from', 'pass `-` for stdin, or a file path')
+    }
+
+    refuseSharedStdin(file, passwordFrom)
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const doc = readSourceFile(file)
+
+    // Read immediately before writing rather than asking the caller for the
+    // tokens. A hand-copied `expectedUpdatedAt` is stale as often as not, and
+    // the resulting 409 reads as a platform fault rather than a race.
+    const current = await api.getSource(sourceId)
+    const expectedUpdatedAt = String(current.updatedAt ?? '')
+    const expectedRevision = Number(
+      (current as { currentRevision?: { revision?: number } }).currentRevision?.revision
+      ?? (current as { revision?: number }).revision,
+    )
+    if (!expectedUpdatedAt || !Number.isFinite(expectedRevision)) {
+      throw new CliError('cannot read the Source’s current revision', {
+        code: 'FAILURE',
+        hint: `frontera source get ${sourceId} --json — and report what it shows`,
+      })
+    }
+
+    const result = await api.updateSource(sourceId, {
+      expectedUpdatedAt,
+      expectedRevision,
+      displayName: typeof doc.displayName === 'string' ? doc.displayName : String(current.displayName ?? ''),
+      ...(typeof doc.description === 'string' ? { description: doc.description } : {}),
+      config: { ...requireConfig(doc, file), password: readPassword(passwordFrom) },
+      ...(Array.isArray(doc.datasets) && doc.datasets.length > 0 ? { datasets: doc.datasets } : {}),
+    })
+
+    return {
+      data: result,
+      text:
+        `Updated ${sourceId}.\n`
+        + '  Datasets in the file were ADDED; nothing was removed — this route has no removal channel.',
+    }
+  },
+}
+
+const revise: Command = {
+  meta: {
+    noun: 'source',
+    verb: 'revise',
+    args: [{ name: 'source', required: true, description: 'Source id, from `frontera source list`' }],
+    flags: { file: 'string', 'password-from': 'string' },
+    aliases: { f: 'file' },
+    summary: 'Publish a new connection revision, leaving Datasets alone',
+    examples: ['frontera source revise <sourceId> --file ./source.json --password-from -'],
+  },
+  async run(ctx) {
+    const sourceId = ctx.positional[0]
+    if (!sourceId) throw new UsageError('missing <source>', 'frontera source list')
+    const file = flagString(ctx, 'file')
+    if (!file) throw new UsageError('missing --file', 'the file holds the `config` block only')
+    const passwordFrom = flagString(ctx, 'password-from')
+    if (!passwordFrom) throw new UsageError('missing --password-from', 'pass `-` for stdin, or a file path')
+
+    refuseSharedStdin(file, passwordFrom)
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const doc = readSourceFile(file)
+    const current = await api.getSource(sourceId)
+    const expectedRevision = Number(
+      (current as { currentRevision?: { revision?: number } }).currentRevision?.revision
+      ?? (current as { revision?: number }).revision,
+    )
+    if (!Number.isFinite(expectedRevision)) {
+      throw new CliError('cannot read the Source’s current revision', {
+        code: 'FAILURE',
+        hint: `frontera source get ${sourceId} --json`,
+      })
+    }
+
+    const result = await api.reviseSource(sourceId, {
+      expectedRevision,
+      config: { ...requireConfig(doc, file), password: readPassword(passwordFrom) },
+    })
+
+    return {
+      data: result,
+      text:
+        `Revised ${sourceId} to a new connection revision.\n`
+        + `  \`frontera dataset test-source ${sourceId}\` — confirm it still reaches the database.`,
+    }
+  },
+}
+
+const disable: Command = {
+  meta: {
+    noun: 'source',
+    verb: 'disable',
+    args: [{ name: 'source', required: true, description: 'Source id, from `frontera source list`' }],
+    flags: {},
+    summary: 'Stop reads through a Source, without deleting it',
+    examples: ['frontera source disable <sourceId>'],
+  },
+  async run(ctx) {
+    const sourceId = ctx.positional[0]
+    if (!sourceId) throw new UsageError('missing <source>', 'frontera source list')
+
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const current = await api.getSource(sourceId)
+    const expectedUpdatedAt = String(current.updatedAt ?? '')
+    if (!expectedUpdatedAt) {
+      throw new CliError('cannot read the Source’s updatedAt', {
+        code: 'FAILURE',
+        hint: `frontera source get ${sourceId} --json`,
+      })
+    }
+
+    const result = await api.disableSource(sourceId, { expectedUpdatedAt })
+    return {
+      data: result,
+      text:
+        `Disabled ${sourceId}.\n`
+        + '  The Source is marked disabled; already-published dataset revisions are immutable\n'
+        + `  and are not rewritten. Check what still reads it with \`frontera dataset list\`.`,
+    }
+  },
+}
+
+export const sourceCommands: Command[] = [list, get, create, update, revise, disable]