@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/service/server-api-files.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, extname, normalize, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeHeaders } from "./server-helpers.js";
+export function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+}
+function contentType(filePath) {
+    switch (extname(filePath)) {
+        case ".html":
+            return "text/html; charset=utf-8";
+        case ".js":
+            return "text/javascript; charset=utf-8";
+        case ".css":
+            return "text/css; charset=utf-8";
+        case ".json":
+            return "application/json; charset=utf-8";
+        case ".svg":
+            return "image/svg+xml";
+        case ".png":
+            return "image/png";
+        case ".ico":
+            return "image/x-icon";
+        case ".txt":
+            return "text/plain; charset=utf-8";
+        case ".md":
+            return "text/markdown; charset=utf-8";
+        case ".yml":
+        case ".yaml":
+            return "application/yaml; charset=utf-8";
+        case ".map":
+            return "application/json; charset=utf-8";
+        case ".webmanifest":
+            return "application/manifest+json; charset=utf-8";
+        case ".woff2":
+            return "font/woff2";
+        default:
+            return "application/octet-stream";
+    }
+}
+export function safeApiFilePath(root, relativePath) {
+    const normalized = normalize(relativePath).replace(/^(\.\.(?:\/|\\|$))+/, "");
+    const absolute = resolve(root, normalized);
+    const resolvedRoot = resolve(root);
+    if (absolute !== resolvedRoot && !absolute.startsWith(`${resolvedRoot}${sep}`)) {
+        return null;
+    }
+    return absolute;
+}
+export function sendApiFile(res, filePath) {
+    if (!existsSync(filePath))
+        return false;
+    try {
+        if (!statSync(filePath).isFile())
+            return false;
+        const type = contentType(filePath);
+        const headers = { "content-type": type };
+        if (type.startsWith("text/html")) {
+            headers["cache-control"] = "no-store";
+        }
+        writeHeaders(res, 200, headers);
+        res.end(readFileSync(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reject any path that contains `..` or absolute segments. These helpers are
+ * only for authenticated `/v1/.../files/...` API resources, not for serving
+ * the Desktop renderer.
+ */
+export function isTraversalRelativePath(relPath) {
+    if (relPath.length === 0)
+        return true;
+    const segments = relPath.split(/[\\/]+/);
+    for (const segment of segments) {
+        if (segment === ".." || segment === "")
+            return true;
+    }
+    if (relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath))
+        return true;
+    return false;
+}

package/dist/packages/runtime/service/server-app-boot.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function sendDesktopAppBoot(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime): boolean;
+export declare function sendServiceNotFound(res: ServerResponse): void;

package/dist/packages/runtime/service/server-app-boot.js

@@ -0,0 +1,46 @@
+import { buildLocalServiceUrl } from "./routes.js";
+import { parseRequestUrl, sendText, writeHeaders } from "./server-helpers.js";
+function escapedJsonForHtml(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+export function sendDesktopAppBoot(req, res, runtime) {
+    const url = parseRequestUrl(req);
+    if (url.pathname !== "/")
+        return false;
+    const method = req.method ?? "GET";
+    if (method !== "GET" && method !== "HEAD")
+        return false;
+    const boot = {
+        kind: "interf-app-boot",
+        version: 1,
+        service_url: buildLocalServiceUrl({ host: runtime.host, port: runtime.port }),
+        auth_required: Boolean(runtime.authToken),
+        auth_token: runtime.authToken,
+    };
+    const json = escapedJsonForHtml(boot);
+    writeHeaders(res, 200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    if (method === "HEAD") {
+        res.end();
+        return true;
+    }
+    res.end(`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Interf local service</title>
+  <script id="interf-app-boot" type="application/json">${json}</script>
+</head>
+<body>
+  <p>Interf local service is running.</p>
+</body>
+</html>
+`);
+    return true;
+}
+export function sendServiceNotFound(res) {
+    sendText(res, 404, "Not found. Interf local service is running.\n");
+}

package/dist/packages/runtime/service/server-guards.d.ts

@@ -0,0 +1,63 @@
+import type { IncomingMessage } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+import { type ValidatedAccessToken } from "../auth/jwt-validator.js";
+/** Generate a fresh per-instance bearer token. */
+export declare function createLocalServiceAuthToken(): string;
+export interface AllowedOrigins {
+    hostnames: string[];
+    ports: number[];
+    hostUrls: string[];
+}
+/**
+ * Build the per-instance CORS / Origin allowlist. Only the loopback
+ * hostnames bound to the active port count as same-origin. `null` and
+ * absent Origin are also accepted (Electron / file:// / CLI tools).
+ */
+export declare function buildAllowedOrigins(host: string, port: number): AllowedOrigins;
+export declare function originHeaderValue(req: IncomingMessage): string | null;
+export declare function isOriginAllowed(origin: string | null, allowed: AllowedOrigins): boolean;
+export declare function corsHeadersFor(origin: string | null, allowed: AllowedOrigins): Record<string, string>;
+export declare function isMutatingMethod(method: string | undefined): boolean;
+/**
+ * Return whether a request is one of the tokenless local discovery reads.
+ *
+ * The body of these routes must stay small and must not include Project,
+ * Source, Context Graph, trace, or evidence state.
+ */
+export declare function isPublicDiscoveryRead(method: string | undefined, path: string): boolean;
+/**
+ * Return whether the local-service dispatcher must authenticate this request.
+ *
+ * Product mode protects every non-discovery `/v1` route, including read-only
+ * Project, Source, Context Graph, trace, evidence, account, run, and action
+ * resources. Mutating routes are always protected.
+ */
+export declare function requiresLocalServiceAuthorization(method: string | undefined, path: string): boolean;
+/**
+ * Validate the bearer token on a protected local request. Returns true when:
+ * - the runtime has no token (test harness mode), or
+ * - the request includes `Authorization: Bearer <token>` matching the runtime token.
+ */
+export declare function isAuthorizedLocalBearer(req: IncomingMessage, runtime: LocalServiceRuntime): boolean;
+/** @deprecated use `isAuthorizedLocalBearer`. */
+export declare const isAuthorizedMutation: typeof isAuthorizedLocalBearer;
+export type BearerJwtValidationResult = {
+    ok: true;
+    account: ValidatedAccessToken;
+} | {
+    ok: false;
+    reason: "missing" | "malformed" | "invalid";
+    message?: string;
+};
+/**
+ * Validate a `Authorization: Bearer <jwt>` header against the WorkOS JWKS.
+ *
+ * Used by the cloud engine binding (`authMode: "jwt"`). The loopback engine
+ * stays on `isAuthorizedMutation` — the loopback bind + CORS allowlist + hex
+ * bearer are sufficient there, and avoiding the JWKS HTTP fetch keeps the
+ * local dev loop snappy.
+ *
+ * On `ok: true`, the validated claims are returned so the dispatcher can
+ * attach them to the request for downstream handlers.
+ */
+export declare function validateBearerJwt(req: IncomingMessage): Promise<BearerJwtValidationResult>;

package/dist/packages/runtime/service/server-guards.js

@@ -0,0 +1,181 @@
+import { randomBytes } from "node:crypto";
+import { LOCAL_SERVICE_LOOPBACK_HOSTS } from "../schemas/index.js";
+import { JwtValidationError, validateAccessToken, } from "../auth/jwt-validator.js";
+/** HTTP methods that require an authenticated bearer token + Origin guard. */
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** Read-only probes agents may use before authorization. */
+const PUBLIC_DISCOVERY_GET_PATHS = new Set(["/health", "/v1", "/v1/instance", "/v1/openapi.json"]);
+/** Generate a fresh per-instance bearer token. */
+export function createLocalServiceAuthToken() {
+    return randomBytes(32).toString("hex");
+}
+/**
+ * Build the per-instance CORS / Origin allowlist. Only the loopback
+ * hostnames bound to the active port count as same-origin. `null` and
+ * absent Origin are also accepted (Electron / file:// / CLI tools).
+ */
+export function buildAllowedOrigins(host, port) {
+    const hostnames = Array.from(new Set([host, ...LOCAL_SERVICE_LOOPBACK_HOSTS]));
+    // Dev mode: also allow the Next.js dev ports so the UI dev server can
+    // hit the engine cross-origin. Defaults to 3000,3001 — covers the
+    // standard `desktop:renderer:dev` + a previous A/B worktree. Override with the
+    // `INTERF_DEV_ORIGINS_PORTS` env var (comma-separated).
+    const devPortsRaw = process.env.INTERF_DEV_ORIGINS_PORTS ?? "3000,3001";
+    const devPorts = devPortsRaw
+        .split(",")
+        .map((raw) => Number.parseInt(raw.trim(), 10))
+        .filter((value) => Number.isInteger(value) && value > 0 && value !== port);
+    const ports = Array.from(new Set([port, ...devPorts]));
+    return {
+        hostnames,
+        ports,
+        hostUrls: hostnames.map((hostname) => {
+            const wrapped = hostname.includes(":") ? `[${hostname}]` : hostname;
+            return `http://${wrapped}:${port}`;
+        }),
+    };
+}
+export function originHeaderValue(req) {
+    const raw = req.headers.origin;
+    if (raw === undefined)
+        return null;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function authorizationHeaderValue(req) {
+    const raw = req.headers.authorization;
+    if (!raw)
+        return null;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function isOriginAllowed(origin, allowed) {
+    if (origin === null)
+        return true; // CLI / Node fetch / native app — no Origin sent.
+    if (origin === "null")
+        return true; // Electron / sandboxed / file:// page.
+    if (origin === "zero://app" || origin === "zero://inline")
+        return true;
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return false;
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+    if (!allowed.hostnames.includes(hostname))
+        return false;
+    // Default ports (no explicit port in URL) cannot be the local service.
+    if (!parsed.port)
+        return false;
+    const portNumber = Number.parseInt(parsed.port, 10);
+    if (!Number.isInteger(portNumber))
+        return false;
+    return allowed.ports.includes(portNumber);
+}
+export function corsHeadersFor(origin, allowed) {
+    if (!isOriginAllowed(origin, allowed))
+        return { vary: "origin" };
+    return {
+        "access-control-allow-origin": origin ?? allowed.hostUrls[0] ?? "",
+        "access-control-allow-credentials": "false",
+        "access-control-allow-methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "access-control-allow-headers": "content-type, authorization, x-interf-idempotency-key",
+        vary: "origin",
+    };
+}
+export function isMutatingMethod(method) {
+    return method !== undefined && MUTATING_METHODS.has(method.toUpperCase());
+}
+/**
+ * Return whether a request is one of the tokenless local discovery reads.
+ *
+ * The body of these routes must stay small and must not include Project,
+ * Source, Context Graph, trace, or evidence state.
+ */
+export function isPublicDiscoveryRead(method, path) {
+    return method?.toUpperCase() === "GET" && PUBLIC_DISCOVERY_GET_PATHS.has(path);
+}
+/**
+ * Return whether the local-service dispatcher must authenticate this request.
+ *
+ * Product mode protects every non-discovery `/v1` route, including read-only
+ * Project, Source, Context Graph, trace, evidence, account, run, and action
+ * resources. Mutating routes are always protected.
+ */
+export function requiresLocalServiceAuthorization(method, path) {
+    if (isMutatingMethod(method))
+        return true;
+    if (isPublicDiscoveryRead(method, path))
+        return false;
+    return method?.toUpperCase() === "GET" && path.startsWith("/v1");
+}
+/**
+ * Validate the bearer token on a protected local request. Returns true when:
+ * - the runtime has no token (test harness mode), or
+ * - the request includes `Authorization: Bearer <token>` matching the runtime token.
+ */
+export function isAuthorizedLocalBearer(req, runtime) {
+    if (!runtime.authToken)
+        return true;
+    const authorization = authorizationHeaderValue(req);
+    if (!authorization)
+        return false;
+    const match = /^Bearer\s+([A-Za-z0-9._\-]+)$/.exec(authorization);
+    if (!match)
+        return false;
+    const presented = match[1];
+    if (!presented || presented.length !== runtime.authToken.length)
+        return false;
+    // Constant-time compare to avoid timing oracles.
+    let mismatch = 0;
+    for (let index = 0; index < runtime.authToken.length; index += 1) {
+        mismatch |= presented.charCodeAt(index) ^ runtime.authToken.charCodeAt(index);
+    }
+    return mismatch === 0;
+}
+/** @deprecated use `isAuthorizedLocalBearer`. */
+export const isAuthorizedMutation = isAuthorizedLocalBearer;
+/**
+ * Validate a `Authorization: Bearer <jwt>` header against the WorkOS JWKS.
+ *
+ * Used by the cloud engine binding (`authMode: "jwt"`). The loopback engine
+ * stays on `isAuthorizedMutation` — the loopback bind + CORS allowlist + hex
+ * bearer are sufficient there, and avoiding the JWKS HTTP fetch keeps the
+ * local dev loop snappy.
+ *
+ * On `ok: true`, the validated claims are returned so the dispatcher can
+ * attach them to the request for downstream handlers.
+ */
+export async function validateBearerJwt(req) {
+    const authorization = authorizationHeaderValue(req);
+    if (!authorization)
+        return { ok: false, reason: "missing" };
+    const match = /^Bearer\s+(.+)$/.exec(authorization);
+    if (!match || !match[1])
+        return { ok: false, reason: "malformed" };
+    const token = match[1].trim();
+    if (token.length === 0)
+        return { ok: false, reason: "malformed" };
+    try {
+        const account = await validateAccessToken(token);
+        return { ok: true, account };
+    }
+    catch (error) {
+        const message = error instanceof JwtValidationError
+            ? error.message
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return { ok: false, reason: "invalid", message };
+    }
+}

package/dist/packages/runtime/service/server-helpers.d.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Per-request response context. Carries the precomputed CORS headers so
+ * every helper call echoes the same allowlisted Origin.
+ *
+ * Default state is `NO_ORIGIN_RESPONSE_CONTEXT` — only `vary: origin`
+ * is emitted, no `access-control-allow-origin`, so a browser blocks the
+ * cross-origin response. The entry-point handler swaps in a context with
+ * `access-control-allow-origin` once it has validated the Origin header.
+ */
+export interface ResponseContext {
+    cors: Record<string, string>;
+}
+export declare const NO_ORIGIN_RESPONSE_CONTEXT: ResponseContext;
+export declare function attachResponseContext(res: ServerResponse, ctx: ResponseContext): void;
+export declare function writeHeaders(res: ServerResponse, statusCode: number, contextOrHeaders?: ResponseContext | Record<string, string>, headers?: Record<string, string>): void;
+export declare function sendJson(res: ServerResponse, statusCode: number, contextOrValue: ResponseContext | unknown, maybeValue?: unknown): void;
+export declare function sendText(res: ServerResponse, statusCode: number, contextOrValue: ResponseContext | string, maybeValue?: string): void;
+export declare function sendError(res: ServerResponse, statusCode: number, contextOrMessage: ResponseContext | string, maybeMessage?: string): void;
+/**
+ * Route any thrown error to its proper response. EntitlementError gets its
+ * own status (402) and propagates `upgrade_hint` so clients can render an
+ * upgrade CTA. Everything else becomes a 400 with the message body.
+ */
+export declare function sendErrorResponse(res: ServerResponse, error: unknown, fallbackStatus?: number): void;
+export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
+export declare function parseRequestUrl(req: IncomingMessage): URL;
+/**
+ * Decode a single percent-encoded path segment, or send a structured 400 and
+ * return `null`. `decodeURIComponent` throws a `URIError` on malformed input
+ * (e.g. a truncated escape like `%E0%A4%A`); left unguarded that crashes the
+ * handler into an uncaught 500. Routing every guarded call site through this
+ * helper keeps the decode semantics and the 400 message single-sourced.
+ *
+ * `label` names the id in the error message, e.g. `"Run id"` ->
+ * `"Run id is not valid URI-encoded UTF-8."`.
+ */
+export declare function decodeOr400(res: ServerResponse, raw: string, label: string): string | null;

package/dist/packages/runtime/service/server-helpers.js

@@ -0,0 +1,108 @@
+import { LocalServiceErrorSchema } from "../schemas/index.js";
+import { EntitlementError } from "../entitlement-guard.js";
+export const NO_ORIGIN_RESPONSE_CONTEXT = { cors: { vary: "origin" } };
+/** Stash slot on the response object that holds the per-request CORS headers. */
+const RESPONSE_CONTEXT_KEY = Symbol.for("interf.localService.responseContext");
+export function attachResponseContext(res, ctx) {
+    res[RESPONSE_CONTEXT_KEY] = ctx;
+}
+function activeResponseContext(res) {
+    const ctx = res[RESPONSE_CONTEXT_KEY];
+    return ctx ?? NO_ORIGIN_RESPONSE_CONTEXT;
+}
+export function writeHeaders(res, statusCode, contextOrHeaders, headers = {}) {
+    // Compatibility shim while call sites migrate. Older callers pass a
+    // plain headers record as the third argument; new callers thread a
+    // `ResponseContext`. When neither is supplied (or only headers are),
+    // we read the per-request context the entry-point handler stashed on
+    // the response.
+    const isContext = contextOrHeaders !== undefined && "cors" in contextOrHeaders;
+    const context = isContext ? contextOrHeaders : activeResponseContext(res);
+    const extraHeaders = isContext ? headers : (contextOrHeaders ?? {});
+    res.writeHead(statusCode, {
+        ...context.cors,
+        ...extraHeaders,
+    });
+}
+export function sendJson(res, statusCode, contextOrValue, maybeValue) {
+    const usingContext = contextOrValue !== null
+        && typeof contextOrValue === "object"
+        && "cors" in contextOrValue
+        && maybeValue !== undefined;
+    const context = usingContext ? contextOrValue : activeResponseContext(res);
+    const value = usingContext ? maybeValue : contextOrValue;
+    writeHeaders(res, statusCode, context, {
+        "content-type": "application/json; charset=utf-8",
+    });
+    res.end(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function sendText(res, statusCode, contextOrValue, maybeValue) {
+    const usingContext = typeof contextOrValue === "object" && contextOrValue !== null && "cors" in contextOrValue;
+    const context = usingContext ? contextOrValue : activeResponseContext(res);
+    const value = usingContext ? (maybeValue ?? "") : contextOrValue;
+    writeHeaders(res, statusCode, context, {
+        "content-type": "text/plain; charset=utf-8",
+    });
+    res.end(value);
+}
+export function sendError(res, statusCode, contextOrMessage, maybeMessage) {
+    const usingContext = typeof contextOrMessage === "object" && contextOrMessage !== null && "cors" in contextOrMessage;
+    const context = usingContext ? contextOrMessage : activeResponseContext(res);
+    const message = usingContext ? (maybeMessage ?? "") : contextOrMessage;
+    sendJson(res, statusCode, context, LocalServiceErrorSchema.parse({
+        error: {
+            message,
+        },
+    }));
+}
+/**
+ * Route any thrown error to its proper response. EntitlementError gets its
+ * own status (402) and propagates `upgrade_hint` so clients can render an
+ * upgrade CTA. Everything else becomes a 400 with the message body.
+ */
+export function sendErrorResponse(res, error, fallbackStatus = 400) {
+    if (error instanceof EntitlementError) {
+        sendJson(res, error.httpStatus, LocalServiceErrorSchema.parse({
+            error: {
+                message: error.message,
+                code: "entitlement-required",
+                upgrade_hint: error.upgradeHint,
+            },
+        }));
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    sendError(res, fallbackStatus, message);
+}
+export async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw)
+        return {};
+    return JSON.parse(raw);
+}
+export function parseRequestUrl(req) {
+    return new URL(req.url ?? "/", "http://127.0.0.1");
+}
+/**
+ * Decode a single percent-encoded path segment, or send a structured 400 and
+ * return `null`. `decodeURIComponent` throws a `URIError` on malformed input
+ * (e.g. a truncated escape like `%E0%A4%A`); left unguarded that crashes the
+ * handler into an uncaught 500. Routing every guarded call site through this
+ * helper keeps the decode semantics and the 400 message single-sourced.
+ *
+ * `label` names the id in the error message, e.g. `"Run id"` ->
+ * `"Run id is not valid URI-encoded UTF-8."`.
+ */
+export function decodeOr400(res, raw, label) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        sendError(res, 400, `${label} is not valid URI-encoded UTF-8.`);
+        return null;
+    }
+}

package/dist/packages/runtime/service/server-instance-helpers.d.ts

@@ -0,0 +1,30 @@
+import type { BuildRunResource, LocalJobRunResource, RunObservabilityResource, VerifyRunResource } from "../schemas/index.js";
+import type { LocalServiceRuntime } from "../runtime.js";
+type InstanceBuildPlanResource = ReturnType<LocalServiceRuntime["listBuildPlans"]>[number];
+export declare function listInstanceRuns(runtime: LocalServiceRuntime): RunObservabilityResource[];
+export declare function findInstanceRun(runtime: LocalServiceRuntime, runId: string): RunObservabilityResource | null;
+export declare function findInstanceJob(runtime: LocalServiceRuntime, runId: string): {
+    job: LocalJobRunResource;
+    projectDataDir: string;
+} | null;
+export declare function findInstanceBuildRun(runtime: LocalServiceRuntime, runId: string): {
+    run: BuildRunResource;
+    projectDataDir: string;
+} | null;
+export declare function findInstanceVerifyRun(runtime: LocalServiceRuntime, runId: string): {
+    run: VerifyRunResource;
+    projectDataDir: string;
+} | null;
+export declare function listInstanceBuildPlans(runtime: LocalServiceRuntime): InstanceBuildPlanResource[];
+export declare function findInstanceBuildPlan(runtime: LocalServiceRuntime, buildPlanId: string): InstanceBuildPlanResource | null;
+export declare function listInstanceBuildPlanRuns(runtime: LocalServiceRuntime, buildPlanId: string): RunObservabilityResource[];
+/**
+ * Resolve the on-disk root path for a Build Plan id. Used by the
+ * `/v1/build-plans/<id>/files/<relpath>` route. Resolution order matches
+ * the runtime: project-draft (if a project id is supplied) → user
+ * library → built-in. Returns `null` when the Build Plan id resolves
+ * nowhere.
+ */
+export declare function resolveBuildPlanPackageRoot(buildPlanId: string, projectDataDir?: string): string | null;
+export declare function resolveInstanceBuildPlanPackageRoot(runtime: LocalServiceRuntime, buildPlanId: string): string | null;
+export {};

package/dist/packages/runtime/service/server-instance-helpers.js

@@ -0,0 +1,114 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { buildPlanDefinitionPath, builtinBuildPlanPackagePath, } from "../../build-plans/package/local-build-plans.js";
+import { userBuildPlanExists, userBuildPlanPath, } from "../../build-plans/package/user-build-plans.js";
+import { listStoredProjects } from "../project-store.js";
+function projectDataDirsForInstance(runtime) {
+    return listStoredProjects().map((project) => project.projectDataDir);
+}
+export function listInstanceRuns(runtime) {
+    return projectDataDirsForInstance(runtime)
+        .flatMap((projectDataDir) => runtime.listRunObservability(projectDataDir))
+        .sort((left, right) => {
+        const leftMs = Date.parse(left.started_at ?? left.created_at ?? left.finished_at ?? "");
+        const rightMs = Date.parse(right.started_at ?? right.created_at ?? right.finished_at ?? "");
+        return (Number.isFinite(rightMs) ? rightMs : 0) - (Number.isFinite(leftMs) ? leftMs : 0);
+    });
+}
+export function findInstanceRun(runtime, runId) {
+    for (const projectDataDir of projectDataDirsForInstance(runtime)) {
+        const run = runtime.getRunObservability(projectDataDir, runId);
+        if (run)
+            return run;
+    }
+    return null;
+}
+export function findInstanceJob(runtime, runId) {
+    for (const projectDataDir of projectDataDirsForInstance(runtime)) {
+        const job = runtime.getJob(projectDataDir, runId);
+        if (job)
+            return { job, projectDataDir };
+    }
+    return null;
+}
+export function findInstanceBuildRun(runtime, runId) {
+    for (const projectDataDir of projectDataDirsForInstance(runtime)) {
+        const run = runtime.getBuildRun(projectDataDir, runId);
+        if (run)
+            return { run, projectDataDir };
+    }
+    return null;
+}
+export function findInstanceVerifyRun(runtime, runId) {
+    for (const projectDataDir of projectDataDirsForInstance(runtime)) {
+        const run = runtime.getVerifyRun(projectDataDir, runId);
+        if (run)
+            return { run, projectDataDir };
+    }
+    return null;
+}
+export function listInstanceBuildPlans(runtime) {
+    const byId = new Map();
+    const projectDataDirs = projectDataDirsForInstance(runtime);
+    for (const projectDataDir of projectDataDirs.length > 0 ? projectDataDirs : [runtime.rootPath]) {
+        for (const buildPlanResource of runtime.listBuildPlans(projectDataDir)) {
+            const existing = byId.get(buildPlanResource.id);
+            if (!existing) {
+                byId.set(buildPlanResource.id, buildPlanResource);
+                continue;
+            }
+            const preferred = existing.built_in && !buildPlanResource.built_in
+                ? buildPlanResource
+                : existing;
+            byId.set(buildPlanResource.id, {
+                ...preferred,
+                active_for_projects: Array.from(new Set([
+                    ...existing.active_for_projects,
+                    ...buildPlanResource.active_for_projects,
+                ])).sort(),
+            });
+        }
+    }
+    return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+export function findInstanceBuildPlan(runtime, buildPlanId) {
+    return listInstanceBuildPlans(runtime).find((buildPlanResource) => buildPlanResource.id === buildPlanId) ?? null;
+}
+export function listInstanceBuildPlanRuns(runtime, buildPlanId) {
+    return projectDataDirsForInstance(runtime)
+        .flatMap((projectDataDir) => runtime.listBuildPlanRuns(projectDataDir, buildPlanId))
+        .sort((left, right) => {
+        const leftMs = Date.parse(left.started_at ?? left.created_at ?? left.finished_at ?? "");
+        const rightMs = Date.parse(right.started_at ?? right.created_at ?? right.finished_at ?? "");
+        return (Number.isFinite(rightMs) ? rightMs : 0) - (Number.isFinite(leftMs) ? leftMs : 0);
+    });
+}
+/**
+ * Resolve the on-disk root path for a Build Plan id. Used by the
+ * `/v1/build-plans/<id>/files/<relpath>` route. Resolution order matches
+ * the runtime: project-draft (if a project id is supplied) → user
+ * library → built-in. Returns `null` when the Build Plan id resolves
+ * nowhere.
+ */
+export function resolveBuildPlanPackageRoot(buildPlanId, projectDataDir) {
+    if (projectDataDir) {
+        const localPath = buildPlanDefinitionPath(projectDataDir, buildPlanId);
+        if (existsSync(join(localPath, "build-plan.json")))
+            return localPath;
+    }
+    if (userBuildPlanExists(buildPlanId)) {
+        return userBuildPlanPath(buildPlanId);
+    }
+    const builtinPath = builtinBuildPlanPackagePath(buildPlanId);
+    if (existsSync(join(builtinPath, "build-plan.json")))
+        return builtinPath;
+    return null;
+}
+export function resolveInstanceBuildPlanPackageRoot(runtime, buildPlanId) {
+    for (const projectDataDir of projectDataDirsForInstance(runtime)) {
+        const localPath = buildPlanDefinitionPath(projectDataDir, buildPlanId);
+        if (existsSync(join(localPath, "build-plan.json")))
+            return localPath;
+    }
+    return resolveBuildPlanPackageRoot(buildPlanId);
+}