in2-agent-server 0.20260821.185429

package/dist/cli.js

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+// The `in2` CLI — setup, check, update, diagnose, from outside the MCP session.
+//
+// WHY THIS EXISTS SEPARATELY FROM THE MCP TOOLS
+//
+// update_server lives inside the server, which makes it convenient and makes it useless in exactly
+// the situations that matter most:
+//
+//   - a server that fails to start has no tools at all, so nothing in-session can diagnose it
+//   - a broken install needs a way back that does not depend on the thing that broke
+//
+// Distribution is npm (`npm install -g in2-agent-server`), so `in2 update` is a thin wrapper over
+// `npm install -g` — the reason it exists at all is that the operator should never need to know
+// the package name, and `in2 doctor` should be one word to say on a support call. `in2 setup` is
+// what replaced ~1000 lines of platform-forked installer shell: everything after "get Node and run
+// npm install" lives here, in one language, testable, shipping with the thing it installs.
+//
+// Claude reaches this through Bash, which means it keeps working when MCP does not.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { IN2_HOME, PACKAGE_NAME, SERVER_ROOT, installedVersion, isNpmInstall } from "./core/install.js";
+import { checkForUpdate, installUpdate, npmInvocation } from "./core/update.js";
+import { sfInvocation } from "./core/spawn.js";
+import { WORKSPACE_ROOT } from "./core/paths.js";
+const argv = process.argv.slice(2);
+const command = argv[0] ?? "help";
+const flag = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+};
+const has = (name) => argv.includes(`--${name}`);
+const out = (s = "") => {
+    process.stdout.write(`${s}\n`);
+};
+const die = (s) => {
+    process.stderr.write(`${s}\n`);
+    return process.exit(1);
+};
+async function cmdVersion() {
+    out(installedVersion());
+}
+const DEFAULT_LAUNCH_URL = "https://in2-launch.onrender.com";
+/**
+ * Everything a fresh machine needs after `npm install -g in2-agent-server`, in one command.
+ *
+ * The npm install put THIS CLI on a PATH somewhere; what is left is the machine setup the old
+ * platform-forked installers did in ~1000 lines of bash/PowerShell:
+ *   1. the Salesforce CLI — the server shells out to `sf` for every deploy; installed into a
+ *      private prefix under ~/.in2-agent/tools when absent, so no machine ever needs sudo
+ *   2. the Claude Code registration — server env is fixed at spawn, so every gate the run needs
+ *      travels on the registration, not on a shell profile
+ *   3. skills + agents into ~/.claude (the server re-syncs these at every start; doing it here too
+ *      means the FIRST conversation already has them)
+ *   4. a real JSON-RPC probe, because "registered" and "starts" are different claims
+ *
+ * Idempotent: re-running repairs a registration, re-syncs assets, and skips what already works.
+ */
+async function cmdSetup() {
+    const launchUrl = flag("launch-url") ?? DEFAULT_LAUNCH_URL;
+    const serverEntry = path.join(SERVER_ROOT, "dist", "index.js");
+    // 1. Salesforce CLI. System `sf` wins; otherwise a private npm-prefix install under IN2_HOME.
+    //
+    // The private path is probed and registered by its JS ENTRY, never through PATH. Two live-caught
+    // reasons (adversarial review, 2026-08-21): sfInvocation memoizes its Windows PATH scan, so a
+    // probe taken before the install poisons every probe after it; and a PATH mutated in THIS
+    // process reaches neither the server (spawned by the MCP client with its own env) nor the next
+    // `in2 setup` run. CC_MCP_SF_ENTRY on the registration env is the one channel that reliably
+    // reaches the server, on every platform — spawn.ts honors it ahead of any PATH resolution.
+    out("checking for the Salesforce CLI…");
+    const toolsDir = path.join(IN2_HOME, "tools");
+    const privateSfEntry = path.join(toolsDir, "node_modules", "@salesforce", "cli", "bin", "run.js");
+    const entryWorks = (entry) => {
+        try {
+            execFileSync(process.execPath, [entry, "--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const systemSfWorks = () => {
+        try {
+            const sf = sfInvocation(["--version"]);
+            execFileSync(sf.command, sf.args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    let sfEntry;
+    if (await fs
+        .stat(privateSfEntry)
+        .then(() => entryWorks(privateSfEntry))
+        .catch(() => false)) {
+        // A previous setup already installed it privately — reuse, and re-register the entry.
+        sfEntry = privateSfEntry;
+    }
+    else if (!systemSfWorks()) {
+        out("installing @salesforce/cli (the slow step: ~150 MB down, ~576 MB on disk)…");
+        await fs.mkdir(toolsDir, { recursive: true });
+        const npm = npmInvocation(["install", "--prefix", toolsDir, "@salesforce/cli", "--no-audit", "--no-fund"]);
+        execFileSync(npm.command, npm.args, { stdio: "inherit", timeout: 1_800_000 });
+        // Verified by running the entry we just installed — not by re-resolving PATH, which would
+        // consult sfInvocation's pre-install cache and report a working install as broken.
+        if (!entryWorks(privateSfEntry)) {
+            die("the Salesforce CLI did not install cleanly — re-run `in2 setup`, or install `sf` yourself and retry.");
+        }
+        sfEntry = privateSfEntry;
+    }
+    out(`  ok — sf is available${sfEntry ? " (private install under ~/.in2-agent/tools)" : ""}`);
+    // 2. Register with Claude Code, idempotently (remove-then-add; remove of a missing entry is fine).
+    //
+    // The env rides the REGISTRATION because MCP server env is fixed at spawn: CC_MCP_LAUNCH_URL is
+    // what lets activate_session redeem a code; the two write gates are capabilities whose per-org
+    // AUTHORITY still comes from activation grants; CC_MCP_BETA=1 keeps the feedback channel with
+    // the install. CC_MCP_DIRECT_ALLOWLIST is deliberately never set — on a consultant machine it
+    // would make their other clients' orgs writable.
+    //
+    // The command registered is `<this node> <absolute dist/index.js>`: the package path is stable
+    // across `npm install -g` updates (same prefix), and naming the node binary dodges every PATH
+    // difference between a login shell and however the client spawns servers.
+    out("registering with Claude Code…");
+    const resolved = await resolveClaude();
+    const claude = resolved ??
+        die("Claude Code's `claude` CLI was not found. Install it (https://claude.ai/install.sh), then re-run `in2 setup`.");
+    const env = [
+        ["CC_MCP_LAUNCH_URL", launchUrl],
+        ["CC_MCP_DIRECT_WRITE", "1"],
+        ["CC_MCP_CAMPFIRE_WRITE", "1"],
+        ["CC_MCP_BETA", "1"],
+        // On EVERY platform, not only Windows: a private sf install is off the server's PATH by
+        // construction, and this env var is how the server finds it (spawn.ts checks it first).
+        ...(sfEntry ? [["CC_MCP_SF_ENTRY", sfEntry]] : [])
+    ];
+    // Through cmd.exe on Windows when the resolved claude is a shim (a .cmd cannot be spawned
+    // directly); direct everywhere else. None of the argv values here carry user-typed content, so
+    // cmd.exe's re-tokenization is safe in a way it is not for sf's SOQL-bearing arguments.
+    const claudeCall = (args) => process.platform === "win32" && !claude.toLowerCase().endsWith(".exe")
+        ? ["cmd.exe", ["/d", "/c", claude, ...args]]
+        : [claude, args];
+    try {
+        const [cmd, args] = claudeCall(["mcp", "remove", "in2", "-s", "user"]);
+        execFileSync(cmd, args, { stdio: "ignore" });
+    }
+    catch {
+        // Not registered yet — the normal first-run case.
+    }
+    {
+        const [cmd, args] = claudeCall([
+            "mcp",
+            "add",
+            "in2",
+            "-s",
+            "user",
+            ...env.flatMap(([k, v]) => ["-e", `${k}=${v}`]),
+            "--",
+            process.execPath,
+            serverEntry
+        ]);
+        execFileSync(cmd, args, { stdio: "inherit" });
+    }
+    // 3. Skills + agents now, not just at first server start.
+    const { installClaudeAssets } = await import("./core/claudeAssets.js");
+    await installClaudeAssets();
+    out("  ok — skills and agents installed to ~/.claude");
+    // 4. Prove it starts. Same probe as the doctor; a registration that cannot answer initialize is
+    // a setup that failed, and this is the moment to say so.
+    out("verifying the server starts…");
+    const started = await probeServer(serverEntry);
+    if (!started)
+        die("the server did not answer an MCP initialize — run `in2 doctor` for the breakdown.");
+    out("  ok — server answers");
+    out("");
+    out("Setup complete. Open a NEW Claude Code conversation and paste your activation prompt.");
+}
+/** The `claude` binary, probed at its real install locations — a non-interactive shell's PATH may miss it. */
+async function resolveClaude() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const candidates = process.platform === "win32"
+        ? ["claude.exe", path.join(home, ".local", "bin", "claude.exe")]
+        : ["claude", path.join(home, ".local", "bin", "claude"), "/usr/local/bin/claude", "/opt/homebrew/bin/claude"];
+    for (const candidate of candidates) {
+        try {
+            execFileSync(candidate, ["--version"], { stdio: "ignore" });
+            return candidate;
+        }
+        catch {
+            // keep probing
+        }
+    }
+    // An npm-installed Claude Code on Windows is claude.cmd + claude.ps1, no .exe anywhere — and a
+    // cmd shim cannot be spawned directly (CVE-2024-27980, same constraint spawn.ts documents for
+    // sf.cmd). Probe it through cmd.exe; the registration itself then also runs through cmd.exe.
+    if (process.platform === "win32") {
+        try {
+            execFileSync("cmd.exe", ["/d", "/c", "claude", "--version"], { stdio: "ignore" });
+            return "claude";
+        }
+        catch {
+            // truly absent
+        }
+    }
+    return undefined;
+}
+async function cmdCheck() {
+    const check = await checkForUpdate(flag("registry"));
+    if (has("json")) {
+        out(JSON.stringify(check, null, 2));
+        // Exit 1 signals "an update is available" so a script can branch without parsing prose.
+        process.exit(check.updateAvailable ? 1 : 0);
+    }
+    out(`installed : ${check.currentVersion}`);
+    out(`published : ${check.latestVersion ?? "unknown"}`);
+    out(check.updateAvailable ? "an update is available — run: in2 update" : "up to date");
+    if (check.reason)
+        out(`note      : ${check.reason}`);
+    process.exit(check.updateAvailable ? 1 : 0);
+}
+async function cmdUpdate() {
+    const current = installedVersion();
+    const result = await installUpdate({
+        force: has("force"),
+        ...(flag("registry") ? { registry: flag("registry") } : {})
+    });
+    if (!result.ok) {
+        if (result.failure === "not-managed") {
+            die(`Not an npm install (running from ${SERVER_ROOT}).\nA repo checkout updates with git pull; anything else, reinstall with: npm install -g ${PACKAGE_NAME}`);
+        }
+        die(`update failed: ${result.error ?? "unknown error"} — nothing was changed; still on ${current}.`);
+    }
+    if (!result.updated) {
+        out(`already on ${current}; published version is ${result.toVersion}. Nothing to do.`);
+        return;
+    }
+    out(`installed ${result.toVersion} (was ${current})`);
+    // Said plainly because it is the difference between "done" and "done, and you lost your session".
+    out("An MCP server already running does NOT pick this up — a NEW conversation runs the new version.");
+}
+// Everything that has to be true for a session to work, checked in the order it would break.
+// Written because the failure it diagnoses is otherwise invisible: the server registers fine and
+// then fails on first use, in a new conversation, with no obvious cause.
+async function cmdDoctor() {
+    const problems = [];
+    const check = (label, okay, detail = "") => {
+        out(`${okay ? "  ok  " : "  FAIL"} ${label}${detail ? ` — ${detail}` : ""}`);
+        if (!okay)
+            problems.push(label);
+    };
+    out(`IN2 home  : ${IN2_HOME}`);
+    out(`install   : ${installedVersion()} from ${SERVER_ROOT}`);
+    out("");
+    check("npm-managed install", isNpmInstall(), isNpmInstall() ? "" : "a checkout updates with git, not in2 update");
+    // npm resolvable — it is the whole update path now.
+    let npmOk = false;
+    let npmVersion = "";
+    try {
+        const npm = npmInvocation(["--version"]);
+        npmVersion = execFileSync(npm.command, npm.args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+            .split("\n")[0]
+            .trim();
+        npmOk = true;
+    }
+    catch {
+        npmOk = false;
+    }
+    check("npm reachable", npmOk, npmVersion ? `npm ${npmVersion}` : "updates need it");
+    // The server shells out to `sf` for every deploy and every Campfire read/write.
+    let sfOk = false;
+    let sfVersion = "";
+    try {
+        const sf = sfInvocation(["--version"]);
+        sfVersion = execFileSync(sf.command, sf.args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+            .split("\n")[0]
+            .trim();
+        sfOk = true;
+    }
+    catch {
+        sfOk = false;
+    }
+    check("Salesforce CLI reachable", sfOk, sfVersion || "every deploy and writeback needs it");
+    const entry = path.join(SERVER_ROOT, "dist", "index.js");
+    const entryExists = await fs
+        .stat(entry)
+        .then(() => true)
+        .catch(() => false);
+    check("server entry present", entryExists, entry);
+    if (entryExists) {
+        check("server starts and answers", await probeServer(entry));
+    }
+    const update = await checkForUpdate();
+    out("");
+    out(update.updateAvailable
+        ? `An update is available: ${update.currentVersion} -> ${update.latestVersion}. Run: in2 update`
+        : `Version ${update.currentVersion}${update.latestVersion ? " (latest)" : ""}${update.reason ? ` — ${update.reason}` : ""}`);
+    if (problems.length > 0) {
+        out("");
+        die(`${problems.length} problem(s): ${problems.join("; ")}`);
+    }
+}
+// The only check that proves the server actually works rather than merely looks right: spawn it
+// and complete an MCP initialize round-trip. stdin must STAY OPEN until the response arrives — a
+// probe that writes the request and closes immediately loses a race on Windows (the transport sees
+// EOF and shuts down before the async initialize dispatch flushes; live-caught in CI).
+async function probeServer(entry) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [entry], { stdio: ["pipe", "pipe", "ignore"] });
+        let buf = "";
+        let settled = false;
+        const settle = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill();
+            }
+            catch {
+                /* already gone */
+            }
+            resolve(v);
+        };
+        const timer = setTimeout(() => settle(false), 60_000);
+        timer.unref();
+        child.stdout.on("data", (d) => {
+            buf += String(d);
+            if (buf.includes('"result"')) {
+                clearTimeout(timer);
+                try {
+                    child.stdin.end(); // now EOF — the server exits on its own
+                }
+                catch {
+                    /* stream already closed */
+                }
+                settle(true);
+            }
+        });
+        child.on("error", () => {
+            clearTimeout(timer);
+            settle(false);
+        });
+        child.on("exit", () => {
+            clearTimeout(timer);
+            settle(buf.includes('"result"'));
+        });
+        child.stdin.write(`${JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "in2-doctor", version: "0" } }
+        })}\n`);
+    });
+}
+/**
+ * Re-materialize one org's mirror from every evidence bundle this machine can reach.
+ *
+ * OUT OF PROCESS ON PURPOSE, like everything else here: the mirror is a rebuildable cache derived
+ * from the bundles, and the case that needs rebuilding is precisely the case where the RULE for
+ * reading a bundle changed under an existing history — an install that has already committed waves
+ * under the old rule keeps them until something replays them. Nothing in a live session should be
+ * rewriting history underneath a conversation that may be quoting it.
+ *
+ * `--fetch` IS OPT-IN, and that is a deliberate choice about what this command is. Without it the
+ * command is a local repair that touches no network and needs no grant; with it, it is the
+ * convergence step (R24) — this machine's bundles united with the parcels other machines uploaded
+ * for the same org, replayed into one history. Either way the result SAYS WHICH, because a
+ * local-only history and an org-wide one look identical from the outside and only one of them
+ * supports "this is what happened in this org".
+ *
+ * Safe to run at any time and safe to run twice: same bundles in, same history out.
+ */
+async function cmdRebuildMirror() {
+    const orgId = argv[1];
+    if (!orgId)
+        die("usage: in2 rebuild-mirror <orgId> [--fetch [--batch <batchId>]]");
+    const { mirrorPath, rebuildFromSets, workspaceBundleDirs } = await import("./direct/orgRepo.js");
+    const bundles = await workspaceBundleDirs();
+    out(`workspace : ${WORKSPACE_ROOT}`);
+    out(`bundles   : ${bundles.length} local`);
+    // The fetch runs BEFORE the "nothing to rebuild from" bail: an install that has never delivered
+    // to this org still has an org history to materialize once another machine's parcels arrive, and
+    // refusing on an empty local set would make that machine permanently unable to see it.
+    let foreign;
+    if (has("fetch")) {
+        const { fetchForeignBundles } = await import("./core/parcels.js");
+        const batchId = flag("batch");
+        const fetched = await fetchForeignBundles({
+            orgId: orgId,
+            ...(batchId ? { batchId } : {}),
+            log: (line) => out(`            ${line}`)
+        });
+        out(fetched.ok
+            ? `parcels   : ${fetched.listed} listed, ${fetched.downloaded} downloaded, ${fetched.cached} already staged, ${fetched.failed} failed`
+            : `parcels   : NOT FETCHED — ${fetched.unavailable}`);
+        for (const problem of fetched.problems.slice(0, 10))
+            out(`            ! ${problem}`);
+        foreign = fetched.ok
+            ? { dirs: fetched.bundles.map((bundle) => bundle.bundleDir), ...(fetched.failed > 0 ? { missing: fetched.failed } : {}) }
+            : { dirs: [], unavailable: fetched.unavailable ?? "the parcel fetch did not complete" };
+    }
+    if (bundles.length === 0 && (foreign?.dirs.length ?? 0) === 0) {
+        die("no evidence bundles found — nothing to rebuild from. Check the workspace path above.");
+    }
+    const result = await rebuildFromSets(orgId, bundles, foreign);
+    out(`mirror    : ${mirrorPath(orgId)}`);
+    out(`waves     : ${result.local} local, ${result.foreign} foreign`);
+    // Fewer commits than waves is the rule working, not a loss: a wave that re-delivered unchanged
+    // content leaves the tree alone and records nothing (R2).
+    out(`commits   : ${result.commits}`);
+    out(`skipped   : ${result.skipped} bundle(s) — another org, or a verdict that never changed this one`);
+    // Its own line, never folded into `skipped`: a skip is coverage this mirror correctly does not
+    // hold, and an unreadable parcel is coverage it is MISSING. The scope note says the same thing in
+    // sentences; this says it in the count, next to the counts it must not be mistaken for.
+    if (result.unreadable > 0) {
+        out(`unreadable: ${result.unreadable} fetched parcel(s) staged but NOT readable as a wave — waves may be missing`);
+    }
+    if (result.duplicates > 0)
+        out(`duplicate : ${result.duplicates} wave(s) present both locally and as a parcel — replayed once`);
+    out(`head      : ${result.head ?? "(no wave commits)"}`);
+    if (result.materializerMismatch) {
+        out(`rebuilt   : the previous mirror carried ${result.priorMaterializers.join(", ")} — every commit has been re-derived under this build`);
+    }
+    out("");
+    out(`scope     : ${result.scope.note}`);
+    out("");
+    out("Every commit id in this mirror is NEW — a rebuild rewrites them by design. Read history through");
+    out("direct_history and address a wave by (session, wave), never by a commit id.");
+}
+try {
+    switch (command) {
+        case "version":
+            await cmdVersion();
+            break;
+        case "setup":
+            await cmdSetup();
+            break;
+        case "check":
+            await cmdCheck();
+            break;
+        case "update":
+            await cmdUpdate();
+            break;
+        case "doctor":
+            await cmdDoctor();
+            break;
+        case "rebuild-mirror":
+            await cmdRebuildMirror();
+            break;
+        default:
+            out("in2 — manage the IN2 MCP server install");
+            out("");
+            out("  in2 setup [--launch-url URL]            first-time machine setup: sf CLI, Claude Code registration, skills");
+            out("  in2 check [--json]                      is a newer version published on npm? (exit 1 = yes)");
+            out("  in2 update [--force]                    npm install -g the published version");
+            out("  in2 doctor                              check everything a session needs, and say what is broken");
+            out("  in2 version                             print the installed version");
+            out("  in2 rebuild-mirror <orgId> [--fetch]    re-derive an org's history from its evidence bundles");
+            out("                                          --fetch also pulls other machines' parcels for that org");
+            out("");
+            out("An update never changes a conversation already running — start a NEW conversation to use it.");
+    }
+}
+catch (error) {
+    die(`in2 ${command}: ${error instanceof Error ? error.message : String(error)}`);
+}