@frontera-sdk/cli 1.44.1 → 1.45.0

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

@@ -4,7 +4,7 @@ import { dirname, resolve } from 'node:path'
 import { DatasetApi, type DatasetColumn } from '../../api/dataset-api'
 import { CliError } from '../../errors'
 import { table } from '../../table'
-import type { Command } from '../types'
+import { flagString, type Command } from '../types'
 
 /**
  * Datasets — the source contract a Blueprint object type reads.
@@ -127,6 +127,105 @@ const list: Command = {
   },
 }
 
+/**
+ * A dataset by API name.
+ *
+ * Datasets are addressed by `apiName` everywhere a caller meets one — it is
+ * what `backing.dataset` holds in a committed tree — while every route takes
+ * the uuid, so the lookup is unavoidable and belongs in one place.
+ */
+async function resolveDataset(api: DatasetApi, apiName: string) {
+  const datasets = await api.list()
+  const dataset = datasets.find((entry) => (entry.apiName ?? entry.name) === apiName)
+  if (!dataset?.id) {
+    throw new CliError(`No dataset named "${apiName}" in this organization.`, {
+      code: 'NOT_FOUND',
+      // The empty case reads as "missing" and is usually a capability, not a fact.
+      hint: datasets.length === 0
+        ? 'No datasets are visible at all — the key may have been minted without dataset:read.'
+        : `Visible: ${datasets.map((entry) => entry.apiName ?? entry.name).filter(Boolean).join(', ')}`,
+    })
+  }
+  return dataset
+}
+
+const rows: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'rows',
+    args: [{ name: 'apiName', required: true, description: 'The dataset’s API name' }],
+    flags: { limit: 'string', cursor: 'string' },
+    summary: 'Read rows of the dataset’s current revision',
+    examples: ['frontera dataset rows customers', 'frontera dataset rows customers --limit 20 --json'],
+  },
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    if (!apiName) {
+      throw new CliError('A dataset apiName is required.', { code: 'USAGE', hint: 'frontera dataset list' })
+    }
+
+    const limitRaw = flagString(ctx, 'limit')
+    const limit = limitRaw === undefined ? undefined : Number(limitRaw)
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+      throw new CliError(`--limit must be a positive whole number, not "${limitRaw}".`, {
+        code: 'USAGE',
+        hint: 'The service caps a page at 100 rows; try --limit 20.',
+      })
+    }
+
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const dataset = await resolveDataset(api, apiName)
+    // The CURRENT revision, not the newest row in the table: a dataset can
+    // carry a draft revision that nothing is bound to, and reading that one
+    // would answer a question nobody asked.
+    const revisionId = dataset.currentRevisionId
+      ?? (await api.revisions(dataset.id!)).at(-1)?.id
+    if (!revisionId) {
+      throw new CliError(`"${apiName}" has no published revision, so it has no rows.`, {
+        code: 'NOT_FOUND',
+        hint: 'A dataset binds only through a published revision — publish one in the Console first.',
+      })
+    }
+
+    const cursor = flagString(ctx, 'cursor')
+    const page = await api.revisionRows(revisionId, {
+      ...(limit === undefined ? {} : { limit }),
+      ...(cursor === undefined ? {} : { cursor }),
+    })
+
+    const columns = (page.columns ?? []).map((c) => c.name ?? '?')
+    const body = page.rows ?? []
+
+    if (body.length === 0) {
+      return {
+        data: page,
+        // The contract exists and the data does not — the state `dataset get`
+        // cannot distinguish, and the reason this verb exists.
+        text:
+          `No rows in the current revision of "${apiName}".\n`
+          + '  The column contract is published, so anything bound to it will bind and read nothing.\n'
+          + `  \`frontera dataset get ${apiName}\` shows the contract.`,
+      }
+    }
+
+    return {
+      data: page,
+      text:
+        table(columns, body.map((row) => row.map(cellText)))
+        + `\n\n${body.length} row${body.length === 1 ? '' : 's'} read ${page.readAt ?? 'now'}`
+        + (page.consistency ? ` (${page.consistency})` : '')
+        + (page.nextCursor ? `\nMore rows. Continue with --cursor ${page.nextCursor}` : ''),
+    }
+  },
+}
+
+/** Cells arrive as arbitrary JSON: nulls print empty, objects collapse. */
+function cellText(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
 const get: Command = {
   meta: {
     noun: 'dataset',
@@ -145,18 +244,8 @@ const get: Command = {
       })
     }
     const api = new DatasetApi(ctx.apiUrl, ctx.token)
-    const datasets = await api.list()
-    const dataset = datasets.find((entry) => (entry.apiName ?? entry.name) === apiName)
-    if (!dataset?.id) {
-      throw new CliError(`No dataset named "${apiName}" in this organization.`, {
-        code: 'NOT_FOUND',
-        // The empty case reads as "missing" and is usually a capability, not a fact.
-        hint: datasets.length === 0
-          ? 'No datasets are visible at all — the key may have been minted without dataset:read.'
-          : `Visible: ${datasets.map((entry) => entry.apiName ?? entry.name).filter(Boolean).join(', ')}`,
-      })
-    }
-    const revisions = await api.revisions(dataset.id)
+    const dataset = await resolveDataset(api, apiName)
+    const revisions = await api.revisions(dataset.id!)
     const current = revisions.find((entry) => entry.id === dataset.currentRevisionId) ?? revisions.at(-1)
     return {
       data: { dataset, revision: current },
@@ -428,4 +517,4 @@ const create: Command = {
   },
 }
 
-export const datasetCommands: Command[] = [list, get, sources, preview, testSource, create]
+export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create]

