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

package/dist/plugins/gitOps.d.ts

@@ -21,10 +21,63 @@ export type GitResult = {
     ok: false;
     error: string;
 };
+/**
+ * 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 declare function isMissingDeveloperToolsStderr(stderr: string): boolean;
+/**
+ * Force git to never prompt interactively. gitOps runs in headless contexts
+ * (the Electron main process, the agent worker) that have no TTY, so a
+ * private/auth-required clone or an unknown SSH host key would otherwise make
+ * git BLOCK on a credential/host-key prompt — the operation appears to hang
+ * until the safeSpawn timeout (or an off-screen askpass dialog). With these
+ * set, git fails fast with an auth error instead.
+ *
+ * - GIT_TERMINAL_PROMPT=0 — git's own username/password prompt becomes an error.
+ * - GIT_SSH_COMMAND BatchMode=yes — ssh never asks for a password/passphrase;
+ *   accept-new auto-trusts a first-seen host key (instead of the y/n prompt)
+ *   but still rejects a changed key. Not overridden if the caller already
+ *   provides GIT_SSH_COMMAND (e.g. a custom identity file).
+ */
+export declare function nonInteractiveGitEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Clone a marketplace repo cheaply. These repos can bundle hundreds of plugins
+ * (thousands of files), but adding a marketplace only needs its manifest — the
+ * individual plugin trees are pulled on demand at install time
+ * ({@link gitSparseCheckoutAdd}). So we do a blobless, no-checkout clone and
+ * then sparse-check out only the manifest directories.
+ *
+ * `sparsePaths` defaults to the two manifest locations we support
+ * (.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 declare function gitClone(url: string, destDir: string, options?: {
     ref?: string;
+    sparsePaths?: string[];
+    full?: boolean;
 }): Promise<GitResult>;
+/**
+ * Expand a sparse-checkout to include an additional path (a plugin subdir),
+ * materializing its blobs. Best-effort: if the repo isn't sparse this errors
+ * harmlessly and the caller proceeds (the files are already present).
+ */
+export declare function gitSparseCheckoutAdd(repoDir: string, relPath: string): Promise<GitResult>;
 export declare function gitRevParseHead(repoDir: string): Promise<GitResult>;
+/**
+ * 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 declare function gitLsRemote(url: string, ref?: string): Promise<GitResult>;
 export declare function gitFetchAndReset(repoDir: string, ref?: string): Promise<GitResult>;
 /**
  * Github source helper: convert "owner/repo" to an https clone URL.

package/dist/plugins/gitOps.js

@@ -15,10 +15,53 @@
  * 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
+ * private/auth-required clone or an unknown SSH host key would otherwise make
+ * git BLOCK on a credential/host-key prompt — the operation appears to hang
+ * until the safeSpawn timeout (or an off-screen askpass dialog). With these
+ * set, git fails fast with an auth error instead.
+ *
+ * - GIT_TERMINAL_PROMPT=0 — git's own username/password prompt becomes an error.
+ * - GIT_SSH_COMMAND BatchMode=yes — ssh never asks for a password/passphrase;
+ *   accept-new auto-trusts a first-seen host key (instead of the y/n prompt)
+ *   but still rejects a changed key. Not overridden if the caller already
+ *   provides GIT_SSH_COMMAND (e.g. a custom identity file).
+ */
+export function nonInteractiveGitEnv(base) {
+    return {
+        ...base,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_SSH_COMMAND: base.GIT_SSH_COMMAND ?? "ssh -oBatchMode=yes -oStrictHostKeyChecking=accept-new",
+    };
+}
 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: process.env,
+        env: nonInteractiveGitEnv(process.env),
         timeoutMs,
     });
     if (r.spawnFailed) {
@@ -30,25 +73,107 @@ 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"}`,
     };
 }
