@frontera-sdk/cli 1.44.0 → 1.45.0

package/src/commands/auth/add.ts

@@ -0,0 +1,145 @@
+import { verifyKey } from '../../auth-verify'
+import { ensureMigrated } from '../../config'
+import { credentialStore } from '../../credential-store'
+import { CliError, UsageError } from '../../errors'
+import { canPrompt, promptConfirm, promptSecret } from '../../prompt'
+import {
+  assertApiUrl,
+  assertOriginMatches,
+  assertProfileName,
+  fingerprint,
+  getProfile,
+  putProfile,
+} from '../../profiles'
+import { readSecretValue } from '../../secrets'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
+
+/**
+ * Where the key comes from, in the order a caller would expect.
+ *
+ * There is no `--token`. A secret in a flag lands in process listings and shell
+ * history, and a CLI that offers the option will have it used — so the only
+ * routes in are stdin, a no-echo prompt on a real terminal, and the
+ * environment. An agent's stdin is a pipe or /dev/null, so an agent lands in
+ * the stdin branch or the error, never on a prompt that would hang.
+ */
+async function readKey(ctx: CommandContext): Promise<string> {
+  const from = flagString(ctx, 'from')
+  if (from) return (await readSecretValue(from)).trim()
+
+  const noInput = flagBool(ctx, 'no-input')
+  if (!noInput && canPrompt()) return promptSecret('Frontera API key (sk-ws-… or sk-org-…): ')
+
+  const fromEnv = (process.env.FRONTERA_TOKEN ?? '').trim()
+  if (fromEnv) return fromEnv
+
+  throw new UsageError(
+    'no key supplied',
+    'pipe it in with `--from -`, point at a file with `--from ./key.txt`, '
+    + 'or run this in a terminal to be asked for it',
+  )
+}
+
+export const authAdd: Command = {
+  meta: {
+    noun: 'auth',
+    verb: 'add',
+    args: [{ name: 'profile', required: true, description: 'name for this credential, e.g. acme-prod' }],
+    flags: { from: 'string', force: 'boolean', 'no-input': 'boolean' },
+    summary: 'Verify an API key and store it under a profile name',
+    examples: [
+      'frontera auth add acme-prod --api-url https://api.frontera.test --from -',
+      'frontera --api-url https://api.frontera.test auth add globex-dev --from -',
+      'frontera auth add acme-prod --api-url https://api.frontera.test --force',
+    ],
+    // It SUPPLIES a credential, so it must not require one to start.
+    offline: true,
+  },
+
+  async run(ctx) {
+    const [name] = ctx.positional
+    if (!name) throw new UsageError('no profile name given', 'run `frontera auth add <profile> --api-url <origin>`')
+    assertProfileName(name)
+
+    await ensureMigrated(process.env)
+
+    const existing = getProfile(name)
+    const supplied = flagString(ctx, 'api-url') ?? process.env.FRONTERA_API_URL
+    if (existing && supplied) assertOriginMatches(name, existing.apiUrl, supplied)
+
+    const apiUrl = supplied ?? existing?.apiUrl
+    if (!apiUrl) {
+      throw new UsageError(
+        'no API origin given',
+        'pass --api-url <origin>, or set FRONTERA_API_URL — a key is only valid at the deployment that issued it',
+      )
+    }
+    assertApiUrl(apiUrl)
+
+    /**
+     * Replacing is a decision, not a default.
+     *
+     * An agent gets a usage error rather than a prompt: it cannot answer one,
+     * and silently overwriting a working customer credential because a command
+     * was re-run is not recoverable — the previous key is not stored anywhere
+     * else.
+     */
+    if (existing && !flagBool(ctx, 'force')) {
+      const confirmed =
+        canPrompt() && !flagBool(ctx, 'no-input')
+          ? await promptConfirm(`Replace the key stored for ${name} (${existing.fingerprint})?`)
+          : false
+      if (!confirmed) {
+        throw new CliError(`profile "${name}" already exists`, {
+          code: 'USAGE',
+          hint: `re-run with --force to replace its key (${existing.fingerprint}), or pick another name`,
+        })
+      }
+    }
+
+    const token = await readKey(ctx)
+    if (!token) {
+      throw new UsageError('the key was empty', 'check what you piped in — a key starts with sk-ws- or sk-org-')
+    }
+
+    const verified = await verifyKey(apiUrl, token)
+
+    const store = credentialStore()
+    await store.set(name, token)
+
+    const now = new Date().toISOString()
+    putProfile(name, {
+      apiUrl,
+      credentialKind: verified.kind,
+      workspaceId: verified.workspaceId,
+      orgId: verified.orgId,
+      fingerprint: fingerprint(token),
+      createdAt: existing?.createdAt ?? now,
+      lastVerifiedAt: now,
+    })
+
+    const data = {
+      profile: name,
+      apiUrl,
+      credentialKind: verified.kind,
+      workspaceId: verified.workspaceId,
+      orgId: verified.orgId,
+      fingerprint: fingerprint(token),
+      credentialSource: store.kind,
+      replaced: Boolean(existing),
+    }
+
+    const scope = verified.kind === 'organization'
+      ? "it authors this organization's Blueprint"
+      : `workspace ${verified.workspaceId}`
+
+    return {
+      data,
+      text: [
+        `${existing ? 'Replaced' : 'Stored'} profile ${name} (${data.fingerprint})`,
+        `  ${apiUrl} — ${scope}`,
+        `  select it here with \`frontera auth use ${name}\``,
+      ].join('\n'),
+    }
+  },
+}

