superpowers-manager 0.3.0 → 0.5.0

package/dist/commands/prepare.js

@@ -1,39 +1,16 @@
-import { cp, mkdir, rm, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { mkdir, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, sep } from "node:path";
 import { atomicReplaceDir } from "../atomic.js";
 import { oneLine } from "../cli-arguments.js";
 import { computeEffectiveSelection } from "../effective-selection.js";
 import { runGit } from "../git.js";
-import { readManifest } from "../hooks.js";
-import { writeProvenance } from "../provenance.js";
 import { SafetyError } from "../safety-error.js";
-import { manifestVersionForRef } from "../upstream-version.js";
 import { fetchExactCommit, gitSafeSource } from "../upstream.js";
+import { upstreamCacheRoot } from "../upstream-workspace.js";
 import { BOUNDED_EXECUTABLE, UNBOUNDED_LEGACY, launchFailureMessage, resolveValidator, runValidator, displayPath, } from "../validator.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
 import { replayOutcome } from "./probe.js";
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:64-67::spw_require_upstream_path "$cache/skills`, via spw_require_upstream_path. Order is the shell's;
-// the first miss wins.
-const REQUIRED_UPSTREAM = [
-    { path: "skills", label: "skills/" },
-    { path: "LICENSE", label: "LICENSE" },
-    { path: "README.md", label: "README.md" },
-    { path: "CODE_OF_CONDUCT.md", label: "CODE_OF_CONDUCT.md" },
-];
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:73-77::spw_copy_path_if_present "$cache/skills`. Same names on both sides.
-const COPY_PATHS = [
-    "skills",
-    "assets",
-    "LICENSE",
-    "README.md",
-    "CODE_OF_CONDUCT.md",
-];
-const RESOLUTION_KINDS = [
-    "latest-release",
-    "tag",
-    "ref",
-    "raw-commit",
-];
+import { runWithMutation } from "./mutation.js";
 // Every message this module writes is hand-written here. The cause is attached
 // for debuggability and never reaches a stream: oneLine (src/cli-arguments.ts)
 // reads .message only. Same arrangement as hookError
@@ -41,28 +18,10 @@ const RESOLUTION_KINDS = [
 function prepareError(message, cause) {
     return new SafetyError("prepare", message, { cause });
 }
-// `[ -e ]` — follows symlinks, so a dangling link is absent to the shell too.
-// Two call sites, each mirroring a distinct `-e` in the shell: the
-// REQUIRED_UPSTREAM loop
-// (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/common.sh:53-59::spw_require_upstream_path`
-// — e.g. skills/ is a directory, not a regular file) and copyPathIfPresent's
-// guard (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/common.sh:44-51::spw_copy_path_if_present`). The `.git`
-// check below is NOT a third site: it needs `-d` (F1), not `-e`, and uses
-// directoryExists instead.
-async function pathExists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-// `[ -f ]` — regular file. `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:42::missing`, :80, and :108 all use -f, and
+// `[ -f ]` — regular file. `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:108::[ -f "$additional_validator` uses -f, and
 // tests/baseline/cli-parity.test.js's "CLI-ENV-MANIFEST-TEMPLATE-01 fallback
-// template bytes and non-file rejection" asserts a DIRECTORY passed as
-// SUPERPOWERS_MANIFEST_TEMPLATE is rejected before any adapter build. A
-// stat-only predicate would accept it.
+// template bytes and non-file rejection" also covers the separately extracted
+// fallback check.
 async function regularFileExists(path) {
     try {
         return (await stat(path)).isFile();
@@ -84,8 +43,8 @@ async function directoryExists(path) {
         return false;
     }
 }
-// mkdir, cp, and rm throw raw ErrnoExceptions. Every prepare-owned call goes
-// through here so the message on the stream is this module's, not Node's.
+// mkdir throws raw ErrnoExceptions. Every command-owned call goes through here
+// so the message on the stream is this module's, not Node's.
 async function owned(message, fn) {
     try {
         return await fn();
@@ -94,50 +53,6 @@ async function owned(message, fn) {
         throw prepareError(message, cause);
     }
 }
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/common.sh:44-51::spw_copy_path_if_present`.
-// `cp -R` copies symlinks AS symlinks;
-// fs.cp's default rewrites relative link targets against the destination,
-// which would change what the adapter's containment checks see.
-async function copyPathIfPresent(source, destination) {
-    if (!(await pathExists(source)))
-        return;
-    await owned(`cannot clear candidate path: ${destination}`, () => rm(destination, { recursive: true, force: true }));
-    await owned(`cannot copy upstream path into candidate: ${source}`, () => cp(source, destination, { recursive: true, verbatimSymlinks: true }));
-}
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:17-24::case "$cache_parent`. Only cache_parent and plugin_root are resolved against
-// the invocation cwd; manifest_template (:14) is not.
-function resolveFromCwd(value, cwd) {
-    return isAbsolute(value) ? value : resolve(cwd, value);
-}
-// readManifest (`src/hooks.ts:113::readManifest`) owns the read and the parse completely: byte
-// read so invalid UTF-8 is rejected rather than replaced, cause dropped, three
-// hand-written messages naming the path, object check included. Its
-// diagnostics are pinned by
-// `tests/unit/hooks.test.js:108::void test("readManifest diagnostics`. This wrapper adds only
-// the `version` type check.
-export async function readUpstreamManifestVersion(path) {
-    const manifest = await readManifest(path);
-    const value = manifest.version;
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/provenance.sh:56-62::for part in dotted_key.split`
-    // — absent key and JSON null both yield "".
-    if (value === undefined || value === null)
-        return "";
-    if (typeof value !== "string") {
-        // The shell stringified any other type through Python's print()
-        // (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/provenance.sh:62::print(value`), so `"version": 6` became "6" and flowed into both the
-        // provenance record and --upstream-manifest-version. Fail closed instead.
-        // Spec divergence 7.
-        throw prepareError(`upstream manifest version is not a string: ${path}`);
-    }
-    return value;
-}
-function asResolutionKind(value) {
-    for (const kind of RESOLUTION_KINDS) {
-        if (kind === value)
-            return kind;
-    }
-    throw prepareError(`unknown upstream resolution kind: ${value}`);
-}
 // Each stream's marker goes to that stream's own destination, so a reader of either
 // sees its own truncation and neither is silently short.
 function withTruncationMarker(captured, stream) {
@@ -167,34 +82,66 @@ function disclosureLine(resolution) {
     return `[superpowers-manager: running external validator ${configured}${via} -> ${displayPath(resolution.resolved)}]\n`;
 }
 const NO_VALIDATOR_OUTPUT = { stdout: "", stderr: "" };
+function validStagingLeaf(value) {
+    return (value.length > 0 &&
+        value !== "." &&
+        value !== ".." &&
+        !value.includes("/") &&
+        !value.includes("\\"));
+}
 async function gatherPrepare(ctx) {
     const env = ctx.env;
     // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:16::invocation_root=` — captured before the two case statements below.
     // getcwd(3) returns the physical path, so this matches `pwd -P` without a
     // realpath call.
     const cwd = process.cwd();
-    const cacheParent = resolveFromCwd(env.SUPERPOWERS_CACHE_DIR || join(ctx.root, ".cache", "upstream"), cwd);
-    const pluginRoot = resolveFromCwd(env.SUPERPOWERS_PLUGIN_ROOT || join(ctx.root, "plugins", "superpowers"), cwd);
-    const manifestTemplate = env.SUPERPOWERS_MANIFEST_TEMPLATE ||
-        join(ctx.root, "plugins", "superpowers", ".codex-plugin", "plugin.template.json");
+    const cache = upstreamCacheRoot(ctx.root, env, cwd);
+    const cacheParent = dirname(cache);
+    const adapterContext = { root: ctx.root, env };
+    let location;
+    try {
+        location = ctx.adapter.preparationLocation(adapterContext);
+    }
+    catch (cause) {
+        throw prepareError("cannot determine preparation location", cause);
+    }
+    if (!isAbsolute(location.destinationRoot)) {
+        throw prepareError("adapter returned a non-absolute preparation destination");
+    }
+    if (!validStagingLeaf(location.stagingLeaf)) {
+        throw prepareError("adapter returned an invalid preparation staging leaf");
+    }
+    const pluginRoot = location.destinationRoot;
     const additionalValidator = env.SUPERPOWERS_VALIDATOR || "";
     const executableValidator = env.SUPERPOWERS_VALIDATOR_EXECUTABLE || "";
-    const cache = join(cacheParent, "superpowers");
     const tmpParent = dirname(pluginRoot);
     await owned(`cannot create directory: ${tmpParent}`, () => mkdir(tmpParent, { recursive: true }));
     let cleanupWarning = null;
     const outcome = await withWorkspace(tmpParent, ".superpowers.prepare.", async (workspace) => {
+        const outcomes = [];
         const failed = (message) => ({
             kind: "failed",
-            outcomes: [],
+            outcomes,
             validator: NO_VALIDATOR_OUTPUT,
             message,
         });
-        const candidate = join(workspace, "superpowers");
-        const selection = await computeEffectiveSelection(ctx.root, env);
-        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:42::missing` — `[ -f ]`.
-        if (!(await regularFileExists(manifestTemplate))) {
-            return failed(`missing fallback manifest template: ${manifestTemplate}`);
+        const candidate = join(workspace, location.stagingLeaf);
+        const selection = ctx.selection ?? (await computeEffectiveSelection(ctx.root, env));
+        let prefetch;
+        try {
+            prefetch =
+                await ctx.adapter.validatePreparationBeforeFetch(adapterContext);
+        }
+        catch {
+            return failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
+                .unexpected);
+        }
+        outcomes.push(prefetch.outcome);
+        if (!prefetch.outcome.ok)
+            return failed(null);
+        if (prefetch.status !== 0) {
+            return failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
+                .invalidStatus);
         }
         await owned(`cannot create directory: ${cacheParent}`, () => mkdir(cacheParent, { recursive: true }));
         if (selection.selectionMode === "pinned") {
@@ -237,86 +184,34 @@ async function gatherPrepare(ctx) {
         if (checkedOut.status !== 0) {
             return failed(`cannot check out upstream commit: ${selection.desiredCommit}`);
         }
-        for (const required of REQUIRED_UPSTREAM) {
-            // spw_require_upstream_path is `[ -e ]`, not `[ -f ]`: skills/ is a
-            // directory.
-            if (!(await pathExists(join(cache, required.path)))) {
-                return failed(`required upstream path missing: ${required.label}`);
-            }
+        let prepared;
+        try {
+            prepared = await ctx.adapter.prepareCandidate({
+                upstreamRoot: cache,
+                workspaceRoot: workspace,
+                candidateRoot: candidate,
+                selection,
+            }, adapterContext);
         }
-        await owned(`cannot clear candidate root: ${candidate}`, () => rm(candidate, { recursive: true, force: true }));
-        await owned(`cannot create candidate root: ${candidate}`, () => mkdir(join(candidate, ".codex-plugin"), { recursive: true }));
-        for (const name of COPY_PATHS) {
-            await copyPathIfPresent(join(cache, name), join(candidate, name));
+        catch {
+            return failed(ctx.adapter.presentation.callFailure("prepare", adapterContext)
+                .unexpected);
         }
-        const upstreamManifest = join(cache, ".codex-plugin", "plugin.json");
-        let upstreamManifestVersion = "";
-        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:80::if [ -f` — `[ -f ]`.
-        if (await regularFileExists(upstreamManifest)) {
-            upstreamManifestVersion =
-                await readUpstreamManifestVersion(upstreamManifest);
+        outcomes.push(prepared.outcome);
+        if (prepared.status !== 0 || !prepared.outcome.ok) {
+            return failed(prepared.outcome.ok
+                ? ctx.adapter.presentation.callFailure("prepare", adapterContext)
+                    .invalidStatus
+                : null);
         }
-        await writeProvenance(join(candidate, ".superpowers-upstream.json"), {
-            source: selection.effectiveSource,
-            requested_ref: selection.requestedRef,
-            resolved_ref: selection.resolvedRef,
-            commit: selection.desiredCommit,
-            upstream_manifest_version: upstreamManifestVersion,
-        });
-        const managerVersion = manifestVersionForRef({
-            requestedRef: selection.requestedRef,
-            resolutionKind: asResolutionKind(selection.resolutionKind),
-            resolvedRef: selection.resolvedRef,
-            commit: selection.desiredCommit,
-        });
-        let built;
-        try {
-            built = await ctx.adapter([
-                "build",
-                "--upstream-root",
-                cache,
-                "--candidate-root",
-                candidate,
-                "--requested-ref",
-                selection.requestedRef,
-                "--resolved-ref",
-                selection.resolvedRef,
-                "--commit",
-                selection.desiredCommit,
-                "--manager-version",
-                managerVersion,
-                "--upstream-manifest-version",
-                upstreamManifestVersion,
-                "--fallback-manifest",
-                manifestTemplate,
-            ], { root: ctx.root, env });
+        if (prepared.outcome.result.root !== candidate) {
+            return failed("adapter returned an unexpected preparation root");
         }
-        catch {
-            // ctx.adapter reports CONTROLLED failures by return value
-            // (`src/adapter-result.ts:32-35::export interface AdapterResult`) but still THROWS for a
-            // non-AdapterFailure cause (runAdapter's closing `throw cause`,
-            // src/adapter.ts). That cause is by construction the one failure
-            // src/adapter.ts declined to own, so its text must never reach
-            // ctx.stderr. Caught here rather than in runPrepare's outer catch,
-            // the same treatment
-            // `src/commands/probe.ts:205-228::It does still THROW for a non-AdapterFailure cause`
-            // gives it.
-            return failed("cannot build the generated plugin candidate");
+        if (prepared.outcome.result.commit !== selection.desiredCommit) {
+            return failed("adapter returned an unexpected preparation commit");
         }
-        const outcomes = [built.outcome];
-        if (built.status !== 0 || !built.outcome.ok) {
-            return {
-                kind: "failed",
-                outcomes,
-                validator: NO_VALIDATOR_OUTPUT,
-                // replayOutcome emits the adapter's own error and hints; a second
-                // line here would duplicate them. The `ok && status !== 0`
-                // combination cannot arise from successResult/failureResult, so it
-                // gets its own hand-written message rather than a silent replay.
-                message: built.outcome.ok
-                    ? "adapter reported failure without an error outcome"
-                    : null,
-            };
+        if (prepared.outcome.result.compatibility.kind === "unsupported") {
+            return failed(prepared.outcome.result.compatibility.reason);
         }
         let validator = NO_VALIDATOR_OUTPUT;
         if (additionalValidator.length > 0) {
@@ -391,11 +286,12 @@ async function gatherPrepare(ctx) {
         // The swap must run inside the workspace callback: withWorkspace removes
         // the workspace on return, and the candidate lives in it.
         //
-        // atomicReplaceDir's outer catch (`src/atomic.ts:208-215::if (cause`) wraps every
-        // non-SafetyError into a SafetyError, so the callee owns every failure on
-        // this path and re-emitting its own diagnostic is the sanctioned form of
-        // interpolation. The hand-written prefix carries the live root, which the
-        // callee's message does not.
+        // atomicReplaceDir delegates to beginDirectoryPublication, whose outer
+        // catch (`src/atomic.ts:341-348::if (cause`) wraps every non-SafetyError
+        // into a SafetyError, so the callee owns every failure on this path and
+        // re-emitting its own diagnostic is the sanctioned form of interpolation.
+        // The hand-written prefix carries the live root, which the callee's message
+        // does not.
         try {
             await atomicReplaceDir(candidate, pluginRoot);
         }
@@ -426,6 +322,9 @@ async function gatherPrepare(ctx) {
     return { outcome, cleanupWarning };
 }
 export async function runPrepare(argv, ctx) {
+    return await runWithMutation("prepare", ctx, async (scoped) => performPrepare(argv, scoped));
+}
+async function performPrepare(argv, ctx) {
     // scripts/prepare never reads "$@", so extra arguments are ignored. This is a
     // deliberate asymmetry with probe, whose shell original rejected unknown
     // arguments and whose arity therefore moved into parseArgs in slice 2.
@@ -443,7 +342,7 @@ export async function runPrepare(argv, ctx) {
         // spawn error, which oneLine never reads -- it takes .message only);
         // readManifest's three hookError messages
         // (`src/hooks.ts:113-138::readManifest`), pinned by
-        // `tests/unit/hooks.test.js:108::void test("readManifest diagnostics` as carrying no reader vocabulary or
+        // `tests/unit/hooks.test.ts:95::void test("readManifest diagnostics` as carrying no reader vocabulary or
         // errno; and SafetyErrors from gitSafeSource, writeProvenance, and
         // withWorkspace.
         //
@@ -454,7 +353,7 @@ export async function runPrepare(argv, ctx) {
         //      This is the DEFAULT invocation -- plain `prepare`, `track-latest`,
         //      and any non-40-hex SUPERPOWERS_REF -- not an exotic corner. Pinned
         //      by
-        //      `tests/unit/upstream.test.js:460-469::void test("resolveRef reports a query failure for latest`,
+        //      `tests/unit/upstream.test.ts:453-462::void test("resolveRef reports a query failure for latest`,
         //      :471-481, and :483-501.
         //   2. fetchExactCommit splices the same combined stdout+stderr into its
         //      own text on the PINNED path (both of its own splice sites in
@@ -519,7 +418,7 @@ export async function runPrepare(argv, ctx) {
         // completed before cleanup ran, so it is not being reported as unverified
         // -- but something did still go wrong, and AGENTS.md's fail-closed rule
         // extends to it. Mirrors
-        // `src/commands/install.ts:503-510::if (cleanupWarning`.
+        // `src/commands/install.ts:546-554::if (cleanupWarning`.
         ctx.stderr.write(`error: ${cleanupWarning}\n`);
         return 1;
     }