@frontera-sdk/cli 1.50.12 → 1.50.13

package/src/forge/touch-details.ts

@@ -0,0 +1,90 @@
+import type { ForgeArtifactTouchDetails, ForgeProject } from '@frontera-sdk/forge-contracts'
+
+import { PlatformApi } from '../api/platform-api'
+import { agentDraftChanges } from '../commands/agent/draft-changes'
+import { resolveAgentRef, type AgentRow } from '../commands/agent/resolve'
+import { resolveCredential } from '../config'
+import type { TouchInput } from './touches'
+
+/**
+ * What a touch changed, in more detail than the command line says.
+ *
+ * `frontera agent apply underwriter` tells the pane WHICH agent; it does not
+ * say which section. The draft the command staged does — it differs from
+ * live in exactly the sections the session edited — so after the command
+ * succeeds the daemon asks, the same way `frontera agent diff` would, and
+ * records the answer on the touch. The pane opens the page on that section.
+ *
+ * In-process, with the project's own profile: the daemon IS the CLI, so it
+ * resolves the credential the way any command run in that folder would and
+ * calls the platform directly. Nothing is spawned.
+ *
+ * Best-effort by design. A failure here (no profile, a key that cannot read
+ * drafts, the network) leaves the touch as it was — the pane still opens the
+ * right page, just at the top — and never touches the turn.
+ */
+export type TouchEnricher = (touch: TouchInput, project: ForgeProject) => Promise<ForgeArtifactTouchDetails | null>
+
+
+const TIMEOUT_MS = 15_000
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms)
+    timer.unref?.()
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (err) => {
+        clearTimeout(timer)
+        reject(err)
+      },
+    )
+  })
+}
+
+/**
+ * What this touch changed on its own. The draft diff is cumulative — after a
+ * prompt edit and then a knowledge binding it lists both — so the pane would
+ * point at the prompt twice. Subtracting what the previous touch on the same
+ * agent already reported leaves the new part. Same agent means same ref, or
+ * same resolved name: the CLI addresses by slug and MCP by uuid.
+ */
+export function touchDelta(
+  changed: readonly string[],
+  previous: { changed: readonly string[] } | null | undefined,
+): string[] {
+  if (!previous) return [...changed]
+  const before = new Set(previous.changed)
+  return changed.filter((k) => !before.has(k))
+}
+
+export const enrichTouch: TouchEnricher = async (touch, project) => {
+  // Any change to an agent that did not make it live may sit on the draft —
+  // from the CLI (`apply`, `skill-attach`) or from MCP (`update_agent`,
+  // `set_prompt`, `bind_skill`, …). No draft is a normal answer, not an error.
+  const { ref } = touch
+  const { profile } = project
+  if (touch.kind !== 'agent' || !ref || touch.live || !profile) return null
+
+  const run = async (): Promise<ForgeArtifactTouchDetails | null> => {
+    const credential = await resolveCredential({ profile }, { cwd: project.root })
+    // An organization key names no workspace, and agents live in one. The
+    // managed folder IS a workspace's folder, so the project knows which —
+    // the same thing `--workspace` would say on the command line.
+    const workspaceId = credential.workspaceId ?? project.workspaceId ?? undefined
+    const api = new PlatformApi(credential.apiUrl, credential.token, workspaceId)
+    const id = await resolveAgentRef(api, ref)
+    const [outcome, row] = await Promise.all([
+      agentDraftChanges(api, id),
+      // The name, for the pane header: an MCP tool addresses the agent by
+      // uuid, which is nothing a person recognises.
+      (api.agent(id) as Promise<AgentRow>).catch(() => null),
+    ])
+    const label = row?.name ?? row?.agentId
+    return { changed: outcome.hasDraft ? outcome.changed : [], ...(label ? { label } : {}) }
+  }
+  return withTimeout(run(), TIMEOUT_MS)
+}

package/src/forge/touches.ts

