specpi 0.10.0

package/extensions/workflow-controls/scope.mjs

@@ -0,0 +1,272 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+export const MAX_SCOPE_ENTRIES = 40;
+export const MAX_SNAPSHOT_PATHS = 256;
+export const MAX_FINGERPRINT_BYTES = 8 * 1024 * 1024;
+
+function portableRelative(value) {
+    return value.split(path.sep).join("/");
+}
+
+function comparable(value, platform = process.platform) {
+    const normalized = path.resolve(value);
+
+    return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function isInside(root, candidate, platform = process.platform) {
+    const base = comparable(root, platform);
+    const target = comparable(candidate, platform);
+
+    return target === base || target.startsWith(`${base}${path.sep}`);
+}
+
+function nearestExistingParent(candidate) {
+    let current = candidate;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+
+        current = parent;
+    }
+
+    return current;
+}
+
+export function canonicalRoot(root) {
+    const resolved = path.resolve(root);
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+        throw new Error("Scope root must be a directory");
+    }
+
+    return fs.realpathSync.native(resolved);
+}
+
+export function resolveScopedPath(root, input, options = {}) {
+    if (typeof input !== "string" || !input.trim() || /[\u0000-\u001f\u007f]/u.test(input)) {
+        throw new Error("Scope paths must be non-empty text without control characters");
+    }
+
+    const trimmed = input.trim();
+    if (path.isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/u.test(trimmed)) {
+        throw new Error("Scope paths must be project-relative");
+    }
+
+    const resolvedRoot = canonicalRoot(root);
+    const candidate = path.resolve(resolvedRoot, trimmed);
+    if (!isInside(resolvedRoot, candidate, options.platform)) {
+        throw new Error("Scope path escapes the project root");
+    }
+
+    const existing = nearestExistingParent(candidate);
+    if (!existing) {
+        throw new Error("Scope path has no verifiable parent");
+    }
+
+    const canonicalParent = fs.realpathSync.native(existing);
+    if (!isInside(resolvedRoot, canonicalParent, options.platform)) {
+        throw new Error("Scope path escapes the project root through a symlink");
+    }
+
+    const relative = portableRelative(path.relative(resolvedRoot, candidate)) || ".";
+    const explicitDirectory = /[\\/]$/u.test(trimmed);
+    const directory = explicitDirectory || (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory());
+
+    return { path: relative, directory };
+}
+
+export function normalizeScopeEntries(root, inputs, options = {}) {
+    if (!Array.isArray(inputs) || inputs.length === 0) {
+        throw new Error("Scope requires at least one path");
+    }
+
+    if (inputs.length > MAX_SCOPE_ENTRIES) {
+        throw new Error(`Scope supports at most ${MAX_SCOPE_ENTRIES} paths`);
+    }
+
+    const seen = new Set();
+    const entries = [];
+    for (const input of inputs) {
+        const entry = resolveScopedPath(root, input, options);
+        const key = `${options.platform === "win32" ? entry.path.toLowerCase() : entry.path}:${entry.directory}`;
+        if (seen.has(key)) {
+            continue;
+        }
+
+        seen.add(key);
+        entries.push(entry);
+    }
+
+    if (entries.length === 0) {
+        throw new Error("Scope requires at least one distinct path");
+    }
+
+    return entries;
+}
+
+export function scopeMatches(entries, relativePath, platform = process.platform) {
+    if (!Array.isArray(entries) || typeof relativePath !== "string") {
+        return false;
+    }
+
+    const normalize = (value) => {
+        const result = value.replaceAll("\\", "/").replace(/^\.\//u, "").replace(/\/+$/u, "") || ".";
+
+        return platform === "win32" ? result.toLowerCase() : result;
+    };
+
+    const candidate = normalize(relativePath);
+
+    return entries.some((entry) => {
+        const expected = normalize(entry.path);
+        if (entry.directory) {
+            return expected === "." || candidate === expected || candidate.startsWith(`${expected}/`);
+        }
+
+        return candidate === expected;
+    });
+}
+
+// Git reports NUL-delimited paths verbatim, so a filename may legally contain a newline. Those paths are reported back
+// through the system prompt, tool results, and the UI, where a raw newline would let a hostile filename forge a line of
+// guidance. Escaping keeps the path identifiable without letting it break out of the line it belongs on.
+export function sanitizePathLabel(value) {
+    return String(value).replace(/[%\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, (character) => encodeURIComponent(character));
+}
+
+export function parsePorcelainEntries(output) {
+    if (typeof output !== "string") {
+        throw new Error("Git status output is unavailable");
+    }
+
+    const fields = output.split("\0");
+    const entries = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const field = fields[index];
+        if (!field) {
+            continue;
+        }
+
+        if (field.length < 4 || field[2] !== " ") {
+            throw new Error("Malformed NUL-delimited Git status output");
+        }
+
+        const status = field.slice(0, 2);
+        const candidate = field.slice(3);
+        if (!candidate || candidate.includes("\0")) {
+            throw new Error("Malformed Git status path");
+        }
+
+        entries.push({ status, path: candidate.replaceAll("\\", "/") });
+        if (status.includes("R") || status.includes("C")) {
+            index += 1;
+            if (index >= fields.length || !fields[index]) {
+                throw new Error("Malformed Git rename status");
+            }
+
+            if (status.includes("R")) {
+                entries.push({ status, path: fields[index].replaceAll("\\", "/") });
+            }
+        }
+    }
+
+    return entries;
+}
+
+export function parsePorcelainZ(output) {
+    return [...new Set(parsePorcelainEntries(output).map((entry) => entry.path))].sort();
+}
+
+function fingerprintPath(root, relativePath) {
+    const candidate = path.resolve(root, relativePath);
+    if (!isInside(root, candidate)) {
+        throw new Error("Git reported a path outside the project root");
+    }
+
+    let stat;
+    try {
+        stat = fs.lstatSync(candidate);
+    } catch (error) {
+        if (error?.code === "ENOENT") {
+            return "missing";
+        }
+
+        throw error;
+    }
+
+    if (stat.isSymbolicLink()) {
+        return `symlink:${fs.readlinkSync(candidate)}`;
+    }
+
+    if (!stat.isFile()) {
+        return `${stat.mode}:${stat.size}:${stat.mtimeMs}`;
+    }
+
+    if (stat.size > MAX_FINGERPRINT_BYTES) {
+        return `large:${stat.size}:${stat.mtimeMs}`;
+    }
+
+    return createHash("sha256").update(fs.readFileSync(candidate)).digest("hex");
+}
+
+export function createWorktreeSnapshot(root, porcelainOutput) {
+    const resolvedRoot = canonicalRoot(root);
+    const paths = parsePorcelainZ(porcelainOutput);
+    if (paths.length > MAX_SNAPSHOT_PATHS) {
+        return {
+            root: resolvedRoot,
+            paths: paths.slice(0, MAX_SNAPSHOT_PATHS),
+            fingerprints: {},
+            indeterminate: true,
+            reason: `More than ${MAX_SNAPSHOT_PATHS} changed paths`,
+        };
+    }
+
+    const fingerprints = {};
+    for (const relativePath of paths) {
+        fingerprints[relativePath] = fingerprintPath(resolvedRoot, relativePath);
+    }
+
+    return { root: resolvedRoot, paths, fingerprints, indeterminate: false };
+}
+
+export function compareWorktreeSnapshots(before, after, entries) {
+    if (!before || !after || before.indeterminate || after.indeterminate || before.root !== after.root) {
+        return { changed: [], outside: [], indeterminate: true };
+    }
+
+    const candidates = new Set([...before.paths, ...after.paths]);
+    const changed = [...candidates]
+        .filter((candidate) => before.fingerprints[candidate] !== after.fingerprints[candidate])
+        .sort();
+    const outside = changed.filter((candidate) => !scopeMatches(entries, candidate));
+
+    return { changed, outside, indeterminate: false };
+}
+
+export function relativeMutationPath(root, input, options = {}) {
+    if (typeof input !== "string" || !input.trim() || /[\u0000-\u001f\u007f]/u.test(input)) {
+        throw new Error("Mutation path must be non-empty text without control characters");
+    }
+
+    const relative = !path.isAbsolute(input) && !/^[A-Za-z]:[\\/]/u.test(input);
+    const requested = relative ? input.trim() : input;
+    const resolvedRoot = canonicalRoot(root);
+    const cwd = typeof options.cwd === "string" && options.cwd ? options.cwd : resolvedRoot;
+    const candidate = relative ? path.resolve(cwd, requested) : path.resolve(requested);
+    if (!isInside(resolvedRoot, candidate, options.platform)) {
+        throw new Error("Mutation path escapes the project root");
+    }
+
+    const existing = nearestExistingParent(candidate);
+    if (!existing || !isInside(resolvedRoot, fs.realpathSync.native(existing), options.platform)) {
+        throw new Error("Mutation path escapes the project root through a symlink");
+    }
+
+    return portableRelative(path.relative(resolvedRoot, candidate)) || ".";
+}

package/extensions/workflow-controls/smoke.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { compareWorktreeSnapshots, createWorktreeSnapshot, normalizeScopeEntries } from "./scope.mjs";
+import {
+    createExperiment,
+    discardExperiment,
+    experimentStatus,
+    exportExperimentPatch,
+    inspectRepository,
+} from "./experiments.mjs";
+import { validateChallengeSubmission } from "./challenge.mjs";
+
+function run(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        encoding: "utf8",
+        timeout: options.timeout ?? 30_000,
+        maxBuffer: 40 * 1024 * 1024,
+    });
+
+    return Promise.resolve({
+        code: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? (result.error ? result.error.message : ""),
+    });
+}
+
+function git(root, ...args) {
+    const result = spawnSync("git", args, { cwd: root, encoding: "utf8", timeout: 30_000 });
+    if (result.status !== 0) {
+        throw new Error((result.stderr || result.stdout || "Git failed").trim());
+    }
+
+    return result.stdout;
+}
+
+function repositoryFixture(prefix) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    git(root, "init");
+    git(root, "config", "user.email", "workflow-smoke@example.invalid");
+    git(root, "config", "user.name", "Workflow Smoke");
+    fs.mkdirSync(path.join(root, "src"));
+    fs.writeFileSync(path.join(root, "src", "inside.txt"), "inside\n");
+    fs.writeFileSync(path.join(root, "outside.txt"), "outside\n");
+    fs.writeFileSync(path.join(root, "latin1.txt"), Buffer.from("caf\u00e9 latin1\n", "latin1"));
+    fs.writeFileSync(path.join(root, ".gitignore"), "ignored-work/\n");
+    git(root, "add", ".");
+    git(root, "commit", "-m", "base");
+
+    return root;
+}
+
+function status(root) {
+    return git(root, "status", "--porcelain=v1", "-z", "--untracked-files=all");
+}
+
+async function scopeSmoke() {
+    const root = repositoryFixture("specpi-scope-smoke-");
+    try {
+        const entries = normalizeScopeEntries(root, ["src/"]);
+        const before = createWorktreeSnapshot(root, status(root));
+        fs.writeFileSync(path.join(root, "outside.txt"), "changed\n");
+        const after = createWorktreeSnapshot(root, status(root));
+        const drift = compareWorktreeSnapshots(before, after, entries);
+        assert.deepEqual(drift.outside, ["outside.txt"]);
+        assert.throws(() => normalizeScopeEntries(root, ["../escape"]), /escapes/);
+
+        return "scope-drift-monitor-smoke passed: path boundary and observed outside-scope mutation verified";
+    } finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+}
+
+async function experimentSmoke() {
+    const root = repositoryFixture("specpi-experiment-smoke-");
+    const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "specpi-experiment-state-smoke-"));
+    try {
+        const repository = await inspectRepository(run, root);
+        const head = git(root, "rev-parse", "HEAD").trim();
+        const record = await createExperiment({
+            exec: run,
+            stateDir,
+            repository,
+            card: {
+                name: "smoke",
+                hypothesis: "Detached work keeps the base clean",
+                acceptance: "Export includes tracked and untracked work",
+                nonGoals: ["No merge"],
+            },
+        });
+        fs.writeFileSync(path.join(record.worktreePath, "src", "inside.txt"), "changed\n");
+        fs.writeFileSync(path.join(record.worktreePath, "new.txt"), "new\n");
+        fs.writeFileSync(
+            path.join(record.worktreePath, "latin1.txt"),
+            Buffer.from("caf\u00e9 latin1 changed\n", "latin1"),
+        );
+        fs.mkdirSync(path.join(record.worktreePath, "ignored-work"));
+        fs.writeFileSync(path.join(record.worktreePath, "ignored-work", "local.txt"), "ignored but real\n");
+
+        // Committing inside an experiment moves its HEAD; work measured against HEAD would then report clean.
+        fs.writeFileSync(path.join(record.worktreePath, "committed.txt"), "committed work\n");
+        git(record.worktreePath, "add", "committed.txt");
+        git(record.worktreePath, "commit", "-m", "experiment commit");
+
+        // Ignored work never reaches a patch, so a discard prompt that cannot see it would delete it silently.
+        const state = await experimentStatus(run, record);
+        assert.equal(state.ignored, 1);
+        assert.deepEqual(state.ignoredPaths, ["ignored-work/"]);
+        assert.deepEqual(state.committedPaths, ["committed.txt"]);
+        assert.equal(state.hasWork, true);
+
+        const exported = await exportExperimentPatch({ exec: run, stateDir, record });
+        const patchBytes = fs.readFileSync(exported.outputPath);
+        const patch = patchBytes.toString("utf8");
+        assert.match(patch, /src\/inside\.txt/);
+        assert.match(patch, /new\.txt/);
+        assert.match(patch, /committed\.txt/);
+        // A UTF-8 round trip would replace the latin-1 byte and produce a patch that no longer applies.
+        assert.ok(patchBytes.includes(0xe9), "exported patch lost the original non-UTF-8 bytes");
+        assert.ok(!patchBytes.includes(Buffer.from("\uFFFD")), "exported patch contains a replacement character");
+        assert.equal(status(root), "");
+        assert.equal(git(root, "rev-parse", "HEAD").trim(), head);
+
+        const applyTarget = fs.mkdtempSync(path.join(os.tmpdir(), "specpi-experiment-apply-smoke-"));
+        try {
+            git(applyTarget, "clone", "--quiet", root, applyTarget);
+            git(applyTarget, "apply", "--check", exported.outputPath);
+        } finally {
+            fs.rmSync(applyTarget, { recursive: true, force: true });
+        }
+
+        await discardExperiment({ exec: run, stateDir, record });
+        assert.equal(fs.existsSync(record.worktreePath), false);
+
+        return "guided-experiment-worktrees-smoke passed: detached create, byte-exact appliable export of committed and dirty work, disclosed ignored work, clean base, and discard verified";
+    } finally {
+        fs.rmSync(root, { recursive: true, force: true });
+        fs.rmSync(stateDir, { recursive: true, force: true });
+    }
+}
+
+async function challengeSmoke() {
+    const submission = {
+        verdict: "ready-for-human-review",
+        requirements: [{ requirement: "Direct check", status: "proven", evidence: "Smoke passed" }],
+        contradictions: [],
+        falsePositiveChecks: [],
+        scopeFindings: [],
+        validationGaps: [],
+        residualRisks: ["Model-authored review"],
+        nextAction: "Human reviews the result",
+    };
+    assert.equal(validateChallengeSubmission(submission, { pendingScope: [] }).verdict, "ready-for-human-review");
+    assert.throws(
+        () => validateChallengeSubmission(submission, { pendingScope: ["outside.txt"] }),
+        /scope drift remains pending/,
+    );
+    assert.throws(
+        () =>
+            validateChallengeSubmission({ ...submission, contradictions: ["A check disagrees"] }, { pendingScope: [] }),
+        /contradictory evidence/,
+    );
+
+    return "completion-challenge-smoke passed: structured readiness and deterministic rejection gates verified";
+}
+
+export async function runWorkflowControlsSmoke(name) {
+    if (name === "scope-drift-monitor-smoke") {
+        return scopeSmoke();
+    }
+
+    if (name === "guided-experiment-worktrees-smoke") {
+        return experimentSmoke();
+    }
+
+    if (name === "completion-challenge-smoke") {
+        return challengeSmoke();
+    }
+
+    throw new Error(`Unknown workflow-controls smoke: ${name}`);
+}
+
+const invokedDirectly =
+    Boolean(process.argv[1]) &&
+    (process.platform === "win32"
+        ? path.resolve(process.argv[1]).toLowerCase() === fileURLToPath(import.meta.url).toLowerCase()
+        : path.resolve(process.argv[1]) === fileURLToPath(import.meta.url));
+if (invokedDirectly) {
+    runWorkflowControlsSmoke(process.argv[2])
+        .then((message) => console.log(message))
+        .catch((error) => {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        });
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "specpi",
+  "version": "0.10.0",
+  "description": "An explicit, privacy-conscious, self-improving harness for the Pi coding agent",
+  "author": "Tanner Middleton",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TannerMidd/SpecPi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TannerMidd/SpecPi/issues"
+  },
+  "homepage": "https://github.com/TannerMidd/SpecPi#readme",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "agent-harness"
+  ],
+  "bin": {
+    "specpi": "./scripts/specpi.mjs"
+  },
+  "files": [
+    "specpi",
+    "specpi.cmd",
+    "scripts",
+    "browser-runtime",
+    "templates",
+    "extensions",
+    "skills",
+    "themes",
+    "shell",
+    "README.md",
+    "site/logo.svg",
+    "site/self-improvement-loop-v2.svg",
+    "SECURITY.md",
+    "SECURITY_MODEL.md",
+    "THIRD_PARTY.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NPM_RELEASE.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "format": "prettier --write \"**/*.{js,mjs,ts,tsx}\" && eslint . --fix --rule \"@stylistic/max-statements-per-line: off\" && prettier --write \"**/*.{js,mjs,ts,tsx}\" && eslint . --fix",
+    "format:check": "prettier --check \"**/*.{js,mjs,ts,tsx}\" && eslint .",
+    "check:package": "node scripts/check-package.mjs",
+    "check:pi-package": "node scripts/check-pi-package.mjs",
+    "prepublishOnly": "npm run check",
+    "check": "npm run format:check && node --check scripts/specpi.mjs && node --check scripts/lib.mjs && node --check scripts/lock.mjs && node --check scripts/check-release-order.mjs && node --check scripts/verify-artifact.mjs && node --check extensions/spec/core.mjs && node --experimental-strip-types --check extensions/command-guard/index.ts && node --check extensions/command-guard/core.mjs && node --check extensions/command-guard/rules.mjs && node --check extensions/command-guard/bash.mjs && node --check extensions/command-guard/powershell.mjs && node --check extensions/command-guard/cmd.mjs && node --check extensions/command-guard/paths.mjs && node --check extensions/command-guard/redact.mjs && node --check extensions/command-guard/managed-files.mjs && node --check extensions/command-guard/smoke.mjs && node --check extensions/files/core.mjs && node --check extensions/tool-wishlist/core.mjs && node --check extensions/tool-wishlist/registry.mjs && node --check extensions/tool-wishlist/validators.mjs && node --experimental-strip-types --check extensions/tool-wishlist/index.ts && node --experimental-strip-types --check extensions/ui-refresh/index.ts && node --experimental-strip-types --check extensions/workflow-controls/index.ts && node --check extensions/workflow-controls/scope.mjs && node --check extensions/workflow-controls/experiments.mjs && node --check extensions/workflow-controls/challenge.mjs && node --check extensions/workflow-controls/smoke.mjs && node --check extensions/browser/core.mjs && node --check extensions/browser/smoke.mjs && node --check site/cycle.js && node --test && npm run check:package"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "5.10.0",
+    "@typescript-eslint/parser": "8.68.0",
+    "eslint": "10.9.1",
+    "prettier": "3.9.6",
+    "typescript": "6.0.3"
+  }
+}