akm-cli 0.6.0 → 0.7.0-rc1

package/dist/tests/source-registry.test.js

@@ -0,0 +1,350 @@
+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, akmRemove, akmUpdate } from "../src/commands/installed-stashes";
+import { loadConfig, saveConfig } from "../src/core/config";
+import { createWiki } from "../src/wiki/wiki";
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-registry-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    createdTmpDirs.push(dir);
+    return dir;
+}
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+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-registry-cache-");
+    testConfigDir = createTmpDir("akm-registry-config-");
+    stashDir = createTmpDir("akm-registry-stash-");
+    for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+        fs.mkdirSync(path.join(stashDir, sub), { recursive: true });
+    }
+    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 = "";
+    }
+});
+// ── akmListSources ────────────────────────────────────────────────────
+describe("akmListSources", () => {
+    test("returns empty list when no sources configured", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const result = await akmListSources({ stashDir });
+        expect(result.totalSources).toBe(0);
+        expect(result.sources).toEqual([]);
+        expect(result.stashDir).toBe(stashDir);
+    });
+    test("returns managed and local sources", async () => {
+        const cacheDir = createTmpDir("akm-registry-cache-entry-");
+        const stashRoot = createTmpDir("akm-registry-stashroot-");
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: stashRoot, writable: true }],
+            installed: [
+                {
+                    id: "test-pkg",
+                    source: "npm",
+                    ref: "test-pkg",
+                    artifactUrl: "https://example.com/test-pkg.tgz",
+                    stashRoot: stashRoot,
+                    cacheDir: cacheDir,
+                    installedAt: new Date().toISOString(),
+                },
+            ],
+        });
+        const result = await akmListSources({ stashDir });
+        expect(result.totalSources).toBe(2);
+        // Filesystem source from stashes[] — kind must be "filesystem" (spec §2.1)
+        const local = result.sources.find((s) => s.kind === "filesystem");
+        expect(local).toBeDefined();
+        if (!local) {
+            throw new Error("Expected filesystem source");
+        }
+        expect(local.path).toBe(stashRoot);
+        expect(local.writable).toBe(true);
+        // Managed source from installed[]
+        const managed = result.sources.find((s) => s.kind === "managed");
+        expect(managed).toBeDefined();
+        if (!managed) {
+            throw new Error("Expected managed source");
+        }
+        expect(managed.name).toBe("test-pkg");
+        expect(managed.ref).toBe("test-pkg");
+        expect(managed.status.exists).toBe(true);
+        expect(managed.writable).toBe(false);
+    });
+    test("includes stash-owned wikis as filesystem wiki sources", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        createWiki(stashDir, "research");
+        const result = await akmListSources({ stashDir });
+        expect(result.totalSources).toBe(1);
+        expect(result.sources).toEqual([
+            expect.objectContaining({
+                name: "research",
+                kind: "filesystem",
+                wiki: "research",
+                path: path.join(stashDir, "wikis", "research"),
+                writable: true,
+                status: { exists: true },
+            }),
+        ]);
+    });
+    test("reports missing directories in status", async () => {
+        const nonExistentCache = path.join(os.tmpdir(), `akm-nonexistent-cache-${Date.now()}`);
+        const nonExistentStashRoot = path.join(os.tmpdir(), `akm-nonexistent-root-${Date.now()}`);
+        saveConfig({
+            semanticSearchMode: "off",
+            installed: [
+                {
+                    id: "missing-pkg",
+                    source: "npm",
+                    ref: "missing-pkg",
+                    artifactUrl: "https://example.com/missing-pkg.tgz",
+                    stashRoot: nonExistentStashRoot,
+                    cacheDir: nonExistentCache,
+                    installedAt: new Date().toISOString(),
+                },
+            ],
+        });
+        const result = await akmListSources({ stashDir });
+        expect(result.totalSources).toBe(1);
+        expect(result.sources[0].kind).toBe("managed");
+        expect(result.sources[0].status.exists).toBe(false);
+        expect(result.sources[0].writable).toBe(false);
+    });
+    test("reports writable managed sources from installed metadata", async () => {
+        const cacheDir = createTmpDir("akm-registry-cache-entry-");
+        const stashRoot = createTmpDir("akm-registry-stashroot-");
+        saveConfig({
+            semanticSearchMode: "off",
+            installed: [
+                {
+                    id: "github:owner/repo",
+                    source: "github",
+                    ref: "github:owner/repo",
+                    artifactUrl: "https://github.com/owner/repo.git",
+                    stashRoot,
+                    cacheDir,
+                    installedAt: new Date().toISOString(),
+                    writable: true,
+                },
+            ],
+        });
+        const result = await akmListSources({ stashDir, kind: ["managed"] });
+        expect(result.totalSources).toBe(1);
+        expect(result.sources[0].kind).toBe("managed");
+        expect(result.sources[0].writable).toBe(true);
+    });
+    test("filters by kind", async () => {
+        const stashRoot = createTmpDir("akm-registry-stashroot-");
+        const cacheDir = createTmpDir("akm-registry-cache-");
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: stashRoot }],
+            installed: [
+                {
+                    id: "test-pkg",
+                    source: "npm",
+                    ref: "test-pkg",
+                    artifactUrl: "https://example.com/test-pkg.tgz",
+                    stashRoot,
+                    cacheDir,
+                    installedAt: new Date().toISOString(),
+                },
+            ],
+        });
+        const managedOnly = await akmListSources({ stashDir, kind: ["managed"] });
+        expect(managedOnly.totalSources).toBe(1);
+        expect(managedOnly.sources[0].kind).toBe("managed");
+        const filesystemOnly = await akmListSources({ stashDir, kind: ["filesystem"] });
+        expect(filesystemOnly.totalSources).toBe(1);
+        expect(filesystemOnly.sources[0].kind).toBe("filesystem");
+    });
+});
+// ── akmRemove ──────────────────────────────────────────────────────────
+describe("akmRemove", () => {
+    test("throws for empty target", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        await expect(akmRemove({ target: "", stashDir })).rejects.toThrow("Target is required.");
+    });
+    test("throws for whitespace-only target", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        await expect(akmRemove({ target: "   ", stashDir })).rejects.toThrow("Target is required.");
+    });
+    test("throws for unknown target", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        await expect(akmRemove({ target: "nonexistent-package", stashDir })).rejects.toThrow("No matching source for target");
+    });
+    test("removes entry by id", async () => {
+        const cacheDir = createTmpDir("akm-registry-remove-cache-");
+        const stashRoot = createTmpDir("akm-registry-remove-root-");
+        for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+            fs.mkdirSync(path.join(stashRoot, sub), { recursive: true });
+        }
+        const entry = {
+            id: "test-pkg",
+            source: "npm",
+            ref: "npm:test-pkg",
+            artifactUrl: "https://example.com/test.tgz",
+            stashRoot,
+            cacheDir,
+            installedAt: new Date().toISOString(),
+        };
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: stashRoot }],
+            installed: [entry],
+        });
+        const result = await akmRemove({ target: entry.id, stashDir });
+        expect(result.removed.id).toBe(entry.id);
+        const config = loadConfig();
+        const remaining = config.installed ?? [];
+        expect(remaining.find((e) => e.id === entry.id)).toBeUndefined();
+    });
+    test("removes entry by ref", async () => {
+        const cacheDir = createTmpDir("akm-registry-remove-cache-ref-");
+        const stashRoot = createTmpDir("akm-registry-remove-root-ref-");
+        for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+            fs.mkdirSync(path.join(stashRoot, sub), { recursive: true });
+        }
+        const entry = {
+            id: "test-pkg-ref",
+            source: "npm",
+            ref: "npm:test-pkg-ref",
+            artifactUrl: "https://example.com/test-ref.tgz",
+            stashRoot,
+            cacheDir,
+            installedAt: new Date().toISOString(),
+        };
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: stashRoot }],
+            installed: [entry],
+        });
+        const result = await akmRemove({ target: entry.ref, stashDir });
+        expect(result.removed.id).toBe(entry.id);
+        const config = loadConfig();
+        const remaining = config.installed ?? [];
+        expect(remaining.find((e) => e.id === entry.id)).toBeUndefined();
+    });
+    test("cleans up cache directory", async () => {
+        const cacheDir = createTmpDir("akm-registry-remove-cache-cleanup-");
+        const stashRoot = createTmpDir("akm-registry-remove-root-cleanup-");
+        for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+            fs.mkdirSync(path.join(stashRoot, sub), { recursive: true });
+        }
+        const entry = {
+            id: "test-pkg-cleanup",
+            source: "npm",
+            ref: "npm:test-pkg-cleanup",
+            artifactUrl: "https://example.com/test-cleanup.tgz",
+            stashRoot,
+            cacheDir,
+            installedAt: new Date().toISOString(),
+        };
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: stashRoot }],
+            installed: [entry],
+        });
+        await akmRemove({ target: entry.id, stashDir });
+        expect(fs.existsSync(cacheDir)).toBe(false);
+    });
+});
+// ── selectTargets (tested via akmUpdate error paths) ────────────────
+describe("selectTargets via akmUpdate", () => {
+    test("throws when both target and all are specified", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        await expect(akmUpdate({ target: "some-pkg", all: true, stashDir })).rejects.toThrow("Specify either <target> or --all, not both.");
+    });
+    test("throws when neither target nor all is specified", async () => {
+        saveConfig({ semanticSearchMode: "off" });
+        await expect(akmUpdate({ stashDir })).rejects.toThrow("Either <target> or --all is required.");
+    });
+    test("--all selects all installed entries (registry stashes only)", async () => {
+        // Use local directory refs so installRegistryRef works without network.
+        const localDir1 = createTmpDir("akm-registry-all-1-");
+        const localDir2 = createTmpDir("akm-registry-all-2-");
+        for (const dir of [localDir1, localDir2]) {
+            for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+                fs.mkdirSync(path.join(dir, sub), { recursive: true });
+            }
+        }
+        // Store as source: "npm" with local-path refs so they stay in installed[]
+        // but parseRegistryRef recognizes the ref as a local path.
+        saveConfig({
+            semanticSearchMode: "off",
+            installed: [
+                {
+                    id: `local:${path.basename(localDir1)}`,
+                    source: "npm",
+                    ref: localDir1,
+                    artifactUrl: `file://${localDir1}`,
+                    stashRoot: localDir1,
+                    cacheDir: localDir1,
+                    installedAt: new Date().toISOString(),
+                },
+                {
+                    id: `local:${path.basename(localDir2)}`,
+                    source: "npm",
+                    ref: localDir2,
+                    artifactUrl: `file://${localDir2}`,
+                    stashRoot: localDir2,
+                    cacheDir: localDir2,
+                    installedAt: new Date().toISOString(),
+                },
+            ],
+        });
+        const result = await akmUpdate({ all: true, stashDir });
+        expect(result.processed).toHaveLength(2);
+    });
+    test("local directories in stashes are preserved by update --force", async () => {
+        const localDir = createTmpDir("akm-registry-update-local-force-");
+        fs.mkdirSync(path.join(localDir, "scripts"), { recursive: true });
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: localDir, name: "test-local" }],
+            installed: [],
+        });
+        // Local dirs are stash sources now — update only affects installed entries
+        expect(fs.existsSync(localDir)).toBe(true);
+        const config = loadConfig();
+        expect((config.sources ?? []).some((s) => s.path === localDir)).toBe(true);
+    });
+});

