swarmkit 0.0.1 → 0.0.3

package/dist/hub/credentials.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+// Mock homedir so config writes go to a temp dir
+let testDir;
+vi.mock("node:os", async () => {
+    const actual = await import("node:os");
+    return {
+        ...actual,
+        homedir: () => testDir,
+    };
+});
+const { readCredentials, writeCredentials, deleteCredentials, isLoggedIn, } = await import("./credentials.js");
+beforeEach(() => {
+    testDir = join(tmpdir(), `swarmkit-cred-test-${randomUUID()}`);
+    mkdirSync(testDir, { recursive: true });
+});
+afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+});
+describe("readCredentials", () => {
+    it("returns null when no credentials file exists", () => {
+        expect(readCredentials()).toBeNull();
+    });
+    it("returns credentials when file exists", () => {
+        writeCredentials({
+            token: "jwt-token-123",
+            apiUrl: "https://api.swarmkit.ai",
+        });
+        const creds = readCredentials();
+        expect(creds).toEqual({
+            token: "jwt-token-123",
+            apiUrl: "https://api.swarmkit.ai",
+        });
+    });
+    it("returns null for malformed JSON", () => {
+        const dir = join(testDir, ".swarmkit");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "credentials.json"), "not json");
+        expect(readCredentials()).toBeNull();
+    });
+    it("returns null when token is missing", () => {
+        const dir = join(testDir, ".swarmkit");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "credentials.json"), JSON.stringify({ apiUrl: "https://api.swarmkit.ai" }));
+        expect(readCredentials()).toBeNull();
+    });
+});
+describe("writeCredentials", () => {
+    it("creates the credentials file", () => {
+        writeCredentials({
+            token: "test-token",
+            apiUrl: "https://api.example.com",
+        });
+        const path = join(testDir, ".swarmkit", "credentials.json");
+        expect(existsSync(path)).toBe(true);
+    });
+    it("writes valid JSON", () => {
+        writeCredentials({
+            token: "test-token",
+            apiUrl: "https://api.example.com",
+        });
+        const path = join(testDir, ".swarmkit", "credentials.json");
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        expect(parsed.token).toBe("test-token");
+        expect(parsed.apiUrl).toBe("https://api.example.com");
+    });
+    it("overwrites existing credentials", () => {
+        writeCredentials({ token: "old", apiUrl: "https://old.com" });
+        writeCredentials({ token: "new", apiUrl: "https://new.com" });
+        const creds = readCredentials();
+        expect(creds?.token).toBe("new");
+        expect(creds?.apiUrl).toBe("https://new.com");
+    });
+});
+describe("deleteCredentials", () => {
+    it("removes the credentials file", () => {
+        writeCredentials({ token: "test", apiUrl: "https://api.test.com" });
+        deleteCredentials();
+        expect(readCredentials()).toBeNull();
+    });
+    it("does nothing when no credentials exist", () => {
+        expect(() => deleteCredentials()).not.toThrow();
+    });
+});
+describe("isLoggedIn", () => {
+    it("returns false when not logged in", () => {
+        expect(isLoggedIn()).toBe(false);
+    });
+    it("returns true when credentials exist", () => {
+        writeCredentials({ token: "test", apiUrl: "https://api.test.com" });
+        expect(isLoggedIn()).toBe(true);
+    });
+    it("returns false after logout", () => {
+        writeCredentials({ token: "test", apiUrl: "https://api.test.com" });
+        deleteCredentials();
+        expect(isLoggedIn()).toBe(false);
+    });
+});

package/dist/index.d.ts

