@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/commands/login.ts

@@ -78,26 +78,64 @@ export const loginCommand: Command = {
         'run `frontera login` in a terminal to be asked for one, or pipe it in: `echo $KEY | frontera login`',
       )
     }
-    if (!token.startsWith('sk-ws-')) {
+    // Two credential kinds reach this CLI, and they are not interchangeable:
+    //
+    //   sk-ws-   a WORKSPACE key — one workspace's slice of the platform.
+    //   sk-org-  an ORGANIZATION key — the organization-level Blueprint draft,
+    //            which no workspace credential can reach, because that draft is
+    //            shared by every workspace in the organization.
+    //
+    // Both are stored the same way; only the verification below differs, because an
+    // organization key belongs to no workspace and `whoami` has none to report.
+    const isWorkspaceKey = token.startsWith('sk-ws-')
+    const isOrgKey = token.startsWith('sk-org-')
+    if (!isWorkspaceKey && !isOrgKey) {
       throw new UsageError(
-        'that does not look like a workspace key',
-        'workspace keys start with sk-ws- and are created in Workspace settings → API Keys',
+        'that does not look like a Frontera key',
+        'workspace keys start with sk-ws- (Workspace settings → API Keys); ' +
+        'organization keys start with sk-org- (Settings → API keys)',
       )
     }
 
-    const me = await new PlatformApi(ctx.apiUrl, token).whoami().catch(() => null)
-    if (!me?.workspaceId) {
-      throw new CliError('the token was rejected by this API origin', {
-        code: 'UNAUTHORIZED',
-        hint: `check the key is enabled, and that --api-url is right (currently ${ctx.apiUrl})`,
-      })
+    // Shaped as `whoami` actually answers — both fields are nullable there, and
+    // declaring them merely optional made the assignment below unassignable.
+    let me: { workspaceId: string | null; orgId: string | null } | null = null
+    if (isWorkspaceKey) {
+      me = await new PlatformApi(ctx.apiUrl, token).whoami().catch(() => null)
+      if (!me?.workspaceId) {
+        throw new CliError('the token was rejected by this API origin', {
+          code: 'UNAUTHORIZED',
+          hint: `check the key is enabled, and that --api-url is right (currently ${ctx.apiUrl})`,
+        })
+      }
+    } else {
+      // Verified against an organization-scoped read instead. A revoked or expired
+      // key answers 401 here, which is exactly what login should catch.
+      const lifecycle = await fetch(`${ctx.apiUrl}/v1/blueprint/lifecycle`, {
+        headers: { authorization: `Bearer ${token}` },
+      }).catch(() => null)
+      if (!lifecycle || lifecycle.status === 401 || lifecycle.status === 403) {
+        throw new CliError('the organization key was rejected by this API origin', {
+          code: 'UNAUTHORIZED',
+          hint: `check the key is active and carries organization:update, and that --api-url is right (currently ${ctx.apiUrl})`,
+        })
+      }
     }
 
     writeStoredToken(ctx.apiUrl, token)
 
     return {
-      data: { apiUrl: ctx.apiUrl, workspaceId: me.workspaceId, orgId: me.orgId },
-      text: `Stored a key for ${ctx.apiUrl}\n  workspace ${me.workspaceId}`,
+      data: {
+        apiUrl: ctx.apiUrl,
+        kind: isOrgKey ? 'organization' : 'workspace',
+        workspaceId: me?.workspaceId ?? null,
+        orgId: me?.orgId ?? null,
+      },
+      // An organization key belongs to no workspace, so saying "workspace <id>" for
+      // one would be a comforting lie about what the credential reaches.
+      text: isOrgKey
+        ? `Stored an organization key for ${ctx.apiUrl}\n  it authors this organization's Blueprint`
+        : `Stored a key for ${ctx.apiUrl}\n  workspace ${me?.workspaceId}`,
     }
   },
 }

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

