@testchimp/cli 0.1.84 → 0.1.85

package/dist/core/tools.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import { TestChimpHttpError } from "./client.js";
 import { getToolDefinition, runTool } from "./tools.js";
 const runtimeObservation = {
     windowStartMillis: "1789497600000",
@@ -163,3 +164,96 @@ describe("list-meeting-filter-options", () => {
         assert.deepEqual(request, { path: "/api/mcp/list_meeting_filter_options", body: {} });
     });
 });
+describe("ack-bot-events", () => {
+    it("posts deduped eventIds to the delivery ackUrl", async () => {
+        let request;
+        const response = JSON.stringify({ results: [{ eventId: "e1", status: "BOT_ACK_ACKED" }] });
+        const result = await runTool("ack-bot-events", { eventIds: ["e1", "e1", "e2"], ackUrl: "https://ingress.testchimp.io/bot/events/ack" }, {
+            postMcp: async () => assert.fail("ack must not go to featureservice"),
+            postIngress: async (pathOrUrl, body) => {
+                request = { pathOrUrl, body };
+                return response;
+            },
+        });
+        assert.deepEqual(request, {
+            pathOrUrl: "https://ingress.testchimp.io/bot/events/ack",
+            body: { eventIds: ["e1", "e2"] },
+        });
+        assert.equal(result, response);
+    });
+    it("defaults to the ingress ack path", async () => {
+        let target;
+        await runTool("ack-bot-events", { eventIds: ["e1"] }, {
+            postMcp: async () => "{}",
+            postIngress: async (pathOrUrl) => {
+                target = pathOrUrl;
+                return "{}";
+            },
+        });
+        assert.equal(target, "/bot/events/ack");
+    });
+    it("explains a 404 from an older backend", async () => {
+        await assert.rejects(runTool("ack-bot-events", { eventIds: ["e1"] }, {
+            postMcp: async () => "{}",
+            postIngress: async () => {
+                throw new TestChimpHttpError(404, "Not Found", "");
+            },
+        }), /does not support bot acks yet/);
+    });
+    it("validates eventIds count and characters", async () => {
+        const ctx = { postMcp: async () => "{}", postIngress: async () => "{}" };
+        await assert.rejects(runTool("ack-bot-events", { eventIds: [] }, ctx), /Invalid input/);
+        const tooMany = Array.from({ length: 101 }, (_, i) => `e${i}`);
+        await assert.rejects(runTool("ack-bot-events", { eventIds: tooMany }, ctx), /Invalid input/);
+        await assert.rejects(runTool("ack-bot-events", { eventIds: ["é"] }, ctx), /Invalid input/);
+    });
+});
+describe("bot tools", () => {
+    async function capture(kebab, args) {
+        let request;
+        await runTool(kebab, args, {
+            postMcp: async (path, body) => {
+                request = { path, body };
+                return "{}";
+            },
+        });
+        return request;
+    }
+    it("maps read tools to their endpoints", async () => {
+        assert.deepEqual(await capture("get-my-tasks", { userId: "u1" }), {
+            path: "/api/mcp/get_my_tasks",
+            body: { userId: "u1" },
+        });
+        assert.deepEqual(await capture("get-my-tasks", {}), { path: "/api/mcp/get_my_tasks", body: {} });
+        assert.deepEqual(await capture("list-tests-awaiting-verification", { limit: 5 }), {
+            path: "/api/mcp/list_tests_awaiting_verification",
+            body: { limit: 5 },
+        });
+        assert.deepEqual(await capture("get-qa-posture", {}), { path: "/api/mcp/get_qa_posture", body: {} });
+        assert.deepEqual(await capture("get-bot-compat", {}), { path: "/api/mcp/get_bot_compat", body: {} });
+        assert.deepEqual(await capture("get-bot-profile", {}), { path: "/api/mcp/get_bot_profile", body: {} });
+    });
+    it("registers a bot profile with default filter op", async () => {
+        assert.deepEqual(await capture("register-bot-profile", {
+            role: "QA_ENGINEER",
+            responsibilities: " checkout flows ",
+            capabilities: ["E2E_AUTHORING", "TEST_BATCH_FIX"],
+            subscriptions: [
+                { eventType: "git-push", filters: [{ field: "author", value: "me" }] },
+                { eventType: "e2e-batch-completed" },
+            ],
+        }), {
+            path: "/bots/register_profile",
+            body: {
+                role: "QA_ENGINEER",
+                responsibilities: "checkout flows",
+                capabilities: ["E2E_AUTHORING", "TEST_BATCH_FIX"],
+                subscriptions: [
+                    { eventType: "git-push", filters: [{ field: "author", op: "eq", value: "me" }] },
+                    { eventType: "e2e-batch-completed", filters: [] },
+                ],
+            },
+        });
+        await assert.rejects(capture("register-bot-profile", { role: "CEO" }), /Invalid input/);
+    });
+});

