@testchimp/cli 0.1.83 → 0.1.85

package/README.md

@@ -36,7 +36,7 @@ The config **file path** depends on the host (e.g. Cursor often uses `<repo>/.cu
 ## CLI
 
 ```bash
-export TESTCHIMP_API_KEY=...   # required (often read from project MCP env; never commit keys)
+export TESTCHIMP_API_KEY=...   # required unless TESTCHIMP_OAUTH_TOKEN is set (often read from project MCP env; never commit keys)
 testchimp --help
 testchimp get-requirement-coverage --branch-name main --help
 testchimp create-user-story --platform-file-path plans/stories/foo.md --title "Checkout"
@@ -59,6 +59,83 @@ testchimp get-meeting-transcript --meeting-id <meeting-id> --summary-only
 - **Meetings:** `list-meetings` / `list-meeting-filter-options` cover team-wide Meeting Bots meetings only (same filters as the Meetings page). `--from` / `--to` take `YYYY-MM-DD` (inclusive local days), ISO datetimes, or epoch millis; `--label`, `--participant`, `--domain` are repeatable or comma-separated.
 - **Flags:** default for each subcommand; **`--json-input '<json>'`** or **`--json-input @file.json`** merges over flags (JSON wins on conflicts). Use JSON for nested bodies (e.g. TrueCoverage scopes).
 
+## Authentication and environment
+
+| Variable | Purpose |
+|---|---|
+| `TESTCHIMP_API_KEY` | Project API key (sent as `TestChimp-Api-Key`). Required unless `TESTCHIMP_OAUTH_TOKEN` is set. |
+| `TESTCHIMP_OAUTH_TOKEN` | OAuth 2.1 access token issued by featureservice (sent as `Authorization: Bearer`). When both are set, both are sent and the backend prefers the bearer. |
+| `TESTCHIMP_BOT_ID` | QA bot id (sent as `bot-id` header for attribution). Must be 1–64 printable ASCII characters without spaces; otherwise it is ignored with a warning. |
+| `TESTCHIMP_BACKEND_URL` | Featureservice base URL (default `https://featureservice.testchimp.io`). |
+| `TESTCHIMP_INGRESS_URL` | Ingress base URL used for bot event acks (default `https://ingress.testchimp.io`). |
+| `TESTCHIMP_HOME` | TestChimp Studio / CLI home holding `projects.json` (default `~/.testchimp`). |
+
+## Workspace folder mapping
+
+Map a local repository folder to a TestChimp project for the current user. The mapping lives in `~/.testchimp/projects.json` (or `$TESTCHIMP_HOME/projects.json`), the same file TestChimp Studio uses, so a folder mapped from the CLI shows up in Studio and in the headless AgentWatch daemon.
+
+```bash
+testchimp workspace map --project-id <id> --folder ~/code/shop [--project-name "Shop"] [--reassign] [--skip-repo-check]
+testchimp workspace get --project-id <id>        # prints the mapping JSON; exit 1 when unmapped
+```
+
+`workspace map` follows the same rules as Studio:
+
+- The folder must exist and be a git work tree. Paths are stored as canonical real paths.
+- When `TESTCHIMP_API_KEY` / `TESTCHIMP_OAUTH_TOKEN` is set, the CLI loads the project's connected repository (`get-git-folder-mapping`). If one is connected, the folder must be the repository root and one of its git remotes must match (`owner/repo`, case-insensitive). If no credential is set, no repo is connected, or the lookup fails, the check is skipped with a note on stderr. The credential's own project is used for this lookup, so run it with the same project's key or bot token. `--skip-repo-check` skips the lookup entirely.
+- A folder belongs to one project. Mapping it to a second project fails unless you pass `--reassign`, which moves it (and drops the old project's entry if that leaves it with no folders).
+- The file is written atomically (temp file, then rename) with mode `0600`. Other projects are left alone, and unknown fields written by newer Studio versions are kept. A file that is not valid JSON or does not match schema v2 is moved to `projects.invalid.<millis>.json` and replaced with an empty registry. Schema v1 files are migrated to v2.
+
+The byte-level format is pinned by `fixtures/projects-registry/`, with an identical copy in the Studio repo. Both test suites replay the same upsert sequences and compare the output bytes.
+
+## QA bots
+
+```bash
+testchimp get-my-tasks --user-id <user-id>      # OAuth tokens imply the user
+testchimp list-tests-awaiting-verification --limit 20
+testchimp get-qa-posture
+testchimp bot get-profile
+testchimp bot register-profile --role QA_ENGINEER --responsibilities "Checkout + payments" \
+  --capability E2E_AUTHORING --capability TEST_BATCH_FIX \
+  --subscriptions-json '[{"eventType":"git-push","filters":[{"field":"author","op":"eq","value":"me"}]},{"eventType":"e2e-batch-completed"}]'
+testchimp bot ack <eventId> [<eventId>...] --ack-url <delivery ackUrl>
+testchimp bot compat --skill-version 1.0.53
+```
+
+`bot ack` prints one `eventId<TAB>status` line per id and exits non-zero when any status is `BOT_ACK_UNKNOWN_EVENT`, `BOT_ACK_NOT_A_TARGET`, or `BOT_ACK_MISSING_BOT_ID`. An explicit `--ack-url` must be https (http only on localhost) and point at a TestChimp host or the `TESTCHIMP_INGRESS_URL` host. `bot compat` exits 0 and prints the deployment minimums plus `cliUpgradeRequired` / `skillUpgradeRequired`.
+
+### AgentWatch without TestChimp Studio
+
+```bash
+testchimp bot connect --project-id <id>       # browser approval (OAuth, "agentwatch" scope)
+npx -y @testchimp/agentwatch query --project-id <id>
+testchimp bot disconnect --project-id <id>    # forget the stored keys
+```
+
+Headless AgentWatch acts as the user, so it needs their user id, personal access key and the project API key. `bot connect` runs an OAuth 2.1 PKCE login with a loopback redirect, asks for the opt-in `agentwatch` scope (the consent page warns that keys will be stored locally), fetches the keys from `/bots/get_agentwatch_credentials`, and writes them to `~/.testchimp/agentwatch/credentials.json` (mode `0600`, keyed by project) with the backend and ingress URLs. It revokes the OAuth refresh token straight away and never prints the keys. Approving also opts the project in to AgentWatch.
+
+## Remote MCP (Streamable HTTP)
+
+```bash
+testchimp mcp --http [--port 8080] [--host 0.0.0.0]
+```
+
+Stateless Streamable HTTP at `POST /mcp`. Every request must carry `Authorization: Bearer <OAuth access token>`; the caller's token is forwarded to TestChimp for each tool call, and the server's own `TESTCHIMP_API_KEY` / `TESTCHIMP_OAUTH_TOKEN` / `TESTCHIMP_BOT_ID` are never used. Requests without a bearer get `401` with `WWW-Authenticate: Bearer resource_metadata="…"`. Other endpoints: `GET /.well-known/oauth-protected-resource` (RFC 9728 metadata), `GET /healthz`. Request bodies are capped at 1 MB.
+
+| Variable | Purpose |
+|---|---|
+| `PORT` | Listen port when `--port` is not given (default `8080`; Cloud Run sets it). |
+| `TESTCHIMP_MCP_PUBLIC_URL` | Public base URL of this server (e.g. `https://mcp.testchimp.io`); used for the protected-resource `resource` and `WWW-Authenticate`. Defaults to the request's forwarded proto + host. |
+| `TESTCHIMP_OAUTH_ISSUER` | Authorization server advertised in the metadata (default: `TESTCHIMP_BACKEND_URL`). |
+| `TESTCHIMP_BACKEND_URL` / `TESTCHIMP_INGRESS_URL` | Upstream TestChimp services. |
+
+The repository `Dockerfile` builds an image that runs `testchimp mcp --http` as a non-root user (Cloud Run ready):
+
+```bash
+docker build -t testchimp-mcp .
+docker run -p 8080:8080 -e TESTCHIMP_MCP_PUBLIC_URL=https://mcp.example.com testchimp-mcp
+```
+
 ## Migration from `testchimp-mcp-client`
 
 The npm package **`testchimp-mcp-client`** is superseded by **`@testchimp/cli`**. Update MCP `args` to `["-y", "@testchimp/cli@latest", "mcp"]` and rename tool references to **kebab-case**. See [MIGRATION.md](./MIGRATION.md).

package/dist/agentwatch/connect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `testchimp bot connect`: OAuth 2.1 (PKCE, loopback redirect) against the TestChimp authorization
+ * server with the opt-in `agentwatch` scope, then one call to `/bots/get_agentwatch_credentials` to
+ * fetch the user id, PAT and project API key, stored for headless AgentWatch. Nothing secret is
+ * printed; the refresh token is revoked straight away because the stored credentials replace it.
+ */
+import type { RegistryEnv } from "../workspace/projectsRegistry.js";
+export declare const AGENTWATCH_OAUTH_SCOPE = "testchimp agentwatch";
+export type ConnectOptions = {
+    backendUrl: string;
+    ingressUrl?: string;
+    /** When set, the project picked on the consent page must match. */
+    expectedProjectId?: string;
+    /** Loopback port for the redirect; 0 picks a free one. */
+    port?: number;
+    timeoutMs?: number;
+    /** Opens the consent URL; default launches the system browser. */
+    openUrl?: (url: string) => void | Promise<void>;
+    /** Progress lines (stderr in the CLI). */
+    log?: (line: string) => void;
+    env?: RegistryEnv;
+};
+export type ConnectResult = {
+    projectId: string;
+    userId: string;
+    email?: string;
+    botId?: string;
+    credentialsPath: string;
+};
+/**
+ * Ingress for a TestChimp SaaS backend (`featureservice[-env].testchimp.io` → `ingress[-env].testchimp.io`),
+ * so stored credentials never mix deployments. Undefined for other hosts.
+ */
+export declare function ingressUrlForBackend(backendUrl: string): string | undefined;
+/** Best-effort system browser launch; the URL is always printed too. */
+export declare function openInBrowser(url: string): void;
+export declare function connectAgentWatch(opts: ConnectOptions): Promise<ConnectResult>;

package/dist/agentwatch/connect.js

@@ -0,0 +1,250 @@
+/**
+ * `testchimp bot connect`: OAuth 2.1 (PKCE, loopback redirect) against the TestChimp authorization
+ * server with the opt-in `agentwatch` scope, then one call to `/bots/get_agentwatch_credentials` to
+ * fetch the user id, PAT and project API key, stored for headless AgentWatch. Nothing secret is
+ * printed; the refresh token is revoked straight away because the stored credentials replace it.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { saveProjectCredentials } from "./credentialsFile.js";
+export const AGENTWATCH_OAUTH_SCOPE = "testchimp agentwatch";
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Ingress for a TestChimp SaaS backend (`featureservice[-env].testchimp.io` → `ingress[-env].testchimp.io`),
+ * so stored credentials never mix deployments. Undefined for other hosts.
+ */
+export function ingressUrlForBackend(backendUrl) {
+    const url = new URL(backendUrl);
+    const m = /^featureservice(-[a-z0-9-]+)?\.testchimp\.io$/i.exec(url.hostname);
+    return m ? `https://ingress${m[1] ?? ""}.testchimp.io` : undefined;
+}
+function base64url(buf) {
+    return buf.toString("base64url");
+}
+function stringField(obj, key) {
+    const v = obj[key];
+    return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+async function readJson(res, what) {
+    const text = await res.text();
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        /* non-JSON error body */
+    }
+    if (!res.ok) {
+        const detail = stringField(body, "error_description") ??
+            stringField(body.responseHeader ?? {}, "errorMessage") ??
+            text.slice(0, 200);
+        throw new Error(`${what} failed (${res.status})${detail ? `: ${detail}` : ""}`);
+    }
+    return body;
+}
+async function discover(backendUrl) {
+    const res = await fetch(`${backendUrl}/.well-known/oauth-authorization-server`);
+    if (res.status === 404) {
+        throw new Error(`OAuth is not enabled on ${backendUrl}; bot connect needs a deployment with the TestChimp OAuth server`);
+    }
+    // RFC 8414 metadata field names.
+    const m = await readJson(res, "OAuth discovery");
+    const authorizationEndpoint = stringField(m, "authorization_endpoint");
+    const tokenEndpoint = stringField(m, "token_endpoint");
+    const registrationEndpoint = stringField(m, "registration_endpoint");
+    if (!authorizationEndpoint || !tokenEndpoint || !registrationEndpoint) {
+        throw new Error("OAuth discovery returned incomplete metadata");
+    }
+    return {
+        issuer: stringField(m, "issuer"),
+        authorizationEndpoint,
+        tokenEndpoint,
+        registrationEndpoint,
+        revocationEndpoint: stringField(m, "revocation_endpoint"),
+    };
+}
+async function registerClient(meta, redirectUri) {
+    // RFC 7591 client metadata field names.
+    const res = await fetch(meta.registrationEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: "TestChimp CLI (AgentWatch)",
+            redirect_uris: [redirectUri],
+            token_endpoint_auth_method: "none",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+        }),
+    });
+    const clientId = stringField(await readJson(res, "OAuth client registration"), "client_id");
+    if (!clientId)
+        throw new Error("OAuth client registration returned no client_id");
+    return clientId;
+}
+function listenForCallback(port, state, issuer) {
+    return new Promise((resolveListen, rejectListen) => {
+        let settle = null;
+        const callback = new Promise((resolve, reject) => {
+            settle = { resolve, reject };
+        });
+        // The browser can answer before the caller starts awaiting (e.g. while openUrl is still running).
+        callback.catch(() => undefined);
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const page = (title, body) => {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+                res.end(`<!doctype html><title>${title}</title><body style="font-family:sans-serif;padding:2rem"><h2>${title}</h2><p>${body}</p></body>`);
+            };
+            const error = url.searchParams.get("error");
+            if (url.searchParams.get("state") !== state) {
+                page("TestChimp connection failed", "The response did not match this login attempt. Run testchimp bot connect again.");
+                settle?.reject(new Error("OAuth state mismatch"));
+                return;
+            }
+            const iss = url.searchParams.get("iss");
+            if (issuer && iss && iss !== issuer) {
+                page("TestChimp connection failed", "Unexpected authorization server.");
+                settle?.reject(new Error(`OAuth issuer mismatch: ${iss}`));
+                return;
+            }
+            if (error) {
+                const denied = error === "access_denied";
+                page(denied ? "Connection denied" : "TestChimp connection failed", denied ? "You can close this tab." : "You can close this tab and check the terminal.");
+                settle?.reject(new Error(denied ? "The user denied access" : `OAuth error: ${error} ${url.searchParams.get("error_description") ?? ""}`.trim()));
+                return;
+            }
+            const code = url.searchParams.get("code");
+            if (!code) {
+                page("TestChimp connection failed", "No authorization code was returned.");
+                settle?.reject(new Error("OAuth callback carried no code"));
+                return;
+            }
+            page("Connected to TestChimp", "AgentWatch credentials are being saved. You can close this tab.");
+            settle?.resolve({ code });
+        });
+        server.once("error", rejectListen);
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", rejectListen);
+            const actual = server.address().port;
+            resolveListen({ server, redirectUri: `http://127.0.0.1:${actual}/callback`, callback });
+        });
+    });
+}
+/** Best-effort system browser launch; the URL is always printed too. */
+export function openInBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        /* printed URL is the fallback */
+    }
+}
+function withTimeout(p, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Timed out after ${Math.round(ms / 1000)}s waiting for browser approval`)), ms);
+    });
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+export async function connectAgentWatch(opts) {
+    const log = opts.log ?? (() => undefined);
+    const meta = await discover(opts.backendUrl);
+    const state = base64url(randomBytes(16));
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    const { server, redirectUri, callback } = await listenForCallback(opts.port ?? 0, state, meta.issuer);
+    try {
+        const clientId = await registerClient(meta, redirectUri);
+        const authorize = new URL(meta.authorizationEndpoint);
+        authorize.search = new URLSearchParams({
+            response_type: "code",
+            client_id: clientId,
+            redirect_uri: redirectUri,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+            state,
+            scope: AGENTWATCH_OAUTH_SCOPE,
+        }).toString();
+        log(`Open this URL to approve AgentWatch access (pick the project, tick "Use this connection as my QA bot"):`);
+        log(authorize.toString());
+        await (opts.openUrl ?? openInBrowser)(authorize.toString());
+        const { code } = await withTimeout(callback, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        // RFC 6749 token request / response field names.
+        const tokenRes = await fetch(meta.tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code,
+                client_id: clientId,
+                redirect_uri: redirectUri,
+                code_verifier: verifier,
+            }).toString(),
+        });
+        const tokens = await readJson(tokenRes, "OAuth token exchange");
+        const accessToken = stringField(tokens, "access_token");
+        const refreshToken = stringField(tokens, "refresh_token");
+        if (!accessToken)
+            throw new Error("OAuth token exchange returned no access_token");
+        try {
+            const granted = (stringField(tokens, "scope") ?? "").split(/\s+/);
+            if (!granted.includes("agentwatch")) {
+                throw new Error("This deployment did not grant the agentwatch scope; upgrade TestChimp or use TestChimp Studio sign-in");
+            }
+            const credsRes = await fetch(`${opts.backendUrl}/bots/get_agentwatch_credentials`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}` },
+                body: "{}",
+            });
+            const creds = await readJson(credsRes, "Fetching AgentWatch credentials");
+            const projectId = stringField(creds, "projectId");
+            const userId = stringField(creds, "userId");
+            const userAuthKey = stringField(creds, "userAuthKey");
+            const projectApiKey = stringField(creds, "projectApiKey");
+            if (!projectId || !userId || !userAuthKey || !projectApiKey) {
+                throw new Error("AgentWatch credentials response was incomplete");
+            }
+            if (opts.expectedProjectId && opts.expectedProjectId !== projectId) {
+                throw new Error(`Approved project ${projectId} does not match --project-id ${opts.expectedProjectId}; run bot connect again and pick the right project`);
+            }
+            const email = stringField(creds, "email");
+            const botId = stringField(creds, "botId");
+            const credentialsPath = saveProjectCredentials(projectId, {
+                userId,
+                ...(email ? { email } : {}),
+                userAuthKey,
+                projectApiKey,
+                ...(botId ? { botId } : {}),
+                backendUrl: opts.backendUrl,
+                ...(opts.ingressUrl ? { ingressUrl: opts.ingressUrl } : {}),
+                savedAtMillis: Date.now(),
+            }, opts.env);
+            return { projectId, userId, ...(email ? { email } : {}), ...(botId ? { botId } : {}), credentialsPath };
+        }
+        finally {
+            if (refreshToken && meta.revocationEndpoint) {
+                await fetch(meta.revocationEndpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: new URLSearchParams({ token: refreshToken }).toString(),
+                }).catch(() => undefined);
+            }
+        }
+    }
+    finally {
+        server.closeAllConnections?.();
+        server.close();
+    }
+}