@@ -1 +1,17 @@
-export {};
+export { PACKAGES, BUNDLES, INTEGRATIONS, getBundlePackages, getActiveIntegrations, getNewIntegrations, getLostIntegrations, getNpmName, isKnownPackage, getAllPackageNames, } from "./packages/registry.js";
+export type { PackageDefinition, BundleDefinition, Integration, } from "./packages/registry.js";
+export { installPackages, uninstallPackage, getInstalledVersion, getLatestVersion, updatePackages, isClaudeCliAvailable, getGlobalPackagePath, } from "./packages/installer.js";
+export type { InstallResult, UpdateResult } from "./packages/installer.js";
+export { isInstalledPlugin, registerPlugin, } from "./packages/plugin.js";
+export { PROJECT_CONFIG_DIRS, PROJECT_INIT_ORDER, GLOBAL_CONFIG_DIRS, isProjectInit, isGlobalInit, initProjectPackage, initGlobalPackage, } from "./packages/setup.js";
+export type { InitContext, GlobalContext, OpenhiveOptions, SetupResult, } from "./packages/setup.js";
+export { readConfig, writeConfig, isFirstRun, getConfigDir, addInstalledPackages, removeInstalledPackage, } from "./config/global.js";
+export type { GlobalConfig } from "./config/global.js";
+export { readKey, writeKey, deleteKey, listKeys, hasKey, } from "./config/keys.js";
+export { runAllChecks } from "./doctor/checks.js";
+export type { CheckResult, CheckContext, CheckStatus, } from "./doctor/types.js";
+export type { DoctorReport } from "./doctor/checks.js";
+export { readCredentials, writeCredentials, deleteCredentials, isLoggedIn, } from "./hub/credentials.js";
+export type { HubCredentials } from "./hub/credentials.js";
+export { exchangeAuthCode, refreshToken, getMe, createHive, listHives, getHive, startHive, stopHive, destroyHive, getHubUrl, HubApiError, } from "./hub/client.js";
+export type { HubUser, Hive, HiveStatus, HiveTier, CreateHiveOptions, } from "./hub/client.js";

package/dist/index.js

@@ -1,2 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+// Public API — re-export modules for programmatic use
+export { PACKAGES, BUNDLES, INTEGRATIONS, getBundlePackages, getActiveIntegrations, getNewIntegrations, getLostIntegrations, getNpmName, isKnownPackage, getAllPackageNames, } from "./packages/registry.js";
+export { installPackages, uninstallPackage, getInstalledVersion, getLatestVersion, updatePackages, isClaudeCliAvailable, getGlobalPackagePath, } from "./packages/installer.js";
+export { isInstalledPlugin, registerPlugin, } from "./packages/plugin.js";
+export { PROJECT_CONFIG_DIRS, PROJECT_INIT_ORDER, GLOBAL_CONFIG_DIRS, isProjectInit, isGlobalInit, initProjectPackage, initGlobalPackage, } from "./packages/setup.js";
+export { readConfig, writeConfig, isFirstRun, getConfigDir, addInstalledPackages, removeInstalledPackage, } from "./config/global.js";
+export { readKey, writeKey, deleteKey, listKeys, hasKey, } from "./config/keys.js";
+export { runAllChecks } from "./doctor/checks.js";
+export { readCredentials, writeCredentials, deleteCredentials, isLoggedIn, } from "./hub/credentials.js";
+export { exchangeAuthCode, refreshToken, getMe, createHive, listHives, getHive, startHive, stopHive, destroyHive, getHubUrl, HubApiError, } from "./hub/client.js";

package/dist/packages/installer.d.ts

@@ -0,0 +1,42 @@
+export interface InstallResult {
+    package: string;
+    success: boolean;
+    version?: string;
+    error?: string;
+}
+export interface UpdateResult {
+    package: string;
+    previousVersion: string | null;
+    newVersion: string | null;
+    updated: boolean;
+    error?: string;
+}
+/**
+ * Install packages globally via npm.
+ */
+export declare function installPackages(packages: string[]): Promise<InstallResult[]>;
+/**
+ * Uninstall a package globally via npm.
+ */
+export declare function uninstallPackage(packageName: string): Promise<void>;
+/**
+ * Get the currently installed global version of a package, or null if not installed.
+ */
+export declare function getInstalledVersion(packageName: string): Promise<string | null>;
+/**
+ * Get the latest published version of a package from the registry.
+ */
+export declare function getLatestVersion(packageName: string): Promise<string | null>;
+/**
+ * Update installed packages to their latest versions.
+ */
+export declare function updatePackages(packages: string[]): Promise<UpdateResult[]>;
+/**
+ * Check if the Claude Code CLI is available.
+ */
+export declare function isClaudeCliAvailable(): Promise<boolean>;
+/**
+ * Resolve the global installation path of an npm package.
+ * Uses `npm list -g --parseable` to get the filesystem path.
+ */
+export declare function getGlobalPackagePath(npmName: string): Promise<string | null>;

