@frontera-sdk/cli 0.1.0 → 1.43.6

package/src/dev-env.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resolveCredential } from './config'
+
+/**
+ * Give a project the credential the machine already holds.
+ *
+ * ## The failure this closes
+ *
+ * The dev host reads `VITE_FRONTERA_TOKEN` and warns, accurately, when it is
+ * missing:
+ *
+ *     [dev-host] No VITE_FRONTERA_TOKEN — the app will mount but platform
+ *     reads will 401.
+ *
+ * The credential is on the machine — `frontera login` stores it, and the
+ * Computer is provisioned with it before a turn starts. The dev host wants
+ * exactly it. Nothing joined the two for a project created by `app init`, so
+ * every app built from scratch rendered empty, and the agent looking at it
+ * reported the 401s as "normal, not a bug in the code" — which is true of the
+ * code and false of the situation.
+ *
+ * That is worth stating plainly, because it defeats the check that was added
+ * to catch it: an agent that renders its own dashboard and finds no numbers on
+ * it cannot see that one of the numbers is wrong.
+ *
+ * ## Why Vite needs its own file
+ *
+ * Vite exposes only `VITE_`-prefixed variables to client code, and reads them
+ * from the project's own `.env.local` — it does not inherit a shell profile,
+ * and the dev server is started by a non-login shell. So a project-local file
+ * is the mechanism, not a convenience.
+ *
+ * ## Why this never fails a command
+ *
+ * `app init` is `offline: true` and must stay so: scaffolding has to work
+ * before anyone has logged in. Everything here is best-effort — resolve, and
+ * on any failure write nothing and say nothing. A scaffold that refused
+ * because there was no credential would break the one case the offline flag
+ * exists for.
+ */
+
+export const DEV_ENV_FILE = '.env.local'
+
+export interface DevEnvResult {
+  /** False when there was no credential, or the file already existed. */
+  written: boolean
+  /** Why not, for a caller that wants to say something. */
+  reason?: 'no-credential' | 'exists' | 'failed'
+}
+
+interface DevEnvDeps {
+  env?: NodeJS.ProcessEnv
+  /** Seam: lets the no-credential path be exercised on a machine that has one. */
+  credential?: () => { apiUrl: string; token: string }
+}
+
+/**
+ * Write `<root>/.env.local` so the dev host can reach the platform.
+ *
+ * Never overwrites. An author who has pointed a project at a different origin,
+ * or pasted a longer-lived key, has said something more specific than we know —
+ * and silently replacing a credential file is the kind of help nobody asks for
+ * twice.
+ */
+export function writeDevEnv(root: string, deps: DevEnvDeps = {}): DevEnvResult {
+  const path = join(root, DEV_ENV_FILE)
+  if (existsSync(path)) return { written: false, reason: 'exists' }
+
+  let credential: { apiUrl: string; token: string }
+  try {
+    credential = (deps.credential ?? (() => resolveCredential({}, { env: deps.env })))()
+  } catch {
+    // No origin, no token, no keychain — the ordinary state before a login.
+    return { written: false, reason: 'no-credential' }
+  }
+
+  const env = deps.env ?? process.env
+  // Only what the dev host actually reads. `workspaceId`/`orgId` are optional
+  // there and optional here: an `sk-ws-` key resolves to its own workspace
+  // server-side and cannot be widened by a header, so the token alone is
+  // enough to read real data. They are written when known because the dev host
+  // passes them into `frontera:init`, where an app may read them.
+  const lines = [
+    '# Written by the frontera CLI so the dev host can read real data.',
+    '# Not packaged, not committed — see .gitignore.',
+    `VITE_FRONTERA_API_URL=${credential.apiUrl}`,
+    `VITE_FRONTERA_TOKEN=${credential.token}`,
+    env.FRONTERA_WORKSPACE_ID ? `VITE_FRONTERA_WORKSPACE_ID=${env.FRONTERA_WORKSPACE_ID}` : '',
+    env.FRONTERA_ORG_ID ? `VITE_FRONTERA_ORG_ID=${env.FRONTERA_ORG_ID}` : '',
+  ].filter(Boolean)
+
+  try {
+    writeFileSync(path, `${lines.join('\n')}\n`, { mode: 0o600 })
+  } catch {
+    return { written: false, reason: 'failed' }
+  }
+  return { written: true }
+}
+
+/**
+ * Is this project's dev host able to read real data?
+ *
+ * Read rather than assumed, so a caller can say the true thing about a
+ * project whose `.env.local` predates this or was written by hand.
+ */
+export function devEnvHasToken(root: string): boolean {
+  try {
+    return /^VITE_FRONTERA_TOKEN=.+$/m.test(readFileSync(join(root, DEV_ENV_FILE), 'utf8'))
+  } catch {
+    return false
+  }
+}