package/dist/agentwatch/connect.test.d.ts

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

package/dist/agentwatch/connect.test.js

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { connectAgentWatch, ingressUrlForBackend } from "./connect.js";
+import { agentwatchCredentialsPath, readAgentwatchCredentials, removeProjectCredentials, saveProjectCredentials, } from "./credentialsFile.js";
+function body(req) {
+    return new Promise((resolve) => {
+        let data = "";
+        req.on("data", (c) => (data += c));
+        req.on("end", () => resolve(data));
+    });
+}
+async function startFakeAuthServer(opts = {}) {
+    const fake = { url: "", server: createServer(), authorizeScopes: [], revoked: [] };
+    let challenge = "";
+    let redirectUri = "";
+    fake.server.on("request", async (req, res) => {
+        const url = new URL(req.url ?? "/", fake.url);
+        const json = (status, value) => {
+            res.writeHead(status, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(value));
+        };
+        if (url.pathname === "/.well-known/oauth-authorization-server") {
+            return json(200, {
+                issuer: fake.url,
+                authorization_endpoint: `${fake.url}/oauth/authorize`,
+                token_endpoint: `${fake.url}/oauth/token`,
+                registration_endpoint: `${fake.url}/oauth/register`,
+                revocation_endpoint: `${fake.url}/oauth/revoke`,
+            });
+        }
+        if (url.pathname === "/oauth/register") {
+            redirectUri = JSON.parse(await body(req)).redirect_uris[0];
+            return json(201, { client_id: "client-1" });
+        }
+        if (url.pathname === "/oauth/authorize") {
+            fake.authorizeScopes.push(url.searchParams.get("scope") ?? "");
+            challenge = url.searchParams.get("code_challenge") ?? "";
+            const back = new URL(url.searchParams.get("redirect_uri") ?? redirectUri);
+            back.searchParams.set("state", url.searchParams.get("state") ?? "");
+            back.searchParams.set("iss", fake.url);
+            if (opts.deny)
+                back.searchParams.set("error", "access_denied");
+            else
+                back.searchParams.set("code", "code-1");
+            res.writeHead(302, { Location: back.toString() });
+            return res.end();
+        }
+        if (url.pathname === "/oauth/token") {
+            const form = new URLSearchParams(await body(req));
+            const expected = createHash("sha256").update(form.get("code_verifier") ?? "").digest("base64url");
+            if (form.get("code") !== "code-1" || expected !== challenge || form.get("redirect_uri") !== redirectUri) {
+                return json(400, { error: "invalid_grant", error_description: "bad exchange" });
+            }
+            return json(200, {
+                access_token: "access-1",
+                refresh_token: "refresh-1",
+                token_type: "Bearer",
+                scope: opts.grantedScope ?? "testchimp agentwatch",
+            });
+        }
+        if (url.pathname === "/bots/get_agentwatch_credentials") {
+            if (req.headers.authorization !== "Bearer access-1")
+                return json(401, {});
+            return json(200, {
+                projectId: opts.projectId ?? "proj-1",
+                userId: "user-1",
+                email: "dev@example.com",
+                userAuthKey: "pat-0123456789",
+                projectApiKey: "key-0123456789",
+                botId: "bot-1",
+            });
+        }
+        if (url.pathname === "/oauth/revoke") {
+            fake.revoked.push(new URLSearchParams(await body(req)).get("token") ?? "");
+            return json(200, {});
+        }
+        json(404, {});
+    });
+    await new Promise((r) => fake.server.listen(0, "127.0.0.1", () => r()));
+    fake.url = `http://127.0.0.1:${fake.server.address().port}`;
+    return fake;
+}
+/** Plays the browser: follows the consent redirect back to the CLI's loopback callback. */
+async function browser(url) {
+    await fetch(url);
+}
+describe("bot connect (AgentWatch credentials)", () => {
+    let home;
+    let fake = null;
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "tc-aw-"));
+    });
+    afterEach(() => {
+        fake?.server.close();
+        fake = null;
+        rmSync(home, { recursive: true, force: true });
+    });
+    it("requests the agentwatch scope, stores user id / PAT / API key at 0600 and revokes the refresh token", async () => {
+        fake = await startFakeAuthServer();
+        const result = await connectAgentWatch({
+            backendUrl: fake.url,
+            ingressUrl: "https://ingress.testchimp.io",
+            openUrl: browser,
+            env: { home },
+        });
+        assert.deepEqual(result, {
+            projectId: "proj-1",
+            userId: "user-1",
+            email: "dev@example.com",
+            botId: "bot-1",
+            credentialsPath: agentwatchCredentialsPath({ home }),
+        });
+        assert.deepEqual(fake.authorizeScopes, ["testchimp agentwatch"]);
+        assert.deepEqual(fake.revoked, ["refresh-1"]);
+        const stored = readAgentwatchCredentials({ home })?.projects["proj-1"];
+        assert.equal(stored?.userId, "user-1");
+        assert.equal(stored?.userAuthKey, "pat-0123456789");
+        assert.equal(stored?.projectApiKey, "key-0123456789");
+        assert.equal(stored?.botId, "bot-1");
+        assert.equal(stored?.backendUrl, fake.url);
+        if (process.platform !== "win32") {
+            assert.equal(statSync(agentwatchCredentialsPath({ home })).mode & 0o777, 0o600);
+        }
+    });
+    it("refuses a project other than --project-id and stores nothing", async () => {
+        fake = await startFakeAuthServer({ projectId: "proj-2" });
+        await assert.rejects(connectAgentWatch({ backendUrl: fake.url, expectedProjectId: "proj-1", openUrl: browser, env: { home } }), /does not match --project-id proj-1/);
+        assert.equal(readAgentwatchCredentials({ home }), null);
+        assert.deepEqual(fake.revoked, ["refresh-1"]);
+    });
+    it("fails clearly when the deployment does not grant the agentwatch scope", async () => {
+        fake = await startFakeAuthServer({ grantedScope: "testchimp" });
+        await assert.rejects(connectAgentWatch({ backendUrl: fake.url, openUrl: browser, env: { home } }), /did not grant the agentwatch scope/);
+        assert.equal(readAgentwatchCredentials({ home }), null);
+    });
+    it("reports a denied consent", async () => {
+        fake = await startFakeAuthServer({ deny: true });
+        await assert.rejects(connectAgentWatch({ backendUrl: fake.url, openUrl: browser, env: { home } }), /denied access/);
+    });
+    it("derives the ingress of the same SaaS deployment", () => {
+        assert.equal(ingressUrlForBackend("https://featureservice.testchimp.io"), "https://ingress.testchimp.io");
+        assert.equal(ingressUrlForBackend("https://featureservice-staging.testchimp.io/"), "https://ingress-staging.testchimp.io");
+        assert.equal(ingressUrlForBackend("http://localhost:8080"), undefined);
+    });
+    it("keeps other projects when saving and removes the file with the last project", () => {
+        const entry = (userId) => ({
+            userId,
+            userAuthKey: "pat-0123456789",
+            projectApiKey: "key-0123456789",
+            backendUrl: "https://featureservice.testchimp.io",
+            savedAtMillis: 1,
+        });
+        saveProjectCredentials("a", entry("u1"), { home });
+        saveProjectCredentials("b", entry("u2"), { home });
+        assert.deepEqual(Object.keys(readAgentwatchCredentials({ home })?.projects ?? {}).sort(), ["a", "b"]);
+        assert.equal(removeProjectCredentials("a", { home }), true);
+        assert.equal(removeProjectCredentials("a", { home }), false);
+        assert.equal(removeProjectCredentials("b", { home }), true);
+        assert.equal(readAgentwatchCredentials({ home }), null);
+    });
+});

