martin-loop 0.1.1 → 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

@@ -0,0 +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.

package/docs/oss/OSS-BOUNDARY-REPORT.json

@@ -0,0 +1,113 @@
+{
+  "generatedAt": "2026-04-22T11:35:54.851Z",
+  "verdict": "go",
+  "publicSurface": {
+    "packageName": "martin-loop",
+    "canonicalPackageManager": "npm",
+    "installCommand": "npm install martin-loop",
+    "npxCommand": "npx martin-loop",
+    "sdkImportPath": "martin-loop",
+    "supportsNpxCommand": true,
+    "supportsSdkImport": true
+  },
+  "ossCorePackages": [
+    {
+      "name": "@martin/contracts",
+      "path": "packages/contracts",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/core",
+      "path": "packages/core",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/contracts"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/adapters",
+      "path": "packages/adapters",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/core"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/cli",
+      "path": "packages/cli",
+      "private": false,
+      "publishAccess": "public",
+      "workspaceDependencies": [
+        "@martin/adapters",
+        "@martin/contracts",
+        "@martin/core"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/mcp",
+      "path": "packages/mcp",
+      "private": false,
+      "publishAccess": "public",
+      "workspaceDependencies": [
+        "@martin/adapters",
+        "@martin/contracts",
+        "@martin/core"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    }
+  ],
+  "nonOssWorkspacePackages": [
+    {
+      "name": "@martin/control-plane",
+      "path": "apps/control-plane",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/contracts"
+      ],
+      "classification": "non_oss_workspace",
+      "classificationReason": "Managed or RC-only workspace surface that stays out of the initial OSS boundary."
+    },
+    {
+      "name": "@martin/benchmarks",
+      "path": "benchmarks",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/adapters",
+        "@martin/contracts",
+        "@martin/core"
+      ],
+      "classification": "non_oss_workspace",
+      "classificationReason": "Managed or RC-only workspace surface that stays out of the initial OSS boundary."
+    }
+  ],
+  "localOnlySurfaces": [
+    {
+      "path": "apps/local-dashboard",
+      "reason": "Local read-model viewer that is not yet packaged as a publishable OSS workspace."
+    }
+  ],
+  "dependencyLeaks": [],
+  "summary": {
+    "ossCoreCount": 5,
+    "nonOssWorkspaceCount": 2,
+    "localOnlySurfaceCount": 1,
+    "dependencyLeakCount": 0,
+    "privateOssCoreCount": 3,
+    "publishReadyOssCoreCount": 2
+  }
+}

package/docs/oss/OSS-BOUNDARY-REPORT.md

@@ -0,0 +1,48 @@
+# Martin Loop Phase 13 OSS Core Boundary
+
+Generated: 2026-04-22T11:35:54.851Z
+
+## Verdict
+**GO**
+
+## Summary
+- Public package target: martin-loop
+- Canonical public package manager: npm
+- Intended OSS core packages: 5
+- Non-OSS workspace packages: 2
+- Local-only surfaces: 1
+- Private OSS-core packages still gated from publish: 3
+- OSS-core packages already publish-configured: 2
+- Dependency leaks: 0
+- No workspace dependency leaks detected between the intended OSS core and the non-OSS workspace surfaces.
+
+## Public Package Surface
+- Install target: `npm install martin-loop`
+- CLI target: `npx martin-loop`
+- SDK target: `import { MartinLoop } from 'martin-loop'`
+- Root `npx martin-loop` support shipped: yes
+- Root SDK import shipped: yes
+
+## Intended OSS Core Packages
+| Package | Path | Private | Publish Access | Workspace Deps |
+|---|---|---|---|---|
+| @martin/contracts | packages/contracts | yes | n/a | none |
+| @martin/core | packages/core | yes | n/a | @martin/contracts |
+| @martin/adapters | packages/adapters | yes | n/a | @martin/core |
+| @martin/cli | packages/cli | no | public | @martin/adapters, @martin/contracts, @martin/core |
+| @martin/mcp | packages/mcp | no | public | @martin/adapters, @martin/contracts, @martin/core |
+
+## Non-OSS Workspace Packages
+| Package | Path | Reason |
+|---|---|---|
+| @martin/control-plane | apps/control-plane | Managed or RC-only workspace surface that stays out of the initial OSS boundary. |
+| @martin/benchmarks | benchmarks | Managed or RC-only workspace surface that stays out of the initial OSS boundary. |
+
+## Local-Only Surfaces
+| Path | Reason |
+|---|---|
+| apps/local-dashboard | Local read-model viewer that is not yet packaged as a publishable OSS workspace. |
+
+## Dependency Leak Review
+- No workspace dependency leaks detected.
+

