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

package/dist/core/adapter/adapters/akm-metadata.js

@@ -0,0 +1,416 @@
+// 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/.
+/**
+ * Index-time metadata fold for the `akm` adapter's `recognize` — akm 0.9.0
+ * chunk-2, WI-C, implementing spec §2 ("the nine index-time metadata
+ * contributors move into recognize") + the 2 workflow contributors.
+ *
+ * This leaf reproduces the 11 `registerMetadataContributor` sites keyed on the
+ * winning RENDERER name (exactly how each contributor's `appliesTo({ rendererName })`
+ * selects):
+ *
+ *   - `output/renderers.ts` (9): toc-metadata (knowledge-md),
+ *     lesson-frontmatter-metadata, memory-frontmatter-metadata,
+ *     script-comment-metadata, env-file-metadata, secret-file-metadata,
+ *     task-yaml-metadata, session-md-metadata, fact-md-metadata;
+ *   - `workflows/renderer.ts` (2): workflow-document-metadata (workflow-md),
+ *     workflow-program-metadata (workflow-program-yaml).
+ *
+ * ── Cycle-safety (chunk-2 ratchet, baseline 18) ──
+ *
+ * Imported ONLY by `akm-adapter.ts` (itself imported by nothing in `src/` — see
+ * that file's header), so this leaf can never gain an inbound edge from a cycle
+ * participant and therefore can never JOIN a cycle. It VALUE-imports the pure
+ * parsers each contributor already uses so the fold cannot drift from them:
+ * `parseFrontmatter`, `parseMarkdownToc`, `parseWorkflow`, `parseWorkflowProgram`,
+ * `projectProgramParameters`/`programStepInstructions`, and `listKeys`
+ * (env key-names). `output/renderers.ts` / `workflows/renderer.ts` are the
+ * cycle-sensitive modules whose contributor bodies live in this port — their
+ * ONE non-importable helper (`metadata.ts#extractDescriptionFromComments`, a
+ * heavy cycle-participant module) is copied verbatim below as
+ * {@link extractDescriptionFromComments} rather than imported. Verified:
+ * `bun scripts/lint-import-cycles.ts` stays at 18.
+ *
+ * ── What is folded, and where it lands on the IndexDocument ──
+ *
+ * The contributors mutate a `IndexDocument`; {@link foldRecognizedMetadata} returns
+ * the same fields as a plain {@link FoldedMetadata}, which `recognize` maps onto
+ * `IndexDocument` first-class fields (`tags`/`searchHints`/`description`/
+ * `confidence`) and, for the fields without a first-class home
+ * (`toc`/`parameters`/`source`), onto `documentJson` (opaque adapter extras).
+ * The seed is a MINIMAL entry (name+type only): this isolates exactly what the
+ * contributors add, which is what the parity test compares against
+ * `applyMetadataContributors` run on the same minimal seed.
+ *
+ * ── Tolerance note ──
+ *
+ * Every contributor that reads/parses content is reproduced with the SAME
+ * try/catch tolerance it has today (toc/memory/session/fact/task swallow parse
+ * errors). The two workflow contributors throw-to-skip in today's pipeline (a
+ * broken workflow is dropped by the metadata drain); here the parse is wrapped
+ * so a broken workflow yields no folded metadata instead of throwing out of the
+ * synchronous `recognize` — the drop-the-entry behavior is an index-drain
+ * concern (Chunk 4/5), not recognition's. On the valid Chunk-0b fixture this
+ * distinction never triggers.
+ */
+import fs from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { listKeys } from "../../../commands/env/env.js";
+import { parseWorkflow } from "../../../workflows/parser.js";
+import { parseWorkflowProgram } from "../../../workflows/program/parser.js";
+import { programStepInstructions, projectProgramParameters } from "../../../workflows/program/project.js";
+import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { parseMarkdownToc } from "../../asset/markdown.js";
+import { nonEmptyString } from "./shared.js";
+/**
+ * Verbatim copy of `indexer/passes/metadata.ts#extractDescriptionFromComments`
+ * (`:1510-1552`) — `metadata.ts` is a heavy cycle-participant module, so the
+ * one non-importable helper `applyScriptMetadata` needs is copied here (the
+ * others are imported). Reads a leading JSDoc block or hash-comment run from the
+ * script file; returns `null` on read/parse miss.
+ */
+function extractDescriptionFromComments(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const lines = content.split(/\r?\n/).slice(0, 50);
+    const blockStart = lines.findIndex((l) => /^\s*\/\*\*/.test(l));
+    if (blockStart >= 0) {
+        const desc = [];
+        for (let i = blockStart; i < lines.length; i++) {
+            const line = lines[i];
+            if (i > blockStart && /\*\//.test(line))
+                break;
+            const cleaned = line
+                .replace(/^\s*\/?\*\*?\s?/, "")
+                .replace(/\*\/\s*$/, "")
+                .trim();
+            if (cleaned)
+                desc.push(cleaned);
+        }
+        if (desc.length > 0)
+            return desc.join(" ");
+    }
+    let start = 0;
+    if (lines[0]?.startsWith("#!"))
+        start = 1;
+    const hashLines = [];
+    for (let i = start; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.startsWith("#") && !line.startsWith("#!")) {
+            hashLines.push(line.replace(/^#+\s*/, "").trim());
+        }
+        else if (line === "") {
+        }
+        else {
+            break;
+        }
+    }
+    if (hashLines.length > 0)
+        return hashLines.join(" ");
+    return null;
+}
+/**
+ * Reproduce `applyFrontmatterDescriptionAndTags` (`output/renderers.ts:668-684`):
+ * set description/source/confidence from frontmatter (only when not already set)
+ * and merge frontmatter `tags:` onto the folded tags. Returns nothing — mutates
+ * `out`.
+ */
+function applyFrontmatterDescriptionAndTags(fm, out) {
+    const desc = nonEmptyString(fm.description);
+    if (desc && !out.description) {
+        out.description = desc;
+        out.source = "frontmatter";
+        out.confidence = 0.9;
+    }
+    if (Array.isArray(fm.tags) && fm.tags.length > 0) {
+        const fmTags = fm.tags.filter((t) => typeof t === "string" && t.trim().length > 0);
+        if (fmTags.length > 0) {
+            out.tags = Array.from(new Set([...(out.tags ?? []), ...fmTags]));
+        }
+    }
+}
+/** Collect + finalize a searchHints set the way every contributor does (`Array.from(hints).filter(Boolean)`, assigned only when non-empty). */
+function finalizeHints(out, hints) {
+    if (hints.size > 0)
+        out.searchHints = Array.from(hints).filter(Boolean);
+}
+/**
+ * The metadata fold, keyed on the winning renderer NAME. Returns the fields the
+ * 11 contributors would add to a MINIMAL (name+type) `IndexDocument`. `recognize`
+ * maps the result onto the `IndexDocument`. Reads the live file (index-time, so
+ * disk reads are legitimate — unlike `validate`).
+ */
+export function foldRecognizedMetadata(rendererName, file) {
+    const out = {};
+    switch (rendererName) {
+        // ── toc-metadata (knowledge-md) ──
+        case "knowledge-md": {
+            try {
+                const toc = parseMarkdownToc(file.content());
+                if (toc.headings.length > 0)
+                    out.toc = toc.headings;
+            }
+            catch {
+                // Non-fatal: skip TOC if file can't be read
+            }
+            return out;
+        }
+        // ── lesson-frontmatter-metadata (lesson-md) ──
+        case "lesson-md": {
+            try {
+                const fm = parseFrontmatter(file.content()).data;
+                applyFrontmatterDescriptionAndTags(fm, out);
+                const whenToUse = nonEmptyString(fm.when_to_use);
+                if (whenToUse)
+                    finalizeHints(out, new Set([`when_to_use:${whenToUse}`]));
+            }
+            catch {
+                // Non-fatal: skip metadata extraction on parse error
+            }
+            return out;
+        }
+        // ── memory-frontmatter-metadata (memory-md) ──
+        case "memory-md": {
+            try {
+                const fm = parseFrontmatter(file.content()).data;
+                applyFrontmatterDescriptionAndTags(fm, out);
+                const hints = new Set();
+                const source = nonEmptyString(fm.source);
+                if (source)
+                    hints.add(source);
+                const fmObservedAt = nonEmptyString(fm.observed_at);
+                if (fmObservedAt) {
+                    hints.add(`observed_at:${fmObservedAt}`);
+                }
+                else {
+                    try {
+                        const isoDate = file.stat().mtime.toISOString().slice(0, 10);
+                        hints.add(`observed_at:${isoDate}`);
+                    }
+                    catch {
+                        // Non-fatal: skip mtime fallback on stat error
+                    }
+                }
+                const expires = nonEmptyString(fm.expires);
+                if (expires)
+                    hints.add(`expires:${expires}`);
+                if (fm.subjective === true)
+                    hints.add("subjective");
+                finalizeHints(out, hints);
+            }
+            catch {
+                // Non-fatal: skip metadata extraction on error
+            }
+            return out;
+        }
+        // ── script-comment-metadata (script-source) ──
+        case "script-source": {
+            if (file.ext === ".md")
+                return out;
+            const commentDesc = extractDescriptionFromComments(file.absPath);
+            if (commentDesc && !out.description) {
+                out.description = commentDesc;
+                out.source = "comments";
+                out.confidence = 0.7;
+            }
+            return out;
+        }
+        // ── env-file-metadata (env-file) ──
+        case "env-file": {
+            const { keys } = listKeys(file.absPath);
+            if (keys.length > 0)
+                out.searchHints = keys;
+            out.tags = Array.from(new Set([...(out.tags ?? []), "env", "secrets"]));
+            return out;
+        }
+        // ── secret-file-metadata (secret-file) — tags only, NEVER reads the body ──
+        case "secret-file": {
+            out.tags = Array.from(new Set([...(out.tags ?? []), "secret", "sensitive"]));
+            return out;
+        }
+        // ── task-yaml-metadata (task-yaml) ──
+        case "task-yaml": {
+            out.tags = Array.from(new Set([...(out.tags ?? []), "task", "scheduled"]));
+            try {
+                const doc = parseYaml(file.content());
+                const data = doc && typeof doc === "object" && !Array.isArray(doc) ? doc : {};
+                const hints = new Set();
+                const schedule = nonEmptyString(data.schedule);
+                if (schedule)
+                    hints.add(`schedule:${schedule}`);
+                const workflow = nonEmptyString(data.workflow);
+                if (workflow)
+                    hints.add(`workflow:${workflow}`);
+                const prompt = nonEmptyString(data.prompt);
+                if (prompt)
+                    hints.add(`prompt:${prompt}`);
+                finalizeHints(out, hints);
+            }
+            catch {
+                // Non-fatal: skip metadata extraction on parse error
+            }
+            return out;
+        }
+        // ── session-md-metadata (session-md) ──
+        case "session-md": {
+            try {
+                const fm = parseFrontmatter(file.content()).data;
+                applyFrontmatterDescriptionAndTags(fm, out);
+                out.tags = Array.from(new Set([...(out.tags ?? []), "session"]));
+                const hints = new Set();
+                const harness = nonEmptyString(fm.harness);
+                if (harness)
+                    hints.add(`harness:${harness}`);
+                const project = nonEmptyString(fm.project);
+                if (project)
+                    hints.add(`project:${project}`);
+                const logPath = nonEmptyString(fm.log_path);
+                if (logPath)
+                    hints.add(`log_path:${logPath}`);
+                finalizeHints(out, hints);
+            }
+            catch {
+                // Non-fatal: skip metadata extraction on parse error
+            }
+            return out;
+        }
+        // ── fact-md-metadata (fact-md) ──
+        case "fact-md": {
+            try {
+                const fm = parseFrontmatter(file.content()).data;
+                applyFrontmatterDescriptionAndTags(fm, out);
+                const tags = new Set([...(out.tags ?? []), "fact"]);
+                const hints = new Set();
+                const category = nonEmptyString(fm.category);
+                if (category) {
+                    tags.add(category);
+                    hints.add(`category:${category}`);
+                }
+                if (fm.pinned === true) {
+                    tags.add("pinned");
+                    hints.add("pinned");
+                }
+                out.tags = Array.from(tags).filter(Boolean);
+                finalizeHints(out, hints);
+            }
+            catch {
+                // Non-fatal: skip metadata extraction on parse error
+            }
+            return out;
+        }
+        // ── workflow-document-metadata (workflow-md) ──
+        case "workflow-md": {
+            try {
+                const result = parseWorkflow(file.content(), { path: file.relPath });
+                if (!result.ok)
+                    return out;
+                const doc = result.document;
+                const hints = new Set();
+                hints.add(doc.title);
+                for (const step of doc.steps) {
+                    hints.add(step.title);
+                    hints.add(step.id);
+                    hints.add(step.instructions.text);
+                    for (const criterion of step.completionCriteria ?? [])
+                        hints.add(criterion.text);
+                }
+                out.searchHints = Array.from(hints).filter(Boolean);
+                if (doc.parameters?.length) {
+                    out.parameters = doc.parameters.map((p) => ({
+                        name: p.name,
+                        ...(p.description ? { description: p.description } : {}),
+                    }));
+                }
+            }
+            catch {
+                // See file header: broken workflows drop at drain time, not here.
+            }
+            return out;
+        }
+        // ── workflow-program-metadata (workflow-program-yaml) ──
+        case "workflow-program-yaml": {
+            try {
+                const result = parseWorkflowProgram(file.content(), { path: file.relPath });
+                if (!result.ok)
+                    return out;
+                const program = result.program;
+                const hints = new Set();
+                hints.add(program.name);
+                for (const step of program.steps) {
+                    hints.add(step.id);
+                    if (step.title)
+                        hints.add(step.title);
+                    hints.add(programStepInstructions(step));
+                    for (const criterion of step.gate?.criteria ?? [])
+                        hints.add(criterion);
+                }
+                out.searchHints = Array.from(hints).filter(Boolean);
+                if (!out.description && program.description)
+                    out.description = program.description;
+                const parameters = projectProgramParameters(program);
+                if (parameters?.length)
+                    out.parameters = parameters;
+            }
+            catch {
+                // See file header: broken programs drop at drain time, not here.
+            }
+            return out;
+        }
+        default:
+            // No contributor applies to this renderer (e.g. skill-md/command-md/
+            // agent-md — the static-only mappings carry no metadata contributor).
+            return out;
+    }
+}
+/**
+ * Apply {@link foldRecognizedMetadata}'s output onto a `IndexDocument` with the
+ * SAME precedence the live in-place renderer contributors use (Chunk 5 M-b), so
+ * `entry.applyPreContributorFields → applyFoldedMetadata → applyPostContributorFields`
+ * reproduces `buildEntryFromFile`'s `P1/P2 → contributors → P4` byte-for-byte.
+ *
+ * Precedence, verified against every case in {@link foldRecognizedMetadata}:
+ *  - description/source/confidence travel together and only when the entry has
+ *    no description yet (contributors gate on `!entry.description`); a
+ *    contributor that sets description WITHOUT source/confidence
+ *    (workflow-program-yaml) leaves those untouched — mirrored by the
+ *    `folded.source`/`folded.confidence` guards below;
+ *  - tags UNION into the existing set (order-preserving Set dedup), matching the
+ *    contributors' `Array.from(new Set([...entry.tags, ...added]))`;
+ *  - searchHints / toc / parameters are SET (overwrite), matching the
+ *    contributors' direct assignment.
+ *
+ * The fold computes each field unconditionally from an empty seed; re-gating on
+ * `entry` state here is what recovers the in-place precedence (the fold ≡
+ * contributors-on-a-minimal-seed is pinned by the akm-adapter fold-parity test).
+ */
+export function applyFoldedMetadata(entry, folded) {
+    if (folded.description && !entry.description) {
+        entry.description = folded.description;
+        if (folded.source)
+            entry.source = folded.source;
+        if (folded.confidence !== undefined)
+            entry.confidence = folded.confidence;
+    }
+    if (folded.tags && folded.tags.length > 0) {
+        entry.tags = Array.from(new Set([...(entry.tags ?? []), ...folded.tags]));
+    }
+    // searchHints MERGE (not overwrite): every live contributor seeds its hints
+    // from `new Set(entry.searchHints ?? [])` before adding, so a frontmatter
+    // `searchHints:` set by P2 (applyCuratedFrontmatter) survives and the
+    // contributor's hints append to it. The fold computes only the contributor's
+    // additions (from an empty seed), so unioning them onto the existing set —
+    // existing first, deduped, truthy-filtered — reproduces the live merge exactly.
+    if (folded.searchHints) {
+        entry.searchHints = Array.from(new Set([...(entry.searchHints ?? []), ...folded.searchHints])).filter(Boolean);
+    }
+    if (folded.toc)
+        entry.toc = folded.toc;
+    if (folded.parameters)
+        entry.parameters = folded.parameters;
+}

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -0,0 +1,150 @@
+// 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 `akm-task` adapter — akm 0.9.0 format-family work item (#46).
+ *
+ * A native akm task-YAML bundle (spec §6/§7). A `.yml` file derives
+ * `type: task`; conceptId strips the `.yml` extension. Tasks are AKM-native
+ * YAML, NOT OKF markdown concepts. Recognition does NOT gate on validity — an
+ * invalid task (e.g. two targets) is still RECOGNIZED; the `invalid-task-yaml`
+ * violation surfaces only in `validate`.
+ *
+ * ── validate (spec §6 task validation column) ──
+ *
+ * A task must declare a `schedule`, an `enabled` boolean, and EXACTLY ONE
+ * target (`prompt` XOR `workflow` XOR `command`). The akm adapter's
+ * `TaskLinter` port checks "at least one" target; the native task family here is
+ * STRICTER — declaring two targets is `invalid-task-yaml`. So this adapter owns
+ * a purpose-built one-target check rather than reusing that port.
+ *
+ * Conformance oracle (authored, DO NOT modify): fixture
+ * `tests/fixtures/bundles/akm-task/` + goldens
+ * `tests/fixtures/format-family-goldens/akm-task/{recognition,placement,lint,renderer}.json`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { hashContent } from "./shared.js";
+/** A native task bundle is single-component; its one component is `main`. */
+const COMPONENT_ID = "main";
+/** The task YAML extension (spec §6 task row). */
+const TASK_EXT = ".yml";
+/** The mutually-exclusive task target keys (exactly one required). */
+const TARGET_KEYS = ["prompt", "workflow", "command"];
+/** 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 recognize(c, file) {
+    if (file.ext !== TASK_EXT)
+        return null;
+    const conceptId = toPosix(file.relPath).replace(/\.yml$/i, "");
+    const name = conceptId.split("/").pop() ?? conceptId;
+    const raw = file.content();
+    return {
+        ref: `${c.id}//${conceptId}`,
+        bundle: c.id,
+        component: COMPONENT_ID,
+        conceptId,
+        path: file.absPath,
+        hash: hashContent(raw),
+        adapterId: "akm-task",
+        type: "task",
+        name,
+        content: raw.length > MAX_CONTENT_CHARS ? raw.slice(0, MAX_CONTENT_CHARS) : raw,
+    };
+}
+/** Parse a task YAML into a plain record (tolerant: malformed / non-mapping → {}). */
+function parseTaskYaml(raw) {
+    try {
+        const doc = parseYaml(raw);
+        if (doc && typeof doc === "object" && !Array.isArray(doc))
+            return doc;
+    }
+    catch {
+        // malformed YAML
+    }
+    return {};
+}
+/** The native `invalid-task-yaml` check: schedule + enabled(boolean) + EXACTLY ONE target. */
+function taskDiagnostics(relPath, data) {
+    if (Object.keys(data).length === 0)
+        return [];
+    const problems = [];
+    if (typeof data.schedule !== "string" || data.schedule.trim() === "")
+        problems.push("schedule");
+    if (typeof data.enabled !== "boolean")
+        problems.push("enabled (must be a boolean)");
+    const targets = TARGET_KEYS.filter((k) => k in data && data[k] !== undefined && data[k] !== null);
+    if (targets.length === 0)
+        problems.push("exactly one target (prompt, workflow, or command)");
+    else if (targets.length > 1)
+        problems.push(`exactly one target — declares ${targets.length} (${targets.join(", ")})`);
+    if (problems.length === 0)
+        return [];
+    return [
+        { file: relPath, issue: "invalid-task-yaml", detail: `task field errors: ${problems.join("; ")}`, fixed: false },
+    ];
+}
+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 (path.extname(change.path).toLowerCase() !== TASK_EXT)
+            continue;
+        diagnostics.push(...taskDiagnostics(toPosix(change.path), parseTaskYaml(raw)));
+    }
+    return diagnostics;
+}
+export const akmTaskAdapter = {
+    id: "akm-task",
+    version: "0.9.0",
+    extensions: [TASK_EXT],
+    recognize,
+    validate,
+    /** A task places to `<conceptId>.yml`; an already-suffixed conceptId is idempotent. */
+    placeNew(c, conceptId) {
+        const posix = toPosix(conceptId);
+        return path.join(c.root, /\.yml$/i.test(posix) ? posix : `${posix}.yml`);
+    },
+    /** Tasks live anywhere under the component root. */
+    directoryList() {
+        return ["."];
+    },
+    /**
+     * Install-time probe (§1.2): a root holding a top-level `.yml` file that
+     * parses as a task (a `schedule` key). The task-shape probe keeps it disjoint
+     * from the `akm-workflow` YAML program (`version` + `steps`, no `schedule`)
+     * and from any non-task YAML.
+     */
+    looksLikeRoot(root) {
+        let entries;
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || path.extname(entry.name).toLowerCase() !== TASK_EXT)
+                continue;
+            let raw;
+            try {
+                raw = fs.readFileSync(path.join(root, entry.name), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const data = parseTaskYaml(raw);
+            if (typeof data.schedule === "string" && data.schedule.trim() !== "")
+                return true;
+        }
+        return false;
+    },
+};