akm-cli 0.9.4 → 0.9.5

package/dist/core/config/config-version-shim.js

@@ -0,0 +1,101 @@
+// 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/.
+/**
+ * The `configVersion` read shim (#863).
+ *
+ * `configVersion` used to be a hard `z.literal(CURRENT_CONFIG_VERSION)` gate:
+ * every value other than the exact current string threw
+ * `UNSUPPORTED_CONFIG_VERSION` for every command, since every akm invocation
+ * loads config first. That is the same shape of break #858/#859 (proposal
+ * rows), the `task_history` `metadataVersion` gate, and the task-source v2/v3
+ * gate each caused in 0.9.x — a version gate with no read shim — except
+ * `configVersion`'s blast radius is the whole CLI rather than one subsystem.
+ *
+ * This module mirrors the in-tree template for that fix,
+ * `src/tasks/source/parse-task-source.ts`'s v2/v3 -> v4 shim: a known-old
+ * version routes through a pure, in-memory upgrade function to the current
+ * shape, with a one-line stderr deprecation warning; the result is never
+ * written back to disk (the on-disk rewrite already happens for free — every
+ * `saveConfig`/`mutateConfig` write forces `configVersion` to
+ * {@link CURRENT_CONFIG_VERSION}, so the very next `akm config set` or any
+ * other mutating command silences the warning permanently). A version that is
+ * neither current nor a known old version — including anything NEWER than
+ * current — still fails closed with `UNSUPPORTED_CONFIG_VERSION`:
+ * forward-incompatibility is a real hazard (an older binary must not guess at
+ * a newer, unknown shape) and this shim does not soften that.
+ *
+ * IMPORTANT — as of this writing, `"0.9.0"` is the only `configVersion` akm
+ * has ever shipped; there is no real prior release to shim. `"0.0.1"` below
+ * is a SYNTHETIC placeholder entry that exists solely to stand up and
+ * exercise this mechanism — the known-versions list, the dispatch table, the
+ * warn-once-and-upgrade behavior, the fail-closed behavior for anything
+ * else — before a real bump ever needs it (see
+ * `tests/integration/config-version-shim.test.ts` and the
+ * `previous-release-corpus.test.ts` fixture). When the first genuine
+ * `configVersion` bump ships, add its real old shape as its own entry the
+ * same way and delete the synthetic `"0.0.1"` entry (and this paragraph) in
+ * the same change.
+ */
+import { ConfigError } from "../errors.js";
+import { warn } from "../warn.js";
+import { CURRENT_CONFIG_VERSION } from "./schema/primitives.js";
+/**
+ * Every `configVersion` this binary can still READ, other than
+ * {@link CURRENT_CONFIG_VERSION} itself — each with an in-memory upgrade
+ * function in {@link CONFIG_VERSION_UPGRADES}. Anything not in this list (and
+ * not equal to current) fails closed.
+ */
+export const KNOWN_OLD_CONFIG_VERSIONS = ["0.0.1"];
+function isKnownOldConfigVersion(value) {
+    return typeof value === "string" && KNOWN_OLD_CONFIG_VERSIONS.includes(value);
+}
+/**
+ * SYNTHETIC 0.0.1 -> 0.9.0 upgrade (placeholder — see module doc). Per this
+ * placeholder, 0.0.1 kept the default LLM engine name at the config root as
+ * `defaultEngine`; 0.9.0 moved it under `defaults.llmEngine`. Pure function:
+ * takes the raw parsed JSON object, returns a new raw object with the 0.9.0
+ * shape. Never touches disk.
+ */
+function upgradeFrom080(raw) {
+    const { defaultEngine, defaults, ...rest } = raw;
+    if (typeof defaultEngine !== "string" || defaultEngine.length === 0) {
+        return { ...rest, ...(defaults !== undefined ? { defaults } : {}), configVersion: CURRENT_CONFIG_VERSION };
+    }
+    const existingDefaults = defaults !== null && typeof defaults === "object" ? defaults : {};
+    return {
+        ...rest,
+        configVersion: CURRENT_CONFIG_VERSION,
+        // An explicit `defaults.llmEngine` already present in the raw 0.0.1
+        // document (should never happen for a real 0.0.1 file, but a malformed
+        // one is possible) wins over the root-level field being migrated in.
+        defaults: { llmEngine: defaultEngine, ...existingDefaults },
+    };
+}
+const CONFIG_VERSION_UPGRADES = {
+    "0.0.1": upgradeFrom080,
+};
+function unsupportedConfigVersionError(rawVersion, sourcePath) {
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    const supported = [CURRENT_CONFIG_VERSION, ...KNOWN_OLD_CONFIG_VERSIONS].map((v) => `"${v}"`).join(", ");
+    return new ConfigError(`Unsupported configVersion${where}: got ${JSON.stringify(rawVersion)}, expected one of ${supported}.`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
+}
+/**
+ * Route a raw parsed config object through the version shim before schema
+ * validation. Returns a raw object whose `configVersion` is
+ * {@link CURRENT_CONFIG_VERSION} — either unchanged (already current),
+ * in-memory-upgraded (a known old version, with a one-line stderr warning),
+ * or this throws `UNSUPPORTED_CONFIG_VERSION` (unknown, newer, missing, or
+ * malformed).
+ */
+export function upgradeConfigVersion(raw, sourcePath) {
+    const version = raw.configVersion;
+    if (version === CURRENT_CONFIG_VERSION)
+        return raw;
+    if (isKnownOldConfigVersion(version)) {
+        const upgraded = CONFIG_VERSION_UPGRADES[version](raw);
+        warn(`Config${sourcePath ? ` at ${sourcePath}` : ""} uses configVersion "${version}" — auto-upgraded to ${CURRENT_CONFIG_VERSION} in memory; the next config write (e.g. \`akm config set\`) persists this and silences the warning.`);
+        return upgraded;
+    }
+    throw unsupportedConfigVersionError(version, sourcePath);
+}

package/dist/core/config/config.js

@@ -8,6 +8,7 @@ import { liftLegacyEngineExtraParams } from "../extra-params.js";
 import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
 import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
 import { bundlesToSourceEntries } from "./config-sources.js";
+import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig } from "./deep-merge.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
@@ -138,14 +139,13 @@ export function acquireConfigReadFence() {
  * Parse raw config text and validate via Zod.
  * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
  *
- * The schema accepts only the current config version and validates the
- * canonical shape before defaults are merged.
+ * The schema accepts only the current config version. A known older version
+ * is auto-upgraded in memory first (see `./config-version-shim`); anything
+ * else — including anything newer — is rejected before the canonical shape
+ * is validated.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
-    const parsedRaw = parseConfigText(text, sourcePath);
-    if (parsedRaw.configVersion !== CURRENT_CONFIG_VERSION) {
-        throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
-    }
+    const parsedRaw = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
     // #852 (following #815): lift legacy `extraParams` keys — e.g.
     // `reasoning_effort`, a documented 0.9.1 workaround — onto the first-class
     // engine field they now shadow, before the protected-key check in

package/dist/core/improve-result.js

@@ -456,20 +456,24 @@ function validateCommon(value) {
         }
     }
 }
