@interf/compiler 0.22.0 → 0.33.0

package/dist/cli/commands/runtime.js

@@ -0,0 +1,373 @@
+/**
+ * `interf runtime` — start the local service in the foreground until Ctrl-C.
+ *
+ *   interf runtime                # start on default port; hard error if port busy
+ *   interf runtime start          # start the service in the background
+ *   interf runtime stop           # send SIGTERM to the running service
+ *   interf runtime status         # print service info via the connected URL
+ *
+ * Pure server. No reuse / register-with-existing logic. Writes
+ * `~/.interf/connection.json` on startup so subsequent CLI commands can
+ * connect without a pointer file.
+ */
+import chalk from "chalk";
+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/runtime/service/routes.js";
+import { startLocalService } from "../../packages/runtime/service/server.js";
+import { createNativeLocalServiceRunHandlers } from "../../packages/runtime/native-run-handlers.js";
+import { CONNECT_OR_ERROR_HINT, clearConnection, readActiveConnection, writeConnection, } from "../../packages/runtime/connection-config.js";
+import { serviceRegistryPath } from "../../packages/contracts/lib/project-paths.js";
+function packageVersionFromManifest() {
+    try {
+        const url = new URL("../../../package.json", import.meta.url);
+        const raw = readFileSync(url, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPortInUseError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return code === "EADDRINUSE";
+}
+export async function runRuntimeForeground(args) {
+    const host = args.host ?? LOCAL_SERVICE_DEFAULT_HOST;
+    const port = args.port ?? LOCAL_SERVICE_DEFAULT_PORT;
+    let service;
+    try {
+        service = await startLocalService({
+            host,
+            port,
+            packageVersion: packageVersionFromManifest(),
+            handlers: createNativeLocalServiceRunHandlers(),
+            ownerKind: args.appOwned ? "desktop-app" : "headless",
+            ...(args.parentPid ? { ownerPid: args.parentPid } : {}),
+        });
+    }
+    catch (error) {
+        if (isPortInUseError(error)) {
+            console.error(chalk.red(`Error: another Interf local service is already running at ${buildLocalServiceUrl({ host, port })}.`));
+            console.error("Stop it first with `interf runtime stop`.");
+            process.exit(1);
+        }
+        throw error;
+    }
+    const shutdown = async () => {
+        try {
+            await service.close();
+        }
+        catch {
+            // best effort
+        }
+        process.exit(0);
+    };
+    console.log();
+    console.log(`  Interf service: ${chalk.bold(service.url)}${args.appOwned ? chalk.dim(" (app-owned)") : ""}`);
+    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);
+    if (args.appOwned && args.parentPid) {
+        const parentPid = args.parentPid;
+        const monitor = setInterval(() => {
+            try {
+                process.kill(parentPid, 0);
+            }
+            catch {
+                clearInterval(monitor);
+                void shutdown();
+            }
+        }, 1000);
+        monitor.unref();
+    }
+    await new Promise(() => {
+        /* block forever; signals trigger shutdown */
+    });
+}
+async function isServiceReachable(url) {
+    try {
+        const response = await fetch(`${url}/health`);
+        return response.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+async function serviceRequiresAuth(url) {
+    try {
+        const response = await fetch(`${url}/v1/instance`);
+        if (response.status !== 200)
+            return true;
+        const body = await response.json();
+        return body.auth_required === true;
+    }
+    catch {
+        return true;
+    }
+}
+function activeConnectionForUrl(url) {
+    const conn = readActiveConnection();
+    if (!conn)
+        return null;
+    return conn.url.replace(/\/+$/, "") === url.replace(/\/+$/, "")
+        ? { url: conn.url.replace(/\/+$/, ""), auth_token: conn.auth_token }
+        : null;
+}
+async function waitForService(url, timeoutMs) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        if (await isServiceReachable(url))
+            return true;
+        await new Promise((resolveWait) => setTimeout(resolveWait, 150));
+    }
+    return false;
+}
+function managedRuntimeLogPath(port) {
+    return `${dirname(serviceRegistryPath())}/interf-runtime-${port}.log`;
+}
+export async function runRuntimeStart(args) {
+    const host = args.host ?? LOCAL_SERVICE_DEFAULT_HOST;
+    const port = args.port ?? LOCAL_SERVICE_DEFAULT_PORT;
+    const url = buildLocalServiceUrl({ host, port });
+    if (await isServiceReachable(url)) {
+        const existing = activeConnectionForUrl(url);
+        if (existing) {
+            writeConnection(existing);
+        }
+        else if (await serviceRequiresAuth(url)) {
+            console.error(chalk.red(`Interf local service is already running at ${chalk.bold(url)}, but no bearer token is available.`));
+            console.error("Use the existing connection.json, pass --token, or restart the service from this CLI.");
+            process.exit(1);
+        }
+        else {
+            writeConnection({ url, auth_token: null });
+        }
+        console.log(chalk.green(`Interf local service is already running at ${chalk.bold(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 runtime` in a separate terminal instead.");
+        process.exit(1);
+    }
+    const logPath = args.log ?? managedRuntimeLogPath(port);
+    mkdirSync(dirname(logPath), { recursive: true });
+    const stdoutFd = openSync(logPath, "a");
+    const stderrFd = openSync(logPath, "a");
+    let child;
+    try {
+        child = spawn(process.execPath, [binPath, "runtime", "--host", host, "--port", String(port)], {
+            detached: true,
+            stdio: ["ignore", stdoutFd, stderrFd],
+            env: process.env,
+        });
+        child.unref();
+    }
+    finally {
+        closeSync(stdoutFd);
+        closeSync(stderrFd);
+    }
+    const ready = await waitForService(url, args.timeoutMs ?? 5000);
+    if (!ready) {
+        console.error(chalk.red(`Timed out waiting for Interf local service at ${url}.`));
+        console.error(`Log: ${logPath}`);
+        process.exit(1);
+    }
+    const conn = activeConnectionForUrl(url);
+    if (conn) {
+        writeConnection(conn);
+    }
+    else if (await serviceRequiresAuth(url)) {
+        console.error(chalk.red(`Interf local service started at ${url}, but no bearer token was written to connection.json.`));
+        console.error(`Log: ${logPath}`);
+        process.exit(1);
+    }
+    else {
+        writeConnection({ url, auth_token: null });
+    }
+    console.log(chalk.green(`Started Interf local service at ${chalk.bold(url)}.`));
+    console.log(`Log: ${logPath}`);
+    console.log(chalk.dim("Stop it with `interf runtime stop`."));
+}
+function findServicePidByUrl(url) {
+    try {
+        const raw = readFileSync(serviceRegistryPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        const entry = parsed.services?.find((s) => s.url === url);
+        return entry?.pid ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    try {
+        // Signal 0 is a no-op probe — succeeds if the PID exists and we can
+        // signal it; throws ESRCH otherwise.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan ~/.interf/services.json for engines whose PID is still alive.
+ * Used by `interf runtime stop` when ~/.interf/connection.json is missing
+ * — the registry tells us which local service processes are actually running
+ * regardless of which one the wizard last connected to.
+ */
+function listLiveServicesFromRegistry() {
+    try {
+        const raw = readFileSync(serviceRegistryPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return (parsed.services ?? []).filter((entry) => typeof entry.pid === "number" && isPidAlive(entry.pid));
+    }
+    catch {
+        return [];
+    }
+}
+export async function runRuntimeStop(args) {
+    // Resolution order: explicit --url override → active connection.json
+    // → fall back to scanning services.json for any live service. The
+    // last fallback recovers from the case where connection.json was
+    // cleared while a service was still running (e.g. another `interf
+    // runtime` attempt failed mid-startup, or `interf logout` was run while
+    // the service kept going).
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    let urlToStop = conn ? conn.url.replace(/\/+$/, "") : null;
+    let pidToStop = urlToStop ? findServicePidByUrl(urlToStop) : null;
+    if (!pidToStop) {
+        const liveServices = listLiveServicesFromRegistry();
+        if (liveServices.length === 0) {
+            console.error("No live Interf local service to stop.");
+            console.error("Checked ~/.interf/connection.json and ~/.interf/services.json — neither pointed at a running process.");
+            process.exit(1);
+        }
+        if (liveServices.length > 1 && !urlToStop) {
+            console.error(`Multiple live Interf local services registered. Pick one with --url:`);
+            for (const entry of liveServices) {
+                console.error(`  ${entry.url} (pid ${entry.pid})`);
+            }
+            process.exit(1);
+        }
+        const target = urlToStop
+            ? liveServices.find((entry) => entry.url === urlToStop)
+            : liveServices[0];
+        if (!target) {
+            console.error(`No live local service matches ${urlToStop ?? "the active connection"} in services.json.`);
+            process.exit(1);
+        }
+        urlToStop = target.url;
+        pidToStop = target.pid;
+        if (!conn) {
+            console.log(chalk.dim(`  No active connection.json — recovering service pid ${pidToStop} from services.json.`));
+        }
+    }
+    try {
+        process.kill(pidToStop, "SIGTERM");
+        console.log(chalk.green(`Sent SIGTERM to service pid ${pidToStop} (${urlToStop}).`));
+        if (conn)
+            clearConnection();
+    }
+    catch (error) {
+        console.error(`Failed to stop service pid ${pidToStop}: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
+export async function runRuntimeStatus(args) {
+    const existingForUrl = args.url ? activeConnectionForUrl(args.url) : null;
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token ?? existingForUrl?.auth_token ?? null,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    const url = conn.url.replace(/\/+$/, "");
+    try {
+        const headers = new Headers();
+        if (conn.auth_token)
+            headers.set("authorization", `Bearer ${conn.auth_token}`);
+        const response = await fetch(`${url}/v1/instance`, { headers });
+        const raw = await response.text();
+        if (response.status !== 200) {
+            console.error(chalk.red(`Local service status request failed (HTTP ${response.status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        if (args.requireOwnerKind || args.requireOwnerPid) {
+            const parsed = JSON.parse(raw);
+            if (args.requireOwnerKind && parsed.owner_kind !== args.requireOwnerKind) {
+                console.error(chalk.red(`Local service owner mismatch: expected ${args.requireOwnerKind}, got ${String(parsed.owner_kind ?? "unknown")}.`));
+                process.exit(1);
+            }
+            if (args.requireOwnerPid && parsed.owner_pid !== args.requireOwnerPid) {
+                console.error(chalk.red(`Local service owner pid mismatch: expected ${args.requireOwnerPid}, got ${String(parsed.owner_pid ?? "unknown")}.`));
+                process.exit(1);
+            }
+        }
+        console.log(raw);
+    }
+    catch (error) {
+        console.error(chalk.red(`Local service ${url} unreachable: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+}
+export const runtimeCommand = {
+    command: "runtime [subcommand]",
+    describe: "Start / stop / inspect the Interf local service",
+    builder: (yargs) => yargs
+        .command("start", "Start the local service 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 service logs" }), runRuntimeStart)
+        .command("stop", "Stop the connected local service", (y) => y
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" }), runRuntimeStop)
+        .command("status", "Show local service status via the connected URL", (y) => y
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .option("require-owner-kind", {
+        choices: ["desktop-app", "headless"],
+        describe: "Exit non-zero unless the connected service has this owner kind",
+        hidden: true,
+    })
+        .option("require-owner-pid", {
+        type: "number",
+        describe: "Exit non-zero unless the connected service was started for this owner PID",
+        hidden: true,
+    }), runRuntimeStatus)
+        .command("$0", "Start the local service in the foreground (default)", (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("app-owned", {
+        type: "boolean",
+        default: false,
+        describe: "Run as a foreground service child process",
+        hidden: true,
+    })
+        .option("parent-pid", {
+        type: "number",
+        describe: "Parent process pid for app-owned service shutdown",
+        hidden: true,
+    }), runRuntimeForeground)
+        .strict(),
+    handler: () => {
+        /* yargs subcommand handlers do the work */
+    },
+};

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

@@ -2,6 +2,7 @@ import type { CommandModule } from "yargs";
 interface StatusArgs {
     url?: string;
     token?: string;
+    debug?: boolean;
 }
 export declare const statusCommand: CommandModule<unknown, StatusArgs>;
 export {};

package/dist/cli/commands/status.js

@@ -1,8 +1,9 @@
 /**
- * `interf status` — print connection state + preparation summary.
+ * `interf status` — print connection state + Project summary.
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { InstanceResourceSchema, ProjectListResponseSchema, } from "../../packages/runtime/schemas/index.js";
 async function callJson(url, token) {
     const headers = new Headers();
     if (token)
@@ -27,10 +28,11 @@ async function callJson(url, token) {
 }
 export const statusCommand = {
     command: "status",
-    describe: "Show connection + preparation summary",
+    describe: "Show connection + Project summary",
     builder: (yargs) => yargs
         .option("url", { type: "string", describe: "Override the active connection URL" })
-        .option("token", { type: "string", describe: "Override the active bearer token" }),
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .option("debug", { type: "boolean", default: false, describe: "Show debug metadata such as package version" }),
     handler: async (args) => {
         const conn = readActiveConnection({
             urlOverride: args.url,
@@ -48,31 +50,40 @@ export const statusCommand = {
             console.error(CONNECT_OR_ERROR_HINT);
             process.exit(1);
         }
+        const instanceResource = InstanceResourceSchema.safeParse(instance.body);
+        if (!instanceResource.success) {
+            console.error(chalk.red("Connected service returned an invalid instance resource."));
+            process.exit(1);
+        }
         console.log();
-        console.log(chalk.bold("  Interf engine"));
+        console.log(chalk.bold("  Interf local service"));
         console.log(`  URL:      ${url}`);
-        if (instance.body?.pid)
-            console.log(`  PID:      ${instance.body.pid}`);
-        if (instance.body?.package_version)
-            console.log(`  Version:  ${instance.body.package_version}`);
-        if (instance.body?.uptime_seconds !== undefined) {
-            console.log(`  Uptime:   ${instance.body.uptime_seconds}s`);
+        if (instanceResource.data.pid)
+            console.log(`  PID:      ${instanceResource.data.pid}`);
+        if (args.debug && instanceResource.data.package_version) {
+            console.log(`  Version:  ${instanceResource.data.package_version}`);
+        }
+        if (instanceResource.data.uptime_seconds !== undefined) {
+            console.log(`  Uptime:   ${instanceResource.data.uptime_seconds}s`);
+        }
+        console.log(`  Auth:     ${instanceResource.data.auth_required ? "required (token in connection.json)" : "open (explicit dev/test mode)"}`);
+        const projects = await callJson(`${url}/v1/projects`, token);
+        const parsedProjects = ProjectListResponseSchema.safeParse(projects.body);
+        if (!parsedProjects.success) {
+            console.error(chalk.red("Connected service returned an invalid Project list."));
+            process.exit(1);
         }
-        console.log(`  Auth:     ${instance.body?.auth_required ? "required (token in connection.json)" : "open (loopback)"}`);
-        const preps = await callJson(`${url}/v1/preparations`, token);
-        const list = preps.body?.preparations ?? [];
+        const list = parsedProjects.data.projects;
         console.log();
-        console.log(chalk.bold(`  Preparations (${list.length})`));
+        console.log(chalk.bold(`  Projects (${list.length})`));
         if (list.length === 0) {
-            console.log(chalk.dim("  No preparations yet. `interf prep create <id> --source <path>`."));
+            console.log(chalk.dim("  No Projects yet. `interf project create <id> --source <path>`."));
         }
         else {
-            for (const prep of list) {
-                const readiness = prep.readiness?.status ?? "—";
-                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}`));
+            for (const project of list) {
+                const buildPlan = project.build_plan_id ?? "no Plan";
+                console.log(`  ${chalk.bold(project.id)} ${chalk.dim(`(${buildPlan})`)}`);
+                console.log(chalk.dim(`    source: ${project.source.locator}`));
             }
         }
         console.log();

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

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const tracesCommand: CommandModule;

package/dist/cli/commands/traces.js

@@ -0,0 +1,125 @@
+/**
+ * `interf traces` — inspect Context Graph traces on the connected instance.
+ *
+ *   interf traces ls --project <id>
+ *   interf traces show <trace-kind> --project <id>
+ */
+import chalk from "chalk";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { TracesSchema, } from "../../packages/contracts/lib/project-schema.js";
+import { projectSubresourcePath } from "../../packages/runtime/service/routes.js";
+function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
+}
+async function callJson(url, token) {
+    const headers = new Headers();
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    const response = await fetch(url, { headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = null;
+        }
+    }
+    return { status: response.status, body, raw };
+}
+function tracesUrl(baseUrl, projectId) {
+    return `${baseUrl}${projectSubresourcePath(projectId, "traces")}`;
+}
+async function readTraces(baseUrl, token, projectId) {
+    const { status, body, raw } = await callJson(tracesUrl(baseUrl, projectId), token);
+    if (status !== 200 || !body) {
+        console.error(chalk.red(`Failed to read Context Graph traces (HTTP ${status}).`));
+        if (raw)
+            console.error(raw);
+        process.exit(1);
+    }
+    const parsed = TracesSchema.safeParse(body);
+    if (!parsed.success) {
+        console.error(chalk.red("Failed to parse Context Graph traces."));
+        process.exit(1);
+    }
+    return parsed.data;
+}
+function renderTrace(trace) {
+    const marker = trace.passed === false ? chalk.red("fail") : chalk.green("pass");
+    const value = trace.count === undefined
+        ? ""
+        : trace.total === undefined
+            ? chalk.dim(` ${trace.count}`)
+            : chalk.dim(` ${trace.count}/${trace.total}`);
+    console.log(`  ${marker} ${chalk.bold(trace.kind)}${value}`);
+    console.log(chalk.dim(`    ${trace.label}`));
+    if (trace.detail)
+        console.log(chalk.dim(`    ${trace.detail}`));
+}
+export const tracesCommand = {
+    command: "traces <subcommand>",
+    describe: "Inspect Context Graph traces for a Project",
+    builder: (yargs) => yargs
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .option("project", { type: "string", demandOption: true, describe: "Project id" })
+        .command("ls", "List Context Graph traces for a Project", (y) => y, async (args) => {
+        const { url, token } = resolveConnection(args);
+        const traces = await readTraces(url, token, args.project);
+        const items = traces.items ?? [];
+        console.log();
+        console.log(chalk.bold(`  ${traces.project_id} / ${traces.graph_id}`));
+        console.log(chalk.dim(`    files: ${traces.files_processed}/${traces.files_total}`));
+        console.log(chalk.dim(`    checks: ${traces.checks_passed}/${traces.checks_total}`));
+        console.log(chalk.dim(`    ready: ${traces.ready ? "yes" : "no"}`));
+        if (items.length === 0) {
+            console.log(chalk.dim("    No trace items."));
+        }
+        else {
+            console.log();
+            for (const trace of items)
+                renderTrace(trace);
+        }
+        console.log();
+    })
+        .command("show <traceKind>", "Show one Context Graph trace item", (y) => y
+        .positional("traceKind", {
+        type: "string",
+        demandOption: true,
+        describe: "Trace kind, for example files-processed or checks",
+    })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw trace item JSON",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const traces = await readTraces(url, token, args.project);
+        const trace = (traces.items ?? []).find((item) => item.kind === args.traceKind);
+        if (!trace) {
+            console.error(chalk.red(`Trace ${args.traceKind} was not found for Project ${args.project}.`));
+            process.exit(1);
+        }
+        if (args.json) {
+            console.log(JSON.stringify(trace, null, 2));
+            return;
+        }
+        console.log();
+        renderTrace(trace);
+        console.log();
+    })
+        .demandCommand(1, "Choose a traces subcommand."),
+    handler: () => {
+        // Subcommands own all behavior.
+    },
+};