akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

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

@@ -2,85 +2,7 @@
 // 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 { isAssetType } from "../common.js";
 import { UsageError } from "../errors.js";
-/** Accepted spelling aliases mapping to a canonical asset type. */
-const TYPE_ALIASES = {
-    environment: "env",
-};
-// ── Construction ────────────────────────────────────────────────────────────
-/**
- * Build a ref string from components.
- *
- * Examples:
- *   makeAssetRef("script", "deploy.sh")
- *     → "script:deploy.sh"
- *   makeAssetRef("script", "deploy.sh", "npm:@scope/pkg")
- *     → "npm:@scope/pkg//script:deploy.sh"
- *   makeAssetRef("skill", "code-review", "local")
- *     → "local//skill:code-review"
- *   makeAssetRef("script", "db/migrate/run.sh", "owner/repo")
- *     → "owner/repo//script:db/migrate/run.sh"
- */
-export function makeAssetRef(type, name, origin) {
-    validateName(name);
-    const normalized = normalizeName(name);
-    const asset = `${type}:${normalized}`;
-    if (!origin)
-        return asset;
-    return `${origin}//${asset}`;
-}
-/**
- * Serialize a parsed {@link AssetRef} value-object back to its canonical
- * `[origin//]type:name` string form. The single formatter for refs — call
- * this instead of hand-building `${type}:${name}` template strings so the
- * serialization rules (origin prefix, name normalization) live in one place
- * and stay in lockstep with {@link parseAssetRef}.
- *
- * `refToString(parseAssetRef(s))` round-trips for any `s` that
- * `parseAssetRef` accepts.
- */
-export function refToString(ref) {
-    return makeAssetRef(ref.type, ref.name, ref.origin);
-}
-// ── Parsing ─────────────────────────────────────────────────────────────────
-/**
- * Parse a ref string in the format `[origin//]type:name`.
- */
-export function parseAssetRef(ref) {
-    const trimmed = ref.trim();
-    if (!trimmed)
-        throw new UsageError("Empty ref.", "MISSING_REQUIRED_ARGUMENT");
-    let origin;
-    let body = trimmed;
-    const boundary = trimmed.indexOf("//");
-    if (boundary >= 0) {
-        origin = trimmed.slice(0, boundary);
-        body = trimmed.slice(boundary + 2);
-        if (!origin)
-            throw new UsageError("Empty origin in ref.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const colon = body.indexOf(":");
-    if (colon <= 0) {
-        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name, e.g. skill:deploy or knowledge:guide.md`, "MISSING_REQUIRED_ARGUMENT");
-    }
-    const rawType = body.slice(0, colon);
-    const rawName = body.slice(colon + 1);
-    // The `vault` asset type was removed in 0.9.0. Point callers at its
-    // replacements rather than failing with a generic unknown-type error.
-    if (rawType === "vault") {
-        throw new UsageError("The `vault` asset type was removed in 0.9.0 — use `env:` (whole .env config) or `secret:` (a single value).", "MISSING_REQUIRED_ARGUMENT");
-    }
-    // Type aliases: `environment:` is an accepted spelling of the canonical
-    // `env:` type.
-    const resolvedType = TYPE_ALIASES[rawType] ?? rawType;
-    if (!isAssetType(resolvedType)) {
-        throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");
-    }
-    validateName(rawName);
-    const name = normalizeName(rawName);
-    return { type: resolvedType, name, origin: origin || undefined };
-}
 // ── Validation ──────────────────────────────────────────────────────────────
 function validateName(name) {
     if (!name)
@@ -103,3 +25,110 @@ function validateName(name) {
 function normalizeName(name) {
     return path.posix.normalize(name.replace(/\\/g, "/"));
 }
+/**
+ * Bundle slug charset (spec §3.4): non-empty, and excluding `:`/`.`/`#`/`/`
+ * plus whitespace. Excluding `:`/`.` is what keeps `bundle//conceptId` lexically
+ * distinguishable from a URL in prose; excluding `/` is what makes the first
+ * `//` an unambiguous bundle boundary; excluding `#` reserves it for fragments.
+ */
+const BUNDLE_SLUG_RE = /^[^\s:.#/]+$/;
+/**
+ * True when `s` is a legal bundle slug (spec §11.1 / D-R5 charset: non-empty,
+ * no `:`/`.`/`#`/`/` or whitespace). Exported so the dual-grammar input dispatch
+ * (`resolve-ref.ts`) can classify a `prefix//tail` token by whether its prefix
+ * is a legal bundle slug — the clean legacy-vs-new-grammar discriminator.
+ */
+export function isBundleSlug(s) {
+    return BUNDLE_SLUG_RE.test(s);
+}
+/**
+ * Body-ref recognition (prose): the FULLY-QUALIFIED anchored form ONLY
+ * (`<bundle>//<concept-id>[#<fragment>]`, spec §11.1 — the short form is never
+ * recognized in prose). `g`/`m` for scanning; group 1 = the whole ref token.
+ *
+ * The leading `//` must be preceded by a bundle slug, so a URL (`https://…`,
+ * `//cdn.example.com/…`) never matches: a scheme carries a `:` before `//`
+ * (excluded from the slug), and a scheme-relative `//host` has no slug before
+ * its `//` at all. The bundle-slug charset here additionally excludes the prose
+ * boundary punctuation (brackets/parens/quotes/backtick/comma/angle) so a
+ * leading boundary char (e.g. the `[` of a markdown link) is not absorbed into
+ * the slug. The concept segment reuses the same terminator charset as the
+ * legacy body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
+ * `.`, and a trailing `#fragment`.
+ */
+export const BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]+)/gm;
+/** NFC-normalize + traversal/null-byte/drive-letter guard + path-normalize a concept id. */
+function normalizeConceptId(raw) {
+    const nfc = raw.normalize("NFC");
+    if (nfc.includes("#")) {
+        throw new UsageError("`#` is reserved for the export fragment in a concept id.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    validateName(nfc);
+    return normalizeName(nfc);
+}
+/**
+ * Build a fully-qualified (or short) bundle ref string from its components.
+ *
+ * Examples:
+ *   makeBundleRef(undefined, "knowledge/http-caching")   → "knowledge/http-caching"
+ *   makeBundleRef("core", "knowledge/http-caching")      → "core//knowledge/http-caching"
+ *   makeBundleRef("core", "skills/review", "usage")      → "core//skills/review#usage"
+ */
+export function makeBundleRef(bundle, conceptId, fragment) {
+    const normalized = normalizeConceptId(conceptId);
+    let out = normalized;
+    if (bundle) {
+        if (!BUNDLE_SLUG_RE.test(bundle)) {
+            throw new UsageError(`Invalid bundle slug "${bundle}". A bundle slug may not contain ':', '.', '#', '/', or whitespace.`, "MISSING_REQUIRED_ARGUMENT");
+        }
+        out = `${bundle}//${normalized}`;
+    }
+    if (fragment)
+        out = `${out}#${fragment}`;
+    return out;
+}
+/**
+ * Serialize a parsed {@link BundleRef} back to its canonical
+ * `[bundle//]conceptId[#fragment]` string form — the single formatter for the
+ * 0.9.0 grammar (call this instead of hand-building `${bundle}//${conceptId}`).
+ * `bundleRefToString(parseBundleRef(s))` round-trips for any `s` that
+ * `parseBundleRef` accepts.
+ */
+export function bundleRefToString(ref) {
+    return makeBundleRef(ref.bundle, ref.conceptId, ref.fragment);
+}
+/**
+ * Parse a ref string in the 0.9.0 format `[<bundle>//]<concept-id>[#<fragment>]`.
+ * The bundle prefix and the export fragment are both optional; the short form
+ * (no `bundle//`) leaves `bundle` undefined for the caller to resolve against
+ * the containing bundle (§11.1).
+ */
+export function parseBundleRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new UsageError("Empty ref.", "MISSING_REQUIRED_ARGUMENT");
+    let bundle;
+    let body = trimmed;
+    const boundary = trimmed.indexOf("//");
+    if (boundary >= 0) {
+        bundle = trimmed.slice(0, boundary);
+        body = trimmed.slice(boundary + 2);
+        if (!bundle)
+            throw new UsageError("Empty bundle in ref.", "MISSING_REQUIRED_ARGUMENT");
+        if (!BUNDLE_SLUG_RE.test(bundle)) {
+            throw new UsageError(`Invalid bundle slug "${bundle}" in ref "${trimmed}". A bundle slug may not contain ':', '.', '#', '/', or whitespace.`, "MISSING_REQUIRED_ARGUMENT");
+        }
+    }
+    // Export fragment: everything after the first `#` in the concept body.
+    let fragment;
+    const hash = body.indexOf("#");
+    if (hash >= 0) {
+        fragment = body.slice(hash + 1) || undefined;
+        body = body.slice(0, hash);
+    }
+    if (!body) {
+        throw new UsageError(`Invalid ref "${trimmed}". Expected [bundle//]conceptId, e.g. knowledge/guide or core//skills/review`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    const conceptId = normalizeConceptId(body);
+    return { bundle: bundle || undefined, conceptId, fragment };
+}

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

@@ -45,6 +45,26 @@ import { stringify as yamlStringify } from "yaml";
 export function serializeFrontmatter(frontmatter) {
     return yamlStringify(frontmatter).trimEnd();
 }
+/**
+ * Serialize a frontmatter object with every value `JSON.stringify`-quoted,
+ * without `---` fences and without a trailing newline.
+ *
+ * Use this instead of {@link serializeFrontmatter} when the input is a
+ * pre-validated LLM payload where `yaml.stringify` may emit shapes
+ * (`|`-block scalars, anchors, unquoted multiline) that the project's
+ * hand-rolled `parseFrontmatter` subset parser cannot read back. Every scalar
+ * becomes a quoted JSON literal; arrays become `[<json>, <json>]` (space after
+ * the comma). Field order is preserved from the input's insertion order.
+ *
+ * This is the single home for the "guaranteed-quoted scalars" serializer the
+ * module doc above anticipates; before it, `distill` (array-aware) and
+ * `distill/content-repair` (scalar-only) reimplemented it divergently.
+ */
+export function serializeFrontmatterQuoted(frontmatter) {
+    return Object.entries(frontmatter)
+        .map(([k, v]) => Array.isArray(v) ? `${k}: [${v.map((s) => JSON.stringify(s)).join(", ")}]` : `${k}: ${JSON.stringify(v)}`)
+        .join("\n");
+}
 /**
  * Assemble a complete asset file string from a frontmatter object and a body.
  *

package/dist/core/asset/frontmatter.js

@@ -151,7 +151,7 @@ export function parseFrontmatterBlock(raw) {
         return {
             frontmatter,
             content,
-            bodyStartLine: countLines(raw.slice(0, match[0].length - match[2].length)) + 1,
+            bodyStartLine: countLines(raw.slice(0, match[0].length - content.length)) + 1,
         };
     }
     // Empty frontmatter (---\n---): the content-bearing regex above requires at

package/dist/core/asset/resolve-ref.js

@@ -0,0 +1,223 @@
+// 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/.
+/**
+ * Ref RESOLUTION layer — akm 0.9.0 Chunk-5 flip, stage F1 (ref-grammar decision
+ * D-R1 / D-R4).
+ *
+ * The 0.9.0 ref abstraction is `parse → resolve → serialize`:
+ *   - parse     — `parseBundleRef` (`asset-ref.ts`), pure syntax, no I/O.
+ *   - resolve   — {@link resolveRef} (this module): turn a maybe-short
+ *                 {@link BundleRef} into a fully-qualified {@link ResolvedRef}
+ *                 against an injected {@link RefContext}. This is the "the short
+ *                 form is input sugar" rule (§11.1) made structural: only a
+ *                 `ResolvedRef` ever crosses a storage boundary.
+ *   - serialize — `bundleRefToString` (`asset-ref.ts`); serializing a
+ *                 `ResolvedRef` always emits the fully-qualified form.
+ *
+ * ── Cycle-safety (HARD constraint) ──
+ *
+ * This is a PURE LEAF. It imports only sibling leaves (`asset-ref`,
+ * `asset-placement`) and the `core/errors` sink — nothing from the indexer-db
+ * SCC and no `Database`/config handle. The resolution surface is INJECTED via
+ * {@link RefContext}; callers build the context from their own db handle /
+ * installation list and hand it in. Keeping the resolver free of I/O is what
+ * lets it stay out of every import cycle.
+ *
+ * ── Input-boundary parser (new-grammar only) ──
+ *
+ * {@link parseRefInput} parses a RAW user/CLI/API ref in the 0.9.0
+ * `[bundle//]conceptId` grammar and returns an {@link AssetRef} value object via
+ * the permanent D-R2 reverse table {@link typeNameFromConceptId}. Post-Chunk-8
+ * every durable ref reaching a reader is already the new grammar, so this is the
+ * ONE ref parser outside the frozen migrator — there is no stored-ref dual
+ * grammar to bridge any more.
+ */
+import { NotFoundError, UsageError } from "../errors.js";
+import { stashDirFor, typeForStashDir } from "./asset-placement.js";
+import { isBundleSlug, parseBundleRef } from "./asset-ref.js";
+/**
+ * Resolve a maybe-short input ref to a fully-qualified {@link ResolvedRef}
+ * against `ctx`, implementing D-R4 exactly:
+ *
+ *   1. Already-qualified input (`bundle//…`) → that bundle (passthrough). When
+ *      `ctx.only` is set and disagrees, that is a not-found (the ref names a
+ *      bundle the caller scoped out).
+ *   2. Short input, `only` set → resolve to `only` iff it contains the concept.
+ *   3. Short input, no `only` → `defaultBundle` if it contains the concept,
+ *      otherwise the FIRST bundle (priority order) that contains it.
+ *   4. No match → {@link NotFoundError} naming the forms tried.
+ *
+ * The `#fragment` is carried through untouched.
+ */
+export function resolveRef(input, ctx) {
+    const ref = typeof input === "string" ? parseBundleRef(input) : input;
+    const { conceptId, fragment } = ref;
+    // 1. Qualified passthrough — an explicit bundle prefix wins.
+    if (ref.bundle !== undefined) {
+        if (ctx.only !== undefined && ref.bundle !== ctx.only) {
+            throw notFound(conceptId, [`${ref.bundle}//${conceptId}`], ctx);
+        }
+        return { bundle: ref.bundle, conceptId, fragment };
+    }
+    // `only` scoping restricts the candidate set to a single bundle.
+    const candidates = ctx.only !== undefined ? ctx.bundles.filter((b) => b.id === ctx.only) : ctx.bundles;
+    // 2/3. defaultBundle wins over priority order for a short ref (but only when
+    // not `only`-scoped; an `only` request never falls back to the default).
+    if (ctx.only === undefined && ctx.defaultBundle !== undefined) {
+        const def = ctx.bundles.find((b) => b.id === ctx.defaultBundle);
+        if (def?.hasConcept(conceptId))
+            return { bundle: def.id, conceptId, fragment };
+    }
+    // First candidate (priority order) that contains the concept.
+    for (const b of candidates) {
+        if (b.hasConcept(conceptId))
+            return { bundle: b.id, conceptId, fragment };
+    }
+    throw notFound(conceptId, [conceptId], ctx);
+}
+function notFound(conceptId, triedForms, ctx) {
+    const scope = ctx.only !== undefined ? ` in bundle "${ctx.only}"` : "";
+    const forms = triedForms.map((f) => `"${f}"`).join(", ");
+    return new NotFoundError(`No bundle contains concept "${conceptId}"${scope} (tried ${forms}).`, "ASSET_NOT_FOUND");
+}
+/**
+ * D-R2 conceptId derivation from a legacy `type`/`name` pair
+ * (`stashDirFor(type)/name`; bare name for a foreign type with no placement
+ * stash-subdir). Kept self-contained so {@link displayRef} — a PERMANENT display
+ * rule — does not depend on the transient legacy shims.
+ *
+ * Exported (Chunk-8 WI-8.5c) as the ONE conceptId derivation the improve
+ * correlation sites (`eligibility.ts` candidate refs, `salience.ts`
+ * last-use lookup, `collapse-detector.ts` canary mint/score) share with the
+ * display rule — the permanent successor to the retired transient
+ * `legacyConceptId`.
+ */
+export function conceptIdFromTypeName(type, name) {
+    const stashDir = stashDirFor(type);
+    return stashDir !== undefined ? `${stashDir}/${name}` : name;
+}
+/**
+ * Build the USER-FACING / envelope ref string for an indexed item, applying the
+ * Chunk-5 flip F4b output-spelling rule (orchestrator decision; ref-grammar
+ * decision D-R2 / D-R3). This is the ONE place the rule lives — every emission
+ * site calls it instead of hand-building a ref from an entry.
+ *
+ * The rule mirrors TODAY'S origin-qualification UX, transposed to the 0.9.0
+ * grammar:
+ *
+ *   - An item in the **default/primary bundle** (`bundleId` undefined, or equal
+ *     to `defaultBundleId`) emits the SHORT conceptId (`knowledge/http-caching`)
+ *     — exactly where the pre-0.9.0 output emitted an un-qualified `type:name`.
+ *   - Any other **non-default bundle** emits the fully-qualified
+ *     `bundle//conceptId`. Post-Chunk-8 every bundle id is a legal slug (the
+ *     config migration assigned each source its D-R5 slug bundle key), so this
+ *     is always the new grammar — a non-slug registryId now displays under its
+ *     derived slug bundle id, never the retired `origin//type:name` spelling.
+ */
+export function displayRef(item, defaultBundleId) {
+    const conceptId = item.conceptId ?? conceptIdFromTypeName(item.type, item.name);
+    const { bundleId } = item;
+    // Default/primary bundle → SHORT conceptId (the flip). `"local"`/`"stash"` are
+    // the primary-stash origin sentinels (never real bundle slugs — they name the
+    // workspace's own stash, exactly where the pre-0.9.0 output was un-qualified),
+    // so they display short too.
+    if (bundleId === undefined || bundleId === defaultBundleId || bundleId === "local" || bundleId === "stash")
+        return conceptId;
+    // Non-default bundle → the new fully-qualified `bundle//conceptId` grammar.
+    return `${bundleId}//${conceptId}`;
+}
+/**
+ * Split a qualified conceptId (`<stash-subdir>/<name>`) back to its legacy
+ * `type`/`name`, or `undefined` when the leading segment is not a known stash
+ * subdir (a bare-name conceptId from a foreign type — no legacy predicate
+ * applies). The PERMANENT D-R2 reverse table: the input boundary uses it to map
+ * a new-grammar conceptId onto today's {@link AssetRef} shape. (The migrate home
+ * keeps a private transient copy for stored-ref parsing.)
+ */
+export function typeNameFromConceptId(conceptId) {
+    const slash = conceptId.indexOf("/");
+    if (slash <= 0)
+        return undefined;
+    const type = typeForStashDir(conceptId.slice(0, slash));
+    if (type === undefined)
+        return undefined;
+    return { type, name: conceptId.slice(slash + 1) };
+}
+/**
+ * Parse a RAW user / CLI / API ref string in the 0.9.0 `[bundle//]conceptId`
+ * grammar, returning it in today's {@link AssetRef} value-object shape
+ * (ref-grammar decision D-R1 / D-R4). All boundaries are NEW-GRAMMAR ONLY: a
+ * legacy `type:name` input now fails as an unknown-conceptId not-found. Post-
+ * Chunk-8 every durable ref is already the new grammar, so this parser also
+ * serves the (formerly dual-grammar) stored-ref readers.
+ *
+ * Mapping (new grammar → {@link AssetRef}):
+ *   - `conceptId` → `type`/`name` via {@link typeNameFromConceptId} (the D-R2
+ *     static stash-subdir table). A conceptId whose leading segment is not a
+ *     known stash subdir has no legacy `type` predicate — the same outcome an
+ *     unknown asset type produces today (a not-found).
+ *   - `bundle`    → `origin`. A new-grammar bundle slug is a registryId-shaped
+ *     id by construction, so it flows straight into the legacy origin channel
+ *     that `resolveSourcesForOrigin` matches on `registryId`. The SHORT form (no
+ *     bundle) leaves `origin` undefined = search-all-sources.
+ *   - `#fragment` → rejected. No input boundary consumes an export fragment.
+ */
+export function parseRefInput(raw) {
+    const ref = parseBundleRef(raw);
+    if (ref.fragment !== undefined) {
+        throw new UsageError(`Export fragment "#${ref.fragment}" is not accepted here — drop it from "${raw.trim()}".`, "INVALID_FLAG_VALUE");
+    }
+    const legacy = typeNameFromConceptId(ref.conceptId);
+    if (legacy === undefined) {
+        throw new NotFoundError(`Unrecognized asset ref "${raw.trim()}": conceptId "${ref.conceptId}" has no known asset-type prefix.`, "ASSET_NOT_FOUND");
+    }
+    return { type: legacy.type, name: legacy.name, origin: ref.bundle };
+}
+/**
+ * Parse a CLI/API ref that MAY be qualified by a NON-slug origin — a registry
+ * ref (`github:owner/repo`, `npm:@scope/pkg`, `git:host/path`), a bare path, or
+ * a URL — as its `origin//conceptId` prefix. Such an origin carries `:`/`.`/`/`
+ * so it is not a legal bundle slug and the strict {@link parseRefInput} rejects
+ * it; but it is still a valid SOURCE origin that `resolveSourcesForOrigin`
+ * matches by registry-id / path and the remote-fetch fallback can install. The
+ * conceptId body is parsed under the strict new grammar; the raw origin is kept
+ * as-is — the symmetric input side of {@link displayRef}, which likewise keeps
+ * `origin//…` for exactly these non-slug origins (ref-grammar decision D-R5).
+ *
+ * A short ref (no origin) or a slug-origin ref is delegated verbatim to
+ * {@link parseRefInput}, so this is a safe superset for origin-accepting
+ * commands (`show`, `clone`, `graph`, `history`).
+ */
+export function parseQualifiedRefInput(raw) {
+    const trimmed = raw.trim();
+    const boundary = trimmed.indexOf("//");
+    if (boundary > 0) {
+        const origin = trimmed.slice(0, boundary);
+        if (!isBundleSlug(origin)) {
+            return { ...parseRefInput(trimmed.slice(boundary + 2)), origin };
+        }
+    }
+    return parseRefInput(trimmed);
+}
+/**
+ * Does `raw` already read as a COMPLETE new-grammar asset ref, as opposed to a
+ * bare asset name that a boundary would prefix with a default type (the
+ * `env`/`secret`/`akm mv` "bare name" convenience)?
+ *
+ * True when `raw` is a `[bundle//]conceptId` whose conceptId leads with a KNOWN
+ * stash subdir ({@link typeNameFromConceptId} resolves it). A bare name like
+ * `prod` or `projectA/new-note` is neither — its leading segment maps to no
+ * type — so it stays a bare name for the caller to qualify.
+ */
+export function isFullRefInput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return false;
+    try {
+        return typeNameFromConceptId(parseBundleRef(trimmed).conceptId) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/asset/stash-meta.js

@@ -54,7 +54,7 @@ export function parseMetaRef(ref) {
 }
 /**
  * Reject meta names that would escape the `.meta/` directory. Mirrors the
- * traversal guards in `parseAssetRef`'s `validateName`.
+ * traversal guards in the ref parser's `validateName`.
  */
 function assertSafeMetaName(name) {
     if (name.includes("\0")) {