@frontera-sdk/cli 1.44.1 → 1.45.0

package/src/exit.ts

@@ -29,9 +29,32 @@ export interface ErrorEnvelope {
   hint?: string
 }
 
-const USAGE_CODES = new Set(['USAGE', 'VALIDATION_ERROR', 'BAD_REQUEST', 'NOT_FOUND'])
+const USAGE_CODES = new Set([
+  'USAGE',
+  'VALIDATION_ERROR',
+  'BAD_REQUEST',
+  'NOT_FOUND',
+  // Profile selection. Every one of these is fixed by changing the command or
+  // the directory binding — never by retrying, which is what separates them
+  // from AUTH below: a wrong profile is a usage mistake, a revoked key is not.
+  'PROFILE_NOT_FOUND',
+  'PROFILE_NOT_SELECTED',
+  'PROFILE_ORIGIN_MISMATCH',
+  'PROFILE_INVALID',
+  'PROJECT_CONTEXT_NOT_FOUND',
+  'PROJECT_CONTEXT_CORRUPT',
+  'PROJECT_CONTEXT_UNTRUSTED',
+  // Authoring kit. Both are resolved by running a named command, not by retry.
+  'KIT_VERSION_MISMATCH',
+  'GENERATED_FILE_CONFLICT',
+])
 const CONFLICT_CODES = new Set(['DRAFT_CONFLICT', 'CONFLICT', 'VALIDATION_STALE'])
-const AUTH_CODES = new Set(['UNAUTHORIZED', 'FORBIDDEN'])
+const AUTH_CODES = new Set([
+  'UNAUTHORIZED',
+  'FORBIDDEN',
+  // The key is gone, not merely unselected — same recovery as a revoked one.
+  'PROFILE_SECRET_MISSING',
+])
 
 /**
  * Unrecognised codes fall to FAILURE rather than throwing. The SDK does not
@@ -63,6 +86,10 @@ const SERVICE_HINTS: Record<string, string> = {
   FORBIDDEN: 'this credential lacks permission for that resource — ask an admin, or use a different key',
   NOT_FOUND: 'list the resource first to confirm the id',
   RATE_LIMITED: 'wait and retry',
+  // Exit 1: the store may be locked or momentarily unreachable, so one retry is
+  // a reasonable move before reporting.
+  SECURE_STORE_UNAVAILABLE:
+    'unlock the OS credential store and retry, or set FRONTERA_SECRET_STORE=file',
   SERVICE_UNAVAILABLE: 'the service is unavailable — retry shortly',
 }
 

package/src/flag-help.ts

@@ -41,7 +41,8 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   quiet: 'suppress progress commentary on stderr',
   yes: 'assume yes for confirmations',
   help: 'show this help',
-  'api-url': 'API origin to use, overriding FRONTERA_API_URL and the stored default',
+  'api-url': "API origin to use — must match the selected profile's origin",
+  profile: 'credential profile to use for this command, overriding the directory selection',
   output: 'project-relative .ts path for generated output',
   check: 'verify generated output is current without writing it',
 
@@ -82,16 +83,64 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Packs
   'remove-apps': 'also uninstall the apps the pack installed',
 
-  // Secrets
+  // Secrets, and the same rule for API keys in `auth add`
   from: 'where to read the value from: `-` for stdin, or a file path. Never an inline value',
+  // Same rule as `--from`, named separately because a Source definition file
+  // carries every other field and only this one is refused inside it.
+  'password-from':
+    'where to read the connection password from: `-` for stdin, or a file path. Never an inline '
+    + 'value, and never inside the definition file',
+
+  // Blueprint reads
+  select: 'comma-separated property API names to return (default: whatever the service returns)',
+  where:
+    'filter as <property>:<value>, <property>:<op>:<value>, or a JSON where-node for anything '
+    + 'with and/or in it',
+  order: 'sort as <property>:asc or <property>:desc, comma-separated for more than one',
+  // No number here on purpose. This map is keyed by flag NAME across every
+  // command, and the three surfaces that take `--limit` cap a page at 1000,
+  // 200 and 100 — so any figure stated once is wrong for two of them. Each
+  // command's own refusal names its real ceiling.
+  limit: 'maximum rows to return in one page; each surface has its own ceiling',
+  'page-token': 'cursor from the previous response’s nextPageToken; omit for the first page',
+  // Named for the field the response carries, which differs by surface —
+  // Blueprint answers `nextPageToken`, data-integration answers `nextCursor`.
+  // Matching each flag to its own response beats one name that is wrong half
+  // the time.
+  cursor: 'cursor from the previous response’s nextCursor; omit for the first page',
+  lifecycle: 'only requests in this lifecycle state; comma-separate for more than one',
+
+  // Plugins and agent capabilities
+  enable: 'switch the install on',
+  disable: 'switch the install off, leaving it installed',
+  actions:
+    'Action policy for the install: allow_all, read_only or custom. read_only refuses every '
+    + 'Action capability grant on it',
+  'new-capability': 'what a newly discovered capability defaults to: enabled or disabled',
+  'end-user':
+    'bind as end_user, so every caller connects their own account, instead of agent_owned, '
+    + 'which uses one credential the workspace holds',
+  'accept-orphaned-knowledge':
+    'revert even though the old version names a knowledge base that no longer exists',
 
   // Knowledge
   description: 'one-line description stored on the resource',
+  'top-k': 'how many chunks to return (default 10)',
+  // A DISTANCE cutoff, not the similarity the output column shows — the query
+  // keeps chunks whose cosine distance is below it, so a HIGHER value is more
+  // permissive and 0 matches nothing at all. Described the wrong way round
+  // first, which made `--threshold 0` look like "return everything".
+  threshold:
+    'maximum cosine distance a chunk may have; higher is more permissive (default 0.9). '
+    + 'Not the similarity score shown in the output — 0 matches nothing',
   strategy:
     'text extraction to use per file: auto (default), text, or ocr; ocr needs an OCR engine on the base',
 
   // Auth and setup
-  'token-stdin': 'read the workspace key from stdin instead of prompting',
+  // "key", not "workspace key": `login` verifies an organization key too, and
+  // naming only one kind here was the last place the CLI still implied that a
+  // holder of the other had no route in.
+  'token-stdin': 'read the key from stdin instead of prompting — sk-ws- or sk-org-',
   'no-input': 'never prompt; fail instead, for use in scripts and CI',
   config: 'print the resolved configuration and where each value came from',
 }
@@ -103,6 +152,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
  */
 const PLACEHOLDER: Readonly<Record<string, string>> = {
   'api-url': 'origin',
+  profile: 'name',
   output: 'path',
   dataset: 'name',
   plan: 'path',
@@ -116,8 +166,20 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   description: 'text',
   strategy: 'auto|text|ocr',
   from: '-|path',
+  'password-from': '-|path',
   name: 'text',
   kind: 'conversation|work',
+  select: 'a,b,c',
+  where: 'prop:value',
+  order: 'prop:asc',
+  limit: 'n',
+  'page-token': 'cursor',
+  cursor: 'cursor',
+  lifecycle: 'state',
+  actions: 'allow_all|read_only|custom',
+  'new-capability': 'enabled|disabled',
+  'top-k': 'n',
+  threshold: '0-2',
   template: 'non-negative|percentage|status-enum|code-length',
 }
 