package/src/commands/kit/doctor.ts

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { checkCompatibility, findDuplicateSources, KIT, readLock } from '../../kit'
+import type { Command } from '../types'
+import { cliVersion, kitRoot } from './shared'
+
+/**
+ * Diagnose a harness that is present twice, or not at all.
+ *
+ * The condition worth having a command for: installed plugin AND vendored copy
+ * at the same time. Codex does not merge equal skill names across scopes, so
+ * both appear, and a model choosing between two identical-looking skills is
+ * making a coin flip nobody asked it to make. Claude namespaces plugin skills,
+ * but the recommendation is the same for both hosts so that behaviour does not
+ * depend on which one the person happens to be in.
+ *
+ * It reports the paths it actually found rather than asserting a diagnosis, so
+ * a wrong one is visible.
+ */
+export const kitDoctor: Command = {
+  meta: {
+    noun: 'kit',
+    verb: 'doctor',
+    args: [],
+    flags: { dir: 'string' },
+    summary: 'Diagnose duplicate skill sources, stale kits and version mismatches',
+    examples: ['frontera kit doctor', 'frontera kit doctor --json'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const root = kitRoot(ctx)
+    const lock = readLock(root)
+    const duplicates = findDuplicateSources(root)
+    const compat = checkCompatibility(cliVersion())
+
+    const findings: Array<{ level: 'error' | 'warning' | 'ok'; message: string; fix?: string }> = []
+
+    if (duplicates.length > 0) {
+      findings.push({
+        level: 'warning',
+        message:
+          `${duplicates.length} Frontera skill(s) resolve from more than one source — `
+          + 'Codex does not merge equal names across scopes, so both appear',
+        fix: lock
+          ? 'pick one mode: uninstall the plugin, or delete .agents/skills, .claude/skills and frontera.kit.lock.json'
+          : 'pick one mode: uninstall the duplicate plugin install',
+      })
+    }
+
+    if (lock && lock.kitVersion !== KIT.kitVersion) {
+      findings.push({
+        level: 'warning',
+        message: `vendored kit ${lock.kitVersion} is behind the ${KIT.kitVersion} this CLI carries`,
+        fix: 'frontera kit sync',
+      })
+    }
+
+    if (!compat.compatible) {
+      findings.push({
+        level: 'error',
+        message: `${compat.reason} (CLI ${compat.cliVersion}, kit ${KIT.kitVersion})`,
+        fix: `install a CLI in [${compat.required.minimum}, ${compat.required.maximumExclusive})`,
+      })
+    }
+
+    const claudeMd = join(root, 'CLAUDE.md')
+    if (lock && existsSync(claudeMd)) {
+      const imports = readFileSync(claudeMd, 'utf8').split('\n').some((l) => l.trim() === '@AGENTS.md')
+      if (!imports) {
+        findings.push({
+          level: 'error',
+          message: 'CLAUDE.md does not import @AGENTS.md, so Claude Code never loads the project contract',
+          fix: 'frontera kit vendor',
+        })
+      }
+    }
+
+    if (findings.length === 0) {
+      findings.push({
+        level: 'ok',
+        message: lock
+          ? `vendored kit ${lock.kitVersion}, one source per skill, CLI in range`
+          : 'not vendored — installed plugins are the normal path, and nothing here conflicts with them',
+      })
+    }
+
+    const data = { root, vendored: lock !== null, duplicateSkillSources: duplicates, compatibility: compat, findings }
+
+    const lines = findings.flatMap((f) => [
+      `${f.level === 'ok' ? 'ok' : f.level === 'error' ? 'error' : 'warning'}: ${f.message}`,
+      ...(f.fix ? [`  → ${f.fix}`] : []),
+    ])
+    for (const dup of duplicates) {
+      lines.push(`  ${dup.skill}:`, ...dup.sources.map((s) => `    ${s}`))
+    }
+
+    return { data, text: lines.join('\n') }
+  },
+}

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

@@ -0,0 +1,7 @@
+import { kitDoctor } from './doctor'
+import { kitStatus } from './status'
+import { kitSync } from './sync'
+import { kitVendor } from './vendor'
+import type { Command } from '../types'
+
+export const kitCommands: readonly Command[] = [kitVendor, kitStatus, kitSync, kitDoctor]

package/src/commands/kit/shared.ts

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { CliError } from '../../errors'
+import { checkCompatibility, KIT } from '../../kit'
+import { resolveBindingRoot } from '../../project-context'
+import { flagString, type CommandContext } from '../types'
+
+/**
+ * The kit writes into the same root `auth use` binds.
+ *
+ * One notion of "this project" across authentication and authoring. Two would
+ * mean a repository whose profile is selected at the Git root and whose skills
+ * land in a subdirectory, which reads as a bug long before anyone finds the two
+ * different rules that produced it.
+ */
+export function kitRoot(ctx: CommandContext): string {
+  return resolveBindingRoot(ctx.cwd, flagString(ctx, 'dir')).root
+}
+
+/**
+ * The version this CLI reports, which is what compatibility is judged against.
+ *
+ * A released binary is stamped at build time; a checkout falls back to the
+ * manifest. Both are the same number a bug report would name.
+ */
+export function cliVersion(): string {
+  const stamped = process.env.FRONTERA_CLI_VERSION
+  if (stamped) return stamped
+  const pkgPath = join(import.meta.dir, '..', '..', '..', 'package.json')
+  if (!existsSync(pkgPath)) return '0.0.0'
+  return (JSON.parse(readFileSync(pkgPath, 'utf8')) as { version: string }).version
+}
+
+/**
+ * Refuse to write instructions this CLI's own command surface has outgrown.
+ *
+ * A skill describing commands that moved is worse than no skill: a model acts
+ * on it rather than noticing it is stale, and the failure surfaces as a wrong
+ * command rather than as a version problem.
+ */
+export function requireCompatible(): void {
+  const compat = checkCompatibility(cliVersion())
+  if (compat.compatible) return
+  throw new CliError(
+    `authoring kit ${KIT.kitVersion} does not support CLI ${compat.cliVersion} — ${compat.reason}`,
+    {
+      code: 'KIT_VERSION_MISMATCH',
+      hint: `this kit expects a CLI in [${compat.required.minimum}, ${compat.required.maximumExclusive}) — upgrade the CLI, or run \`frontera kit status --json\``,
+    },
+  )
+}

package/src/commands/kit/status.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { checkCompatibility, digest, findDuplicateSources, KIT, LOCK_FILE, readLock, renderKit } from '../../kit'
+import type { Command } from '../types'
+import { cliVersion, kitRoot } from './shared'
+
+/**
+ * What this repository has, what this CLI carries, and whether they agree.
+ *
+ * Answerable without writing anything, because the question "is my harness
+ * stale" should never require a command that could change the answer.
+ */
+export const kitStatus: Command = {
+  meta: {
+    noun: 'kit',
+    verb: 'status',
+    args: [],
+    flags: { dir: 'string' },
+    summary: 'Show the installed and bundled kit versions, local edits and compatibility',
+    examples: ['frontera kit status', 'frontera kit status --json'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const root = kitRoot(ctx)
+    const lock = readLock(root)
+    const rendered = renderKit()
+    const compat = checkCompatibility(cliVersion())
+
+    const modified: string[] = []
+    const missing: string[] = []
+    for (const [rel, content] of Object.entries(rendered.generated)) {
+      const path = join(root, rel)
+      if (!existsSync(path)) {
+        if (lock) missing.push(rel)
+        continue
+      }
+      const current = readFileSync(path, 'utf8')
+      if (current === content) continue
+      // Modified against the LOCK, not against the bundle: a file matching what
+      // we last wrote is out of date, which `sync` fixes, while one matching
+      // neither is a local edit, which `sync` must not silently discard.
+      if (lock?.files[rel] && digest(current) === lock.files[rel]) continue
+      modified.push(rel)
+    }
+
+    const outdated = Boolean(lock && lock.kitVersion !== KIT.kitVersion)
+    const duplicates = findDuplicateSources(root)
+
+    const claudeMd = join(root, 'CLAUDE.md')
+    const claudeImportsAgents = existsSync(claudeMd)
+      ? readFileSync(claudeMd, 'utf8').split('\n').some((l) => l.trim() === '@AGENTS.md')
+      : null
+
+    const data = {
+      root,
+      vendored: lock !== null,
+      installedKitVersion: lock?.kitVersion ?? null,
+      bundledKitVersion: KIT.kitVersion,
+      outdated,
+      modified,
+      missing,
+      duplicateSkillSources: duplicates,
+      claudeImportsAgents,
+      compatibility: compat,
+      lock: lock ? LOCK_FILE : null,
+    }
+
+    const lines: string[] = []
+    if (!lock) {
+      lines.push('Not vendored here — installed plugins are the normal path.')
+      lines.push(`  bundled kit ${KIT.kitVersion}; run \`frontera kit vendor\` to commit it to this repository`)
+    } else {
+      lines.push(`kit ${lock.kitVersion} vendored${outdated ? ` — this CLI carries ${KIT.kitVersion}` : ' (current)'}`)
+      if (modified.length > 0) lines.push(`  ${modified.length} generated file(s) edited locally:`)
+      lines.push(...modified.map((f) => `    · ${f}`))
+      if (missing.length > 0) lines.push(...missing.map((f) => `    - ${f} (missing)`))
+    }
+    if (claudeImportsAgents === false) {
+      lines.push('  ! CLAUDE.md does not import @AGENTS.md — run `frontera kit vendor` to repair it')
+    }
+    if (duplicates.length > 0) {
+      lines.push(`  ! ${duplicates.length} skill(s) resolve from more than one source — run \`frontera kit doctor\``)
+    }
+    if (!compat.compatible) {
+      lines.push(`  ! ${compat.reason} — this kit expects [${compat.required.minimum}, ${compat.required.maximumExclusive})`)
+    }
+
+    return { data, text: lines.join('\n') }
+  },
+}

package/src/commands/kit/sync.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { applyClaudeImport, applyManagedBlock, KIT, readLock, renderKit, writeGenerated, writeLock } from '../../kit'
+import { UsageError } from '../../errors'
+import { flagBool, type Command } from '../types'
+import { cliVersion, kitRoot, requireCompatible } from './shared'
+
+/**
+ * Bring an already-vendored repository up to this CLI's kit.
+ *
+ * The difference from `vendor` is what it refuses to do: `sync` updates files
+ * that are already here and does not adopt a project that never opted in. A
+ * command that quietly started managing a repository because someone ran the
+ * wrong verb is a command people stop running.
+ *
+ * An unchanged generated file is updated. A locally edited one is a conflict
+ * and needs `--force` — someone changed it for a reason, and finding out by
+ * losing it is the worst way to learn that a tool regenerates.
+ */
+export const kitSync: Command = {
+  meta: {
+    noun: 'kit',
+    verb: 'sync',
+    args: [],
+    flags: { force: 'boolean', dir: 'string' },
+    summary: 'Update vendored Frontera skills to the kit this CLI carries',
+    examples: ['frontera kit sync', 'frontera kit sync --force'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    requireCompatible()
+
+    const root = kitRoot(ctx)
+    const lock = readLock(root)
+    if (!lock) {
+      throw new UsageError(
+        'nothing is vendored here',
+        'run `frontera kit vendor` to write the skills into this repository — or use the installed plugins, which need no files at all',
+      )
+    }
+
+    const rendered = renderKit()
+    const force = flagBool(ctx, 'force')
+    const report = writeGenerated(root, rendered.generated, lock, { force, onlyExisting: false })
+
+    const edited: string[] = []
+    const repaired: string[] = []
+
+    if (rendered.agentsMd !== null) {
+      const path = join(root, 'AGENTS.md')
+      const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
+      const next = applyManagedBlock(existing, rendered.agentsMd)
+      if (next !== existing) {
+        writeFileSync(path, next)
+        edited.push('AGENTS.md')
+      }
+    }
+
+    if (rendered.claudeMd !== null) {
+      const path = join(root, 'CLAUDE.md')
+      const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
+      const result = applyClaudeImport(existing, rendered.claudeMd)
+      if (result.content !== existing) {
+        writeFileSync(path, result.content)
+        edited.push('CLAUDE.md')
+      }
+      if (result.repaired) repaired.push('CLAUDE.md')
+    }
+
+    const locked = Object.fromEntries(
+      Object.entries(rendered.generated).filter(([rel]) => !report.conflicts.includes(rel)),
+    )
+    writeLock(root, locked, cliVersion())
+
+    const data = {
+      root,
+      from: lock.kitVersion,
+      to: KIT.kitVersion,
+      written: report.written,
+      unchanged: report.unchanged,
+      conflicts: report.conflicts,
+      edited,
+      repaired,
+    }
+
+    const lines = [
+      `kit ${lock.kitVersion} → ${KIT.kitVersion}`,
+      ...report.written.map((f) => `  + ${f}`),
+      ...edited.map((f) => `  ~ ${f}`),
+      ...repaired.map((f) => `  ! ${f} — replaced the non-importing ./AGENTS.md line with @AGENTS.md`),
+      ...report.conflicts.map((f) => `  · ${f} (edited locally — use --force to replace)`),
+    ]
+    if (report.unchanged.length > 0) lines.push(`  = ${report.unchanged.length} file(s) already current`)
+
+    if (report.conflicts.length > 0 && !force) {
+      ctx.output.note(
+        `${report.conflicts.length} generated file(s) were edited locally and were left alone — `
+        + 'diff them, then re-run with --force to take the kit version',
+      )
+    }
+
+    return { data, text: lines.join('\n') }
+  },
+}

package/src/commands/kit/vendor.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { CliError } from '../../errors'
+import {
+  applyClaudeImport,
+  applyManagedBlock,
+  KIT,
+  LOCK_FILE,
+  readLock,
+  renderKit,
+  writeGenerated,
+  writeLock,
+} from '../../kit'
+import { flagBool, type Command } from '../types'
+import { cliVersion, kitRoot, requireCompatible } from './shared'
+
+/**
+ * Commit the Frontera instructions to a repository.
+ *
+ * The OPTIONAL path. Installed Codex and Claude plugins are the normal
+ * distribution, and a repository needs no generated files for directory-aware
+ * authentication or ordinary Frontera authoring. This exists for teams who want
+ * the instructions versioned with the code, and for the places a plugin install
+ * does not reach: Windows checkouts, archives, remote sandboxes, Codex cloud and
+ * Claude cloud.
+ *
+ * The kit decides which hosts it renders, so there is no `--hosts`. A flag there
+ * would let one repository ship half a harness, and the half missing is the half
+ * whose absence nobody notices until an agent runs without the contract.
+ */
+export const kitVendor: Command = {
+  meta: {
+    noun: 'kit',
+    verb: 'vendor',
+    args: [],
+    flags: { force: 'boolean', dir: 'string' },
+    summary: 'Write the Frontera skills and project contract into this repository',
+    examples: ['frontera kit vendor', 'frontera kit vendor --dir ./packages/ops --json'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    requireCompatible()
+
+    const root = kitRoot(ctx)
+    const rendered = renderKit()
+    const lock = readLock(root)
+    const force = flagBool(ctx, 'force')
+
+    const report = writeGenerated(root, rendered.generated, lock, { force })
+
+    const edited: string[] = []
+    const repaired: string[] = []
+
+    if (rendered.agentsMd !== null) {
+      const path = join(root, 'AGENTS.md')
+      const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
+      const next = applyManagedBlock(existing, rendered.agentsMd)
+      if (next !== existing) {
+        writeFileSync(path, next)
+        edited.push('AGENTS.md')
+      }
+    }
+
+    if (rendered.claudeMd !== null) {
+      const path = join(root, 'CLAUDE.md')
+      const existing = existsSync(path) ? readFileSync(path, 'utf8') : null
+      const result = applyClaudeImport(existing, rendered.claudeMd)
+      if (result.content !== existing) {
+        writeFileSync(path, result.content)
+        edited.push('CLAUDE.md')
+      }
+      if (result.repaired) repaired.push('CLAUDE.md')
+    }
+
+    // The lock records what WAS written. A conflicted file keeps whatever digest
+    // it had, so the next run still reports it rather than adopting the local
+    // edit as ours.
+    const locked = Object.fromEntries(
+      Object.entries(rendered.generated).filter(([rel]) => !report.conflicts.includes(rel)),
+    )
+    writeLock(root, locked, cliVersion())
+
+    const data = {
+      root,
+      kitVersion: KIT.kitVersion,
+      hosts: KIT.hosts,
+      written: report.written,
+      unchanged: report.unchanged,
+      conflicts: report.conflicts,
+      edited,
+      repaired,
+      lock: LOCK_FILE,
+    }
+
+    const lines = [
+      ...report.written.map((f) => `  + ${f}`),
+      ...edited.map((f) => `  ~ ${f}`),
+      ...repaired.map((f) => `  ! ${f} — replaced the non-importing ./AGENTS.md line with @AGENTS.md`),
+      ...report.conflicts.map((f) => `  · ${f} (edited locally — use --force to replace)`),
+    ]
+    if (report.unchanged.length > 0) lines.push(`  = ${report.unchanged.length} file(s) already current`)
+    lines.push(`  wrote ${LOCK_FILE} at kit ${KIT.kitVersion}`)
+
+    if (report.conflicts.length > 0 && !force) {
+      // Reported, not thrown: the files that COULD be written were, and stopping
+      // the whole command over one edited skill would leave a project half
+      // prepared with no record of why.
+      ctx.output.note(
+        `${report.conflicts.length} generated file(s) were edited locally and were left alone — `
+        + 'run `frontera kit sync --force` to replace them',
+      )
+    }
+
+    return { data, text: lines.join('\n') }
+  },
+}
+
+export { CliError }