package/src/flag-help.ts

@@ -13,6 +13,17 @@
  * fails if a command declares a flag this file does not describe.
  */
 export const FLAG_HELP: Readonly<Record<string, string>> = {
+  // Declarative Blueprint authoring — the file tree, and what applying it may do.
+  prune: 'also remove artifacts that are on the draft but absent from the file tree',
+  dataset: 'dataset name the object type reads through; the revision is resolved at apply time',
+  plan: 'write a mapping skeleton to this path instead of binding',
+  'accept-contract-change': 'confirm a rebind whose column contract differs from the pinned one',
+  revoke: 'remove the grant instead of adding it',
+  // Blueprint authoring (organization API key). `notes` is described further down
+  // — this map is keyed by flag name across every command, so one entry serves both.
+  label: 'release label recorded on the published or rolled-back release',
+  report: 'validation report id to publish against; defaults to a fresh validation',
+  instruction: 'migration instruction applied to every change a rollback discards',
   // Global
   json: 'machine-readable output on stdout; stderr still carries commentary',
   quiet: 'suppress progress commentary on stderr',
@@ -33,8 +44,24 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Apps
   version: 'version to publish, overriding the one in package.json',
   'no-promote': 'publish the version without moving the live pointer',
+  'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
   draft: 'act on your saved draft rather than a published version',
 
+  // Agents
+  name: 'display name; defaults to the slug',
+  kind: 'agent kind: conversation (default) or work',
+
+  // Packs
+  'remove-apps': 'also uninstall the apps the pack installed',
+
+  // Secrets
+  from: 'where to read the value from: `-` for stdin, or a file path. Never an inline value',
+
+  // Knowledge
+  description: 'one-line description stored on the resource',
+  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',
   'no-input': 'never prompt; fail instead, for use in scripts and CI',
@@ -48,11 +75,18 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
  */
 const PLACEHOLDER: Readonly<Record<string, string>> = {
   'api-url': 'origin',
+  dataset: 'name',
+  plan: 'path',
   dir: 'path',
   file: 'path',
   version: 'semver',
   'expect-revision': 'hash',
   notes: 'text',
+  description: 'text',
+  strategy: 'auto|text|ocr',
+  from: '-|path',
+  name: 'text',
+  kind: 'conversation|work',
 }
 
 /**

package/src/harness.ts

@@ -72,13 +72,40 @@ Errors carry a \`hint\` naming the next command. Read it.
 - **On exit 3, re-fetch — never force.** The document you hold is stale. Get it
   again, reapply your edit on top, then send it. Overwriting discards whatever
   the other writer did.
-- **Secrets never go in a flag.** Use \`--secret name@-\` (stdin), \`name@./file\`,
-  or \`name=ref:<workspace-secret>\`. A value on the command line lands in
-  process listings and shell history.
+- **Secrets never go in a flag.** \`frontera secret set NAME --from -\` reads the
+  value from stdin, \`--from ./file\` from a file. A value passed inline lands in
+  shell history and in the process list, so the inline form is refused. An
+  automation then NAMES the secret — \`auth: { secret: 'NAME' }\` plus a
+  \`secret:NAME\` grant — and its value never enters the automation's process.
 - **\`.env\` is never packaged**, and that is not overridable.
 - **A pull refuses to clobber.** If it reports dirty files, deal with them —
   inside a sandbox there is usually no git to recover from.
 
+## Seeding a knowledge base
+
+\`\`\`bash
+frontera knowledge create <name> --description "<what is in it>"
+frontera knowledge upload <name> ./corpus       # a directory is walked
+frontera knowledge attach <name> <agent>        # nothing can read it until this
+frontera knowledge sources <name>               # status per file, minutes later
+\`\`\`
+
+Three things about this are not visible from \`--help\`:
+
+- **Upload queues ingestion; it does not finish it.** A file comes back
+  \`processing\` with 0 chunks and turns \`ready\` minutes later. Retrieval tested
+  before then returns nothing, which is not a failed upload.
+- **A partial batch still exits 0.** One unreadable file does not end the run, so
+  read \`failed\` in the payload rather than trusting the exit code alone. Exit is
+  non-zero only when nothing at all landed. Re-running is safe — upload is
+  additive.
+- **Attachment is the only route in.** An automation has no knowledge capability
+  of its own; it reaches a corpus only through \`ctx.agent(<slug>)\` where that
+  agent has the base attached. A base nobody is attached to is unreachable.
+
+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.
+
 ## Building an app
 
 \`\`\`bash

package/src/main.ts

@@ -34,14 +34,21 @@ import type { AppProject } from './context'
  * A released binary is stamped at build time with the tag it shipped from
  * (`scripts/build-release.ts`), because that is the number a caller can
  * actually act on: it names the platform release this client was built
- * against, so a bug report says which server contract it expects. Running from
- * source there is no tag, and the package version is the honest answer.
+ * against, so a bug report says which server contract it expects.
+ *
+ * Unstamped, the manifest version is the answer, and whether it is a release
+ * depends on where this file is running from. Installed from npm it is exact:
+ * the release commit bumps this package with the tag, so the manifest version
+ * IS the release. In a checkout it is the LAST release, with unreleased commits
+ * on top — so it gets `-dev`, which is what stops a bug report from naming a
+ * version whose code the reporter is not running.
  */
 async function resolveVersion(): Promise<string> {
   const stamped = process.env.FRONTERA_CLI_VERSION
   if (stamped) return stamped
   const pkg = await import('../package.json', { with: { type: 'json' } })
-  return `${(pkg.default as { version: string }).version}-dev`
+  const version = (pkg.default as { version: string }).version
+  return import.meta.dir.includes('/node_modules/') ? version : `${version}-dev`
 }
 
 async function main(): Promise<number> {

package/src/render-evidence.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+import { isExcluded } from './packaging'
+
+/**
+ * Has anybody looked at this app before it goes live?
+ *
+ * ## Why deploy asks
+ *
+ * `bun run build` was the only gate between authoring and live. It says the
+ * TypeScript compiles. It does not say the COD Share tile reads 551,7% because
+ * the numerator forgot the filter its denominator applies, or that the status
+ * pie renders nothing because the API returns counts as JSON strings and
+ * Recharts cannot do angle math on strings. Both shipped, to a live URL, with
+ * "the dashboard is ready".
+ *
+ * Both were one screenshot away. So the deploy path asks the one question a
+ * compiler cannot: since you last changed the source, did you look at it?
+ *
+ * ## Why it does not refuse
+ *
+ * A tree can legitimately deploy unrendered — a copy edit, a promotion from
+ * CI, a rebuild of something already reviewed. A gate that fires on legitimate
+ * cases is one people learn to route around, and the routing-around outlives
+ * the gate. This records, reports, and stores the answer on the version. That
+ * is the whole intervention.
+ *
+ * ## Why mtime
+ *
+ * The question is literally "was this rendered SINCE the last source change",
+ * and file mtimes are that question written down. A content hash would be
+ * stabler against a `touch`, and would also call an unchanged reformat a new
+ * tree; neither error matters here, because nothing is being enforced. The
+ * cheap answer to a reported question beats the expensive answer to a blocked
+ * one.
+ */
+
+/** Written by `render_app`; see RENDER_EVIDENCE_RELATIVE_PATH in the service. */
+export const RENDER_EVIDENCE_PATH = '.frontera/last-render.json'
+
+export interface RenderEvidence {
+  /** True only when a render happened AFTER the newest source change. */
+  rendered: boolean
+  /**
+   * `fresh` — rendered, and nothing has changed since.
+   * `stale` — rendered, but the source moved on afterwards.
+   * `none`  — this tree has never been rendered.
+   */
+  reason: 'fresh' | 'stale' | 'none'
+  renderedAt?: string
+  /** Which page was opened — "/" proves less than "/dev-host.html" for an App. */
+  path?: string
+  /** What the browser console said at render time, if the renderer recorded it. */
+  consoleErrors?: number
+}
+
+interface RenderRecord {
+  renderedAt?: string
+  renderedAtMs?: number
+  path?: string
+  consoleErrors?: number
+}
+
+/**
+ * Newest mtime across the files that would be packaged.
+ *
+ * Same exclusion set as packaging, so `node_modules` churn and build output
+ * cannot make a tree look edited — the ONE failure mode that would make this
+ * report worthless, because it would report `stale` every single time and
+ * everyone would stop reading it.
+ */
+export function newestSourceChangeMs(root: string): number {
+  let newest = 0
+  const walk = (dir: string) => {
+    let entries: string[]
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry)
+      const rel = relative(root, full).split(sep).join('/')
+      if (isExcluded(rel)) continue
+      // The evidence file lives inside the project and is written by the
+      // render itself. Counting it would make every render immediately stale.
+      if (rel === RENDER_EVIDENCE_PATH || rel === '.frontera') continue
+      let stat: ReturnType<typeof statSync>
+      try {
+        stat = statSync(full)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) {
+        walk(full)
+        continue
+      }
+      newest = Math.max(newest, stat.mtimeMs)
+    }
+  }
+  walk(root)
+  return newest
+}
+
+export function readRenderEvidence(root: string): RenderEvidence {
+  const path = join(root, RENDER_EVIDENCE_PATH)
+  if (!existsSync(path)) return { rendered: false, reason: 'none' }
+
+  let record: RenderRecord
+  try {
+    record = JSON.parse(readFileSync(path, 'utf8')) as RenderRecord
+  } catch {
+    // Unreadable is indistinguishable from absent, and claiming a render on
+    // the strength of a corrupt file is the one answer that would be worse
+    // than no answer.
+    return { rendered: false, reason: 'none' }
+  }
+
+  const renderedAtMs = record.renderedAtMs ?? (record.renderedAt ? Date.parse(record.renderedAt) : NaN)
+  if (!Number.isFinite(renderedAtMs)) return { rendered: false, reason: 'none' }
+
+  const rendered = renderedAtMs >= newestSourceChangeMs(root)
+  return {
+    rendered,
+    reason: rendered ? 'fresh' : 'stale',
+    ...(record.renderedAt ? { renderedAt: record.renderedAt } : {}),
+    ...(record.path ? { path: record.path } : {}),
+    ...(typeof record.consoleErrors === 'number' ? { consoleErrors: record.consoleErrors } : {}),
+  }
+}
+
+/**
+ * The line deploy prints, and the one the agent reads.
+ *
+ * Written as a statement of fact rather than a warning. "You should have
+ * rendered this" invites an argument; "deploying a tree that has never been
+ * rendered" is simply what is happening, and a reader who is fine with that
+ * moves on.
+ */
+export function describeRenderEvidence(evidence: RenderEvidence): string {
+  switch (evidence.reason) {
+    case 'fresh':
+      return `  rendered ${evidence.path ?? '/'}${
+        evidence.consoleErrors ? ` (${evidence.consoleErrors} console error${evidence.consoleErrors === 1 ? '' : 's'} at render time)` : ''
+      }`
+    case 'stale':
+      return '  deploying source that has changed since it was last rendered — nobody has seen this version'
+    default:
+      return '  deploying a tree that has never been rendered — a build that compiles is the only check this version has had'
+  }
+}

