superpowers-manager 0.4.0 → 0.5.0

package/dist/pi-package.js

@@ -0,0 +1,153 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmod, mkdir, symlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, addArtifactHashField, digestArtifactTree, readArtifactObject, } from "./artifact-tree.js";
+import { COMMIT_RE } from "./domain/refs.js";
+import { assertNoFollowType, assertSymlinkTargetContained, } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
+import { validateSource } from "./selection.js";
+import { assessPiCompatibility } from "./pi-compatibility.js";
+const exec = promisify(execFile);
+const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+// A consistency checksum, not authentication. A coherent manual rewrite of
+// both receipt and bytes remains possible; installed comparison must still use
+// an independently validated candidate.
+export function piReceiptBinding(receipt) {
+    const hash = createHash("sha256");
+    for (const field of [
+        String(receipt.schema),
+        receipt.manager,
+        receipt.harness,
+        receipt.source,
+        receipt.commit,
+        receipt.digest,
+    ])
+        addArtifactHashField(hash, Buffer.from(field));
+    return hash.digest("hex");
+}
+async function gitBytes(repository, args) {
+    try {
+        return (await exec("git", ["--no-replace-objects", "-C", repository, ...args], {
+            encoding: null,
+            maxBuffer: 256 * 1024 * 1024,
+        })).stdout;
+    }
+    catch (cause) {
+        throw new SafetyError("pi-package", `cannot read Pi tree objects from repository: ${repository}`, { cause });
+    }
+}
+export async function materializePiTree(repository, commit, destination) {
+    try {
+        if (!COMMIT_RE.test(commit))
+            throw new Error("commit");
+        if (!(await gitBytes(repository, ["cat-file", "-t", commit])).equals(Buffer.from("commit\n")))
+            throw new Error("not a commit");
+        await assertNoFollowType(destination, ["missing"]);
+        const bytes = await gitBytes(repository, [
+            "ls-tree",
+            "-rz",
+            "--full-tree",
+            commit,
+        ]);
+        const entries = [];
+        let offset = 0;
+        while (offset < bytes.length) {
+            const end = bytes.indexOf(0, offset);
+            if (end < 0)
+                throw new Error("tree framing");
+            const record = DECODER.decode(bytes.subarray(offset, end));
+            offset = end + 1;
+            const match = /^(100644|100755|120000) blob ([a-f0-9]{40})\t([\s\S]+)$/.exec(record);
+            if (!match)
+                throw new Error("tree entry");
+            const path = match[3];
+            if (path
+                .split("/")
+                .some((part) => !part ||
+                part === "." ||
+                part === ".." ||
+                part.toLowerCase() === ".git") ||
+                isAbsolute(path) ||
+                path.includes("\\") ||
+                path.split("/")[0] === ARTIFACT_RECEIPT)
+                throw new Error("tree path");
+            entries.push({ mode: match[1], oid: match[2], path });
+        }
+        await mkdir(destination, { recursive: true });
+        for (const entry of entries) {
+            await mkdir(dirname(join(destination, entry.path)), { recursive: true });
+        }
+        for (const entry of entries.filter((entry) => entry.mode !== "120000")) {
+            const path = join(destination, entry.path);
+            await writeFile(path, await gitBytes(repository, ["cat-file", "blob", entry.oid]), { flag: "wx", mode: entry.mode === "100755" ? 0o755 : 0o644 });
+            await chmod(path, entry.mode === "100755" ? 0o755 : 0o644);
+        }
+        for (const entry of entries.filter((entry) => entry.mode === "120000")) {
+            const target = DECODER.decode(await gitBytes(repository, ["cat-file", "blob", entry.oid]));
+            const path = join(destination, entry.path);
+            const suffix = relative(resolve(destination), resolve(dirname(path), target));
+            if (!target ||
+                target.includes("\0") ||
+                isAbsolute(target) ||
+                suffix === ".." ||
+                suffix.startsWith("../") ||
+                isAbsolute(suffix))
+                throw new Error("link escape");
+            await symlink(target, path);
+        }
+        for (const entry of entries.filter((entry) => entry.mode === "120000"))
+            await assertSymlinkTargetContained(destination, join(destination, entry.path));
+    }
+    catch (cause) {
+        throw new SafetyError("pi-package", `cannot materialize Pi tree from ${repository} into ${destination}`, { cause });
+    }
+}
+export async function digestPiTree(root) {
+    return await digestArtifactTree(root);
+}
+export async function readPiReceipt(root) {
+    const path = join(root, ARTIFACT_RECEIPT);
+    try {
+        const value = await readArtifactObject(root, path);
+        if (value.schema !== 1 ||
+            value.manager !== "superpowers-manager" ||
+            value.harness !== "pi" ||
+            typeof value.source !== "string" ||
+            typeof value.commit !== "string" ||
+            !COMMIT_RE.test(value.commit) ||
+            typeof value.digest !== "string" ||
+            !ARTIFACT_DIGEST_RE.test(value.digest) ||
+            typeof value.binding !== "string" ||
+            !ARTIFACT_DIGEST_RE.test(value.binding))
+            throw new Error("receipt fields");
+        validateSource(value.source);
+        if (piReceiptBinding(value) !== value.binding)
+            throw new Error("receipt binding");
+        const compatibility = value.compatibility;
+        if (!compatibility ||
+            typeof compatibility !== "object" ||
+            Array.isArray(compatibility) ||
+            typeof compatibility.reason !== "string" ||
+            typeof compatibility.kind !== "string" ||
+            !["unknown", "unsupported", "supported", "experimental"].includes(compatibility.kind) ||
+            ((compatibility.kind === "supported" ||
+                compatibility.kind === "experimental") &&
+                typeof compatibility.generation !== "string"))
+            throw new Error("receipt compatibility");
+        return value;
+    }
+    catch (cause) {
+        throw new SafetyError("pi-package", `invalid Pi artifact receipt: ${path}`, { cause });
+    }
+}
+export async function readPiPackageAssessment(root) {
+    const receipt = await readPiReceipt(root);
+    if ((await digestPiTree(root)) !== receipt.digest)
+        throw new SafetyError("pi-package", `Pi artifact digest mismatch: ${root}`);
+    const compatibility = await assessPiCompatibility(root, {
+        effectiveSource: receipt.source,
+    });
+    return { receipt, compatibility };
+}