package/dist/tests/source-resolve.test.js

@@ -0,0 +1,100 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveAssetPath } from "../src/sources/resolve";
+const createdTmpDirs = [];
+function createTmpDir(prefix = "akm-resolve-") {
+    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);
+}
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+// ── resolveAssetPath ──────────────────────────────────────────────────────────
+describe("resolveAssetPath", () => {
+    test("returns real path for valid script", async () => {
+        const stashDir = createTmpDir();
+        const scriptPath = path.join(stashDir, "scripts", "deploy.sh");
+        writeFile(scriptPath, "#!/bin/sh\necho hello");
+        const result = await resolveAssetPath(stashDir, "script", "deploy.sh");
+        expect(result).toBe(fs.realpathSync(scriptPath));
+    });
+    test("throws for missing type root", async () => {
+        const stashDir = createTmpDir();
+        // No scripts/ directory created
+        // QA #27: error message no longer leaks internal "Stash type root" wording
+        await expect(resolveAssetPath(stashDir, "script", "deploy.sh")).rejects.toThrow(/Asset not found for ref: script:deploy\.sh|not found for ref/i);
+    });
+    test("throws for missing file", async () => {
+        const stashDir = createTmpDir();
+        fs.mkdirSync(path.join(stashDir, "scripts"), { recursive: true });
+        await expect(resolveAssetPath(stashDir, "script", "nonexistent.sh")).rejects.toThrow("Stash asset not found for ref: script:nonexistent.sh");
+    });
+    test("throws for path traversal", async () => {
+        const stashDir = createTmpDir();
+        fs.mkdirSync(path.join(stashDir, "scripts"), { recursive: true });
+        // Create a file outside the scripts root
+        writeFile(path.join(stashDir, "outside.sh"), "#!/bin/sh\necho escape");
+        await expect(resolveAssetPath(stashDir, "script", "../outside.sh")).rejects.toThrow("Ref resolves outside the stash root.");
+    });
+    test("throws for symlink escape", async () => {
+        const stashDir = createTmpDir();
+        const scriptsDir = path.join(stashDir, "scripts");
+        fs.mkdirSync(scriptsDir, { recursive: true });
+        // Create a file outside the stash entirely
+        const outsideDir = createTmpDir("akm-outside-");
+        const outsideFile = path.join(outsideDir, "escaped.sh");
+        writeFile(outsideFile, "#!/bin/sh\necho escaped");
+        const symlinkPath = path.join(scriptsDir, "link.sh");
+        try {
+            fs.symlinkSync(outsideFile, symlinkPath);
+        }
+        catch {
+            // Symlinks may not be supported on all environments; skip gracefully
+            return;
+        }
+        await expect(resolveAssetPath(stashDir, "script", "link.sh")).rejects.toThrow("Ref resolves outside the stash root.");
+    });
+    test("validates script extension", async () => {
+        const stashDir = createTmpDir();
+        const badFile = path.join(stashDir, "scripts", "readme.txt");
+        writeFile(badFile, "not a script");
+        await expect(resolveAssetPath(stashDir, "script", "readme.txt")).rejects.toThrow("Script ref must resolve to a file with a supported script extension");
+    });
+    test("resolves broader script extensions (e.g. .py)", async () => {
+        const stashDir = createTmpDir();
+        const scriptPath = path.join(stashDir, "scripts", "analyze.py");
+        writeFile(scriptPath, "print('hello')");
+        const result = await resolveAssetPath(stashDir, "script", "analyze.py");
+        expect(result).toBe(fs.realpathSync(scriptPath));
+    });
+    test("resolves skill by directory", async () => {
+        const stashDir = createTmpDir();
+        const skillFile = path.join(stashDir, "skills", "ops", "SKILL.md");
+        writeFile(skillFile, "# Ops Skill");
+        const result = await resolveAssetPath(stashDir, "skill", "ops");
+        expect(result).toBe(fs.realpathSync(skillFile));
+    });
+    test("resolves installed-stash style nested agent refs outside top-level agents root", async () => {
+        const stashDir = createTmpDir();
+        const agentFile = path.join(stashDir, "tools", "agents", "svelte-file-editor.md");
+        writeFile(agentFile, "---\nname: svelte-file-editor\n---\nUse Svelte tools.\n");
+        const result = await resolveAssetPath(stashDir, "agent", "tools/agents/svelte-file-editor");
+        expect(result).toBe(fs.realpathSync(agentFile));
+    });
+    test("resolves installed-stash style nested skill refs outside top-level skills root", async () => {
+        const stashDir = createTmpDir();
+        const skillFile = path.join(stashDir, "tools", "skills", "svelte-code-writer", "SKILL.md");
+        writeFile(skillFile, "# Svelte code writer\n");
+        const result = await resolveAssetPath(stashDir, "skill", "tools/skills/svelte-code-writer");
+        expect(result).toBe(fs.realpathSync(skillFile));
+    });
+});

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

