akm-cli 0.6.1 → 0.7.0-rc1

package/dist/tests/setup-wizard.test.js

@@ -0,0 +1,198 @@
+/**
+ * Tests for setup wizard interactive logic:
+ * - onCancel: Escape on confirmation should stay, not exit
+ * - stepAddSources: recommended GitHub repos multiselect, cancel returns to menu
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+// ── Mock plumbing ────────────────────────────────────────────────────────────
+/** Sentinel returned by mocked prompts when simulating Escape / Ctrl-C. */
+const CANCEL = Symbol("clack:cancel");
+/** Per-test response queues — shift one value per prompt call. */
+const q = {
+    confirms: [],
+    selects: [],
+    texts: [],
+    multiselects: [],
+    logged: [],
+};
+function reset() {
+    q.confirms.length = 0;
+    q.selects.length = 0;
+    q.texts.length = 0;
+    q.multiselects.length = 0;
+    q.logged.length = 0;
+}
+// Must be called **before** any module that imports @clack/prompts is loaded.
+mock.module("@clack/prompts", () => ({
+    isCancel: (v) => v === CANCEL,
+    cancel: (msg) => {
+        q.logged.push(`[cancel] ${msg}`);
+    },
+    confirm: async () => q.confirms.shift() ?? false,
+    select: async () => q.selects.shift() ?? "done",
+    text: async () => q.texts.shift() ?? "",
+    multiselect: async () => q.multiselects.shift() ?? [],
+    spinner: () => ({ start: () => { }, stop: () => { } }),
+    log: {
+        info: (msg) => {
+            q.logged.push(msg);
+        },
+        success: (msg) => {
+            q.logged.push(msg);
+        },
+        warn: (msg) => {
+            q.logged.push(msg);
+        },
+        step: () => { },
+    },
+    intro: () => { },
+    outro: () => { },
+    note: (msg, title) => {
+        q.logged.push(`[note] ${title ?? ""} ${msg}`.trim());
+    },
+}));
+// ── onCancel tests ───────────────────────────────────────────────────────────
+describe("onCancel – escape handling", () => {
+    beforeEach(reset);
+    test("pressing Escape on the exit-confirmation stays in the wizard", async () => {
+        const { onCancel } = await import("../src/setup/setup");
+        // Simulate: user already pressed Escape in a prompt (value = CANCEL),
+        // then presses Escape again on the "Exit the wizard?" confirmation.
+        q.confirms.push(CANCEL);
+        const stayed = await onCancel(CANCEL);
+        expect(stayed).toBe(true);
+    });
+    test("choosing No on the exit-confirmation stays in the wizard", async () => {
+        const { onCancel } = await import("../src/setup/setup");
+        q.confirms.push(false);
+        const stayed = await onCancel(CANCEL);
+        expect(stayed).toBe(true);
+    });
+    test("choosing Yes on the exit-confirmation calls bail (exits)", async () => {
+        const { onCancel } = await import("../src/setup/setup");
+        q.confirms.push(true);
+        // bail() calls process.exit — mock it so it throws instead of killing the runner
+        const originalExit = process.exit;
+        process.exit = ((code) => {
+            throw new Error(`EXIT:${code}`);
+        });
+        try {
+            await expect(onCancel(CANCEL)).rejects.toThrow("EXIT:0");
+        }
+        finally {
+            process.exit = originalExit;
+        }
+    });
+    test("non-cancel input is a no-op (returns false)", async () => {
+        const { onCancel } = await import("../src/setup/setup");
+        const stayed = await onCancel("normal-value");
+        expect(stayed).toBe(false);
+    });
+});
+// ── stepAddSources tests ───────────────────────────────────────────────────
+describe("stepAddSources – recommended GitHub repos", () => {
+    beforeEach(reset);
+    test("with no recommended repos configured, the multiselect prompt is skipped", async () => {
+        const { stepAddSources } = await import("../src/setup/setup");
+        // No multiselect should be consumed because the recommended-repos array
+        // is empty. Only the "Add another source?" select should be needed.
+        q.selects.push("done");
+        const result = await stepAddSources({ sources: [] });
+        expect(result).toEqual([]);
+        // multiselect queue should still be empty (nothing pushed, nothing consumed)
+        expect(q.multiselects.length).toBe(0);
+    });
+    test("preserves an existing git stash that points at the legacy context-hub URL", async () => {
+        const { stepAddSources } = await import("../src/setup/setup");
+        const ctxHubUrl = "https://github.com/andrewyng/context-hub";
+        const cfg = {
+            sources: [{ type: "git", url: ctxHubUrl, name: "context-hub" }],
+        };
+        q.selects.push("done");
+        const result = await stepAddSources(cfg);
+        const hub = result.find((s) => s.url === ctxHubUrl);
+        expect(hub).toBeDefined();
+        expect(hub?.type).toBe("git");
+    });
+});
+describe("semantic search setup", () => {
+    beforeEach(reset);
+    test("should list local model and sqlite-vec guidance when describing semantic search assets", async () => {
+        const { describeSemanticSearchAssets } = await import("../src/setup/setup");
+        const assets = describeSemanticSearchAssets();
+        expect(assets[0]).toContain("Local embedding model");
+        expect(assets[0]).toContain("download");
+        expect(assets[1]).toContain("sqlite-vec");
+    });
+    test("stepSemanticSearch returns disabled when user opts out", async () => {
+        const { stepSemanticSearch } = await import("../src/setup/setup");
+        q.confirms.push(false);
+        const result = await stepSemanticSearch({ semanticSearchMode: "auto" });
+        expect(result).toEqual({ mode: "off", prepareAssets: false });
+    });
+    test("stepSemanticSearch shows assets and allows asset preparation", async () => {
+        const { stepSemanticSearch } = await import("../src/setup/setup");
+        q.confirms.push(true, true);
+        const result = await stepSemanticSearch({ semanticSearchMode: "auto" });
+        expect(result).toEqual({ mode: "auto", prepareAssets: true });
+        expect(q.logged.some((entry) => entry.includes("Semantic Search Assets"))).toBe(true);
+    });
+});
+describe("stepAddSources – custom GitHub repo", () => {
+    beforeEach(reset);
+    test("adds a custom GitHub repo with type 'git'", async () => {
+        const { stepAddSources } = await import("../src/setup/setup");
+        // multiselect recommended repos → none
+        q.multiselects.push([]);
+        // select "Add another source?" → "github-repo"
+        q.selects.push("github-repo");
+        // text: GitHub URL
+        q.texts.push("https://github.com/owner/repo");
+        // text: name
+        q.texts.push("my-repo");
+        // select → done
+        q.selects.push("done");
+        const result = await stepAddSources({ sources: [] });
+        const repo = result.find((s) => s.url === "https://github.com/owner/repo");
+        expect(repo).toBeDefined();
+        expect(repo?.type).toBe("git");
+        expect(repo?.name).toBe("my-repo");
+    });
+});
+describe("stepAddSources – cancel within sub-actions", () => {
+    beforeEach(reset);
+    test("pressing Escape on a sub-action text prompt returns to menu", async () => {
+        const { stepAddSources } = await import("../src/setup/setup");
+        // multiselect recommended → none
+        q.multiselects.push([]);
+        // select → github-repo
+        q.selects.push("github-repo");
+        // text: press Escape (cancel) → should return to menu, not re-prompt
+        q.texts.push(CANCEL);
+        // back at menu → done
+        q.selects.push("done");
+        const result = await stepAddSources({ sources: [] });
+        // No repo was added because the user cancelled
+        expect(result).toEqual([]);
+    });
+    test("pressing Escape on filesystem path returns to menu", async () => {
+        const { stepAddSources } = await import("../src/setup/setup");
+        q.multiselects.push([]);
+        q.selects.push("filesystem");
+        q.texts.push(CANCEL); // cancel the path prompt
+        q.selects.push("done");
+        const result = await stepAddSources({ sources: [] });
+        expect(result).toEqual([]);
+    });
+    test("pressing Escape on name prompt returns to menu without adding", async () => {
+        const { stepAddSources } = await import("../src/setup/setup");
+        q.multiselects.push([]);
+        q.selects.push("github-repo");
+        q.texts.push("https://github.com/owner/repo"); // provide URL
+        q.texts.push(CANCEL); // cancel on name prompt
+        q.selects.push("done");
+        const result = await stepAddSources({ sources: [] });
+        // Repo was NOT added because user cancelled at the name step
+        expect(result).toEqual([]);
+    });
+});

