akm-cli 0.7.0 → 0.7.2

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

@@ -1,304 +0,0 @@
-/**
- * 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

@@ -1,160 +0,0 @@
-/**
- * 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

@@ -1,111 +0,0 @@
-/**
- * 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();
-    });
-});