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

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/convertMcp.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve a Codex manifest's mcpServers declaration into a plain server map.
+ * - object → returned as-is (inline)
+ * - string → read that file relative to sourceDir; accept either a bare map
+ *   or a `{ mcpServers: {...} }` wrapper.
+ * - 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,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { PluginInstallError } from "../types.js";
+/**
+ * Resolve a Codex manifest's mcpServers declaration into a plain server map.
+ * - object → returned as-is (inline)
+ * - string → read that file relative to sourceDir; accept either a bare map
+ *   or a `{ mcpServers: {...} }` wrapper.
+ * - undefined → {}
+ */
+export function resolveCodexMcpServers(sourceDir, decl) {
+    if (decl === undefined)
+        return {};
+    if (typeof decl === "object")
+        return 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 parsed.mcpServers ?? {};
+    }
+    return 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>;

package/dist/plugins/installer/install.js

@@ -0,0 +1,99 @@
+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 { 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 });
+            meta = { name, format: "cc", 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);
+            // 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;
+    }
+}
+/** 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/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,45 @@
+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 { 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 });
+        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;
+        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,23 @@
+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)) {
+        if (disabled.has(pluginNameFromKey(key)))
+            continue;
+        for (const entry of entries) {
+            const dir = join(entry.installPath, "agents");
+            if (existsSync(dir))
+                out.push({ dir, source: "plugin" });
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,7 @@
+import type { MCPServerConfig } 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.
+ */
+export declare function mergePluginMcpServers(base: Record<string, MCPServerConfig>, disabledPlugins?: string[]): Record<string, MCPServerConfig>;

package/dist/plugins/installer/loadPluginMcp.js

@@ -0,0 +1,74 @@
+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;
+}
+/**
+ * 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.
+ */
+export function mergePluginMcpServers(base, disabledPlugins = []) {
+    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] = cfg;
+            }
+        }
+    }
+    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;

package/dist/plugins/installer/paths.js

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PluginInstallError } from "./types.js";
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+/** A plugin name must be a single safe path segment — no separators, no traversal. */
+export function assertSafePluginName(name) {
+    if (!name || name === "." || name === "..") {
+        throw new PluginInstallError(`invalid plugin name: ${JSON.stringify(name)}`);
+    }
+    if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+        throw new PluginInstallError(`plugin name must be a single path segment: ${JSON.stringify(name)}`);
+    }
+}
+export function pluginsRoot() {
+    return join(userHome(), ".code-shell", "plugins");
+}
+export function pluginInstallDir(name) {
+    assertSafePluginName(name);
+    return join(pluginsRoot(), name);
+}
+export function pluginMetaPath(name) {
+    return join(pluginInstallDir(name), ".cs-meta.json");
+}