package/docs/oss/QUICKSTART.md

@@ -0,0 +1,135 @@
+# Quickstart
+
+This quickstart is intentionally conservative. It is written for a fresh engineer validating the current Phase 13 release-candidate state, not for a hypothetical future public release.
+
+## Public launch target vs current RC path
+
+The frozen public launch target is:
+
+- `npm install martin-loop`
+- `npx martin-loop ...`
+- `import { MartinLoop } from "martin-loop"`
+
+That launch surface is now implemented in the root package facade and smoke-validated from a clean temporary install. This quickstart still documents the honest RC-from-source path because public registry publication is a later release step.
+
+## Prerequisites
+
+- Node.js 20+ recommended
+- `pnpm` 10.x
+- A clean local checkout of this repo
+
+Optional for live runs:
+
+- Claude Code CLI for the Claude adapter path
+- OpenAI Codex CLI plus credentials for the Codex adapter path
+
+## Install and build
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Run the RC validation matrix
+
+```bash
+pnpm rc:validate
+```
+
+What this does:
+
+- creates an isolated temporary home or profile directory
+- points Martin run artifacts at that clean location
+- runs the current build, lint, test, benchmark, and certification matrix
+- writes step logs into a temp `martin-rc-validation-*` directory
+
+Use this when you want to answer, "Can a fresh environment still reproduce the current RC baseline?"
+
+## RC gate commands
+
+The current Phase 13 RC gate is made of these commands:
+
+- `pnpm oss:validate`
+- `pnpm public:smoke`
+- `pnpm repo:smoke`
+- `pnpm rc:validate`
+- `pnpm pilot:prep:validate`
+- `pnpm release:matrix:local`
+
+Recommended order for a fresh local reviewer:
+
+```bash
+pnpm oss:validate
+pnpm public:smoke
+pnpm repo:smoke
+pnpm rc:validate
+pnpm release:matrix:local
+```
+
+`pnpm release:matrix:local` runs the full local OS lane for the current machine. The repository also defines Windows, macOS, and Linux CI lanes in `.github/workflows/phase13-release-matrix.yml`.
+
+## Stub-safe CLI run
+
+This is the safest first run because it avoids real provider spend.
+
+### PowerShell
+
+```powershell
+$env:MARTIN_LIVE='false'
+pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
+Remove-Item Env:MARTIN_LIVE
+```
+
+### Bash
+
+```bash
+MARTIN_LIVE=false pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
+```
+
+This path uses the stub adapter and still exercises the loop, persistence, and policy surfaces.
+
+## Config-driven run
+
+The repo ships an example config at `martin.config.example.yaml`.
+
+Martin auto-looks for `martin.config.yaml` in the invocation root, or you can pass `--config <path>`.
+
+Example:
+
+```bash
+pnpm run:cli -- run --config martin.config.example.yaml --objective "Run with repo defaults" --verify "pnpm --filter @martin/core test"
+```
+
+## Inspect a saved run
+
+Martin persists runs under `~/.martin/runs/` by default, or under `MARTIN_RUNS_DIR` if you override it.
+
+```bash
+pnpm run:cli -- inspect --file path/to/loop-record.json
+```
+
+For persisted run folders, inspect the `contract.json`, `state.json`, `ledger.jsonl`, and `artifacts/attempt-XXX/` files together. Those artifacts are the source of truth for runtime behavior.
+
+## MCP server
+
+Build first, then start the server from the workspace:
+
+```bash
+pnpm --filter @martin/mcp build
+node packages/mcp/dist/server.js
+```
+
+The current MCP tools are:
+
+- `martin_run`
+- `martin_inspect`
+- `martin_status`
+
+## Notes for reviewers
+
+- Fresh-home behavior matters. Do not rely only on a long-lived `~/.martin` directory.
+- Exact-versus-estimated cost labels are meaningful and should not be merged in docs or dashboards.
+- The repo contains control-plane code, but the public OSS boundary is still being finalized during Phase 13.
+- The benchmark harness remains a workspace-level RC surface; `martin bench` is not part of the publishable CLI boundary yet.