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

package/dist/plugins/gitOps.js

@@ -15,6 +15,17 @@
  * classification. See docs/architecture/17 for the trust framing.
  */
 import { safeSpawn } from "../runtime/safe-spawn.js";
+import { resolveGit, isGitAvailable } from "../utils/exec.js";
+/**
+ * On a fresh macOS without the Command Line Tools, `/usr/bin/git` is an `xcrun`
+ * stub that spawns fine (so `isGitAvailable()`'s findExecutable check is fooled)
+ * but exits non-zero with an xcrun error on stderr. Classify that as a
+ * missing-git condition so runGit returns GIT_NOT_FOUND and the host shows the
+ * friendly "install Git" guidance instead of leaking the raw xcrun error.
+ */
+export function isMissingDeveloperToolsStderr(stderr) {
+    return /xcrun: error|not a developer tool|no developer tools/i.test(stderr);
+}
 /**
  * Force git to never prompt interactively. gitOps runs in headless contexts
  * (the Electron main process, the agent worker) that have no TTY, so a
@@ -37,7 +48,18 @@ export function nonInteractiveGitEnv(base) {
     };
 }
 async function runGit(args, cwd, timeoutMs = 60_000) {
-    const r = await safeSpawn("git", args, {
+    // Up-front check: if git isn't installed/reachable at all, return a clear,
+    // actionable error instead of a raw "spawn git ENOENT". The desktop host
+    // turns GIT_NOT_FOUND into a friendly "install Git" prompt.
+    if (!isGitAvailable()) {
+        return {
+            ok: false,
+            error: "GIT_NOT_FOUND: git was not found. Install Git (https://git-scm.com/downloads) " +
+                "and restart, or set the `git.path` setting to your git binary.",
+        };
+    }
+    // Resolve git: user `git.path` override, else PATH×PATHEXT (.cmd/.exe on Win).
+    const r = await safeSpawn(resolveGit(), args, {
         cwd: cwd ?? process.cwd(),
         env: nonInteractiveGitEnv(process.env),
         timeoutMs,
@@ -51,6 +73,16 @@ async function runGit(args, cwd, timeoutMs = 60_000) {
     if (r.exitCode === 0) {
         return { ok: true, stdout: r.stdout.trim() };
     }
+    // mac CLT-missing stub: git spawned but exited non-zero with an xcrun error —
+    // treat as not-installed so the host shows install guidance (not a raw error).
+    if (isMissingDeveloperToolsStderr(r.stderr)) {
+        return {
+            ok: false,
+            error: "GIT_NOT_FOUND: git was not found (the macOS Command Line Tools are not installed). " +
+                "Run `xcode-select --install`, or install Git from https://git-scm.com/downloads, " +
+                "then restart — or set the `git.path` setting to your git binary.",
+        };
+    }
     return {
         ok: false,
         error: `git ${args.join(" ")} exited ${r.exitCode}: ${r.stderr.trim() || "unknown error"}`,
@@ -67,6 +99,11 @@ async function runGit(args, cwd, timeoutMs = 60_000) {
  * (.claude-plugin and .agents/plugins). On any failure of the sparse setup we
  * fall back to checking out the full tree, so correctness never depends on
  * sparse support being present.
+ *
+ * Pass `full: true` to skip sparse entirely and check out the whole tree. This
+ * is required when the caller reads arbitrary plugin content from the clone
+ * (installing a plugin or a plugin subdir), as opposed to a marketplace where
+ * only the manifest dirs are needed up front.
  */
 export async function gitClone(url, destDir, options) {
     const sparsePaths = options?.sparsePaths ?? [".claude-plugin", ".agents/plugins"];
@@ -77,9 +114,20 @@ export async function gitClone(url, destDir, options) {
     const cloned = await runGit(args);
     if (!cloned.ok)
         return cloned;
+    // Full-tree clone: skip sparse setup and check out everything. Used by plugin
+    // content clones, which read files anywhere in the repo.
+    if (options?.full) {
+        const checkout = await runGit(["checkout"], destDir);
+        if (!checkout.ok)
+            return checkout;
+        return cloned;
+    }
     // Restrict the working tree to the manifest dirs, then check out. Use
     // non-cone mode so nested paths like ".agents/plugins" match exactly.
-    const init = await runGit(["sparse-checkout", "set", "--no-cone", ...sparsePaths], destDir);
+    // `--` before the manifest-derived paths: a malicious manifest path shaped
+    // like `--stdin`/`--cone` would otherwise be parsed as a sparse-checkout flag
+    // (arg-injection). No RCE flag here as in ls-remote, but match the discipline.
+    const init = await runGit(["sparse-checkout", "set", "--no-cone", "--", ...sparsePaths], destDir);
     if (!init.ok) {
         // Sparse unsupported/failed — fall back to a normal full checkout so the
         // manifest is still present.
@@ -96,15 +144,36 @@ export async function gitClone(url, destDir, options) {
  * harmlessly and the caller proceeds (the files are already present).
  */
 export async function gitSparseCheckoutAdd(repoDir, relPath) {
-    return runGit(["sparse-checkout", "add", relPath], repoDir);
+    return runGit(["sparse-checkout", "add", "--", relPath], repoDir);
 }
 export async function gitRevParseHead(repoDir) {
     return runGit(["rev-parse", "HEAD"], repoDir);
 }
+/**
+ * Resolve a ref (default HEAD) on a remote git URL WITHOUT cloning — one
+ * cheap network round-trip. Returns the 40-char SHA on success.
+ */
+export async function gitLsRemote(url, ref) {
+    // `git ls-remote <url> <ref>` prints "<sha>\t<refname>"; take the first sha.
+    // SECURITY: the `--` end-of-options separator is REQUIRED before a
+    // user-controlled `url`. Without it a marketplace/plugin URL shaped like
+    // `--upload-pack=<cmd>` is parsed as a git flag and git EXECUTES <cmd> (RCE).
+    // gitClone already does this (`-- url destDir`); ls-remote must match.
+    const r = await runGit(["ls-remote", "--", url, ref ?? "HEAD"]);
+    if (!r.ok)
+        return r;
+    const sha = r.stdout.split(/\s+/)[0] ?? "";
+    if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
+        return { ok: false, error: `ls-remote: no sha for ${ref ?? "HEAD"} in: ${r.stdout.slice(0, 120)}` };
+    }
+    return { ok: true, stdout: sha };
+}
 export async function gitFetchAndReset(repoDir, ref) {
     const fetchArgs = ["fetch", "--depth", "1", "origin"];
+    // `--` before a (possibly user/manifest-derived) ref so a flag-shaped ref
+    // can't be parsed as a git fetch option. Consistent with clone/ls-remote.
     if (ref)
-        fetchArgs.push(ref);
+        fetchArgs.push("--", ref);
     const fetch = await runGit(fetchArgs, repoDir);
     if (!fetch.ok)
         return fetch;

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

@@ -0,0 +1,16 @@
+export interface UpdateCheck {
+    name: string;
+    updateAvailable: boolean;
+    currentCommit?: string;
+    latestCommit?: string;
+    reason?: string;
+}
+/**
+ * Check whether a remote (git-sourced) plugin has a newer commit upstream,
+ * WITHOUT cloning. Compares the recorded install commit (meta.commit) against
+ * `git ls-remote`. Local-source plugins, older installs without a recorded
+ * commit, and ls-remote failures all resolve to `updateAvailable: false` with
+ * an explanatory `reason` rather than throwing — the only hard error is an
+ * unknown plugin name.
+ */
+export declare function checkPluginUpdate(name: string): Promise<UpdateCheck>;

package/dist/plugins/installer/checkUpdate.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import { gitLsRemote } from "../gitOps.js";
+import { pluginMetaPath } from "./paths.js";
+import { parseSource } from "./parseSource.js";
+import { CSMeta, PluginInstallError } from "./types.js";
+/**
+ * Check whether a remote (git-sourced) plugin has a newer commit upstream,
+ * WITHOUT cloning. Compares the recorded install commit (meta.commit) against
+ * `git ls-remote`. Local-source plugins, older installs without a recorded
+ * commit, and ls-remote failures all resolve to `updateAvailable: false` with
+ * an explanatory `reason` rather than throwing — the only hard error is an
+ * unknown plugin name.
+ */
+export async function checkPluginUpdate(name) {
+    const metaPath = pluginMetaPath(name);
+    if (!existsSync(metaPath))
+        throw new PluginInstallError(`no plugin named '${name}'`);
+    const meta = CSMeta.parse(JSON.parse(readFileSync(metaPath, "utf-8")));
+    const parsed = parseSource(meta.source);
+    if (parsed.kind !== "remote") {
+        return { name, updateAvailable: false, reason: "not a remote source" };
+    }
+    if (!meta.commit) {
+        return { name, updateAvailable: false, reason: "no recorded commit to compare" };
+    }
+    const latest = await gitLsRemote(parsed.url, parsed.ref);
+    if (!latest.ok) {
+        return { name, updateAvailable: false, currentCommit: meta.commit, reason: latest.error };
+    }
+    const updateAvailable = latest.stdout.toLowerCase() !== meta.commit.toLowerCase();
+    return { name, updateAvailable, currentCommit: meta.commit, latestCommit: latest.stdout };
+}

package/dist/plugins/installer/codex/convertCommands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Map a Codex plugin's slash commands into CC's `commands/` layout.
+ *
+ * Codex `prompts/*.md` and CC `commands/*.md` are isomorphic: each is a
+ * markdown file (optional `description`/`argument-hint` frontmatter) whose
+ * basename becomes the command name, and codeshell's `pluginCommandsLoader`
+ * already scans `commands/*.md`. So the conversion is a flat copy of every
+ * `.md` from `prompts/` (and any explicit `commands/`) into `dest/commands/`.
+ *
+ * Placeholder syntax differs (Codex `$1`/`$FILE` vs CC `$ARGUMENTS`) but the
+ * body is copied verbatim — v1 inert, the same stance taken for `codex_`
+ * agent fields (see convertAgents.ts). Non-`.md` files are ignored, matching
+ * Codex's own behaviour. On a filename collision an explicit `commands/`
+ * entry wins over `prompts/` (the more specific source).
+ *
+ * Async fs throughout: this runs in the Electron main process during install;
+ * sync copies block the event loop and freeze the UI (see convertSkills.ts).
+ */
+export declare function copyCodexCommands(sourceDir: string, destDir: string): Promise<void>;

package/dist/plugins/installer/codex/convertCommands.js

@@ -0,0 +1,46 @@
+import { existsSync } from "node:fs";
+import { readdir, mkdir, copyFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Map a Codex plugin's slash commands into CC's `commands/` layout.
+ *
+ * Codex `prompts/*.md` and CC `commands/*.md` are isomorphic: each is a
+ * markdown file (optional `description`/`argument-hint` frontmatter) whose
+ * basename becomes the command name, and codeshell's `pluginCommandsLoader`
+ * already scans `commands/*.md`. So the conversion is a flat copy of every
+ * `.md` from `prompts/` (and any explicit `commands/`) into `dest/commands/`.
+ *
+ * Placeholder syntax differs (Codex `$1`/`$FILE` vs CC `$ARGUMENTS`) but the
+ * body is copied verbatim — v1 inert, the same stance taken for `codex_`
+ * agent fields (see convertAgents.ts). Non-`.md` files are ignored, matching
+ * Codex's own behaviour. On a filename collision an explicit `commands/`
+ * entry wins over `prompts/` (the more specific source).
+ *
+ * Async fs throughout: this runs in the Electron main process during install;
+ * sync copies block the event loop and freeze the UI (see convertSkills.ts).
+ */
+export async function copyCodexCommands(sourceDir, destDir) {
+    // prompts/ first, then commands/ — later writes overwrite earlier, so an
+    // explicit commands/ entry wins the collision.
+    const written = await copyMdFiles(join(sourceDir, "prompts"), join(destDir, "commands"));
+    await copyMdFiles(join(sourceDir, "commands"), join(destDir, "commands"), written);
+}
+/** Flat-copy *.md from srcDir into destDir; returns the set of basenames written. */
+async function copyMdFiles(srcDir, destDir, written = new Set()) {
+    if (!existsSync(srcDir))
+        return written;
+    let ensuredDest = false;
+    for (const dirent of await readdir(srcDir, { withFileTypes: true })) {
+        if (!dirent.isFile() && !dirent.isSymbolicLink())
+            continue;
+        if (!dirent.name.endsWith(".md"))
+            continue;
+        if (!ensuredDest) {
+            await mkdir(destDir, { recursive: true });
+            ensuredDest = true;
+        }
+        await copyFile(join(srcDir, dirent.name), join(destDir, dirent.name));
+        written.add(dirent.name);
+    }
+    return written;
+}

package/dist/plugins/installer/codex/convertMcp.d.ts

@@ -1,8 +1,11 @@
+export declare function normalizeCodexMcpFields(cfg: Record<string, unknown>): Record<string, unknown>;
 /**
  * Resolve a Codex manifest's mcpServers declaration into a plain server map.
- * - object → returned as-is (inline)
+ * Each server's env-secret fields are normalized from Codex's snake_case to
+ * our runtime camelCase (see normalizeCodexMcpFields).
+ * - object → normalized inline map
  * - string → read that file relative to sourceDir; accept either a bare map
- *   or a `{ mcpServers: {...} }` wrapper.
+ *   or a `{ mcpServers: {...} }` wrapper, then normalize.
  * - undefined → {}
  */
 export declare function resolveCodexMcpServers(sourceDir: string, decl: string | Record<string, unknown> | undefined): Record<string, unknown>;

package/dist/plugins/installer/codex/convertMcp.js

@@ -1,18 +1,58 @@
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { PluginInstallError } from "../types.js";
+/**
+ * Codex `.mcp.json` writes env-secret fields in snake_case
+ * (`bearer_token_env_var`, `env_http_headers`, `env_vars`), but our runtime
+ * MCP manager reads camelCase (`bearerTokenEnvVar`, `envHeaders`, `envVars` —
+ * see buildStdioEnv / buildHttpHeaders in tool-system/mcp-manager.ts). Nothing
+ * between install and connect runs these through a zod schema (install spreads
+ * the object verbatim; loadPluginMcp casts raw JSON), so without this re-key an
+ * imported Codex plugin's secret references would silently never apply and the
+ * server would connect without its auth header / env. Re-key one server config
+ * object. An already-present camelCase key wins over its snake_case twin so we
+ * never clobber the canonical form. Non-object input passes through unchanged.
+ */
+const CODEX_FIELD_MAP = {
+    bearer_token_env_var: "bearerTokenEnvVar",
+    env_http_headers: "envHeaders",
+    env_vars: "envVars",
+};
+export function normalizeCodexMcpFields(cfg) {
+    if (!cfg || typeof cfg !== "object" || Array.isArray(cfg))
+        return cfg;
+    const out = {};
+    for (const [key, value] of Object.entries(cfg)) {
+        const mapped = CODEX_FIELD_MAP[key];
+        // Skip the snake_case form if its camelCase twin is already present.
+        if (mapped && mapped in cfg)
+            continue;
+        out[mapped ?? key] = value;
+    }
+    return out;
+}
+/** Apply normalizeCodexMcpFields to every server in a name → config map. */
+function normalizeServerMap(servers) {
+    const out = {};
+    for (const [name, cfg] of Object.entries(servers)) {
+        out[name] = normalizeCodexMcpFields(cfg);
+    }
+    return out;
+}
 /**
  * Resolve a Codex manifest's mcpServers declaration into a plain server map.
- * - object → returned as-is (inline)
+ * Each server's env-secret fields are normalized from Codex's snake_case to
+ * our runtime camelCase (see normalizeCodexMcpFields).
+ * - object → normalized inline map
  * - string → read that file relative to sourceDir; accept either a bare map
- *   or a `{ mcpServers: {...} }` wrapper.
+ *   or a `{ mcpServers: {...} }` wrapper, then normalize.
  * - undefined → {}
  */
 export function resolveCodexMcpServers(sourceDir, decl) {
     if (decl === undefined)
         return {};
     if (typeof decl === "object")
-        return decl;
+        return normalizeServerMap(decl);
     // `decl` is an untrusted, unvalidated manifest field from a (possibly
     // remote-cloned) plugin. Resolve it and assert it stays inside sourceDir so
     // a value like "../../../../etc/secret.json" can't escape the plugin dir and
@@ -39,7 +79,7 @@ export function resolveCodexMcpServers(sourceDir, decl) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
         return {};
     if ("mcpServers" in parsed) {
-        return parsed.mcpServers ?? {};
+        return normalizeServerMap(parsed.mcpServers ?? {});
     }
-    return parsed;
+    return normalizeServerMap(parsed);
 }

package/dist/plugins/installer/install.js

@@ -7,6 +7,7 @@ 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>/.
@@ -35,7 +36,12 @@ export async function installPluginFromPath(sourceDir, name, installedAt) {
             // 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 });
-            meta = { name, format: "cc", source: sourceDir, installedAt };
+            // 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")));
@@ -43,6 +49,8 @@ export async function installPluginFromPath(sourceDir, name, installedAt) {
             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 = {};
@@ -74,6 +82,22 @@ export async function installPluginFromPath(sourceDir, name, installedAt) {
         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");

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.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { gitClone } from "../gitOps.js";
+import { gitClone, gitRevParseHead } from "../gitOps.js";
 import { installPluginFromPath } from "./install.js";
 import { pluginMetaPath } from "./paths.js";
 import { PluginInstallError } from "./types.js";
@@ -22,7 +22,7 @@ export async function installPluginFromSource(parsed, name, installedAt) {
     }
     const tmp = mkdtempSync(join(tmpdir(), "cs-tmp-clone-"));
     try {
-        const clone = await gitClone(parsed.url, tmp, { ref: parsed.ref });
+        const clone = await gitClone(parsed.url, tmp, { ref: parsed.ref, full: true });
         if (!clone.ok) {
             throw new PluginInstallError(`clone failed: ${clone.error}`);
         }
@@ -36,6 +36,12 @@ export async function installPluginFromSource(parsed, name, installedAt) {
         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;
     }

package/dist/plugins/installer/loadPluginAgents.js

@@ -11,12 +11,16 @@ export function pluginAgentDirs(disabledPlugins = []) {
     const out = [];
     const data = readInstalledPlugins();
     for (const [key, entries] of Object.entries(data.plugins)) {
-        if (disabled.has(pluginNameFromKey(key)))
+        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" });
+                out.push({ dir, source: "plugin", pluginName });
         }
     }
     return out;

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

@@ -1,7 +1,14 @@
-import type { MCPServerConfig } from "../../types.js";
+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[]): Record<string, MCPServerConfig>;
+export declare function mergePluginMcpServers(base: Record<string, MCPServerConfig>, disabledPlugins?: string[], overrides?: Record<string, MCPServerOverride>): Record<string, MCPServerConfig>;