@testchimp/cli 0.1.84 → 0.1.86

package/dist/agentwatch/credentialsFile.js

@@ -0,0 +1,76 @@
+/**
+ * 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 { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { getTestchimpHome } from "../workspace/projectsRegistry.js";
+export const AgentwatchProjectCredentialsSchema = z.looseObject({
+    userId: z.string().min(1),
+    email: z.string().optional(),
+    userAuthKey: z.string().min(8),
+    projectApiKey: z.string().min(8),
+    botId: z.string().optional(),
+    backendUrl: z.string().url(),
+    ingressUrl: z.string().url().optional(),
+    savedAtMillis: z.number().int().nonnegative(),
+});
+export const AgentwatchCredentialsFileSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    projects: z.record(z.string(), AgentwatchProjectCredentialsSchema),
+});
+export function agentwatchCredentialsPath(env = {}) {
+    return join(getTestchimpHome(env), "agentwatch", "credentials.json");
+}
+/** Parsed file, or null when missing / unreadable / another schema. */
+export function readAgentwatchCredentials(env = {}) {
+    const path = agentwatchCredentialsPath(env);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = AgentwatchCredentialsFileSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeAtomic(file, env) {
+    const path = agentwatchCredentialsPath(env);
+    const dir = join(getTestchimpHome(env), "agentwatch");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows ignores POSIX modes.
+    }
+}
+export function saveProjectCredentials(projectId, creds, env = {}) {
+    const entry = AgentwatchProjectCredentialsSchema.parse(creds);
+    const file = readAgentwatchCredentials(env) ?? { schemaVersion: 1, projects: {} };
+    file.projects[projectId] = entry;
+    writeAtomic(file, env);
+    return agentwatchCredentialsPath(env);
+}
+/** True when an entry was removed. Deletes the file once no project is left. */
+export function removeProjectCredentials(projectId, env = {}) {
+    const file = readAgentwatchCredentials(env);
+    if (!file || !(projectId in file.projects))
+        return false;
+    delete file.projects[projectId];
+    if (Object.keys(file.projects).length === 0) {
+        unlinkSync(agentwatchCredentialsPath(env));
+    }
+    else {
+        writeAtomic(file, env);
+    }
+    return true;
+}

package/dist/agentwatch/pairing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `testchimp bot connect --pair` / `--finish-pair`: AgentWatch credentials without a second browser consent.
+ *
+ * Start keeps a random verifier in `~/.testchimp/agentwatch/pairing.json` (0600) and prints the pairing code
+ * BASE64URL(SHA-256(verifier)). The QA bot approves that code with its own OAuth token
+ * (`approve-agentwatch-pairing`, needs the consent-page "set up AgentWatch" opt-in). Finish redeems with the
+ * verifier at `/bots/redeem_agentwatch_pairing` and stores the keys like `bot connect`. The bot only ever
+ * sees the pairing code, which is useless without the verifier on this computer.
+ */
+import { type RegistryEnv } from "../workspace/projectsRegistry.js";
+import type { ConnectResult } from "./connect.js";
+/** Matches the server's pairing TTL. */
+export declare const PAIRING_TTL_MS: number;
+export type StartPairingOptions = {
+    backendUrl: string;
+    ingressUrl?: string;
+    expectedProjectId?: string;
+    env?: RegistryEnv;
+};
+export type StartPairingResult = {
+    pairingCode: string;
+    expiresAtMillis: number;
+};
+export type FinishPairingOptions = {
+    /** When set, must match the backend the pairing was started against. */
+    backendUrl?: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    env?: RegistryEnv;
+};
+export declare function pendingPairingPath(env?: RegistryEnv): string;
+export declare function pairingCodeFor(verifier: string): string;
+/** Replaces any earlier pending pairing on this computer. */
+export declare function startAgentWatchPairing(opts: StartPairingOptions): StartPairingResult;
+/** Polls until the bot has approved the pending pairing, then stores the credentials and removes the pending file. */
+export declare function finishAgentWatchPairing(opts?: FinishPairingOptions): Promise<ConnectResult>;

package/dist/agentwatch/pairing.js

