mergestorm 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# mergestorm CLI
+
+Review a local git diff with MergeStorm without opening a GitHub PR — for local loops and CI. Diffs are reviewed by the same engine as PR reviews and each review consumes one standard credit.
+
+Requires **Node.js 22+**.
+
+## Install
+
+One-liner (installs the global `mergestorm` binary, then sign in via your browser):
+
+```bash
+curl -fsSL https://mergestorm.ai/install.sh | bash
+mergestorm login
+```
+
+Or install directly with npm:
+
+```bash
+npm install -g mergestorm
+mergestorm login
+```
+
+### From this monorepo (development)
+
+```bash
+npm run build --workspace=mergestorm
+node packages/mergestorm-cli/dist/cli.js <command>
+# or skip the build during dev (runs src/cli.ts via tsx):
+npm run dev --workspace=mergestorm -- <command>
+```
+
+## Commands
+
+```
+mergestorm login                 Sign in via browser; stores an API key in ~/.mergestorm/config.json
+mergestorm login --key           Paste an existing API key instead (headless/CI)
+mergestorm logout                Remove the stored API key
+mergestorm review [base] [head]  Review git diff base...head (default: main...HEAD)
+mergestorm status <job_id>       Poll a review job and print its result
+```
+
+### `login`
+
+Runs a browser device-authorization flow: prints a short code, opens `https://mergestorm.ai/cli/auth`, and — once you approve — mints and stores an API key in `~/.mergestorm/config.json` (mode `600`). No key copy/paste needed.
+
+For headless or CI environments, use `mergestorm login --key` to paste an existing `msk_live_…` key (create one on the dashboard [Account page](https://mergestorm.ai/dashboard/account) → **API keys**).
+
+### `logout`
+
+Removes `~/.mergestorm/config.json` so the stored key is no longer used.
+
+### `review [base] [head]`
+
+Collects `git diff base...head` (default `main...HEAD`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), auto-attaches context from `./.mergestorm/**/*.md|*.txt`, submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings.
+
+```bash
+mergestorm review              # main...HEAD
+mergestorm review develop      # develop...HEAD
+mergestorm review main feat/x  # main...feat/x
+```
+
+Exit code is non-zero on quota limit (402), submission failure, a `failed`/`quota_exceeded` job, or a poll timeout.
+
+### `status <job_id>`
+
+Fetches a job by id and prints the raw JSON (status, verdict, summary, findings).
+
+## Context pack (`.mergestorm/`)
+
+Any `*.md` / `*.txt` files under `./.mergestorm/` (one level of nesting) are attached as context so the reviewer understands intent, conventions, or migration notes without you resending history.
+
+## Environment
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `MERGESTORM_API_KEY` | API key (overrides the stored config) | — |
+| `MERGESTORM_API_URL` | API base URL | `https://api.mergestorm.ai` |
+
+## See also
+
+- [Review Jobs API reference](../../docs/review-jobs-api.md) — raw HTTP endpoints, webhook signing, thread chains, quota.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { mkdir, readFile, writeFile, rm, readdir, stat } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+const DEFAULT_API = "https://api.mergestorm.ai";
+const CONTEXT_DIR = ".mergestorm";
+function configPath() {
+    return path.join(homedir(), ".mergestorm", "config.json");
+}
+async function loadConfig() {
+    try {
+        const raw = await readFile(configPath(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function saveConfig(cfg) {
+    const dir = path.dirname(configPath());
+    await mkdir(dir, { recursive: true });
+    await writeFile(configPath(), JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+}
+function apiBase(cfg) {
+    return (process.env.MERGESTORM_API_URL?.trim() || cfg.apiBase || DEFAULT_API).replace(/\/$/, "");
+}
+async function apiFetch(cfg, route, init = {}) {
+    const key = process.env.MERGESTORM_API_KEY?.trim() || cfg.apiKey;
+    if (!key) {
+        throw new Error("No API key. Run `mergestorm login` or set MERGESTORM_API_KEY.");
+    }
+    const headers = {
+        Authorization: `Bearer ${key}`,
+        ...init.headers,
+    };
+    let body = init.body;
+    if (init.json !== undefined) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(init.json);
+    }
+    const res = await fetch(`${apiBase(cfg)}${route}`, { ...init, headers, body });
+    const text = await res.text();
+    let parsed = text;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // keep text
+    }
+    return { status: res.status, body: parsed };
+}
+function git(args, cwd = process.cwd()) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    if (result.status !== 0) {
+        throw new Error(result.stderr?.trim() || `git ${args.join(" ")} failed`);
+    }
+    return result.stdout;
+}
+async function collectContextFiles(root) {
+    const pack = path.join(root, CONTEXT_DIR);
+    let entries;
+    try {
+        entries = await readdir(pack, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        if (entry.isFile() && (entry.name.toLowerCase().endsWith(".md") || entry.name.toLowerCase().endsWith(".txt"))) {
+            const content = await readFile(path.join(pack, entry.name), "utf8");
+            files.push({ path: entry.name, content });
+        }
+        else if (entry.isDirectory() && !entry.name.startsWith(".")) {
+            const nested = await readdir(path.join(pack, entry.name), { withFileTypes: true }).catch(() => []);
+            for (const child of nested) {
+                if (child.isFile() && (child.name.toLowerCase().endsWith(".md") || child.name.toLowerCase().endsWith(".txt"))) {
+                    const rel = `${entry.name}/${child.name}`;
+                    const content = await readFile(path.join(pack, entry.name, child.name), "utf8");
+                    files.push({ path: rel, content });
+                }
+            }
+        }
+    }
+    return files;
+}
+async function collectChangedFiles(base, head) {
+    const names = git(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`])
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const files = [];
+    for (const name of names.slice(0, 40)) {
+        try {
+            const st = await stat(path.join(process.cwd(), name));
+            if (!st.isFile() || st.size > 400_000)
+                continue;
+            const content = await readFile(path.join(process.cwd(), name), "utf8");
+            files.push({ path: name, content });
+        }
+        catch {
+            // deleted or unreadable
+        }
+    }
+    return files;
+}
+function printBanner() {
+    console.log(`
+  ┌─────────────────────────────┐
+  │       MergeStorm CLI        │
+  │   review local diffs fast   │
+  └─────────────────────────────┘
+`);
+}
+function usage() {
+    printBanner();
+    console.log(`Usage:
+  mergestorm login                 Sign in via browser and store an API key
+  mergestorm login --key           Paste an existing API key instead (headless/CI)
+  mergestorm logout                Remove the stored API key
+  mergestorm review [base] [head]  Review git diff base...head (default: main...HEAD)
+  mergestorm status <job_id>       Poll a review job
+
+Env:
+  MERGESTORM_API_KEY   API key (overrides config)
+  MERGESTORM_API_URL   API base (default ${DEFAULT_API})
+`);
+}
+/** Best-effort open a URL in the user's browser; silent if no opener exists. */
+function openBrowser(url) {
+    const os = platform();
+    const cmd = os === "darwin" ? "open" : os === "win32" ? "cmd" : "xdg-open";
+    const args = os === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // no-op — the URL is printed for manual open
+    }
+}
+async function devicePost(base, route, json) {
+    const res = await fetch(`${base}${route}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(json),
+    });
+    const text = await res.text();
+    let parsed = text;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // keep text
+    }
+    return { status: res.status, body: parsed };
+}
+async function cmdLoginWithKey() {
+    const rl = createInterface({ input, output });
+    try {
+        const key = (await rl.question("Paste your MergeStorm API key (msk_live_...): ")).trim();
+        if (!key.startsWith("msk_live_")) {
+            console.error("Key should start with msk_live_");
+            process.exitCode = 1;
+            return;
+        }
+        const cfg = await loadConfig();
+        cfg.apiKey = key;
+        await saveConfig(cfg);
+        console.log(`Saved to ${configPath()}`);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function cmdLogin(args) {
+    printBanner();
+    if (args.includes("--key")) {
+        await cmdLoginWithKey();
+        return;
+    }
+    const cfg = await loadConfig();
+    const base = apiBase(cfg);
+    let start;
+    try {
+        start = await devicePost(base, "/api/v1/cli/device", {});
+    }
+    catch {
+        console.error("Could not start device login. The API may be unreachable or misconfigured.\n" +
+            "Run `mergestorm login --key` to paste an existing API key instead.");
+        process.exitCode = 1;
+        return;
+    }
+    if (start.status !== 200 || !start.body?.device_code) {
+        console.error(`Could not start device login (HTTP ${start.status}). The API may be unreachable or misconfigured.\n` +
+            `Run \`mergestorm login --key\` to paste an existing API key instead.`);
+        process.exitCode = 1;
+        return;
+    }
+    const { device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in, } = start.body;
+    const openUrl = verification_uri_complete || verification_uri;
+    console.log("To sign in, open this URL and confirm the code:\n");
+    console.log(`  ${openUrl}`);
+    console.log(`\n  Code: ${user_code}\n`);
+    openBrowser(openUrl);
+    console.log("Waiting for approval…");
+    const pollMs = Math.max((interval || 5), 2) * 1000;
+    const deadline = Date.now() + (expires_in || 600) * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        let poll;
+        try {
+            poll = await devicePost(base, "/api/v1/cli/device/token", { device_code });
+        }
+        catch {
+            console.error("\nLogin failed: network error. Check your connection and run `mergestorm login` again.");
+            process.exitCode = 1;
+            return;
+        }
+        if (poll.status === 200 && poll.body?.api_key) {
+            const next = await loadConfig();
+            next.apiKey = poll.body.api_key;
+            await saveConfig(next);
+            console.log(`\nLogged in. Key saved to ${configPath()}`);
+            return;
+        }
+        const err = poll.body?.error;
+        if (err === "authorization_pending") {
+            process.stdout.write(".");
+            continue;
+        }
+        if (err === "key_limit_reached") {
+            console.error("\nYou have reached the max active API keys. Revoke one at https://mergestorm.ai/dashboard/account and try again.");
+            process.exitCode = 1;
+            return;
+        }
+        if (err === "expired_token") {
+            console.error("\nLogin code expired. Run `mergestorm login` again.");
+            process.exitCode = 1;
+            return;
+        }
+        if (err === "already_redeemed") {
+            console.error("\nThis code was already used. Run `mergestorm login` again.");
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`\nLogin failed: ${typeof err === "string" ? err : JSON.stringify(poll.body)}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.error("\nLogin timed out. Run `mergestorm login` again.");
+    process.exitCode = 1;
+}
+async function cmdLogout() {
+    try {
+        await rm(configPath(), { force: true });
+        console.log("Logged out. Removed stored API key.");
+    }
+    catch (err) {
+        console.error("Could not remove config:", err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+    }
+}
+async function cmdReview(args) {
+    const base = args[0] || "main";
+    const head = args[1] || "HEAD";
+    const cfg = await loadConfig();
+    console.log(`Collecting diff ${base}...${head} …`);
+    const diff = git(["diff", `${base}...${head}`]);
+    if (!diff.trim()) {
+        console.log("No changes to review.");
+        return;
+    }
+    const files = await collectChangedFiles(base, head);
+    const context_files = await collectContextFiles(process.cwd());
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim() || "local";
+    const thread = `local/${branch}`.replace(/[^a-zA-Z0-9._/-]/g, "-").slice(0, 120);
+    console.log(`Submitting review (${Buffer.byteLength(diff, "utf8")} byte diff, ${files.length} file(s), ${context_files.length} context file(s))…`);
+    const { status, body } = await apiFetch(cfg, "/api/v1/reviews", {
+        method: "POST",
+        json: {
+            thread,
+            base_label: base,
+            head_label: head,
+            diff,
+            files,
+            context_files,
+        },
+    });
+    if (status === 402) {
+        console.error("Monthly review limit reached. Upgrade at https://mergestorm.ai/billing");
+        process.exitCode = 1;
+        return;
+    }
+    if (status !== 202 && status !== 200) {
+        console.error("Failed:", JSON.stringify(body, null, 2));
+        process.exitCode = 1;
+        return;
+    }
+    const job = body;
+    console.log(`Job ${job.job_id} (${job.status}). Waiting…`);
+    for (let i = 0; i < 90; i += 1) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const poll = await apiFetch(cfg, `/api/v1/reviews/${job.job_id}`);
+        if (poll.status !== 200) {
+            console.error("\nPoll failed:", JSON.stringify(poll.body, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        const row = poll.body;
+        if (row.status === "queued" || row.status === "in_progress") {
+            process.stdout.write(".");
+            continue;
+        }
+        console.log("");
+        if (row.status === "failed" || row.status === "quota_exceeded") {
+            console.error(`Review ${row.status}: ${row.error ?? ""}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`\nVerdict: ${row.verdict ?? "comment"}`);
+        console.log(row.summary ?? "");
+        const inline = row.findings?.inline ?? [];
+        const off = row.findings?.off_diff ?? row.findings?.offDiff ?? [];
+        for (const c of inline) {
+            console.log(`\n[${c.severity}] ${c.path}:${c.line}${c.title ? ` — ${c.title}` : ""}`);
+            console.log(c.body);
+        }
+        for (const c of off) {
+            console.log(`\n[${c.severity}] off-diff ${c.path ?? ""}`);
+            console.log(c.body);
+        }
+        if (inline.length === 0 && off.length === 0) {
+            console.log("\nNo findings.");
+        }
+        return;
+    }
+    console.error("\nTimed out waiting for review. Check: mergestorm status " + job.job_id);
+    process.exitCode = 1;
+}
+async function cmdStatus(jobId) {
+    const cfg = await loadConfig();
+    const { status, body } = await apiFetch(cfg, `/api/v1/reviews/${jobId}`);
+    if (status !== 200) {
+        console.error(JSON.stringify(body, null, 2));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(JSON.stringify(body, null, 2));
+}
+async function main() {
+    const [, , cmd, ...args] = process.argv;
+    if (!cmd || cmd === "-h" || cmd === "--help") {
+        usage();
+        return;
+    }
+    if (cmd === "login")
+        return cmdLogin(args);
+    if (cmd === "logout")
+        return cmdLogout();
+    if (cmd === "review")
+        return cmdReview(args);
+    if (cmd === "status") {
+        if (!args[0]) {
+            console.error("usage: mergestorm status <job_id>");
+            process.exitCode = 1;
+            return;
+        }
+        return cmdStatus(args[0]);
+    }
+    usage();
+    process.exitCode = 1;
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "mergestorm",
+  "version": "0.1.0",
+  "description": "MergeStorm CLI — review local diffs via the Review Jobs API",
+  "type": "module",
+  "bin": {
+    "mergestorm": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}