@frontera-sdk/cli 1.44.0 → 1.45.0

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

@@ -1,6 +1,9 @@
+import { readFileSync } from 'node:fs'
+
 import { PlatformApi } from '../../api/platform-api'
+import { UsageError } from '../../errors'
 import { table } from '../../table'
-import type { Command } from '../types'
+import { flagString, type Command } from '../types'
 
 /**
  * `/v1/apps` returns `{ install, catalog, … }` per row, not a flattened
@@ -78,35 +81,295 @@ const catalog: Command = {
   },
 }
 
+const get: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'get',
+    args: [{ name: 'plugin', required: true, description: 'install id, from `frontera plugin list`' }],
+    flags: {},
+    summary: 'Show one installed plugin — its configuration and connection state',
+    examples: ['frontera plugin get <installId>', 'frontera plugin get <installId> --json'],
+  },
+  async run(ctx) {
+    const installId = ctx.positional[0]
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
+
+    const install = await new PlatformApi(ctx.apiUrl, ctx.token).plugin(installId)
+    return {
+      data: install,
+      text: table(
+        ['field', 'value'],
+        Object.entries(install).map(([k, v]) => [
+          k,
+          v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
+        ]),
+        [undefined, 70],
+      ),
+    }
+  },
+}
+
+const add: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'add',
+    args: [{ name: 'kind', required: true, description: 'catalog kind, from `frontera plugin catalog`' }],
+    flags: { name: 'string', file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Install a plugin from the catalog',
+    examples: [
+      'frontera plugin add slack --name "Support Slack"',
+      'frontera plugin add postgres --file ./config.json',
+    ],
+  },
+  async run(ctx) {
+    const kind = ctx.positional[0]
+    if (!kind) throw new UsageError('missing <kind>', 'frontera plugin catalog — then pass a kind')
+
+    // Configuration by file, never by flag: a connector config carries
+    // credentials, and a flag lands in shell history and the process list.
+    // Same rule `secret set` states for itself.
+    const file = flagString(ctx, 'file')
+    let config: Record<string, unknown> | undefined
+    if (file) {
+      const raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8')
+      try {
+        config = JSON.parse(raw) as Record<string, unknown>
+      } catch (e) {
+        throw new UsageError(
+          `${file === '-' ? 'stdin' : file} is not valid JSON: ${(e as Error).message}`,
+          'the file holds the connector config object for this plugin kind',
+        )
+      }
+    }
+
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token).createPluginInstall({
+      kind,
+      ...(flagString(ctx, 'name') ? { installName: flagString(ctx, 'name')! } : {}),
+      ...(config ? { config } : {}),
+    })
+
+    // An OAuth-backed install answers with a URL and is inert until a person
+    // opens it. Reporting "installed" without saying so would leave a caller
+    // wiring capabilities onto something that cannot connect.
+    const authUrl = (result as { authUrl?: string }).authUrl
+    return {
+      data: result,
+      text: authUrl
+        ? `Installed ${kind}, and it is NOT usable yet.\n`
+          + `  Open this to authorize it:\n    ${authUrl}\n`
+          + '  Then `frontera plugin verify <installId>`.'
+        : `Installed ${kind}.\n`
+          + '  `frontera plugin verify <installId>` — confirm it can reach the far end.\n'
+          + '  `frontera capability available <installId>` — what it now offers.',
+    }
+  },
+}
+
+const configure: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'configure',
+    args: [{ name: 'plugin', required: true, description: 'install id, from `frontera plugin list`' }],
+    flags: { name: 'string', file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Rename an install, or replace its stored configuration',
+    examples: [
+      'frontera plugin configure <installId> --name "Support Slack"',
+      'frontera plugin configure <installId> --file ./config.json',
+    ],
+  },
+  async run(ctx) {
+    const installId = ctx.positional[0]
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
+
+    const name = flagString(ctx, 'name')
+    const file = flagString(ctx, 'file')
+    if (!name && !file) {
+      throw new UsageError(
+        'nothing to change',
+        'pass --name to rename, or --file to replace the configuration',
+      )
+    }
+
+    let config: Record<string, unknown> | undefined
+    if (file) {
+      const raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8')
+      try {
+        config = JSON.parse(raw) as Record<string, unknown>
+      } catch (e) {
+        throw new UsageError(
+          `${file === '-' ? 'stdin' : file} is not valid JSON: ${(e as Error).message}`,
+          'the file holds the connector config object — `frontera plugin get <installId>` shows the current one',
+        )
+      }
+    }
+
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token).updatePluginInstall(installId, {
+      ...(name ? { installName: name } : {}),
+      ...(config ? { config } : {}),
+    })
+
+    return {
+      data: result,
+      text: `Updated ${installId}.`
+        + (config ? '\n  Configuration replaced — `frontera plugin verify` to confirm it still connects.' : ''),
+    }
+  },
+}
+
+/**
+ * Policy is separate from configuration on purpose.
+ *
+ * `configure` changes how the install reaches the far end. This changes what
+ * the platform will let it do once it gets there — including `read_only`,
+ * which refuses every Action capability grant across every agent bound to it.
+ * Granting a capability against a read-only install fails with a conflict that
+ * no retry fixes, and this is the verb that fixes it.
+ */
+const policy: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'policy',
+    args: [{ name: 'plugin', required: true, description: 'install id, from `frontera plugin list`' }],
+    flags: { enable: 'boolean', disable: 'boolean', actions: 'string', 'new-capability': 'string' },
+    summary: 'Set an install’s policy — enabled, Action policy, new-capability default',
+    examples: [
+      'frontera plugin policy <installId> --actions allow_all',
+      'frontera plugin policy <installId> --disable',
+    ],
+  },
+  async run(ctx) {
+    const installId = ctx.positional[0]
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
+
+    const enable = ctx.flags.enable === true
+    const disable = ctx.flags.disable === true
+    if (enable && disable) {
+      throw new UsageError('--enable and --disable contradict each other', 'pass one of them')
+    }
+
+    const actions = flagString(ctx, 'actions')
+    const ACTION_POLICIES = ['allow_all', 'read_only', 'custom'] as const
+    if (actions && !ACTION_POLICIES.includes(actions as never)) {
+      throw new UsageError(
+        `--actions must be one of ${ACTION_POLICIES.join(', ')}, not "${actions}"`,
+        'read_only refuses every Action capability grant on this install',
+      )
+    }
+
+    const newCapability = flagString(ctx, 'new-capability')
+    if (newCapability && newCapability !== 'enabled' && newCapability !== 'disabled') {
+      throw new UsageError(
+        `--new-capability must be enabled or disabled, not "${newCapability}"`,
+        'it decides what a capability discovered later defaults to; disabled is the safe choice',
+      )
+    }
+
+    if (!enable && !disable && !actions && !newCapability) {
+      throw new UsageError('nothing to change', 'pass --enable, --disable, --actions or --new-capability')
+    }
+
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token).patchPluginInstall(installId, {
+      ...(enable ? { enabled: true } : {}),
+      ...(disable ? { enabled: false } : {}),
+      ...(actions ? { actionPolicy: actions as 'allow_all' | 'read_only' | 'custom' } : {}),
+      ...(newCapability ? { newCapabilityDefault: newCapability as 'enabled' | 'disabled' } : {}),
+    })
+
+    return { data: result, text: `Policy updated on ${installId}.` }
+  },
+}
+
+const verify: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'verify',
+    args: [{ name: 'plugin', required: true, description: 'install id, from `frontera plugin list`' }],
+    flags: {},
+    summary: 'Check that an install can reach the far end',
+    examples: ['frontera plugin verify <installId>'],
+  },
+  async run(ctx) {
+    const installId = ctx.positional[0]
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
+
+    // A failed check still answers 200 — the verdict is in the body, the same
+    // shape `dataset test-source` established. Exiting non-zero here would
+    // make an unreachable plugin indistinguishable from an unreachable API.
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token).verifyPluginInstall(installId)
+
+    return {
+      data: result,
+      text: table(
+        ['field', 'value'],
+        Object.entries(result).map(([k, v]) => [
+          k,
+          v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
+        ]),
+        [undefined, 70],
+      ),
+    }
+  },
+}
+
+const remove: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'remove',
+    args: [{ name: 'plugin', required: true, description: 'install id, from `frontera plugin list`' }],
+    flags: {},
+    summary: 'Uninstall a plugin from this workspace',
+    examples: ['frontera plugin remove <installId>'],
+  },
+  async run(ctx) {
+    const installId = ctx.positional[0]
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
+
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token).deletePluginInstall(installId)
+    return {
+      data: result,
+      text: `Uninstalled ${installId}.\n`
+        + '  Every agent bound to it loses the capabilities it carried.',
+    }
+  },
+}
+
 /**
- * `connect` is reserved rather than half-built. It needs the headless consent
- * flow — print the authorization URL, poll, `--no-wait` to hand off — because
- * the Computer has no browser, and shipping it without that would produce a
- * command that hangs in exactly the environment it exists for.
+ * `connect` stays reserved, alone among the five.
+ *
+ * It needs the headless consent flow — print the authorization URL, poll,
+ * `--no-wait` to hand off — because the Computer has no browser, and shipping
+ * it without that produces a command that hangs in exactly the environment it
+ * exists for. `plugin add` prints the URL when an install needs one, which
+ * covers the start of the handshake; finishing it is what remains.
  */
