swarmkit 0.0.2 → 0.0.4

package/dist/config/global.test.js

@@ -12,7 +12,7 @@ vi.mock("node:os", async () => {
     };
 });
 // Import after mock is set up
-const { getConfigDir, getConfigPath, ensureConfigDir, isFirstRun, readConfig, writeConfig, addInstalledPackages, removeInstalledPackage, } = await import("./global.js");
+const { getConfigDir, getConfigPath, ensureConfigDir, isFirstRun, readConfig, writeConfig, addInstalledPackages, removeInstalledPackage, getSwarmkitVersion, isConfigOutdated, } = await import("./global.js");
 describe("config/global", () => {
     beforeEach(() => {
         tempHome = mkdtempSync(join(tmpdir(), "swarmkit-test-"));
@@ -67,12 +67,12 @@ describe("config/global", () => {
         });
         it("reads written config", () => {
             writeConfig({
-                installedPackages: ["macro-agent"],
+                installedPackages: ["opentasks"],
                 embeddingProvider: "openai",
                 embeddingModel: "text-embedding-3-small",
             });
             const config = readConfig();
-            expect(config.installedPackages).toEqual(["macro-agent"]);
+            expect(config.installedPackages).toEqual(["opentasks"]);
             expect(config.embeddingProvider).toBe("openai");
             expect(config.embeddingModel).toBe("text-embedding-3-small");
         });
@@ -112,23 +112,23 @@ describe("config/global", () => {
     describe("addInstalledPackages", () => {
         it("adds packages to an empty list", () => {
             writeConfig({ installedPackages: [] });
-            addInstalledPackages(["macro-agent", "minimem"]);
+            addInstalledPackages(["opentasks", "minimem"]);
             const config = readConfig();
-            expect(config.installedPackages).toEqual(["macro-agent", "minimem"]);
+            expect(config.installedPackages).toEqual(["minimem", "opentasks"]);
         });
         it("deduplicates packages", () => {
-            writeConfig({ installedPackages: ["macro-agent"] });
-            addInstalledPackages(["macro-agent", "minimem"]);
+            writeConfig({ installedPackages: ["opentasks"] });
+            addInstalledPackages(["opentasks", "minimem"]);
             const config = readConfig();
-            expect(config.installedPackages).toEqual(["macro-agent", "minimem"]);
+            expect(config.installedPackages).toEqual(["minimem", "opentasks"]);
         });
         it("sorts packages alphabetically", () => {
-            addInstalledPackages(["minimem", "agent-iam", "macro-agent"]);
+            addInstalledPackages(["minimem", "cognitive-core", "opentasks"]);
             const config = readConfig();
             expect(config.installedPackages).toEqual([
-                "agent-iam",
-                "macro-agent",
+                "cognitive-core",
                 "minimem",
+                "opentasks",
             ]);
         });
         it("preserves other config fields", () => {
@@ -143,16 +143,16 @@ describe("config/global", () => {
     });
     describe("removeInstalledPackage", () => {
         it("removes a package from the list", () => {
-            writeConfig({ installedPackages: ["macro-agent", "minimem"] });
+            writeConfig({ installedPackages: ["opentasks", "minimem"] });
             removeInstalledPackage("minimem");
             const config = readConfig();
-            expect(config.installedPackages).toEqual(["macro-agent"]);
+            expect(config.installedPackages).toEqual(["opentasks"]);
         });
         it("does nothing if package is not in list", () => {
-            writeConfig({ installedPackages: ["macro-agent"] });
+            writeConfig({ installedPackages: ["opentasks"] });
             removeInstalledPackage("minimem");
             const config = readConfig();
-            expect(config.installedPackages).toEqual(["macro-agent"]);
+            expect(config.installedPackages).toEqual(["opentasks"]);
         });
         it("preserves other config fields", () => {
             writeConfig({
@@ -164,4 +164,37 @@ describe("config/global", () => {
             expect(config.embeddingProvider).toBe("gemini");
         });
     });
+    describe("getSwarmkitVersion", () => {
+        it("returns a semver string", () => {
+            const version = getSwarmkitVersion();
+            expect(version).toMatch(/^\d+\.\d+\.\d+/);
+        });
+    });
+    describe("isConfigOutdated", () => {
+        it("returns true when configVersion is missing", () => {
+            const config = { installedPackages: [] };
+            expect(isConfigOutdated(config, "1.0.0")).toBe(true);
+        });
+        it("returns false when versions match exactly", () => {
+            const config = { installedPackages: [], configVersion: "1.2.3" };
+            expect(isConfigOutdated(config, "1.2.3")).toBe(false);
+        });
+        it("returns false for patch-only difference", () => {
+            const config = { installedPackages: [], configVersion: "1.2.0" };
+            expect(isConfigOutdated(config, "1.2.5")).toBe(false);
+        });
+        it("returns true when minor version differs", () => {
+            const config = { installedPackages: [], configVersion: "1.0.0" };
+            expect(isConfigOutdated(config, "1.1.0")).toBe(true);
+        });
+        it("returns true when major version differs", () => {
+            const config = { installedPackages: [], configVersion: "0.1.0" };
+            expect(isConfigOutdated(config, "1.0.0")).toBe(true);
+        });
+        it("uses getSwarmkitVersion when currentVersion is not provided", () => {
+            const version = getSwarmkitVersion();
+            const config = { installedPackages: [], configVersion: version };
+            expect(isConfigOutdated(config)).toBe(false);
+        });
+    });
 });

package/dist/doctor/checks.d.ts

@@ -9,7 +9,7 @@ export declare function checkPackages(ctx: CheckContext): Promise<CheckResult[]>
 export declare function checkCredentials(ctx: CheckContext): CheckResult[];
 /**
  * Check that project-level config directories exist for installed packages.
- * Only runs when cwd is a project directory.
+ * Only runs when cwd is a project directory. Checks both .swarm/ and flat layouts.
  */
 export declare function checkProjectConfigs(ctx: CheckContext): CheckResult[];
 /**

package/dist/doctor/checks.js

@@ -1,13 +1,26 @@
 import { join } from "node:path";
 import { PACKAGES, getActiveIntegrations } from "../packages/registry.js";
-/** Config directories each package creates at the project level */
-const PROJECT_CONFIG_DIRS = {
-    "macro-agent": ".multiagent",
+/** Config directories — prefixed layout (.swarm/) */
+const PREFIXED_CONFIG_DIRS = {
+    opentasks: ".swarm/opentasks",
+    minimem: ".swarm/minimem",
+    "cognitive-core": ".swarm/cognitive-core",
+    "skill-tree": ".swarm/skilltree",
+    "self-driving-repo": ".swarm/self-driving",
+    openteams: ".swarm/openteams",
+    sessionlog: ".swarm/sessionlog",
+    "claude-code-swarm": ".swarm/claude-swarm",
+};
+/** Config directories — flat layout (legacy / --no-prefix) */
+const FLAT_CONFIG_DIRS = {
     opentasks: ".opentasks",
     minimem: ".minimem",
     "cognitive-core": ".cognitive-core",
     "skill-tree": ".skilltree",
     "self-driving-repo": ".self-driving",
+    openteams: ".openteams",
+    sessionlog: ".sessionlog",
+    "claude-code-swarm": ".claude-swarm",
 };
 /** Embedding provider → required key name */
 const EMBEDDING_KEY_MAP = {
@@ -113,31 +126,34 @@ export function checkCredentials(ctx) {
 // ── Project config checks ───────────────────────────────────────
 /**
  * Check that project-level config directories exist for installed packages.
- * Only runs when cwd is a project directory.
+ * Only runs when cwd is a project directory. Checks both .swarm/ and flat layouts.
  */
 export function checkProjectConfigs(ctx) {
     if (!ctx.isProject)
         return [];
     const results = [];
     for (const pkg of ctx.installedPackages) {
-        const configDir = PROJECT_CONFIG_DIRS[pkg];
-        if (!configDir)
+        const prefixedDir = PREFIXED_CONFIG_DIRS[pkg];
+        const flatDir = FLAT_CONFIG_DIRS[pkg];
+        if (!prefixedDir)
             continue; // Package has no project-level config
         if (PACKAGES[pkg]?.globalOnly)
             continue;
-        const fullPath = join(ctx.cwd, configDir);
-        if (ctx.exists(fullPath)) {
+        const hasPrefixed = ctx.exists(join(ctx.cwd, prefixedDir));
+        const hasFlat = flatDir ? ctx.exists(join(ctx.cwd, flatDir)) : false;
+        if (hasPrefixed || hasFlat) {
+            const found = hasPrefixed ? prefixedDir : flatDir;
             results.push({
                 name: `${pkg}-config`,
                 status: "pass",
-                message: `${configDir}/`,
+                message: `${found}/`,
             });
         }
         else {
             results.push({
                 name: `${pkg}-config`,
                 status: "warn",
-                message: `${configDir}/ not found`,
+                message: `${prefixedDir}/ not found`,
                 fix: `swarmkit init (or ${pkg} init)`,
             });
         }

package/dist/doctor/checks.test.js

@@ -16,10 +16,10 @@ function createContext(overrides = {}) {
 describe("checkPackages", () => {
     it("passes when all packages are installed", async () => {
         const ctx = createContext({
-            installedPackages: ["macro-agent", "minimem"],
+            installedPackages: ["opentasks", "minimem"],
             getInstalledVersion: async (pkg) => {
                 const versions = {
-                    "macro-agent": "0.1.0",
+                    opentasks: "0.1.0",
                     minimem: "0.2.0",
                 };
                 return versions[pkg] ?? null;
@@ -28,14 +28,14 @@ describe("checkPackages", () => {
         const results = await checkPackages(ctx);
         expect(results).toHaveLength(2);
         expect(results[0].status).toBe("pass");
-        expect(results[0].message).toContain("macro-agent");
+        expect(results[0].message).toContain("opentasks");
         expect(results[0].message).toContain("0.1.0");
         expect(results[1].status).toBe("pass");
     });
     it("fails when a package is not found", async () => {
         const ctx = createContext({
-            installedPackages: ["macro-agent", "minimem"],
-            getInstalledVersion: async (pkg) => pkg === "macro-agent" ? "0.1.0" : null,
+            installedPackages: ["opentasks", "minimem"],
+            getInstalledVersion: async (pkg) => pkg === "opentasks" ? "0.1.0" : null,
         });
         const results = await checkPackages(ctx);
         expect(results[0].status).toBe("pass");
@@ -124,7 +124,7 @@ describe("checkCredentials", () => {
     });
     it("skips embedding check when no embedding consumers installed", () => {
         const ctx = createContext({
-            installedPackages: ["macro-agent", "opentasks"],
+            installedPackages: ["opentasks", "self-driving-repo"],
             embeddingProvider: undefined,
         });
         const results = checkCredentials(ctx);
@@ -146,21 +146,32 @@ describe("checkProjectConfigs", () => {
     it("returns empty when not in a project", () => {
         const ctx = createContext({
             isProject: false,
-            installedPackages: ["macro-agent"],
+            installedPackages: ["opentasks"],
         });
         const results = checkProjectConfigs(ctx);
         expect(results).toEqual([]);
     });
-    it("passes when config directory exists", () => {
+    it("passes when prefixed config directory exists", () => {
         const ctx = createContext({
             isProject: true,
-            installedPackages: ["macro-agent"],
-            exists: (path) => path.endsWith(".multiagent"),
+            installedPackages: ["opentasks"],
+            exists: (path) => path.endsWith(".swarm/opentasks"),
         });
         const results = checkProjectConfigs(ctx);
         expect(results).toHaveLength(1);
         expect(results[0].status).toBe("pass");
-        expect(results[0].message).toContain(".multiagent");
+        expect(results[0].message).toContain(".swarm/opentasks");
+    });
+    it("passes when flat config directory exists", () => {
+        const ctx = createContext({
+            isProject: true,
+            installedPackages: ["opentasks"],
+            exists: (path) => path.endsWith(".opentasks"),
+        });
+        const results = checkProjectConfigs(ctx);
+        expect(results).toHaveLength(1);
+        expect(results[0].status).toBe("pass");
+        expect(results[0].message).toContain(".opentasks");
     });
     it("warns when config directory is missing", () => {
         const ctx = createContext({
@@ -171,54 +182,68 @@ describe("checkProjectConfigs", () => {
         const results = checkProjectConfigs(ctx);
         expect(results).toHaveLength(1);
         expect(results[0].status).toBe("warn");
-        expect(results[0].message).toContain(".opentasks");
+        expect(results[0].message).toContain(".swarm/opentasks");
         expect(results[0].fix).toContain("opentasks init");
     });
-    it("skips globalOnly packages", () => {
+    it("passes for claude-code-swarm with prefixed config", () => {
+        const ctx = createContext({
+            isProject: true,
+            installedPackages: ["claude-code-swarm"],
+            exists: (path) => path.endsWith(".swarm/claude-swarm"),
+        });
+        const results = checkProjectConfigs(ctx);
+        expect(results).toHaveLength(1);
+        expect(results[0].status).toBe("pass");
+        expect(results[0].message).toContain(".swarm/claude-swarm");
+    });
+    it("skips packages without project config dirs", () => {
         const ctx = createContext({
             isProject: true,
-            installedPackages: ["agent-iam"],
+            installedPackages: ["multi-agent-protocol"],
             exists: () => false,
         });
         const results = checkProjectConfigs(ctx);
         expect(results).toEqual([]);
     });
-    it("checks multiple packages", () => {
-        const existingDirs = new Set(["/tmp/test-project/.multiagent"]);
+    it("checks multiple packages (mixed layouts)", () => {
+        const existingDirs = new Set([
+            "/tmp/test-project/.swarm/opentasks",
+            "/tmp/test-project/.minimem",
+        ]);
         const ctx = createContext({
             isProject: true,
             cwd: "/tmp/test-project",
-            installedPackages: ["macro-agent", "opentasks", "minimem"],
+            installedPackages: ["opentasks", "minimem", "cognitive-core"],
             exists: (path) => existingDirs.has(path),
         });
         const results = checkProjectConfigs(ctx);
         expect(results).toHaveLength(3);
-        expect(results[0].status).toBe("pass"); // macro-agent
-        expect(results[1].status).toBe("warn"); // opentasks
-        expect(results[2].status).toBe("warn"); // minimem
+        expect(results[0].status).toBe("pass"); // opentasks (prefixed)
+        expect(results[1].status).toBe("pass"); // minimem (flat)
+        expect(results[2].status).toBe("warn"); // cognitive-core (missing)
     });
 });
 describe("checkIntegrations", () => {
     it("passes when both packages in an integration are installed", async () => {
         const ctx = createContext({
-            installedPackages: ["macro-agent", "opentasks"],
+            installedPackages: ["cognitive-core", "minimem"],
             getInstalledVersion: async () => "0.1.0",
         });
         const results = await checkIntegrations(ctx);
         expect(results).toHaveLength(1);
         expect(results[0].status).toBe("pass");
-        expect(results[0].message).toContain("macro-agent");
-        expect(results[0].message).toContain("opentasks");
+        expect(results[0].message).toContain("cognitive-core");
+        expect(results[0].message).toContain("minimem");
     });
     it("fails when one package in an integration is missing from PATH", async () => {
         const ctx = createContext({
-            installedPackages: ["macro-agent", "opentasks"],
-            getInstalledVersion: async (pkg) => pkg === "macro-agent" ? "0.1.0" : null,
+            installedPackages: ["cognitive-core", "minimem"],
+            getInstalledVersion: async (pkg) => pkg === "cognitive-core" ? "0.1.0" : null,
         });
         const results = await checkIntegrations(ctx);
         expect(results).toHaveLength(1);
         expect(results[0].status).toBe("fail");
-        expect(results[0].fix).toContain("opentasks");
+        expect(results[0].fix).toContain("minimem");
     });
     it("returns empty when no integrations are active", async () => {
         const ctx = createContext({
@@ -251,7 +276,7 @@ describe("checkGlobalConfig", () => {
 describe("runAllChecks", () => {
     it("returns a complete report", async () => {
         const ctx = createContext({
-            installedPackages: ["macro-agent", "minimem"],
+            installedPackages: ["opentasks", "minimem"],
             embeddingProvider: "openai",
             storedKeys: ["anthropic", "openai"],
             isProject: true,

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 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, } from "./packages/installer.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 { readConfig, writeConfig, isFirstRun, getConfigDir, addInstalledPackages, removeInstalledPackage, getSwarmkitVersion, isConfigOutdated, } 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";

package/dist/index.js

@@ -1,8 +1,9 @@
 // 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, } from "./packages/installer.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 { readConfig, writeConfig, isFirstRun, getConfigDir, addInstalledPackages, removeInstalledPackage, getSwarmkitVersion, isConfigOutdated, } 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";

package/dist/packages/installer.d.ts

@@ -31,3 +31,12 @@ export declare function getLatestVersion(packageName: string): Promise<string |
  * 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

@@ -8,21 +8,24 @@ const execFileAsync = promisify(execFile);
 export async function installPackages(packages) {
     const results = [];
     for (const pkg of packages) {
-        const npmName = getNpmName(pkg);
-        try {
-            await execFileAsync("npm", ["install", "-g", npmName], {
-                timeout: 120_000,
-            });
-            const version = await getInstalledVersion(pkg);
-            results.push({ package: pkg, success: true, version: version ?? undefined });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            results.push({ package: pkg, success: false, error: formatNpmError(message) });
-        }
+        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.
  */
@@ -112,6 +115,34 @@ export async function updatePackages(packages) {
     }
     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";

package/dist/packages/installer.test.js

@@ -12,7 +12,7 @@ vi.mock("node:util", async () => {
         promisify: () => mockExecFile,
     };
 });
-const { installPackages, uninstallPackage, getInstalledVersion, getLatestVersion, updatePackages, } = await import("./installer.js");
+const { installPackages, uninstallPackage, getInstalledVersion, getLatestVersion, updatePackages, isClaudeCliAvailable, getGlobalPackagePath, } = await import("./installer.js");
 describe("installer", () => {
     beforeEach(() => {
         mockExecFile.mockReset();
@@ -197,4 +197,87 @@ describe("installer", () => {
             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 {};