superpowers-manager 0.2.0 → 0.3.0

package/dist/upstream-cli.js

@@ -0,0 +1,110 @@
+import { realpathSync } from "node:fs";
+import { oneLine, parseFlags, UsageError } from "./cli-arguments.js";
+import { COMMIT_INPUT_RE, TAG_RE } from "./domain/refs.js";
+import { fetchExactCommit, gitSafeSource, resolveExactTag, resolveRef, verifyRawCommit, } from "./upstream.js";
+import { manifestVersionForRef } from "./upstream-version.js";
+const COMMAND_FLAGS = {
+    "resolve-ref": ["source", "ref"],
+    "resolve-exact-tag": ["source", "ref"],
+    "verify-raw-commit": ["source", "commit", "workspace-parent"],
+    "fetch-exact-commit": ["source", "commit", "repository", "workspace-parent"],
+    "manifest-version": [
+        "requested-ref",
+        "resolution-kind",
+        "resolved-ref",
+        "commit",
+    ],
+    "pin-kind": ["ref"],
+    "safe-source": ["source"],
+};
+const RESOLUTION_KINDS = [
+    "latest-release",
+    "tag",
+    "ref",
+    "raw-commit",
+];
+function parseResolutionKind(value) {
+    const found = RESOLUTION_KINDS.find((kind) => kind === value);
+    if (found === undefined) {
+        throw new UsageError(`unknown resolution kind: ${value}`);
+    }
+    return found;
+}
+function parseCommand(argv) {
+    const [name, ...rest] = argv;
+    if (name === undefined)
+        throw new UsageError("a subcommand is required");
+    if (!Object.hasOwn(COMMAND_FLAGS, name)) {
+        throw new UsageError(`unknown subcommand: ${name}`);
+    }
+    const command = name;
+    return { name: command, flags: parseFlags(rest, COMMAND_FLAGS[command]) };
+}
+async function dispatch({ name, flags }) {
+    if (name === "resolve-ref") {
+        const resolution = await resolveRef(flags.source, flags.ref);
+        process.stdout.write(`${resolution.kind} ${resolution.ref} ${resolution.commit}\n`);
+        return;
+    }
+    if (name === "resolve-exact-tag") {
+        process.stdout.write(`${await resolveExactTag(flags.source, flags.ref)}\n`);
+        return;
+    }
+    if (name === "verify-raw-commit") {
+        const commit = await verifyRawCommit(flags.source, flags.commit, flags["workspace-parent"]);
+        process.stdout.write(`${commit}\n`);
+        return;
+    }
+    if (name === "fetch-exact-commit") {
+        await fetchExactCommit(flags.source, flags.commit, flags.repository, flags["workspace-parent"]);
+        return;
+    }
+    if (name === "manifest-version") {
+        const version = manifestVersionForRef({
+            requestedRef: flags["requested-ref"],
+            resolutionKind: parseResolutionKind(flags["resolution-kind"]),
+            resolvedRef: flags["resolved-ref"],
+            commit: flags.commit,
+        });
+        process.stdout.write(`${version}\n`);
+        return;
+    }
+    if (name === "pin-kind") {
+        const kind = TAG_RE.test(flags.ref)
+            ? "tag"
+            : COMMIT_INPUT_RE.test(flags.ref)
+                ? "raw-commit"
+                : "none";
+        process.stdout.write(`${kind}\n`);
+        return;
+    }
+    if (name === "safe-source") {
+        process.stdout.write(`${gitSafeSource(flags.source)}\n`);
+        return;
+    }
+    const unreachable = name;
+    throw new Error(`unhandled subcommand: ${String(unreachable)}`);
+}
+export async function runUpstreamCli(argv) {
+    let command;
+    try {
+        command = parseCommand(argv);
+    }
+    catch (cause) {
+        process.stderr.write(`usage: upstream-cli <subcommand> [options]\n`);
+        process.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 2;
+    }
+    try {
+        await dispatch(command);
+        return 0;
+    }
+    catch (cause) {
+        process.stderr.write(`error: ${oneLine(cause)}\n`);
+        return cause instanceof UsageError ? 2 : 1;
+    }
+}
+const entry = process.argv[1];
+if (entry !== undefined && import.meta.filename === realpathSync(entry)) {
+    process.exitCode = await runUpstreamCli(process.argv.slice(2));
+}

