superpowers-manager 0.1.6 → 0.3.0

package/dist/git.js

@@ -0,0 +1,38 @@
+import { execFile } from "node:child_process";
+import { SafetyError } from "./safety-error.js";
+export function runGit(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        execFile("git", [...args], {
+            cwd: options.cwd,
+            env: { ...process.env, LC_ALL: "C", GIT_TERMINAL_PROMPT: "0" },
+            encoding: "utf8",
+            maxBuffer: Infinity,
+            shell: false,
+            windowsHide: true,
+        }, (error, stdout, stderr) => {
+            if (error === null) {
+                resolve({ status: 0, signal: null, stdout, stderr });
+                return;
+            }
+            const failure = error;
+            if (typeof failure.code === "string") {
+                const message = failure.code === "ENOENT"
+                    ? "required command not found: git"
+                    : `cannot run git: ${failure.message}`;
+                reject(new SafetyError("git", message, { cause: error }));
+                return;
+            }
+            const signal = failure.signal ?? null;
+            if (signal !== null) {
+                resolve({ status: null, signal, stdout, stderr });
+                return;
+            }
+            resolve({
+                status: typeof failure.code === "number" ? failure.code : 1,
+                signal: null,
+                stdout,
+                stderr,
+            });
+        });
+    });
+}

package/dist/hooks.js

