@frontera-sdk/cli 1.44.1 → 1.45.0

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

@@ -111,6 +111,168 @@ const sources: Command = {
   },
 }
 
+const get: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'get',
+    args: [{ name: 'base', required: true, description: 'knowledge base name or id, from `frontera knowledge list`' }],
+    flags: {},
+    summary: 'Show one knowledge base — its settings and ingestion counts',
+    examples: ['frontera knowledge get product-docs', 'frontera knowledge get product-docs --json'],
+  },
+  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 base = await client.knowledgeBase(await resolveKnowledgeRef(client, ref))
+
+    return {
+      data: base,
+      // Whatever the route returns, flattened. Naming the fields here would
+      // print "?" for every one the service renames, and the embedding model
+      // and chunker are exactly the fields a caller comes to this verb to read.
+      text: table(
+        ['field', 'value'],
+        Object.entries(base).map(([k, v]) => [
+          k,
+          v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
+        ]),
+        [undefined, 70],
+      ),
+    }
+  },
+}
+
+/**
+ * Retrieval, which is the only thing that proves an upload landed.
+ *
+ * `knowledge upload` reports what it sent; `knowledge sources` reports the
+ * ingestion status per file. Neither answers the question a caller actually
+ * has — can the agent find this — because a source can reach `ready` with
+ * chunks that embed nothing useful. Searching is the check.
+ */
+const search: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'search',
+    args: [
+      { name: 'base', required: true, description: 'knowledge base name or id, from `frontera knowledge list`' },
+      { name: 'query', required: true, description: 'text to search for, as an agent would ask it' },
+    ],
+    flags: { 'top-k': 'string', threshold: 'string' },
+    summary: 'Search a knowledge base and show the chunks that come back',
+    examples: [
+      'frontera knowledge search product-docs "how do refunds work"',
+      'frontera knowledge search product-docs "refund policy" --top-k 3 --json',
+    ],
+  },
+  async run(ctx) {
+    const [ref, ...queryParts] = ctx.positional
+    if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+    // Joined rather than requiring quotes: an unquoted multi-word query is the
+    // normal typo, and refusing it teaches nothing a join cannot fix.
+    const query = queryParts.join(' ').trim()
+    if (!query) {
+      throw new UsageError('missing <query>', `frontera knowledge search ${ref} "what a user would ask"`)
+    }
+
+    const topKRaw = flagString(ctx, 'top-k')
+    const topK = topKRaw === undefined ? undefined : Number(topKRaw)
+    if (topK !== undefined && (!Number.isInteger(topK) || topK < 1)) {
+      throw new UsageError(`--top-k must be a positive whole number, not "${topKRaw}"`, 'try --top-k 5')
+    }
+    const thresholdRaw = flagString(ctx, 'threshold')
+    const threshold = thresholdRaw === undefined ? undefined : Number(thresholdRaw)
+    if (threshold !== undefined && Number.isNaN(threshold)) {
+      throw new UsageError(`--threshold must be a number, not "${thresholdRaw}"`, 'try --threshold 0.7')
+    }
+
+    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const baseId = await resolveKnowledgeRef(client, ref)
+    const result = await client.knowledgeSearch(baseId, {
+      query,
+      ...(topK === undefined ? {} : { topK }),
+      ...(threshold === undefined ? {} : { threshold }),
+    })
+
+    const chunks = result.results
+    if (chunks.length === 0) {
+      // The overwhelmingly common cause, and the one a caller cannot see from
+      // here: ingestion is asynchronous, so a base uploaded a minute ago is
+      // empty rather than broken.
+      return {
+        data: result,
+        text:
+          'No chunks matched.\n'
+          + `  If the upload was recent, check \`frontera knowledge sources ${ref}\` — a source\n`
+          + '  still `processing` is not searchable yet.\n'
+          // Stated the right way round: --threshold is a distance cutoff, so a
+          // LOW value is the restrictive one and 0 can never match.
+          + (threshold !== undefined
+            ? `  --threshold ${threshold} is a maximum cosine distance — raise it to widen the search.\n`
+            : '  The default cutoff is 0.9; pass a higher --threshold to widen the search.\n')
+          + '  Otherwise the corpus may simply not cover this.',
+      }
+    }
+
+    return {
+      data: result,
+      text: table(
+        ['score', 'source', 'chunk'],
+        chunks.map((c) => [
+          typeof c.score === 'number' ? c.score.toFixed(3) : String(c.score ?? ''),
+          String(c.fileName ?? c.sourceId ?? ''),
+          String(c.content ?? c.text ?? '').replace(/\s+/g, ' ').trim(),
+        ]),
+        [8, 30, 90],
+      ),
+    }
+  },
+}
+
+/**
+ * Re-run ingestion for a source that failed.
+ *
+ * `upload` exits 0 on a partial batch by design — one unreadable file does not
+ * end the run — so a failed source is normal and recovery has to be normal
+ * too. Until this verb the only route was the Console, which meant an
+ * unattended `knowledge upload` could not repair itself.
+ */
+const retry: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'retry',
+    args: [
+      { name: 'base', required: true, description: 'knowledge base name or id' },
+      { name: 'source', required: true, description: 'source id, from `frontera knowledge sources`' },
+    ],
+    flags: {},
+    summary: 'Re-run ingestion for one source that failed',
+    examples: ['frontera knowledge retry product-docs <sourceId>'],
+  },
+  async run(ctx) {
+    const [ref, sourceId] = ctx.positional
+    if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+    if (!sourceId) {
+      throw new UsageError('missing <source>', `frontera knowledge sources ${ref} — the id column`)
+    }
+
+    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const baseId = await resolveKnowledgeRef(client, ref)
+    const result = await client.retryKnowledgeSource(baseId, sourceId)
+
+    return {
+      data: result,
+      // Same asynchrony as upload: this queues the job, it does not finish it.
+      text:
+        `Re-queued ${sourceId}.\n`
+        + `  Ingestion is asynchronous — \`frontera knowledge sources ${ref}\` shows the outcome.\n`
+        + '  Retrying is additive and safe to repeat.',
+    }
+  },
+}
+
 const create: Command = {
   meta: {
     noun: 'knowledge',
@@ -381,7 +543,10 @@ const reserved: Command[] = (
 
 export const knowledgeCommands: Command[] = [
   list,
+  get,
   sources,
+  search,
+  retry,
   create,
   upload,
   attach,

package/src/commands/login.ts

@@ -1,41 +1,31 @@
-import { PlatformApi } from '../api/platform-api'
-import { writeStoredToken } from '../config'
+import { verifyKey } from '../auth-verify'
+import { ensureMigrated } from '../config'
+import { credentialStore } from '../credential-store'
 import { CliError, UsageError } from '../errors'
-import { readSecretValue } from '../secrets'
 import { canPrompt, promptSecret } from '../prompt'
-import type { Command } from './types'
+import { assertApiUrl, fingerprint, getProfile, putProfile } from '../profiles'
+import { readSecretValue } from '../secrets'
+import { flagBool, type Command } from './types'
 
 /**
- * Store a workspace key for an API origin.
+ * The old entry point, kept working.
  *
- * 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.
+ * `login` predates profiles and stored one token per API origin, which is the
+ * limitation profiles exist to remove. It survives for two minor releases as an
+ * alias that creates or replaces the `default` profile, because a machine that
+ * upgrades mid-task should not discover its setup command is gone.
  *
- * 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.
+ * Replacement is still explicit: an existing `default` needs `--force`, exactly
+ * as `auth add` does. Silently rebinding `default` was the old behaviour and it
+ * is the behaviour that made two customers impossible to hold at once.
  */
+const DEPRECATION = 'frontera login is deprecated — use `frontera auth add <profile> --api-url <origin>`'
+
 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
@@ -43,7 +33,11 @@ async function readToken(flags: Record<string, string | boolean>): Promise<strin
     return (process.env.FRONTERA_TOKEN ?? '').trim()
   }
 
-  return promptSecret('Workspace key (sk-ws-…): ')
+  // Names BOTH kinds, because the prompt is the only place most callers ever
+  // learn which are accepted. It read `Workspace key (sk-ws-…)` while the
+  // verification below has always taken an organization key too — so a holder
+  // of one had no way to discover that except by pasting it and being right.
+  return promptSecret('Frontera key (sk-ws-… or sk-org-…): ')
 }
 
 export const loginCommand: Command = {
@@ -51,91 +45,77 @@ export const loginCommand: Command = {
     noun: 'login',
     verb: '',
     args: [],
-    flags: { 'token-stdin': 'boolean', 'no-input': 'boolean' },
-    summary: 'Verify a workspace key and store it for this API origin',
+    flags: { 'token-stdin': 'boolean', 'no-input': 'boolean', force: 'boolean' },
+    // Keeps the upstream correction that this accepts an organization key too,
+    // inside the deprecation framing profiles introduce.
+    summary: 'Deprecated — store a workspace or organization key as `default`',
     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',
+      'frontera login --api-url http://localhost:4000 --force',
     ],
-    // It SUPPLIES a credential, so it must not require one to start.
     offline: true,
   },
 
   async run(ctx) {
+    ctx.output.note(DEPRECATION)
+
     if (!ctx.apiUrl) {
       throw new UsageError(
         'no API origin configured',
         'set FRONTERA_API_URL, or pass --api-url <origin>',
       )
     }
+    assertApiUrl(ctx.apiUrl)
 
-    const token = await readToken(ctx.flags)
+    await ensureMigrated(process.env)
 
+    const existing = getProfile('default')
+    if (existing && !flagBool(ctx, 'force')) {
+      throw new CliError('the `default` profile already exists', {
+        code: 'USAGE',
+        hint: 're-run with --force to replace it, or name a new one with `frontera auth add <profile>`',
+      })
+    }
+
+    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`',
       )
     }
-    // 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 Frontera key',
-        'workspace keys start with sk-ws- (Workspace settings → API Keys); ' +
-        'organization keys start with sk-org- (Settings → API keys)',
-      )
-    }
 
-    // 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})`,
-        })
-      }
-    }
+    const verified = await verifyKey(ctx.apiUrl, token)
+
+    const store = credentialStore()
+    await store.set('default', token)
 
-    writeStoredToken(ctx.apiUrl, token)
+    const now = new Date().toISOString()
+    putProfile('default', {
+      apiUrl: ctx.apiUrl,
+      credentialKind: verified.kind,
+      workspaceId: verified.workspaceId,
+      orgId: verified.orgId,
+      fingerprint: fingerprint(token),
+      createdAt: existing?.createdAt ?? now,
+      lastVerifiedAt: now,
+    })
 
     return {
       data: {
+        profile: 'default',
         apiUrl: ctx.apiUrl,
-        kind: isOrgKey ? 'organization' : 'workspace',
-        workspaceId: me?.workspaceId ?? null,
-        orgId: me?.orgId ?? null,
+        kind: verified.kind,
+        workspaceId: verified.workspaceId,
+        orgId: verified.orgId,
+        deprecated: true,
       },
-      // 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}`,
+      text: [
+        verified.kind === 'organization'
+          ? `Stored an organization key as profile default for ${ctx.apiUrl}\n  it authors this organization's Blueprint`
+          : `Stored a key as profile default for ${ctx.apiUrl}\n  workspace ${verified.workspaceId}`,
+        '  select it for this directory with `frontera auth use default`',
+      ].join('\n'),
     }
   },
 }