+/**
+ * Clone a marketplace repo cheaply. These repos can bundle hundreds of plugins
+ * (thousands of files), but adding a marketplace only needs its manifest — the
+ * individual plugin trees are pulled on demand at install time
+ * ({@link gitSparseCheckoutAdd}). So we do a blobless, no-checkout clone and
+ * then sparse-check out only the manifest directories.
+ *
+ * `sparsePaths` defaults to the two manifest locations we support
+ * (.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 args = ["clone", "--depth", "1"];
+    const sparsePaths = options?.sparsePaths ?? [".claude-plugin", ".agents/plugins"];
+    const args = ["clone", "--depth", "1", "--filter=blob:none", "--no-checkout"];
     if (options?.ref)
         args.push("--branch", options.ref);
     args.push("--", url, destDir);
-    return runGit(args);
+    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.
+    // `--` 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.
+        return runGit(["checkout"], destDir);
+    }
+    const checkout = await runGit(["checkout"], destDir);
+    if (!checkout.ok)
+        return checkout;
+    return cloned;
+}
+/**
+ * Expand a sparse-checkout to include an additional path (a plugin subdir),
+ * materializing its blobs. Best-effort: if the repo isn't sparse this errors
+ * harmlessly and the caller proceeds (the files are already present).
+ */
+export async function gitSparseCheckoutAdd(repoDir, relPath) {
+    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/convertAgents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert one Codex agent TOML into a CC agent Markdown string.
+ * Real CC fields: name, description, model, body(=developer_instructions).
+ * Every other field is preserved with a `codex_` prefix (v1 inert; see spec §7.1).
+ * `mcp_servers` values are rewritten to `<plugin>:<server>` to match the MCP merge key.
+ */
+export declare function convertCodexAgentToml(toml: string, sourceName: string, pluginName: string): string;

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

@@ -0,0 +1,55 @@
+import { parse as parseToml } from "smol-toml";
+import { stringify as stringifyYaml } from "yaml";
+import { serializeAgentDefinition } from "../../../agent/agent-definition.js";
+import { PluginInstallError } from "../types.js";
+const MAPPED = new Set(["name", "description", "model", "developer_instructions"]);
+/**
+ * Convert one Codex agent TOML into a CC agent Markdown string.
+ * Real CC fields: name, description, model, body(=developer_instructions).
+ * Every other field is preserved with a `codex_` prefix (v1 inert; see spec §7.1).
+ * `mcp_servers` values are rewritten to `<plugin>:<server>` to match the MCP merge key.
+ */
+export function convertCodexAgentToml(toml, sourceName, pluginName) {
+    let raw;
+    try {
+        raw = parseToml(toml);
+    }
+    catch (err) {
+        throw new PluginInstallError(`${sourceName}: invalid TOML — ${err.message}`);
+    }
+    if (typeof raw.name !== "string" || !raw.name.trim()) {
+        throw new PluginInstallError(`${sourceName}: missing required 'name'`);
+    }
+    if (typeof raw.description !== "string" || !raw.description.trim()) {
+        throw new PluginInstallError(`${sourceName}: missing required 'description'`);
+    }
+    const body = typeof raw.developer_instructions === "string" ? raw.developer_instructions.trim() : "";
+    const base = serializeAgentDefinition({
+        name: raw.name.trim(),
+        description: raw.description.trim(),
+        systemPrompt: body,
+        ...(typeof raw.model === "string" && raw.model.trim() ? { model: raw.model.trim() } : {}),
+    });
+    // Collect codex_-prefixed extras.
+    const extras = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (MAPPED.has(key))
+            continue;
+        const outKey = `codex_${key}`;
+        if (key === "mcp_servers" && Array.isArray(value)) {
+            extras[outKey] = value.map((s) => (typeof s === "string" ? `${pluginName}:${s}` : s));
+        }
+        else {
+            extras[outKey] = value;
+        }
+    }
+    if (Object.keys(extras).length === 0)
+        return base;
+    // Splice the extra YAML lines into the existing frontmatter block.
+    const extraYaml = stringifyYaml(extras).trimEnd();
+    const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(base);
+    if (!match)
+        throw new PluginInstallError(`${sourceName}: internal — serializer produced no frontmatter`);
+    const [, fm, rest] = match;
+    return `---\n${fm}\n${extraYaml}\n---\n${rest}`;
+}

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

