@frontera-sdk/cli 0.1.0

package/src/config.ts

@@ -0,0 +1,142 @@
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { CliError, UsageError } from './errors'
+
+export interface Credential {
+  apiUrl: string
+  token: string
+}
+
+type Env = Record<string, string | undefined>
+
+interface StoredConfig {
+  /**
+   * The origin `frontera login` last verified.
+   *
+   * Without it, logging in successfully still left every following command
+   * failing on "no API origin configured" — the credential was stored under a
+   * key nothing knew to look up. Storing the origin is what makes `login` a
+   * complete act rather than half of one.
+   */
+  defaultOrigin?: string
+  origins?: Record<string, { token?: string }>
+}
+
+const KEYCHAIN_SERVICE = 'frontera-cli'
+
+/**
+ * XDG, not `~/.frontera`.
+ *
+ * The spec assigns credentials to `$XDG_CONFIG_HOME` and disposable data to
+ * `$XDG_CACHE_HOME`; `gh` follows it, and Supabase's `~/.supabase` is its
+ * fallback rather than its design. A bare dotfile directory is the shape
+ * nobody chose deliberately.
+ */
+export function configPath(env: Env = process.env): string {
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config')
+  return join(base, 'frontera', 'config.json')
+}
+
+/** Disposable, keyed by API origin because the registry is per-deployment. */
+export function cacheDir(apiUrl: string, env: Env = process.env): string {
+  const base = env.XDG_CACHE_HOME || join(env.HOME || homedir(), '.cache')
+  const key = createHash('sha256').update(apiUrl).digest('hex').slice(0, 16)
+  return join(base, 'frontera', key)
+}
+
+function readStored(env: Env): StoredConfig {
+  const path = configPath(env)
+  if (!existsSync(path)) return {}
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as StoredConfig
+  } catch {
+    // A corrupt config must not brick every command — treat it as absent and
+    // let the missing-credential error say what to do.
+    return {}
+  }
+}
+
+/**
+ * macOS keychain read. Returns null on any failure, including "not macOS" and
+ * "no keychain in this sandbox" — both ordinary, since the file fallback is
+ * the hot path in CI and inside the Computer.
+ */
+function readKeychain(apiUrl: string): string | null {
+  try {
+    const res = spawnSync(
+      'security',
+      ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', apiUrl, '-w'],
+      { encoding: 'utf8' },
+    )
+    if (res.status !== 0) return null
+    const value = res.stdout.trim()
+    return value || null
+  } catch {
+    return null
+  }
+}
+
+export interface CredentialDeps {
+  env?: Env
+  keychain?: (apiUrl: string) => string | null
+}
+
+/**
+ * Resolve the API origin and token.
+ *
+ * Order: `--api-url` → environment → OS keychain → XDG config file. The
+ * environment keeps precedence over stored credentials so that adding storage
+ * changes nothing for the Computer or CI, both of which set the variable.
+ *
+ * The token is never read from a flag. A secret in a flag lands in process
+ * listings and shell history, and a CLI that offers the option will have it
+ * used.
+ */
+export function resolveCredential(
+  opts: { apiUrl?: string } = {},
+  deps: CredentialDeps = {},
+): Credential {
+  const env = deps.env ?? process.env
+  const keychain = deps.keychain ?? readKeychain
+
+  const stored = readStored(env)
+  const apiUrl = opts.apiUrl || env.FRONTERA_API_URL || stored.defaultOrigin
+  if (!apiUrl) {
+    throw new UsageError(
+      'no API origin configured',
+      'run `frontera login --api-url <origin>`, set FRONTERA_API_URL, or pass --api-url',
+    )
+  }
+
+  const token = env.FRONTERA_TOKEN || keychain(apiUrl) || stored.origins?.[apiUrl]?.token
+
+  if (!token) {
+    throw new CliError(`no credential for ${apiUrl}`, {
+      code: 'UNAUTHORIZED',
+      hint: `set FRONTERA_TOKEN to an sk-ws- workspace key, or store one at ${configPath(env)}`,
+    })
+  }
+
+  return { apiUrl, token }
+}
+
+/** Persist a token for one origin, leaving any other origin's untouched. */
+export function writeStoredToken(apiUrl: string, token: string, env: Env = process.env): void {
+  const path = configPath(env)
+  const current = readStored(env)
+  const next: StoredConfig = {
+    ...current,
+    // The most recent successful login becomes the default, so the next
+    // command needs no environment at all.
+    defaultOrigin: apiUrl,
+    origins: { ...current.origins, [apiUrl]: { token } },
+  }
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`)
+  // 0600 because this holds a key with full workspace write.
+  chmodSync(path, 0o600)
+}

package/src/context.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import { UsageError } from './errors'
+import { readProject, type ProjectConfig } from './project'
+
+export interface AppProject extends ProjectConfig {
+  /** Absolute path of the directory holding package.json. */
+  root: string
+}
+
+export interface Context {
+  cwd: string
+  /** Resolved lazily by the commands that need it — see `requireProject`. */
+  project: AppProject | null
+  apiUrl: string
+  token: string
+}
+
+/**
+ * Is this directory the root of a Frontera app project?
+ *
+ * The marker is `package.json` carrying a `frontera` field, which the scaffold
+ * writes at init (`frontera: { displayName }`) and `writeAppId` fills in after
+ * the first deploy. A bare `package.json` deliberately does NOT match: without
+ * the field, every JavaScript repository on the machine would look like an app.
+ */
+function isProjectRoot(dir: string): boolean {
+  const pkgPath = join(dir, 'package.json')
+  if (!existsSync(pkgPath)) return false
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { frontera?: unknown }
+    return typeof pkg.frontera === 'object' && pkg.frontera !== null
+  } catch {
+    // A malformed package.json is not a project — and must not abort the walk,
+    // since an unrelated broken file higher up would strand a valid project.
+    return false
+  }
+}
+
+/**
+ * Walk up from `from` to the filesystem root looking for a project.
+ *
+ * Nearest wins, so an app nested inside another tree resolves to itself.
+ * Returns null rather than throwing; `requireProject` owns the error, because
+ * only some commands need a project at all.
+ */
+export function findProjectRoot(from: string): string | null {
+  let dir = resolve(from)
+  for (;;) {
+    if (isProjectRoot(dir)) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+export function requireProject(from: string): AppProject {
+  const root = findProjectRoot(from)
+  if (!root) {
+    throw new UsageError(
+      'not in a Frontera app directory',
+      'cd into an app project, or run `frontera app init <name>`',
+    )
+  }
+  return { ...readProject(root), root }
+}

package/src/errors.ts

@@ -0,0 +1,30 @@
+/**
+ * Errors the CLI raises itself.
+ *
+ * Distinct from `FronteraError`, which carries a code the SERVICE emitted.
+ * Both reach the same renderer and the same exit-code mapping; the difference
+ * is only who decided the request was wrong.
+ *
+ * Every CliError carries a `hint` naming the next command. An error that
+ * leaves the caller — usually a model — with nothing to try next is
+ * incomplete, and a wrong retry costs more than the message saved.
+ */
+export class CliError extends Error {
+  readonly code: string
+  readonly hint?: string
+
+  constructor(message: string, opts: { code: string; hint?: string }) {
+    super(message)
+    this.name = 'CliError'
+    this.code = opts.code
+    if (opts.hint) this.hint = opts.hint
+  }
+}
+
+/** Bad invocation: unknown flag, missing value, wrong arity. Always exit 2. */
+export class UsageError extends CliError {
+  constructor(message: string, hint?: string) {
+    super(message, hint ? { code: 'USAGE', hint } : { code: 'USAGE' })
+    this.name = 'UsageError'
+  }
+}

package/src/exit.ts

@@ -0,0 +1,98 @@
+import { CliError } from './errors'
+
+/**
+ * Exit codes, one per action the caller can take.
+ *
+ * A caller — usually a model — checks the code before parsing anything, so
+ * each one has to map to a genuinely different next move. Conflict and auth
+ * earn their own codes for that reason: no retry fixes a 4, and a 3 has a
+ * specific two-step recovery that can be automated.
+ */
+export const EXIT = {
+  OK: 0,
+  /** Transient or remote. Retry, then report. */
+  FAILURE: 1,
+  /** Bad invocation or bad input. Fix the command. */
+  USAGE: 2,
+  /** Someone else changed it first. Re-fetch, reapply. */
+  CONFLICT: 3,
+  /** Credentials or permission. Neither retry nor rewording helps. */
+  AUTH: 4,
+} as const
+
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT]
+
+export interface ErrorEnvelope {
+  error: true
+  code: string
+  message: string
+  hint?: string
+}
+
+const USAGE_CODES = new Set(['USAGE', 'VALIDATION_ERROR', 'BAD_REQUEST', 'NOT_FOUND'])
+const CONFLICT_CODES = new Set(['DRAFT_CONFLICT', 'CONFLICT', 'VALIDATION_STALE'])
+const AUTH_CODES = new Set(['UNAUTHORIZED', 'FORBIDDEN'])
+
+/**
+ * Unrecognised codes fall to FAILURE rather than throwing. The SDK does not
+ * enumerate service codes — deliberately, so the service can add one without
+ * an SDK release — which means this function must treat "never seen it" as
+ * ordinary, not exceptional.
+ */
+export function exitCodeFor(code: string): ExitCode {
+  if (USAGE_CODES.has(code)) return EXIT.USAGE
+  if (CONFLICT_CODES.has(code)) return EXIT.CONFLICT
+  if (AUTH_CODES.has(code)) return EXIT.AUTH
+  return EXIT.FAILURE
+}
+
+/**
+ * Hints for codes the SERVICE raises. A `CliError` brings its own, because the
+ * CLI knows exactly which command failed; for a service code the best we can
+ * say is what class of recovery applies.
+ */
+const SERVICE_HINTS: Record<string, string> = {
+  DRAFT_CONFLICT: 'someone else changed it first — re-fetch, reapply your edit, then try again',
+  // Deliberately vaguer than DRAFT_CONFLICT. The service also raises CONFLICT
+  // for "this identity already exists" — an immutable version being republished
+  // — where re-fetching and reapplying does nothing at all. Commands that know
+  // which case they are in throw a CliError with a specific hint instead.
+  CONFLICT: 'the message above names what conflicted — resolve that, then retry',
+  VALIDATION_STALE: 're-fetch the resource and re-run validation against the current revision',
+  UNAUTHORIZED: 'set FRONTERA_TOKEN to a valid sk-ws- workspace key',
+  FORBIDDEN: 'this credential lacks permission for that resource — ask an admin, or use a different key',
+  NOT_FOUND: 'list the resource first to confirm the id',
+  RATE_LIMITED: 'wait and retry',
+  SERVICE_UNAVAILABLE: 'the service is unavailable — retry shortly',
+}
+
+function isFronteraError(err: unknown): err is { code: string; message: string } {
+  return (
+    err instanceof Error &&
+    'code' in err &&
+    typeof (err as { code: unknown }).code === 'string'
+  )
+}
+
+/** Normalise anything thrown into the one envelope shape stderr emits. */
+export function toEnvelope(err: unknown): ErrorEnvelope {
+  if (err instanceof CliError) {
+    return {
+      error: true,
+      code: err.code,
+      message: err.message,
+      ...(err.hint ? { hint: err.hint } : {}),
+    }
+  }
+
+  if (isFronteraError(err)) {
+    const hint = SERVICE_HINTS[err.code]
+    return { error: true, code: err.code, message: err.message, ...(hint ? { hint } : {}) }
+  }
+
+  return {
+    error: true,
+    code: 'INTERNAL_ERROR',
+    message: err instanceof Error ? err.message : String(err),
+  }
+}

package/src/flag-help.ts

@@ -0,0 +1,70 @@
+/**
+ * What every flag means, in one place.
+ *
+ * `--help` used to print a bare list of flag names with no descriptions at
+ * all — the reader learned that `--expect-revision` exists and nothing about
+ * what to pass it. Codex and Claude Code describe every option; so does this
+ * now.
+ *
+ * Central rather than per-command because a flag name means the same thing
+ * everywhere it appears: `--force` overrides a refusal, `--json` switches the
+ * output contract. Declaring it once removes the way that guarantee usually
+ * dies — the same flag described two different ways in two commands. A test
+ * fails if a command declares a flag this file does not describe.
+ */
+export const FLAG_HELP: Readonly<Record<string, string>> = {
+  // Global
+  json: 'machine-readable output on stdout; stderr still carries commentary',
+  quiet: 'suppress progress commentary on stderr',
+  yes: 'assume yes for confirmations',
+  help: 'show this help',
+  'api-url': 'API origin to use, overriding FRONTERA_API_URL and the stored default',
+
+  // Project resolution
+  dir: 'project directory to act on (default: walk up from the working directory)',
+
+  // Writes
+  file: 'read the document from this path, or `-` for stdin',
+  force: 'proceed past a refusal — overwrite existing files, or a dirty tree',
+  'expect-revision':
+    'refuse the write unless the resource is still at this revision; exit 3 if it moved',
+  notes: 'note recorded against the published version',
+
+  // Apps
+  version: 'version to publish, overriding the one in package.json',
+  'no-promote': 'publish the version without moving the live pointer',
+  draft: 'act on your saved draft rather than a published version',
+
+  // Auth and setup
+  'token-stdin': 'read the workspace key from stdin instead of prompting',
+  'no-input': 'never prompt; fail instead, for use in scripts and CI',
+  config: 'print the resolved configuration and where each value came from',
+}
+
+/**
+ * What a value-taking flag expects, so the placeholder says something. `--dir
+ * <value>` tells the reader only that a value goes there; `--dir <path>` tells
+ * them what kind.
+ */
+const PLACEHOLDER: Readonly<Record<string, string>> = {
+  'api-url': 'origin',
+  dir: 'path',
+  file: 'path',
+  version: 'semver',
+  'expect-revision': 'hash',
+  notes: 'text',
+}
+
+/**
+ * `--flag <thing>` or `--flag`, so the reader can see which take an argument
+ * without cross-referencing anything.
+ */
+export function flagUsage(name: string, type: 'string' | 'boolean', alias?: string): string {
+  const short = alias ? `-${alias}, ` : ''
+  if (type === 'boolean') return `${short}--${name}`
+  return `${short}--${name} <${PLACEHOLDER[name] ?? 'value'}>`
+}
+
+export function describeFlag(name: string): string {
+  return FLAG_HELP[name] ?? ''
+}

package/src/harness.ts

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * Files that prepare a directory for a coding harness.
+ *
+ * A skill only works where a harness scans. `.agents/skills/` is the
+ * vendor-neutral location, and AGENTS.md is what most harnesses read first —
+ * so the contract is placed in the project, committed, rather than hidden in
+ * a home directory nothing looks at.
+ *
+ * The skill ROUTES; it does not restate. `--help` is generated from the
+ * command table, so it is authoritative for syntax, and a skill that listed
+ * flags would drift into handing a model wrong instructions. What lives here
+ * is workflow, invariants and recovery — the things `--help` cannot say.
+ */
+const SKILL = `---
+name: using-frontera-cli
+description: Use when reading or changing anything on the Frontera platform from a shell — agents, skills, plugins, knowledge, Blueprint, apps, or automations — via the \`frontera\` CLI.
+---
+
+# Using the Frontera CLI
+
+\`frontera <noun> <verb>\`. Help is generated from the command table, so it is
+never out of date — read it instead of guessing, and instead of trusting this
+file for syntax.
+
+## Discover the surface as data
+
+\`\`\`bash
+frontera help --json
+\`\`\`
+
+Returns every command: usage, arguments, flags with types, examples, whether it
+is available, and two preconditions worth knowing before you call — whether it
+needs an app project (\`needsProject\`) and whether it needs a credential
+(\`requiresCredential\`). Narrow it with \`frontera <noun> --help --json\`, or one
+command with \`frontera <noun> <verb> --help --json\`.
+
+Prefer this over parsing \`--help\` text. Everything \`--help\` shows is in it,
+and it cannot drift, because both are projected from the same table.
+
+## The two shapes
+
+**Apps are projects.** \`frontera app …\` resolves the project by walking up from
+the working directory, so run it from anywhere inside the app. Not in one is an
+error naming the fix.
+
+**Everything else is addressed by id.** \`frontera agent get <id>\` writes a
+document to stdout; edit it; \`frontera agent apply <id> -f <file>\` sends it
+back. Nothing is implicit, so nothing goes stale.
+
+## Reading the result
+
+Pass \`--json\` for machine-readable output. The contract:
+
+- **stdout is data and nothing else.** Progress and errors go to stderr.
+- **exit 0 means stdout is trustworthy.** Check the code before parsing.
+
+| Exit | Meaning | What to do |
+|------|---------|-----------|
+| 0 | success | continue |
+| 1 | transient or remote failure | retry, then report |
+| 2 | usage or input error | fix the command |
+| 3 | conflict — someone changed it first | re-fetch, reapply, retry |
+| 4 | auth or permission | different credential, or ask an admin |
+
+Errors carry a \`hint\` naming the next command. Read it.
+
+## Invariants
+
+- **On exit 3, re-fetch — never force.** The document you hold is stale. Get it
+  again, reapply your edit on top, then send it. Overwriting discards whatever
+  the other writer did.
+- **Secrets never go in a flag.** Use \`--secret name@-\` (stdin), \`name@./file\`,
+  or \`name=ref:<workspace-secret>\`. A value on the command line lands in
+  process listings and shell history.
+- **\`.env\` is never packaged**, and that is not overridable.
+- **A pull refuses to clobber.** If it reports dirty files, deal with them —
+  inside a sandbox there is usually no git to recover from.
+
+## Building an app
+
+\`\`\`bash
+frontera app init <name>        # scaffold — installs with public npm only
+bun install
+frontera blueprint list         # what data this workspace actually has
+frontera app add <component>    # registry source into the project
+bun run typecheck               # vite build does NOT type-check
+bun run build                   # the deploy gate — must succeed
+frontera app deploy --no-promote
+frontera app promote <version>
+\`\`\`
+
+Read \`frontera blueprint list\` and \`frontera blueprint get <apiName>\` before
+designing against data. What they return is the slice this workspace is granted,
+which is exactly what the app will be able to query at runtime — so anything
+absent there will be absent for the app too.
+
+\`src/frontera/\` in a scaffolded project is the SDK, copied in as source so the
+project installs anywhere. Read it; never edit it, never rewrite an
+\`@frontera-sdk/…\` import to a relative path, never add \`@frontera-sdk/*\` to
+\`package.json\`. The project's own \`using-frontera-sdk\` skill has the detail.
+
+\`bun run dev\` serves the app, but opening \`/\` directly renders "This app runs
+inside Frontera" instead of mounting: the handshake refuses an unknown parent,
+which is correct, not a broken build.
+
+Open **\`/dev-host.html\`** instead. It frames the app and plays the host side of
+the bridge, so the app mounts and reads real data. That is the URL to screenshot
+or click through when verifying your work — a screenshot of \`/\` is a screenshot
+of the refusal panel.
+`
+
+const AGENTS_MD = `# Frontera
+
+This directory works with the Frontera platform through the \`frontera\` CLI.
+
+Load the skill at \`.agents/skills/using-frontera-cli/SKILL.md\` before running
+any \`frontera\` command. It carries the workflow, the exit-code contract and the
+invariants that are not obvious from \`--help\`.
+
+For syntax, run \`frontera help\` or \`frontera <noun> <verb> --help\` — help is
+generated from the command table and is always current.
+`
+
+export interface HarnessResult {
+  written: string[]
+  skipped: string[]
+}
+
+/**
+ * Idempotent: an existing file is left alone unless `force`, so re-running
+ * changes nothing and never clobbers a customised AGENTS.md.
+ */
+export function writeHarnessFiles(dir: string, opts: { force?: boolean } = {}): HarnessResult {
+  const files: Array<[string, string]> = [
+    ['AGENTS.md', AGENTS_MD],
+    [join('.agents', 'skills', 'using-frontera-cli', 'SKILL.md'), SKILL],
+  ]
+
+  const written: string[] = []
+  const skipped: string[] = []
+
+  for (const [rel, content] of files) {
+    const dest = join(dir, rel)
+    if (existsSync(dest) && !opts.force) {
+      // Unchanged content is not a conflict — report it as written so a
+      // re-run reads as a no-op rather than a refusal.
+      if (readFileSync(dest, 'utf8') === content) continue
+      skipped.push(rel)
+      continue
+    }
+    mkdirSync(dirname(dest), { recursive: true })
+    writeFileSync(dest, content)
+    written.push(rel)
+  }
+
+  return { written, skipped }
+}
+
+export const HARNESS_SKILL_BODY = SKILL