package/dist/mcp/httpServer.d.ts

@@ -0,0 +1,14 @@
+import { type Server } from "node:http";
+export declare const MAX_MCP_BODY_BYTES: number;
+export interface McpHttpServerOptions {
+    port: number;
+    host: string;
+}
+/**
+ * Unverified peek at a JWT `exp` so expired access tokens get an HTTP 401 (which makes MCP clients
+ * refresh) instead of a tool-level error. Signature verification stays with TestChimp.
+ */
+export declare function isExpiredJwt(token: string, nowSeconds?: number): boolean;
+/** Remote MCP (Streamable HTTP, stateless). Each caller's bearer is forwarded to TestChimp; env credentials are never used. */
+export declare function createMcpHttpServer(): Server;
+export declare function runMcpHttpServer(options: McpHttpServerOptions): Promise<Server>;

package/dist/mcp/httpServer.js

@@ -0,0 +1,169 @@
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { getBackendUrl, runWithRequestAuth } from "../core/client.js";
+import { createMcpServer } from "./server.js";
+export const MAX_MCP_BODY_BYTES = 1024 * 1024;
+const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+class BodyTooLargeError extends Error {
+}
+function firstHeader(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/** Public origin of this server: TESTCHIMP_MCP_PUBLIC_URL, else derived from the request (Cloud Run sets X-Forwarded-Proto). */
+function publicBaseUrl(req) {
+    const configured = process.env.TESTCHIMP_MCP_PUBLIC_URL?.trim();
+    if (configured)
+        return configured.replace(/\/+$/, "").replace(/\/mcp$/, "");
+    const proto = firstHeader(req.headers["x-forwarded-proto"])?.split(",")[0].trim() === "https" ? "https" : "http";
+    const host = firstHeader(req.headers["x-forwarded-host"])?.split(",")[0].trim() || req.headers.host || "localhost";
+    return `${proto}://${host}`;
+}
+function authorizationServer() {
+    return process.env.TESTCHIMP_OAUTH_ISSUER?.trim().replace(/\/+$/, "") || getBackendUrl();
+}
+function sendJson(res, status, body, headers = {}) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+        ...headers,
+    });
+    res.end(payload);
+}
+function jsonRpcError(res, status, message, headers = {}) {
+    sendJson(res, status, { jsonrpc: "2.0", error: { code: -32000, message }, id: null }, headers);
+}
+function bearerToken(req) {
+    const match = /^Bearer\s+(\S+)\s*$/i.exec(firstHeader(req.headers.authorization) ?? "");
+    return match?.[1];
+}
+/**
+ * Unverified peek at a JWT `exp` so expired access tokens get an HTTP 401 (which makes MCP clients
+ * refresh) instead of a tool-level error. Signature verification stays with TestChimp.
+ */
+export function isExpiredJwt(token, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        return typeof payload.exp === "number" && payload.exp <= nowSeconds;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buf.length;
+        if (size > MAX_MCP_BODY_BYTES)
+            throw new BodyTooLargeError();
+        chunks.push(buf);
+    }
+    const text = Buffer.concat(chunks).toString("utf8");
+    return text.trim() === "" ? undefined : JSON.parse(text);
+}
+async function handleMcpPost(req, res) {
+    const token = bearerToken(req);
+    if (!token) {
+        const metadataUrl = `${publicBaseUrl(req)}${PROTECTED_RESOURCE_PATH}`;
+        jsonRpcError(res, 401, "Unauthorized: Authorization: Bearer <token> is required", {
+            "WWW-Authenticate": `Bearer resource_metadata="${metadataUrl}"`,
+        });
+        return;
+    }
+    if (isExpiredJwt(token)) {
+        const metadataUrl = `${publicBaseUrl(req)}${PROTECTED_RESOURCE_PATH}`;
+        jsonRpcError(res, 401, "Unauthorized: access token expired", {
+            "WWW-Authenticate": `Bearer error="invalid_token", error_description="expired", resource_metadata="${metadataUrl}"`,
+        });
+        return;
+    }
+    const declaredLength = Number(firstHeader(req.headers["content-length"]) ?? 0);
+    if (declaredLength > MAX_MCP_BODY_BYTES) {
+        jsonRpcError(res, 413, "Request body too large");
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (e) {
+        if (e instanceof BodyTooLargeError)
+            jsonRpcError(res, 413, "Request body too large");
+        else
+            jsonRpcError(res, 400, "Parse error: request body must be JSON");
+        return;
+    }
+    const server = createMcpServer();
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    res.on("close", () => {
+        void transport.close();
+        void server.close();
+    });
+    const botId = firstHeader(req.headers["bot-id"])?.trim() || undefined;
+    await runWithRequestAuth({ bearerToken: token, botId, isolated: true }, async () => {
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    });
+}
+async function route(req, res) {
+    const path = new URL(req.url ?? "/", "http://localhost").pathname.replace(/\/+$/, "") || "/";
+    if (path === "/healthz") {
+        sendJson(res, 200, { status: "ok" });
+        return;
+    }
+    if (path === PROTECTED_RESOURCE_PATH || path === `${PROTECTED_RESOURCE_PATH}/mcp`) {
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            sendJson(res, 405, { error: "Method not allowed" }, { Allow: "GET" });
+            return;
+        }
+        // RFC 9728 protected-resource metadata keys are spec-mandated snake_case.
+        sendJson(res, 200, {
+            resource: `${publicBaseUrl(req)}/mcp`,
+            authorization_servers: [authorizationServer()],
+            bearer_methods_supported: ["header"],
+            scopes_supported: ["testchimp"],
+        });
+        return;
+    }
+    if (path === "/mcp") {
+        if (req.method === "POST") {
+            await handleMcpPost(req, res);
+            return;
+        }
+        jsonRpcError(res, 405, "Method not allowed (stateless server: use POST)", { Allow: "POST" });
+        return;
+    }
+    sendJson(res, 404, { error: "Not found" });
+}
+/** Remote MCP (Streamable HTTP, stateless). Each caller's bearer is forwarded to TestChimp; env credentials are never used. */
+export function createMcpHttpServer() {
+    return createServer((req, res) => {
+        route(req, res).catch((e) => {
+            console.error(`[testchimp mcp] request failed: ${e instanceof Error ? e.message : String(e)}`);
+            if (!res.headersSent)
+                jsonRpcError(res, 500, "Internal server error");
+            else
+                res.end();
+        });
+    });
+}
+export async function runMcpHttpServer(options) {
+    const server = createMcpHttpServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => resolve());
+    });
+    console.error(`[testchimp mcp] Streamable HTTP listening on http://${options.host}:${options.port}/mcp`);
+    const shutdown = () => server.close(() => process.exit(0));
+    process.once("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
+    return server;
+}

