repolith 0.2.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 > Make a set of independent git repos feel like one monorepo — without touching git internals, GitHub, or CI.
 
-**Status: v0.2 — CLI + MCP server.** All CLI commands (`sync`, `checkout`, `status`, `grep`, `log`, `diff`, `exec`, `init`, `bisect`) are implemented and tested, plus an **MCP server** (`repolith mcp`) so AI agents can query and restore workspace state, and a VS Code extension. APIs may still change pre-1.0.
+**Status: v0.3 — CLI + MCP server.** All CLI commands (`sync`, `checkout`, `status`, `grep`, `log`, `diff`, `exec`, `init`, `bisect`, `state`, `freeze`, `open`) are implemented and tested — with `--json` on the read commands — plus an **MCP server** (`repolith mcp`) so AI agents can query and restore workspace state, and a VS Code extension. APIs may still change pre-1.0.
 
 ## What it is
 
@@ -24,6 +24,8 @@ npm i -g repolith
 bun add -g repolith
 ```
 
+**VS Code extension:** search "repolith" in the Extensions view, or install [`stanicky.repolith-vscode`](https://marketplace.visualstudio.com/items?itemName=stanicky.repolith-vscode).
+
 ## Quick start
 
 ```bash
@@ -34,8 +36,13 @@ repolith grep "TODO"         # search across all repos at once
 repolith exec "npm test"     # run a command in every repo
 repolith checkout            # restore every repo to the locked commit (deterministic)
 repolith bisect --good good.lock.json --test "npm test"  # find the repo+commit that broke the system
+repolith state --json        # print the atomic hash + per-repo commits (scriptable)
+repolith freeze snap.json    # write a shareable snapshot of the current state
+repolith open snap.json      # reconstruct the exact system from a shared snapshot
 ```
 
+`status`, `grep`, `log`, `diff`, and `state` all accept `--json` for scripting and agent/CI use.
+
 ## For AI agents (MCP)
 
 `repolith` ships an [MCP](https://modelcontextprotocol.io) server so coding agents can query and reconstruct multi-repo state deterministically — *git pins a repo; repolith pins a system.*

package/dist/cli.js

@@ -17058,24 +17058,21 @@ Sync completed with errors — lockfile NOT updated.`);
 import { readFile as readFile3 } from "node:fs/promises";
 import { existsSync as existsSync2 } from "node:fs";
 import { resolve as resolve2, join as join3 } from "node:path";