package/dist/tests/setup.test.js

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// ── detect.ts tests ─────────────────────────────────────────────────────────
+describe("detectAgentPlatforms", () => {
+    let testHome;
+    const originalHome = process.env.HOME;
+    beforeEach(() => {
+        testHome = fs.mkdtempSync(path.join(os.tmpdir(), "akm-detect-"));
+        process.env.HOME = testHome;
+    });
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        fs.rmSync(testHome, { recursive: true, force: true });
+    });
+    test("returns empty array when no platforms found", async () => {
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        expect(result).toEqual([]);
+    });
+    test("detects .claude directory", async () => {
+        fs.mkdirSync(path.join(testHome, ".claude"), { recursive: true });
+        // Re-import to pick up fresh HOME
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        const claude = result.find((p) => p.name === "Claude Code");
+        expect(claude).toBeDefined();
+        expect(claude?.path).toBe(path.join(testHome, ".claude"));
+    });
+    test("detects .config/opencode directory", async () => {
+        fs.mkdirSync(path.join(testHome, ".config", "opencode"), { recursive: true });
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        const opencode = result.find((p) => p.name === "OpenCode");
+        expect(opencode).toBeDefined();
+        expect(opencode?.path).toBe(path.join(testHome, ".config", "opencode"));
+    });
+    test("detects multiple platforms", async () => {
+        fs.mkdirSync(path.join(testHome, ".claude"), { recursive: true });
+        fs.mkdirSync(path.join(testHome, ".cursor"), { recursive: true });
+        fs.mkdirSync(path.join(testHome, ".continue"), { recursive: true });
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        expect(result.length).toBeGreaterThanOrEqual(3);
+    });
+    test("ignores files (only detects directories)", async () => {
+        fs.writeFileSync(path.join(testHome, ".claude"), "not a directory");
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        const claude = result.find((p) => p.name === "Claude Code");
+        expect(claude).toBeUndefined();
+    });
+    test("returns empty when HOME and USERPROFILE are both unset", async () => {
+        delete process.env.HOME;
+        delete process.env.USERPROFILE;
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        expect(result).toEqual([]);
+    });
+    test("falls back to USERPROFILE when HOME is unset (Windows)", async () => {
+        delete process.env.HOME;
+        process.env.USERPROFILE = testHome;
+        fs.mkdirSync(path.join(testHome, ".claude"), { recursive: true });
+        const { detectAgentPlatforms } = await import("../src/setup/detect");
+        const result = detectAgentPlatforms();
+        const claude = result.find((p) => p.name === "Claude Code");
+        expect(claude).toBeDefined();
+        expect(claude?.path).toBe(path.join(testHome, ".claude"));
+        delete process.env.USERPROFILE;
+    });
+});
+describe("detectOllama", () => {
+    let originalFetch;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    test("returns available=true with models from API", async () => {
+        globalThis.fetch = (async (input) => {
+            const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+            if (url.includes("/api/tags")) {
+                return new Response(JSON.stringify({
+                    models: [{ name: "llama3.2:latest" }, { name: "nomic-embed-text:latest" }, { name: "codellama:latest" }],
+                }), { status: 200 });
+            }
+            return new Response("", { status: 404 });
+        });
+        const { detectOllama } = await import("../src/setup/detect");
+        const result = await detectOllama();
+        expect(result.available).toBe(true);
+        expect(result.models).toContain("llama3.2");
+        expect(result.models).toContain("nomic-embed-text");
+        expect(result.models).toContain("codellama");
+    });
+    test("strips :latest suffix from model names", async () => {
+        globalThis.fetch = (async () => {
+            return new Response(JSON.stringify({
+                models: [{ name: "llama3.2:latest" }, { name: "phi3:v2" }],
+            }), { status: 200 });
+        });
+        const { detectOllama } = await import("../src/setup/detect");
+        const result = await detectOllama();
+        expect(result.models).toContain("llama3.2");
+        expect(result.models).toContain("phi3:v2");
+        expect(result.models).not.toContain("llama3.2:latest");
+    });
+    test("returns available=false when fetch fails", async () => {
+        globalThis.fetch = (async () => {
+            throw new Error("Connection refused");
+        });
+        const { detectOllama } = await import("../src/setup/detect");
+        const result = await detectOllama();
+        // May still be available=true if `ollama list` CLI works, or false if both fail
+        // Just verify it doesn't throw
+        expect(typeof result.available).toBe("boolean");
+        expect(Array.isArray(result.models)).toBe(true);
+    });
+    test("returns sorted model names", async () => {
+        globalThis.fetch = (async () => {
+            return new Response(JSON.stringify({
+                models: [{ name: "zephyr:latest" }, { name: "alpaca:latest" }, { name: "mistral:latest" }],
+            }), { status: 200 });
+        });
+        const { detectOllama } = await import("../src/setup/detect");
+        const result = await detectOllama();
+        expect(result.models).toEqual(["alpaca", "mistral", "zephyr"]);
+    });
+});

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

