akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/git-message.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Leaf util for sanitizing git commit messages.
+ *
+ * Split out of `core/write-source.ts` so that `sources/providers/git-stash.ts`
+ * (which `core/write-source.ts` imports `getCachePaths`/`listGitChangedPaths`/
+ * `parseGitRepoUrl`/`saveGitStash` from, via the `sources/providers/git`
+ * barrel, by value) does not need to import back into `write-source.ts` just
+ * for this helper — that back-edge was a 3-file static-graph cycle
+ * (write-source.ts → git.ts → git-stash.ts → write-source.ts; chunk 9 WI-9.8
+ * KILL 6 sever). Callers import `sanitizeCommitMessage` directly so
+ * the dependency graph stays acyclic.
+ */
+/**
+ * Maximum length of a sanitized git commit message. Git itself imposes no
+ * fixed limit, but message strings come from refs and `--message` flags that
+ * can be supplied by users or upstream config. A 4096-char clamp keeps audit
+ * trails readable and prevents pathological payloads from bloating the log
+ * stream a downstream consumer parses.
+ */
+const COMMIT_MESSAGE_MAX_LENGTH = 4096;
+/**
+ * Sanitize a string before passing it as `git commit -m <message>`.
+ *
+ * Defenses, in order:
+ *   1. Strip NUL bytes (`\0`) — git rejects them anyway, but we never want
+ *      them in argv.
+ *   2. Replace any CR/LF (`\r`, `\n`) and other ASCII control chars with a
+ *      single space. This collapses newline-injection attempts that would
+ *      otherwise turn a single-line commit subject into a forged trailer
+ *      block.
+ *   3. Collapse runs of whitespace into a single space and trim.
+ *   4. Clamp to {@link COMMIT_MESSAGE_MAX_LENGTH} characters.
+ *
+ * If the result is empty after sanitization the caller should substitute a
+ * default — this helper returns `""` rather than throwing because not every
+ * callsite has a sensible "invalid input" exit code, and "empty" is a
+ * recoverable signal.
+ */
+export function sanitizeCommitMessage(input) {
+    if (typeof input !== "string")
+        return "";
+    // 1. Strip NULs outright.
+    let out = input.replace(/\0/g, "");
+    // 2. Replace CR/LF + other C0 control characters (0x00-0x1F, 0x7F) with a
+    //    space. Tab (0x09) is included intentionally — commit subjects should
+    //    be a single visual line.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitization
+    out = out.replace(/[\x00-\x1F\x7F]/g, " ");
+    // 3. Collapse whitespace runs and trim.
+    out = out.replace(/\s+/g, " ").trim();
+    // 4. Clamp length.
+    if (out.length > COMMIT_MESSAGE_MAX_LENGTH) {
+        out = out.slice(0, COMMIT_MESSAGE_MAX_LENGTH).trimEnd();
+    }
+    return out;
+}

package/dist/core/improve-result.js