-const RESERVED = 'plugin writes are not available in this release; list and catalog are read-only'
-
-const reserved: Command[] = (
-  [
-    ['add', 'Install a plugin from the catalog'],
-    ['configure', 'Set a plugin’s configuration or credentials'],
-    ['connect', 'Complete an OAuth connection'],
-    ['verify', 'Check a plugin’s connection'],
-    ['remove', 'Uninstall a plugin'],
-  ] as const
-).map(([verb, summary]) => ({
+const RESERVED = 'completing an OAuth handshake needs a browser the CLI does not have; '
+  + '`frontera plugin add` prints the authorization URL to open'
+
+const connect: Command = {
   meta: {
     noun: 'plugin',
-    verb,
+    verb: 'connect',
     args: [],
     flags: {},
-    summary,
-    examples: [`frontera plugin ${verb} <id>`],
+    summary: 'Complete an OAuth connection',
+    examples: ['frontera plugin connect <installId>'],
     reserved: RESERVED,
   },
   async run(): Promise<never> {
     throw new Error(RESERVED)
   },
-}))
+}
 
-export const pluginCommands: Command[] = [list, catalog, ...reserved]
+export const pluginCommands: Command[] = [
+  list,
+  get,
+  catalog,
+  add,
+  configure,
+  policy,
+  verify,
+  remove,
+  connect,
+]