package/dist/upstream-version.js

@@ -0,0 +1,40 @@
+import { SEMVER_BASE_RE } from "./domain/refs.js";
+export function shortCommit(commit) {
+    return commit.slice(0, 7);
+}
+function trimDashes(value) {
+    return value.replace(/^-+/, "").replace(/-+$/, "");
+}
+export function sanitizeRefForVersion(ref) {
+    const collapsed = trimDashes(ref.replace(/[^0-9A-Za-z-]+/g, "-"));
+    const truncated = trimDashes(collapsed.slice(0, 48));
+    return truncated === "" ? "unknown" : truncated;
+}
+export function manifestVersionForRef(input) {
+    const short = shortCommit(input.commit);
+    switch (input.resolutionKind) {
+        case "latest-release":
+        case "tag": {
+            if (input.resolvedRef.startsWith("v")) {
+                const base = input.resolvedRef.slice(1);
+                if (base !== "" && SEMVER_BASE_RE.test(base)) {
+                    return `${base}+manager.${short}`;
+                }
+            }
+            break;
+        }
+        case "ref": {
+            if (input.requestedRef === "main") {
+                return `0.0.0-main+manager.${short}`;
+            }
+            return `0.0.0-ref-${sanitizeRefForVersion(input.requestedRef)}+manager.${short}`;
+        }
+        case "raw-commit":
+            break;
+        default: {
+            const unreachable = input.resolutionKind;
+            throw new Error(`unhandled resolution kind: ${String(unreachable)}`);
+        }
+    }
+    return `0.0.0+manager.${short}`;
+}

package/dist/upstream.js

