@frontera-sdk/cli 1.45.6 → 1.45.8

package/src/commands/knowledge/upload-batch.ts

@@ -121,6 +121,61 @@ export function summarizeUploads(
  * the count of what did not land has to be the first thing on the page rather
  * than a column someone has to notice.
  */
+/**
+ * How many source rows already carry these filenames.
+ *
+ * A failed upload does NOT mean nothing was recorded: the service registers the
+ * source and then fails downstream — ingestion, embedding — so `all 1
+ * upload(s) failed` was printed while a `pending` row sat in the base. Retrying
+ * added a second row for the same file, which is the opposite of the "a retry
+ * duplicates nothing" the hint used to promise.
+ *
+ * Counted rather than guessed, and matched on the filename because that is all
+ * a failed upload leaves behind — no id comes back. Names are not unique, so
+ * this is reported as "rows carrying this name", never as "your upload".
+ */
+export async function countExistingSources(
+  api: { knowledgeSources(id: string): Promise<unknown[]> },
+  baseId: string,
+  filenames: string[],
+): Promise<Map<string, number>> {
+  const wanted = new Set(filenames)
+  const counts = new Map<string, number>()
+  // Best effort: this runs on a path that is already failing, and a second
+  // failure here must not replace the cause the caller needs to see.
+  const rows = await api.knowledgeSources(baseId).catch(() => [] as unknown[])
+  for (const row of rows as Array<{ fileName?: string }>) {
+    const name = row?.fileName
+    if (!name || !wanted.has(name)) continue
+    counts.set(name, (counts.get(name) ?? 0) + 1)
+  }
+  return counts
+}
+
+/**
+ * What to say about rows a failed upload may have left behind.
+ *
+ * Returns `undefined` when there is nothing to warn about, so a clean failure
+ * keeps a clean message.
+ */
+export function describeExistingSources(counts: Map<string, number>): string | undefined {
+  const present = [...counts.entries()].filter(([, n]) => n > 0)
+  if (present.length === 0) return undefined
+
+  const total = present.reduce((sum, [, n]) => sum + n, 0)
+  const duplicated = present.filter(([, n]) => n > 1)
+  return (
+    `${total} source row${total === 1 ? '' : 's'} already `
+    + `${total === 1 ? 'carries' : 'carry'} `
+    + `${present.length === 1 ? 'that filename' : 'those filenames'}`
+    + (duplicated.length > 0
+      ? `, and ${duplicated.length} filename${duplicated.length === 1 ? '' : 's'} `
+        + `${duplicated.length === 1 ? 'has' : 'have'} more than one — `
+        + 'a failed upload still registers a source, so re-running adds another'
+      : ' — a failed upload still registers a source')
+  )
+}
+
 export function renderUploadSummary(summary: UploadSummary): string {
   const lines: string[] = []
   const total = summary.sources.length

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

@@ -3,6 +3,7 @@ import { CliError, UsageError } from '../../errors'
 import { readSecretValue } from '../../secrets'
 import { table } from '../../table'
 import { flagString, type Command } from '../types'
+import { resolveWorkspaceId } from '../workspace-id'
 
 /**
  * Workspace secrets.
@@ -30,16 +31,6 @@ interface SecretRow {
   dependents?: Array<{ kind?: string; displayName?: string; name?: string }>
 }
 
-async function requireWorkspaceId(api: PlatformApi): Promise<string> {
-  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',
-    })
-  }
-  return me.workspaceId
-}
 
 const list: Command = {
   meta: {
@@ -52,7 +43,7 @@ const list: Command = {
   },
   async run(ctx) {
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const rows = (await api.workspaceSecrets(await requireWorkspaceId(api))) as SecretRow[]
+    const rows = (await api.workspaceSecrets(await resolveWorkspaceId(api))) as SecretRow[]
 
     return {
       data: rows,
@@ -130,7 +121,7 @@ const set: Command = {
     }
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const workspaceId = await requireWorkspaceId(api)
+    const workspaceId = await resolveWorkspaceId(api)
     const description = flagString(ctx, 'description')
 
     // List, then create or replace. The service has no upsert, and choosing by
@@ -180,7 +171,7 @@ const remove: Command = {
     if (!name) throw new UsageError('missing <name>', 'frontera secret list — then pass a name')
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    await api.deleteWorkspaceSecret(await requireWorkspaceId(api), name)
+    await api.deleteWorkspaceSecret(await resolveWorkspaceId(api), name)
 
     // No `--force`. The service refuses while anything still resolves the
     // secret and says what, and an override here would only move the outage

package/src/commands/skill/bundle-commands.ts

@@ -6,6 +6,7 @@ import matter from 'gray-matter'
 import { PlatformApi } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
 import { flagBool, flagString, type Command } from '../types'
+import { resolveWorkspaceId } from '../workspace-id'
 import { resolveSkillRef } from './resolve'
 
 /**
@@ -123,7 +124,9 @@ const pull: Command = {
 
   async run(ctx) {
     const ref = ctx.positional[0]
-    if (!ref) throw new UsageError('missing <skill>', 'frontera skill pull <skill> [--dir <path>]')
+    // `skill get` and `skill delete` both name the producer; pull restated its
+    // own form, which tells a caller nothing they did not already have.
+    if (!ref) throw new UsageError('missing <skill>', 'frontera skill list — then pass a name or id')
 
     const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const id = await resolveSkillRef(client, ref)
@@ -152,21 +155,16 @@ const pull: Command = {
       written.push(script.path)
     }
 
-    // Assets need the workspace segment for the download route; a workspace
-    // key resolves its own scope, so whoami is authoritative.
+    // Assets need the workspace segment for the download route. `--workspace`
+    // answers it for an organization key, which cannot call whoami at all; a
+    // workspace key still falls back to its own scope.
     const assets = doc.assets ?? []
     if (assets.length > 0) {
-      const who = await client.whoami()
-      if (!who.workspaceId) {
-        throw new CliError('cannot download assets without a workspace scope', {
-          code: 'FORBIDDEN',
-          hint: 'use a workspace-scoped API key',
-        })
-      }
+      const workspaceId = await resolveWorkspaceId(client)
       for (const asset of assets) {
         const filename = assetFilename(asset.storageKey)
         if (!filename) continue
-        const bytes = await client.downloadSkillAsset(who.workspaceId, filename)
+        const bytes = await client.downloadSkillAsset(workspaceId, filename)
         writeBundleFile(dir, asset.path, bytes)
         written.push(`${asset.path}${asset.visible ? ' *' : ''}`)
       }

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

@@ -172,7 +172,85 @@ function requireConfig(doc: SourceFile, path: string): Record<string, unknown> {
       hint: 'config: { kind: "postgres", host, port, database, username, sslMode, connectTimeoutMs }',
     })
   }
-  return doc.config as Record<string, unknown>
+  const config = doc.config as Record<string, unknown>
+  validateConnectionConfig(config, path)
+  return config
+}
+
+const SSL_MODES = ['require', 'verify-ca', 'verify-full', 'disable']
+
+/**
+ * The connection block, checked here for the reason `validateDatasets` gives.
+ *
+ * That function exists because the service's refusal for this body names the
+ * wrong field — `strictJsonBody` substitutes a sentinel that omits `mode`, so
+ * ANY failure anywhere in the document comes back as "Expected 'virtual' at
+ * /datasets/0/mode". It pre-empted that for `datasets` and not for `config`,
+ * which left the commonest mistakes unreachable: a `config` missing `kind` or
+ * `connectTimeoutMs` was reported as a bad `mode` on a dataset whose `mode` was
+ * already `"virtual"`.
+ *
+ * That is how `source create` came to look like a write path with no passing
+ * document. It has one — the errors were describing the wrong half of the file.
+ *
+ * `password` is deliberately absent: it never travels in the file, and a file
+ * carrying one is refused rather than stripped, above.
+ */
+export function validateConnectionConfig(config: Record<string, unknown>, path: string): void {
+  const where = `${path}: config`
+
+  if (config.kind !== 'postgres') {
+    throw new CliError(`${where} has kind ${JSON.stringify(config.kind)}.`, {
+      code: 'USAGE',
+      hint: 'kind must be "postgres" — it is the only connector the service accepts today',
+    })
+  }
+
+  for (const field of ['host', 'database', 'username'] as const) {
+    const value = config[field]
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new CliError(`${where}.${field} is ${JSON.stringify(value)}.`, {
+        code: 'USAGE',
+        hint: `${field} must be a non-empty string`,
+      })
+    }
+  }
+
+  const port = config.port
+  if (!Number.isInteger(port) || (port as number) < 1 || (port as number) > 65_535) {
+    throw new CliError(`${where}.port is ${JSON.stringify(port)}.`, {
+      code: 'USAGE',
+      hint: 'port must be a whole number between 1 and 65535 — 5432 for a default PostgreSQL',
+    })
+  }
+
+  if (typeof config.sslMode !== 'string' || !SSL_MODES.includes(config.sslMode)) {
+    throw new CliError(`${where}.sslMode is ${JSON.stringify(config.sslMode)}.`, {
+      code: 'USAGE',
+      hint: `sslMode must be one of: ${SSL_MODES.join(', ')}`,
+    })
+  }
+
+  const timeout = config.connectTimeoutMs
+  if (!Number.isInteger(timeout) || (timeout as number) < 1_000 || (timeout as number) > 15_000) {
+    throw new CliError(`${where}.connectTimeoutMs is ${JSON.stringify(timeout)}.`, {
+      code: 'USAGE',
+      // Easily missed: it has no sensible default the CLI could supply, because
+      // the right value depends on where the database is.
+      hint: 'connectTimeoutMs must be a whole number of milliseconds between 1000 and 15000',
+    })
+  }
+
+  // The service sets `additionalProperties: false`, so an extra key fails the
+  // whole document — and fails it by naming a dataset's `mode`.
+  const KNOWN = new Set(['kind', 'host', 'port', 'database', 'username', 'sslMode', 'connectTimeoutMs'])
+  const unknown = Object.keys(config).filter((key) => !KNOWN.has(key))
+  if (unknown.length > 0) {
+    throw new CliError(`${where} carries unknown field(s): ${unknown.join(', ')}.`, {
+      code: 'USAGE',
+      hint: `config accepts exactly: ${[...KNOWN].join(', ')}`,
+    })
+  }
 }
 
 const list: Command = {

package/src/commands/types.ts

@@ -6,6 +6,14 @@ export interface ArgSpec {
   name: string
   required: boolean
   description: string
+  /**
+   * What to run to obtain this value, when the dispatcher reports it missing.
+   *
+   * Only read for `needsProject` commands, whose own `run` never executes when
+   * an argument is absent. Everywhere else the command raises its own error and
+   * names its own producer, which is strictly better than anything general.
+   */
+  producer?: string
 }
 
 export interface CommandMeta {
@@ -18,6 +26,21 @@ export interface CommandMeta {
   summary: string
   /** At least one, copy-pasteable. Agents read --help before documentation. */
   examples: readonly string[]
+  /**
+   * The grain this VERB acts at, when it differs from its noun's.
+   *
+   * Scope was tracked per noun, and several nouns span both grains: Blueprint
+   * AUTHORING edits one draft shared by the organization while Blueprint
+   * READING returns the slice granted to one workspace, and `action list` is
+   * organization-wide while `action requests` is not. A per-noun map cannot be
+   * right about either — it produced a warning that named the wrong commands,
+   * and let `agent list` answer "No agents in this workspace" for a request
+   * that had never named a workspace.
+   *
+   * Omit it and the noun's own grain applies. See `scopes.ts`.
+   */
+  scope?: 'workspace' | 'organization'
+
   /** Resolve an app project before running, and fail if there is none. */
   needsProject?: boolean
   /**

package/src/commands/workspace-id.ts

@@ -0,0 +1,38 @@
+import type { PlatformApi } from '../api/platform-api'
+import { CliError } from '../errors'
+
+/**
+ * Which workspace a command is acting in.
+ *
+ * `knowledge` and `secret` name a workspace in the URL, so they have to resolve
+ * one before they can call anything. Both asked `whoami`, which is right for a
+ * workspace key — it carries its own workspace and nothing else names it — and
+ * wrong for an organization key in two compounding ways:
+ *
+ *   `/v1/whoami` answers 403 to an organization key, so the resolution failed
+ *   before it could report what was actually missing. The caller read
+ *   "Insufficient permissions" and went looking for a capability, when the key
+ *   held every one the route needed.
+ *
+ *   `--workspace` was already on the command line. The flag exists precisely so
+ *   an organization key can say which workspace it means, and these two nouns
+ *   are in the addressable set — so the CLI accepted the answer and then went
+ *   and asked someone else.
+ *
+ * The flag wins when present. `whoami` stays as the fallback, because a
+ * workspace key does not pass `--workspace` and should not have to.
+ */
+export async function resolveWorkspaceId(api: PlatformApi): Promise<string> {
+  if (api.workspaceId) return api.workspaceId
+
+  const me = await api.whoami().catch(() => null)
+  if (me?.workspaceId) return me.workspaceId
+
+  throw new CliError('this credential does not name a workspace', {
+    code: 'FORBIDDEN',
+    // Both routes out, because both are real: an organization key names one per
+    // invocation, and a workspace key carries one permanently.
+    hint: 'pass --workspace <id> (see `frontera workspace list`), '
+      + 'or use a workspace key (sk-ws-…) created for the workspace you mean',
+  })
+}

package/src/main.ts

@@ -6,6 +6,7 @@ import { CliError, UsageError } from './errors'
 import { EXIT } from './exit'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
+import { commandScope } from './scopes'
 import {
   aliasesFor,
   describeCommand,
@@ -154,6 +155,29 @@ async function main(): Promise<number> {
     const dirFlag = typeof flags.dir === 'string' ? flags.dir : undefined
     const cwd = dirFlag ?? process.cwd()
 
+    /**
+     * A missing argument outranks a missing project directory.
+     *
+     * `needsProject` is enforced here, before `run`, so a command that
+     * validates its own arguments never got to speak: `frontera app promote`
+     * with no version reported "not in a Frontera app directory" and never
+     * mentioned `<version>` or `app versions`. Two things were wrong and the
+     * caller was told the one they had not asked about.
+     *
+     * Scoped to `needsProject` deliberately. Every other command reaches its
+     * own check, and those checks name the command that PRODUCES the missing
+     * value — better than anything derivable here, and worth not preempting.
+     */
+    const missingArg = command.meta.args.find((arg, i) => arg.required && positional[i] === undefined)
+
+    if (command.meta.needsProject && missingArg) {
+      throw new UsageError(
+        `missing <${missingArg.name}>`,
+        missingArg.producer ?? command.meta.examples[0]
+          ?? `frontera ${command.meta.noun} ${command.meta.verb} <${missingArg.name}>`,
+      )
+    }
+
     let project: AppProject | null = null
     if (command.meta.needsProject || command.meta.optionalProject) {
       const root = findProjectRoot(cwd)
@@ -187,9 +211,6 @@ async function main(): Promise<number> {
     const workspaceFlag = typeof flags.workspace === 'string' ? flags.workspace.trim() : undefined
 
     /**
-     * Nouns whose commands build a `PlatformApi`, which is the only client that
-     * carries `x-workspace-id`.
-     *
      * `--workspace` is global — same reasoning as `--profile`: an escape hatch
      * that exists on six commands and not the seventh is useless when the
      * seventh is the one being diagnosed. But global must not mean "silently
@@ -197,45 +218,61 @@ async function main(): Promise<number> {
      * and reported nothing, which is the plausible-wrong-answer shape this CLI
      * refuses everywhere else.
      *
-     * Listed rather than derived because the mapping is a fact about which
-     * client a command constructs, and a wrong entry should be a failing test
-     * rather than a silent no-op.
+     * Judged per VERB, not per noun: `blueprint status` edits the shared draft
+     * and has no workspace to name, while `blueprint list` reads the slice
+     * granted to one. A noun-level refusal was wrong about both.
      */
-    const WORKSPACE_ADDRESSABLE = new Set([
-      'agent', 'app', 'blueprint', 'capability', 'knowledge',
-      'pack', 'plugin', 'secret', 'skill',
-    ])
-
-    if (workspaceFlag && !WORKSPACE_ADDRESSABLE.has(command.meta.noun)) {
+    // `offline` as well as organization grain: `init` and `setup` write files
+    // and never open a connection, so a workspace means nothing to them. They
+    // are not organization-scoped either, so scope alone would have let the
+    // flag through — `frontera init --workspace <id>` scaffolded a directory
+    // and ignored the flag in silence.
+    const label = `${command.meta.noun}${command.meta.verb ? ` ${command.meta.verb}` : ''}`
+    if (workspaceFlag && (command.meta.offline || commandScope(command.meta) === 'organization')) {
       throw new UsageError(
-        `--workspace does nothing on \`${command.meta.noun}\``,
-        'these commands are organization-scoped, or need no credential at all. '
-        + '--workspace applies to: ' + [...WORKSPACE_ADDRESSABLE].sort().join(', '),
+        `--workspace does nothing on \`${label}\``,
+        command.meta.offline
+          ? 'this command touches no service, so there is no request to address.'
+          : 'this command acts on the whole organization. '
+            + '--workspace applies to workspace-scoped commands — '
+            + `try \`frontera ${command.meta.noun} --help\``,
       )
     }
 
-    // An organization key with no workspace named runs at ORG scope, and a
-    // workspace-scoped read then answers with an empty list rather than a
-    // refusal — `agent list` said "No agents in this workspace" for a workspace
-    // holding thirty. A plausible wrong answer is worse than an error, so say
-    // so before the command runs.
-    //
-    // Exempt where org scope is the point: those nouns are correct as-is, and
-    // `workspace list` is the FIRST thing such a caller runs to find an id.
-    // Listed rather than inferred — there is no scope field on a command, and
-    // adding one to silence a note would be the wrong trade.
-    const ORG_SCOPED_NOUNS = new Set(['blueprint', 'dataset', 'source', 'workspace', 'auth', 'kit'])
+    /**
+     * An organization key that named no workspace cannot run a
+     * workspace-scoped command, so it is refused rather than warned.
+     *
+     * This was a note, and a note was not enough. The request still went out,
+     * ran at organization scope, matched nothing, and `agent list` printed
+     * "No agents in this workspace." and exited 0 — for a request that had
+     * never looked at a workspace. Every sibling already refused (`app` and
+     * `pack` with 400, `skill` with 403, `knowledge` and `secret` with advice);
+     * `agent` was the one that answered a plausible lie with a success code.
+     *
+     * The wording is `knowledge`'s, because both routes out are real: an
+     * organization key names a workspace per invocation, a workspace key
+     * carries one permanently.
+     */
     if (
       !command.meta.offline
       && !workspaceFlag
-      && !ORG_SCOPED_NOUNS.has(command.meta.noun)
+      // A missing argument outranks a missing workspace, for the reason the
+      // project gate above gives: `skill pull` with no skill named has a
+      // better error waiting inside the command, and it names the command
+      // that produces the value. Let it be raised.
+      && !missingArg
+      && commandScope(command.meta) === 'workspace'
       && credential.token.startsWith('sk-org-')
     ) {
-      output.note(
-        'note: organization key with no --workspace. Organization-scoped commands '
-        + '(blueprint authoring, dataset, source) work as-is; workspace-scoped ones '
-        + '(agent, skill, plugin, capability, knowledge, pack, secret) will read nothing. '
-        + '`frontera workspace list` shows the ids.',
+      throw new CliError(
+        `\`${label}\` acts inside a workspace, `
+        + 'and this organization key names none',
+        {
+          code: 'FORBIDDEN',
+          hint: 'pass --workspace <id> (see `frontera workspace list`), '
+            + 'or use a workspace key (sk-ws-…) created for the workspace you mean',
+        },
       )
     }
 

package/src/scopes.ts

@@ -0,0 +1,56 @@
+/**
+ * Which grain each noun acts at — stated once.
+ *
+ * This map had grown three copies: the dispatcher's unaddressed-organization-key
+ * note, the list of nouns `--workspace` can reach, and the hint a 403 carries.
+ * They had already disagreed — `action` appeared in none of them, so an
+ * organization key running `action list` was warned about workspace scope by a
+ * sentence that did not mention `action`, and refused by a hint that called
+ * Actions organization-scoped.
+ *
+ * The noun map is a DEFAULT, not the answer: `commandScope` below lets a verb
+ * override it, because several nouns span both grains.
+ *
+ * There is no scope field on a command to derive this from, and adding one to
+ * silence a note would be the wrong trade — the grain is a fact about the
+ * SERVICE's routes, not about the command that calls them. So it is listed, and
+ * listed here only.
+ */
+
+/**
+ * Nouns whose routes answer at organization grain.
+ *
+ * A workspace key is refused these BY DESIGN — it is not a narrower
+ * organization key, it is a different lane. `auth` and `kit` are here because
+ * naming a workspace means nothing to them, not because they reach the service.
+ */
+export const ORG_SCOPED_NOUNS = new Set([
+  'auth',
+  'kit',
+  'workspace',
+  'blueprint',
+  'dataset',
+  'source',
+  // Governed Actions live under `/v1/blueprint/governed-actions` and carry the
+  // Blueprint's grain, which is why a workspace key is refused `action list`.
+  'action',
+])
+
+/**
+ * The grain one command acts at.
+ *
+ * The verb's own declaration wins; otherwise the noun's. Most nouns are
+ * uniform, so declaring all 129 would be noise that rots — and the ones that
+ * are not uniform are precisely the ones a per-noun map gets wrong.
+ */
+export function commandScope(meta: {
+  noun: string
+  scope?: 'workspace' | 'organization'
+}): 'workspace' | 'organization' {
+  return meta.scope ?? (ORG_SCOPED_NOUNS.has(meta.noun) ? 'organization' : 'workspace')
+}
+
+/** For prose: the organization-scoped nouns that actually reach the service. */
+export function orgScopedServiceNouns(): string[] {
+  return [...ORG_SCOPED_NOUNS].filter((n) => n !== 'auth' && n !== 'kit').sort()
+}