@@ -0,0 +1,11 @@
+import { describe, expect, test } from "bun:test";
+import { shouldAddAsWebsiteUrl } from "../src/commands/source-add";
+describe("shouldAddAsWebsiteUrl", () => {
+    test("treats docs-style URLs as website sources", () => {
+        expect(shouldAddAsWebsiteUrl("https://docs.example.com/guide")).toBe(true);
+    });
+    test("keeps known git hosts on the registry install path", () => {
+        expect(shouldAddAsWebsiteUrl("https://gitlab.com/acme/project")).toBe(false);
+        expect(shouldAddAsWebsiteUrl("https://example.com/acme/project.git")).toBe(false);
+    });
+});

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

@@ -0,0 +1,254 @@
+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 { akmClone } from "../src/commands/source-clone";
+import { saveConfig } from "../src/core/config";
+import { UsageError } from "../src/core/errors";
+const originalStashDir = process.env.AKM_STASH_DIR;
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+let testConfigDir = "";
+let testCacheDir = "";
+let stashDir = "";
+let searchPathDir = "";
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+}
+function createStashDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+        fs.mkdirSync(path.join(dir, sub), { recursive: true });
+    }
+    return dir;
+}
+beforeEach(() => {
+    testConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-clone-config-"));
+    testCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-clone-cache-"));
+    stashDir = createStashDir("akm-clone-working-");
+    searchPathDir = createStashDir("akm-clone-searchpath-");
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+    process.env.XDG_CACHE_HOME = testCacheDir;
+    process.env.AKM_STASH_DIR = stashDir;
+    saveConfig({
+        semanticSearchMode: "off",
+        sources: [{ type: "filesystem", path: searchPathDir }],
+    });
+});
+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 (originalXdgCacheHome === undefined)
+        delete process.env.XDG_CACHE_HOME;
+    else
+        process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    for (const dir of [testConfigDir, testCacheDir, stashDir, searchPathDir]) {
+        if (dir)
+            fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("akmClone", () => {
+    test("clones a script from search path to primary stash", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "#!/bin/bash\necho deploy\n");
+        const result = await akmClone({ sourceRef: "script:deploy.sh" });
+        expect(result.destination.ref).toContain("script:deploy.sh");
+        expect(result.overwritten).toBe(false);
+        expect(fs.existsSync(path.join(stashDir, "scripts", "deploy.sh"))).toBe(true);
+        expect(fs.readFileSync(path.join(stashDir, "scripts", "deploy.sh"), "utf8")).toBe("#!/bin/bash\necho deploy\n");
+    });
+    test("clones a skill directory", async () => {
+        writeFile(path.join(searchPathDir, "skills", "review", "SKILL.md"), "# Review Skill\n");
+        writeFile(path.join(searchPathDir, "skills", "review", "helper.md"), "# Helper\n");
+        const result = await akmClone({ sourceRef: "skill:review" });
+        expect(result.overwritten).toBe(false);
+        expect(fs.existsSync(path.join(stashDir, "skills", "review", "SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(stashDir, "skills", "review", "helper.md"))).toBe(true);
+    });
+    test("clones with a new name", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo deploy\n");
+        const result = await akmClone({ sourceRef: "script:deploy.sh", newName: "my-deploy.sh" });
+        expect(fs.existsSync(path.join(stashDir, "scripts", "my-deploy.sh"))).toBe(true);
+        expect(result.destination.ref).toContain("my-deploy.sh");
+    });
+    test("throws when asset already exists without --force", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo original\n");
+        writeFile(path.join(stashDir, "scripts", "deploy.sh"), "echo existing\n");
+        await expect(akmClone({ sourceRef: `${searchPathDir}//script:deploy.sh` })).rejects.toThrow("already exists");
+    });
+    test("overwrites with --force", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo updated\n");
+        writeFile(path.join(stashDir, "scripts", "deploy.sh"), "echo old\n");
+        const result = await akmClone({ sourceRef: `${searchPathDir}//script:deploy.sh`, force: true });
+        expect(result.overwritten).toBe(true);
+        expect(fs.readFileSync(path.join(stashDir, "scripts", "deploy.sh"), "utf8")).toBe("echo updated\n");
+    });
+    test("force overwrite removes stale files from skill directory", async () => {
+        // Source skill has only SKILL.md
+        writeFile(path.join(searchPathDir, "skills", "review", "SKILL.md"), "# Updated\n");
+        // Existing working skill has an extra file
+        writeFile(path.join(stashDir, "skills", "review", "SKILL.md"), "# Old\n");
+        writeFile(path.join(stashDir, "skills", "review", "stale.md"), "# Stale\n");
+        await akmClone({ sourceRef: `${searchPathDir}//skill:review`, force: true });
+        expect(fs.existsSync(path.join(stashDir, "skills", "review", "SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(stashDir, "skills", "review", "stale.md"))).toBe(false);
+    });
+    test("throws when source asset not found", async () => {
+        await expect(akmClone({ sourceRef: "script:nonexistent.sh" })).rejects.toThrow();
+    });
+    test("clones from working stash to itself with new name", async () => {
+        writeFile(path.join(stashDir, "scripts", "original.sh"), "echo original\n");
+        const _result = await akmClone({ sourceRef: "script:original.sh", newName: "copy.sh" });
+        expect(fs.existsSync(path.join(stashDir, "scripts", "copy.sh"))).toBe(true);
+    });
+    test("throws when self-cloning a script without rename", async () => {
+        writeFile(path.join(stashDir, "scripts", "deploy.sh"), "echo deploy\n");
+        await expect(akmClone({ sourceRef: "script:deploy.sh" })).rejects.toThrow("same path");
+        // Verify the file was not destroyed
+        expect(fs.readFileSync(path.join(stashDir, "scripts", "deploy.sh"), "utf8")).toBe("echo deploy\n");
+    });
+    test("throws when self-cloning a skill without rename", async () => {
+        writeFile(path.join(stashDir, "skills", "review", "SKILL.md"), "# Review\n");
+        await expect(akmClone({ sourceRef: "skill:review" })).rejects.toThrow("same path");
+        // Verify the skill was not destroyed
+        expect(fs.existsSync(path.join(stashDir, "skills", "review", "SKILL.md"))).toBe(true);
+    });
+    describe("newName validation", () => {
+        beforeEach(() => {
+            writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo deploy\n");
+            writeFile(path.join(searchPathDir, "skills", "review", "SKILL.md"), "# Review\n");
+        });
+        test("throws on empty string newName", async () => {
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "" })).rejects.toThrow(UsageError);
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "" })).rejects.toThrow(/empty/);
+        });
+        test("throws on '.' as newName", async () => {
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "." })).rejects.toThrow(UsageError);
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "." })).rejects.toThrow(/Unsafe/);
+        });
+        test("throws on '..' as newName", async () => {
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: ".." })).rejects.toThrow(UsageError);
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: ".." })).rejects.toThrow(/Unsafe/);
+        });
+        test("throws on path-traversal newName", async () => {
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "../escape.sh" })).rejects.toThrow(UsageError);
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "../escape.sh" })).rejects.toThrow(/Unsafe/);
+        });
+        test("throws on absolute path as newName", async () => {
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "/etc/evil.sh" })).rejects.toThrow(UsageError);
+            await expect(akmClone({ sourceRef: "script:deploy.sh", newName: "/etc/evil.sh" })).rejects.toThrow(/Unsafe/);
+        });
+        test("empty newName does not wipe the type directory for skills", async () => {
+            writeFile(path.join(stashDir, "skills", "existing", "SKILL.md"), "# Existing\n");
+            await expect(akmClone({ sourceRef: "skill:review", newName: "", force: true })).rejects.toThrow(UsageError);
+            // Existing skill must be untouched
+            expect(fs.existsSync(path.join(stashDir, "skills", "existing", "SKILL.md"))).toBe(true);
+        });
+    });
+});
+describe("akmClone --dest", () => {
+    let customDest;
+    beforeEach(() => {
+        customDest = fs.mkdtempSync(path.join(os.tmpdir(), "akm-clone-dest-"));
+    });
+    afterEach(() => {
+        if (customDest)
+            fs.rmSync(customDest, { recursive: true, force: true });
+    });
+    test("clones script to custom destination preserving type dir structure", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "#!/bin/bash\necho deploy\n");
+        const result = await akmClone({ sourceRef: "script:deploy.sh", dest: customDest });
+        expect(result.destination.path).toBe(path.join(customDest, "scripts", "deploy.sh"));
+        expect(fs.existsSync(path.join(customDest, "scripts", "deploy.sh"))).toBe(true);
+        expect(fs.readFileSync(path.join(customDest, "scripts", "deploy.sh"), "utf8")).toBe("#!/bin/bash\necho deploy\n");
+        // Working stash should NOT have the file
+        expect(fs.existsSync(path.join(stashDir, "scripts", "deploy.sh"))).toBe(false);
+    });
+    test("clones skill directory to custom destination", async () => {
+        writeFile(path.join(searchPathDir, "skills", "review", "SKILL.md"), "# Review Skill\n");
+        writeFile(path.join(searchPathDir, "skills", "review", "helper.md"), "# Helper\n");
+        const result = await akmClone({ sourceRef: "skill:review", dest: customDest });
+        expect(fs.existsSync(path.join(customDest, "skills", "review", "SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(customDest, "skills", "review", "helper.md"))).toBe(true);
+        expect(result.overwritten).toBe(false);
+    });
+    test("--dest does not require a working stash", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo deploy\n");
+        // Point AKM_STASH_DIR to a non-existent directory to simulate no working stash
+        process.env.AKM_STASH_DIR = path.join(os.tmpdir(), `nonexistent-stash-${Date.now()}`);
+        const result = await akmClone({
+            sourceRef: `${searchPathDir}//script:deploy.sh`,
+            dest: customDest,
+        });
+        expect(fs.existsSync(path.join(customDest, "scripts", "deploy.sh"))).toBe(true);
+        expect(result.destination.path).toBe(path.join(customDest, "scripts", "deploy.sh"));
+    });
+    test("--dest with --force overwrites at custom destination", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo updated\n");
+        writeFile(path.join(customDest, "scripts", "deploy.sh"), "echo old\n");
+        const result = await akmClone({
+            sourceRef: `${searchPathDir}//script:deploy.sh`,
+            force: true,
+            dest: customDest,
+        });
+        expect(result.overwritten).toBe(true);
+        expect(fs.readFileSync(path.join(customDest, "scripts", "deploy.sh"), "utf8")).toBe("echo updated\n");
+    });
+    test("throws when asset exists at --dest without --force", async () => {
+        writeFile(path.join(searchPathDir, "scripts", "deploy.sh"), "echo new\n");
+        writeFile(path.join(customDest, "scripts", "deploy.sh"), "echo existing\n");
+        await expect(akmClone({ sourceRef: `${searchPathDir}//script:deploy.sh`, dest: customDest })).rejects.toThrow("already exists at destination");
+    });
+});
+describe("akmClone remote", () => {
+    let remoteFixtureDir;
+    beforeEach(() => {
+        // Create a fixture directory that simulates a remote package
+        remoteFixtureDir = createStashDir("akm-clone-remote-fixture-");
+        writeFile(path.join(remoteFixtureDir, "scripts", "remote-tool.sh"), "#!/bin/bash\necho remote\n");
+        writeFile(path.join(remoteFixtureDir, "skills", "remote-skill", "SKILL.md"), "# Remote Skill\n");
+    });
+    afterEach(() => {
+        if (remoteFixtureDir)
+            fs.rmSync(remoteFixtureDir, { recursive: true, force: true });
+    });
+    test("clones a script from a remote origin via installRegistryRef", async () => {
+        // Use bare path as origin — not in stashes, so isRemoteOrigin returns true
+        const result = await akmClone({
+            sourceRef: `${remoteFixtureDir}//script:remote-tool.sh`,
+        });
+        expect(result.remoteFetched).toBeDefined();
+        expect(result.remoteFetched?.origin).toBe(remoteFixtureDir);
+        expect(fs.existsSync(path.join(stashDir, "scripts", "remote-tool.sh"))).toBe(true);
+        expect(fs.readFileSync(path.join(stashDir, "scripts", "remote-tool.sh"), "utf8")).toBe("#!/bin/bash\necho remote\n");
+    });
+    test("returns remoteFetched metadata", async () => {
+        const result = await akmClone({
+            sourceRef: `${remoteFixtureDir}//script:remote-tool.sh`,
+        });
+        expect(result.remoteFetched).toBeDefined();
+        expect(result.remoteFetched?.stashRoot).toBeTruthy();
+        expect(result.remoteFetched?.cacheDir).toBeTruthy();
+    });
+    test("throws when remote fetch succeeds but asset not found in package", async () => {
+        await expect(akmClone({ sourceRef: `${remoteFixtureDir}//script:nonexistent.sh` })).rejects.toThrow("not found");
+    });
+    test("clones from remote origin to custom destination", async () => {
+        const customDest = fs.mkdtempSync(path.join(os.tmpdir(), "akm-clone-remote-dest-"));
+        try {
+            const result = await akmClone({
+                sourceRef: `${remoteFixtureDir}//script:remote-tool.sh`,
+                dest: customDest,
+            });
+            expect(result.remoteFetched).toBeDefined();
+            expect(fs.existsSync(path.join(customDest, "scripts", "remote-tool.sh"))).toBe(true);
+            expect(result.destination.path).toBe(path.join(customDest, "scripts", "remote-tool.sh"));
+        }
+        finally {
+            fs.rmSync(customDest, { recursive: true, force: true });
+        }
+    });
+});