akm-cli 0.6.1 → 0.7.0

package/dist/tests/source-providers/git.test.js

@@ -0,0 +1,252 @@
+import { afterAll, afterEach, beforeEach, 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 { resetConfigCache, saveConfig } from "../../src/core/config";
+import { resolveSourceProviderFactory } from "../../src/sources/provider-factory";
+import { ensureGitMirror, getCachePaths, parseGitRepoUrl, saveGitStash } from "../../src/sources/providers/git";
+// Trigger self-registration
+import "../../src/sources/providers/git";
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-git-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    createdTmpDirs.push(dir);
+    return dir;
+}
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, "utf8");
+}
+/** Create a local git repo with akm-style content for use as a clone source in tests. */
+function createLocalGitRepo() {
+    const repoDir = createTmpDir("akm-git-repo-");
+    writeFile(path.join(repoDir, "content", "openai", "docs", "chat-api", "python", "DOC.md"), `---
+name: chat-api
+description: "Python chat completions reference"
+metadata:
+  languages: "python"
+  versions: "1.1.0"
+  tags: "openai,chat,python"
+---
+# Chat API
+
+Use this document to call chat completions safely.
+`);
+    writeFile(path.join(repoDir, "content", "openai", "skills", "prompt-chaining", "SKILL.md"), `---
+name: prompt-chaining
+description: "Build multi-step prompt flows"
+metadata:
+  revision: 1
+  updated-on: "2026-03-10"
+  tags: "automation,prompts"
+---
+# Prompt Chaining
+
+Chain multiple prompts together.
+`);
+    // Initialise a real git repo so git clone works from local path
+    for (const args of [
+        ["init"],
+        ["checkout", "-b", "main"],
+        ["config", "user.email", "test@test.com"],
+        ["config", "user.name", "Test"],
+        ["config", "commit.gpgsign", "false"],
+        ["add", "."],
+        ["commit", "-m", "init"],
+    ]) {
+        const result = spawnSync("git", args, { cwd: repoDir, encoding: "utf8", timeout: 30_000 });
+        if (result.status !== 0) {
+            throw new Error(`git ${args.join(" ")} failed: ${result.stderr}`);
+        }
+    }
+    return repoDir;
+}
+function createWorkingStash() {
+    const dir = createTmpDir("akm-git-stash-");
+    for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+        fs.mkdirSync(path.join(dir, sub), { recursive: true });
+    }
+    return dir;
+}
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalAkmStashDir = process.env.AKM_STASH_DIR;
+beforeEach(() => {
+    process.env.XDG_CACHE_HOME = createTmpDir("akm-git-cache-");
+    process.env.XDG_CONFIG_HOME = createTmpDir("akm-git-config-");
+    process.env.AKM_STASH_DIR = createWorkingStash();
+});
+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;
+});
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("GitSourceProvider", () => {
+    test("self-registers as 'git' only (legacy aliases removed)", () => {
+        expect(resolveSourceProviderFactory("git")).toBeTruthy();
+        expect(resolveSourceProviderFactory("context-hub")).toBeNull();
+        expect(resolveSourceProviderFactory("github")).toBeNull();
+    });
+    test("provider exposes only the v1 SourceProvider surface (no search/show stubs)", () => {
+        const factory = resolveSourceProviderFactory("git");
+        expect(factory).toBeTruthy();
+        // biome-ignore lint/style/noNonNullAssertion: factory is guaranteed by the expect above
+        const provider = factory({
+            type: "git",
+            url: "https://github.com/andrewyng/context-hub",
+            name: "context-hub",
+        });
+        expect(provider.kind).toBe("git");
+        expect(provider.name).toBe("context-hub");
+        expect(typeof provider.path).toBe("function");
+        expect(typeof provider.sync).toBe("function");
+        // The v1 interface intentionally drops these stubs.
+        expect(provider.search).toBeUndefined();
+        expect(provider.show).toBeUndefined();
+        expect(provider.canShow).toBeUndefined();
+    });
+    test("path() returns the same value across calls (lifetime stability)", () => {
+        const factory = resolveSourceProviderFactory("git");
+        expect(factory).toBeTruthy();
+        // biome-ignore lint/style/noNonNullAssertion: factory is guaranteed by the expect above
+        const provider = factory({
+            type: "git",
+            url: "https://github.com/andrewyng/context-hub",
+            name: "test",
+        });
+        const first = provider.path();
+        const second = provider.path();
+        expect(second).toBe(first);
+    });
+    test("getCachePaths uses 'git-' prefix (not legacy 'context-hub-')", () => {
+        const cachePaths = getCachePaths("https://github.com/example/repo");
+        expect(path.basename(cachePaths.rootDir).startsWith("git-")).toBe(true);
+        expect(path.basename(cachePaths.rootDir).startsWith("context-hub-")).toBe(false);
+    });
+    test("cache mirror clones content to disk via git", async () => {
+        const localRepoPath = createLocalGitRepo();
+        // Construct ParsedRepoUrl directly to point at the local repo
+        const repo = { cloneUrl: localRepoPath, ref: null, canonicalUrl: localRepoPath };
+        const cachePaths = getCachePaths(repo.canonicalUrl);
+        await ensureGitMirror(repo, cachePaths, { requireRepoDir: true });
+        // Verify cloned content exists at the expected path
+        const docPath = path.join(cachePaths.repoDir, "content", "openai", "docs", "chat-api", "python", "DOC.md");
+        expect(fs.existsSync(docPath)).toBe(true);
+        const content = fs.readFileSync(docPath, "utf8");
+        expect(content).toContain("# Chat API");
+    });
+    test("cache mirror respects TTL and skips re-clone when fresh", async () => {
+        const localRepoPath = createLocalGitRepo();
+        const repo = { cloneUrl: localRepoPath, ref: null, canonicalUrl: localRepoPath };
+        const cachePaths = getCachePaths(repo.canonicalUrl);
+        // Prime the cache
+        await ensureGitMirror(repo, cachePaths, { requireRepoDir: true });
+        // Remove the content to verify it is NOT re-cloned (cache is still fresh)
+        const docPath = path.join(cachePaths.repoDir, "content", "openai", "docs", "chat-api", "python", "DOC.md");
+        fs.rmSync(docPath);
+        await ensureGitMirror(repo, cachePaths, { requireRepoDir: false });
+        // File should still be absent — clone was skipped due to fresh cache
+        expect(fs.existsSync(docPath)).toBe(false);
+    });
+    test("integrates with stash sources via ensureSourceCaches", async () => {
+        // Pre-populate the cache so ensureGitMirror returns early without cloning
+        const stashUrl = "https://github.com/andrewyng/context-hub";
+        const repo = parseGitRepoUrl(stashUrl);
+        const cachePaths = getCachePaths(repo.canonicalUrl);
+        fs.mkdirSync(cachePaths.rootDir, { recursive: true });
+        fs.mkdirSync(path.join(cachePaths.repoDir, "content"), { recursive: true });
+        fs.writeFileSync(cachePaths.indexPath, "[]", { encoding: "utf8", mode: 0o600 });
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "git", url: stashUrl, name: "context-hub" }],
+        });
+        resetConfigCache();
+        const { ensureSourceCaches } = await import("../../src/indexer/search-source");
+        const { loadConfig } = await import("../../src/core/config");
+        const config = loadConfig();
+        await ensureSourceCaches(config);
+        // Verify git stash content dir appears in stash sources.
+        const { resolveSourceEntries } = await import("../../src/indexer/search-source");
+        const sources = resolveSourceEntries(undefined, config);
+        const gitSource = sources.find((s) => s.path.includes(path.basename(cachePaths.rootDir)));
+        expect(gitSource).toBeDefined();
+    });
+});
+// ── saveGitStash commit message sanitization (issue #270) ───────────────────
+describe("saveGitStash — commit message sanitization (issue #270)", () => {
+    /** Initialise an empty git repo at the given dir. */
+    function initRepo(dir) {
+        for (const args of [
+            ["init", "--initial-branch=main"],
+            ["config", "user.email", "test@akm.local"],
+            ["config", "user.name", "akm-test"],
+            ["config", "commit.gpgsign", "false"],
+        ]) {
+            const result = spawnSync("git", ["-C", dir, ...args], { encoding: "utf8" });
+            if (result.status !== 0)
+                throw new Error(`git ${args.join(" ")} failed: ${result.stderr}`);
+        }
+    }
+    test("--message with embedded newlines is collapsed to a single line", () => {
+        const stashDir = process.env.AKM_STASH_DIR;
+        initRepo(stashDir);
+        // Stage some change to commit.
+        writeFile(path.join(stashDir, "skills", "x.md"), "x\n");
+        const malign = "feat: add skill\n\nCo-Authored-By: attacker <evil@example>";
+        const result = saveGitStash(undefined, malign);
+        expect(result.committed).toBe(true);
+        const log = spawnSync("git", ["-C", stashDir, "log", "--format=%B%x00", "-1"], { encoding: "utf8" });
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: NUL is the explicit record separator.
+        const body = log.stdout.replace(/\x00\s*$/, "").replace(/\n$/, "");
+        expect(body.includes("\n")).toBe(false);
+        expect(body).toBe("feat: add skill Co-Authored-By: attacker <evil@example>");
+    });
+    test("--message with NUL byte is sanitized so commit succeeds", () => {
+        const stashDir = process.env.AKM_STASH_DIR;
+        initRepo(stashDir);
+        writeFile(path.join(stashDir, "skills", "y.md"), "y\n");
+        const malign = "subject\x00embedded";
+        const result = saveGitStash(undefined, malign);
+        expect(result.committed).toBe(true);
+        const log = spawnSync("git", ["-C", stashDir, "log", "--format=%s", "-1"], { encoding: "utf8" });
+        expect(log.stdout.includes("\x00")).toBe(false);
+        expect(log.stdout.trim()).toBe("subjectembedded");
+    });
+    test("--message that sanitizes to empty falls back to the timestamped default", () => {
+        const stashDir = process.env.AKM_STASH_DIR;
+        initRepo(stashDir);
+        writeFile(path.join(stashDir, "skills", "z.md"), "z\n");
+        // Whitespace + control chars only — must NOT result in an empty commit
+        // subject; fall back to the timestamped default.
+        const result = saveGitStash(undefined, "\n\r\x00 \t");
+        expect(result.committed).toBe(true);
+        const log = spawnSync("git", ["-C", stashDir, "log", "--format=%s", "-1"], { encoding: "utf8" });
+        expect(log.stdout.startsWith("akm save ")).toBe(true);
+    });
+    test("--message exceeding 4096 chars is clamped", () => {
+        const stashDir = process.env.AKM_STASH_DIR;
+        initRepo(stashDir);
+        writeFile(path.join(stashDir, "skills", "w.md"), "w\n");
+        const longMessage = `prefix-${"x".repeat(5000)}`;
+        const result = saveGitStash(undefined, longMessage);
+        expect(result.committed).toBe(true);
+        const log = spawnSync("git", ["-C", stashDir, "log", "--format=%s", "-1"], { encoding: "utf8" });
+        expect(log.stdout.trim().length).toBeLessThanOrEqual(4096);
+        expect(log.stdout.trim().startsWith("prefix-xxxx")).toBe(true);
+    });
+});

