@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/plugins/installer/install.js

@@ -0,0 +1,123 @@
+import { existsSync, statSync } from "node:fs";
+import { mkdir, writeFile, readFile, readdir, cp, rm, rename, } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { detectPluginFormat } from "./detectFormat.js";
+import { pluginInstallDir, pluginsRoot, assertSafePluginName } from "./paths.js";
+import { CodexPluginManifest, PluginInstallError } from "./types.js";
+import { convertCodexAgentToml } from "./codex/convertAgents.js";
+import { resolveCodexMcpServers } from "./codex/convertMcp.js";
+import { copyCodexSkills } from "./codex/convertSkills.js";
+import { copyCodexCommands } from "./codex/convertCommands.js";
+import { appendInstallEntry, pluginInstallKey } from "../installedPlugins.js";
+/**
+ * Install a local plugin directory into ~/.code-shell/plugins/<name>/.
+ * Builds into a temp sibling dir, then renames into place — a conversion
+ * failure leaves nothing behind. `installedAt` is passed in (caller stamps the
+ * timestamp) to keep this function pure of the unavailable Date.now().
+ */
+export async function installPluginFromPath(sourceDir, name, installedAt) {
+    assertSafePluginName(name);
+    if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {
+        throw new PluginInstallError(`source is not a directory: ${sourceDir}`);
+    }
+    const finalDir = pluginInstallDir(name);
+    if (existsSync(finalDir)) {
+        throw new PluginInstallError(`plugin '${name}' already installed; uninstall first or rename the source`);
+    }
+    await mkdir(pluginsRoot(), { recursive: true });
+    const tmpDir = join(pluginsRoot(), `.tmp-${name}-${process.pid}`);
+    await rm(tmpDir, { recursive: true, force: true });
+    await mkdir(tmpDir, { recursive: true });
+    try {
+        const format = detectPluginFormat(sourceDir);
+        let meta;
+        if (format === "cc") {
+            // Async cp: a recursive copy of a whole plugin dir is the dominant cost
+            // here; awaiting it yields the event loop so the Electron main process
+            // keeps answering IPC (no UI freeze during install).
+            await cp(sourceDir, tmpDir, { recursive: true });
+            // Read the declared version from .claude-plugin/plugin.json so the
+            // install record (and the UI's "installed version" chip) shows e.g.
+            // "v0.1.0" instead of falling back to the literal "local". Best-effort:
+            // CC plugins commonly omit version, and the file may be absent/malformed.
+            const version = await readCcPluginVersion(sourceDir);
+            meta = { name, format: "cc", version, source: sourceDir, installedAt };
+        }
+        else {
+            const manifest = CodexPluginManifest.parse(JSON.parse(await readFile(join(sourceDir, ".codex-plugin", "plugin.json"), "utf-8")));
+            // skills (verbatim copy)
+            await copyCodexSkills(sourceDir, tmpDir);
+            // agents (TOML → MD)
+            await convertAgentsInto(sourceDir, tmpDir, name);
+            // prompts/ (+ commands/) → commands/ (Codex slash commands == CC commands)
+            await copyCodexCommands(sourceDir, tmpDir);
+            // mcp → mcp-servers.json keyed <plugin>:<server>
+            const servers = resolveCodexMcpServers(sourceDir, manifest.mcpServers);
+            const keyed = {};
+            for (const [serverName, cfg] of Object.entries(servers)) {
+                const key = `${name}:${serverName}`;
+                keyed[key] = { ...cfg, name: key };
+            }
+            if (Object.keys(keyed).length > 0) {
+                await writeFile(join(tmpDir, "mcp-servers.json"), JSON.stringify(keyed, null, 2));
+            }
+            meta = { name, format: "codex", version: manifest.version, source: sourceDir, installedAt };
+        }
+        await writeFile(join(tmpDir, ".cs-meta.json"), JSON.stringify(meta, null, 2));
+        await rename(tmpDir, finalDir);
+        // Register so existing loaders (scanInstalledPlugins / loadPluginHooks)
+        // discover this local install. Marketplace tag "local" distinguishes it
+        // from cache/marketplace installs.
+        appendInstallEntry(pluginInstallKey(name, "local"), {
+            scope: "user",
+            installPath: finalDir,
+            version: meta.version ?? "local",
+            installedAt,
+            lastUpdated: installedAt,
+        });
+        return finalDir;
+    }
+    catch (err) {
+        await rm(tmpDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+/**
+ * Best-effort read of a CC plugin's declared version from
+ * <sourceDir>/.claude-plugin/plugin.json. Returns undefined when the file is
+ * absent, unparseable, or has no string `version` — the caller then records the
+ * install without a version (UI shows the source tag instead of a number).
+ */
+async function readCcPluginVersion(sourceDir) {
+    try {
+        const raw = await readFile(join(sourceDir, ".claude-plugin", "plugin.json"), "utf-8");
+        const v = JSON.parse(raw).version;
+        return typeof v === "string" && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Walk <sourceDir>/agents/**.toml → <destDir>/agents/**.md (structure preserved). */
+async function convertAgentsInto(sourceDir, destDir, pluginName) {
+    const agentsSrc = join(sourceDir, "agents");
+    if (!existsSync(agentsSrc))
+        return;
+    const walk = async (dir) => {
+        for (const dirent of await readdir(dir, { withFileTypes: true })) {
+            const abs = join(dir, dirent.name);
+            if (dirent.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (!dirent.name.endsWith(".toml"))
+                continue;
+            const rel = relative(agentsSrc, abs).replace(/\.toml$/, ".md");
+            const outPath = join(destDir, "agents", rel);
+            await mkdir(join(outPath, ".."), { recursive: true });
+            const md = convertCodexAgentToml(await readFile(abs, "utf-8"), rel, pluginName);
+            await writeFile(outPath, md);
+        }
+    };
+    await walk(agentsSrc);
+}

package/dist/plugins/installer/installFromArchive.d.ts

@@ -0,0 +1,43 @@
+/** Options for the unified local-install entry. */
+export interface InstallLocalOptions {
+    /**
+     * When the target name is already installed, replace it instead of throwing
+     * "already installed". The replace is atomic (rename-backup + rollback via
+     * {@link reinstallAtomic}), so a failed overwrite keeps the old version and
+     * its registration intact. Unlike a manual uninstall+install, this preserves
+     * the user's disable flags in settings (an upgrade is not a removal).
+     */
+    overwrite?: boolean;
+}
+/**
+ * Install a local plugin from a .zip archive.
+ *
+ * Mirrors installFromSource (the git path): extract to a private temp dir,
+ * locate the plugin root inside it, hand off to the local installer (which
+ * does CC/Codex detect + convert + register), then always clean up the temp
+ * dir. On any failure nothing is left behind.
+ *
+ * `name` is optional — when omitted it is derived from the plugin manifest
+ * (`name` field) or, failing that, the archive's top-level directory. The
+ * caller stamps `installedAt` to keep this pure of the unavailable Date.now().
+ */
+export declare function installPluginFromArchive(zipPath: string, installedAt: string, name?: string, options?: InstallLocalOptions): Promise<{
+    dir: string;
+    name: string;
+}>;
+/**
+ * Unified local-install entry for the desktop/UI: takes either a directory or
+ * a .zip and installs it as a global plugin, deriving the name when not given.
+ * The host (which has Date.now) stamps `installedAt`.
+ *
+ * For a directory we still run findPluginRoot/deriveName so a user can point at
+ * a repo checkout whose plugin sits one level down, and so the name comes from
+ * the manifest rather than forcing the caller to guess it.
+ */
+export declare function installLocalPlugin(input: {
+    kind: "dir" | "zip";
+    path: string;
+}, installedAt: string, name?: string, options?: InstallLocalOptions): Promise<{
+    dir: string;
+    name: string;
+}>;

package/dist/plugins/installer/installFromArchive.js

@@ -0,0 +1,134 @@
+import { existsSync, statSync } from "node:fs";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { extractZip } from "./unzip.js";
+import { installPluginFromPath } from "./install.js";
+import { reinstallAtomic } from "./update.js";
+import { pluginInstallDir } from "./paths.js";
+import { PluginInstallError } from "./types.js";
+/**
+ * Install `root` as plugin `name`, atomically replacing an already-installed
+ * plugin of the same name when `overwrite` is set. When no same-name plugin
+ * exists this is a plain install (overwrite is a no-op). `root` must stay valid
+ * for the duration of the call (zip callers keep their extracted temp dir alive
+ * until this resolves).
+ */
+async function installRootMaybeOverwrite(root, resolvedName, installedAt, overwrite) {
+    const finalDir = pluginInstallDir(resolvedName);
+    if (overwrite && existsSync(finalDir)) {
+        await reinstallAtomic(resolvedName, root, () => installPluginFromPath(root, resolvedName, installedAt));
+        return finalDir;
+    }
+    return installPluginFromPath(root, resolvedName, installedAt);
+}
+/**
+ * Install a local plugin from a .zip archive.
+ *
+ * Mirrors installFromSource (the git path): extract to a private temp dir,
+ * locate the plugin root inside it, hand off to the local installer (which
+ * does CC/Codex detect + convert + register), then always clean up the temp
+ * dir. On any failure nothing is left behind.
+ *
+ * `name` is optional — when omitted it is derived from the plugin manifest
+ * (`name` field) or, failing that, the archive's top-level directory. The
+ * caller stamps `installedAt` to keep this pure of the unavailable Date.now().
+ */
+export async function installPluginFromArchive(zipPath, installedAt, name, options) {
+    if (!existsSync(zipPath) || !statSync(zipPath).isFile()) {
+        throw new PluginInstallError(`archive is not a file: ${zipPath}`);
+    }
+    const tmp = await mkdtemp(join(tmpdir(), "cs-tmp-zip-"));
+    try {
+        await extractZip(zipPath, tmp);
+        const root = await findPluginRoot(tmp);
+        const resolvedName = normalizePluginName(name ?? (await deriveName(root)));
+        // Overwrite (when set) runs inside this try so the extracted `root` is still
+        // present while reinstallAtomic installs from it; the finally removes tmp.
+        const dir = await installRootMaybeOverwrite(root, resolvedName, installedAt, options?.overwrite ?? false);
+        return { dir, name: resolvedName };
+    }
+    finally {
+        await rm(tmp, { recursive: true, force: true });
+    }
+}
+/**
+ * Unified local-install entry for the desktop/UI: takes either a directory or
+ * a .zip and installs it as a global plugin, deriving the name when not given.
+ * The host (which has Date.now) stamps `installedAt`.
+ *
+ * For a directory we still run findPluginRoot/deriveName so a user can point at
+ * a repo checkout whose plugin sits one level down, and so the name comes from
+ * the manifest rather than forcing the caller to guess it.
+ */
+export async function installLocalPlugin(input, installedAt, name, options) {
+    if (input.kind === "zip") {
+        return installPluginFromArchive(input.path, installedAt, name, options);
+    }
+    if (!existsSync(input.path) || !statSync(input.path).isDirectory()) {
+        throw new PluginInstallError(`source is not a directory: ${input.path}`);
+    }
+    const root = await findPluginRoot(input.path);
+    const resolvedName = normalizePluginName(name ?? (await deriveName(root)));
+    const dir = await installRootMaybeOverwrite(root, resolvedName, installedAt, options?.overwrite ?? false);
+    return { dir, name: resolvedName };
+}
+/**
+ * A plugin root is a dir that holds a recognizable manifest or component dir.
+ * Zip archives commonly wrap everything in a single top-level folder, so if
+ * `dir` itself isn't a plugin root but contains exactly one subdirectory, dive
+ * one level. Only one level — deeper nesting is treated as malformed.
+ */
+async function findPluginRoot(dir) {
+    if (looksLikePluginRoot(dir))
+        return dir;
+    const entries = await readdir(dir, { withFileTypes: true });
+    const subDirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith("."));
+    if (subDirs.length === 1) {
+        const nested = join(dir, subDirs[0].name);
+        if (looksLikePluginRoot(nested))
+            return nested;
+    }
+    throw new PluginInstallError("no plugin found in archive (expected .claude-plugin/plugin.json, .codex-plugin/plugin.json, or a skills/commands/agents/hooks directory)");
+}
+function looksLikePluginRoot(dir) {
+    return (existsSync(join(dir, ".claude-plugin", "plugin.json")) ||
+        existsSync(join(dir, ".codex-plugin", "plugin.json")) ||
+        ["skills", "commands", "agents", "hooks"].some((d) => existsSync(join(dir, d))));
+}
+/** Read the `name` field from a CC or Codex manifest; fall back to the dir name. */
+async function deriveName(root) {
+    for (const rel of [
+        [".claude-plugin", "plugin.json"],
+        [".codex-plugin", "plugin.json"],
+    ]) {
+        const manifestPath = join(root, ...rel);
+        if (!existsSync(manifestPath))
+            continue;
+        try {
+            const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
+            if (typeof parsed.name === "string" && parsed.name.trim())
+                return parsed.name.trim();
+        }
+        catch {
+            // Malformed manifest → fall through to dir-name derivation.
+        }
+    }
+    return root.split(/[\\/]/).filter(Boolean).pop() ?? "plugin";
+}
+/**
+ * Coerce an arbitrary derived name into a safe single path segment:
+ * lowercase, only [a-z0-9._-], collapse the rest to '-'. assertSafePluginName
+ * (called by installPluginFromPath) rejects separators outright; this makes a
+ * manifest name like "My Plugin" usable instead of erroring.
+ */
+function normalizePluginName(raw) {
+    const cleaned = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "");
+    if (!cleaned)
+        throw new PluginInstallError(`cannot derive a valid plugin name from: ${JSON.stringify(raw)}`);
+    return cleaned;
+}

package/dist/plugins/installer/installFromSource.d.ts

@@ -0,0 +1,13 @@
+import type { ParsedSource } from "./parseSource.js";
+/**
+ * Remote install orchestrator: a thin bridge over the existing pieces. Clone
+ * the git source to a private temp dir, hand the (sub)directory to the local
+ * installer (which does CC/Codex detect + convert + register), then rewrite
+ * the recorded `.cs-meta.json` source back to the original git string so
+ * `plugin list`/`update` see the git source instead of the throwaway clone.
+ *
+ * Guarantees: on any failure nothing is left behind — the temp clone is always
+ * removed, and `installPluginFromPath` itself leaves no half-built install dir.
+ * See spec docs/superpowers/specs/2026-05-29-plugin-remote-install-design.md.
+ */
+export declare function installPluginFromSource(parsed: ParsedSource, name: string, installedAt: string): Promise<string>;

package/dist/plugins/installer/installFromSource.js

@@ -0,0 +1,51 @@
+import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { gitClone, gitRevParseHead } from "../gitOps.js";
+import { installPluginFromPath } from "./install.js";
+import { pluginMetaPath } from "./paths.js";
+import { PluginInstallError } from "./types.js";
+/**
+ * Remote install orchestrator: a thin bridge over the existing pieces. Clone
+ * the git source to a private temp dir, hand the (sub)directory to the local
+ * installer (which does CC/Codex detect + convert + register), then rewrite
+ * the recorded `.cs-meta.json` source back to the original git string so
+ * `plugin list`/`update` see the git source instead of the throwaway clone.
+ *
+ * Guarantees: on any failure nothing is left behind — the temp clone is always
+ * removed, and `installPluginFromPath` itself leaves no half-built install dir.
+ * See spec docs/superpowers/specs/2026-05-29-plugin-remote-install-design.md.
+ */
+export async function installPluginFromSource(parsed, name, installedAt) {
+    if (parsed.kind !== "remote") {
+        throw new PluginInstallError("installPluginFromSource expects a remote source");
+    }
+    const tmp = mkdtempSync(join(tmpdir(), "cs-tmp-clone-"));
+    try {
+        const clone = await gitClone(parsed.url, tmp, { ref: parsed.ref, full: true });
+        if (!clone.ok) {
+            throw new PluginInstallError(`clone failed: ${clone.error}`);
+        }
+        const realSrc = parsed.subdir ? join(tmp, parsed.subdir) : tmp;
+        if (!existsSync(realSrc) || !statSync(realSrc).isDirectory()) {
+            throw new PluginInstallError(`subdir not found in repo: ${parsed.subdir}`);
+        }
+        const dir = await installPluginFromPath(realSrc, name, installedAt);
+        // Rewrite source: realSrc is the throwaway clone path; record the git
+        // string so list/update can re-clone later.
+        const metaPath = pluginMetaPath(name);
+        const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+        meta.source = parsed.raw;
+        // Record the cloned repo's HEAD sha so `checkPluginUpdate` can compare it
+        // against `git ls-remote` later. A failed rev-parse only means "can't check
+        // updates", never an install failure — so omit commit and carry on.
+        const head = await gitRevParseHead(tmp);
+        if (head.ok)
+            meta.commit = head.stdout;
+        writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+        return dir;
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/plugins/installer/list.d.ts

@@ -0,0 +1,9 @@
+export interface PluginListRow {
+    name: string;
+    format: "cc" | "codex";
+    version?: string;
+    source: string;
+    installedAt: string;
+}
+/** Read .cs-meta.json from each registered plugin dir that has one (local installs). */
+export declare function listInstalledPlugins(): PluginListRow[];

package/dist/plugins/installer/list.js

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readInstalledPlugins } from "../installedPlugins.js";
+import { CSMeta } from "./types.js";
+/** Read .cs-meta.json from each registered plugin dir that has one (local installs). */
+export function listInstalledPlugins() {
+    const rows = [];
+    const data = readInstalledPlugins();
+    for (const entries of Object.values(data.plugins)) {
+        for (const entry of entries) {
+            const metaPath = join(entry.installPath, ".cs-meta.json");
+            if (!existsSync(metaPath))
+                continue;
+            try {
+                const meta = CSMeta.parse(JSON.parse(readFileSync(metaPath, "utf-8")));
+                rows.push({
+                    name: meta.name,
+                    format: meta.format,
+                    version: meta.version,
+                    source: meta.source,
+                    installedAt: meta.installedAt,
+                });
+            }
+            catch {
+                // not a local cs-managed install; skip
+            }
+        }
+    }
+    return rows;
+}

package/dist/plugins/installer/loadPluginAgents.d.ts

@@ -0,0 +1,3 @@
+import type { AgentSourceDir } from "../../agent/agent-definition-registry.js";
+/** Agent source dirs contributed by installed plugins (each <installPath>/agents). */
+export declare function pluginAgentDirs(disabledPlugins?: string[]): AgentSourceDir[];

package/dist/plugins/installer/loadPluginAgents.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readInstalledPlugins } from "../installedPlugins.js";
+function pluginNameFromKey(key) {
+    const at = key.lastIndexOf("@");
+    return at > 0 ? key.slice(0, at) : key;
+}
+/** Agent source dirs contributed by installed plugins (each <installPath>/agents). */
+export function pluginAgentDirs(disabledPlugins = []) {
+    const disabled = new Set(disabledPlugins);
+    const out = [];
+    const data = readInstalledPlugins();
+    for (const [key, entries] of Object.entries(data.plugins)) {
+        const pluginName = pluginNameFromKey(key);
+        if (disabled.has(pluginName))
+            continue;
+        for (const entry of entries) {
+            const dir = join(entry.installPath, "agents");
+            // Carry pluginName so a plugin agent's bare skill allowlist
+            // (`director-skill`) can be namespaced to `<pluginName>:director-skill`
+            // at spawn time — see resolveAgentTypeOverrides.
+            if (existsSync(dir))
+                out.push({ dir, source: "plugin", pluginName });
+        }
+    }
+    return out;
+}

package/dist/plugins/installer/loadPluginMcp.d.ts

@@ -0,0 +1,14 @@
+import type { MCPServerConfig, MCPServerOverride } from "../../types.js";
+/**
+ * Merge each registered plugin's MCP servers into a copy of `base`.
+ * Plugin keys are `<plugin>:<server>`. A key already present in `base`
+ * (user-configured) is NOT overwritten. Disabled plugins are skipped.
+ *
+ * `overrides` lets the user *supplement* a plugin server's env/credential
+ * fields without editing the plugin's manifest: for a plugin-sourced server,
+ * the override's {@link OVERRIDE_FIELDS} are layered on top (override wins),
+ * while command/args/url/transport stay from the plugin. Overrides do NOT
+ * apply to user-added (base) servers — those are edited via `mcpServers`
+ * directly — and an override for an unknown/disabled server has no effect.
+ */
+export declare function mergePluginMcpServers(base: Record<string, MCPServerConfig>, disabledPlugins?: string[], overrides?: Record<string, MCPServerOverride>): Record<string, MCPServerConfig>;

package/dist/plugins/installer/loadPluginMcp.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readInstalledPlugins } from "../installedPlugins.js";
+function pluginNameFromKey(key) {
+    const at = key.lastIndexOf("@");
+    return at > 0 ? key.slice(0, at) : key;
+}
+/**
+ * Layer a user override's supplement fields onto a plugin server config.
+ *
+ * Only env/credential fields are picked — command/args/url/transport are
+ * deliberately NOT carried, because those are the plugin's identity and must
+ * keep coming from the plugin manifest so a plugin update can change them
+ * without the user being stuck on a stale shadow copy. This explicit pick is
+ * defense-in-depth on top of the schema's `.strict()`, so a hand-edited
+ * settings file can never smuggle those fields in.
+ */
+function applyOverride(pluginConfig, override) {
+    if (!override)
+        return pluginConfig;
+    const supplement = {};
+    if (override.env !== undefined)
+        supplement.env = override.env;
+    if (override.envVars !== undefined)
+        supplement.envVars = override.envVars;
+    if (override.credentialRef !== undefined)
+        supplement.credentialRef = override.credentialRef;
+    if (override.bearerTokenEnvVar !== undefined)
+        supplement.bearerTokenEnvVar = override.bearerTokenEnvVar;
+    if (override.envHeaders !== undefined)
+        supplement.envHeaders = override.envHeaders;
+    return { ...pluginConfig, ...supplement };
+}
+/**
+ * Read a single plugin's MCP servers, already keyed `<plugin>:<server>`.
+ *
+ * Two on-disk shapes are supported:
+ *  - `mcp-servers.json` — the Codex-install product: already keyed + named.
+ *  - `.mcp.json` — what a CC plugin ships verbatim (Docker's mcp-toolkit etc.).
+ *    It uses a `{ mcpServers: {...} }` wrapper with bare server names; we unwrap
+ *    it and apply the `<plugin>:` prefix + `name` so it matches the keyed shape.
+ *
+ * `mcp-servers.json` wins if both exist. Malformed files yield {} (must not
+ * break startup).
+ */
+function readPluginMcp(installPath, pluginName) {
+    const keyedPath = join(installPath, "mcp-servers.json");
+    if (existsSync(keyedPath)) {
+        try {
+            return JSON.parse(readFileSync(keyedPath, "utf-8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    const rawPath = join(installPath, ".mcp.json");
+    if (existsSync(rawPath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(rawPath, "utf-8"));
+        }
+        catch {
+            return {};
+        }
+        const servers = parsed && typeof parsed === "object" && "mcpServers" in parsed
+            ? parsed.mcpServers ?? {}
+            : parsed ?? {};
+        const keyed = {};
+        for (const [serverName, cfg] of Object.entries(servers)) {
+            const key = `${pluginName}:${serverName}`;
+            keyed[key] = { ...cfg, name: key };
+        }
+        return keyed;
+    }
+    return {};
+}
+/**
+ * Merge each registered plugin's MCP servers into a copy of `base`.
+ * Plugin keys are `<plugin>:<server>`. A key already present in `base`
+ * (user-configured) is NOT overwritten. Disabled plugins are skipped.
+ *
+ * `overrides` lets the user *supplement* a plugin server's env/credential
+ * fields without editing the plugin's manifest: for a plugin-sourced server,
+ * the override's {@link OVERRIDE_FIELDS} are layered on top (override wins),
+ * while command/args/url/transport stay from the plugin. Overrides do NOT
+ * apply to user-added (base) servers — those are edited via `mcpServers`
+ * directly — and an override for an unknown/disabled server has no effect.
+ */
+export function mergePluginMcpServers(base, disabledPlugins = [], overrides = {}) {
+    const disabled = new Set(disabledPlugins);
+    const merged = { ...base };
+    const data = readInstalledPlugins();
+    for (const [key, entries] of Object.entries(data.plugins)) {
+        const pluginName = pluginNameFromKey(key);
+        if (disabled.has(pluginName))
+            continue;
+        for (const entry of entries) {
+            const servers = readPluginMcp(entry.installPath, pluginName);
+            for (const [k, cfg] of Object.entries(servers)) {
+                if (k in merged)
+                    continue; // user / earlier wins
+                merged[k] = applyOverride(cfg, overrides[k]);
+            }
+        }
+    }
+    return merged;
+}

package/dist/plugins/installer/parseSource.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Result of classifying a `plugin install <source>` argument. Pure parse — no
+ * I/O, no execution. `local` resolves to an absolute path; `remote` carries a
+ * git-cloneable URL plus optional ref/subdir and the original raw string
+ * (written back into .cs-meta.json so `plugin list`/`update` see the git
+ * source, not the throwaway clone path). See spec
+ * docs/superpowers/specs/2026-05-29-plugin-remote-install-design.md §4–§5.
+ */
+export type ParsedSource = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "remote";
+    url: string;
+    ref?: string;
+    subdir?: string;
+    raw: string;
+    inferredName: string;
+};
+export declare function parseSource(input: string): ParsedSource;

package/dist/plugins/installer/parseSource.js

@@ -0,0 +1,74 @@
+import { resolve } from "node:path";
+import { githubRepoToCloneUrl } from "../gitOps.js";
+/** SSH shorthand `git@host:org/repo.git` — has a `:` after the `git@host` part. */
+function isSshUrl(s) {
+    return /^[^/]+@[^/]+:/.test(s) && !s.includes("://");
+}
+function isRemote(s) {
+    return (s.startsWith("github:") ||
+        s.startsWith("https://") ||
+        s.startsWith("http://") ||
+        s.startsWith("git://") ||
+        s.startsWith("file://") ||
+        isSshUrl(s));
+}
+/** Last path segment of a repo url/path, with a trailing `.git` stripped. */
+function repoNameFromUrl(url) {
+    const noGit = url.replace(/\.git$/, "");
+    const seg = noGit.split(/[/:]/).filter(Boolean).pop() ?? noGit;
+    return seg;
+}
+/** Last path segment of a subdir. */
+function lastSegment(p) {
+    return p.split("/").filter(Boolean).pop() ?? p;
+}
+export function parseSource(input) {
+    if (!isRemote(input)) {
+        return { kind: "local", path: resolve(input) };
+    }
+    const raw = input;
+    // 1. Split off `#subdir` (last `#`).
+    let rest = input;
+    let subdir;
+    const hashIdx = rest.indexOf("#");
+    if (hashIdx >= 0) {
+        subdir = rest.slice(hashIdx + 1) || undefined;
+        rest = rest.slice(0, hashIdx);
+    }
+    // 2. Split off `@ref`. SSH form `git@host:...` contains its own `@`, so
+    //    strip the leading `user@` first, then look for a ref `@` in the tail.
+    let ref;
+    let base = rest;
+    if (isSshUrl(rest)) {
+        const at = rest.indexOf("@");
+        const head = rest.slice(0, at + 1); // "git@"
+        const tail = rest.slice(at + 1); // "host:org/repo.git@ref"
+        const tailAt = tail.lastIndexOf("@");
+        if (tailAt >= 0) {
+            ref = tail.slice(tailAt + 1) || undefined;
+            base = head + tail.slice(0, tailAt);
+        }
+    }
+    else {
+        const at = rest.lastIndexOf("@");
+        if (at >= 0) {
+            ref = rest.slice(at + 1) || undefined;
+            base = rest.slice(0, at);
+        }
+    }
+    // 3. Normalize url.
+    let url;
+    if (base.startsWith("github:")) {
+        url = githubRepoToCloneUrl(base.slice("github:".length));
+    }
+    else {
+        url = base;
+    }
+    const inferredName = subdir ? lastSegment(subdir) : repoNameFromUrl(url);
+    const result = { kind: "remote", url, raw, inferredName };
+    if (ref)
+        result.ref = ref;
+    if (subdir)
+        result.subdir = subdir;
+    return result;
+}

package/dist/plugins/installer/paths.d.ts

@@ -0,0 +1,5 @@
+/** A plugin name must be a single safe path segment — no separators, no traversal. */
+export declare function assertSafePluginName(name: string): void;
+export declare function pluginsRoot(): string;
+export declare function pluginInstallDir(name: string): string;
+export declare function pluginMetaPath(name: string): string;