@frontera-sdk/cli 0.1.0

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

@@ -0,0 +1,140 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+interface KnowledgeRow {
+  id?: string
+  name?: string
+  displayName?: string
+  description?: string
+}
+
+/** Accept a base by name or id — `knowledge list` shows both. */
+async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<string> {
+  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+  if (UUID.test(ref)) return ref
+
+  const me = await client.whoami()
+  if (!me.workspaceId) {
+    throw new CliError('this credential is not scoped to a workspace', {
+      code: 'FORBIDDEN',
+      hint: 'use a workspace key (sk-ws-…) created for the workspace you mean',
+    })
+  }
+  const rows = (await client.knowledgeBases(me.workspaceId)) as KnowledgeRow[]
+  const match = rows.find((k) => (k.name ?? '').toLowerCase() === ref.toLowerCase())
+  if (match?.id) return match.id
+
+  throw new CliError(`no knowledge base named "${ref}"`, {
+    code: 'NOT_FOUND',
+    hint: `known bases: ${rows.map((k) => k.name).filter(Boolean).join(', ') || '(none)'}`,
+  })
+}
+
+const list: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List knowledge bases in this workspace',
+    examples: ['frontera knowledge list', 'frontera knowledge list --json'],
+  },
+  async run(ctx) {
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    // The route takes the workspace explicitly, and a key holder cannot see
+    // its own workspace id from anywhere else — hence /v1/whoami.
+    const me = await api.whoami()
+    if (!me.workspaceId) {
+      throw new CliError('this credential is not scoped to a workspace', {
+        code: 'FORBIDDEN',
+        hint: 'use a workspace key (sk-ws-…) created for the workspace you mean',
+      })
+    }
+    const rows = (await api.knowledgeBases(me.workspaceId)) as KnowledgeRow[]
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No knowledge bases in this workspace.'
+          : // NAME first: it is the value `knowledge sources` takes, not the id.
+            // No `displayName` on these rows, so a column for it was always
+            // blank and shifted the description out of alignment.
+            table(
+              ['name', 'description', 'id'],
+              rows.map((k) => [k.name ?? '?', k.description ?? '', k.id ?? '']),
+              [undefined, 60, undefined],
+            ),
+    }
+  },
+}
+
+const sources: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'sources',
+    args: [{ name: 'base', required: true, description: 'knowledge base name or id, from `frontera knowledge list`' }],
+    flags: {},
+    summary: 'List the sources in one knowledge base',
+    examples: ['frontera knowledge sources product-docs'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+
+    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const id = await resolveKnowledgeRef(client, ref)
+    const rows = (await client.knowledgeSources(id)) as Array<Record<string, unknown>>
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No sources in this knowledge base.'
+          : table(
+              // `fileName`, not `name` — a source is an uploaded file, and
+              // guessing the field printed "?" for every row.
+              ['file', 'status', 'chunks', 'id'],
+              rows.map((r) => [
+                String(r.fileName ?? '?'),
+                String(r.error ? `error: ${r.error}` : (r.status ?? '')),
+                String(r.chunkCount ?? ''),
+                String(r.id ?? ''),
+              ]),
+              [50, 40, undefined, undefined],
+            ),
+    }
+  },
+}
+
+/**
+ * `upload` is the strongest case for this noun existing at all — nobody wants
+ * to drag two hundred PDFs into a browser — and is reserved rather than
+ * half-built: it needs per-file outcome reporting so one unreadable file does
+ * not fail a batch, which is the whole reason to prefer it over the UI.
+ */
+const RESERVED = 'knowledge writes are not available in this release; list and sources are read-only'
+
+const reserved: Command[] = (
+  [
+    ['create', 'Create a knowledge base'],
+    ['upload', 'Upload files into a knowledge base'],
+    ['delete', 'Delete a knowledge base'],
+  ] as const
+).map(([verb, summary]) => ({
+  meta: {
+    noun: 'knowledge',
+    verb,
+    args: [],
+    flags: {},
+    summary,
+    examples: [`frontera knowledge ${verb} <name>`],
+    reserved: RESERVED,
+  },
+  async run(): Promise<never> {
+    throw new Error(RESERVED)
+  },
+}))
+
+export const knowledgeCommands: Command[] = [list, sources, ...reserved]

package/src/commands/login.ts

