akm-cli 0.9.3 → 0.9.4

package/dist/core/asset/asset-placement.js

@@ -151,10 +151,10 @@ const BUILTIN_PLACEMENT_SPECS = {
         isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".yml",
         toCanonicalName: (typeRoot, filePath) => {
             const rel = toPosix(path.relative(typeRoot, filePath));
-            return rel.endsWith(".yml") ? rel.slice(0, -4) : rel;
+            return rel.toLowerCase().endsWith(".yml") ? rel.slice(0, -4) : rel;
         },
         toAssetPath: (typeRoot, name) => {
-            const withExt = name.endsWith(".yml") ? name : `${name}.yml`;
+            const withExt = name.toLowerCase().endsWith(".yml") ? name : `${name}.yml`;
             return path.join(typeRoot, withExt);
         },
     },
@@ -241,3 +241,22 @@ export function assetPathForName(assetType, typeRoot, name) {
         throw new Error(`Unknown asset type: "${assetType}"`);
     return spec.toAssetPath(typeRoot, name);
 }
+/**
+ * Every physical path spelling that could own `name`, closed-form (#857).
+ * `toAssetPath` is a function, so it can only pick ONE spelling — but `env`'s
+ * "default" alias is genuinely dual-owned: both `<dir>/.env` and
+ * `<dir>/default.env` derive the same canonical name (`toCanonicalName`
+ * above), so a physical-owner lookup must consider both without reading
+ * either file. Every other placement type has exactly one inverse spelling.
+ */
+export function assetPathCandidatesForName(assetType, typeRoot, name) {
+    const primary = assetPathForName(assetType, typeRoot, name);
+    if (assetType !== "env")
+        return [primary];
+    const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;
+    if (base === undefined)
+        return [primary];
+    const dotForm = path.join(typeRoot, base, ".env");
+    const namedForm = path.join(typeRoot, base, "default.env");
+    return [...new Set([primary, dotForm, namedForm])];
+}

package/dist/core/common.js

@@ -5,7 +5,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "./errors.js";
-import { getConfigPath, getDefaultStashDir } from "./paths.js";
+import { getConfigPath, getDefaultStashDir, getRegistryCacheDir, getRegistryIndexCacheDir } from "./paths.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 // Moved to the platform leaf so paths.ts can use it without a common↔paths
 // cycle (chunk-8 WI-8.6, DoD 11); re-exported here for the existing surface.
