@testchimp/cli 0.1.84 → 0.1.85

package/dist/workspace/projectsRegistry.js

@@ -0,0 +1,246 @@
+/**
+ * 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 { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, normalize, resolve } from "node:path";
+import { z } from "zod";
+// Loose objects: fields written by a newer Studio survive a CLI rewrite.
+export const WorkspaceFolderSchema = z.looseObject({
+    id: z.string().min(1),
+    path: z.string().min(1),
+    name: z.string().optional(),
+});
+export const WorkspaceMappingSchema = z.looseObject({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    projectName: z.string().optional(),
+    folders: z.array(WorkspaceFolderSchema).min(0),
+    createdAtMillis: z.number().int().nonnegative(),
+    lastOpenedAtMillis: z.number().int().nonnegative(),
+    browserStartUrl: z.string().url().optional(),
+});
+export const ProjectsRegistrySchema = z.looseObject({
+    schemaVersion: z.literal(2),
+    activeWorkspaceId: z.string().nullable(),
+    mappings: z.array(WorkspaceMappingSchema),
+});
+const EMPTY = { schemaVersion: 2, activeWorkspaceId: null, mappings: [] };
+export function getTestchimpHome(env = {}) {
+    if (env.home)
+        return env.home;
+    const override = process.env.TESTCHIMP_HOME?.trim();
+    if (override)
+        return override;
+    return join(homedir(), ".testchimp");
+}
+export function projectsRegistryPath(env = {}) {
+    return join(getTestchimpHome(env), "projects.json");
+}
+function nowOf(env) {
+    return env.now ? env.now() : Date.now();
+}
+function idOf(env) {
+    return env.newId ? env.newId() : randomUUID();
+}
+function ensureHome(env) {
+    const home = getTestchimpHome(env);
+    if (!existsSync(home))
+        mkdirSync(home, { recursive: true, mode: 0o700 });
+}
+/** Serialized bytes exactly as written to disk (2-space JSON + trailing newline). */
+export function serializeRegistry(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function writeJsonAtomic(path, value, env, mode = 0o600) {
+    ensureHome(env);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, serializeRegistry(value), { mode });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Real absolute directory path (follows symlinks); same error codes as Studio. */
+export function canonicalizePath(input) {
+    const trimmed = String(input || "").trim();
+    if (!trimmed)
+        throw new Error("PATH_ESCAPE: empty path");
+    const absolute = isAbsolute(trimmed) ? normalize(trimmed) : resolve(trimmed);
+    if (!existsSync(absolute))
+        throw new Error("NOT_FOUND: path does not exist");
+    if (!statSync(absolute).isDirectory())
+        throw new Error("INVALID_PAYLOAD: path is not a directory");
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        throw new Error("PATH_ESCAPE: cannot resolve real path");
+    }
+}
+function folderNameFromPath(path) {
+    return basename(path) || path;
+}
+/** v1 → v2: single rootPath becomes folders[0]. */
+function migrateRawRegistry(raw, env) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const obj = raw;
+    if (obj.schemaVersion === 2)
+        return raw;
+    if (obj.schemaVersion !== 1 || !Array.isArray(obj.mappings))
+        return raw;
+    const mappings = obj.mappings.map((m) => {
+        if (!m || typeof m !== "object")
+            return m;
+        const row = m;
+        if (Array.isArray(row.folders))
+            return row;
+        const rootPath = typeof row.rootPath === "string" ? row.rootPath : "";
+        return {
+            id: row.id,
+            projectId: row.projectId,
+            projectName: row.projectName,
+            folders: rootPath ? [{ id: idOf(env), path: rootPath, name: folderNameFromPath(rootPath) }] : [],
+            createdAtMillis: row.createdAtMillis,
+            lastOpenedAtMillis: row.lastOpenedAtMillis,
+        };
+    });
+    return { schemaVersion: 2, activeWorkspaceId: obj.activeWorkspaceId ?? null, mappings };
+}
+function quarantine(env) {
+    const target = join(getTestchimpHome(env), `projects.invalid.${nowOf(env)}.json`);
+    renameSync(projectsRegistryPath(env), target);
+    return target;
+}
+/**
+ * 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 function readProjectsRegistry(env = {}) {
+    ensureHome(env);
+    const path = projectsRegistryPath(env);
+    if (!existsSync(path)) {
+        writeJsonAtomic(path, EMPTY, env);
+        return { ...EMPTY, mappings: [] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        quarantine(env);
+        writeJsonAtomic(path, EMPTY, env);
+        return { ...EMPTY, mappings: [] };
+    }
+    const parsed = ProjectsRegistrySchema.safeParse(migrateRawRegistry(raw, env));
+    if (!parsed.success) {
+        quarantine(env);
+        writeJsonAtomic(path, EMPTY, env);
+        return { ...EMPTY, mappings: [] };
+    }
+    if (raw.schemaVersion !== 2) {
+        writeJsonAtomic(path, parsed.data, env);
+    }
+    return parsed.data;
+}
+/** Side-effect-free lookup for `workspace get` (never creates, migrates, or quarantines). */
+export function findWorkspaceMapping(projectId, env = {}) {
+    const path = projectsRegistryPath(env);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`INVALID_REGISTRY: ${path} is not valid JSON`);
+    }
+    const migrated = migrateRawRegistry(raw, { ...env, newId: () => "migrated" });
+    const parsed = ProjectsRegistrySchema.safeParse(migrated);
+    if (!parsed.success)
+        throw new Error(`INVALID_REGISTRY: ${path} does not match schema v2`);
+    return parsed.data.mappings.find((m) => m.projectId === projectId) ?? null;
+}
+function saveRegistry(registry, env) {
+    const next = ProjectsRegistrySchema.parse(registry);
+    writeJsonAtomic(projectsRegistryPath(env), next, env);
+    return next;
+}
+function conflictIn(registry, projectId, root) {
+    for (const m of registry.mappings) {
+        if (m.projectId === projectId)
+            continue;
+        if (m.folders.some((f) => f.path === root)) {
+            return { projectId: m.projectId, ...(m.projectName ? { projectName: m.projectName } : {}) };
+        }
+    }
+    return null;
+}
+/** Remove `root` from every mapping that is not `projectId`; drop empty rows. */
+function stripFolderFromOtherProjects(mappings, projectId, root) {
+    return mappings
+        .map((m) => {
+        if (m.projectId === projectId)
+            return m;
+        if (!m.folders.some((f) => f.path === root))
+            return m;
+        return { ...m, folders: m.folders.filter((f) => f.path !== root) };
+    })
+        .filter((m) => m.projectId === projectId || m.folders.length > 0);
+}
+/**
+ * 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 function upsertWorkspaceFolder(input, env = {}) {
+    const root = canonicalizePath(input.rootPath);
+    const reg = readProjectsRegistry(env);
+    const conflict = conflictIn(reg, input.projectId, root);
+    if (conflict && !input.reassign) {
+        throw new Error(`INVALID_PAYLOAD: folder already mapped to project ${conflict.projectId}`);
+    }
+    let baseMappings = reg.mappings;
+    if (conflict && input.reassign) {
+        baseMappings = stripFolderFromOtherProjects(baseMappings, input.projectId, root);
+    }
+    const now = nowOf(env);
+    const existing = baseMappings.find((m) => m.projectId === input.projectId);
+    let mapping;
+    let mappings;
+    if (existing) {
+        const already = existing.folders.find((f) => f.path === root);
+        const folders = already
+            ? existing.folders.map((f) => (f.path === root ? { ...f, path: root, name: f.name || folderNameFromPath(root) } : f))
+            : [...existing.folders, { id: idOf(env), path: root, name: folderNameFromPath(root) }];
+        mapping = {
+            ...existing,
+            projectName: input.projectName ?? existing.projectName,
+            folders,
+            lastOpenedAtMillis: now,
+        };
+        mappings = baseMappings.map((m) => (m.id === existing.id ? mapping : m));
+    }
+    else {
+        mapping = {
+            id: idOf(env),
+            projectId: input.projectId,
+            projectName: input.projectName,
+            folders: [{ id: idOf(env), path: root, name: folderNameFromPath(root) }],
+            createdAtMillis: now,
+            lastOpenedAtMillis: now,
+        };
+        mappings = [...baseMappings, mapping];
+    }
+    const saved = saveRegistry({ ...reg, schemaVersion: 2, activeWorkspaceId: mapping.id, mappings }, env);
+    return saved.mappings.find((m) => m.id === mapping.id);
+}

package/dist/workspace/projectsRegistry.test.d.ts

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

package/dist/workspace/projectsRegistry.test.js

@@ -0,0 +1,249 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertFolderMatchesRepo, inspectLocalGitRepo, normalizeGitRemoteToFullName } from "./gitRepo.js";
+import { findWorkspaceMapping, ProjectsRegistrySchema, projectsRegistryPath, readProjectsRegistry, upsertWorkspaceFolder, } from "./projectsRegistry.js";
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const fixturesDir = join(repoRoot, "fixtures", "projects-registry");
+const desktopFixturesDir = process.env.TESTCHIMP_DESKTOP_FIXTURES_DIR ??
+    resolve(repoRoot, "..", "AwareRepo", "desktop", "src", "main", "workspace", "__fixtures__", "projectsRegistry");
+const cliBin = join(repoRoot, "dist", "bin", "testchimp.js");
+const sequenceFile = JSON.parse(readFileSync(join(fixturesDir, "sequences.json"), "utf8"));
+function listFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listFiles(full));
+        else
+            out.push(relative(fixturesDir, full));
+    }
+    return out;
+}
+function withRoot(text, root) {
+    return text.split("__ROOT__").join(JSON.stringify(root).slice(1, -1));
+}
+function readFixture(rel, root) {
+    return withRoot(readFileSync(join(fixturesDir, rel), "utf8"), root);
+}
+function makeScratch() {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "tc-projects-registry-")));
+    const home = join(base, "home");
+    const root = join(base, "work");
+    mkdirSync(home);
+    mkdirSync(root);
+    for (const f of sequenceFile.folders)
+        mkdirSync(join(root, f));
+    return { home, root };
+}
+function idSource() {
+    let n = 0;
+    return () => sequenceFile.idPattern.replace("{n12}", String(++n).padStart(12, "0"));
+}
+describe("projects.json fixtures parse with the CLI schema", () => {
+    const root = "/fixture-root";
+    for (const rel of listFiles(join(fixturesDir, "valid")).concat(listFiles(join(fixturesDir, "edge")))) {
+        it(`accepts ${rel}`, () => {
+            assert.equal(ProjectsRegistrySchema.safeParse(JSON.parse(readFixture(rel, root))).success, true);
+        });
+    }
+    for (const rel of listFiles(join(fixturesDir, "invalid"))) {
+        it(`rejects ${rel}`, () => {
+            assert.equal(ProjectsRegistrySchema.safeParse(JSON.parse(readFixture(rel, root))).success, false);
+        });
+    }
+    for (const rel of listFiles(join(fixturesDir, "expected"))) {
+        it(`accepts writer output ${rel} (incl. Studio's)`, () => {
+            assert.equal(ProjectsRegistrySchema.safeParse(JSON.parse(readFixture(rel, root))).success, true);
+        });
+    }
+});
+describe("upsert sequences produce the contract bytes", () => {
+    for (const seq of sequenceFile.sequences) {
+        it(seq.name, () => {
+            const { home, root } = makeScratch();
+            try {
+                let step = 0;
+                const env = {
+                    home,
+                    newId: idSource(),
+                    now: () => sequenceFile.clock.startMillis + step * sequenceFile.clock.stepMillis,
+                };
+                const registryPath = projectsRegistryPath(env);
+                let initialBytes = null;
+                if (seq.initial) {
+                    initialBytes = readFixture(seq.initial, root);
+                    writeFileSync(registryPath, initialBytes);
+                }
+                for (; step < seq.steps.length; step++) {
+                    const s = seq.steps[step];
+                    const input = { projectId: s.projectId, projectName: s.projectName, rootPath: join(root, s.folder), reassign: s.reassign };
+                    if (s.expectError) {
+                        const before = readFileSync(registryPath, "utf8");
+                        assert.throws(() => upsertWorkspaceFolder(input, env), (e) => e.message.includes(s.expectError));
+                        assert.equal(readFileSync(registryPath, "utf8"), before);
+                    }
+                    else {
+                        upsertWorkspaceFolder(input, env);
+                    }
+                }
+                const actual = readFileSync(registryPath, "utf8");
+                const expectedRel = seq.expectedCli ?? seq.expected;
+                if (process.env.UPDATE_PROJECTS_REGISTRY_FIXTURES === "1") {
+                    writeFileSync(join(fixturesDir, expectedRel), actual.split(JSON.stringify(root).slice(1, -1)).join("__ROOT__"));
+                }
+                assert.equal(actual, readFixture(expectedRel, root));
+                assert.equal(statSync(registryPath).mode & 0o777, 0o600);
+                const quarantined = readdirSync(home).filter((f) => /^projects\.invalid\.\d+\.json$/.test(f));
+                if (seq.expectQuarantine) {
+                    assert.equal(quarantined.length, 1);
+                    assert.equal(readFileSync(join(home, quarantined[0]), "utf8"), initialBytes);
+                }
+                else {
+                    assert.deepEqual(quarantined, []);
+                }
+            }
+            finally {
+                rmSync(dirname(home), { recursive: true, force: true });
+            }
+        });
+    }
+});
+describe("fixture copy in TestChimp Studio (desktop) is byte-identical", () => {
+    it("matches every file", { skip: existsSync(desktopFixturesDir) ? false : `no desktop checkout at ${desktopFixturesDir}` }, () => {
+        const ours = listFiles(fixturesDir).sort();
+        const theirs = (function walk(dir) {
+            const out = [];
+            for (const e of readdirSync(dir, { withFileTypes: true })) {
+                const full = join(dir, e.name);
+                if (e.isDirectory())
+                    out.push(...walk(full));
+                else
+                    out.push(relative(desktopFixturesDir, full));
+            }
+            return out;
+        })(desktopFixturesDir).sort();
+        assert.deepEqual(theirs, ours);
+        for (const rel of ours) {
+            assert.equal(readFileSync(join(desktopFixturesDir, rel), "utf8"), readFileSync(join(fixturesDir, rel), "utf8"), rel);
+        }
+    });
+});
+describe("registry read edge cases", () => {
+    let scratch;
+    beforeEach(() => {
+        scratch = makeScratch();
+    });
+    afterEach(() => {
+        rmSync(dirname(scratch.home), { recursive: true, force: true });
+    });
+    it("quarantines an unparseable file instead of discarding it", () => {
+        const env = { home: scratch.home, now: () => 42 };
+        writeFileSync(projectsRegistryPath(env), "{not json");
+        assert.deepEqual(readProjectsRegistry(env).mappings, []);
+        assert.equal(readFileSync(join(scratch.home, "projects.invalid.42.json"), "utf8"), "{not json");
+    });
+    it("findWorkspaceMapping is read-only", () => {
+        const env = { home: scratch.home };
+        assert.equal(findWorkspaceMapping("p1", env), null);
+        assert.equal(existsSync(projectsRegistryPath(env)), false);
+        writeFileSync(projectsRegistryPath(env), "{not json");
+        assert.throws(() => findWorkspaceMapping("p1", env), /INVALID_REGISTRY/);
+        assert.equal(readFileSync(projectsRegistryPath(env), "utf8"), "{not json");
+    });
+    it("honours TESTCHIMP_HOME", () => {
+        const prev = process.env.TESTCHIMP_HOME;
+        process.env.TESTCHIMP_HOME = scratch.home;
+        try {
+            upsertWorkspaceFolder({ projectId: "p1", rootPath: join(scratch.root, "repo-a") });
+            assert.equal(findWorkspaceMapping("p1")?.folders[0]?.path, join(scratch.root, "repo-a"));
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.TESTCHIMP_HOME;
+            else
+                process.env.TESTCHIMP_HOME = prev;
+        }
+    });
+    it("rejects a missing folder", () => {
+        assert.throws(() => upsertWorkspaceFolder({ projectId: "p1", rootPath: join(scratch.root, "nope") }, { home: scratch.home }), /NOT_FOUND/);
+    });
+});
+function git(cwd, ...args) {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+    assert.equal(r.status, 0, r.stderr);
+}
+describe("git validation", () => {
+    let scratch;
+    beforeEach(() => {
+        scratch = makeScratch();
+    });
+    afterEach(() => {
+        rmSync(dirname(scratch.home), { recursive: true, force: true });
+    });
+    it("normalizes remotes like Studio", () => {
+        assert.equal(normalizeGitRemoteToFullName("git@github.com:Acme/Shop.git"), "Acme/Shop");
+        assert.equal(normalizeGitRemoteToFullName("https://github.com/Acme/Shop.git"), "Acme/Shop");
+        assert.equal(normalizeGitRemoteToFullName("ssh://git@gitlab.com/group/sub/repo"), "group/sub/repo");
+    });
+    it("rejects non-git folders, sub-folders and mismatched remotes", () => {
+        const repo = join(scratch.root, "repo-a");
+        assert.throws(() => assertFolderMatchesRepo(inspectLocalGitRepo(repo), null), /NOT_A_GIT_REPO/);
+        git(repo, "init", "-q");
+        git(repo, "remote", "add", "origin", "git@github.com:acme/shop.git");
+        assertFolderMatchesRepo(inspectLocalGitRepo(repo), null);
+        assertFolderMatchesRepo(inspectLocalGitRepo(repo), "Acme/Shop");
+        assert.throws(() => assertFolderMatchesRepo(inspectLocalGitRepo(repo), "acme/other"), /REPO_MISMATCH/);
+        const sub = join(repo, "pkg");
+        mkdirSync(sub);
+        assert.throws(() => assertFolderMatchesRepo(inspectLocalGitRepo(sub), "acme/shop"), /NOT_REPO_ROOT/);
+    });
+});
+describe("testchimp workspace map|get (CLI)", () => {
+    let scratch;
+    beforeEach(() => {
+        scratch = makeScratch();
+    });
+    afterEach(() => {
+        rmSync(dirname(scratch.home), { recursive: true, force: true });
+    });
+    function cli(...args) {
+        const env = { ...process.env, TESTCHIMP_HOME: scratch.home };
+        delete env.TESTCHIMP_API_KEY;
+        delete env.TESTCHIMP_OAUTH_TOKEN;
+        return spawnSync(process.execPath, [cliBin, ...args], { env, encoding: "utf8" });
+    }
+    it("maps a git repo, prints it, and enforces the conflict rule", () => {
+        const repo = join(scratch.root, "repo-a");
+        git(repo, "init", "-q");
+        const unmapped = cli("workspace", "get", "--project-id", "p1");
+        assert.equal(unmapped.status, 1);
+        const mapped = cli("workspace", "map", "--project-id", "p1", "--folder", repo, "--project-name", "One");
+        assert.equal(mapped.status, 0, mapped.stderr);
+        assert.match(mapped.stderr, /skipping connected-repository check/);
+        const mapping = JSON.parse(mapped.stdout);
+        assert.equal(mapping.projectId, "p1");
+        assert.equal(mapping.projectName, "One");
+        assert.equal(mapping.folders[0]?.path, repo);
+        assert.equal(statSync(join(scratch.home, "projects.json")).mode & 0o777, 0o600);
+        const got = cli("workspace", "get", "--project-id", "p1");
+        assert.equal(got.status, 0, got.stderr);
+        assert.deepEqual(JSON.parse(got.stdout), mapping);
+        const conflict = cli("workspace", "map", "--project-id", "p2", "--folder", repo);
+        assert.equal(conflict.status, 1);
+        assert.match(conflict.stderr, /already mapped to project p1/);
+        const reassigned = cli("workspace", "map", "--project-id", "p2", "--folder", repo, "--reassign");
+        assert.equal(reassigned.status, 0, reassigned.stderr);
+        assert.equal(cli("workspace", "get", "--project-id", "p1").status, 1);
+    });
+    it("refuses a folder that is not a git repo", () => {
+        const r = cli("workspace", "map", "--project-id", "p1", "--folder", join(scratch.root, "repo-b"));
+        assert.equal(r.status, 1);
+        assert.match(r.stderr, /NOT_A_GIT_REPO/);
+        assert.equal(existsSync(join(scratch.home, "projects.json")), false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.84",
+  "version": "0.1.85",
   "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test dist/core/client.test.js dist/core/tools.test.js dist/chimphands/llmRetryProxy.test.js dist/chimphands/midTurnSteering.test.js dist/chimphands/steeringSidecar.test.js dist/chimphands/agentBranch.test.js dist/chimphands/worktreeCommitPaths.test.js",
+    "test": "npm run build && node --test dist/core/client.test.js dist/core/tools.test.js dist/mcp/httpServer.test.js dist/workspace/projectsRegistry.test.js dist/agentwatch/connect.test.js dist/chimphands/llmRetryProxy.test.js dist/chimphands/midTurnSteering.test.js dist/chimphands/steeringSidecar.test.js dist/chimphands/agentBranch.test.js dist/chimphands/worktreeCommitPaths.test.js",
     "watch": "tsc --watch",
     "start": "node dist/bin/testchimp.js",
     "prepublishOnly": "npm run build"