akm-cli 0.9.2 → 0.9.4

package/dist/storage/repositories/proposals-repository.js

@@ -23,8 +23,24 @@ function changesToStored(changes) {
 /**
  * Reconstruct `Proposal.changes` from `metadata_json.changes` + the `content`
  * column.
+ *
+ * Read-time compatibility shim (#858/#859): proposals created before this
+ * field existed have no `changes` key in `metadata_json` at all (~89% of the
+ * archived accepted/rejected rows on real installs) and that history cannot
+ * be reconstructed from `content` alone. Treat a completely absent `changes`
+ * key as a known legacy gap — return an empty change list rather than
+ * throwing — so these rows still round-trip as real proposals (and count
+ * toward accepted/rejected totals) instead of being dropped or crashing
+ * every reader. A `changes` value that *is* present but malformed (wrong
+ * type, invalid entries) is still corruption and throws, same as before; the
+ * write path (`proposalToRowValues`) still refuses to persist an empty or
+ * missing change list for new proposals, so this leniency only ever applies
+ * to pre-existing rows.
  */
 function storedToChanges(stored, content) {
+    if (stored === undefined) {
+        return [];
+    }
     if (!Array.isArray(stored) || stored.length === 0) {
         throw new Error("Proposal metadata is missing changes.");
     }
@@ -307,7 +323,23 @@ export function listStateProposals(db, options = {}) {
               content, frontmatter_json, metadata_json
        FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
         .all(...params);
-    return rows.map(proposalRowToProposal);
+    // Per-row skip-and-warn (#858/#859): a single row that fails to parse
+    // (invalid ref/status/metadata shape — genuine corruption, distinct from
+    // the tolerated legacy-missing-`changes` case in `storedToChanges` above)
+    // must not abort the entire list. Every caller of this function reads a
+    // multi-row archive; one bad row hiding the rest behind a thrown error is
+    // strictly worse than surfacing the well-formed rows plus a warning.
+    const proposals = [];
+    for (const row of rows) {
+        try {
+            proposals.push(proposalRowToProposal(row));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[akm] Skipping unparseable proposal row (id=${row.id}, ref=${row.ref}): ${message}`);
+        }
+    }
+    return proposals;
 }
 /**
  * Look up a single proposal by id, optionally scoped to one stash root.

package/dist/storage/repositories/task-history-repository.js

@@ -24,7 +24,23 @@ function validateDetail(value) {
         metadataError("detail.exitCode must be a number or null");
     }
 }
-/** Decode the current task-history metadata shape. */
+/**
+ * Decode the task-history metadata shape.
+ *
+ * Read-time compatibility shim (mirrors proposals-repository's
+ * `storedToChanges`): `metadataVersion` was added in a later release. 58% of
+ * a real install's `task_history` rows (8,596/14,801) predate the field
+ * entirely, and 88 more carry additive fields (`profile`, `repairReason`)
+ * written by prior releases. An absent `metadataVersion` is a LEGACY row, not
+ * corruption — decode what's present (defaulting the absent `detail` key to
+ * `null`) instead of throwing. Unknown keys are ignored rather than
+ * hard-rejected, so the next additive field never regresses this again;
+ * neither `profile` nor `repairReason` is read anywhere downstream, so they
+ * are dropped harmlessly rather than round-tripped. A `metadataVersion` that
+ * IS present but not `2` is a genuinely unknown/future shape and still
+ * rejected, as is a non-number `durationMs` or a `detail` that fails
+ * {@link validateDetail} — real corruption, not version skew.
+ */
 export function decodeTaskHistoryMetadata(input) {
     let parsed = input;
     if (typeof input === "string") {
@@ -37,27 +53,23 @@ export function decodeTaskHistoryMetadata(input) {
     }
     if (!isRecord(parsed))
         metadataError("root must be an object");
-    if (parsed.metadataVersion !== 2)
+    if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 2) {
         metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
-    const allowed = new Set(["metadataVersion", "durationMs", "detail", "engine", "targetVocab"]);
-    const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
-    if (unknown.length > 0)
-        metadataError(`unknown fields: ${unknown.sort().join(", ")}`);
+    }
     if (typeof parsed.durationMs !== "number")
         metadataError("durationMs must be a number");
-    if (!("detail" in parsed))
-        metadataError("detail is required");
+    const detail = "detail" in parsed ? parsed.detail : null;
     if (parsed.engine !== undefined && parsed.engine !== null && typeof parsed.engine !== "string") {
         metadataError("engine must be a string or null");
     }
     if (parsed.targetVocab !== undefined && parsed.targetVocab !== 2) {
         metadataError("targetVocab must be 2 when present");
     }
-    validateDetail(parsed.detail);
+    validateDetail(detail);
     return {
         metadataVersion: 2,
         durationMs: parsed.durationMs,
-        detail: parsed.detail ?? null,
+        detail: detail ?? null,
         ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
         ...(parsed.targetVocab === 2 ? { targetVocab: 2 } : {}),
     };

package/dist/tasks/run/run-native-task.js

@@ -64,13 +64,40 @@ export function shellCommand(task, platform = process.platform, env = process.en
             return [task.shell, "-c", command];
         case "pwsh":
         case "powershell":
-            return [shellExecutable(task.shell, platform, env), "-NoProfile", "-NonInteractive", "-Command", command];
+            return [
+                shellExecutable(task.shell, platform, env),
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                withExitCodePropagation(command),
+            ];
         case "cmd":
             return [shellExecutable("cmd", platform, env), "/d", "/s", "/c", command];
         default:
             return assertNever(task.shell, "shellCommand");
     }
 }
+/**
+ * `-Command` (documented identically for powershell.exe 5.1 and pwsh 7+, in
+ * about_PowerShell_exe / about_Pwsh) already derives its own process exit
+ * code from `$?`, so a genuinely failing last statement already yields a
+ * nonzero exit and status "failed" — but any native exit code outside {0, 1}
+ * is collapsed to 1, discarding the real value that task history reports.
+ *
+ * Appending a bare `exit $LASTEXITCODE` to recover it is unsafe on its own:
+ * `$LASTEXITCODE` stays `$null` for a command that never runs a native
+ * executable (a pure PowerShell/cmdlet command), and `exit $null` resolves
+ * to exit code 0 — turning a failed cmdlet into a false "completed".
+ *
+ * Reading `$?` first, before anything else can run, reproduces -Command's
+ * own completed/failed determination exactly (immune to that regression and
+ * to a `$LASTEXITCODE` left stale by an earlier native call in the same
+ * command), then upgrades to the precise native exit code only when the
+ * failing last statement actually set one.
+ */
+function withExitCodePropagation(command) {
+    return `${command}; if ($?) { exit 0 } elseif ($LASTEXITCODE -ne $null) { exit $LASTEXITCODE } else { exit 1 }`;
+}
 /**
  * Bind an unambiguous leading bare `akm` (including the task-v2 migrator's
  * quoted form) to this installation. Explicit paths and arbitrary shell

package/dist/tasks/run/task-history.js

@@ -79,14 +79,34 @@ export function readTaskHistory(options = {}) {
             // discarded and `akm task history --id X --limit 20` always returned one
             // run. The CLI documents --limit as "Maximum rows to return"; honour it.
             if (options.limit !== undefined && options.limit > 0) {
-                return getTaskHistoryRuns(db, options.id, options.limit).map(taskHistoryRowToResult);
+                return decodeTaskHistoryRows(getTaskHistoryRuns(db, options.id, options.limit));
             }
             const row = getTaskHistory(db, options.id);
-            return row ? [taskHistoryRowToResult(row)] : [];
+            return row ? decodeTaskHistoryRows([row]) : [];
         }
-        return queryTaskHistory(db, options.limit !== undefined && options.limit > 0 ? { limit: options.limit } : {}).map(taskHistoryRowToResult);
+        return decodeTaskHistoryRows(queryTaskHistory(db, options.limit !== undefined && options.limit > 0 ? { limit: options.limit } : {}));
     });
 }
+/**
+ * Per-row skip-and-warn (mirrors `listStateProposals` in
+ * proposals-repository.ts): a single genuinely-corrupt `metadata_json` row
+ * must not abort the entire history read. `decodeTaskHistoryMetadata` (via
+ * `taskHistoryRowToResult`) already tolerates legacy/additive shapes; only
+ * real corruption reaches this catch.
+ */
+function decodeTaskHistoryRows(rows) {
+    const results = [];
+    for (const row of rows) {
+        try {
+            results.push(taskHistoryRowToResult(row));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[akm] Skipping unparseable task_history row (task_id=${row.task_id}, started_at=${row.started_at}): ${message}`);
+        }
+    }
+    return results;
+}
 /**
  * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape
  * that callers of `readTaskHistory()` expect.

package/dist/tasks/scheduler-sync-preview.js

@@ -0,0 +1,43 @@
+// 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/.
+/**
+ * Project a set of scheduler sync operations into a preview report. Pure:
+ * no I/O, no backend calls. Accepts a bare operation array (not the whole
+ * `SchedulerSyncPlan`) so a future `task prune` can build a preview from
+ * its own remove-only operation set without needing a full sync plan.
+ */
+export function renderSchedulerPlanPreview(backend, operations, unchanged = []) {
+    const adds = [];
+    const updates = [];
+    const removes = [];
+    for (const operation of operations) {
+        if (operation.kind === "remove") {
+            removes.push({
+                id: operation.id,
+                kind: "remove",
+                nativeId: operation.nativeId,
+                ...(operation.ownerBundlePath !== undefined ? { ownerBundlePath: operation.ownerBundlePath } : {}),
+            });
+        }
+        else if (operation.kind === "install") {
+            adds.push({ id: operation.binding.id, kind: "install" });
+        }
+        else {
+            updates.push({ id: operation.binding.id, kind: "update" });
+        }
+    }
+    return Object.freeze({
+        backend,
+        dryRun: true,
+        adds: Object.freeze(adds),
+        updates: Object.freeze(updates),
+        removes: Object.freeze(removes),
+        unchanged: Object.freeze([...unchanged]),
+        hasRemovals: removes.length > 0,
+    });
+}
+/** Convenience wrapper for the common case: previewing a whole {@link SchedulerSyncPlan}. */
+export function renderSchedulerSyncPlanPreview(backend, plan) {
+    return renderSchedulerPlanPreview(backend, plan.operations, plan.unchanged);
+}

package/dist/tasks/scheduler-sync.js

@@ -135,6 +135,7 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
                 invocation: current.invocation,
                 fingerprint: priorFingerprint,
             }),
