martin-loop 0.1.4 → 1.3.0

package/dist/vendor/cli/commands/doctor.js

@@ -0,0 +1,219 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+const RUNS_ROOT = join(homedir(), ".martin", "runs");
+const CONFIG_SEARCH_PATHS = [
+    join(process.cwd(), "martin.config.yaml"),
+    join(homedir(), ".martin", "martin.config.yaml")
+];
+export async function handleDoctorCommand(args, options = {}) {
+    const checkFilter = parseFlag(args, "--check");
+    const allMode = args.includes("--all");
+    const checks = await runChecks(checkFilter, options.cwd ?? process.cwd());
+    const failed = checks.filter((c) => c.status === "fail");
+    const passed = checks.filter((c) => c.status === "pass");
+    if (args.includes("--json")) {
+        return {
+            exitCode: failed.length > 0 ? 1 : 0,
+            stdout: JSON.stringify({ checks, passed: passed.length, failed: failed.length }, null, 2),
+            stderr: ""
+        };
+    }
+    const lines = [
+        "martin doctor",
+        "─".repeat(54)
+    ];
+    for (const check of checks) {
+        const icon = check.status === "pass" ? "✓" : check.status === "skip" ? "─" : "✗";
+        const label = check.name.padEnd(34);
+        const detail = check.detail;
+        lines.push(`${icon}  ${label} ${detail}`);
+        if (check.status === "fail" && check.hint) {
+            lines.push(`   ${" ".repeat(34)} Hint: ${check.hint}`);
+        }
+    }
+    lines.push("─".repeat(54));
+    if (failed.length === 0) {
+        lines.push(`All ${passed.length} checks passed. Martin Loop is ready.`);
+    }
+    else {
+        const plural = failed.length === 1 ? "check" : "checks";
+        lines.push(`${failed.length} ${plural} failed. Fix the above and re-run martin doctor.`);
+    }
+    return {
+        exitCode: failed.length > 0 ? 1 : 0,
+        stdout: lines.join("\n"),
+        stderr: ""
+    };
+}
+async function runChecks(filter, cwd) {
+    const allChecks = [
+        { id: "credentials", fn: checkAdapterCredentials },
+        { id: "budget", fn: () => checkBudgetConfig(cwd) },
+        { id: "policy", fn: () => checkPolicyFile(cwd) },
+        { id: "leash", fn: checkLeashConfig },
+        { id: "store", fn: checkRunStore },
+    ];
+    const selected = filter
+        ? allChecks.filter((c) => c.id === filter)
+        : allChecks;
+    const results = [];
+    for (const check of selected) {
+        try {
+            results.push(await check.fn());
+        }
+        catch (err) {
+            results.push({
+                name: check.id,
+                status: "fail",
+                detail: "FAIL — unexpected error",
+                hint: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+    return results;
+}
+async function checkAdapterCredentials() {
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (anthropicKey && anthropicKey.length > 10) {
+        return {
+            name: "Adapter credentials",
+            status: "pass",
+            detail: "OK  (ANTHROPIC_API_KEY set)"
+        };
+    }
+    if (openaiKey && openaiKey.length > 10) {
+        return {
+            name: "Adapter credentials",
+            status: "pass",
+            detail: "OK  (OPENAI_API_KEY set)"
+        };
+    }
+    return {
+        name: "Adapter credentials",
+        status: "fail",
+        detail: "FAIL — no API key found",
+        hint: "Set ANTHROPIC_API_KEY or OPENAI_API_KEY in your environment"
+    };
+}
+async function checkBudgetConfig(cwd) {
+    // Check for config file with a budget set
+    for (const configPath of [join(cwd, "martin.config.yaml"), ...CONFIG_SEARCH_PATHS]) {
+        try {
+            const contents = await readFile(configPath, "utf8");
+            const maxUsdMatch = contents.match(/maxUsd:\s*([0-9.]+)/);
+            const maxUsdValue = maxUsdMatch?.[1];
+            if (maxUsdValue) {
+                const val = parseFloat(maxUsdValue);
+                if (val > 0) {
+                    return {
+                        name: "Budget configured",
+                        status: "pass",
+                        detail: `OK  ($${val.toFixed(2)} max per run in ${basename(configPath)})`
+                    };
+                }
+            }
+        }
+        catch { /* not found — continue */ }
+    }
+    return {
+        name: "Budget configured",
+        status: "pass",
+        detail: "OK  (using default $10.00 — set maxUsd in martin.config.yaml to override)"
+    };
+}
+async function checkPolicyFile(cwd) {
+    const policyPaths = [
+        join(cwd, "martin.policy.yaml"),
+        join(homedir(), ".martin", "martin.policy.yaml")
+    ];
+    for (const policyPath of policyPaths) {
+        try {
+            const contents = await readFile(policyPath, "utf8");
+            // Basic YAML validation: check for obvious typos in known fields
+            const knownFields = ["budgetUsd", "allowedVerifiers", "blockedCommands", "fileScopeGlob", "maxAttempts", "requireApprovalAboveUsd", "siem", "cveCheck", "circuitBreaker", "output"];
+            const lines = contents.split("\n");
+            for (const line of lines) {
+                const topLevelMatch = line.match(/^([A-Za-z][\w-]*):/);
+                const key = topLevelMatch?.[1];
+                if (key) {
+                    if (!knownFields.includes(key)) {
+                        return {
+                            name: "Policy file",
+                            status: "fail",
+                            detail: `FAIL — ${basename(policyPath)}: unknown field '${key}'`,
+                            hint: `Known fields: ${knownFields.join(", ")}`
+                        };
+                    }
+                }
+            }
+            return {
+                name: "Policy file",
+                status: "pass",
+                detail: `OK  (${basename(policyPath)} valid)`
+            };
+        }
+        catch { /* not found — continue */ }
+    }
+    return {
+        name: "Policy file",
+        status: "pass",
+        detail: "OK  (no policy file — using built-in defaults)"
+    };
+}
+async function checkLeashConfig() {
+    // Leash is part of core — if the relevant exports are importable, the guard is active.
+    try {
+        const core = await import("../../core/index.js");
+        if (typeof core.evaluateVerificationLeash === "function") {
+            return {
+                name: "Leash config",
+                status: "pass",
+                detail: "OK  (verification leash loaded)"
+            };
+        }
+        return {
+            name: "Leash config",
+            status: "fail",
+            detail: "FAIL — leash export missing from @martin/core",
+            hint: "Run: pnpm --filter @martin/core build"
+        };
+    }
+    catch (err) {
+        return {
+            name: "Leash config",
+            status: "fail",
+            detail: "FAIL — @martin/core failed to import",
+            hint: "Run: pnpm build in the repo root"
+        };
+    }
+}
+async function checkRunStore() {
+    try {
+        await mkdir(RUNS_ROOT, { recursive: true });
+        // Test write access by creating and removing a temp file
+        const testPath = join(RUNS_ROOT, `.doctor-check-${Date.now()}`);
+        await writeFile(testPath, "ok", "utf8");
+        const { unlink } = await import("node:fs/promises");
+        await unlink(testPath);
+        return {
+            name: "Run store writable",
+            status: "pass",
+            detail: `OK  (${RUNS_ROOT.replace(homedir(), "~")})`
+        };
+    }
+    catch (err) {
+        return {
+            name: "Run store writable",
+            status: "fail",
+            detail: `FAIL — cannot write to ${RUNS_ROOT}`,
+            hint: `Check permissions on ${RUNS_ROOT} or set MARTIN_RUNS_ROOT env var`
+        };
+    }
+}
+function parseFlag(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/vendor/cli/commands/explain.d.ts

@@ -0,0 +1,17 @@
+/**
+ * explain.ts — SLICE-25
+ *
+ * CLI command: martin explain <loop-id>
+ *
+ * Reads stored run artifacts from ~/.martin/loops/<loop-id>/ and produces
+ * plain-English Markdown (or JSON) explaining every gate decision.
+ * No model calls — pure artifact reading.
+ */
+export interface ExplainCommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function handleExplainCommand(args: string[], options?: {
+    cwd?: string;
+}): Promise<ExplainCommandResult>;

package/dist/vendor/cli/commands/explain.js

@@ -0,0 +1,176 @@
+/**
+ * explain.ts — SLICE-25
+ *
+ * CLI command: martin explain <loop-id>
+ *
+ * Reads stored run artifacts from ~/.martin/loops/<loop-id>/ and produces
+ * plain-English Markdown (or JSON) explaining every gate decision.
+ * No model calls — pure artifact reading.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { formatRunExplanation, formatRunTimeline, resolveRunsRoot } from "../../core/index.js";
+export async function handleExplainCommand(args, options = {}) {
+    // Extract loop-id — first positional argument
+    const loopId = args.find(a => !a.startsWith("--")) ?? "";
+    if (!loopId) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "Error: explain requires a loop ID. Usage: martin explain <loop-id> [--attempt N] [--decision <gate>] [--timeline] [--html] [--json] [--debug]"
+        };
+    }
+    const attemptFlag = parseFlag(args, "--attempt");
+    const decisionFlag = parseFlag(args, "--decision");
+    const timelineMode = args.includes("--timeline");
+    const htmlMode = args.includes("--html");
+    const jsonMode = args.includes("--json");
+    const debugMode = args.includes("--debug");
+    const loopDir = await resolveExplainDirectory(loopId);
+    // Attempt to load artifacts
+    let artifacts;
+    try {
+        artifacts = await loadArtifacts(loopDir, debugMode);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isNotFound = message.includes("ENOENT") || message.includes("no such file");
+        if (isNotFound) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `No artifacts found for loop ${loopId}. Run \`martin doctor\` to check your storage path.`
+            };
+        }
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `Error reading artifacts: ${message}`
+        };
+    }
+    if (timelineMode) {
+        try {
+            const timelineData = await loadTimelineData(loopDir);
+            const result = formatRunTimeline({
+                loopId,
+                objective: timelineData.objective,
+                lifecycleState: timelineData.lifecycleState,
+                events: timelineData.events,
+                ledgerEvents: timelineData.ledgerEvents
+            });
+            if (jsonMode) {
+                return {
+                    exitCode: 0,
+                    stdout: JSON.stringify(result.json, null, 2),
+                    stderr: ""
+                };
+            }
+            return {
+                exitCode: 0,
+                stdout: htmlMode ? result.html : result.markdown,
+                stderr: ""
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `Error building timeline: ${message}`
+            };
+        }
+    }
+    if (artifacts.length === 0) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `No artifacts found for loop ${loopId}. Run \`martin doctor\` to check your storage path.`
+        };
+    }
+    const result = formatRunExplanation(artifacts, {
+        loopId,
+        attemptFilter: attemptFlag != null ? parseInt(attemptFlag, 10) : undefined,
+        decisionFilter: decisionFlag ?? undefined,
+        json: jsonMode
+    });
+    if (jsonMode) {
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify(result.json, null, 2),
+            stderr: ""
+        };
+    }
+    return {
+        exitCode: 0,
+        stdout: result.markdown,
+        stderr: ""
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+async function loadArtifacts(loopDir, debug) {
+    const entries = await readdir(loopDir);
+    const artifactFiles = entries.filter(f => f.endsWith(".json") && (f.startsWith("attempt-") || f.includes("artifact")));
+    const artifacts = [];
+    for (const file of artifactFiles.sort()) {
+        try {
+            const raw = await readFile(join(loopDir, file), "utf8");
+            const parsed = JSON.parse(raw);
+            artifacts.push(parsed);
+        }
+        catch (err) {
+            if (debug) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[debug] skipped ${file}: ${msg}\n`);
+            }
+            // Non-fatal — skip malformed artifact files
+        }
+    }
+    // Also accept a single loop-record.json that may contain an attempts array
+    if (artifacts.length === 0 && entries.includes("loop-record.json")) {
+        const raw = await readFile(join(loopDir, "loop-record.json"), "utf8");
+        const record = JSON.parse(raw);
+        if (Array.isArray(record.attempts)) {
+            return record.attempts;
+        }
+    }
+    return artifacts;
+}
+async function loadTimelineData(loopDir) {
+    const loopRecordRaw = await readFile(join(loopDir, "loop-record.json"), "utf8");
+    const loopRecord = JSON.parse(loopRecordRaw);
+    const ledgerPath = join(loopDir, "ledger.jsonl");
+    const ledgerRaw = await readFile(ledgerPath, "utf8");
+    const ledgerEvents = ledgerRaw
+        .split(/\r?\n/u)
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+    return {
+        objective: loopRecord.task?.objective ?? "unknown",
+        ...(loopRecord.lifecycleState ? { lifecycleState: loopRecord.lifecycleState } : {}),
+        events: loopRecord.events ?? [],
+        ledgerEvents
+    };
+}
+async function resolveExplainDirectory(loopId) {
+    const roots = [
+        resolveRunsRoot(process.env),
+        join(homedir(), ".martin", "loops")
+    ];
+    for (const root of roots) {
+        const candidate = join(root, loopId);
+        try {
+            await readdir(candidate);
+            return candidate;
+        }
+        catch {
+            // Try the next legacy root.
+        }
+    }
+    return join(roots[0] ?? join(homedir(), ".martin", "runs"), loopId);
+}
+function parseFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+//# sourceMappingURL=explain.js.map

package/dist/vendor/cli/commands/export.d.ts

@@ -0,0 +1,5 @@
+export declare function handleExportCommand(args: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;

package/dist/vendor/cli/commands/export.js

@@ -0,0 +1,60 @@
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pushOtlp, readRuns, runsToOtlp } from "@martin/trace-intelligence";
+export async function handleExportCommand(args) {
+    const maxRuns = parseIntFlag(args, "--runs") ?? 20;
+    const since = parseFlag(args, "--since");
+    const runsRoot = parseFlag(args, "--runs-root");
+    const outputPath = parseFlag(args, "--output") ?? "spans.json";
+    const endpoint = parseFlag(args, "--endpoint");
+    try {
+        const runs = await readRuns({ maxRuns, since, runsRoot });
+        if (runs.length === 0) {
+            return {
+                exitCode: 0,
+                stdout: "",
+                stderr: "No runs found. Run martin-loop at least once to generate trace data."
+            };
+        }
+        const otlpRequest = runsToOtlp(runs);
+        const totalSpans = otlpRequest.resourceSpans.reduce((sum, rs) => sum + rs.scopeSpans.reduce((s, ss) => s + ss.spans.length, 0), 0);
+        if (endpoint) {
+            const pushResult = await pushOtlp(otlpRequest, endpoint);
+            if (!pushResult.ok) {
+                return {
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: `OTLP push failed (HTTP ${pushResult.status}): ${pushResult.body}`
+                };
+            }
+            return {
+                exitCode: 0,
+                stdout: `Exported ${totalSpans} spans from ${runs.length} runs to ${endpoint}`,
+                stderr: ""
+            };
+        }
+        const resolved = resolve(outputPath);
+        await writeFile(resolved, JSON.stringify(otlpRequest, null, 2), "utf8");
+        return {
+            exitCode: 0,
+            stdout: `Exported ${totalSpans} spans from ${runs.length} runs to ${resolved}`,
+            stderr: ""
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, stdout: "", stderr: `Error: ${message}` };
+    }
+}
+function parseFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+function parseIntFlag(args, flag) {
+    const val = parseFlag(args, flag);
+    if (val === undefined)
+        return undefined;
+    const n = parseInt(val, 10);
+    return isNaN(n) ? undefined : n;
+}
+//# sourceMappingURL=export.js.map

package/dist/vendor/cli/commands/governance.d.ts

@@ -0,0 +1,8 @@
+export interface GovernanceCommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function handleGovernanceCommand(args: string[], options?: {
+    cwd?: string;
+}): Promise<GovernanceCommandResult>;

package/dist/vendor/cli/commands/governance.js

@@ -0,0 +1,95 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createBlastRadiusReport } from "@martin/sdk";
+export async function handleGovernanceCommand(args, options = {}) {
+    const subcommand = args[0];
+    try {
+        if (subcommand !== "check") {
+            return {
+                stdout: "",
+                stderr: [
+                    "Usage: martin governance check --change-description <text> --repos <repo1,repo2> [options]",
+                    "",
+                    "Options:",
+                    "  --services <svc1,svc2>",
+                    "  --truth-facts <fact1,fact2>",
+                    "  --active-treaties <treaty1,treaty2>",
+                    "  --release-window-conflicts <conflict1,conflict2>",
+                    "  --lock-conflicts <resource@holder@expiresAt,...>",
+                    "  --window-ends-at <timestamp>",
+                    "  --output <path>"
+                ].join("\n"),
+                exitCode: 1
+            };
+        }
+        const changeDescription = parseFlag(args, "--change-description");
+        const reposAffected = parseCsvFlag(args, "--repos");
+        if (!changeDescription) {
+            return { stdout: "", stderr: "Missing --change-description", exitCode: 1 };
+        }
+        if (reposAffected.length === 0) {
+            return { stdout: "", stderr: "Missing --repos", exitCode: 1 };
+        }
+        const report = createBlastRadiusReport({
+            proposedChange: changeDescription,
+            reposAffected,
+            servicesAffected: parseCsvFlag(args, "--services"),
+            truthFactsAffected: parseCsvFlag(args, "--truth-facts"),
+            activeTreatiesAffected: parseCsvFlag(args, "--active-treaties"),
+            releaseWindowConflicts: parseCsvFlag(args, "--release-window-conflicts"),
+            lockConflicts: parseLockConflicts(parseFlag(args, "--lock-conflicts")),
+            ...(parseFlag(args, "--window-ends-at")
+                ? { evaluationWindowEndsAt: parseFlag(args, "--window-ends-at") }
+                : {})
+        });
+        const outputPath = parseFlag(args, "--output");
+        if (outputPath) {
+            const resolvedOutputPath = resolve(options.cwd ?? process.cwd(), outputPath);
+            await mkdir(dirname(resolvedOutputPath), { recursive: true });
+            await writeFile(resolvedOutputPath, JSON.stringify(report, null, 2), "utf8");
+        }
+        return {
+            stdout: JSON.stringify(report, null, 2),
+            stderr: "",
+            exitCode: 0
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { stdout: "", stderr: message, exitCode: 1 };
+    }
+}
+function parseFlag(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function parseCsvFlag(args, flag) {
+    const value = parseFlag(args, flag);
+    return value
+        ? value
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)
+        : [];
+}
+function parseLockConflicts(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((entry) => {
+        const [resource, lockHolder, expiresAt] = entry.split("@");
+        if (!resource || !lockHolder) {
+            throw new Error(`Invalid lock conflict entry: ${entry}`);
+        }
+        return {
+            resource,
+            lockHolder,
+            ...(expiresAt ? { expiresAt } : {})
+        };
+    });
+}
+//# sourceMappingURL=governance.js.map

package/dist/vendor/cli/commands/improve.d.ts

@@ -0,0 +1,18 @@
+export declare function handleImproveCommand(args: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+export type ImproveLiveEngine = "claude" | "codex";
+export interface ImproveAdapterSelection {
+    engine: ImproveLiveEngine;
+    model?: string;
+}
+export declare function resolveImproveAdapterSelection(args: string[], env?: NodeJS.ProcessEnv): ImproveAdapterSelection;
+export declare function resolveImproveLiveAdapterTimeoutMs(env?: NodeJS.ProcessEnv): number;
+export declare function resolveImproveMaxIterations(args: string[], env?: NodeJS.ProcessEnv, options?: {
+    certifyTraceAutonomy?: boolean;
+}): number;
+export declare function resolveImproveRetryLimit(options?: {
+    certifyTraceAutonomy?: boolean;
+}): number;