akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/improve/source-identity.js

@@ -1,56 +1,28 @@
 // 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 { primaryBundlePath } from "../../core/config/config.js";
-// ── Durable improve-state keys (Chunk-8 WI-8.5c — collapsed to the item_ref) ──
+// ── Durable improve-state keys ───────────────────────────────────────────────
 //
-// Every improve ref is now the new grammar (a SHORT conceptId), and the durable
+// Every improve ref uses the current grammar (a short conceptId), and the durable
 // state key is the resolved index entry's `item_ref` when the planner supplied
 // one, else the conceptId `ref` itself (`preparation.ts`
-// `salienceWriteKey`/`outcomeWriteKey` = `itemRef ?? ref`). The pre-flip
-// source-qualified / legacy-bare dual-key machinery (and its dependency on the
-// retired dual-grammar stored-ref parser) is gone.
+// `salienceWriteKey`/`outcomeWriteKey` = `itemRef ?? ref`).
 /**
  * The durable improve-state key for a ref with no resolved `item_ref` — the
- * conceptId `ref` itself. (`sourceName` is retained for call-site compatibility;
- * the pre-flip source-qualification it drove is gone.)
+ * conceptId `ref` itself.
  */
-export function durableImproveRef(ref, _sourceName) {
+export function durableImproveRef(ref) {
     return ref;
 }
-/** The conceptId for a stored key: strip a `bundle//` prefix if present. */
+/** Return the conceptId portion of a durable improve-state key. */
 export function bareImproveRef(ref) {
     const boundary = ref.indexOf("//");
     return boundary >= 0 ? ref.slice(boundary + 2) : ref;
 }
 /**
- * The durable read key-set for improve state, collapsed onto the write key
- * (`preparation.ts` `salienceWriteKey`/`outcomeWriteKey` = `itemRef ?? ref`).
- * Because that write key is the `item_ref` for a provenance-bearing entry but
- * the bare conceptId `ref` for a provenance-absent one, an asset's durable rows
- * can carry EITHER spelling across runs — so the reader probes both, item_ref
- * first, deduped. The `sourceName`/`includeLegacyBare` parameters are retained
- * for call-site compatibility but no longer widen the set (the retired
- * source-qualified / legacy-bare arms).
+ * The single durable improve-state key used by both readers and writers.
+ * Indexed entries use item_ref; direct or provenance-free refs use conceptId.
  */
-export function improveStateReadRefs(ref, _sourceName, _includeLegacyBare = false, itemRef) {
-    return itemRef !== undefined && itemRef !== ref ? [itemRef, ref] : [ref];
-}
-/**
- * Bare improve state predates source-qualified refs and belongs only to the
- * historical local stash. Named sources at any other root must never inherit it.
- */
-export function shouldReadLegacyBareImproveState(sourceName, sourcePath, config) {
-    if (!sourceName || !sourcePath)
-        return false;
-    // 0.9.0 (spec §10.1 / Decision C): the historical local stash is the primary
-    // bundle (`defaultBundle`). A named source at any other root must never
-    // inherit the pre-source-qualified bare improve state. This defaultBundle-path
-    // equivalence preserves the pre-cutover behavior for a migrated workspace,
-    // whose `stashDir` became the defaultBundle's filesystem `path`.
-    const primaryPath = primaryBundlePath(config);
-    if (!primaryPath)
-        return false;
-    return path.resolve(sourcePath) === path.resolve(primaryPath);
+export function improveStateReadRefs(ref, itemRef) {
+    return [itemRef ?? ref];
 }

package/dist/commands/lint/base-linter.js

@@ -10,7 +10,7 @@
 // `<type>:<slug>` -> on-disk-asset question and MUST agree on the set of
 // reachable refs for any given stash layout.
 //
-// The lock is enforced by `tests/contracts/ref-resolver-contract.test.ts`,
+// The lock is enforced by `tests/integration/contracts/ref-resolver-contract.test.ts`,
 // which drives this implementation through a canonical fixture set. The
 // akm-plugins repo ships an equivalent test that drives its copy through the
 // SAME inputs and asserts identical outcomes. Any change to the resolver
@@ -19,50 +19,28 @@
 //
 // Cases the contract covers (see fixture in the contract test):
 //   - existing memory / knowledge / agent / workflow / skill refs
-//   - knowledge subdirectory layout (knowledge/<category>/<slug>.md)
+//   - namespaced knowledge paths (knowledge/<category>/<slug>.md)
 //   - skill multi-file layout (skills/<slug>/SKILL.md)
-//   - memory `.derived.md` sibling
 //   - namespaced slugs containing `/`
 //   - env (`env/.env`, `env/<name>.env`) and secret (`secrets/<name>`) refs
 //   - non-existent refs
-//   - script type (unresolvable by design — both must return false)
+//   - script paths with explicit extensions
 //
 // As of 0.9 the path mapping in `refToRelPath` is DERIVED FROM THE PLACEMENT
 // SPECS (`assetPathForName` in `src/core/asset/asset-placement.ts`) rather than
 // hand-encoded, so it can no longer drift from the placement layer. `env`/
-// `secret` refs are path-resolved. `script` stays unresolvable and `task`
-// keeps its legacy `.md` resolution (see refToRelPath for both).
+// `secret`, `script`, and `task` refs are path-resolved.
 // ----------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
+import { spliceFrontmatterLine } from "../../core/asset/frontmatter.js";
+import { checkUnquotedDescriptionColon } from "../../core/asset/frontmatter-lint.js";
 import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { localDateStamp } from "../../core/common.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
-function formatDate(d) {
-    const y = d.getFullYear();
-    const m = String(d.getMonth() + 1).padStart(2, "0");
-    const day = String(d.getDate()).padStart(2, "0");
-    return `${y}-${m}-${day}`;
-}
-function checkUnquotedColon(frontmatterText) {
-    if (!frontmatterText)
-        return null;
-    for (const line of frontmatterText.split(/\r?\n/)) {
-        const match = line.match(/^description:\s*(.*)/);
-        if (!match)
-            continue;
-        const value = match[1].trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            return null;
-        }
-        if (value.includes(":")) {
-            return `description value contains unquoted colon: ${value}`;
-        }
-    }
-    return null;
-}
 function fixUnquotedColon(raw) {
     const lines = raw.split(/\r?\n/);
     if (lines[0]?.trim() !== "---")
@@ -88,15 +66,7 @@ function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);
 }
 function fixMissingUpdated(raw, mtime) {
-    const dateStr = formatDate(mtime);
-    const lines = raw.split(/\r?\n/);
-    if (lines[0]?.trim() !== "---")
-        return raw;
-    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
-    if (closeIdx === -1)
-        return raw;
-    lines.splice(closeIdx, 0, `updated: ${dateStr}`);
-    return lines.join("\n");
+    return spliceFrontmatterLine(raw, `updated: ${localDateStamp(mtime)}`) ?? raw;
 }
 // ── stale-path helpers ────────────────────────────────────────────────────────
 function checkStalePath(body) {
@@ -129,50 +99,17 @@ function stripFencedBlocks(body) {
     return lines.join("\n");
 }
 // ── missing-ref helpers ───────────────────────────────────────────────────────
-/**
- * Body-ref boundary grammar, shared with `akm mv`'s ref-rewrite pattern —
- * `src/commands/mv-cli.ts` imports these constants so the two grammars cannot
- * drift. Any character-class change here retargets both the lint missing-ref
- * scan and mv's inbound-xref rewriting.
- *
- * `REF_BOUNDARY_PREFIX_CLASS_SRC` is the character class a ref may start
- * after (a ref also matches at line start): whitespace, backtick, quote,
- * `(`, `[`, or `,` — the `[` admits markdown-link-style refs like
- * `see [memory:foo]`, which the legacy class silently skipped, and the `,`
- * admits the ref AFTER a bare comma in a no-space flow list like
- * `xrefs: [memory:a,memory:b]` (valid YAML). `,` is already a slug
- * TERMINATOR (excluded from `REF_SLUG_CHAR_CLASS_SRC`), so `a,b` splits
- * cleanly and adding it here cannot extend any existing match; false
- * positives are fenced by the type alternation — a comma only starts a match
- * when a literal `<type>:` follows it.
- *
- * `REF_SLUG_CHAR_CLASS_SRC` is the character class a ref's `<type>:<slug>`
- * token is made of; the first excluded character ends the ref.
- */
-export const REF_BOUNDARY_PREFIX_CLASS_SRC = "[\\s`\"'(,\\[]";
-export const REF_SLUG_CHAR_CLASS_SRC = "[^\\s\"'`)\\]>,\\n]";
 /**
  * Map from ref type to relative path pattern within stashRoot. Returns null to
  * skip (type is unresolvable by the slug walker).
  *
  * Path layout is owned by the placement layer: we resolve through
  * `assetPathForName(type, stashDirFor(type), name)` so the linter and the
- * rest of the CLI agree on where an asset lives. Two legacy carve-outs are
- * preserved to keep pre-0.9 behaviour byte-identical:
- *   - `script`: returns null (scripts live in nested dirs with arbitrary
- *     extensions — unresolvable by the slug-based walker, as the contract pins).
- *   - `task`: M1 fix — tasks are stored as `<id>.yml` on disk, so resolve
- *     `task:` refs against `tasks/<id>.yml` to match actual on-disk layout.
+ * rest of the CLI agree on where an asset lives.
  *
  * Exported for contract testing — see header CONTRACT block.
  */
 export function refToRelPath(refType, refName) {
-    // script is intentionally unresolvable (contract-pinned).
-    if (refType === "script")
-        return null;
-    // M1: tasks are stored as .yml on disk; resolve task: refs against tasks/<id>.yml.
-    if (refType === "task")
-        return path.join(stashDirFor("task") ?? "tasks", `${refName}.yml`);
     const typeDir = stashDirFor(refType);
     if (!typeDir)
         return null; // unknown type — skip
@@ -208,56 +145,16 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
  * (the contract pins `refToRelPath` + `refExistsInAnyStash`; this is the
  * shared internal both build on).
  */
-export function resolveRefPathInStash(relPath, refType, refName, root) {
+export function resolveRefPathInStash(relPath, _refType, _refName, root) {
     const absPath = path.join(root, relPath);
     if (fs.existsSync(absPath))
         return absPath;
-    // Multi-file skill layout: directory containing SKILL.md
-    const bareDir = absPath.replace(/\.md$/, "");
-    if (fs.existsSync(bareDir) && fs.existsSync(path.join(bareDir, "SKILL.md"))) {
-        return path.join(bareDir, "SKILL.md");
-    }
-    // .derived.md variant for memory refs
-    if (refType === "memory") {
-        const derivedPath = path.join(root, "memories", `${refName}.derived.md`);
-        if (fs.existsSync(derivedPath))
-            return derivedPath;
-    }
-    // Knowledge-specific: search subdirectories like knowledge/projects/, knowledge/tools/, etc.
-    if (refType === "knowledge") {
-        try {
-            const knowledgeDir = path.join(root, "knowledge");
-            if (fs.existsSync(knowledgeDir) && fs.statSync(knowledgeDir).isDirectory()) {
-                const entries = fs.readdirSync(knowledgeDir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (!entry.isDirectory())
-                        continue;
-                    const subPath = path.join(knowledgeDir, entry.name, `${refName}.md`);
-                    if (fs.existsSync(subPath))
-                        return subPath;
-                }
-            }
-        }
-        catch {
-            // Ignore errors reading directory
-        }
-    }
-    // Fallback: the refName may already encode the full stash-relative path
-    // (e.g. knowledge:skills/foo/references/bar where the file lives at
-    // <stash>/skills/foo/references/bar.md, not <stash>/knowledge/skills/...).
-    const directPath = path.join(root, `${refName}.md`);
-    if (fs.existsSync(directPath))
-        return directPath;
-    const directDir = path.join(root, refName);
-    if (fs.existsSync(directDir) && fs.existsSync(path.join(directDir, "SKILL.md"))) {
-        return path.join(directDir, "SKILL.md");
-    }
     return null;
 }
 /**
  * A `(refType, refName)` pair that is not a lint-checkable local asset ref —
- * shared skip-guard for BOTH recognition arms (legacy `type:name` and the 0.9.0
- * `bundle//conceptId` grammar). Filters the false-positive patterns:
+ * shared skip-guard for recognized `bundle//conceptId` refs. Filters the
+ * false-positive patterns:
  *   - Shell variables: memory:$(cmd) or knowledge:${VAR} (guarded by callers on
  *     the raw token, before it is split).
  *   - Empty names or names that look like absolute paths / home dirs / URLs.
@@ -322,10 +219,10 @@ function scanBundleRefs(scanBody, allRoots) {
  */
 function classifyConceptRef(rawConceptId, allRoots) {
     const conceptId = rawConceptId.split("#", 1)[0];
-    const legacy = typeNameFromConceptId(conceptId);
-    if (legacy === undefined)
+    const parts = typeNameFromConceptId(conceptId);
+    if (parts === undefined)
         return null; // foreign type / not a local asset ref
-    return localRefMissingRelPath(legacy.type, legacy.name, allRoots);
+    return localRefMissingRelPath(parts.type, parts.name, allRoots);
 }
 /**
  * Returns an array of {ref, resolvedRelPath} for every local AKM ref in the
@@ -401,9 +298,8 @@ function dedupeMissing(rows) {
  * would otherwise dangle them silently.
  *
  * `sources:` is deliberately excluded (non-wiki `sources:` was rejected as a
- * typed channel; wiki `sources:` is checked by lintWiki). `source_refs:` /
- * `evidenceSources:` are excluded too — they legitimately point at
- * merged-away or pruned assets (historical provenance).
+ * typed channel; wiki `sources:` is checked by lintWiki). `evidenceSources:` is
+ * excluded because it can point at merged-away or pruned assets.
  */
 const XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
 /**
@@ -568,7 +464,7 @@ export function runBaseChecks(ctx) {
     const shouldRun = (issueType) => !lintSkip.includes(issueType);
     // ── 1. unquoted-colon ──────────────────────────────────────────────────
     if (shouldRun("unquoted-colon")) {
-        const unquotedColonDetail = checkUnquotedColon(ctx.frontmatter);
+        const unquotedColonDetail = checkUnquotedDescriptionColon(ctx.frontmatter);
         if (unquotedColonDetail) {
             if (ctx.fix) {
                 currentRaw = fixUnquotedColon(currentRaw);
@@ -605,7 +501,7 @@ export function runBaseChecks(ctx) {
             issues.push({
                 file: ctx.relPath,
                 issue: "missing-updated",
-                detail: `stamped updated: ${formatDate(mtime)}`,
+                detail: `stamped updated: ${localDateStamp(mtime)}`,
                 fixed: true,
             });
         }
@@ -632,7 +528,7 @@ export function runBaseChecks(ctx) {
         for (const candidate of [...staleInBody, ...staleInFrontmatter]) {
             // M4: Suggest portable replacement when path is under stashRoot.
             const portableHint = candidate.startsWith(ctx.stashRoot)
-                ? ` (portable form: $AKM_STASH_DIR${candidate.slice(ctx.stashRoot.length)})`
+                ? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(ctx.stashRoot.length)})`
                 : "";
             issues.push({
                 file: ctx.relPath,

package/dist/commands/lint/env-key-rules.js

@@ -2,32 +2,32 @@
 // 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/.
 /**
- * Vault security lint rules — flags known-dangerous environment variable names.
+ * Environment security lint rules — flags known-dangerous variable names.
  *
- * These env var names, when present as vault keys, indicate the vault can be
+ * These env var names, when present in an environment file, indicate the file can be
  * used to hijack process execution via loader injection, path override, or
  * shell/runtime startup hooks.  The lint pass emits a warning-level finding;
- * it does NOT block vault load or `akm vault setKey`.
+ * it does NOT block local environment edits.
  *
  * Enforcement scope:
- *   - `akm lint` reports findings as `dangerous-vault-key` (non-blocking warn).
- *   - `akm add` BLOCKS install unless `--allow-insecure` is set (or, on TTY,
+ *   - `akm lint` reports findings as `dangerous-env-key` (non-blocking warn).
+ *   - `akm bundle add` BLOCKS install unless `--allow-insecure` is set (or, on TTY,
  *     the user explicitly confirms at the prompt).
- *   - `akm vault setKey` does NOT consult this list — by design, the operator
- *     owns their own vault and may legitimately store any key locally.  The
- *     gate exists only for third-party stash installation.
+ *   - Local env writes do NOT consult this list — by design, the operator may
+ *     legitimately store any key locally. The gate exists only for third-party
+ *     stash installation.
  *
  * False-positive tradeoff:
  *   A handful of keys (EDITOR, VISUAL, PAGER) are included because they are
  *   invoked by many interactive tools and are a documented RCE vector when
- *   sourced from untrusted vaults.  They will also flag on benign vaults
+ *   sourced from untrusted environments. They will also flag on benign files
  *   where the operator legitimately wants to set their editor — accept the
  *   FP and bypass with `--allow-insecure` after review.
  */
 import fs from "node:fs";
 import { listKeys } from "../env/env.js";
 // ── Dangerous key set ─────────────────────────────────────────────────────────
-export const DANGEROUS_VAULT_KEYS = new Set([
+export const DANGEROUS_ENV_KEYS = new Set([
     // Dynamic linker hijacking (Linux glibc ld.so)
     "LD_PRELOAD", // forces shared library injection
     "LD_LIBRARY_PATH", // overrides library search path
@@ -89,7 +89,7 @@ export const DANGEROUS_VAULT_KEYS = new Set([
  * prefixed with `BASH_FUNC_`.  Listing every concrete name is impossible; we
  * test against this pattern set in addition to the literal `Set`.
  */
-export const DANGEROUS_VAULT_KEY_PATTERNS = [
+export const DANGEROUS_ENV_KEY_PATTERNS = [
     {
         // CVE-2014-6271 (Shellshock) — bash imports exported functions named
         // `BASH_FUNC_<name>%%` and parses their bodies, enabling RCE.
@@ -103,13 +103,13 @@ export const DANGEROUS_VAULT_KEY_PATTERNS = [
 ];
 /**
  * Returns `true` if the given key name is dangerous — either by literal match
- * against `DANGEROUS_VAULT_KEYS` or by matching any entry in
- * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ * against `DANGEROUS_ENV_KEYS` or by matching any entry in
+ * `DANGEROUS_ENV_KEY_PATTERNS`.
  */
-export function isDangerousVaultKey(key) {
-    if (DANGEROUS_VAULT_KEYS.has(key))
+export function isDangerousEnvKey(key) {
+    if (DANGEROUS_ENV_KEYS.has(key))
         return true;
-    for (const { pattern } of DANGEROUS_VAULT_KEY_PATTERNS) {
+    for (const { pattern } of DANGEROUS_ENV_KEY_PATTERNS) {
         if (pattern.test(key))
             return true;
     }
@@ -117,27 +117,26 @@ export function isDangerousVaultKey(key) {
 }
 // ── Checker ───────────────────────────────────────────────────────────────────
 /**
- * Inspect a vault `.env` file and return a lint finding for every key whose
- * name appears in `DANGEROUS_VAULT_KEYS` or matches a pattern in
- * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ * Inspect an `.env` file and return a lint finding for every key whose name
+ * appears in `DANGEROUS_ENV_KEYS` or matches `DANGEROUS_ENV_KEY_PATTERNS`.
  *
- * @param vaultPath  Absolute path to the `.env` file.
+ * @param envPath    Absolute path to the `.env` file.
  * @param relPath    Stash-relative path used as the `file` field in findings
- *                   (e.g. `"vaults/prod.env"`).
- * @param vaultRef   Human-readable vault ref (e.g. `"vault:prod"`) shown in
+ *                   (e.g. `"env/prod.env"`).
+ * @param envRef     Human-readable env ref (e.g. `"env/prod"`) shown in
  *                   the finding message.
  */
 /** Suppression comment token checked case-insensitively on the preceding non-empty line. */
-const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-vault-key";
+const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key";
 /**
- * Returns the set of keys suppressed by an inline `# akm-lint-ok: dangerous-vault-key`
+ * Returns the set of keys suppressed by an inline `# akm-lint-ok: dangerous-env-key`
  * comment on the line immediately preceding the key assignment in the `.env` file.
  */
-function collectSuppressedKeys(vaultPath) {
+function collectSuppressedKeys(envPath) {
     const suppressed = new Set();
     let raw;
     try {
-        raw = fs.readFileSync(vaultPath, "utf8");
+        raw = fs.readFileSync(envPath, "utf8");
     }
     catch {
         return suppressed;
@@ -156,36 +155,21 @@ function collectSuppressedKeys(vaultPath) {
     }
     return suppressed;
 }
-export function checkVaultForDangerousKeys(vaultPath, relPath, vaultRef) {
-    const { keys } = listKeys(vaultPath);
-    const suppressed = collectSuppressedKeys(vaultPath);
+export function checkEnvForDangerousKeys(envPath, relPath, envRef) {
+    const { keys } = listKeys(envPath);
+    const suppressed = collectSuppressedKeys(envPath);
     const issues = [];
     for (const key of keys) {
-        if (!isDangerousVaultKey(key))
+        if (!isDangerousEnvKey(key))
             continue;
         if (suppressed.has(key))
             continue;
         issues.push({
             file: relPath,
-            issue: "dangerous-vault-key",
-            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${vaultRef}. Review this file before running \`akm env run\` commands against untrusted stashes. (suppress with: ${SUPPRESSION_COMMENT} on previous line)`,
+            issue: "dangerous-env-key",
+            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${envRef}. Review this file before running \`akm env run\` commands against untrusted stashes. (suppress with: ${SUPPRESSION_COMMENT} on previous line)`,
             fixed: false,
         });
     }
     return issues;
 }
-// ── Env-neutral aliases ───────────────────────────────────────────────────────
-//
-// These primitives guard *environment variable injection*, which is shared by
-// the `env` asset type, whole-file `secret` injection, and the `akm add`
-// supply-chain gate. The original `*Vault*` names are retained above for
-// backward compatibility (and stable lint output) through the 0.8.x
-// deprecation window; new call sites should prefer the env-neutral names.
-/** Env-neutral alias of {@link DANGEROUS_VAULT_KEYS}. */
-export const DANGEROUS_ENV_KEYS = DANGEROUS_VAULT_KEYS;
-/** Env-neutral alias of {@link DANGEROUS_VAULT_KEY_PATTERNS}. */
-export const DANGEROUS_ENV_KEY_PATTERNS = DANGEROUS_VAULT_KEY_PATTERNS;
-/** Env-neutral alias of {@link isDangerousVaultKey}. */
-export const isDangerousEnvKey = isDangerousVaultKey;
-/** Env-neutral alias of {@link checkVaultForDangerousKeys}. */
-export const checkEnvForDangerousKeys = checkVaultForDangerousKeys;