akm-cli 0.6.0 → 0.7.0-rc1

package/dist/tests/manifest.test.js

@@ -0,0 +1,205 @@
+/**
+ * Tests for the `akm manifest` command (Task E-1: Deferred/Lazy Tool Loading).
+ *
+ * The manifest provides a compact asset listing (name, type, ref, one-line
+ * description) that stays under 500 tokens for 50 assets, giving agents a
+ * cheap way to discover capabilities without loading full content.
+ */
+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 { saveConfig } from "../src/core/config";
+import { akmIndex } from "../src/indexer/indexer";
+import { akmManifest } from "../src/indexer/manifest";
+// ── Temp directory tracking ─────────────────────────────────────────────────
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-manifest-") {
+    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 tmpStash() {
+    const dir = createTmpDir("akm-manifest-stash-");
+    for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+        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" });
+    await 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-manifest-cache-");
+    testConfigDir = createTmpDir("akm-manifest-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;
+    }
+});
+// ── Tests ───────────────────────────────────────────────────────────────────
+describe("akm manifest", () => {
+    test("returns all indexed entries", async () => {
+        const stashDir = tmpStash();
+        await buildTestIndex(stashDir, {
+            "scripts/deploy/deploy.sh": "#!/bin/bash\n# Deploy to production\necho deploy",
+            "scripts/lint/lint.sh": "#!/bin/bash\n# Run linter\necho lint",
+            "skills/code-review/SKILL.md": "---\ndescription: Review code for quality\n---\n# Code Review",
+            "commands/build/BUILD.md": "---\ndescription: Build the project\n---\n# Build",
+            "knowledge/api-docs/api-docs.md": "---\ndescription: API documentation reference\n---\n# API Docs",
+        });
+        const result = await akmManifest({ stashDir });
+        expect(result.entries.length).toBe(5);
+    });
+    test("entries have compact shape (name, type, ref, description only)", async () => {
+        const stashDir = tmpStash();
+        await buildTestIndex(stashDir, {
+            "scripts/deploy/deploy.sh": "#!/bin/bash\n# Deploy to production\necho deploy",
+        });
+        const result = await akmManifest({ stashDir });
+        expect(result.entries.length).toBeGreaterThan(0);
+        const entry = result.entries[0];
+        // Must have the compact fields
+        expect(typeof entry.name).toBe("string");
+        expect(typeof entry.type).toBe("string");
+        expect(typeof entry.ref).toBe("string");
+        // Must NOT have full search hit fields like path, tags, score, action, whyMatched
+        const raw = entry;
+        expect(raw.path).toBeUndefined();
+        expect(raw.tags).toBeUndefined();
+        expect(raw.score).toBeUndefined();
+        expect(raw.action).toBeUndefined();
+        expect(raw.whyMatched).toBeUndefined();
+        expect(raw.searchText).toBeUndefined();
+    });
+    test("filters by type", async () => {
+        const stashDir = tmpStash();
+        await buildTestIndex(stashDir, {
+            "scripts/deploy/deploy.sh": "#!/bin/bash\n# Deploy to production\necho deploy",
+            "scripts/lint/lint.sh": "#!/bin/bash\n# Run linter\necho lint",
+            "skills/code-review/SKILL.md": "---\ndescription: Review code for quality\n---\n# Code Review",
+        });
+        const result = await akmManifest({ stashDir, type: "script" });
+        expect(result.entries.length).toBe(2);
+        for (const entry of result.entries) {
+            expect(entry.type).toBe("script");
+        }
+    });
+    test("descriptions are truncated to ~80 chars", async () => {
+        const stashDir = tmpStash();
+        const longDesc = "This is a very long description that goes well beyond eighty characters and should be truncated with an ellipsis indicator to keep the manifest compact and token-efficient";
+        await buildTestIndex(stashDir, {
+            "skills/verbose/SKILL.md": `---\ndescription: ${longDesc}\n---\n# Verbose Skill`,
+        });
+        const result = await akmManifest({ stashDir });
+        expect(result.entries.length).toBeGreaterThan(0);
+        const entry = result.entries.find((e) => e.name === "verbose");
+        expect(entry).toBeDefined();
+        expect(entry?.description).toBeDefined();
+        expect(entry?.description?.length).toBeLessThanOrEqual(83); // 80 + "..."
+        expect(entry?.description?.endsWith("...")).toBe(true);
+    });
+    test("output is compact (token budget) for 50 entries", async () => {
+        const stashDir = tmpStash();
+        const files = {};
+        // Create 50 script files
+        for (let i = 0; i < 50; i++) {
+            const name = `script-${String(i).padStart(2, "0")}`;
+            files[`scripts/${name}/${name}.sh`] = `#!/bin/bash\n# Task number ${i}\necho ${name}`;
+        }
+        await buildTestIndex(stashDir, files);
+        const result = await akmManifest({ stashDir });
+        expect(result.entries.length).toBe(50);
+        const json = JSON.stringify(result);
+        // Compact: each entry averages ~120 bytes (name, type, ref, short description).
+        // 50 entries ≈ 6000 bytes ≈ 1500 tokens. Cap at ~2500 bytes per token budget
+        // would be too tight for 50 entries, so we allow up to 7500 bytes (~1875 tokens).
+        expect(json.length).toBeLessThan(7500);
+        // Verify no entry carries heavyweight fields
+        for (const entry of result.entries) {
+            const raw = entry;
+            expect(raw.path).toBeUndefined();
+            expect(raw.tags).toBeUndefined();
+            expect(raw.score).toBeUndefined();
+            expect(raw.action).toBeUndefined();
+        }
+    });
+    test("works without an index (fallback to walker)", async () => {
+        const stashDir = tmpStash();
+        // Write files but do NOT run akmIndex
+        const helloDir = path.join(stashDir, "scripts", "hello");
+        fs.mkdirSync(helloDir, { recursive: true });
+        fs.writeFileSync(path.join(helloDir, "hello.sh"), "#!/bin/bash\n# Say hello\necho hello");
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        const result = await akmManifest({ stashDir });
+        // Should find entries via walker fallback even without index
+        expect(result.entries.length).toBeGreaterThanOrEqual(1);
+    });
+    test("response has schemaVersion and entries array", async () => {
+        const stashDir = tmpStash();
+        await buildTestIndex(stashDir, {
+            "scripts/deploy/deploy.sh": "#!/bin/bash\n# Deploy\necho deploy",
+            "scripts/lint/lint.sh": "#!/bin/bash\n# Lint\necho lint",
+            "scripts/test/test.sh": "#!/bin/bash\n# Test\necho test",
+        });
+        const result = await akmManifest({ stashDir });
+        expect(result.schemaVersion).toBe(1);
+        expect(result.entries.length).toBe(3);
+    });
+    test("empty stash returns empty manifest", async () => {
+        const stashDir = tmpStash();
+        process.env.AKM_STASH_DIR = stashDir;
+        saveConfig({ semanticSearchMode: "off" });
+        const result = await akmManifest({ stashDir });
+        expect(result.entries).toEqual([]);
+        expect(result.schemaVersion).toBe(1);
+    });
+    test("ref field follows type:name format", async () => {
+        const stashDir = tmpStash();
+        await buildTestIndex(stashDir, {
+            "skills/code-review/SKILL.md": "---\ndescription: Review code quality\n---\n# Code Review",
+        });
+        const result = await akmManifest({ stashDir });
+        const entry = result.entries.find((e) => e.name === "code-review");
+        expect(entry).toBeDefined();
+        expect(entry?.ref).toMatch(/^skill:code-review$/);
+    });
+});