+            ...(current.ownerBundlePath !== undefined ? { ownerBundlePath: current.ownerBundlePath } : {}),
         }));
     }
     return Object.freeze({

package/dist/tasks/source/bounded-document.js

@@ -392,7 +392,7 @@ export function assertBoundedTaskYamlDocument(document, options) {
  * P4 (docs/plans/specs/p4-deletions-closeout.md §3.2) deleted task v3
  * acceptance from `src` entirely — `parseTaskV3Yaml` and its `"task v3
  * source"` label no longer exist here (the grammar survives only in the
- * vendored, frozen `scripts/akm-migrate/migrate/task-source-v3-frozen.ts`
+ * vendored, frozen `src/tasks/source/task-source-v3-frozen.ts`
  * copy, which does not call this function). The two live `src` callers
  * today: `parseTaskSourceV4`'s standalone YAML-string entry
  * (`task-source-v4.ts:790`) passes `sourceLabel: "task source v4"`; the

package/dist/tasks/source/parse-task-source.js

@@ -7,14 +7,17 @@
  *
  * Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
  * `root.version`, and either dispatches into `parseTaskSourceV4Document` or
- * fails closed — no second parse, no re-serialization, no synthetic document
- * (the P1b §4.3 invariant this phase carries forward).
+ * routes through the in-memory read shim below — no second parse of the v4
+ * grammar itself, no re-serialization back to disk, no synthetic document
+ * (the P1b §4.3 invariant this phase carries forward: the shim adds a pure
+ * bytes-in/bytes-out detour, never a disk write).
  *
  * The terminal routing table:
  *
  *   | root `version`        | outcome                                                        |
  *   |------------------------|-----------------------------------------------------------------|
  *   | `4`                    | `parseTaskSourceV4Document` — the new grammar (row B-13)        |
+ *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) — the shim removes friction for the deterministic case, it never hides a real problem |
  *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) |
  *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
  *
@@ -24,17 +27,28 @@
  * message that would send the user to the migrator for a document that was
  * never task v2 or v3 in the first place.
  *
- * task v2 and task v3 sources are no longer read by `src` at all — the only
- * surviving reader is the frozen, vendored copy in
- * `scripts/akm-migrate/migrate/task-source-v3-frozen.ts`, reachable only
- * through `akm migrate apply` / `akm-migrate`. The front end's own
- * pre-version failures (source not a string, source too large, YAML
- * parse/warning/expansion) render with the label `task source` (row B-17,
- * closing the "task v3 source" label wart P2a's §3.4 recorded).
+ * task v2 and task v3 sources are no longer read as their own standing
+ * grammar anywhere else in `src` — the only readers of that grammar are the
+ * pure, byte-producing planners (`./task-to-v3.ts`, `./task-to-v4.ts`, and
+ * the frozen v3 reader `./task-source-v3-frozen.ts`), reached either through
+ * this shim (bytes in, bytes out, never touches disk) or through
+ * `akm migrate apply` / `akm-migrate` (`scripts/akm-migrate`, which
+ * additionally rewrites the file on disk once the user asks for that).
+ * Policy: a deterministic byte transform is the tool's job, not the user's —
+ * upgrading past a schema bump must not silently break a scheduled task, so
+ * v2/v3 files keep reading successfully at the cost of a one-line
+ * deprecation warning, and `akm migrate apply` remains available to rewrite
+ * the file and silence it. The front end's own pre-version failures (source
+ * not a string, source too large, YAML parse/warning/expansion) render with
+ * the label `task source` (row B-17, closing the "task v3 source" label
+ * wart P2a's §3.4 recorded).
  */
 import { UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
 import { readBoundedTaskSourceYaml } from "./bounded-document.js";
-import { parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION } from "./task-source-v4.js";
+import { parseTaskSourceV4, parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION, } from "./task-source-v4.js";
+import { planTaskToV3File } from "./task-to-v3.js";
+import { planTaskToV4File } from "./task-to-v4.js";
 /** Read the root `version` field without over-accepting non-number values (e.g. the string `"4"`). */
 export function peekTaskSourceVersion(root) {
     if (root === null || typeof root !== "object" || Array.isArray(root))
@@ -43,12 +57,64 @@ export function peekTaskSourceVersion(root) {
     return typeof value === "number" ? value : undefined;
 }
 const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+function unsupportedVersionError(filePath, version) {
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
+}
+/**
+ * Plan the SAME bytes already in hand through the pure v3->v4 (and, for v2,
+ * chained v2->v3->v4) migration planner(s) — never touches disk, never
+ * writes the file, never re-reads it from disk. Returns the produced v4
+ * YAML text, or `undefined` when the deterministic conversion cannot
+ * proceed (an unmigratable v2/v3 shape) — the caller falls back to the same
+ * hard error this gate threw before the shim existed.
+ */
+function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
+    const bytes = Buffer.from(yaml, "utf8");
+    // `writable`/`onDiskWritable` gate the DISK apply path's "don't touch a
+    // read-only file" check inside the planners; this shim never writes
+    // anything to disk, so that check does not apply here and must not block
+    // an otherwise-legal read of a task file that happens to be read-only.
+    const baseInput = {
+        filePath,
+        bytes,
+        mode: 0o644,
+        writable: true,
+        onDiskWritable: true,
+        ...(workspaceRoot ? { containmentRoot: workspaceRoot } : {}),
+    };
+    let v3Bytes;
+    if (version === 3) {
+        v3Bytes = bytes;
+    }
+    else {
+        const v3Outcome = planTaskToV3File(baseInput);
+        if (v3Outcome.status !== "changed")
+            return undefined;
+        v3Bytes = v3Outcome.after;
+    }
+    const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
+    if (v4Outcome.status !== "changed")
+        return undefined;
+    return v4Outcome.after.toString("utf8");
+}
 /** Parse task source YAML, routing per the terminal table above. */
 export function parseTaskSource(input) {
     const { root, lineAt } = readBoundedTaskSourceYaml(input, { sourceLabel: "task source" });
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
-        throw new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${input.filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
+        if (version === 2 || version === 3) {
+            const v4Yaml = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+            if (v4Yaml !== undefined) {
+                const v4 = parseTaskSourceV4({
+                    yaml: v4Yaml,
+                    filePath: input.filePath,
+                    ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
+                });
+                warn(`akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
+                return Object.freeze({ version: 4, v4 });
+            }
+        }
+        throw unsupportedVersionError(input.filePath, version);
     }
     const documentOptions = {
         filePath: input.filePath,