akm-cli 0.7.0 → 0.7.2

package/dist/tests/walker.test.js

@@ -1,252 +0,0 @@
-import { afterAll, 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";
-import { walkStash, walkStashFlat } from "../src/indexer/walker";
-const createdTmpDirs = [];
-function tmpDir() {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-walker-"));
-    createdTmpDirs.push(dir);
-    return dir;
-}
-afterAll(() => {
-    for (const dir of createdTmpDirs) {
-        fs.rmSync(dir, { recursive: true, force: true });
-    }
-});
-function writeFile(filePath, content = "") {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, content);
-}
-describe("walkStash", () => {
-    test("returns empty array for non-existent directory", () => {
-        expect(walkStash("/nonexistent/path", "script")).toEqual([]);
-    });
-    test("returns empty array for empty directory", () => {
-        const dir = tmpDir();
-        expect(walkStash(dir, "script")).toEqual([]);
-    });
-    test("groups script files by parent directory", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "docker", "build.sh"), "echo build\n");
-        writeFile(path.join(root, "docker", "compose.sh"), "echo compose\n");
-        writeFile(path.join(root, "git", "diff.ts"), "console.log('diff')\n");
-        const groups = walkStash(root, "script");
-        expect(groups).toHaveLength(2);
-        const dockerGroup = groups.find((g) => g.dirPath.endsWith("docker"));
-        const gitGroup = groups.find((g) => g.dirPath.endsWith("git"));
-        expect(dockerGroup).toBeDefined();
-        expect(dockerGroup?.files).toHaveLength(2);
-        expect(gitGroup).toBeDefined();
-        expect(gitGroup?.files).toHaveLength(1);
-    });
-    test("skips .stash.json files", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "group", "run.sh"), "echo hi\n");
-        writeFile(path.join(root, "group", ".stash.json"), '{"entries":[]}');
-        const groups = walkStash(root, "script");
-        expect(groups).toHaveLength(1);
-        const files = groups[0].files;
-        expect(files).toHaveLength(1);
-        expect(files[0]).toContain("run.sh");
-    });
-    test("only includes relevant files for script type", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "group", "run.sh"), "echo hi\n");
-        writeFile(path.join(root, "group", "README.md"), "ignore\n");
-        writeFile(path.join(root, "group", "data.json"), "{}");
-        const groups = walkStash(root, "script");
-        expect(groups).toHaveLength(1);
-        expect(groups[0].files).toHaveLength(1);
-    });
-    test("only includes SKILL.md for skill type", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "review", "SKILL.md"), "# Review\n");
-        writeFile(path.join(root, "review", "README.md"), "ignore\n");
-        writeFile(path.join(root, "refactor", "SKILL.md"), "# Refactor\n");
-        const groups = walkStash(root, "skill");
-        expect(groups).toHaveLength(2);
-        for (const group of groups) {
-            expect(group.files).toHaveLength(1);
-            expect(group.files[0]).toContain("SKILL.md");
-        }
-    });
-    test("only includes .md for command type", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "release.md"), "release\n");
-        writeFile(path.join(root, "setup.sh"), "echo setup\n");
-        const groups = walkStash(root, "command");
-        expect(groups).toHaveLength(1);
-        expect(groups[0].files).toHaveLength(1);
-        expect(groups[0].files[0]).toContain("release.md");
-    });
-    test("walks nested directories", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "a", "b", "c", "deep.sh"), "echo deep\n");
-        const groups = walkStash(root, "script");
-        expect(groups).toHaveLength(1);
-        expect(groups[0].files[0]).toContain("deep.sh");
-    });
-    test("includes files from root level", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "deploy.sh"), "echo deploy\n");
-        const groups = walkStash(root, "script");
-        expect(groups).toHaveLength(1);
-        expect(groups[0].dirPath).toBe(root);
-    });
-    test("handles knowledge type (.md files)", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "guide.md"), "# Guide\n");
-        writeFile(path.join(root, "reference.md"), "# Reference\n");
-        writeFile(path.join(root, "data.json"), "{}");
-        const groups = walkStash(root, "knowledge");
-        expect(groups).toHaveLength(1);
-        expect(groups[0].files).toHaveLength(2);
-    });
-});
-describe("walkStashFlat", () => {
-    test("returns FileContext objects (not plain paths)", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "scripts", "build.sh"), "echo build\n");
-        const results = walkStashFlat(root);
-        expect(results).toHaveLength(1);
-        const ctx = results[0];
-        expect(typeof ctx.absPath).toBe("string");
-        expect(typeof ctx.relPath).toBe("string");
-        expect(typeof ctx.ext).toBe("string");
-        expect(typeof ctx.fileName).toBe("string");
-        expect(typeof ctx.stashRoot).toBe("string");
-        expect(typeof ctx.content).toBe("function");
-        expect(typeof ctx.frontmatter).toBe("function");
-        expect(typeof ctx.stat).toBe("function");
-    });
-    test("walks across all asset type directories", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "scripts", "build.sh"), "echo build\n");
-        writeFile(path.join(root, "agents", "helper.md"), "# Helper\n");
-        writeFile(path.join(root, "knowledge", "guide.md"), "# Guide\n");
-        writeFile(path.join(root, "scripts", "deploy.py"), "print('deploy')\n");
-        const results = walkStashFlat(root);
-        expect(results).toHaveLength(4);
-        const fileNames = results.map((r) => r.fileName).sort();
-        expect(fileNames).toEqual(["build.sh", "deploy.py", "guide.md", "helper.md"]);
-    });
-    test("does not filter by asset type", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "data.json"), '{"key":"value"}');
-        writeFile(path.join(root, "script.py"), "print('hi')\n");
-        const results = walkStashFlat(root);
-        expect(results).toHaveLength(2);
-        const fileNames = results.map((r) => r.fileName).sort();
-        expect(fileNames).toEqual(["data.json", "script.py"]);
-    });
-    test("skips directories starting with dot", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, ".hidden", "file.txt"), "secret\n");
-        writeFile(path.join(root, "visible", "file.txt"), "public\n");
-        const results = walkStashFlat(root);
-        expect(results).toHaveLength(1);
-        expect(results[0].fileName).toBe("file.txt");
-        expect(results[0].absPath).toContain("visible");
-    });
-    test("preserves stashRoot on all FileContext results", () => {
-        const root = tmpDir();
-        writeFile(path.join(root, "a", "one.sh"), "echo one\n");
-        writeFile(path.join(root, "b", "two.md"), "# Two\n");
-        writeFile(path.join(root, "c", "three.py"), "print(3)\n");
-        const results = walkStashFlat(root);
-        expect(results).toHaveLength(3);
-        for (const ctx of results) {
-            expect(ctx.stashRoot).toBe(root);
-        }
-    });
-    test("git walk stays scoped to the stash root subtree", () => {
-        const repoRoot = tmpDir();
-        const stashRoot = path.join(repoRoot, "stash");
-        writeFile(path.join(repoRoot, "outside.txt"), "outside\n");
-        writeFile(path.join(stashRoot, "scripts", "build.sh"), "echo build\n");
-        const gitInit = spawnSync("git", ["init"], { cwd: repoRoot, encoding: "utf8" });
-        expect(gitInit.status).toBe(0);
-        const results = walkStashFlat(stashRoot);
-        expect(results).toHaveLength(1);
-        expect(results[0]?.relPath).toBe("scripts/build.sh");
-        expect(results[0]?.absPath.startsWith(stashRoot)).toBe(true);
-    });
-});
-// ── T6: isInsideGitRepo in nested repo ───────────────────────────────────────
-//
-// Gap: isInsideGitRepo() walks up the directory tree looking for .git. In a
-// nested git repo (e.g. a stash directory inside a monorepo worktree), it
-// should find the nearest .git — but creating nested repos in CI is fragile
-// and platform-dependent, so this gap is intentionally left untested here.
-// If regression is suspected, test manually by creating a nested git init
-// inside an existing repo and verifying walkStashFlat still uses the git walker.
-// ── R4.3: symlink escape ─────────────────────────────────────────────────────
-//
-// walkStashFlat (manual fallback) must skip symlinks that point outside the
-// stash root so that malicious or accidental symlinks cannot leak files from
-// the host filesystem into search results.
-describe("walkStashFlat — symlink escape", () => {
-    // Track extra files created outside tmpDir() so we can clean them up.
-    const extraFiles = [];
-    afterEach(() => {
-        for (const f of extraFiles.splice(0)) {
-            try {
-                fs.rmSync(f, { force: true });
-            }
-            catch {
-                // best-effort
-            }
-        }
-    });
-    test("symlink pointing outside stash root is NOT included in results", () => {
-        // Create a stash root that is NOT inside a git repo so the manual walker
-        // is used (the git walker relies on git ls-files which won't list a
-        // symlink that targets an untracked file outside the repo).
-        const stashRoot = tmpDir();
-        const skillsDir = path.join(stashRoot, "skills");
-        fs.mkdirSync(skillsDir, { recursive: true });
-        // Create a real file OUTSIDE the stash root
-        const outsideFile = path.join(os.tmpdir(), `akm-symlink-target-${process.pid}-${Date.now()}.md`);
-        fs.writeFileSync(outsideFile, "# Secret content outside stash\n");
-        extraFiles.push(outsideFile);
-        // Create a symlink inside the stash that points to the outside file
-        const symlinkPath = path.join(skillsDir, "escaped.md");
-        fs.symlinkSync(outsideFile, symlinkPath);
-        // Also create a legitimate file so we can confirm the walker still works
-        writeFile(path.join(skillsDir, "legitimate.md"), "# Legit\n");
-        const results = walkStashFlat(stashRoot);
-        const resultPaths = results.map((r) => r.absPath);
-        // The symlink must NOT appear in results
-        expect(resultPaths).not.toContain(symlinkPath);
-        // Confirm the outside target is also not reached through the symlink
-        expect(resultPaths).not.toContain(outsideFile);
-        // The legitimate file should still be found
-        expect(resultPaths.some((p) => p.endsWith("legitimate.md"))).toBe(true);
-        // Cleanup the symlink (tmpDir cleanup handles the rest)
-        fs.rmSync(symlinkPath, { force: true });
-    });
-    test("symlink pointing to a directory outside stash root is also skipped", () => {
-        const stashRoot = tmpDir();
-        const knowledgeDir = path.join(stashRoot, "knowledge");
-        fs.mkdirSync(knowledgeDir, { recursive: true });
-        // Create a directory OUTSIDE the stash with a file inside
-        const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-symlink-dir-target-"));
-        extraFiles.push(outsideDir);
-        fs.writeFileSync(path.join(outsideDir, "secret.md"), "# Outside dir secret\n");
-        // Symlink the outside directory into the stash
-        const symlinkDir = path.join(knowledgeDir, "escaped-dir");
-        fs.symlinkSync(outsideDir, symlinkDir);
-        // Create a legitimate file to confirm walker still functions
-        writeFile(path.join(knowledgeDir, "real.md"), "# Real\n");
-        const results = walkStashFlat(stashRoot);
-        const resultPaths = results.map((r) => r.absPath);
-        // No file from inside the outside dir must appear
-        expect(resultPaths.some((p) => p.startsWith(outsideDir))).toBe(false);
-        // The legitimate file should still be found
-        expect(resultPaths.some((p) => p.endsWith("real.md"))).toBe(true);
-        // Cleanup the symlink
-        fs.rmSync(symlinkDir, { force: true });
-    });
-});

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

