akm-cli 0.6.1 → 0.7.0

package/dist/tests/walker.test.js

@@ -0,0 +1,252 @@
+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

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

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