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.

feat: narratage services up|down|status

kashorin8819fa002e31
diff --git a/examples/echo-pro-aroll/svml.runtime-packages.lock b/examples/echo-pro-aroll/svml.runtime-packages.lock
index cba08eb5..9cd1f2e0 100644
--- a/examples/echo-pro-aroll/svml.runtime-packages.lock
+++ b/examples/echo-pro-aroll/svml.runtime-packages.lock
@@ -129,7 +129,7 @@
{
"name": "@narratage/provider-whisperx-local",
"version": "0.0.0-dev",
- "digest": "sha256:f1abef0bb16d172d2d013b1e44cedcd77bc1beeaa46590b90774892fd948514f"
+ "digest": "sha256:35b536fe2e6752d4cc92ca368a318214e8e56e0d8356eba56a049d3a626543c5"
},
{
"name": "@narratage/render-hyperframes",
@@ -886,8 +886,8 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:3686b84c42cc2b1bcaccf57cbdcda25a15c7d9d3778fb92d25437f9880ed8f5d",
- "closureDigest": "sha256:a9a75710e062f02bb8ba55cd5eac6ef2c8622fcddd8908547f336503b1f188ca"
+ "closureDigest": "sha256:d82fe2de72e4ce6fee4f660552b12485617b4254289a0ee4fd50e72a492f44e8"
}
],
- "digest": "sha256:f0cf55a93a5bbc7e9500b20a3c09d49624b5b3fdc49cb5c9d8e4d0fe0e436e83"
+ "digest": "sha256:680b29750d6c64627622b37eb9975077d09ba616093170bb08b65b43bbe2947e"
}
diff --git a/packages/cli/src/distribution.ts b/packages/cli/src/distribution.ts
index eee52571..3bbfb712 100644
--- a/packages/cli/src/distribution.ts
+++ b/packages/cli/src/distribution.ts
@@ -1,6 +1,6 @@
import type { NodeCompiler } from "@narratage/compiler-node";
import type { LocalRuntime } from "@narratage/local";
-import type { RuntimeConfigDoctorResult } from "@narratage/local";
+import type { ExternalServiceReport, RuntimeConfigDoctorResult } from "@narratage/local";
import type { NodePackageContribution } from "@narratage/package-loader-node";
import type { RunFrontend } from "@narratage/run";
@@ -23,4 +23,15 @@ export type CliDistribution = {
createCompiler(options: CliCompilerOptions): NodeCompiler;
createRuntimeFromConfig(path: string): Promise<LocalRuntime>;
doctorRuntimeConfig(path: string): Promise<RuntimeConfigDoctorResult>;
+ /** The external programs a Runtime Profile implies: probe, prepare and start them. */
+ readonly externalServices: {
+ up(path: string, options: { maxWaitMs?: number }): Promise<ExternalServiceResult>;
+ down(path: string): Promise<ExternalServiceResult>;
+ report(path: string): Promise<ExternalServiceResult>;
+ };
+};
+
+export type ExternalServiceResult = {
+ readonly root: string;
+ readonly services: readonly ExternalServiceReport[];
};
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 5c637872..cf4e72ae 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -29,6 +29,8 @@ type CliIo = {
type ParsedArgs = {
readonly command: string | undefined;
+ /** Second command word. Only `services` takes one. */
+ readonly action: string | undefined;
readonly file: string | undefined;
readonly root: string | undefined;
readonly targets: readonly string[];
@@ -50,8 +52,10 @@ type ParsedArgs = {
function parseArgs(argv: readonly string[]): ParsedArgs {
const [command, ...tail] = argv;
- const file = command === "builds" ? undefined : tail[0];
- const rest = command === "builds" ? tail : tail.slice(1);
+ const action = command === "services" ? tail[0] : undefined;
+ const positional = command === "services" ? tail.slice(1) : tail;
+ const file = command === "builds" ? undefined : positional[0];
+ const rest = command === "builds" ? positional : positional.slice(1);
const targets: string[] = [];
let root: string | undefined;
let runtime: string | undefined;
@@ -185,6 +189,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
}
return {
command,
+ action,
file,
root,
targets,
@@ -210,6 +215,7 @@ function usage(): string {
"usage:",
" narratage lock-packages <svml.packages.lock> --package installed-name [--package installed-name] [--root directory]",
" narratage doctor <runtime-profile.json>",
+ " narratage services up|down|status <runtime-profile.json> [--max-wait-ms milliseconds]",
" narratage gc <runtime-profile.json> [--apply]",
" narratage check <self-described-source> [--runtime profile.json] [--package-lock file] [--root directory]",
" narratage plan <run-source> [--runtime profile.json] [--package-lock file]",
@@ -287,7 +293,7 @@ export async function runCli(
const known = args.command === "lock-packages" || args.command === "check" || args.command === "plan"
|| args.command === "build" || args.command === "status" || args.command === "builds"
|| args.command === "inspect" || args.command === "get" || args.command === "cancel"
- || args.command === "doctor" || args.command === "gc";
+ || args.command === "doctor" || args.command === "gc" || args.command === "services";
if (!known || (args.command !== "builds" && args.file === undefined)) {
throw new Error(usage());
}
@@ -313,6 +319,31 @@ export async function runCli(
}, null, 2)}\n`);
return;
}
+ if (args.command === "services") {
+ if (args.runtime !== undefined || args.packageLock !== undefined || args.packages.length > 0 || args.apply) {
+ throw new Error("services reads all deployment selection from the Runtime Profile itself");
+ }
+ if (args.action !== "up" && args.action !== "down" && args.action !== "status") {
+ throw new Error("services takes up, down or status");
+ }
+ if (args.action !== "up" && args.maxWaitMs !== undefined) {
+ throw new Error("--max-wait-ms applies to services up");
+ }
+ const profile = resolve(args.file!);
+ const result = args.action === "up"
+ ? await distribution.externalServices.up(profile, {
+ ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
+ })
+ : args.action === "down"
+ ? await distribution.externalServices.down(profile)
+ : await distribution.externalServices.report(profile);
+ io.write(`${JSON.stringify({
+ ok: result.services.every((item) => (args.action === "down" ? item.state.state !== "ready" : item.state.state === "ready")),
+ root: result.root,
+ services: result.services,
+ }, null, 2)}\n`);
+ return;
+ }
if (args.command === "gc") {
if (args.runtime !== undefined || args.packageLock !== undefined || args.packages.length > 0) {
throw new Error("gc reads all deployment selection from the Runtime Profile itself");
diff --git a/packages/cli/test/services-command.test.ts b/packages/cli/test/services-command.test.ts
new file mode 100644
index 00000000..1c7c35c9
--- /dev/null
+++ b/packages/cli/test/services-command.test.ts
@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runCli } from "../src/main.js";
+import type { CliDistribution, ExternalServiceResult } from "../src/distribution.js";
+
+const empty: ExternalServiceResult = { root: "/tmp", services: [] };
+
+function distribution(calls: string[]): CliDistribution {
+ return {
+ name: "test",
+ builtInPackageContributions: [],
+ runFrontends: [],
+ externalServices: {
+ up: async (path: string, options: { maxWaitMs?: number }) => {
+ calls.push(`up ${path} ${JSON.stringify(options)}`);
+ return empty;
+ },
+ down: async (path: string) => { calls.push(`down ${path}`); return empty; },
+ report: async (path: string) => { calls.push(`report ${path}`); return empty; },
+ },
+ } as unknown as CliDistribution;
+}
+
+const io = { write: () => {} };
+
+test("services dispatches its second word, and passes the wait only to up", async () => {
+ const calls: string[] = [];
+ await runCli(["services", "up", "/p/svml.runtime.json", "--max-wait-ms", "1000"], io, distribution(calls));
+ await runCli(["services", "down", "/p/svml.runtime.json"], io, distribution(calls));
+ await runCli(["services", "status", "/p/svml.runtime.json"], io, distribution(calls));
+ assert.deepEqual(calls, [
+ 'up /p/svml.runtime.json {"maxWaitMs":1000}',
+ "down /p/svml.runtime.json",
+ "report /p/svml.runtime.json",
+ ]);
+});
+
+test("services names its three words rather than guessing one", async () => {
+ await assert.rejects(
+ async () => await runCli(["services", "restart", "/p/svml.runtime.json"], io, distribution([])),
+ /services takes up, down or status/u,
+ );
+});
+
+test("waiting is a property of bringing up, not of looking or stopping", async () => {
+ await assert.rejects(
+ async () => await runCli(["services", "status", "/p/svml.runtime.json", "--max-wait-ms", "1000"], io, distribution([])),
+ /--max-wait-ms applies to services up/u,
+ );
+});
+
+test("services reads deployment selection from the Profile, never from flags", async () => {
+ await assert.rejects(
+ async () => await runCli(
+ ["services", "up", "/p/svml.runtime.json", "--runtime", "other.json"],
+ io,
+ distribution([]),
+ ),
+ /services reads all deployment selection from the Runtime Profile itself/u,
+ );
+});
diff --git a/packages/local/src/config.ts b/packages/local/src/config.ts
index 583237a8..f1f89b82 100644
--- a/packages/local/src/config.ts
+++ b/packages/local/src/config.ts
@@ -187,6 +187,43 @@ async function installLockedRuntimeAdapters(
}
}
+/** One Endpoint's declaration of an external program its Provider drives. */
+export type DeclaredExternalService = {
+ readonly instance: string;
+ readonly service: RuntimeExternalService;
+};
+
+/**
+ * The external programs a Runtime Profile implies, in the order it declares
+ * them. Two Endpoints may name the same program — one WhisperX serves every
+ * Provider instance pointed at it — so callers that act on these deduplicate
+ * by `service.id` and act once.
+ */
+export async function declaredExternalServices(
+ path: string,
+ options: LoadRuntimeConfigOptions = {},
+): Promise<{ readonly root: string; readonly services: readonly DeclaredExternalService[] }> {
+ const absolute = resolve(path);
+ const document = parseRuntimeConfig(JSON.parse(await readFile(absolute, "utf8")));
+ const root = resolve(dirname(absolute), document.root ?? ".");
+ const registry = options.registry ?? new RuntimeAdapterRegistry();
+ await installLockedRuntimeAdapters(registry, document.runtimePackageLock, root);
+ const services: DeclaredExternalService[] = [];
+ for (const item of document.endpoints) {
+ if (!registry.has(item.use, "endpoint")) {
+ throw new Error(`Runtime Adapter ${item.use} is not registered`);
+ }
+ const service = registry.service(item.use, {
+ root,
+ instance: item.instance,
+ ...(item.lane === undefined ? {} : { lane: item.lane }),
+ config: item.config ?? {},
+ });
+ if (service !== undefined) services.push({ instance: item.instance, service });
+ }
+ return { root, services };
+}
+
function diagnostic(error: unknown, code: string, subject?: string): RuntimeDoctorDiagnostic {
return {
severity: "error",
diff --git a/packages/local/src/external-services.ts b/packages/local/src/external-services.ts
new file mode 100644
index 00000000..cf771806
--- /dev/null
+++ b/packages/local/src/external-services.ts
@@ -0,0 +1,218 @@
+import { spawn } from "node:child_process";
+import { mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import type { RuntimeExternalService, RuntimeServiceCommand, RuntimeServiceState } from "@narratage/runtime-adapter";
+
+import { declaredExternalServices } from "./config.js";
+import type { LoadRuntimeConfigOptions } from "./config.js";
+
+export type ExternalServiceAction =
+ | "already-running"
+ | "prepared"
+ | "started"
+ | "stopped"
+ | "not-ours"
+ | "nothing-to-stop"
+ | "unchanged";
+
+export type ExternalServiceReport = {
+ readonly id: string;
+ /** Every Endpoint this program serves, so an operator sees what a restart affects. */
+ readonly instances: readonly string[];
+ /** What this call did. Absent when it was only asked to look. */
+ readonly action?: ExternalServiceAction;
+ readonly state: RuntimeServiceState;
+ /** Why the action fell short. Never a copy of what `state` already says. */
+ readonly detail?: string;
+ readonly logPath?: string;
+ readonly pid?: number;
+};
+
+export type ExternalServiceOptions = LoadRuntimeConfigOptions & {
+ /** How long to wait for a started program to answer its probe. Default 300000. */
+ readonly maxWaitMs?: number;
+};
+
+/** Two Endpoints may drive the same program; it is brought up once. */
+function distinct(services: readonly { instance: string; service: RuntimeExternalService }[]) {
+ const unique = new Map<string, { service: RuntimeExternalService; instances: string[] }>();
+ for (const item of services) {
+ const found = unique.get(item.service.id);
+ if (found === undefined) unique.set(item.service.id, { service: item.service, instances: [item.instance] });
+ else found.instances.push(item.instance);
+ }
+ return [...unique.values()];
+}
+
+function directory(root: string): string {
+ return join(root, ".svml", "services");
+}
+
+async function readPid(root: string, id: string): Promise<number | undefined> {
+ try {
+ const text = await readFile(join(directory(root), `${id}.pid`), "utf8");
+ const pid = Number.parseInt(text.trim(), 10);
+ return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+function alive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function run(root: string, command: RuntimeServiceCommand): Promise<{ ok: boolean; detail: string }> {
+ return new Promise((resolve) => {
+ const child = spawn(command.command, [...command.args], { cwd: root, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+ let output = "";
+ child.stdout.on("data", (chunk: Buffer) => { output += chunk.toString(); });
+ child.stderr.on("data", (chunk: Buffer) => { output += chunk.toString(); });
+ child.on("error", (error) => resolve({ ok: false, detail: error.message }));
+ child.on("close", (code) => resolve({
+ ok: code === 0,
+ detail: code === 0 ? "" : (output.trim().split("\n").at(-1) ?? `exited ${code}`),
+ }));
+ });
+}
+
+/**
+ * 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.
+ */
+async function waitForReady(service: RuntimeExternalService, maxWaitMs: number): Promise<RuntimeServiceState> {
+ const deadline = Date.now() + maxWaitMs;
+ let state = await service.probe();
+ while (state.state === "down" && Date.now() < deadline) {
+ await sleep(1000);
+ state = await service.probe();
+ }
+ return state;
+}
+
+async function bringUp(
+ root: string,
+ service: RuntimeExternalService,
+ instances: readonly string[],
+ maxWaitMs: number,
+): Promise<ExternalServiceReport> {
+ const base = { id: service.id, instances };
+ const initial = await service.probe();
+ if (initial.state === "ready") return { ...base, action: "already-running", state: initial };
+ if (initial.state === "mismatch") {
+ // Never start a second copy beside a program that is already answering.
+ return { ...base, action: "unchanged", state: initial };
+ }
+
+ if (service.prepare !== undefined) {
+ const prepared = await run(root, service.prepare);
+ if (!prepared.ok) {
+ return { ...base, action: "unchanged", state: initial, detail: `${service.prepare.command} failed: ${prepared.detail}` };
+ }
+ }
+ if (service.start === undefined) {
+ // Nothing to keep running: preparing was the whole job, and the probe says
+ // whether it worked.
+ const state = await service.probe();
+ return { ...base, action: state.state === "ready" ? "prepared" : "unchanged", state };
+ }
+
+ await mkdir(directory(root), { recursive: true });
+ const logPath = join(directory(root), `${service.id}.log`);
+ const log = await open(logPath, "a");
+ try {
+ const child = spawn(service.start.command, [...service.start.args], {
+ cwd: root,
+ shell: false,
+ detached: true,
+ stdio: ["ignore", log.fd, log.fd],
+ });
+ child.unref();
+ if (child.pid === undefined) {
+ return { ...base, action: "unchanged", state: initial, detail: `${service.start.command} did not start`, logPath };
+ }
+ await writeFile(join(directory(root), `${service.id}.pid`), `${child.pid}\n`);
+ const state = await waitForReady(service, maxWaitMs);
+ return {
+ ...base,
+ action: state.state === "ready" ? "started" : "unchanged",
+ state,
+ pid: child.pid,
+ logPath,
+ ...(state.state === "ready" ? {} : { detail: `see ${logPath}` }),
+ };
+ } finally {
+ await log.close();
+ }
+}
+
+/** Prepare and start every external program the Runtime Profile implies. */
+export async function bringExternalServicesUp(
+ path: string,
+ options: ExternalServiceOptions = {},
+): Promise<{ readonly root: string; readonly services: readonly ExternalServiceReport[] }> {
+ const { root, services } = await declaredExternalServices(path, options);
+ const reports: ExternalServiceReport[] = [];
+ for (const { service, instances } of distinct(services)) {
+ reports.push(await bringUp(root, service, instances, options.maxWaitMs ?? 300_000));
+ }
+ return { root, services: reports };
+}
+
+/** Stop the programs this project started. A program it did not start is left alone. */
+export async function takeExternalServicesDown(
+ path: string,
+ options: ExternalServiceOptions = {},
+): Promise<{ readonly root: string; readonly services: readonly ExternalServiceReport[] }> {
+ const { root, services } = await declaredExternalServices(path, options);
+ const reports: ExternalServiceReport[] = [];
+ for (const { service, instances } of distinct(services)) {
+ const base = { id: service.id, instances };
+ const pid = await readPid(root, service.id);
+ if (pid === undefined || !alive(pid)) {
+ if (pid !== undefined) await rm(join(directory(root), `${service.id}.pid`), { force: true });
+ const state = await service.probe();
+ reports.push(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: `${service.id} is running but this project did not start it` });
+ continue;
+ }
+ process.kill(pid, "SIGTERM");
+ const deadline = Date.now() + 15_000;
+ while (alive(pid) && Date.now() < deadline) await sleep(200);
+ if (alive(pid)) process.kill(pid, "SIGKILL");
+ await rm(join(directory(root), `${service.id}.pid`), { force: true });
+ reports.push({ ...base, action: "stopped", state: await service.probe(), pid });
+ }
+ return { root, services: reports };
+}
+
+/** Probe every external program without changing anything. */
+export async function reportExternalServices(
+ path: string,
+ options: ExternalServiceOptions = {},
+): Promise<{ readonly root: string; readonly services: readonly ExternalServiceReport[] }> {
+ const { root, services } = await declaredExternalServices(path, options);
+ const reports: ExternalServiceReport[] = [];
+ for (const { service, instances } of distinct(services)) {
+ const state = await service.probe();
+ const pid = await readPid(root, service.id);
+ reports.push({
+ id: service.id,
+ instances,
+ state,
+ ...(pid !== undefined && alive(pid) ? { pid } : {}),
+ });
+ }
+ return { root, services: reports };
+}
diff --git a/packages/local/src/index.ts b/packages/local/src/index.ts
index 3cdd96c8..b0faddd1 100644
--- a/packages/local/src/index.ts
+++ b/packages/local/src/index.ts
@@ -9,12 +9,19 @@ export {
} from "./runtime.js";
export {
createRuntimeFromConfig,
+ declaredExternalServices,
doctorRuntimeConfig,
parseRuntimeConfig,
} from "./config.js";
+export {
+ bringExternalServicesUp,
+ reportExternalServices,
+ takeExternalServicesDown,
+} from "./external-services.js";
export {
RuntimeAdapterRegistry,
RuntimeAdapterRegistry as RuntimeConfigRegistry,
} from "@narratage/runtime-adapter";
export type * from "./types.js";
export type * from "./config.js";
+export type * from "./external-services.js";
diff --git a/packages/local/test/external-services.test.ts b/packages/local/test/external-services.test.ts
new file mode 100644
index 00000000..ef2d51a4
--- /dev/null
+++ b/packages/local/test/external-services.test.ts
@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { createRuntimeEndpointAdapterFacet } from "@narratage/runtime-adapter";
+import type { RuntimeExternalService } from "@narratage/runtime-adapter";
+
+import {
+ bringExternalServicesUp,
+ reportExternalServices,
+ RuntimeConfigRegistry,
+ takeExternalServicesDown,
+} from "@narratage/local";
+
+/**
+ * A stand-in program: `start` writes a file and sleeps, and the probe reads that
+ * file back. That is enough to exercise detaching, the pid file, waiting for
+ * ready, and stopping — without a Python environment.
+ */
+async function project(service: (root: string) => RuntimeExternalService) {
+ const root = await mkdtemp(join(tmpdir(), "svml-services-"));
+ const path = join(root, "svml.runtime.json");
+ await writeFile(path, JSON.stringify({
+ format: "svml.runtime-config@1",
+ endpoints: [
+ { use: "example.program", instance: "one", config: {} },
+ // A second Endpoint driving the same program: it is brought up once.
+ { use: "example.program", instance: "two", config: {} },
+ ],
+ permissions: [],
+ }));
+ const registry = new RuntimeConfigRegistry();
+ registry.registerFacet(createRuntimeEndpointAdapterFacet({
+ use: "example.program",
+ create: () => ({}) as never,
+ service: () => service(root),
+ }));
+ return { root, path, options: { registry } };
+}
+
+function fileBackedService(root: string, marker: string): RuntimeExternalService {
+ return {
+ id: "example",
+ start: { command: "sh", args: ["-c", `printf ready > ${marker}; while true; do sleep 1; done`] },
+ async probe() {
+ try {
+ await readFile(marker, "utf8");
+ return { state: "ready" };
+ } catch {
+ return { state: "down", detail: `${marker} is absent` };
+ }
+ },
+ };
+}
+
+test("up starts the program once for every Endpoint that drives it, and down stops it", async () => {
+ const marker = join(await mkdtemp(join(tmpdir(), "svml-marker-")), "ready");
+ const { root, path, options } = await project((projectRoot) => fileBackedService(projectRoot, marker));
+
+ const started = await bringExternalServicesUp(path, { ...options, maxWaitMs: 20_000 });
+ assert.equal(started.services.length, 1, "one program, not one per Endpoint");
+ assert.deepEqual(started.services[0]!.instances, ["one", "two"]);
+ assert.equal(started.services[0]!.action, "started");
+ assert.deepEqual(started.services[0]!.state, { state: "ready" });
+
+ const pid = started.services[0]!.pid!;
+ assert.equal(await readFile(join(root, ".svml", "services", "example.pid"), "utf8"), `${pid}\n`);
+
+ // Asking again changes nothing: a healthy program is left alone.
+ const again = await bringExternalServicesUp(path, { ...options, maxWaitMs: 20_000 });
+ assert.equal(again.services[0]!.action, "already-running");
+ assert.equal(again.services[0]!.pid, undefined, "nothing was started, so no pid is claimed");
+
+ await rm(marker, { force: true });
+ const stopped = await takeExternalServicesDown(path, options);
+ assert.equal(stopped.services[0]!.action, "stopped");
+ assert.equal(stopped.services[0]!.pid, pid);
+ await sleep(100);
+ assert.throws(() => process.kill(pid, 0), "the detached program is gone");
+ await assert.rejects(async () => await readFile(join(root, ".svml", "services", "example.pid"), "utf8"));
+ await rm(root, { recursive: true, force: true });
+});
+
+test("a program answering with another identity is never joined by a second copy", async () => {
+ const { path, options } = await project(() => ({
+ id: "example",
+ start: { command: "sh", args: ["-c", "exit 1"] },
+ probe: async () => ({ state: "mismatch", detail: "model is large-v3, expected small" }),
+ }));
+ const result = await bringExternalServicesUp(path, options);
+ assert.equal(result.services[0]!.action, "unchanged");
+ assert.equal(result.services[0]!.state.state, "mismatch");
+ assert.equal(result.services[0]!.pid, undefined, "nothing was started beside it");
+});
+
+test("down leaves a running program this project did not start", async () => {
+ const { path, options } = await project(() => ({
+ id: "example",
+ start: { command: "sh", args: ["-c", "sleep 60"] },
+ probe: async () => ({ state: "ready" }),
+ }));
+ const result = await takeExternalServicesDown(path, options);
+ assert.equal(result.services[0]!.action, "not-ours");
+ assert.match(result.services[0]!.detail ?? "", /this project did not start it/u);
+});
+
+test("a program with nothing to start is prepared, and preparing is the whole job", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "svml-prepare-"));
+ const marker = join(directory, "installed");
+ const { path, options } = await project(() => ({
+ id: "example",
+ prepare: { command: "sh", args: ["-c", `printf done > ${marker}`] },
+ async probe() {
+ try {
+ await readFile(marker, "utf8");
+ return { state: "ready" };
+ } catch {
+ return { state: "down", detail: "not installed" };
+ }
+ },
+ }));
+ const result = await bringExternalServicesUp(path, options);
+ assert.equal(result.services[0]!.action, "prepared");
+ assert.deepEqual(result.services[0]!.state, { state: "ready" });
+ assert.equal(result.services[0]!.pid, undefined, "there is no daemon to hold a pid");
+ await rm(directory, { recursive: true, force: true });
+});
+
+test("a failing prepare stops before starting anything, and says which command failed", async () => {
+ const { path, options } = await project(() => ({
+ id: "example",
+ prepare: { command: "sh", args: ["-c", "echo 'no such project' >&2; exit 1"] },
+ start: { command: "sh", args: ["-c", "while true; do sleep 1; done"] },
+ probe: async () => ({ state: "down", detail: "nothing is answering" }),
+ }));
+ const result = await bringExternalServicesUp(path, options);
+ assert.equal(result.services[0]!.action, "unchanged");
+ assert.match(result.services[0]!.detail ?? "", /sh failed: no such project/u);
+ assert.equal(result.services[0]!.logPath, undefined, "nothing was started, so nothing logged");
+});
+
+test("status probes and changes nothing, so it claims no action", async () => {
+ const { path, options } = await project(() => ({
+ id: "example",
+ start: { command: "sh", args: ["-c", "exit 1"] },
+ probe: async () => ({ state: "down", detail: "nothing is answering" }),
+ }));
+ const result = await reportExternalServices(path, options);
+ assert.equal(result.services[0]!.action, undefined);
+ assert.deepEqual(result.services[0]!.state, { state: "down", detail: "nothing is answering" });
+});
diff --git a/packages/provider-image-opencv-local/src/service.ts b/packages/provider-image-opencv-local/src/service.ts
index 070fc185..0eebdc94 100644
--- a/packages/provider-image-opencv-local/src/service.ts
+++ b/packages/provider-image-opencv-local/src/service.ts
@@ -1,20 +1,22 @@
import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
import { runtimeConfigObject, runtimeConfigString } from "@narratage/runtime-adapter";
import type { RuntimeAdapterFactoryContext, RuntimeExternalService, RuntimeServiceState } from "@narratage/runtime-adapter";
import { resolveRuntimeExecutable } from "@narratage/runtime-adapter-node";
+const WORKSPACE_PROJECT = fileURLToPath(new URL("../../../services/image-opencv", import.meta.url));
+
/**
- * OpenCV runs as one bounded process per Need, so there is nothing to keep
- * warm and this service declares no `start`. What it does declare is the
- * interpreter's identity: a Python without `cv2`, or with a `cv2` from before
- * the APIs this Provider calls, fails in the middle of a Build with a
- * subprocess error. Probing says so at `doctor` time instead.
+ * Absolute, because a Runtime root is wherever the operator keeps their Profile
+ * and not where the pinned uv project lives. An installation without that
+ * project has nothing to prepare and says so through the probe instead.
*/
-const DEFAULT_PREPARE = {
- command: "uv",
- args: ["sync", "--project", "services/image-opencv", "--frozen"],
-} as const;
+function workspacePrepare() {
+ if (!existsSync(WORKSPACE_PROJECT)) return undefined;
+ return { command: "uv", args: ["sync", "--project", WORKSPACE_PROJECT, "--frozen"] };
+}
/** Kept equal to `services/image-opencv/pyproject.toml` by a test in this package. */
const REQUIRED_MAJOR = { cv2: 4, numpy: 2 } as const;
@@ -32,13 +34,21 @@ function run(executable: string, args: readonly string[]): Promise<{ ok: boolean
});
}
+/**
+ * OpenCV runs as one bounded process per Need, so there is nothing to keep warm
+ * and this service declares no `start`. What it does declare is the
+ * interpreter's identity: a Python without `cv2`, or with a `cv2` from before
+ * the APIs this Provider calls, fails in the middle of a Build with a
+ * subprocess error. Probing says so at `doctor` time instead.
+ */
export function localOpenCvService(context: RuntimeAdapterFactoryContext): RuntimeExternalService {
const config = runtimeConfigObject(context.config, "local OpenCV image");
const configured = runtimeConfigString(config.pythonExecutable, "OpenCV pythonExecutable");
const python = configured === undefined ? "python3" : resolveRuntimeExecutable(context.root, configured);
+ const prepare = workspacePrepare();
return {
id: "image-opencv",
- prepare: DEFAULT_PREPARE,
+ ...(prepare === undefined ? {} : { prepare }),
async probe(): Promise<RuntimeServiceState> {
const result = await run(python, ["-c", PROBE_PROGRAM]);
if (!result.ok) return { state: "down", detail: `${python} cannot import cv2 and numpy: ${result.output}` };
diff --git a/packages/provider-image-opencv-local/test/service.test.ts b/packages/provider-image-opencv-local/test/service.test.ts
index 8b6e1bd9..a792bb6b 100644
--- a/packages/provider-image-opencv-local/test/service.test.ts
+++ b/packages/provider-image-opencv-local/test/service.test.ts
@@ -1,7 +1,8 @@
import assert from "node:assert/strict";
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
import test from "node:test";
import { localOpenCvService } from "../src/service.js";
@@ -14,10 +15,13 @@ test("OpenCV declares how to install its interpreter and nothing to keep running
const service = localOpenCvService(context());
assert.equal(service.id, "image-opencv");
assert.equal(service.start, undefined, "OpenCV runs per Need; there is no daemon to start");
- assert.deepEqual(service.prepare, {
- command: "uv",
- args: ["sync", "--project", "services/image-opencv", "--frozen"],
- });
+ // Absolute: a Runtime root is wherever the Profile lives, not where the
+ // pinned uv project lives.
+ assert.equal(service.prepare?.command, "uv");
+ assert.equal(service.prepare?.args.at(-1), "--frozen");
+ const project = service.prepare?.args.at(-2) ?? "";
+ assert.ok(isAbsolute(project), `${project} must be absolute`);
+ assert.ok(existsSync(join(project, "pyproject.toml")), `${project} must be the pinned uv project`);
});
test("an interpreter without cv2 is reported here, not mid-Build", async () => {
diff --git a/packages/provider-whisperx-local/src/service.ts b/packages/provider-whisperx-local/src/service.ts
index 69d963c4..04791eee 100644
--- a/packages/provider-whisperx-local/src/service.ts
+++ b/packages/provider-whisperx-local/src/service.ts
@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
import { runtimeConfigObject, runtimeConfigString } from "@narratage/runtime-adapter";
import type { RuntimeAdapterFactoryContext, RuntimeExternalService, RuntimeServiceState } from "@narratage/runtime-adapter";
@@ -8,21 +11,34 @@ import { localWhisperXPunktTabDigest } from "./provider.js";
* program a developer keeps running, not a process spawned for each Need. The
* Provider declares how to bring it up; the Runtime Profile may override the
* command for an environment that installs WhisperX differently.
+ *
+ * The default names the pinned uv project shipped beside this package in the
+ * Narratage repository, by absolute path — a Runtime root is wherever the
+ * operator keeps their Profile, and it is not where that project lives. An
+ * installation that obtained this package on its own has no such directory and
+ * must say what to run instead; `serviceCommand` is that.
*/
-const DEFAULT_START = {
- command: "uv",
- args: ["run", "--project", "services/whisperx", "--frozen", "svml-whisperx-service"],
-} as const;
+const WORKSPACE_PROJECT = fileURLToPath(new URL("../../../services/whisperx", import.meta.url));
-const DEFAULT_PREPARE = {
- command: "uv",
- args: ["run", "--project", "services/whisperx", "--frozen", "svml-whisperx-prepare"],
-} as const;
+function workspaceCommand(entry: string): { command: string; args: readonly string[] } | undefined {
+ if (!existsSync(WORKSPACE_PROJECT)) return undefined;
+ return { command: "uv", args: ["run", "--project", WORKSPACE_PROJECT, "--frozen", entry] };
+}
-function command(value: unknown, fallback: { readonly command: string; readonly args: readonly string[] }) {
- if (value === undefined) return fallback;
+function command(
+ value: unknown,
+ fallback: { readonly command: string; readonly args: readonly string[] } | undefined,
+ key: string,
+) {
+ if (value === undefined) {
+ if (fallback !== undefined) return fallback;
+ throw new Error(
+ `WhisperX ${key} is required: the pinned uv project is not at ${WORKSPACE_PROJECT},`
+ + " so this deployment must say what command runs WhisperX",
+ );
+ }
if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string")) {
- throw new Error("WhisperX serviceCommand must be a non-empty array of strings");
+ throw new Error(`WhisperX ${key} must be a non-empty array of strings`);
}
return { command: value[0] as string, args: (value as string[]).slice(1) };
}
@@ -37,12 +53,13 @@ export function localWhisperXService(context: RuntimeAdapterFactoryContext): Run
whisperxVersion: runtimeConfigString(config.expectedWhisperXVersion, "WhisperX expectedWhisperXVersion") ?? "3.8.6",
model: runtimeConfigString(config.expectedModel, "WhisperX expectedModel") ?? "small",
device: runtimeConfigString(config.expectedDevice, "WhisperX expectedDevice") ?? "cpu",
- punktTabDigest: runtimeConfigString(config.expectedPunktTabDigest, "WhisperX expectedPunktTabDigest") ?? localWhisperXPunktTabDigest,
+ punktTabDigest: runtimeConfigString(config.expectedPunktTabDigest, "WhisperX expectedPunktTabDigest")
+ ?? localWhisperXPunktTabDigest,
};
return {
id: "whisperx",
- prepare: command(config.servicePrepareCommand, DEFAULT_PREPARE),
- start: command(config.serviceCommand, DEFAULT_START),
+ prepare: command(config.servicePrepareCommand, workspaceCommand("svml-whisperx-prepare"), "servicePrepareCommand"),
+ start: command(config.serviceCommand, workspaceCommand("svml-whisperx-service"), "serviceCommand"),
async probe(): Promise<RuntimeServiceState> {
let health: Record<string, unknown>;
try {
diff --git a/packages/provider-whisperx-local/test/service.test.ts b/packages/provider-whisperx-local/test/service.test.ts
index 4e12de1c..33934409 100644
--- a/packages/provider-whisperx-local/test/service.test.ts
+++ b/packages/provider-whisperx-local/test/service.test.ts
@@ -1,4 +1,6 @@
import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
import test from "node:test";
import { localWhisperXService } from "../src/service.js";
@@ -10,11 +12,14 @@ const context = (config: Record<string, unknown> = {}) => ({
test("the Provider declares how to bring WhisperX up and how to recognise it", () => {
const service = localWhisperXService(context());
assert.equal(service.id, "whisperx");
- assert.deepEqual(service.start, {
- command: "uv",
- args: ["run", "--project", "services/whisperx", "--frozen", "svml-whisperx-service"],
- });
+ assert.equal(service.start?.command, "uv");
+ assert.equal(service.start?.args.at(-1), "svml-whisperx-service");
assert.equal(service.prepare?.args.at(-1), "svml-whisperx-prepare");
+ // Absolute: a Runtime root is wherever the Profile lives, not where the
+ // pinned uv project lives.
+ const project = service.start?.args.at(-3) ?? "";
+ assert.ok(isAbsolute(project), `${project} must be absolute`);
+ assert.ok(existsSync(join(project, "pyproject.toml")), `${project} must be the pinned uv project`);
});
test("a deployment that installs WhisperX elsewhere overrides the command", () => {
diff --git a/packages/video-cli/src/distribution.ts b/packages/video-cli/src/distribution.ts
index 6784acf9..3279b8c1 100644
--- a/packages/video-cli/src/distribution.ts
+++ b/packages/video-cli/src/distribution.ts
@@ -3,7 +3,12 @@ import {
createVideoCompiler,
videoBuiltInPackageContributions,
} from "./compiler.js";
-import { doctorRuntimeConfig } from "@narratage/local";
+import {
+ bringExternalServicesUp,
+ doctorRuntimeConfig,
+ reportExternalServices,
+ takeExternalServicesDown,
+} from "@narratage/local";
import { createVideoRuntimeFromConfig } from "./runtime-config.js";
/** Official video authoring and local Runtime-adapter assembly for the generic CLI engine. */
@@ -14,4 +19,9 @@ export const videoCliDistribution: CliDistribution = {
createCompiler: createVideoCompiler,
createRuntimeFromConfig: createVideoRuntimeFromConfig,
doctorRuntimeConfig,
+ externalServices: {
+ up: bringExternalServicesUp,
+ down: takeExternalServicesDown,
+ report: reportExternalServices,
+ },
};