package/src/fs-atomic.ts

@@ -0,0 +1,44 @@
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * Write a file so a reader never sees half of it.
+ *
+ * Profile metadata and directory context are read by every command, including
+ * the ones running concurrently in another terminal. A plain `writeFileSync`
+ * truncates first and fills after, so a crash — or a reader arriving in that
+ * window — finds an empty or partial JSON document, which the resolver would
+ * then have to treat as corrupt. Temp file, fsync, atomic rename: the reader
+ * sees the old bytes or the new ones and nothing between.
+ *
+ * Mode 0600 by default because both files this is used for are personal
+ * machine configuration, and one of them sits next to a credential store.
+ */
+export function writeFileAtomic(path: string, content: string, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true })
+  // Same directory, so the rename stays within one filesystem — a cross-device
+  // rename is not atomic and not even permitted.
+  const tmp = join(dirname(path), `.${Date.now()}-${process.pid}.tmp`)
+  try {
+    writeFileSync(tmp, content, { mode })
+    // Explicitly, because the create mode is masked by the process umask — a
+    // file asked for as 0664 lands as 0644 under the usual 022, so preserving
+    // an existing file's mode across an atomic replace requires this.
+    chmodSync(tmp, mode)
+    const fd = openSync(tmp, 'r+')
+    try {
+      fsyncSync(fd)
+    } finally {
+      closeSync(fd)
+    }
+    renameSync(tmp, path)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // The temp file may never have been created. Losing it is not the failure
+      // worth reporting — the write is.
+    }
+    throw err
+  }
+}

package/src/harness.ts

@@ -25,6 +25,22 @@ description: Use when reading or changing anything on the Frontera platform from
 never out of date — read it instead of guessing, and instead of trusting this
 file for syntax.
 
