Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

refactor(cli): streamline the author workflow

kashorin363635a163fb
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.md
index 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
# Narratage
Use 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.json
node --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 --follow
node --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.json
node --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 Provider
work.
diff --git a/.agents/skills/narratage/references/environment.md b/.agents/skills/narratage/references/environment.md
index 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, refresh
project 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 the
diff --git a/.agents/skills/narratage/references/playbooks/craft/production-gates.md b/.agents/skills/narratage/references/playbooks/craft/production-gates.md
index 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 late
and 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 images
diff --git a/.agents/skills/narratage/references/runtime.md b/.agents/skills/narratage/references/runtime.md
index 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.json
node --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 --follow
node --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.json
node --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 orderly
stop. It stops the Worker from claiming more leases and stops Runtime-owned programs, but preserves
durable Builds and does not cancel remote Provider work.
diff --git a/README.md b/README.md
index 33d26500..9288ea04 100644
--- a/README.md
+++ b/README.md
@@ -115,12 +115,10 @@ corepack enable
pnpm install --frozen-lockfile
node --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
node --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:
```bash
cd /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 observes
that 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 Runtime
Profiles, credentials, concurrency, cancellation and explicit reuse of previous outputs.
diff --git a/docs/guide/develop.md b/docs/guide/develop.md
index 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.md
index 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 and
Stores, Endpoints, credentials and concurrency. It is deployment configuration, not
creative 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 communi
must wait for a real process/Wasm isolation boundary with enforceable filesystem, network, process
and 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.
## Diagnostics
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 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.
```bash
node --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:
```bash
node --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 programs
declared 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.json
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index 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 ou
which 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.json
narratage build build.svrun --runtime svml.runtime.json --build-id my-video-001 --follow
narratage 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 o
The 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.
```text
main.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:
```bash
node --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
```bash
node --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
```
```bash
node --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.
```bash
node --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:
```bash
node --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 Runtime
diff --git a/docs/zh/guide/develop.md b/docs/zh/guide/develop.md
index 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.md
index 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.md
index 97a19a1b..77742e9b 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -40,8 +40,7 @@ pnpm install --frozen-lockfile
```bash
node --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 \
```bash
node --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.json
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index 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`。只
```bash
node --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 配置、凭
```bash
node --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
```
```bash
diff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.md
index 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 referenced
Artifacts 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 Record
Candidates 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 dest
test("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 build
status: "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,
);
});