@@ -1,228 +0,0 @@
-/**
- * Wave-2 QA fixes tests — Cluster B (#21, #36) and Cluster C (#6, #14, #24).
- *
- * Cluster B: defaultWriteTarget and llm/embedding subkey support in config-cli.
- * Cluster C: empty-query guards + minScore floor for semantic-only hits.
- */
-import { describe, expect, test } from "bun:test";
-import { getConfigValue, listConfig, parseConfigValue, setConfigValue, unsetConfigValue, } from "../src/commands/config-cli";
-// ── Cluster B: #21 defaultWriteTarget ────────────────────────────────────────
-describe("config-cli: defaultWriteTarget (#21)", () => {
-    const base = { semanticSearchMode: "auto" };
-    test("parseConfigValue returns defaultWriteTarget", () => {
-        expect(parseConfigValue("defaultWriteTarget", "my-stash")).toEqual({
-            defaultWriteTarget: "my-stash",
-        });
-    });
-    test("parseConfigValue rejects empty defaultWriteTarget", () => {
-        expect(() => parseConfigValue("defaultWriteTarget", "")).toThrow();
-    });
-    test("getConfigValue returns null when not set", () => {
-        expect(getConfigValue(base, "defaultWriteTarget")).toBeNull();
-    });
-    test("getConfigValue returns the set value", () => {
-        const config = { ...base, defaultWriteTarget: "my-stash" };
-        expect(getConfigValue(config, "defaultWriteTarget")).toBe("my-stash");
-    });
-    test("setConfigValue sets defaultWriteTarget — no sources configured", () => {
-        const result = setConfigValue(base, "defaultWriteTarget", "any-name");
-        expect(result.defaultWriteTarget).toBe("any-name");
-    });
-    test("setConfigValue validates name against sources when sources[] is non-empty", () => {
-        const config = {
-            ...base,
-            sources: [{ type: "filesystem", path: "/tmp/stash", name: "primary" }],
-        };
-        expect(() => setConfigValue(config, "defaultWriteTarget", "unknown-stash")).toThrow(/Unknown source name/);
-    });
-    test("setConfigValue accepts a valid source name", () => {
-        const config = {
-            ...base,
-            sources: [{ type: "filesystem", path: "/tmp/stash", name: "primary" }],
-        };
-        const result = setConfigValue(config, "defaultWriteTarget", "primary");
-        expect(result.defaultWriteTarget).toBe("primary");
-    });
-    test("unsetConfigValue clears defaultWriteTarget", () => {
-        const config = { ...base, defaultWriteTarget: "primary" };
-        const result = unsetConfigValue(config, "defaultWriteTarget");
-        expect(result.defaultWriteTarget).toBeUndefined();
-    });
-    test("listConfig includes defaultWriteTarget when set", () => {
-        const config = { ...base, defaultWriteTarget: "primary" };
-        const listed = listConfig(config);
-        expect(listed.defaultWriteTarget).toBe("primary");
-    });
-    test("listConfig omits defaultWriteTarget when not set", () => {
-        const listed = listConfig(base);
-        expect(listed.defaultWriteTarget).toBeUndefined();
-    });
-});
-// ── Cluster B: #36 llm/embedding subkey support ───────────────────────────────
-describe("config-cli: llm.* and embedding.* subkeys (#36)", () => {
-    const base = { semanticSearchMode: "auto" };
-    // ── parseConfigValue ──────────────────────────────────────────────────────
-    test("parseConfigValue handles llm.endpoint", () => {
-        const result = parseConfigValue("llm.endpoint", "http://localhost:11434/v1/chat/completions");
-        expect(result.llm?.endpoint).toBe("http://localhost:11434/v1/chat/completions");
-    });
-    test("parseConfigValue handles llm.model", () => {
-        const result = parseConfigValue("llm.model", "llama3.2");
-        expect(result.llm?.model).toBe("llama3.2");
-    });
-    test("parseConfigValue handles llm.apiKey", () => {
-        const result = parseConfigValue("llm.apiKey", "sk-test");
-        expect(result.llm?.apiKey).toBe("sk-test");
-    });
-    test("parseConfigValue handles embedding.endpoint", () => {
-        const result = parseConfigValue("embedding.endpoint", "http://localhost:11434/v1/embeddings");
-        expect(result.embedding?.endpoint).toBe("http://localhost:11434/v1/embeddings");
-    });
-    test("parseConfigValue handles embedding.model", () => {
-        const result = parseConfigValue("embedding.model", "nomic-embed-text");
-        expect(result.embedding?.model).toBe("nomic-embed-text");
-    });
-    test("parseConfigValue handles embedding.apiKey", () => {
-        const result = parseConfigValue("embedding.apiKey", "sk-embed");
-        expect(result.embedding?.apiKey).toBe("sk-embed");
-    });
-    test("parseConfigValue rejects empty llm.endpoint", () => {
-        expect(() => parseConfigValue("llm.endpoint", "")).toThrow();
-    });
-    // ── getConfigValue ────────────────────────────────────────────────────────
-    test("getConfigValue: llm.endpoint returns null when llm not set", () => {
-        expect(getConfigValue(base, "llm.endpoint")).toBeNull();
-    });
-    test("getConfigValue: llm.endpoint returns value when set", () => {
-        const config = {
-            ...base,
-            llm: { endpoint: "http://localhost/v1", model: "llama3.2" },
-        };
-        expect(getConfigValue(config, "llm.endpoint")).toBe("http://localhost/v1");
-        expect(getConfigValue(config, "llm.model")).toBe("llama3.2");
-        expect(getConfigValue(config, "llm.apiKey")).toBeNull();
-    });
-    test("getConfigValue: embedding subkeys work", () => {
-        const config = {
-            ...base,
-            embedding: { endpoint: "http://localhost/emb", model: "bge-small" },
-        };
-        expect(getConfigValue(config, "embedding.endpoint")).toBe("http://localhost/emb");
-        expect(getConfigValue(config, "embedding.model")).toBe("bge-small");
-        expect(getConfigValue(config, "embedding.apiKey")).toBeNull();
-    });
-    // ── setConfigValue with deep merge ────────────────────────────────────────
-    test("setConfigValue: llm.endpoint preserves sibling model field", () => {
-        const config = {
-            ...base,
-            llm: { endpoint: "http://old/", model: "old-model" },
-        };
-        const result = setConfigValue(config, "llm.endpoint", "http://new/");
-        expect(result.llm?.endpoint).toBe("http://new/");
-        expect(result.llm?.model).toBe("old-model");
-    });
-    test("setConfigValue: llm.model preserves sibling endpoint field", () => {
-        const config = {
-            ...base,
-            llm: { endpoint: "http://localhost/v1", model: "old-model" },
-        };
-        const result = setConfigValue(config, "llm.model", "gpt-4o");
-        expect(result.llm?.model).toBe("gpt-4o");
-        expect(result.llm?.endpoint).toBe("http://localhost/v1");
-    });
-    test("setConfigValue: llm.apiKey merges into existing llm config", () => {
-        const config = {
-            ...base,
-            llm: { endpoint: "http://localhost/v1", model: "llama3.2" },
-        };
-        const result = setConfigValue(config, "llm.apiKey", "sk-secret");
-        expect(result.llm?.apiKey).toBe("sk-secret");
-        expect(result.llm?.endpoint).toBe("http://localhost/v1");
-    });
-    test("setConfigValue: embedding.endpoint works when embedding was undefined", () => {
-        const result = setConfigValue(base, "embedding.endpoint", "http://localhost/emb");
-        expect(result.embedding?.endpoint).toBe("http://localhost/emb");
-        expect(result.embedding?.model).toBe("");
-    });
-    // ── unsetConfigValue ──────────────────────────────────────────────────────
-    test("unsetConfigValue: llm.endpoint sets endpoint to empty string", () => {
-        const config = {
-            ...base,
-            llm: { endpoint: "http://localhost/v1", model: "llama3.2" },
-        };
-        const result = unsetConfigValue(config, "llm.endpoint");
-        expect(result.llm?.endpoint).toBe("");
-        expect(result.llm?.model).toBe("llama3.2");
-    });
-    test("unsetConfigValue: llm.apiKey removes the key", () => {
-        const config = {
-            ...base,
-            llm: { endpoint: "http://localhost/v1", model: "llama3.2", apiKey: "sk-secret" },
-        };
-        const result = unsetConfigValue(config, "llm.apiKey");
-        expect(result.llm?.apiKey).toBeUndefined();
-        expect(result.llm?.endpoint).toBe("http://localhost/v1");
-    });
-    test("unsetConfigValue: embedding.apiKey removes the key", () => {
-        const config = {
-            ...base,
-            embedding: { endpoint: "http://localhost/emb", model: "bge-small", apiKey: "sk-embed" },
-        };
-        const result = unsetConfigValue(config, "embedding.apiKey");
-        expect(result.embedding?.apiKey).toBeUndefined();
-        expect(result.embedding?.endpoint).toBe("http://localhost/emb");
-    });
-});
-// ── Cluster C: #14 empty query guard ────────────────────────────────────────
-describe("search empty-query guard (#14, #24)", () => {
-    // Note: The empty-query guard for `akmSearch` lives in the CLI layer (src/cli.ts),
-    // not in `akmSearch` itself (which accepts empty queries for programmatic list-all).
-    // The guard for `akmCurate` IS in the function itself since curation always
-    // requires a meaningful query.
-    test("akmCurate throws UsageError for empty string query", async () => {
-        const { akmCurate } = await import("../src/commands/curate");
-        await expect(akmCurate({ query: "" })).rejects.toThrow(/query is required/i);
-    });
-    test("akmCurate throws UsageError for whitespace-only query", async () => {
-        const { akmCurate } = await import("../src/commands/curate");
-        await expect(akmCurate({ query: "   " })).rejects.toThrow(/query is required/i);
-    });
-    test("akmCurate UsageError has MISSING_REQUIRED_ARGUMENT code", async () => {
-        const { akmCurate } = await import("../src/commands/curate");
-        const { UsageError } = await import("../src/core/errors");
-        try {
-            await akmCurate({ query: "" });
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            expect(err.code).toBe("MISSING_REQUIRED_ARGUMENT");
-        }
-    });
-});
-// ── Cluster C: #6 minScore floor ─────────────────────────────────────────────
-describe("search.minScore floor in config (#6)", () => {
-    test("AkmConfig accepts search.minScore", () => {
-        const config = {
-            semanticSearchMode: "auto",
-            search: { minScore: 0.3 },
-        };
-        expect(config.search?.minScore).toBe(0.3);
-    });
-    test("AkmConfig accepts search.minScore of 0 (disabled)", () => {
-        const config = {
-            semanticSearchMode: "auto",
-            search: { minScore: 0 },
-        };
-        expect(config.search?.minScore).toBe(0);
-    });
-    test("minScore default is 0.2 in db-search (white-box)", () => {
-        // Verify the default is what the implementation docs: if search is
-        // undefined then minScore should be 0.2 (defaulted in db-search.ts).
-        const config = { semanticSearchMode: "auto" };
-        expect(config.search?.minScore).toBeUndefined();
-        // The effective default 0.2 is applied inside searchDatabase; we just
-        // confirm the config field default is undefined here. An integration test
-        // would require a live DB with semantic hits, which is out of scope.
-    });
-});

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