@@ -0,0 +1,412 @@
+import type { ForgeArtifactKind } from '@frontera-sdk/forge-contracts'
+import type { UIMessageChunk } from 'ai'
+
+/**
+ * Which platform artifacts a session changed, read off the `frontera`
+ * commands and platform MCP tools the host ran.
+ *
+ * Recorded live, as the run streams, into their own table: the pane follows
+ * the run as it happens, and the store answers a reload without re-reading
+ * every message. (The persisted message keeps tool parts on the normal path;
+ * only the malformed-stream fallback drops to text.)
+ *
+ * The signal is the COMMAND, not the files. The workspace folder's layout is
+ * whatever the session invented (`design/`, `ingest/`, `org-admin/` …), so a
+ * changed path says nothing reliable about which agent or object type it is.
+ * `frontera agent apply underwriter` says exactly: the noun, the verb, the
+ * slug. And the tool result says whether it worked.
+ *
+ * Two rules keep the preview pane honest:
+ *
+ *   - Only a command that did not fail records a touch. A `tool-output-error`
+ *     discards what the input promised.
+ *   - Only MUTATING verbs record one. The pane should not jump because the
+ *     session ran `frontera agent list` to look around.
+ */
+
+/** Runtime list; `ForgeArtifactKind` in forge-contracts is its type. */
+export const FORGE_ARTIFACT_KINDS = [
+  'agent',
+  'automation',
+  'app',
+  'blueprint',
+  'action',
+  'skill',
+  'source',
+  'dataset',
+  'knowledge',
+] as const satisfies readonly ForgeArtifactKind[]
+
+/**
+ * Verbs that change the artifact. Everything else on a noun — `list`, `get`,
+ * `diff`, `status`, `versions`, `catalog`, `query`, `preview`, `rows`,
+ * `search`, `runs`, `bindings` — is a read and is deliberately absent.
+ */
+export const TOUCHING_VERBS: Record<ForgeArtifactKind, readonly string[]> = {
+  agent: ['apply', 'create', 'publish', 'revert', 'discard', 'skill-attach', 'skill-detach'],
+  automation: ['deploy', 'promote', 'enable', 'disable', 'init', 'bind', 'unbind', 'run'],
+  app: ['deploy', 'promote', 'save', 'add'],
+  blueprint: ['apply', 'publish', 'create', 'update', 'delete', 'rename', 'rollback', 'bind', 'grant', 'adopt', 'editable'],
+  action: ['prepare', 'deploy', 'grant', 'review'],
+  skill: ['push', 'delete'],
+  source: ['create', 'update', 'revise', 'disable'],
+  dataset: ['create', 'upload', 'test-source'],
+  knowledge: ['create', 'attach', 'detach', 'upload', 'retry', 'delete'],
+}
+
+/** Verbs after which the artifact is LIVE, not merely changed. */
+const LIVE_VERBS: Partial<Record<ForgeArtifactKind, readonly string[]>> = {
+  agent: ['publish'],
+  automation: ['promote', 'enable'],
+  app: ['promote'],
+  blueprint: ['publish'],
+}
+
+/**
+ * Nouns the CLI registers under another name. `function` is what `--help`
+ * prints and what a host types; `automation` is the alias it still accepts.
+ */
+export const NOUN_ALIASES: Record<string, ForgeArtifactKind> = { function: 'automation' }
+
+/**
+ * Nouns whose verbs change an AGENT's draft: the touch belongs to the agent
+ * the positional names, not to a "capability" or a "pack" page. `frontera
+ * capability grant underwriter blueprint:read` stages the same section a
+ * later `agent apply` would report as `capabilities`.
+ */
+export const AGENT_PROXY_NOUNS: Record<string, { verbs: readonly string[]; agentAt: number }> = {
+  capability: { verbs: ['grant', 'revoke', 'bind', 'unbind'], agentAt: 0 },
+  pack: { verbs: ['apply', 'detach'], agentAt: 1 },
+}
+
+/**
+ * Verbs whose positional is a FILE, not the artifact's name. `frontera
+ * function deploy src/nightly.ts` names a source file; the slug comes from
+ * inside it. Recording the path as the ref would build a page for a path.
+ */
+const FILE_POSITIONAL_VERBS: Partial<Record<ForgeArtifactKind, readonly string[]>> = {
+  automation: ['deploy', 'init'],
+  skill: ['push'],
+  blueprint: ['create'],
+  // `app deploy` names nothing (the folder is the app); `app promote` names
+  // a VERSION. The app itself is the project's, which the pane knows.
+  app: ['deploy', 'promote', 'save', 'add'],
+}
+
+/**
+ * Blueprint verbs whose FIRST positional is the definition kind
+ * (`object-type`, `link-type`, `metric`, …) and whose second is the name:
+ * `frontera blueprint update object-type Loan`. The ref is the name.
+ */
+const BLUEPRINT_KINDED_VERBS = new Set(['update', 'delete', 'rename'])
+
+/**
+ * Flags that take no value. Any other `--flag` is assumed to consume the next
+ * token, so `--profile kata underwriter` yields the ref `underwriter` and not
+ * `kata`. Unknown boolean flags would swallow one token — a wrong ref, never a
+ * wrong noun — and the parser tests pin the ones the CLI actually has.
+ */
+export const BOOLEAN_FLAGS = new Set([
+  // Global.
+  'json', 'quiet', 'yes', 'help', 'force',
+  // Every `'boolean'` FlagSpec a command declares (`grep "'boolean'" src/commands`).
+  'accept-contract-change', 'accept-orphaned-knowledge', 'dry-run', 'end-user', 'no-activate',
+  'no-components', 'no-git', 'no-input', 'no-install', 'no-open', 'no-promote', 'no-wait',
+  'remove-apps', 'token-stdin', 'prune', 'dev', 'revoke', 'draft', 'check',
+])
+
+/**
+ * A shell redirection, attached (`>out.log`, `2>&1`, `>/dev/null`) or as an
+ * operator on its own (`>`, `>>`, `<`, `2>`, `&>`) whose target is the next
+ * token. Neither is an argument to `frontera`.
+ */
+const REDIRECTION = /^(\d*|&)?(>>?|<)(&\d+)?(.*)$/
+
+export interface ParsedFronteraCommand {
+  kind: ForgeArtifactKind
+  verb: string
+  ref: string | null
+  live: boolean
+}
+
+/**
+ * The platform's MCP server, which the daemon injects as `frontera`. A host
+ * that has it reaches for `update_agent` as readily as for the CLI, and the
+ * pane must follow either — the earlier session that used the CLI opened the
+ * pane, the later one that used MCP did not, for the same edit.
+ *
+ * Tool names are the catalogue's (`copilot-tool-catalog.ts` in the service):
+ * `mcp__frontera__<tool>`. Reads never touch; everything else touches the
+ * artifact its domain names, keyed by the id the tool takes.
+ */
+const MCP_PREFIX = 'mcp__frontera__'
+
+/**
+ * Tools that change nothing: a `list_`/`get_` segment anywhere in the name
+ * (`list_agents`, `data_list_sources`, `get_draft_diff`), or one of the named
+ * reads that call themselves something else. `touches-mcp-catalog.test.ts`
+ * holds this to the service's own risk classification.
+ */
+const MCP_READ_SEGMENT = /(^|_)(list|get)_/
+const MCP_READ_TOOLS = new Set([
+  'navigate', 'validate_case', 'test_case', 'test_agent', 'test_channel', 'verify_mcp_server',
+  'blueprint_aggregate', 'blueprint_query',
+])
+
+/** Tools whose success makes the artifact LIVE. */
+const MCP_LIVE_TOOLS = new Set(['publish_agent', 'publish_case', 'promote_platform_app_version'])
+
+/** Tools that remove the artifact: nothing left to preview. */
+const MCP_GONE_TOOLS = new Set(['delete_agent'])
+
+/**
+ * The artifact a tool changes, from its name. Anything on an agent — its
+ * prompts, skills, knowledge, packs, capabilities, MCP servers, channels — is
+ * a touch on THAT AGENT: the page the person wants is the agent's.
+ */
+function mcpArtifact(tool: string, input: Record<string, unknown>): { kind: ForgeArtifactKind; ref: string | null } | null {
+  const str = (key: string) => (typeof input[key] === 'string' && input[key] ? (input[key] as string) : null)
+  if (tool.startsWith('blueprint_')) {
+    // Most Blueprint tools name the OBJECT TYPE separately from the thing
+    // they add to it (`objectTypeApiName` + a property `apiName`); only the
+    // object-type tools carry the type as `apiName`.
+    const objectType = str('objectTypeApiName') ?? (/_object_type$/.test(tool) ? str('apiName') : null)
+    return { kind: 'blueprint', ref: objectType }
+  }
+  const agentId = str('agentId') ?? str('caseId')
+  if (agentId) return { kind: 'agent', ref: agentId }
+  if (tool === 'data_create_source') return { kind: 'source', ref: str('displayName') ?? str('name') }
+  if (tool === 'data_create_dataset') return { kind: 'dataset', ref: str('apiName') ?? str('name') }
+  if (tool === 'promote_platform_app_version') return { kind: 'app', ref: str('app') ?? str('slug') }
+  if (/_skill$/.test(tool)) return { kind: 'skill', ref: str('slug') ?? str('skillId') }
+  if (/knowledge/.test(tool)) return { kind: 'knowledge', ref: str('knowledgeBaseId') ?? str('name') }
+  if (/^create_(work_)?agent$|^duplicate_agent$/.test(tool)) return { kind: 'agent', ref: null }
+  return null
+}
+
+export function parseMcpTool(toolName: string, input: unknown): ParsedFronteraCommand | null {
+  if (!toolName.startsWith(MCP_PREFIX)) return null
+  const tool = toolName.slice(MCP_PREFIX.length)
+  if (MCP_READ_SEGMENT.test(tool) || MCP_READ_TOOLS.has(tool)) return null
+  if (MCP_GONE_TOOLS.has(tool)) return null
+  const record = input && typeof input === 'object' && !Array.isArray(input) ? (input as Record<string, unknown>) : {}
+  const artifact = mcpArtifact(tool, record)
+  if (!artifact) return null
+  return { kind: artifact.kind, verb: tool, ref: artifact.ref, live: MCP_LIVE_TOOLS.has(tool) }
+}
+
+/** What the tracker hands back for the store to persist. */
+export interface TouchInput extends ParsedFronteraCommand {
+  toolCallId: string
+}
+
+function isKind(value: string): value is ForgeArtifactKind {
+  return (FORGE_ARTIFACT_KINDS as readonly string[]).includes(value)
+}
+
+/**
+ * Split a shell line into the simple commands a `&&`, `||`, `;` or `|`
+ * separates, honouring quotes so a separator inside an argument stays put.
+ * Subshells and redirections are not modelled — a command that hides
+ * `frontera` behind one is simply not recognised, which fails safe.
+ */
+function splitCommands(line: string): string[] {
+  const out: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i]!
+    if (quote) {
+      current += ch
+      if (ch === quote) quote = null
+      else if (ch === '\\' && quote === '"' && i + 1 < line.length) current += line[++i]
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      current += ch
+      continue
+    }
+    if (ch === '\\' && i + 1 < line.length) {
+      current += ch + line[++i]
+      continue
+    }
+    const two = line.slice(i, i + 2)
+    if (two === '&&' || two === '||') {
+      out.push(current)
+      current = ''
+      i += 1
+      continue
+    }
+    if (ch === ';' || ch === '|' || ch === '\n') {
+      out.push(current)
+      current = ''
+      continue
+    }
+    current += ch
+  }
+  out.push(current)
+  return out.map((c) => c.trim()).filter((c) => c !== '')
+}
+
+/** Tokenize one simple command, dropping the quotes an argument was wrapped in. */
+function tokenize(command: string): string[] {
+  const tokens: string[] = []
+  let current = ''
+  let has = false
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i]!
+    if (quote) {
+      if (ch === quote) quote = null
+      else if (ch === '\\' && quote === '"' && i + 1 < command.length) current += command[++i]
+      else current += ch
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      has = true
+      continue
+    }
+    if (ch === '\\' && i + 1 < command.length) {
+      current += command[++i]
+      has = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t') {
+      if (has) tokens.push(current)
+      current = ''
+      has = false
+      continue
+    }
+    current += ch
+    has = true
+  }
+  if (has) tokens.push(current)
+  return tokens
+}
+
+/**
+ * The index of the first token AFTER the `frontera` invocation, or -1.
+ * Accepts `frontera`, a path ending in `/frontera`, and `bunx`/`npx` in front
+ * of either `frontera` or the published package name (with or without a
+ * version). Leading `NAME=value` assignments are skipped.
+ */
+function invocationEnd(tokens: string[]): number {
+  let i = 0
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]!)) i += 1
+  const head = tokens[i]
+  if (!head) return -1
+  const isFrontera = (t: string) => t === 'frontera' || t.endsWith('/frontera')
+  if (isFrontera(head)) return i + 1
+  if (head === 'bunx' || head === 'npx') {
+    const next = tokens[i + 1]
+    if (!next) return -1
+    if (isFrontera(next) || next.startsWith('@frontera-sdk/cli')) return i + 2
+  }
+  return -1
+}
+
+/**
+ * Parse every `frontera` invocation on a shell line into the touches it
+ * would record if it succeeded. Non-`frontera` commands, read verbs and
+ * unknown nouns yield nothing.
+ */
+export function parseFronteraCommands(line: string): ParsedFronteraCommand[] {
+  const out: ParsedFronteraCommand[] = []
+  for (const command of splitCommands(line)) {
+    const tokens = tokenize(command)
+    const start = invocationEnd(tokens)
+    if (start < 0) continue
+
+    // Positionals after the invocation, with flags (and their values) and
+    // shell redirections removed.
+    const positionals: string[] = []
+    const flags = new Set<string>()
+    for (let i = start; i < tokens.length; i += 1) {
+      const token = tokens[i]!
+      if (token === '--') {
+        positionals.push(...tokens.slice(i + 1).filter((t) => !REDIRECTION.test(t)))
+        break
+      }
+      const redirect = REDIRECTION.exec(token)
+      if (redirect) {
+        // A bare operator takes the next token as its target.
+        if (redirect[4] === '' && !redirect[3]) i += 1
+        continue
+      }
+      if (token.startsWith('--')) {
+        const eq = token.indexOf('=')
+        const name = eq >= 0 ? token.slice(2, eq) : token.slice(2)
+        flags.add(name)
+        if (eq < 0 && !BOOLEAN_FLAGS.has(name) && i + 1 < tokens.length && !tokens[i + 1]!.startsWith('-')) i += 1
+        continue
+      }
+      if (token.startsWith('-')) continue
+      positionals.push(token)
+    }
+
+    const [noun, verb, ...rest] = positionals
+    if (!noun || !verb) continue
+
+    const proxy = AGENT_PROXY_NOUNS[noun]
+    if (proxy) {
+      if (!proxy.verbs.includes(verb)) continue
+      out.push({ kind: 'agent', verb: `${noun}-${verb}`, ref: rest[proxy.agentAt] ?? null, live: false })
+      continue
+    }
+
+    const kind = NOUN_ALIASES[noun] ?? (isKind(noun) ? noun : null)
+    if (!kind) continue
+    if (!TOUCHING_VERBS[kind].includes(verb)) continue
+    const ref = (FILE_POSITIONAL_VERBS[kind] ?? []).includes(verb)
+      ? null
+      : kind === 'blueprint' && BLUEPRINT_KINDED_VERBS.has(verb)
+        ? (rest[1] ?? null)
+        : (rest[0] ?? null)
+    const live =
+      (LIVE_VERBS[kind] ?? []).includes(verb)
+      // `app deploy` and `function deploy` build and promote in one act
+      // unless told not to.
+      || ((kind === 'app' || kind === 'automation') && verb === 'deploy' && !flags.has('no-promote'))
+    out.push({ kind, verb, ref, live })
+  }
+  return out
+}
+
+/**
+ * Feed it the run's chunks; it answers with the touches that just became
+ * certain. A `Bash` input holding a `frontera` command is only a CANDIDATE
+ * until its result arrives: success records it, an error discards it.
+ */
+export class TouchTracker {
+  private readonly pending = new Map<string, ParsedFronteraCommand[]>()
+
+  observe(chunk: UIMessageChunk): TouchInput[] {
+    switch (chunk.type) {
+      case 'tool-input-available': {
+        if (chunk.toolName === 'Bash') {
+          const input = chunk.input as { command?: unknown } | undefined
+          if (!input || typeof input.command !== 'string') return []
+          const parsed = parseFronteraCommands(input.command)
+          if (parsed.length > 0) this.pending.set(chunk.toolCallId, parsed)
+          return []
+        }
+        const mcp = parseMcpTool(chunk.toolName, chunk.input)
+        if (mcp) this.pending.set(chunk.toolCallId, [mcp])
+        return []
+      }
+      case 'tool-output-available': {
+        const parsed = this.pending.get(chunk.toolCallId)
+        if (!parsed) return []
+        this.pending.delete(chunk.toolCallId)
+        return parsed.map((p) => ({ ...p, toolCallId: chunk.toolCallId }))
+      }
+      case 'tool-output-error':
+        this.pending.delete(chunk.toolCallId)
+        return []
+      default:
+        return []
+    }
+  }
+}

package/src/project-context.ts

@@ -50,7 +50,7 @@ export function contextPath(root: string): string {
   return join(root, CONTEXT_DIR, CONTEXT_FILE)
 }
 
-function readContextAt(root: string, env: Env): FoundContext | null {
+export function readContextAt(root: string, env: Env): FoundContext | null {
   const path = contextPath(root)
   if (!existsSync(path)) return null