@@ -0,0 +1,221 @@
+import { 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 { findSourceForPath, getPrimarySource, isEditable, resolveAllStashDirs, resolveSourceEntries, } from "../src/indexer/search-source";
+const originalStashDir = process.env.AKM_STASH_DIR;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+let testConfigDir = "";
+let stashDir = "";
+beforeEach(() => {
+    testConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-source-config-"));
+    stashDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-source-stash-"));
+    for (const sub of ["scripts", "skills", "commands", "agents", "knowledge"]) {
+        fs.mkdirSync(path.join(stashDir, sub), { recursive: true });
+    }
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+    process.env.AKM_STASH_DIR = stashDir;
+});
+afterEach(() => {
+    process.env.AKM_STASH_DIR = originalStashDir ?? undefined;
+    if (originalXdgConfigHome === undefined) {
+        delete process.env.XDG_CONFIG_HOME;
+    }
+    else {
+        process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
+    }
+    if (testConfigDir)
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+    if (stashDir)
+        fs.rmSync(stashDir, { recursive: true, force: true });
+});
+describe("resolveSourceEntries", () => {
+    test("returns primary stash as first source", () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const sources = resolveSourceEntries();
+        expect(sources.length).toBeGreaterThanOrEqual(1);
+        expect(sources[0].path).toBe(stashDir);
+        expect(sources[0].registryId).toBeUndefined();
+    });
+    test("includes valid stash paths", () => {
+        const extraDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-extra-"));
+        try {
+            saveConfig({ semanticSearchMode: "off", sources: [{ type: "filesystem", path: extraDir }] });
+            const sources = resolveSourceEntries();
+            expect(sources.length).toBe(2);
+            expect(sources[1].path).toBe(extraDir);
+        }
+        finally {
+            fs.rmSync(extraDir, { recursive: true, force: true });
+        }
+    });
+    test("skips non-existent stash paths", () => {
+        saveConfig({
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: "/nonexistent/path/should/not/exist" }],
+        });
+        const sources = resolveSourceEntries();
+        expect(sources.length).toBe(1);
+    });
+    test("includes installed registry entries with registryId", () => {
+        const installedDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-installed-"));
+        try {
+            saveConfig({
+                semanticSearchMode: "off",
+                installed: [
+                    {
+                        id: "npm:test-pkg",
+                        source: "npm",
+                        ref: "npm:test-pkg@1.0.0",
+                        artifactUrl: "https://example.test/test-pkg.tgz",
+                        stashRoot: installedDir,
+                        cacheDir: installedDir,
+                        installedAt: new Date().toISOString(),
+                    },
+                ],
+            });
+            const sources = resolveSourceEntries();
+            const installed = sources.find((s) => s.registryId === "npm:test-pkg");
+            expect(installed).toBeDefined();
+            expect(installed?.path).toBe(installedDir);
+        }
+        finally {
+            fs.rmSync(installedDir, { recursive: true, force: true });
+        }
+    });
+    test("preserves ordering: primary, stashes, installed", () => {
+        const extraDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-extra-"));
+        const installedDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-installed-"));
+        try {
+            saveConfig({
+                semanticSearchMode: "off",
+                sources: [{ type: "filesystem", path: extraDir }],
+                installed: [
+                    {
+                        id: "npm:test-pkg",
+                        source: "npm",
+                        ref: "npm:test-pkg@1.0.0",
+                        artifactUrl: "https://example.test/test-pkg.tgz",
+                        stashRoot: installedDir,
+                        cacheDir: installedDir,
+                        installedAt: new Date().toISOString(),
+                    },
+                ],
+            });
+            const sources = resolveSourceEntries();
+            expect(sources[0].path).toBe(stashDir);
+            expect(sources[0].registryId).toBeUndefined();
+            expect(sources[1].path).toBe(extraDir);
+            expect(sources[1].registryId).toBeUndefined();
+            expect(sources[2].path).toBe(installedDir);
+            expect(sources[2].registryId).toBe("npm:test-pkg");
+        }
+        finally {
+            fs.rmSync(extraDir, { recursive: true, force: true });
+            fs.rmSync(installedDir, { recursive: true, force: true });
+        }
+    });
+    test("accepts overrideStashDir parameter", () => {
+        const overrideDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-override-"));
+        try {
+            saveConfig({ semanticSearchMode: "off" });
+            const sources = resolveSourceEntries(overrideDir);
+            expect(sources[0].path).toBe(overrideDir);
+        }
+        finally {
+            fs.rmSync(overrideDir, { recursive: true, force: true });
+        }
+    });
+});
+describe("resolveAllStashDirs", () => {
+    test("returns just paths in correct order", () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const dirs = resolveAllStashDirs();
+        expect(dirs[0]).toBe(stashDir);
+    });
+});
+describe("getPrimarySource", () => {
+    test("returns first source from list", () => {
+        const sources = [{ path: stashDir }, { path: "/other/dir" }];
+        const primary = getPrimarySource(sources);
+        expect(primary).toBeDefined();
+        expect(primary?.path).toBe(stashDir);
+    });
+    test("returns undefined for empty list", () => {
+        expect(getPrimarySource([])).toBeUndefined();
+    });
+});
+describe("findSourceForPath", () => {
+    test("finds correct source for file inside primary stash", () => {
+        const sources = [{ path: stashDir }, { path: "/other/dir" }];
+        const filePath = path.join(stashDir, "scripts", "deploy.sh");
+        const result = findSourceForPath(filePath, sources);
+        expect(result).toBeDefined();
+        expect(result?.path).toBe(stashDir);
+    });
+    test("finds correct source for file inside search path", () => {
+        const extraDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-extra-"));
+        try {
+            const sources = [{ path: stashDir }, { path: extraDir }];
+            const filePath = path.join(extraDir, "scripts", "test.sh");
+            const result = findSourceForPath(filePath, sources);
+            expect(result).toBeDefined();
+            expect(result?.path).toBe(extraDir);
+        }
+        finally {
+            fs.rmSync(extraDir, { recursive: true, force: true });
+        }
+    });
+    test("returns undefined for file not in any source", () => {
+        const sources = [{ path: stashDir }];
+        const result = findSourceForPath("/completely/unrelated/path.sh", sources);
+        expect(result).toBeUndefined();
+    });
+});
+describe("isEditable", () => {
+    test("files in primary stash are editable", () => {
+        saveConfig({ semanticSearchMode: "off" });
+        const filePath = path.join(stashDir, "scripts", "deploy.sh");
+        expect(isEditable(filePath)).toBe(true);
+    });
+    test("files in stash paths are editable", () => {
+        const extraDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-extra-"));
+        try {
+            saveConfig({ semanticSearchMode: "off", sources: [{ type: "filesystem", path: extraDir }] });
+            const filePath = path.join(extraDir, "scripts", "deploy.sh");
+            expect(isEditable(filePath)).toBe(true);
+        }
+        finally {
+            fs.rmSync(extraDir, { recursive: true, force: true });
+        }
+    });
+    test("files in cache-managed dirs are NOT editable", () => {
+        const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-cache-"));
+        try {
+            saveConfig({
+                semanticSearchMode: "off",
+                installed: [
+                    {
+                        id: "npm:test-pkg",
+                        source: "npm",
+                        ref: "npm:test-pkg@1.0.0",
+                        artifactUrl: "https://example.test/test-pkg.tgz",
+                        stashRoot: cacheDir,
+                        cacheDir: cacheDir,
+                        installedAt: new Date().toISOString(),
+                    },
+                ],
+            });
+            const filePath = path.join(cacheDir, "scripts", "deploy.sh");
+            expect(isEditable(filePath)).toBe(false);
+        }
+        finally {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+    });
+    test("files outside any known path are editable", () => {
+        saveConfig({ semanticSearchMode: "off" });
+        expect(isEditable("/some/random/path/file.sh")).toBe(true);
+    });
+});