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.

fix(runtime): expose preparation progress and preserve CLI context

kashorine6aa3a23ef03
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 871bce04..e9d44f0a 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -14,11 +14,28 @@ invent targets, candidates or Provider choices.
Human and JSON output answer the same command-specific question. `--json` changes encoding;
`--verbose` expands scope. Compiler, Runtime and Repository objects are not default reports.
+Design reports for the decision they support: retain relevant facts, uncertainty and usable object
+selectors, with direct access to omitted detail. Shorter output is useful when the next action
+remains well-founded. Observe the command result separately from service availability; titles,
+exit codes and JSON must preserve that distinction. A lifecycle refusal cannot become success just
+because a health probe is down. These rules concern presentation and composition of existing
+operations, not a prescribed production workflow.
+
Argument errors use `CLI_USAGE` and point to the relevant `hypit help <command>`; JSON retains that
command in `error.help`. Unknown help topics fail explicitly. Runtime and execution failures retain
their own diagnostics and optional `--debug` trace. Result pagination changes only the `--before`
cursor on the current query, preserving its project, Source filter and other options.
+Concrete follow-up commands keep the selected project and, for execution operations, Runtime Profile.
+Result-only commands need no Runtime. Arguments in displayed commands are quoted for POSIX shells
+or PowerShell on Windows, including paths with spaces. The CLI formats these existing commands;
+it does not choose which one the Agent must execute next.
+
+`build --follow` and `status --watch` report coalesced progress through `CliIo.writeProgress` when
+provided, including in JSON mode. The executable writes that channel to stderr; stdout remains the
+final machine result. A stopped Worker ends observation with evidence-reading commands, without
+promising to restart failed execution or describing the interruption as a Result storage failure.
+
| Command | Default scope | Explicit detail |
| --- | --- | --- |
| `check` | Validation, targets and counts | `--verbose`: exported names/types and historical references |
@@ -61,6 +78,12 @@ not select it. The pointer is a file, separate from the Profile's `dataRoot`; a
path is reported explicitly and preserved. Project selection is also available on `paths`, `doctor`, execution status/control,
Runtime operations, `programs` and `auth`. Machine-wide `packages` operations have no project selector.
+`auth status <endpoint>` reports credential presence, write access, and the Provider's declared
+OAuth authorization endpoint when present. This describes how a subsequent `auth login` acquires a
+credential; it does not classify the secret already stored or verify remote account access.
+Without browser acquisition, login uses secure input. `--from <file>` explicitly imports a secret
+instead. Credential entry operates on an already declared Endpoint and changes no Provider or binding.
+
`paths` shows the effective locations and whether the Profile came from a command argument, a project
selection or neither. Its JSON fields `profileSource` and `selectionFile` expose that distinction; the
selection-file location is shown even when no selection exists. `doctor` states whether it checked
@@ -131,6 +154,10 @@ CLI, Studio and creation tools call that same package; the CLI is not another en
The same Endpoint scope reaches package preparation and Program operations. Omission means the whole
Profile. Build preflight instead uses the Endpoints resolved for that Build's concrete requests.
An unrelated offered capability does not add another credential or Program requirement.
+Program rows show the configured Endpoint selector alongside an internal Program ID when they differ.
+The `programs` JSON `ok` field reports whether this command succeeded; `ready` reports service
+readiness. Successful stopping can therefore report `ok: true` with `ready: false`. A declined stop remains visible even
+while the service is still preparing and cannot yet answer its health probe.
Upstream package installation reports an `install.log` path at preparation time. Exact package
releases coexist below the machine home, each with npm's own package.json and lockfile. `paths` shows
diff --git a/packages/cli/src/command-hint.ts b/packages/cli/src/command-hint.ts
new file mode 100644
index 00000000..dce4305d
--- /dev/null
+++ b/packages/cli/src/command-hint.ts
@@ -0,0 +1,20 @@
+/** Scope belongs to the invocation; a suggested command must keep the same target. */
+export type CommandScope = {
+ readonly projectRoot?: string;
+ readonly runtimeProfile?: string;
+};
+
+/** Display copyable arguments for POSIX shells or PowerShell, without expanding their contents. */
+export function commandHint(
+ args: readonly string[],
+ scope: CommandScope = {},
+ shell: "posix" | "powershell" = process.platform === "win32" ? "powershell" : "posix",
+): string {
+ const quote = (value: string): string => /^[a-zA-Z0-9_./:@=+-]+$/u.test(value)
+ ? value
+ : `'${value.replaceAll("'", shell === "powershell" ? "''" : "'\"'\"'")}'`;
+ return ["hypit", ...args,
+ ...(scope.projectRoot === undefined ? [] : ["--workspace", scope.projectRoot]),
+ ...(scope.runtimeProfile === undefined ? [] : ["--runtime", scope.runtimeProfile]),
+ ].map(quote).join(" ");
+}
diff --git a/packages/cli/src/commands/environment.ts b/packages/cli/src/commands/environment.ts
index c723906f..8eb1cff8 100644
--- a/packages/cli/src/commands/environment.ts
+++ b/packages/cli/src/commands/environment.ts
@@ -5,12 +5,13 @@ import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
import { hypitHostPackageRoot, inspectHostPackage, prepareHostPackages } from "@hypit/runtime-host-node";
import type { CliCommand, EnvironmentCommand } from "../command.js";
+import { commandHint } from "../command-hint.js";
import type { CliDistribution } from "../distribution.js";
import { acquireOAuthCredential } from "../oauth.js";
import { writeCliOutput } from "../output.js";
import type { CliIo } from "../output.js";
import { hypitHostStateRoot, hypitProjectStateRoot } from "../paths.js";
-import type { CliManagedProgramReport, CliRuntimeController } from "../runtime-port.js";
+import type { CliManagedProgramProgress, CliManagedProgramReport, CliRuntimeController } from "../runtime-port.js";
import type { OperationalWriter } from "./types.js";
function programRecord(item: CliManagedProgramReport) {
@@ -27,8 +28,12 @@ function programDescription(item: CliManagedProgramReport): string {
...(item.detail === undefined ? [] : [item.detail]),
])];
return `${item.id}: ${item.state.state}${details.length === 0 ? "" : ` — ${details.join("; ")}`}`
+ + (item.endpoint === item.id ? "" : ` · endpoint ${item.endpoint}`)
+ (item.pid === undefined ? "" : ` · PID ${item.pid}`)
- + (item.logPath === undefined ? "" : ` · log ${item.logPath}`);
+ + (item.logPath === undefined ? "" : ` · log ${item.logPath}`)
+ + (item.installationLogPath === undefined || item.installationLogPath === item.logPath
+ ? "" : ` · installation log ${item.installationLogPath}`)
+ + (item.errorLogPath === undefined ? "" : ` · stderr ${item.errorLogPath}`);
}
export function isEnvironmentCommand(args: CliCommand): args is EnvironmentCommand {
@@ -58,10 +63,11 @@ export async function runEnvironmentCommand(input: {
const selectionDescription = profileSource === "argument"
? "command argument (this invocation only)"
: runtimeSelectionFile ?? "none";
- const reportProgramProgress = args.presentation.json
+ const progressWriter = args.presentation.json ? io.writeProgress : io.writeProgress ?? io.write;
+ const reportProgramProgress = progressWriter === undefined
? undefined
- : (event: { readonly id: string; readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready"; readonly logPath?: string }): void => {
- if (!args.presentation.verbose && event.phase !== "installing" && event.phase !== "starting") return;
+ : (event: CliManagedProgramProgress): void => {
+ if (!args.presentation.verbose && event.detail === undefined && event.phase !== "installing" && event.phase !== "starting") return;
const verb = {
checking: "Checking",
installing: "Installing",
@@ -69,12 +75,12 @@ export async function runEnvironmentCommand(input: {
waiting: "Waiting for",
ready: "Ready",
}[event.phase];
- io.write(` · ${verb} ${event.id}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
+ progressWriter(` · ${verb} ${event.id}${event.detail === undefined ? "" : ` — ${event.detail}`}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
};
- const reportPackageProgress = args.presentation.json
+ const reportPackageProgress = progressWriter === undefined
? undefined
: (event: { readonly specifier: string; readonly phase: "checking" | "installing" | "ready"; readonly logPath?: string }): void => {
- if (event.phase === "installing") io.write(` · Installing ${event.specifier}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
+ if (event.phase === "installing") progressWriter(` · Installing ${event.specifier}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
};
const reportCredentialProgress = args.presentation.json
? io.writeProgress
@@ -183,22 +189,25 @@ export async function runEnvironmentCommand(input: {
? await controller.programs.down(args.endpoints === undefined ? {} : { endpoints: args.endpoints })
: await controller.programs.report(args.endpoints === undefined ? {} : { endpoints: args.endpoints });
const ready = result.programs.every((item) => item.state.state === "ready");
- const desiredState = args.action === "down" ? !result.programs.some((item) => item.state.state === "ready") : ready;
- const lifecycleOk = args.action === "status" || desiredState;
const needsAttention = (item: typeof result.programs[number]) => args.action === "down"
- ? item.state.state === "ready" : item.state.state !== "ready";
+ ? item.state.state !== "down" || (item.action !== "stopped" && item.action !== "nothing-to-stop")
+ : item.state.state !== "ready";
+ // Readiness describes the service, not whether a stop was performed. An owned process can
+ // still be loading, and another command may have declined a concurrent stop during preparation.
+ const lifecycleOk = args.action === "status" || !result.programs.some(needsAttention);
const relevant = result.programs.filter((item) => args.presentation.verbose || args.action === "status" || needsAttention(item));
const urgent = relevant.filter(needsAttention);
const shownPrograms = [...urgent, ...relevant.filter((item) => !needsAttention(item)).slice(0, Math.max(0, args.limit - urgent.length))];
const omittedPrograms = relevant.length - shownPrograms.length;
const title = args.action === "up"
- ? desiredState ? "External programs ready" : "External programs need attention"
+ ? lifecycleOk ? "External programs ready" : "External programs need attention"
: args.action === "down"
- ? desiredState ? "External programs stopped" : "Some external programs are still running"
+ ? lifecycleOk ? "External programs stopped" : "External program stop needs attention"
: "External program status";
write({
format: "hypit.cli-programs@1",
action: args.action,
+ ok: lifecycleOk,
ready,
programCount: result.programs.length,
readyCount: result.programs.filter((item) => item.state.state === "ready").length,
@@ -278,9 +287,12 @@ export async function runEnvironmentCommand(input: {
const worker = await controller.worker.down({
...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
});
+ const stopped = worker.state === "stopped";
write({ format: "hypit.cli-runtime-down@1", worker: worker.state },
- "Runtime Worker is down", "success", [["Worker", worker.state]],
- ["Managed programs were left running. Stop them explicitly with hypit programs down."]);
+ stopped ? "Runtime Worker is down" : "Runtime Worker is still running",
+ stopped ? "success" : "warning", [["Worker", worker.state]],
+ [`Managed programs were left running. To stop them: ${commandHint(["programs", "down"], { projectRoot, runtimeProfile: resolve(profile) })}`]);
+ if (!stopped) io.setExitCode?.(1);
return;
}
@@ -324,7 +336,8 @@ export async function runEnvironmentCommand(input: {
};
write(machine, attention
? "Local Runtime needs attention"
- : ready ? "Local Runtime ready" : "Runtime Worker stopped",
+ : ready ? "Local Runtime ready" : worker.state === "running"
+ ? "Runtime Worker running; Programs not ready" : "Runtime Worker stopped",
attention ? "warning" : ready ? "success" : "info", [
["Worker", worker.state],
["Active Builds", String(activity.builds.length)],
@@ -365,6 +378,10 @@ export async function runEnvironmentCommand(input: {
kind: item.kind,
configured: item.configured,
writable: item.writable,
+ ...(item.acquisition === undefined ? {} : { acquisition: {
+ kind: item.acquisition.kind,
+ authorizationEndpoint: item.acquisition.authorizationEndpoint,
+ } }),
}));
write({
format: "hypit.cli-auth-status@1",
@@ -374,8 +391,12 @@ export async function runEnvironmentCommand(input: {
}, "Credential status", "info", [
["Endpoint", args.endpoint],
["Configured", `${credentials.filter((item) => item.configured).length}/${credentials.length}`],
- ], credentials.slice(0, args.limit).map((item) =>
- `${item.slot}: ${item.configured ? "configured" : "missing"} · ${item.writable ? "writable" : "read-only"}`));
+ ], credentials.slice(0, args.limit).map((item) => {
+ const entry = !item.writable ? "managed by its external credential source"
+ : item.acquisition === undefined ? "login uses secure secret input"
+ : `login opens OAuth: ${item.acquisition.authorizationEndpoint}`;
+ return `${item.slot}: ${item.configured ? "configured" : "missing"} · ${item.writable ? "writable" : "read-only"} · ${entry}`;
+ }));
} else if (args.action === "login") {
const [item] = credentials;
if (item === undefined) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
diff --git a/packages/cli/src/commands/execution.ts b/packages/cli/src/commands/execution.ts
index 48d2fb69..cadf2835 100644
--- a/packages/cli/src/commands/execution.ts
+++ b/packages/cli/src/commands/execution.ts
@@ -1,8 +1,11 @@
+import { resolve } from "node:path";
+
import { readExecutionLog } from "@hypit/runtime";
import type { BuildResultManifest, BuildResultRepository } from "@hypit/build-result";
import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
import type { CliCommand, ExecutionCommand } from "../command.js";
+import { commandHint } from "../command-hint.js";
import { activityObservationKey, buildProgressLines, buildProgressView, observeBuildView } from "../observation.js";
import type { CliIo } from "../output.js";
import type { CliRuntimeController } from "../runtime-port.js";
@@ -37,6 +40,7 @@ export function isExecutionCommand(args: CliCommand): args is ExecutionCommand {
/** Inspect or control accepted Build work. Observation never owns execution. */
export async function runExecutionCommand(input: {
readonly args: ExecutionCommand;
+ readonly projectRoot: string;
readonly runtimeProfile: string | undefined;
readonly resolveProjectRuntime?: () => Promise<string | undefined>;
readonly io: CliIo;
@@ -46,6 +50,10 @@ export async function runExecutionCommand(input: {
readonly write: OperationalWriter;
}): Promise<void> {
const { args, runtimeProfile, io, runtimeHost, runtimeController, openProjectResults, write } = input;
+ const commandScope = {
+ projectRoot: input.projectRoot,
+ ...(runtimeProfile === undefined ? {} : { runtimeProfile: resolve(runtimeProfile) }),
+ };
if (args.command === "logs") {
const opened = await openProjectResults();
let source: "runtime" | "result" | "unavailable" = "unavailable";
@@ -164,7 +172,7 @@ export async function runExecutionCommand(input: {
controller.worker.status(),
]);
const builds = activity.builds.slice(0, args.limit).map((item) => {
- const status = buildStatusView({ id: item.id, runtime: item });
+ const status = buildStatusView({ id: item.id, runtime: item, commandScope });
return {
id: item.id,
work: status.work,
@@ -219,23 +227,23 @@ export async function runExecutionCommand(input: {
let result: BuildResultManifest | undefined;
let resultReadError: string | undefined;
let openedResults: Awaited<ReturnType<OpenProjectResults>> | undefined;
+ if (args.watch && view !== undefined && view.issue === undefined) {
+ const controller = await runtimeController(runtimeProfile);
+ view = await observeBuildView(runtime, args.build, view, {
+ ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
+ controller,
+ commandScope,
+ onProgress: (progress) => {
+ const report = io.writeProgress ?? (args.presentation.json ? undefined : io.write);
+ for (const line of buildProgressLines(progress, {
+ verbose: args.presentation.verbose,
+ limit: args.limit,
+ })) report?.(`${line}\n`);
+ },
+ });
+ }
try {
openedResults = await openProjectResults();
- if (args.watch && view !== undefined && view.issue === undefined) {
- const controller = await runtimeController(runtimeProfile);
- view = await observeBuildView(runtime, args.build, view, {
- ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
- controller,
- ...(args.presentation.json ? {} : {
- onProgress: (progress) => {
- for (const line of buildProgressLines(progress, {
- verbose: args.presentation.verbose,
- limit: args.limit,
- })) io.write(`${line}\n`);
- },
- }),
- });
- }
result = await openedResults.repository.read(args.build);
} catch (error) {
resultReadError = error instanceof Error ? error.message : String(error);
@@ -250,6 +258,7 @@ export async function runExecutionCommand(input: {
const issue = view?.issue;
const build = !found ? null : buildStatusView({
id: view?.id ?? result!.id,
+ commandScope,
...(view === undefined ? {} : { runtime: view }),
...(result === undefined ? {} : { result }),
...(resultReadError === undefined ? {} : { resultReadError }),
@@ -338,7 +347,7 @@ export async function runExecutionCommand(input: {
outcome: finished.outcome,
...(finished.issue === undefined ? {} : { attention: {
message: finished.issue.message,
- action: `hypit result finish ${args.build}`,
+ action: commandHint(["result", "finish", args.build], commandScope),
} }),
}, finished.issue === undefined ? "Result finished" : "Result still needs attention",
finished.issue === undefined ? "success" : "error", [
@@ -356,6 +365,7 @@ export async function runExecutionCommand(input: {
: await openedResults.repository.read(args.build).finally(async () => await openedResults.close());
const build = active === undefined && finished === undefined ? null : buildStatusView({
id: args.build,
+ commandScope,
...(active === undefined ? {} : { runtime: active }),
...(finished === undefined ? {} : { result: finished }),
});
diff --git a/packages/cli/src/commands/results.ts b/packages/cli/src/commands/results.ts
index 46e3cd9a..d2c242dc 100644
--- a/packages/cli/src/commands/results.ts
+++ b/packages/cli/src/commands/results.ts
@@ -13,6 +13,7 @@ import {
projectPath,
} from "../view.js";
import type { OperationalWriter } from "./types.js";
+import { commandHint } from "../command-hint.js";
export function isProjectResultCommand(args: CliCommand): args is ProjectResultCommand {
return args.command === "builds" || args.command === "history" || args.command === "inspect"
@@ -120,7 +121,7 @@ export async function runProjectResultCommand(input: {
] : []),
], [
...(build.failure === undefined ? [] : [`Reason ${build.failure}`]),
- ...(build.executionLog === undefined ? [] : [`Execution log hypit logs ${build.id}`]),
+ ...(build.executionLog === undefined ? [] : [`Execution log ${commandHint(["logs", build.id], { projectRoot })}`]),
...(build.operations ?? []).map((operation) =>
`${operation.endpoint}: ${operation.status}${operation.receipt === undefined ? "" : ` · task ${operation.receipt.id}`}`
+ (operation.failure === undefined ? "" : ` · ${operation.failure.code}: ${operation.failure.message}`)),
diff --git a/packages/cli/src/machine-view.ts b/packages/cli/src/machine-view.ts
index 20a39134..f2ad7bb6 100644
--- a/packages/cli/src/machine-view.ts
+++ b/packages/cli/src/machine-view.ts
@@ -9,6 +9,8 @@ type ProgramStateView = {
readonly detail?: string;
readonly pid?: number;
readonly logPath?: string;
+ readonly installationLogPath?: string;
+ readonly errorLogPath?: string;
};
type AttentionView = { readonly message: string; readonly action?: string };
@@ -18,12 +20,12 @@ export type OperationalMachineView =
| { readonly format: "hypit.cli-runtime-selection@1"; readonly selected: boolean; readonly removed?: boolean; readonly profile?: string; readonly project?: string }
| { readonly format: "hypit.cli-paths@1"; readonly project: string; readonly projectState: string; readonly profileSource: "argument" | "project" | "none"; readonly selectionFile: string; readonly profile?: string; readonly runtimeData?: string; readonly hostState: string; readonly machinePackages: string; readonly distribution?: string }
| { readonly format: "hypit.cli-package@1"; readonly action: "install" | "status"; readonly package: string; readonly ready: boolean }
- | { readonly format: "hypit.cli-programs@1"; readonly action: "up" | "down" | "status"; readonly ready: boolean; readonly programCount: number; readonly readyCount: number; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
+ | { readonly format: "hypit.cli-programs@1"; readonly action: "up" | "down" | "status"; readonly ok: boolean; readonly ready: boolean; readonly programCount: number; readonly readyCount: number; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
| { readonly format: "hypit.cli-runtime-up@1"; readonly ready: boolean; readonly worker: string; readonly preparedPackages: number; readonly programs: { readonly total: number; readonly ready: number; readonly items: readonly ProgramStateView[] } }
| { readonly format: "hypit.cli-runtime-logs@1"; readonly lines: readonly string[]; readonly totalLines: number; readonly omittedLines: number; readonly path?: string }
| { readonly format: "hypit.cli-runtime-down@1"; readonly worker: string }
| { readonly format: "hypit.cli-runtime-status@1"; readonly ready: boolean; readonly attention: boolean; readonly worker: { readonly state: string; readonly configuration?: string }; readonly builds: Readonly<Record<string, number>>; readonly programs: { readonly total: number; readonly ready: number; readonly unavailable: readonly ProgramStateView[] }; readonly capacity: { readonly active: number } }
- | { readonly format: "hypit.cli-auth-status@1"; readonly endpoint: string; readonly credentials: readonly { readonly endpoint: string; readonly slot: string; readonly label: string; readonly kind: string; readonly configured: boolean; readonly writable: boolean }[]; readonly omittedCredentials?: number }
+ | { readonly format: "hypit.cli-auth-status@1"; readonly endpoint: string; readonly credentials: readonly { readonly endpoint: string; readonly slot: string; readonly label: string; readonly kind: string; readonly configured: boolean; readonly writable: boolean; readonly acquisition?: { readonly kind: string; readonly authorizationEndpoint: string } }[]; readonly omittedCredentials?: number }
| { readonly format: "hypit.cli-auth-change@1"; readonly endpoint: string; readonly slot: string; readonly configured: boolean; readonly changed?: boolean }
| { readonly format: "hypit.cli-builds@1"; readonly builds: readonly { readonly id: string; readonly createdAt: string; readonly title?: string; readonly outcome: string; readonly run?: string; readonly targetCount: number; readonly targets?: readonly string[]; readonly omittedTargets?: number; readonly outputCount: number }[]; readonly next?: string }
| { readonly format: "hypit.cli-history@1"; readonly output: string; readonly source?: string; readonly entries: readonly { readonly build: string; readonly title?: string; readonly createdAt: string; readonly outcome: string; readonly output: CliOutputView }[]; readonly next?: string }
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index cce5a6a9..dea9dca6 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -17,6 +17,7 @@ import { createPlanOutput, createPricingOutput, writeCliHelp, writeCliOutput } f
import type { CliIo, CliMachineView } from "./output.js";
import { parseCommand } from "./arguments.js";
import type { CliCommand, RuntimeOption } from "./command.js";
+import { commandHint } from "./command-hint.js";
import { assertPlannedRequests, assertPreflight, createCatalogDescriptor, describePlanNeeds, describePlanPricing, describePlanProviders, evaluatePlanNeeds, preflightPlan } from "./build-planning.js";
import { buildProgressLines, observeBuild } from "./observation.js";
import { isProjectResultCommand, runProjectResultCommand } from "./commands/results.js";
@@ -180,14 +181,11 @@ export async function runCli(
let runtimeProfile = acceptsRuntimeContext(args) ? args.runtimeProfile : undefined;
let runtimeSelectionFile: string | undefined;
- const runtimeWasExplicit = runtimeProfile !== undefined;
- let runtimeNeedsHint = runtimeWasExplicit;
if (acceptsRuntimeContext(args) && runtimeProfile === undefined && args.command !== "logs") {
const selected = await findRuntimeProfile(await commandProjectRoot());
if (selected !== undefined) {
runtimeProfile = selected.profile;
runtimeSelectionFile = selected.selectionFile;
- runtimeNeedsHint = false;
}
}
const runtimeController = async (profile: string): Promise<CliRuntimeController> => {
@@ -228,6 +226,7 @@ export async function runCli(
if (isExecutionCommand(args)) {
await runExecutionCommand({
args,
+ projectRoot: await commandProjectRoot(),
runtimeProfile,
io,
runtimeHost,
@@ -347,6 +346,7 @@ export async function runCli(
if (runtimeProfile === undefined) {
throw new Error("build requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>");
}
+ const commandScope = { projectRoot: projectResultsRoot, runtimeProfile: resolve(runtimeProfile) };
const buildResults = await projectResults(projectResultsRoot);
let loadedRun;
try {
@@ -435,7 +435,7 @@ export async function runCli(
]),
].join(" · ");
if (args.follow && "view" in built && !args.presentation.json) {
- const acceptedView = buildStatusView({ id: built.id, runtime: built.view });
+ const acceptedView = buildStatusView({ id: built.id, runtime: built.view, commandScope });
const targets = built.view.targets.slice(0, args.limit);
writeOperational({
format: "hypit.cli-build@1",
@@ -452,15 +452,15 @@ export async function runCli(
built = await observeBuild(runtime, built, {
...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
controller,
+ commandScope,
readResult: async () => await buildResults.repository.read(built.id),
- ...(args.presentation.json ? {} : {
- onProgress: (progress) => {
- for (const line of buildProgressLines(progress, {
- verbose: args.presentation.verbose,
- limit: args.limit,
- })) io.write(`${line}\n`);
- },
- }),
+ onProgress: (progress) => {
+ const report = io.writeProgress ?? (args.presentation.json ? undefined : io.write);
+ for (const line of buildProgressLines(progress, {
+ verbose: args.presentation.verbose,
+ limit: args.limit,
+ })) report?.(`${line}\n`);
+ },
});
}
const finished = "completion" in built;
@@ -491,6 +491,7 @@ export async function runCli(
});
const buildView = buildStatusView({
id: built.id,
+ commandScope,
...(activeView === undefined ? {} : { runtime: activeView }),
...(finishedResult === undefined ? {} : { result: finishedResult }),
verbose: args.presentation.verbose,
@@ -501,7 +502,7 @@ export async function runCli(
? buildView
: { ...buildView, title: args.title },
};
- const runtimeHint = runtimeNeedsHint ? ` --runtime ${runtimeProfile}` : "";
+ const resultScope = { projectRoot: projectResultsRoot };
const resultTargets = finishedResult?.targets.flatMap((name) => {
const output = finishedResult.outputs[name];
return output === undefined ? [] : [{ name, output }];
@@ -509,11 +510,11 @@ export async function runCli(
const finishedLines = resultTargets.length === 0 && targetPresentations.length === 0
? [
...(completionReason === undefined ? [] : [`Reason ${completionReason}`]),
- `Inspect hypit inspect ${built.id}`,
+ `Inspect ${commandHint(["inspect", built.id], resultScope)}`,
]
: [
...(completionReason === undefined ? [] : [`Reason ${completionReason}`]),
- `Inspect hypit inspect ${built.id}`,
+ `Inspect ${commandHint(["inspect", built.id], resultScope)}`,
...resultTargets
.filter((item) => item.output.value.kind === "inline")
.slice(0, args.limit)
@@ -524,14 +525,14 @@ export async function runCli(
.filter((item) => item.output.value.kind !== "inline")
.slice(0, args.limit)
.map((item) =>
- `Export hypit get ${built.id} --output ${item.name} --to <path>`),
+ `Export ${commandHint(["get", built.id, "--output", item.name], resultScope)} --to <path>`),
...(resultTargets.length > 0 ? [] : targetPresentations
.filter((item) => item.inline !== undefined)
.slice(0, args.limit)
.map((item) => `Result ${item.published.name} = ${item.inline}`)),
];
const humanTitle = issue !== undefined
- ? "Result needs attention"
+ ? "Build needs attention"
: finished
? buildOutcome === "complete"
? "Build complete"
@@ -551,14 +552,14 @@ export async function runCli(
] : []),
...(issue === undefined ? [] : [
["Execution", buildOutcome ?? machine.build.work.state] as const,
- ["Result", "needs attention"] as const,
+ [issue.scope === "cleanup" ? "Cleanup" : "Result", "needs attention"] as const,
]),
], finished ? finishedLines : issue !== undefined ? [
- `Result ${issue.scope}: ${issue.message}`,
- `Finish hypit result finish ${built.id}${runtimeHint}`,
+ `Attention ${issue.scope}: ${issue.message}`,
+ `Finish ${commandHint(["result", "finish", built.id], commandScope)}`,
] : [
- `Watch hypit status ${built.id}${runtimeHint} --watch`,
- `Cancel hypit cancel ${built.id}${runtimeHint}`,
+ `Watch ${commandHint(["status", built.id, "--watch"], commandScope)}`,
+ `Cancel ${commandHint(["cancel", built.id], commandScope)}`,
]);
if (buildOutcome === "failed" || issue !== undefined) io.setExitCode?.(1);
} finally {
diff --git a/packages/cli/src/observation.ts b/packages/cli/src/observation.ts
index 8f160454..a03e84de 100644
--- a/packages/cli/src/observation.ts
+++ b/packages/cli/src/observation.ts
@@ -1,6 +1,8 @@
import type { BuildResultManifest } from "@hypit/build-result";
import type { CliBuildSubmission, CliBuildView, CliRuntimeControl, CliRuntimeController } from "./runtime-port.js";
+import { commandHint } from "./command-hint.js";
+import type { CommandScope } from "./command-hint.js";
import { formatOperationProgress } from "./runtime-view.js";
const FIRST_HEARTBEAT_MS = 30_000;
@@ -122,6 +124,7 @@ export async function observeBuildView(
readonly maxWaitMs?: number;
readonly controller?: CliRuntimeController;
readonly onProgress?: (value: BuildProgressView) => void;
+ readonly commandScope?: CommandScope;
} = {},
): Promise<CliBuildView | undefined> {
let view: CliBuildView | undefined = initial;
@@ -158,8 +161,9 @@ export async function observeBuildView(
const worker = await options.controller.worker.status();
if (worker.state !== "running") {
throw new Error(
- `Runtime Worker is ${worker.state}; Build ${build} remains durable. `
- + `Run hypit runtime up, then run hypit status ${build} --watch again`,
+ `Runtime Worker is ${worker.state}; stopped watching Build ${build}. `
+ + `Inspect the Runtime with ${commandHint(["runtime", "status"], options.commandScope)}; `
+ + `read execution evidence with ${commandHint(["logs", build], options.commandScope)}`,
);
}
}
@@ -184,6 +188,7 @@ export async function observeBuild(
readonly controller?: CliRuntimeController;
readonly readResult: () => Promise<BuildResultManifest | undefined>;
readonly onProgress?: (value: BuildProgressView) => void;
+ readonly commandScope?: CommandScope;
},
): Promise<CliBuildSubmission> {
const finishFromResult = async (): Promise<CliBuildSubmission> => {
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index 351fe46b..4442d7cf 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -971,6 +971,9 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
" hypit auth login <endpoint-instance> [--runtime <profile>] [--slot <name>] [--from <secret-file>]",
" hypit auth logout <endpoint-instance> [--runtime <profile>] [--slot <name>]",
" All auth actions accept --workspace <project> to use that project's selection.",
+ " status shows credential presence and the Provider's declared browser login, if any.",
+ " login opens that browser flow or securely prompts for the secret; --from imports a secret instead.",
+ " Configure the service's Endpoint first. Storing a key does not install a Provider or select bindings.",
],
};
const selected = topics[topic];
diff --git a/packages/cli/src/view.ts b/packages/cli/src/view.ts
index d6502d4e..1864ae9c 100644
--- a/packages/cli/src/view.ts
+++ b/packages/cli/src/view.ts
@@ -8,6 +8,8 @@ import type {
import { buildIdCreatedAt } from "@hypit/protocol";
import type { TypeRef } from "@hypit/protocol";
import type { BuildView } from "@hypit/runtime-host-node";
+import { commandHint } from "./command-hint.js";
+import type { CommandScope } from "./command-hint.js";
export type PublicOutputKind = "scalar" | "resource" | "composite";
@@ -159,6 +161,7 @@ export function buildStatusView(options: {
readonly result?: BuildResultManifest;
readonly resultReadError?: string;
readonly verbose?: boolean;
+ readonly commandScope?: CommandScope;
}): CliBuildStatusView {
const resultState = options.resultReadError !== undefined
? "unavailable" as const
@@ -195,7 +198,7 @@ export function buildStatusView(options: {
attention: issue !== undefined
? {
message: issue.message,
- ...(issue.scope === "result" ? { action: `hypit result finish ${options.id}` } : {}),
+ action: commandHint(["result", "finish", options.id], options.commandScope),
}
: { message: options.resultReadError! },
}),
diff --git a/packages/cli/test/build-programs.test.ts b/packages/cli/test/build-programs.test.ts
index 9461ed4d..a352430c 100644
--- a/packages/cli/test/build-programs.test.ts
+++ b/packages/cli/test/build-programs.test.ts
@@ -1,13 +1,14 @@
import assert from "node:assert/strict";
import { mkdtemp, readFile, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
import test from "node:test";
import { FileBuildResultRepository } from "@hypit/build-result";
import { createRunFrontendHostFacet } from "@hypit/run";
import { runCli } from "../src/main.js";
+import { commandHint } from "../src/command-hint.js";
import type { CliDistribution } from "../src/distribution.js";
import type { RuntimeDoctorDiagnostic } from "@hypit/runtime-kit";
@@ -220,6 +221,29 @@ test("Build confirms durable submission before following stable work progress",
assert.match(output, /Target\s+result/u);
assert.match(output, /Work\s+0 requests/u);
assert.match(output, /Ctrl-C stops watching; the Build continues\./u);
+
+ output = "";
+ let progress = "";
+ const projectRoot = dirname(source);
+ const runtimeProfile = resolve("/p/a selected runtime.json");
+ await runCli([
+ "build", source, "--workspace", projectRoot, "--runtime", runtimeProfile,
+ "--follow", "--max-wait-ms", "0", "--json",
+ ], {
+ write(text) { output += text; }, writeProgress(text) { progress += text; },
+ }, distribution(calls, [], "./main.svml", execution));
+ const build = JSON.parse(output).build;
+ assert.equal(build.work.state, "working");
+ assert.match(progress, /Working/u);
+
+ output = "";
+ await runCli([
+ "build", source, "--workspace", projectRoot, "--runtime", runtimeProfile,
+ ], { write(text) { output += text; } }, distribution(calls, [], "./main.svml", execution));
+ const id = /Watch\s+hypit status (\S+)/u.exec(output)?.[1];
+ assert.ok(id);
+ assert.ok(output.includes(commandHint(["status", id, "--watch"], { projectRoot, runtimeProfile })));
+ assert.ok(output.includes(commandHint(["cancel", id], { projectRoot, runtimeProfile })));
});
test("plan preserves the selected work summary but exits non-zero when cheap preflight fails", async () => {
diff --git a/packages/cli/test/build-results.test.ts b/packages/cli/test/build-results.test.ts
index d6ca3f7c..eb7491d3 100644
--- a/packages/cli/test/build-results.test.ts
+++ b/packages/cli/test/build-results.test.ts
@@ -3,6 +3,7 @@ import { mkdtemp, readFile, readdir, realpath, rm, stat, writeFile } from "node:
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pathToFileURL } from "node:url";
+import { commandHint } from "../src/command-hint.js";
import test from "node:test";
import { FileBuildResult, FileBuildResultRepository } from "@hypit/build-result";
@@ -610,7 +611,7 @@ test("a failed Result exposes task receipts and credential references without a
need: { id: "generation-1", capability: valueType },
credentials: { apiKey: { store: "os", key: "personal-api-key" } },
receipt: { id: "remote-task-1" }, status: "failed" as const,
- failure: { code: "DOWNLOAD_FAILED", message: "network timed out" },
+ failure: { code: "DOWNLOAD_FAILED", message: `HTTP 502; request=req-example; ${"public reason ".repeat(35)}last diagnostic detail` },
createdAt: 1, acknowledgedAt: 2,
};
await result.finish({ outcome: "failed", failure: "download failed", operations: [operation] });
@@ -626,6 +627,7 @@ test("a failed Result exposes task receipts and credential references without a
const human = await humanCommand(["inspect", id], root);
assert.match(human, /remote-task-1/);
assert.match(human, /DOWNLOAD_FAILED/);
+ assert.ok(human.includes(operation.failure.message));
} finally { await rm(root, { recursive: true, force: true }); }
});
@@ -641,6 +643,9 @@ test("logs reads finished evidence without a Runtime and clearly limits the tail
yield Buffer.from(records.map((record) => JSON.stringify(record) + "\n").join(""));
})() });
await writeFile(join(root, ".hypit/runtime"), "missing-profile.json\n");
+ assert.ok((await humanCommand(["inspect", id], root)).includes(
+ commandHint(["logs", id], { projectRoot: root }),
+ ));
assert.deepEqual(await jsonCommand(["logs", id, "--lines", "1"], root), {
format: "hypit.cli-logs@1", build: id, source: "result", records: [records[1]], omittedRecords: 1,
});
diff --git a/packages/cli/test/command-hint.test.ts b/packages/cli/test/command-hint.test.ts
new file mode 100644
index 00000000..45b745c5
--- /dev/null
+++ b/packages/cli/test/command-hint.test.ts
@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import test from "node:test";
+
+import { commandHint } from "../src/command-hint.js";
+
+test("POSIX command hints preserve selectors and literal path characters when copied", { skip: process.platform === "win32" }, () => {
+ const args = ["get", "build-1", "--output", "scene's $draft `name`", "--to", ""];
+ const projectRoot = "/tmp/film $(printf changed)";
+ const runtimeProfile = "/tmp/voice & picture/profile.json";
+ const command = commandHint(args, { projectRoot, runtimeProfile }, "posix");
+ const output = execFileSync("/bin/sh", ["-c",
+ `hypit() { "$HINT_TEST_NODE" -e 'process.stdout.write(JSON.stringify(process.argv.slice(1)))' -- "$@"; }; ${command}`,
+ ], { encoding: "utf8", env: { ...process.env, HINT_TEST_NODE: process.execPath } });
+ assert.deepEqual(JSON.parse(output), [...args, "--workspace", projectRoot, "--runtime", runtimeProfile]);
+});
+
+test("PowerShell command hints quote paths as literal strings", () => {
+ assert.equal(commandHint(["status", "build-1", "--watch"], {
+ projectRoot: "C:\\Films\\director's cut", runtimeProfile: "C:\\$profiles\\voice`new.json",
+ }, "powershell"), "hypit status build-1 --watch --workspace 'C:\\Films\\director''s cut' --runtime 'C:\\$profiles\\voice`new.json'");
+});
diff --git a/packages/cli/test/control-commands.test.ts b/packages/cli/test/control-commands.test.ts
index 928b5117..48af0161 100644
--- a/packages/cli/test/control-commands.test.ts
+++ b/packages/cli/test/control-commands.test.ts
@@ -5,6 +5,7 @@ import test from "node:test";
import type { CliDistribution } from "../src/distribution.js";
import { runCli } from "../src/main.js";
import type { CliCredentialControl, CliRuntimeControl } from "../src/runtime-port.js";
+import { commandHint } from "../src/command-hint.js";
test("activity opens Runtime control without constructing execution Providers", async () => {
const calls: string[] = [];
@@ -138,9 +139,14 @@ test("status --watch follows active execution, then reads its finished Result",
} as unknown as CliDistribution;
let output = "";
+ let progress = "";
await runCli([
"status", "build-watch", "--runtime", "/tmp/runtime.json", "--watch", "--json",
- ], { write: (text) => { output += text; } }, distribution);
+ ], {
+ write: (text) => { output += text; },
+ writeProgress: (text) => { progress += text; },
+ }, distribution);
+ assert.match(progress, /Working/u);
const result = JSON.parse(output) as {
readonly build: { readonly id: string; readonly work: { readonly outcome: string }; readonly result: { readonly state: string } };
@@ -264,7 +270,7 @@ test("status preserves Runtime decision and attention when its Result Store is u
createdAt: 1,
activity: "saving-result" as const,
outcome: "failed" as const,
- issue: { scope: "result" as const, message: "S3 unavailable" },
+ issue: { scope: "result" as "result" | "cleanup", message: "S3 unavailable" },
cancellationRequested: false,
targets: [],
acceptedRecords: 0,
@@ -287,23 +293,34 @@ test("status preserves Runtime decision and attention when its Result Store is u
let exitCode = 0;
await runCli([
- "status", view.id, "--runtime", "/tmp/runtime.json", "--json",
+ "status", view.id, "--workspace", "/tmp", "--runtime", "/tmp/runtime with space.json", "--json",
], { write: (text) => { output += text; }, setExitCode: (code) => { exitCode = code; } }, distribution);
const result = JSON.parse(output) as {
readonly build: {
readonly work: { readonly outcome: string };
readonly result: { readonly state: string };
- readonly attention: { readonly message: string };
+ readonly attention: { readonly message: string; readonly action: string };
};
};
assert.equal(result.build.work.outcome, "failed");
assert.equal(result.build.result.state, "unavailable");
assert.equal(result.build.attention.message, "S3 unavailable");
+ assert.equal(result.build.attention.action, commandHint(["result", "finish", view.id], {
+ projectRoot: resolve("/tmp"), runtimeProfile: resolve("/tmp/runtime with space.json"),
+ }));
assert.deepEqual((result.build as { operations?: unknown }).operations, [{
endpoint: "images.internal", state: "failed", failure: { code: "REMOTE", message: "provider detail" },
}]);
assert.equal(exitCode, 1);
+ view.issue = { scope: "cleanup", message: "temporary resource cleanup unavailable" };
+ output = "";
+ await runCli([
+ "status", view.id, "--workspace", "/tmp", "--runtime", "/tmp/runtime with space.json", "--json",
+ ], { write: (text) => { output += text; } }, distribution);
+ const cleanup = JSON.parse(output).build.attention;
+ assert.equal(cleanup.message, "temporary resource cleanup unavailable");
+ assert.equal(cleanup.action, result.build.attention.action);
});
test("result finish writes only an already-decided Result that needs attention", async () => {
@@ -496,6 +513,52 @@ test("auth opens only one Endpoint credential control, never the execution Runti
assert.equal("key" in machine.credentials[0]!, false);
});
+test("auth status exposes declared acquisition without acquiring or revealing credentials", async () => {
+ const acquisition = {
+ kind: "oauth2-pkce", authorizationEndpoint: "https://service.example/authorize",
+ tokenEndpoint: "https://service.example/token", clientId: "example-client", scopes: ["inference"],
+ };
+ const distribution = {
+ openRuntimeHost: async () => ({
+ openCredentials: async () => ({
+ credentials: async () => [
+ { endpoint: "service.project", slot: "browser", label: "Service access", kind: "secret",
+ configured: false, writable: true, ref: { store: "os", key: "private-reference" }, acquisition,
+ secret: "not-for-display" },
+ { endpoint: "service.project", slot: "key", label: "Service key", kind: "secret",
+ configured: false, writable: true, ref: { store: "os", key: "private-reference" } },
+ { endpoint: "service.project", slot: "external", label: "External key", kind: "secret",
+ configured: false, writable: false, ref: { store: "env", key: "PRIVATE_KEY" } },
+ ],
+ putCredential: async () => { throw new Error("Status must not acquire a credential"); },
+ close() {},
+ }),
+ createRuntime: async () => { throw new Error("Status must not start execution"); },
+ }),
+ } as unknown as CliDistribution;
+ for (const json of [true, false]) {
+ let output = "";
+ await runCli(["auth", "status", "service.project", "--runtime", "/tmp/runtime.json", ...(json ? ["--json"] : [])], {
+ write: (text) => { output += text; },
+ readSecret: async () => { throw new Error("Status must not request user input"); },
+ }, distribution);
+ assert.doesNotMatch(output, /not-for-display|private-reference|PRIVATE_KEY|example-client/u);
+ if (json) {
+ const view = JSON.parse(output);
+ assert.equal(view.format, "hypit.cli-auth-status@1");
+ assert.deepEqual(view.credentials[0].acquisition, {
+ kind: "oauth2-pkce", authorizationEndpoint: "https://service.example/authorize",
+ });
+ assert.equal(view.credentials[1].acquisition, undefined);
+ assert.equal(view.credentials[2].writable, false);
+ } else {
+ assert.match(output, /login opens OAuth: https:\/\/service.example\/authorize/u);
+ assert.match(output, /login uses secure secret input/u);
+ assert.match(output, /managed by its external credential source/u);
+ }
+ }
+});
+
test("runtime logs returns only the requested tail and hides its path by default", async () => {
const distribution = {
openRuntimeHost: async (path: string) => ({
@@ -627,3 +690,35 @@ test("cancelling an already failed execution preserves and reports its stop reas
assert.match(output, /already stopping after failure/);
assert.match(output, /Original execution failure/);
});
+
+test("a stopped Worker ends observation with scoped evidence commands, not a Result-read failure", async () => {
+ const projectRoot = resolve("/tmp");
+ const runtimeProfile = resolve("/tmp/selected runtime.json");
+ let closed = false;
+ let resultOpened = false;
+ const selected = {
+ openRuntimeHost: async () => ({
+ openControl: async () => ({
+ inspect: async () => ({
+ id: "waiting-build", createdAt: Date.now(), activity: "waiting", cancellationRequested: false,
+ targets: [], acceptedRecords: 0, outstandingCommands: 1, operations: [],
+ }),
+ close() { closed = true; },
+ }),
+ controller: async () => ({ worker: {
+ status: async () => ({ state: "stopped", profile: runtimeProfile, logPath: "/tmp/worker.log" }),
+ } }),
+ }),
+ openProjectResults: async () => { resultOpened = true; throw new Error("must not be mistaken for result storage"); },
+ } as unknown as CliDistribution;
+ await assert.rejects(runCli([
+ "status", "waiting-build", "--workspace", projectRoot, "--runtime", runtimeProfile, "--watch", "--json",
+ ], { write() {} }, selected), (error: Error) => {
+ assert.match(error.message, /Runtime Worker is stopped; stopped watching Build waiting-build/u);
+ assert.ok(error.message.includes(commandHint(["runtime", "status"], { projectRoot, runtimeProfile })));
+ assert.ok(error.message.includes(commandHint(["logs", "waiting-build"], { projectRoot, runtimeProfile })));
+ return true;
+ });
+ assert.equal(closed, true);
+ assert.equal(resultOpened, false);
+});
diff --git a/packages/cli/test/programs-command.test.ts b/packages/cli/test/programs-command.test.ts
index d9ca3229..8e2fbe00 100644
--- a/packages/cli/test/programs-command.test.ts
+++ b/packages/cli/test/programs-command.test.ts
@@ -3,8 +3,9 @@ import { resolve } from "node:path";
import test from "node:test";
import { runCli } from "../src/main.js";
+import { commandHint } from "../src/command-hint.js";
import type { CliDistribution } from "../src/distribution.js";
-import type { CliManagedProgramReport, CliRuntimeController } from "../src/runtime-port.js";
+import type { CliManagedProgramProgress, CliManagedProgramReport, CliRuntimeController } from "../src/runtime-port.js";
const io = { write: () => {} };
@@ -87,7 +88,7 @@ test("scoped preparation and startup receive the same explicit Endpoint set", as
test("program discovery preserves readiness and failed shutdown names the service still running", async () => {
const reports: CliManagedProgramReport[] = [
...Array.from({ length: 25 }, (_, index) => ({ id: `ready-${index}`, endpoint: "chosen", state: { state: "ready" as const } })),
- { id: "needs-help", endpoint: "other", state: { state: "down", detail: "cannot connect" } },
+ { id: "needs-help", endpoint: "other", action: "nothing-to-stop", state: { state: "down", detail: "cannot connect" } },
];
let output = "";
await runCli(["programs", "status", "/tmp/profile.json", "--json", "--limit", "2"], {
@@ -129,6 +130,67 @@ test("program status may report down without failing the observation", async ()
}]));
assert.equal(exitCode, undefined);
assert.match(output, /speech-evidence\.local: down/u);
+ assert.match(output, /endpoint speech\.primary/u, "expose the selector accepted by --endpoint");
+});
+
+test("a declined stop stays visible even when the service is not Ready", async () => {
+ const busy: CliManagedProgramReport = {
+ id: "preparing", endpoint: "chosen", action: "unchanged",
+ state: { state: "down", detail: "not serving yet" },
+ detail: "another command owns this Program's preparation or lifecycle change; inspect its logs",
+ installationLogPath: "/tmp/install.log",
+ };
+ for (const json of [false, true]) {
+ let output = "";
+ let exitCode: number | undefined;
+ await runCli(["programs", "down", "/p/profile.json", "--limit", "1", ...(json ? ["--json"] : [])], {
+ write(text) { output += text; }, setExitCode(code) { exitCode = code; },
+ }, distribution([], [busy]));
+ assert.equal(exitCode, 1);
+ if (json) {
+ const value = JSON.parse(output);
+ assert.equal(value.ok, false);
+ assert.equal(value.ready, false);
+ assert.equal(value.programs[0].installationLogPath, busy.installationLogPath);
+ } else {
+ assert.match(output, /stop needs attention/u);
+ assert.match(output, /another command owns/u);
+ assert.doesNotMatch(output, /External programs stopped/u);
+ }
+ }
+ let output = "";
+ await runCli(["programs", "down", "/p/profile.json", "--json"], {
+ write(text) { output += text; },
+ }, distribution([], [{ id: busy.id, endpoint: busy.endpoint, state: busy.state, action: "nothing-to-stop" }]));
+ const stopped = JSON.parse(output);
+ assert.equal(stopped.ok, true);
+ assert.equal(stopped.ready, false, "a successful stop is not service readiness");
+});
+
+test("Runtime headlines preserve a running Worker when Programs are down or stop fails", async () => {
+ const selected = {
+ bootstrapPackages: [],
+ openRuntimeHost: async () => ({
+ controller: async () => ({
+ worker: {
+ status: async () => ({ state: "running" }),
+ down: async () => ({ state: "running" }),
+ },
+ programs: { report: async () => ({ programs: [{ id: "loading", endpoint: "chosen", state: { state: "down", detail: "loading" }, pid: 12 }] }) },
+ }),
+ openControl: async () => ({ activity: async () => ({ builds: [], capacity: [] }), close: async () => {} }),
+ }),
+ } as unknown as CliDistribution;
+ for (const action of ["status", "down"]) {
+ let output = "";
+ let exitCode: number | undefined;
+ await runCli(["runtime", action, "/p/profile.json"], {
+ write(text) { output += text; }, setExitCode(code) { exitCode = code; },
+ }, selected);
+ assert.doesNotMatch(output, /Runtime Worker stopped|Runtime Worker is down/u);
+ assert.match(output, action === "status" ? /Programs not ready/u : /Worker is still running/u);
+ assert.equal(exitCode, action === "status" ? undefined : 1);
+ }
});
test("program startup reports actions, not no-op checks", async () => {
@@ -172,6 +234,8 @@ test("programs and runtime startup retain failure evidence in human and JSON out
detail: "service is still loading",
pid: 321,
logPath: "/tmp/local-service/program.log",
+ installationLogPath: "/tmp/local-service/install.log",
+ errorLogPath: "/tmp/local-service/program.err.log",
};
for (const command of ["programs", "runtime"]) {
for (const json of [false, true]) {
@@ -190,17 +254,47 @@ test("programs and runtime startup retain failure evidence in human and JSON out
assert.equal(item.endpoint, report.endpoint);
assert.equal(item.detail, report.detail);
assert.equal(item.logPath, report.logPath);
+ assert.equal(item.installationLogPath, report.installationLogPath);
+ assert.equal(item.errorLogPath, report.errorLogPath);
assert.equal(item.pid, report.pid);
} else {
assert.match(output, /health endpoint is not answering/u);
assert.match(output, /service is still loading/u);
assert.match(output, /PID 321/u);
assert.match(output, /\/tmp\/local-service\/program\.log/u);
+ assert.match(output, /\/tmp\/local-service\/install\.log/u);
+ assert.match(output, /\/tmp\/local-service\/program\.err\.log/u);
}
}
}
});
+test("JSON startup keeps live preparation evidence on stderr and one result on stdout", async () => {
+ let output = "";
+ let progress = "";
+ const selected = {
+ bootstrapPackages: [],
+ openRuntimeHost: async () => ({
+ prepare: async () => [],
+ controller: async () => ({
+ programs: {
+ async up(options: { onProgress?: (event: CliManagedProgramProgress) => void }) {
+ options.onProgress?.({ id: "example", phase: "installing", logPath: "/tmp/install.log", detail: "Prepare sentence data" });
+ assert.match(progress, /Prepare sentence data.*\/tmp\/install\.log/u);
+ assert.equal(output, "", "no partial JSON or progress text reaches stdout");
+ return { dataRoot: "/tmp", programs: [{ id: "example", endpoint: "example", state: { state: "ready" } }] };
+ },
+ },
+ }),
+ }),
+ } as unknown as CliDistribution;
+ await runCli(["programs", "up", "/project/profile.json", "--json"], {
+ write(text) { output += text; },
+ writeProgress(text) { progress += text; },
+ }, selected);
+ assert.equal(JSON.parse(output).readyCount, 1);
+});
+
test("runtime up validates the Runtime before it starts Programs", async () => {
const calls: string[] = [];
const base = distribution(calls);
@@ -248,3 +342,13 @@ test("runtime status keeps scheduling phases out of the default view", async ()
assert.match(output, /Active Builds\s+0/u);
assert.doesNotMatch(output, /\bStarting\b|\bWaiting\b|\bDecided\b|Running turn|Capacity in use/u);
});
+
+test("Worker stop suggests Program control in the same project and Profile", async () => {
+ const projectRoot = resolve("/tmp");
+ const runtimeProfile = resolve("/tmp/a selected profile.json");
+ let output = "";
+ await runCli(["runtime", "down", "--workspace", projectRoot, "--runtime", runtimeProfile], {
+ write(text) { output += text; },
+ }, distribution([]));
+ assert.ok(output.includes(commandHint(["programs", "down"], { projectRoot, runtimeProfile })));
+});
diff --git a/packages/provider-whisperx-local/README.md b/packages/provider-whisperx-local/README.md
index d003e1ca..a1f98fba 100644
--- a/packages/provider-whisperx-local/README.md
+++ b/packages/provider-whisperx-local/README.md
@@ -85,8 +85,14 @@ Program needs restarting, and account for active work using it.
Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
`program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
+`programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
+exist, even before installation finishes. Preparation notices name the Python environment and NLTK
+commands separately. The service logs the start and completion of ASR loading, transcription,
+language-alignment model loading and alignment, with elapsed times. Loading may include a download;
+transfer details come from the underlying client, not an estimated percentage from the Provider.
The service health endpoint becomes available after ASR loading. A startup readiness wait expiring
-can leave that process still loading; check its reported PID and logs before starting another process.
+can leave that process still loading. Its PID is recorded when spawned; repeated `up` observes it,
+and `programs down` can stop it during loading. PID liveness and service readiness are separate facts.
Python installation, Python packages, NLTK sentence data, ASR weights and language-alignment weights
are separate downloads. `UV_PYTHON_INSTALL_MIRROR` configures a Python distribution mirror;
diff --git a/packages/provider-whisperx-local/src/program.ts b/packages/provider-whisperx-local/src/program.ts
index 0f0c5f3d..9feaf514 100644
--- a/packages/provider-whisperx-local/src/program.ts
+++ b/packages/provider-whisperx-local/src/program.ts
@@ -126,10 +126,12 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
probe: installationProbe,
prepareBeforeStart: true,
commands: [{
+ label: "Prepare the locked Python environment",
command: "uv",
args: ["sync", "--project", localWhisperXManagedProject, "--frozen", "--no-editable"],
env: { UV_PROJECT_ENVIRONMENT: environment },
}, {
+ label: "Prepare NLTK sentence data",
command: pythonEnvironmentCommand(environment, "hypit-whisperx-prepare"),
args: ["--nltk-data", nltkData],
env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.ts
index d0740cf5..f8644a5a 100644
--- a/packages/runtime-host-node/src/index.ts
+++ b/packages/runtime-host-node/src/index.ts
@@ -203,6 +203,8 @@ export type RuntimeHostProviderQuery = {
export type ManagedProgramProgress = {
readonly id: string;
readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
+ readonly logPath?: string;
+ readonly detail?: string;
};
export type ManagedProgramReport = {
@@ -215,6 +217,8 @@ export type ManagedProgramReport = {
| { readonly state: "mismatch"; readonly detail: string };
readonly detail?: string;
readonly logPath?: string;
+ readonly installationLogPath?: string;
+ readonly errorLogPath?: string;
readonly pid?: number;
};
diff --git a/packages/runtime-kit/README.md b/packages/runtime-kit/README.md
index a337c966..a4d05e1b 100644
--- a/packages/runtime-kit/README.md
+++ b/packages/runtime-kit/README.md
@@ -45,3 +45,6 @@ video package by name.
before a cold start, even when the installation probe already passes. The declared commands use the
Provider's ordinary package manager. A healthy running Program is reused before this preparation is
considered; Runtime does not inspect source files or infer implementation versions.
+`ManagedProgramCommand.label` optionally names a command's purpose for progress and log headings.
+It is display text supplied by the Program owner, not a phase to persist or interpret. Runtime
+reports generic process/probe facts; the service itself owns domain-specific progress in its logs.
diff --git a/packages/runtime-kit/src/index.ts b/packages/runtime-kit/src/index.ts
index 3f02f614..ce19cb19 100644
--- a/packages/runtime-kit/src/index.ts
+++ b/packages/runtime-kit/src/index.ts
@@ -33,6 +33,8 @@ export type RuntimeDoctorDiagnostic = {
};
export type ManagedProgramCommand = {
+ /** Optional human-readable purpose, supplied by the program owner. Not a lifecycle state. */
+ readonly label?: string;
readonly command: string;
readonly args: readonly string[];
readonly cwd?: string;
diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.md
index b12174bb..cb0d5202 100644
--- a/packages/runtime-local/README.md
+++ b/packages/runtime-local/README.md
@@ -6,12 +6,29 @@ worklist. Project-owned Build Results hold finished public Outputs.
Managed Program preparation writes subprocess stdout and stderr directly to that Program's
`install.log`, so dependency-download output is readable before installation finishes. Installation
and startup progress expose `logPath`; failed installation reports retain it with a short error.
+Each preparation command adds its owner-supplied purpose (or executable name) and start/end time to
+the log. Command arguments and environment values are not copied into these headings.
The files belong to the Program's configured state directory. Service output uses `program.log`
and, on Windows, a separate `program.err.log` for stderr. Keeping installation output separate
preserves it when Windows opens fresh service logs at startup.
The CLI retains Program failure reasons, PIDs and log paths in `programs` and `runtime up` reports.
Human output stays compact for successful preparation; `programs status --verbose` also shows
ready helpers, and JSON retains the reported details independently of verbosity.
+With `--json`, preparation notices use stderr; stdout remains the final JSON result. Status reports
+existing `installationLogPath`, `logPath` and Windows `errorLogPath` separately. These paths identify
+historical files, not currently running phases.
+
+Each Program Home has OS-owned exclusion for preparation, spawning and stopping. Concurrent lifecycle
+commands for that home return the observed facts and a busy explanation; other Programs remain
+independent. The empty `lifecycle.lock` file is only a lock address. The OS releases ownership on
+command exit; no phase record, expiry, stale-lock deletion or recovery procedure is attached to it.
+This uses the Distribution's existing native binding dependency for POSIX `flock` and Windows
+exclusive file handles, rather than coordinating all services in a central table.
+
+Startup publishes `process.pid` before waiting for the probe, then releases exclusion. Repeated `up`
+observes that live process; `down` can stop it while it is still loading. A readiness observation
+timeout leaves the process alone and reports that it remains alive. This is Program lifecycle
+coordination, separate from Build execution; it does not retry or recover Builds.
A Runtime Profile selects only the environmental parts that genuinely vary:
diff --git a/packages/runtime-local/package.json b/packages/runtime-local/package.json
index edadfe96..2ed11984 100644
--- a/packages/runtime-local/package.json
+++ b/packages/runtime-local/package.json
@@ -24,7 +24,8 @@
"@hypit/runtime-kit": "workspace:*",
"@hypit/runtime-host-node": "workspace:*",
"@hypit/store-sqlite": "workspace:*",
- "@hypit/validation": "workspace:*"
+ "@hypit/validation": "workspace:*",
+ "koffi": "3.2.1"
},
"devDependencies": {
"@hypit/build-result": "workspace:*",
diff --git a/packages/runtime-local/src/program-lock.ts b/packages/runtime-local/src/program-lock.ts
new file mode 100644
index 00000000..238a8e69
--- /dev/null
+++ b/packages/runtime-local/src/program-lock.ts
@@ -0,0 +1,40 @@
+import { closeSync, openSync } from "node:fs";
+import { constants } from "node:os";
+import { join, toNamespacedPath } from "node:path";
+import koffi from "koffi";
+
+// The OS owns exclusion and releases it when the calling process exits. The empty file
+// is only an address: never unlink it, infer a phase from it, or expire another owner's lock.
+const library = koffi.load(process.platform === "win32" ? "kernel32.dll" : null);
+const flock = process.platform === "win32" ? undefined : library.func("int flock(int fd, int operation)");
+const createFile = process.platform === "win32"
+ ? library.func("intptr_t __stdcall CreateFileW(const char16_t *path, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t attributes, intptr_t templateFile)") : undefined;
+const lastError = process.platform === "win32" ? library.func("uint32_t __stdcall GetLastError()") : undefined;
+const closeHandle = process.platform === "win32" ? library.func("int __stdcall CloseHandle(intptr_t file)") : undefined;
+
+/** Try once. An occupied program returns immediately; unrelated programs remain independent. */
+export function tryProgramLock(directory: string): (() => void) | undefined {
+ const path = join(directory, "lifecycle.lock");
+ let close: () => void;
+ if (createFile !== undefined) {
+ // OPEN_ALWAYS, no sharing: exclusive while the handle is open, including across CLI processes.
+ const handle = createFile(toNamespacedPath(path), 0xc0000000, 0, null, 4, 0x80, 0);
+ if (handle === -1 || handle === -1n) {
+ const code = lastError!();
+ if (code === 32 || code === 33) return undefined;
+ throw new Error(`Cannot acquire Program ownership at ${path}: Windows error ${code}`);
+ }
+ close = () => { closeHandle!(handle); };
+ } else {
+ const fd = openSync(path, "a");
+ if (flock!(fd, 2 | 4) !== 0) { // LOCK_EX | LOCK_NB
+ const code = koffi.errno();
+ closeSync(fd);
+ if (code === constants.errno.EAGAIN || code === constants.errno.EWOULDBLOCK) return undefined;
+ throw new Error(`Cannot acquire Program ownership at ${path}: errno ${code}`);
+ }
+ close = () => { closeSync(fd); };
+ }
+ let released = false;
+ return () => { if (!released) { released = true; close(); } };
+}
diff --git a/packages/runtime-local/src/programs.ts b/packages/runtime-local/src/programs.ts
index 2ebf67f6..f10d6823 100644
--- a/packages/runtime-local/src/programs.ts
+++ b/packages/runtime-local/src/programs.ts
@@ -1,6 +1,6 @@
import { spawn } from "node:child_process";
import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
import { setTimeout as sleep } from "node:timers/promises";
import type { CapabilityRef } from "@hypit/protocol";
@@ -30,6 +30,8 @@ export type ManagedProgramReport = {
/** Why the action fell short. Never a copy of what `state` already says. */
readonly detail?: string;
readonly logPath?: string;
+ readonly installationLogPath?: string;
+ readonly errorLogPath?: string;
readonly pid?: number;
};
@@ -37,6 +39,7 @@ export type ManagedProgramProgress = {
readonly id: string;
readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
readonly logPath?: string;
+ readonly detail?: string;
};
export type ManagedProgramOptions = LoadRuntimeConfigOptions & {
@@ -99,9 +102,40 @@ async function readPid(root: string, program: ManagedProgram): Promise<number |
}
}
+async function existingLogs(root: string, program: ManagedProgram) {
+ const home = directory(root, program);
+ const paths = {
+ logPath: join(home, "program.log"),
+ installationLogPath: join(home, "install.log"),
+ ...(process.platform === "win32" ? { errorLogPath: processErrorLogPath(join(home, "program.log")) } : {}),
+ };
+ const found: { logPath?: string; installationLogPath?: string; errorLogPath?: string } = {};
+ for (const [key, path] of Object.entries(paths)) {
+ try { await stat(path); found[key as keyof typeof found] = path; }
+ catch (error) { if (!nodeError(error, "ENOENT")) throw error; }
+ }
+ return found;
+}
+
+async function programReport(root: string, program: ManagedProgram, endpoint: string): Promise<ManagedProgramReport> {
+ const state = await program.probe();
+ const pid = await readPid(root, program);
+ return { id: program.id, endpoint, state, ...await existingLogs(root, program),
+ ...(pid !== undefined && processAlive(pid) ? { pid } : {}),
+ };
+}
+
+function commandLabel(command: ManagedProgramCommand): string {
+ // Labels describe purpose. Arguments and environment values can contain credentials.
+ return (command.label ?? basename(command.command)).replace(/\s+/gu, " ").trim();
+}
+
async function run(root: string, command: ManagedProgramCommand, logPath: string): Promise<{ ok: boolean; detail: string }> {
const log = await open(logPath, "a+");
try {
+ const started = Date.now();
+ const label = commandLabel(command);
+ await log.appendFile(`\n${new Date().toISOString()} Starting: ${label}\n`);
const offset = (await log.stat()).size;
const exit = await new Promise<{ code: number | null; error?: string }>((resolve) => {
const child = spawn(command.command, [...command.args], {
@@ -114,25 +148,24 @@ async function run(root: string, command: ManagedProgramCommand, logPath: string
child.on("error", (error) => resolve({ code: null, error: error.message }));
child.on("close", (code) => resolve({ code }));
});
- if (exit.code === 0) return { ok: true, detail: "" };
+ if (exit.code === 0) {
+ await log.appendFile(`${new Date().toISOString()} Finished: ${label} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
+ return { ok: true, detail: "" };
+ }
const end = (await log.stat()).size;
const start = Math.max(offset, end - 8192);
const tail = Buffer.alloc(end - start);
const { bytesRead } = await log.read(tail, 0, tail.length, start);
const line = tail.subarray(0, bytesRead).toString().trim().split(/\r?\n/u).at(-1);
+ await log.appendFile(`${new Date().toISOString()} Failed: ${label} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
return { ok: false, detail: exit.error ?? (line || `exited ${exit.code}`) };
} finally {
await log.close();
}
}
-/**
- * Poll until the program answers as itself. `down` is expected while it loads
- * weights; `mismatch` is not, and stops the wait — a program that is answering
- * with another identity will not become the right one by waiting.
- */
/** POSIX: its own session, and stdio already pointed at the log. */
-async function startDetached(start: ManagedProgramCommand, root: string, logFd: number): Promise<number | undefined> {
+async function startDetached(start: ManagedProgramCommand, root: string, logFd: number): Promise<{ pid?: number; detail?: string }> {
const child = spawn(start.command, [...start.args], {
cwd: start.cwd ?? root,
env: { ...process.env, ...start.env },
@@ -141,8 +174,13 @@ async function startDetached(start: ManagedProgramCommand, root: string, logFd:
windowsHide: true,
stdio: ["ignore", logFd, logFd],
});
- child.unref();
- return child.pid;
+ return await new Promise((resolve) => {
+ child.once("error", (error) => resolve({ detail: error.message }));
+ child.once("spawn", () => {
+ child.unref();
+ resolve(child.pid === undefined ? { detail: "spawn reported no process id" } : { pid: child.pid });
+ });
+ });
}
/** A PowerShell single-quoted literal, which escapes by doubling the quote and nothing else. */
@@ -243,11 +281,12 @@ async function waitForReady(program: ManagedProgram, pid: number, maxWaitMs: num
return state;
}
-async function bringUp(
+async function bringUpOwned(
root: string,
program: ManagedProgram,
endpoint: string,
maxWaitMs: number,
+ release: () => void,
onProgress?: (event: ManagedProgramProgress) => void,
): Promise<ManagedProgramReport> {
const base = { id: program.id, endpoint };
@@ -265,13 +304,28 @@ async function bringUp(
let installed = false;
const logPath = join(directory(root, program), "program.log");
const installLogPath = join(directory(root, program), "install.log");
+ const existingPid = await readPid(root, program);
+ if (existingPid !== undefined && processAlive(existingPid)) {
+ release();
+ onProgress?.({ id: program.id, phase: "waiting", logPath,
+ detail: `observing existing process ${existingPid}` });
+ const state = await waitForReady(program, existingPid, maxWaitMs);
+ const alive = processAlive(existingPid);
+ return { ...base, action: state.state === "ready" ? "already-running" : "unchanged", state, logPath,
+ ...(alive ? { pid: existingPid } : {}),
+ ...(state.state === "ready" ? {} : { detail: alive
+ ? `process ${existingPid} is still running; readiness has not been established; see ${logPath}`
+ : `process exited; see ${logPath}` }),
+ };
+ }
+ if (existingPid !== undefined) await rm(join(directory(root, program), "process.pid"), { force: true });
if (program.installation !== undefined) {
const installation = await program.installation.probe();
if (installation.state !== "ready" || program.installation.prepareBeforeStart === true) {
await mkdir(directory(root, program), { recursive: true });
await rotateLog(installLogPath);
- onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath });
for (const command of program.installation.commands) {
+ onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath, detail: commandLabel(command) });
const result = await run(root, command, installLogPath);
if (!result.ok) {
return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `${command.command} failed: ${result.detail}` };
@@ -317,7 +371,7 @@ async function bringUp(
// creates a new console and hides it, which is the combination neither spawn option reaches.
const started = process.platform === "win32"
? await startWithOwnConsole(program.start, root, logPath)
- : { pid: await startDetached(program.start, root, log.fd) };
+ : await startDetached(program.start, root, log.fd);
if (started.pid === undefined) {
const refusal = "detail" in started && started.detail !== undefined ? `: ${started.detail}` : "";
return {
@@ -329,11 +383,27 @@ async function bringUp(
};
}
const child = { pid: started.pid };
+ // Publish ownership before observing readiness. Another up can now reuse this process,
+ // and down can stop it even if loading is slow. The observation owns no startup lock.
+ const pidPath = join(directory(root, program), "process.pid");
+ // Under the startup lock the old record is already absent. Rename publishes a complete
+ // record to read-only observers without replacing a file they might have open on Windows.
+ await writeFile(`${pidPath}.tmp`, `${child.pid}\n`);
+ await rename(`${pidPath}.tmp`, pidPath);
+ release();
onProgress?.({ id: program.id, phase: "waiting" });
const state = await waitForReady(program, child.pid, maxWaitMs);
if (state.state === "ready") onProgress?.({ id: program.id, phase: "ready" });
const alive = processAlive(child.pid);
- if (alive) await writeFile(join(directory(root, program), "process.pid"), `${child.pid}\n`);
+ if (!alive) {
+ const { tryProgramLock } = await import("./program-lock.js");
+ const releaseCleanup = tryProgramLock(directory(root, program));
+ if (releaseCleanup !== undefined) {
+ try {
+ if (await readPid(root, program) === child.pid) await rm(pidPath, { force: true });
+ } finally { releaseCleanup(); }
+ }
+ }
return {
...base,
action: state.state === "ready" ? (alive ? "started" : "already-running") : "unchanged",
@@ -341,7 +411,7 @@ async function bringUp(
...(alive ? { pid: child.pid } : {}),
logPath,
...(state.state === "ready" ? {} : {
- detail: alive ? `see ${logPath}` : `process exited; see ${logPath}`,
+ detail: alive ? `process ${child.pid} is still running; readiness has not been established; see ${logPath}` : `process exited; see ${logPath}`,
}),
};
} finally {
@@ -349,6 +419,22 @@ async function bringUp(
}
}
+async function bringUp(
+ root: string, program: ManagedProgram, endpoint: string, maxWaitMs: number,
+ onProgress?: (event: ManagedProgramProgress) => void,
+): Promise<ManagedProgramReport> {
+ const home = directory(root, program);
+ await mkdir(home, { recursive: true });
+ const { tryProgramLock } = await import("./program-lock.js");
+ const release = tryProgramLock(home);
+ if (release === undefined) return { ...await programReport(root, program, endpoint), action: "unchanged",
+ detail: "another command owns this Program's preparation or lifecycle change; inspect its logs", };
+ try {
+ const report = await bringUpOwned(root, program, endpoint, maxWaitMs, release, onProgress);
+ return { ...await existingLogs(root, program), ...report };
+ } finally { release(); }
+}
+
/** Install when needed and start every external program the Runtime Profile implies. */
export async function bringManagedProgramsUp(
path: string,
@@ -371,60 +457,68 @@ export async function takeManagedProgramsDown(
const { dataRoot, programs } = await declaredManagedPrograms(path, options);
const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
const base = { id: program.id, endpoint: instance };
- const pid = await readPid(dataRoot, program);
- if (pid === undefined || !processAlive(pid)) {
- if (pid !== undefined) await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
- const state = await program.probe();
- return state.state === "down"
- ? { ...base, action: "nothing-to-stop", state }
- // Someone else's process, or one started by hand. Killing it is not this
- // command's business; saying so is.
- : { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
- }
- const term = await stopProcessTree(pid);
- if (term === "denied") {
- return {
- ...base,
- action: "unchanged",
- state: await program.probe(),
- pid,
- detail: `process ${pid} is running but this environment cannot stop it`,
- };
- }
- if (term === "gone") {
- await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
- const state = await program.probe();
- return state.state === "down"
- ? { ...base, action: "nothing-to-stop", state }
- : { ...base, action: "not-ours", state, detail: `${program.id} is now served by another process` };
- }
- const deadline = Date.now() + 15_000;
- while (processAlive(pid) && Date.now() < deadline) await sleep(200);
- if (processAlive(pid)) {
- if (await stopProcessTree(pid, true) === "denied") {
+ const home = directory(dataRoot, program);
+ await mkdir(home, { recursive: true });
+ const { tryProgramLock } = await import("./program-lock.js");
+ const release = tryProgramLock(home);
+ if (release === undefined) return { ...await programReport(dataRoot, program, instance), action: "unchanged",
+ detail: "another command owns this Program's preparation or lifecycle change; inspect its logs", };
+ try {
+ const pid = await readPid(dataRoot, program);
+ if (pid === undefined || !processAlive(pid)) {
+ if (pid !== undefined) await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+ const state = await program.probe();
+ return state.state === "down"
+ ? { ...base, action: "nothing-to-stop", state }
+ // Someone else's process, or one started by hand. Killing it is not this
+ // command's business; saying so is.
+ : { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
+ }
+ const term = await stopProcessTree(pid);
+ if (term === "denied") {
return {
...base,
action: "unchanged",
state: await program.probe(),
pid,
- detail: `process ${pid} ignored graceful termination and cannot be force-stopped`,
+ detail: `process ${pid} is running but this environment cannot stop it`,
};
}
- const forceDeadline = Date.now() + 2_000;
- while (processAlive(pid) && Date.now() < forceDeadline) await sleep(50);
+ if (term === "gone") {
+ await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+ const state = await program.probe();
+ return state.state === "down"
+ ? { ...base, action: "nothing-to-stop", state }
+ : { ...base, action: "not-ours", state, detail: `${program.id} is now served by another process` };
+ }
+ const deadline = Date.now() + 15_000;
+ while (processAlive(pid) && Date.now() < deadline) await sleep(200);
if (processAlive(pid)) {
- return {
- ...base,
- action: "unchanged",
- state: await program.probe(),
- pid,
- detail: `process ${pid} remained alive after forced termination`,
- };
+ if (await stopProcessTree(pid, true) === "denied") {
+ return {
+ ...base,
+ action: "unchanged",
+ state: await program.probe(),
+ pid,
+ detail: `process ${pid} ignored graceful termination and cannot be force-stopped`,
+ };
+ }
+ const forceDeadline = Date.now() + 2_000;
+ while (processAlive(pid) && Date.now() < forceDeadline) await sleep(50);
+ if (processAlive(pid)) {
+ return {
+ ...base,
+ action: "unchanged",
+ state: await program.probe(),
+ pid,
+ detail: `process ${pid} remained alive after forced termination`,
+ };
+ }
}
- }
- await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
- return { ...base, action: "stopped", state: await program.probe(), pid };
- }));
+ await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+ return { ...base, action: "stopped", state: await program.probe(), pid };
+ } finally { release(); }
+ }));
return { dataRoot, programs: reports };
}
@@ -434,24 +528,7 @@ export async function reportManagedPrograms(
options: ManagedProgramOptions = {},
): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }> {
const { dataRoot, programs } = await declaredManagedPrograms(path, options);
- const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
- const state = await program.probe();
- const pid = await readPid(dataRoot, program);
- const logPath = join(directory(dataRoot, program), "program.log");
- let hasLog = false;
- try {
- await stat(logPath);
- hasLog = true;
- } catch (error) {
- if (!nodeError(error, "ENOENT")) throw error;
- }
- return {
- id: program.id,
- endpoint: instance,
- state,
- ...(pid !== undefined && processAlive(pid) ? { pid } : {}),
- ...(hasLog ? { logPath } : {}),
- };
- }));
+ const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }) =>
+ await programReport(dataRoot, program, instance)));
return { dataRoot, programs: reports };
}
diff --git a/packages/runtime-local/test/program-lock.test.ts b/packages/runtime-local/test/program-lock.test.ts
new file mode 100644
index 00000000..d449f71a
--- /dev/null
+++ b/packages/runtime-local/test/program-lock.test.ts
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { tryProgramLock } from "../src/program-lock.js";
+
+test("Program ownership excludes another process and the OS releases it on owner exit", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-program-lock-"));
+ const other = join(root, "other");
+ await mkdir(other);
+ const moduleUrl = new URL("../src/program-lock.ts", import.meta.url).href;
+ const child = spawn(process.execPath, ["--import", "tsx", "--input-type=module", "-e", `
+ const { tryProgramLock } = await import(${JSON.stringify(moduleUrl)});
+ if (!tryProgramLock(process.argv[1])) throw new Error('unexpected owner');
+ process.stdout.write('owned');
+ setInterval(() => {}, 1000);
+ `, root], { stdio: ["ignore", "pipe", "inherit"] });
+ const exited = once(child, "exit");
+ try {
+ await once(child.stdout, "data");
+ assert.equal(tryProgramLock(root), undefined);
+ const unrelated = tryProgramLock(other);
+ assert.ok(unrelated, "unrelated Programs do not share a global lock");
+ unrelated();
+ child.kill("SIGKILL");
+ await exited;
+ const released = tryProgramLock(root);
+ assert.ok(released, "an abandoned lock file needs no timeout, stale-owner repair or deletion");
+ released();
+ } finally {
+ if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+ await exited;
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/runtime-local/test/programs.test.ts b/packages/runtime-local/test/programs.test.ts
index aa326981..81aef711 100644
--- a/packages/runtime-local/test/programs.test.ts
+++ b/packages/runtime-local/test/programs.test.ts
@@ -182,6 +182,7 @@ test("up preserves installation logs through service startup and down stops it",
const status = await reportManagedPrograms(path, options);
assert.equal(status.programs[0]!.pid, pid);
assert.equal(status.programs[0]!.logPath, join(root, "programs", "example", "program.log"));
+ assert.equal(status.programs[0]!.installationLogPath, join(root, "programs", "example", "install.log"));
await rm(marker, { force: true });
const stopped = await takeManagedProgramsDown(path, options);
@@ -316,17 +317,18 @@ test("a failing install stops before starting anything, and says which command f
assert.match(await readFile(result.programs[0]!.logPath!, "utf8"), /no such project/u);
});
-test("installation output is readable while preparation is still running", async () => {
+test("ongoing preparation exposes its log and excludes another preparation", async () => {
const { root, path, options } = await project((root) => ({
id: "downloader",
installation: {
commands: [nodeProgram(`
const fs = require('node:fs');
+ fs.appendFileSync(process.argv[2], 'once\\n');
process.stdout.write('fetching dependency\\n');
const timer = setInterval(() => {
if (fs.existsSync(process.argv[1])) { clearInterval(timer); process.stderr.write('download complete\\n'); }
}, 10);
- `, join(root, "release"))],
+ `, join(root, "release"), join(root, "preparations"))],
probe: async () => ({ state: "down", detail: "not installed" }),
},
probe: async () => ({ state: "down", detail: "not running" }),
@@ -345,6 +347,16 @@ test("installation output is readable while preparation is still running", async
}
assert.match(output, /fetching dependency/u);
assert.equal(done, false);
+ const status = (await reportManagedPrograms(path, options)).programs[0]!;
+ assert.equal(status.installationLogPath, logPath);
+ assert.equal(status.logPath, undefined, "preparation output is not a running service log");
+ const again = (await bringManagedProgramsUp(path, options)).programs[0]!;
+ assert.equal(again.action, "unchanged");
+ assert.match(again.detail!, /another command owns/u);
+ assert.equal(again.installationLogPath, logPath);
+ const down = (await takeManagedProgramsDown(path, options)).programs[0]!;
+ assert.match(down.detail!, /another command owns/u);
+ assert.equal(await readFile(join(root, "preparations"), "utf8"), "once\n");
} finally {
await writeFile(join(root, "release"), "continue");
await pending;
@@ -353,6 +365,43 @@ test("installation output is readable while preparation is still running", async
await rm(root, { recursive: true, force: true });
});
+test("a loading process is visible and reused after a readiness wait, and down can stop it", async () => {
+ const { root, path, options } = await project((root) => ({
+ id: "loading",
+ start: nodeProgram(`require('node:fs').appendFileSync(process.argv[1], 'once\\n'); ${STAY_ALIVE}`, join(root, "starts")),
+ probe: async () => ({ state: "down", detail: "model loading" }),
+ }));
+ try {
+ const first = (await bringManagedProgramsUp(path, { ...options, maxWaitMs: 0 })).programs[0]!;
+ assert.equal(first.action, "unchanged");
+ assert.ok(first.pid, "ownership is published before readiness");
+ const status = (await reportManagedPrograms(path, options)).programs[0]!;
+ assert.equal(status.pid, first.pid);
+ assert.equal(status.state.state, "down", "a live PID is not readiness");
+
+ let observed!: () => void;
+ const waiting = new Promise<void>((resolve) => { observed = resolve; });
+ const pending = bringManagedProgramsUp(path, { ...options, maxWaitMs: 20_000,
+ onProgress(event) { if (event.phase === "waiting") observed(); },
+ });
+ await waiting;
+ // Give the synthetic child an opportunity to write its startup evidence, not to become Ready.
+ for (let attempt = 0; attempt < 100; attempt++) {
+ if (await readFile(join(root, "starts"), "utf8").catch(() => "") === "once\n") break;
+ await sleep(20);
+ }
+ assert.equal(await readFile(join(root, "starts"), "utf8"), "once\n");
+ const down = (await takeManagedProgramsDown(path, options)).programs[0]!;
+ assert.equal(down.action, "stopped", "observing readiness does not prevent stopping the service");
+ const second = (await pending).programs[0]!;
+ assert.match(second.detail!, /process exited/u);
+ assert.equal(second.pid, undefined);
+ } finally {
+ await takeManagedProgramsDown(path, options);
+ await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+ }
+});
+
test("up stops waiting when a started program exits", async () => {
const { root, path, options } = await project(() => ({
id: "example",
diff --git a/packages/video-cli/README.md b/packages/video-cli/README.md
index f58fea22..4853ee87 100644
--- a/packages/video-cli/README.md
+++ b/packages/video-cli/README.md
@@ -11,15 +11,38 @@ reusable Source directly, for example
`<import as="ugc" source="@hypit/gpt-image-kits/phone-ugc-v1"/>`; resolving that Source does not
activate package code.
-From any project:
+`hypit version` reports the Distribution version, physical root and launcher independently of a
+project or Runtime. `hypit version --check` also reads the package's `latest` tag at
+`https://registry.npmjs.org/`; `--registry <url>` explicitly selects another registry. `--json`
+returns `hypit.cli-version@1`. A failed check retains local facts, leaves the remote version unknown
+and exits nonzero. A different version is not automatically newer: the launcher may be a newer
+checkout or the mirror may lag. The command links release notes and never installs or updates.
+Skill installers own their separate installed copies; this command does not scan Agent directories.
+`hypit --version` remains a local version-only query.
+
+Commands below serve independent authoring decisions. Start with the current project's material;
+local inspection and estimation need no generation account:
```bash
cd path/to/project
-hypit runtime init
-hypit auth login hypihub.default
-hypit doctor
-hypit runtime up
hypit check main.svml
+hypit measure main.svml --segment hook --language en
+```
+
+When the work needs execution, the project selects a Runtime Profile. `hypit runtime init` creates
+an editable starter; its Endpoint entries describe available routes, not choices made by the user.
+Keep an existing chosen service, or configure the chosen local or hosted Provider and its capability
+bindings. HypiHub is the recommended integrated hosted route in the official Distribution; other
+services use project Provider packages. If the user chooses HypiHub,
+`hypit auth login hypihub.default` connects that account.
+`hypit doctor --endpoint <name>` checks a selected Endpoint;
+`hypit runtime up --endpoint <name>` prepares that Endpoint and starts the Worker. Repeat the flag
+for several chosen Endpoints; omitting it prepares the whole Profile. `hypit programs up --endpoint
+<name>` prepares a local helper independently of the Worker.
+
+With the selected execution environment:
+
+```bash
hypit plan build.svrun
hypit build build.svrun --follow
hypit status <build-id> --watch
@@ -29,7 +52,6 @@ hypit history <source-output-name> [--source ./main.svml]
hypit inspect <build-id> [--output <source-output-name>]
hypit get <build-id> --output final.video --to ./final.mp4
hypit cancel <build-id>
-hypit doctor
```
`transcribe` runs one immediate request through the selected Runtime Profile, with no Build,
@@ -63,6 +85,11 @@ that produced them, so they are declared in the Source and go through `plan` and
voice or learn a passage's real length before authoring the rest, build a Run whose target is that
speech output and reuse it as a Candidate.
+Provider selection is checked before `transcribe` invokes the service. Multiple matching Endpoints
+can remain in the Profile: `bindings` chooses one for the capability. An unsupported request reports
+the selected binding and Provider-owned rejection reasons so the author can adjust the request or
+choose a compatible Endpoint. It does not imply that an account needs payment or login.
+
Two more families are local, stateless and spend nothing. `hypit media` exposes the source at chosen
times and scales, and `hypit vocabulary`
prints what a Source may write:
diff --git a/packages/video-cli/src/cli.ts b/packages/video-cli/src/cli.ts
index c8fee77c..094c94d2 100644
--- a/packages/video-cli/src/cli.ts
+++ b/packages/video-cli/src/cli.ts
@@ -5,6 +5,7 @@ import { creationCommands, isCreationCommand, writeCreationHelp } from "./creati
import { isMediaCommand, mediaCommands, writeMediaHelp } from "./media.js";
import { writeVocabularyHelp } from "./vocabulary.js";
import { writeCaptureHelp } from "./capture.js";
+import { runVersionCli, writeVersionHelp } from "./version.js";
const argv = process.argv.slice(2);
const json = argv.includes("--json");
@@ -67,6 +68,7 @@ async function main(): Promise<void> {
const topic = argv[0] === "help" ? argv[1]
: argv[0] === "--help" ? undefined
: argv.includes("--help") ? argv[0] : undefined;
+ if (topic === "version") { writeVersionHelp(io); return; }
if (isCreationCommand(topic)) {
writeCreationHelp(io, topic);
return;
@@ -86,12 +88,13 @@ async function main(): Promise<void> {
}
writeCliHelp(io, topic);
if (topic === undefined) {
- io.write(`\nCreation tools (one request through the selected Runtime Profile, no Build)\n${
+ io.write(`\nInstallation\n version [--check] [--registry <url>] [--json]\n\nCreation tools (one request through the selected Runtime Profile, no Build)\n${
creationCommands.map((item) => ` ${item}`).join("\n")}\n hypit help <tool> for each\n`
+ `\nStudio\n studio --run <build.svrun>\n hypit studio --help for session options\n\nPreparation (local tools and project files)\n media ${mediaCommands.join(" | ")}\n capture screenshot | run | install-browser\n vocabulary\n hypit help media, hypit help capture, hypit help vocabulary\n`);
}
return;
}
+ if (argv[0] === "version") { await runVersionCli(argv, io); return; }
const { runVideoCli } = await import("./index.js");
await runVideoCli(argv, io);
}
diff --git a/packages/video-cli/src/creation.ts b/packages/video-cli/src/creation.ts
index ab47120b..b68b013e 100644
--- a/packages/video-cli/src/creation.ts
+++ b/packages/video-cli/src/creation.ts
@@ -159,9 +159,14 @@ async function selectedProvider(host: CreationHost, need: Need, profile: string)
}]);
const subject = capabilityName(need.capability);
assert(provider !== undefined && provider.status !== "unresolved",
- `No Endpoint in ${profile} serves ${subject}; hypit plan --runtime ${profile} shows which Endpoint each capability needs`);
+ `No Endpoint in ${profile} serves ${subject}; configure an Endpoint that supports this capability and check its binding in that Profile`);
assert(provider.status !== "ambiguous",
- `Several Endpoints in ${profile} serve ${subject}: ${(provider.endpoints ?? []).join(", ")}; keep exactly one`);
+ `Several Endpoints in ${profile} serve ${subject}: ${(provider.endpoints ?? []).join(", ")}; select one with bindings[${JSON.stringify(subject)}] in that Profile`);
+ assert(provider.status !== "unsupported",
+ `The configured Endpoints in ${profile} do not support this request for ${subject}`
+ + (provider.binding === undefined ? "" : ` (binding: ${provider.binding})`)
+ + `: ${(provider.rejections ?? []).map((item) => `${item.endpoint}: ${item.message}`).join("; ") || "no support reason supplied"}`
+ + "; adjust the request or select a compatible Endpoint in that Profile");
return provider;
}
diff --git a/packages/video-cli/src/index.ts b/packages/video-cli/src/index.ts
index d30884ff..e07ef389 100644
--- a/packages/video-cli/src/index.ts
+++ b/packages/video-cli/src/index.ts
@@ -12,6 +12,7 @@ import { videoCliDistribution } from "./distribution.js";
import { runMediaCli } from "./media.js";
import { runVocabularyCli } from "./vocabulary.js";
import { runCaptureCli } from "./capture.js";
+import { runVersionCli } from "./version.js";
export {
createVideoCompiler,
@@ -35,6 +36,7 @@ export function runVideoCli(
io: CliIo,
packages: readonly LoadedPackage[] = [],
): Promise<void> {
+ if (argv[0] === "version") return runVersionCli(argv, io);
installDistributionPackageResolution(videoCliDistribution.packageRoot === undefined
? []
: [videoCliDistribution.packageRoot]);
diff --git a/packages/video-cli/src/version.ts b/packages/video-cli/src/version.ts
new file mode 100644
index 00000000..fb6accad
--- /dev/null
+++ b/packages/video-cli/src/version.ts
@@ -0,0 +1,90 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { CliIo } from "@hypit/cli";
+import { requestDeadline } from "@hypit/runtime-kit";
+
+type VersionEnvironment = {
+ readonly packageRoot: string;
+ readonly launcher?: string;
+ readonly fetch: typeof globalThis.fetch;
+ readonly timeoutMs?: number;
+};
+
+export function writeVersionHelp(io: CliIo): void {
+ io.write("Usage: hypit version [--check] [--registry <url>] [--json]\n\n"
+ + "Show the executing Distribution and launcher without opening a project or Runtime.\n"
+ + "--check queries npm latest (registry.npmjs.org by default); --registry selects a mirror.\n"
+ + "No packages or Skills are updated. hypit --version remains a local version-only query.\n");
+}
+
+/** Installation discovery belongs to the executable, independent of video execution and Skill installers. */
+export async function runVersionCli(argv: readonly string[], io: CliIo, environment: VersionEnvironment = {
+ packageRoot: resolve(import.meta.dirname, "../../.."),
+ ...(process.env.HYPIT_CLI_LAUNCHER === undefined ? {} : { launcher: process.env.HYPIT_CLI_LAUNCHER }),
+ fetch: globalThis.fetch,
+}): Promise<void> {
+ let check = false;
+ let json = false;
+ let registry = "https://registry.npmjs.org/";
+ let selectedRegistry = false;
+ for (let i = 1; i < argv.length; i++) {
+ const arg = argv[i];
+ if (arg === "--check") check = true;
+ else if (arg === "--json") json = true;
+ else if (arg === "--registry") {
+ selectedRegistry = true;
+ const value = argv[++i];
+ if (value === undefined || value.startsWith("--")) throw new Error("--registry requires a URL");
+ const url = new URL(value);
+ if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+ throw new Error("--registry requires an HTTP(S) registry URL without credentials, query or fragment");
+ }
+ registry = `${url.href.replace(/\/+$/u, "")}/`;
+ } else if (arg === "--help") { writeVersionHelp(io); return; }
+ else if (arg !== "--no-color" && arg !== "--debug") throw new Error(`Unknown version option: ${arg}`);
+ }
+ if (selectedRegistry && !check) throw new Error("--registry selects the source for --check; add --check to query it");
+ const manifest = JSON.parse(await readFile(resolve(environment.packageRoot, "package.json"), "utf8")) as {
+ name: string; version: string; repository?: { url?: string };
+ };
+ const repository = manifest.repository?.url?.replace(/^git\+/u, "").replace(/\.git$/u, "");
+ const releases = repository === undefined ? undefined : `${repository}/releases`;
+ let latest: { registry: string; version?: string; matchesInstalled?: boolean; error?: string } | undefined;
+ if (check) {
+ latest = { registry };
+ const deadline = requestDeadline(environment.timeoutMs ?? 10_000,
+ () => new Error("Registry version query timed out; latest version is unknown"));
+ try {
+ const response = await deadline.wait(environment.fetch(new URL(`${encodeURIComponent(manifest.name)}/latest`, registry), {
+ signal: deadline.signal, headers: { accept: "application/json" },
+ }));
+ if (!response.ok) throw new Error(`Registry returned HTTP ${response.status}; latest version is unknown`);
+ const body = await deadline.wait(response.json()) as { name?: unknown; version?: unknown };
+ if (body.name !== manifest.name || typeof body.version !== "string" || body.version.length === 0) {
+ throw new Error("Registry returned no matching package version; latest version is unknown");
+ }
+ latest.version = body.version;
+ latest.matchesInstalled = body.version === manifest.version;
+ } catch (error) {
+ latest.error = error instanceof Error ? error.message : String(error);
+ io.setExitCode?.(1);
+ } finally { deadline.finish(); }
+ }
+ const report = {
+ format: "hypit.cli-version@1", package: manifest.name, version: manifest.version,
+ distribution: resolve(environment.packageRoot),
+ ...(environment.launcher === undefined ? {} : { launcher: resolve(environment.launcher) }),
+ ...(releases === undefined ? {} : { releases }),
+ ...(latest === undefined ? {} : { latest }),
+ };
+ if (json) { io.write(`${JSON.stringify(report, null, 2)}\n`); return; }
+ io.write(`${manifest.name} ${manifest.version}\nDistribution: ${report.distribution}\n`
+ + (report.launcher === undefined ? "" : `Launcher: ${report.launcher}\n`));
+ if (latest !== undefined) {
+ io.write(`npm latest: ${latest.version === undefined ? "unknown" : `${latest.version} (${latest.matchesInstalled ? "matches installed" : "differs from installed"})`}\nRegistry: ${registry}\n`);
+ if (latest.error !== undefined) io.write(`${latest.error}\n`);
+ if (releases !== undefined) io.write(`Release notes: ${releases}\n`);
+ io.write("Update through this installation's package manager or checkout; preserve the project's chosen version.\n"
+ + "Skill updates belong to its installer and are separate from this executable.\n");
+ }
+}
diff --git a/packages/video-cli/test/creation.test.ts b/packages/video-cli/test/creation.test.ts
index 88d841b9..a65199f6 100644
--- a/packages/video-cli/test/creation.test.ts
+++ b/packages/video-cli/test/creation.test.ts
@@ -148,7 +148,7 @@ test("a Profile that does not serve the capability stops before anything is spen
};
await assert.rejects(
runCreationCli(["transcribe", "speech.wav", "--to", "speech.json", "--language", "en"], capture().io, unserved),
- /No Endpoint in .*hypit\.runtime\.json serves @hypit\/whisperx@1#whisperx-alignment; hypit plan --runtime/u,
+ /No Endpoint in .*hypit\.runtime\.json serves @hypit\/whisperx@1#whisperx-alignment; configure an Endpoint/u,
);
assert.equal(invoked, false);
} finally {
@@ -186,3 +186,39 @@ test("Chinese transcription explicitly sends zh and retains individual character
]);
} finally { await rm(root, { recursive: true, force: true }); }
});
+
+test("transcription explains ambiguous selection and preserves unsupported request reasons before invoking", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-transcribe-selection-"));
+ try {
+ await writeFile(join(root, "speech.wav"), wav(16_000));
+ for (const selection of [
+ { status: "ambiguous" as const, endpoints: ["local.words", "hosted.words"] },
+ { status: "unsupported" as const, binding: "hosted.words",
+ rejections: [{ endpoint: "hosted.words", message: "This deployment does not support zh alignment" }] },
+ ]) {
+ let invoked = false;
+ const env: CreationEnvironment = { cwd: root, openHost: async () => ({
+ profile: join(root, "runtime.json"), host: {
+ providers: async (requests) => requests.map((request) => ({
+ request: request.request, capability: request.capability, ...selection,
+ })),
+ invoke: async () => { invoked = true; throw new Error("must not invoke rejected selection"); },
+ },
+ }) };
+ await assert.rejects(runCreationCli([
+ "transcribe", "speech.wav", "--to", "speech.json", "--language", "zh",
+ ], capture().io, env), (error: Error) => {
+ if (selection.status === "ambiguous") {
+ assert.match(error.message, /local\.words, hosted\.words/u);
+ assert.match(error.message, /bindings\["@hypit\/whisperx@1#whisperx-alignment"\]/u);
+ } else {
+ assert.match(error.message, /binding: hosted\.words/u);
+ assert.match(error.message, /hosted\.words: This deployment does not support zh alignment/u);
+ }
+ assert.doesNotMatch(error.message, /keep exactly one|hypit plan --runtime/u);
+ return true;
+ });
+ assert.equal(invoked, false);
+ }
+ } finally { await rm(root, { recursive: true, force: true }); }
+});
diff --git a/packages/video-cli/test/version.test.ts b/packages/video-cli/test/version.test.ts
new file mode 100644
index 00000000..4962270f
--- /dev/null
+++ b/packages/video-cli/test/version.test.ts
@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { runVersionCli } from "../src/version.js";
+
+test("version reads its Distribution without a project, Runtime or registry request", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-version-"));
+ try {
+ await writeFile(join(root, "package.json"), JSON.stringify({ name: "@hypit/hypit", version: "0.1.8" }));
+ let output = "";
+ await runVersionCli(["version", "--json"], { write: (s) => { output += s; } }, {
+ packageRoot: root, launcher: join(root, "bin", "hypit.mjs"),
+ fetch: async () => { throw new Error("No network expected"); },
+ });
+ assert.deepEqual(JSON.parse(output), {
+ format: "hypit.cli-version@1", package: "@hypit/hypit", version: "0.1.8",
+ distribution: root, launcher: join(root, "bin", "hypit.mjs"),
+ });
+ } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("version check reports the selected registry's evidence, including newer local checkouts", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-version-"));
+ try {
+ await writeFile(join(root, "package.json"), JSON.stringify({ name: "@hypit/hypit", version: "0.1.9" }));
+ let output = "";
+ let calls = 0;
+ await runVersionCli(["version", "--check", "--registry", "https://mirror.example/npm", "--json"], {
+ write: (s) => { output += s; },
+ }, { packageRoot: root, fetch: async (url, init) => {
+ calls++;
+ assert.equal(String(url), "https://mirror.example/npm/%40hypit%2Fhypit/latest");
+ assert.equal(init?.method, undefined);
+ return Response.json({ name: "@hypit/hypit", version: "0.1.8" });
+ } });
+ assert.equal(calls, 1);
+ assert.deepEqual(JSON.parse(output).latest, {
+ registry: "https://mirror.example/npm/", version: "0.1.8", matchesInstalled: false,
+ });
+ } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+for (const mode of ["offline", "body-timeout", "wrong-package"] as const) {
+ test(`version ${mode} retains local facts and marks latest as unknown`, async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-version-"));
+ try {
+ await writeFile(join(root, "package.json"), JSON.stringify({ name: "@hypit/hypit", version: "0.1.8" }));
+ let output = "";
+ let exitCode = 0;
+ await runVersionCli(["version", "--check", "--json"], {
+ write: (s) => { output += s; }, setExitCode: (code) => { exitCode = code; },
+ }, { packageRoot: root, timeoutMs: 20, fetch: async () => {
+ if (mode === "offline") throw new Error("offline");
+ if (mode === "body-timeout") return new Response(new ReadableStream());
+ return Response.json({ name: "different-package", version: "9.0.0" });
+ } });
+ const report = JSON.parse(output);
+ assert.equal(report.version, "0.1.8");
+ assert.equal(report.latest.version, undefined);
+ assert.equal(report.latest.matchesInstalled, undefined);
+ assert.ok(report.latest.error);
+ assert.equal(exitCode, 1);
+ } finally { await rm(root, { recursive: true, force: true }); }
+ });
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6aa40f1e..7879ee08 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2636,6 +2636,9 @@ importers:
'@hypit/validation':
specifier: workspace:*
version: link:../validation
+ koffi:
+ specifier: 3.2.1
+ version: 3.2.1
devDependencies:
'@hypit/build-result':
specifier: workspace:*
diff --git a/services/whisperx/README.md b/services/whisperx/README.md
index f9e7405d..9c270cad 100644
--- a/services/whisperx/README.md
+++ b/services/whisperx/README.md
@@ -19,8 +19,8 @@ semantic projection combines this evidence with one explicit Script Segment late
## Install
For an ordinary installed Distribution, select the local WhisperX Endpoint and run
-`hypit runtime up`. The Runtime creates this environment in the machine Program Home only when it is
-missing, and reuses it across projects and sessions. The commands below are contributor/operator
+`hypit programs up --endpoint <instance>`. The Runtime creates or reconciles the cold environment in
+the machine Program Home and reuses a running service across projects and sessions. The commands below are contributor/operator
diagnostics for a deliberately managed deployment:
WhisperX 3.8.6 supports Python 3.10 through 3.13. The checked-in lock selects Python 3.13:
@@ -32,7 +32,8 @@ uv run --project services/whisperx --frozen hypit-whisperx-prepare
uv run --project services/whisperx --frozen hypit-whisperx-check
```
-The first model start may download ASR and alignment weights. Production should put the relevant
+The first model start may download ASR weights; first use of a language can download its alignment
+model during the request. Production should put the relevant
Hugging Face cache on persistent storage. `hypit-whisperx-prepare` separately installs NLTK's
`punkt_tab` sentence data through NLTK's own downloader. This resource is required by WhisperX
alignment and is prepared explicitly before the warm service starts, never inside an inference request.
@@ -71,6 +72,12 @@ Configuration is deployment state:
The Node Provider must configure the same model, device, compute, batch size, service version and
WhisperX version. A mismatch fails before transcription results are accepted.
+The service logs ASR loading, transcription, language-model loading and word alignment where those
+operations run. Completion entries include elapsed times. A loading entry means the library call
+has begun and may include a weight download; the download client supplies any transfer progress.
+Transcripts and audio content are not included in these service progress entries. `/health` answers
+after ASR loading, so a healthy service may still prepare a language model on its first request.
+
## Package preparation
Local package preparation includes `src/**/*.py` in uv's package cache inputs. Updating service code
diff --git a/services/whisperx/src/hypit_whisperx_service/engine.py b/services/whisperx/src/hypit_whisperx_service/engine.py
index 10fc6f73..779c6fd5 100644
--- a/services/whisperx/src/hypit_whisperx_service/engine.py
+++ b/services/whisperx/src/hypit_whisperx_service/engine.py
@@ -1,15 +1,19 @@
from __future__ import annotations
import importlib.metadata as metadata
+import logging
import math
import os
import threading
+import time
from typing import Any, Mapping
from .audio import CanonicalAudio
from .config import ServiceConfig
from .resources import assert_punkt_tab
+logger = logging.getLogger("hypit.whisperx")
+
class InferenceInputError(ValueError):
pass
@@ -104,11 +108,14 @@ class WhisperXEngine:
self._config = config
self._inference_lock = threading.Lock()
self._alignment_models: dict[str, tuple[object, object]] = {}
+ started = time.monotonic()
+ logger.info("loading ASR model=%s; uncached weights may download during this call", config.model)
self._asr = whisperx_module.load_model(
config.model,
config.device,
compute_type=config.compute,
)
+ logger.info("ASR model ready in %.1fs", time.monotonic() - started)
self._whisperx_version = metadata.version("whisperx")
def identity(self) -> dict[str, object]:
@@ -123,6 +130,8 @@ class WhisperXEngine:
def _alignment_model(self, language: str) -> tuple[object, object]:
model = self._alignment_models.get(language)
if model is None:
+ started = time.monotonic()
+ logger.info("loading alignment model for language=%s; uncached weights may download during this call", language)
loaded = self._whisperx.load_align_model(
language_code=language,
device=self._config.device,
@@ -131,6 +140,7 @@ class WhisperXEngine:
raise RuntimeError("WhisperX returned an invalid alignment model")
model = loaded
self._alignment_models[language] = model
+ logger.info("alignment model ready for language=%s in %.1fs", language, time.monotonic() - started)
return model
def transcribe(self, audio: CanonicalAudio, language: str | None) -> dict[str, object]:
@@ -144,11 +154,14 @@ class WhisperXEngine:
if not self._inference_lock.acquire(blocking=False):
raise InferenceBusyError("the warm WhisperX model is already executing one request")
try:
+ started = time.monotonic()
+ logger.info("transcribing %.2fs of audio, language=%s", audio.duration_sec, language or "auto")
transcription = self._asr.transcribe(
samples,
batch_size=self._config.batch_size,
language=language,
)
+ logger.info("transcription completed in %.1fs", time.monotonic() - started)
detected = transcription.get("language") or language or "en"
if not isinstance(detected, str) or not detected.strip():
raise RuntimeError("WhisperX did not return a valid language")
@@ -156,8 +169,11 @@ class WhisperXEngine:
if not isinstance(segments, list):
raise RuntimeError("WhisperX transcription returned invalid segments")
if not segments:
+ logger.info("no speech segments; alignment is unnecessary")
return {"language": detected, "segments": []}
alignment_model, metadata_value = self._alignment_model(detected)
+ started = time.monotonic()
+ logger.info("aligning %d speech segments, language=%s", len(segments), detected)
aligned = self._whisperx.align(
segments,
alignment_model,
@@ -168,6 +184,8 @@ class WhisperXEngine:
)
if not isinstance(aligned, Mapping):
raise RuntimeError("WhisperX returned an invalid alignment result")
- return normalize_alignment(detected, aligned)
+ result = normalize_alignment(detected, aligned)
+ logger.info("word timing ready in %.1fs", time.monotonic() - started)
+ return result
finally:
self._inference_lock.release()