specpi 0.10.0

package/scripts/check-pi-package.mjs

@@ -0,0 +1,223 @@
+#!/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 process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..");
+const npmCli = process.env.npm_execpath;
+const artifactIndex = process.argv.indexOf("--artifact");
+const artifactPath = artifactIndex >= 0 ? process.argv[artifactIndex + 1] : undefined;
+const piPackage = "@earendil-works/pi-coding-agent";
+const piVersion = "0.84.4";
+const specpiVersion = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
+const hostPeerPackages = [
+    "@earendil-works/pi-ai",
+    "@earendil-works/pi-coding-agent",
+    "@earendil-works/pi-tui",
+    "typebox",
+];
+
+if ((artifactIndex >= 0 && !artifactPath) || (artifactIndex < 0 && process.argv.length > 2)) {
+    throw new Error("Use no arguments, or supply --artifact <tarball>");
+}
+
+if (!npmCli || !fs.existsSync(npmCli)) {
+    throw new Error("Run Pi package validation through npm so npm_execpath identifies the active npm CLI");
+}
+
+function runNode(args, options = {}) {
+    const result = spawnSync(process.execPath, args, {
+        cwd: options.cwd || repoRoot,
+        env: options.env || process.env,
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: options.timeout || 300_000,
+        maxBuffer: 20 * 1024 * 1024,
+    });
+    if (result.error) {
+        throw result.error;
+    }
+
+    if (result.status !== 0) {
+        throw new Error(
+            `${process.execPath} ${args.join(" ")} failed (${result.status})\n${result.stdout || ""}${result.stderr || ""}`,
+        );
+    }
+
+    return result;
+}
+
+function runNpm(args, options = {}) {
+    return runNode([npmCli, ...args], options);
+}
+
+const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "specpi-pi-package-check-"));
+try {
+    const prefix = path.join(temporaryRoot, "prefix");
+    const packDirectory = path.join(temporaryRoot, "pack");
+    const agentDir = path.join(temporaryRoot, "agent");
+    fs.mkdirSync(prefix, { recursive: true });
+    fs.mkdirSync(packDirectory, { recursive: true });
+    fs.mkdirSync(agentDir, { recursive: true });
+    const authPath = path.join(agentDir, "auth.json");
+    const authCanary = "{}\n";
+    fs.writeFileSync(authPath, authCanary, { mode: 0o600 });
+
+    const env = {
+        ...process.env,
+        PI_CODING_AGENT_DIR: agentDir,
+        npm_config_audit: "false",
+        npm_config_fund: "false",
+    };
+    let tarball;
+    let artifactLabel;
+    if (artifactPath) {
+        tarball = path.resolve(artifactPath);
+        artifactLabel = path.basename(tarball);
+    } else {
+        const packed = runNpm(["pack", "--pack-destination", packDirectory, "--json", "--ignore-scripts"], {
+            env,
+        });
+        const packResult = JSON.parse(packed.stdout)[0];
+        assert.ok(packResult?.filename, "npm pack did not report the SpecPi tarball");
+        tarball = path.join(packDirectory, packResult.filename);
+        artifactLabel = packResult.filename;
+    }
+
+    assert.ok(fs.existsSync(tarball), "the SpecPi tarball does not exist");
+
+    runNpm(
+        [
+            "install",
+            "--global",
+            "--prefix",
+            prefix,
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            `${piPackage}@${piVersion}`,
+        ],
+        { env, timeout: 600_000 },
+    );
+
+    const globalRoot = runNpm(["root", "--global", "--prefix", prefix], { env }).stdout.trim();
+    const piRoot = path.join(globalRoot, "@earendil-works", "pi-coding-agent");
+    const piManifest = JSON.parse(fs.readFileSync(path.join(piRoot, "package.json"), "utf8"));
+    assert.equal(piManifest.version, piVersion);
+    const piBin = typeof piManifest.bin === "string" ? piManifest.bin : piManifest.bin?.pi;
+    assert.equal(typeof piBin, "string");
+    const piCli = path.join(piRoot, piBin);
+    assert.ok(fs.existsSync(piCli), "the pinned Pi package did not provide its CLI entrypoint");
+    assert.equal(fs.existsSync(path.join(globalRoot, "specpi")), false, "SpecPi shared Pi's npm installation tree");
+
+    const npmWrapper = path.join(temporaryRoot, "candidate-npm.mjs");
+    fs.writeFileSync(
+        npmWrapper,
+        `import process from "node:process";\n` +
+            `import { spawnSync } from "node:child_process";\n` +
+            `const npmCli = ${JSON.stringify(npmCli)};\n` +
+            `const candidate = ${JSON.stringify(tarball)};\n` +
+            `const requested = ${JSON.stringify(`specpi@${specpiVersion}`)};\n` +
+            `const args = process.argv.slice(2).map((arg) => arg === requested ? candidate : arg);\n` +
+            `const result = spawnSync(process.execPath, [npmCli, ...args], { env: process.env, stdio: "inherit" });\n` +
+            `if (result.error) throw result.error;\n` +
+            `process.exitCode = result.status ?? 1;\n`,
+    );
+    fs.writeFileSync(
+        path.join(agentDir, "settings.json"),
+        `${JSON.stringify({ npmCommand: [process.execPath, npmWrapper] }, null, 2)}\n`,
+        { mode: 0o600 },
+    );
+
+    const npmSource = `npm:specpi@${specpiVersion}`;
+    runNode([piCli, "install", npmSource], { cwd: temporaryRoot, env });
+    const specpiRoot = path.join(agentDir, "npm", "node_modules", "specpi");
+    assert.ok(fs.existsSync(path.join(specpiRoot, "package.json")), "Pi did not install the npm package candidate");
+    assert.equal(JSON.parse(fs.readFileSync(path.join(specpiRoot, "package.json"), "utf8")).version, specpiVersion);
+    for (const peer of hostPeerPackages) {
+        const peerSegments = peer.split("/");
+        assert.equal(
+            fs.existsSync(path.join(agentDir, "npm", "node_modules", ...peerSegments)),
+            false,
+            `Pi installed host peer beside SpecPi: ${peer}`,
+        );
+        assert.equal(
+            fs.existsSync(path.join(specpiRoot, "node_modules", ...peerSegments)),
+            false,
+            `Pi installed host peer inside SpecPi: ${peer}`,
+        );
+    }
+
+    const listed = runNode([piCli, "list"], { cwd: temporaryRoot, env });
+    assert.match(listed.stdout, /User packages:/);
+    assert.match(listed.stdout, new RegExp(`npm:specpi@${specpiVersion.replaceAll(".", "\\.")}`));
+
+    const probePath = path.join(temporaryRoot, "resource-probe.mjs");
+    const piEntryUrl = pathToFileURL(path.join(piRoot, "dist", "index.js")).href;
+    fs.writeFileSync(
+        probePath,
+        `import { DefaultResourceLoader } from ${JSON.stringify(piEntryUrl)};\n` +
+            `const loader = new DefaultResourceLoader(${JSON.stringify({ cwd: temporaryRoot, agentDir })});\n` +
+            "await loader.reload();\n" +
+            "const extensionResult = loader.getExtensions();\n" +
+            "console.log('SPECPI_RESOURCE_PROBE=' + JSON.stringify({\n" +
+            "  extensionPaths: extensionResult.extensions.map((extension) => extension.resolvedPath),\n" +
+            "  extensionErrors: extensionResult.errors,\n" +
+            "  skillNames: loader.getSkills().skills.map((skill) => skill.name),\n" +
+            "  themeNames: loader.getThemes().themes.map((theme) => theme.name),\n" +
+            "}));\n",
+    );
+    const probeResult = runNode([probePath], { cwd: temporaryRoot, env });
+    const probeLine = probeResult.stdout.split(/\r?\n/).find((line) => line.startsWith("SPECPI_RESOURCE_PROBE="));
+    assert.ok(probeLine, `Pi resource probe did not return structured output:\n${probeResult.stdout}`);
+    const resources = JSON.parse(probeLine.slice("SPECPI_RESOURCE_PROBE=".length));
+    for (const expected of [
+        "/extensions/browser/index.ts",
+        "/extensions/command-guard/index.ts",
+        "/extensions/files/index.ts",
+        "/extensions/spec.ts",
+        "/extensions/tool-wishlist/index.ts",
+        "/extensions/ui-refresh/index.ts",
+        "/extensions/workflow-controls/index.ts",
+    ]) {
+        assert.ok(
+            resources.extensionPaths.some((entry) => entry.replaceAll("\\", "/").endsWith(expected)),
+            `Pi did not discover ${expected}: ${JSON.stringify(resources)}`,
+        );
+    }
+
+    assert.deepEqual(resources.extensionErrors, [], `Pi reported extension load errors: ${JSON.stringify(resources)}`);
+    assert.ok(resources.skillNames.includes("specpi-improve"), "Pi did not discover the SpecPi improvement skill");
+    assert.ok(resources.skillNames.includes("donsetch"), "Pi did not discover the DonSeTch skill");
+    assert.ok(resources.themeNames.includes("specpi-spec"), "Pi did not discover the SpecPi theme");
+    assert.ok(resources.themeNames.includes("tea-house"), "Pi did not discover the tea-house theme");
+
+    const loaded = runNode([piCli, "--offline", "--no-session", "--no-context-files", "--list-models", "gpt"], {
+        env,
+        timeout: 300_000,
+    });
+    assert.doesNotMatch(
+        `${loaded.stdout}\n${loaded.stderr}`,
+        /failed to load|cannot find package|ERR_MODULE_NOT_FOUND/i,
+    );
+    assert.equal(fs.readFileSync(authPath, "utf8"), authCanary, "Pi package smoke modified authentication state");
+    assert.equal(
+        fs.existsSync(path.join(specpiRoot, "browser-runtime", "node_modules")),
+        false,
+        "native package unexpectedly bundled the managed browser runtime",
+    );
+    const browserCore = await import(pathToFileURL(path.join(specpiRoot, "extensions", "browser", "core.mjs")).href);
+    await assert.rejects(
+        browserCore.loadBrowserRuntime(path.join(agentDir, "specpi", "browser-runtime")),
+        /SpecPi browser runtime is not installed.*Run specpi update/s,
+    );
+
+    console.log(`Pi package check passed: ${artifactLabel} loaded through Pi ${piVersion}`);
+} finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+}

