@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/runtime/service/server-routes-events.js

@@ -0,0 +1,99 @@
+import { LOCAL_SERVICE_ROUTES } from "./routes.js";
+import { parseRequestUrl, sendError, writeHeaders } from "./server-helpers.js";
+/**
+ * `GET /v1/events` — a Server-Sent Events change stream.
+ *
+ * Every authorized client (Interf Desktop, CLI, MCP host) is a peer of the
+ * same local service, so any client's write fans out here to every open
+ * renderer. The renderer keeps one `EventSource` open and refreshes on each
+ * frame — push, not idle polling. The dispatcher calls `notifyServiceChange`
+ * after a successful mutating request (see `server.ts`); the active-run poll
+ * still owns in-flight run progress.
+ *
+ * Auth: browser `EventSource` cannot set an `Authorization` header, so the
+ * token rides in `?token=`. The dispatcher exempts this path from the header
+ * guard; we validate the query token here against the runtime token.
+ */
+// One subscriber set per runtime. A WeakMap keeps multi-runtime test setups
+// isolated and lets sets be GC'd with their runtime — no global leak.
+const subscribers = new WeakMap();
+const KEEPALIVE_INTERVAL_MS = 25_000;
+function subscriberSet(runtime) {
+    let set = subscribers.get(runtime);
+    if (!set) {
+        set = new Set();
+        subscribers.set(runtime, set);
+    }
+    return set;
+}
+/** Constant-time compare of the query token against the runtime token. */
+function isAuthorizedQueryToken(runtime, token) {
+    if (!runtime.authToken)
+        return true; // tokenless-dev mode
+    if (!token || token.length !== runtime.authToken.length)
+        return false;
+    let mismatch = 0;
+    for (let index = 0; index < runtime.authToken.length; index += 1) {
+        mismatch |= token.charCodeAt(index) ^ runtime.authToken.charCodeAt(index);
+    }
+    return mismatch === 0;
+}
+/** Fan a change ping out to every open events stream for this runtime. */
+export function notifyServiceChange(runtime) {
+    const set = subscribers.get(runtime);
+    if (!set || set.size === 0)
+        return;
+    const frame = `event: changed\ndata: {"ts":"${new Date().toISOString()}"}\n\n`;
+    for (const res of set) {
+        try {
+            res.write(frame);
+        }
+        catch {
+            // A dead socket is reaped by its own close handler; ignore here.
+        }
+    }
+}
+export function tryHandleEvents(req, res, runtime, path, method) {
+    if (path !== LOCAL_SERVICE_ROUTES.events)
+        return false;
+    if (method !== "GET")
+        return false;
+    const url = parseRequestUrl(req);
+    if (!isAuthorizedQueryToken(runtime, url.searchParams.get("token"))) {
+        sendError(res, 401, "Missing or invalid token.");
+        return true;
+    }
+    // SSE headers (CORS context is merged in by writeHeaders). Connection stays
+    // open — no res.end until the client disconnects.
+    writeHeaders(res, 200, {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-cache, no-transform",
+        connection: "keep-alive",
+        // Disable proxy buffering so frames flush immediately.
+        "x-accel-buffering": "no",
+    });
+    // Initial sync frame: tells the client to refresh on every (re)connect.
+    // EventSource reconnects when the webview wakes, so this is what makes the
+    // app fresh "on focus" without any client-side focus listener.
+    res.write(`event: sync\ndata: {"ts":"${new Date().toISOString()}"}\n\n`);
+    const set = subscriberSet(runtime);
+    set.add(res);
+    // Keepalive comment so idle connections aren't reaped by the webview/proxy.
+    const keepalive = setInterval(() => {
+        try {
+            res.write(`: keepalive ${Date.now()}\n\n`);
+        }
+        catch {
+            // ignore; close handler cleans up
+        }
+    }, KEEPALIVE_INTERVAL_MS);
+    if (typeof keepalive.unref === "function")
+        keepalive.unref();
+    const cleanup = () => {
+        clearInterval(keepalive);
+        set.delete(res);
+    };
+    req.on("close", cleanup);
+    res.on("close", cleanup);
+    return true;
+}

