akm-cli 0.6.0 → 0.7.0-rc1

package/dist/tests/wave2-cluster-e.test.js

@@ -0,0 +1,179 @@
+/**
+ * Wave-2 QA fixes tests — Cluster E (output shapes, remember, info, vault, registry brief).
+ *
+ * #2  — `akm info` populates sourceProviders from stashDir when sources[] is empty.
+ * #7  — `akm show` JSON shape always includes path + editable.
+ * #20 — `akm remember --description` persisted in frontmatter.
+ * #28 — `registry search --detail brief` projects name + installRef + score.
+ * #35 — Vault list returns entries:[{key,comment}] instead of parallel arrays.
+ */
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildMemoryFrontmatter } from "../src/commands/remember";
+import { listEntries } from "../src/commands/vault";
+import { shapeSearchHit, shapeShowOutput } from "../src/output/shapes";
+// ── #7: show shape includes path + editable ───────────────────────────────────
+describe("shapeShowOutput — path + editable always included (#7)", () => {
+    const showResult = {
+        type: "skill",
+        name: "deploy",
+        origin: null,
+        action: "akm show skill:deploy",
+        description: "Deploy script",
+        path: "/home/user/stash/skills/deploy/SKILL.md",
+        editable: true,
+        editHint: "vim /home/user/stash/skills/deploy/SKILL.md",
+        content: "# Deploy\nRun deploy.",
+    };
+    test("default detail includes path and editable", () => {
+        const out = shapeShowOutput(showResult, "normal");
+        expect(out).toHaveProperty("path");
+        expect(out).toHaveProperty("editable");
+        expect(out.path).toBe("/home/user/stash/skills/deploy/SKILL.md");
+        expect(out.editable).toBe(true);
+    });
+    test("brief detail also includes path and editable", () => {
+        const out = shapeShowOutput(showResult, "brief");
+        expect(out).toHaveProperty("path");
+        expect(out).toHaveProperty("editable");
+    });
+    test("full detail includes path, editable, and editHint", () => {
+        const out = shapeShowOutput(showResult, "full");
+        expect(out).toHaveProperty("path");
+        expect(out).toHaveProperty("editable");
+        expect(out).toHaveProperty("editHint");
+    });
+    test("agent mode does NOT expose path (security: keep in non-agent shape only)", () => {
+        const out = shapeShowOutput(showResult, "normal", /* forAgent */ true);
+        // Agent mode picks a minimal subset; path is not in that subset
+        expect(out.editable).toBeUndefined();
+        expect(out.path).toBeUndefined();
+    });
+});
+// ── #28: registry brief projects name + installRef + score ───────────────────
+describe("shapeSearchHit — registry brief projects name + score (#28)", () => {
+    // v1 spec §4.2: registry hits no longer carry the legacy `curated` boolean.
+    const registryHit = {
+        type: "registry",
+        title: "deploy-stash",
+        name: "deploy-stash",
+        installRef: "npm:@myorg/deploy-stash",
+        description: "A deployment stash",
+        action: "akm add npm:@myorg/deploy-stash -> then search again",
+        score: 0.85,
+    };
+    test("brief includes name, installRef, score", () => {
+        const out = shapeSearchHit(registryHit, "brief");
+        expect(out.name).toBeTruthy();
+        expect(out.score).toBe(0.85);
+        // installRef should be present when it exists
+        expect(out.installRef).toBe("npm:@myorg/deploy-stash");
+    });
+    test("brief with only title (no name field): normalises title → name", () => {
+        const hit = {
+            type: "registry",
+            title: "some-kit",
+            installRef: "github:org/some-kit",
+            score: 0.5,
+        };
+        const out = shapeSearchHit(hit, "brief");
+        expect(out.name).toBe("some-kit");
+    });
+    test("brief does NOT return empty object for registry hits", () => {
+        const out = shapeSearchHit(registryHit, "brief");
+        expect(Object.keys(out).length).toBeGreaterThan(0);
+    });
+    test("normal mode keeps description, action, installRef, score (curated removed in v1)", () => {
+        const out = shapeSearchHit(registryHit, "normal");
+        expect(out.description).toBeDefined();
+        expect(out.installRef).toBeDefined();
+        expect(out.score).toBe(0.85);
+        expect(out).not.toHaveProperty("curated");
+    });
+});
+// ── #20: --description persisted in frontmatter ──────────────────────────────
+describe("buildMemoryFrontmatter — description field (#20)", () => {
+    test("description is included when present", () => {
+        const fm = buildMemoryFrontmatter({
+            description: "Short description of this memory",
+            tags: ["test"],
+        });
+        expect(fm).toContain("description:");
+        expect(fm).toContain("Short description of this memory");
+    });
+    test("description is omitted when not present", () => {
+        const fm = buildMemoryFrontmatter({ tags: ["test"] });
+        expect(fm).not.toContain("description:");
+    });
+    test("description is omitted when empty", () => {
+        const fm = buildMemoryFrontmatter({ description: "", tags: ["test"] });
+        expect(fm).not.toContain("description:");
+    });
+    test("description is omitted when whitespace only", () => {
+        const fm = buildMemoryFrontmatter({ description: "   ", tags: ["test"] });
+        expect(fm).not.toContain("description:");
+    });
+    test("description with special chars is safely serialised", () => {
+        const fm = buildMemoryFrontmatter({
+            description: 'value with: "quotes" and \nnewlines',
+            tags: ["test"],
+        });
+        expect(fm).toContain("description:");
+        // Should be quoted to handle special chars
+    });
+});
+// ── #35: vault list returns entries:[{key,comment}] ──────────────────────────
+describe("vault listEntries — entries shape (#35)", () => {
+    function makeTmpVault(content) {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-vault-test-"));
+        const vaultPath = path.join(tmpDir, "test.env");
+        fs.writeFileSync(vaultPath, content);
+        return vaultPath;
+    }
+    test("returns empty array for nonexistent vault", () => {
+        const result = listEntries("/tmp/nonexistent-vault-file-xyz.env");
+        expect(result).toEqual([]);
+    });
+    test("returns keys without comments for uncommented vault", () => {
+        const vaultPath = makeTmpVault("DB_URL=postgres://localhost\nAPI_KEY=secret\n");
+        const entries = listEntries(vaultPath);
+        expect(entries.map((e) => e.key)).toEqual(["DB_URL", "API_KEY"]);
+        expect(entries.every((e) => e.comment === undefined)).toBe(true);
+    });
+    test("associates comment with the following key", () => {
+        const vaultPath = makeTmpVault("# Database connection URL\nDB_URL=postgres://localhost\n");
+        const entries = listEntries(vaultPath);
+        expect(entries).toHaveLength(1);
+        expect(entries[0].key).toBe("DB_URL");
+        expect(entries[0].comment).toBe("Database connection URL");
+    });
+    test("returns {key, comment} shape", () => {
+        const vaultPath = makeTmpVault("# API key\nAPI_KEY=secret\n# DB\nDB_URL=pg://localhost\n");
+        const entries = listEntries(vaultPath);
+        expect(entries).toHaveLength(2);
+        expect(entries[0]).toMatchObject({ key: "API_KEY", comment: "API key" });
+        expect(entries[1]).toMatchObject({ key: "DB_URL", comment: "DB" });
+    });
+    test("duplicate keys: only first occurrence kept", () => {
+        const vaultPath = makeTmpVault("DB_URL=first\nDB_URL=second\n");
+        const entries = listEntries(vaultPath);
+        expect(entries.map((e) => e.key)).toEqual(["DB_URL"]);
+    });
+    test("entry has no comment field when there's no preceding comment", () => {
+        const vaultPath = makeTmpVault("API_KEY=abc\n");
+        const entries = listEntries(vaultPath);
+        expect(entries[0].comment).toBeUndefined();
+    });
+});
+// ── #2: info sourceProviders from stashDir ────────────────────────────────────
+describe("assembleInfo — sourceProviders populated from stashDir (#2)", () => {
+    test("sourceProviders includes stashDir when sources[] is empty", () => {
+        const { assembleInfo } = require("../src/commands/info");
+        // We can't easily override loadConfig, but we can verify the function shape.
+        // The actual integration is tested via the info-command.test.ts suite.
+        // This is a unit-level smoke test that the function signature is stable.
+        expect(typeof assembleInfo).toBe("function");
+    });
+});