+## Preflight: know which customer you are about to change
+
+\`\`\`bash
+frontera auth current --json
+\`\`\`
+
+The working directory selects the credential profile, so this is the only
+reliable answer to "which workspace am I in". It reports the profile, its API
+origin, the credential kind and where the selection came from — and no key
+material, ever.
+
+Exit 2 with \`PROFILE_NOT_SELECTED\` means this directory is bound to nothing.
+Do not work around it with \`--profile\`; report it, and offer
+\`frontera auth list\` and \`frontera auth use <profile>\`. Only the person can
+add a profile, because it needs their API key.
+
 ## Discover the surface as data
 
 \`\`\`bash
@@ -40,6 +56,52 @@ command with \`frontera <noun> <verb> --help --json\`.
 Prefer this over parsing \`--help\` text. Everything \`--help\` shows is in it,
 and it cannot drift, because both are projected from the same table.
 
+Two fields decide whether a call can work at all:
+
+- \`authLane\` — \`api-key\` reaches the command with \`sk-ws-\`/\`sk-org-\` or a
+  session. \`session\` reaches it with a session token ONLY: a valid key answers
+  401 there, which looks exactly like an expired credential. Run
+  \`frontera login\` before those.
+- \`available\` — \`false\` means the verb is named but unbuilt, and
+  \`unavailableReason\` says why. Pick another route rather than retrying.
+
+## Two kinds of credential
+
+\`frontera login\` accepts either, stores both the same way, and verifies them
+differently. One origin holds ONE key, so logging in again on the same
+\`--api-url\` replaces whatever was there.
+
+- **\`sk-ws-\`, a workspace key.** One workspace's slice. Reaches \`agent\`,
+  \`skill\`, \`plugin\`, \`capability\`, \`knowledge\`, \`pack\`, \`secret\`,
+  \`automation\`, \`app\`, and Blueprint READS through the granted slice.
+- **\`sk-org-\`, an organization key.** Reaches the organization-level Blueprint
+  draft, which no workspace key can — that draft is shared by every workspace,
+  so a workspace credential is refused there by design, not by oversight.
+  Needed for Blueprint AUTHORING (\`adopt\`, \`create\`, \`update\`, \`publish\`,
+  \`apply\`, \`pull\`, \`plan\`, \`validate\`, \`rollback\`) and for \`dataset\` and
+  \`source\`.
+
+A 403 on one of those nouns usually means the wrong KIND of key, not a missing
+permission. Rather than re-logging in each time, pass the other per call:
+
+\`\`\`bash
+FRONTERA_TOKEN=sk-org-… frontera blueprint pull
+FRONTERA_TOKEN=sk-org-… frontera source list
+\`\`\`
+
+An organization key carries a second rule worth knowing: its effective grant is
+its own permissions INTERSECTED with its creator's authority, re-resolved on
+every request. Demoting whoever minted it shrinks the key; removing them kills
+it.
+
+## Where the CLI ends
+
+Most of the platform has no CLI surface, on purpose — channels, workspaces,
+members, API keys, sheets, tasks and the evaluation suite are Console-only. The
+CLI says so by name: reaching for one of those nouns answers with what it is
+and where it lives, not "unknown command". Read that hint instead of guessing a
+synonym; there isn't one.
+
 ## The two shapes
 
 **Apps are projects.** \`frontera app …\` resolves the project by walking up from
@@ -61,7 +123,7 @@ Pass \`--json\` for machine-readable output. The contract:
 |------|---------|-----------|
 | 0 | success | continue |
 | 1 | transient or remote failure | retry, then report |
-| 2 | usage or input error | fix the command |
+| 2 | usage, input, or profile selection | fix the command |
 | 3 | conflict — someone changed it first | re-fetch, reapply, retry |
 | 4 | auth or permission | different credential, or ask an admin |
 
@@ -106,6 +168,72 @@ Three things about this are not visible from \`--help\`:
 Naming a directory is the normal case: unsupported types inside it are skipped
 and counted. Naming an unsupported file directly is an error and uploads nothing.
 
+## Proving a write landed
+
+A write verb reports what it SENT. Whether the thing is now readable is a
+different question, and on this platform the two come apart often enough that
+assuming they agree is how a broken binding ships:
+
+\`\`\`bash
+frontera knowledge search <base> "a question a user would ask"
+frontera blueprint query <apiName> --limit 5
+frontera blueprint instance <apiName> <pk>
+\`\`\`
+
+- **An empty \`knowledge search\` right after an upload is normal.** Ingestion is
+  asynchronous. Check \`frontera knowledge sources <base>\` — anything still
+  \`processing\` is not searchable yet, and that is not a failed upload.
+- **An empty \`blueprint query\` after a bind is not normal.** It usually means
+  the object type has no dataset binding on the ACTIVE release, not that the
+  table is empty. \`frontera blueprint get <apiName>\` shows the binding.
+- Reads resolve through the granted slice, so what comes back is exactly what an
+  app or agent sees at runtime. Anything absent here is absent for them too.
+
+\`--where\` takes \`<property>:<value>\` or \`<property>:<op>:<value>\` for one
+condition; pass a JSON where-node for anything with and/or in it, or
+\`--file\` a whole query document for unions and link traversals.
+
+## Configuring an agent
+
+\`\`\`bash
+frontera agent get <agent> --json > agent.json    # edit it
+frontera agent apply <agent> -f agent.json        # stages onto the draft
+frontera agent skill-attach <agent> <skillId>     # skill push does NOT bind
+frontera capability available <installId>         # what a plugin offers
+frontera capability grant <agent> <capabilityId>  # stages onto the draft
+frontera agent diff <agent>                       # what is staged vs live
+frontera agent publish <agent>                    # the only step that goes live
+\`\`\`
+
+- **Almost everything stages.** \`apply\`, \`capability grant\` and \`capability
+  revoke\` all write the DRAFT. A caller who grants, tests the live agent, sees
+  no change and grants again has skipped \`publish\` — that is the one step that
+  reaches the running agent.
+- **\`agent revert\` is the exception.** It publishes an old version as a new live
+  one immediately, with no draft in between.
+- **Granting a capability auto-binds its plugin install** if the agent did not
+  already hold it, so an install you never named appears in \`agent diff\`.
+- **An install set to \`read_only\` refuses every Action capability grant.** The
+  conflict names the install, not the capability; \`frontera plugin policy
+  <installId> --actions allow_all\` is the fix, and retrying the grant is not.
+- **Binding is not granting.** \`capability bind\` decides whose account the agent
+  reaches (\`agent_owned\` by default, \`--end-user\` for per-caller accounts) and
+  grants nothing on its own.
+
+## Connecting a database
+
+\`\`\`bash
+printf %s "$PGPASSWORD" | frontera source create -f ./source.json --password-from -
+frontera source list
+frontera dataset test-source <sourceId>
+\`\`\`
+
+The password is never in the definition file — a file carrying \`config.password\`
+is refused, not stripped. Everything else lives in the file so it can be
+committed. \`source update\`, \`source revise\` and \`source disable\` re-read the
+Source first and send its own concurrency tokens, so a write refused with exit 3
+means someone else changed it: re-read and retry, never force.
+
 ## Building an app
 
 \`\`\`bash
@@ -143,14 +271,29 @@ const AGENTS_MD = `# Frontera
 
 This directory works with the Frontera platform through the \`frontera\` CLI.
 
-Load the skill at \`.agents/skills/using-frontera-cli/SKILL.md\` before running
-any \`frontera\` command. It carries the workflow, the exit-code contract and the
-invariants that are not obvious from \`--help\`.
+Load the \`using-frontera-cli\` skill before running any \`frontera\` command. It
+carries the workflow, the exit-code contract and the invariants that are not
+obvious from \`--help\`. Codex finds it at
+\`.agents/skills/using-frontera-cli/SKILL.md\`; Claude Code finds the same bytes
+at \`.claude/skills/using-frontera-cli/SKILL.md\`.
+
+Before anything that writes, run \`frontera auth current --json\` — the working
+directory selects which customer's credential is in play.
 
 For syntax, run \`frontera help\` or \`frontera <noun> <verb> --help\` — help is
 generated from the command table and is always current.
 `
 