package/dist/packages/runtime/service/server-routes-project-context.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ProjectRouteContext } from "./server-routes-project-runs.js";
+import type { LocalServiceRuntime } from "../runtime.js";
+/**
+ * Read-only observability over a project: readiness state,
+ * source-file inventory, Context Graph locator, file serving
+ * inside the Context Graph root, and per-Artifact status.
+ */
+export declare function tryHandleProjectContext(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, ctx: ProjectRouteContext, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-project-context.js

@@ -0,0 +1,192 @@
+import { PROJECT_SUBRESOURCES } from "./routes.js";
+import { parseRequestUrl, sendError, sendJson, } from "./server-helpers.js";
+import { isTraversalRelativePath, safeApiFilePath, sendApiFile, } from "./server-api-files.js";
+import { buildTraces } from "../build/traces.js";
+import { loadContextGraphSourceManifest } from "../build/source-manifest.js";
+import { computeProjectSourceState } from "../project-source-state.js";
+/**
+ * Read-only observability over a project: readiness state,
+ * source-file inventory, Context Graph locator, file serving
+ * inside the Context Graph root, and per-Artifact status.
+ */
+export async function tryHandleProjectContext(req, res, runtime, ctx, method) {
+    const { storedProject, subPath } = ctx;
+    if (subPath === PROJECT_SUBRESOURCES.readiness) {
+        if (method === "GET") {
+            const readiness = runtime.getReadiness(storedProject.projectDataDir, storedProject.id);
+            sendJson(res, 200, readiness);
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.sourceFiles) {
+        if (method === "GET") {
+            sendJson(res, 200, {
+                source_files: runtime.listSourceFiles(storedProject.projectDataDir, storedProject.id),
+            });
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.sourceManifest) {
+        if (method === "GET") {
+            const latestContext = runtime.getLatestContextGraph(storedProject.projectDataDir, storedProject.id);
+            const manifest = latestContext?.path ? loadContextGraphSourceManifest(latestContext.path) : null;
+            if (!manifest)
+                sendError(res, 404, "Source Manifest not found.");
+            else
+                sendJson(res, 200, { source_manifest: manifest });
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.contextGraph) {
+        if (method === "GET") {
+            const context = runtime.getLatestContextGraph(storedProject.projectDataDir, storedProject.id);
+            if (!context)
+                sendError(res, 404, "Context Graph not found.");
+            else
+                sendJson(res, 200, context);
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.graphs) {
+        if (method === "GET") {
+            sendJson(res, 200, {
+                graphs: runtime.listContextGraphs(storedProject.projectDataDir, storedProject.id),
+            });
+            return true;
+        }
+    }
+    if (subPath.startsWith(`${PROJECT_SUBRESOURCES.graphs}/`)) {
+        if (method === "GET") {
+            const rawGraphId = subPath.slice(PROJECT_SUBRESOURCES.graphs.length + 1);
+            let graphId;
+            try {
+                graphId = decodeURIComponent(rawGraphId);
+            }
+            catch {
+                sendError(res, 400, "Context Graph id is not valid URI-encoded UTF-8.");
+                return true;
+            }
+            const graph = runtime
+                .listContextGraphs(storedProject.projectDataDir, storedProject.id)
+                .find((entry) => entry.graph_id === graphId || entry.build_run_id === graphId);
+            if (!graph)
+                sendError(res, 404, "Context Graph not found.");
+            else
+                sendJson(res, 200, graph);
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.buildEvidence) {
+        if (method === "GET") {
+            const context = runtime.getLatestContextGraph(storedProject.projectDataDir, storedProject.id);
+            if (!context?.build_evidence) {
+                sendError(res, 404, "Build evidence not found.");
+            }
+            else {
+                sendJson(res, 200, context.build_evidence);
+            }
+            return true;
+        }
+    }
+    // GET /v1/projects/<id>/context-graph/traces — first-class traces surface.
+    // Returns a derived Traces wire shape rolled up from the current
+    // Context Graph's artifacts + Checks + source file index.
+    if (subPath === PROJECT_SUBRESOURCES.traces) {
+        if (method === "GET") {
+            const project = runtime.getProject(storedProject.projectDataDir, storedProject.id);
+            if (!project) {
+                sendError(res, 404, "Context Graph not found.");
+                return true;
+            }
+            const readiness = runtime.getReadiness(storedProject.projectDataDir, storedProject.id);
+            const sourceFiles = runtime.listSourceFiles(storedProject.projectDataDir, storedProject.id);
+            const sourceFileCount = Array.isArray(sourceFiles) ? sourceFiles.length : 0;
+            const context = runtime.getLatestContextGraph(storedProject.projectDataDir, storedProject.id);
+            const filesProcessed = context?.build_evidence?.rows
+                .find((row) => row.id === "files-processed")
+                ?.metric.observed;
+            const traces = buildTraces({
+                projectId: storedProject.id,
+                graphId: project.latest_build_run_id ?? project.runs?.latest_build_run_id ?? "no-graph",
+                readiness,
+                artifacts: project.artifacts ?? [],
+                sourceFileCount,
+                filesProcessed,
+            });
+            sendJson(res, 200, traces);
+            return true;
+        }
+    }
+    // GET /v1/projects/<id>/source-state — manifest-backed drift verdict for
+    // the Project's Source binding.
+    if (subPath === PROJECT_SUBRESOURCES.sourceState) {
+        if (method === "GET") {
+            // The per-run SourceState record carries the historical file index;
+            // for v1 we treat the latest Build id as the graph pointer and
+            // leave the hash comparison to a follow-up enhancement. For now the
+            // verdict is `unknown` until a Build has produced a Context Graph.
+            const latestContext = runtime.getLatestContextGraph(storedProject.projectDataDir, storedProject.id);
+            const state = computeProjectSourceState({
+                projectId: storedProject.id,
+                sourceFolderPath: storedProject.source.locator,
+                contextGraphPath: latestContext?.path ?? storedProject.contextGraphPath,
+                lastGraphIndexHash: null,
+            });
+            sendJson(res, 200, state);
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.contextGraphFile) {
+        // GET /v1/projects/<id>/context-graph/file?path=<relpath>
+        if (method === "GET") {
+            const relPath = parseRequestUrl(req).searchParams.get("path")?.trim() ?? "";
+            if (!relPath) {
+                sendError(res, 400, "Missing required query parameter: path.");
+                return true;
+            }
+            if (isTraversalRelativePath(relPath)) {
+                sendError(res, 400, "File path escapes Context Graph root.");
+                return true;
+            }
+            const latestContext = runtime.getLatestContextGraph(storedProject.projectDataDir, storedProject.id);
+            if (!latestContext?.path) {
+                sendError(res, 404, "Context Graph not found.");
+                return true;
+            }
+            const contextGraphPath = latestContext.path;
+            const safePath = safeApiFilePath(contextGraphPath, relPath);
+            if (!safePath) {
+                sendError(res, 400, "File path escapes Context Graph root.");
+                return true;
+            }
+            if (!sendApiFile(res, safePath)) {
+                sendError(res, 404, `File not found: ${relPath}`);
+            }
+            return true;
+        }
+    }
+    if (subPath.startsWith(`${PROJECT_SUBRESOURCES.artifacts}/`)) {
+        // GET /v1/projects/<id>/artifacts/<artifact-id> — per-Artifact
+        // status from the latest Build.
+        if (method === "GET") {
+            const rawArtifactId = subPath.slice(PROJECT_SUBRESOURCES.artifacts.length + 1);
+            let artifactId;
+            try {
+                artifactId = decodeURIComponent(rawArtifactId);
+            }
+            catch {
+                sendError(res, 400, "Artifact id is not valid URI-encoded UTF-8.");
+                return true;
+            }
+            const project = runtime.getProject(storedProject.projectDataDir, storedProject.id);
+            const status = project?.artifacts.find((entry) => entry.artifact_id === artifactId);
+            if (!status) {
+                sendError(res, 404, `Artifact not found: ${artifactId}`);
+                return true;
+            }
+            sendJson(res, 200, status);
+            return true;
+        }
+    }
+    return false;
+}

package/dist/packages/runtime/service/server-routes-project-jobs.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ProjectRouteContext } from "./server-routes-project-runs.js";
+import type { LocalServiceRuntime } from "../runtime.js";
+/**
+ * Async/structured mutations on a project: Build Plan authoring
+ * and improvement jobs, benchmark-question drafts, Build Plan change deltas,
+ * and the destructive reset action.
+ */
+export declare function tryHandleProjectJobs(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, ctx: ProjectRouteContext, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-project-jobs.js

@@ -0,0 +1,130 @@
+import { PROJECT_SUBRESOURCES } from "./routes.js";
+import { readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { writeBenchmarkSpecsForProject } from "../../projects/source-config.js";
+import { loadTestSpec } from "../verify/verify-specs.js";
+/**
+ * Async/structured mutations on a project: Build Plan authoring
+ * and improvement jobs, benchmark-question drafts, Build Plan change deltas,
+ * and the destructive reset action.
+ */
+export async function tryHandleProjectJobs(req, res, runtime, ctx, method) {
+    const { storedProject, subPath } = ctx;
+    if (subPath === PROJECT_SUBRESOURCES.buildPlanDraftRuns ||
+        subPath === PROJECT_SUBRESOURCES.legacyBuildPlanDraftRuns) {
+        if (method === "POST") {
+            try {
+                const body = (await readJsonBody(req));
+                const job = await runtime.createBuildPlanAuthoringRun(storedProject.projectDataDir, {
+                    ...(body ?? {}),
+                    project: storedProject.id,
+                    source_folder_path: storedProject.source.locator,
+                });
+                sendJson(res, 202, job);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.buildPlanImprovementRuns) {
+        if (method === "POST") {
+            try {
+                const body = (await readJsonBody(req));
+                const job = await runtime.createBuildPlanAuthoringRun(storedProject.projectDataDir, {
+                    ...(body ?? {}),
+                    project: storedProject.id,
+                    source_folder_path: storedProject.source.locator,
+                }, "build-plan-improvement");
+                sendJson(res, 202, job);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.benchmarkQuestionDrafts) {
+        if (method === "POST") {
+            try {
+                const body = (await readJsonBody(req));
+                const job = await runtime.createBenchmarkQuestionDraftRun(storedProject.projectDataDir, {
+                    ...(body ?? {}),
+                    project: storedProject.id,
+                    source_folder_path: storedProject.source.locator,
+                });
+                sendJson(res, 202, job);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    // The saved Q&A check set is the editable benchmark spec. Read it from the
+    // source-files spec (source + context graph specs share the same cases) and
+    // persist edits to both via the spec writer.
+    if (subPath === PROJECT_SUBRESOURCES.benchmarkChecks) {
+        if (method === "GET") {
+            const spec = loadTestSpec(storedProject.projectDataDir, "source-files", storedProject.id);
+            const checks = (spec?.cases ?? []).map((testCase) => ({
+                question: testCase.question,
+                answer: testCase.answer ?? "",
+            }));
+            sendJson(res, 200, { checks });
+            return true;
+        }
+        if (method === "PATCH") {
+            try {
+                const body = (await readJsonBody(req));
+                const rawChecks = Array.isArray(body?.checks) ? body.checks : [];
+                const checks = rawChecks
+                    .filter((entry) => Boolean(entry) &&
+                    typeof entry === "object" &&
+                    typeof entry.question === "string")
+                    .map((entry) => ({
+                    question: entry.question.trim(),
+                    answer: typeof entry.answer === "string" ? entry.answer.trim() : "",
+                }))
+                    .filter((entry) => entry.question.length > 0);
+                writeBenchmarkSpecsForProject({
+                    projectDataDir: storedProject.projectDataDir,
+                    projectName: storedProject.id,
+                    checks,
+                });
+                sendJson(res, 200, { checks });
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.buildPlanChanges) {
+        if (method === "POST") {
+            try {
+                const body = (await readJsonBody(req));
+                sendJson(res, 200, runtime.applyBuildPlanChange(storedProject.projectDataDir, body));
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.reset) {
+        if (method === "POST") {
+            try {
+                const body = (await readJsonBody(req));
+                const request = { project: storedProject.id, scope: "build", ...(body ?? {}) };
+                const result = runtime.applyReset(storedProject.projectDataDir, request);
+                sendJson(res, 200, result);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    return false;
+}

package/dist/packages/runtime/service/server-routes-project-runs.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { StoredProject } from "../project-store.js";
+import type { LocalServiceRuntime } from "../runtime.js";
+export type ProjectRouteContext = {
+    storedProject: StoredProject;
+    decodedProjectId: string;
+    subPath: string;
+};
+/**
+ * Build/verify run mutations and the per-Project runs listing.
+ * Run-id lookups for an unknown project are handled by the
+ * top-level /v1/runs and /v1/verify-runs routes.
+ */
+export declare function tryHandleProjectRuns(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, ctx: ProjectRouteContext, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-project-runs.js

@@ -0,0 +1,85 @@
+import { PROJECT_SUBRESOURCES } from "./routes.js";
+import { readJsonBody, sendError, sendErrorResponse, sendJson, } from "./server-helpers.js";
+import { assertCanRunBenchmark } from "../entitlement-guard.js";
+/**
+ * Build/verify run mutations and the per-Project runs listing.
+ * Run-id lookups for an unknown project are handled by the
+ * top-level /v1/runs and /v1/verify-runs routes.
+ */
+export async function tryHandleProjectRuns(req, res, runtime, ctx, method) {
+    const { storedProject, subPath } = ctx;
+    if (subPath === PROJECT_SUBRESOURCES.buildRuns) {
+        if (method === "POST") {
+            if (!storedProject.buildPlanId) {
+                sendError(res, 400, `Project ${storedProject.id} has no Build Plan selected. Select one via PATCH /v1/projects/${storedProject.id} { "build_plan_id": "<id>" } before building.`);
+                return true;
+            }
+            try {
+                const body = (await readJsonBody(req));
+                const request = { project: storedProject.id, ...(body ?? {}) };
+                const idempotencyKeyRaw = req.headers["x-interf-idempotency-key"];
+                const idempotencyKey = Array.isArray(idempotencyKeyRaw)
+                    ? idempotencyKeyRaw[0]
+                    : idempotencyKeyRaw;
+                const trimmedKey = typeof idempotencyKey === "string" ? idempotencyKey.trim() : "";
+                const dedupedRunId = trimmedKey
+                    ? runtime.findIdempotentBuildRun(storedProject.projectDataDir, trimmedKey)
+                    : null;
+                if (dedupedRunId) {
+                    const existing = runtime.getBuildRun(storedProject.projectDataDir, dedupedRunId);
+                    if (existing) {
+                        sendJson(res, 200, existing);
+                        return true;
+                    }
+                }
+                const resource = await runtime.createBuildRun(storedProject.projectDataDir, request);
+                if (trimmedKey) {
+                    runtime.recordIdempotentBuildRun(storedProject.projectDataDir, trimmedKey, resource.run.run_id);
+                }
+                sendJson(res, 201, resource);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.verifyRuns) {
+        if (method === "GET") {
+            const runs = runtime.listVerifyRunsForProject(storedProject.projectDataDir, storedProject.id);
+            sendJson(res, 200, { runs });
+            return true;
+        }
+        if (method === "POST") {
+            if (!storedProject.buildPlanId) {
+                sendError(res, 400, `Project ${storedProject.id} has no Build Plan selected. Select one via PATCH /v1/projects/${storedProject.id} { "build_plan_id": "<id>" } before running a benchmark.`);
+                return true;
+            }
+            try {
+                // Free-tier benchmark quota lives next to project creation.
+                // Pro / Enterprise have `benchmarking-unlimited` and bypass;
+                // Free / Anonymous get one run per Project, ever.
+                const existingCount = runtime
+                    .listVerifyRunsForProject(storedProject.projectDataDir, storedProject.id)
+                    .filter((run) => !run.parent_run_id).length;
+                assertCanRunBenchmark(runtime.currentAccount, existingCount);
+                const body = (await readJsonBody(req));
+                const request = { project: storedProject.id, ...(body ?? {}) };
+                const resource = await runtime.createVerifyRun(storedProject.projectDataDir, request);
+                sendJson(res, 201, resource);
+            }
+            catch (error) {
+                sendErrorResponse(res, error);
+            }
+            return true;
+        }
+    }
+    if (subPath === PROJECT_SUBRESOURCES.runs) {
+        if (method === "GET") {
+            const runs = runtime.listBuildRunsForProject(storedProject.projectDataDir, storedProject.id);
+            sendJson(res, 200, { runs });
+            return true;
+        }
+    }
+    return false;
+}

package/dist/packages/runtime/service/server-routes-projects.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleProjectCollection(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;
+export declare function tryHandlePerProject(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-projects.js

@@ -0,0 +1,92 @@
+import { ProjectCreateRequestSchema, ProjectUpdateRequestSchema, } from "../schemas/index.js";
+import { LOCAL_SERVICE_ROUTES } from "./routes.js";
+import { readJsonBody, sendError, sendErrorResponse, sendJson, } from "./server-helpers.js";
+import { createStoredProject, deleteStoredProject, getStoredProject, listStoredProjects, projectWireShape, updateStoredProject, } from "../project-store.js";
+import { tryHandleProjectRuns, } from "./server-routes-project-runs.js";
+import { tryHandleProjectJobs } from "./server-routes-project-jobs.js";
+import { tryHandleProjectContext } from "./server-routes-project-context.js";
+export async function tryHandleProjectCollection(req, res, runtime, path, method) {
+    // GET /v1/projects — list every Project on the instance.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.projects) {
+        const items = listStoredProjects().map(projectWireShape);
+        sendJson(res, 200, { projects: items });
+        return true;
+    }
+    // POST /v1/projects — create a new Project.
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.projects) {
+        try {
+            const body = ProjectCreateRequestSchema.parse(await readJsonBody(req));
+            const stored = createStoredProject(runtime, {
+                id: body.id,
+                source: { kind: "local-folder", locator: body.source.locator },
+                build_plan_id: body.build_plan_id,
+            });
+            sendJson(res, 201, projectWireShape(stored));
+        }
+        catch (error) {
+            // assertCanCreateProject throws EntitlementError when the Free
+            // 10-Project cap is reached. sendErrorResponse routes it to 402 with
+            // upgrade_hint; everything else stays a 400 with the message body.
+            sendErrorResponse(res, error);
+        }
+        return true;
+    }
+    return false;
+}
+export async function tryHandlePerProject(req, res, runtime, path, method) {
+    if (!path.startsWith(`${LOCAL_SERVICE_ROUTES.projects}/`)) {
+        return false;
+    }
+    const tail = path.slice(LOCAL_SERVICE_ROUTES.projects.length + 1);
+    const slashIndex = tail.indexOf("/");
+    const projectId = slashIndex === -1 ? tail : tail.slice(0, slashIndex);
+    const subPath = slashIndex === -1 ? "" : tail.slice(slashIndex + 1);
+    const decodedProjectId = decodeURIComponent(projectId);
+    const storedProject = getStoredProject(decodedProjectId);
+    if (!storedProject) {
+        sendError(res, 404, `Project not found: ${decodedProjectId}`);
+        return true;
+    }
+    runtime.touchProject(storedProject.projectDataDir);
+    if (subPath === "") {
+        // Bare /v1/projects/{id} — project CRUD.
+        if (method === "GET") {
+            const project = runtime.getProject(storedProject.projectDataDir, storedProject.id);
+            if (!project) {
+                sendError(res, 404, `Project not found: ${decodedProjectId}`);
+                return true;
+            }
+            sendJson(res, 200, project);
+            return true;
+        }
+        if (method === "PATCH") {
+            try {
+                const body = ProjectUpdateRequestSchema.parse(await readJsonBody(req));
+                const updated = updateStoredProject(decodedProjectId, {
+                    build_plan_id: body.build_plan_id,
+                });
+                sendJson(res, 200, projectWireShape(updated));
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+        if (method === "DELETE") {
+            deleteStoredProject(runtime, decodedProjectId);
+            sendJson(res, 200, { id: decodedProjectId, deleted: true });
+            return true;
+        }
+        sendError(res, 404, `Unknown project route: ${path}`);
+        return true;
+    }
+    const ctx = { storedProject, decodedProjectId, subPath };
+    if (await tryHandleProjectRuns(req, res, runtime, ctx, method))
+        return true;
+    if (await tryHandleProjectJobs(req, res, runtime, ctx, method))
+        return true;
+    if (await tryHandleProjectContext(req, res, runtime, ctx, method))
+        return true;
+    sendError(res, 404, `Unknown project sub-route: ${subPath}`);
+    return true;
+}

package/dist/packages/runtime/service/server-routes-runs.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleRuns(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): boolean;