superpowers-manager 0.9.0 → 0.10.0

package/dist/harnesses/hermes/observe.js

@@ -0,0 +1,178 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parseDocument } from "yaml";
+import { readArtifactFile } from "../../artifact-tree.js";
+import { compareByCodePoint } from "../../python-text.js";
+import { assertNoFollowType, classifyPathNoFollow, isAbsenceError, } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+const DECODER = new TextDecoder("utf-8", { fatal: true });
+function mapping(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function parseYaml(text, uniqueKeys = true) {
+    const document = parseDocument(text, { uniqueKeys, merge: true });
+    if (document.errors.length > 0 ||
+        document.warnings.some((warning) => warning.code === "TAG_RESOLVE_FAILED"))
+        throw new Error("YAML document");
+    return document.toJS();
+}
+async function configuration(root) {
+    await assertNoFollowType(root, ["directory", "missing"]);
+    const path = join(root, "config.yaml");
+    if ((await classifyPathNoFollow(path)) === "missing")
+        return null;
+    const value = parseYaml(DECODER.decode(await readArtifactFile(root, path))) ?? {};
+    if (!mapping(value))
+        throw new Error("configuration mapping");
+    return value;
+}
+async function managedDirectory(env, systemManagedDir) {
+    const configured = env.HERMES_MANAGED_DIR?.trim();
+    for (const path of configured
+        ? [configured, systemManagedDir]
+        : [systemManagedDir]) {
+        const kind = await classifyPathNoFollow(path);
+        if (kind === "directory")
+            return path;
+        if (kind === "symlink")
+            throw new Error("managed directory symlink");
+    }
+    return null;
+}
+function activationList(value) {
+    if (!Array.isArray(value))
+        return [];
+    if (value.some((item) => (item !== null && typeof item === "object") ||
+        (typeof item === "string" && item.includes("${"))))
+        throw new SafetyError("hermes-observe", "cannot determine Hermes plugin activation");
+    return value;
+}
+export async function readHermesStatus(paths, env, systemManagedDir = "/etc/hermes") {
+    let user;
+    try {
+        user = await configuration(paths.hermesHome);
+    }
+    catch (cause) {
+        throw new SafetyError("hermes-observe", "cannot inspect Hermes configuration", { cause });
+    }
+    try {
+        const directory = await managedDirectory(env, systemManagedDir);
+        const managed = directory === null ? null : await configuration(directory);
+        const plugins = managed?.plugins;
+        if (plugins !== undefined && plugins !== null && !mapping(plugins))
+            throw new Error("managed plugins shape");
+        if (mapping(plugins) &&
+            (Object.hasOwn(plugins, "enabled") || Object.hasOwn(plugins, "disabled")))
+            throw new Error("managed activation");
+    }
+    catch (cause) {
+        throw new SafetyError("hermes-observe", "cannot determine Hermes plugin activation", { cause });
+    }
+    const plugins = mapping(user?.plugins) ? user.plugins : {};
+    const enabled = activationList(plugins.enabled);
+    const disabled = activationList(plugins.disabled);
+    return disabled.includes("superpowers")
+        ? "disabled"
+        : enabled.includes("superpowers")
+            ? "enabled"
+            : "not enabled";
+}
+const FOREIGN_MANIFEST_DIRECTORIES = new Set([
+    ".claude-plugin",
+    ".codex-plugin",
+    ".cursor-plugin",
+    ".devin-plugin",
+    ".kimi-plugin",
+]);
+export async function findSuperpowersManifests(paths) {
+    try {
+        if ((await classifyPathNoFollow(paths.pluginsRoot)) === "missing")
+            return [];
+        const found = [];
+        async function scan(root, physicalRoot, depth) {
+            await assertNoFollowType(physicalRoot, ["directory"]);
+            for (const name of (await readdir(physicalRoot)).sort(compareByCodePoint)) {
+                if ((name.startsWith("__") && name.endsWith("__")) ||
+                    FOREIGN_MANIFEST_DIRECTORIES.has(name))
+                    continue;
+                const child = join(root, name);
+                const physicalChild = join(physicalRoot, name);
+                const kind = await classifyPathNoFollow(physicalChild);
+                if (kind === "symlink") {
+                    if (child === paths.pluginRoot)
+                        throw new Error("owned plugin directory symlink");
+                    try {
+                        if (!(await stat(physicalChild)).isDirectory())
+                            continue;
+                    }
+                    catch (cause) {
+                        if (isAbsenceError(cause))
+                            continue;
+                        throw cause;
+                    }
+                }
+                else if (kind !== "directory")
+                    continue;
+                const directory = await realpath(physicalChild);
+                let manifest = null;
+                for (const file of ["plugin.yaml", "plugin.yml", "plugin.json"]) {
+                    if ((await classifyPathNoFollow(join(directory, file))) !== "missing") {
+                        manifest = file;
+                        break;
+                    }
+                }
+                if (manifest === null) {
+                    if (depth === 0)
+                        await scan(child, directory, 1);
+                    continue;
+                }
+                const bytes = await readArtifactFile(directory, join(directory, manifest), 64 * 1024);
+                let value;
+                try {
+                    const text = DECODER.decode(bytes);
+                    if (manifest === "plugin.json")
+                        value = JSON.parse(text);
+                    else {
+                        const parsed = parseYaml(text, false);
+                        value =
+                            parsed === null ||
+                                parsed === undefined ||
+                                parsed === false ||
+                                parsed === 0 ||
+                                parsed === "" ||
+                                (Array.isArray(parsed) && parsed.length === 0) ||
+                                (parsed instanceof Set && parsed.size === 0) ||
+                                (parsed instanceof Map && parsed.size === 0) ||
+                                (Buffer.isBuffer(parsed) && parsed.length === 0)
+                                ? {}
+                                : parsed;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                if (!mapping(value))
+                    continue;
+                const pluginName = Object.hasOwn(value, "name")
+                    ? value.name
+                    : manifest === "plugin.json"
+                        ? undefined
+                        : basename(child);
+                if (pluginName === "superpowers")
+                    found.push(child);
+            }
+        }
+        await scan(paths.pluginsRoot, paths.pluginsRoot, 0);
+        return found.sort(compareByCodePoint);
+    }
+    catch (cause) {
+        throw new SafetyError("hermes-observe", "cannot inspect Hermes plugins", {
+            cause,
+        });
+    }
+}
+export function projectPluginsEnabled(env) {
+    return ["1", "true", "yes", "on"].includes((env.HERMES_ENABLE_PROJECT_PLUGINS ?? "").trim().toLowerCase());
+}

package/dist/harnesses/hermes/paths.js

@@ -0,0 +1,61 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { assertNoFollowType } from "../../safe-path.js";
+function trimHome(value) {
+    const whitespace = (index) => {
+        const code = value.charCodeAt(index);
+        return ((code >= 0x1c && code <= 0x1f) ||
+            /\p{White_Space}/u.test(value.charAt(index)));
+    };
+    let start = 0;
+    let end = value.length;
+    while (start < end && whitespace(start))
+        start++;
+    while (end > start && whitespace(end - 1))
+        end--;
+    return value.slice(start, end);
+}
+function expandHome(value, env, home) {
+    const expanded = trimHome(value).replace(/\$([A-Za-z0-9_]+|\{[^}]*\})/gu, (token, name) => {
+        const variable = name.startsWith("{") ? name.slice(1, -1) : name;
+        return Object.hasOwn(env, variable) ? (env[variable] ?? token) : token;
+    });
+    if (expanded === "~")
+        return home;
+    if (expanded.startsWith("~/"))
+        return join(home, expanded.slice(2));
+    if (expanded.startsWith("~"))
+        throw new Error("cannot resolve HERMES_HOME: named user homes are unsupported");
+    return expanded;
+}
+export function hermesPaths(env, cwd) {
+    const configured = trimHome(env.HERMES_HOME ?? "");
+    const home = env.HOME && env.HOME.length > 0 ? env.HOME : homedir();
+    const hermesHome = configured.length > 0
+        ? resolve(cwd, expandHome(configured, env, home))
+        : join(resolve(cwd, home), ".hermes");
+    if (expandHome(hermesHome, env, home) !== hermesHome)
+        throw new Error("cannot resolve HERMES_HOME: home expansion is not stable");
+    const managerRoot = join(hermesHome, "superpowers-manager");
+    const pluginsRoot = join(hermesHome, "plugins");
+    return {
+        hermesHome,
+        managerRoot,
+        preparedRoot: join(managerRoot, "prepared"),
+        pluginsRoot,
+        pluginRoot: join(pluginsRoot, "superpowers"),
+    };
+}
+export async function assertHermesStorageAncestorsSafe(paths) {
+    for (const path of [
+        paths.hermesHome,
+        paths.managerRoot,
+        paths.preparedRoot,
+        paths.pluginsRoot,
+    ])
+        await assertNoFollowType(path, ["directory", "missing"]);
+}
+export async function assertHermesStorageSafe(paths) {
+    await assertHermesStorageAncestorsSafe(paths);
+    await assertNoFollowType(paths.pluginRoot, ["directory", "missing"]);
+}

package/dist/harnesses/hermes/prepare.js

@@ -0,0 +1,78 @@
+import { readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { readArtifactFile, validateNativeSkill } from "../../artifact-tree.js";
+import { assertNoFollowType, classifyPathNoFollow } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { validateSource } from "../../selection.js";
+import { createSnapshotReceipts, } from "../../snapshot-package.js";
+import { createSnapshotPreparation } from "../../snapshot-prepare.js";
+import { assertHermesStorageSafe, hermesPaths } from "./paths.js";
+async function flattenHermesPlugin(root) {
+    const nativeRoot = join(root, ".hermes-plugin");
+    if ((await classifyPathNoFollow(nativeRoot)) !== "directory")
+        return;
+    const entries = await readdir(nativeRoot);
+    if (entries.some((entry) => entry === "skills" || entry === "LICENSE"))
+        throw new SafetyError("hermes-package", `Hermes plugin layout collides with shared content: ${root}`);
+    for (const entry of await readdir(root))
+        if (entry !== ".hermes-plugin" && entry !== "skills" && entry !== "LICENSE")
+            await rm(join(root, entry), { recursive: true, force: true });
+    for (const entry of entries)
+        await rename(join(nativeRoot, entry), join(root, entry));
+    await rm(nativeRoot, { recursive: true });
+    await writeFile(join(root, "__pycache__"), "", { flag: "wx" });
+}
+async function assessHermesCompatibility(root, selection) {
+    try {
+        validateSource(selection.effectiveSource);
+        await readArtifactFile(root, join(root, "__pycache__"), 0);
+        for (const relative of [
+            "plugin.yaml",
+            "__init__.py",
+            "skills/using-superpowers/references/hermes-tools.md",
+        ])
+            await assertNoFollowType(join(root, relative), ["regular-file"]);
+        await validateNativeSkill(root);
+        return {
+            kind: "supported",
+            generation: "hermes-flat-plugin-v1",
+            reason: "native Hermes plugin",
+        };
+    }
+    catch {
+        return {
+            kind: "unsupported",
+            reason: `Hermes package does not provide a native Hermes plugin: ${root}`,
+        };
+    }
+}
+const receipts = createSnapshotReceipts({
+    harness: "hermes",
+    label: "Hermes",
+    strictGeneration: true,
+    assessCompatibility: assessHermesCompatibility,
+});
+export const readHermesReceipt = receipts.readReceipt;
+export const readHermesPackageAssessment = receipts.readAssessment;
+export async function validateHermesPreparationBeforeFetch(ctx) {
+    try {
+        await assertHermesStorageSafe(hermesPaths(ctx.env ?? {}, process.cwd()));
+        return successResult("prepare", null, []);
+    }
+    catch {
+        return failureResult("prepare", "invalid-package", "cannot validate Hermes artifact storage", [], []);
+    }
+}
+const preparation = createSnapshotPreparation({
+    harness: "hermes",
+    label: "Hermes",
+    paths: hermesPaths,
+    assessCompatibility: assessHermesCompatibility,
+    readAssessment: readHermesPackageAssessment,
+    layout: flattenHermesPlugin,
+});
+export const hermesPreparationLocation = preparation.preparationLocation;
+export const prepareHermesCandidate = preparation.prepareCandidate;
+export const inspectHermesPrepared = preparation.inspectPrepared;
+export const readHermesPrepared = preparation.readPrepared;

package/dist/harnesses/hermes/presentation.js

@@ -0,0 +1,23 @@
+import { displaySource } from "../../selection.js";
+import { createSnapshotPresentation, probeOutput, } from "../../snapshot-presentation.js";
+import { displayPath } from "../../validator.js";
+const renderProbe = (facts) => {
+    const fields = [
+        ["harness", "hermes"],
+        ["desired_commit", facts.selection.desiredCommit],
+        ["upstream_source_origin", facts.selection.upstreamSourceOrigin],
+        ["effective_source", displaySource(facts.selection.effectiveSource)],
+        ["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],
+    ].map(([key, value]) => [key, displayPath(value)]);
+    return probeOutput(fields);
+};
+export const hermesPresentation = createSnapshotPresentation("Hermes", renderProbe, (input) => input.ownership === "absent");

package/dist/harnesses/hermes/state.js

@@ -0,0 +1,144 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { inspectionFailure, successResult, } from "../../adapter-result.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
+import { observeSnapshot, sameSnapshotSource } from "../../snapshot-package.js";
+import { displayPath } from "../../validator.js";
+import { findSuperpowersManifests, projectPluginsEnabled, readHermesStatus, } from "./observe.js";
+import { assertHermesStorageAncestorsSafe, hermesPaths, } from "./paths.js";
+import { readHermesPackageAssessment, readHermesReceipt, } from "./prepare.js";
+export async function observeHermesOwnership(paths) {
+    await assertHermesStorageAncestorsSafe(paths);
+    const snapshot = await observeSnapshot(paths.pluginRoot, readHermesReceipt);
+    return snapshot.kind === "unverified" ? { kind: "foreign" } : snapshot;
+}
+export async function otherSuperpowersManifests(paths) {
+    await assertHermesStorageAncestorsSafe(paths);
+    return (await findSuperpowersManifests(paths)).filter((root) => root !== paths.pluginRoot);
+}
+async function observeFacts(ctx) {
+    const env = ctx.env ?? {};
+    const paths = hermesPaths(env, process.cwd());
+    const ownership = await observeHermesOwnership(paths);
+    const status = await readHermesStatus(paths, env);
+    // A foreign leaf is already a blocking decision. Do not scan its contents
+    // or pass a symlink to the manifest observer.
+    const manifests = ownership.kind === "foreign" ? [] : await findSuperpowersManifests(paths);
+    return {
+        paths,
+        ownership,
+        status,
+        manifests,
+        conflicts: manifests.filter((root) => root !== paths.pluginRoot),
+    };
+}
+function blocked(...stderr) {
+    return {
+        kind: "blocked",
+        output: { stdout: [], stderr: stderr.map(displayPath) },
+    };
+}
+function installDecision(facts, env) {
+    if (facts.ownership.kind === "foreign")
+        return blocked("error: another Superpowers copy is present in Hermes; remove it manually, then retry:", "  hermes plugins remove superpowers");
+    if (facts.conflicts.length > 0)
+        return blocked("error: Hermes discovers another plugin named superpowers; remove it manually, then retry:", ...facts.conflicts.map((path) => `  ${path}`));
+    if (projectPluginsEnabled(env))
+        return blocked("error: HERMES_ENABLE_PROJECT_PLUGINS is set; a project-local Superpowers copy would override the managed one. Unset HERMES_ENABLE_PROJECT_PLUGINS, then retry.");
+    return { kind: "allowed" };
+}
+export async function inspectHermesOwnership(ctx) {
+    const operation = "inspect-hermes-ownership";
+    try {
+        const facts = await observeFacts(ctx);
+        const listed = facts.status !== "not enabled";
+        return successResult(operation, {
+            installEligibility: installDecision(facts, ctx.env ?? {}),
+            removalInput: { ownership: facts.ownership.kind, listed },
+            removalVerification: facts.ownership.kind !== "absent" || listed
+                ? blocked("error: Hermes still lists Superpowers or its plugin directory is still present after removal")
+                : { kind: "allowed" },
+            postRemovalOutput: { stdout: [], stderr: [] },
+            presentationValue: facts.ownership.kind === "owned"
+                ? `managed ${facts.ownership.digest}`
+                : facts.ownership.kind === "foreign"
+                    ? "foreign plugin directory"
+                    : "absent",
+            presentationConflicts: facts.conflicts,
+        }, []);
+    }
+    catch {
+        return inspectionFailure(operation, "Hermes ownership");
+    }
+}
+export async function inspectHermesInstalled(selection, ctx) {
+    const operation = "inspect-hermes-installed";
+    let facts;
+    try {
+        facts = await observeFacts(ctx);
+    }
+    catch {
+        return inspectionFailure(operation, "Hermes installed state");
+    }
+    if (facts.ownership.kind === "absent" &&
+        facts.status === "not enabled" &&
+        facts.manifests.length === 0)
+        return successResult(operation, { kind: "absent", observedIdentity: "" }, []);
+    const observed = facts.ownership.kind === "owned"
+        ? facts.ownership.digest
+        : facts.ownership.kind === "foreign"
+            ? "foreign plugin directory"
+            : "listed without an installed snapshot";
+    const mismatch = () => successResult(operation, { kind: "mismatch", observedIdentity: observed }, []);
+    if (facts.ownership.kind !== "owned" ||
+        facts.status !== "enabled" ||
+        !facts.manifests.includes(facts.paths.pluginRoot) ||
+        facts.conflicts.length > 0)
+        return mismatch();
+    try {
+        const prepared = await readHermesPackageAssessment(facts.paths.preparedRoot);
+        if (prepared.compatibility.kind !== "supported" ||
+            prepared.receipt.commit !== selection.desiredCommit ||
+            !sameSnapshotSource(prepared.receipt.source, selection.effectiveSource) ||
+            facts.ownership.receipt.commit !== selection.desiredCommit ||
+            !sameSnapshotSource(facts.ownership.receipt.source, selection.effectiveSource) ||
+            facts.ownership.digest !== prepared.receipt.digest)
+            return mismatch();
+    }
+    catch {
+        return mismatch();
+    }
+    return successResult(operation, { kind: "current", observedIdentity: observed }, []);
+}
+export async function leftoverHermesPublication(paths) {
+    await assertHermesStorageAncestorsSafe(paths);
+    if ((await classifyPathNoFollow(paths.managerRoot)) === "missing")
+        return [];
+    return (await readdir(paths.managerRoot))
+        .filter((name) => name.startsWith("publish."))
+        .sort()
+        .map((name) => join(paths.managerRoot, name));
+}
+export async function inspectHermesControl(ctx) {
+    const operation = "inspect-hermes-control";
+    try {
+        const paths = hermesPaths(ctx.env ?? {}, process.cwd());
+        const leftovers = await leftoverHermesPublication(paths);
+        if (leftovers.length === 0)
+            return successResult(operation, {
+                probeEligibility: { kind: "allowed" },
+                mutationEligibility: { kind: "allowed" },
+                presentationValue: "clear",
+            }, []);
+        const decision = blocked("error: Hermes recovery required; inspect and remove leftover publication material manually:", ...leftovers.map((path) => `  ${path}`));
+        return successResult(operation, {
+            probeEligibility: decision,
+            mutationEligibility: decision,
+            presentationValue: displayPath(`recovery required at ${leftovers.join(", ")}`),
+            recoveryState: "required",
+        }, []);
+    }
+    catch {
+        return inspectionFailure(operation, "Hermes update control");
+    }
+}

package/dist/snapshot-prepare.js

@@ -21,6 +21,8 @@ export function createSnapshotPreparation(b) {
         async prepareCandidate(input) {
             try {
                 await materializeGitTree(input.upstreamRoot, input.selection.desiredCommit, input.candidateRoot);
+                if (b.layout !== undefined)
+                    await b.layout(input.candidateRoot);
                 const compatibility = await b.assessCompatibility(input.candidateRoot, input.selection);
                 if (compatibility.kind === "unsupported" ||
                     compatibility.kind === "unknown")

package/node_modules/yaml/LICENSE

@@ -0,0 +1,13 @@
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.