Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
refactor(cli): streamline the author workflow
kashorin363635a163fb
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.mdindex c3fe42cd..1eb3538a 100644--- a/.agents/skills/narratage/SKILL.md+++ b/.agents/skills/narratage/SKILL.md@@ -6,7 +6,7 @@ description: Author, check, plan, build, inspect, and retrieve Narratage/SVML vi# NarratageUse this entrypoint for work in the `narratage` repository. Keep `.svml` Author Source, `.svrun` Run-Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.+Source, and the declarative `svml.runtime.json` Runtime Profile separate.## Route the task@@ -24,20 +24,20 @@ Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.`references/runtime.md`; diagnose and start the durable Runtime, `check` Author Source, `plan`before paid work, then submit, inspect, and retrieve the Build.-## Required loop+## Ordinary loop```bash-node --run narratage -- packages sync path/to/build.svrun --runtime path/to/svml.runtime.json --root .-node --run narratage -- doctor path/to/svml.runtime.json-node --run narratage -- check path/to/main.svml --runtime path/to/svml.runtime.json --root .-node --run narratage -- plan path/to/build.svrun --runtime path/to/svml.runtime.json --root .+node --run narratage -- plan path/to/build.svrun --runtime path/to/svml.runtime.jsonnode --run narratage -- build path/to/build.svrun --runtime path/to/svml.runtime.json \- --root . --build-id my-build-001 --follow+ --build-id my-build-001 --follownode --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.jsonnode --run narratage -- get my-build-001 --runtime path/to/svml.runtime.json \--name final.video --to path/to/output/final.mp4```+Run `packages sync` after import or Runtime package selections change. Use `check` while editing and+`doctor` for deployment setup or diagnosis; do not impose either as ceremony before every Build.+Treat `--follow` as an observer: stopping it does not stop the durable Build. Use `runtime down`only to stop the Worker and Runtime-owned programs; it does not cancel Builds or remote Providerwork.diff --git a/.agents/skills/narratage/references/environment.md b/.agents/skills/narratage/references/environment.mdindex 62695a3e..b9802438 100644--- a/.agents/skills/narratage/references/environment.md+++ b/.agents/skills/narratage/references/environment.md@@ -46,7 +46,7 @@ After intentionally installing, removing or changing selected packages, refreshproject locks in one reviewed action:```text-node --run narratage -- packages sync build.svrun --runtime svml.runtime.json --root .+node --run narratage -- packages sync build.svrun --runtime svml.runtime.json```This command derives Author roots from that Run/Author Source closure and Runtime roots from thediff --git a/.agents/skills/narratage/references/playbooks/craft/production-gates.md b/.agents/skills/narratage/references/playbooks/craft/production-gates.mdindex 3abb7cb2..0a057e6e 100644--- a/.agents/skills/narratage/references/playbooks/craft/production-gates.md+++ b/.agents/skills/narratage/references/playbooks/craft/production-gates.md@@ -8,7 +8,7 @@ Use staged Run Sources so unreviewed expensive outputs cannot silently feed lateand factual claims before writing prompts.- Give every planned shot one job: hook, context, evidence, mechanism, reaction, payoff, transition,or CTA. Delete shots with no distinct job.-- Confirm credentials, Runtime Profile, package locks, model limits, resolution, and permissions.+- Confirm credentials, Runtime Profile, package locks, model limits, resolution, and Endpoint prerequisites.Run `doctor`, `check`, and `plan` before the first paid Build.## Gate 1: build and review reference imagesdiff --git a/.agents/skills/narratage/references/runtime.md b/.agents/skills/narratage/references/runtime.mdindex 935cce7c..9aa931c5 100644--- a/.agents/skills/narratage/references/runtime.md+++ b/.agents/skills/narratage/references/runtime.md@@ -6,20 +6,12 @@ Build, retrieval, and reuse syntax. Use this file as the operational checklist.## Execute the lifecycle```bash-node --run narratage -- packages sync path/to/build.svrun \- --runtime path/to/svml.runtime.json --root .-node --run narratage -- doctor path/to/svml.runtime.json-node --run narratage -- runtime up path/to/svml.runtime.json-node --run narratage -- runtime status path/to/svml.runtime.json--node --run narratage -- check path/to/main.svml \- --runtime path/to/svml.runtime.json --root .node --run narratage -- plan path/to/build.svrun \- --runtime path/to/svml.runtime.json --root .+ --runtime path/to/svml.runtime.jsonnode --run narratage -- build path/to/build.svrun \--runtime path/to/svml.runtime.json \- --root . --build-id my-build-001 --follow+ --build-id my-build-001 --follownode --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.jsonnode --run narratage -- get my-build-001 \@@ -27,6 +19,10 @@ node --run narratage -- get my-build-001 \--name final.video --to path/to/output/final.mp4```+Use `packages sync` only after package selection changes. Use `check` during authoring and `doctor`+or `runtime status` when diagnosing the deployment. `build` already ensures the detached Worker+and demanded managed services are available.+Use `runtime logs` to diagnose the Worker and managed programs. Use `runtime down` for an orderlystop. It stops the Worker from claiming more leases and stops Runtime-owned programs, but preservesdurable Builds and does not cancel remote Provider work.diff --git a/README.md b/README.mdindex 33d26500..9288ea04 100644--- a/README.md+++ b/README.md@@ -115,12 +115,10 @@ corepack enablepnpm install --frozen-lockfilenode --run narratage -- check examples/talking-film-graph-check/main.svml \- --package-lock examples/talking-film-graph-check/svml.packages.lock \- --root .+ --package-lock examples/talking-film-graph-check/svml.packages.locknode --run narratage -- plan examples/talking-film-graph-check/build.svrun \- --package-lock examples/talking-film-graph-check/svml.packages.lock \- --root .+ --package-lock examples/talking-film-graph-check/svml.packages.lock````check` verifies the Author Source and prints its typed outputs. `plan` shows the exact demanded@@ -178,14 +176,13 @@ lightweight launcher from the project directory:```bashcd /path/to/my-video+# Setup once, then repeat only after imports or Runtime package choices change./path/to/narratage/narratage packages sync build.svrun \- --runtime svml.runtime.json --root .+ --runtime svml.runtime.json-/path/to/narratage/narratage doctor svml.runtime.json-/path/to/narratage/narratage check main.svml \- --runtime svml.runtime.json --root .+# See the exact work selected by this Run./path/to/narratage/narratage plan build.svrun \- --runtime svml.runtime.json --root .+ --runtime svml.runtime.json/path/to/narratage/narratage build build.svrun \--runtime svml.runtime.json \@@ -200,7 +197,8 @@ cd /path/to/my-video`build` submits durable work and ensures the selected Worker is available. `--follow` only observesthat Build; closing the observer does not cancel it. Use `status`, `queue`, `operations` and-`inspect` to see what is happening.+`inspect` to see what is happening. `check` is useful while editing source; `doctor` diagnoses the+whole deployment when setting up or troubleshooting it. Neither is a ritual before every Build.Read [Run Source & Builds](./docs/quickstart/run.md) before the first paid Build. It covers RuntimeProfiles, credentials, concurrency, cancellation and explicit reuse of previous outputs.diff --git a/docs/guide/develop.md b/docs/guide/develop.mdindex e1354d70..a5d62854 100644--- a/docs/guide/develop.md+++ b/docs/guide/develop.md@@ -56,7 +56,7 @@ narratage/| [Package architecture](./packages.md) | The five layers, dependency rules, package anatomy, facets || [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, activation || [Adding a Provider](./providers.md) | Step-by-step: new Endpoint adapter |-| [Runtime Profile](./runtime-profile.md) | JSON and TypeScript configuration, diagnostics, Build archive |+| [Runtime Profile](./runtime-profile.md) | Declarative CLI configuration, embedding boundary, diagnostics, Build archive || [Caption Playground](./caption-playground.md) | Edit real Caption SVML/SVS with live feedback || [Local services](./services.md) | WhisperX and OpenCV setup || [Testing](./testing.md) | Test runner, patterns, examples, boundary tests |diff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.mdindex e2166179..850c759f 100644--- a/docs/guide/runtime-profile.md+++ b/docs/guide/runtime-profile.md@@ -9,13 +9,6 @@ The Runtime Profile declares *where* a frozen Build executes: the Scheduler andStores, Endpoints, credentials and concurrency. It is deployment configuration, notcreative content—it never enters Author or Run graph identity.-Two forms are supported:--| Form | File | Use case |-|---|---|---|-| Declarative JSON | `svml.runtime.json` | Standard path |-| Executable TypeScript | `svml.runtime.ts` | Advanced embedding API |-## Declarative JSON```json@@ -126,80 +119,12 @@ allowlist can restrict Node code that shares the Host process. Arbitrary communimust wait for a real process/Wasm isolation boundary with enforceable filesystem, network, processand resource controls.-## Executable TypeScript--For advanced embedding, construct the Runtime programmatically:--```typescript-import { join } from "node:path";-import { createFileArtifactStorePackage } from "@narratage/artifact-store-fs";-import { createEnvironmentCredentialStorePackage } from "@narratage/credential-store-env";-import { createLocalExecutionPackage, createProjectLocalRuntime } from "@narratage/local";-import { createKieProvider } from "@narratage/provider-kie";-import { createLocalMediaProvider } from "@narratage/provider-media-local";-import { credentialRef } from "@narratage/runtime";-import { createSqliteRuntimeServicePackage } from "@narratage/store-sqlite";--export default async function createRuntime() {- const root = import.meta.dirname;- const execution = createLocalExecutionPackage("execution");- const state = createSqliteRuntimeServicePackage({- path: join(root, ".svml/runtime.sqlite"),- name: "state",- buildInstance: "state.builds",- operationInstance: "state.operations",- dispatchInstance: "state.dispatch",- journalInstance: "state.journal",- });- const artifacts = createFileArtifactStorePackage({ root: join(root, ".svml/artifacts"), instance: "artifacts" });- const credentials = createEnvironmentCredentialStorePackage({ instance: "credentials.env" });- const endpoints = [- createKieProvider({- instance: "kie.prod",- authority: "kie.prod",- apiKey: credentialRef("env", "KIE_API_KEY"),- defaultConcurrency: 2,- }),- createLocalMediaProvider({- instance: "media.prod",- authority: "media.prod",- defaultConcurrency: 2,- }),- ];-- return await createProjectLocalRuntime({- root,- packageLock: "./svml.packages.lock",- runtimeServices: [execution, state, artifacts, credentials],- runtimeSelection: {- scheduler: "execution.scheduler",- worker: "execution.worker",- stores: {- build: "state.builds",- operations: "state.operations",- dispatch: "state.dispatch",- journal: "state.journal",- artifacts: "artifacts",- credentials: ["credentials.env"],- },- },- endpoints,- scheduling: {- maxConcurrency: 4,- },- });-}-```--Pass either form to `--runtime`:--```bash-node --run narratage -- build build.svrun --runtime ./svml.runtime.json-node --run narratage -- build build.svrun --runtime ./svml.runtime.ts-```+## Embedding API-Both forms describe the same explicit assembly. The TypeScript form is trusted embedding code, not-a source-language escape hatch or a place for author intent.+The CLI deliberately accepts only declarative JSON Profiles. A server or application embedding+Narratage may assemble the same Scheduler, Worker, Store and Endpoint roles directly through+`@narratage/local`. That assembly is application code—not another Profile syntax and not a+source-language escape hatch.## Diagnosticsdiff --git a/docs/quickstart.md b/docs/quickstart.mdindex 965403ee..4f4afbc3 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -41,8 +41,7 @@ alignment, captions, a media Track, text, Film and final rendering.```bashnode --run narratage -- check examples/talking-film-graph-check/main.svml \- --package-lock examples/talking-film-graph-check/svml.packages.lock \- --root .+ --package-lock examples/talking-film-graph-check/svml.packages.lock````check` reads the self-described source, loads only its locked packages and prints the public typed@@ -52,8 +51,7 @@ Now compile the Run Source:```bashnode --run narratage -- plan examples/talking-film-graph-check/build.svrun \- --package-lock examples/talking-film-graph-check/svml.packages.lock \- --root .+ --package-lock examples/talking-film-graph-check/svml.packages.lock````plan` binds the Author Graph and Run Graph, walks backward from `final.video`, and freezes the@@ -98,13 +96,10 @@ lightweight `narratage` launcher from your project directory:cd /path/to/my-video/path/to/narratage/narratage packages sync build.svrun \- --runtime svml.runtime.json --root .+ --runtime svml.runtime.json-/path/to/narratage/narratage doctor svml.runtime.json-/path/to/narratage/narratage check main.svml \- --runtime svml.runtime.json --root ./path/to/narratage/narratage plan build.svrun \- --runtime svml.runtime.json --root .+ --runtime svml.runtime.json```The launcher uses dependencies installed in the Narratage checkout, but Source, SQLite state,@@ -117,7 +112,7 @@ and credentials with your own.## 5. Build and retrieve an output-After `doctor`, `check` and `plan` pass:+After reviewing the plan:```bash/path/to/narratage/narratage build build.svrun \@@ -129,6 +124,9 @@ After `doctor`, `check` and `plan` pass:`build` stores the Build, ensures its Worker is available, and starts only the external programsdeclared by the selected endpoints. `--follow` is an observer; closing it does not stop the Build.+Use `check` while editing a source. Use `doctor` to diagnose a new or broken deployment. They are+safe, but neither is required as a repetitive pre-Build ceremony.+```bash/path/to/narratage/narratage status my-video-001 \--runtime svml.runtime.jsondiff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex 99ac0c7f..d705820e 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -9,13 +9,16 @@ The Author Source defines the video. A Run Source chooses which of its public ouwhich explicit Candidates, if any, should satisfy them. The Runtime Profile chooses the machine,stores and Provider endpoints that execute the resulting plan.-Most work follows the same loop:+Package trust is synchronized once after package selections change:```bash-narratage packages sync build.svrun --runtime svml.runtime.json --root .-narratage doctor svml.runtime.json-narratage check main.svml --runtime svml.runtime.json --root .-narratage plan build.svrun --runtime svml.runtime.json --root .+narratage packages sync build.svrun --runtime svml.runtime.json+```++Ordinary work then follows the short path:++```bash+narratage plan build.svrun --runtime svml.runtime.jsonnarratage build build.svrun --runtime svml.runtime.json --build-id my-video-001 --follownarratage get my-video-001 --runtime svml.runtime.json --name final.video --to output/final.mp4```@@ -23,7 +26,8 @@ narratage get my-video-001 --runtime svml.runtime.json --name final.video --to oThe checked-in source launcher is `/path/to/narratage/narratage`; commands written as `narratage`on this page mean that launcher or the future installed CLI.-Only `build` submits work. `packages sync`, `doctor`, `check` and `plan` are safe preparation steps.+Only `build` submits work. `plan` is the normal preview. `check` is an editing aid; `doctor` is a+deployment diagnostic. They are safe to run, but not mandatory ceremony before every Build.```textmain.svml author meaning@@ -187,11 +191,10 @@ human-supplied result uses the same mechanism.## Runtime Profile-The Runtime Profile (`svml.runtime.json`) tells the system **where** to run each type of work:--Declarative `svml.runtime.json` is the standard form. Advanced trusted embedding may instead use-`svml.runtime.ts`; both are passed to `--runtime` and assemble the same explicit roles. See the-complete [Runtime Profile guide](../guide/runtime-profile.md).+The declarative Runtime Profile (`svml.runtime.json`) tells the CLI **where** to run each type of+work. Applications embedding Narratage may assemble the same Runtime roles through+`@narratage/local`, but executable modules are not CLI Profiles. See the complete+[Runtime Profile guide](../guide/runtime-profile.md).```json{@@ -413,7 +416,7 @@ After installing or updating packages, explicitly accept both declared closures:```bashnode --run narratage -- packages sync examples/talking-head-aroll/build.svrun \- --runtime examples/talking-head-aroll/svml.runtime.json --root .+ --runtime examples/talking-head-aroll/svml.runtime.json```The Author and Run sources choose author packages. The Runtime Profile chooses environment@@ -436,12 +439,12 @@ Doctor is intentionally a **full profile audit**. For the environment required b```bashnode --run narratage -- check examples/talking-head-aroll/main.svml \- --runtime examples/talking-head-aroll/svml.runtime.json --root .+ --runtime examples/talking-head-aroll/svml.runtime.json``````bashnode --run narratage -- plan examples/talking-head-aroll/build.svrun \- --runtime examples/talking-head-aroll/svml.runtime.json --root .+ --runtime examples/talking-head-aroll/svml.runtime.json```Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the@@ -457,7 +460,6 @@ commands manage external programs only and do not own the Worker lifecycle.```bashnode --run narratage -- build examples/talking-head-aroll/build.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --root . \--build-id my-film-001 \--follow```@@ -515,7 +517,7 @@ above), then submit it:```bashnode --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --root . --build-id my-film-reuse-001 --follow+ --build-id my-film-reuse-001 --follow```### 7. Diagnose or stop the local Runtimediff --git a/docs/zh/guide/develop.md b/docs/zh/guide/develop.mdindex b8b629f1..af708e89 100644--- a/docs/zh/guide/develop.md+++ b/docs/zh/guide/develop.md@@ -56,7 +56,7 @@ narratage/| [包架构](./packages.md) | 五个层次、依赖规则、包的构成、facets || [添加 Author 包](./author-packages.md) | 分步说明:新增组件、Surface、activation || [添加 Provider](./providers.md) | 分步说明:新增 Endpoint 适配器 |-| [Runtime Profile](./runtime-profile.md) | JSON 与 TypeScript 配置、诊断、Build 归档 |+| [Runtime Profile](./runtime-profile.md) | 声明式 CLI 配置、嵌入边界、诊断、Build 归档 || [字幕 Playground](./caption-playground.md) | 直接编辑真实字幕 SVML/SVS 并实时预览 || [本地服务](./services.md) | WhisperX 与 OpenCV 的搭建 || [测试](./testing.md) | 测试运行器、写法、示例、boundary tests |diff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.mdindex 68b3b510..1e5a6b95 100644--- a/docs/zh/guide/runtime-profile.md+++ b/docs/zh/guide/runtime-profile.md@@ -134,8 +134,7 @@ Build 取消先关闭准入;Operation 取消只抑制那个精确实现。`acc不等于已停止;系统继续协调到 `confirmed`、`unsupported`、`too-late` 或自然结束。迟到的付费产物继续归档,但不能进入被抑制的 Core 分支。Runtime 不会因此偷偷换 Candidate 或 Provider。-## 高级 TypeScript 嵌入+## 嵌入 API-`svml.runtime.ts` 仍可用于可信的私有部署代码,但必须构造与选择同样完整的一组 Runtime-service package。它不是作者语言逃生口,也没有隐藏默认值。仓库中的-`examples/talking-film-live/svml.runtime.ts` 是可执行参考。+CLI 只接受声明式 JSON Profile。嵌入 Narratage 的应用可以通过 `@narratage/local` 直接组装+相同的 Runtime 角色;这属于应用代码,而不是第二种 CLI Profile 文件。diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex 97a19a1b..77742e9b 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -40,8 +40,7 @@ pnpm install --frozen-lockfile```bashnode --run narratage -- check examples/talking-film-graph-check/main.svml \- --package-lock examples/talking-film-graph-check/svml.packages.lock \- --root .+ --package-lock examples/talking-film-graph-check/svml.packages.lock````check` 会读取自描述的源码,只加载锁中允许的包,并列出这份 Author Source 声明的公共类型化输出。@@ -50,8 +49,7 @@ node --run narratage -- check examples/talking-film-graph-check/main.svml \```bashnode --run narratage -- plan examples/talking-film-graph-check/build.svrun \- --package-lock examples/talking-film-graph-check/svml.packages.lock \- --root .+ --package-lock examples/talking-film-graph-check/svml.packages.lock````plan` 会连接 Author Graph 和 Run Graph,从 `final.video` 反向找到真正需要的子图,冻结将要使用的@@ -95,13 +93,10 @@ Runtime Profile 说明在哪里做。cd /path/to/my-video/path/to/narratage/narratage packages sync build.svrun \- --runtime svml.runtime.json --root .+ --runtime svml.runtime.json-/path/to/narratage/narratage doctor svml.runtime.json-/path/to/narratage/narratage check main.svml \- --runtime svml.runtime.json --root ./path/to/narratage/narratage plan build.svrun \- --runtime svml.runtime.json --root .+ --runtime svml.runtime.json```启动器使用 Narratage 仓库已经安装好的依赖,但源码、SQLite 状态、Artifact 和输出都会留在你的项目里。@@ -113,7 +108,7 @@ cd /path/to/my-video## 5. Build 并取出结果-在 `doctor`、`check` 和 `plan` 全部通过之后:+检查并确认计划之后:```bash/path/to/narratage/narratage build build.svrun \@@ -125,6 +120,9 @@ cd /path/to/my-video`build` 会持久化这次 Build、确保对应 Worker 可用,并只启动所选 Endpoint 声明的外部程序。`--follow` 只是观察器;关掉它不会停止 Build。+编辑源码时使用 `check`;配置或排查部署时使用 `doctor`。它们都不会提交工作,但也不是每次+Build 前必须重复的仪式。+```bash/path/to/narratage/narratage status my-video-001 \--runtime svml.runtime.jsondiff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdindex 7fff862a..1cfc2c2e 100644--- a/docs/zh/quickstart/run.md+++ b/docs/zh/quickstart/run.md@@ -151,8 +151,8 @@ Core 不再给 Candidate 标注 `exact` 或 `substitute`。选择 Candidate 本Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类型的工作:-声明式 `svml.runtime.json` 是标准形式。高级可信嵌入也可以使用 `svml.runtime.ts`;两种形式-都通过 `--runtime` 传入,并装配同样显式的角色。完整说明见+CLI 只接受声明式 `svml.runtime.json`。嵌入 Narratage 的应用可以通过 `@narratage/local`+直接组装相同的 Runtime 角色;应用代码不是另一种 CLI Profile。完整说明见[Runtime Profile 指南](../guide/runtime-profile.md)。```json@@ -366,7 +366,7 @@ Runtime 状态、归档 Artifact 和 lock 仍全部留在 `/work/my-film`。只```bashnode --run narratage -- packages sync examples/talking-head-aroll/build.svrun \- --runtime examples/talking-head-aroll/svml.runtime.json --root .+ --runtime examples/talking-head-aroll/svml.runtime.json```Author/Run Source 选择作者包,Runtime Profile 选择环境包;该命令只闭包并锁定这两组声明,@@ -388,7 +388,7 @@ Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭```bashnode --run narratage -- check examples/talking-head-aroll/main.svml \- --runtime examples/talking-head-aroll/svml.runtime.json --root .+ --runtime examples/talking-head-aroll/svml.runtime.json``````bashdiff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.mdindex 751784d4..1ca57bdd 100644--- a/examples/talking-film-live/README.md+++ b/examples/talking-film-live/README.md@@ -60,8 +60,8 @@ does not cancel the Build.`build.svrun` owns the Targets and any explicit Candidate selections. `svml.runtime.json` owns Provider instances,credentials and concurrency. The Build archives all accepted intermediate Records and referencedArtifacts even when no destination path is requested. `get` only makes an optional copy of the-already archived named target. The existing `svml.runtime.ts` shows the advanced executable-embedding API and remains supported.+already archived named target. The CLI accepts the declarative JSON Runtime Profile shown here;+applications that embed Narratage assemble Runtime roles directly through `@narratage/local`.To reuse the paid shot outputs from a verified earlier Build, add two zero-input Build RecordCandidates and their explicit Satisfaction edges to another `.svrun`:diff --git a/examples/talking-film-live/svml.runtime.ts b/examples/talking-film-live/svml.runtime.tsdeleted file mode 100644index 17e65671..00000000--- a/examples/talking-film-live/svml.runtime.ts+++ /dev/null@@ -1,89 +0,0 @@-import { fileURLToPath } from "node:url";-import { join } from "node:path";--import { createFileArtifactStorePackage } from "@narratage/artifact-store-fs";-import { createEnvironmentCredentialStorePackage } from "@narratage/credential-store-env";-import { createLocalExecutionPackage, createProjectLocalRuntime } from "@narratage/local";-import { createGoogleVertexCaptionProvider } from "@narratage/provider-google-vertex";-import { createLocalHyperframesProvider } from "@narratage/provider-hyperframes-local";-import { createKieProvider } from "@narratage/provider-kie";-import { createLocalMediaProvider } from "@narratage/provider-media-local";-import { createLocalWhisperXProvider } from "@narratage/provider-whisperx-local";-import { credentialRef } from "@narratage/runtime";-import { createSqliteRuntimeServicePackage } from "@narratage/store-sqlite";--export default async function createTalkingFilmRuntime() {- const root = fileURLToPath(new URL(".", import.meta.url));- const project = process.env.GOOGLE_CLOUD_PROJECT?.trim();- if (!project) throw new Error("GOOGLE_CLOUD_PROJECT is required for the explicit Vertex Gemini Caption Provider");-- const endpoints = [- createKieProvider({- instance: "kie.talking-film",- authority: "kie.talking-film",- apiKey: credentialRef("env", "KIE_API_KEY"),- defaultConcurrency: 2,- }),- createLocalMediaProvider({- instance: "media.talking-film",- authority: "media.talking-film",- defaultConcurrency: 2,- }),- createLocalWhisperXProvider({- instance: "whisperx.talking-film",- authority: "whisperx.talking-film",- defaultConcurrency: 1,- }),- createGoogleVertexCaptionProvider({- project,- instance: "vertex.talking-film",- authority: "vertex.talking-film",- credentialsJson: credentialRef("env", "GOOGLE_APPLICATION_CREDENTIALS_JSON"),- defaultConcurrency: 1,- }),- createLocalHyperframesProvider({- instance: "hyperframes.talking-film",- authority: "hyperframes.talking-film",- workers: 2,- quality: "standard",- defaultConcurrency: 1,- }),- ];-- const execution = createLocalExecutionPackage("execution");- const state = createSqliteRuntimeServicePackage({- path: join(root, ".svml", "state.sqlite"),- name: "state",- buildInstance: "state.builds",- operationInstance: "state.operations",- dispatchInstance: "state.dispatch",- journalInstance: "state.journal",- });- const artifacts = createFileArtifactStorePackage({- root: join(root, ".svml", "artifacts"),- instance: "artifacts",- });- const credentials = createEnvironmentCredentialStorePackage({ instance: "credentials.env" });-- return await createProjectLocalRuntime({- root,- packageLock: "./svml.packages.lock",- runtimeServices: [execution, state, artifacts, credentials],- runtimeSelection: {- scheduler: "execution.scheduler",- worker: "execution.worker",- stores: {- build: "state.builds",- operations: "state.operations",- dispatch: "state.dispatch",- journal: "state.journal",- artifacts: "artifacts",- credentials: ["credentials.env"],- },- },- endpoints,- scheduling: {- maxConcurrency: 4,- },- });-}diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex 0b2c43cc..750bdd16 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -1,5 +1,4 @@import { dirname, extname, resolve } from "node:path";-import { pathToFileURL } from "node:url";import { readFile } from "node:fs/promises";import type {@@ -12,7 +11,7 @@ import type {import type { NodeCompiledSourceClosure } from "@narratage/compiler-node";import type { BuildCatalogDescriptor, CapacityReservation, OperationProgress } from "@narratage/runtime";import { isDigest } from "@narratage/protocol";-import type { BuildState, CapabilityRef } from "@narratage/protocol";+import type { BuildState, CapabilityRef, TypeRef } from "@narratage/protocol";import { parseSourceHeader } from "@narratage/source";import {createNodePackageLock,@@ -230,7 +229,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {}if (item === "--runtime") {const value = rest[index + 1];- if (value === undefined || value.startsWith("--")) throw new Error("--runtime requires a Runtime Profile or trusted config module");+ if (value === undefined || value.startsWith("--")) throw new Error("--runtime requires a declarative JSON Runtime Profile");runtime = resolve(value);index += 1;continue;@@ -457,16 +456,16 @@ function usage(): string {" narratage gc <runtime-profile.json> [--apply]"," narratage check <self-described-source> [--runtime profile.json] [--package-lock file] [--root workspace] [--asset-root directory]"," narratage plan <run-source> [--runtime profile.json] [--package-lock file] [--root workspace] [--asset-root directory]",- " narratage build <run-source> --runtime profile.json|./svml.runtime.ts [--root workspace] [--asset-root directory] [--follow] [--no-services]",- " narratage status <build-id> --runtime profile.json|./svml.runtime.ts",- " narratage builds --runtime profile.json|./svml.runtime.ts",- " narratage history [source-output-name] --runtime profile.json|./svml.runtime.ts [--source author.svml]",- " narratage inspect <build-id> --runtime profile.json|./svml.runtime.ts",- " narratage get <build-id> --runtime profile.json|./svml.runtime.ts [--name source-name|--record record-id|--output logical-output-id|--artifact digest] [--to path]",- " narratage operations <build-id> --runtime profile.json|./svml.runtime.ts",- " narratage operation <operation-id> --runtime profile.json|./svml.runtime.ts",- " narratage cancel build <build-id> --runtime profile.json|./svml.runtime.ts [--reason text]",- " narratage cancel operation <operation-id> --runtime profile.json|./svml.runtime.ts [--reason text]",+ " narratage build <run-source> --runtime profile.json [--root workspace] [--asset-root directory] [--follow] [--no-services]",+ " narratage status <build-id> --runtime profile.json",+ " narratage builds --runtime profile.json",+ " narratage history [source-output-name] --runtime profile.json [--source author.svml]",+ " narratage inspect <build-id> --runtime profile.json",+ " narratage get <build-id> --runtime profile.json [--name source-name|--record record-id|--output logical-output-id|--artifact digest] [--to path]",+ " narratage operations <build-id> --runtime profile.json",+ " narratage operation <operation-id> --runtime profile.json",+ " narratage cancel build <build-id> --runtime profile.json [--reason text]",+ " narratage cancel operation <operation-id> --runtime profile.json [--reason text]"," narratage auth status|login|logout <endpoint-instance> --runtime profile.json [--slot name] [--from secret-file]","","output:",@@ -474,25 +473,13 @@ function usage(): string {].join("\n");}-function isLocalRuntime(value: unknown): value is LocalRuntime {- return typeof value === "object"- && value !== null- && "build" in value- && typeof value.build === "function"- && "builds" in value- && typeof value.builds === "function"- && "readArtifact" in value- && typeof value.readArtifact === "function"- && "openArtifact" in value- && typeof value.openArtifact === "function"- && "credentials" in value- && typeof value.credentials === "function"- && "putCredential" in value- && typeof value.putCredential === "function"- && "deleteCredential" in value- && typeof value.deleteCredential === "function"- && "close" in value- && typeof value.close === "function";+function requireJsonRuntimeProfile(path: string): void {+ if (extname(path) !== ".json") {+ throw new Error(+ `Narratage CLI Runtime Profiles are declarative JSON files; ${path} is not .json. `+ + "Programmatic Runtime assembly belongs in an application that embeds @narratage/local.",+ );+ }}function createCatalogDescriptor(options: {@@ -603,13 +590,18 @@ async function preflightPlan(} as const;}-function assertPreflight(preflight: Awaited<ReturnType<typeof preflightPlan>>): void {+function assertPreflight(+ preflight: Awaited<ReturnType<typeof preflightPlan>>,+ ignoredCodes: ReadonlySet<string> = new Set(),+): void {if (preflight === undefined || preflight.ok) return;- const errors = preflight.diagnostics.filter((item) => item.severity === "error");+ const errors = preflight.diagnostics.filter((item) =>+ item.severity === "error" && !ignoredCodes.has(item.code));+ if (errors.length === 0) return;throw new Error([`Runtime preflight failed for ${errors.length} demanded deployment requirement${errors.length === 1 ? "" : "s"}:`,...errors.map((item) => ` ${item.code}${item.subject === undefined ? "" : ` (${item.subject})`}: ${item.message}`),- "No Build was submitted and no external request was made.",+ "No Build was submitted and no external capability request was made.",].join("\n"));}@@ -618,35 +610,22 @@ async function loadLocalRuntime(distribution: CliDistribution,implementationPackages?: LoadedNodePackageSet,): Promise<LocalRuntime> {- if (extname(path) === ".json") {- return await distribution.createRuntimeFromConfig(path, {- ...(implementationPackages === undefined ? {} : { implementationPackages }),- });- }- // A Runtime config is trusted executable deployment code, never an Author Frontend or .svml import.- const imported = await import(pathToFileURL(path).href) as {- readonly default?: unknown;- readonly runtime?: unknown;- };- let candidate = imported.default ?? imported.runtime;- if (typeof candidate === "function") candidate = await candidate();- else candidate = await candidate;- if (!isLocalRuntime(candidate)) {- throw new Error(`Runtime config ${path} must export a LocalRuntime or a function that creates one`);- }- return candidate;+ requireJsonRuntimeProfile(path);+ return await distribution.createRuntimeFromConfig(path, {+ ...(implementationPackages === undefined ? {} : { implementationPackages }),+ });}async function loadRuntimeControl(path: string,distribution: CliDistribution,): Promise<LocalRuntimeControl> {- if (extname(path) === ".json") {- return await distribution.createRuntimeControlFromConfig(path);- }- // Trusted executable Runtime modules cannot be partially inspected without- // executing their own assembly. They retain the full-Runtime fallback.- return await loadLocalRuntime(path, distribution);+ requireJsonRuntimeProfile(path);+ return await distribution.createRuntimeControlFromConfig(path);+}++function displayType(type: TypeRef): string {+ return `${type.module.name}@${type.module.version}/${type.name}`;}function submissionStatus(@@ -926,6 +905,7 @@ export async function runCli(throw new Error("history requires an output name or --source path");}assertCommandOptions(args);+ if (args.runtime !== undefined) requireJsonRuntimeProfile(args.runtime);if (args.command === "lock-packages") {const exact = args.packages.length > 0;const mutation = args.addPackages.length > 0 || args.removePackages.length > 0;@@ -1133,12 +1113,15 @@ export async function runCli(runtime: { path: selection.runtimePackageLock, digest: runtimeAfter.digest, difference: runtime },}, changed ? "Project package locks synchronized" : "Project package locks already current",changed ? "success" : "info", [- ["Run", source], ["Profile", profile], ["Package root", packageRoot],- ["Author roots", String(sourceSelection.selected.length)],- ["Runtime roots", String(runtimePackages.length)],- ["Author changes", String(author.added.length + author.removed.length + author.changed.length)],- ["Runtime changes", String(runtime.added.length + runtime.removed.length + runtime.changed.length)],+ ["Run", source], ["Profile", profile],+ ["Author packages", String(sourceSelection.selected.length)],+ ["Runtime packages", String(runtimePackages.length)],+ ["Updated entries", String(author.added.length + author.removed.length + author.changed.length+ + runtime.added.length + runtime.removed.length + runtime.changed.length)],], args.verbose ? [+ `Package root ${packageRoot}`,+ ...sourceSelection.selected.map((item) => `Author selected ${item}`),+ ...runtimePackages.map((item) => `Runtime selected ${item}`),...author.changed.map((item) => `Author changed ${item}`),...author.added.map((item) => `Author added ${item}`),...author.removed.map((item) => `Author removed ${item}`),@@ -1155,6 +1138,7 @@ export async function runCli(throw new Error("doctor reads all deployment selection from the Runtime Profile itself");}const profile = resolve(args.file!);+ requireJsonRuntimeProfile(profile);const result = await distribution.doctorRuntimeConfig(profile);const machine = {format: "narratage.cli-doctor@1" as const,@@ -1178,6 +1162,7 @@ export async function runCli(throw new Error("--max-wait-ms applies to services up");}const profile = resolve(args.file!);+ requireJsonRuntimeProfile(profile);const result = args.action === "up"? await distribution.externalServices.up(profile, {...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),@@ -1213,6 +1198,7 @@ export async function runCli(throw new Error("runtime takes up, down, status or logs");}const profile = resolve(args.file!);+ requireJsonRuntimeProfile(profile);if (args.action === "up") {// Validate the exact Runtime Revision against unfinished work before replacing a stale Worker// or starting external programs. A refusal must leave the old execution environment intact.@@ -1612,10 +1598,11 @@ export async function runCli(} else if (args.command === "inspect") {const status = await runtime.status(args.file!);if (status.build === undefined) throw new Error(`Build ${args.file} does not exist`);+ const archive = inspectBuild(status.build.state, status.catalog);const machine = {build: status.build.build,revision: status.build.revision,- archive: inspectBuild(status.build.state, status.catalog),+ archive,operations: status.operations.map((operation) => ({id: operation.id,command: operation.command,@@ -1628,10 +1615,38 @@ export async function runCli(...(operation.failure === undefined ? {} : { failure: operation.failure }),})),};+ const aliases = archive.presentation?.aliases ?? [];+ const aliasByOutput = new Map(aliases.flatMap((alias) =>+ alias.ref.kind === "logical-output" ? [[alias.ref.id, alias] as const] : []));+ const recordById = new Map(archive.records.map((record) => [record.id, record]));+ const targetOutputs = new Set(archive.targets.map((target) => target.output));+ const targetLines = archive.targets.map((target) => {+ const alias = aliasByOutput.get(target.output);+ const record = target.record === undefined ? undefined : recordById.get(target.record);+ const name = alias?.name ?? target.output;+ if (record === undefined) return `Target ${name} · not accepted`;+ return `Target ${name} · ${displayType(record.type)} · ${record.digest.slice(0, 18)}…`;+ });+ const otherAccepted = archive.demandedOutputs.filter((item) =>+ item.accepted && !targetOutputs.has(item.output));+ const otherLines = args.verbose+ ? otherAccepted.map((item) => {+ const alias = aliasByOutput.get(item.output);+ const record = recordById.get(item.record);+ const name = alias?.name ?? item.output;+ return record === undefined+ ? `Output ${name}`+ : `Output ${name} · ${displayType(record.type)} · ${record.digest.slice(0, 18)}…`;+ })+ : otherAccepted.length === 0+ ? []+ : [`Other accepted outputs ${otherAccepted.length} · use --verbose to list them`];writeOperational(machine, "Build archive detail", "info", [- ["Build", status.build.build], ["Revision", String(status.build.revision)],+ ["Build", status.build.build], ["Status", archive.status],+ ["Targets", String(archive.targets.length)], ["Accepted records", String(archive.records.length)],["Operations", String(status.operations.length)],- ]);+ ...(args.verbose ? [["Revision", String(status.build.revision)] as const] : []),+ ], [...targetLines, ...otherLines]);} else if (args.command === "get") {const status = await runtime.status(args.file!);if (status.build === undefined) throw new Error(`Build ${args.file} does not exist`);@@ -1702,10 +1717,19 @@ export async function runCli(admission: result?.admission,terminal: result?.terminal,};- writeOperational(machine, result === undefined ? "Build not found" : "Build cancellation requested",- result === undefined ? "warning" : "success", [+ const title = result === undefined+ ? "Build not found"+ : result.terminal === "cancelled"+ ? "Build cancelled"+ : result.phase === "terminal"+ ? "Build already finished"+ : "Build cancellation requested";+ writeOperational(machine, title,+ result === undefined ? "warning" : result.phase === "terminal" && result.terminal !== "cancelled" ? "info" : "success", [["Build", args.file!], ["Admission", result?.admission ?? "missing"], ["Phase", result?.phase ?? "missing"],- ]);+ ], result?.phase === "terminal" && result.terminal !== "cancelled"+ ? [`No running work was changed; this Build is already ${result.terminal}.`]+ : []);if (result === undefined) io.setExitCode?.(1);} else if (args.action === "operation") {if (args.file === undefined || !isDigest(args.file)) {@@ -1830,7 +1854,7 @@ export async function runCli(}}if (args.command === "build") {- if (args.runtime === undefined) throw new Error("build requires --runtime with a Runtime Profile or trusted local config module");+ if (args.runtime === undefined) throw new Error("build requires --runtime with a declarative JSON Runtime Profile");const archive = lazyRuntimeArchive(args.runtime, distribution);let loadedRun;try {@@ -1846,7 +1870,12 @@ export async function runCli(}const result = loadedRun.compiler.planCompilation(loadedRun, loadedPackageSet?.lock.digest);const preflight = await preflightPlan(args.runtime, distribution, result.state, loadedPackageSet);- assertPreflight(preflight);+ // A managed program being down is repairable after Runtime validation;+ // every other deployment error fails before we construct execution or+ // start anything. With --no-services, readiness errors remain fatal.+ assertPreflight(preflight, args.noServices+ ? new Set()+ : new Set(["EXTERNAL_SERVICE_DOWN", "EXTERNAL_SERVICE_MISMATCH"]));const runtime = await loadLocalRuntime(args.runtime, distribution, loadedPackageSet);try {const catalog = createCatalogDescriptor({diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.tsindex 23d27c49..fcd23502 100644--- a/packages/cli/src/output.ts+++ b/packages/cli/src/output.ts@@ -183,6 +183,13 @@ function typeName(type: TypeRef): string {return `${type.module.name}@${type.module.version}/${type.name}`;}+/** Frontends may export graph plumbing so later compilers can address it.+ * Keep that machine surface intact, but do not make authors read generated+ * binding names during an ordinary source check. */+function isGeneratedExportName(name: string): boolean {+ return name.includes(".__") || /\.binding-\d+$/u.test(name) || name.endsWith(".bindings");+}+function facts(rows: readonly (readonly [string, string])[], colors: Palette): string[] {const width = Math.max(...rows.map(([name]) => name.length), 0);return rows.map(([name, value]) => ` ${colors.dim(name.padEnd(width))} ${value}`);@@ -232,17 +239,22 @@ function renderAuthorCheck(verbose: boolean,): string {const lines = [heading("success", "Source is valid", io, colors), ""];+ const authorFacing = view.machine.exports.filter((item) => !isGeneratedExportName(item.name));+ const outputs = authorFacing.filter((item) => item.kind === "logical-output");+ const values = authorFacing.filter((item) => item.kind !== "logical-output");+ const readable = verbose ? view.machine.exports : outputs;lines.push(...facts([["Source", shortPath(view.source)],["Frontend", view.frontend],["Modules", String(view.machine.modules.length)],["Units", String(view.machine.units)],- ["Exports", String(view.machine.exports.length)],+ ["Outputs", String(outputs.length)],+ ...(verbose ? [["Values", String(values.length)] as const] : []),["Assets", String(view.machine.sourceAssets.length)],], colors));- if (view.machine.exports.length > 0) {- lines.push("", colors.strong("Exports"));- const ordered = [...view.machine.exports].sort((left, right) => {+ if (readable.length > 0) {+ lines.push("", colors.strong(verbose ? "All exports" : "Runnable outputs"));+ const ordered = [...readable].sort((left, right) => {const leftRank = left.kind === "logical-output" ? 0 : 1;const rightRank = right.kind === "logical-output" ? 0 : 1;return leftRank - rightRank || left.name.localeCompare(right.name);@@ -250,7 +262,8 @@ function renderAuthorCheck(const shown = verbose ? ordered : ordered.slice(0, 12);const width = Math.max(...shown.map((item) => item.name.length));for (const item of shown) {- lines.push(` ${colors.accent(item.name.padEnd(width))} ${typeName(item.type)} ${colors.dim(item.kind)}`);+ lines.push(` ${colors.accent(item.name.padEnd(width))} ${typeName(item.type)}`+ + `${verbose ? ` ${colors.dim(item.kind)}` : ""}`);}if (shown.length < ordered.length) {lines.push(` ${colors.dim(`${ordered.length - shown.length} more · use --verbose for the complete list`)}`);@@ -328,7 +341,7 @@ function renderPlan(["Steps", String(plan.steps.length)],["External requests", String(requestCount)],], colors));- if (grouped.size > 0) {+ if (verbose && grouped.size > 0) {lines.push("", colors.strong("Operations"));const entries = [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right));const countWidth = Math.max(...entries.map(([, count]) => String(count).length));@@ -360,9 +373,11 @@ function renderPlan(const capabilityCount = view.machine.preflight.capabilities.length;lines.push(` ${colors.dim(`Only the ${capabilityCount} demanded ${capabilityCount === 1 ? "capability was" : "capabilities were"} checked.`)}`);}- const visibleSelections = verbose ? plan.selections : [];+ const visibleSelections = verbose+ ? plan.selections+ : plan.selections.filter((selection) => view.candidateNames?.[selection.candidate] !== undefined);if (visibleSelections.length > 0) {- lines.push("", colors.strong("Selections"));+ lines.push("", colors.strong(verbose ? "Selections" : "Run choices"));for (const selection of visibleSelections) {const status = colors.success(glyph(io, "✓", "+"));const output = view.outputNames?.[selection.output] ?? shortOpaque(selection.output);@@ -435,9 +450,15 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi""," narratage check <source> [--runtime <profile>] [--package-lock <lock>] [--root <workspace>] [--asset-root <directory>]",],+ doctor: [+ colors.accent(colors.strong("narratage doctor")),+ colors.dim("Diagnose one complete declarative Runtime Profile without submitting work."),+ "",+ " narratage doctor <runtime-profile.json>",+ ],plan: [colors.accent(colors.strong("narratage plan")),- colors.dim("Freeze the demanded subgraph and expose every selected Candidate and external Need."),+ colors.dim("Freeze the demanded subgraph and expose explicit Run choices and every external Need."),""," narratage plan <run-source> [--runtime <profile>] [--package-lock <lock>] [--root <workspace>] [--asset-root <directory>]","",@@ -478,11 +499,69 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi" narratage queue --runtime <profile> [--watch]"," narratage queue --runtime <profile> --watch --jsonl",],+ builds: [+ colors.accent(colors.strong("narratage builds")),+ colors.dim("List Builds archived by one Runtime Profile."),+ "",+ " narratage builds --runtime <profile>",+ ],+ status: [+ colors.accent(colors.strong("narratage status")),+ colors.dim("Show the current state of one Build and its notable external Operations."),+ "",+ " narratage status <build-id> --runtime <profile>",+ ],+ inspect: [+ colors.accent(colors.strong("narratage inspect")),+ colors.dim("Inspect one Build's targets and accepted archive."),+ "",+ " narratage inspect <build-id> --runtime <profile>",+ ],+ get: [+ colors.accent(colors.strong("narratage get")),+ colors.dim("Read or copy one archived result; copying never reruns work."),+ "",+ " narratage get <build-id> --runtime <profile> [--name <source-name>|--record <id>|--output <id>|--artifact <digest>] [--to <path>]",+ ],history: [colors.accent(colors.strong("narratage history")),colors.dim("Find accepted historical Logical Outputs without selecting them for a new Run."),""," narratage history <output-name> --runtime <profile> [--source <author-source>]",+ " narratage history --source <author-source> --runtime <profile>",+ ],+ operations: [+ colors.accent(colors.strong("narratage operations")),+ colors.dim("List external Operation attempts belonging to one Build."),+ "",+ " narratage operations <build-id> --runtime <profile>",+ ],+ operation: [+ colors.accent(colors.strong("narratage operation")),+ colors.dim("Inspect one exact external Operation realization."),+ "",+ " narratage operation <operation-digest> --runtime <profile>",+ ],+ cancel: [+ colors.accent(colors.strong("narratage cancel")),+ colors.dim("Request cancellation without pretending an external Provider stopped instantly."),+ "",+ " narratage cancel build <build-id> --runtime <profile> [--reason <text>]",+ " narratage cancel operation <operation-digest> --runtime <profile> [--reason <text>]",+ ],+ auth: [+ colors.accent(colors.strong("narratage auth")),+ colors.dim("Manage credentials required by one declared Endpoint instance."),+ "",+ " narratage auth status <endpoint-instance> --runtime <profile> [--slot <name>]",+ " narratage auth login <endpoint-instance> --runtime <profile> [--slot <name>] [--from <secret-file>]",+ " narratage auth logout <endpoint-instance> --runtime <profile> [--slot <name>]",+ ],+ gc: [+ colors.accent(colors.strong("narratage gc")),+ colors.dim("Report unreachable archived Artifacts; delete them only with --apply."),+ "",+ " narratage gc <profile> [--apply]",],packages: [colors.accent(colors.strong("narratage packages")),@@ -509,14 +588,14 @@ export function writeCliHelp(io: CliIo, topic?: string): void {}io.write([colors.accent(colors.strong("Narratage")),- colors.dim("Write the story. Compile the result."),+ colors.dim('"First, there was narration. Then, there were montages."'),"",colors.strong("Typical flow"),- " doctor <profile> audit the complete configured deployment",- " check <source> --runtime <profile> verify author or run intent",- " plan <run-source> --runtime <profile> inspect the exact demanded subgraph",- " build <run-source> --runtime <profile> submit durable work and ensure a Worker",- " queue --runtime <profile> --watch observe shared work without owning it",+ " plan <run-source> --runtime <profile> see exactly what this Run will demand",+ " build <run-source> --runtime <profile> submit durable work; add --follow to watch",+ " get <build-id> --runtime <profile> read or copy an archived result",+ " packages sync ... setup step after package selection changes",+ " doctor <profile> diagnose deployment setup when needed","",colors.strong("Authoring")," check <source> verify one self-described Author or Run source",diff --git a/packages/cli/test/control-commands.test.ts b/packages/cli/test/control-commands.test.tsindex 5785fe80..a3aa6110 100644--- a/packages/cli/test/control-commands.test.ts+++ b/packages/cli/test/control-commands.test.ts@@ -71,6 +71,12 @@ test("command options fail closed instead of being silently ignored", async () =], io, distribution),/doctor already uses the Runtime Profile directory and its declared root; remove --root/u,);+ await assert.rejects(+ async () => await runCli([+ "queue", "--runtime", "/tmp/svml.runtime.ts",+ ], io, distribution),+ /CLI Runtime Profiles are declarative JSON files/u,+ );});test("auth opens only one Endpoint credential control, never the execution Runtime", async () => {diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.tsindex 01f23896..1f66173c 100644--- a/packages/cli/test/output.test.ts+++ b/packages/cli/test/output.test.ts@@ -41,7 +41,7 @@ test("author check renders a compact human summary without dumping identity", ()exports: [{name: "story",type: { module: { name: "@narratage/narrative", version: "1" }, name: "Narrative" },- kind: "record",+ kind: "logical-output",}],},});@@ -81,6 +81,44 @@ test("large author exports are bounded until verbose output is requested", () =>assert.match(capture({ ...human, verbose: true }, presentation), /output-14/u);});+test("author check hides generated graph plumbing without deleting machine exports", () => {+ const machine = {+ format: "narratage.cli-check@1" as const,+ sourceKind: "author" as const,+ ok: true as const,+ sourceClosure: digest,+ moduleClosure: digest,+ graph: digest,+ units: 1,+ sourceAssets: [],+ modules: [],+ exports: [{+ name: "final.video",+ type: { module: { name: "example", version: "1" }, name: "Video" },+ kind: "logical-output",+ }, {+ name: "card.__canvas-frame",+ type: { module: { name: "example", version: "1" }, name: "Frame" },+ kind: "record",+ }, {+ name: "rendered.binding-0001",+ type: { module: { name: "example", version: "1" }, name: "Binding" },+ kind: "record",+ }],+ };+ const presentation = {+ kind: "check-author" as const,+ source: "/project/main.svml",+ frontend: "example@1",+ machine,+ };+ const compact = capture(human, presentation);+ assert.match(compact, /final\.video/u);+ assert.doesNotMatch(compact, /__canvas-frame|binding-0001/u);+ assert.match(capture({ ...human, verbose: true }, presentation), /__canvas-frame/u);+ assert.deepEqual(machine.exports.length, 3);+});+test("verbose human output reveals shortened identities", () => {const output = capture({ ...human, verbose: true }, {kind: "check-author",@@ -120,7 +158,7 @@ test("JSON mode is exact machine data with no terminal decoration", () => {assert.doesNotMatch(output, /\u001b\[/u);});-test("plan groups operations by their declaring module", () => {+test("plan keeps named Run choices visible and leaves graph internals to verbose output", () => {const plan: BuildPlan = {format: "svml.plan@1",id: digest,@@ -154,10 +192,19 @@ test("plan groups operations by their declaring module", () => {outputNames: { "logical:take": "take.video" },candidateNames: { "candidate:preview": "preview" },});- assert.match(output, /2\s+@narratage\/media@1/u);+ assert.match(output, /Run choices/u);+ assert.match(output, /take\.video\s+← preview/u);+ assert.doesNotMatch(output, /Operations/u);assert.match(output, /External requests/u);assert.match(output, /1\s+@narratage\/media@1#inspect/u);assert.doesNotMatch(output, /No external work was started\./u);+ assert.match(capture({ ...human, verbose: true }, {+ kind: "plan",+ machine: { format: "narratage.cli-plan@1", ok: true, plan },+ run: "/project/build.svrun",+ outputNames: { "logical:take": "take.video" },+ candidateNames: { "candidate:preview": "preview" },+ }), /2\s+@narratage\/media@1/u);});test("a plan with no Needs stays compact without knowing any Provider names", () => {@@ -242,3 +289,11 @@ test("command help explains only the selected shell grammar", () => {assert.match(output, /--follow/u);assert.doesNotMatch(output, /Authoring/u);});++test("archive commands have their own help instead of falling back to the global screen", () => {+ let output = "";+ writeCliHelp({ write(text) { output += text; } }, "get");+ assert.match(output, /^narratage get\n/u);+ assert.match(output, /copying never reruns work/u);+ assert.doesNotMatch(output, /Typical flow/u);+});diff --git a/packages/local/src/config.ts b/packages/local/src/config.tsindex 4cb8e066..2d45b4ac 100644--- a/packages/local/src/config.ts+++ b/packages/local/src/config.ts@@ -149,6 +149,11 @@ function serviceSelection(value: unknown): RuntimeServiceSelection {export function parseRuntimeConfig(value: unknown): RuntimeConfigDocument {const item = object(value, "$runtime");+ if ("permissions" in item) {+ throw Object.assign(new Error(+ "$runtime.permissions was removed. Remove this field: Runtime access is declared by the selected Store, Endpoint, and external-service adapters instead of a central permission list.",+ ), { code: "RUNTIME_CONFIG_OUTDATED" });+ }exactKeys(item, ["format", "root", "packageRoot", "packageLock", "runtimePackageLock","runtimeServices", "services", "endpoints", "scheduling",diff --git a/packages/local/test/config.test.ts b/packages/local/test/config.test.tsindex a84eb928..70a61788 100644--- a/packages/local/test/config.test.ts+++ b/packages/local/test/config.test.ts@@ -88,6 +88,17 @@ test("Runtime config is closed data and rejects unknown environment authority",}), /does not accept apiKey/u);});+test("removed central permissions receive an actionable migration error", () => {+ assert.throws(() => parseRuntimeConfig({+ format: "svml.runtime-config@1",+ ...required,+ endpoints: [],+ permissions: { network: ["example.com"] },+ }), (error: unknown) => error instanceof Error+ && (error as Error & { readonly code?: string }).code === "RUNTIME_CONFIG_OUTDATED"+ && /Remove this field/u.test(error.message));+});+test("Endpoint authority is optional and remains explicit only when shared", () => {const local = parseRuntimeConfig({format: "svml.runtime-config@1",diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.tsindex 44edc44e..56394214 100644--- a/packages/video-cli/test/cli.test.ts+++ b/packages/video-cli/test/cli.test.ts@@ -6,6 +6,8 @@ import { join } from "node:path";import test from "node:test";import { createNodePackageLock, writeNodePackageLock } from "@narratage/package-loader-node";+import { runCli as runCoreCli } from "@narratage/cli";+import type { CliDistribution } from "@narratage/cli";import { materializeRecord, runVideoCli } from "@narratage/video-cli";import { videoCliDistribution } from "@narratage/video-cli";@@ -658,7 +660,7 @@ test("streaming materialization verifies bytes before replacing an existing desttest("CLI inspect and get read the durable Build archive independently of build execution", async () => {const root = await mkdtemp(join(tmpdir(), "svml-cli-archive-"));- const runtimePath = join(root, "runtime.mjs");+ const runtimePath = join(root, "svml.runtime.json");const destination = join(root, "final.mp4");const rawDestination = join(root, "whisperx-raw.json");const bytes = Buffer.from("archived-video");@@ -736,36 +738,47 @@ test("CLI inspect and get read the durable Build archive independently of buildstatus: "pending",};const dispatch = { build: "archive-1", phase: "waiting", admission: "open" };- await writeFile(runtimePath, `const bytes = Buffer.from(${JSON.stringify(bytes.toString("base64"))}, "base64");-const rawBytes = Buffer.from(${JSON.stringify(rawBytes.toString("base64"))}, "base64");-const catalog = ${JSON.stringify(catalog)};-const operation = ${JSON.stringify(operation)};-const dispatch = ${JSON.stringify(dispatch)};-export default {- async build() { throw new Error("not used"); },- async builds() { return [catalog]; },- async credentials() { return []; },- async putCredential() { throw new Error("not used"); },- async deleteCredential() { throw new Error("not used"); },- async queue() { return { dispatches: [dispatch], capacity: [], operations: [] }; },- async operation(id) { return id === operation.id ? operation : undefined; },- async cancelOperation(id) { return id === operation.id ? { ...operation, cancellation: { status: "requested" } } : undefined; },- async status(id) { return { build: id === "archive-1" ? { build: id, revision: 7, state: ${JSON.stringify(state)} } : undefined, catalog: id === "archive-1" ? catalog : undefined, operations: id === "archive-1" ? [operation] : [], dispatch: id === "archive-1" ? dispatch : undefined }; },- async readArtifact(digest) {- if (digest === ${JSON.stringify(artifactDigest)}) return bytes;- if (digest === ${JSON.stringify(rawDigest)}) return rawBytes;- return undefined;- },- async openArtifact(digest) {- const value = digest === ${JSON.stringify(artifactDigest)} ? bytes- : digest === ${JSON.stringify(rawDigest)} ? rawBytes : undefined;- return value === undefined ? undefined : (async function* () { yield value; })();- },- async close() {},-};\n`, "utf8");+ const control = {+ async builds() { return [catalog]; },+ async queue() { return { dispatches: [dispatch], capacity: [], operations: [] }; },+ async operation(id: string) { return id === operation.id ? operation : undefined; },+ async cancelOperation(id: string) {+ return id === operation.id ? { ...operation, cancellation: { status: "requested" } } : undefined;+ },+ async cancel(id: string) {+ return id === "archive-1"+ ? { build: id, phase: "terminal", admission: "closed", terminal: "complete" }+ : undefined;+ },+ async status(id: string) {+ return {+ build: id === "archive-1" ? { build: id, revision: 7, state } : undefined,+ catalog: id === "archive-1" ? catalog : undefined,+ operations: id === "archive-1" ? [operation] : [],+ dispatch: id === "archive-1" ? dispatch : undefined,+ };+ },+ async readArtifact(digest: string) {+ if (digest === artifactDigest) return bytes;+ if (digest === rawDigest) return rawBytes;+ return undefined;+ },+ async openArtifact(digest: string) {+ const value = digest === artifactDigest ? bytes : digest === rawDigest ? rawBytes : undefined;+ return value === undefined ? undefined : (async function* () { yield value; })();+ },+ async close() {},+ };+ const selected = {+ createRuntimeControlFromConfig: async () => control,+ } as unknown as CliDistribution;+ const runArchiveCli = (+ argv: readonly string[],+ io: { readonly write: (text: string) => void },+ ) => runCoreCli([...argv, "--json"], io, selected);let inspectedOutput = "";- await runCli(["inspect", "archive-1", "--runtime", runtimePath], {+ await runArchiveCli(["inspect", "archive-1", "--runtime", runtimePath], {write: (text) => { inspectedOutput += text; },});const inspected = JSON.parse(inspectedOutput) as {@@ -786,7 +799,7 @@ export default {]);let buildsOutput = "";- await runCli(["builds", "--runtime", runtimePath], { write: (text) => { buildsOutput += text; } });+ await runArchiveCli(["builds", "--runtime", runtimePath], { write: (text) => { buildsOutput += text; } });const listed = JSON.parse(buildsOutput) as {readonly builds: readonly {readonly build: string;@@ -807,7 +820,7 @@ export default {}]);let historyOutput = "";- await runCli(["history", "final.video", "--runtime", runtimePath], {+ await runArchiveCli(["history", "final.video", "--runtime", runtimePath], {write: (text) => { historyOutput += text; },});const history = JSON.parse(historyOutput) as {@@ -826,7 +839,7 @@ export default {assert.equal(history.entries[0]?.output.record.digest, recordDigest);let sourceHistoryOutput = "";- await runCli(["history", "--source", catalog.source.path, "--runtime", runtimePath], {+ await runArchiveCli(["history", "--source", catalog.source.path, "--runtime", runtimePath], {write: (text) => { sourceHistoryOutput += text; },});const sourceHistory = JSON.parse(sourceHistoryOutput) as {@@ -835,13 +848,13 @@ export default {assert.deepEqual(sourceHistory.entries.map((item) => item.output.name), ["final.video"]);let absentHistoryOutput = "";- await runCli(["history", "unused.image", "--runtime", runtimePath], {+ await runArchiveCli(["history", "unused.image", "--runtime", runtimePath], {write: (text) => { absentHistoryOutput += text; },});assert.deepEqual((JSON.parse(absentHistoryOutput) as { readonly entries: readonly unknown[] }).entries, []);let statusOutput = "";- await runCli(["status", "archive-1", "--runtime", runtimePath], {+ await runArchiveCli(["status", "archive-1", "--runtime", runtimePath], {write: (text) => { statusOutput += text; },});const status = JSON.parse(statusOutput) as {@@ -855,18 +868,18 @@ export default {});let queueOutput = "";- await runCli(["queue", "--runtime", runtimePath], { write: (text) => { queueOutput += text; } });+ await runArchiveCli(["queue", "--runtime", runtimePath], { write: (text) => { queueOutput += text; } });const queue = JSON.parse(queueOutput) as { readonly dispatches: readonly { readonly phase: string }[] };assert.equal(queue.dispatches[0]?.phase, "waiting");let operationOutput = "";- await runCli(["operation", operationId, "--runtime", runtimePath], {+ await runArchiveCli(["operation", operationId, "--runtime", runtimePath], {write: (text) => { operationOutput += text; },});assert.equal((JSON.parse(operationOutput) as { readonly operation?: { readonly id: string } }).operation?.id, operationId);let getOutput = "";- await runCli([+ await runArchiveCli(["get", "archive-1", "--runtime", runtimePath,"--name", "final.video", "--to", destination,], { write: (text) => { getOutput += text; } });@@ -875,14 +888,14 @@ export default {assert.equal(got.materialized.kind, "artifact");assert.equal(got.materialized.digest, artifactDigest);- await runCli([+ await runArchiveCli(["get", "archive-1", "--runtime", runtimePath,"--artifact", rawDigest, "--to", rawDestination,], { write() {} });assert.deepEqual(await readFile(rawDestination), rawBytes);let cancellationOutput = "";- await runCli([+ await runArchiveCli(["cancel", "operation", operationId, "--runtime", runtimePath,"--reason", "stop this attempt",], { write: (text) => { cancellationOutput += text; } });@@ -903,24 +916,28 @@ export default {const human = async (argv: readonly string[]) => {let output = "";- await runVideoCli([...argv, "--color", "never"], { write: (text) => { output += text; } });+ await runCoreCli([...argv, "--color", "never"], { write: (text) => { output += text; } }, selected);return output;};assert.match(await human(["queue", "--runtime", runtimePath]), /Runtime queue[\s\S]*archive-1: waiting/u);assert.match(await human(["status", "archive-1", "--runtime", runtimePath]), /Build status[\s\S]*Dispatch\s+waiting/u);+ assert.match(await human(["inspect", "archive-1", "--runtime", runtimePath]),+ /Build archive detail[\s\S]*Target\s+final\.video[\s\S]*example@1\/Artifact/u);assert.match(await human(["operation", operationId, "--runtime", runtimePath]), /Operation detail[\s\S]*Status\s+pending/u);assert.match(await human(["cancel", "operation", operationId, "--runtime", runtimePath]),/Operation cancellation requested[\s\S]*Control\s+requested/u);+ assert.match(await human(["cancel", "build", "archive-1", "--runtime", runtimePath]),+ /Build already finished[\s\S]*No running work was changed; this Build is already complete/u);await assert.rejects(- runCli(["status", "archive-1", "--runtime", runtimePath, "--watch"], { write() {} }),+ runArchiveCli(["status", "archive-1", "--runtime", runtimePath, "--watch"], { write() {} }),/--watch applies only to queue/u,);await assert.rejects(- runCli(["queue", "--runtime", runtimePath, "--jsonl"], { write() {} }),+ runArchiveCli(["queue", "--runtime", runtimePath, "--jsonl"], { write() {} }),/--jsonl applies only to queue --watch/u,);await assert.rejects(- runCli(["queue", "--runtime", runtimePath, "--watch", "--json"], { write() {} }),+ runArchiveCli(["queue", "--runtime", runtimePath, "--watch", "--json"], { write() {} }),/use --jsonl instead of --json/u,);});