package/scripts/check-release-order.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import process from "node:process";
+
+function parseVersion(value, label) {
+    const match =
+        /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+            value || "",
+        );
+    if (!match) {
+        throw new Error(`${label} is not a semantic version: ${value || "<empty>"}`);
+    }
+
+    const prerelease = match[4]?.split(".") || [];
+    if (
+        prerelease.some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith("0"))
+    ) {
+        throw new Error(`${label} has a numeric prerelease identifier with a leading zero: ${value}`);
+    }
+
+    return {
+        core: match.slice(1, 4),
+        prerelease,
+    };
+}
+
+function compareNumericIdentifiers(left, right) {
+    if (left.length !== right.length) {
+        return left.length > right.length ? 1 : -1;
+    }
+
+    return left === right ? 0 : left > right ? 1 : -1;
+}
+
+function compareIdentifiers(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        return compareNumericIdentifiers(left, right);
+    }
+
+    if (leftNumeric !== rightNumeric) {
+        return leftNumeric ? -1 : 1;
+    }
+
+    return left === right ? 0 : left > right ? 1 : -1;
+}
+
+function compareVersions(left, right) {
+    for (let index = 0; index < left.core.length; index += 1) {
+        const compared = compareNumericIdentifiers(left.core[index], right.core[index]);
+        if (compared !== 0) {
+            return compared;
+        }
+    }
+
+    if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+        if (left.prerelease.length === right.prerelease.length) {
+            return 0;
+        }
+
+        return left.prerelease.length === 0 ? 1 : -1;
+    }
+
+    const length = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        if (left.prerelease[index] === undefined || right.prerelease[index] === undefined) {
+            return left.prerelease[index] === undefined ? -1 : 1;
+        }
+
+        const compared = compareIdentifiers(left.prerelease[index], right.prerelease[index]);
+        if (compared !== 0) {
+            return compared;
+        }
+    }
+
+    return 0;
+}
+
+const [command, candidateValue, currentValue] = process.argv.slice(2);
+try {
+    const candidate = parseVersion(candidateValue, "candidate version");
+    if (command === "tag") {
+        console.log(candidate.prerelease.length === 0 ? "latest" : "next");
+    } else if (command === "advance") {
+        const current = parseVersion(currentValue, "current dist-tag version");
+        if (compareVersions(candidate, current) <= 0) {
+            throw new Error(`candidate ${candidateValue} would not advance its dist-tag from ${currentValue}`);
+        }
+
+        console.log(`Release order check passed: ${candidateValue} advances its dist-tag from ${currentValue}`);
+    } else {
+        throw new Error("Usage: check-release-order.mjs tag <version> | advance <candidate> <current>");
+    }
+} catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/scripts/lib.mjs

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+
+export const AGENTS_START = "<!-- specpi:start -->";
+export const AGENTS_END = "<!-- specpi:end -->";
+export const SHELL_START = "# >>> SpecPi >>>";
+export const SHELL_END = "# <<< SpecPi <<<";
+
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+
+export function deepEqual(a, b) {
+    return isDeepStrictEqual(a, b);
+}
+
+export function packageSource(entry) {
+    return typeof entry === "string" ? entry : entry?.source;
+}
+
+export function packageIdentity(entry) {
+    const source = packageSource(entry);
+    if (typeof source !== "string") {
+        return undefined;
+    }
+
+    if (!source.startsWith("npm:")) {
+        return source;
+    }
+
+    const spec = source.slice(4);
+    if (spec.startsWith("@")) {
+        const slash = spec.indexOf("/");
+        const versionAt = slash < 0 ? -1 : spec.indexOf("@", slash);
+
+        return `npm:${versionAt < 0 ? spec : spec.slice(0, versionAt)}`;
+    }
+
+    const versionAt = spec.lastIndexOf("@");
+
+    return `npm:${versionAt > 0 ? spec.slice(0, versionAt) : spec}`;
+}
+
+export function mergePackages(existing, desired) {
+    const result = Array.isArray(existing) ? structuredClone(existing) : [];
+    for (const wanted of desired) {
+        const identity = packageIdentity(wanted);
+        const index = result.findIndex((entry) => packageIdentity(entry) === identity);
+        if (index >= 0) {
+            result[index] = structuredClone(wanted);
+        } else {
+            result.push(structuredClone(wanted));
+        }
+    }
+
+    return result;
+}
+
+export function restorePackageChanges(current, changes, warnings = []) {
+    const result = Array.isArray(current) ? structuredClone(current) : [];
+    for (const change of changes) {
+        const currentIndex = result.findIndex((entry) => packageIdentity(entry) === change.identity);
+        if (currentIndex < 0 || !deepEqual(result[currentIndex], change.installed)) {
+            warnings.push(`Preserved modified package setting: ${change.identity}`);
+            continue;
+        }
+
+        if (change.beforeExists) {
+            result[currentIndex] = structuredClone(change.before);
+        } else {
+            result.splice(currentIndex, 1);
+        }
+    }
+
+    return result;
+}
+
+function markerRange(text, start, end) {
+    const startIndex = text.indexOf(start);
+    const endIndex = text.indexOf(end);
+    if (startIndex < 0 !== endIndex < 0) {
+        throw new Error(`Malformed managed block: expected both ${start} and ${end}`);
+    }
+
+    if (startIndex < 0) {
+        return undefined;
+    }
+
+    if (text.indexOf(start, startIndex + start.length) >= 0 || text.indexOf(end, endIndex + end.length) >= 0) {
+        throw new Error(`Malformed managed block: duplicate ${start} or ${end}`);
+    }
+
+    if (endIndex < startIndex) {
+        throw new Error(`Malformed managed block: ${end} precedes ${start}`);
+    }
+
+    return { startIndex, endIndex: endIndex + end.length };
+}
+
+export function upsertManagedBlock(text, start, end, body) {
+    const normalized = String(text ?? "").replace(/\r\n/g, "\n");
+    const block = `${start}\n${String(body).trim()}\n${end}`;
+    const range = markerRange(normalized, start, end);
+    if (!range) {
+        return `${normalized.trimEnd()}${normalized.trim() ? "\n\n" : ""}${block}\n`;
+    }
+
+    const before = normalized.slice(0, range.startIndex).trimEnd();
+    const after = normalized.slice(range.endIndex).trimStart();
+
+    return `${before}${before ? "\n\n" : ""}${block}${after ? `\n\n${after}` : "\n"}`;
+}
+
+export function removeManagedBlock(text, start, end) {
+    const normalized = String(text ?? "").replace(/\r\n/g, "\n");
+    const range = markerRange(normalized, start, end);
+    if (!range) {
+        return normalized;
+    }
+
+    const before = normalized.slice(0, range.startIndex).trimEnd();
+    const after = normalized.slice(range.endIndex).trimStart();
+    if (!before && !after) {
+        return "";
+    }
+
+    return `${before}${before && after ? "\n\n" : ""}${after}\n`;
+}
+
+export function readPath(object, pathParts) {
+    let current = object;
+    for (const part of pathParts) {
+        if (current === null || typeof current !== "object" || !Object.hasOwn(current, part)) {
+            return { exists: false, value: undefined };
+        }
+
+        current = current[part];
+    }
+
+    return { exists: true, value: structuredClone(current) };
+}
+
+export function setPath(object, pathParts, value) {
+    let current = object;
+    for (const part of pathParts.slice(0, -1)) {
+        if (current[part] === null || typeof current[part] !== "object" || Array.isArray(current[part])) {
+            current[part] = {};
+        }
+
+        current = current[part];
+    }
+
+    current[pathParts.at(-1)] = structuredClone(value);
+}
+
+export function deletePath(object, pathParts) {
+    let current = object;
+    const parents = [];
+    for (const part of pathParts.slice(0, -1)) {
+        if (current === null || typeof current !== "object" || !Object.hasOwn(current, part)) {
+            return;
+        }
+
+        parents.push([current, part]);
+        current = current[part];
+    }
+
+    if (!current || typeof current !== "object") {
+        return;
+    }
+
+    delete current[pathParts.at(-1)];
+
+    for (const [parent, key] of parents.reverse()) {
+        const child = parent[key];
+        if (child && typeof child === "object" && !Array.isArray(child) && Object.keys(child).length === 0) {
+            delete parent[key];
+        } else {
+            break;
+        }
+    }
+}