package/src/commands/auth/current.ts

@@ -0,0 +1,82 @@
+import { credentialStore } from '../../credential-store'
+import { describeSelection } from '../../config'
+import { CliError } from '../../errors'
+import { listProfiles } from '../../profiles'
+import { flagString, type Command } from '../types'
+
+/**
+ * The preflight every Frontera skill runs first.
+ *
+ * "Which key is this command about to use" has to be answerable without
+ * running a mutation to find out, and answerable as DATA — an agent about to
+ * deploy to a customer cannot be asked to parse a sentence. So this reports
+ * the resolved profile AND where each part of the resolution came from.
+ *
+ * It reads no secret bytes. It reports only whether one is present, which is
+ * the part that changes what happens next.
+ */
+export const authCurrent: Command = {
+  meta: {
+    noun: 'auth',
+    verb: 'current',
+    args: [],
+    flags: {},
+    summary: 'Show the profile, origin and scope this directory resolves to',
+    examples: ['frontera auth current', 'frontera auth current --json'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const { selection, metadata } = await describeSelection(
+      { profile: flagString(ctx, 'profile') },
+      { cwd: ctx.cwd },
+    )
+
+    if (!selection.profile || !metadata) {
+      const known = listProfiles().map((p) => p.name)
+      throw new CliError('no Frontera profile is selected for this directory', {
+        code: 'PROFILE_NOT_SELECTED',
+        hint: known.length
+          ? `run \`frontera auth use <profile>\` here — you have: ${known.join(', ')}`
+          : 'run `frontera auth add <profile> --api-url <origin>`, then `frontera auth use <profile>`',
+      })
+    }
+
+    const store = credentialStore()
+    const located = await store.locate(selection.profile)
+
+    const envToken = Boolean(process.env.FRONTERA_TOKEN?.trim())
+    const suppliedOrigin = flagString(ctx, 'api-url') ?? process.env.FRONTERA_API_URL
+
+    const data = {
+      profile: selection.profile,
+      profileSource: selection.source,
+      ...(selection.path ? { profileSourcePath: selection.path } : {}),
+      apiUrl: metadata.apiUrl,
+      apiUrlSource: suppliedOrigin ? (flagString(ctx, 'api-url') ? 'flag' : 'environment') : 'profile',
+      credentialSource: envToken ? 'environment' : (located?.source ?? null),
+      credentialKind: metadata.credentialKind,
+      workspaceId: metadata.workspaceId,
+      orgId: metadata.orgId,
+      fingerprint: metadata.fingerprint,
+      lastVerifiedAt: metadata.lastVerifiedAt,
+      hasSecret: located !== null,
+    }
+
+    const where = selection.source === 'directory' ? ` (from ${selection.path})` : ` (from ${selection.source})`
+    const scope = metadata.credentialKind === 'organization'
+      ? "organization Blueprint author"
+      : `workspace ${metadata.workspaceId ?? 'unknown'}`
+
+    const lines = [
+      `${selection.profile}${where}`,
+      `  ${metadata.apiUrl} — ${scope}`,
+      `  key ${data.hasSecret ? metadata.fingerprint : 'MISSING — run `frontera auth add ' + selection.profile + '`'}`,
+    ]
+    if (envToken) {
+      lines.push('  FRONTERA_TOKEN is set and takes precedence over this profile’s stored key')
+    }
+
+    return { data, text: lines.join('\n') }
+  },
+}

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

@@ -0,0 +1,16 @@
+import { authAdd } from './add'
+import { authCurrent } from './current'
+import { authList } from './list'
+import { authRemove } from './remove'
+import { authUse } from './use'
+import { authVerify } from './verify'
+import type { Command } from '../types'
+
+export const authCommands: readonly Command[] = [
+  authAdd,
+  authList,
+  authCurrent,
+  authUse,
+  authVerify,
+  authRemove,
+]

package/src/commands/auth/list.ts

@@ -0,0 +1,71 @@
+import { ensureMigrated } from '../../config'
+import { credentialStore } from '../../credential-store'
+import { listProfiles } from '../../profiles'
+import { findContext } from '../../project-context'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * Every profile on this machine, with no key bytes anywhere in the output.
+ *
+ * The fingerprint is what makes the listing useful without being dangerous: it
+ * answers "is this the key I rotated on Tuesday" by eye, and answers nothing
+ * else.
+ */
+export const authList: Command = {
+  meta: {
+    noun: 'auth',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List the credential profiles stored on this machine',
+    examples: ['frontera auth list', 'frontera auth list --json'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    await ensureMigrated(process.env)
+
+    const store = credentialStore()
+    const selected = findContext(ctx.cwd)?.profile ?? null
+
+    const rows = []
+    for (const { name, profile } of listProfiles()) {
+      rows.push({
+        profile: name,
+        apiUrl: profile.apiUrl,
+        credentialKind: profile.credentialKind,
+        workspaceId: profile.workspaceId,
+        orgId: profile.orgId,
+        fingerprint: profile.fingerprint,
+        lastVerifiedAt: profile.lastVerifiedAt,
+        // A profile whose secret has been removed from the OS store is the one
+        // state that looks fine in metadata and fails on the next command.
+        hasSecret: (await store.get(name)) !== null,
+        selectedHere: name === selected,
+      })
+    }
+
+    if (rows.length === 0) {
+      return {
+        data: { profiles: [] },
+        text: 'No profiles yet.\n  frontera auth add <profile> --api-url <origin>',
+      }
+    }
+
+    const text = table(
+      ['', 'profile', 'origin', 'kind', 'key'],
+      rows.map((r) => [
+        // The directory's selection, marked where a reader is already looking,
+        // rather than in a separate line they have to correlate.
+        r.selectedHere ? '*' : ' ',
+        r.profile,
+        r.apiUrl,
+        r.credentialKind,
+        r.hasSecret ? r.fingerprint : 'MISSING',
+      ]),
+    )
+
+    return { data: { profiles: rows, selectedHere: selected }, text }
+  },
+}

package/src/commands/auth/remove.ts

@@ -0,0 +1,80 @@
+import { ensureMigrated } from '../../config'
+import { credentialStore } from '../../credential-store'
+import { CliError, UsageError } from '../../errors'
+import { assertProfileName, deleteProfile, requireProfile } from '../../profiles'
+import { canPrompt, promptConfirm } from '../../prompt'
+import { forgetBinding } from '../../binding-registry'
+import { findContext } from '../../project-context'
+import { flagBool, type Command } from '../types'
+
+/**
+ * Delete a profile's key and its metadata.
+ *
+ * Confirmation is required because the key is not stored anywhere else — this
+ * is the last copy, and re-adding it means going back to the platform for a new
+ * one. `--yes` is the non-interactive form, so an agent has an explicit way to
+ * say it meant this.
+ *
+ * Directory bindings that pointed at it are REPORTED rather than rewritten. A
+ * binding is a file in someone's repository; leaving it and naming it is
+ * honest, and rewriting files across a filesystem to tidy up after a delete is
+ * not a thing a credential command should do.
+ */
+export const authRemove: Command = {
+  meta: {
+    noun: 'auth',
+    verb: 'remove',
+    args: [{ name: 'profile', required: true, description: 'profile to delete' }],
+    flags: {},
+    summary: 'Delete a profile and its stored key',
+    examples: ['frontera auth remove globex-dev --yes'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const [name] = ctx.positional
+    if (!name) throw new UsageError('no profile name given', 'run `frontera auth remove <profile> --yes`')
+    assertProfileName(name)
+
+    await ensureMigrated(process.env)
+    const metadata = requireProfile(name)
+
+    if (!flagBool(ctx, 'yes')) {
+      const confirmed = canPrompt()
+        ? await promptConfirm(`Delete ${name} (${metadata.fingerprint}) and its stored key?`)
+        : false
+      if (!confirmed) {
+        throw new CliError(`removing "${name}" deletes the only copy of that key`, {
+          code: 'USAGE',
+          hint: `re-run with --yes to confirm — the key (${metadata.fingerprint}) cannot be recovered afterwards`,
+        })
+      }
+    }
+
+    const store = credentialStore()
+    await store.delete(name)
+    deleteProfile(name)
+
+    // Only the ancestry of the current directory is inspectable. Claiming to
+    // have found every binding on the machine would be a claim this cannot
+    // support, so it reports the one it can see.
+    const bound = findContext(ctx.cwd)
+    const danglingHere = bound?.profile === name ? bound.path : null
+    // The binding named a profile that no longer exists, so the record that
+    // made it trusted is now meaningless — drop it rather than leave it to
+    // vouch for a future profile that happens to reuse the name.
+    if (bound?.profile === name) forgetBinding(bound.root)
+
+    return {
+      data: {
+        profile: name,
+        apiUrl: metadata.apiUrl,
+        fingerprint: metadata.fingerprint,
+        danglingContext: danglingHere,
+      },
+      text: danglingHere
+        ? `Removed ${name}\n  ${danglingHere} still selects it — run \`frontera auth use <profile>\` there`
+        : `Removed ${name}`,
+    }
+  },
+}

package/src/commands/auth/use.ts

@@ -0,0 +1,84 @@
+import { relative } from 'node:path'
+
+import { ensureMigrated } from '../../config'
+import { credentialStore } from '../../credential-store'
+import { CliError, UsageError } from '../../errors'
+import { assertProfileName, requireProfile } from '../../profiles'
+import { ensureGitignored, resolveBindingRoot, writeContext } from '../../project-context'
+import { flagString, type Command } from '../types'
+
+/**
+ * Bind a directory tree to a profile.
+ *
+ * No initialization is required and none is created: the binding root is the
+ * nearest Frontera project, else the Git root, else the working directory, so
+ * this works on the first command in a bare customer folder. `--dir` binds that
+ * exact directory and searches no further.
+ *
+ * It writes no token and makes no request — `auth add` already verified the
+ * key, and `auth verify` exists for an explicit freshness check. What it writes
+ * is a NAME, which is why a nested customer project can override its parent
+ * without either one being able to redirect a key to another deployment.
+ */
+export const authUse: Command = {
+  meta: {
+    noun: 'auth',
+    verb: 'use',
+    args: [{ name: 'profile', required: true, description: 'profile to select for this directory tree' }],
+    flags: { dir: 'string' },
+    summary: 'Select a profile for this directory and everything under it',
+    examples: [
+      'frontera auth use acme-prod',
+      'frontera auth use globex-dev --dir ~/Customers/globex',
+    ],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const [name] = ctx.positional
+    if (!name) throw new UsageError('no profile name given', 'run `frontera auth use <profile>` — see `frontera auth list`')
+    assertProfileName(name)
+
+    await ensureMigrated(process.env)
+    const metadata = requireProfile(name)
+
+    // A selection pointing at a profile with no key is a binding that fails on
+    // the next command with a confusing error. Catch it here, where the fix is
+    // one command away.
+    const store = credentialStore()
+    if ((await store.get(name)) === null) {
+      throw new CliError(`profile "${name}" has no stored key`, {
+        code: 'PROFILE_SECRET_MISSING',
+        hint: `re-add it with \`frontera auth add ${name} --api-url ${metadata.apiUrl}\``,
+      })
+    }
+
+    const { root, source } = resolveBindingRoot(ctx.cwd, flagString(ctx, 'dir'))
+    const path = writeContext(root, name)
+    const gitignore = ensureGitignored(root)
+
+    const scope = metadata.credentialKind === 'organization'
+      ? "organization Blueprint author"
+      : `workspace ${metadata.workspaceId ?? 'unknown'}`
+
+    return {
+      data: {
+        profile: name,
+        root,
+        rootSource: source,
+        contextPath: path,
+        gitignore,
+        apiUrl: metadata.apiUrl,
+        credentialKind: metadata.credentialKind,
+        workspaceId: metadata.workspaceId,
+        orgId: metadata.orgId,
+        fingerprint: metadata.fingerprint,
+      },
+      text: [
+        `Selected ${name} for ${root}`,
+        `  ${metadata.apiUrl} — ${scope}`,
+        `  wrote ${relative(root, path) || path}${gitignore === 'present' ? '' : `, ${gitignore} .gitignore entry`}`,
+      ].join('\n'),
+    }
+  },
+}

package/src/commands/auth/verify.ts

@@ -0,0 +1,93 @@
+import { verifyKey } from '../../auth-verify'
+import { describeSelection } from '../../config'
+import { credentialStore } from '../../credential-store'
+import { CliError } from '../../errors'
+import { assertApiUrl, assertOriginMatches, assertProfileName, putProfile, requireProfile } from '../../profiles'
+import { flagString, type Command } from '../types'
+
+/**
+ * Ask the service whether the key still works.
+ *
+ * Stored scope metadata is descriptive and can go stale — a key is revoked, a
+ * workspace is renamed, an organization grant is withdrawn — and nothing about
+ * a local file would show it. This is the explicit freshness check, and it
+ * refreshes `lastVerifiedAt` and the recorded scope on success.
+ *
+ * The service remains authoritative regardless: a passing verify is a statement
+ * about this moment, not a grant.
+ */
+export const authVerify: Command = {
+  meta: {
+    noun: 'auth',
+    verb: 'verify',
+    args: [{ name: 'profile', required: false, description: "profile to check (default: this directory's)" }],
+    flags: {},
+    summary: 'Check a stored key against its API origin and refresh its scope',
+    examples: ['frontera auth verify', 'frontera auth verify acme-prod --json'],
+    offline: true,
+  },
+
+  async run(ctx) {
+    const [named] = ctx.positional
+    if (named) assertProfileName(named)
+
+    const { selection, metadata: selected } = await describeSelection(
+      { profile: named ?? flagString(ctx, 'profile') },
+      { cwd: ctx.cwd },
+    )
+
+    const name = named ?? selection.profile
+    if (!name) {
+      throw new CliError('no profile to verify', {
+        code: 'PROFILE_NOT_SELECTED',
+        hint: 'name one — `frontera auth verify <profile>` — or select one with `frontera auth use <profile>`',
+      })
+    }
+
+    const metadata = selected ?? requireProfile(name)
+
+    const supplied = flagString(ctx, 'api-url')
+    if (supplied) {
+      assertApiUrl(supplied)
+      assertOriginMatches(name, metadata.apiUrl, supplied)
+    }
+
+    const store = credentialStore()
+    const token = await store.get(name)
+    if (!token) {
+      throw new CliError(`profile "${name}" has no stored key`, {
+        code: 'PROFILE_SECRET_MISSING',
+        hint: `re-add it with \`frontera auth add ${name} --api-url ${metadata.apiUrl}\``,
+      })
+    }
+
+    const verified = await verifyKey(metadata.apiUrl, token)
+    const now = new Date().toISOString()
+
+    putProfile(name, {
+      ...metadata,
+      credentialKind: verified.kind,
+      workspaceId: verified.workspaceId ?? metadata.workspaceId,
+      orgId: verified.orgId ?? metadata.orgId,
+      lastVerifiedAt: now,
+    })
+
+    const scope = verified.kind === 'organization'
+      ? "organization Blueprint author"
+      : `workspace ${verified.workspaceId}`
+
+    return {
+      data: {
+        profile: name,
+        apiUrl: metadata.apiUrl,
+        credentialKind: verified.kind,
+        workspaceId: verified.workspaceId ?? metadata.workspaceId,
+        orgId: verified.orgId ?? metadata.orgId,
+        fingerprint: metadata.fingerprint,
+        lastVerifiedAt: now,
+        valid: true,
+      },
+      text: `${name} is valid at ${metadata.apiUrl}\n  ${scope}\n  key ${metadata.fingerprint}`,
+    }
+  },
+}

package/src/commands/automation/run.ts

@@ -339,17 +339,56 @@ export const automationRuns: Command = {
   meta: {
     noun: 'automation',
     verb: 'runs',
-    args: [{ name: 'slug', required: true, description: 'automation slug' }],
+    args: [
+      { name: 'slug', required: true, description: 'automation slug' },
+      {
+        name: 'runId',
+        required: false,
+        description: 'one run to open, with its step trail; omit to list recent runs',
+      },
+    ],
     flags: { dev: 'boolean' },
-    summary: 'List recent runs, newest first, with what each one returned',
+    summary: 'List recent runs, newest first — or open one run and its steps',
     examples: [
       'frontera automation runs daily-digest',
       'frontera automation runs daily-digest --dev',
+      'frontera automation runs daily-digest <runId> --json',
     ],
   },
 
   async run(ctx) {
     const slug = requireSlug(ctx)
+
+    // A run id turns the listing into a detail view rather than needing a
+    // second verb. The list is where a failure is noticed and the steps are
+    // where it is explained, so the two belong under one name.
+    const runId = ctx.positional[1]
+    if (runId) {
+      const api = new AutomationApi(ctx.apiUrl, ctx.token)
+      const [detail, steps] = await Promise.all([
+        api.runById(slug, runId),
+        // A run that failed before its first step has none, and that is a fact
+        // about the run rather than an error — so a failure to read the trail
+        // must not lose the run it belongs to.
+        api.runSteps(runId).catch(() => [] as Awaited<ReturnType<typeof api.runSteps>>),
+      ])
+
+      const trail = steps.length === 0
+        ? '  (no steps recorded — the run failed before the first one, or made none)'
+        : steps
+            .map((s) => {
+              const duration = s.durationMs === null ? '' : `  ${s.durationMs}ms`
+              return `  ${String(s.seq).padStart(3)}  ${s.status.padEnd(9)}`
+                + `  ${s.stepName ?? s.label}${duration}`
+            })
+            .join('\n')
+
+      return {
+        data: { run: detail, steps },
+        text: `${describeRun(detail)}\n\nSteps\n${trail}`,
+      }
+    }
+
     // The two histories are separate rows and the route defaults to live, so
     // without this a dev run is invisible from the CLI — the same blind spot
     // that made `run --dev` wait out its timeout.