@frontera-sdk/cli 0.1.0

package/src/commands/blueprint/get.ts

@@ -0,0 +1,160 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import type { Command } from '../types'
+
+interface Property {
+  apiName?: string
+  displayName?: string
+  propertyType?: string
+  dataType?: string
+}
+
+interface Link {
+  apiName?: string
+  fromObjectTypeId?: string
+  toObjectTypeId?: string
+  cardinality?: string
+}
+
+interface Metric {
+  apiName?: string
+  displayName?: string
+  objectTypeId?: string
+}
+
+interface ObjectTypeRow {
+  apiName?: string
+  displayName?: string
+  description?: string | null
+}
+
+/**
+ * Resolve what the caller typed to a real api name.
+ *
+ * Api names are capitalised (`City`, `SupportTicket`) and the service matches
+ * them exactly, so `city` returned "object type with ID city not found" — an
+ * error that names a different concept than the argument does, and does not
+ * say the one thing that would fix it.
+ *
+ * The exact name is tried first, so the common path stays one request. Only a
+ * miss pays for the list, and then it either resolves the case or names the
+ * closest thing it found.
+ */
+async function resolveApiName(api: PlatformApi, typed: string): Promise<string> {
+  const types = (await api.blueprintObjectTypes()) as ObjectTypeRow[]
+  const names = types.map((t) => t.apiName).filter((n): n is string => Boolean(n))
+
+  const insensitive = names.find((n) => n.toLowerCase() === typed.toLowerCase())
+  if (insensitive) return insensitive
+
+  const partial = names.filter((n) => n.toLowerCase().includes(typed.toLowerCase()))
+  const suggestion =
+    partial.length > 0
+      ? `did you mean ${partial.slice(0, 3).join(', ')}?`
+      : `known object types: ${names.join(', ') || '(none readable with this credential)'}`
+
+  throw new CliError(`no object type named "${typed}"`, { code: 'NOT_FOUND', hint: suggestion })
+}
+
+export const blueprintGet: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'get',
+    args: [
+      {
+        name: 'apiName',
+        required: true,
+        description: 'object type api name from `frontera blueprint list` (e.g. Shipment); case is corrected for you',
+      },
+    ],
+    flags: {},
+    summary: 'Show one object type: its properties, relations and metrics',
+    examples: ['frontera blueprint get Shipment', 'frontera blueprint get shipment --json'],
+  },
+
+  async run(ctx) {
+    const typed = ctx.positional[0]
+    if (!typed) {
+      throw new UsageError(
+        'missing <apiName>',
+        'run `frontera blueprint list` and pass a name from the API NAME column',
+      )
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+
+    // The response is `{ objectType, properties }`, NOT a flat object type.
+    // Reading apiName off the top level silently yielded undefined and fell
+    // back to whatever the caller typed — so the header echoed the input and
+    // looked correct only when the case already matched.
+    let payload: { objectType?: ObjectTypeRow & { description?: string | null }; properties?: Property[] }
+    try {
+      payload = (await api.blueprintObjectType(typed)) as typeof payload
+    } catch {
+      // Miss: resolve the case, or fail with the names that do exist.
+      payload = (await api.blueprintObjectType(await resolveApiName(api, typed))) as typeof payload
+    }
+
+    const type = payload.objectType ?? {}
+    const apiName = type.apiName ?? typed
+
+    // Relations and metrics, not just columns. A property list alone says what
+    // a table holds and nothing about how it joins or what is measured on it —
+    // which is most of what someone designing against the model needs.
+    //
+    // Both key on object-type UUIDs, not api names, so the catalog is fetched
+    // to resolve them. Matching on names silently produced "Relations (0)" for
+    // a type with eight of them.
+    const [links, metrics, types] = await Promise.all([
+      api.blueprintLinkTypes().catch(() => [] as unknown[]),
+      api.blueprintMetrics().catch(() => [] as unknown[]),
+      api.blueprintObjectTypes().catch(() => [] as unknown[]),
+    ])
+
+    const nameById = new Map<string, string>()
+    for (const t of types as Array<{ id?: string; apiName?: string }>) {
+      if (t.id && t.apiName) nameById.set(t.id, t.apiName)
+    }
+    const selfId = (type as { id?: string }).id ?? ''
+
+    const related = (links as Link[]).filter(
+      (l) => l.fromObjectTypeId === selfId || l.toObjectTypeId === selfId,
+    )
+    const own = (metrics as Metric[]).filter((m) => m.objectTypeId === selfId)
+
+    const props = payload.properties ?? []
+    const heading = [apiName, type.displayName].filter(Boolean)
+    const lines = [
+      heading[1] && heading[1] !== heading[0] ? `${heading[0]} — ${heading[1]}` : String(heading[0]),
+      ...(type.description ? ['', type.description] : []),
+      '',
+      `Properties (${props.length})`,
+      ...(props.length === 0
+        ? ['  (none)']
+        : props.map(
+            (p) =>
+              `  ${(p.apiName ?? '?').padEnd(26)}${(p.dataType ?? '').padEnd(12)}${p.propertyType ?? ''}`,
+          )),
+      '',
+      `Relations (${related.length})`,
+      ...(related.length === 0
+        ? ['  (none)']
+        : related.map((l) => {
+            const outbound = l.fromObjectTypeId === selfId
+            const otherId = outbound ? l.toObjectTypeId : l.fromObjectTypeId
+            const other = nameById.get(otherId ?? '') ?? otherId ?? ''
+            return `  ${(l.apiName ?? '?').padEnd(26)}${outbound ? '→' : '←'} ${other.padEnd(18)}${l.cardinality ?? ''}`
+          })),
+      '',
+      `Metrics (${own.length})`,
+      ...(own.length === 0
+        ? ['  (none)']
+        : own.map((m) => `  ${(m.apiName ?? '?').padEnd(26)}${m.displayName ?? ''}`)),
+    ]
+
+    return {
+      data: { ...payload, relations: related, metrics: own },
+      text: lines.join('\n'),
+    }
+  },
+}