package/dist/tests/source-providers/website.test.js

@@ -0,0 +1,128 @@
+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 { ConfigError, UsageError } from "../../src/core/errors";
+import { resolveSourceProviderFactory } from "../../src/sources/provider-factory";
+import { ensureWebsiteMirror, getCachePaths, validateWebsiteInputUrl, validateWebsiteUrl, } from "../../src/sources/providers/website";
+// Trigger self-registration
+import "../../src/sources/providers/website";
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-website-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    createdTmpDirs.push(dir);
+    return dir;
+}
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalAkmStashDir = process.env.AKM_STASH_DIR;
+beforeEach(() => {
+    process.env.XDG_CACHE_HOME = createTmpDir("akm-website-cache-");
+    process.env.XDG_CONFIG_HOME = createTmpDir("akm-website-config-");
+    process.env.AKM_STASH_DIR = createTmpDir("akm-website-stash-");
+    saveConfig({ semanticSearchMode: "off" });
+});
+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;
+});
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("WebsiteSourceProvider", () => {
+    test("self-registers as 'website'", () => {
+        expect(resolveSourceProviderFactory("website")).toBeTruthy();
+    });
+    test("provider exposes only the v1 SourceProvider surface (no search/show stubs)", () => {
+        const factory = resolveSourceProviderFactory("website");
+        expect(factory).toBeTruthy();
+        if (!factory)
+            throw new Error("expected website factory to be registered");
+        const provider = factory({
+            type: "website",
+            url: "https://example.com/docs",
+            name: "example",
+        });
+        expect(provider.kind).toBe("website");
+        expect(provider.name).toBe("example");
+        expect(typeof provider.path).toBe("function");
+        expect(typeof provider.sync).toBe("function");
+        expect(provider.search).toBeUndefined();
+        expect(provider.show).toBeUndefined();
+        expect(provider.canShow).toBeUndefined();
+    });
+    test("path() returns the same value across calls (lifetime stability)", () => {
+        const factory = resolveSourceProviderFactory("website");
+        expect(factory).toBeTruthy();
+        if (!factory)
+            throw new Error("expected website factory to be registered");
+        const provider = factory({
+            type: "website",
+            url: "https://example.com/docs",
+            name: "example",
+        });
+        const first = provider.path();
+        const second = provider.path();
+        expect(second).toBe(first);
+    });
+    test("scrapes a website into cached markdown files", async () => {
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (async (input) => {
+            const url = String(input);
+            if (url === "https://docs.example.test/") {
+                return new Response("<html><head><title>Docs Home</title></head><body><h1>Docs Home</h1><p>Welcome.</p><a href='/guide'>Guide</a></body></html>", {
+                    status: 200,
+                    headers: { "Content-Type": "text/html; charset=utf-8" },
+                });
+            }
+            if (url === "https://docs.example.test/guide") {
+                return new Response("<html><body><h1>Guide</h1><p>Install the tool safely.</p></body></html>", {
+                    status: 200,
+                    headers: { "Content-Type": "text/html; charset=utf-8" },
+                });
+            }
+            return new Response("not found", { status: 404 });
+        });
+        try {
+            const entry = { type: "website", url: "https://docs.example.test/" };
+            const cachePaths = await ensureWebsiteMirror(entry, { requireStashDir: true });
+            const topFiles = fs.readdirSync(path.join(cachePaths.stashDir, "knowledge")).sort();
+            expect(topFiles).toEqual(["guide.md", "index.md"]);
+            const homeDoc = fs.readFileSync(path.join(cachePaths.stashDir, "knowledge", "index.md"), "utf8");
+            expect(homeDoc).toContain("# Docs Home");
+            expect(homeDoc).toContain("Source: https://docs.example.test/");
+            expect(homeDoc).toContain("[Guide](https://docs.example.test/guide)");
+            const guideDoc = fs.readFileSync(path.join(cachePaths.stashDir, "knowledge", "guide.md"), "utf8");
+            expect(guideDoc).toContain("# Guide");
+            expect(guideDoc).toContain("Install the tool safely.");
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+    test("validateWebsiteUrl rejects embedded credentials", () => {
+        expect(() => validateWebsiteUrl("https://user:pass@example.com")).toThrow("embedded credentials");
+    });
+    test("CLI input validation throws UsageError while config validation throws ConfigError", () => {
+        expect(() => validateWebsiteInputUrl("not a url")).toThrow(UsageError);
+        expect(() => validateWebsiteUrl("not a url")).toThrow(ConfigError);
+    });
+    test("getCachePaths is stable for normalized URLs", () => {
+        const a = getCachePaths("https://example.com/docs/");
+        const b = getCachePaths("https://example.com/docs");
+        expect(a.rootDir).toBe(b.rootDir);
+    });
+});

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

@@ -0,0 +1,286 @@
+/**
+ * Tests for QA fixes in cluster A (issues #9, #10, #11, #12, #17, #18, #19, #22, #23).
+ *
+ * - #9/#18/#22: `akm add <path> --name extra` persists the name for filesystem sources.
+ * - #10:        Filesystem kind reported as "filesystem", not "local".
+ * - #11/#23:    Filesystem writable defaults to true in list output.
+ * - #12:        `updatable` field dropped from SourceEntry.
+ * - #17:        Website kind reported as "website", not "remote".
+ * - #19:        akm update re-mirrors website sources via sync().
+ */
+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 { akmListSources, akmUpdate } from "../src/commands/installed-stashes";
+import { akmAdd } from "../src/commands/source-add";
+import { addStash } from "../src/commands/source-manage";
+import { loadConfig, saveConfig } from "../src/core/config";
+import { ConfigError } from "../src/core/errors";
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-qa-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    createdTmpDirs.push(dir);
+    return dir;
+}
+function makeStashDir(base) {
+    for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+        fs.mkdirSync(path.join(base, sub), { recursive: true });
+    }
+}
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+});
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalStashDir = process.env.AKM_STASH_DIR;
+let testCacheDir = "";
+let testConfigDir = "";
+let stashDir = "";
+beforeEach(() => {
+    testCacheDir = createTmpDir("akm-qa-cache-");
+    testConfigDir = createTmpDir("akm-qa-config-");
+    stashDir = createTmpDir("akm-qa-stash-");
+    makeStashDir(stashDir);
+    process.env.XDG_CACHE_HOME = testCacheDir;
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+    process.env.AKM_STASH_DIR = stashDir;
+});
+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 (originalStashDir === undefined)
+        delete process.env.AKM_STASH_DIR;
+    else
+        process.env.AKM_STASH_DIR = originalStashDir;
+    if (testCacheDir) {
+        fs.rmSync(testCacheDir, { recursive: true, force: true });
+        testCacheDir = "";
+    }
+    if (testConfigDir) {
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+        testConfigDir = "";
+    }
+});
+// ── Issue #9 / #18 / #22: --name persisted for filesystem sources ──────────
+describe("issue #9: --name flag persisted for filesystem sources", () => {
+    test("akmAdd persists explicit --name for a local path", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const extraStash = createTmpDir("akm-qa-extra-");
+        makeStashDir(extraStash);
+        const result = await akmAdd({ ref: extraStash, name: "extra" });
+        // sourceAdded should carry the explicit name
+        expect(result.sourceAdded).toBeDefined();
+        expect(result.sourceAdded?.name).toBe("extra");
+        // Config should persist the name
+        const config = loadConfig();
+        const sources = config.sources ?? config.stashes ?? [];
+        const added = sources.find((s) => s.type === "filesystem" && s.path === path.resolve(extraStash));
+        expect(added).toBeDefined();
+        expect(added?.name).toBe("extra");
+    });
+    test("akm remove works when source was added with --name", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const extraStash = createTmpDir("akm-qa-extra-rm-");
+        makeStashDir(extraStash);
+        await akmAdd({ ref: extraStash, name: "extra" });
+        // Verify the name is in the config
+        const configBefore = loadConfig();
+        const sources = configBefore.sources ?? configBefore.stashes ?? [];
+        expect(sources.some((s) => s.name === "extra")).toBe(true);
+    });
+    test("akmAdd without --name falls back to readable path", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const someStash = createTmpDir("akm-qa-noname-");
+        makeStashDir(someStash);
+        await akmAdd({ ref: someStash });
+        const config = loadConfig();
+        const sources = config.sources ?? config.stashes ?? [];
+        const added = sources.find((s) => s.type === "filesystem" && s.path === path.resolve(someStash));
+        expect(added).toBeDefined();
+        // Name should NOT be the raw path (it's the readable form), but should not be empty
+        expect(added?.name).toBeTruthy();
+        // name should not be undefined
+        expect(typeof added?.name).toBe("string");
+    });
+});
+describe("manual QA add validation", () => {
+    test("akmAdd rejects writable installs for npm refs before syncing", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        await expect(akmAdd({ ref: "npm:left-pad", writable: true })).rejects.toThrow(ConfigError);
+    });
+    test("addStash rejects openviking providers before persisting config", () => {
+        saveConfig({ semanticSearchMode: "off" });
+        expect(() => addStash({ target: "https://example.com", providerType: "openviking" })).toThrow(ConfigError);
+        expect(loadConfig().sources).toBeUndefined();
+    });
+    test("addStash rejects writable website sources before persisting config", () => {
+        saveConfig({ semanticSearchMode: "off" });
+        expect(() => addStash({ target: "https://example.com", providerType: "website", writable: true })).toThrow(ConfigError);
+        expect(loadConfig().sources).toBeUndefined();
+    });
+});
+// ── Issue #10: filesystem kind = "filesystem" in list output ──────────────
+describe("issue #10: filesystem kind in list output", () => {
+    test("filesystem source has kind='filesystem' in akmListSources", async () => {
+        const sourceDir = createTmpDir("akm-qa-fs-kind-");
+        makeStashDir(sourceDir);
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: sourceDir }],
+        });
+        const result = await akmListSources({ stashDir });
+        const fsSrc = result.sources.find((s) => s.path === sourceDir);
+        expect(fsSrc).toBeDefined();
+        expect(fsSrc?.kind).toBe("filesystem");
+    });
+    test("git source has kind='git' in akmListSources", async () => {
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "git", url: "https://github.com/example/repo.git", name: "my-git" }],
+        });
+        const result = await akmListSources({ stashDir });
+        const gitSrc = result.sources.find((s) => s.name === "my-git");
+        expect(gitSrc).toBeDefined();
+        expect(gitSrc?.kind).toBe("git");
+    });
+});
+// ── Issue #17: website kind = "website" in list output ──────────────────
+describe("issue #17: website kind in list output", () => {
+    test("website source has kind='website' in akmListSources", async () => {
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "website", url: "https://example.com", name: "docs-site" }],
+        });
+        const result = await akmListSources({ stashDir });
+        const webSrc = result.sources.find((s) => s.name === "docs-site");
+        expect(webSrc).toBeDefined();
+        expect(webSrc?.kind).toBe("website");
+    });
+});
+// ── Issue #11 / #23: filesystem writable defaults to true ─────────────────
+describe("issue #11: filesystem writable defaults to true in list output", () => {
+    test("filesystem source without explicit writable defaults to true", async () => {
+        const sourceDir = createTmpDir("akm-qa-writable-");
+        makeStashDir(sourceDir);
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: sourceDir }],
+        });
+        const result = await akmListSources({ stashDir });
+        const fsSrc = result.sources.find((s) => s.path === sourceDir);
+        expect(fsSrc).toBeDefined();
+        expect(fsSrc?.writable).toBe(true);
+    });
+    test("filesystem source with writable: false respects the explicit setting", async () => {
+        const sourceDir = createTmpDir("akm-qa-writable-false-");
+        makeStashDir(sourceDir);
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: sourceDir, writable: false }],
+        });
+        const result = await akmListSources({ stashDir });
+        const fsSrc = result.sources.find((s) => s.path === sourceDir);
+        expect(fsSrc).toBeDefined();
+        expect(fsSrc?.writable).toBe(false);
+    });
+    test("git source without explicit writable defaults to false", async () => {
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "git", url: "https://github.com/example/repo.git", name: "my-git" }],
+        });
+        const result = await akmListSources({ stashDir });
+        const gitSrc = result.sources.find((s) => s.name === "my-git");
+        expect(gitSrc).toBeDefined();
+        expect(gitSrc?.writable).toBe(false);
+    });
+    test("website source without explicit writable defaults to false", async () => {
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "website", url: "https://example.com", name: "docs-site" }],
+        });
+        const result = await akmListSources({ stashDir });
+        const webSrc = result.sources.find((s) => s.name === "docs-site");
+        expect(webSrc).toBeDefined();
+        expect(webSrc?.writable).toBe(false);
+    });
+});
+// ── Issue #12: updatable field dropped from SourceEntry ──────────────────
+describe("issue #12: updatable field absent from SourceEntry", () => {
+    test("filesystem sources do not expose updatable field", async () => {
+        const sourceDir = createTmpDir("akm-qa-no-updatable-");
+        makeStashDir(sourceDir);
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: sourceDir }],
+        });
+        const result = await akmListSources({ stashDir });
+        const fsSrc = result.sources.find((s) => s.path === sourceDir);
+        expect(fsSrc).toBeDefined();
+        expect("updatable" in (fsSrc ?? {})).toBe(false);
+    });
+    test("managed sources do not expose updatable field", async () => {
+        const cacheDir = createTmpDir("akm-qa-managed-cache-");
+        const stashRoot = createTmpDir("akm-qa-managed-root-");
+        makeStashDir(stashRoot);
+        saveConfig({
+            semanticSearchMode: "off",
+            installed: [
+                {
+                    id: "test-pkg",
+                    source: "npm",
+                    ref: "test-pkg",
+                    artifactUrl: "https://example.com/test-pkg.tgz",
+                    stashRoot,
+                    cacheDir,
+                    installedAt: new Date().toISOString(),
+                },
+            ],
+        });
+        const result = await akmListSources({ stashDir });
+        const managed = result.sources.find((s) => s.kind === "managed");
+        expect(managed).toBeDefined();
+        expect("updatable" in (managed ?? {})).toBe(false);
+    });
+});
+// ── Issue #19: akm update syncs website sources ───────────────────────────
+describe("issue #19: akm update website sources", () => {
+    test("website source update does not throw TARGET_NOT_UPDATABLE", async () => {
+        // Use a local HTTP server to serve minimal HTML for the crawl
+        const server = Bun.serve({
+            port: 0,
+            fetch(_req) {
+                return new Response("<html><head><title>Test</title></head><body><h1>Test</h1><p>hello world</p></body></html>", { headers: { "Content-Type": "text/html; charset=utf-8" } });
+            },
+        });
+        const siteUrl = `http://127.0.0.1:${server.port}`;
+        try {
+            saveConfig({
+                semanticSearchMode: "off",
+                sources: [{ type: "website", url: siteUrl, name: "test-site" }],
+            });
+            // Should not throw TARGET_NOT_UPDATABLE
+            const result = await akmUpdate({ target: "test-site", stashDir });
+            // Returns an UpdateResponse with processed[] (empty for website sources)
+            expect(result).toBeDefined();
+            expect(result.schemaVersion).toBe(1);
+            expect(result.processed).toEqual([]);
+        }
+        finally {
+            server.stop(true);
+        }
+    });
+});