-/** 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) {
+/**
+ * Per-`schemaVersion` decoders for the persisted `improve_runs.result_json`
+ * contract, keyed by the literal `schemaVersion` value each accepts.
+ *
+ * #866 item 5 / read-shim policy (same shape as the version router in
+ * src/tasks/source/parse-task-source.ts, which this mirrors): every
+ * `schemaVersion` this build understands gets its own entry here, so
+ * decoding never regresses to "reject every row" the day the version bumps
+ * — it only stops accepting the ONE version that changed shape. All 1,539
+ * live rows today are v2; when a v3 shape is introduced, add a `3` entry
+ * (and, if v2 rows must keep reading under the newer runtime, keep this `2`
+ * entry as-is — every caller already skip-and-counts a decode failure, so a
+ * genuinely unreadable old row degrades to "excluded from metrics", never a
+ * crash). Do not remove the `2` entry when adding `3` unless the schema
+ * bump is known to be a strict superset callers can validate with it.
+ */
+const SCHEMA_DECODERS = {
+    2: (parsed) => {
         requireExactFields(parsed, V2_FIELDS);
         validateCommon(parsed);
         if (typeof parsed.strategy !== "string" || parsed.strategy.length === 0) {
@@ -482,6 +486,23 @@ export function decodeImproveResult(input) {
             envelope: parsed,
             strategy: parsed.strategy,
         };
+    },
+};
+/** 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");
+    const decoder = typeof parsed.schemaVersion === "number" ? SCHEMA_DECODERS[parsed.schemaVersion] : undefined;
+    if (decoder)
+        return decoder(parsed);
     fail(`unsupported schemaVersion: ${String(parsed.schemaVersion)}`);
 }

package/dist/execution/guarded-source.js

@@ -7,7 +7,6 @@ import path from "node:path";
 import { parseFrontmatter } from "../core/asset/frontmatter.js";
 import { UsageError } from "../core/errors.js";
 import { createExecutionSourceIdentity } from "./source.js";
-export const DEFAULT_GUARDED_SOURCE_MAX_BYTES = 1024 * 1024;
 function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
@@ -71,10 +70,6 @@ function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
     const sourcePath = path.resolve(sourcePathInput);
     const { containmentRoot, containmentRealPath, containmentStat } = requireContainmentRoot(containmentRootInput);
     const lexicalRelative = containedRelative(containmentRoot, sourcePath, false);
-    const maxBytes = options.maxBytes ?? DEFAULT_GUARDED_SOURCE_MAX_BYTES;
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
-        throw new UsageError("Guarded source byte limit must be a non-negative safe integer.", "INVALID_FLAG_VALUE");
-    }
     const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
     let descriptor;
     try {
@@ -83,9 +78,6 @@ function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
         if (!before.isFile()) {
             throw new UsageError(`${sourcePath} is not a regular guarded source file.`, "INVALID_FLAG_VALUE");
         }
-        if (before.size > BigInt(maxBytes)) {
-            throw new UsageError(`${sourcePath} exceeds the guarded source size limit (1 MiB; ${maxBytes} bytes).`, "INVALID_FLAG_VALUE");
-        }
         const bytes = fs.readFileSync(descriptor);
         const after = fs.fstatSync(descriptor, { bigint: true });
         if (!sameBigIntStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
@@ -127,7 +119,6 @@ function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
                 ...(options.identity ? { identity: options.identity } : {}),
             }),
             stat: numberStat(before),
-            maxBytes,
         };
     }
     catch (cause) {
@@ -402,7 +393,6 @@ export class GuardedExecutionSourceCollector {
             try {
                 current = captureRecord(record.source.sourcePath, record.source.containmentRoot, {
                     authored: record.source.authored,
-                    maxBytes: record.maxBytes,
                     ...(record.source.identity ? { identity: record.source.identity } : {}),
                 }).source;
             }

package/dist/indexer/passes/metadata.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { isVerbose, warn } from "../../core/warn.js";
+import { isVerbose, warn, warnVerbose } from "../../core/warn.js";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
 /**
@@ -1119,7 +1119,7 @@ function stripMarkdownLinkDestinations(text, nesting = 0) {
  * secret/env/session bytes; that policy is enforced at the adapter metadata
  * boundary below.
  */
-export function projectMarkdownContent(body) {
+export function projectMarkdownContent(body, truncationInfo) {
     const lines = body.split(/\r?\n/);
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
@@ -1168,6 +1168,8 @@ export function projectMarkdownContent(body) {
     const text = projected.join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
+    if (truncationInfo)
+        truncationInfo.truncated = text.length > MARKDOWN_CONTENT_MAX_CHARS;
     return truncateUnicodeSafe(text, MARKDOWN_CONTENT_MAX_CHARS);
 }
 // ── Metadata Generation ─────────────────────────────────────────────────────
@@ -1212,9 +1214,15 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
         if (entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content)) {
-            const contentProjection = projectMarkdownContent(parsed.content);
-            if (contentProjection)
+            const truncationInfo = { truncated: false };
+            const contentProjection = projectMarkdownContent(parsed.content, truncationInfo);
+            if (contentProjection) {
                 entry.content = contentProjection;
+                if (truncationInfo.truncated) {
+                    entry.contentTruncated = true;
+                    warnVerbose(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
+                }
+            }
         }
         // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
         if (entry.type === "command") {

package/dist/indexer/scan/doc-to-entry.js

@@ -58,6 +58,8 @@ export function indexDocumentToStashEntry(doc) {
         entry.tags = doc.tags;
     if (doc.content !== undefined)
         entry.content = doc.content;
+    if (doc.contentTruncated !== undefined)
+        entry.contentTruncated = doc.contentTruncated;
     if (doc.ownsPresentation !== undefined)
         entry.ownsPresentation = doc.ownsPresentation;
     if (doc.updated !== undefined)

package/dist/indexer/search/search-fields.js

@@ -1,6 +1,16 @@
 // 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/.
+/**
+ * Per-field search text extraction for FTS5 indexing.
+ *
+ * Extracted from indexer.ts to break the circular dependency:
+ *   db.ts -> indexer.ts -> db.ts
+ *
+ * This module imports only from metadata.ts (for the IndexDocument type),
+ * so it can be safely imported by both db.ts and indexer.ts.
+ */
+import { warnVerbose } from "../../core/warn.js";
 /** Structured metadata plus bounded body text supplied to embedding providers. */
 export const SEARCH_TEXT_MAX_CHARS = 8_192;
 /**
@@ -80,12 +90,17 @@ export function buildSearchText(entry) {
     const structured = [fields.name, fields.description, fields.tags, fields.hints]
         .filter((field) => field.length > 0)
         .join(" ");
-    if (structured.length >= SEARCH_TEXT_MAX_CHARS)
+    if (structured.length >= SEARCH_TEXT_MAX_CHARS) {
+        warnVerbose(`${entry.ref ?? entry.name}: search text truncated to ${SEARCH_TEXT_MAX_CHARS} chars (content dropped entirely)`);
         return truncateUnicodeSafe(structured, SEARCH_TEXT_MAX_CHARS);
+    }
     if (!fields.content)
         return structured;
     const separator = structured ? " " : "";
     const remaining = SEARCH_TEXT_MAX_CHARS - structured.length - separator.length;
+    if (fields.content.length > remaining) {
+        warnVerbose(`${entry.ref ?? entry.name}: search text truncated to ${SEARCH_TEXT_MAX_CHARS} chars`);
+    }
     return `${structured}${separator}${truncateUnicodeSafe(fields.content, remaining)}`;
 }
 function truncateUnicodeSafe(text, maxChars) {

package/dist/output/shapes/passthrough.js

@@ -4,6 +4,15 @@
 // #484: stamp schemaVersion + shape discriminator on passthrough envelopes so
 // third-party consumers can pin a schema version and dispatch on shape uniformly.
 // Idempotent — never overwrites an existing schemaVersion or shape field.
+//
+// Builds a shallow copy rather than mutating `result` in place: several
+// command results (e.g. `akm task sync --dry-run`'s `SchedulerPlanPreview`,
+// see src/tasks/scheduler-sync-preview.ts) are deliberately `Object.freeze`d
+// by their producer as an immutability guarantee, and an in-place `obj.shape
+// = …` assignment throws ("Attempting to define property on object that is
+// not extensible") the moment it hits one. Copying tolerates both frozen and
+// mutable inputs uniformly, and `output()` never uses the result's identity
+// past this call, so a copy is safe here.
 function makeStampHandler(command) {
     return (result) => {
         if (result === null || result === undefined)
@@ -11,11 +20,13 @@ function makeStampHandler(command) {
         if (typeof result !== "object" || Array.isArray(result))
             return result;
         const obj = result;
-        if (obj.shape === undefined)
-            obj.shape = command;
-        if (obj.schemaVersion === undefined)
-            obj.schemaVersion = 1;
-        return obj;
+        if (obj.shape !== undefined && obj.schemaVersion !== undefined)
+            return obj;
+        return {
+            ...obj,
+            shape: obj.shape ?? command,
+            schemaVersion: obj.schemaVersion ?? 1,
+        };
     };
 }
 const PASSTHROUGH_COMMANDS = [
@@ -55,6 +66,7 @@ const PASSTHROUGH_COMMANDS = [
     "task-doctor",
     "task-explain",
     "task-history",
+    "task-prune",
     "task-run",
     "task-sync",
     "task-sync-dry-run",