package/scripts/lock.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { randomBytes } from "node:crypto";
+
+function assertSafeLockPath(agentDir, lockPath) {
+    const root = path.resolve(agentDir);
+    let current = path.dirname(path.resolve(lockPath));
+    while (current !== root) {
+        try {
+            if (fs.lstatSync(current).isSymbolicLink()) {
+                throw new Error(`SpecPi refuses a symlinked lock parent: ${current}`);
+            }
+        } catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`SpecPi lock path escapes the agent directory: ${lockPath}`);
+        }
+
+        current = parent;
+    }
+
+    try {
+        if (fs.lstatSync(lockPath).isSymbolicLink()) {
+            throw new Error(`SpecPi refuses a symlinked lock target: ${lockPath}`);
+        }
+    } catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+
+function processState(pid) {
+    try {
+        process.kill(pid, 0);
+
+        return "active";
+    } catch (error) {
+        if (error?.code === "ESRCH") {
+            return "absent";
+        }
+
+        throw error;
+    }
+}
+
+export function acquireSpecPiLock(agentDir) {
+    const root = path.resolve(agentDir);
+    const stateDir = path.join(root, "specpi");
+    const lockPath = path.join(stateDir, "install.lock");
+    assertSafeLockPath(root, lockPath);
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const token = `${process.pid}:${randomBytes(12).toString("hex")}`;
+    const payload = `${JSON.stringify({ pid: process.pid, token })}\n`;
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, "wx", 0o600);
+    } catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+
+        const raw = fs.readFileSync(lockPath, "utf8").trim();
+        let pid;
+        if (/^[1-9]\d*$/.test(raw)) {
+            pid = Number(raw);
+        } else {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            } catch {
+                throw new Error(`SpecPi lock is malformed and was not reclaimed: ${lockPath}`);
+            }
+
+            if (
+                !parsed ||
+                typeof parsed !== "object" ||
+                Array.isArray(parsed) ||
+                !Number.isInteger(parsed.pid) ||
+                parsed.pid <= 0 ||
+                typeof parsed.token !== "string" ||
+                !parsed.token
+            ) {
+                throw new Error(`SpecPi lock is malformed and was not reclaimed: ${lockPath}`);
+            }
+
+            pid = parsed.pid;
+        }
+
+        if (processState(pid) === "active") {
+            throw new Error(`Another SpecPi operation appears active: ${lockPath}`);
+        }
+
+        if (fs.readFileSync(lockPath, "utf8").trim() !== raw) {
+            throw new Error(`SpecPi lock changed during recovery and was not reclaimed: ${lockPath}`);
+        }
+
+        fs.rmSync(lockPath);
+        fd = fs.openSync(lockPath, "wx", 0o600);
+    }
+
+    fs.writeFileSync(fd, payload);
+    fs.closeSync(fd);
+
+    return () => {
+        try {
+            if (fs.readFileSync(lockPath, "utf8") === payload) {
+                fs.rmSync(lockPath);
+            }
+        } catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    };
+}