@frontera-sdk/cli 0.1.0

package/src/commands/registry.ts

@@ -0,0 +1,405 @@
+import type { FlagSpec } from '../args'
+import { UsageError } from '../errors'
+import { describeFlag, flagUsage } from '../flag-help'
+import { accent, definitions, dim, heading, terminalWidth, wrap } from '../help'
+import type { Command, CommandMeta } from './types'
+
+import { appInit } from './app/init'
+import { appList } from './app/list'
+import { appAdd } from './app/add'
+import { appPull } from './app/pull'
+import { appSave } from './app/save'
+import { appDeploy } from './app/deploy'
+import { appPromote } from './app/promote'
+import { appVersions } from './app/versions'
+import { blueprintList } from './blueprint/list'
+import { blueprintGet } from './blueprint/get'
+import { blueprintReserved } from './blueprint/reserved'
+import { agentCommands } from './agent/index-commands'
+import { skillCommands } from './skill/index-commands'
+import { pluginCommands } from './plugin/index-commands'
+import { knowledgeCommands } from './knowledge/index-commands'
+import { automationCommands } from './automation/index-commands'
+import { completionCommand } from './completion'
+import { initCommand } from './init'
+import { loginCommand } from './login'
+
+/**
+ * Flags every command accepts. Declared once so a caller never has to wonder
+ * whether `--json` works here — it works everywhere.
+ */
+export const GLOBAL_FLAGS: FlagSpec = {
+  json: 'boolean',
+  quiet: 'boolean',
+  yes: 'boolean',
+  help: 'boolean',
+  'api-url': 'string',
+}
+
+/** Additionally accepted by any command that resolves a project. */
+export const PROJECT_FLAGS: FlagSpec = { dir: 'string' }
+
+export const COMMANDS: readonly Command[] = [
+  initCommand,
+  loginCommand,
+  completionCommand,
+
+  appInit,
+  appList,
+  appAdd,
+  appPull,
+  appSave,
+  appDeploy,
+  appPromote,
+  appVersions,
+
+  ...agentCommands,
+  ...skillCommands,
+  ...pluginCommands,
+  ...knowledgeCommands,
+  ...automationCommands,
+
+  blueprintList,
+  blueprintGet,
+  ...blueprintReserved,
+]
+
+export function findCommand(noun: string, verb: string | undefined): Command | null {
+  return (
+    COMMANDS.find((c) => c.meta.noun === noun && c.meta.verb === (verb ?? '')) ?? null
+  )
+}
+
+export function nouns(): string[] {
+  return [...new Set(COMMANDS.map((c) => c.meta.noun))]
+}
+
+/**
+ * What each noun is for.
+ *
+ * Top-level help lists nouns before verbs, so the noun line has to carry its
+ * own meaning — otherwise the first thing a reader sees is `app`, `agent`,
+ * `plugin` with no way to tell which one holds what they came for.
+ */
+const NOUN_SUMMARY: Readonly<Record<string, string>> = {
+  app: 'Frontera Apps — scaffold, deploy and version a React app',
+  agent: 'Agents — read a configuration, stage a change, publish it',
+  skill: 'Workspace skills an agent loads at runtime',
+  plugin: 'Integrations and MCP servers connected to this workspace',
+  knowledge: 'Knowledge bases and the sources inside them',
+  automation: 'Automations — TypeScript deployed here, run on a schedule',
+  blueprint: 'The shared model of the organization — what an app can read',
+}
+
+export function nounSummary(noun: string): string {
+  return NOUN_SUMMARY[noun] ?? ''
+}
+
+/** Short forms every command understands, plus the command's own. */
+export function aliasesFor(meta: CommandMeta): Readonly<Record<string, string>> {
+  return { h: 'help', ...(meta.aliases ?? {}) }
+}
+
+export function flagsFor(meta: CommandMeta): FlagSpec {
+  return {
+    ...GLOBAL_FLAGS,
+    ...(meta.needsProject || meta.optionalProject ? PROJECT_FLAGS : {}),
+    ...meta.flags,
+  }
+}
+
+function usage(meta: CommandMeta): string {
+  const parts = ['frontera', meta.noun, meta.verb].filter(Boolean)
+  for (const a of meta.args) parts.push(a.required ? `<${a.name}>` : `[${a.name}]`)
+  return parts.join(' ')
+}
+
+/** The verb and its arguments, without the `frontera <noun>` prefix. */
+function verbUsage(meta: CommandMeta): string {
+  const parts = [meta.verb].filter(Boolean)
+  for (const a of meta.args) parts.push(a.required ? `<${a.name}>` : `[${a.name}]`)
+  return parts.join(' ')
+}
+
+const GLOBAL_SECTION = [
+  '',
+  heading('Global flags'),
+  ...definitions(
+    Object.entries(GLOBAL_FLAGS).map(
+      ([name, type]) => [flagUsage(name, type), describeFlag(name)] as const,
+    ),
+  ),
+  '',
+  heading('Environment'),
+  ...definitions([
+    ['FRONTERA_API_URL', 'Frontera API origin'],
+    ['FRONTERA_TOKEN', 'workspace API key (sk-ws-…)'],
+    ['NO_COLOR', 'set to disable colour'],
+  ]),
+]
+
+/**
+ * Help is GENERATED from the table, never written by hand.
+ *
+ * Hand-maintained help drifts, and drifted help is a wrong instruction handed
+ * straight to a model — which will act on it rather than notice. Generating it
+ * also means a command cannot ship undocumented: the summary and example are
+ * required fields.
+ */
+export function renderHelp(): string {
+  const lines: string[] = [
+    `${accent('frontera')} — author and deploy on the Frontera platform`,
+    '',
+    heading('Usage'),
+    ...definitions([
+      ['frontera <noun> <verb> [args] [flags]', ''],
+      ['frontera --version', ''],
+    ]),
+  ]
+
+  // Setup first and ungrouped: these are the two commands someone runs before
+  // any noun makes sense.
+  const setup = COMMANDS.filter((c) => c.meta.verb === '')
+  if (setup.length > 0) {
+    lines.push('', heading('Getting started'))
+    lines.push(
+      ...definitions(setup.map((c) => [accent(usage(c.meta)), c.meta.summary] as const)),
+    )
+  }
+
+  for (const noun of nouns()) {
+    const group = COMMANDS.filter((c) => c.meta.noun === noun && c.meta.verb !== '')
+    if (group.length === 0) continue
+
+    lines.push('', `${heading(accent(`frontera ${noun}`))}  ${dim(nounSummary(noun))}`.trimEnd())
+    lines.push(
+      ...definitions(
+        group
+          .filter((c) => !c.meta.reserved)
+          .map((c) => [verbUsage(c.meta), c.meta.summary] as const),
+        { indent: 4 },
+      ),
+    )
+
+    // Reserved verbs are named but not itemised. Naming them stops a caller
+    // concluding they mistyped; itemising all fifteen of them at the top level
+    // buried the twenty commands that work.
+    const reserved = group.filter((c) => c.meta.reserved).map((c) => c.meta.verb)
+    if (reserved.length > 0) {
+      lines.push(`    ${dim(`${reserved.join(', ')} — not available yet`)}`)
+    }
+  }
+
+  lines.push(
+    ...GLOBAL_SECTION,
+    '',
+    heading('Learn more'),
+    ...definitions([
+      ['frontera <noun> --help', 'every verb for one noun, including the reserved ones'],
+      ['frontera <noun> <verb> --help', "one command's arguments and flags"],
+      ['frontera help --json', 'the whole command table as data'],
+    ]),
+  )
+  return lines.join('\n')
+}
+
+/**
+ * Help for a whole noun — `frontera agent --help`, or a bare `frontera agent`.
+ *
+ * This was missing, and the CLI's own error hints pointed at it: a reserved
+ * verb tells the caller to "run `frontera <noun> --help`", which answered
+ * "unknown verb for agent: --help". A hint that leads nowhere is worse than
+ * no hint, because it costs a turn before the caller stops trusting them.
+ */
+export function renderNounHelp(noun: string): string {
+  const group = COMMANDS.filter((c) => c.meta.noun === noun)
+  const summary = nounSummary(noun)
+  const lines = [`${accent(`frontera ${noun}`)}${summary ? ` — ${summary}` : ''}`, '', heading('Commands')]
+
+  lines.push(
+    ...definitions(
+      group.map(
+        (c) =>
+          [
+            c.meta.reserved ? dim(verbUsage(c.meta)) : verbUsage(c.meta),
+            c.meta.reserved ? `${c.meta.summary}  (not available yet)` : c.meta.summary,
+          ] as const,
+      ),
+    ),
+  )
+
+  lines.push(
+    '',
+    heading('Learn more'),
+    ...definitions([
+      [`frontera ${noun} <verb> --help`, "one command's arguments and flags"],
+      [`frontera ${noun} --help --json`, 'these commands as data'],
+    ]),
+  )
+  return lines.join('\n')
+}
+
+export function renderCommandHelp(meta: CommandMeta): string {
+  const width = terminalWidth()
+  const lines = [accent(usage(meta)), '', ...wrap(meta.summary, width)]
+
+  if (meta.reserved) {
+    lines.push('', ...wrap(`Not available yet: ${meta.reserved}`, width).map(dim))
+  }
+
+  if (meta.args.length > 0) {
+    lines.push('', heading('Arguments'))
+    lines.push(
+      ...definitions(
+        meta.args.map(
+          (a) =>
+            [
+              a.required ? `<${a.name}>` : `[${a.name}]`,
+              a.required ? a.description : `${a.description}  (optional)`,
+            ] as const,
+        ),
+      ),
+    )
+  }
+
+  const spec = flagsFor(meta)
+  // Command flags first, then the ones every command shares — what is specific
+  // to this command is what the reader came for.
+  const shared = new Set(Object.keys(GLOBAL_FLAGS))
+  const own = Object.keys(spec).filter((f) => !shared.has(f)).sort()
+  const short = Object.entries(aliasesFor(meta)).reduce<Record<string, string>>((acc, [s, long]) => {
+    acc[long] = s
+    return acc
+  }, {})
+
+  if (own.length > 0) {
+    lines.push('', heading('Flags'))
+    lines.push(
+      ...definitions(
+        own.map((f) => [flagUsage(f, spec[f]!, short[f]), describeFlag(f)] as const),
+      ),
+    )
+  }
+
+  lines.push('', heading('Examples'))
+  lines.push(...meta.examples.map((e) => `  ${e}`))
+
+  lines.push(...GLOBAL_SECTION)
+  return lines.join('\n')
+}
+
+/**
+ * The command table as data.
+ *
+ * `--help` is the discovery surface, and an agent discovering it had to parse
+ * columns of prose to learn what exists. This is the same information without
+ * the layout: one call to `frontera help --json` returns every command, its
+ * arguments, its flags and whether it is available, so a harness can plan
+ * against the real surface instead of guessing at it.
+ */
+export interface CommandDescriptor {
+  noun: string
+  verb: string
+  usage: string
+  summary: string
+  available: boolean
+  unavailableReason?: string
+  args: Array<{ name: string; required: boolean; description: string }>
+  flags: Array<{ name: string; type: 'string' | 'boolean'; short?: string; description: string }>
+  examples: string[]
+  needsProject: boolean
+  requiresCredential: boolean
+}
+
+export function describeCommand(meta: CommandMeta): CommandDescriptor {
+  const spec = flagsFor(meta)
+  const short = Object.entries(aliasesFor(meta)).reduce<Record<string, string>>((acc, [s, long]) => {
+    acc[long] = s
+    return acc
+  }, {})
+
+  return {
+    noun: meta.noun,
+    verb: meta.verb,
+    usage: usage(meta),
+    summary: meta.summary,
+    available: !meta.reserved,
+    ...(meta.reserved ? { unavailableReason: meta.reserved } : {}),
+    args: meta.args.map((a) => ({ ...a })),
+    flags: Object.keys(spec)
+      .sort()
+      .map((name) => ({
+        name,
+        type: spec[name]!,
+        ...(short[name] ? { short: short[name]! } : {}),
+        description: describeFlag(name),
+      })),
+    examples: [...meta.examples],
+    needsProject: Boolean(meta.needsProject),
+    requiresCredential: !meta.offline,
+  }
+}
+
+export function describeCommands(noun?: string): CommandDescriptor[] {
+  return COMMANDS.filter((c) => !noun || c.meta.noun === noun).map((c) => describeCommand(c.meta))
+}
+
+/** Levenshtein distance, iterative with one row — enough for a typo check. */
+function editDistance(a: string, b: string): number {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i += 1) {
+    const current = [i]
+    for (let j = 1; j <= b.length; j += 1) {
+      current[j] = Math.min(
+        previous[j]! + 1,
+        current[j - 1]! + 1,
+        previous[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+    }
+    previous = current
+  }
+  return previous[b.length]!
+}
+
+/**
+ * The closest real name to what was typed, if anything is close enough.
+ *
+ * Listing every valid name is correct but slow to act on — `frontera app
+ * delpoy` should not require reading eight alternatives to find the one that
+ * differs by a swap. Threshold scales with length so short names do not match
+ * each other by accident: at distance 2, `get` and `set` would be neighbours.
+ */
+function nearest(typed: string, candidates: string[]): string | null {
+  const limit = typed.length <= 4 ? 1 : 2
+  let best: { name: string; distance: number } | null = null
+
+  for (const candidate of candidates) {
+    const distance = editDistance(typed.toLowerCase(), candidate.toLowerCase())
+    if (distance <= limit && (!best || distance < best.distance)) {
+      best = { name: candidate, distance }
+    }
+  }
+  return best?.name ?? null
+}
+
+export function unknownCommand(noun: string, verb: string | undefined): UsageError {
+  const known = nouns()
+  if (!known.includes(noun)) {
+    const guess = nearest(noun, known)
+    return new UsageError(
+      `unknown command: ${noun}`,
+      guess
+        ? `did you mean \`frontera ${guess}\`? — run \`frontera help\` for all of them`
+        : `run \`frontera help\` — available: ${known.join(', ')}`,
+    )
+  }
+
+  const verbs = COMMANDS.filter((c) => c.meta.noun === noun).map((c) => c.meta.verb)
+  const guess = verb ? nearest(verb, verbs) : null
+  return new UsageError(
+    `unknown verb for ${noun}: ${verb ?? '(none)'}`,
+    guess
+      ? `did you mean \`frontera ${noun} ${guess}\`? — \`frontera ${noun} --help\` lists them all`
+      : `run \`frontera ${noun} --help\` — ${noun} accepts: ${verbs.join(', ')}`,
+  )
+}

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

@@ -0,0 +1,140 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+interface SkillRow {
+  id?: string
+  name?: string
+  displayName?: string
+  description?: string
+}
+
+/**
+ * `skill` is the PLATFORM resource — a workspace skill an agent binds and
+ * loads at runtime. It is not `.agents/skills/`, which teaches a coding
+ * harness and is written by `frontera init`, and it is not `frontera app add`,
+ * which copies registry source into a project. One word, one meaning.
+ */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+async function resolveSkillRef(client: PlatformApi, ref: string): Promise<string> {
+  if (UUID.test(ref)) return ref
+
+  const rows = (await client.workspaceSkills()) as SkillRow[]
+  const match =
+    rows.find((s) => (s.name ?? '').toLowerCase() === ref.toLowerCase()) ??
+    rows.find((s) => (s.displayName ?? '').toLowerCase() === ref.toLowerCase())
+  if (match?.id) return match.id
+
+  const near = rows
+    .filter((s) => `${s.name ?? ''} ${s.displayName ?? ''}`.toLowerCase().includes(ref.toLowerCase()))
+    .map((s) => s.name)
+    .filter(Boolean)
+
+  throw new CliError(`no skill named "${ref}"`, {
+    code: 'NOT_FOUND',
+    hint:
+      near.length > 0
+        ? `did you mean ${near.slice(0, 3).join(', ')}?`
+        : 'run `frontera skill list` to see names and ids',
+  })
+}
+
+const list: Command = {
+  meta: {
+    noun: 'skill',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List workspace skills',
+    examples: ['frontera skill list', 'frontera skill list --json'],
+  },
+  async run(ctx) {
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).workspaceSkills()) as SkillRow[]
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No workspace skills defined.'
+          : table(
+              ['id', 'name', 'description'],
+              rows.map((s) => [s.id ?? '?', s.name ?? '', s.description ?? '']),
+              // Skill descriptions are trigger prose and run to hundreds of
+              // characters; uncapped they wrapped every row. --json has them whole.
+              [undefined, undefined, 70],
+            ),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'skill',
+    verb: 'get',
+    args: [{ name: 'skill', required: true, description: 'skill name or id, from `frontera skill list`' }],
+    flags: {},
+    summary: 'Write one workspace skill as a document to stdout',
+    examples: ['frontera skill get kpi-performance-analysis', 'frontera skill get 8f1c… --json'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <skill>', 'frontera skill list — then pass a name or id')
+
+    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    // Name or id, like every other noun. `skill list` leads with the id but a
+    // reader reaches for the name, and an id-only argument made this the one
+    // command that refused the obvious input.
+    const id = await resolveSkillRef(client, ref)
+    const doc = (await client.workspaceSkill(id)) as SkillRow & {
+      body?: string
+      trigger?: string
+      keywords?: string[] | null
+      references?: Array<{ filename?: string }> | null
+    }
+
+    // The body is markdown a person reads, and JSON-encoding it turns every
+    // newline into `\n` — technically the same content, unreadable in a
+    // terminal. Metadata first, then the body verbatim.
+    const meta = [
+      ['name', doc.name],
+      ['display name', doc.displayName],
+      ['trigger', doc.trigger],
+      ['keywords', doc.keywords?.join(', ')],
+      ['references', doc.references?.map((r) => r.filename).filter(Boolean).join(', ')],
+    ].filter(([, v]) => v) as Array<[string, string]>
+
+    return {
+      data: doc,
+      text: [
+        ...meta.map(([k, v]) => `${k.padEnd(14)}${v}`),
+        ...(doc.description ? ['', doc.description] : []),
+        ...(doc.body ? ['', '─'.repeat(60), '', doc.body.trimEnd()] : ['', '(no body)']),
+      ].join('\n'),
+    }
+  },
+}
+
+const RESERVED = 'skill writes are not available in this release; list and get are read-only'
+
+const reserved: Command[] = (
+  [
+    ['apply', 'Create or update a workspace skill from a document'],
+    ['delete', 'Delete a workspace skill'],
+  ] as const
+).map(([verb, summary]) => ({
+  meta: {
+    noun: 'skill',
+    verb,
+    args: [],
+    flags: {},
+    summary,
+    examples: [`frontera skill ${verb} <id>`],
+    reserved: RESERVED,
+  },
+  async run(): Promise<never> {
+    throw new Error(RESERVED)
+  },
+}))
+
+export const skillCommands: Command[] = [list, get, ...reserved]

