akm-cli 0.6.1 → 0.7.0

package/dist/tests/registry-providers/static-index.test.js

@@ -0,0 +1,238 @@
+/**
+ * Phase 6 (v1 architecture refactor) — coverage for the `static-index`
+ * registry provider exercised through the full `RegistryProvider` interface
+ * (`search`, `searchKits`, `searchAssets`, `getKit`, `canHandle`).
+ *
+ * These tests are intentionally siloed from the orchestrator-level tests in
+ * `tests/registry-search.test.ts`: they hit the provider directly to make sure
+ * the v1-spec §3.1 surface contracts hold for the default provider.
+ */
+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 { resolveProviderFactory } from "../../src/registry/factory";
+// Trigger self-registration
+import "../../src/registry/providers/static-index";
+// ── Fixtures ────────────────────────────────────────────────────────────────
+const FIXTURE_INDEX = {
+    version: 3,
+    updatedAt: "2026-04-25T00:00:00Z",
+    stashes: [
+        {
+            id: "github:vercel-labs/agent-skills",
+            name: "agent-skills",
+            description: "Production-ready agent skills",
+            ref: "vercel-labs/agent-skills",
+            source: "github",
+            tags: ["agent", "skills"],
+            assetTypes: ["skill"],
+            assets: [
+                { type: "skill", name: "deploy", description: "Deploy to Vercel" },
+                { type: "skill", name: "rollback" },
+            ],
+            author: "vercel-labs",
+            latestVersion: "1.0.0",
+        },
+        {
+            id: "npm:@itlackey/openkit",
+            name: "@itlackey/openkit",
+            description: "OpenCode starter",
+            ref: "@itlackey/openkit",
+            source: "npm",
+            tags: ["opencode", "starter"],
+            author: "itlackey",
+        },
+    ],
+};
+// ── Helpers ─────────────────────────────────────────────────────────────────
+const createdTmpDirs = [];
+const servers = [];
+function createTmpDir(prefix = "akm-static-index-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    createdTmpDirs.push(dir);
+    return dir;
+}
+function serveJson(body) {
+    const server = Bun.serve({
+        port: 0,
+        fetch() {
+            return new Response(JSON.stringify(body), {
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+    });
+    servers.push(server);
+    return {
+        url: `http://localhost:${server.port}/index.json`,
+        close: () => server.stop(true),
+    };
+}
+function makeProvider(url, name = "official") {
+    const factory = resolveProviderFactory("static-index");
+    if (!factory)
+        throw new Error("static-index provider not registered");
+    return factory({ url, name });
+}
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+beforeEach(() => {
+    process.env.XDG_CACHE_HOME = createTmpDir("akm-si-cache-");
+});
+afterEach(() => {
+    for (const s of servers) {
+        try {
+            s.stop(true);
+        }
+        catch {
+            /* already stopped */
+        }
+    }
+    servers.length = 0;
+    if (originalXdgCacheHome === undefined) {
+        delete process.env.XDG_CACHE_HOME;
+    }
+    else {
+        process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    }
+});
+afterAll(() => {
+    for (const dir of createdTmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+// ── Tests ───────────────────────────────────────────────────────────────────
+describe("StaticIndexProvider", () => {
+    test("factory is registered", () => {
+        expect(resolveProviderFactory("static-index")).not.toBeNull();
+    });
+    describe("searchKits (v1-spec §3.1)", () => {
+        test("returns KitResult entries with installRef", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const kits = await provider.searchKits({ text: "skills", limit: 10 });
+            expect(kits.length).toBeGreaterThan(0);
+            for (const kit of kits) {
+                expect(typeof kit.id).toBe("string");
+                expect(typeof kit.title).toBe("string");
+                expect(typeof kit.installRef).toBe("string");
+            }
+        });
+        test("kit installRef is a valid akm add target", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const kits = await provider.searchKits({ text: "agent", limit: 10 });
+            const githubKit = kits.find((k) => k.id.startsWith("github:"));
+            expect(githubKit?.installRef).toBe("github:vercel-labs/agent-skills");
+        });
+        test("respects limit", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const kits = await provider.searchKits({ text: "agent skills opencode", limit: 1 });
+            expect(kits.length).toBeLessThanOrEqual(1);
+        });
+    });
+    describe("searchAssets (v1-spec §3.1)", () => {
+        test("returns AssetPreview entries scoped to kits", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const assets = await provider.searchAssets?.({ text: "deploy", limit: 10 });
+            expect(assets).toBeDefined();
+            const deploy = assets?.find((a) => a.name === "deploy");
+            expect(deploy?.type).toBe("skill");
+            expect(deploy?.kitId).toBe("github:vercel-labs/agent-skills");
+            expect(deploy?.cloneRef).toBe("github:vercel-labs/agent-skills");
+        });
+    });
+    describe("getKit (v1-spec §3.1)", () => {
+        test("returns a KitManifest for a known id", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const manifest = await provider.getKit("github:vercel-labs/agent-skills");
+            expect(manifest).not.toBeNull();
+            expect(manifest?.id).toBe("github:vercel-labs/agent-skills");
+            expect(manifest?.installRef).toBe("github:vercel-labs/agent-skills");
+            expect(manifest?.assets?.length ?? 0).toBeGreaterThan(0);
+        });
+        test("returns null for an unknown id", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const manifest = await provider.getKit("github:does-not-exist/anywhere");
+            expect(manifest).toBeNull();
+        });
+        test("preserves npm install refs", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const manifest = await provider.getKit("npm:@itlackey/openkit");
+            expect(manifest?.installRef).toBe("npm:@itlackey/openkit");
+        });
+    });
+    describe("canHandle (plan §9 item 2)", () => {
+        test("claims github refs", () => {
+            const srv = serveJson({ stashes: [] });
+            const provider = makeProvider(srv.url);
+            const ref = {
+                source: "github",
+                ref: "owner/repo",
+                id: "github:owner/repo",
+                owner: "owner",
+                repo: "repo",
+            };
+            expect(provider.canHandle(ref)).toBe(true);
+        });
+        test("claims npm refs (default catch-all)", () => {
+            const srv = serveJson({ stashes: [] });
+            const provider = makeProvider(srv.url);
+            const ref = {
+                source: "npm",
+                ref: "npm:foo",
+                id: "npm:foo",
+                packageName: "foo",
+            };
+            expect(provider.canHandle(ref)).toBe(true);
+        });
+    });
+    describe("backwards-compat search", () => {
+        test("legacy search() still returns RegistrySearchHit shape", async () => {
+            const srv = serveJson(FIXTURE_INDEX);
+            const provider = makeProvider(srv.url);
+            const result = await provider.search({ query: "agent", limit: 10 });
+            expect(Array.isArray(result.hits)).toBe(true);
+            const hit = result.hits.find((h) => h.id === "github:vercel-labs/agent-skills");
+            expect(hit?.installRef).toBe("github:vercel-labs/agent-skills");
+        });
+    });
+    describe("registry version contract", () => {
+        test("version 3 index parses without warnings (canonical format)", async () => {
+            const srv = serveJson(FIXTURE_INDEX); // FIXTURE_INDEX has version: 3
+            const provider = makeProvider(srv.url);
+            const result = await provider.search({ query: "agent", limit: 10 });
+            expect(result.warnings ?? []).toHaveLength(0);
+            expect(result.hits.length).toBeGreaterThan(0);
+        });
+        test("version 2 index parses without warnings (live official registry format)", async () => {
+            const v2Index = { ...FIXTURE_INDEX, version: 2 };
+            const srv = serveJson(v2Index);
+            const provider = makeProvider(srv.url);
+            const result = await provider.search({ query: "agent", limit: 10 });
+            expect(result.warnings ?? []).toHaveLength(0);
+            expect(result.hits.length).toBeGreaterThan(0);
+        });
+        test("version 2 index returns correct kit hits", async () => {
+            const v2Index = { ...FIXTURE_INDEX, version: 2 };
+            const srv = serveJson(v2Index);
+            const provider = makeProvider(srv.url);
+            const kits = await provider.searchKits({ text: "agent", limit: 10 });
+            expect(kits.length).toBeGreaterThan(0);
+            expect(kits.some((k) => k.id === "github:vercel-labs/agent-skills")).toBe(true);
+        });
+        test("version 1 index returns null (unsupported)", async () => {
+            // version 1 is explicitly unsupported per schema comment
+            const v1Index = { ...FIXTURE_INDEX, version: 1 };
+            const srv = serveJson(v1Index);
+            const provider = makeProvider(srv.url);
+            const result = await provider.search({ query: "agent", limit: 10 });
+            // No hits because the parser returns null for unsupported versions
+            expect(result.hits).toHaveLength(0);
+        });
+    });
+});

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

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { UsageError } from "../src/core/errors";
+import { trustedNpmTarballHosts, UntrustedNpmTarballError, validateGitRef, validateGitUrl, validateNpmTarballUrl, } from "../src/registry/resolve";
+// ── validateGitUrl ───────────────────────────────────────────────────────────
+describe("validateGitUrl", () => {
+    // ── Rejected schemes ──────────────────────────────────────────────────────
+    test("rejects ext:: protocol helper (arbitrary command execution)", () => {
+        expect(() => validateGitUrl("ext::evil-command arg")).toThrow(UsageError);
+    });
+    test("rejects fd:: protocol helper", () => {
+        expect(() => validateGitUrl("fd::5")).toThrow(UsageError);
+    });
+    test("rejects file:// scheme (local path traversal)", () => {
+        expect(() => validateGitUrl("file:///etc/passwd")).toThrow(UsageError);
+    });
+    test("rejects ftp:// scheme", () => {
+        expect(() => validateGitUrl("ftp://example.com/repo")).toThrow(UsageError);
+    });
+    test("rejects completely invalid URLs", () => {
+        expect(() => validateGitUrl("not a url at all !!")).toThrow(UsageError);
+    });
+    // ── Accepted schemes ──────────────────────────────────────────────────────
+    test("accepts https:// URLs", () => {
+        expect(() => validateGitUrl("https://github.com/valid/repo.git")).not.toThrow();
+    });
+    test("accepts http:// URLs", () => {
+        expect(() => validateGitUrl("http://internal.example.com/repo.git")).not.toThrow();
+    });
+    test("accepts ssh:// URLs", () => {
+        expect(() => validateGitUrl("ssh://git@github.com/org/repo.git")).not.toThrow();
+    });
+    test("accepts git:// URLs", () => {
+        expect(() => validateGitUrl("git://github.com/org/repo.git")).not.toThrow();
+    });
+    test("accepts git@ SSH shorthand", () => {
+        expect(() => validateGitUrl("git@github.com:org/repo.git")).not.toThrow();
+    });
+    test("accepts git@ SSH shorthand with subdomain", () => {
+        expect(() => validateGitUrl("git@gitlab.example.com:group/subgroup/repo.git")).not.toThrow();
+    });
+});
+// ── validateGitRef ───────────────────────────────────────────────────────────
+describe("validateGitRef", () => {
+    // ── Rejected patterns ─────────────────────────────────────────────────────
+    test("rejects refs with semicolons", () => {
+        expect(() => validateGitRef("main;rm -rf /")).toThrow(UsageError);
+    });
+    test("rejects refs with spaces", () => {
+        expect(() => validateGitRef("main branch")).toThrow(UsageError);
+    });
+    test("rejects refs with shell special chars", () => {
+        expect(() => validateGitRef("$(evil)")).toThrow(UsageError);
+        expect(() => validateGitRef("`evil`")).toThrow(UsageError);
+        expect(() => validateGitRef("main&evil")).toThrow(UsageError);
+    });
+    test("rejects empty string", () => {
+        expect(() => validateGitRef("")).toThrow(UsageError);
+    });
+    // ── Accepted patterns ─────────────────────────────────────────────────────
+    test("accepts branch names", () => {
+        expect(() => validateGitRef("main")).not.toThrow();
+        expect(() => validateGitRef("feat/my-feature")).not.toThrow();
+        expect(() => validateGitRef("v1.2.3")).not.toThrow();
+        expect(() => validateGitRef("release-candidate_1")).not.toThrow();
+    });
+    test("accepts full git SHA hashes", () => {
+        expect(() => validateGitRef("abc1234def567890abc1234def567890abc12345")).not.toThrow();
+    });
+    test("accepts short SHA hashes", () => {
+        expect(() => validateGitRef("abc1234")).not.toThrow();
+    });
+});
+// ── validateNpmTarballUrl ───────────────────────────────────────────────────
+describe("validateNpmTarballUrl", () => {
+    const originalRegistry = process.env.AKM_NPM_REGISTRY;
+    beforeEach(() => {
+        delete process.env.AKM_NPM_REGISTRY;
+    });
+    afterEach(() => {
+        if (originalRegistry === undefined) {
+            delete process.env.AKM_NPM_REGISTRY;
+        }
+        else {
+            process.env.AKM_NPM_REGISTRY = originalRegistry;
+        }
+    });
+    test("accepts public registry tarball", () => {
+        expect(() => validateNpmTarballUrl("https://registry.npmjs.org/@scope/pkg/-/pkg-1.0.0.tgz", "@scope/pkg@1.0.0")).not.toThrow();
+    });
+    test("rejects tarball on attacker-controlled host", () => {
+        let caught;
+        try {
+            validateNpmTarballUrl("https://evil.example.com/pkg-1.0.0.tgz", "pkg@1.0.0");
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(UntrustedNpmTarballError);
+        expect(caught.code).toBe("UNTRUSTED_NPM_TARBALL");
+        expect(caught?.message).toContain("evil.example.com");
+    });
+    test("rejects malformed tarball URL", () => {
+        expect(() => validateNpmTarballUrl("not-a-url", "pkg@1.0.0")).toThrow(UntrustedNpmTarballError);
+    });
+    test("rejects disallowed scheme", () => {
+        expect(() => validateNpmTarballUrl("ftp://registry.npmjs.org/pkg.tgz", "pkg@1.0.0")).toThrow(UntrustedNpmTarballError);
+    });
+    test("accepts operator-configured private registry", () => {
+        process.env.AKM_NPM_REGISTRY = "https://npm.internal.example.com";
+        expect(() => validateNpmTarballUrl("https://npm.internal.example.com/pkg/-/pkg-2.0.0.tgz", "pkg@2.0.0")).not.toThrow();
+    });
+    test("still accepts public registry alongside operator override", () => {
+        process.env.AKM_NPM_REGISTRY = "https://npm.internal.example.com";
+        expect(() => validateNpmTarballUrl("https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz", "pkg@1.0.0")).not.toThrow();
+    });
+    test("rejects untrusted host even with override set", () => {
+        process.env.AKM_NPM_REGISTRY = "https://npm.internal.example.com";
+        expect(() => validateNpmTarballUrl("https://evil.example.com/pkg.tgz", "pkg@1.0.0")).toThrow(UntrustedNpmTarballError);
+    });
+    test("ignores unparseable AKM_NPM_REGISTRY override", () => {
+        process.env.AKM_NPM_REGISTRY = "this is not a url";
+        const hosts = trustedNpmTarballHosts();
+        expect(hosts.has("registry.npmjs.org")).toBe(true);
+        expect(hosts.size).toBe(1);
+    });
+});