@frontera-sdk/cli 0.1.0

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

@@ -0,0 +1,348 @@
+import { readFileSync } from 'node:fs'
+
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagString, type Command, type CommandContext } from '../types'
+import { renderComposition, type Lookups } from './compose'
+import { resolveAgentRef, type AgentRow } from './resolve'
+
+function api(ctx: CommandContext): PlatformApi {
+  return new PlatformApi(ctx.apiUrl, ctx.token)
+}
+
+async function target(ctx: CommandContext, verb: string): Promise<{ api: PlatformApi; id: string; ref: string }> {
+  const ref = ctx.positional[0]
+  if (!ref) {
+    throw new UsageError(`missing <agent>`, `frontera agent ${verb} <id-or-slug> — see \`frontera agent list\``)
+  }
+  const client = api(ctx)
+  return { api: client, id: await resolveAgentRef(client, ref), ref }
+}
+
+/**
+ * Names for the ids a snapshot carries.
+ *
+ * Best-effort on purpose: a caller whose key cannot list plugins should still
+ * get the agent, with those entries marked unresolved rather than the whole
+ * read failing.
+ */
+async function buildLookups(
+  client: PlatformApi,
+  identity?: { id?: string; slug?: string; kind?: string },
+): Promise<Lookups> {
+  const [plugins, knowledge, skills] = await Promise.all([
+    client.pluginInstalls().catch(() => [] as unknown[]),
+    client.whoami().then((me) => (me.workspaceId ? client.knowledgeBases(me.workspaceId) : [])).catch(() => [] as unknown[]),
+    client.workspaceSkills().catch(() => [] as unknown[]),
+  ])
+
+  const pluginMap = new Map<string, string>()
+  for (const row of plugins as Array<{ install?: { id?: string; installName?: string }; catalog?: { kind?: string; displayName?: string } }>) {
+    const id = row.install?.id
+    if (!id) continue
+    pluginMap.set(id, row.install?.installName ?? row.catalog?.displayName ?? row.catalog?.kind ?? id)
+  }
+
+  const knowledgeMap = new Map<string, string>()
+  for (const row of knowledge as Array<{ id?: string; name?: string; displayName?: string }>) {
+    if (row.id) knowledgeMap.set(row.id, row.name ?? row.displayName ?? row.id)
+  }
+
+  const skillMap = new Map<string, string>()
+  for (const row of skills as Array<{ id?: string; name?: string; displayName?: string }>) {
+    if (row.id) skillMap.set(row.id, row.name ?? row.displayName ?? row.id)
+  }
+
+  return { plugins: pluginMap, knowledge: knowledgeMap, skills: skillMap, ...(identity ? { identity } : {}) }
+}
+
+/** Read a document from `-f <path>`, or from stdin when it is piped. */
+async function readDocument(ctx: CommandContext): Promise<Record<string, unknown>> {
+  const file = flagString(ctx, 'file')
+  let raw: string
+
+  if (file && file !== '-') {
+    try {
+      raw = readFileSync(file, 'utf8')
+    } catch {
+      throw new UsageError(`could not read ${file}`, 'check the path, or pipe the document in with -f -')
+    }
+  } else if (file === '-' || !process.stdin.isTTY) {
+    const chunks: Uint8Array[] = []
+    for await (const chunk of Bun.stdin.stream()) chunks.push(chunk)
+    raw = Buffer.concat(chunks).toString('utf8')
+  } else {
+    throw new UsageError(
+      'no document supplied',
+      'pass -f <file>, or pipe one in: `frontera agent get <id> --draft --json | … | frontera agent apply <id> -f -`',
+    )
+  }
+
+  try {
+    return JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    throw new UsageError('the document is not valid JSON', 'it should be the object `agent get --draft` returns')
+  }
+}
+
+const list: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List agents in this workspace',
+    examples: ['frontera agent list', 'frontera agent list --json'],
+  },
+  async run(ctx) {
+    const rows = (await api(ctx).agents()) as AgentRow[]
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No agents in this workspace.'
+          : // Either ID or SLUG works wherever an agent is named.
+            table(
+              ['id', 'slug', 'kind', 'name'],
+              rows.map((a) => [a.id ?? '?', a.agentId ?? '', a.kind ?? '', a.name ?? '']),
+            ),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'get',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug, from `frontera agent list`' }],
+    flags: { draft: 'boolean', config: 'boolean' },
+    summary: 'Show what an agent is made of — models, prompts, skills, plugins, knowledge',
+    examples: [
+      'frontera agent get sei',
+      'frontera agent get sei --json > agent.json',
+      'frontera agent get sei --draft --json',
+      'frontera agent get sei --config',
+    ],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) {
+      throw new UsageError('missing <agent>', 'frontera agent get <id-or-slug> — see `frontera agent list`')
+    }
+
+    // `--config` is the old behaviour: the settings row alone, no relations.
+    if (ctx.flags.config === true && ctx.flags.draft !== true) {
+      const doc = await api(ctx).agent(ref)
+      return { data: doc, text: JSON.stringify(doc, null, 2) }
+    }
+
+    const t = await target(ctx, 'get')
+
+    if (ctx.flags.draft !== true) {
+      // The full composition, not the config row: prompts, skills, models,
+      // knowledge, plugins and channels are the reason to read an agent.
+      // The lookups turn the snapshot's uuids into names — without them the
+      // human output is a list of identifiers nobody can act on.
+      // The snapshot's config carries neither id, slug, kind nor the published
+      // version, so the config ROW is read alongside it. Two requests for a
+      // complete picture beats one that silently omits what an agent is.
+      const [snapshot, row, lookups] = await Promise.all([
+        t.api.agentComposition(t.id),
+        t.api.agent(t.id).catch(() => null),
+        buildLookups(t.api),
+      ])
+      const identity = (row ?? {}) as {
+        id?: string
+        agentId?: string
+        kind?: string
+        currentVersion?: { versionNumber?: number }
+      }
+      return {
+        data: snapshot,
+        text: renderComposition(snapshot, {
+          ...lookups,
+          identity: {
+            id: identity.id ?? t.id,
+            slug: identity.agentId,
+            kind: identity.kind,
+            version: identity.currentVersion?.versionNumber,
+          },
+        }),
+      }
+    }
+    const draft = await t.api.agentDraft(t.id)
+    if (!draft) {
+      throw new CliError(`no draft staged for ${t.ref}`, {
+        code: 'NOT_FOUND',
+        hint: 'edit the live document instead: `frontera agent get <agent> --json`',
+      })
+    }
+    return { data: draft, text: JSON.stringify(draft, null, 2) }
+  },
+}
+
+const apply: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'apply',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: { file: 'string', 'expect-revision': 'string' },
+    aliases: { f: 'file' },
+    summary: 'Stage a document onto the agent draft (does not publish)',
+    examples: [
+      'frontera agent apply sei -f agent.json',
+      'cat agent.json | frontera agent apply sei -f -',
+    ],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'apply')
+    const document = await readDocument(ctx)
+
+    // Accept either the whole `get --draft` document or a bare snapshot, so a
+    // round trip works without the caller unwrapping anything by hand.
+    const patch = (document.snapshot ?? document) as Record<string, unknown>
+
+    // The revision the caller last read. Passing it is what turns a
+    // concurrent edit into a DRAFT_CONFLICT instead of a silent overwrite.
+    const explicit = flagString(ctx, 'expect-revision')
+    const fromDocument = typeof document.revision === 'number' ? document.revision : undefined
+    const expectedRevision = explicit !== undefined ? Number(explicit) : fromDocument
+
+    if (explicit !== undefined && Number.isNaN(expectedRevision)) {
+      throw new UsageError('--expect-revision must be a number', 'take it from the document you applied')
+    }
+
+    const draft = await t.api.patchAgentDraft(t.id, patch, expectedRevision)
+
+    return {
+      data: draft,
+      text:
+        `Staged a draft for ${t.ref} (revision ${draft.revision}).\n` +
+        `Nothing is live yet — publish with \`frontera agent publish ${t.ref}\`.`,
+    }
+  },
+}
+
+const publish: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'publish',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: { notes: 'string', 'expect-revision': 'string' },
+    summary: 'Publish the staged draft as a new live version',
+    examples: ['frontera agent publish sei', 'frontera agent publish sei --notes "raise temperature"'],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'publish')
+
+    // Read the draft first: it supplies the revision, and its absence is a
+    // clearer failure here than whatever the publish route would return.
+    const draft = await t.api.agentDraft(t.id)
+    if (!draft) {
+      throw new CliError(`no draft staged for ${t.ref}`, {
+        code: 'NOT_FOUND',
+        hint: `stage one first: \`frontera agent apply ${t.ref} -f <file>\``,
+      })
+    }
+
+    const explicit = flagString(ctx, 'expect-revision')
+    const result = await t.api.publishAgent(t.id, {
+      ...(flagString(ctx, 'notes') ? { notes: flagString(ctx, 'notes')! } : {}),
+      expectedRevision: explicit !== undefined ? Number(explicit) : draft.revision,
+    })
+
+    return { data: result, text: `Published ${t.ref} from draft revision ${draft.revision}.` }
+  },
+}
+
+const diff: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'diff',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'Show which sections of the draft differ from what is live',
+    examples: ['frontera agent diff sei'],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'diff')
+    const draft = await t.api.agentDraft(t.id)
+
+    if (!draft) {
+      return { data: { hasDraft: false, changed: [] }, text: 'No draft staged — the live version is current.' }
+    }
+
+    const live = (await t.api.agent(t.id)) as Record<string, unknown>
+    const liveConfig = (live.config ?? live) as Record<string, unknown>
+    const draftConfig = (draft.snapshot.config ?? {}) as Record<string, unknown>
+
+    // Only what the DRAFT declares, and never server-managed bookkeeping.
+    // Taking the union instead reported `createdAt`, `createdBy` and
+    // `currentVersion` as pending changes on a draft that touched none of
+    // them — noise that buries the one field the caller actually staged.
+    const MANAGED = new Set([
+      'id', 'orgId', 'workspaceId', 'createdAt', 'updatedAt', 'createdBy',
+      'currentVersion', 'currentVersionId', 'draft', 'lifecycleStatus',
+    ])
+    const changed = Object.keys(draftConfig)
+      .filter((k) => !MANAGED.has(k))
+      .filter((k) => JSON.stringify(draftConfig[k]) !== JSON.stringify(liveConfig[k]))
+      .sort()
+
+    return {
+      data: { hasDraft: true, revision: draft.revision, changed },
+      text:
+        changed.length === 0
+          ? `Draft revision ${draft.revision} matches the live version.`
+          : [`Draft revision ${draft.revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n'),
+    }
+  },
+}
+
+const discard: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'discard',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'Throw away the staged draft, leaving the live version untouched',
+    examples: ['frontera agent discard sei'],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'discard')
+    await t.api.discardAgentDraft(t.id)
+    return { data: { discarded: true, agent: t.ref }, text: `Discarded the draft for ${t.ref}.` }
+  },
+}
+
+const versions: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'versions',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'List published versions of one agent',
+    examples: ['frontera agent versions sei'],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'versions')
+    const rows = (await t.api.agentVersions(t.id)) as Array<Record<string, unknown>>
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No versions published yet.'
+          : table(
+              ['version', 'published', 'by'],
+              rows.map((v) => [
+                String(v.versionNumber ?? v.version ?? '?'),
+                String(v.publishedAt ?? ''),
+                String(v.publishedBy ?? ''),
+              ]),
+            ),
+    }
+  },
+}
+
+export const agentCommands: Command[] = [list, get, apply, publish, diff, discard, versions]

package/src/commands/agent/resolve.ts

@@ -0,0 +1,58 @@
+import type { PlatformApi } from '../../api/platform-api'
+import { CliError } from '../../errors'
+
+export interface AgentRow {
+  id?: string
+  /** `agent_configs.agentId` — the SLUG, despite the column name. */
+  agentId?: string
+  name?: string
+  kind?: string
+  lifecycleStatus?: string
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Turn an id or a slug into the id every write route needs.
+ *
+ * `GET /config/agents/:ref` resolves either, so one request answers it —
+ * deliberately NOT a scan of `agent list`, which omits agents still in
+ * `configuring`. Resolving from the list made a freshly created agent
+ * unreachable by its own slug, which is exactly the create-then-configure
+ * sequence an agent-driven caller runs.
+ *
+ * Only the draft and publish routes need this: they key on
+ * `agent_drafts.agent_id`, a uuid column, so a slug reaches postgres as a
+ * malformed uuid rather than a lookup.
+ */
+export async function resolveAgentRef(api: PlatformApi, ref: string): Promise<string> {
+  if (UUID.test(ref)) return ref
+
+  try {
+    const agent = (await api.agent(ref)) as { id?: string }
+    if (agent?.id) return agent.id
+  } catch (err) {
+    // A miss is worth a second request to say what DOES exist; anything else
+    // (auth, network) belongs to the caller unchanged.
+    if ((err as { code?: string }).code !== 'NOT_FOUND') throw err
+    throw await notFound(api, ref)
+  }
+
+  throw await notFound(api, ref)
+}
+
+async function notFound(api: PlatformApi, ref: string): Promise<CliError> {
+  const rows = await api.agents().catch(() => [] as unknown[])
+  const near = (rows as AgentRow[])
+    .filter((a) => `${a.agentId ?? ''} ${a.name ?? ''}`.toLowerCase().includes(ref.toLowerCase()))
+    .map((a) => a.agentId ?? a.id)
+    .filter(Boolean)
+
+  return new CliError(`no agent named "${ref}"`, {
+    code: 'NOT_FOUND',
+    hint:
+      near.length > 0
+        ? `did you mean ${near.slice(0, 3).join(', ')}?`
+        : 'run `frontera agent list` to see ids and slugs',
+  })
+}

package/src/commands/app/add.ts

@@ -0,0 +1,78 @@
+import { RegistryApi, type RegistryItem } from '../../api/registry-api'
+import { UsageError } from '../../errors'
+import { missingDependencies, writeRegistryItems } from '../../registry'
+import { flagBool, type Command } from '../types'
+
+/**
+ * Copy registry source into this project.
+ *
+ * Collapses the former `ui add` and `skills add`: the registry already tags
+ * every item with a `type` and already resolves transitive dependencies, so
+ * two verbs were distinguishing something the caller does not have to know.
+ * With `skill` now meaning the platform resource, keeping a second `skills`
+ * verb here would have put one word on two unrelated things.
+ */
+export const appAdd: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'add',
+    args: [{ name: 'name...', required: false, description: 'registry items to copy; omit to list what is available' }],
+    flags: { force: 'boolean' },
+    summary: 'Copy components and authoring skills from the registry into this project',
+    examples: [
+      'frontera app add',
+      'frontera app add data-table',
+      'frontera app add data-table chart --force',
+    ],
+    // Listing the registry is how someone decides what to scaffold, so it must
+    // work outside a project; writing into one still requires it (below).
+    optionalProject: true,
+  },
+
+  async run(ctx) {
+    const registry = new RegistryApi(ctx.apiUrl)
+    const names = ctx.positional
+
+    if (names.length === 0) {
+      const items = await registry.list()
+      return {
+        data: items,
+        text:
+          items.length === 0
+            ? 'Nothing published to the registry yet.'
+            : items.map((i) => `  ${i.name.padEnd(24)} ${i.type.padEnd(6)} ${i.description}`).join('\n'),
+      }
+    }
+
+    const project = ctx.project
+    if (!project) {
+      throw new UsageError(
+        'not in a Frontera app directory',
+        'cd into an app project, or run `frontera app init <name>` — `frontera app add` with no arguments lists the registry from anywhere',
+      )
+    }
+
+    // Resolve every requested item BEFORE writing anything, so one bad name
+    // fails before the project is half-updated.
+    const resolved = new Map<string, RegistryItem>()
+    for (const name of names) {
+      for (const item of await registry.resolve(name)) resolved.set(item.name, item)
+    }
+
+    const result = writeRegistryItems(project.root, [...resolved.values()], {
+      force: flagBool(ctx, 'force'),
+    })
+    const missing = missingDependencies(project.root, result.npmDependencies)
+
+    const lines = [
+      ...result.written.map((f) => `  + ${f}`),
+      ...result.skipped.map((f) => `  · ${f} (exists — use --force to replace)`),
+    ]
+    if (missing.length > 0) lines.push('', `Install the packages these need:`, `  bun add ${missing.join(' ')}`)
+
+    return {
+      data: { written: result.written, skipped: result.skipped, missingDependencies: missing },
+      text: lines.join('\n'),
+    }
+  },
+}

package/src/commands/app/deploy.ts

@@ -0,0 +1,105 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { AppsApi } from '../../api/apps-api'
+import { CliError } from '../../errors'
+import { resolveManifest } from '../../manifest'
+import { collectSourceFiles, formatBytes } from '../../packaging'
+import { packDirectory } from '../../pack'
+import { readPackageVersion, writeAppId, writeState } from '../../project'
+import { createTarGz } from '../../tar'
+import { requireProjectFrom } from './shared'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * Publish, and say the useful thing when the version is taken.
+ *
+ * Versions are immutable, so republishing one is a CONFLICT — but the generic
+ * conflict hint says "re-fetch, reapply your edit", which is the recovery for a
+ * DRAFT conflict and does nothing here. The fix is to bump a number, and this
+ * is the only layer that knows that.
+ */
+async function publish(
+  client: AppsApi,
+  appId: string,
+  args: Parameters<AppsApi['publish']>[1],
+): Promise<{ version: string; promoted: boolean }> {
+  try {
+    return await client.publish(appId, args)
+  } catch (err) {
+    const code = (err as { code?: string }).code
+    if (code === 'CONFLICT' || code === 'DRAFT_CONFLICT') {
+      throw new CliError(`version ${args.version} already exists for this app`, {
+        code: 'CONFLICT',
+        hint: 'versions are immutable — bump "version" in package.json, or pass --version <next>',
+      })
+    }
+    throw err
+  }
+}
+
+export const appDeploy: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'deploy',
+    args: [],
+    flags: { version: 'string', 'no-promote': 'boolean' },
+    summary: 'Build output up to an immutable version, and promote it',
+    examples: ['frontera app deploy', 'frontera app deploy --no-promote'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const project = requireProjectFrom(ctx)
+    const version = flagString(ctx, 'version') ?? readPackageVersion(project.root)
+    const distDir = join(project.root, 'dist')
+
+    if (!existsSync(join(distDir, 'index.html'))) {
+      throw new CliError('dist/index.html not found', {
+        code: 'VALIDATION_ERROR',
+        hint: 'run your build first: bun run build',
+      })
+    }
+
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await client.ensureApp(project.slug, project.displayName, project.appId)
+
+    const distFiles = collectSourceFiles(distDir)
+    ctx.output.note(
+      `  bundle ${distFiles.length} files, ${formatBytes(distFiles.reduce((n, f) => n + f.bytes.byteLength, 0))}`,
+    )
+    const dist = createTarGz(distFiles)
+    const { tgz: source } = packDirectory(project.root, ctx.output, 'packaged')
+
+    // Synthesised from package.json when the build emitted none, so the CSP
+    // domains an author declared actually reach the served headers.
+    const manifest = resolveManifest(distDir, project)
+    const reach = [...manifest.connectDomains, ...manifest.resourceDomains]
+    if (reach.length > 0) ctx.output.note(`  may reach ${reach.join(', ')}`)
+
+    const promote = !flagBool(ctx, 'no-promote')
+    const res = await publish(client, app.id, {
+      version,
+      parentVersion: project.parentVersion,
+      dist,
+      source,
+      manifest,
+      promote,
+    })
+
+    writeState(project.root, { appId: app.id, parentVersion: res.version })
+    // Committed alongside the code, so a clone deploys to THIS app even after
+    // the slug is renamed — and any stale slug is dropped.
+    writeAppId(project.root, app.id)
+
+    return {
+      data: { app: app.slug, appId: app.id, version: res.version, promoted: res.promoted },
+      // The slug as the PLATFORM knows it: `project.slug` is a bootstrap name
+      // and goes stale the moment the app is renamed, so printing it would
+      // report a deploy to an app that no longer exists.
+      text:
+        `Published ${app.slug}@${res.version}` +
+        (res.promoted ? ' and promoted it' : ' (not promoted — use `frontera app promote`)'),
+    }
+  },
+}

package/src/commands/app/init.ts

@@ -0,0 +1,53 @@
+import { join } from 'node:path'
+
+import { UsageError } from '../../errors'
+import { scaffold, scaffoldFiles } from '../../template'
+import { writeHarnessFiles } from '../../harness'
+import type { Command } from '../types'
+
+export const appInit: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'init',
+    args: [{ name: 'name', required: true, description: 'directory and bootstrap slug for the new app' }],
+    flags: { dir: 'string' },
+    summary: 'Scaffold a new Frontera app project',
+    examples: ['frontera app init shipments-console'],
+    // Scaffolding must work before a credential exists.
+    offline: true,
+  },
+
+  async run(ctx) {
+    const name = ctx.positional[0]
+    if (!name) throw new UsageError('missing <name>', 'frontera app init <name>')
+
+    const base = typeof ctx.flags.dir === 'string' ? ctx.flags.dir : ctx.cwd
+    const target = join(base, name)
+    scaffold(target, name)
+    // The app project is also a directory a harness will work in, so it gets
+    // the same AGENTS.md + CLI skill that `frontera init` writes.
+    const harness = writeHarnessFiles(target)
+
+    // The SDK is written into `src/frontera/` rather than declared as a
+    // dependency, so `package.json` asks for nothing but public npm and this
+    // installs on a laptop or in a sandbox that has never seen the monorepo.
+    // Reported here because it is the one surprising thing about the tree, and
+    // an agent that does not know it will try to "fix" the imports.
+    const vendored = Object.keys(scaffoldFiles(name)).filter((f) =>
+      f.startsWith('src/frontera/'),
+    ).length
+    ctx.output.note(`  SDK vendored into src/frontera/ (${vendored} files) — imports resolve by alias`)
+
+    return {
+      data: { name, path: target, harnessFiles: harness.written, vendoredSdkFiles: vendored },
+      text: [
+        `Scaffolded ${name}`,
+        '',
+        `  cd ${name}`,
+        '  bun install',
+        '  bun run build',
+        '  frontera app deploy',
+      ].join('\n'),
+    }
+  },
+}

package/src/commands/app/list.ts

@@ -0,0 +1,51 @@
+import { PlatformApi } from '../../api/platform-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+interface AppRow {
+  id?: string
+  slug?: string
+  displayName?: string
+  status?: string
+  deployedVersionId?: string | null
+}
+
+/**
+ * Frontera Apps in this workspace.
+ *
+ * Every other `app` verb resolves a project from the filesystem, which left no
+ * way to see what exists on the platform — you had to already know a slug to
+ * pull one. This is the entry point that makes the rest discoverable, and it
+ * needs no project.
+ */
+export const appList: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List Frontera Apps in this workspace',
+    examples: ['frontera app list', 'frontera app list --json'],
+  },
+
+  async run(ctx) {
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).platformApps()) as AppRow[]
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No apps in this workspace. Create one with `frontera app init <name>`.'
+          : table(
+              ['slug', 'name', 'live', 'status', 'id'],
+              rows.map((a) => [
+                a.slug ?? '?',
+                a.displayName ?? '',
+                a.deployedVersionId ? 'yes' : 'no',
+                a.status ?? '',
+                a.id ?? '',
+              ]),
+            ),
+    }
+  },
+}