package/dist/packages/installer.js

@@ -0,0 +1,158 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getNpmName } from "./registry.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Install packages globally via npm.
+ */
+export async function installPackages(packages) {
+    const results = [];
+    for (const pkg of packages) {
+        results.push(await installNpmPackage(pkg));
+    }
+    return results;
+}
+async function installNpmPackage(pkg) {
+    const npmName = getNpmName(pkg);
+    try {
+        await execFileAsync("npm", ["install", "-g", npmName], {
+            timeout: 120_000,
+        });
+        const version = await getInstalledVersion(pkg);
+        return { package: pkg, success: true, version: version ?? undefined };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { package: pkg, success: false, error: formatNpmError(message) };
+    }
+}
+/**
+ * Uninstall a package globally via npm.
+ */
+export async function uninstallPackage(packageName) {
+    const npmName = getNpmName(packageName);
+    await execFileAsync("npm", ["uninstall", "-g", npmName], {
+        timeout: 60_000,
+    });
+}
+/**
+ * Get the currently installed global version of a package, or null if not installed.
+ */
+export async function getInstalledVersion(packageName) {
+    const npmName = getNpmName(packageName);
+    try {
+        const { stdout } = await execFileAsync("npm", ["list", "-g", npmName, "--json", "--depth=0"], { timeout: 15_000 });
+        const data = JSON.parse(stdout);
+        return data.dependencies?.[npmName]?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the latest published version of a package from the registry.
+ */
+export async function getLatestVersion(packageName) {
+    const npmName = getNpmName(packageName);
+    try {
+        const { stdout } = await execFileAsync("npm", ["view", npmName, "version"], { timeout: 15_000 });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Update installed packages to their latest versions.
+ */
+export async function updatePackages(packages) {
+    const results = [];
+    for (const pkg of packages) {
+        const previousVersion = await getInstalledVersion(pkg);
+        const latestVersion = await getLatestVersion(pkg);
+        if (!latestVersion) {
+            results.push({
+                package: pkg,
+                previousVersion,
+                newVersion: null,
+                updated: false,
+                error: "Could not fetch latest version",
+            });
+            continue;
+        }
+        if (previousVersion === latestVersion) {
+            results.push({
+                package: pkg,
+                previousVersion,
+                newVersion: latestVersion,
+                updated: false,
+            });
+            continue;
+        }
+        const npmName = getNpmName(pkg);
+        try {
+            await execFileAsync("npm", ["install", "-g", `${npmName}@latest`], {
+                timeout: 120_000,
+            });
+            const newVersion = await getInstalledVersion(pkg);
+            results.push({
+                package: pkg,
+                previousVersion,
+                newVersion,
+                updated: true,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                package: pkg,
+                previousVersion,
+                newVersion: null,
+                updated: false,
+                error: formatNpmError(message),
+            });
+        }
+    }
+    return results;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Check if the Claude Code CLI is available.
+ */
+export async function isClaudeCliAvailable() {
+    try {
+        await execFileAsync("claude", ["--version"], { timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the global installation path of an npm package.
+ * Uses `npm list -g --parseable` to get the filesystem path.
+ */
+export async function getGlobalPackagePath(npmName) {
+    try {
+        const { stdout } = await execFileAsync("npm", ["list", "-g", npmName, "--parseable", "--depth=0"], { timeout: 15_000 });
+        // --parseable returns: prefix-root\npackage-path
+        const lines = stdout.trim().split("\n").filter(Boolean);
+        return lines.length > 1 ? lines[lines.length - 1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatNpmError(message) {
+    if (message.includes("EACCES") || message.includes("permission")) {
+        return "Permission denied — try running with sudo or configure npm prefix";
+    }
+    if (message.includes("ENOTFOUND") || message.includes("network")) {
+        return "Network error — check your internet connection";
+    }
+    if (message.includes("404") || message.includes("Not Found")) {
+        return "Package not found in npm registry";
+    }
+    // Return first line of error to keep it concise
+    return message.split("\n")[0];
+}

package/dist/packages/installer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/packages/installer.test.js

@@ -0,0 +1,283 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+// Mock child_process.execFile
+const mockExecFile = vi.fn();
+vi.mock("node:child_process", () => ({
+    execFile: mockExecFile,
+}));
+// Mock promisify to return our mock
+vi.mock("node:util", async () => {
+    const actual = await vi.importActual("node:util");
+    return {
+        ...actual,
+        promisify: () => mockExecFile,
+    };
+});
+const { installPackages, uninstallPackage, getInstalledVersion, getLatestVersion, updatePackages, isClaudeCliAvailable, getGlobalPackagePath, } = await import("./installer.js");
+describe("installer", () => {
+    beforeEach(() => {
+        mockExecFile.mockReset();
+    });
+    describe("getInstalledVersion", () => {
+        it("returns version when package is installed", async () => {
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            const version = await getInstalledVersion("minimem");
+            expect(version).toBe("0.1.0");
+            expect(mockExecFile).toHaveBeenCalledWith("npm", ["list", "-g", "minimem", "--json", "--depth=0"], { timeout: 15_000 });
+        });
+        it("returns null when package is not installed", async () => {
+            mockExecFile.mockRejectedValueOnce(new Error("not found"));
+            const version = await getInstalledVersion("not-installed");
+            expect(version).toBeNull();
+        });
+        it("returns null when dependencies field is missing", async () => {
+            mockExecFile.mockResolvedValueOnce({ stdout: JSON.stringify({}) });
+            const version = await getInstalledVersion("minimem");
+            expect(version).toBeNull();
+        });
+    });
+    describe("getLatestVersion", () => {
+        it("returns version from npm registry", async () => {
+            mockExecFile.mockResolvedValueOnce({ stdout: "0.2.0\n" });
+            const version = await getLatestVersion("minimem");
+            expect(version).toBe("0.2.0");
+            expect(mockExecFile).toHaveBeenCalledWith("npm", ["view", "minimem", "version"], { timeout: 15_000 });
+        });
+        it("returns null on network error", async () => {
+            mockExecFile.mockRejectedValueOnce(new Error("ENOTFOUND"));
+            const version = await getLatestVersion("minimem");
+            expect(version).toBeNull();
+        });
+        it("returns null for empty stdout", async () => {
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            const version = await getLatestVersion("minimem");
+            expect(version).toBeNull();
+        });
+    });
+    describe("installPackages", () => {
+        it("installs a single package successfully", async () => {
+            // First call: npm install -g
+            mockExecFile.mockResolvedValueOnce({ stdout: "", stderr: "" });
+            // Second call: npm list -g (getInstalledVersion)
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            const results = await installPackages(["minimem"]);
+            expect(results).toHaveLength(1);
+            expect(results[0]).toEqual({
+                package: "minimem",
+                success: true,
+                version: "0.1.0",
+            });
+        });
+        it("reports failure on install error", async () => {
+            mockExecFile.mockRejectedValueOnce(new Error("EACCES permission denied"));
+            const results = await installPackages(["minimem"]);
+            expect(results).toHaveLength(1);
+            expect(results[0].success).toBe(false);
+            expect(results[0].error).toContain("Permission denied");
+        });
+        it("installs multiple packages sequentially", async () => {
+            // Package 1: success
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            // Package 2: success
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { opentasks: { version: "0.0.3" } },
+                }),
+            });
+            const results = await installPackages(["minimem", "opentasks"]);
+            expect(results).toHaveLength(2);
+            expect(results[0].success).toBe(true);
+            expect(results[1].success).toBe(true);
+        });
+        it("handles mixed success and failure", async () => {
+            // Package 1: success
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            // Package 2: failure
+            mockExecFile.mockRejectedValueOnce(new Error("404 Not Found"));
+            const results = await installPackages(["minimem", "bad-package"]);
+            expect(results[0].success).toBe(true);
+            expect(results[1].success).toBe(false);
+            expect(results[1].error).toContain("not found");
+        });
+    });
+    describe("uninstallPackage", () => {
+        it("calls npm uninstall -g", async () => {
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            await uninstallPackage("minimem");
+            expect(mockExecFile).toHaveBeenCalledWith("npm", ["uninstall", "-g", "minimem"], { timeout: 60_000 });
+        });
+        it("throws on failure", async () => {
+            mockExecFile.mockRejectedValueOnce(new Error("failed"));
+            await expect(uninstallPackage("minimem")).rejects.toThrow("failed");
+        });
+    });
+    describe("updatePackages", () => {
+        it("reports package as up to date when versions match", async () => {
+            // getInstalledVersion
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            // getLatestVersion
+            mockExecFile.mockResolvedValueOnce({ stdout: "0.1.0\n" });
+            const results = await updatePackages(["minimem"]);
+            expect(results).toHaveLength(1);
+            expect(results[0].updated).toBe(false);
+            expect(results[0].previousVersion).toBe("0.1.0");
+            expect(results[0].newVersion).toBe("0.1.0");
+        });
+        it("updates package when newer version is available", async () => {
+            // getInstalledVersion (before)
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            // getLatestVersion
+            mockExecFile.mockResolvedValueOnce({ stdout: "0.2.0\n" });
+            // npm install -g minimem@latest
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            // getInstalledVersion (after)
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.2.0" } },
+                }),
+            });
+            const results = await updatePackages(["minimem"]);
+            expect(results).toHaveLength(1);
+            expect(results[0].updated).toBe(true);
+            expect(results[0].previousVersion).toBe("0.1.0");
+            expect(results[0].newVersion).toBe("0.2.0");
+        });
+        it("reports error when latest version cannot be fetched", async () => {
+            // getInstalledVersion
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            // getLatestVersion fails
+            mockExecFile.mockRejectedValueOnce(new Error("network error"));
+            const results = await updatePackages(["minimem"]);
+            expect(results[0].updated).toBe(false);
+            expect(results[0].error).toBe("Could not fetch latest version");
+        });
+        it("reports error when install fails during update", async () => {
+            // getInstalledVersion
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { minimem: { version: "0.1.0" } },
+                }),
+            });
+            // getLatestVersion
+            mockExecFile.mockResolvedValueOnce({ stdout: "0.2.0\n" });
+            // npm install fails
+            mockExecFile.mockRejectedValueOnce(new Error("EACCES permission denied"));
+            const results = await updatePackages(["minimem"]);
+            expect(results[0].updated).toBe(false);
+            expect(results[0].error).toContain("Permission denied");
+        });
+    });
+    describe("isClaudeCliAvailable", () => {
+        it("returns true when claude --version succeeds", async () => {
+            mockExecFile.mockResolvedValueOnce({ stdout: "1.0.0\n" });
+            const available = await isClaudeCliAvailable();
+            expect(available).toBe(true);
+            expect(mockExecFile).toHaveBeenCalledWith("claude", ["--version"], { timeout: 10_000 });
+        });
+        it("returns false when claude is not found", async () => {
+            mockExecFile.mockRejectedValueOnce(new Error("ENOENT"));
+            const available = await isClaudeCliAvailable();
+            expect(available).toBe(false);
+        });
+    });
+    describe("getGlobalPackagePath", () => {
+        it("returns path from npm list --parseable", async () => {
+            mockExecFile.mockResolvedValueOnce({
+                stdout: "/usr/local/lib/node_modules\n/usr/local/lib/node_modules/claude-code-swarm\n",
+            });
+            const result = await getGlobalPackagePath("claude-code-swarm");
+            expect(result).toBe("/usr/local/lib/node_modules/claude-code-swarm");
+        });
+        it("returns null when package is not installed", async () => {
+            mockExecFile.mockRejectedValueOnce(new Error("not found"));
+            const result = await getGlobalPackagePath("not-installed");
+            expect(result).toBeNull();
+        });
+    });
+    describe("installPackages — claude-code-swarm as normal npm", () => {
+        it("installs claude-code-swarm via npm without any claude CLI calls", async () => {
+            // npm install -g
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            // getInstalledVersion
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { "claude-code-swarm": { version: "0.3.1" } },
+                }),
+            });
+            const results = await installPackages(["claude-code-swarm"]);
+            expect(results).toHaveLength(1);
+            expect(results[0].success).toBe(true);
+            expect(results[0].version).toBe("0.3.1");
+            // Verify no calls to claude CLI
+            for (const call of mockExecFile.mock.calls) {
+                expect(call[0]).not.toBe("claude");
+            }
+        });
+    });
+    describe("uninstallPackage — claude-code-swarm as normal npm", () => {
+        it("just calls npm uninstall (no plugin deregistration)", async () => {
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            await uninstallPackage("claude-code-swarm");
+            expect(mockExecFile).toHaveBeenCalledTimes(1);
+            expect(mockExecFile).toHaveBeenCalledWith("npm", ["uninstall", "-g", "claude-code-swarm"], { timeout: 60_000 });
+        });
+    });
+    describe("updatePackages — claude-code-swarm as normal npm", () => {
+        it("updates via npm without plugin re-registration", async () => {
+            // getInstalledVersion (before)
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { "claude-code-swarm": { version: "0.3.0" } },
+                }),
+            });
+            // getLatestVersion
+            mockExecFile.mockResolvedValueOnce({ stdout: "0.4.0\n" });
+            // npm install -g claude-code-swarm@latest
+            mockExecFile.mockResolvedValueOnce({ stdout: "" });
+            // getInstalledVersion (after)
+            mockExecFile.mockResolvedValueOnce({
+                stdout: JSON.stringify({
+                    dependencies: { "claude-code-swarm": { version: "0.4.0" } },
+                }),
+            });
+            const results = await updatePackages(["claude-code-swarm"]);
+            expect(results).toHaveLength(1);
+            expect(results[0].updated).toBe(true);
+            expect(results[0].newVersion).toBe("0.4.0");
+            // Verify no calls to claude CLI
+            for (const call of mockExecFile.mock.calls) {
+                expect(call[0]).not.toBe("claude");
+            }
+        });
+    });
+});

