martin-loop 0.1.2 → 0.1.3

package/dist/vendor/core/rollback.js

@@ -0,0 +1,219 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+export async function captureRollbackBoundary(input) {
+    if (!input.repoRoot) {
+        return undefined;
+    }
+    const repoState = readRepoState(input.repoRoot);
+    const snapshotPaths = uniqueSorted([
+        ...repoState.trackedDirtyFiles,
+        ...repoState.untrackedFiles
+    ]);
+    const snapshots = [];
+    for (const filePath of snapshotPaths) {
+        snapshots.push(await readRollbackSnapshot(input.repoRoot, filePath));
+    }
+    return {
+        strategy: "git_head_plus_snapshot",
+        capturedAt: input.capturedAt,
+        ...(readGitScalar(input.repoRoot, ["rev-parse", "HEAD"])
+            ? { headRef: readGitScalar(input.repoRoot, ["rev-parse", "HEAD"]) }
+            : {}),
+        trackedDirtyFiles: repoState.trackedDirtyFiles,
+        untrackedFiles: repoState.untrackedFiles,
+        snapshots
+    };
+}
+export async function restoreRollbackBoundary(input) {
+    if (!input.repoRoot) {
+        return undefined;
+    }
+    if (!input.boundary) {
+        return {
+            attempted: false,
+            status: "unavailable",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before: emptyRepoState(),
+            after: emptyRepoState(),
+            restoredFiles: [],
+            deletedFiles: [],
+            error: "Rollback boundary was unavailable for this attempt."
+        };
+    }
+    const before = readRepoState(input.repoRoot);
+    if (repoStateMatchesBoundary(before, input.boundary)) {
+        return {
+            attempted: false,
+            status: "not_required",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before,
+            after: before,
+            restoredFiles: [],
+            deletedFiles: []
+        };
+    }
+    const restoredFiles = new Set();
+    const deletedFiles = new Set();
+    try {
+        const baselineTracked = new Set(input.boundary.trackedDirtyFiles);
+        const baselineUntracked = new Set(input.boundary.untrackedFiles);
+        for (const filePath of before.trackedDirtyFiles) {
+            if (!baselineTracked.has(filePath)) {
+                restoreTrackedFileFromHead(input.repoRoot, filePath);
+                restoredFiles.add(filePath);
+            }
+        }
+        for (const filePath of before.untrackedFiles) {
+            if (!baselineUntracked.has(filePath)) {
+                await removeRepoPath(input.repoRoot, filePath);
+                deletedFiles.add(filePath);
+            }
+        }
+        for (const snapshot of input.boundary.snapshots) {
+            await restoreRollbackSnapshot(input.repoRoot, snapshot);
+            if (snapshot.existed) {
+                restoredFiles.add(snapshot.path);
+            }
+            else {
+                deletedFiles.add(snapshot.path);
+            }
+        }
+        const after = readRepoState(input.repoRoot);
+        const restored = repoStateMatchesBoundary(after, input.boundary);
+        return {
+            attempted: true,
+            status: restored ? "restored" : "failed",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before,
+            after,
+            restoredFiles: [...restoredFiles].sort(),
+            deletedFiles: [...deletedFiles].sort(),
+            ...(restored
+                ? {}
+                : { error: "Repo state still diverged from the recorded rollback boundary after restore." })
+        };
+    }
+    catch (error) {
+        const after = readRepoState(input.repoRoot);
+        return {
+            attempted: true,
+            status: "failed",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before,
+            after,
+            restoredFiles: [...restoredFiles].sort(),
+            deletedFiles: [...deletedFiles].sort(),
+            error: toErrorMessage(error)
+        };
+    }
+}
+function readRepoState(repoRoot) {
+    return {
+        trackedDirtyFiles: readGitLines(repoRoot, ["diff", "--name-only", "HEAD"]),
+        untrackedFiles: readGitLines(repoRoot, ["ls-files", "--others", "--exclude-standard"])
+    };
+}
+function readGitLines(repoRoot, args) {
+    const result = spawnSync("git", args, {
+        cwd: repoRoot,
+        encoding: "utf8"
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") {
+        return [];
+    }
+    return uniqueSorted(result.stdout
+        .split(/\r?\n/u)
+        .map((line) => normalizeRepoPath(line))
+        .filter(Boolean));
+}
+function readGitScalar(repoRoot, args) {
+    const result = spawnSync("git", args, {
+        cwd: repoRoot,
+        encoding: "utf8"
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") {
+        return undefined;
+    }
+    const value = result.stdout.trim();
+    return value.length > 0 ? value : undefined;
+}
+async function readRollbackSnapshot(repoRoot, filePath) {
+    const absolutePath = resolveRepoPath(repoRoot, filePath);
+    try {
+        const contents = await readFile(absolutePath);
+        return {
+            path: normalizeRepoPath(filePath),
+            existed: true,
+            encoding: "base64",
+            contentBase64: contents.toString("base64")
+        };
+    }
+    catch {
+        return {
+            path: normalizeRepoPath(filePath),
+            existed: false,
+            encoding: "base64"
+        };
+    }
+}
+async function restoreRollbackSnapshot(repoRoot, snapshot) {
+    const absolutePath = resolveRepoPath(repoRoot, snapshot.path);
+    if (!snapshot.existed || !snapshot.contentBase64) {
+        await rm(absolutePath, { recursive: true, force: true });
+        return;
+    }
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, Buffer.from(snapshot.contentBase64, "base64"));
+}
+function restoreTrackedFileFromHead(repoRoot, filePath) {
+    const result = spawnSync("git", ["restore", "--staged", "--worktree", "--source=HEAD", "--", filePath], {
+        cwd: repoRoot,
+        encoding: "utf8"
+    });
+    if (result.status !== 0) {
+        throw new Error(result.stderr?.trim() || `git restore failed for ${filePath}`);
+    }
+}
+async function removeRepoPath(repoRoot, filePath) {
+    await rm(resolveRepoPath(repoRoot, filePath), { recursive: true, force: true });
+}
+function resolveRepoPath(repoRoot, filePath) {
+    const resolvedRoot = resolve(repoRoot);
+    const resolvedPath = resolve(resolvedRoot, filePath);
+    const relativePath = relative(resolvedRoot, resolvedPath);
+    if (relativePath.startsWith("..") || relativePath === "") {
+        throw new Error(`Refusing to access a rollback path outside repo root: ${filePath}`);
+    }
+    return resolvedPath;
+}
+function repoStateMatchesBoundary(state, boundary) {
+    return arraysEqual(state.trackedDirtyFiles, boundary.trackedDirtyFiles) &&
+        arraysEqual(state.untrackedFiles, boundary.untrackedFiles);
+}
+function arraysEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function uniqueSorted(values) {
+    return [...new Set(values.map((value) => normalizeRepoPath(value)).filter(Boolean))].sort();
+}
+function normalizeRepoPath(value) {
+    return value.trim().replace(/\\/gu, "/");
+}
+function emptyRepoState() {
+    return {
+        trackedDirtyFiles: [],
+        untrackedFiles: []
+    };
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=rollback.js.map

package/docs/oss/EXAMPLES.md

@@ -1,126 +1,126 @@
-# Examples
-
-These examples are grounded in the current CLI and MCP surfaces in this repo. Where an example depends on a real provider path, it is labeled that way explicitly.
-
-These are still primarily repo-local RC examples. The root `martin-loop` package facade is now real and smoke-validated, but registry publication remains a later release step.
-
-## 1. Stub-backed hello world
-
-Use this when you want a safe first pass through the loop without real model spend.
-
-### PowerShell
-
-```powershell
-$env:MARTIN_LIVE='false'
-pnpm run:cli -- run `
-  --workspace ws_demo `
-  --project proj_demo `
-  --objective "Describe the current Martin run lifecycle in one paragraph" `
-  --verify "pnpm --filter @martin/core test"
-Remove-Item Env:MARTIN_LIVE
-```
-
-Why this is useful:
-
-- exercises `runMartin`
-- writes a real loop record and artifacts
-- avoids external provider dependencies
-
-## 2. Repo-backed task with explicit scope
-
-Use allow and deny paths so the task contract is narrow and reviewable.
-
-```bash
-pnpm run:cli -- run \
-  --cwd . \
-  --objective "Tighten README wording for the OSS quickstart" \
-  --verify "pnpm --filter @martin/core test" \
-  --allow-path README.md \
-  --allow-path docs/oss/** \
-  --deny-path apps/control-plane/** \
-  --accept "Only update documentation files" \
-  --accept "Do not modify runtime code"
-```
-
-What this demonstrates:
-
-- repo root selection with `--cwd`
-- scoped file-edit boundaries
-- acceptance criteria injection into the task contract
-
-## 3. Safety-block example
-
-This example is expected to block before execution because the verifier command is unsafe.
-
-```bash
-pnpm run:cli -- run \
-  --objective "Try to run an unsafe verifier" \
-  --verify "rm -rf ."
-```
-
-Expected behavior:
-
-- the leash blocks the verifier command before adapter execution
-- the run exits through a safety-oriented path rather than pretending the command was acceptable
-- the attempt artifact set includes a persisted leash artifact when applicable
-
-The point of this example is not that `rm` exists on every machine. The point is that the raw verifier text is evaluated before the process would be allowed to run.
-
-## 4. Budget-constrained live run
-
-This is a live-provider example. Only use it when you have the relevant CLI and credentials configured.
-
-```bash
-pnpm run:cli -- run \
-  --engine codex \
-  --model o3 \
-  --objective "Refactor the CLI argument parser for clarity" \
-  --verify "pnpm --filter @martin/cli test" \
-  --budget-usd 2 \
-  --soft-limit-usd 1 \
-  --max-iterations 2
-```
-
-What to review afterward:
-
-- admission and settlement events in `ledger.jsonl`
-- cost provenance labels in the run artifacts
-- whether the loop stopped for completion, budget pressure, or lack of progress
-
-## 5. MCP invocation shape
-
-The MCP server exposes `martin_run`, `martin_inspect`, and `martin_status`.
-
-Example `martin_run` payload:
-
-```json
-{
-  "objective": "Tighten the local dashboard copy",
-  "workingDirectory": ".",
-  "engine": "claude",
-  "verificationPlan": ["pnpm --filter @martin/control-plane test"],
-  "maxUsd": 5,
-  "maxIterations": 2,
-  "maxTokens": 20000,
-  "workspaceId": "ws_mcp",
-  "projectId": "proj_mcp"
-}
-```
-
-## 6. What to inspect in artifacts
-
-For a repo-backed attempt, look at:
-
-- `contract.json`
-- `state.json`
-- `ledger.jsonl`
-- `artifacts/attempt-XXX/compiled-context.json`
-- `artifacts/attempt-XXX/diff.patch`
-- `artifacts/attempt-XXX/grounding-scan.json`
-- `artifacts/attempt-XXX/leash.json`
-- `artifacts/attempt-XXX/patch-score.json`
-- `artifacts/attempt-XXX/patch-decision.json`
-- `artifacts/attempt-XXX/rollback-boundary.json`
-- `artifacts/attempt-XXX/rollback-outcome.json`
-
-Those files are the evidence trail that backs the runtime’s claims.
+# Examples
+
+These examples are grounded in the current CLI and MCP surfaces in this repo. Where an example depends on a real provider path, it is labeled that way explicitly.
+
+These are still primarily repo-local RC examples. The root `martin-loop` package facade is now real and smoke-validated, but registry publication remains a later release step.
+
+## 1. Stub-backed hello world
+
+Use this when you want a safe first pass through the loop without real model spend.
+
+### PowerShell
+
+```powershell
+$env:MARTIN_LIVE='false'
+pnpm run:cli -- run `
+  --workspace ws_demo `
+  --project proj_demo `
+  --objective "Describe the current Martin run lifecycle in one paragraph" `
+  --verify "pnpm --filter @martin/core test"
+Remove-Item Env:MARTIN_LIVE
+```
+
+Why this is useful:
+
+- exercises `runMartin`
+- writes a real loop record and artifacts
+- avoids external provider dependencies
+
+## 2. Repo-backed task with explicit scope
+
+Use allow and deny paths so the task contract is narrow and reviewable.
+
+```bash
+pnpm run:cli -- run \
+  --cwd . \
+  --objective "Tighten README wording for the OSS quickstart" \
+  --verify "pnpm --filter @martin/core test" \
+  --allow-path README.md \
+  --allow-path docs/oss/** \
+  --deny-path apps/control-plane/** \
+  --accept "Only update documentation files" \
+  --accept "Do not modify runtime code"
+```
+
+What this demonstrates:
+
+- repo root selection with `--cwd`
+- scoped file-edit boundaries
+- acceptance criteria injection into the task contract
+
+## 3. Safety-block example
+
+This example is expected to block before execution because the verifier command is unsafe.
+
+```bash
+pnpm run:cli -- run \
+  --objective "Try to run an unsafe verifier" \
+  --verify "rm -rf ."
+```
+
+Expected behavior:
+
+- the leash blocks the verifier command before adapter execution
+- the run exits through a safety-oriented path rather than pretending the command was acceptable
+- the attempt artifact set includes a persisted leash artifact when applicable
+
+The point of this example is not that `rm` exists on every machine. The point is that the raw verifier text is evaluated before the process would be allowed to run.
+
+## 4. Budget-constrained live run
+
+This is a live-provider example. Only use it when you have the relevant CLI and credentials configured.
+
+```bash
+pnpm run:cli -- run \
+  --engine codex \
+  --model o3 \
+  --objective "Refactor the CLI argument parser for clarity" \
+  --verify "pnpm --filter @martin/cli test" \
+  --budget-usd 2 \
+  --soft-limit-usd 1 \
+  --max-iterations 2
+```
+
+What to review afterward:
+
+- admission and settlement events in `ledger.jsonl`
+- cost provenance labels in the run artifacts
+- whether the loop stopped for completion, budget pressure, or lack of progress
+
+## 5. MCP invocation shape
+
+The MCP server exposes `martin_run`, `martin_inspect`, and `martin_status`.
+
+Example `martin_run` payload:
+
+```json
+{
+  "objective": "Tighten the local dashboard copy",
+  "workingDirectory": ".",
+  "engine": "claude",
+  "verificationPlan": ["pnpm --filter @martin/control-plane test"],
+  "maxUsd": 5,
+  "maxIterations": 2,
+  "maxTokens": 20000,
+  "workspaceId": "ws_mcp",
+  "projectId": "proj_mcp"
+}
+```
+
+## 6. What to inspect in artifacts
+
+For a repo-backed attempt, look at:
+
+- `contract.json`
+- `state.json`
+- `ledger.jsonl`
+- `artifacts/attempt-XXX/compiled-context.json`
+- `artifacts/attempt-XXX/diff.patch`
+- `artifacts/attempt-XXX/grounding-scan.json`
+- `artifacts/attempt-XXX/leash.json`
+- `artifacts/attempt-XXX/patch-score.json`
+- `artifacts/attempt-XXX/patch-decision.json`
+- `artifacts/attempt-XXX/rollback-boundary.json`
+- `artifacts/attempt-XXX/rollback-outcome.json`
+
+Those files are the evidence trail that backs the runtime’s claims.