@interf/compiler 0.18.0 → 0.22.0

package/dist/cli/commands/reset.js

@@ -1,8 +1,8 @@
 /**
- * `interf reset <prep-id>` — reset a preparation's compile output (or all state).
+ * `interf reset <prep-id>` — reset a preparation's built output (or all state).
  *
- *   interf reset bristol             # default mode = compile
- *   interf reset bristol --mode all  # also clear method draft / runs
+ *   interf reset bristol             # default mode = build
+ *   interf reset bristol --mode all  # also clear Build Plan draft / runs
  */
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
@@ -29,13 +29,13 @@ async function callJson(url, token, init = {}) {
 }
 export const resetCommand = {
     command: "reset <prep-id>",
-    describe: "Reset a preparation's compile output",
+    describe: "Reset a preparation's built output",
     builder: (yargs) => yargs
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
         .option("mode", {
         type: "string",
-        choices: ["compile", "all"],
-        default: "compile",
+        choices: ["build", "all"],
+        default: "build",
         describe: "Scope of the reset",
     })
         .option("url", { type: "string", describe: "Override the active connection URL" })

package/dist/cli/commands/runs.js

@@ -4,11 +4,8 @@
  *   interf runs ls [--prep <id>]
  *   interf runs status <run-id>
  *   interf runs cancel <run-id>
- *   interf runs fetch <run-id> --to <path>
  */
 import chalk from "chalk";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
@@ -40,6 +37,90 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+function runStatusColor(status) {
+    if (status === "succeeded" || status === "completed")
+        return chalk.green;
+    if (status === "failed" || status === "cancelled")
+        return chalk.red;
+    if (status === "running")
+        return chalk.yellow;
+    return chalk.dim;
+}
+function renderRunStatus(run) {
+    const status = run.status ?? (run.trace?.run?.error ? "failed" : "unknown");
+    const color = runStatusColor(status);
+    console.log();
+    console.log(`  ${chalk.bold(run.title ?? run.run_id)} ${color(`(${status})`)}`);
+    console.log(chalk.dim(`    run: ${run.run_id}`));
+    if (run.run_type)
+        console.log(chalk.dim(`    type: ${run.run_type}`));
+    if (run.preparation)
+        console.log(chalk.dim(`    preparation: ${run.preparation}`));
+    if (run.build_plan)
+        console.log(chalk.dim(`    Build Plan: ${run.build_plan}`));
+    if (run.agent_label)
+        console.log(chalk.dim(`    agent: ${run.agent_label}`));
+    if (run.started_at)
+        console.log(chalk.dim(`    started: ${run.started_at}`));
+    if (run.finished_at)
+        console.log(chalk.dim(`    finished: ${run.finished_at}`));
+    if (run.output_path ?? run.verifiable_context_path) {
+        console.log(chalk.dim(`    output: ${run.output_path ?? run.verifiable_context_path}`));
+    }
+    if (run.trace?.run?.error?.message) {
+        console.log();
+        console.log(chalk.red("    Error"));
+        console.log(chalk.dim(`      ${run.trace.run.error.message}`));
+    }
+    const readiness = run.readiness;
+    if (readiness?.status) {
+        console.log();
+        const readinessColor = readiness.ready ? chalk.green : chalk.yellow;
+        console.log(`    readiness: ${readinessColor(readiness.status)}${readiness.summary ? chalk.dim(` (${readiness.summary})`) : ""}`);
+    }
+    const metrics = run.metrics ?? [];
+    if (metrics.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Metrics"));
+        for (const metric of metrics.slice(0, 8)) {
+            const value = metric.value !== undefined ? `${metric.value}${metric.unit ? ` ${metric.unit}` : ""}` : "";
+            console.log(chalk.dim(`      ${metric.label ?? "metric"}: ${value}`));
+        }
+    }
+    const artifacts = run.artifacts ?? [];
+    if (artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        for (const artifact of artifacts.slice(0, 12)) {
+            const stage = artifact.stage_id ? chalk.dim(` ← ${artifact.stage_id}`) : "";
+            console.log(`      ${artifact.label ?? artifact.role}: ${chalk.dim(artifact.path)}${stage}`);
+        }
+        if (artifacts.length > 12)
+            console.log(chalk.dim(`      ... ${artifacts.length - 12} more`));
+    }
+    const proof = run.proof ?? [];
+    if (proof.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Proof"));
+        for (const check of proof.slice(0, 12)) {
+            const marker = check.ok ? chalk.green("pass") : chalk.red("fail");
+            console.log(`      ${marker} ${check.label}${check.detail ? chalk.dim(` — ${check.detail}`) : ""}`);
+        }
+        if (proof.length > 12)
+            console.log(chalk.dim(`      ... ${proof.length - 12} more`));
+    }
+    const events = run.trace?.events ?? [];
+    if (events.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Recent trace"));
+        for (const event of events.slice(-6)) {
+            console.log(chalk.dim(`      ${event.createdAt ?? ""} ${event.eventType ?? "event"}`.trim()));
+        }
+    }
+    console.log();
+    console.log(chalk.dim("  Run with --json for the raw run resource."));
+    console.log();
+}
 export const runsCommand = {
     command: "runs <subcommand>",
     describe: "Inspect runs on the connected instance",
@@ -48,24 +129,23 @@ export const runsCommand = {
         .option("token", { type: "string", describe: "Override the active bearer token" })
         .command("ls", "List runs (optionally filtered by preparation)", (y) => y.option("prep", { type: "string", describe: "Filter by preparation id" }), async (args) => {
         const { url, token } = resolveConnection(args);
-        const path = args.prep
-            ? `/v1/preparations/${encodeURIComponent(args.prep)}/runs`
-            : "/v1/runs";
-        const { status, body, raw } = await callJson(`${url}${path}`, token);
+        const { status, body, raw } = await callJson(`${url}/v1/runs`, token);
         if (status !== 200) {
             console.error(chalk.red(`Failed to list runs (HTTP ${status}).`));
             if (raw)
                 console.error(raw);
             process.exit(1);
         }
-        const runs = body?.runs
-            ?? (body?.compile_runs ?? []).map((r) => r.run).filter(Boolean);
-        if (runs.length === 0) {
+        const runs = body?.runs ?? [];
+        const visibleRuns = args.prep
+            ? runs.filter((run) => run.preparation === args.prep)
+            : runs;
+        if (visibleRuns.length === 0) {
             console.log(chalk.dim("  No runs."));
             return;
         }
         console.log();
-        for (const run of runs) {
+        for (const run of visibleRuns) {
             console.log(`  ${chalk.bold(run.run_id)} ${chalk.dim(`(${run.status ?? "?"})`)}`);
             if (run.preparation)
                 console.log(chalk.dim(`    prep: ${run.preparation}`));
@@ -74,18 +154,28 @@ export const runsCommand = {
         }
         console.log();
     })
-        .command("status <run-id>", "Show full record for a run", (y) => y.positional("run-id", { type: "string", demandOption: true, describe: "Run id" }), async (args) => {
+        .command("status <run-id>", "Show full record for a run", (y) => y
+        .positional("run-id", { type: "string", demandOption: true, describe: "Run id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
         const { url, token } = resolveConnection(args);
-        const { status, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}`, token);
+        const { status, body, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}`, token);
         if (status !== 200) {
             console.error(chalk.red(`Failed to read run ${args.runId} (HTTP ${status}).`));
             process.exit(1);
         }
-        console.log(raw);
+        if (args.json || !body) {
+            console.log(raw);
+            return;
+        }
+        renderRunStatus(body);
     })
         .command("cancel <run-id>", "Cancel a running run", (y) => y.positional("run-id", { type: "string", demandOption: true, describe: "Run id" }), async (args) => {
         const { url, token } = resolveConnection(args);
-        const { status, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}/cancel`, token, { method: "POST", body: JSON.stringify({}) });
+        const { status, raw } = await callJson(`${url}/v1/build-runs/${encodeURIComponent(args.runId)}/cancel`, token, { method: "POST", body: JSON.stringify({}) });
         if (status !== 200 && status !== 202 && status !== 204) {
             console.error(chalk.red(`Failed to cancel ${args.runId} (HTTP ${status}).`));
             if (raw)
@@ -93,24 +183,6 @@ export const runsCommand = {
             process.exit(1);
         }
         console.log(chalk.green(`Cancelled ${chalk.bold(args.runId)}.`));
-    })
-        .command("fetch <run-id>", "Download a run's portable context", (y) => y
-        .positional("run-id", { type: "string", demandOption: true, describe: "Run id" })
-        .option("to", { type: "string", demandOption: true, describe: "Target path" }), async (args) => {
-        const { url, token } = resolveConnection(args);
-        const headers = new Headers();
-        if (token)
-            headers.set("authorization", `Bearer ${token}`);
-        const response = await fetch(`${url}/v1/runs/${encodeURIComponent(args.runId)}/artifacts/portable-context`, { headers });
-        if (response.status !== 200) {
-            console.error(chalk.red(`Failed to fetch artifact (HTTP ${response.status}).`));
-            process.exit(1);
-        }
-        const target = isAbsolute(args.to) ? args.to : resolve(process.cwd(), args.to);
-        mkdirSync(dirname(target), { recursive: true });
-        const buffer = Buffer.from(await response.arrayBuffer());
-        writeFileSync(target, buffer);
-        console.log(chalk.green(`Wrote ${target} (${buffer.length} bytes).`));
     })
         .demandCommand(1)
         .strict(),

package/dist/cli/commands/status.js

@@ -64,12 +64,14 @@ export const statusCommand = {
         console.log();
         console.log(chalk.bold(`  Preparations (${list.length})`));
         if (list.length === 0) {
-            console.log(chalk.dim("  No preparations yet. `interf prep create <id> --source <path> --method <id>`."));
+            console.log(chalk.dim("  No preparations yet. `interf prep create <id> --source <path>`."));
         }
         else {
             for (const prep of list) {
                 const readiness = prep.readiness?.status ?? "—";
-                console.log(`  ${chalk.bold(prep.id)} ${chalk.dim(`(${prep.method_id} · ${readiness})`)}`);
+                const buildPlan = prep.build_plan_id ?? "no Build Plan";
+                const requested = prep.requested_artifacts?.length ?? 0;
+                console.log(`  ${chalk.bold(prep.id)} ${chalk.dim(`(${buildPlan} · ${requested} requested · ${readiness})`)}`);
                 console.log(chalk.dim(`    source: ${prep.source.locator}`));
             }
         }

package/dist/cli/commands/test.d.ts

@@ -0,0 +1,10 @@
+import type { CommandModule } from "yargs";
+type TestTarget = "verifiable-context" | "source-files";
+interface TestArgs {
+    prepId: string;
+    target?: TestTarget;
+    url?: string;
+    token?: string;
+}
+export declare const testCommand: CommandModule<unknown, TestArgs>;
+export {};

package/dist/cli/commands/{verify.js → test.js}

@@ -1,14 +1,13 @@
 /**
- * `interf verify <prep-id>` — verify a preparation's claim-checks via a
- * judge against the latest compiled portable context (default) or
- * against the source folder baseline (`--target source-files`). The
- * source-files target reveals how much value the Method actually adds.
- * Together with the method's structural checks (auto-run on every
- * `interf compile`), this feeds the preparation's overall readiness
- * state.
+ * `interf test <prep-id>` — run readiness checks for a Preparation via a
+ * judge against the latest verifiable context (default) or against the source
+ * baseline (`--target source-files`). The source-files target reveals how
+ * much value the Build Plan adds. Together with Build Plan Artifact checks
+ * (auto-run on every `interf build`), this feeds the Preparation's
+ * overall readiness state.
  *
- *   interf verify bristol
- *   interf verify bristol --target source-files
+ *   interf test bristol
+ *   interf test bristol --target source-files
  */
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
@@ -42,35 +41,34 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
-export const verifyCommand = {
-    command: "verify <prep-id>",
-    describe: "Verify a preparation's claim-checks against its portable context (or source-files baseline)",
+export const testCommand = {
+    command: "test <prep-id>",
+    describe: "Run readiness checks against a Preparation's verifiable context (or source-files baseline)",
     builder: (yargs) => yargs
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
         .option("target", {
         type: "string",
-        choices: ["compiled", "source-files"],
-        default: "compiled",
-        describe: "Judge target: 'compiled' (default) checks the portable context, 'source-files' checks the raw source folder baseline",
+        choices: ["verifiable-context", "source-files"],
+        default: "verifiable-context",
+        describe: "Judge target: 'verifiable-context' (default) checks built output, 'source-files' checks the raw Source baseline",
     })
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" }),
     handler: async (args) => {
         const { url, token } = resolveConnection(args);
-        // 0.15 hard-error: refuse to start a verify run if the engine has
-        // zero connected agents — verifier-role stages can't run without
-        // one.
+        // 0.15 hard-error: refuse to start a readiness-check run if the engine
+        // has zero connected agents — verifier-role stages can't run without one.
         const instance = await callJson(`${url}/v1/instance`, token);
         if (instance.body && instance.body.agent_count === 0) {
-            console.error(chalk.red("  Cannot verify — no agents available."));
+            console.error(chalk.red("  Cannot run readiness checks — no agents available."));
             console.error("  Install Claude Code, Codex, Gemini, or another agent CLI, or");
             console.error("  register a custom CLI: `interf agents register <name> --command <cmd>`.");
             process.exit(1);
         }
-        const target = args.target ?? "compiled";
+        const target = args.target ?? "verifiable-context";
         const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/verify-runs`, token, { method: "POST", body: JSON.stringify({ target }) });
         if (status !== 201 && status !== 200) {
-            console.error(chalk.red(`Failed to start verify run for ${args.prepId} (HTTP ${status}).`));
+            console.error(chalk.red(`Failed to start readiness-check run for ${args.prepId} (HTTP ${status}).`));
             if (raw)
                 console.error(raw);
             process.exit(1);

package/dist/cli/commands/web.js

@@ -2,6 +2,7 @@
  * `interf web` — start the engine in the foreground until Ctrl-C.
  *
  *   interf web                # start on default port; hard error if port busy
+ *   interf web start          # start the engine in the background
  *   interf web stop           # send SIGTERM to the running engine
  *   interf web status         # print engine info via the connected URL
  *
@@ -10,11 +11,13 @@
  * connect without a pointer file.
  */
 import chalk from "chalk";
-import { readFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
 import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, buildLocalServiceUrl, } from "../../packages/engine/routes.js";
 import { startLocalService } from "../../packages/engine/server.js";
 import { createNativeLocalServiceRunHandlers } from "../../packages/engine/native-run-handlers.js";
-import { CONNECT_OR_ERROR_HINT, clearConnection, readActiveConnection, } from "../../packages/engine/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, clearConnection, readActiveConnection, writeConnection, } from "../../packages/engine/connection-config.js";
 import { serviceRegistryPath } from "../../packages/engine/instance-paths.js";
 function packageVersionFromManifest() {
     try {
@@ -53,12 +56,6 @@ async function runWebForeground(args) {
         }
         throw error;
     }
-    console.log();
-    console.log(`  Interf engine: ${chalk.bold(service.url)}`);
-    console.log(`  Compiler UI:   ${service.url}/`);
-    console.log(`  Health:        ${service.url}/health`);
-    console.log(chalk.dim("  Press Ctrl-C to stop."));
-    console.log();
     const shutdown = async () => {
         try {
             await service.close();
@@ -68,12 +65,84 @@ async function runWebForeground(args) {
         }
         process.exit(0);
     };
+    console.log();
+    console.log(`  Interf engine: ${chalk.bold(service.url)}`);
+    console.log(`  Interf UI:     ${service.url}/`);
+    console.log(`  Health:        ${service.url}/health`);
+    console.log(chalk.dim("  Press Ctrl-C to stop."));
+    console.log();
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     await new Promise(() => {
         /* block forever; signals trigger shutdown */
     });
 }
+async function isEngineReachable(url) {
+    try {
+        const response = await fetch(`${url}/health`);
+        return response.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForEngine(url, timeoutMs) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        if (await isEngineReachable(url))
+            return true;
+        await new Promise((resolveWait) => setTimeout(resolveWait, 150));
+    }
+    return false;
+}
+function managedWebLogPath(port) {
+    return `${dirname(serviceRegistryPath())}/interf-web-${port}.log`;
+}
+async function runWebStart(args) {
+    const host = args.host ?? LOCAL_SERVICE_DEFAULT_HOST;
+    const port = args.port ?? LOCAL_SERVICE_DEFAULT_PORT;
+    const url = buildLocalServiceUrl({ host, port });
+    if (await isEngineReachable(url)) {
+        writeConnection({ url, auth_token: null });
+        console.log(chalk.green(`Interf engine already running at ${chalk.bold(url)}.`));
+        console.log(`Interf UI: ${url}/`);
+        return;
+    }
+    const binPath = process.argv[1];
+    if (!binPath) {
+        console.error(chalk.red("Cannot locate the Interf CLI entrypoint for managed start."));
+        console.error(`Try running \`interf web\` in a separate terminal instead.`);
+        process.exit(1);
+    }
+    const logPath = args.log ?? managedWebLogPath(port);
+    mkdirSync(dirname(logPath), { recursive: true });
+    const stdoutFd = openSync(logPath, "a");
+    const stderrFd = openSync(logPath, "a");
+    let child;
+    try {
+        child = spawn(process.execPath, [binPath, "web", "--host", host, "--port", String(port)], {
+            detached: true,
+            stdio: ["ignore", stdoutFd, stderrFd],
+            env: process.env,
+        });
+        child.unref();
+    }
+    finally {
+        closeSync(stdoutFd);
+        closeSync(stderrFd);
+    }
+    const ready = await waitForEngine(url, args.timeoutMs ?? 5000);
+    if (!ready) {
+        console.error(chalk.red(`Timed out waiting for Interf engine at ${url}.`));
+        console.error(`Log: ${logPath}`);
+        process.exit(1);
+    }
+    writeConnection({ url, auth_token: null });
+    console.log(chalk.green(`Started Interf engine at ${chalk.bold(url)}.`));
+    console.log(`Interf UI: ${url}/`);
+    console.log(`Log: ${logPath}`);
+    console.log(chalk.dim(`Stop it with \`interf web stop\`.`));
+}
 function findEnginePidByUrl(url) {
     try {
         const raw = readFileSync(serviceRegistryPath(), "utf8");
@@ -196,6 +265,11 @@ export const webCommand = {
     command: "web [subcommand]",
     describe: "Start / stop / inspect the Interf engine",
     builder: (yargs) => yargs
+        .command("start", "Start the engine in the background", (y) => y
+        .option("host", { type: "string", default: LOCAL_SERVICE_DEFAULT_HOST, describe: "Host to bind" })
+        .option("port", { type: "number", default: LOCAL_SERVICE_DEFAULT_PORT, describe: "Port to bind" })
+        .option("timeout-ms", { type: "number", default: 5000, describe: "How long to wait for startup" })
+        .option("log", { type: "string", describe: "Path to write background engine logs" }), runWebStart)
         .command("stop", "Stop the connected engine", (y) => y
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" }), runWebStop)