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): make result export explicit

kashorin26cf35373376
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 88a892ef..78e09020 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -147,8 +147,10 @@ hypit get <build-id> \
--to output/final.mp4
```
-The Build Result saves every public Author Output completed on the Target route. `get` makes an
-optional human-readable copy; Targets do not double as a retention list.
+The Build Result saves every public Author Output completed on the Target route. `get` exports one
+exact named Output to the explicit `--to` destination; Targets do not double as a retention list.
+A Scalar or Resource becomes a file, while a Composite becomes a directory containing `value.json`
+and its referenced Resource files.
## Local tools used by real Builds
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index 534ddd1d..299b9d68 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -29,12 +29,23 @@ from any independent video project.
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.
+One convenient project layout is:
+
```text
-main.svml author meaning
-build.svrun this Run's Targets and Candidate choices
-hypit.runtime.json execution environment
+my-video/
+ main.svml author meaning
+ styles.svs optional authored styles
+ build.svrun this Run's Targets and Candidate choices
+ assets/ project-owned input media
+ output/ explicit exports for people and other tools
+ hypit.runtime.json execution environment
```
+This is a convention, not a schema. Hypit uses the paths written in Source imports, `<author
+source="…">`, CLI arguments and `get --to`; it does not require these names or recognize `assets/`
+or `output/` specially. The managed Result repository remains separate under `.hypit/results` by
+default.
+
Run Source and Runtime Profile do not silently rewrite the video. Creative model choices remain in
the Author Source or in packages that it explicitly imports.
@@ -100,13 +111,13 @@ As soon as a generated image or take is accepted, reuse it explicitly in the nex
<target output="final.video"/>
<build-record id="hook-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="hook-take.video"/>
<build-record id="meeting-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="meeting-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="meeting-take.video"/>
<build-record id="evidence-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="evidence-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="evidence-take.video"/>
<build-record id="payoff-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="payoff-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="payoff-take.video"/>
<satisfy output="hook-take.video" candidate="hook-video"/>
<satisfy output="meeting-take.video" candidate="meeting-video"/>
@@ -262,10 +273,10 @@ only with `--workspace`. `--package-root` locates installed packages and never w
result.json
files/
values/
-output/
```
-That is the zero-configuration Result repository. A project-owned `hypit.results.json` may instead select
+That is the zero-configuration Result repository. The `output/` directory shown earlier is only a
+convenient destination for explicit exports and is not part of Result storage. A project-owned `hypit.results.json` may instead select
`@hypit/build-result-s3`; commands and historical `build-record` references then use that same
repository. Runtime working Artifacts remain local and private to the Runtime.
@@ -364,9 +375,15 @@ hypit get <build-id> \
--to examples/talking-head-aroll/output/final.mp4
```
-`get` resolves one exact `build + output` address and makes an optional copy. A file Output is copied
-from that Result; a structured Output is read from its Result value file; a forwarded historical
-Output is followed to its declared earlier Result. The Runtime Profile is not involved.
+`get` exports one exact `build + output` address to the required `--to` destination. A Scalar becomes
+a JSON file. A Resource becomes one file containing its original bytes. A Composite becomes a
+self-contained directory: `value.json` holds its Composite value document and the Resource files it
+references keep their Result-relative paths inside that directory. The destination must not already
+exist.
+
+A forwarded historical Output is resolved transparently to its declared earlier Result. This does
+not create a Build, alter a Result or copy anything back into Result storage, and the Runtime Profile
+is not involved. Use `inspect` to view an Output; `get` is only explicit local export.
The finished Build result prints the exact `get --output …` command for every file Target;
there is no need to inspect opaque Record ids just to export `final.video`.
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index 88cc1b8e..df074e51 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -142,7 +142,8 @@ hypit get <build-id> \
```
Build Result 会保存目标路径上已经完成的所有公开 Author Output,包括媒体和结构化值。`get`
-只负责按唯一公开名称读取或复制某个 Output,不会决定哪些中间结果应该被保存。
+只把唯一公开名称指定的 Output 导出到明确的 `--to` 目的地,不会决定哪些中间结果应该被保存。
+Scalar 与 Resource 导出为文件;Composite 导出为包含 `value.json` 及其引用 Resource 的目录。
## 真实 Build 可能使用的本地工具
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index df36c661..9648d589 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -25,12 +25,22 @@ hypit get <build-id> --output final.video --to output/final.mp4
只有 `build` 会真正提交工作。`plan` 是普通预览;`check` 用于编辑源码,`doctor` 用于配置和排查部署。它们都安全,但不是每次 Build 前必须重复的仪式。
+一种顺手的项目目录约定是:
+
```text
-main.svml 作者意图
-build.svrun 本次 Run 的 Target 与 Candidate 选择
-hypit.runtime.json 执行环境
+my-video/
+ main.svml 作者意图
+ styles.svs 可选的作者样式
+ build.svrun 本次 Run 的 Target 与 Candidate 选择
+ assets/ 项目自己的输入素材
+ output/ 显式导出给人或其他工具的副本
+ hypit.runtime.json 执行环境
```
+这只是推荐,不是项目格式。Hypit 只服从 Source import、`<author source="…">`、CLI 参数和
+`get --to` 中明确写出的路径,不要求这些名字,也不会特殊识别 `assets/` 或 `output/`。受管理的
+Result 仓库与它们分开,零配置时仍位于 `.hypit/results`。
+
Run Source 与 Runtime Profile 不会悄悄改写视频。创作性的模型选择仍然留在 Author Source,或它显式导入的包里。
## Run Source 语法
@@ -87,13 +97,13 @@ Hypit 没有隐式缓存。复用结果是显式的运行图编写:把某个
<target output="final.video"/>
<build-record id="hook-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="hook-take.video"/>
<build-record id="meeting-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="meeting-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="meeting-take.video"/>
<build-record id="evidence-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="evidence-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="evidence-take.video"/>
<build-record id="payoff-video"
- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="payoff-take.video"/>
+ build="bld_20260902T142031123Z_0123456789" output="payoff-take.video"/>
<satisfy output="hook-take.video" candidate="hook-video"/>
<satisfy output="meeting-take.video" candidate="meeting-video"/>
@@ -264,7 +274,7 @@ hypit plan /work/my-film/build.svrun --asset-root /work/shared-media
```
`--asset-root` 可重复使用,只授权读取素材字节,不允许从那里导入 `.svml/.svs` 源码。该 Host
-选项不进入作者或 Build 身份;真正进入图的仍是素材内容摘要。
+选项不进入作者或 Build 身份;真正进入图的是由该文件形成的显式 Resource 值。
Runtime Profile 只选择 Runtime 包与该 Runtime 的封闭配置。完整结构只在
[Runtime](../guide/runtime.md) 维护,不在 Quickstart 复制第二份。
@@ -354,9 +364,13 @@ hypit get <build-id> \
--to examples/talking-head-aroll/output/final.mp4
```
-`get` 解析一个精确的 `build + output` 地址并按需复制。文件从所属 Result 复制,结构化 Output
-从 Result 的值文件读取,历史转发则沿显式关系找到前一个 Result;整个过程不需要 Runtime Profile。
-Build 的最终输出会为每个文件 Target 打印精确的 `get --output …` 命令。
+`get` 把一个精确的 `build + output` 地址导出到必填的 `--to` 目的地。Scalar 写成 JSON 文件;
+Resource 原样写成一个文件;Composite 写成一个自足目录,其中 `value.json` 保存它的 Composite 值
+文档,被引用的 Resource 则按 Result 内的相对路径一起写入。目的地必须尚不存在。
+
+历史转发会透明地沿显式关系找到更早的 Result。这个过程不会创建 Build、修改 Result,或把
+副本写回 Result 仓库,也不需要 Runtime Profile。查看 Output 用 `inspect`;`get` 只负责显式
+本地导出。Build 的最终输出会为每个文件 Target 打印精确的 `get --output …` 命令。
### 6. 在新 Build 中复用
diff --git a/packages/build-result/src/index.ts b/packages/build-result/src/index.ts
index c4b2f818..7c3ae309 100644
--- a/packages/build-result/src/index.ts
+++ b/packages/build-result/src/index.ts
@@ -16,8 +16,6 @@ export {
applyBuildResultPresentation,
browseBuildResults,
buildResultDirectory,
- materializeBuildResultOutput,
- materializeRepositoryBuildResultOutput,
readBuildResult,
resolveBuildResultOutput,
} from "./store.js";
diff --git a/packages/build-result/src/store.ts b/packages/build-result/src/store.ts
index e6f72094..1782929d 100644
--- a/packages/build-result/src/store.ts
+++ b/packages/build-result/src/store.ts
@@ -1,6 +1,5 @@
import { randomUUID } from "node:crypto";
import {
- copyFile,
mkdir,
open,
readFile,
@@ -241,89 +240,6 @@ export async function resolveBuildResultOutput(
}
}
-export async function materializeBuildResultOutput(
- root: string,
- build: string,
- output: string,
- destination: string,
-): Promise<{
- readonly build: string;
- readonly output: string;
- readonly path: string;
- readonly kind: "file" | "value" | "inline";
-}> {
- const resolvedOutput = await resolveBuildResultOutput(root, build, output);
- if (resolvedOutput === undefined) throw new Error(`Build ${build} has no Output ${output}`);
- const target = resolve(destination);
- await mkdir(dirname(target), { recursive: true });
- const temporary = `${target}.part-${randomUUID()}`;
- try {
- if (resolvedOutput.value.kind === "inline") {
- await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.value, null, 2)}\n`, { flag: "wx" });
- } else {
- await copyFile(containedResultPath(resolvedOutput.directory, resolvedOutput.value.path), temporary);
- }
- await rename(temporary, target);
- } catch (error) {
- await rm(temporary, { force: true });
- throw error;
- }
- return {
- build: resolvedOutput.build,
- output: resolvedOutput.output,
- path: target,
- kind: resolvedOutput.value.kind === "build-file"
- ? "file"
- : resolvedOutput.value.kind === "value" ? "value" : "inline",
- };
-}
-
-export async function materializeRepositoryBuildResultOutput(
- repository: BuildResultRepository,
- build: string,
- output: string,
- destination: string,
-): Promise<{
- readonly build: string;
- readonly output: string;
- readonly path: string;
- readonly kind: "file" | "value" | "inline";
-}> {
- const resolvedOutput = await repository.resolve(build, output);
- if (resolvedOutput === undefined) throw new Error(`Build ${build} has no Output ${output}`);
- const target = resolve(destination);
- await mkdir(dirname(target), { recursive: true });
- const temporary = `${target}.part-${randomUUID()}`;
- try {
- if (resolvedOutput.value.kind === "inline") {
- await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.value, null, 2)}\n`, { flag: "wx" });
- } else if (resolvedOutput.value.kind === "value") {
- await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.document, null, 2)}\n`, { flag: "wx" });
- } else {
- const input = await repository.openFile(resolvedOutput.build, resolvedOutput.value);
- if (input === undefined) {
- throw new Error(`Build ${resolvedOutput.build} file ${resolvedOutput.value.path} is unavailable`);
- }
- const handle = await open(temporary, "wx");
- try {
- for await (const chunk of input) await handle.write(Uint8Array.from(chunk));
- } finally {
- await handle.close();
- }
- }
- await rename(temporary, target);
- } catch (error) {
- await rm(temporary, { force: true });
- throw error;
- }
- return {
- build: resolvedOutput.build,
- output: resolvedOutput.output,
- path: target,
- kind: resolvedOutput.value.kind === "build-file" ? "file" : resolvedOutput.value.kind === "value" ? "value" : "inline",
- };
-}
-
export class FileBuildResult {
readonly directory: string;
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 909ef564..1375f278 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -5,10 +5,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
import { deterministicSpeechDurations, deterministicSpeechDurationsFromGraph } from "@hypit/compiler-node";
-import {
- FileBuildResultRepository,
- materializeRepositoryBuildResultOutput,
-} from "@hypit/build-result";
+import { FileBuildResultRepository } from "@hypit/build-result";
import type { BuildResultManifest, BuildResultRepository } from "@hypit/build-result";
import type { NodeCompiledSourceClosure } from "@hypit/compiler-node";
import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
@@ -38,6 +35,7 @@ import type {
} from "./runtime-port.js";
import { writeCliHelp, writeCliOutput } from "./output.js";
import type { CliColorMode, CliIo } from "./output.js";
+import { exportBuildResultOutput } from "./result-export.js";
import { hypitHostStateRoot, hypitProjectStateRoot } from "./paths.js";
import { loadDiscoveredSourcePackages } from "./source-packages.js";
import {
@@ -411,7 +409,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
continue;
}
if (item === "--out") {
- throw new Error("--out does not apply to Build submission; use `get <build-id> --output <name> --to <path>` for an optional copy");
+ throw new Error("--out does not apply to Build submission; use `get <build-id> --output <name> --to <path>` to export one Result Output");
}
if (item === "--output") {
const value = rest[index + 1];
@@ -684,6 +682,12 @@ function assertCommandOptions(args: ParsedArgs): void {
if (args.seenOptions.includes("--color") && args.seenOptions.includes("--no-color")) {
throw new Error("--color and --no-color are mutually exclusive");
}
+ if (args.command === "get" && args.output === undefined) {
+ throw new Error("get requires --output with one public Output name");
+ }
+ if (args.command === "get" && args.to === undefined) {
+ throw new Error("get requires --to with the export destination");
+ }
}
function usage(): string {
@@ -706,7 +710,7 @@ function usage(): string {
" hypit builds [--workspace project] [--limit count] [--before build-id]",
" hypit history [output-name] [--workspace project] [--source author.svml] [--limit count] [--before build-id] [--pin] [--exclude-targets]",
" hypit inspect <build-id> [--workspace project]",
- " hypit get <build-id> --output output-name [--workspace project] [--to path]",
+ " hypit get <build-id> --output output-name --to path [--workspace project]",
" hypit cancel <build-id> [--runtime profile.json] [--reason text]",
" hypit auth status|login|logout <endpoint-instance> [--runtime profile.json] [--slot name] [--from secret-file]",
" hypit image --prompt <text|text-file> --to <path.png> [--model package] [--aspect-ratio r] [--resolution r]",
@@ -1650,31 +1654,14 @@ export async function runCli(
], manifest.note === undefined ? [] : [`Note ${manifest.note}`]);
return;
}
- const manifest = await repository.read(args.file!);
- if (manifest === undefined) throw new Error(`Build Result ${args.file} does not exist`);
- const available = Object.keys(manifest.outputs);
- const name = args.output
- ?? (manifest.targets.length === 1 && manifest.outputs[manifest.targets[0]!] !== undefined
- ? manifest.targets[0]
- : available.length === 1 ? available[0] : undefined);
- if (name === undefined) throw new Error(`Build ${manifest.id} has several Outputs; select one with --output`);
- const resolved = await repository.resolve(manifest.id, name);
- if (resolved === undefined) throw new Error(`Build ${manifest.id} has no Output ${name}`);
- if (args.to === undefined) {
- writeOperational({ format: "hypit.cli-get@2", build: manifest.id, output: name, type: resolved.type, value: resolved.value }, "Build Output", "info", [
- ["Build", manifest.id],
- ["Output", name],
- ["Type", displayType(resolved.type)],
- ...(resolved.value.kind === "build-file" ? [["Media", `${resolved.value.mediaType} · ${resolved.value.size} bytes`] as const] : []),
- ], resolved.build === manifest.id && resolved.output === name
- ? []
- : [`Forwards to ${resolved.build} / ${resolved.output}`]);
- } else {
- const materialized = await materializeRepositoryBuildResultOutput(repository, manifest.id, name, args.to);
- writeOperational({ format: "hypit.cli-get@2", build: manifest.id, output: name, path: materialized.path, kind: materialized.kind }, "Build Output materialized", "success", [
- ["Build", manifest.id], ["Output", name], ["Path", materialized.path],
- ]);
- }
+ const exported = await exportBuildResultOutput(repository, args.file!, args.output!, args.to!);
+ writeOperational({ format: "hypit.cli-get@3", ...exported }, "Build Output exported", "success", [
+ ["Build", exported.build],
+ ["Output", exported.output],
+ ["Type", displayType(exported.type)],
+ ["Kind", exported.kind],
+ ["Path", exported.path],
+ ]);
return;
} finally {
await results.close();
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index b0607e6c..c6db95a5 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -529,9 +529,12 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
],
get: [
colors.accent(colors.strong("hypit get")),
- colors.dim("Read or copy one exact named Build Output; copying never reruns work."),
+ colors.dim("Export one exact named Build Output to an explicit local destination."),
"",
- " hypit get <build-id> --output <name> [--workspace <project>] [--to <path>]",
+ " hypit get <build-id> --output <name> --to <path> [--workspace <project>]",
+ "",
+ "Scalar and Resource Outputs become files. A Composite Output becomes a directory",
+ "containing value.json and every Resource referenced by that value.",
],
history: [
colors.accent(colors.strong("hypit history")),
@@ -607,7 +610,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
row("runtime use <profile>", "select this project's execution environment", 40),
row("plan <run-source>", "see exactly what this Run will demand", 40),
row("build <run-source>", "submit durable work; add --follow to watch", 40),
- row("get <build-id>", "read or copy a Result Output", 40),
+ row("get <build-id>", "export one named Result Output", 40),
row("doctor [profile]", "diagnose deployment setup when needed", 40),
"",
colors.strong("Authoring"),
@@ -621,7 +624,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
row("history [output]", "find named historical Build Outputs"),
row("status <build-id> [--watch]", "show or continuously observe one Build"),
row("inspect <build-id>", "inspect one project Build Result"),
- row("get <build-id> --output <name>", "read or materialize one Build Output"),
+ row("get <build-id> --output <name> --to <path>", "export one Build Output"),
row("cancel <build-id>", "withdraw one Build and reconcile submitted work"),
row("result finish <build-id>", "finish an interrupted Result write"),
row("result discard <build-id>", "discard one incomplete submission"),
diff --git a/packages/cli/src/result-export.ts b/packages/cli/src/result-export.ts
new file mode 100644
index 00000000..43219d96
--- /dev/null
+++ b/packages/cli/src/result-export.ts
@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+import type {
+ BuildResultFileRef,
+ BuildResultRepository,
+ RepositoryBuildResultOutput,
+} from "@hypit/build-result";
+
+export type BuildResultExport = {
+ readonly build: string;
+ readonly output: string;
+ readonly type: RepositoryBuildResultOutput["type"];
+ readonly kind: "scalar" | "resource" | "composite";
+ readonly path: string;
+};
+
+type CompositeResultOutput = Omit<RepositoryBuildResultOutput, "value"> & {
+ readonly value: Extract<RepositoryBuildResultOutput["value"], { readonly kind: "value" }>;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+ return await lstat(path).then(() => true, (error: unknown) => {
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+ throw error;
+ });
+}
+
+function containedPath(root: string, path: string): string {
+ const target = resolve(root, path);
+ const relation = relative(root, target);
+ assert(relation.length > 0 && relation !== ".." && !relation.startsWith(`..${sep}`),
+ `Result file ${path} leaves export directory ${root}`);
+ return target;
+}
+
+async function writeStream(
+ path: string,
+ input: AsyncIterable<Uint8Array>,
+): Promise<void> {
+ await mkdir(dirname(path), { recursive: true });
+ await writeFile(path, input, { flag: "wx" });
+}
+
+async function openResultFile(
+ repository: BuildResultRepository,
+ build: string,
+ file: BuildResultFileRef,
+): Promise<AsyncIterable<Uint8Array>> {
+ const input = await repository.openFile(build, file);
+ if (input === undefined) throw new Error(`Build ${build} file ${file.path} is unavailable`);
+ return input;
+}
+
+async function exportFile(
+ target: string,
+ write: (temporary: string) => Promise<void>,
+): Promise<void> {
+ assert(!await pathExists(target), `Export destination ${target} already exists`);
+ await mkdir(dirname(target), { recursive: true });
+ const temporary = join(dirname(target), `.${basename(target)}.part-${randomUUID()}`);
+ try {
+ await write(temporary);
+ await rename(temporary, target);
+ } catch (error) {
+ await rm(temporary, { force: true });
+ throw error;
+ }
+}
+
+async function exportComposite(
+ repository: BuildResultRepository,
+ resolvedOutput: CompositeResultOutput,
+ target: string,
+): Promise<void> {
+ assert(!await pathExists(target), `Export destination ${target} already exists`);
+ await mkdir(dirname(target), { recursive: true });
+ const temporary = join(dirname(target), `.${basename(target)}.part-${randomUUID()}`);
+ try {
+ await mkdir(temporary);
+ const copied = new Set<string>();
+ for (const binding of resolvedOutput.value.document.resources) {
+ const file = binding.file;
+ if (copied.has(file.path)) continue;
+ copied.add(file.path);
+ assert(file.path !== "value.json", "Composite Result file value.json conflicts with its exported value document");
+ await writeStream(
+ containedPath(temporary, file.path),
+ await openResultFile(repository, resolvedOutput.build, file),
+ );
+ }
+ await writeFile(
+ join(temporary, "value.json"),
+ `${JSON.stringify(resolvedOutput.value.document, null, 2)}\n`,
+ { flag: "wx" },
+ );
+ await rename(temporary, target);
+ } catch (error) {
+ await rm(temporary, { recursive: true, force: true });
+ throw error;
+ }
+}
+
+/** Export one resolved public Output into an explicit user-owned local destination. */
+export async function exportBuildResultOutput(
+ repository: BuildResultRepository,
+ build: string,
+ output: string,
+ destination: string,
+): Promise<BuildResultExport> {
+ const manifest = await repository.read(build);
+ if (manifest === undefined) throw new Error(`Build Result ${build} does not exist`);
+ const publishedOutput = manifest.outputs[output];
+ if (publishedOutput === undefined) throw new Error(`Build ${build} has no Output ${output}`);
+ const resolvedOutput = await repository.resolve(build, output);
+ if (resolvedOutput === undefined) throw new Error(`Build ${build} Output ${output} cannot be resolved`);
+ const target = resolve(destination);
+ if (resolvedOutput.value.kind === "value") {
+ await exportComposite(repository, { ...resolvedOutput, value: resolvedOutput.value }, target);
+ } else if (resolvedOutput.value.kind === "build-file") {
+ const resource = resolvedOutput.value;
+ await exportFile(target, async (temporary) => {
+ await writeStream(
+ temporary,
+ await openResultFile(repository, resolvedOutput.build, resource),
+ );
+ });
+ } else {
+ const scalar = resolvedOutput.value.value;
+ await exportFile(target, async (temporary) => {
+ await writeFile(temporary, `${JSON.stringify(scalar, null, 2)}\n`, { flag: "wx" });
+ });
+ }
+ return {
+ build,
+ output,
+ type: publishedOutput.type,
+ kind: resolvedOutput.value.kind === "inline"
+ ? "scalar"
+ : resolvedOutput.value.kind === "build-file" ? "resource" : "composite",
+ path: target,
+ };
+}
diff --git a/packages/cli/test/build-results.test.ts b/packages/cli/test/build-results.test.ts
index 1f0d511f..29d12653 100644
--- a/packages/cli/test/build-results.test.ts
+++ b/packages/cli/test/build-results.test.ts
@@ -1,5 +1,5 @@
import assert from "node:assert/strict";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
@@ -87,8 +87,118 @@ test("builds, history, inspect and get read project Build Results without openin
assert.equal(inspected.result.title, "episode-stage");
const destination = join(root, "exported.json");
- await jsonCommand(["get", "bld_20260902T110000000Z_0000000001", "--output", "stage.value", "--to", destination], root);
+ const exported = await jsonCommand([
+ "get", "bld_20260902T110000000Z_0000000001", "--output", "stage.value", "--to", destination,
+ ], root);
+ assert.deepEqual(exported, {
+ format: "hypit.cli-get@3",
+ build: "bld_20260902T110000000Z_0000000001",
+ output: "stage.value",
+ type: valueType,
+ kind: "scalar",
+ path: destination,
+ });
assert.equal(await readFile(destination, "utf8"), "\"ready\"\n");
+ await assert.rejects(
+ jsonCommand(["get", "bld_20260902T110000000Z_0000000001", "--output", "stage.value", "--to", destination], root),
+ /Export destination .* already exists/u,
+ );
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("get exports Resource bytes and a self-contained Composite directory", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-cli-get-"));
+ const build = "bld_20260902T110000010Z_0000000001";
+ const videoType = { module: { name: "example.media", version: "1" }, name: "Video" } satisfies TypeRef;
+ const takeType = { module: { name: "example.speech", version: "1" }, name: "SemanticTake" } satisfies TypeRef;
+ const bytes = new TextEncoder().encode("video bytes");
+ const video = {
+ kind: "blob",
+ resource: "res_video",
+ size: bytes.byteLength,
+ mediaType: "video/mp4",
+ } as const;
+ try {
+ const result = await FileBuildResult.create(join(root, ".hypit", "results"), {
+ id: build,
+ source: { path: join(root, "main.svml") },
+ targets: ["final.video"],
+ publishedOutputs: [
+ { name: "final.video", output: "logical:video" },
+ { name: "final.take", output: "logical:take" },
+ ],
+ });
+ await result.sync({
+ state: {
+ status: "complete",
+ records: [
+ { id: "record:video", type: videoType, value: video },
+ {
+ id: "record:take",
+ type: takeType,
+ value: { kind: "inline", value: { words: ["hello"], media: { artifact: video } } },
+ },
+ ],
+ plan: { outputBindings: [
+ { output: "logical:video", record: "record:video", type: videoType },
+ { output: "logical:take", record: "record:take", type: takeType },
+ ] },
+ } as unknown as BuildState,
+ resources: {
+ async open() { return (async function* () { yield bytes; })(); },
+ },
+ });
+ await result.finish({ outcome: "complete" });
+
+ const resourceDestination = join(root, "output", "final.mp4");
+ const resource = await jsonCommand([
+ "get", build, "--output", "final.video", "--to", resourceDestination,
+ ], root) as { readonly kind: string; readonly build: string; readonly output: string };
+ assert.equal(resource.kind, "resource");
+ assert.equal(resource.build, build);
+ assert.equal(resource.output, "final.video");
+ assert.equal(new TextDecoder().decode(await readFile(resourceDestination)), "video bytes");
+
+ const compositeDestination = join(root, "output", "final-take");
+ const composite = await jsonCommand([
+ "get", build, "--output", "final.take", "--to", compositeDestination,
+ ], root) as { readonly kind: string; readonly path: string };
+ assert.equal(composite.kind, "composite");
+ assert.equal(composite.path, compositeDestination);
+ assert.equal((await stat(compositeDestination)).isDirectory(), true);
+ const document = JSON.parse(await readFile(join(compositeDestination, "value.json"), "utf8")) as {
+ readonly format: string;
+ readonly value: { readonly words: readonly string[]; readonly media: { readonly artifact: null } };
+ readonly resources: readonly [{ readonly file: { readonly path: string } }];
+ };
+ assert.equal(document.format, "hypit.result-value@1");
+ assert.deepEqual(document.value.words, ["hello"]);
+ assert.equal(document.value.media.artifact, null);
+ assert.equal(
+ new TextDecoder().decode(await readFile(join(compositeDestination, document.resources[0].file.path))),
+ "video bytes",
+ );
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("get requires an exact Output name and an explicit destination", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-cli-get-options-"));
+ try {
+ const silent = { write() {} };
+ await assert.rejects(
+ runCli(["get", "bld_20260902T110000000Z_0000000001", "--workspace", root], silent, {} as CliDistribution),
+ /get requires --output/u,
+ );
+ await assert.rejects(
+ runCli([
+ "get", "bld_20260902T110000000Z_0000000001", "--output", "stage.value", "--workspace", root,
+ ], silent, {} as CliDistribution),
+ /get requires --to/u,
+ );
} finally {
await rm(root, { recursive: true, force: true });
}
diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.ts
index dbd49cad..cd0d2f71 100644
--- a/packages/cli/test/output.test.ts
+++ b/packages/cli/test/output.test.ts
@@ -253,6 +253,7 @@ test("Result commands have their own help instead of falling back to the global
let output = "";
writeCliHelp({ write(text) { output += text; } }, "get");
assert.match(output, /^hypit get\n/u);
- assert.match(output, /copying never reruns work/u);
+ assert.match(output, /--output <name> --to <path>/u);
+ assert.match(output, /Composite Output becomes a directory/u);
assert.doesNotMatch(output, /Typical flow/u);
});
diff --git a/packages/video-cli/README.md b/packages/video-cli/README.md
index caf65e4f..63682937 100644
--- a/packages/video-cli/README.md
+++ b/packages/video-cli/README.md
@@ -61,10 +61,11 @@ another Candidate. None of these commands creates or stores a ready-Command queu
The Result saves every public Author Output completed on the demanded route, including structured
values such as semantic takes. Each Logical Output has exactly one public name in `publishedOutputs`;
-there are no Record, Artifact or alias selectors. `inspect` shows those Outputs, and `get --output`
-reads one exact name. `--to` copies a file or writes an inline structured value as JSON. This is Host
-egress only and never changes Build identity or retention. File streaming writes a temporary file and
-then atomically replaces the destination, so large video need not be loaded into CLI memory.
+there are no Record, Artifact or alias selectors. `inspect` shows those Outputs. `get` requires one
+exact `--output` name and one explicit `--to` destination: a Scalar becomes a JSON file, a Resource
+streams to one file, and a Composite becomes a self-contained directory with `value.json` plus every
+referenced Resource. The destination must not already exist. This is Host egress only and never
+changes Build identity or retention; large media does not need to be loaded into CLI memory.
`builds` and `history` browse project-owned Result manifests newest first. `--before <build-id>` moves
the cursor to older Results without a central history table. Presentation titles, notes and highlights