package/dist/pi-paths.js

@@ -0,0 +1,30 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+function homeDirectory(env) {
+    return env.HOME && env.HOME.length > 0 ? env.HOME : homedir();
+}
+function expandTilde(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return join(home, path.slice(2));
+    return path;
+}
+export function piPaths(env, cwd) {
+    const homeDir = resolve(cwd, homeDirectory(env));
+    const configured = env.PI_CODING_AGENT_DIR;
+    const selected = configured && configured.length > 0
+        ? expandTilde(configured, homeDir)
+        : join(homeDir, ".pi", "agent");
+    const agentDir = resolve(cwd, selected);
+    const managerRoot = join(agentDir, "superpowers-manager");
+    return {
+        homeDir,
+        agentDir,
+        settingsFile: join(agentDir, "settings.json"),
+        managerRoot,
+        preparedRoot: join(managerRoot, "prepared"),
+        installedRoot: join(managerRoot, "installed"),
+        recoveryRoot: join(managerRoot, "recovery"),
+    };
+}

package/dist/pi-prepare.js

@@ -0,0 +1,111 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { failureResult, successResult, } from "./adapter-result.js";
+import { ARTIFACT_RECEIPT } from "./artifact-tree.js";
+import { piPaths } from "./pi-paths.js";
+import { assessPiCompatibility, samePiSource } from "./pi-compatibility.js";
+import { digestPiTree, materializePiTree, readPiPackageAssessment, piReceiptBinding, } from "./pi-package.js";
+import { classifyPathNoFollow } from "./safe-path.js";
+export function piPreparationLocation(ctx) {
+    return {
+        destinationRoot: piPaths(ctx.env ?? {}, process.cwd()).preparedRoot,
+        stagingLeaf: "superpowers",
+    };
+}
+export async function preparePiCandidate(input, _ctx) {
+    try {
+        await materializePiTree(input.upstreamRoot, input.selection.desiredCommit, input.candidateRoot);
+        const compatibility = await assessPiCompatibility(input.candidateRoot, input.selection);
+        if (compatibility.kind === "unsupported" ||
+            compatibility.kind === "unknown")
+            return failureResult("prepare", "unsupported", compatibility.reason, [], []);
+        const digest = await digestPiTree(input.candidateRoot);
+        const identity = {
+            schema: 1,
+            manager: "superpowers-manager",
+            harness: "pi",
+            source: input.selection.effectiveSource,
+            commit: input.selection.desiredCommit,
+            digest,
+        };
+        const receipt = {
+            ...identity,
+            binding: piReceiptBinding(identity),
+            compatibility,
+        };
+        await writeFile(join(input.candidateRoot, ARTIFACT_RECEIPT), JSON.stringify(receipt) + "\n", { flag: "wx" });
+        return successResult("prepare", {
+            root: input.candidateRoot,
+            commit: receipt.commit,
+            identity: digest,
+            compatibility,
+        }, []);
+    }
+    catch {
+        return failureResult("prepare", "invalid-package", `cannot prepare Pi artifact: ${input.candidateRoot}`, [], []);
+    }
+}
+async function readArtifactAssessment(root) {
+    const { receipt, compatibility } = await readPiPackageAssessment(root);
+    return {
+        receipt,
+        artifact: {
+            root,
+            commit: receipt.commit,
+            identity: receipt.digest,
+            compatibility,
+        },
+    };
+}
+async function readArtifact(root) {
+    const { artifact } = await readArtifactAssessment(root);
+    const { compatibility } = artifact;
+    if (compatibility.kind !== "supported" &&
+        compatibility.kind !== "experimental")
+        throw new Error("unsupported profile");
+    return artifact;
+}
+export async function inspectPiPrepared(selection, ctx) {
+    const root = piPreparationLocation(ctx).destinationRoot;
+    const unknown = {
+        kind: "unknown",
+        reason: "Pi prepared compatibility evidence is missing",
+    };
+    try {
+        if ((await classifyPathNoFollow(join(root, ARTIFACT_RECEIPT))) === "missing")
+            return successResult("inspect-prepared", { kind: "needs-prepare", observedIdentity: "", compatibility: unknown }, []);
+        const { artifact, receipt } = await readArtifactAssessment(root);
+        if (artifact.commit !== selection.desiredCommit ||
+            !samePiSource(receipt.source, selection.effectiveSource))
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity: artifact.identity,
+                compatibility: unknown,
+            }, []);
+        if (artifact.compatibility.kind !== "supported" &&
+            artifact.compatibility.kind !== "experimental")
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity: artifact.identity,
+                compatibility: artifact.compatibility,
+            }, []);
+        return successResult("inspect-prepared", {
+            kind: "current",
+            artifact,
+            observedIdentity: artifact.identity,
+            compatibility: artifact.compatibility,
+        }, []);
+    }
+    catch {
+        return failureResult("inspect-prepared", "invalid-package", `cannot inspect Pi prepared artifact: ${root}`, [], []);
+    }
+}
+export async function readPiPrepared(ctx) {
+    const root = piPreparationLocation(ctx).destinationRoot;
+    try {
+        return successResult("read-prepared", await readArtifact(root), []);
+    }
+    catch {
+        return failureResult("read-prepared", "invalid-package", `cannot read Pi prepared artifact: ${root}`, [], []);
+    }
+}

