Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
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.lockindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 runningconst 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.tsindex 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): RunwhisperxVersion: 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.tsindex 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.tsindex 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,+ },};