package/dist/tests/markdown.test.js

@@ -0,0 +1,126 @@
+import { expect, test } from "bun:test";
+import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc, } from "../src/core/markdown";
+const SAMPLE_DOC = `---
+title: Guide
+description: "A test guide"
+---
+# Getting Started
+
+Welcome to the guide.
+
+## Installation
+
+Run \`npm install\` to get started.
+
+## Configuration
+
+Set up your config file.
+
+### Advanced Config
+
+For power users.
+
+# API Reference
+
+The API docs.
+
+## Endpoints
+
+List of endpoints.
+`;
+test("parseMarkdownToc extracts headings with correct levels and line numbers", () => {
+    const toc = parseMarkdownToc(SAMPLE_DOC);
+    expect(toc.headings.length).toBe(6);
+    expect(toc.headings[0]).toEqual({ level: 1, text: "Getting Started", line: 5 });
+    expect(toc.headings[1]).toEqual({ level: 2, text: "Installation", line: 9 });
+    expect(toc.headings[2]).toEqual({ level: 2, text: "Configuration", line: 13 });
+    expect(toc.headings[3]).toEqual({ level: 3, text: "Advanced Config", line: 17 });
+    expect(toc.headings[4]).toEqual({ level: 1, text: "API Reference", line: 21 });
+    expect(toc.headings[5]).toEqual({ level: 2, text: "Endpoints", line: 25 });
+});
+test("parseMarkdownToc skips frontmatter block", () => {
+    const doc = "---\ntitle: Test\n---\n# Heading\n";
+    const toc = parseMarkdownToc(doc);
+    expect(toc.headings.length).toBe(1);
+    expect(toc.headings[0].text).toBe("Heading");
+});
+test("parseMarkdownToc handles document without frontmatter", () => {
+    const doc = "# Title\n\nSome text\n\n## Section\n";
+    const toc = parseMarkdownToc(doc);
+    expect(toc.headings.length).toBe(2);
+    expect(toc.headings[0]).toEqual({ level: 1, text: "Title", line: 1 });
+    expect(toc.headings[1]).toEqual({ level: 2, text: "Section", line: 5 });
+});
+test("parseMarkdownToc handles empty content", () => {
+    const toc = parseMarkdownToc("");
+    expect(toc.headings).toEqual([]);
+    expect(toc.totalLines).toBe(1);
+});
+test("parseMarkdownToc strips trailing hash markers", () => {
+    const doc = "# Heading ##\n## Another ###\n";
+    const toc = parseMarkdownToc(doc);
+    expect(toc.headings[0].text).toBe("Heading");
+    expect(toc.headings[1].text).toBe("Another");
+});
+test("extractSection returns content from heading to next same-or-higher level", () => {
+    const result = extractSection(SAMPLE_DOC, "Installation");
+    expect(result).not.toBeNull();
+    expect(result?.content).toContain("npm install");
+    expect(result?.content).not.toContain("Configuration");
+});
+test("extractSection returns content including sub-headings", () => {
+    const result = extractSection(SAMPLE_DOC, "Configuration");
+    expect(result).not.toBeNull();
+    expect(result?.content).toContain("Advanced Config");
+    expect(result?.content).not.toContain("API Reference");
+});
+test("extractSection is case-insensitive", () => {
+    const result = extractSection(SAMPLE_DOC, "installation");
+    expect(result).not.toBeNull();
+    expect(result?.content).toContain("npm install");
+});
+test("extractSection returns null for non-existent heading", () => {
+    const result = extractSection(SAMPLE_DOC, "Nonexistent");
+    expect(result).toBeNull();
+});
+test("extractSection handles last section (no following heading)", () => {
+    const result = extractSection(SAMPLE_DOC, "Endpoints");
+    expect(result).not.toBeNull();
+    expect(result?.content).toContain("List of endpoints");
+});
+test("extractLineRange returns correct lines (1-based inclusive)", () => {
+    const content = "line1\nline2\nline3\nline4\nline5";
+    expect(extractLineRange(content, 2, 4)).toBe("line2\nline3\nline4");
+});
+test("extractLineRange clamps to valid range", () => {
+    const content = "line1\nline2\nline3";
+    expect(extractLineRange(content, 0, 100)).toBe("line1\nline2\nline3");
+    expect(extractLineRange(content, 2, 2)).toBe("line2");
+});
+test("extractLineRange returns empty when end is before start", () => {
+    const content = "line1\nline2\nline3\nline4\nline5";
+    expect(extractLineRange(content, 5, 2)).toBe("");
+});
+test("extractFrontmatterOnly returns YAML block", () => {
+    const fm = extractFrontmatterOnly(SAMPLE_DOC);
+    expect(fm).not.toBeNull();
+    expect(fm).toContain("title: Guide");
+    expect(fm).toContain('description: "A test guide"');
+});
+test("extractFrontmatterOnly returns null when no frontmatter", () => {
+    expect(extractFrontmatterOnly("# Just a heading\n")).toBeNull();
+});
+test("formatToc produces readable output with line numbers", () => {
+    const toc = parseMarkdownToc(SAMPLE_DOC);
+    const output = formatToc(toc);
+    expect(output).toContain("# Getting Started");
+    expect(output).toContain("## Installation");
+    expect(output).toContain("### Advanced Config");
+    expect(output).toContain("lines total");
+    expect(output).toMatch(/L\s*\d+/);
+});
+test("formatToc handles empty headings", () => {
+    const output = formatToc({ headings: [], totalLines: 5 });
+    expect(output).toContain("no headings found");
+    expect(output).toContain("5 lines total");
+});