package/dist/mcp/httpServer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/httpServer.test.js

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { after, afterEach, before, describe, it } from "node:test";
+import { createMcpHttpServer, isExpiredJwt } from "./httpServer.js";
+const originalFetch = globalThis.fetch;
+const originalEnv = { ...process.env };
+let server;
+let baseUrl;
+before(async () => {
+    server = createMcpHttpServer();
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+    baseUrl = `http://127.0.0.1:${server.address().port}`;
+});
+after(async () => {
+    await new Promise((resolve) => server.close(() => resolve()));
+});
+afterEach(() => {
+    globalThis.fetch = originalFetch;
+    process.env = { ...originalEnv };
+});
+describe("isExpiredJwt", () => {
+    const jwt = (payload) => `e30.${Buffer.from(JSON.stringify(payload)).toString("base64url")}.sig`;
+    it("flags expired tokens and passes live or opaque ones", () => {
+        assert.equal(isExpiredJwt(jwt({ exp: 100 }), 200), true);
+        assert.equal(isExpiredJwt(jwt({ exp: 300 }), 200), false);
+        assert.equal(isExpiredJwt(jwt({}), 200), false);
+        assert.equal(isExpiredJwt("opaque-token", 200), false);
+    });
+});
+describe("remote MCP over HTTP", () => {
+    it("serves /healthz", async () => {
+        const res = await originalFetch(`${baseUrl}/healthz`);
+        assert.equal(res.status, 200);
+    });
+    it("rejects /mcp without a bearer and points at the resource metadata", async () => {
+        process.env.TESTCHIMP_MCP_PUBLIC_URL = "https://mcp.example.com";
+        const res = await originalFetch(`${baseUrl}/mcp`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
+        });
+        assert.equal(res.status, 401);
+        assert.equal(res.headers.get("www-authenticate"), 'Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"');
+    });
+    it("returns 405 for GET /mcp in stateless mode", async () => {
+        const res = await originalFetch(`${baseUrl}/mcp`, { headers: { Authorization: "Bearer t" } });
+        assert.equal(res.status, 405);
+    });
+    it("publishes RFC 9728 protected-resource metadata", async () => {
+        process.env.TESTCHIMP_BACKEND_URL = "https://featureservice-staging.testchimp.io";
+        delete process.env.TESTCHIMP_MCP_PUBLIC_URL;
+        delete process.env.TESTCHIMP_OAUTH_ISSUER;
+        for (const path of ["/.well-known/oauth-protected-resource", "/.well-known/oauth-protected-resource/mcp"]) {
+            const res = await originalFetch(`${baseUrl}${path}`, { headers: { "X-Forwarded-Proto": "https" } });
+            assert.equal(res.status, 200);
+            const host = new URL(baseUrl).host;
+            assert.deepEqual(await res.json(), {
+                resource: `https://${host}/mcp`,
+                authorization_servers: ["https://featureservice-staging.testchimp.io"],
+                bearer_methods_supported: ["header"],
+                scopes_supported: ["testchimp"],
+            });
+        }
+    });
+    it("rejects oversized bodies", async () => {
+        const res = await originalFetch(`${baseUrl}/mcp`, {
+            method: "POST",
+            headers: { Authorization: "Bearer t", "Content-Type": "application/json" },
+            body: JSON.stringify({ pad: "x".repeat(1024 * 1024 + 10) }),
+        });
+        assert.equal(res.status, 413);
+    });
+    it("forwards the caller's bearer (never the server API key) on tool calls", async () => {
+        process.env.TESTCHIMP_BACKEND_URL = "https://featureservice.example.com";
+        process.env.TESTCHIMP_API_KEY = "server-key";
+        process.env.TESTCHIMP_OAUTH_TOKEN = "server-token";
+        const upstream = [];
+        globalThis.fetch = (async (input, init) => {
+            const url = String(input);
+            if (url.startsWith(baseUrl))
+                return originalFetch(input, init);
+            upstream.push({ url, headers: init?.headers });
+            return new Response(JSON.stringify({ minSkillVersion: "1.0.53", minCliVersion: "0.1.85", eventSchemaVersion: 1 }));
+        });
+        const res = await originalFetch(`${baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+                Authorization: "Bearer caller-jwt",
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 7,
+                method: "tools/call",
+                params: { name: "get-bot-compat", arguments: {} },
+            }),
+        });
+        assert.equal(res.status, 200);
+        const payload = (await res.json());
+        assert.equal(JSON.parse(payload.result?.content?.[0]?.text ?? "{}").minCliVersion, "0.1.85");
+        assert.deepEqual(upstream, [
+            {
+                url: "https://featureservice.example.com/api/mcp/get_bot_compat",
+                headers: { "Content-Type": "application/json", Authorization: "Bearer caller-jwt" },
+            },
+        ]);
+    });
+});

package/dist/mcp/server.d.ts

@@ -1 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** McpServer with every TestChimp tool registered (shared by stdio and HTTP transports). */
+export declare function createMcpServer(): McpServer;
 export declare function runMcpServer(): Promise<void>;

package/dist/mcp/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { postMcp } from "../core/client.js";
+import { postIngress, postMcp } from "../core/client.js";
 import { TOOL_DEFINITIONS, runTool } from "../core/tools.js";
 import { PACKAGE_VERSION } from "../core/version.js";
 function textResult(json) {
@@ -8,7 +8,8 @@ function textResult(json) {
         content: [{ type: "text", text: json }],
     };
 }
-export async function runMcpServer() {
+/** McpServer with every TestChimp tool registered (shared by stdio and HTTP transports). */
+export function createMcpServer() {
     const server = new McpServer({ name: "testchimp", version: PACKAGE_VERSION }, { capabilities: { tools: {}, logging: {} } });
     for (const def of TOOL_DEFINITIONS) {
         server.registerTool(def.kebab, {
@@ -27,11 +28,16 @@ export async function runMcpServer() {
                 : undefined;
             const json = await runTool(def.kebab, args ?? {}, {
                 postMcp,
+                postIngress,
                 onProgress,
             });
             return textResult(json);
         });
     }
+    return server;
+}
+export async function runMcpServer() {
+    const server = createMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/workspace/gitRepo.d.ts

@@ -0,0 +1,18 @@
+/** Local git inspection for `testchimp workspace map` (same rules as TestChimp Studio folder mapping). */
+/** Normalize a git remote URL to `owner/repo` (or GitLab nested path); host is ignored. */
+export declare function normalizeGitRemoteToFullName(remoteUrl: string | undefined | null): string | null;
+/** Case-insensitive compare of repositoryFullName values. */
+export declare function repositoryFullNamesMatch(expected: string | undefined | null, actual: string | undefined | null): boolean;
+export type LocalGitRepoInspection = {
+    selectedPath: string;
+    /** Canonical git toplevel, or null if not a work tree. */
+    toplevelPath: string | null;
+    isRepoRoot: boolean;
+    remoteFullNames: string[];
+};
+export declare function inspectLocalGitRepo(folderPath: string): LocalGitRepoInspection;
+/**
+ * Throw a user-visible error unless `inspection` is a git work tree; when `expectedRepositoryFullName`
+ * is known, also require the repository root and a matching remote.
+ */
+export declare function assertFolderMatchesRepo(inspection: LocalGitRepoInspection, expectedRepositoryFullName: string | null): void;

package/dist/workspace/gitRepo.js

@@ -0,0 +1,103 @@
+/** Local git inspection for `testchimp workspace map` (same rules as TestChimp Studio folder mapping). */
+import { spawnSync } from "node:child_process";
+import { canonicalizePath } from "./projectsRegistry.js";
+function runGit(cwd, args) {
+    const res = spawnSync("git", args, {
+        cwd,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (res.error)
+        throw res.error;
+    return { code: res.status ?? 1, stdout: res.stdout ?? "" };
+}
+function cleanFullName(pathOrName) {
+    const cleaned = String(pathOrName ?? "")
+        .replace(/\\/g, "/")
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "")
+        .trim();
+    if (!cleaned || cleaned.includes(".."))
+        return null;
+    return cleaned;
+}
+/** Normalize a git remote URL to `owner/repo` (or GitLab nested path); host is ignored. */
+export function normalizeGitRemoteToFullName(remoteUrl) {
+    let raw = String(remoteUrl ?? "").trim();
+    if (!raw)
+        return null;
+    raw = raw.replace(/\.git$/i, "");
+    const scp = raw.match(/^git@[^:]+:(.+)$/);
+    if (scp?.[1])
+        return cleanFullName(scp[1]);
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw)) {
+        try {
+            return cleanFullName(new URL(raw).pathname);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (raw.includes("/") && !raw.startsWith("~"))
+        return cleanFullName(raw);
+    return null;
+}
+/** Case-insensitive compare of repositoryFullName values. */
+export function repositoryFullNamesMatch(expected, actual) {
+    const a = String(expected ?? "").trim().replace(/\.git$/i, "").toLowerCase();
+    const b = String(actual ?? "").trim().replace(/\.git$/i, "").toLowerCase();
+    return Boolean(a && b && a === b);
+}
+export function inspectLocalGitRepo(folderPath) {
+    const selectedPath = canonicalizePath(folderPath);
+    const inside = runGit(selectedPath, ["rev-parse", "--is-inside-work-tree"]);
+    if (inside.code !== 0 || inside.stdout.trim() !== "true") {
+        return { selectedPath, toplevelPath: null, isRepoRoot: false, remoteFullNames: [] };
+    }
+    const top = runGit(selectedPath, ["rev-parse", "--show-toplevel"]);
+    let toplevelPath = null;
+    if (top.code === 0 && top.stdout.trim()) {
+        try {
+            toplevelPath = canonicalizePath(top.stdout.trim());
+        }
+        catch {
+            toplevelPath = null;
+        }
+    }
+    const remoteFullNames = [];
+    const remotes = runGit(selectedPath, ["remote", "-v"]);
+    if (remotes.code === 0) {
+        for (const line of remotes.stdout.split("\n")) {
+            const m = line.match(/^\S+\s+(\S+)\s+/);
+            if (!m?.[1])
+                continue;
+            const full = normalizeGitRemoteToFullName(m[1]);
+            if (full && !remoteFullNames.some((n) => repositoryFullNamesMatch(n, full)))
+                remoteFullNames.push(full);
+        }
+    }
+    const prefix = runGit(selectedPath, ["rev-parse", "--show-prefix"]);
+    const isRepoRoot = prefix.code === 0 && prefix.stdout.replace(/\\/g, "/").trim() === "";
+    return { selectedPath, toplevelPath, isRepoRoot, remoteFullNames };
+}
+/**
+ * Throw a user-visible error unless `inspection` is a git work tree; when `expectedRepositoryFullName`
+ * is known, also require the repository root and a matching remote.
+ */
+export function assertFolderMatchesRepo(inspection, expectedRepositoryFullName) {
+    if (!inspection.toplevelPath) {
+        throw new Error(`NOT_A_GIT_REPO: ${inspection.selectedPath} is not a Git repository${expectedRepositoryFullName ? ` (connected repo: ${expectedRepositoryFullName})` : ""}.`);
+    }
+    const expected = String(expectedRepositoryFullName ?? "").trim();
+    if (!expected)
+        return;
+    if (!inspection.isRepoRoot) {
+        throw new Error(`NOT_REPO_ROOT: folder is inside a Git repository but is not its root. Use ${inspection.toplevelPath} (connected repo: ${expected}).`);
+    }
+    if (!inspection.remoteFullNames.some((n) => repositoryFullNamesMatch(expected, n))) {
+        const found = inspection.remoteFullNames.length > 0 ? inspection.remoteFullNames.join(", ") : "none";
+        throw new Error(`REPO_MISMATCH: this folder's Git remote does not match the repository connected to the project (expected: ${expected}; found: ${found}).`);
+    }
+}

package/dist/workspace/projectsRegistry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-user folder ↔ project mapping in `~/.testchimp/projects.json` (TESTCHIMP_HOME honoured).
+ *
+ * Format contract shared with TestChimp Studio (desktop `src/main/workspace/projectsRegistry.ts`):
+ * same schema v2, canonical real paths, conflict rule, v1 → v2 migration, atomic writes (0600) and
+ * quarantine naming. `fixtures/projects-registry/` (mirrored byte-for-byte in the desktop repo)
+ * pins the on-disk bytes both writers must produce.
+ */
+import { z } from "zod";
+export declare const WorkspaceFolderSchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type WorkspaceFolder = z.infer<typeof WorkspaceFolderSchema>;
+export declare const WorkspaceMappingSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    projectName: z.ZodOptional<z.ZodString>;
+    folders: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    createdAtMillis: z.ZodNumber;
+    lastOpenedAtMillis: z.ZodNumber;
+    browserStartUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type WorkspaceMapping = z.infer<typeof WorkspaceMappingSchema>;
+export declare const ProjectsRegistrySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    activeWorkspaceId: z.ZodNullable<z.ZodString>;
+    mappings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        projectId: z.ZodString;
+        projectName: z.ZodOptional<z.ZodString>;
+        folders: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            path: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        createdAtMillis: z.ZodNumber;
+        lastOpenedAtMillis: z.ZodNumber;
+        browserStartUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ProjectsRegistry = z.infer<typeof ProjectsRegistrySchema>;
+/** Injectable clock / id source (tests pin these to compare bytes with Studio). */
+export type RegistryEnv = {
+    home?: string;
+    now?: () => number;
+    newId?: () => string;
+};
+export declare function getTestchimpHome(env?: RegistryEnv): string;
+export declare function projectsRegistryPath(env?: RegistryEnv): string;
+/** Serialized bytes exactly as written to disk (2-space JSON + trailing newline). */
+export declare function serializeRegistry(value: unknown): string;
+/** Real absolute directory path (follows symlinks); same error codes as Studio. */
+export declare function canonicalizePath(input: string): string;
+/**
+ * Read projects.json for a write. Missing → empty file created; v1 → migrated + persisted;
+ * schema-invalid or unparseable → moved to `projects.invalid.<millis>.json` and reset to empty.
+ */
+export declare function readProjectsRegistry(env?: RegistryEnv): ProjectsRegistry;
+/** Side-effect-free lookup for `workspace get` (never creates, migrates, or quarantines). */
+export declare function findWorkspaceMapping(projectId: string, env?: RegistryEnv): WorkspaceMapping | null;
+export type FolderMappingConflict = {
+    projectId: string;
+    projectName?: string;
+};
+export type UpsertWorkspaceFolderInput = {
+    projectId: string;
+    projectName?: string;
+    rootPath: string;
+    /** When true, steal `rootPath` from another project's mapping if present. */
+    reassign?: boolean;
+};
+/**
+ * Ensure a project workspace exists and add `rootPath` as a folder (or refresh if already present).
+ * Rejects if the path is mapped to a different project unless `reassign` is set.
+ */
+export declare function upsertWorkspaceFolder(input: UpsertWorkspaceFolderInput, env?: RegistryEnv): WorkspaceMapping;