@@ -0,0 +1,253 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { COMMIT_INPUT_RE, compareStable, parseStableTag, } from "./domain/refs.js";
+import { runGit } from "./git.js";
+import { SafetyError } from "./safety-error.js";
+import { displaySource } from "./selection.js";
+import { withWorkspace } from "./workspace.js";
+const UNAVAILABLE_OBJECT_RE = /not our ref|unadvertised object|couldn't find remote ref/;
+function upstreamError(message) {
+    return new SafetyError("upstream", message);
+}
+// Mirrors
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/upstream.sh:6-13::spw_config_ref`:
+// SUPERPOWERS_REF wins; otherwise the first line of config/upstream-ref with
+// trailing whitespace stripped.
+// The diagnostic names the path and does not interpolate the caught cause.
+export async function readConfigRef(root, env) {
+    if (env.SUPERPOWERS_REF)
+        return env.SUPERPOWERS_REF;
+    const path = join(root, "config", "upstream-ref");
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        throw upstreamError(`cannot read packaged upstream ref ${path}`);
+    }
+    return (text.split("\n")[0] ?? "").replace(/\s+$/, "");
+}
+// Signal termination carries `status: null`, and `null !== 0`, so this one
+// comparison covers both non-zero exits and killed children.
+function failed(result) {
+    return result.status !== 0;
+}
+function combined(result) {
+    return `${result.stdout}${result.stderr}`.replace(/\n+$/, "");
+}
+// Mirrors `[ -d "$repository/.git" ]`: a regular file, a broken symlink, or
+// an unreadable path is *not* a directory, so the cache is re-initialized.
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function parseLsRemote(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        const fields = line.split(/[ \t]+/).filter((field) => field !== "");
+        if (fields.length < 2)
+            continue;
+        entries.push({ sha: fields[0], ref: fields[1] });
+    }
+    return entries;
+}
+export function selectLatestRelease(entries) {
+    const candidates = new Map();
+    for (const entry of entries) {
+        if (!entry.ref.startsWith("refs/tags/"))
+            continue;
+        let tag = entry.ref.slice("refs/tags/".length);
+        let peeled = false;
+        if (tag.endsWith("^{}")) {
+            peeled = true;
+            tag = tag.slice(0, -3);
+        }
+        const version = parseStableTag(tag);
+        if (version === null)
+            continue;
+        const existing = candidates.get(tag);
+        if (existing === undefined) {
+            candidates.set(tag, { tag, sha: entry.sha, version });
+        }
+        else if (peeled) {
+            existing.sha = entry.sha;
+        }
+    }
+    let best = null;
+    for (const candidate of candidates.values()) {
+        if (best === null || compareStable(candidate.version, best.version) > 0) {
+            best = candidate;
+        }
+    }
+    return best === null ? null : { tag: best.tag, sha: best.sha };
+}
+export function gitSafeSource(source) {
+    if (source.startsWith("/") ||
+        source.startsWith("~") ||
+        source.includes("://") ||
+        source.includes(":")) {
+        return source;
+    }
+    return `${process.cwd()}/${source}`;
+}
+export async function resolveRef(upstreamUrl, requestedRef) {
+    const querySource = gitSafeSource(upstreamUrl);
+    if (requestedRef === "latest-release") {
+        const listed = await runGit([
+            "ls-remote",
+            "--tags",
+            "--",
+            querySource,
+            "refs/tags/v*",
+        ]);
+        if (failed(listed)) {
+            throw upstreamError(`cannot query upstream tags from ${upstreamUrl}: ${combined(listed)}`);
+        }
+        const selected = selectLatestRelease(parseLsRemote(listed.stdout));
+        if (selected === null) {
+            throw upstreamError("no stable semver tag found for latest-release");
+        }
+        return { kind: "latest-release", ref: selected.tag, commit: selected.sha };
+    }
+    if (COMMIT_INPUT_RE.test(requestedRef)) {
+        return { kind: "raw-commit", ref: requestedRef, commit: requestedRef };
+    }
+    const wanted = `refs/tags/${requestedRef}`;
+    const tagged = await runGit([
+        "ls-remote",
+        "--tags",
+        "--",
+        querySource,
+        wanted,
+        `${wanted}^{}`,
+    ]);
+    if (failed(tagged)) {
+        throw upstreamError(`cannot query upstream tag ${requestedRef} from ${upstreamUrl}: ${combined(tagged)}`);
+    }
+    let tagSha = "";
+    for (const entry of parseLsRemote(tagged.stdout)) {
+        if (entry.ref === wanted || entry.ref === `${wanted}^{}`) {
+            tagSha = entry.sha;
+        }
+    }
+    if (tagSha !== "") {
+        return { kind: "tag", ref: requestedRef, commit: tagSha };
+    }
+    const generic = await runGit(["ls-remote", "--", querySource, requestedRef]);
+    if (failed(generic)) {
+        throw upstreamError(`cannot query upstream ref ${requestedRef} from ${upstreamUrl}: ${combined(generic)}`);
+    }
+    const first = parseLsRemote(generic.stdout)[0];
+    if (first !== undefined) {
+        return { kind: "ref", ref: requestedRef, commit: first.sha };
+    }
+    throw upstreamError(`cannot resolve upstream ref: ${requestedRef}`);
+}
+export async function resolveExactTag(source, ref) {
+    const display = displaySource(source);
+    const querySource = gitSafeSource(source);
+    const wanted = `refs/tags/${ref}`;
+    const listed = await runGit([
+        "ls-remote",
+        "--tags",
+        "--",
+        querySource,
+        wanted,
+        `${wanted}^{}`,
+    ]);
+    if (failed(listed)) {
+        throw upstreamError(`cannot query exact upstream tag ${ref} from ${display}: ${combined(listed)}`);
+    }
+    let direct = "";
+    let peeled = "";
+    for (const entry of parseLsRemote(listed.stdout)) {
+        if (entry.ref === wanted)
+            direct = entry.sha;
+        if (entry.ref === `${wanted}^{}`)
+            peeled = entry.sha;
+    }
+    const commit = peeled !== "" ? peeled : direct;
+    if (commit === "")
+        throw upstreamError(`upstream tag not found: ${ref}`);
+    return commit;
+}
+async function inWorkspace(parent, prefix, creationMessage, fn) {
+    try {
+        return await withWorkspace(parent, prefix, fn);
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError &&
+            cause.module === "workspace" &&
+            cause.message === "cannot create workspace") {
+            throw upstreamError(creationMessage);
+        }
+        throw cause;
+    }
+}
+async function proveCommit(workspace, fetchSource, commit, display, initMessage) {
+    const init = await runGit(["init", workspace]);
+    if (failed(init)) {
+        throw upstreamError(`${initMessage}: ${combined(init)}`);
+    }
+    const fetched = await runGit([
+        "-C",
+        workspace,
+        "fetch",
+        "--no-tags",
+        "--",
+        fetchSource,
+        commit,
+    ]);
+    if (failed(fetched)) {
+        if (UNAVAILABLE_OBJECT_RE.test(combined(fetched))) {
+            throw upstreamError(`source cannot supply requested commit: ${commit}`);
+        }
+        throw upstreamError(`cannot fetch requested commit from ${display}`);
+    }
+    const typed = await runGit(["-C", workspace, "cat-file", "-t", commit]);
+    if (failed(typed) || typed.stdout.trim() !== "commit") {
+        throw upstreamError(`requested object is not a commit: ${commit}`);
+    }
+}
+export async function verifyRawCommit(source, rawCommit, workspaceParent) {
+    const commit = rawCommit.toLowerCase();
+    const display = displaySource(source);
+    const fetchSource = gitSafeSource(source);
+    await inWorkspace(workspaceParent, "superpowers-manager.commit.", `cannot create raw-commit verification workspace under ${workspaceParent}`, async (workspace) => {
+        await proveCommit(workspace, fetchSource, commit, display, "cannot initialize raw-commit verification workspace");
+    });
+    return commit;
+}
+export async function fetchExactCommit(source, commit, repository, workspaceParent) {
+    const display = displaySource(source);
+    const fetchSource = gitSafeSource(source);
+    await inWorkspace(workspaceParent, "superpowers-manager.fetch.", `cannot create exact-commit fetch workspace under ${workspaceParent}`, async (workspace) => {
+        await proveCommit(workspace, fetchSource, commit, display, "cannot initialize exact-commit fetch workspace");
+        if (!(await isDirectory(`${repository}/.git`))) {
+            const init = await runGit(["init", repository]);
+            if (failed(init)) {
+                throw upstreamError(`cannot initialize upstream cache repository: ${combined(init)}`);
+            }
+        }
+        const transfer = await runGit([
+            "-C",
+            repository,
+            "fetch",
+            "--no-tags",
+            "--",
+            workspace,
+            commit,
+        ]);
+        if (failed(transfer)) {
+            throw upstreamError(`cannot transfer requested commit into upstream cache: ${combined(transfer)}`);
+        }
+        const typed = await runGit(["-C", repository, "cat-file", "-t", commit]);
+        if (failed(typed) || typed.stdout.trim() !== "commit") {
+            throw upstreamError(`cannot verify requested commit in upstream cache: ${commit}`);
+        }
+    });
+}

package/dist/validate-generated-plugin-cli.js

@@ -0,0 +1,118 @@
+import { realpathSync } from "node:fs";
+import { oneLine, parseFlags, UsageError } from "./cli-arguments.js";
+import { validateGeneratedPlugin, } from "./generated-plugin.js";
+const FLAGS = [
+    "plugin-root",
+    "source",
+    "requested-ref",
+    "resolved-ref",
+    "commit",
+    "manifest-version",
+    "manifest-source",
+    "upstream-manifest-version",
+];
+// `argparse` accepts a lone `-` and a bare negative number as a split value;
+// every other dash-leading split value is treated as an option and rejected.
+// CPython's `_negative_number_matcher` is `^-\d+$|^-\d*\.\d+$`, and `re` `\d` on
+// a `str` pattern matches every character in Unicode category Nd. JavaScript
+// `\d` is `[0-9]` whatever the flags, so `\p{Nd}` plus `u` is what mirrors it.
+// The `\.` stays a literal ASCII period: `argparse` accepts no other separator.
+const NEGATIVE_NUMBER_RE = /^-\p{Nd}+$|^-\p{Nd}*\.\p{Nd}+$/u;
+/** True when `argparse` would accept `value` in `--flag value` form. */
+export function isAcceptedSplitValue(value) {
+    if (!value.startsWith("-"))
+        return true;
+    return value === "-" || NEGATIVE_NUMBER_RE.test(value);
+}
+/**
+ * Node replaces an undecodable argv byte with U+FFFD before any JavaScript
+ * runs, so the original byte is unrecoverable. Rejecting at the boundary is
+ * the only portable fail-closed option.
+ */
+export function hasReplacementCharacter(value) {
+    return value.includes("�");
+}
+/** Pre-scan argv for split-form values the dash rule rejects. */
+function findRejectedSplitFlag(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith("--") || token.includes("="))
+            continue;
+        const value = argv[index + 1];
+        if (value === undefined)
+            continue;
+        if (!isAcceptedSplitValue(value))
+            return token;
+        index += 1;
+    }
+    return undefined;
+}
+function parseOptions(argv) {
+    const rejected = findRejectedSplitFlag(argv);
+    if (rejected !== undefined) {
+        throw new UsageError(`option ${rejected} rejects a dash-leading value`);
+    }
+    const flags = parseFlags(argv, FLAGS);
+    if (hasReplacementCharacter(flags["plugin-root"])) {
+        throw new UsageError("option --plugin-root contains an undecodable character");
+    }
+    const manifestSource = flags["manifest-source"];
+    if (manifestSource !== "upstream" && manifestSource !== "fallback") {
+        throw new UsageError("option --manifest-source must be `upstream` or `fallback`");
+    }
+    return {
+        pluginRoot: flags["plugin-root"],
+        source: flags.source,
+        requestedRef: flags["requested-ref"],
+        resolvedRef: flags["resolved-ref"],
+        commit: flags.commit,
+        manifestVersion: flags["manifest-version"],
+        manifestSource,
+        upstreamManifestVersion: flags["upstream-manifest-version"],
+    };
+}
+export async function runValidateGeneratedPluginCli(argv) {
+    let options;
+    try {
+        options = parseOptions(argv);
+    }
+    catch (cause) {
+        process.stderr.write("usage: validate-generated-plugin-cli --plugin-root <path> --source <url> " +
+            "--requested-ref <ref> --resolved-ref <ref> --commit <sha> " +
+            "--manifest-version <version> --manifest-source <upstream|fallback> " +
+            "--upstream-manifest-version <version>\n");
+        process.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 2;
+    }
+    let errors;
+    try {
+        errors = await validateGeneratedPlugin(options);
+    }
+    catch (cause) {
+        // A rejection must never escape as a traceback-shaped crash.
+        process.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 2;
+    }
+    if (errors.length > 0) {
+        process.stderr.write("Generated plugin validation failed:\n");
+        for (const error of errors)
+            process.stderr.write(`- ${error}\n`);
+        return 1;
+    }
+    process.stdout.write(`generated plugin validation passed: ${options.pluginRoot}\n`);
+    return 0;
+}
+const entry = process.argv[1];
+let entryRealpath;
+if (entry !== undefined) {
+    try {
+        entryRealpath = realpathSync(entry);
+    }
+    catch {
+        // An unresolvable argv[1] means "not the entry point", not a crash.
+        entryRealpath = undefined;
+    }
+}
+if (entryRealpath !== undefined && import.meta.filename === entryRealpath) {
+    process.exitCode = await runValidateGeneratedPluginCli(process.argv.slice(2));
+}