akm-cli 0.6.1 → 0.7.0

package/dist/tests/issue-36-repro.test.js

@@ -0,0 +1,304 @@
+/**
+ * Reproduction test for issue #36: Search and index issues
+ *
+ * Problem: Scripts in the stash aren't found via `akm search` with keywords
+ * like "foundry", "provision", "ai" — even though the file
+ * `provision-ai-foundry.sh` exists under scripts/.
+ *
+ * Also covers: sqlite-vec extension not available on macOS arm binary install.
+ */
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { akmSearch } from "../src/commands/search";
+import { saveConfig } from "../src/core/config";
+import { closeDatabase, getAllEntries, openDatabase, searchFts } from "../src/indexer/db";
+import { akmIndex } from "../src/indexer/indexer";
+// ── Temp directory tracking ─────────────────────────────────────────────────
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-issue36-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    createdTmpDirs.push(dir);
+    return dir;
+}
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function writeFile(filePath, content = "") {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+}
+function tmpStash() {
+    const dir = createTmpDir("akm-issue36-stash-");
+    for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+        fs.mkdirSync(path.join(dir, sub), { recursive: true });
+    }
+    return dir;
+}
+async function buildTestIndex(stashDir, files = {}) {
+    for (const [relPath, content] of Object.entries(files)) {
+        const fullPath = path.join(stashDir, relPath);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, content);
+    }
+    process.env.AKM_STASH_DIR = stashDir;
+    saveConfig({ semanticSearchMode: "off" });
+    return akmIndex({ stashDir, full: true });
+}
+// ── Environment isolation ───────────────────────────────────────────────────
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalAkmStashDir = process.env.AKM_STASH_DIR;
+let testCacheDir = "";
+let testConfigDir = "";
+beforeEach(() => {
+    testCacheDir = createTmpDir("akm-issue36-cache-");
+    testConfigDir = createTmpDir("akm-issue36-config-");
+    process.env.XDG_CACHE_HOME = testCacheDir;
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+});
+afterEach(() => {
+    if (originalXdgCacheHome === undefined) {
+        delete process.env.XDG_CACHE_HOME;
+    }
+    else {
+        process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    }
+    if (originalXdgConfigHome === undefined) {
+        delete process.env.XDG_CONFIG_HOME;
+    }
+    else {
+        process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
+    }
+    if (originalAkmStashDir === undefined) {
+        delete process.env.AKM_STASH_DIR;
+    }
+    else {
+        process.env.AKM_STASH_DIR = originalAkmStashDir;
+    }
+    if (testCacheDir) {
+        fs.rmSync(testCacheDir, { recursive: true, force: true });
+        testCacheDir = "";
+    }
+    if (testConfigDir) {
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+        testConfigDir = "";
+    }
+});
+// ── Issue #36 reproduction tests ────────────────────────────────────────────
+describe("Issue #36: Script search and index", () => {
+    test("scripts placed directly in scripts/ dir are indexed", async () => {
+        const stashDir = tmpStash();
+        // Mimics the reported scenario: a script file placed directly in scripts/
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources on Azure\naz group create --name ai-foundry\n");
+        const result = await buildTestIndex(stashDir);
+        expect(result.totalEntries).toBeGreaterThanOrEqual(1);
+        // Verify the script entry was created in the index
+        const db = openDatabase();
+        try {
+            const entries = getAllEntries(db);
+            const scriptEntries = entries.filter((e) => e.entry.type === "script");
+            expect(scriptEntries.length).toBeGreaterThanOrEqual(1);
+            const foundryEntry = scriptEntries.find((e) => e.entry.name.includes("provision") || e.entry.name.includes("foundry"));
+            expect(foundryEntry).toBeDefined();
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+    test("search for 'foundry' finds provision-ai-foundry.sh", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources on Azure\naz group create --name ai-foundry\n");
+        await buildTestIndex(stashDir);
+        const result = await akmSearch({ query: "foundry", source: "local" });
+        const localHits = result.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+        const foundryHit = localHits.find((h) => h.name.includes("foundry") || h.name.includes("provision"));
+        expect(foundryHit).toBeDefined();
+    });
+    test("search for 'provision' finds provision-ai-foundry.sh", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources on Azure\naz group create --name ai-foundry\n");
+        await buildTestIndex(stashDir);
+        const result = await akmSearch({ query: "provision", source: "local" });
+        const localHits = result.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+        const hit = localHits.find((h) => h.name.includes("provision") || h.name.includes("foundry"));
+        expect(hit).toBeDefined();
+    });
+    test("search for 'ai' finds provision-ai-foundry.sh", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources on Azure\naz group create --name ai-foundry\n");
+        await buildTestIndex(stashDir);
+        const result = await akmSearch({ query: "ai", source: "local" });
+        const localHits = result.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+        const hit = localHits.find((h) => h.name.includes("provision") || h.name.includes("foundry") || h.name.includes("ai"));
+        expect(hit).toBeDefined();
+    });
+    test("multiple scripts in scripts/ dir are all indexed", async () => {
+        const stashDir = tmpStash();
+        // Scenario: multiple scripts placed flat in scripts/ (not in subdirectories)
+        const scripts = {
+            "scripts/provision-ai-foundry.sh": "#!/bin/bash\n# Provision AI Foundry\necho provision\n",
+            "scripts/deploy-webapp.sh": "#!/bin/bash\n# Deploy web application\necho deploy\n",
+            "scripts/backup-database.py": "#!/usr/bin/env python3\n# Backup the database\nprint('backup')\n",
+            "scripts/setup-environment.sh": "#!/bin/bash\n# Set up dev environment\necho setup\n",
+            "scripts/run-tests.ts": "// Run all test suites\nconsole.log('test')\n",
+        };
+        const result = await buildTestIndex(stashDir, scripts);
+        // All 5 scripts should be indexed
+        expect(result.totalEntries).toBeGreaterThanOrEqual(5);
+        const db = openDatabase();
+        try {
+            const entries = getAllEntries(db);
+            const scriptEntries = entries.filter((e) => e.entry.type === "script");
+            expect(scriptEntries.length).toBe(5);
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+    test("scripts in subdirectories of scripts/ are indexed", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "azure", "provision-ai-foundry.sh"), "#!/bin/bash\n# Provision AI Foundry\necho provision\n");
+        const result = await buildTestIndex(stashDir);
+        expect(result.totalEntries).toBeGreaterThanOrEqual(1);
+        const searchResult = await akmSearch({ query: "foundry", source: "local" });
+        const localHits = searchResult.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+    });
+});
+describe("Issue #36: buildSearchText includes script content from comments", () => {
+    test("buildSearchText includes description derived from comments for scripts", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources on Azure\naz group create --name ai-foundry\n");
+        await buildTestIndex(stashDir);
+        const db = openDatabase();
+        try {
+            const entries = getAllEntries(db);
+            const scriptEntry = entries.find((e) => e.entry.name.includes("provision"));
+            expect(scriptEntry).toBeDefined();
+            // The search text should include words from filename AND from the description
+            // (which is extracted from the comment header)
+            const searchText = scriptEntry?.searchText;
+            expect(searchText).toContain("provision");
+            expect(searchText).toContain("foundry");
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+});
+describe("Issue #36: FTS5 query sanitization", () => {
+    test("sanitizeFtsQuery keeps short but valid tokens like 'ai'", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "ai-helper.sh"), "#!/bin/bash\n# AI helper script\necho ai\n");
+        await buildTestIndex(stashDir);
+        // Directly test FTS with "ai" query
+        const db = openDatabase();
+        try {
+            const results = searchFts(db, "ai", 10);
+            expect(results.length).toBeGreaterThanOrEqual(1);
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+    test("sanitizeFtsQuery preserves single-character tokens", async () => {
+        const stashDir = tmpStash();
+        writeFile(path.join(stashDir, "scripts", "x-tool.sh"), "#!/bin/bash\n# X tool\necho x\n");
+        await buildTestIndex(stashDir);
+        // Single-char tokens are now passed through to FTS5 so that searches
+        // for short identifiers (e.g., "R", "C", "x") can return results.
+        const db = openDatabase();
+        try {
+            const results = searchFts(db, "x", 10);
+            // "x" appears in the indexed search text, so FTS should find it
+            expect(results.length).toBeGreaterThanOrEqual(1);
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+});
+describe("Issue #36: Stale .stash.json prevents new files from being indexed", () => {
+    test("new files added after initial index are discovered on re-index", async () => {
+        const stashDir = tmpStash();
+        // Step 1: Create initial scripts and index
+        writeFile(path.join(stashDir, "scripts", "deploy-app.sh"), "#!/bin/bash\n# Deploy application\necho deploy\n");
+        writeFile(path.join(stashDir, "scripts", "backup-db.sh"), "#!/bin/bash\n# Backup database\necho backup\n");
+        const result1 = await buildTestIndex(stashDir);
+        expect(result1.totalEntries).toBe(2);
+        // No .stash.json should be auto-generated
+        const stashJsonPath = path.join(stashDir, "scripts", ".stash.json");
+        expect(fs.existsSync(stashJsonPath)).toBe(false);
+        // Step 2: Add a NEW script file after the initial index
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources\naz group create --name ai-foundry\n");
+        // Step 3: Re-index (full rebuild) — all files discovered without .stash.json
+        const result2 = await buildTestIndex(stashDir);
+        expect(result2.totalEntries).toBe(3);
+        // Step 4: Verify the new script is searchable
+        const searchResult = await akmSearch({ query: "foundry", source: "local" });
+        const localHits = searchResult.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+        const foundryHit = localHits.find((h) => h.name.includes("foundry") || h.name.includes("provision"));
+        expect(foundryHit).toBeDefined();
+    });
+    test("incremental index discovers newly added scripts in existing directory", async () => {
+        const stashDir = tmpStash();
+        // Initial index with one script
+        writeFile(path.join(stashDir, "scripts", "existing.sh"), "#!/bin/bash\n# Existing script\necho existing\n");
+        await buildTestIndex(stashDir);
+        // Add new script and run incremental index
+        writeFile(path.join(stashDir, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources\necho provision\n");
+        // Incremental index (not full)
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        const result = await akmIndex({ stashDir });
+        // Both scripts should be in the index
+        expect(result.totalEntries).toBe(2);
+        // Search should find the new script
+        const searchResult = await akmSearch({ query: "provision", source: "local" });
+        const localHits = searchResult.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+    });
+});
+describe("Issue #36: Search path and installed source indexing", () => {
+    test("scripts from search path sources are indexed and searchable", async () => {
+        const workingStash = tmpStash();
+        const searchPathStash = tmpStash();
+        // Put the script in the search path, not the primary stash
+        writeFile(path.join(searchPathStash, "scripts", "provision-ai-foundry.sh"), "#!/usr/bin/env bash\n# Provision AI Foundry resources on Azure\naz group create --name ai-foundry\n");
+        process.env.AKM_STASH_DIR = workingStash;
+        saveConfig({ semanticSearchMode: "off", sources: [{ type: "filesystem", path: searchPathStash }] });
+        await akmIndex({ stashDir: workingStash, full: true });
+        const result = await akmSearch({ query: "foundry", source: "local" });
+        const localHits = result.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+        const hit = localHits.find((h) => h.name.includes("foundry") || h.name.includes("provision"));
+        expect(hit).toBeDefined();
+    });
+    test("empty primary stash + populated search path still indexes all assets", async () => {
+        const workingStash = tmpStash(); // empty
+        const searchPathStash = tmpStash();
+        // Populate search path with various assets
+        writeFile(path.join(searchPathStash, "scripts", "provision-ai-foundry.sh"), "#!/bin/bash\n# Provision AI Foundry\necho foundry\n");
+        writeFile(path.join(searchPathStash, "scripts", "deploy-app.sh"), "#!/bin/bash\n# Deploy application\necho deploy\n");
+        writeFile(path.join(searchPathStash, "scripts", "lint", "lint.sh"), "#!/bin/bash\n# Lint code\necho lint\n");
+        writeFile(path.join(searchPathStash, "commands", "release.md"), "---\ndescription: Release the project\n---\n# Release\n");
+        process.env.AKM_STASH_DIR = workingStash;
+        saveConfig({ semanticSearchMode: "off", sources: [{ type: "filesystem", path: searchPathStash }] });
+        const indexResult = await akmIndex({ stashDir: workingStash, full: true });
+        // All 4 assets from the search path should be indexed
+        expect(indexResult.totalEntries).toBeGreaterThanOrEqual(4);
+        // Verify search finds the script
+        const searchResult = await akmSearch({ query: "foundry", source: "local" });
+        const localHits = searchResult.hits.filter((h) => h.type !== "registry");
+        expect(localHits.length).toBeGreaterThanOrEqual(1);
+    });
+});

package/dist/tests/issues-191-194.test.js

@@ -0,0 +1,160 @@
+/**
+ * Regression tests for GitHub issues 191–194 (filed against 0.6.0-rc1).
+ *
+ * Issue 191 — search misses freshly-added memory
+ *   Status at re-run: NOT REPRODUCING. Test asserts the current correct
+ *   behavior so we don't regress.
+ *
+ * Issue 192 — `akm list` reports no stash after `akm init`
+ *   Status at re-run: NOT REPRODUCING. Test asserts the current correct
+ *   behavior so we don't regress.
+ *
+ * Issue 193 — `database is locked` during normal CLI use
+ *   Status at re-run: NOT REPRODUCING under heavy concurrency, but the
+ *   underlying gap (no `PRAGMA busy_timeout`) is real. Test asserts the
+ *   pragma is set after fix.
+ *
+ * Issue 194 — `workflowEntryId: null` after `workflow create --from`
+ *   Status at re-run: REPRODUCED. Test asserts the field is non-null on
+ *   first start after a fresh import.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CLI = path.join(__dirname, "..", "src", "cli.ts");
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function makeEnv() {
+    const akmHome = makeTempDir("akm-issue-rc1-");
+    return {
+        ...process.env,
+        HOME: akmHome,
+        XDG_CONFIG_HOME: path.join(akmHome, "config"),
+        XDG_CACHE_HOME: path.join(akmHome, "cache"),
+        XDG_DATA_HOME: path.join(akmHome, "data"),
+        AKM_STASH_DIR: path.join(akmHome, "stash"),
+    };
+}
+function runCli(args, env) {
+    return spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 60_000,
+        env,
+    });
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+const ACA_WORKFLOW = `---
+description: Test workflow imported via workflow create --from
+tags:
+  - test
+params:
+  app_name: name of the app
+---
+
+# Workflow: Imported Test Workflow
+
+## Step: First Step
+Step ID: first-step
+
+### Instructions
+Do thing one.
+
+### Completion Criteria
+- Done
+
+## Step: Second Step
+Step ID: second-step
+
+### Instructions
+Do thing two.
+
+### Completion Criteria
+- Done
+`;
+describe("issue #191 — memory search misses freshly-added memory", () => {
+    test("exact-phrase search returns the memory hit at high score", () => {
+        const env = makeEnv();
+        expect(runCli(["init"], env).status).toBe(0);
+        const phrase = "Sandbox memory for rc1 test";
+        const remembered = runCli(["remember", phrase], env);
+        expect(remembered.status).toBe(0);
+        const searched = runCli(["search", phrase, "--format", "json", "--detail", "full"], env);
+        expect(searched.status).toBe(0);
+        const json = JSON.parse(searched.stdout);
+        const memoryHit = json.hits.find((h) => h.type === "memory");
+        expect(memoryHit).toBeDefined();
+        expect(memoryHit?.score ?? 0).toBeGreaterThan(0.5);
+    });
+});
+describe("issue #192 — `akm list` after `akm init`", () => {
+    test("list resolves the stashDir written by init", () => {
+        const env = makeEnv();
+        const initRes = runCli(["init"], env);
+        expect(initRes.status).toBe(0);
+        const initJson = JSON.parse(initRes.stdout);
+        const listRes = runCli(["list", "--format", "json"], env);
+        expect(listRes.status).toBe(0);
+        const listJson = JSON.parse(listRes.stdout);
+        expect(listJson.stashDir).toBe(initJson.stashDir);
+    });
+});
+describe("issue #193 — database is locked under contention", () => {
+    test("openDatabase sets PRAGMA busy_timeout so contended writers wait", async () => {
+        // Use the actual openDatabase helper via dynamic import so we exercise
+        // the same code path the CLI uses.
+        const { openDatabase, closeDatabase } = await import("../src/indexer/db");
+        const tmp = path.join(makeTempDir("akm-issue-193-"), "test.db");
+        const db = openDatabase(tmp);
+        try {
+            const row = db.prepare("PRAGMA busy_timeout").get();
+            expect(row).toBeDefined();
+            // Any non-zero value is acceptable; we just want the pragma set so
+            // SQLITE_BUSY is retried instead of bubbling up to the user.
+            expect(row.timeout ?? 0).toBeGreaterThan(0);
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+    test("WAL journal mode is preserved (regression guard)", async () => {
+        const { openDatabase, closeDatabase } = await import("../src/indexer/db");
+        const tmp = path.join(makeTempDir("akm-issue-193-wal-"), "test.db");
+        const db = openDatabase(tmp);
+        try {
+            const row = db.prepare("PRAGMA journal_mode").get();
+            expect(row.journal_mode?.toLowerCase()).toBe("wal");
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+});
+describe("issue #194 — workflow create --from then start has non-null workflowEntryId", () => {
+    test("imported workflow run carries a real numeric workflowEntryId", () => {
+        const env = makeEnv();
+        expect(runCli(["init"], env).status).toBe(0);
+        const sourceDir = makeTempDir("akm-issue-194-src-");
+        const sourcePath = path.join(sourceDir, "imported.md");
+        fs.writeFileSync(sourcePath, ACA_WORKFLOW, "utf8");
+        const created = runCli(["workflow", "create", "imported", "--from", sourcePath], env);
+        expect(created.status).toBe(0);
+        // No explicit `akm index` — `workflow create --from` should leave the
+        // FTS index in a state that lets `workflow start` resolve a workflowEntryId.
+        const started = runCli(["workflow", "start", "workflow:imported", "--params", '{"app_name":"sandbox-app"}'], env);
+        expect(started.status).toBe(0);
+        const startJson = JSON.parse(started.stdout);
+        expect(startJson.run.id).toBeTruthy();
+        expect(startJson.run.workflowEntryId).not.toBeNull();
+        expect(typeof startJson.run.workflowEntryId).toBe("number");
+    });
+});

package/dist/tests/lesson-lint.test.js

@@ -0,0 +1,111 @@
+/**
+ * Lint contract for the `lesson` asset type (v1 spec §13).
+ *
+ * `description` and `when_to_use` are required, non-empty single-line
+ * strings. The lint module produces structured findings; the strict
+ * variant (`assertLessonValid`) throws a `UsageError` whose message
+ * includes the offending file path and which fields failed.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ASSET_SPECS, TYPE_DIRS } from "../src/core/asset-spec";
+import { UsageError } from "../src/core/errors";
+import { assertLessonValid, lintLessonContent, lintLessonFile } from "../src/core/lesson-lint";
+describe("lesson asset type registration (v1 spec §13)", () => {
+    test("`lesson` is a built-in asset type with stashDir `lessons`", () => {
+        expect(ASSET_SPECS.lesson).toBeDefined();
+        expect(TYPE_DIRS.lesson).toBe("lessons");
+    });
+    test("`lesson` registers a renderer and an action builder", () => {
+        expect(ASSET_SPECS.lesson.rendererName).toBe("lesson-md");
+        expect(typeof ASSET_SPECS.lesson.actionBuilder).toBe("function");
+    });
+    test("`lesson` accepts `.md` files only", () => {
+        expect(ASSET_SPECS.lesson.isRelevantFile("foo.md")).toBe(true);
+        expect(ASSET_SPECS.lesson.isRelevantFile("foo.txt")).toBe(false);
+    });
+});
+describe("lintLessonContent (deterministic, no fs)", () => {
+    test("passes when both required fields are present and non-empty", () => {
+        const raw = [
+            "---",
+            "description: Always check the cache before fetching",
+            "when_to_use: When the upstream service is rate-limited",
+            "---",
+            "",
+            "Body.",
+        ].join("\n");
+        const report = lintLessonContent(raw, "/virtual/lesson.md");
+        expect(report.findings).toEqual([]);
+    });
+    test("flags missing description with the offending file path", () => {
+        const raw = ["---", "when_to_use: when X", "---", "Body."].join("\n");
+        const report = lintLessonContent(raw, "/virtual/no-desc.md");
+        expect(report.findings).toHaveLength(1);
+        expect(report.findings[0].kind).toBe("missing-description");
+        expect(report.findings[0].field).toBe("description");
+        expect(report.findings[0].message).toContain("/virtual/no-desc.md");
+        expect(report.findings[0].message).toContain("description");
+    });
+    test("flags missing when_to_use with the offending file path", () => {
+        const raw = ["---", "description: Lesson", "---", "Body."].join("\n");
+        const report = lintLessonContent(raw, "/virtual/no-when.md");
+        expect(report.findings).toHaveLength(1);
+        expect(report.findings[0].kind).toBe("missing-when_to_use");
+        expect(report.findings[0].field).toBe("when_to_use");
+        expect(report.findings[0].message).toContain("/virtual/no-when.md");
+    });
+    test("flags empty (whitespace-only) description and when_to_use", () => {
+        const raw = ["---", 'description: "   "', 'when_to_use: ""', "---", ""].join("\n");
+        const report = lintLessonContent(raw, "/virtual/empty.md");
+        const kinds = report.findings.map((f) => f.kind).sort();
+        expect(kinds).toEqual(["empty-description", "empty-when_to_use"]);
+    });
+    test("flags both fields when both are missing", () => {
+        const raw = ["---", "tags: [a]", "---", "Body."].join("\n");
+        const report = lintLessonContent(raw, "/virtual/empty.md");
+        expect(report.findings).toHaveLength(2);
+        const kinds = new Set(report.findings.map((f) => f.kind));
+        expect(kinds.has("missing-description")).toBe(true);
+        expect(kinds.has("missing-when_to_use")).toBe(true);
+    });
+});
+describe("assertLessonValid + lintLessonFile (filesystem)", () => {
+    let tmpDir;
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-lesson-lint-"));
+    });
+    afterAll(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    test("lintLessonFile reads the file and reports findings", () => {
+        const file = path.join(tmpDir, "incomplete.md");
+        fs.writeFileSync(file, ["---", "description: hi", "---", "Body."].join("\n"));
+        const report = lintLessonFile(file);
+        expect(report.path).toBe(file);
+        expect(report.findings).toHaveLength(1);
+        expect(report.findings[0].kind).toBe("missing-when_to_use");
+    });
+    test("assertLessonValid throws UsageError including the offending path", () => {
+        const file = path.join(tmpDir, "bad.md");
+        fs.writeFileSync(file, ["---", "tags: [x]", "---", "Body."].join("\n"));
+        expect(() => assertLessonValid(file)).toThrow(UsageError);
+        try {
+            assertLessonValid(file);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(UsageError);
+            const u = err;
+            expect(u.message).toContain(file);
+            expect(u.code).toBe("MISSING_REQUIRED_ARGUMENT");
+            expect(u.hint()).toMatch(/§13/);
+        }
+    });
+    test("assertLessonValid returns silently when the lesson is valid", () => {
+        const file = path.join(tmpDir, "good.md");
+        fs.writeFileSync(file, ["---", "description: Use the cache", "when_to_use: Rate-limited upstream", "---", "Body."].join("\n"));
+        expect(() => assertLessonValid(file)).not.toThrow();
+    });
+});