package/dist/packages/plugin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check if a globally installed npm package is a Claude Code plugin.
+ * A package is a Claude plugin if it contains `.claude-plugin/plugin.json`.
+ */
+export declare function isInstalledPlugin(packageName: string): Promise<boolean>;
+/**
+ * Register a package as a Claude Code plugin using `claude plugin add`.
+ * Scope controls where the plugin is activated:
+ * - "user": all projects (default)
+ * - "project": this repository only (shared with collaborators)
+ * - "local": this repository only (not shared)
+ */
+export declare function registerPlugin(packageName: string, scope?: "user" | "project" | "local"): Promise<void>;

package/dist/packages/plugin.js

@@ -0,0 +1,33 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getNpmName } from "./registry.js";
+import { getGlobalPackagePath } from "./installer.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Check if a globally installed npm package is a Claude Code plugin.
+ * A package is a Claude plugin if it contains `.claude-plugin/plugin.json`.
+ */
+export async function isInstalledPlugin(packageName) {
+    const npmName = getNpmName(packageName);
+    const pkgPath = await getGlobalPackagePath(npmName);
+    if (!pkgPath)
+        return false;
+    return existsSync(join(pkgPath, ".claude-plugin", "plugin.json"));
+}
+/**
+ * Register a package as a Claude Code plugin using `claude plugin add`.
+ * Scope controls where the plugin is activated:
+ * - "user": all projects (default)
+ * - "project": this repository only (shared with collaborators)
+ * - "local": this repository only (not shared)
+ */
+export async function registerPlugin(packageName, scope = "user") {
+    const npmName = getNpmName(packageName);
+    const pkgPath = await getGlobalPackagePath(npmName);
+    if (!pkgPath) {
+        throw new Error(`Could not resolve global install path for ${packageName}`);
+    }
+    await execFileAsync("claude", ["plugin", "add", pkgPath, "--scope", scope], { timeout: 30_000 });
+}

package/dist/packages/plugin.test.d.ts

@@ -0,0 +1 @@
+export {};