@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/exit.ts

@@ -16,7 +16,12 @@ export const EXIT = {
   FAILURE: 1,
   /** Bad invocation or bad input. Fix the command. */
   USAGE: 2,
-  /** Someone else changed it first. Re-fetch, reapply. */
+  /**
+   * Someone else changed it first, or the state of the record or the request
+   * refuses it (a governed Action's submission criteria, a request whose
+   * outcome is unknown). Re-read, then change the input or the record; the
+   * same request is refused again, so never retry it as it is.
+   */
   CONFLICT: 3,
   /** Credentials or permission. Neither retry nor rewording helps. */
   AUTH: 4,
@@ -58,8 +63,75 @@ const USAGE_CODES = new Set([
   // Authoring kit. Both are resolved by running a named command, not by retry.
   'KIT_VERSION_MISMATCH',
   'GENERATED_FILE_CONFLICT',
+  // The Idempotency-Key was used for a different request: a new key fixes it,
+  // re-reading does not. (An effect another request already made is a
+  // conflict: see CONFLICT_REASONS.)
+  'ACTION_IDEMPOTENCY_CONFLICT',
+  // An Action that isn't there to submit, or a submit without the key it needs.
+  'ACTION_NOT_FOUND',
+  'ACTION_IDEMPOTENCY_KEY_REQUIRED',
 ])
-const CONFLICT_CODES = new Set(['DRAFT_CONFLICT', 'CONFLICT', 'VALIDATION_STALE'])
+/**
+ * Someone changed it first: re-read, then decide or submit again. Each of
+ * these is fixed by re-reading the record or the request, which a retry of
+ * the same body never does.
+ */
+const CONFLICT_CODES = new Set([
+  'DRAFT_CONFLICT',
+  'CONFLICT',
+  'VALIDATION_STALE',
+  // The record moved past `expectedVersion`: read it again, submit with the new one.
+  'ACTION_SOURCE_VERSION_STALE',
+  // The request changed under its approvals: read the request again.
+  'ACTION_APPROVAL_STALE',
+  // The record already has an open request of this Action (`openRequests: one_per_subject`):
+  // read that request (`details.openRequest`) instead of submitting another.
+  'ACTION_REQUEST_ALREADY_OPEN',
+  // Refused by the state of the record, the Action or the request: the same
+  // request is refused every time, so exit 1 ("retry") would send a caller
+  // round a loop. Each is fixed by re-reading and changing something first.
+  // The record or the input fails the Action's submission criteria.
+  'ACTION_CRITERIA_FAILED',
+  // The Action is switched off, has no binding, its binding is revoked or
+  // suspended, or it has no deployment (`ACTION_NOT_DEPLOYED`, the CLI's word
+  // for that 409): nothing changes until someone turns it back on or deploys it.
+  'ACTION_DISABLED',
+  'ACTION_UNBOUND',
+  'ACTION_BINDING_REVOKED',
+  'ACTION_BINDING_SUSPENDED',
+  'ACTION_NOT_DEPLOYED',
+  // It needs an approval first, or affects more records than the Action allows.
+  'ACTION_APPROVAL_REQUIRED',
+  'ACTION_EFFECT_LIMIT_EXCEEDED',
+  // The outcome is settled or unknown: read the request (`action requests`),
+  // never submit again — a second submit could make the change twice.
+  'ACTION_CONFIRMED_NOT_APPLIED',
+  'ACTION_OUTCOME_UNKNOWN',
+  'ACTION_RESOLUTION_REQUIRED',
+  'AUTOMATION_PUBLISH_UNCERTAIN',
+  // The dataset's rows are written somewhere else now.
+  'DATASET_AUTHORITY_MOVED',
+])
+/**
+ * Refusals the service sends under another code with a `reason` that is a
+ * conflict: the approval step moved on, or another request already made the
+ * effect. They exit 3 whatever their code.
+ */
+const CONFLICT_REASONS = new Set([
+  'ACTION_APPROVAL_STEP_CHANGED',
+  'ACTION_LOGICAL_EFFECT_CONFLICT',
+  'ACTION_SOURCE_VERSION_STALE',
+  'ACTION_REQUEST_ALREADY_OPEN',
+])
+
+/** A refusal's `reason`, at the top of its details or nested one level under `details`. */
+export function reasonOf(details: unknown): string | undefined {
+  if (typeof details !== 'object' || details === null) return undefined
+  const body = details as { reason?: unknown; details?: unknown }
+  if (typeof body.reason === 'string') return body.reason
+  const nested = body.details
+  return typeof nested === 'object' && nested !== null && typeof (nested as { reason?: unknown }).reason === 'string' ? (nested as { reason: string }).reason : undefined
+}
 const AUTH_CODES = new Set([
   'UNAUTHORIZED',
   'FORBIDDEN',
@@ -78,7 +150,9 @@ const AUTH_CODES = new Set([
  * an SDK release — which means this function must treat "never seen it" as
  * ordinary, not exceptional.
  */
-export function exitCodeFor(code: string): ExitCode {
+export function exitCodeFor(code: string, details?: unknown): ExitCode {
+  const reason = reasonOf(details)
+  if (reason && CONFLICT_REASONS.has(reason)) return EXIT.CONFLICT
   if (USAGE_CODES.has(code)) return EXIT.USAGE
   if (CONFLICT_CODES.has(code)) return EXIT.CONFLICT
   if (AUTH_CODES.has(code)) return EXIT.AUTH
@@ -98,6 +172,10 @@ const SERVICE_HINTS: Record<string, string> = {
   // which case they are in throw a CliError with a specific hint instead.
   CONFLICT: 'the message above names what conflicted — resolve that, then retry',
   VALIDATION_STALE: 're-fetch the resource and re-run validation against the current revision',
+  ACTION_SOURCE_VERSION_STALE: 'the record changed first — read it again (`frontera blueprint query`), then submit with its current version as expectedVersion',
+  ACTION_APPROVAL_STALE: 'the request changed under its approvals — read it again (`frontera action requests`), then decide',
+  ACTION_IDEMPOTENCY_CONFLICT: 'that Idempotency-Key belongs to another request — submit with a new key',
+  ACTION_REQUEST_ALREADY_OPEN: 'this record already has an open request of this Action — follow it (`frontera action requests <requestId>`, the id in the details) instead of submitting another',
   // Names neither kind. Both are valid here — a workspace key for agents,
   // skills, plugins and knowledge; an organization key for Blueprint authoring,
   // datasets and Sources — and naming only one sent holders of the other
@@ -223,6 +301,19 @@ function hintFor(code: string, details: unknown): string | undefined {
   return SERVICE_HINTS[code]
 }
 
+/**
+ * A refusal that names what it refused only in its details (`invalid_plugins`
+ * with `{ invalid: ['decision'] }`), said with the names: the message alone
+ * leaves nobody able to tell which entry to take out.
+ */
+export function withRefusedNames(message: string, details: unknown): string {
+  if (!/^invalid_[a-z_]+$/.test(message) || typeof details !== 'object' || details === null) return message
+  const body = details as { invalid?: unknown; details?: { invalid?: unknown } }
+  const invalid = Array.isArray(body.invalid) ? body.invalid : Array.isArray(body.details?.invalid) ? body.details.invalid : null
+  const names = invalid?.filter((n): n is string => typeof n === 'string') ?? []
+  return names.length ? `${message}: ${names.join(', ')}` : message
+}
+
 function isFronteraError(
   err: unknown,
 ): err is { code: string; message: string; details?: unknown } {
@@ -246,8 +337,16 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
   }
 
   if (isFronteraError(err)) {
+    // Invoking an Action that has no deployment, through any client: said as that.
+    const details = err.details as { details?: { reason?: unknown; readinessReason?: unknown; deploymentStatus?: unknown } ; reason?: unknown; readinessReason?: unknown; deploymentStatus?: unknown } | undefined
+    const nd = details?.reason === 'ACTION_NOT_DEPLOYED' ? details : details?.details?.reason === 'ACTION_NOT_DEPLOYED' ? details.details : null
+    if (nd) {
+      const why = typeof nd.readinessReason === 'string' ? nd.readinessReason : typeof nd.deploymentStatus === 'string' ? `its deployment is ${nd.deploymentStatus}` : 'it has no active deployment'
+      return { error: true, code: 'ACTION_NOT_DEPLOYED', message: `${err.message.replace(/[.]$/, '')}: the Action isn't deployed: ${why}`, hint: '`frontera action list` shows why each Action cannot run; `frontera action deploy <name>` builds its write path' }
+    }
     const hint = hintFor(err.code, err.details)
-    return { error: true, code: err.code, message: err.message, ...(hint ? { hint } : {}) }
+    const reason = reasonOf(err.details)
+    return { error: true, code: err.code, message: withRefusedNames(err.message, err.details), ...(hint ? { hint } : {}), ...(reason ? { details: { reason } } : {}) }
   }
 
   return {

package/src/flag-help.ts

@@ -40,7 +40,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   remove: 'comma-separated property API names to drop from the current set',
   // 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',
+  label: 'release label recorded on the published or rolled-back release; for an App deployment, unique per App',
   report: 'validation report id to act on — the release publishes against it, the review is pinned to it',
   instruction: 'migration instruction applied to every change a rollback discards',
   // Global
@@ -71,7 +71,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 
   // Writes
   file: 'read the document from this path, or `-` for stdin',
-  force: 'proceed past a refusal — overwrite existing files, or a dirty tree',
+  force: 'proceed past a refusal — overwrite existing files, a dirty tree, an App\'s or a change request\'s required checks (with --reason), a running local runtime',
   'expect-revision':
     'refuse the write unless the resource is still at this revision; exit 3 if it moved',
   notes: 'note recorded against the published version',
@@ -91,6 +91,19 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   registry: 'the registry host and namespace image mode pulls the platform images from, such as registry.example.com/frontera',
   reapply: 'apply every file again, including those unchanged since they were last applied',
   stop: 'stop the local runtime when the check ends',
+  'keep-state': 'keep what the Agent and workflow tests wrote, instead of restoring the database as the apply left it',
+  exact: 'restore: put the baseline’s workspace secrets back too, instead of keeping the ones set now',
+  workflow: 'run only this workflow’s tests (workflows/tests/<slug>.yaml)',
+  skip: 'comma-separated check steps to leave out: typecheck, unit, apps, agents, workflows',
+  'object-type': 'the object type a new action acts on; its primary key names the key input',
+  body: 'the request body to send: a file, or - for standard input',
+  path: 'which webhook of the workflow, by its trigger path; needed when it has several',
+  method: 'the HTTP method to send; POST when the webhook takes it',
+  header: 'one header the sender would send, `Name: value` (the webhook’s own auth)',
+  query: 'a query string to send with the delivery, such as source=portal&urgent=1',
+  'fail-fast': 'stop the check at the first step that fails, instead of running and reporting every step',
+  strict: 'fail on inherited failures too: items and files unchanged since the pull, which otherwise are listed and do not fail the check',
+  concurrency: 'how many Agent test cases run at once (1–16, default 2); cases that change records for real still run one at a time. Lower it when the model provider refuses for requests in flight',
 
   // Apps
   framework: 'App scaffold to create: next (default) or react (legacy Vite)',
@@ -104,7 +117,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // choose which version to RUN, one chooses which to publish. The old text
   // described only the third, so `workflow run --help` and `function run
   // --help` both advertised package.json.
-  version: 'the version to act on — the one to run, or on a deploy the one to publish',
+  version: 'the version to act on — the one to run (`workflow run` also takes draft: the newest version not retired), or on a deploy the one to publish',
   input: "JSON object of the declared inputs — inline ('{\"key\": 1}') or @file.json",
   // The primary key alone. A subject-bound workflow takes exactly one, so the
   // flag spends no characters on the `{"pk": …}` the route models it as.
@@ -112,8 +125,11 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Action requests.
   'subject-version': 'record version of --subject the request expects, so a stale read is refused',
   'idempotency-key': 'reuse a key to retry a submit and get the same request back; generated if omitted',
-  'no-promote': 'publish the version without moving the live pointer',
-  'skip-build-check': 'deploy even when the build output is older than the source',
+  'no-promote': 'publish the version without moving the live pointer; with app deploy --prod, stage it for production',
+  build: 'run bun run build first, so the deployment is built from the source as it is now',
+  'skip-build-check': 'deploy even when the build output is older than the source, and skip bun run check',
+  prod: 'go live once the required checks pass (a deploy is otherwise a preview)',
+  undo: 'undo the rollback: production serves what it did before, and is unpinned',
   'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
   // Named for what it RUNS, not where it runs: an author reads this to decide
   // between their working copy and what is deployed.
@@ -129,8 +145,8 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 
   // Blueprint scaffolding
   template:
-    'starting rule for `blueprint new semantic-type`: non-negative, percentage, status-enum '
-    + 'or code-length (default)',
+    'starting shape: a semantic type\'s rule (non-negative, percentage, status-enum, '
+    + 'code-length, the default), or an action\'s (edit, the default, or create)',
 
   // Packs
   'remove-apps': 'also uninstall the apps the pack installed',
@@ -146,8 +162,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // 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',
+    'filter as <property>:<value>, <property>:<op>:<value>, <property>:in:<a>,<b> (also notIn and between; '
+    + 'a backslash before a comma keeps it in a value, or give a JSON array), or a JSON where-node for an '
+    + 'or/not; repeat it for conditions that must all hold',
   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,
@@ -155,6 +172,22 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // 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',
+  as:
+    'on the local runtime only: act as a local persona (`submitter`, or an approval step such as '
+    + '`dispatch_lead`), as `frontera local status` lists them; refused anywhere else',
+  // A metric's query (`blueprint metric query`).
+  measure: 'comma-separated measures of the metric to return; all of them when absent',
+  'group-by': 'comma-separated dimensions of the metric to break the numbers down by',
+  grain: 'a series by hour, day, week, month, quarter or year over the metric’s timeseries dimension (added to the group-by)',
+  range: 'a time window as an ISO-8601 duration (P7D, PT12H, P3M), back from the newest value of the metric’s timeseries in the data, not from now',
+  start: 'the window’s start, an ISO date or timestamp (inclusive; a date is its midnight UTC)',
+  end: 'the window’s end, an ISO date or timestamp (exclusive; a date is its midnight UTC)',
+  compare: 'add the window before the one given: <measure>_prev, <measure>_delta and <measure>_pct',
+  only: 'live: only live runs; test: only test runs (from `local test`, Studio or a draft run)',
+  npm: 'with use-local: switch the App back to the published @frontera-sdk packages from npm, deleting vendor/frontera-sdk/ and any SDK copy under src/frontera/ (the output lists each file)',
+  'object-set':
+    'read a saved object set’s rows: its name, its reference (objectSet/<ref>) or its id, '
+    + 'from `frontera blueprint object-sets`',
   // 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
@@ -184,8 +217,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // 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',
+    'maximum cosine distance a chunk may have, 0 to 2; higher is more permissive (default: the '
+    + 'base’s own match threshold, as an Agent’s retrieval uses it). Not the score shown in the '
+    + 'output: a score is 1 − distance / 2, so 0.5 keeps scores above 0.75',
   strategy:
     'text extraction to use per file: auto (default), text, or ocr; ocr needs an OCR engine on the base',
 
@@ -214,7 +248,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'org-key': '`-` to read an organization key (sk-org-…) from stdin, after the workspace key; widens the Blueprint to the whole model',
   blueprint: 'workspace (the slice granted to the workspace, default) or organization (the whole model; needs an organization key)',
   relink: 'point a project already linked to another workspace at this one',
-  preview: 'list what a pull would bring, or a push would propose, file by file, and change nothing',
+  preview: 'local sync: list what a pull would bring, or a push would propose, file by file, and change nothing; app deploy: make a preview deployment (the default), said explicitly as a pipeline must',
   kinds: 'comma-separated: blueprint, skills, functions, plugins, knowledge, workflows, agents, evaluations',
   drafts: 'comma-separated items (agent/<slug>, workflow/<slug>, function/<slug>, blueprint) to read as their draft instead of the live version; the Blueprint’s draft takes an organization key',
   'all-changed': 'pull every item the workspace changed since the last pull, and every clean merge; never one that conflicts or replaces local edits',
@@ -230,14 +264,25 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   edited: 'take the files as you edited them; the workspace’s copies beside them go',
   title: 'the change request’s title; a push that opens a new one needs it',
   migration: 'for a Blueprint change that is not additive: what happens to existing records',
-  documents: 'comma-separated knowledge bases whose documents a pull brings, or a push proposes (`*` for every one); without it they stay as they are',
+  documents: 'comma-separated knowledge bases whose documents a pull brings (a base pulled now brings its own anyway), or a push proposes (`*` for every one)',
+  'no-documents': 'pull knowledge bases without their documents (by default a pulled base brings them)',
+  'no-app-code': 'pull Custom Apps without their code (by default a pulled App brings its deployed version into apps/<slug>/, unless that folder is there)',
+  release: 'Custom Apps the change request releases, comma-separated slug=deployment (the newest deployment when only the slug is given); Apply promotes each one last',
+  evals: 'run each Agent’s gated cases (gate: true) against the local runtime and attach the results, compared with its last applied run',
+  renders: 'attach each released App’s last render (its screenshot and console summary)',
+  screenshots: 'attach the newest screenshots a Forge session saved (its id; this session’s when run inside Forge)',
+  trace: 'attach a trace link (an http(s) address) to the change request',
   lessons: 'bring each Agent’s reviewed rules from customer feedback into agents/<slug>/lessons.yaml (never the feedback itself); off by default',
   conflicts: 'the conflicts the picks were chosen against, as `diff --json` names them; refused if they moved',
   'from-workspace': 'start the project from a platform workspace instead of the examples',
   'no-sample-data': 'do not generate sample rows for the pulled Blueprint',
+  'keep-sample-data': 'leave the sample datasets as they are; by default they are made again (same seed, rows and day) after a pull that brings Blueprint items, or when an older generator made them',
+  'remake-sample-data': 'make the sample datasets again with the newest sample rules (same seed, rows and day), even the ones a pull wrote, which local dev otherwise keeps as pulled',
   synthetic: 'generate sample rows for the Blueprint: values fit each property, links stay consistent',
   rows: 'rows per object type (default 200; types others link to get half)',
-  seed: 'the same seed writes the same rows (default 7)',
+  seed: 'the same seed writes the same rows on the same day; with --today, on any day (default 7)',
+  today: 'the day sample due dates are spread around, YYYY-MM-DD (default: today, UTC)',
+  region: 'where sample geopoints fall: a country code (ID, US, GB…) or `<lat>,<lon>[,<radius km>]` (default: the project’s `locale` in frontera.yaml, else the workspace’s timezone, else US)',
 }
 
 /**
@@ -259,6 +304,8 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   // take an integer version number, and this map is keyed by flag name for all
   // three. `<version>` is the only placeholder true of every consumer.
   version: 'version',
+  body: 'file',
+  header: 'name: value',
   framework: 'next|react',
   port: 'number',
   origin: 'url',
@@ -279,6 +326,15 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   order: 'prop:asc',
   limit: 'n',
   'page-token': 'cursor',
+  'object-set': 'name|ref|id',
+  measure: 'a,b',
+  'group-by': 'a,b',
+  grain: 'hour|day|week|month|quarter|year',
+  range: 'P7D',
+  start: 'iso',
+  end: 'iso',
+  only: 'live|test',
+  as: 'persona',
   cursor: 'cursor',
   lifecycle: 'state',
   actions: 'allow_all|read_only|custom',
@@ -288,7 +344,7 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   markings: 'a,b',
   'max-distance': '0-2',
   permissions: 'read,write',
-  template: 'non-negative|percentage|status-enum|code-length',
+  template: 'non-negative|percentage|status-enum|code-length|edit|create',
   platform: 'url',
   'workspace-key': '-',
   'org-key': '-',
@@ -299,6 +355,9 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'delete-here': 'kind/name,…',
   'keep-local': 'kind/name,…',
   documents: 'name,…',
+  release: 'slug=deployment,…',
+  screenshots: 'session',
+  trace: 'url',
   keep: 'workspace|mine',
   picks: 'n=side,…',
   rows: 'n',
@@ -315,6 +374,7 @@ export function flagUsage(name: string, type: 'string' | 'boolean', alias?: stri
   return `${short}--${name} <${PLACEHOLDER[name] ?? 'value'}>`
 }
 
-export function describeFlag(name: string): string {
-  return FLAG_HELP[name] ?? ''
+/** A command's own wording for a flag (`meta.flagHelp`) wins: the one place a name means something else there. */
+export function describeFlag(name: string, own?: Readonly<Record<string, string>>): string {
+  return own?.[name] ?? FLAG_HELP[name] ?? ''
 }

package/src/forge/claude-commands.ts

@@ -59,12 +59,17 @@ async function probe(cwd: string, claudePath: string, log?: Logger): Promise<For
     const session = query({
       // Never yields: the initialization response is all this call is for, and
       // a prompt that resolved would send a turn to the model.
-      prompt: (async function* () {
-        await new Promise<void>((resolve) => {
-          if (abort.signal.aborted) resolve()
-          else abort.signal.addEventListener('abort', () => resolve(), { once: true })
-        })
-      })(),
+      prompt: {
+        [Symbol.asyncIterator]() {
+          return {
+            next: () => new Promise<IteratorResult<never>>((resolve) => {
+              const done = () => resolve({ done: true, value: undefined })
+              if (abort.signal.aborted) done()
+              else abort.signal.addEventListener('abort', done, { once: true })
+            }),
+          }
+        },
+      },
       options: {
         cwd,
         pathToClaudeCodeExecutable: claudePath,

package/src/forge/claude-skills.ts

@@ -58,7 +58,7 @@ function readSkillDir(dir: string): Array<{ dirName: string; path: string; conte
     return []
   }
   const out: Array<{ dirName: string; path: string; contents: string }> = []
-  for (const entry of [...entries].sort()) {
+  for (const entry of [...entries].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     const path = join(dir, entry, 'SKILL.md')
     try {
       out.push({ dirName: entry, path, contents: readFileSync(path, 'utf8') })
@@ -92,14 +92,14 @@ function pluginSkillRoots(configDir: string): Array<{ plugin: string; dir: strin
   } catch {
     return []
   }
-  for (const marketplace of marketplaces.sort()) {
+  for (const marketplace of marketplaces.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     let plugins: string[]
     try {
       plugins = readdirSync(join(cache, marketplace))
     } catch {
       continue
     }
-    for (const plugin of plugins.sort()) {
+    for (const plugin of plugins.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
       let versions: string[]
       try {
         versions = readdirSync(join(cache, marketplace, plugin))
@@ -107,7 +107,7 @@ function pluginSkillRoots(configDir: string): Array<{ plugin: string; dir: strin
         continue
       }
       // Newest version wins when a cache holds more than one.
-      for (const version of versions.sort().reverse()) {
+      for (const version of versions.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)).reverse()) {
         const dir = join(cache, marketplace, plugin, version, 'skills')
         try {
           if (statSync(dir).isDirectory()) {

package/src/forge/touches.ts

@@ -44,29 +44,31 @@ export const FORGE_ARTIFACT_KINDS = [
  * `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'],
+  agent: ['apply', 'create', 'publish', 'revert', 'discard', 'skill-attach', 'skill-detach', 'archive', 'restore'],
   automation: ['deploy', 'promote', 'enable', 'disable', 'init', 'bind', 'unbind', 'run'],
-  app: ['deploy', 'promote', 'save', 'add'],
+  app: ['deploy', 'promote', 'rollback', 'unpin', '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'],
+  // `revise` cuts the dataset's next revision from its CSV.
+  dataset: ['create', 'upload', 'revise', 'test-source'],
   knowledge: ['create', 'attach', 'detach', 'upload', 'retry', 'delete'],
+  // `webhook-test` starts a run on the draft through its webhook, as `run` does.
   // `get`, `lineage`, `list`, `runs` and `validate` are reads — `validate` is
   // `push --dry-run` and writes nothing. `cancel` is deliberately absent: it
   // stops one in-flight run and leaves the definition, the versions and the
   // live pointer exactly as they were, and its positional is a RUN id, not a
   // slug, so it could not name the workflow page anyway. Same call
   // `automation` makes, which lists `run` and not `cancel`.
-  workflow: ['push', 'promote', 'run'],
+  workflow: ['push', 'promote', 'run', 'webhook-test', 'archive', 'restore'],
 }
 
 /** 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'],
+  app: ['promote', 'rollback'],
   blueprint: ['publish'],
   workflow: ['promote'],
 }
@@ -97,9 +99,9 @@ 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'],
+  // `app deploy` names nothing (the folder is the app); `app promote` and
+  // `app rollback` name a DEPLOYMENT. The app itself is the project's, which the pane knows.
+  app: ['deploy', 'promote', 'rollback', 'unpin', 'save', 'add'],
 }
 
 /**
@@ -122,7 +124,7 @@ export const BOOLEAN_FLAGS = new Set([
   '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',
-  'skip-build-check',
+  'skip-build-check', 'prod', 'preview', 'undo', 'build',
 ])
 
 /**
@@ -401,9 +403,10 @@ export function parseFronteraCommands(line: string): ParsedFronteraCommand[] {
         : (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'))
+      // `function deploy` builds and promotes in one act unless told not to;
+      // `app deploy` makes a preview unless `--prod` (and `--prod --no-promote` stages it).
+      || (kind === 'automation' && verb === 'deploy' && !flags.has('no-promote'))
+      || (kind === 'app' && verb === 'deploy' && flags.has('prod') && !flags.has('no-promote'))
     out.push({ kind, verb, ref, live })
   }
   return out

package/src/function-outside-imports.ts

@@ -0,0 +1,89 @@
+import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { dirname, join, posix, relative, resolve, sep } from 'node:path'
+
+import { isExcluded, type SourceFile } from './packaging'
+
+/**
+ * The files a Function imports from outside its own project folder.
+ *
+ * A Function deployed from its folder (`functions/<slug>/`) may import a
+ * helper beside it (`../../shared/eligibility` from `src/index.ts`). The
+ * bundle holds that code, but its source archive is the folder alone, so a
+ * pull would bring a Function that no longer builds. Each such file travels
+ * in the archive under `frontera-imports/`, by its path from the folder with
+ * every `..` as `__up__` (`frontera-imports/__up__/shared/eligibility.ts`),
+ * and a pull writes it back where the import finds it.
+ *
+ * Only files the code imports, by relative path, and never above the
+ * solution (the nearest folder with `frontera.yaml`, else two folders above
+ * the Function's): the bundle already carries their code.
+ */
+
+export const OUTSIDE_DIR = 'frontera-imports'
+const UP = '__up__'
+
+const RELATIVE_IMPORT = /(?:from|import)\s*\(?\s*['"](\.{1,2}\/[^'"]+)['"]/g
+const CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs|json)$/
+const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.js', '.mjs', '.json', '/index.ts', '/index.js']
+
+/** `../shared/x.ts` (from the folder) → `frontera-imports/__up__/shared/x.ts`. */
+export function outsidePath(fromFolder: string): string {
+  return `${OUTSIDE_DIR}/${posix.normalize(fromFolder).split('/').map((s) => (s === '..' ? UP : s)).join('/')}`
+}
+
+/** `frontera-imports/__up__/shared/x.ts` → `../shared/x.ts`; null for any other archive path. */
+export function fromOutsidePath(archivePath: string): string | null {
+  if (!archivePath.startsWith(`${OUTSIDE_DIR}/`)) return null
+  const rel = archivePath.slice(OUTSIDE_DIR.length + 1).split('/').map((s) => (s === UP ? '..' : s)).join('/')
+  return rel.startsWith('../') ? rel : null
+}
+
+function solutionRoot(projectRoot: string): string {
+  for (let dir = projectRoot; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'frontera.yaml'))) return dir
+    if (dirname(dir) === dir) break
+  }
+  return dirname(dirname(projectRoot))
+}
+
+const within = (root: string, path: string) => path === root || path.startsWith(`${root}${sep}`)
+
+/**
+ * The files outside `projectRoot` that `entry` imports, followed through the
+ * files it imports inside it too, as archive entries under `frontera-imports/`.
+ */
+export function outsideImports(projectRoot: string, entry: string): SourceFile[] {
+  const root = resolve(projectRoot)
+  const bound = resolve(solutionRoot(root))
+  const seen = new Set<string>()
+  const out: SourceFile[] = []
+  const read = (path: string): string | null => {
+    try {
+      return existsSync(path) && lstatSync(path).isFile() ? readFileSync(path, 'utf8') : null
+    } catch {
+      return null
+    }
+  }
+  const visit = (file: string) => {
+    if (seen.has(file)) return
+    const text = read(file)
+    if (text === null) return
+    seen.add(file)
+    if (!within(root, file)) {
+      const rel = relative(root, file).split(sep).join('/')
+      if (CODE.test(file) && !isExcluded(rel.replace(/^(\.\.\/)+/, ''))) out.push({ rel: outsidePath(rel), bytes: new TextEncoder().encode(text) })
+    }
+    for (const m of text.matchAll(RELATIVE_IMPORT)) {
+      const base = resolve(dirname(file), m[1]!)
+      if (!within(bound, base) || base.split(sep).includes('node_modules')) continue
+      const found = EXTENSIONS.map((ext) => `${base}${ext}`).find((c) => read(c) !== null)
+      if (!found) continue
+      visit(found)
+      // A JavaScript file's types beside it travel with it (a module a pull recovered from a
+      // deployed bundle is a `.js` typed by its `.d.ts`), so the next pull still typechecks.
+      if (found.endsWith('.js')) visit(`${found.slice(0, -'.js'.length)}.d.ts`)
+    }
+  }
+  visit(resolve(entry))
+  return out
+}