package/dist/tests/wiki-qa-fixes.test.js

@@ -0,0 +1,270 @@
+/**
+ * Regression tests for the 0.5.0 QA wiki fixes.
+ *
+ * Covers:
+ *   1. searchInWiki excludes schema.md, index.md, and log.md.
+ *   2. stashRaw with explicitSlug: true throws UsageError on collision;
+ *      with explicitSlug: false auto-increments.
+ *   3. lintWiki emits broken-source findings for dangling sources: refs.
+ *   4. validateWikiName error message includes "lowercase".
+ *   5. wiki search on a nonexistent wiki throws NotFoundError.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { UsageError } from "../src/core/errors";
+import { createWiki, INDEX_MD, LOG_MD, lintWiki, SCHEMA_MD, searchInWiki, stashRaw, validateWikiName, WIKIS_SUBDIR, } from "../src/wiki/wiki";
+const tempDirs = [];
+function makeStash(prefix = "akm-wiki-qa-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function writePage(wikiDir, relPath, body) {
+    const abs = path.join(wikiDir, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, body, "utf8");
+    return abs;
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+/**
+ * Set up an isolated stash env for searchInWiki tests.
+ * Returns the stash dir and a cleanup function.
+ */
+function withIsolatedStash() {
+    const stash = makeStash();
+    const origStash = process.env.AKM_STASH_DIR;
+    const origHome = process.env.XDG_CONFIG_HOME;
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "akm-wiki-qa-home-"));
+    tempDirs.push(tmpHome);
+    process.env.AKM_STASH_DIR = stash;
+    process.env.XDG_CONFIG_HOME = tmpHome;
+    return {
+        stash,
+        cleanup() {
+            if (origStash === undefined)
+                delete process.env.AKM_STASH_DIR;
+            else
+                process.env.AKM_STASH_DIR = origStash;
+            if (origHome === undefined)
+                delete process.env.XDG_CONFIG_HOME;
+            else
+                process.env.XDG_CONFIG_HOME = origHome;
+        },
+    };
+}
+// ── 1. searchInWiki excludes infrastructure files ───────────────────────────
+describe("searchInWiki — infrastructure file exclusion", () => {
+    test("excludes schema.md, index.md, log.md from results", async () => {
+        const { stash, cleanup } = withIsolatedStash();
+        try {
+            createWiki(stash, "research");
+            const wikiDir = path.join(stash, WIKIS_SUBDIR, "research");
+            writePage(wikiDir, "ml-basics.md", "---\ndescription: Machine learning basics\n---\n# ML Basics\nContent.\n");
+            const response = await searchInWiki({
+                stashDir: stash,
+                wikiName: "research",
+                query: "machine learning",
+            });
+            // All returned hits must not be special infrastructure files
+            for (const hit of response.hits) {
+                if (hit.type === "registry")
+                    continue;
+                const stashHit = hit;
+                if (!stashHit.path)
+                    continue;
+                const basename = path.basename(stashHit.path);
+                expect([SCHEMA_MD, INDEX_MD, LOG_MD]).not.toContain(basename);
+            }
+        }
+        finally {
+            cleanup();
+        }
+    });
+    test("does not exclude real page files", async () => {
+        const { stash, cleanup } = withIsolatedStash();
+        try {
+            createWiki(stash, "research");
+            const wikiDir = path.join(stash, WIKIS_SUBDIR, "research");
+            writePage(wikiDir, "valid-page.md", "---\ndescription: A real page\n---\n# Valid\n");
+            // No assertion about hit presence (index may be absent); just no throw.
+            const response = await searchInWiki({
+                stashDir: stash,
+                wikiName: "research",
+                query: "real page",
+            });
+            expect(response).toBeDefined();
+            expect(Array.isArray(response.hits)).toBe(true);
+        }
+        finally {
+            cleanup();
+        }
+    });
+});
+// ── 2. stashRaw explicitSlug collision behaviour ─────────────────────────────
+describe("stashRaw — explicitSlug", () => {
+    test("explicitSlug: true throws UsageError on collision", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        // First write succeeds
+        stashRaw({
+            stashDir: stash,
+            wikiName: "research",
+            content: "first",
+            preferredName: "mysource",
+            explicitSlug: true,
+        });
+        // Second write with same slug and explicitSlug: true must throw
+        expect(() => stashRaw({
+            stashDir: stash,
+            wikiName: "research",
+            content: "second",
+            preferredName: "mysource",
+            explicitSlug: true,
+        })).toThrow(UsageError);
+    });
+    test("UsageError message mentions the slug, 'already exists', and '--as'", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        stashRaw({ stashDir: stash, wikiName: "research", content: "first", preferredName: "myslug", explicitSlug: true });
+        let caught;
+        try {
+            stashRaw({
+                stashDir: stash,
+                wikiName: "research",
+                content: "second",
+                preferredName: "myslug",
+                explicitSlug: true,
+            });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(UsageError);
+        expect(caught?.message).toContain("myslug");
+        expect(caught?.message).toContain("already exists");
+        expect(caught?.message).toContain("--as");
+    });
+    test("explicitSlug: false auto-increments on collision (existing behaviour)", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        const r1 = stashRaw({
+            stashDir: stash,
+            wikiName: "research",
+            content: "a",
+            preferredName: "dup",
+            explicitSlug: false,
+        });
+        const r2 = stashRaw({
+            stashDir: stash,
+            wikiName: "research",
+            content: "b",
+            preferredName: "dup",
+            explicitSlug: false,
+        });
+        expect(r1.slug).toBe("dup");
+        expect(r2.slug).toBe("dup-1");
+    });
+    test("explicitSlug: undefined auto-increments (backward-compat)", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        const r1 = stashRaw({ stashDir: stash, wikiName: "research", content: "a", preferredName: "nodups" });
+        const r2 = stashRaw({ stashDir: stash, wikiName: "research", content: "b", preferredName: "nodups" });
+        expect(r1.slug).toBe("nodups");
+        expect(r2.slug).toBe("nodups-1");
+    });
+    test("explicitSlug: true on a new slug does NOT throw", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        expect(() => stashRaw({ stashDir: stash, wikiName: "research", content: "x", preferredName: "brand-new", explicitSlug: true })).not.toThrow();
+    });
+});
+// ── 3. lintWiki broken-source findings ──────────────────────────────────────
+describe("lintWiki — broken-source", () => {
+    test("emits broken-source finding when sources: references a missing raw file", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        const wikiDir = path.join(stash, WIKIS_SUBDIR, "research");
+        // Page that references a raw file that doesn't exist
+        writePage(wikiDir, "orphaned-page.md", "---\ndescription: Page with dangling source ref\nxrefs:\n  - wiki:research/orphaned-page\nsources:\n  - raw/ghost-paper\n---\n# Orphaned\n");
+        const report = lintWiki(stash, "research");
+        const brokenSrc = report.findings.filter((f) => f.kind === "broken-source");
+        expect(brokenSrc.length).toBeGreaterThanOrEqual(1);
+        expect(brokenSrc[0].refs[0]).toBe("wiki:research/orphaned-page");
+        expect(brokenSrc[0].message).toContain("ghost-paper");
+    });
+    test("does NOT emit broken-source when raw file exists", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        const wikiDir = path.join(stash, WIKIS_SUBDIR, "research");
+        // Stash the raw file first
+        stashRaw({ stashDir: stash, wikiName: "research", content: "raw content", preferredName: "real-paper" });
+        // Page citing the existing raw file — must NOT trigger broken-source
+        writePage(wikiDir, "good-page.md", "---\ndescription: Page with valid source ref\nxrefs:\n  - wiki:research/good-page\nsources:\n  - raw/real-paper\n---\n# Good\n");
+        const report = lintWiki(stash, "research");
+        const brokenSrc = report.findings.filter((f) => f.kind === "broken-source");
+        expect(brokenSrc.length).toBe(0);
+    });
+    test("accepts both 'raw/slug' and 'raw/slug.md' source forms", () => {
+        const stash = makeStash();
+        createWiki(stash, "research");
+        const wikiDir = path.join(stash, WIKIS_SUBDIR, "research");
+        stashRaw({ stashDir: stash, wikiName: "research", content: "raw", preferredName: "existing-slug" });
+        // Cite with .md extension — should not break
+        writePage(wikiDir, "page-with-ext.md", "---\ndescription: Cites with .md extension\nxrefs:\n  - wiki:research/page-with-ext\nsources:\n  - raw/existing-slug.md\n---\n# Ext\n");
+        const report = lintWiki(stash, "research");
+        const brokenSrc = report.findings.filter((f) => f.kind === "broken-source");
+        expect(brokenSrc.length).toBe(0);
+    });
+});
+// ── 4. validateWikiName error message includes "lowercase" ───────────────────
+describe("validateWikiName — error message", () => {
+    test("error message says 'lowercase' when name has uppercase letters", () => {
+        let caught;
+        try {
+            validateWikiName("MyWiki");
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(UsageError);
+        expect(caught?.message.toLowerCase()).toContain("lowercase");
+    });
+    test("error message says 'lowercase' for leading-hyphen names", () => {
+        let caught;
+        try {
+            validateWikiName("-bad");
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(UsageError);
+        expect(caught?.message.toLowerCase()).toContain("lowercase");
+    });
+});
+// ── 5. searchInWiki on nonexistent wiki throws NotFoundError ─────────────────
+describe("searchInWiki — nonexistent wiki", () => {
+    test("throws (via validateWikiName) for invalid wiki names", () => {
+        const stash = makeStash();
+        // An uppercase name fails validateWikiName, which is called by searchInWiki
+        expect(() => searchInWiki({ stashDir: stash, wikiName: "BadName", query: "test" })).toThrow();
+    });
+    test("valid-but-missing wiki name returns zero hits (path-filter drops everything)", async () => {
+        // searchInWiki itself does not throw for a valid-but-absent wiki dir — it
+        // just returns zero hits because the path-filter drops all non-wiki-dir
+        // paths. The CLI layer adds the explicit existence check.
+        const { stash, cleanup } = withIsolatedStash();
+        try {
+            const response = await searchInWiki({ stashDir: stash, wikiName: "nonexistent", query: "test" });
+            expect(response.hits).toEqual([]);
+        }
+        finally {
+            cleanup();
+        }
+    });
+});