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

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -0,0 +1,154 @@
+// 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 `website-snapshot` adapter — akm 0.9.0 format-family work item (#46).
+ *
+ * A READ-ONLY (Mode A) view over a materialized crawl snapshot written by
+ * `src/sources/snapshot-fetchers/website-ingest.ts` (spec §6/§7). The on-disk
+ * pages are KNOWLEDGE-shaped markdown under `stash/knowledge/**` with no `type:`
+ * field; this adapter RE-TYPES them to the open `type: website`. Per
+ * open-question-3 (RESOLVED, maintainer 2026-07) the re-type is GATED — it
+ * applies only to a page carrying the `website` tag / a `sourceUrl` (a page
+ * lacking both is not re-typed); the document KEEPS its `sourceUrl` (surfaced as
+ * `sourceRef` on `documentJson`); and the conceptId STRIPS the
+ * `stash/knowledge/` prefix. `manifest.json` is snapshot PROVENANCE
+ * (`{url, fetchedAt}`), read by the probe but never indexed as a concept.
+ *
+ * Read-only ⇒ NO `placeNew` (Mode B export routes content through the
+ * DESTINATION adapter, which owns placement). `validate` runs base checks only
+ * (a mirror the adapter does not author has no native validators); `updated`
+ * never appears on a snapshot page, so `missing-updated` is filtered out.
+ *
+ * Conformance oracle (authored, DO NOT modify): fixture
+ * `tests/fixtures/bundles/website-snapshot/` + goldens
+ * `tests/fixtures/format-family-goldens/website-snapshot/{recognition,placement,lint,renderer}.json`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseFrontmatter, parseFrontmatterBlock } from "../../asset/frontmatter.js";
+import { hashContent, nonEmptyString, runBaseValidateChecks } from "./shared.js";
+/** A snapshot bundle is single-component; its one component is `main`. */
+const COMPONENT_ID = "main";
+/** The crawl page root the snapshot writer materializes pages under. */
+const PAGES_PREFIX = "stash/knowledge/";
+/** The provenance manifest basename (probe marker only, never indexed). */
+const MANIFEST_FILE = "manifest.json";
+/** The tag the snapshot writer stamps on every crawled page. */
+const WEBSITE_TAG = "website";
+/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
+const MAX_CONTENT_CHARS = 100_000;
+function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+function parseSnapshotFrontmatter(raw) {
+    const out = { tags: [] };
+    const block = parseFrontmatterBlock(raw);
+    if (!block)
+        return out;
+    let data = {};
+    try {
+        const value = parseYaml(block.frontmatter);
+        if (value && typeof value === "object" && !Array.isArray(value))
+            data = value;
+    }
+    catch {
+        return out;
+    }
+    out.title = nonEmptyString(data.title);
+    out.description = nonEmptyString(data.description);
+    out.sourceUrl = nonEmptyString(data.sourceUrl);
+    if (Array.isArray(data.tags)) {
+        out.tags = data.tags.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => t.trim());
+    }
+    return out;
+}
+/** True when a page is a crawl snapshot page under `stash/knowledge/**`. */
+function isSnapshotPage(relPath) {
+    const posix = toPosix(relPath);
+    return posix.startsWith(PAGES_PREFIX) && posix.toLowerCase().endsWith(".md");
+}
+/** The GATED re-type predicate (open-question-3): the page carries the `website` tag OR a `sourceUrl`. */
+function isReTypeGated(fm) {
+    return fm.sourceUrl !== undefined || fm.tags.includes(WEBSITE_TAG);
+}
+/** conceptId = page path − `stash/knowledge/` prefix − `.md`. */
+function conceptIdOf(relPath) {
+    return toPosix(relPath).slice(PAGES_PREFIX.length).replace(/\.md$/i, "");
+}
+function recognize(c, file) {
+    if (file.ext !== ".md" || !isSnapshotPage(file.relPath))
+        return null;
+    const raw = file.content();
+    const fm = parseSnapshotFrontmatter(raw);
+    if (!isReTypeGated(fm))
+        return null; // not a re-typed website page
+    const conceptId = conceptIdOf(file.relPath);
+    const name = fm.title ?? conceptId.split("/").pop() ?? conceptId;
+    const body = parseFrontmatter(raw).content;
+    const doc = {
+        ref: `${c.id}//${conceptId}`,
+        bundle: c.id,
+        component: COMPONENT_ID,
+        conceptId,
+        path: file.absPath,
+        hash: hashContent(raw),
+        adapterId: "website-snapshot",
+        type: "website",
+        name,
+        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+    };
+    if (fm.description !== undefined)
+        doc.description = fm.description;
+    if (fm.sourceUrl !== undefined)
+        doc.documentJson = { sourceRef: fm.sourceUrl };
+    return doc;
+}
+async function validate(c, changes, ctx) {
+    const diagnostics = [];
+    for (const change of changes) {
+        if (change.op === "delete")
+            continue;
+        const raw = change.after ?? (await ctx.readFile(change.path));
+        if (typeof raw !== "string")
+            continue;
+        if (!isSnapshotPage(change.path))
+            continue;
+        const base = await runBaseValidateChecks(toPosix(change.path), parseFrontmatter(raw), c.root, ctx);
+        // A read-only crawl mirror carries `fetchedAt` provenance, never an `updated`
+        // field — so `missing-updated` is not a defect on a snapshot page.
+        diagnostics.push(...base.filter((d) => d.issue !== "missing-updated"));
+    }
+    return diagnostics;
+}
+export const websiteSnapshotAdapter = {
+    id: "website-snapshot",
+    version: "0.9.0",
+    extensions: [".md"],
+    recognize,
+    validate,
+    // No placeNew: the snapshot is READ-ONLY (Mode A). Export (Mode B) routes
+    // content through the DESTINATION adapter, which owns placement.
+    /**
+     * Install-time probe (§1.2): a root carrying the snapshot provenance
+     * `manifest.json` (`{url, fetchedAt}`). No other bundle root carries this
+     * exact marker, so the probe is unambiguous.
+     */
+    looksLikeRoot(root) {
+        let raw;
+        try {
+            raw = fs.readFileSync(path.join(root, MANIFEST_FILE), "utf8");
+        }
+        catch {
+            return false;
+        }
+        try {
+            const manifest = JSON.parse(raw);
+            return typeof manifest.url === "string" && typeof manifest.fetchedAt === "string";
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/dist/core/adapter/bundle-adapter.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/core/adapter/recognize-match.js

@@ -0,0 +1,42 @@
+// 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 { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher, workflowProgramMatcher, } from "../../indexer/walk/matchers.js";
+/**
+ * The five builtin matchers, in registration order. The array index IS the
+ * registration index `runMatchers` uses for tie-breaking. (The `wiki` matcher
+ * was removed in chunk 4 — the wiki asset-type is retired; LLM Wiki content is
+ * served by the first-class `llm-wiki` adapter, not the akm adapter.)
+ */
+const AKM_MATCHERS = [
+    extensionMatcher,
+    directoryMatcher,
+    parentDirHintMatcher,
+    smartMdMatcher,
+    workflowProgramMatcher,
+];
+/**
+ * Synchronous reproduction of `file-context.ts#runMatchers`'s arbitration
+ * (`:242-265`), minus its `ensureBuiltinsRegistered()` dynamic import. Runs
+ * every builtin matcher in registration order, collects the non-null
+ * `MatchResult`s, and returns the highest-specificity one (ties broken by the
+ * later-registered matcher — higher index — winning). Returns null when no
+ * matcher claims the file.
+ */
+export function recognizeMatch(file) {
+    const hits = [];
+    for (let i = 0; i < AKM_MATCHERS.length; i++) {
+        const result = AKM_MATCHERS[i](file);
+        if (result !== null)
+            hits.push({ result, index: i });
+    }
+    if (hits.length === 0)
+        return null;
+    hits.sort((a, b) => {
+        const specDiff = b.result.specificity - a.result.specificity;
+        if (specDiff !== 0)
+            return specDiff;
+        return b.index - a.index;
+    });
+    return hits[0].result;
+}

package/dist/core/adapter/registry.js

@@ -0,0 +1,56 @@
+// 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 format-family adapter registry — akm 0.9.0 (§4 / normative §12.6).
+ *
+ * A STATIC, FROZEN registry per normative §12.6: the ordered built-in adapter
+ * list ({@link BUILTIN_ADAPTERS}) is defined in the built-in barrel
+ * (`./adapters`) and this module exposes read-only lookups over it. There is NO
+ * mutable registration step and NO load-order dependency — `getAdapters()` and
+ * `adapterForId()` are populated at MODULE LOAD, so every production call site
+ * sees the full set without anyone first calling a registration function. This
+ * replaces the earlier mutable module-level singleton, whose "someone must
+ * register the built-ins first" contract left the registry empty in production
+ * (every source then fell back to `akm`).
+ *
+ * PRODUCTION CONSUMERS (all install/index-time, never query-time): the ordered
+ * `looksLikeRoot` probe in `installations.ts#detectAdapterId`, and the
+ * bundle-root probe in `provider-utils.ts#detectStashRoot`.
+ *
+ * KEYED BY `adapter.id` ONLY. Adapters are FORMAT FAMILIES (§0.2): one adapter
+ * per component root, and `recognize()` is the single source of truth for what
+ * a file IS. The open OKF `type` lives on the emitted `IndexDocument`, never on
+ * the adapter — so there is deliberately NO per-`type` → adapter mapping here.
+ *
+ * QUERY-TIME SAFETY (normative §14.3 / D11 — "adapters/registry never run at
+ * query time"): this module is imported only from install/index-time modules;
+ * the search path (`indexer/search/**`) does not import it, and importing the
+ * frozen list pulls the concrete adapters into no query-time graph.
+ */
+import { BUILTIN_ADAPTERS } from "./adapters/index.js";
+export { BUILTIN_ADAPTERS } from "./adapters/index.js";
+/** `adapter.id -> adapter`, frozen at module load from the static built-in list. */
+const BY_ID = new Map(BUILTIN_ADAPTERS.map((a) => [a.id, a]));
+/**
+ * Every built-in adapter, in the §1.2 install-time probe order (array order ==
+ * probe precedence; see `./adapters` for the ordering rationale). Returns a
+ * fresh array each call so callers may sort/filter it without disturbing the
+ * frozen registry.
+ */
+export function getAdapters() {
+    return [...BUILTIN_ADAPTERS];
+}
+/** Look up an adapter by its own `id` (matches `BundleComponent.adapter`); `undefined` for an unknown id (spec §4 — caller skips + warns). */
+export function adapterForId(id) {
+    return BY_ID.get(id);
+}
+/**
+ * DEPRECATED no-op retained for test back-compat only. The registry is a static
+ * frozen map (normative §12.6) populated at module load, so there is nothing to
+ * reset — `getAdapters()` / `adapterForId()` are always the full built-in set.
+ * New code MUST NOT depend on this.
+ */
+export function resetAdapterRegistryForTests() {
+    // intentionally empty — the registry is static; see the doc comment above.
+}

package/dist/core/adapter/types.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

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

@@ -0,0 +1,229 @@
+// 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/.
+/**
+ * Pure recognition/placement layer for the built-in akm asset types — akm
+ * 0.9.0 chunk-3 (the taxonomy-cutover leaf).
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the `AssetSpec` filesystem
+ * surface (`stashDir`/`isRelevantFile`/`toCanonicalName`/`toAssetPath`), the
+ * per-type stash-subdir map, and the derive/resolve helpers built on them.
+ * Chunk-3 deleted the mutable taxonomy globals that used to expose this data
+ * as ambient registries; the surface is now reached through the small typed
+ * accessors below (`stashDirFor`/`stashDirNames`/`placementTypes`/
+ * `assetPathForName`/`placementSpecFor`), which the `akm` bundle adapter
+ * (`adapter/adapters/akm-adapter.ts`) consumes for placement.
+ *
+ * ── Cycle-safety ──
+ *
+ * This leaf imports only Node builtins and the `core/recognition-util` pure
+ * sink, so it is NOT an import-cycle (SCC) participant. Depending on it from
+ * the `akm` adapter keeps the adapter a leaf. Renderer NAMES and action
+ * builders for the built-in types live in the static `type-presentation.ts`
+ * table (`TYPE_PRESENTATION`); they are intentionally absent here — placement
+ * is a filesystem concern, presentation is a rendering concern.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
+function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}
+const workflowSpec = {
+    isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (rel.toLowerCase().endsWith(ext))
+                return rel.slice(0, -ext.length);
+        }
+        return rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Explicit extension wins (accepts refs like "release/ship.yaml").
+        const lower = name.toLowerCase();
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (lower.endsWith(ext))
+                return path.join(typeRoot, name);
+        }
+        // Probe in priority order — `.md` first for back-compat — and fall back
+        // to the markdown path so error messages keep naming the canonical file.
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            const candidate = path.join(typeRoot, `${name}${ext}`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return path.join(typeRoot, `${name}.md`);
+    },
+};
+const markdownSpec = {
+    isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        // Strip .md extension from canonical names (agent:code-reviewer, not agent:code-reviewer.md)
+        return rel.endsWith(".md") ? rel.slice(0, -3) : rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Accept both with and without .md extension
+        const withExt = name.endsWith(".md") ? name : `${name}.md`;
+        return path.join(typeRoot, withExt);
+    },
+};
+const scriptSpec = {
+    isRelevantFile: (fileName) => SCRIPT_EXTENSIONS.has(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+    toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+};
+const PLACEMENT_SPECS = {
+    skill: {
+        stashDir: "skills",
+        isRelevantFile: (fileName) => fileName === "SKILL.md",
+        toCanonicalName: (typeRoot, filePath) => {
+            const relDir = toPosix(path.dirname(path.relative(typeRoot, filePath)));
+            if (!relDir || relDir === ".")
+                return undefined;
+            return relDir;
+        },
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name, "SKILL.md"),
+    },
+    command: { stashDir: "commands", ...markdownSpec },
+    agent: { stashDir: "agents", ...markdownSpec },
+    knowledge: { stashDir: "knowledge", ...markdownSpec },
+    workflow: { stashDir: "workflows", ...workflowSpec },
+    script: { stashDir: "scripts", ...scriptSpec },
+    memory: { stashDir: "memories", ...markdownSpec },
+    // Environment assets — whole `.env` files sourced/injected wholesale. Replaced
+    // the deprecated `vault` type (removed in 0.9.0). Only key NAMES are surfaced
+    // as metadata; values and comment text are never read for indexing (comments
+    // routinely contain commented-out credentials).
+    env: {
+        stashDir: "env",
+        isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
+        toCanonicalName: (typeRoot, filePath) => {
+            const rel = toPosix(path.relative(typeRoot, filePath));
+            const fileName = path.basename(rel);
+            // Treat ".env" as the "default" env; "<name>.env" → "<name>"
+            if (fileName === ".env") {
+                const dir = path.dirname(rel);
+                return dir === "." || dir === "" ? "default" : `${dir}/default`;
+            }
+            const stripped = rel.endsWith(".env") ? rel.slice(0, -4) : rel;
+            return stripped;
+        },
+        toAssetPath: (typeRoot, name) => {
+            if (name === "default")
+                return path.join(typeRoot, ".env");
+            return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
+        },
+    },
+    // Secrets — a single sensitive value used on its own for authentication (a
+    // PEM key, API token, TLS cert). Unlike `env` (a group of related .env
+    // configuration), the ENTIRE file is the one secret value — there is no safe
+    // region to parse, so only the filename is ever surfaced as metadata. A
+    // secret is any regular file under `secrets/` except `.lock`/`.sensitive`
+    // sidecars; the canonical name preserves the natural filename.
+    secret: {
+        stashDir: "secrets",
+        isRelevantFile: (fileName) => !fileName.endsWith(".lock") && !fileName.endsWith(".sensitive"),
+        toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+    },
+    // v1 spec §13 — `lesson` asset type. Required frontmatter fields are
+    // `description` and `when_to_use`; lint enforces both.
+    lesson: { stashDir: "lessons", ...markdownSpec },
+    // Scheduled tasks. A task file pairs a cron-style schedule with a target
+    // (workflow ref, prompt, or command). Stored as pure YAML under
+    // <stash>/tasks/<id>.yml.
+    task: {
+        stashDir: "tasks",
+        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;
+        },
+        toAssetPath: (typeRoot, name) => {
+            const withExt = name.endsWith(".yml") ? name : `${name}.yml`;
+            return path.join(typeRoot, withExt);
+        },
+    },
+    // #561 — agent sessions indexed as a first-class searchable asset type.
+    // Generated markdown written by the `extract` pass to
+    // `sessions/<harness>/<session-id>.md`.
+    session: { stashDir: "sessions", ...markdownSpec },
+    // Durable stash-level semantic knowledge — facts about the user, team, or
+    // project. A plain markdown spec; see docs/architecture/specs/fact-asset-type.md.
+    fact: { stashDir: "facts", ...markdownSpec },
+};
+/** Live placement spec for a type, or `undefined` for an unknown type. */
+export function placementSpecFor(type) {
+    return PLACEMENT_SPECS[type];
+}
+/** Every registered placement spec (for whole-registry sweeps). */
+export function placementSpecList() {
+    return Object.values(PLACEMENT_SPECS);
+}
+/** Every registered placement type key (the set of types that have a stash subdir). */
+export function placementTypes() {
+    return Object.keys(PLACEMENT_SPECS);
+}
+/** The stash subdir a type places into, or `undefined` for an unknown type. */
+export function stashDirFor(type) {
+    return PLACEMENT_SPECS[type]?.stashDir;
+}
+/**
+ * Reverse of {@link stashDirFor}: the placement type owning a stash subdir, or
+ * `undefined` when no registered type places into it. The type→subdir map is a
+ * bijection over the built-in types (each type has a distinct subdir), so this
+ * is the well-defined inverse. Used by the Chunk-5 dual-grammar shim to reverse
+ * a D-R2 qualified conceptId (`<stash-subdir>/<name>`) back to a legacy
+ * `type:name` predicate so NULL-`item_ref` rows stay findable by new refs.
+ */
+export function typeForStashDir(stashDir) {
+    for (const [type, spec] of Object.entries(PLACEMENT_SPECS)) {
+        if (spec.stashDir === stashDir)
+            return type;
+    }
+    return undefined;
+}
+/** All stash subdir names across the registered types. */
+export function stashDirNames() {
+    return Object.values(PLACEMENT_SPECS).map((spec) => spec.stashDir);
+}
+/**
+ * Mutate the placement registry to add/replace a type's spec. Used by the
+ * custom-asset-type registration surface (extension types); built-ins are
+ * baked into {@link PLACEMENT_SPECS} above.
+ */
+export function registerAssetSpec(type, spec) {
+    PLACEMENT_SPECS[type] = spec;
+}
+/** Remove a previously-registered type's spec. */
+export function deregisterAssetSpec(type) {
+    delete PLACEMENT_SPECS[type];
+}
+export function isRelevantAssetFile(assetType, fileName) {
+    return PLACEMENT_SPECS[assetType]?.isRelevantFile(fileName) ?? false;
+}
+export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
+    return PLACEMENT_SPECS[assetType]?.toCanonicalName(typeRoot, filePath);
+}
+export function deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, filePath) {
+    const relPath = toPosix(path.relative(stashRoot, filePath));
+    const segments = relPath.split("/").filter(Boolean);
+    const firstSegment = segments[0];
+    // When the first segment matches the canonical type dir (e.g. "agents"),
+    // use it as the type root so canonical names are relative to it.
+    // Otherwise fall back to stashRoot — this preserves the full relative path
+    // as the canonical name, which is correct for installed stashes that live
+    // under custom directories (e.g. "tools/agents/svelte-file-editor").
+    const typeRoot = firstSegment !== undefined && firstSegment === stashDirFor(assetType)
+        ? path.join(stashRoot, firstSegment)
+        : stashRoot;
+    return deriveCanonicalAssetName(assetType, typeRoot, filePath);
+}
+export function assetPathForName(assetType, typeRoot, name) {
+    const spec = PLACEMENT_SPECS[assetType];
+    if (!spec)
+        throw new Error(`Unknown asset type: "${assetType}"`);
+    return spec.toAssetPath(typeRoot, name);
+}