@@ -0,0 +1,161 @@
+/**
+ * `testchimp bot connect --pair` / `--finish-pair`: AgentWatch credentials without a second browser consent.
+ *
+ * Start keeps a random verifier in `~/.testchimp/agentwatch/pairing.json` (0600) and prints the pairing code
+ * BASE64URL(SHA-256(verifier)). The QA bot approves that code with its own OAuth token
+ * (`approve-agentwatch-pairing`, needs the consent-page "set up AgentWatch" opt-in). Finish redeems with the
+ * verifier at `/bots/redeem_agentwatch_pairing` and stores the keys like `bot connect`. The bot only ever
+ * sees the pairing code, which is useless without the verifier on this computer.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { getTestchimpHome } from "../workspace/projectsRegistry.js";
+import { saveProjectCredentials } from "./credentialsFile.js";
+/** Matches the server's pairing TTL. */
+export const PAIRING_TTL_MS = 10 * 60_000;
+const DEFAULT_FINISH_TIMEOUT_MS = 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const PendingPairingSchema = z.looseObject({
+    verifier: z.string().min(43),
+    pairingCode: z.string().length(43),
+    backendUrl: z.string().url(),
+    ingressUrl: z.string().url().optional(),
+    expectedProjectId: z.string().optional(),
+    createdAtMillis: z.number().int().nonnegative(),
+});
+export function pendingPairingPath(env = {}) {
+    return join(getTestchimpHome(env), "agentwatch", "pairing.json");
+}
+export function pairingCodeFor(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+function writePending(pending, env) {
+    const path = pendingPairingPath(env);
+    mkdirSync(join(getTestchimpHome(env), "agentwatch"), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(pending, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows ignores POSIX modes.
+    }
+}
+function readPending(env) {
+    const path = pendingPairingPath(env);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = PendingPairingSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function clearPending(env) {
+    try {
+        unlinkSync(pendingPairingPath(env));
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Replaces any earlier pending pairing on this computer. */
+export function startAgentWatchPairing(opts) {
+    const verifier = randomBytes(32).toString("base64url");
+    const pairingCode = pairingCodeFor(verifier);
+    const createdAtMillis = Date.now();
+    writePending({
+        verifier,
+        pairingCode,
+        backendUrl: opts.backendUrl,
+        ...(opts.ingressUrl ? { ingressUrl: opts.ingressUrl } : {}),
+        ...(opts.expectedProjectId ? { expectedProjectId: opts.expectedProjectId } : {}),
+        createdAtMillis,
+    }, opts.env ?? {});
+    return { pairingCode, expiresAtMillis: createdAtMillis + PAIRING_TTL_MS };
+}
+function stringField(obj, key) {
+    const v = obj[key];
+    return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+async function redeem(backendUrl, verifier) {
+    const res = await fetch(`${backendUrl}/bots/redeem_agentwatch_pairing`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ codeVerifier: verifier }),
+    });
+    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.responseHeader ?? {}, "errorMessage") ?? text.slice(0, 200);
+        if (res.status === 404) {
+            throw new Error("This TestChimp deployment does not support AgentWatch pairing yet; use testchimp bot connect (browser)");
+        }
+        throw new Error(`Redeeming the AgentWatch pairing failed (${res.status})${detail ? `: ${detail}` : ""}`);
+    }
+    const creds = body.credentials;
+    return creds && typeof creds === "object" ? creds : null;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Polls until the bot has approved the pending pairing, then stores the credentials and removes the pending file. */
+export async function finishAgentWatchPairing(opts = {}) {
+    const env = opts.env ?? {};
+    const pending = readPending(env);
+    if (!pending) {
+        throw new Error("No pending AgentWatch pairing on this computer. Run: testchimp bot connect --pair");
+    }
+    if (Date.now() > pending.createdAtMillis + PAIRING_TTL_MS) {
+        clearPending(env);
+        throw new Error("The AgentWatch pairing expired. Run: testchimp bot connect --pair");
+    }
+    if (opts.backendUrl && opts.backendUrl !== pending.backendUrl) {
+        throw new Error(`The pending pairing was started against ${pending.backendUrl}, not ${opts.backendUrl}. Run testchimp bot connect --pair again`);
+    }
+    const deadline = Date.now() + (opts.timeoutMs ?? DEFAULT_FINISH_TIMEOUT_MS);
+    const interval = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    let creds = null;
+    for (;;) {
+        creds = await redeem(pending.backendUrl, pending.verifier);
+        if (creds || Date.now() + interval > deadline)
+            break;
+        await sleep(interval);
+    }
+    if (!creds) {
+        throw new Error(`The pairing code ${pending.pairingCode} has not been approved yet. Ask your QA bot to approve it, then run testchimp bot connect --finish-pair again`);
+    }
+    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");
+    }
+    clearPending(env);
+    if (pending.expectedProjectId && pending.expectedProjectId !== projectId) {
+        throw new Error(`The bot approved project ${projectId}, not ${pending.expectedProjectId}; nothing was stored. Connect the bot to the right project and pair again`);
+    }
+    const email = stringField(creds, "email");
+    const botId = stringField(creds, "botId");
+    const credentialsPath = saveProjectCredentials(projectId, {
+        userId,
+        ...(email ? { email } : {}),
+        userAuthKey,
+        projectApiKey,
+        ...(botId ? { botId } : {}),
+        backendUrl: pending.backendUrl,
+        ...(pending.ingressUrl ? { ingressUrl: pending.ingressUrl } : {}),
+        savedAtMillis: Date.now(),
+    }, env);
+    return { projectId, userId, ...(email ? { email } : {}), ...(botId ? { botId } : {}), credentialsPath };
+}

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

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

package/dist/agentwatch/pairing.test.js

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { existsSync, 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 { readAgentwatchCredentials } from "./credentialsFile.js";
+import { finishAgentWatchPairing, pairingCodeFor, pendingPairingPath, startAgentWatchPairing } from "./pairing.js";
+async function startFakeBackend(projectId = "proj-1") {
+    const approved = new Set();
+    const redeemed = new Set();
+    const fake = {
+        url: "",
+        server: createServer(),
+        approve: (code) => approved.add(code),
+        redeemCalls: 0,
+    };
+    fake.server.on("request", (req, res) => {
+        let data = "";
+        req.on("data", (c) => (data += c));
+        req.on("end", () => {
+            if (req.url !== "/bots/redeem_agentwatch_pairing") {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            fake.redeemCalls++;
+            const code = pairingCodeFor(JSON.parse(data).codeVerifier);
+            if (!approved.has(code) || redeemed.has(code)) {
+                res.end(JSON.stringify({ pending: true }));
+                return;
+            }
+            redeemed.add(code);
+            res.end(JSON.stringify({
+                credentials: {
+                    projectId,
+                    userId: "user-1",
+                    email: "a@b.c",
+                    userAuthKey: "pat-123456789",
+                    projectApiKey: "key-123456789",
+                    botId: "bot-1",
+                },
+            }));
+        });
+    });
+    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;
+}
+describe("AgentWatch pairing", () => {
+    let home;
+    let fake;
+    let env;
+    beforeEach(async () => {
+        home = mkdtempSync(join(tmpdir(), "aw-pair-"));
+        env = { home };
+        fake = await startFakeBackend();
+    });
+    afterEach(() => {
+        fake.server.close();
+        rmSync(home, { recursive: true, force: true });
+    });
+    it("stores credentials once the bot approves, and keeps the verifier private", async () => {
+        const started = startAgentWatchPairing({ backendUrl: fake.url, expectedProjectId: "proj-1", env });
+        assert.match(started.pairingCode, /^[A-Za-z0-9_-]{43}$/);
+        if (process.platform !== "win32") {
+            assert.equal(statSync(pendingPairingPath(env)).mode & 0o777, 0o600);
+        }
+        await assert.rejects(finishAgentWatchPairing({ backendUrl: fake.url, timeoutMs: 50, pollIntervalMs: 10, env }), /has not been approved yet/);
+        fake.approve(started.pairingCode);
+        const result = await finishAgentWatchPairing({ backendUrl: fake.url, timeoutMs: 1000, pollIntervalMs: 10, env });
+        assert.deepEqual({ projectId: result.projectId, userId: result.userId, botId: result.botId }, { projectId: "proj-1", userId: "user-1", botId: "bot-1" });
+        const stored = readAgentwatchCredentials(env).projects["proj-1"];
+        assert.equal(stored.userAuthKey, "pat-123456789");
+        assert.equal(stored.backendUrl, fake.url);
+        assert.equal(existsSync(pendingPairingPath(env)), false);
+        await assert.rejects(finishAgentWatchPairing({ backendUrl: fake.url, env }), /No pending AgentWatch pairing/);
+    });
+    it("stores nothing when the bot approved another project", async () => {
+        const started = startAgentWatchPairing({ backendUrl: fake.url, expectedProjectId: "proj-2", env });
+        fake.approve(started.pairingCode);
+        await assert.rejects(finishAgentWatchPairing({ backendUrl: fake.url, timeoutMs: 1000, pollIntervalMs: 10, env }), /approved project proj-1, not proj-2/);
+        assert.equal(readAgentwatchCredentials(env), null);
+    });
+    it("refuses to finish against a different backend", async () => {
+        startAgentWatchPairing({ backendUrl: fake.url, env });
+        await assert.rejects(finishAgentWatchPairing({ backendUrl: "https://featureservice.testchimp.io", env }), /was started against/);
+        assert.equal(fake.redeemCalls, 0);
+    });
+});

package/dist/cli/program.d.ts

@@ -1,4 +1,6 @@
 import { Command } from "commander";
 import { PACKAGE_VERSION } from "../core/version.js";
 export { PACKAGE_VERSION };
+/** Numeric x.y.z comparison; prerelease / build suffixes are ignored. */
+export declare function compareSemver(a: string, b: string): number;
 export declare function buildCliProgram(): Command;