@@ -0,0 +1,373 @@
+import { readFileSync } from 'node:fs'
+
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { resolveAgentRef } from '../agent/resolve'
+import { flagBool, type Command } from '../types'
+
+/**
+ * Packs — a named bundle of skills (plus the app kinds and computer setup
+ * script they assume), authored once at organization level and installed into a
+ * workspace.
+ *
+ * This is the closest thing the platform has to repeatable delivery: the same
+ * capability set can be pushed from a file, installed into a customer's
+ * workspace, and applied to a named agent. The routes have existed for a while
+ * with no CLI surface at all, which meant every rollout was hand-repeated in
+ * the Console.
+ *
+ * What a pack does NOT carry: agent configuration, Blueprint, knowledge,
+ * automations, secrets. It is a skills bundle, not a workspace snapshot — worth
+ * knowing before planning a migration around it.
+ */
+
+interface PackRow {
+  id?: string
+  name?: string
+  displayName?: string
+  description?: string
+  version?: number
+  category?: string
+}
+
+interface PackListEntry {
+  pack?: PackRow
+  install?: { id?: string; installedAt?: string; packVersion?: number } | null
+}
+
+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 resolvePackRef(api: PlatformApi, ref: string): Promise<string> {
+  if (UUID.test(ref)) return ref
+
+  const rows = (await api.packs()) as PackListEntry[]
+  const match = rows.find(
+    (r) =>
+      (r.pack?.name ?? '').toLowerCase() === ref.toLowerCase() ||
+      (r.pack?.displayName ?? '').toLowerCase() === ref.toLowerCase(),
+  )
+  if (match?.pack?.id) return match.pack.id
+
+  throw new CliError(`no pack named "${ref}"`, {
+    code: 'NOT_FOUND',
+    hint: `known packs: ${rows.map((r) => r.pack?.name).filter(Boolean).join(', ') || '(none)'}`,
+  })
+}
+
+const list: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List packs available to this organization, and which are installed',
+    examples: ['frontera pack list', 'frontera pack list --json'],
+  },
+  async run(ctx) {
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).packs()) as PackListEntry[]
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No packs in this organization.'
+          : table(
+              // `installed` first among the facts a reader is deciding on: the
+              // same pack list serves "what can I install" and "what did I".
+              ['name', 'installed', 'version', 'description'],
+              rows.map((r) => [
+                r.pack?.name ?? '?',
+                r.install ? 'yes' : '',
+                String(r.pack?.version ?? ''),
+                r.pack?.description ?? '',
+              ]),
+              [undefined, undefined, undefined, 50],
+            ),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'get',
+    args: [{ name: 'pack', required: true, description: 'pack name or id, from `frontera pack list`' }],
+    flags: {},
+    summary: 'Show one pack: its manifest and what it installs',
+    examples: ['frontera pack get analytics-starter', 'frontera pack get analytics-starter --json'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const detail = (await api.pack(await resolvePackRef(api, ref))) as {
+      pack?: PackRow
+      install?: unknown
+      // `itemType`/`itemName`, not `kind`/`name` — guessing printed "?" for
+      // every row, the same way `knowledge agents` did before it was checked
+      // against a real payload.
+      items?: Array<{ itemType?: string; itemName?: string; status?: string }>
+      agents?: Array<{ agentId?: string; name?: string }>
+    }
+
+    const pack = detail.pack ?? (detail as PackRow)
+    const items = detail.items ?? []
+    const lines = [
+      `${pack.name ?? ref}${pack.version ? `  v${pack.version}` : ''}`,
+      ...(pack.description ? [`  ${pack.description}`] : []),
+      '',
+      // `items` are what the INSTALL created, so an empty list means one of two
+      // very different things. Saying which is the difference between "install
+      // it" and "the pack is empty, fix the manifest".
+      items.length === 0
+        ? detail.install
+          ? '  installed, but it carries no items'
+          : `  not installed in this workspace — frontera pack install ${ref}`
+        : table(
+            ['type', 'name', 'status'],
+            items.map((i) => [i.itemType ?? '?', i.itemName ?? '', i.status ?? '']),
+          ),
+    ]
+    if (detail.agents?.length) {
+      lines.push('', `  applied to: ${detail.agents.map((a) => a.agentId ?? a.name).join(', ')}`)
+    }
+
+    return { data: detail, text: lines.join('\n') }
+  },
+}
+
+const push: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'push',
+    args: [{ name: 'file', required: true, description: 'pack manifest JSON, or `-` for stdin' }],
+    flags: { force: 'boolean' },
+    summary: 'Create or replace a pack from a manifest file',
+    examples: [
+      'frontera pack push ./analytics-starter.json',
+      'frontera pack push ./analytics-starter.json --force',
+    ],
+  },
+  async run(ctx) {
+    const path = ctx.positional[0]
+    if (!path) throw new UsageError('missing <file>', 'frontera pack push ./pack.json')
+
+    let raw: string
+    if (path === '-') {
+      const chunks: Uint8Array[] = []
+      for await (const chunk of Bun.stdin.stream()) chunks.push(chunk)
+      raw = Buffer.concat(chunks).toString('utf8')
+    } else {
+      try {
+        raw = readFileSync(path, 'utf8')
+      } catch {
+        throw new UsageError(`could not read ${path}`, 'check the path, or pipe the manifest in with -')
+      }
+    }
+
+    let manifest: { name?: string; version?: number }
+    try {
+      manifest = JSON.parse(raw) as { name?: string; version?: number }
+    } catch {
+      throw new UsageError('the manifest is not valid JSON', 'it should be a pack manifest object')
+    }
+    if (!manifest.name) {
+      throw new UsageError('the manifest has no `name`', 'a pack is addressed by name everywhere else')
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const rows = (await api.packs()) as PackListEntry[]
+    const existing = rows.find(
+      (r) => (r.pack?.name ?? '').toLowerCase() === manifest.name!.toLowerCase(),
+    )
+
+    // Replacing a pack rewrites what every workspace that installed it will get
+    // on its next install, so it is opt-in rather than implied by pushing the
+    // same name twice.
+    if (existing?.pack?.id && !flagBool(ctx, 'force')) {
+      throw new CliError(`a pack named "${manifest.name}" already exists`, {
+        code: 'CONFLICT',
+        hint: 'pass --force to replace it — installed workspaces get the new contents on their next install',
+      })
+    }
+
+    const result = (existing?.pack?.id
+      ? await api.updatePack(existing.pack.id, manifest)
+      : await api.createPack(manifest)) as { data?: PackRow } | PackRow
+    const saved = ((result as { data?: PackRow }).data ?? result) as PackRow
+
+    // The SERVICE decides the version — a replace increments it regardless of
+    // what the manifest says — so echoing the manifest's number told the author
+    // their pack was v1 while every workspace would install v2.
+    const version = saved.version ?? manifest.version
+    return {
+      data: saved,
+      text: `${existing ? 'replaced' : 'created'} pack ${manifest.name}${version ? ` v${version}` : ''}`,
+    }
+  },
+}
+
+const install: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'install',
+    args: [{ name: 'pack', required: true, description: 'pack name or id' }],
+    flags: {},
+    summary: 'Install a pack into this workspace',
+    examples: ['frontera pack install analytics-starter'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const id = await resolvePackRef(api, ref)
+    const result = (await api.installPack(id)) as { skills?: unknown[] }
+
+    return {
+      data: result,
+      text: [
+        `installed ${ref}`,
+        // Installing puts the skills in the workspace; an agent loads none of
+        // them until the pack is applied to it. Two steps, and the second is the
+        // one people forget.
+        `  next: frontera pack apply ${ref} <agent>`,
+      ].join('\n'),
+    }
+  },
+}
+
+const uninstall: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'uninstall',
+    args: [{ name: 'pack', required: true, description: 'pack name or id' }],
+    flags: { 'remove-apps': 'boolean' },
+    summary: 'Remove a pack from this workspace',
+    examples: ['frontera pack uninstall analytics-starter', 'frontera pack uninstall analytics-starter --remove-apps'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const id = await resolvePackRef(api, ref)
+    const removeApps = flagBool(ctx, 'remove-apps')
+    const result = await api.uninstallPack(id, removeApps)
+
+    return {
+      data: result,
+      text: removeApps
+        ? `uninstalled ${ref}, including the apps it installed`
+        : // Stated because the default surprises people who expect uninstall to
+          // undo the whole install.
+          `uninstalled ${ref} — apps it installed were LEFT in place (--remove-apps takes them too)`,
+    }
+  },
+}
+
+const apply: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'apply',
+    args: [
+      { name: 'pack', required: true, description: 'pack name or id' },
+      { name: 'agent', required: true, description: 'agent slug or id' },
+    ],
+    flags: {},
+    summary: 'Give one agent the skills an installed pack carries',
+    examples: ['frontera pack apply analytics-starter ava'],
+  },
+  async run(ctx) {
+    const [packRef, agentRef] = ctx.positional
+    if (!packRef) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
+    if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const packId = await resolvePackRef(api, packRef)
+    const agentId = await resolveAgentRef(api, agentRef)
+    const result = await api.applyPackToAgent(packId, agentId)
+
+    return {
+      data: result,
+      text: [`applied ${packRef} to ${agentRef}`, `  verify: frontera agent get ${agentRef}`].join('\n'),
+    }
+  },
+}
+
+/**
+ * The reverse of `apply`, as its own verb rather than `apply --remove`.
+ *
+ * Two reasons, and the second is not cosmetic: it mirrors `knowledge
+ * attach`/`detach`, which is the same relationship — an agent's access to
+ * something the workspace holds — and a `--remove` flag on `apply` put the word
+ * `remove` in the shell completion script, where it completed `plugin remove`,
+ * a verb that is reserved and fails.
+ */
+const detach: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'detach',
+    args: [
+      { name: 'pack', required: true, description: 'pack name or id' },
+      { name: 'agent', required: true, description: 'agent slug or id' },
+    ],
+    flags: {},
+    summary: 'Take a pack’s skills away from one agent',
+    examples: ['frontera pack detach analytics-starter ava'],
+  },
+  async run(ctx) {
+    const [packRef, agentRef] = ctx.positional
+    if (!packRef) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
+    if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const packId = await resolvePackRef(api, packRef)
+    const agentId = await resolveAgentRef(api, agentRef)
+    await api.removePackFromAgent(packId, agentId)
+
+    return {
+      data: { packId, agentId, applied: false },
+      text: `detached ${packRef} from ${agentRef} — the pack stays installed in the workspace`,
+    }
+  },
+}
+
+const remove: Command = {
+  meta: {
+    noun: 'pack',
+    verb: 'delete',
+    args: [{ name: 'pack', required: true, description: 'pack name or id' }],
+    flags: {},
+    summary: 'Delete a pack from the organization',
+    examples: ['frontera pack delete analytics-starter'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <pack>', 'frontera pack list — then pass a name or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const id = await resolvePackRef(api, ref)
+    await api.deletePack(id)
+
+    return {
+      data: { id, name: ref, deleted: true },
+      // Organization-wide, unlike uninstall — which is why the two verbs are not
+      // spelled the same way.
+      text: `deleted pack ${ref} from the organization`,
+    }
+  },
+}
+
+export const packCommands: Command[] = [
+  list,
+  get,
+  push,
+  install,
+  uninstall,
+  apply,
+  detach,
+  remove,
+]

package/src/commands/registry.ts

@@ -14,11 +14,17 @@ 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 { blueprintAuthoringCommands } from './blueprint/authoring'
+import { blueprintDeclarativeCommands } from './blueprint/declarative'
+import { blueprintBind } from './blueprint/bind'
+import { blueprintGrant } from './blueprint/grants'
 import { agentCommands } from './agent/index-commands'
 import { skillCommands } from './skill/index-commands'
 import { pluginCommands } from './plugin/index-commands'
+import { datasetCommands } from './dataset/index-commands'
 import { knowledgeCommands } from './knowledge/index-commands'
+import { packCommands } from './pack/index-commands'
+import { secretCommands } from './secret/index-commands'
 import { automationCommands } from './automation/index-commands'
 import { completionCommand } from './completion'
 import { initCommand } from './init'
@@ -56,12 +62,20 @@ export const COMMANDS: readonly Command[] = [
   ...agentCommands,
   ...skillCommands,
   ...pluginCommands,
+  ...datasetCommands,
   ...knowledgeCommands,
+  ...packCommands,
+  ...secretCommands,
   ...automationCommands,
 
   blueprintList,
   blueprintGet,
-  ...blueprintReserved,
+  // Authoring is no longer reserved: the organization API key (`sk-org-`) reaches the
+  // organization-level shared draft, which is what these verbs were waiting on.
+  ...blueprintAuthoringCommands,
+  ...blueprintDeclarativeCommands,
+  blueprintBind,
+  blueprintGrant,
 ]
 
 export function findCommand(noun: string, verb: string | undefined): Command | null {
@@ -86,7 +100,10 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   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',
+  dataset: 'Source datasets a Blueprint object type can bind to',
   knowledge: 'Knowledge bases and the sources inside them',
+  pack: 'Reusable skill bundles — author once, install per workspace',
+  secret: 'Workspace secrets — named here, never printed back',
   automation: 'Automations — TypeScript deployed here, run on a schedule',
   blueprint: 'The shared model of the organization — what an app can read',
 }