@frontera-sdk/cli 0.1.0

package/src/api/platform-api.ts

@@ -0,0 +1,193 @@
+import { FronteraClient } from '@frontera-sdk/core/client'
+
+export interface AgentDraft {
+  agentId?: string
+  revision: number
+  updatedBy?: string
+  updatedAt?: string
+  snapshot: Record<string, unknown>
+}
+
+/**
+ * Client for the platform's resource routes.
+ *
+ * One class rather than one per noun: they share a base URL, a credential and
+ * an envelope, and splitting them would multiply construction without
+ * separating anything real. The nouns are separated where it matters — in the
+ * commands.
+ */
+export class PlatformApi {
+  private readonly client: FronteraClient
+
+  constructor(apiBaseUrl: string, token: string) {
+    this.client = new FronteraClient({
+      apiBaseUrl,
+      credential: { kind: 'apiKey', key: token },
+    })
+  }
+
+  private get<T>(path: string): Promise<T> {
+    return this.client.request<T>(path)
+  }
+
+  /**
+   * Normalise a list response.
+   *
+   * Some routers return `ok(result)` where `result` is itself `{ data: [...] }`
+   * — `/v1/apps` and `/v1/workspace-knowledge` both do — so after the SDK
+   * unwraps the outer envelope a second one is left. Rather than encode which
+   * endpoints double-wrap (a list that would rot), accept either shape and
+   * treat anything else as empty.
+   */
+  private async getList<T>(path: string): Promise<T[]> {
+    const body = await this.get<T[] | { data?: T[] }>(path)
+    if (Array.isArray(body)) return body
+    const inner = (body as { data?: T[] })?.data
+    return Array.isArray(inner) ? inner : []
+  }
+
+  // ── Identity ──────────────────────────────────────────────────────────────
+
+  whoami() {
+    return this.get<{ orgId: string | null; workspaceId: string | null; authKind: string; principal: string | null }>(
+      '/v1/whoami',
+    )
+  }
+
+  // ── Blueprint (read) ──────────────────────────────────────────────────────
+
+  blueprintObjectTypes() {
+    return this.getList<unknown>('/v1/blueprint/object-types')
+  }
+
+  blueprintObjectType(apiName: string) {
+    return this.get<unknown>(`/v1/blueprint/object-types/${encodeURIComponent(apiName)}`)
+  }
+
+  blueprintMetrics() {
+    return this.getList<unknown>('/v1/blueprint/metrics')
+  }
+
+  /** How object types relate. Without these the catalog reads as a pile of
+   *  disconnected tables, and nothing can be joined. */
+  blueprintLinkTypes() {
+    return this.getList<unknown>('/v1/blueprint/link-types')
+  }
+
+  // ── Agents ────────────────────────────────────────────────────────────────
+
+  agents() {
+    return this.getList<unknown>('/v1/config/agents')
+  }
+
+  agent(id: string) {
+    return this.get<unknown>(`/v1/config/agents/${encodeURIComponent(id)}`)
+  }
+
+  /**
+   * The agent's full composition: prompts, skills, models, knowledge, app
+   * installs, MCP servers, channels, automations.
+   *
+   * `GET /config/agents/:id` returns the config ROW — flat scalars with every
+   * relation null — so it answers "what are its settings" and not "what is
+   * this agent made of". Nobody can review or rebuild an agent from that.
+   */
+  async agentComposition(id: string): Promise<Record<string, unknown>> {
+    const body = await this.get<{ data?: Record<string, unknown> } | Record<string, unknown>>(
+      `/v1/config/agents/${encodeURIComponent(id)}/snapshot/live`,
+    )
+    return ((body as { data?: Record<string, unknown> })?.data ?? body ?? {}) as Record<string, unknown>
+  }
+
+  /** Frontera Apps in this workspace (not integrations — see `plugin`). */
+  platformApps() {
+    return this.getList<unknown>('/v1/platform-apps/')
+  }
+
+  /** `{ agentId, revision, snapshot }`, or null when nothing is staged. */
+  async agentDraft(id: string): Promise<AgentDraft | null> {
+    // Wrapped twice: `ok({ data: … })` around the SDK's own envelope.
+    const body = await this.get<{ data?: AgentDraft | null } | AgentDraft | null>(
+      `/v1/config/agents/${encodeURIComponent(id)}/draft-v2`,
+    )
+    if (!body) return null
+    const inner = (body as { data?: AgentDraft | null }).data
+    return inner === undefined ? (body as AgentDraft) : inner
+  }
+
+  /**
+   * Stage a partial snapshot onto the draft.
+   *
+   * `expectedRevision` is the whole concurrency story: undefined is
+   * collaborative, a number means "the draft I read", and a stale one comes
+   * back as DRAFT_CONFLICT rather than overwriting whoever wrote first.
+   */
+  async patchAgentDraft(
+    id: string,
+    patch: Record<string, unknown>,
+    expectedRevision?: number,
+  ): Promise<AgentDraft> {
+    const body = await this.client.request<{ data?: AgentDraft } | AgentDraft>(
+      `/v1/config/agents/${encodeURIComponent(id)}/draft-v2`,
+      {
+        method: 'PATCH',
+        body: expectedRevision === undefined ? { patch } : { patch, expectedRevision },
+      },
+    )
+    return ((body as { data?: AgentDraft }).data ?? body) as AgentDraft
+  }
+
+  publishAgent(id: string, args: { notes?: string; expectedRevision?: number } = {}) {
+    return this.client.request<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/publish`, {
+      method: 'POST',
+      body: args,
+    })
+  }
+
+  discardAgentDraft(id: string) {
+    return this.client.request<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/draft-v2`, {
+      method: 'DELETE',
+    })
+  }
+
+  agentVersions(id: string) {
+    return this.getList<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/versions`)
+  }
+
+  // ── Skills ────────────────────────────────────────────────────────────────
+
+  workspaceSkills() {
+    return this.getList<unknown>('/v1/config/workspace-skills')
+  }
+
+  workspaceSkill(id: string) {
+    return this.get<unknown>(`/v1/config/workspace-skills/${encodeURIComponent(id)}`)
+  }
+
+  // ── Plugins (integrations and MCP servers) ────────────────────────────────
+
+  pluginInstalls() {
+    return this.getList<unknown>('/v1/apps/')
+  }
+
+  pluginCatalog() {
+    return this.getList<unknown>('/v1/apps/catalog')
+  }
+
+  // ── Knowledge ─────────────────────────────────────────────────────────────
+
+  knowledgeBases(workspaceId: string) {
+    return this.getList<unknown>(`/v1/workspace-knowledge?workspaceId=${encodeURIComponent(workspaceId)}`)
+  }
+
+  /**
+   * Sources in a WORKSPACE knowledge base, keyed by its id.
+   *
+   * Not `/v1/knowledge/:name/sources` — that is the per-AGENT path, and it
+   * defaults `agentName` to "default", so a workspace base's name reached a
+   * uuid column and came back as a raw postgres 22P02 rendered as a 500.
+   */
+  knowledgeSources(id: string) {
+    return this.getList<unknown>(`/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`)
+  }
+}

package/src/api/registry-api.ts

@@ -0,0 +1,43 @@
+export interface RegistryFile {
+  path: string
+  content: string
+  type: 'ui' | 'lib' | 'style' | 'skill'
+}
+
+export interface RegistryItem {
+  name: string
+  type: 'ui' | 'lib' | 'style' | 'skill'
+  version: string
+  description: string
+  dependencies: string[]
+  registryDependencies: string[]
+  files: RegistryFile[]
+}
+
+/**
+ * Client for the component registry.
+ *
+ * Unauthenticated on purpose (see the service router): this serves the same
+ * first-party component source that ships in the platform's own bundle, and
+ * requiring a credential would stop `frontera app init` scaffolding before a
+ * key exists.
+ */
+export class RegistryApi {
+  constructor(private readonly apiBaseUrl: string) {}
+
+  async list(): Promise<Array<Omit<RegistryItem, 'files'>>> {
+    const res = await fetch(`${this.apiBaseUrl}/v1/apps/registry`)
+    if (!res.ok) throw new Error(`registry unavailable (${res.status})`)
+    const body = (await res.json()) as { data: Array<Omit<RegistryItem, 'files'>> }
+    return body.data
+  }
+
+  /** The item plus its transitive dependencies, dependencies first. */
+  async resolve(name: string): Promise<RegistryItem[]> {
+    const res = await fetch(`${this.apiBaseUrl}/v1/apps/registry/${encodeURIComponent(name)}`)
+    if (res.status === 404) throw new Error(`unknown registry item: ${name}`)
+    if (!res.ok) throw new Error(`registry unavailable (${res.status})`)
+    const body = (await res.json()) as { data: RegistryItem[] }
+    return body.data
+  }
+}

package/src/args.ts

@@ -0,0 +1,108 @@
+import { UsageError } from './errors'
+
+export type FlagKind = 'string' | 'boolean'
+export type FlagSpec = Readonly<Record<string, FlagKind>>
+
+export interface ParsedArgs {
+  positional: string[]
+  flags: Record<string, string | boolean>
+}
+
+/**
+ * Argument parser.
+ *
+ * Strict on purpose. The parser it replaces returned `args[i + 1]` for any
+ * `--flag`, so `--dir --force` set the directory to "--force" and the command
+ * ran against a path that does not exist while reporting success. It also
+ * ignored unknown flags outright, so a typo silently changed nothing. Both
+ * failures are worse for a model caller than for a person: the command appears
+ * to work, so nothing prompts a second look.
+ *
+ * Every rejection is a `UsageError`, which the shell maps to exit 2 — the code
+ * that tells a caller to fix the command rather than retry it.
+ */
+export function parseArgs(
+  argv: string[],
+  spec: FlagSpec,
+  aliases: Readonly<Record<string, string>> = {},
+): ParsedArgs {
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+
+  for (let i = 0; i < argv.length; i += 1) {
+    let token = argv[i]!
+
+    // Short flags (`-f value`, `-f=value`). Conventional for the common ones,
+    // and their absence silently turned `-f` into a positional argument — so a
+    // documented example read the file it was given as an agent name instead.
+    if (/^-[A-Za-z]/.test(token)) {
+      const eqAt = token.indexOf('=')
+      const short = (eqAt === -1 ? token.slice(1) : token.slice(1, eqAt))
+      const long = aliases[short]
+      if (!long) {
+        throw new UsageError(
+          `unknown flag: -${short}`,
+          'run the command with --help to see the flags it accepts',
+        )
+      }
+      token = eqAt === -1 ? `--${long}` : `--${long}${token.slice(eqAt)}`
+    }
+
+    // `--` ends flag parsing. Everything after is positional, even if it
+    // starts with dashes — the escape hatch for a literal value.
+    if (token === '--') {
+      positional.push(...argv.slice(i + 1))
+      break
+    }
+
+    // A lone `-` is the stdin convention, and `-1` is a value. Neither is a
+    // flag, so only `--` prefixes are parsed as one.
+    if (!token.startsWith('--')) {
+      positional.push(token)
+      continue
+    }
+
+    const eq = token.indexOf('=')
+    const name = eq === -1 ? token.slice(2) : token.slice(2, eq)
+    const kind = spec[name]
+
+    if (!kind) {
+      throw new UsageError(
+        `unknown flag: --${name}`,
+        'run the command with --help to see the flags it accepts',
+      )
+    }
+
+    if (kind === 'boolean') {
+      if (eq !== -1) {
+        throw new UsageError(
+          `--${name} is a boolean flag and takes no value`,
+          `pass --${name} on its own`,
+        )
+      }
+      flags[name] = true
+      continue
+    }
+
+    if (eq !== -1) {
+      // `--dir=` is a deliberate empty string, not a missing value.
+      flags[name] = token.slice(eq + 1)
+      continue
+    }
+
+    const value = argv[i + 1]
+    // The defect this replaces: a following flag is not a value. `--` is not
+    // one either — it terminates parsing, so consuming it would swallow the
+    // escape hatch.
+    if (value === undefined || value === '--' || (value.startsWith('--') && value.length > 2)) {
+      throw new UsageError(
+        `--${name} needs a value`,
+        `pass it as --${name} <value> or --${name}=<value>`,
+      )
+    }
+    flags[name] = value
+    i += 1
+  }
+
+  return { positional, flags }
+}

package/src/commands/agent/compose.ts

@@ -0,0 +1,155 @@
+/**
+ * Render an agent's composition the way someone configuring it needs to see it.
+ *
+ * Two things this exists to avoid. The default read used to be the config row:
+ * flat scalars, every relation null — it told you the temperature and nothing
+ * about what the agent is made of. And the snapshot's relations carry only
+ * uuids, so printing them raw ("Knowledge: a7452079-…") is technically
+ * complete and practically useless. Ids are resolved to names here.
+ */
+
+type Row = Record<string, unknown>
+
+export interface Lookups {
+  /** installId → readable plugin name. */
+  plugins: Map<string, string>
+  /** knowledge config id → readable name. */
+  knowledge: Map<string, string>
+  /** workspace skill id → readable name. */
+  skills: Map<string, string>
+  /** Identity the snapshot's config does not carry. */
+  identity?: { id?: string; slug?: string; kind?: string; version?: number }
+}
+
+function arr(value: unknown): Row[] {
+  return Array.isArray(value) ? (value as Row[]) : []
+}
+
+function str(row: Row, ...keys: string[]): string {
+  for (const k of keys) {
+    const v = row[k]
+    if (typeof v === 'string' && v.length > 0) return v
+  }
+  return ''
+}
+
+function section(title: string, items: string[]): string[] {
+  if (items.length === 0) return [`${title}: —`]
+  return [`${title} (${items.length})`, ...items.map((i) => `  ${i}`)]
+}
+
+/** Name if we have one, id if we do not — never a bare uuid with no context. */
+function label(id: string, lookup: Map<string, string>): string {
+  const name = lookup.get(id)
+  return name ? name : `${id}  (unresolved)`
+}
+
+export function renderComposition(snapshot: Row, lookups: Lookups): string {
+  const config = (snapshot.config ?? {}) as Row
+  const lines: string[] = []
+
+  lines.push(str(config, 'name') || str(config, 'agentId'))
+  if (str(config, 'description')) lines.push(str(config, 'description'))
+  lines.push('')
+
+  for (const [k, v] of [
+    ['slug', str(config, 'agentId') || (lookups.identity?.slug ?? '')],
+    ['id', str(config, 'id') || (lookups.identity?.id ?? '')],
+    ['kind', str(config, 'kind') || (lookups.identity?.kind ?? '')],
+    ['status', str(config, 'lifecycleStatus')],
+    ['default mode', str(config, 'defaultMode')],
+    ['live version', lookups.identity?.version ? String(lookups.identity.version) : ''],
+  ] as Array<[string, string]>) {
+    if (v) lines.push(`${k.padEnd(14)}${v}`)
+  }
+  lines.push('')
+
+  lines.push(
+    ...section(
+      'Models',
+      arr(snapshot.modelConfigs).map((m) =>
+        `${str(m, 'modeKey').padEnd(22)}${str(m, 'modelSlug')}${
+          str(m, 'displayName') ? `  (${str(m, 'displayName')})` : ''
+        }`,
+      ),
+    ),
+    '',
+    ...section(
+      'Prompts',
+      arr(snapshot.prompts).map((p) => {
+        const body = str(p, 'content').replace(/\s+/g, ' ')
+        return `${(str(p, 'kind', 'filename') || 'prompt').padEnd(22)}${body.slice(0, 60)}${
+          body.length > 60 ? '…' : ''
+        }`
+      }),
+    ),
+    '',
+    // `skills` is an OBJECT ({ workspaceBindings: [...] }), not an array —
+    // treating it as a list silently reported "no skills" for every agent
+    // that had them.
+    ...section(
+      'Skills',
+      arr((snapshot.skills as Row | undefined)?.workspaceBindings).map((s) => {
+        const name = label(str(s, 'workspaceSkillId'), lookups.skills)
+        return s.enabled === false ? `${name}  (disabled)` : name
+      }),
+    ),
+    '',
+    ...section(
+      'Knowledge',
+      [
+        ...arr(snapshot.knowledgeAttachments).map((k) =>
+          label(str(k, 'knowledgeConfigId'), lookups.knowledge),
+        ),
+        ...arr(snapshot.knowledgeConfigs).map((k) => str(k, 'name') || label(str(k, 'id'), lookups.knowledge)),
+      ],
+    ),
+    '',
+    ...section('Plugins', [
+      ...arr(snapshot.appInstalls).map((a) => {
+        const name = label(str(a, 'installId'), lookups.plugins)
+        const off = a.enabled === false ? '  (disabled)' : ''
+        return `${name}${off}`
+      }),
+      ...arr(snapshot.mcpServers).map((m) => `${str(m, 'name', 'serverName', 'mcpServerId')}  (mcp)`),
+    ]),
+    '',
+    ...section(
+      'Channels',
+      // Channel names need `/v1/channels`, which is not on the programmatic
+      // auth surface — widening that for a label is not worth it, so the id is
+      // shown plainly rather than dressed up as a name.
+      arr(snapshot.channelBindings).map((c) => `channel ${str(c, 'channelId')}`),
+    ),
+    '',
+    ...section(
+      'Automations',
+      arr(snapshot.automations).map((a) => str(a, 'name', 'schedule', 'id')),
+    ),
+    '',
+    ...section(
+      'Packs',
+      arr(snapshot.appliedPacks).map((p) => str(p, 'name', 'packId', 'id')),
+    ),
+  )
+
+  // Capabilities are per-app grants and there are often dozens; a count with
+  // the approval posture is what a reviewer reads, and --json has the rest.
+  const caps = arr(snapshot.appCapabilities)
+  const needsApproval = caps.filter((c) => c.requiresApprovalOverride === true).length
+  lines.push(
+    '',
+    caps.length === 0
+      ? 'Capabilities: —'
+      : `Capabilities (${caps.length})` +
+        (needsApproval > 0 ? `  — ${needsApproval} require approval` : ''),
+  )
+
+  const caseDefinition = snapshot.caseDefinition as Row | null | undefined
+  if (caseDefinition && typeof caseDefinition === 'object') {
+    lines.push('', ...section('Case columns', arr(caseDefinition.columns).map((c) => str(c, 'name', 'key'))))
+  }
+
+  lines.push('', 'Full document: add --json')
+  return lines.join('\n')
+}