+/**
+ * Claude Code imports with \`@AGENTS.md\`.
+ *
+ * \`./AGENTS.md\` is a relative path Claude does not import — it reads as prose,
+ * so the contract silently never loads. One character, and the difference
+ * between a harness that works in both hosts and one that works in one.
+ */
+const CLAUDE_MD = `@AGENTS.md
+`
+
 export interface HarnessResult {
   written: string[]
   skipped: string[]
@@ -159,11 +302,19 @@ export interface HarnessResult {
 /**
  * Idempotent: an existing file is left alone unless `force`, so re-running
  * changes nothing and never clobbers a customised AGENTS.md.
+ *
+ * The same skill is written to BOTH host directories. Codex discovers
+ * `.agents/skills` and Claude Code discovers `.claude/skills`, and neither
+ * reads the other's — so a single tree is a harness that works in one host and
+ * silently does nothing in the other. `frontera kit vendor` is the fuller
+ * version of this, carrying the whole authoring kit rather than one skill.
  */
 export function writeHarnessFiles(dir: string, opts: { force?: boolean } = {}): HarnessResult {
   const files: Array<[string, string]> = [
     ['AGENTS.md', AGENTS_MD],
+    ['CLAUDE.md', CLAUDE_MD],
     [join('.agents', 'skills', 'using-frontera-cli', 'SKILL.md'), SKILL],
+    [join('.claude', 'skills', 'using-frontera-cli', 'SKILL.md'), SKILL],
   ]
 
   const written: string[] = []