package/src/commands/blueprint/list.ts

@@ -0,0 +1,48 @@
+import { PlatformApi } from '../../api/platform-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+interface ObjectTypeRow {
+  apiName?: string
+  displayName?: string
+  description?: string | null
+}
+
+/**
+ * What data does this workspace actually have?
+ *
+ * An app is built on the Blueprint SDK, so an agent authoring one has to know
+ * the object types before it can design against them. Reads resolve through
+ * the workspace's granted slice, so what appears here is exactly what the app
+ * will be able to query at runtime — anything absent is absent for the app too.
+ */
+export const blueprintList: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List the object types this workspace can read',
+    examples: ['frontera blueprint list', 'frontera blueprint list --json'],
+  },
+
+  async run(ctx) {
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const types = (await api.blueprintObjectTypes()) as ObjectTypeRow[]
+
+    return {
+      data: types,
+      text:
+        types.length === 0
+          ? 'No object types are readable with this credential.'
+          : // API NAME first and labelled: it is the value `blueprint get`
+            // takes, and unlabelled columns left a reader guessing which of
+            // the two names to pass.
+            table(
+              ['api name', 'display name', 'description'],
+              types.map((t) => [t.apiName ?? '?', t.displayName ?? '', t.description ?? '']),
+              [undefined, undefined, 70],
+            ),
+    }
+  },
+}

package/src/commands/blueprint/reserved.ts

@@ -0,0 +1,40 @@
+import type { Command } from '../types'
+
+/**
+ * Blueprint AUTHORING is not built yet.
+ *
+ * Reserved in the command table rather than left out, and this is the whole
+ * point of the distinction: a caller that reads "unknown command" concludes it
+ * mistyped and retries, while one that reads the real reason picks another
+ * route. An absent command and a deliberately withheld one are different
+ * facts.
+ *
+ * What is not ready is the organization-level shared draft — its revision
+ * lifecycle, adoption and grant model — not the noun. Reading ships today.
+ */
+const MESSAGE =
+  'blueprint authoring is not available in this release; ' +
+  '`frontera blueprint list` and `frontera blueprint get` are read-only'
+
+const RESERVED_VERBS = [
+  { verb: 'create', summary: 'Create an object type on the shared draft' },
+  { verb: 'apply', summary: 'Apply a Blueprint document to the shared draft' },
+  { verb: 'grant', summary: 'Grant Blueprint access to a workspace or agent' },
+  { verb: 'publish', summary: 'Publish the shared draft as a release' },
+] as const
+
+export const blueprintReserved: Command[] = RESERVED_VERBS.map(({ verb, summary }) => ({
+  meta: {
+    noun: 'blueprint',
+    verb,
+    args: [],
+    flags: {},
+    summary,
+    examples: [`frontera blueprint ${verb}`],
+    reserved: MESSAGE,
+  },
+  async run() {
+    // Unreachable: the shell refuses a reserved command before dispatch.
+    throw new Error(MESSAGE)
+  },
+}))