package/dist/tests/matchers-unit.test.js

@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher, wikiMatcher, } from "../src/indexer/matchers";
+/**
+ * Build a synthetic FileContext for matcher unit tests. The matchers
+ * (except smartMdMatcher) are pure functions of path-derived fields, so
+ * the lazy `content`/`frontmatter`/`stat` getters can return canned data
+ * — no real filesystem access needed.
+ */
+function ctx(opts) {
+    const segments = opts.relPath.split("/");
+    const fileName = segments[segments.length - 1];
+    const ext = (() => {
+        const dot = fileName.lastIndexOf(".");
+        return dot > 0 ? fileName.slice(dot).toLowerCase() : "";
+    })();
+    const dirSegments = segments.slice(0, -1);
+    const parentDir = dirSegments.length > 0 ? dirSegments[dirSegments.length - 1] : "";
+    const parentDirAbs = `/stash/${dirSegments.join("/")}`.replace(/\/+$/, "");
+    return {
+        absPath: `/stash/${opts.relPath}`,
+        relPath: opts.relPath,
+        ext,
+        fileName,
+        parentDir,
+        parentDirAbs,
+        ancestorDirs: dirSegments,
+        stashRoot: "/stash",
+        content: () => opts.content ?? "",
+        frontmatter: () => opts.frontmatter ?? null,
+        stat: () => {
+            throw new Error("stat() should not be called by these matchers");
+        },
+    };
+}
+// ── extensionMatcher ────────────────────────────────────────────────────────
+describe("extensionMatcher", () => {
+    test("classifies SKILL.md anywhere as skill at high specificity", () => {
+        const result = extensionMatcher(ctx({ relPath: "anywhere/deep/SKILL.md" }));
+        expect(result).toEqual({ type: "skill", specificity: 25, renderer: "skill-md" });
+    });
+    test("does NOT classify SKILL.md under wikis/ as skill", () => {
+        const result = extensionMatcher(ctx({ relPath: "wikis/research/SKILL.md" }));
+        expect(result).toBeNull();
+    });
+    test("classifies known script extensions as script at low specificity", () => {
+        expect(extensionMatcher(ctx({ relPath: "stuff/deploy.sh" }))?.type).toBe("script");
+        expect(extensionMatcher(ctx({ relPath: "stuff/lint.ts" }))?.type).toBe("script");
+        expect(extensionMatcher(ctx({ relPath: "stuff/lint.ts" }))?.specificity).toBe(3);
+    });
+    test("does not handle .md files (smartMdMatcher's job)", () => {
+        expect(extensionMatcher(ctx({ relPath: "stuff/notes.md" }))).toBeNull();
+    });
+    test("returns null for unknown extensions", () => {
+        expect(extensionMatcher(ctx({ relPath: "stuff/data.bin" }))).toBeNull();
+    });
+});
+// ── directoryMatcher ────────────────────────────────────────────────────────
+describe("directoryMatcher", () => {
+    test("scripts/ ancestor classifies a script", () => {
+        const result = directoryMatcher(ctx({ relPath: "scripts/azure/deploy.sh" }));
+        expect(result).toEqual({ type: "script", specificity: 10, renderer: "script-source" });
+    });
+    test("first matching ancestor wins (commands/ before agents/ in path)", () => {
+        const result = directoryMatcher(ctx({ relPath: "commands/agents/foo.md" }));
+        expect(result?.type).toBe("command");
+    });
+    test("agents/foo.md classifies as agent", () => {
+        expect(directoryMatcher(ctx({ relPath: "agents/foo.md" }))?.type).toBe("agent");
+    });
+    test("knowledge/foo.md classifies as knowledge", () => {
+        expect(directoryMatcher(ctx({ relPath: "knowledge/foo.md" }))?.type).toBe("knowledge");
+    });
+    test("workflows/foo.md classifies as workflow", () => {
+        expect(directoryMatcher(ctx({ relPath: "workflows/foo.md" }))?.type).toBe("workflow");
+    });
+    test("memories/foo.md classifies as memory", () => {
+        expect(directoryMatcher(ctx({ relPath: "memories/foo.md" }))?.type).toBe("memory");
+    });
+    test("vaults/.env classifies as vault", () => {
+        expect(directoryMatcher(ctx({ relPath: "vaults/.env" }))?.type).toBe("vault");
+        expect(directoryMatcher(ctx({ relPath: "vaults/staging.env" }))?.type).toBe("vault");
+    });
+    test("unmatched directories return null", () => {
+        expect(directoryMatcher(ctx({ relPath: "random/file.md" }))).toBeNull();
+    });
+});
+// ── parentDirHintMatcher ────────────────────────────────────────────────────
+describe("parentDirHintMatcher", () => {
+    test("immediate parent named scripts/ classifies a script at higher specificity", () => {
+        const result = parentDirHintMatcher(ctx({ relPath: "my-project/scripts/run.sh" }));
+        expect(result).toEqual({ type: "script", specificity: 15, renderer: "script-source" });
+    });
+    test("agents parent dir classifies an .md as agent", () => {
+        expect(parentDirHintMatcher(ctx({ relPath: "anything/agents/foo.md" }))?.type).toBe("agent");
+    });
+    test("returns null when parent doesn't match a type", () => {
+        expect(parentDirHintMatcher(ctx({ relPath: "random/blah.md" }))).toBeNull();
+    });
+});
+// ── smartMdMatcher ─────────────────────────────────────────────────────────
+describe("smartMdMatcher", () => {
+    test("returns null for non-.md files", () => {
+        expect(smartMdMatcher(ctx({ relPath: "stuff/run.sh", content: "" }))).toBeNull();
+    });
+    test("workflow signals classify as workflow at specificity 19", () => {
+        const body = `# Workflow: Deploy
+## Step: Validate
+Step ID: validate
+
+### Instructions
+Do the thing.
+`;
+        const result = smartMdMatcher(ctx({ relPath: "anywhere.md", content: body }));
+        expect(result).toEqual({ type: "workflow", specificity: 19, renderer: "workflow-md" });
+    });
+    test("toolPolicy frontmatter classifies as agent at 20 (highest)", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "body",
+            frontmatter: { toolPolicy: "strict" },
+        }));
+        expect(result).toEqual({ type: "agent", specificity: 20, renderer: "agent-md" });
+    });
+    test("tools frontmatter classifies as agent at 20", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "body",
+            frontmatter: { tools: ["read"] },
+        }));
+        expect(result?.type).toBe("agent");
+        expect(result?.specificity).toBe(20);
+    });
+    test("agent-named frontmatter (OpenCode command) classifies as command at 18", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "body",
+            frontmatter: { agent: "review" },
+        }));
+        expect(result).toEqual({ type: "command", specificity: 18, renderer: "command-md" });
+    });
+    test("$ARGUMENTS placeholder classifies as command at 18", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "Run with $ARGUMENTS",
+        }));
+        expect(result).toEqual({ type: "command", specificity: 18, renderer: "command-md" });
+    });
+    test("$1 placeholder classifies as command at 18", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "First arg is $1",
+        }));
+        expect(result?.type).toBe("command");
+    });
+    test("model frontmatter alone is a weak agent signal (specificity 8)", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "body",
+            frontmatter: { model: "gpt-4o" },
+        }));
+        expect(result).toEqual({ type: "agent", specificity: 8, renderer: "agent-md" });
+    });
+    test("plain .md falls back to knowledge at specificity 5", () => {
+        const result = smartMdMatcher(ctx({
+            relPath: "blah.md",
+            content: "Just some prose with no signals.",
+        }));
+        expect(result).toEqual({ type: "knowledge", specificity: 5, renderer: "knowledge-md" });
+    });
+});
+// ── wikiMatcher ─────────────────────────────────────────────────────────────
+describe("wikiMatcher", () => {
+    test("any .md under wikis/<name>/ classifies as wiki at specificity 20", () => {
+        const result = wikiMatcher(ctx({ relPath: "wikis/research/page.md" }));
+        expect(result).toEqual({ type: "wiki", specificity: 20, renderer: "wiki-md" });
+    });
+    test("nested wiki pages also classify as wiki", () => {
+        expect(wikiMatcher(ctx({ relPath: "wikis/research/sub/deep/page.md" }))?.type).toBe("wiki");
+    });
+    test("non-.md files are ignored", () => {
+        expect(wikiMatcher(ctx({ relPath: "wikis/research/page.txt" }))).toBeNull();
+    });
+    test("a stray .md at bare wikis/ root is NOT a wiki page", () => {
+        expect(wikiMatcher(ctx({ relPath: "wikis/orphan.md" }))).toBeNull();
+    });
+    test("paths without wikis/ are ignored", () => {
+        expect(wikiMatcher(ctx({ relPath: "knowledge/page.md" }))).toBeNull();
+    });
+});