package/src/commands/registry.ts

@@ -16,6 +16,7 @@ import { appSdk } from './app/sdk'
 import { appDev } from './app/dev'
 import { blueprintList } from './blueprint/list'
 import { blueprintGet } from './blueprint/get'
+import { blueprintInstance, blueprintQuery } from './blueprint/query'
 import { blueprintGenerateTypes } from './blueprint/generate-types'
 import { blueprintAuthoringCommands } from './blueprint/authoring'
 import { blueprintDeclarativeCommands } from './blueprint/declarative'
@@ -26,7 +27,9 @@ import { actionCommands } from './action/index-commands'
 import { agentCommands } from './agent/index-commands'
 import { skillCommands } from './skill/index-commands'
 import { pluginCommands } from './plugin/index-commands'
+import { capabilityCommands } from './capability/index-commands'
 import { datasetCommands } from './dataset/index-commands'
+import { sourceCommands } from './source/index-commands'
 import { knowledgeCommands } from './knowledge/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
@@ -34,6 +37,9 @@ import { automationCommands } from './automation/index-commands'
 import { completionCommand } from './completion'
 import { initCommand } from './init'
 import { loginCommand } from './login'
+import { setupCommand } from './setup'
+import { authCommands } from './auth/index-commands'
+import { kitCommands } from './kit/index-commands'
 
 /**
  * Flags every command accepts. Declared once so a caller never has to wonder
@@ -45,6 +51,10 @@ export const GLOBAL_FLAGS: FlagSpec = {
   yes: 'boolean',
   help: 'boolean',
   'api-url': 'string',
+  // Global because the override has to work on EVERY command, not only the
+  // auth ones — a one-command escape hatch is useless if it exists on six
+  // commands and the seventh is the one being diagnosed.
+  profile: 'string',
 }
 
 /** Additionally accepted by any command that resolves a project. */