@@ -382,6 +382,26 @@ export function isContainedRelativePath(value) {
 export function isWithin(candidate, root) {
     return isContainedResolvedPath(safeRealpath(candidate), safeRealpath(root));
 }
+/**
+ * True when `filePath` sits inside akm's OWN resolved registry-cache
+ * directories (`<cache>/registry`, `<cache>/registry-index` —
+ * {@link getRegistryCacheDir}/{@link getRegistryIndexCacheDir}), the
+ * read-only installed-source/registry-index copies that lint (and `--fix`)
+ * must never touch.
+ *
+ * This is the single source of truth for that exclusion — it replaces what
+ * used to be three independent unanchored substring checks
+ * (`posixPath.includes("/.cache/") || posixPath.includes("/registry/")`).
+ * That check matched ANY path merely containing the literal text `.cache` or
+ * `registry` anywhere in it — a normal XDG `~/.cache/...` user bundle, or a
+ * CI workspace checked out under a `.cache`-named directory, tripped it and
+ * silently got zero lint findings. Using {@link isWithin} (realpath +
+ * containment, not a string search) fixes that while still excluding the
+ * real cache content the check was meant to skip.
+ */
+export function isAkmRegistryCachePath(filePath) {
+    return isWithin(filePath, getRegistryCacheDir()) || isWithin(filePath, getRegistryIndexCacheDir());
+}
 /**
  * {@link isWithin} for callers that must not block the event loop (e.g. the
  * workflow exec dispatch path, which runs once per fan-out unit). Same

package/dist/indexer/lookup/adapter-concept-owner.js

@@ -10,10 +10,6 @@ import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
 import { resolveUniqueWorkflowSource, workflowNameForConceptId, } from "../../workflows/source-files.js";
 import { buildFileContext } from "../walk/file-context.js";
 const CONTENT_READ_REQUIRED = Symbol("adapter ownership probe requires content");
-const OWNER_SCAN_MAX_DIRECTORIES = 4_096;
-const OWNER_SCAN_MAX_FILES = 16_384;
-const OWNER_SCAN_SKIP_DIRECTORIES = new Set([".git", "node_modules", "bin", ".cache"]);
-const OWNER_SCAN_SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
 export class AdapterConceptOwnershipError extends UsageError {
 }
 export class AdapterConceptCollisionError extends AdapterConceptOwnershipError {
@@ -24,13 +20,6 @@ export class AdapterConceptCollisionError extends AdapterConceptOwnershipError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-export class AdapterConceptScanError extends AdapterConceptOwnershipError {
-    constructor(adapterId, sourcePath, detail) {
-        super(`Adapter "${adapterId}" could not safely enumerate ${sourcePath}: ${detail}.`, "INVALID_FLAG_VALUE");
-        this.name = "AdapterConceptScanError";
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
 function normalizedConceptId(conceptId) {
     const normalized = conceptId.replaceAll("\\", "/");
     if (!normalized ||
@@ -128,79 +117,6 @@ function claimsWithoutContent(adapter, component, owner) {
         throw error;
     }
 }
-function adapterPathContext(root, authoredPath) {
-    const file = buildFileContext(root, authoredPath);
-    return {
-        absPath: file.absPath,
-        relPath: file.relPath,
-        ext: file.ext,
-        fileName: file.fileName,
-        parentDir: file.parentDir,
-        parentDirAbs: file.parentDirAbs,
-        ancestorDirs: file.ancestorDirs,
-        stashRoot: file.stashRoot,
-    };
-}
-function scanRegularAuthoredPaths(sourcePath, realRoot, adapterId) {
-    const paths = [];
-    const stack = [path.resolve(sourcePath)];
-    let directories = 0;
-    let files = 0;
-    while (stack.length > 0) {
-        const current = stack.pop();
-        if (!current)
-            continue;
-        directories++;
-        if (directories > OWNER_SCAN_MAX_DIRECTORIES) {
-            throw new AdapterConceptScanError(adapterId, sourcePath, `directory limit ${OWNER_SCAN_MAX_DIRECTORIES} exceeded`);
-        }
-        let entries;
-        try {
-            entries = fs
-                .readdirSync(current, { withFileTypes: true })
-                .sort((left, right) => comparePaths(left.name, right.name));
-        }
-        catch (error) {
-            throw new AdapterConceptScanError(adapterId, sourcePath, `cannot read ${current}: ${String(error)}`);
-        }
-        for (let index = entries.length - 1; index >= 0; index--) {
-            const entry = entries[index];
-            if (!entry)
-                continue;
-            const authoredPath = path.join(current, entry.name);
-            if (entry.isSymbolicLink())
-                continue;
-            if (entry.isDirectory()) {
-                if (OWNER_SCAN_SKIP_DIRECTORIES.has(entry.name) || entry.name.startsWith("."))
-                    continue;
-                stack.push(authoredPath);
-                continue;
-            }
-            if (!entry.isFile() || OWNER_SCAN_SKIP_FILES.has(entry.name))
-                continue;
-            files++;
-            if (files > OWNER_SCAN_MAX_FILES) {
-                throw new AdapterConceptScanError(adapterId, sourcePath, `file limit ${OWNER_SCAN_MAX_FILES} exceeded`);
-            }
-            let realPath;
-            try {
-                realPath = fs.realpathSync(authoredPath);
-            }
-            catch {
-                continue;
-            }
-            if (isWithin(realPath, realRoot))
-                paths.push(authoredPath);
-        }
-    }
-    return paths.sort(comparePaths);
-}
-function scannedReadCandidates(adapter, component, sourcePath, realRoot, conceptId) {
-    const recognizePathCandidates = adapter.recognizePathCandidates;
-    if (!recognizePathCandidates)
-        return [];
-    return scanRegularAuthoredPaths(sourcePath, realRoot, adapter.id).flatMap((authoredPath) => recognizePathCandidates(component, adapterPathContext(sourcePath, authoredPath)).flatMap((candidateConceptId) => candidateConceptId === conceptId ? [{ path: authoredPath, conceptId: candidateConceptId }] : []));
-}
 /**
  * Resolve one adapter/component's exact physical concept owner without reading
  * authored bytes. Native workflow arbitration is reused verbatim; every other
@@ -240,11 +156,12 @@ export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
             ownersByIdentity.set(`${path.resolve(workflowOwner.path)}\0${resolutionConceptId}`, workflowOwner);
         }
     }
-    const directSpellings = (adapter.readCandidates?.(component, resolutionConceptId) ?? []).flatMap((candidate) => candidateSpellings(candidate, sourcePath, realRoot));
-    const spellings = [
-        ...directSpellings,
-        ...scannedReadCandidates(adapter, component, sourcePath, realRoot, resolutionConceptId),
-    ];
+    // Closed-form candidate set (#857): `readCandidates` inverts the conceptId
+    // directly into every physical spelling that could own it (no bundle walk
+    // — see each adapter's own doc comment for its candidate classes), and
+    // `candidateSpellings` adds case-only siblings via one `readdirSync` of
+    // each candidate's own parent directory.
+    const spellings = (adapter.readCandidates?.(component, resolutionConceptId) ?? []).flatMap((candidate) => candidateSpellings(candidate, sourcePath, realRoot));
     const inspected = [
         ...new Map(spellings.map((candidate) => [`${path.resolve(candidate.path)}\0${candidate.conceptId}`, candidate])).values(),
     ]

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

@@ -785,6 +785,10 @@ export async function buildDbHit(input) {
         ...(input.entry.beliefState ? { beliefState: input.entry.beliefState } : {}),
         ...(input.entry.currentBeliefRefs ? { currentBeliefRefs: input.entry.currentBeliefRefs } : {}),
         ...(graphHit ? { graph: { entities: graphHit.entities, relations: graphHit.relations } } : {}),
+        // Which stage of the progressive AND->OR lexical ladder produced this
+        // hit. Omitted when the hit has no FTS component (pure-semantic hybrid
+        // contribution).
+        ...(input.lexicalMatch ? { matchStage: input.lexicalMatch } : {}),
     };
     attachDbHitAttribution(hit, input);
     if (input.entry.derivedFrom) {
@@ -825,6 +829,8 @@ rankingMode, qualityBoost, confidenceBoost, utilityBoosted, graphBoost, lexicalM
     ];
     if (lexicalMatch === "relaxed")
         reasons.push("lexical recovery after strict query returned no hits");
+    if (lexicalMatch === "prefix")
+        reasons.push("prefix match after strict query returned no hits");
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const queryLower = query.toLowerCase().trim();
     const name = entry.name.toLowerCase();

package/dist/indexer/walk/matchers.js

@@ -270,28 +270,6 @@ function matchResultForFact(fact) {
         ...(fact.meta ? { meta: fact.meta } : {}),
     };
 }
-/**
- * Every smart-Markdown result possible from path fields alone. The actual
- * classifier above returns only facts from this shared table, so owner
- * discovery can conservatively model a byte request without reading bytes.
- */
-export function smartMdPathCandidates(ctx) {
-    if (ctx.ext !== ".md" || ctx.ancestorDirs.includes("secrets"))
-        return [];
-    const facts = isTypedDirDocFile(ctx.fileName)
-        ? [SMART_MD_FACTS.knowledge]
-        : [
-            SMART_MD_FACTS.workflow,
-            SMART_MD_FACTS.toolsAgent,
-            SMART_MD_FACTS.command,
-            SMART_MD_FACTS.modelAgent,
-            SMART_MD_FACTS.knowledge,
-        ];
-    return facts.flatMap((fact) => {
-        const result = matchResultForFact(fact);
-        return result ? [result] : [];
-    });
-}
 // ---------------------------------------------------------------------------
 // Public matchers (API unchanged)
 // ---------------------------------------------------------------------------

package/dist/output/shapes/helpers.js

@@ -275,7 +275,20 @@ export function shapeSearchHit(hit, detail) {
         // visible without forcing callers up to `--detail full`. Optional
         // `quality` (v1 spec §4.2) is also surfaced when present so callers
         // can see why a `proposed` entry showed up under `--include-proposed`.
-        const shaped = capDescription(pickFields(hit, ["type", "name", "description", "action", "score", "estimatedTokens", "warnings", "quality"]), NORMAL_DESCRIPTION_LIMIT);
+        // `matchStage` (issue #856) surfaces which stage of the progressive
+        // AND->OR lexical ladder produced the hit; cheap compact enum, worth
+        // showing without requiring `--detail full`.
+        const shaped = capDescription(pickFields(hit, [
+            "type",
+            "name",
+            "description",
+            "action",
+            "score",
+            "estimatedTokens",
+            "warnings",
+            "quality",
+            "matchStage",
+        ]), NORMAL_DESCRIPTION_LIMIT);
         if (Array.isArray(hit.keys) && hit.keys.length > 0)
             shaped.keys = hit.keys;
         return shaped;
@@ -296,6 +309,11 @@ export function shapeSearchHitForAgent(hit) {
         "score",
         "estimatedTokens",
         "keys",
+        // Issue #856: which stage of the progressive AND->OR lexical ladder
+        // produced this hit. Agents need this to gauge how much to trust a
+        // hit (a strict-AND match is stronger signal than an OR-fallback
+        // recovery match) without going to `--detail full`.
+        "matchStage",
     ]);
     if (picked.editable !== false)
         delete picked.editHint;

package/dist/output/shapes/passthrough.js

@@ -57,6 +57,7 @@ const PASSTHROUGH_COMMANDS = [
     "task-history",
     "task-run",
     "task-sync",
+    "task-sync-dry-run",
     "update",
     "upgrade",
     "workflow-abandon",

package/dist/output/text/command-format.js

@@ -270,6 +270,10 @@ export function formatSearchPlain(r, detail) {
         // Optional v1 spec §4.2 quality marker (e.g. "curated" / "proposed").
         if (typeof hit.quality === "string" && hit.quality)
             lines.push(`  quality: ${hit.quality}`);
+        // Issue #856: which stage of the progressive AND->OR lexical ladder
+        // produced this hit ("exact" | "prefix" | "relaxed").
+        if (typeof hit.matchStage === "string" && hit.matchStage)
+            lines.push(`  matchStage: ${hit.matchStage}`);
         // Surface optional hit-level warnings (v1 spec §4.2).
         if (Array.isArray(hit.warnings) && hit.warnings.length > 0) {
             lines.push(`  warnings: ${hit.warnings.join("; ")}`);

package/dist/registry/pinned-request-helper.js

@@ -117,8 +117,8 @@ export async function nodePinnedRequestHelperMain(readRequest, http, https, isIP
     };
     try {
         const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-        if (!Number.isInteger(nodeMajor) || nodeMajor < 24) {
-            throw new Error(`The pinned registry helper requires Node.js >= 24; found ${process.versions.node}`);
+        if (!Number.isInteger(nodeMajor) || nodeMajor < 22) {
+            throw new Error(`The pinned registry helper requires Node.js >= 22; found ${process.versions.node}`);
         }
         const { addressFamily, bodyPresent, headers, initialBody, iterator, method, pinnedAddress, timeoutMs, url } = await readRequest(isIP);
         const hostname = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;

package/dist/registry/pinned-transport.js

@@ -233,7 +233,7 @@ async function requestWithNodeHelper(url, address, prepared, init, timeoutMs, ex
 }
 function resolveNodeExecutable(override) {
     if (override === null) {
-        throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 24 on PATH; no Node executable is available");
+        throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 22 on PATH; no Node executable is available");
     }
     const candidates = override === undefined
         ? (process.env.PATH ?? "")
@@ -254,10 +254,10 @@ function resolveNodeExecutable(override) {
             return resolved;
         }
         catch {
-            // Try the next PATH entry. The helper itself enforces Node >= 24.
+            // Try the next PATH entry. The helper itself enforces Node >= 22.
         }
     }
-    throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 24 on PATH. Install Node.js or run akm with Node.");
+    throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 22 on PATH. Install Node.js or run akm with Node.");
 }
 function isSupportedNodeExecutable(executable) {
     const result = spawnSync(executable, ["--version"], {
@@ -272,14 +272,14 @@ function isSupportedNodeExecutable(executable) {
         return false;
     const match = /^v(\d+)\./.exec(result.stdout.trim());
     const major = match?.[1];
-    return major !== undefined && Number.parseInt(major, 10) >= 24;
+    return major !== undefined && Number.parseInt(major, 10) >= 22;
 }
 function assertNodeRuntimeVersion() {
     if (process.versions.bun)
         return;
     const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-    if (!Number.isInteger(major) || major < 24) {
-        throw new RegistryPinnedTransportError(`Pinned registry networking requires Node.js >= 24; found ${process.versions.node}`);
+    if (!Number.isInteger(major) || major < 22) {
+        throw new RegistryPinnedTransportError(`Pinned registry networking requires Node.js >= 22; found ${process.versions.node}`);
     }
 }
 function createHelperArtifacts(ca) {