package/dist/pi-presentation.js

@@ -0,0 +1,67 @@
+export const piPresentation = {
+    installNotice: "",
+    currentNotice: "The Superpowers Pi snapshot is current.",
+    renderProbe(facts) {
+        const fields = [
+            ["harness", "pi"],
+            ["desired_commit", facts.selection.desiredCommit],
+            ["prepared_identity", facts.prepared.observedIdentity],
+            ["installed_identity", facts.installed.observedIdentity],
+            ["installation_state", facts.installed.kind],
+            ["resource_state", facts.resourceState ?? "idle"],
+            ["ownership", facts.ownership.presentationValue],
+            ["conflicts", (facts.ownership.presentationConflicts ?? []).join("; ")],
+            ["update_control", facts.control.presentationValue],
+            ["compatibility", facts.compatibility.kind],
+            ["compatibility_reason", facts.compatibility.reason],
+            ["status", facts.status],
+        ];
+        return {
+            human: fields
+                .map(([key, value]) => `${key.replaceAll("_", " ")}: ${value || "not present"}\n`)
+                .join(""),
+            porcelain: fields.map(([key, value]) => `${key}=${value}\n`).join(""),
+        };
+    },
+    renderInstallVerification(_desiredCommit, receipt, inspection) {
+        if (receipt.status !== 0 || !receipt.outcome.ok)
+            return {
+                stdout: [],
+                stderr: [
+                    "error: Pi activation did not return a verified installation receipt",
+                ],
+            };
+        if (inspection.status !== 0 || !inspection.outcome.ok)
+            return receipt.outcome.result.missingVerificationOutput;
+        if (inspection.outcome.result.kind === "current")
+            return {
+                stdout: [
+                    "Installed the frozen Superpowers Pi snapshot. Restart Pi to load it.",
+                ],
+                stderr: [],
+            };
+        return inspection.outcome.result.kind === "absent"
+            ? receipt.outcome.result.missingVerificationOutput
+            : receipt.outcome.result.mismatchVerificationOutput;
+    },
+    renderRemovalCompletion(_ownership, removalInput) {
+        return removalInput.receiptDigest === null &&
+            removalInput.registrationIdentity === null
+            ? {
+                stdout: ["No managed Superpowers Pi installation is present."],
+                stderr: [],
+            }
+            : {
+                stdout: [
+                    "Removed the managed Superpowers Pi installation. Restart Pi to load the resulting state.",
+                ],
+                stderr: [],
+            };
+    },
+    callFailure(site) {
+        return {
+            unexpected: `Pi ${site} did not complete`,
+            invalidStatus: `Pi ${site} returned an invalid status`,
+        };
+    },
+};