@@ -1,180 +0,0 @@
-/**
- * Wave-2 QA fixes tests — Cluster D (errors, exit codes, hint text).
- *
- * #8  — hint field rendered in error output (already working; regression guard).
- * #13 — UsageError exits 2, ConfigError exits 78, NotFoundError exits 1.
- * #15 — `akm show foo` (malformed ref) throws UsageError/MISSING_REQUIRED_ARGUMENT.
- * #16 — `config set sources <bad>` says "sources" not "stashes".
- * #27 — clone missing asset: user-facing message, no "Stash type root" leakage.
- * #38 — deprecation hints reference real commands.
- */
-import { describe, expect, test } from "bun:test";
-import { parseConfigValue } from "../src/commands/config-cli";
-import { parseAssetRef } from "../src/core/asset-ref";
-import { ConfigError, NotFoundError, UsageError } from "../src/core/errors";
-// ── #15: parseAssetRef — MISSING_REQUIRED_ARGUMENT code ────────────────────
-describe("parseAssetRef error codes (#15)", () => {
-    test("empty ref throws UsageError with MISSING_REQUIRED_ARGUMENT", () => {
-        try {
-            parseAssetRef("");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            expect(err.code).toBe("MISSING_REQUIRED_ARGUMENT");
-        }
-    });
-    test("ref without colon throws UsageError with MISSING_REQUIRED_ARGUMENT", () => {
-        try {
-            parseAssetRef("foo");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            expect(err.code).toBe("MISSING_REQUIRED_ARGUMENT");
-        }
-    });
-    test("ref with invalid type throws UsageError with MISSING_REQUIRED_ARGUMENT", () => {
-        try {
-            parseAssetRef("badtype:name");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            expect(err.code).toBe("MISSING_REQUIRED_ARGUMENT");
-        }
-    });
-    test("valid ref parses correctly", () => {
-        const ref = parseAssetRef("skill:deploy");
-        expect(ref.type).toBe("skill");
-        expect(ref.name).toBe("deploy");
-    });
-    test("MISSING_REQUIRED_ARGUMENT has a hint in errors.ts", () => {
-        const err = new UsageError("test", "MISSING_REQUIRED_ARGUMENT");
-        expect(err.hint()).toBeDefined();
-        expect(err.hint()).toMatch(/type:name/);
-    });
-});
-// ── #13: exit code classification ────────────────────────────────────────────
-describe("error class exit-code classification (#13)", () => {
-    test("UsageError should be classified as exit 2", () => {
-        const err = new UsageError("bad input");
-        // Verify the code exists so callers can distinguish
-        expect(err.name).toBe("UsageError");
-        expect(err instanceof UsageError).toBe(true);
-    });
-    test("ConfigError should be classified as exit 78", () => {
-        const err = new ConfigError("config bad");
-        expect(err.name).toBe("ConfigError");
-        expect(err instanceof ConfigError).toBe(true);
-    });
-    test("NotFoundError should be classified as exit 1 (GENERAL)", () => {
-        const err = new NotFoundError("not found");
-        expect(err.name).toBe("NotFoundError");
-        expect(err instanceof NotFoundError).toBe(true);
-    });
-    test("UsageError and ConfigError are distinguishable via instanceof", () => {
-        const usage = new UsageError("bad");
-        const config = new ConfigError("bad");
-        expect(usage instanceof UsageError).toBe(true);
-        expect(usage instanceof ConfigError).toBe(false);
-        expect(config instanceof ConfigError).toBe(true);
-        expect(config instanceof UsageError).toBe(false);
-    });
-});
-// ── #8: hint field rendered ───────────────────────────────────────────────────
-describe("error hint rendering (#8)", () => {
-    test("ConfigError with hint: true returns hint", () => {
-        const err = new ConfigError("bad", "STASH_DIR_NOT_FOUND");
-        expect(err.hint()).toBeDefined();
-        expect(err.hint()).toMatch(/akm init/);
-    });
-    test("ConfigError with explicit hint returns it", () => {
-        const err = new ConfigError("bad", "INVALID_CONFIG_FILE", "my custom hint");
-        expect(err.hint()).toBe("my custom hint");
-    });
-    test("UsageError with INVALID_SOURCE_VALUE has a hint", () => {
-        const err = new UsageError("bad source", "INVALID_SOURCE_VALUE");
-        expect(err.hint()).toBeDefined();
-        expect(err.hint()).toContain("stash");
-    });
-    test("NotFoundError with ASSET_NOT_FOUND has a canned hint (Wave C #284)", () => {
-        const err = new NotFoundError("not found");
-        // Wave C added a default hint for ASSET_NOT_FOUND pointing at search/index.
-        expect(err.hint()).toContain("akm search");
-    });
-    test("NotFoundError with explicit hint returns it", () => {
-        const err = new NotFoundError("not found", "ASSET_NOT_FOUND", "run akm init");
-        expect(err.hint()).toBe("run akm init");
-    });
-});
-// ── #16: config set sources error message says "sources" ─────────────────────
-describe("config-cli parseConfigValue sources error message (#16)", () => {
-    test("invalid sources value shows 'sources' not 'stashes' in error", () => {
-        try {
-            parseConfigValue("sources", "not-json");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            const msg = err.message;
-            expect(msg).toContain("sources");
-            expect(msg).not.toContain("stashes");
-        }
-    });
-    test("stashes alias also shows 'sources' in error", () => {
-        try {
-            parseConfigValue("stashes", "not-json");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            const msg = err.message;
-            expect(msg).toContain("sources");
-        }
-    });
-    test("invalid array element shows 'sources[0]' not 'stashes[0]'", () => {
-        try {
-            parseConfigValue("sources", "[{}]");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(UsageError);
-            const msg = err.message;
-            expect(msg).toContain("sources[0]");
-            expect(msg).not.toContain("stashes[0]");
-        }
-    });
-});
-// ── #27: source-resolve user-facing error messages ───────────────────────────
-describe("source-resolve user-facing errors (#27)", () => {
-    test("error message does not contain 'Stash type root'", async () => {
-        // Import the resolver lazily so we don't pull in full DB on every test run.
-        const { resolveAssetPath } = await import("../src/sources/resolve");
-        try {
-            await resolveAssetPath("/tmp/nonexistent-stash-dir-xyz", "skill", "missing-skill");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(NotFoundError);
-            const msg = err.message;
-            expect(msg).not.toContain("Stash type root");
-            // Should contain user-facing wording
-            expect(msg).toMatch(/Asset not found for ref|not found for ref|not accessible/i);
-        }
-    });
-    test("error hint is set on the not-found error from source-resolve", async () => {
-        const { resolveAssetPath } = await import("../src/sources/resolve");
-        try {
-            await resolveAssetPath("/tmp/nonexistent-stash-dir-xyz", "skill", "missing-skill");
-            throw new Error("should have thrown");
-        }
-        catch (err) {
-            expect(err).toBeInstanceOf(NotFoundError);
-            const hint = err.hint();
-            // Should have an actionable hint
-            expect(hint).toBeDefined();
-            expect(hint).toMatch(/akm list|akm index/i);
-        }
-    });
-});