package/dist/agentwatch/credentialsFile.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Local AgentWatch credentials in `~/.testchimp/agentwatch/credentials.json` (TESTCHIMP_HOME honoured).
+ *
+ * Written by `testchimp bot connect`, read by headless AgentWatch (desktop
+ * `src/main/auth/agentwatchCredentials.ts`) so it runs without TestChimp Studio sign-in. Keyed by
+ * project because the API key is per project. Holds the user's PAT: directory 0700, file 0600.
+ */
+import { z } from "zod";
+import { type RegistryEnv } from "../workspace/projectsRegistry.js";
+export declare const AgentwatchProjectCredentialsSchema: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    userAuthKey: z.ZodString;
+    projectApiKey: z.ZodString;
+    botId: z.ZodOptional<z.ZodString>;
+    backendUrl: z.ZodString;
+    ingressUrl: z.ZodOptional<z.ZodString>;
+    savedAtMillis: z.ZodNumber;
+}, z.core.$loose>;
+export type AgentwatchProjectCredentials = z.infer<typeof AgentwatchProjectCredentialsSchema>;
+export declare const AgentwatchCredentialsFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projects: z.ZodRecord<z.ZodString, z.ZodObject<{
+        userId: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        userAuthKey: z.ZodString;
+        projectApiKey: z.ZodString;
+        botId: z.ZodOptional<z.ZodString>;
+        backendUrl: z.ZodString;
+        ingressUrl: z.ZodOptional<z.ZodString>;
+        savedAtMillis: z.ZodNumber;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type AgentwatchCredentialsFile = z.infer<typeof AgentwatchCredentialsFileSchema>;
+export declare function agentwatchCredentialsPath(env?: RegistryEnv): string;
+/** Parsed file, or null when missing / unreadable / another schema. */
+export declare function readAgentwatchCredentials(env?: RegistryEnv): AgentwatchCredentialsFile | null;
+export declare function saveProjectCredentials(projectId: string, creds: AgentwatchProjectCredentials, env?: RegistryEnv): string;
+/** True when an entry was removed. Deletes the file once no project is left. */
+export declare function removeProjectCredentials(projectId: string, env?: RegistryEnv): boolean;