-async function restoreToLock(manifestPath) {
+async function restoreState(manifestPath, state) {
   const manifestDir = resolve2(manifestPath, "..");
   const manifest = parseManifest(await readFile3(manifestPath, "utf8"));
-  const lock = await readLockfile(manifestDir);
-  if (!lock)
-    throw new Error("no repolith.lock.json — run `repolith sync` first");
   const results = await runAll(manifest.repos, async (repo) => {
-    const locked = lock.repos[repo.name];
-    if (!locked)
-      throw new Error(`repo "${repo.name}" is not in the lockfile`);
+    const pinned = state.repos[repo.name];
+    if (!pinned)
+      throw new Error(`state has no commit for "${repo.name}"`);
     const dest = join3(manifestDir, repo.path);
     if (!existsSync2(dest))
       await gitClone(repo.url, dest, repo.ref);
     await gitFetch(dest);
-    await gitCheckoutCommit(dest, locked.commit);
+    await gitCheckoutCommit(dest, pinned.commit);
     const head = (await gitRun(dest, ["rev-parse", "HEAD"])).stdout.trim();
-    if (head !== locked.commit) {
-      throw new Error(`HEAD ${head.slice(0, 8)} != locked ${locked.commit.slice(0, 8)}`);
+    if (head !== pinned.commit) {
+      throw new Error(`HEAD ${head.slice(0, 8)} != pinned ${pinned.commit.slice(0, 8)}`);
     }
     return head;
   });
@@ -17088,11 +17085,17 @@ async function restoreToLock(manifestPath) {
       repos[r.repo.name] = { url: r.repo.url, ref: r.repo.ref, commit: r.value };
   }
   const hash = computeHash(repos);
-  if (errors.length === 0 && hash !== lock.hash) {
-    throw new Error(`restored hash ${hash.slice(0, 12)} != lockfile hash ${lock.hash.slice(0, 12)} — refusing to claim reproducibility`);
+  if (errors.length === 0 && hash !== state.hash) {
+    throw new Error(`restored hash ${hash.slice(0, 12)} != expected ${state.hash.slice(0, 12)} — refusing to claim reproducibility`);
   }
   return { workspace: manifest.name, hash, repos, errors };
 }
+async function restoreToLock(manifestPath) {
+  const lock = await readLockfile(resolve2(manifestPath, ".."));
+  if (!lock)
+    throw new Error("no repolith.lock.json — run `repolith sync` first");
+  return restoreState(manifestPath, lock);
+}
 async function checkoutCommand(manifestPath) {
   console.log("Restoring workspace to locked state…");
   const { workspace, hash, errors } = await restoreToLock(manifestPath);
@@ -17125,11 +17128,16 @@ async function repoStatus(dest) {
   } catch {}
   return { branch: branch.trim(), dirty: porcelain.trim().length > 0, ahead, behind };
 }
-async function statusCommand(manifestPath) {
+async function statusCommand(manifestPath, json = false) {
   const manifestDir = resolve3(manifestPath, "..");
   const toml = await readFile4(manifestPath, "utf8");
   const manifest = parseManifest(toml);
   const results = await runAll(manifest.repos, (repo) => repoStatus(join4(manifestDir, repo.path)));
+  if (json) {
+    const data = results.map((r) => r.ok ? { repo: r.repo.name, ...r.value } : { repo: r.repo.name, error: r.error.message });
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
   const nameWidth = Math.max(4, ...manifest.repos.map((r) => r.name.length));
   for (const r of results) {
     const name = r.repo.name.padEnd(nameWidth);
@@ -17183,34 +17191,37 @@ async function execCommand(command, manifestPath) {
 // src/commands/grep.ts
 import { readFile as readFile6 } from "node:fs/promises";
 import { resolve as resolve5, join as join6 } from "node:path";
-async function grepCommand(pattern, extraArgs, manifestPath) {
+async function grepCommand(pattern, extraArgs, manifestPath, json = false) {
   const manifestDir = resolve5(manifestPath, "..");
   const toml = await readFile6(manifestPath, "utf8");
   const manifest = parseManifest(toml);
   const results = await runAll(manifest.repos, async (repo) => {
     const dest = join6(manifestDir, repo.path);
-    const { stdout } = await gitRun(dest, ["grep", "--color=never", "-n", pattern, ...extraArgs]).catch(() => ({ stdout: "", stderr: "" }));
+    const { stdout } = await gitRun(dest, ["grep", "--color=never", "-n", ...extraArgs, pattern]).catch(() => ({ stdout: "", stderr: "" }));
     return stdout;
   });
-  let anyMatch = false;
+  const matches = [];
   for (const r of results) {
-    if (!r.ok || !r.value.trim())
-      continue;
-    const lines = r.value.trim().split(`
-`);
-    for (const line of lines) {
-      console.log(`[${r.repo.name}] ${line}`);
-      anyMatch = true;
+    if (r.ok && r.value.trim())
+      matches.push({ repo: r.repo.name, hits: r.value.trim().split(`
+`) });
+  }
+  if (json) {
+    console.log(JSON.stringify(matches, null, 2));
+  } else {
+    for (const m of matches) {
+      for (const line of m.hits)
+        console.log(`[${m.repo}] ${line}`);
     }
   }
-  if (!anyMatch)
+  if (matches.length === 0)
     process.exit(1);
 }
 
 // src/commands/log.ts
 import { readFile as readFile7 } from "node:fs/promises";
 import { resolve as resolve6, join as join7 } from "node:path";
-async function logCommand2(extraArgs, manifestPath) {
+async function logCommand2(extraArgs, manifestPath, json = false) {
   const manifestDir = resolve6(manifestPath, "..");
   const toml = await readFile7(manifestPath, "utf8");
   const manifest = parseManifest(toml);
@@ -17219,6 +17230,11 @@ async function logCommand2(extraArgs, manifestPath) {
     const { stdout } = await gitRun(dest, ["log", "--oneline", ...extraArgs]);
     return stdout.trim();
   });
+  if (json) {
+    const data = results.map((r) => r.ok ? { repo: r.repo.name, log: r.value } : { repo: r.repo.name, error: r.error.message });
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
   for (const r of results) {
     console.log(`
 === [${r.repo.name}] ===`);
@@ -17235,7 +17251,7 @@ async function logCommand2(extraArgs, manifestPath) {
 // src/commands/diff.ts
 import { readFile as readFile8 } from "node:fs/promises";
 import { resolve as resolve7, join as join8 } from "node:path";
-async function diffCommand(extraArgs, manifestPath) {
+async function diffCommand(extraArgs, manifestPath, json = false) {
   const manifestDir = resolve7(manifestPath, "..");
   const toml = await readFile8(manifestPath, "utf8");
   const manifest = parseManifest(toml);
@@ -17244,17 +17260,21 @@ async function diffCommand(extraArgs, manifestPath) {
     const { stdout } = await gitRun(dest, ["diff", ...extraArgs]);
     return stdout;
   });
-  let anyDiff = false;
-  for (const r of results) {
-    if (!r.ok) {
-      console.error(`=== [${r.repo.name}] ERROR: ${r.error.message}`);
-      continue;
-    }
-    if (r.value.trim()) {
-      console.log(`
+  const anyDiff = results.some((r) => r.ok && r.value.trim().length > 0);
+  if (json) {
+    const data = results.map((r) => r.ok ? { repo: r.repo.name, diff: r.value } : { repo: r.repo.name, error: r.error.message });
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    for (const r of results) {
+      if (!r.ok) {
+        console.error(`=== [${r.repo.name}] ERROR: ${r.error.message}`);
+        continue;
+      }
+      if (r.value.trim()) {
+        console.log(`
 === [${r.repo.name}] ===`);
-      process.stdout.write(r.value);
-      anyDiff = true;
+        process.stdout.write(r.value);
+      }
     }
   }
   if (anyDiff)
@@ -39950,7 +39970,7 @@ var jsonResult = (data) => ({
 });
 function buildMcpServer(manifestPath, opts) {
   const manifestDir = resolve8(manifestPath, "..");
-  const server = new McpServer({ name: "repolith", version: "0.2.0" });
+  const server = new McpServer({ name: "repolith", version: "0.3.1" });
   const loadManifest = async () => parseManifest(await readFile9(manifestPath, "utf8"));
   server.registerTool("repolith_state", {
     title: "Workspace state",
@@ -40114,26 +40134,85 @@ async function bisect(opts) {
   }
 }
 
+// src/commands/freeze.ts
+import { readFile as readFile11, writeFile as writeFile3 } from "node:fs/promises";
+import { resolve as resolve10, join as join12 } from "node:path";
+async function buildState(manifestPath) {
+  const manifestDir = resolve10(manifestPath, "..");
+  const manifest = parseManifest(await readFile11(manifestPath, "utf8"));
+  const results = await runAll(manifest.repos, (repo) => gitCurrentCommit(join12(manifestDir, repo.path)));
+  const repos = {};
+  for (const r of results) {
+    if (!r.ok)
+      throw new Error(`${r.repo.name}: ${r.error.message}`);
+    repos[r.repo.name] = { url: r.repo.url, ref: r.repo.ref, commit: r.value };
+  }
+  return { version: 1, repos, hash: computeHash(repos) };
+}
+async function freezeCommand(manifestPath, outPath) {
+  const state = await buildState(manifestPath);
+  await writeFile3(outPath, JSON.stringify(state, null, 2) + `
+`, "utf8");
+  console.log(`Froze ${Object.keys(state.repos).length} repos → ${outPath}`);
+  console.log(`Workspace hash: ${state.hash}`);
+}
+async function stateCommand(manifestPath, json2 = false) {
+  const state = await buildState(manifestPath);
+  if (json2) {
+    console.log(JSON.stringify(state, null, 2));
+    return;
+  }
+  console.log(`hash: ${state.hash}`);
+  for (const [name, r] of Object.entries(state.repos)) {
+    console.log(`  ${name}  ${r.commit.slice(0, 12)}  (${r.ref})`);
+  }
+}
+
+// src/commands/open.ts
+import { readFile as readFile12 } from "node:fs/promises";
+async function openCommand(manifestPath, stateFilePath) {
+  const state = JSON.parse(await readFile12(stateFilePath, "utf8"));
+  console.log(`Opening shared state from ${stateFilePath}…`);
+  const { workspace, hash: hash2, errors: errors3 } = await restoreState(manifestPath, state);
+  for (const e of errors3)
+    console.error(`  ERROR ${e.repo}: ${e.message}`);
+  if (errors3.length) {
+    console.error(`
+Open completed with errors.`);
+    process.exit(1);
+  }
+  console.log(`"${workspace}" restored to ${hash2.slice(0, 12)}… from shared state`);
+}
+
 // src/cli.ts
 function fail(e) {
   console.error(e.message);
   process.exit(1);
 }
 var program2 = new Command;
-program2.name("repolith").description("Make a set of independent git repos feel like one monorepo").version("0.2.0");
+program2.name("repolith").description("Make a set of independent git repos feel like one monorepo").version("0.3.1");
 program2.command("sync").description("Clone missing repos, update all to their tracked refs, and write the lockfile").argument("[manifest]", "Path to repolith.toml", "repolith.toml").action(async (manifest) => {
   await syncCommand(manifest).catch(fail);
 });
 program2.command("checkout").description("Restore every repo to the commit pinned in repolith.lock.json (deterministic system restore)").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").action(async (opts) => {
   await checkoutCommand(opts.manifest).catch(fail);
 });
-program2.command("status").description("Show branch + dirty/clean + ahead/behind for every repo").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").action(async (opts) => {
-  await statusCommand(opts.manifest).catch(fail);
+program2.command("state").description("Print the atomic workspace hash + each repo's current commit").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").option("--json", "Output structured JSON", false).action(async (opts) => {
+  await stateCommand(opts.manifest, opts.json ?? false).catch(fail);
+});
+program2.command("freeze").description("Write a shareable snapshot of the current state to a file").argument("[outfile]", "Output path", "repolith.state.json").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").action(async (outfile, opts) => {
+  await freezeCommand(opts.manifest, outfile).catch(fail);
+});
+program2.command("open").description("Reconstruct the workspace from a shared state file (from `repolith freeze`)").argument("<statefile>", "Path to a repolith.state.json").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").action(async (statefile, opts) => {
+  await openCommand(opts.manifest, statefile).catch(fail);
+});
+program2.command("status").description("Show branch + dirty/clean + ahead/behind for every repo").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").option("--json", "Output structured JSON", false).action(async (opts) => {
+  await statusCommand(opts.manifest, opts.json ?? false).catch(fail);
 });
 program2.command("exec").description("Run a shell command in every repo (quote the command)").argument("<command>", 'Command to run, e.g. "npm test"').option("--manifest <path>", "Path to repolith.toml", "repolith.toml").action(async (command, opts) => {
   await execCommand(command, opts.manifest).catch(fail);
 });
-program2.command("grep").description("Search across all repos (uses git grep)").argument("<pattern>", "Search pattern").option("-i, --ignore-case", "Case-insensitive match").option("-l, --files-with-matches", "Print only filenames").option("-w, --word-regexp", "Match whole words only").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").allowUnknownOption().action(async (pattern, opts) => {
+program2.command("grep").description("Search across all repos (uses git grep)").argument("<pattern>", "Search pattern").option("-i, --ignore-case", "Case-insensitive match").option("-l, --files-with-matches", "Print only filenames").option("-w, --word-regexp", "Match whole words only").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").option("--json", "Output structured JSON", false).allowUnknownOption().action(async (pattern, opts) => {
   const extra = [];
   if (opts.ignoreCase)
     extra.push("-i");
@@ -40141,19 +40220,19 @@ program2.command("grep").description("Search across all repos (uses git grep)").
     extra.push("-l");
   if (opts.wordRegexp)
     extra.push("-w");
-  await grepCommand(pattern, extra, opts.manifest).catch(fail);
+  await grepCommand(pattern, extra, opts.manifest, opts.json ?? false).catch(fail);
 });
-program2.command("log").description("Show git log for all repos").option("-n, --max-count <n>", "Limit number of commits", "10").option("--since <date>", "Show commits more recent than date").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").action(async (opts) => {
+program2.command("log").description("Show git log for all repos").option("-n, --max-count <n>", "Limit number of commits", "10").option("--since <date>", "Show commits more recent than date").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").option("--json", "Output structured JSON", false).action(async (opts) => {
   const extra = ["-n", opts.maxCount];
   if (opts.since)
     extra.push(`--since=${opts.since}`);
-  await logCommand2(extra, opts.manifest).catch(fail);
+  await logCommand2(extra, opts.manifest, opts.json ?? false).catch(fail);
 });
-program2.command("diff").description("Show git diff across all repos").option("--staged", "Show staged changes").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").allowUnknownOption().action(async (opts) => {
+program2.command("diff").description("Show git diff across all repos").option("--staged", "Show staged changes").option("--manifest <path>", "Path to repolith.toml", "repolith.toml").option("--json", "Output structured JSON", false).allowUnknownOption().action(async (opts) => {
   const extra = [];
   if (opts.staged)
     extra.push("--staged");
-  await diffCommand(extra, opts.manifest).catch(fail);
+  await diffCommand(extra, opts.manifest, opts.json ?? false).catch(fail);
 });
 program2.command("init").description("Interactively create a repolith.toml").option("-d, --dir <path>", "Directory to create repolith.toml in", ".").option("-f, --force", "Overwrite an existing repolith.toml").action(async (opts) => {
   await initCommand(opts.dir, opts.force ?? false).catch(fail);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repolith",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Make a set of independent git repos feel like one monorepo — TOML manifest, atomic lockfile hash, parallel git dispatch, a VS Code extension, and an MCP server for AI agents.",
   "keywords": [
     "git",