package/src/commands/types.ts

@@ -0,0 +1,76 @@
+import type { FlagSpec } from '../args'
+import type { AppProject } from '../context'
+import type { Output } from '../output'
+
+export interface ArgSpec {
+  name: string
+  required: boolean
+  description: string
+}
+
+export interface CommandMeta {
+  noun: string
+  verb: string
+  args: readonly ArgSpec[]
+  flags: FlagSpec
+  /** Short forms, e.g. `{ f: 'file' }` for `-f`. */
+  aliases?: Readonly<Record<string, string>>
+  summary: string
+  /** At least one, copy-pasteable. Agents read --help before documentation. */
+  examples: readonly string[]
+  /** Resolve an app project before running, and fail if there is none. */
+  needsProject?: boolean
+  /**
+   * Resolve a project when one is present, but run without it.
+   *
+   * For commands that touch the filesystem without requiring an existing
+   * project: `pull` hydrates a directory that is usually empty, and `add`
+   * lists the registry for someone deciding what to scaffold. Both accept
+   * `--dir` for the same reason.
+   */
+  optionalProject?: boolean
+  /** No credential needed — scaffolding runs before a key exists. */
+  offline?: boolean
+  /**
+   * Present → the command is planned but unbuilt, and fails with this message.
+   * Reserved in the table rather than omitted: a caller reading "unknown
+   * command" concludes it mistyped and retries, while one reading the real
+   * reason picks another route.
+   */
+  reserved?: string
+}
+
+export interface CommandContext {
+  cwd: string
+  apiUrl: string
+  token: string
+  positional: string[]
+  flags: Record<string, string | boolean>
+  output: Output
+  /** Present when `meta.needsProject`. */
+  project: AppProject | null
+}
+
+/**
+ * A command returns data and the text a person should see. It never writes to
+ * a stream and never sets an exit code — `output` decides which of the two to
+ * emit and where. That split is what makes `--json` uniform by construction.
+ */
+export interface CommandResult {
+  data: unknown
+  text: string
+}
+
+export interface Command {
+  meta: CommandMeta
+  run(ctx: CommandContext): Promise<CommandResult>
+}
+
+export function flagString(ctx: CommandContext, name: string): string | undefined {
+  const v = ctx.flags[name]
+  return typeof v === 'string' ? v : undefined
+}
+
+export function flagBool(ctx: CommandContext, name: string): boolean {
+  return ctx.flags[name] === true
+}