@@ -0,0 +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.
+ * 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, 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

@@ -0,0 +1,85 @@
+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.
+ * 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, then normalize.
+ * - undefined → {}
+ */
+export function resolveCodexMcpServers(sourceDir, decl) {
+    if (decl === undefined)
+        return {};
+    if (typeof decl === "object")
+        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
+    // read arbitrary files into the install's mcp-servers.json.
+    const base = resolve(sourceDir);
+    const path = resolve(base, decl);
+    const rel = relative(base, path);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PluginInstallError(`mcpServers ref escapes plugin dir: ${decl}`);
+    }
+    if (!existsSync(path)) {
+        throw new PluginInstallError(`mcpServers ref not found: ${decl}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        throw new PluginInstallError(`invalid mcp json ${decl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Only objects yield server maps. An array/number/string that happens to
+    // parse is not a valid mcp config — return an empty map rather than casting
+    // a non-object to Record.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    if ("mcpServers" in parsed) {
+        return normalizeServerMap(parsed.mcpServers ?? {});
+    }
+    return normalizeServerMap(parsed);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Copy <sourceDir>/skills into <destDir>/skills verbatim (Codex & CC SKILL.md
+ * are isomorphic). Validates each SKILL.md has a frontmatter block first — a
+ * malformed skill fails the whole install (spec §10).
+ *
+ * Async fs throughout: this runs inside the Electron main process during
+ * install; a synchronous recursive copy (cpSync) blocks the event loop and
+ * freezes the UI. The sibling `cc` branch already awaits cp for this reason
+ * (see install.ts) — this mirrors the 178abc8 sync→async migration that
+ * originally missed this function.
+ */
+export declare function copyCodexSkills(sourceDir: string, destDir: string): Promise<void>;

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

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile, cp } from "node:fs/promises";
+import { join } from "node:path";
+import { PluginInstallError } from "../types.js";
+const FRONTMATTER = /^---\s*\n[\s\S]*?\n---/;
+/**
+ * Copy <sourceDir>/skills into <destDir>/skills verbatim (Codex & CC SKILL.md
+ * are isomorphic). Validates each SKILL.md has a frontmatter block first — a
+ * malformed skill fails the whole install (spec §10).
+ *
+ * Async fs throughout: this runs inside the Electron main process during
+ * install; a synchronous recursive copy (cpSync) blocks the event loop and
+ * freezes the UI. The sibling `cc` branch already awaits cp for this reason
+ * (see install.ts) — this mirrors the 178abc8 sync→async migration that
+ * originally missed this function.
+ */
+export async function copyCodexSkills(sourceDir, destDir) {
+    const skillsSrc = join(sourceDir, "skills");
+    if (!existsSync(skillsSrc))
+        return;
+    for (const dirent of await readdir(skillsSrc, { withFileTypes: true })) {
+        if (!dirent.isDirectory())
+            continue;
+        const skillFile = join(skillsSrc, dirent.name, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        const raw = (await readFile(skillFile, "utf-8")).trim();
+        if (!FRONTMATTER.test(raw)) {
+            throw new PluginInstallError(`skills/${dirent.name}/SKILL.md: missing frontmatter`);
+        }
+    }
+    await cp(skillsSrc, join(destDir, "skills"), { recursive: true });
+}

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

@@ -0,0 +1,2 @@
+/** Binary detection: a Codex plugin has `.codex-plugin/plugin.json`; everything else is CC. */
+export declare function detectPluginFormat(sourceDir: string): "codex" | "cc";

package/dist/plugins/installer/detectFormat.js

@@ -0,0 +1,6 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/** Binary detection: a Codex plugin has `.codex-plugin/plugin.json`; everything else is CC. */
+export function detectPluginFormat(sourceDir) {
+    return existsSync(join(sourceDir, ".codex-plugin", "plugin.json")) ? "codex" : "cc";
+}

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

@@ -0,0 +1,7 @@
+/**
+ * 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 declare function installPluginFromPath(sourceDir: string, name: string, installedAt: string): Promise<string>;