@@ -0,0 +1,103 @@
+import { PlatformApi } from '../api/platform-api'
+import { writeStoredToken } from '../config'
+import { CliError, UsageError } from '../errors'
+import { readSecretValue } from '../secrets'
+import { canPrompt, promptSecret } from '../prompt'
+import type { Command } from './types'
+
+/**
+ * Store a workspace key for an API origin.
+ *
+ * Non-interactive by construction: the token arrives on stdin or from the
+ * environment, never as a flag and never through a prompt. A prompt is where
+ * an agent hangs, and a flag lands the secret in process listings and shell
+ * history.
+ *
+ * The token is VERIFIED before it is written. Storing an unusable credential
+ * just moves the failure to the next command, where the cause is no longer
+ * obvious — and the check costs one request that also tells the caller which
+ * workspace it just bound to.
+ */
+/**
+ * Where the token comes from, in the order a caller would expect.
+ *
+ * Piped input wins over a prompt, so `echo $KEY | frontera login` works
+ * without a flag — the clig.dev convention, and the reason `--token-stdin`
+ * is now an explicit opt-in rather than a requirement.
+ *
+ * The prompt is reached only on an interactive terminal. An agent's stdin is
+ * a pipe or /dev/null, so it lands in the stdin branch or the error, never on
+ * a prompt that would hang. `--no-input` forces that even on a TTY.
+ */
+async function readToken(flags: Record<string, string | boolean>): Promise<string> {
+  const noInput = flags['no-input'] === true
+  const explicitStdin = flags['token-stdin'] === true
+
+  if (explicitStdin || !canPrompt() || noInput) {
+    // Not a terminal: read whatever was piped in. Falls back to the
+    // environment so an already-exported key can simply be stored.
+    if (explicitStdin || !process.stdin.isTTY) {
+      const piped = (await readSecretValue('-')).trim()
+      if (piped) return piped
+    }
+    return (process.env.FRONTERA_TOKEN ?? '').trim()
+  }
+
+  return promptSecret('Workspace key (sk-ws-…): ')
+}
+
+export const loginCommand: Command = {
+  meta: {
+    noun: 'login',
+    verb: '',
+    args: [],
+    flags: { 'token-stdin': 'boolean', 'no-input': 'boolean' },
+    summary: 'Verify a workspace key and store it for this API origin',
+    examples: [
+      'frontera login --api-url http://localhost:4000',
+      'echo $KEY | frontera login --api-url http://localhost:4000',
+      'frontera login --api-url https://api.example.com --token-stdin < key.txt',
+    ],
+    // It SUPPLIES a credential, so it must not require one to start.
+    offline: true,
+  },
+
+  async run(ctx) {
+    if (!ctx.apiUrl) {
+      throw new UsageError(
+        'no API origin configured',
+        'set FRONTERA_API_URL, or pass --api-url <origin>',
+      )
+    }
+
+    const token = await readToken(ctx.flags)
+
+    if (!token) {
+      throw new UsageError(
+        'no token supplied',
+        'run `frontera login` in a terminal to be asked for one, or pipe it in: `echo $KEY | frontera login`',
+      )
+    }
+    if (!token.startsWith('sk-ws-')) {
+      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',
+      )
+    }
+
+    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})`,
+      })
+    }
+
+    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}`,
+    }
+  },
+}

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

@@ -0,0 +1,112 @@
+import { PlatformApi } from '../../api/platform-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * `/v1/apps` returns `{ install, catalog, … }` per row, not a flattened
+ * install — so reading `id` and `status` off the top level yielded undefined
+ * and every row printed "?" with a blank status.
+ */
+interface InstallRow {
+  install?: { id?: string; installName?: string; status?: string; enabled?: boolean }
+  catalog?: { kind?: string; displayName?: string; authType?: string }
+}
+
+/**
+ * `plugin` covers an OAuth integration and a workspace-hosted MCP server
+ * alike. The platform already models them as one family — an App may use
+ * OAuth, API-key, native or MCP-backed connectivity, and a custom MCP server
+ * is one App subtype — they simply never had a shared name that was not "app".
+ *
+ * The Console still says "Apps". That divergence is known and tracked, not
+ * accidental: `frontera app` is Frontera Apps, which are a different thing.
+ */
+const list: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List installed plugins — integrations and MCP servers',
+    examples: ['frontera plugin list', 'frontera plugin list --json'],
+  },
+  async run(ctx) {
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).pluginInstalls()) as InstallRow[]
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No plugins installed in this workspace.'
+          : table(
+              ['id', 'kind', 'status', 'name'],
+              rows.map((i) => [
+                i.install?.id ?? '?',
+                i.catalog?.kind ?? '',
+                i.install?.enabled === false ? 'disabled' : (i.install?.status ?? ''),
+                i.install?.installName ?? i.catalog?.displayName ?? '',
+              ]),
+            ),
+    }
+  },
+}
+
+const catalog: Command = {
+  meta: {
+    noun: 'plugin',
+    verb: 'catalog',
+    args: [],
+    flags: {},
+    summary: 'List plugins available to install',
+    examples: ['frontera plugin catalog'],
+  },
+  async run(ctx) {
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token).pluginCatalog()) as Array<{
+      kind?: string
+      displayName?: string
+      authType?: string
+    }>
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'Nothing in the plugin catalog.'
+          : table(
+              ['kind', 'auth', 'name'],
+              rows.map((c) => [c.kind ?? '?', c.authType ?? '', c.displayName ?? '']),
+            ),
+    }
+  },
+}
+
+/**
+ * `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.
+ */
+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]) => ({
+  meta: {
+    noun: 'plugin',
+    verb,
+    args: [],
+    flags: {},
+    summary,
+    examples: [`frontera plugin ${verb} <id>`],
+    reserved: RESERVED,
+  },
+  async run(): Promise<never> {
+    throw new Error(RESERVED)
+  },
+}))
+
+export const pluginCommands: Command[] = [list, catalog, ...reserved]