@@ -52,9 +62,13 @@ export const PROJECT_FLAGS: FlagSpec = { dir: 'string' }
 
 export const COMMANDS: readonly Command[] = [
   initCommand,
+  setupCommand,
   loginCommand,
   completionCommand,
 
+  ...authCommands,
+  ...kitCommands,
+
   appInit,
   appList,
   appAdd,
@@ -69,7 +83,9 @@ export const COMMANDS: readonly Command[] = [
   ...agentCommands,
   ...skillCommands,
   ...pluginCommands,
+  ...capabilityCommands,
   ...datasetCommands,
+  ...sourceCommands,
   ...knowledgeCommands,
   ...packCommands,
   ...secretCommands,
@@ -77,6 +93,10 @@ export const COMMANDS: readonly Command[] = [
 
   blueprintList,
   blueprintGet,
+  // Reads, next to the other two reads: the authoring verbs below all report
+  // success without proving anything came back, and these are what prove it.
+  blueprintQuery,
+  blueprintInstance,
   blueprintGenerateTypes,
   // 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.
@@ -112,18 +132,68 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   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',
+  source: 'Connected Sources — where a dataset’s rows come from',
   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',
   action: 'Governed Actions — arm the write path a published Action runs',
+  capability: 'What an agent may DO — plugin operations granted to it',
+  auth: 'Credential profiles — one per API key, selected by directory',
+  kit: 'Optional project-local Frontera skills for Codex and Claude Code',
 }
 
 export function nounSummary(noun: string): string {
   return NOUN_SUMMARY[noun] ?? ''
 }
 
+/**
+ * Where the CLI ends, and what to do instead.
+ *
+ * A `reserved` verb tells a caller that a command is planned but unbuilt.
+ * Nothing tells them about the surface that has no verb AT ALL — and that is
+ * most of the platform: channels, workspaces, sheets and the evaluation suite
+ * are all API surfaces the CLI deliberately does not carry. A caller asked to
+ * bind a channel reads "unknown command: channel", concludes it mistyped, and
+ * either guesses a synonym or greps the binary. Both waste a turn and neither
+ * ends at the answer.
+ *
+ * Keyed by the noun a caller would REACH FOR, not by the one that exists —
+ * these entries exist to be hit by a wrong guess. Every value names where the
+ * capability actually lives, because "not supported" without a destination is
+ * the same dead end in a politer voice.
+ *
+ * A test asserts no key here collides with a real noun: the day one of these
+ * ships, its entry has to go, or the CLI would disown a command it has.
+ */
+export const UNSUPPORTED: Readonly<Record<string, string>> = {
+  channel:
+    'channels have no CLI surface — create one and bind it to an agent in the Console, '
+    + 'under the agent’s Channels tab',
+  workspace:
+    'workspace and member management is Console-only. `frontera login` selects which workspace '
+    + 'a key acts on; it cannot create one',
+  key: 'API keys are minted in the Console, never by the CLI — a credential that mints credentials '
+    + 'is the escalation that separation exists to prevent',
+  sheet: 'sheets have no CLI surface and none is planned',
+  task: 'task and run history is Console-only; `frontera automation runs` covers automation runs',
+  eval: 'the evaluation suite (datasets, scorers, judges, queues) is Console-only',
+  usage: 'usage, cost and audit reporting is Console-only',
+  site: 'published sites are managed in the Console; `frontera app` covers Frontera Apps',
+  object:
+    'the legacy object surface is superseded by Blueprint — use `frontera blueprint` instead',
+  artifact:
+    'artifacts belong to the chat product — download or export one from the Console, '
+    + 'from the session that produced it',
+  user: 'users, roles and provider credentials are Console-only',
+}
+
+/** The message for a noun the CLI deliberately does not carry, if it is one. */
+export function unsupportedNoun(noun: string): string | null {
+  return UNSUPPORTED[noun] ?? null
+}
+
 /** Short forms every command understands, plus the command's own. */
 export function aliasesFor(meta: CommandMeta): Readonly<Record<string, string>> {
   return { h: 'help', ...(meta.aliases ?? {}) }
@@ -162,7 +232,11 @@ const GLOBAL_SECTION = [
   heading('Environment'),
   ...definitions([
     ['FRONTERA_API_URL', 'Frontera API origin'],
-    ['FRONTERA_TOKEN', 'workspace API key (sk-ws-…)'],
+    // Upstream's key-kind detail, kept — profiles change where a key is stored,
+    // not which kinds are valid.
+    ['FRONTERA_TOKEN', 'sk-ws-… or sk-org-… — requires FRONTERA_API_URL or --api-url'],
+    ['FRONTERA_PROFILE', 'profile to use, overriding the directory selection'],
+    ['FRONTERA_SECRET_STORE', 'where keys are stored: keychain (default on macOS) or file'],
     ['NO_COLOR', 'set to disable colour'],
   ]),
 ]
@@ -276,6 +350,20 @@ export function renderCommandHelp(meta: CommandMeta): string {
     lines.push('', ...wrap(`Not available yet: ${meta.reserved}`, width).map(dim))
   }
 
+  // Stated only for the exception. Printing "works with an API key" on the
+  // thirty commands where that is true trains a reader to skip the line, and
+  // the one command where it is false is the one that has to be read.
+  if (meta.authLane === 'session') {
+    lines.push(
+      '',
+      ...wrap(
+        'Needs a session credential: run `frontera login`. This command’s endpoints '
+        + 'refuse sk-ws- and sk-org- keys, and answer 401 rather than a permission error.',
+        width,
+      ).map(dim),
+    )
+  }
+
   if (meta.args.length > 0) {
     lines.push('', heading('Arguments'))
     lines.push(
@@ -338,6 +426,11 @@ export interface CommandDescriptor {
   examples: string[]
   needsProject: boolean
   requiresCredential: boolean
+  /**
+   * `api-key` — reachable with `sk-ws-`/`sk-org-` or a session.
+   * `session`  — reachable ONLY with a session token from `frontera login`.
+   */
+  authLane: 'api-key' | 'session'
 }
 
 export function describeCommand(meta: CommandMeta): CommandDescriptor {
@@ -366,6 +459,7 @@ export function describeCommand(meta: CommandMeta): CommandDescriptor {
     examples: [...meta.examples],
     needsProject: Boolean(meta.needsProject),
     requiresCredential: !meta.offline,
+    authLane: meta.authLane ?? 'api-key',
   }
 }
 
@@ -414,6 +508,15 @@ function nearest(typed: string, candidates: string[]): string | null {
 export function unknownCommand(noun: string, verb: string | undefined): UsageError {
   const known = nouns()
   if (!known.includes(noun)) {
+    // A deliberate boundary answers before the typo check does. `frontera
+    // channel bind` is not a misspelling of anything, and offering the nearest
+    // real noun would send a caller to an unrelated command with a plausible
+    // name rather than to the Console, where the capability is.
+    const boundary = unsupportedNoun(noun)
+    if (boundary) {
+      return new UsageError(`\`${noun}\` is not a Frontera CLI command`, boundary)
+    }
+
     const guess = nearest(noun, known)
     return new UsageError(
       `unknown command: ${noun}`,