@@ -0,0 +1,167 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+const COMMON_FIELDS = [
+    "schemaVersion",
+    "ok",
+    "scope",
+    "dryRun",
+    "skipped",
+    "guidance",
+    "memorySummary",
+    "memoryCleanup",
+    "cyclesRun",
+    "plannedRefs",
+    "actions",
+    "distillSkipped",
+    "validationFailures",
+    "schemaRepairs",
+    "consolidation",
+    "extract",
+    "lintSummary",
+    "memoryIndexHealth",
+    "coverageGaps",
+    "evalCasesWritten",
+    "deadUrls",
+    "reflectsWithErrorContext",
+    "memoryInference",
+    "graphExtraction",
+    "memoryInferenceDurationMs",
+    "graphExtractionDurationMs",
+    "orphansPurged",
+    "proposalsExpired",
+    "reflectCooldownActions",
+    "reflectSkippedActions",
+    "reflectGuardRejectedActions",
+    "gateAutoAcceptedCount",
+    "gateAutoAcceptFailedCount",
+    "triage",
+    "proactiveMaintenance",
+    "cycleMetrics",
+    "runId",
+    "sync",
+    "terminated",
+];
+const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
+function fail(message) {
+    throw new Error(`invalid improve-result envelope: ${message}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireExactFields(value, allowed) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        fail(`unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.sort().join(", ")}`);
+}
+function validateCommon(value) {
+    if (typeof value.ok !== "boolean")
+        fail("ok must be a boolean");
+    if (typeof value.dryRun !== "boolean")
+        fail("dryRun must be a boolean");
+    if (!Array.isArray(value.plannedRefs))
+        fail("plannedRefs must be an array");
+    if (!isRecord(value.scope))
+        fail("scope must be an object");
+    requireExactFields(value.scope, new Set(["mode", "value"]));
+    if (value.scope.mode !== "all" && value.scope.mode !== "type" && value.scope.mode !== "ref") {
+        fail('scope.mode must be "all", "type", or "ref"');
+    }
+    if (value.scope.value !== undefined && typeof value.scope.value !== "string") {
+        fail("scope.value must be a string when present");
+    }
+    if (!isRecord(value.memorySummary))
+        fail("memorySummary must be an object");
+    requireExactFields(value.memorySummary, new Set(["eligible", "derived"]));
+    if (typeof value.memorySummary.eligible !== "number" || typeof value.memorySummary.derived !== "number") {
+        fail("memorySummary.eligible and memorySummary.derived must be numbers");
+    }
+    for (const field of [
+        "actions",
+        "validationFailures",
+        "schemaRepairs",
+        "extract",
+        "coverageGaps",
+        "deadUrls",
+    ]) {
+        if (value[field] !== undefined && !Array.isArray(value[field]))
+            fail(`${field} must be an array`);
+    }
+    for (const field of [
+        "cyclesRun",
+        "evalCasesWritten",
+        "reflectsWithErrorContext",
+        "memoryInferenceDurationMs",
+        "graphExtractionDurationMs",
+        "orphansPurged",
+        "proposalsExpired",
+        "reflectCooldownActions",
+        "reflectSkippedActions",
+        "reflectGuardRejectedActions",
+        "gateAutoAcceptedCount",
+        "gateAutoAcceptFailedCount",
+    ]) {
+        if (value[field] !== undefined && typeof value[field] !== "number")
+            fail(`${field} must be a number`);
+    }
+    for (const field of ["guidance", "runId"]) {
+        if (value[field] !== undefined && typeof value[field] !== "string")
+            fail(`${field} must be a string`);
+    }
+    for (const field of [
+        "skipped",
+        "memoryCleanup",
+        "distillSkipped",
+        "consolidation",
+        "lintSummary",
+        "memoryIndexHealth",
+        "memoryInference",
+        "graphExtraction",
+        "triage",
+        "proactiveMaintenance",
+        "cycleMetrics",
+        "sync",
+        "terminated",
+    ]) {
+        if (value[field] !== undefined && !isRecord(value[field]))
+            fail(`${field} must be an object`);
+    }
+    if (isRecord(value.terminated)) {
+        requireExactFields(value.terminated, new Set(["reason", "at", "errorMessage"]));
+        if (typeof value.terminated.reason !== "string" || typeof value.terminated.at !== "string") {
+            fail("terminated.reason and terminated.at must be strings");
+        }
+        if (value.terminated.errorMessage !== undefined && typeof value.terminated.errorMessage !== "string") {
+            fail("terminated.errorMessage must be a string when present");
+        }
+    }
+}
+/** Decode the persisted public result contract. */
+export function decodeImproveResult(input) {
+    let parsed = input;
+    if (typeof input === "string") {
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            fail("not valid JSON");
+        }
+    }
+    if (!isRecord(parsed))
+        fail("root must be an object");
+    if (parsed.schemaVersion === 2) {
+        requireExactFields(parsed, V2_FIELDS);
+        validateCommon(parsed);
+        if (typeof parsed.strategy !== "string" || parsed.strategy.length === 0) {
+            fail("strategy must be a non-empty string");
+        }
+        if (parsed.strategyFilteredRefs !== undefined && !Array.isArray(parsed.strategyFilteredRefs)) {
+            fail("strategyFilteredRefs must be an array");
+        }
+        return {
+            envelope: parsed,
+            strategy: parsed.strategy,
+        };
+    }
+    fail(`unsupported schemaVersion: ${String(parsed.schemaVersion)}`);
+}

package/dist/core/json-schema.js

@@ -0,0 +1,142 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Structural JSON-Schema-subset validator (orchestration plan P1).
+ *
+ * The workflow engine's structured-output normalization needs to validate
+ * unit results against the author-declared unit `output` schema on any harness —
+ * including ones with no native schema support. Pulling in a full
+ * draft-2020-12 validator is deliberately avoided (dependency surface); this
+ * module implements the bounded subset that covers the schemas workflow
+ * authors actually write:
+ *
+ *   Supported: `type` (string | string[] — string, number, integer, boolean,
+ *   object, array, null), `properties`, `required`, `items`,
+ *   `additionalProperties: false`, `enum` (primitives), `minItems`,
+ *   `maxItems`, `minLength`, `maxLength`, `minimum`, `maximum`.
+ *
+ *   Ignored (permissive): `$ref`, `allOf`/`anyOf`/`oneOf`/`not`, `pattern`,
+ *   `format`, and every other keyword. Unknown keywords never throw — a
+ *   schema using them simply constrains less. Callers needing full JSON
+ *   Schema semantics should validate downstream.
+ *
+ * Returns a flat list of human-readable error strings (empty = valid), each
+ * prefixed with a JSON-pointer-ish path — the shape `runStructured`'s
+ * corrective-feedback builder wants.
+ */
+export function validateJsonSchemaSubset(value, schema) {
+    const errors = [];
+    validateNode(value, schema, "$", errors);
+    return errors;
+}
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "boolean":
+            return "boolean";
+        case "number":
+            return Number.isInteger(value) ? "integer" : "number";
+        default:
+            return "object";
+    }
+}
+function matchesType(actual, expected) {
+    if (expected === actual)
+        return true;
+    // JSON Schema: every integer is also a number.
+    return expected === "number" && actual === "integer";
+}
+function validateNode(value, schema, path, errors) {
+    const actual = typeOf(value);
+    const declared = schema.type;
+    if (typeof declared === "string" || Array.isArray(declared)) {
+        const expected = (Array.isArray(declared) ? declared : [declared]).filter((t) => typeof t === "string");
+        if (expected.length > 0 && !expected.some((t) => matchesType(actual, t))) {
+            errors.push(`${path}: expected type ${expected.join(" | ")}, got ${actual}`);
+            return; // type mismatch makes the remaining constraints meaningless
+        }
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        const allowed = schema.enum;
+        if (!allowed.some((candidate) => candidate === value)) {
+            errors.push(`${path}: value ${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`);
+            return;
+        }
+    }
+    if (actual === "string" && typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+        }
+        if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+            errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+        }
+        return;
+    }
+    if ((actual === "number" || actual === "integer") && typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum) {
+            errors.push(`${path}: ${value} is below minimum ${schema.minimum}`);
+        }
+        if (typeof schema.maximum === "number" && value > schema.maximum) {
+            errors.push(`${path}: ${value} is above maximum ${schema.maximum}`);
+        }
+        return;
+    }
+    if (actual === "array" && Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            errors.push(`${path}: array has fewer than minItems ${schema.minItems}`);
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            errors.push(`${path}: array has more than maxItems ${schema.maxItems}`);
+        }
+        const items = schema.items;
+        if (items && typeof items === "object" && !Array.isArray(items)) {
+            value.forEach((element, index) => {
+                validateNode(element, items, `${path}[${index}]`, errors);
+            });
+        }
+        return;
+    }
+    if (actual === "object" && typeof value === "object" && value !== null) {
+        const record = value;
+        const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)
+            ? schema.properties
+            : undefined;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                // `Object.hasOwn`, not `key in record`: a required key satisfied only by
+                // an inherited prototype member (e.g. "toString", "constructor") is NOT
+                // present on the value itself, so `{}` must fail `required: ["toString"]`.
+                if (typeof key === "string" && !Object.hasOwn(record, key)) {
+                    errors.push(`${path}: missing required property "${key}"`);
+                }
+            }
+        }
+        if (properties) {
+            for (const [key, propSchema] of Object.entries(properties)) {
+                if (!Object.hasOwn(record, key))
+                    continue;
+                if (propSchema && typeof propSchema === "object" && !Array.isArray(propSchema)) {
+                    validateNode(record[key], propSchema, `${path}.${key}`, errors);
+                }
+            }
+        }
+        // `additionalProperties: false` closes the object to exactly its declared
+        // `properties`. This MUST run even when no `properties` object is present:
+        // `{ type: "object", additionalProperties: false }` admits only `{}`. Use
+        // `Object.hasOwn` so an inherited key name (e.g. "toString") on the empty
+        // property set is not mistaken for a declared property.
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(record)) {
+                if (!properties || !Object.hasOwn(properties, key)) {
+                    errors.push(`${path}: unexpected property "${key}" (additionalProperties: false)`);
+                }
+            }
+        }
+    }
+}

package/dist/core/lesson-lint.js

@@ -13,9 +13,7 @@
  *
  * Lint produces structured findings rather than throwing so callers can
  * batch-validate (e.g. `akm proposal accept` over a queue) and surface every
- * violation in a single pass. A strict wrapper (`assertLessonValid`) throws
- * a `UsageError` for call sites that want a fail-fast contract — most
- * notably the proposal-accept path described in v1 spec §13.1.
+ * violation in a single pass.
  *
  * The lint is intentionally side-effect free and does not import the indexer
  * or filesystem walker; it operates on a single file path + raw string. This
@@ -24,7 +22,6 @@
  */
 import fs from "node:fs";
 import { parseFrontmatter } from "./asset/frontmatter.js";
-import { UsageError } from "./errors.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -74,16 +71,3 @@ export function lintLessonFile(filePath) {
     const raw = fs.readFileSync(filePath, "utf8");
     return lintLessonContent(raw, filePath);
 }
-/**
- * Strict variant: throws a `UsageError` if any finding is present. The thrown
- * error carries the full set of findings on its message and a hint pointing
- * at v1 spec §13. The first finding's `field` becomes the error's primary
- * field for callers that want to highlight the first violation.
- */
-export function assertLessonValid(filePath) {
-    const report = lintLessonFile(filePath);
-    if (report.findings.length === 0)
-        return;
-    const message = report.findings.map((f) => f.message).join("\n");
-    throw new UsageError(message, "MISSING_REQUIRED_ARGUMENT", "Lessons require non-empty `description` and `when_to_use` frontmatter fields. See v1 spec §13.");
-}

package/dist/core/logs-db.js

@@ -9,7 +9,7 @@
  * The strategic direction (stop scattering data across files/folders) means
  * every NEW log consumer queries this database; the per-run text file written
  * by the task runner is retained only as a transitional tail for humans —
- * see docs/technical/logs-audit.md for the full producer audit.
+ * per the #579 logs audit of every producer.
  *
  * ## Why a separate database from state.db
  *

package/dist/core/maintenance-barrier.js

@@ -0,0 +1,135 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "./file-lock.js";
+import { getMaintenanceBarrierPath } from "./paths.js";
+const heldBarrierContext = new AsyncLocalStorage();
+/**
+ * Serialize restore with the short critical section that creates every
+ * long-lived AKM lock or workflow lease. The long operation keeps its own
+ * lock/lease; this barrier is released immediately after acquisition.
+ */
+export function tryAcquireMaintenanceBarrier() {
+    const lockPath = getMaintenanceBarrierPath();
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: "maintenance-start" }));
+        if (ownership) {
+            return () => releaseLock(ownership);
+        }
+        const probe = probeLock(lockPath);
+        if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
+            return undefined;
+    }
+    return undefined;
+}
+export function acquireMaintenanceBarrier() {
+    const release = tryAcquireMaintenanceBarrier();
+    if (release)
+        return release;
+    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes.`, "INVALID_CONFIG_FILE");
+}
+export function withMaintenanceStartBarrier(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = acquireMaintenanceBarrier();
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+/** Run while holding the start barrier, or return undefined when it is busy. */
+export function tryWithMaintenanceStartBarrier(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = tryAcquireMaintenanceBarrier();
+    if (!release)
+        return undefined;
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+async function acquireMaintenanceBarrierAsync() {
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        const release = tryAcquireMaintenanceBarrier();
+        if (release)
+            return release;
+        if (Date.now() >= deadline)
+            return acquireMaintenanceBarrier();
+        await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+}
+export async function withMaintenanceStartBarrierAsync(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = await acquireMaintenanceBarrierAsync();
+    const ownership = { active: true };
+    try {
+        return await heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+function withMaintenanceStartBarrierSyncWait(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const deadline = Date.now() + 5_000;
+    let release = tryAcquireMaintenanceBarrier();
+    while (!release && Date.now() < deadline) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+        release = tryAcquireMaintenanceBarrier();
+    }
+    if (!release)
+        release = acquireMaintenanceBarrier();
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+/** Register a long-lived operation atomically with restore's blocker scan. */
+export async function acquireMaintenanceActivity(name) {
+    return withMaintenanceStartBarrierAsync(async () => {
+        const directory = path.join(path.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const lockPath = path.join(directory, `${name}-${process.pid}-${randomUUID()}.lock`);
+        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
+        if (!ownership) {
+            throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
+        }
+        return () => releaseLock(ownership);
+    });
+}
+/** Synchronous activity registration for synchronous database handle lifetimes. */
+export function acquireMaintenanceActivitySync(name) {
+    return withMaintenanceStartBarrierSyncWait(() => {
+        const directory = path.join(path.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const lockPath = path.join(directory, `${name}-${process.pid}-${randomUUID()}.lock`);
+        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
+        if (!ownership) {
+            throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
+        }
+        return () => releaseLock(ownership);
+    });
+}

package/dist/core/migration-operation.js

@@ -0,0 +1,44 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { getConfigPath, getDataDir } from "./paths.js";
+let afterPendingCheckHook;
+/** TEST-ONLY: run once after a clear pending-operation check. */
+export function _setAfterPendingOperationCheckHookForTests(hook) {
+    afterPendingCheckHook = hook;
+}
+function installationId() {
+    return crypto
+        .createHash("sha256")
+        .update(path.resolve(path.dirname(getConfigPath())))
+        .update("\0")
+        .update(path.resolve(getDataDir()))
+        .digest("hex")
+        .slice(0, 24);
+}
+export function getMigrationOperationRoot() {
+    return path.join(getDataDir(), "backups", "migrations", installationId());
+}
+export function getMigrationRestoreJournalPath() {
+    return path.join(getMigrationOperationRoot(), "restore-active.json");
+}
+export function getMigrationApplyJournalPath() {
+    return path.join(getMigrationOperationRoot(), "apply-active.json");
+}
+export function assertNoPendingMigrationOperation() {
+    for (const [kind, journalPath] of [
+        ["restore", getMigrationRestoreJournalPath()],
+        ["migration apply", getMigrationApplyJournalPath()],
+    ]) {
+        if (fs.existsSync(journalPath)) {
+            throw new ConfigError(`AKM ${kind} recovery is pending at ${journalPath}; refusing canonical config/database access until recovery completes.`, "INVALID_CONFIG_FILE");
+        }
+    }
+    const hook = afterPendingCheckHook;
+    afterPendingCheckHook = undefined;
+    hook?.();
+}

package/dist/core/mutation-target.js

@@ -0,0 +1,78 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import path from "node:path";
+import { deriveInstallations } from "../indexer/installations.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { displayRef } from "./asset/resolve-ref.js";
+import { UsageError } from "./errors.js";
+import { prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, } from "./write-source.js";
+function canonicalSources(config) {
+    const sources = resolveSourceEntries(undefined, config);
+    const installations = deriveInstallations(sources);
+    return sources.flatMap((source, index) => {
+        const bundleId = installations[index]?.id;
+        return bundleId ? [{ bundleId, source }] : [];
+    });
+}
+function targetForCanonicalSource(config, canonical, options) {
+    const target = canonical.source.registryId
+        ? resolveWriteTarget(config, canonical.source.registryId, options)
+        : resolveWorkingStashTarget(config, options);
+    if (path.resolve(target.source.path) !== path.resolve(canonical.source.path)) {
+        throw new UsageError(`Bundle "${canonical.bundleId}" no longer resolves to its indexed source root.`);
+    }
+    return target;
+}
+/** Resolve the canonical bundle id currently assigned to a write target. */
+export function canonicalBundleIdForTarget(config, target) {
+    return (canonicalSources(config).find((candidate) => path.resolve(candidate.source.path) === path.resolve(target.source.path))?.bundleId ?? target.source.name);
+}
+/** Resolve a canonical bundle qualifier to its writable target without preparing a Git boundary. */
+export function resolveBundleWriteTarget(config, bundleId, options = {}) {
+    const canonical = canonicalSources(config).find((candidate) => candidate.bundleId === bundleId);
+    if (!canonical) {
+        throw new UsageError(`Bundle "${bundleId}" is not configured.`, "INVALID_FLAG_VALUE");
+    }
+    const target = targetForCanonicalSource(config, canonical, options);
+    return { ...target, source: { ...target.source, name: canonical.bundleId } };
+}
+function resolveExplicitMutationTarget(config, explicitTarget, options) {
+    try {
+        return resolveWriteTarget(config, explicitTarget, options);
+    }
+    catch (error) {
+        try {
+            return resolveBundleWriteTarget(config, explicitTarget, options);
+        }
+        catch {
+            throw error;
+        }
+    }
+}
+/** Reconcile a qualified mutation ref with `--target`, then resolve the write destination. */
+export function resolveMutationTarget(config, ref, explicitTarget, options = {}) {
+    const writeOptions = { requireWritable: options.requireWritable };
+    const qualifiedTarget = ref.origin ? resolveBundleWriteTarget(config, ref.origin, writeOptions) : undefined;
+    const explicitResolved = explicitTarget
+        ? resolveExplicitMutationTarget(config, explicitTarget, writeOptions)
+        : undefined;
+    if (qualifiedTarget &&
+        explicitResolved &&
+        path.resolve(qualifiedTarget.source.path) !== path.resolve(explicitResolved.source.path)) {
+        throw new UsageError(`Qualified ref bundle "${ref.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or select the same bundle.`);
+    }
+    let target = qualifiedTarget ?? explicitResolved ?? resolveWriteTarget(config, undefined, writeOptions);
+    const bundleId = ref.origin ?? canonicalBundleIdForTarget(config, target);
+    target = prepareWriteTargetForMutation({ ...target, source: { ...target.source, name: bundleId } }, { allowedAdapters: options.allowedAdapters });
+    const stableRef = { ...ref, origin: bundleId };
+    const defaultBundle = defaultBundleForTarget(config);
+    return {
+        target,
+        ref: stableRef,
+        displayRef: displayRef({ type: stableRef.type, name: stableRef.name, bundleId: stableRef.origin }, defaultBundle),
+    };
+}
+export function defaultBundleForTarget(config) {
+    return config.defaultBundle;
+}