package/dist/pi-settings.js

@@ -0,0 +1,171 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalizeProspectivePath } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson, } from "./strict-json.js";
+const SETTINGS_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+    maxDepth: 256,
+};
+// Pi 0.85.1's preliminary isLocalPath check excludes github:, but parseGitUrl
+// does not recognize that shorthand and parseSource falls back to local. Keep
+// that verified case locally inspectable; the remaining exact, case-sensitive
+// prefix policy stays bounded because widening it changes which settings
+// identities compare as paths.
+// Pi 0.85.1 source (isLocalPath, parseGitUrl, then parseSource's local fallback):
+// https://github.com/earendil-works/pi/blob/d981de1229ef899957bbe968bc8dcda02a21f477/packages/coding-agent/src/utils/paths.ts#L50-L64
+// https://github.com/earendil-works/pi/blob/d981de1229ef899957bbe968bc8dcda02a21f477/packages/coding-agent/src/utils/git.ts#L172-L179
+// https://github.com/earendil-works/pi/blob/d981de1229ef899957bbe968bc8dcda02a21f477/packages/coding-agent/src/core/package-manager.ts#L1460-L1470
+const REMOTE_SOURCE_PREFIXES = [
+    "npm:",
+    "git:",
+    "http:",
+    "https:",
+    "ssh:",
+];
+function invalid(path, detail, cause) {
+    throw new SafetyError("pi-settings", `invalid Pi settings ${path}: ${detail}`, {
+        cause,
+    });
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function requiredResourceState(entry) {
+    if (entry.autoload !== false &&
+        entry.skills === undefined &&
+        entry.extensions === undefined) {
+        return "enabled";
+    }
+    if (entry.skills?.length === 0 && entry.extensions?.length === 0) {
+        return "disabled";
+    }
+    if (entry.autoload === false &&
+        entry.skills === undefined &&
+        entry.extensions === undefined) {
+        return "disabled";
+    }
+    return "indeterminate";
+}
+function parsePackage(value, index, path) {
+    if (typeof value === "string") {
+        if (value.trim().length === 0) {
+            invalid(path, `package ${index} source must be a nonempty string`);
+        }
+        return { source: value, resourceState: "enabled" };
+    }
+    const entry = object(value);
+    if (entry === undefined) {
+        invalid(path, `package ${index} must be a string or object`);
+    }
+    if (typeof entry.source !== "string" || entry.source.trim().length === 0) {
+        invalid(path, `package ${index} source must be a nonempty string`);
+    }
+    if (entry.autoload !== undefined && typeof entry.autoload !== "boolean") {
+        invalid(path, `package ${index} autoload must be a boolean`);
+    }
+    if (entry.skills !== undefined && !stringArray(entry.skills)) {
+        invalid(path, `package ${index} skills must be an array of strings`);
+    }
+    if (entry.extensions !== undefined && !stringArray(entry.extensions)) {
+        invalid(path, `package ${index} extensions must be an array of strings`);
+    }
+    return {
+        source: entry.source,
+        resourceState: requiredResourceState({
+            ...(entry.autoload === undefined ? {} : { autoload: entry.autoload }),
+            ...(entry.skills === undefined ? {} : { skills: entry.skills }),
+            ...(entry.extensions === undefined
+                ? {}
+                : { extensions: entry.extensions }),
+        }),
+    };
+}
+function isMissing(cause) {
+    return (typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        cause.code === "ENOENT");
+}
+export function resolvePiLocalSource(source, agentDir, homeDir) {
+    let normalized = source.trim();
+    if (normalized.length === 0 ||
+        REMOTE_SOURCE_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+        return null;
+    }
+    if (normalized === "~" || normalized.startsWith("~/")) {
+        if (homeDir === undefined || homeDir.length === 0) {
+            throw new SafetyError("pi-settings", "cannot resolve Pi local source containing ~ without HOME");
+        }
+        normalized =
+            normalized === "~" ? homeDir : join(homeDir, normalized.slice(2));
+    }
+    else if (normalized.startsWith("file://")) {
+        try {
+            normalized = fileURLToPath(normalized);
+        }
+        catch (cause) {
+            throw new SafetyError("pi-settings", "cannot resolve Pi local source from invalid file URL", { cause });
+        }
+    }
+    return resolve(agentDir, normalized);
+}
+export async function resolveCanonicalPiLocalSource(source, agentDir, homeDir) {
+    const resolved = resolvePiLocalSource(source, agentDir, homeDir);
+    return resolved === null ? null : canonicalizeProspectivePath(resolved);
+}
+export async function readPiSettings(path, homeDir) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return { packages: [] };
+        throw new SafetyError("pi-settings", `cannot read Pi settings ${path}`, {
+            cause,
+        });
+    }
+    let parsed;
+    try {
+        parsed = parseStrictJson(bytes, SETTINGS_PROFILE);
+    }
+    catch (cause) {
+        throw new SafetyError("pi-settings", `cannot parse Pi settings ${path}`, {
+            cause,
+        });
+    }
+    const settings = object(parsed);
+    if (settings === undefined)
+        invalid(path, "settings must be an object");
+    if (settings.skills !== undefined && !stringArray(settings.skills)) {
+        invalid(path, "skills must be an array of strings");
+    }
+    if (settings.packages !== undefined && !Array.isArray(settings.packages)) {
+        invalid(path, "packages must be an array");
+    }
+    const packages = (settings.packages ?? []).map((entry, index) => parsePackage(entry, index, path));
+    const agentDir = dirname(resolve(path));
+    const managerInstallation = await canonicalizeProspectivePath(resolve(agentDir, join("superpowers-manager", "installed")));
+    const managerRegistrations = [];
+    for (const entry of packages) {
+        if ((await resolveCanonicalPiLocalSource(entry.source, agentDir, homeDir)) ===
+            managerInstallation) {
+            managerRegistrations.push(entry);
+        }
+    }
+    if (managerRegistrations.length > 1) {
+        invalid(path, "duplicate Manager package registrations");
+    }
+    return {
+        packages,
+        ...(settings.skills === undefined ? {} : { skills: settings.skills }),
+    };
+}