package/src/template.ts

@@ -298,6 +298,10 @@ export default function App() {
 dist/
 .frontera/
 *.log
+# Holds a workspace key with write scope — written by the CLI so the dev host
+# can read real data. Packaging already refuses it; this stops a commit.
+.env.local
+.env*.local
 `,
 
     '.agents/skills/using-frontera-sdk/SKILL.md': `---

package/src/untar.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+
+/**
+ * Unpack a gzipped ustar archive onto disk, returning the file count.
+ *
+ * Shared by `app pull` and `automation pull`. The `..` refusal below is why this
+ * is one function rather than a copy in each: an archive is remote input, and a
+ * traversal member that is honoured writes anywhere the process can reach.
+ *
+ * Directory members (typeflag '5') are skipped — `mkdirSync(recursive)` on each
+ * file's parent creates everything needed, and honouring them adds a second path
+ * to validate for no benefit.
+ */
+export function unpackTo(dir: string, gz: Uint8Array): number {
+  const buf = new Uint8Array(gunzipSync(Buffer.from(gz)))
+  const dec = new TextDecoder()
+  const readStr = (start: number, len: number) => {
+    let end = start
+    while (end < start + len && buf[end] !== 0) end++
+    return dec.decode(buf.subarray(start, end))
+  }
+  let off = 0
+  let count = 0
+  while (off + 512 <= buf.length) {
+    const name = readStr(off, 100)
+    if (name === '') break
+    const prefix = readStr(off + 345, 155)
+    const size = parseInt(readStr(off + 124, 12).trim() || '0', 8)
+    const dataStart = off + 512
+    if (buf[off + 156] === 0x30 || buf[off + 156] === 0) {
+      const rel = (prefix ? `${prefix}/${name}` : name).replace(/^\.?\//, '')
+      if (rel && !rel.split('/').includes('..')) {
+        const full = join(dir, rel)
+        mkdirSync(dirname(full), { recursive: true })
+        writeFileSync(full, buf.subarray(dataStart, dataStart + size))
+        count++
+      }
+    }
+    off = dataStart + Math.ceil(size / 512) * 512
+  }
+  return count
+}