@@ -0,0 +1,290 @@
+import { copyFile, cp, mkdir, readdir, readFile, readlink, stat, symlink, } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { assertExistingContained, assertProspectiveContained, classifyPathNoFollow, } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson } from "./strict-json.js";
+// Annotated, not `as const`, matching
+// `src/provenance.ts:20::export const PROVENANCE_STRICT_PROFILE` and
+// `src/selection-store.ts:19::const SELECTION_JSON_PROFILE`. The annotation
+// rejects a misspelled or unsupported profile field here rather than at the
+// parseStrictJson call.
+const MANIFEST_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+    maxDepth: 256,
+};
+// Private helper, matching
+// `src/selection.ts:42::return new SafetyError("selection"` and
+// `src/upstream.ts:35::function upstreamError`. No new exported error class:
+// SafetyError already carries module and cause.
+function hookError(message, cause) {
+    return new SafetyError("hooks", message, { cause });
+}
+// One frozen template for every owned safe-path failure. The three wrappers
+// below stay separate because they perform different operations; only the
+// message is shared.
+function ownedPathError(label, path, cause) {
+    return hookError(`${label} escapes or could not be resolved: ${path}`, cause);
+}
+// Every safe-path call goes through here. Calling classifyPathNoFollow
+// directly would let a SafetyError with module "safe-path" escape to the CLI,
+// breaking the promise that this module owns its diagnostics.
+async function classifyOwned(path, label) {
+    try {
+        return await classifyPathNoFollow(path);
+    }
+    catch (cause) {
+        throw ownedPathError(label, path, cause);
+    }
+}
+async function isRegularFileFollowing(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectoryFollowing(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function requireExistingContained(root, path, label) {
+    try {
+        await assertExistingContained(root, path);
+    }
+    catch (cause) {
+        throw ownedPathError(label, path, cause);
+    }
+}
+async function requireProspectiveContained(root, path, label) {
+    try {
+        await assertProspectiveContained(root, path);
+    }
+    catch (cause) {
+        throw ownedPathError(label, path, cause);
+    }
+}
+export async function readManifest(path) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch {
+        // Deliberately drops the cause on both branches. `detail(cause)` on the
+        // read branch surfaced a raw errno (`ENOENT: … open '<path>'`), which the
+        // `hook classification failed:` site in src/adapter.ts re-emits onto the
+        // terminal these commands write to; the parse branch surfaced
+        // strict-json's own wording under a prefix src/manifest-overlay.ts also
+        // uses with CPython wording.
+        // Same text as the `cannot read manifest JSON in` site in src/adapter.ts.
+        throw hookError(`cannot read manifest JSON in ${path}`);
+    }
+    let parsed;
+    try {
+        parsed = parseStrictJson(bytes, MANIFEST_PROFILE);
+    }
+    catch {
+        throw hookError(`invalid manifest JSON in ${path}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw hookError(`manifest must be a JSON object: ${path}`);
+    }
+    return parsed;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isEmptyArray(value) {
+    return Array.isArray(value) && value.length === 0;
+}
+function isEmptyObject(value) {
+    return isPlainObject(value) && Object.keys(value).length === 0;
+}
+async function checkedFile(root, relativePath) {
+    const source = resolve(root, relativePath);
+    await requireExistingContained(root, source, "declared hook source");
+    if (!(await isRegularFileFollowing(source))) {
+        throw hookError(`declared hook source is not a regular file: ${source}`);
+    }
+    return source;
+}
+async function validateDeclaredFile(upstreamRoot, raw, index) {
+    if (!raw.startsWith("./")) {
+        throw hookError(`declared hook path must start with ./: hooks declaration index ${index}`);
+    }
+    await checkedFile(upstreamRoot, raw.slice(2));
+}
+export async function classifyHooks(manifest, source, upstreamRoot) {
+    if (source === "fallback") {
+        if (Object.hasOwn(manifest, "hooks")) {
+            throw hookError("fallback manifest must not declare hooks");
+        }
+        return { copyHooksSubtree: false, declaredPaths: [] };
+    }
+    const declared = Object.hasOwn(manifest, "hooks");
+    const hooksRoot = resolve(upstreamRoot, "hooks");
+    const defaultConfig = resolve(hooksRoot, "hooks.json");
+    const hooksRootPresent = (await classifyOwned(hooksRoot, "hook subtree")) !== "missing";
+    if (!declared) {
+        return {
+            copyHooksSubtree: await isRegularFileFollowing(defaultConfig),
+            declaredPaths: [],
+        };
+    }
+    const hooks = manifest.hooks;
+    if (isEmptyArray(hooks)) {
+        return {
+            copyHooksSubtree: await isRegularFileFollowing(defaultConfig),
+            declaredPaths: [],
+        };
+    }
+    if (isEmptyObject(hooks)) {
+        return { copyHooksSubtree: false, declaredPaths: [] };
+    }
+    let paths;
+    if (typeof hooks === "string") {
+        paths = [hooks];
+    }
+    else if (Array.isArray(hooks) &&
+        hooks.length > 0 &&
+        hooks.every((value) => typeof value === "string")) {
+        paths = hooks;
+    }
+    else if (isPlainObject(hooks) ||
+        (Array.isArray(hooks) && hooks.length > 0 && hooks.every(isPlainObject))) {
+        return { copyHooksSubtree: hooksRootPresent, declaredPaths: [] };
+    }
+    else {
+        throw hookError("unsupported or mixed hooks declaration");
+    }
+    for (const [index, raw] of paths.entries()) {
+        await validateDeclaredFile(upstreamRoot, raw, index);
+    }
+    return { copyHooksSubtree: hooksRootPresent, declaredPaths: paths };
+}
+async function checkedDestination(root, relativePath) {
+    const destination = resolve(root, relativePath);
+    await requireProspectiveContained(root, dirname(destination), "declared hook destination parent");
+    const kind = await classifyOwned(destination, "declared hook destination");
+    if (kind === "symlink") {
+        throw hookError(`declared hook destination must not be a symlink: ${destination}`);
+    }
+    if (kind === "missing") {
+        await requireProspectiveContained(root, destination, "declared hook destination");
+        return destination;
+    }
+    await requireExistingContained(root, destination, "declared hook destination");
+    if (!(await isRegularFileFollowing(destination))) {
+        throw hookError(`declared hook destination is not a regular file: ${destination}`);
+    }
+    return destination;
+}
+async function collectEntries(tree) {
+    const found = [];
+    const pending = [tree];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (cause) {
+            throw hookError(`hook subtree escapes or is broken: ${current}`, cause);
+        }
+        for (const entry of entries) {
+            const path = join(current, entry.name);
+            found.push(path);
+            // Never descend through a symlink; isDirectory() is lstat-based here.
+            if (entry.isDirectory())
+                pending.push(path);
+        }
+    }
+    return found;
+}
+async function validateSubtreeSymlinks(tree, containmentRoot) {
+    if ((await classifyOwned(tree, "hook subtree")) === "symlink") {
+        if (isAbsolute(await readlink(tree))) {
+            throw hookError(`absolute subtree symlink is not allowed: ${tree}`);
+        }
+    }
+    try {
+        await assertExistingContained(containmentRoot, tree);
+    }
+    catch (cause) {
+        throw hookError(`hook subtree escapes or is broken: ${tree}`, cause);
+    }
+    if (!(await isDirectoryFollowing(tree))) {
+        throw hookError(`hook subtree is not a directory: ${tree}`);
+    }
+    for (const path of await collectEntries(tree)) {
+        if ((await classifyOwned(path, "hook subtree entry")) !== "symlink")
+            continue;
+        if (isAbsolute(await readlink(path))) {
+            throw hookError(`absolute symlink is not allowed: ${path}`);
+        }
+        try {
+            await assertExistingContained(containmentRoot, path);
+        }
+        catch (cause) {
+            throw hookError(`symlink escapes or is broken: ${path}`, cause);
+        }
+    }
+}
+async function copyPreservingSymlink(source, destination) {
+    if ((await classifyOwned(source, "declared hook source")) === "symlink") {
+        await symlink(await readlink(source), destination);
+        return;
+    }
+    await copyFile(source, destination);
+}
+async function validateMaterializedDestination(destination, candidateRoot) {
+    const message = `materialized hook destination escapes or is broken: ${destination}`;
+    try {
+        await assertExistingContained(candidateRoot, destination);
+    }
+    catch (cause) {
+        // Retain the safe-path error as `cause`; only the message and module are
+        // re-owned. Discarding it would erase why containment failed.
+        throw hookError(message, cause);
+    }
+    if (!(await isRegularFileFollowing(destination))) {
+        throw hookError(message);
+    }
+}
+export async function materializeHooks(plan, sourceRoot, candidateRoot) {
+    if (plan.copyHooksSubtree) {
+        const sourceHooks = resolve(sourceRoot, "hooks");
+        const candidateHooks = resolve(candidateRoot, "hooks");
+        await validateSubtreeSymlinks(sourceHooks, sourceRoot);
+        if ((await classifyOwned(sourceHooks, "hook subtree")) === "symlink") {
+            await symlink(await readlink(sourceHooks), candidateHooks);
+        }
+        else {
+            await cp(sourceHooks, candidateHooks, {
+                recursive: true,
+                verbatimSymlinks: true,
+            });
+        }
+        await validateSubtreeSymlinks(candidateHooks, candidateRoot);
+    }
+    const destinations = [];
+    for (const raw of plan.declaredPaths) {
+        const relativePath = raw.slice(2);
+        const source = await checkedFile(sourceRoot, relativePath);
+        const destination = await checkedDestination(candidateRoot, relativePath);
+        await mkdir(dirname(destination), { recursive: true });
+        if ((await classifyOwned(destination, "declared hook destination")) ===
+            "missing") {
+            await copyPreservingSymlink(source, destination);
+        }
+        destinations.push(destination);
+    }
+    for (const destination of destinations) {
+        await validateMaterializedDestination(destination, candidateRoot);
+    }
+}

package/dist/lifecycle.js

@@ -0,0 +1,220 @@
+// Ported from scripts/core/lifecycle.sh. Every function here is PURE: it
+// returns its verdict as data and writes nothing. The command modules do the
+// writing.
+//
+// That shape is not stylistic. src/commands/probe.ts's gatherProbe established
+// it because a write inside a try can raise EPIPE, be caught by that try, and
+// be relabelled as a domain failure. Keeping the predicates write-free means
+// the hazard cannot exist here at all.
+// Frozen text, from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:50-53::'Legacy superpowers-wrapper Codex state is`.
+// The version in the second line is a historical package coordinate an operator
+// must type verbatim, not a reference to this package's current version — do not
+// derive it.
+const BLOCKED_LINES = [
+    "Legacy superpowers-wrapper Codex state is installed.",
+    "Run: npx superpowers-wrapper@0.1.1 uninstall",
+    "Then run: npx superpowers-manager install",
+];
+// Frozen text, from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:75-77::remains`.
+// Two lines, not three: the report path does not tell the operator to re-install.
+const REPORT_LINES = [
+    "Legacy superpowers-wrapper Codex state remains installed.",
+    "Run: npx superpowers-wrapper@0.1.1 uninstall",
+];
+function unknownState(identityState) {
+    return {
+        kind: "unknown",
+        message: `unknown adapter identity state: ${identityState}`,
+    };
+}
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:43-60::spw_require_no_legacy_state`
+export function requireNoLegacyState(identityState) {
+    if (identityState === "neither" || identityState === "manager") {
+        return { kind: "ok" };
+    }
+    if (identityState === "legacy" || identityState === "both") {
+        return { kind: "blocked", lines: BLOCKED_LINES };
+    }
+    return unknownState(identityState);
+}
+// Ported from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:72-85::spw_report_legacy_state`.
+// Same enumeration, different disposition: this one reports and continues
+// rather than blocking, so its clean arm and its legacy arm are both non-fatal.
+export function reportLegacyState(identityState) {
+    if (identityState === "neither" || identityState === "manager") {
+        return { kind: "ok" };
+    }
+    if (identityState === "legacy" || identityState === "both") {
+        return { kind: "report", lines: REPORT_LINES };
+    }
+    return unknownState(identityState);
+}
+import { hasTerminalControl } from "./adapter-result.js";
+import { commitMatches } from "./status.js";
+// Ported from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:62-70::spw_require_managed_update_control`.
+// Both refusals reached spw_die in the shell, so both carry the `error: ` prefix
+// at the call site and neither is special.
+export function requireManagedUpdateControl(value) {
+    if (value === "managed")
+        return { ok: true };
+    if (value === "unsupported") {
+        return {
+            ok: false,
+            message: "adapter cannot guarantee manager-controlled updates",
+        };
+    }
+    return {
+        ok: false,
+        message: `unknown adapter update-control capability: ${value}`,
+    };
+}
+function readResult(adapterResult) {
+    if (adapterResult.status !== 0)
+        return { kind: "call-failed" };
+    const outcome = adapterResult.outcome;
+    if (!outcome.ok)
+        return { kind: "call-failed" };
+    const value = outcome.result;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { kind: "unusable" };
+    }
+    return { kind: "object", value: value };
+}
+// Ported from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:87-124::spw_verify_installed_fingerprint`.
+// The shell performed the inspection itself at :91; a pure function cannot, so
+// the caller performs it and a failure arrives here as an AdapterResult with a
+// non-zero status.
+export function verifyInstalledFingerprint(desiredCommit, installResult, inspectResult) {
+    const inspected = readResult(inspectResult);
+    if (inspected.kind === "call-failed") {
+        return {
+            ok: false,
+            stdout: [],
+            stderr: [
+                "error: installed manager fingerprint inspection failed after install.",
+            ],
+        };
+    }
+    if (inspected.kind === "unusable") {
+        // A well-formed outcome whose `result` is not an object is the port's
+        // analogue of the shell's own split: the inspect call SUCCEEDED and only
+        // the content is unusable. This is the branch
+        // tests/unit/lifecycle.test.js's "an unparseable fingerprint result
+        // names parsing, not inspection" exercises. Spec §6.2.3 items 3 and 4.
+        return {
+            ok: false,
+            stdout: [],
+            stderr: [
+                "error: cannot parse installed manager fingerprint inspection result after install.",
+            ],
+        };
+    }
+    const raw = inspected.value.fingerprint;
+    // The Python reader printed the empty string for a JSON null, and
+    // `fingerprint` is null whenever no plugin version is active
+    // (`src/adapter.ts:820::fingerprint: null`). Anything non-string and non-null
+    // is unparseable.
+    //
+    // PORT-ONLY, and intentional. The shell cannot construct this trigger:
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/provenance.sh:62::print(value`
+    // stringifies any non-null scalar, so a non-string fingerprint never reaches
+    // spw_verify_installed_fingerprint.
+    // The port CAN encounter the shape and must fail closed rather than
+    // coerce. Pinned by a test below and recorded in
+    // tests/migration-inventory/codex-state-units.md. Spec §6.2.3 item 3.
+    if (raw !== null && raw !== undefined && typeof raw !== "string") {
+        return {
+            ok: false,
+            stdout: [],
+            stderr: [
+                "error: cannot parse installed manager fingerprint inspection result after install.",
+            ],
+        };
+    }
+    const installedCommit = typeof raw === "string" ? raw : "";
+    // :99-100 printed both lines BEFORE deciding, on every path that got this
+    // far. Moving them into the success branch would silently drop them from the
+    // failure output an operator reads to diagnose the mismatch.
+    const stdout = [
+        `desired_commit=${desiredCommit}`,
+        `installed_commit=${installedCommit}`,
+    ];
+    if (installedCommit.length > 0 &&
+        commitMatches(desiredCommit, installedCommit)) {
+        return { ok: true, stdout: [...stdout, "manager updated"], stderr: [] };
+    }
+    // :106-113 — which hint key is read depends on whether a commit was
+    // detected at all, and the hint is optional in both directions.
+    const installed = readResult(installResult);
+    const hints = installed.kind === "object" ? installed.value.verification_hints : null;
+    let hint = "";
+    if (typeof hints === "object" && hints !== null && !Array.isArray(hints)) {
+        const key = installedCommit.length > 0 ? "mismatch" : "missing";
+        const value = hints[key];
+        if (typeof value === "string" && !hasTerminalControl(value))
+            hint = value;
+    }
+    const stderr = [
+        installedCommit.length > 0
+            ? "error: installed manager fingerprint does not match the prepared plugin after install."
+            : "error: installed manager fingerprint is not detectable after install.",
+    ];
+    if (hint.length > 0)
+        stderr.push(`hint: ${hint}`);
+    return { ok: false, stdout, stderr };
+}
+// Ported from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:126-141::spw_verify_uninstalled_resources`,
+// with the Boolean coercion of
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:58-73::spw_adapter_result_boolean`
+// folded in: a non-Boolean is a hard failure, never a falsy "absent".
+export function verifyUninstalledResources(inspectResult) {
+    const read = readResult(inspectResult);
+    if (read.kind !== "object") {
+        return {
+            ok: false,
+            message: "cannot read the adapter ownership inspection after removal",
+        };
+    }
+    const inspected = read.value;
+    // A missing or non-object `resources` falls THROUGH to the Boolean check
+    // rather than getting its own message.
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:70::expected`
+    // emits "expected Boolean adapter result at resources.plugin" for input {} —
+    // the input tests/unit/lifecycle.test.js's "a non-object resources falls
+    // through to the Boolean message" exercises — so a distinct "not an object"
+    // message here would be a port-only divergence. Parity, not divergence. Spec
+    // §6.2.3 item 3.
+    const resources = inspected.resources;
+    const bag = typeof resources === "object" &&
+        resources !== null &&
+        !Array.isArray(resources)
+        ? resources
+        : {};
+    for (const key of ["plugin", "marketplace"]) {
+        if (typeof bag[key] !== "boolean") {
+            return {
+                ok: false,
+                message: `expected a Boolean adapter result at resources.${key}`,
+            };
+        }
+    }
+    if (bag.plugin === true) {
+        return {
+            ok: false,
+            message: "owned plugin resource is still installed after removal",
+        };
+    }
+    if (bag.marketplace === true) {
+        return {
+            ok: false,
+            message: "owned marketplace resource is still registered after removal",
+        };
+    }
+    return { ok: true };
+}

package/dist/manifest-overlay.js

@@ -0,0 +1,125 @@
+import { escapeNonAscii, formatPythonNumber } from "./python-json-format.js";
+import { SafetyError } from "./safety-error.js";
+import { isRawNumber, isRawObject, parseStrictJsonPreservingNumbers, } from "./strict-json.js";
+const OVERLAY_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+    maxDepth: 256,
+};
+/**
+ * Apply the manager's manifest overlay to a Codex plugin manifest.
+ *
+ * Byte-for-byte equivalent to the CPython implementation this replaces:
+ * `json.dump(data, f, indent=2, allow_nan=False)` plus a trailing newline.
+ * The byte-parity evidence lives in
+ * `tests/baseline/manifest-overlay-parity.test.js` (tracked as
+ * `MANIFEST-READER-OVERLAY-01` in `docs/baseline/traceability.md`) against
+ * the fixtures under `tests/fixtures/baseline/overlay-parity/`. Known,
+ * deliberate divergences from strict byte parity are recorded in
+ * `tests/fixtures/baseline/overlay-parity/divergent/README.md`.
+ */
+export function applyManifestOverlay(source, version, path) {
+    let parsed;
+    try {
+        parsed = parseStrictJsonPreservingNumbers(source, OVERLAY_PROFILE);
+    }
+    catch (cause) {
+        throw translate(cause, source, path);
+    }
+    if (!isRawObject(parsed)) {
+        throw new SafetyError("manifest-overlay", `manifest must be a JSON object: ${path}`);
+    }
+    // CPython assigns into a dict: an existing key keeps its position and a new
+    // key is appended in assignment order. Verified 2026-07-31 —
+    // {"version":"old","b":2} becomes {"version": ..., "b": 2, "skills": ...},
+    // while {"b":2} becomes {"b": 2, "version": ..., "skills": ...}.
+    const entries = parsed.entries.map(([key, value]) => [key, value]);
+    setMember(entries, "version", version);
+    setMember(entries, "skills", "./skills/");
+    try {
+        return `${emitObject(entries, 0)}\n`;
+    }
+    catch (cause) {
+        throw rewrapNumberOutOfRange(cause, path);
+    }
+}
+// formatPythonNumber (src/python-json-format.ts) has no notion of a manifest
+// path — it is a general CPython-`json.dump`-equivalent number formatter,
+// exercised on its own in tests/unit/python-json-format.test.js — so it
+// throws a bare `JSON number out of range: ${raw}`. That left the operator
+// with no indication of which manifest produced the diagnostic, unlike every
+// other overlay failure. This rewrap adds the path without touching
+// formatPythonNumber's own contract, and is scoped to exactly this message so
+// it cannot swallow or reword any other overlay throw.
+const NUMBER_OUT_OF_RANGE_PREFIX = "JSON number out of range: ";
+function rewrapNumberOutOfRange(cause, path) {
+    if (cause instanceof SafetyError &&
+        cause.message.startsWith(NUMBER_OUT_OF_RANGE_PREFIX)) {
+        const raw = cause.message.slice(NUMBER_OUT_OF_RANGE_PREFIX.length);
+        return new SafetyError("manifest-overlay", `JSON number out of range in ${path}: ${raw}`, { cause });
+    }
+    return cause;
+}
+function setMember(entries, key, value) {
+    const index = entries.findIndex(([existing]) => existing === key);
+    if (index === -1)
+        entries.push([key, value]);
+    else
+        entries[index] = [key, value];
+}
+/**
+ * Map strict-json's diagnostics onto the CPython wording the callers assert.
+ * Repository policy at `AGENTS.md:90::most diagnostics are asserted as`
+ * freezes most of these diagnostics as complete-string contracts.
+ */
+function translate(cause, source, path) {
+    const text = cause instanceof Error ? cause.message : String(cause);
+    const token = /^non-standard JSON constant (\S+)/.exec(text)?.[1];
+    if (token !== undefined) {
+        return new SafetyError("manifest-overlay", `invalid manifest JSON in ${path}: non-standard numeric constant: ${token}`, { cause });
+    }
+    if (/container depth exceeds/.test(text)) {
+        return new SafetyError("manifest-overlay", `JSON nesting exceeds limit in ${path}`, { cause });
+    }
+    // strict-json reports `… at character N`
+    // (`src/strict-json.ts:305::at character ${this.index}`), a zero-based offset. CPython reports
+    // one-based line and column. Convert so the message keeps CPython's shape.
+    // This does NOT claim the two parsers fail at the same place on the same
+    // malformed input — see the spec.
+    const match = /^(.*) at character (\d+)$/.exec(text);
+    const reason = match?.[1] ?? text;
+    const offset = match === null ? 0 : Number(match[2]);
+    const preceding = source.slice(0, offset);
+    const newlines = preceding.split("\n");
+    const line = newlines.length;
+    const column = (newlines[newlines.length - 1]?.length ?? 0) + 1;
+    return new SafetyError("manifest-overlay", `invalid manifest JSON in ${path}: line ${line} column ${column}: ${reason}`, { cause });
+}
+function emit(value, depth) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return escapeNonAscii(JSON.stringify(value));
+    // Order matters: isRawNumber before isRawObject, and both before Array —
+    // the branded records are objects too.
+    if (isRawNumber(value))
+        return formatPythonNumber(value.source);
+    if (isRawObject(value))
+        return emitObject(value.entries, depth);
+    const inner = "  ".repeat(depth + 1);
+    const outer = "  ".repeat(depth);
+    if (value.length === 0)
+        return "[]";
+    const items = value.map((item) => `${inner}${emit(item, depth + 1)}`);
+    return `[\n${items.join(",\n")}\n${outer}]`;
+}
+function emitObject(entries, depth) {
+    if (entries.length === 0)
+        return "{}";
+    const inner = "  ".repeat(depth + 1);
+    const outer = "  ".repeat(depth);
+    const members = entries.map(([key, item]) => `${inner}${escapeNonAscii(JSON.stringify(key))}: ${emit(item, depth + 1)}`);
+    return `{\n${members.join(",\n")}\n${outer}}`;
+}