package/src/commands/completion.ts

@@ -0,0 +1,293 @@
+import { UsageError } from '../errors'
+import type { CommandDescriptor } from './registry'
+import type { Command } from './types'
+
+/**
+ * Shell completion, generated from the command table.
+ *
+ * Bun, Codex and Claude Code all ship one; hand-written completion is also how
+ * every one of them has at some point advertised a flag that no longer exists.
+ * Generating it from the same index `--help` renders means it cannot describe a
+ * command that is not there.
+ *
+ * Reserved verbs are excluded: completing to something that always fails is
+ * worse than not completing at all.
+ *
+ * The index is PASSED IN rather than imported. This module is listed in the
+ * command table, so importing the table statically closed a cycle — and a
+ * cycle only bites when module evaluation happens to reach one side first,
+ * which made it pass locally on one Bun version and fail on CI's. The type
+ * import above is erased at runtime, so it cannot reintroduce it.
+ */
+const SHELLS = ['bash', 'zsh', 'fish'] as const
+type Shell = (typeof SHELLS)[number]
+
+type Index = readonly CommandDescriptor[]
+
+function available(index: Index): CommandDescriptor[] {
+  return index.filter((c) => c.available)
+}
+
+function nounsIn(index: Index): string[] {
+  return [...new Set(available(index).map((c) => c.noun))]
+}
+
+function verbsFor(index: Index, noun: string): string[] {
+  return available(index)
+    .filter((c) => c.noun === noun && c.verb !== '')
+    .map((c) => c.verb)
+}
+
+function flagsForNounVerb(index: Index, noun: string, verb: string): string[] {
+  const command = available(index).find((c) => c.noun === noun && c.verb === verb)
+  return command ? command.flags.map((f) => `--${f.name}`) : []
+}
+
+/**
+ * The flags every command shares — the fallback when nothing more specific
+ * matches. Intersection rather than "whatever some command happens to carry":
+ * picking a sample command advertised its own flags everywhere the moment that
+ * command grew one.
+ */
+function globalFlags(index: Index): string[] {
+  const commands = available(index)
+  const first = commands[0]
+  if (!first) return []
+  return first.flags
+    .map((f) => `--${f.name}`)
+    .filter((flag) => commands.every((c) => c.flags.some((f) => `--${f.name}` === flag)))
+}
+
+/**
+ * What a NOUN means, as opposed to what its first verb does.
+ *
+ * Without this, `app` was described as "Scaffold a new Frontera app project" —
+ * the summary of whichever command happened to sort first. A menu that
+ * describes the group by one of its members is worse than terse.
+ */
+export type NounSummaries = Readonly<Record<string, string>>
+
+function summaryForNoun(index: Index, summaries: NounSummaries, noun: string): string {
+  return summaries[noun] || available(index).find((c) => c.noun === noun)!.summary
+}
+
+/** Nouns handled by main.ts rather than the table, so they are not in it. */
+const BUILTINS: ReadonlyArray<{ noun: string; summary: string }> = [
+  { noun: 'help', summary: 'Show every command' },
+  { noun: 'version', summary: 'Print the CLI version' },
+]
+
+function bash(index: Index): string {
+  const withVerbs = nounsIn(index).filter((n) => verbsFor(index, n).length > 0)
+  const cases = withVerbs
+    .map((noun) => `      ${noun}) verbs="${verbsFor(index, noun).join(' ')}" ;;`)
+    .join('\n')
+
+  const flagCases = withVerbs
+    .flatMap((noun) =>
+      verbsFor(index, noun).map(
+        (verb) =>
+          `      "${noun} ${verb}") flags="${flagsForNounVerb(index, noun, verb).join(' ')}" ;;`,
+      ),
+    )
+    .join('\n')
+
+  const globals = globalFlags(index)
+
+  return `# frontera completion for bash — generated, do not edit
+_frontera() {
+  local cur prev nouns verbs flags
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    nouns="${[...nounsIn(index), ...BUILTINS.map((b) => b.noun)].join(' ')}"
+    COMPREPLY=( \$(compgen -W "\$nouns" -- "\$cur") )
+    return
+  fi
+
+  if [ "\$COMP_CWORD" -eq 2 ]; then
+    case "\${COMP_WORDS[1]}" in
+${cases}
+      *) verbs="" ;;
+    esac
+    COMPREPLY=( \$(compgen -W "\$verbs" -- "\$cur") )
+    return
+  fi
+
+  case "\${COMP_WORDS[1]} \${COMP_WORDS[2]}" in
+${flagCases}
+    *) flags="${globals.join(' ')}" ;;
+  esac
+  COMPREPLY=( \$(compgen -W "\$flags" -- "\$cur") )
+}
+complete -F _frontera frontera
+`
+}
+
+/**
+ * A description inside a zsh `name:description` spec.
+ *
+ * The colon is the separator, so an unescaped one in the text silently turns
+ * the rest of the summary into a completion ACTION — `get:Show one object
+ * type: its properties` ran `its properties` as a completion function. Single
+ * quotes are dropped rather than escaped: the spec is single-quoted, and a
+ * summary is prose, not a value anyone parses back out.
+ */
+function zshDescription(text: string): string {
+  return text.replace(/'/g, '').replace(/:/g, '\\:')
+}
+
+function zsh(index: Index, nounSummaries: NounSummaries): string {
+  const nounLines = [
+    ...nounsIn(index).map(
+      (noun) => `    '${noun}:${zshDescription(summaryForNoun(index, nounSummaries, noun))}'`,
+    ),
+    ...BUILTINS.map((b) => `    '${b.noun}:${zshDescription(b.summary)}'`),
+  ].join('\n')
+
+  const verbBlocks = nounsIn(index)
+    .filter((n) => verbsFor(index, n).length > 0)
+    .map((noun) => {
+      const lines = available(index)
+        .filter((c) => c.noun === noun && c.verb !== '')
+        .map((c) => `          '${c.verb}:${zshDescription(c.summary)}'`)
+        .join('\n')
+      return `      ${noun})\n        verbs=(\n${lines}\n        )\n        ;;`
+    })
+    .join('\n')
+
+  const flagBlocks = nounsIn(index)
+    .filter((n) => verbsFor(index, n).length > 0)
+    .flatMap((noun) =>
+      verbsFor(index, noun).map(
+        (verb) =>
+          `      "${noun} ${verb}") flags=(${flagsForNounVerb(index, noun, verb).join(' ')}) ;;`,
+      ),
+    )
+    .join('\n')
+
+  /**
+   * Arrays plus `_describe`, not a line-continued `_values`.
+   *
+   * The continuation is what broke: only the first spec line carried a `\`, so
+   * zsh ran every line after it as a command and the caller got a screen of
+   * `command not found: login:Verify a workspace key` on every TAB. An array
+   * literal needs no continuation at all, which is the point — the generator
+   * cannot emit a half-continued one.
+   */
+  return `#compdef frontera
+# frontera completion for zsh — generated, do not edit
+_frontera() {
+  local -a nouns verbs flags
+
+  if (( CURRENT == 2 )); then
+    nouns=(
+${nounLines}
+    )
+    _describe -t commands 'frontera command' nouns
+    return
+  fi
+
+  if (( CURRENT == 3 )); then
+    case "\${words[2]}" in
+${verbBlocks}
+    esac
+    if (( \${#verbs} )); then
+      _describe -t verbs "frontera \${words[2]}" verbs
+    else
+      _files
+    fi
+    return
+  fi
+
+  case "\${words[2]} \${words[3]}" in
+${flagBlocks}
+    *) flags=(${globalFlags(index).join(' ')}) ;;
+  esac
+
+  # Only when a flag is what is being typed: everything else in this position
+  # is an id or a path, and offering \`--json\` for an agent id helps no one.
+  if [[ "\${words[CURRENT]}" == -* ]]; then
+    compadd -- \${flags}
+  else
+    _files
+  fi
+}
+_frontera "\$@"
+`
+}
+
+function fish(index: Index, nounSummaries: NounSummaries): string {
+  const lines: string[] = ['# frontera completion for fish — generated, do not edit']
+  lines.push('complete -c frontera -f')
+
+  for (const noun of nounsIn(index)) {
+    const summary = summaryForNoun(index, nounSummaries, noun)
+    lines.push(
+      `complete -c frontera -n "__fish_use_subcommand" -a "${noun}" -d "${summary.replace(/"/g, "'")}"`,
+    )
+  }
+
+  for (const builtin of BUILTINS) {
+    lines.push(
+      `complete -c frontera -n "__fish_use_subcommand" -a "${builtin.noun}" -d "${builtin.summary}"`,
+    )
+  }
+
+  for (const c of available(index)) {
+    if (!c.verb) continue
+    lines.push(
+      `complete -c frontera -n "__fish_seen_subcommand_from ${c.noun}" -a "${c.verb}" -d "${c.summary.replace(/"/g, "'")}"`,
+    )
+  }
+  return `${lines.join('\n')}\n`
+}
+
+const GENERATORS: Record<Shell, (index: Index, nounSummaries: NounSummaries) => string> = {
+  bash,
+  zsh,
+  fish,
+}
+
+export function completionScript(
+  shell: Shell,
+  index: Index,
+  nounSummaries: NounSummaries = {},
+): string {
+  return GENERATORS[shell](index, nounSummaries)
+}
+
+export const completionCommand: Command = {
+  meta: {
+    noun: 'completion',
+    verb: '',
+    args: [{ name: 'shell', required: true, description: `one of: ${SHELLS.join(', ')}` }],
+    flags: {},
+    summary: 'Print a shell completion script',
+    examples: [
+      'frontera completion zsh > ~/.zfunc/_frontera',
+      'frontera completion bash >> ~/.bashrc',
+    ],
+    // Nothing here talks to the API, and someone setting up their shell has
+    // usually not logged in yet.
+    offline: true,
+  },
+
+  async run(ctx) {
+    const shell = ctx.positional[0]
+    if (!shell || !SHELLS.includes(shell as Shell)) {
+      throw new UsageError(
+        shell ? `unsupported shell: ${shell}` : 'missing <shell>',
+        `frontera completion <${SHELLS.join('|')}>`,
+      )
+    }
+
+    // Imported HERE, not at module scope: this command is in the table it
+    // reads, and a static import would close the cycle again. By call time
+    // both modules are fully initialised.
+    const { describeCommands, nouns, nounSummary } = await import('./registry')
+    const summaries = Object.fromEntries(nouns().map((n) => [n, nounSummary(n)]))
+    const script = completionScript(shell as Shell, describeCommands(), summaries)
+    return { data: { shell, script }, text: script }
+  },
+}

package/src/commands/init.ts

@@ -0,0 +1,33 @@
+import { writeHarnessFiles } from '../harness'
+import { flagBool, type Command } from './types'
+
+/**
+ * Prepare a directory for agent-driven Frontera work.
+ *
+ * Deliberately top-level and offline: it teaches the CLI, so it has to be
+ * reachable from any directory a harness lands in, including one that is not
+ * an app project and before any credential exists.
+ */
+export const initCommand: Command = {
+  meta: {
+    noun: 'init',
+    verb: '',
+    args: [],
+    flags: { force: 'boolean' },
+    summary: 'Write AGENTS.md and the CLI skill into this directory',
+    examples: ['frontera init', 'frontera init --force'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const result = writeHarnessFiles(ctx.cwd, { force: flagBool(ctx, 'force') })
+
+    const lines = [
+      ...result.written.map((f) => `  + ${f}`),
+      ...result.skipped.map((f) => `  · ${f} (exists — use --force to replace)`),
+    ]
+    if (lines.length === 0) lines.push('  Already prepared — nothing to write.')
+
+    return { data: result, text: lines.join('\n') }
+  },
+}