@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/plugins/parseMarketplaceInput.js

@@ -0,0 +1,73 @@
+/**
+ * Parse a user-typed marketplace identifier into a MarketplaceSource.
+ * MVP subset of Claude Code's utils/plugins/parseMarketplaceInput.ts —
+ * local absolute paths, github shorthand, https git URLs, and ssh git URLs.
+ */
+/**
+ * Returns the parsed source, or null when the input does not match any
+ * supported pattern. Callers should show a usage hint on null.
+ */
+export function parseMarketplaceInput(input) {
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return null;
+    // Absolute local path to a git repository (bare or with .git suffix).
+    // Useful for dev workflows where the marketplace lives on disk rather
+    // than at a remote URL. git clone itself accepts the same form.
+    if ((trimmed.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(trimmed)) &&
+        trimmed.endsWith(".git")) {
+        return { source: "git", url: trimmed };
+    }
+    // SSH: user@host:path[.git]
+    // Username can contain alphanumeric, dots, underscores, hyphens.
+    const sshMatch = trimmed.match(/^[a-zA-Z0-9._-]+@[^:\s]+:[^\s]+$/);
+    if (sshMatch) {
+        return { source: "git", url: trimmed };
+    }
+    // HTTPS
+    if (trimmed.startsWith("https://") || trimmed.startsWith("http://")) {
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            return null;
+        }
+        if (parsed.hostname === "github.com" || parsed.hostname === "www.github.com") {
+            const m = parsed.pathname.match(/^\/([^/]+\/[^/]+?)(\/|\.git|$)/);
+            if (!m)
+                return null;
+            const url = trimmed.endsWith(".git") ? trimmed : `${trimmed}.git`;
+            return { source: "git", url };
+        }
+        if (trimmed.endsWith(".git")) {
+            return { source: "git", url: trimmed };
+        }
+        return null;
+    }
+    // GitHub shorthand: owner/repo (single slash, no protocol, no spaces)
+    const shorthandMatch = trimmed.match(/^([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9._-]+?)(\.git)?$/);
+    if (shorthandMatch) {
+        const owner = shorthandMatch[1];
+        const repo = shorthandMatch[2];
+        return { source: "github", repo: `${owner}/${repo}` };
+    }
+    return null;
+}
+/**
+ * Derive a stable marketplace name from a source. Used as the filesystem
+ * directory and the key in known_marketplaces.json.
+ */
+export function deriveMarketplaceName(source) {
+    if (source.source === "github") {
+        const parts = source.repo.split("/");
+        return parts[parts.length - 1].toLowerCase();
+    }
+    // git: strip protocol, strip trailing .git, take last segment.
+    // Local path /tmp/foo/skills.git → name "skills"
+    // Local path /tmp/skills.git     → name "skills"
+    const stripped = source.url.replace(/\.git$/, "");
+    const segments = stripped.split(/[/:]/).filter(Boolean);
+    const tail = segments[segments.length - 1] ?? "marketplace";
+    return tail.toLowerCase();
+}

package/dist/plugins/pluginCommandHook.d.ts

@@ -0,0 +1,54 @@
+/**
+ * pluginCommandHook — execute a plugin's command-type hook as a child
+ * process and translate its stdout into a HookResult.
+ *
+ * This is the plugin-side analogue of `src/hooks/shell-runner.ts`. The two
+ * runners are intentionally separate because they speak different protocols:
+ *
+ *   src/hooks/shell-runner.ts     codeshell-native: stdout is a HookResult
+ *                                 JSON envelope ({ messages, decision, ... }).
+ *                                 Used by user-authored settings.hooks.
+ *
+ *   this file                     CC plugin protocol: stdout is one of
+ *                                 - { hookSpecificOutput: { hookEventName, additionalContext } }
+ *                                 - { additional_context: "..." }            (Cursor)
+ *                                 - { additionalContext: "..." }             (SDK)
+ *                                 We normalize all three into HookResult.messages
+ *                                 so downstream hook plumbing (inject.ts) is
+ *                                 untouched.
+ *
+ * env contract:
+ *   CODESHELL_PLUGIN_ROOT   — set to installPath. Plugin command strings
+ *                             reference this via ${CODESHELL_PLUGIN_ROOT}
+ *                             (varRewrite.ts rewrites CC's CLAUDE_PLUGIN_ROOT
+ *                             to this name at install time).
+ *   CODESHELL_HOOK_EVENT    — the codeshell-side event name (snake_case)
+ *
+ * We deliberately do NOT set CLAUDE_PLUGIN_ROOT here. Plugin scripts that
+ * branch on which host they detect (e.g. superpowers' session-start checks
+ * `[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]`) get rewritten by varRewrite.ts at
+ * install time, so the branch they take after rewrite is the codeshell
+ * branch — not the CC one.
+ */
+import type { HookContext, HookResult } from "../hooks/events.js";
+export interface PluginCommandHookSpec {
+    /** Shell command line, with ${CODESHELL_PLUGIN_ROOT} placeholder allowed. */
+    command: string;
+    /** Plugin install path; exported as CODESHELL_PLUGIN_ROOT for the child. */
+    installPath: string;
+    /** Plugin install key (`name@marketplace`), used for log lines. */
+    pluginKey: string;
+    /** Per-hook override; falls back to DEFAULT_TIMEOUT_MS. */
+    timeoutMs?: number;
+}
+/**
+ * Run one plugin hook command. Returns an empty HookResult on any failure
+ * (spawn error, timeout, non-zero exit, unparseable stdout) so the hook
+ * chain keeps moving — a misbehaving plugin must not wedge the engine.
+ *
+ * Stdin carries the same envelope shape the codeshell-native shell-runner
+ * uses (eventName + data) so plugin authors who want richer context can
+ * read it; CC plugins typically ignore stdin and emit context derived from
+ * their own state (e.g. reading a SKILL.md off disk via PLUGIN_ROOT).
+ */
+export declare function runPluginCommandHook(spec: PluginCommandHookSpec, ctx: HookContext): Promise<HookResult>;

package/dist/plugins/pluginCommandHook.js

@@ -0,0 +1,180 @@
+/**
+ * pluginCommandHook — execute a plugin's command-type hook as a child
+ * process and translate its stdout into a HookResult.
+ *
+ * This is the plugin-side analogue of `src/hooks/shell-runner.ts`. The two
+ * runners are intentionally separate because they speak different protocols:
+ *
+ *   src/hooks/shell-runner.ts     codeshell-native: stdout is a HookResult
+ *                                 JSON envelope ({ messages, decision, ... }).
+ *                                 Used by user-authored settings.hooks.
+ *
+ *   this file                     CC plugin protocol: stdout is one of
+ *                                 - { hookSpecificOutput: { hookEventName, additionalContext } }
+ *                                 - { additional_context: "..." }            (Cursor)
+ *                                 - { additionalContext: "..." }             (SDK)
+ *                                 We normalize all three into HookResult.messages
+ *                                 so downstream hook plumbing (inject.ts) is
+ *                                 untouched.
+ *
+ * env contract:
+ *   CODESHELL_PLUGIN_ROOT   — set to installPath. Plugin command strings
+ *                             reference this via ${CODESHELL_PLUGIN_ROOT}
+ *                             (varRewrite.ts rewrites CC's CLAUDE_PLUGIN_ROOT
+ *                             to this name at install time).
+ *   CODESHELL_HOOK_EVENT    — the codeshell-side event name (snake_case)
+ *
+ * We deliberately do NOT set CLAUDE_PLUGIN_ROOT here. Plugin scripts that
+ * branch on which host they detect (e.g. superpowers' session-start checks
+ * `[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]`) get rewritten by varRewrite.ts at
+ * install time, so the branch they take after rewrite is the codeshell
+ * branch — not the CC one.
+ */
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Extract the user-facing context string from a CC plugin's stdout JSON.
+ * Returns null if the payload doesn't carry context (which is valid — the
+ * hook may be doing side effects only).
+ */
+function extractAdditionalContext(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    // Claude Code nested shape: { hookSpecificOutput: { additionalContext } }
+    const hso = obj.hookSpecificOutput;
+    if (hso && typeof hso === "object") {
+        const ctx = hso.additionalContext;
+        if (typeof ctx === "string" && ctx.length > 0)
+            return ctx;
+    }
+    // Cursor snake_case (top-level)
+    if (typeof obj.additional_context === "string" && obj.additional_context.length > 0) {
+        return obj.additional_context;
+    }
+    // SDK standard (top-level)
+    if (typeof obj.additionalContext === "string" && obj.additionalContext.length > 0) {
+        return obj.additionalContext;
+    }
+    return null;
+}
+/**
+ * Run one plugin hook command. Returns an empty HookResult on any failure
+ * (spawn error, timeout, non-zero exit, unparseable stdout) so the hook
+ * chain keeps moving — a misbehaving plugin must not wedge the engine.
+ *
+ * Stdin carries the same envelope shape the codeshell-native shell-runner
+ * uses (eventName + data) so plugin authors who want richer context can
+ * read it; CC plugins typically ignore stdin and emit context derived from
+ * their own state (e.g. reading a SKILL.md off disk via PLUGIN_ROOT).
+ */
+export async function runPluginCommandHook(spec, ctx) {
+    const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let child;
+        try {
+            // Strip CLAUDE_PLUGIN_ROOT from the inherited env: a plugin script
+            // that branches on `[ -n "$CLAUDE_PLUGIN_ROOT" ]` must conclude
+            // "not Claude Code" and pick the codeshell branch. varRewrite.ts
+            // converted the literal `${CLAUDE_PLUGIN_ROOT}` references to the
+            // codeshell name; this drop closes the runtime side of the same
+            // story.
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { CLAUDE_PLUGIN_ROOT: _stripped, ...parentEnv } = process.env;
+            child = spawn(spec.command, [], {
+                shell: true,
+                env: {
+                    ...parentEnv,
+                    CODESHELL_PLUGIN_ROOT: spec.installPath,
+                    CODESHELL_HOOK_EVENT: ctx.eventName,
+                },
+            });
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`[plugin-hook] spawn failed for ${spec.pluginKey} command "${spec.command}":`, err.message);
+            resolve({});
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} timed out after ${timeoutMs}ms`);
+            try {
+                child.kill("SIGTERM");
+                setTimeout(() => {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* already exited */
+                    }
+                }, 1000);
+            }
+            catch {
+                /* already exited */
+            }
+            settle({});
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            // eslint-disable-next-line no-console
+            console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} spawn error:`, err.message);
+            settle({});
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                // eslint-disable-next-line no-console
+                console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} exited ${code}; stderr:`, stderr.slice(0, 500));
+                settle({});
+                return;
+            }
+            const trimmed = stdout.trim();
+            if (trimmed.length === 0) {
+                settle({});
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} returned non-JSON stdout, ignoring:`, err.message, "\nfirst 200 chars:", trimmed.slice(0, 200));
+                settle({});
+                return;
+            }
+            const additional = extractAdditionalContext(parsed);
+            if (additional === null) {
+                settle({});
+                return;
+            }
+            settle({ messages: [additional] });
+        });
+        // Stdin envelope: matches the shape codeshell-native shell hooks use.
+        // CC plugins generally don't read stdin, but writing it is cheap and
+        // keeps the protocol open for plugin authors who want it.
+        try {
+            child.stdin?.write(JSON.stringify({ eventName: ctx.eventName, data: ctx.data }));
+            child.stdin?.end();
+        }
+        catch {
+            // Child may have closed stdin already; not fatal.
+        }
+    });
+}

package/dist/plugins/pluginCommandsLoader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Discover plugin-provided slash commands. For each installed plugin,
+ * walks <installPath>/commands/*.md and returns one PluginCommand per
+ * markdown file. Mirrors Claude Code's loadPluginCommands.ts at the
+ * MVP subset (single-level commands directory, no nested subcommands,
+ * no inline-via-plugin.json commands).
+ */
+export interface PluginCommand {
+    /** Namespaced name, e.g. "superpowers:brainstorming" */
+    name: string;
+    /** Plain command (without plugin prefix), e.g. "brainstorming" */
+    commandName: string;
+    /** Plugin id (without @marketplace), e.g. "superpowers" */
+    pluginName: string;
+    /** Frontmatter description, coerced. May be empty. */
+    description: string;
+    /** Frontmatter "argument-hint" if present. */
+    argumentHint?: string;
+    /** Body of the .md (frontmatter stripped). */
+    body: string;
+    /** Absolute path to the .md file. */
+    filePath: string;
+}
+export declare function scanPluginCommands(): PluginCommand[];
+export declare function invalidatePluginCommandsCache(): void;

package/dist/plugins/pluginCommandsLoader.js

@@ -0,0 +1,114 @@
+/**
+ * Discover plugin-provided slash commands. For each installed plugin,
+ * walks <installPath>/commands/*.md and returns one PluginCommand per
+ * markdown file. Mirrors Claude Code's loadPluginCommands.ts at the
+ * MVP subset (single-level commands directory, no nested subcommands,
+ * no inline-via-plugin.json commands).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { memoize } from "../utils/memoize.js";
+import { parseFrontmatter, coerceDescription } from "../skills/frontmatter.js";
+import { installedPluginsPath, readInstalledPlugins } from "./installedPlugins.js";
+function isENOENT(e) {
+    return (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT");
+}
+function isInaccessible(e) {
+    if (typeof e !== "object" || e === null || !("code" in e))
+        return false;
+    const code = e.code;
+    return code === "EACCES" || code === "EPERM" || code === "EIO";
+}
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+function readCommandFile(filePath) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch (e) {
+        if (isENOENT(e))
+            return null;
+        if (isInaccessible(e)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-commands] cannot read ${filePath}: ${e.message}`);
+            return null;
+        }
+        throw e;
+    }
+}
+function scanOnce() {
+    const data = readInstalledPlugins();
+    const out = [];
+    const seen = new Set();
+    const keys = Object.keys(data.plugins).sort();
+    for (const key of keys) {
+        const entries = data.plugins[key] ?? [];
+        const atIdx = key.lastIndexOf("@");
+        const pluginName = atIdx > 0 ? key.slice(0, atIdx) : key;
+        for (const entry of entries) {
+            const commandsDir = join(entry.installPath, "commands");
+            if (!existsSync(commandsDir))
+                continue;
+            let dirEntries;
+            try {
+                dirEntries = readdirSync(commandsDir, { withFileTypes: true });
+            }
+            catch (e) {
+                if (isInaccessible(e)) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[plugin-commands] cannot read ${commandsDir}: ${e.message}`);
+                    continue;
+                }
+                throw e;
+            }
+            for (const dirent of dirEntries) {
+                if (!dirent.isFile() && !dirent.isSymbolicLink())
+                    continue;
+                if (!dirent.name.endsWith(".md"))
+                    continue;
+                const filePath = join(commandsDir, dirent.name);
+                const raw = readCommandFile(filePath);
+                if (raw === null)
+                    continue;
+                const baseName = dirent.name.slice(0, -3); // drop .md
+                const namespaced = `${pluginName}:${baseName}`;
+                if (seen.has(namespaced))
+                    continue;
+                const { frontmatter, body } = parseFrontmatter(raw);
+                const description = coerceDescription(frontmatter.description);
+                const argumentHint = typeof frontmatter["argument-hint"] === "string"
+                    ? frontmatter["argument-hint"]
+                    : undefined;
+                out.push({
+                    name: namespaced,
+                    commandName: baseName,
+                    pluginName,
+                    description,
+                    argumentHint,
+                    body,
+                    filePath,
+                });
+                seen.add(namespaced);
+            }
+        }
+    }
+    return out;
+}
+function installedPluginsMtime() {
+    const p = installedPluginsPath();
+    try {
+        return statSync(p).mtimeMs.toString();
+    }
+    catch {
+        return "0";
+    }
+}
+const memoized = memoize(scanOnce, () => `${userHome()}\0${installedPluginsMtime()}`);
+export function scanPluginCommands() {
+    return memoized();
+}
+export function invalidatePluginCommandsCache() {
+    memoized.cache.clear?.();
+}

package/dist/plugins/pluginInstaller.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Install / uninstall plugins from a known marketplace. Mirrors Claude
+ * Code's installResolvedPlugin pattern at the MVP subset: four entry
+ * source types (path / git / github / git-subdir), no dependencies, no
+ * sparse-checkout, no npm/pip.
+ */
+import type { PluginInstallEntry } from "./types.js";
+export interface VarRewriteReport {
+    filesScanned: number;
+    filesRewritten: number;
+}
+export type InstallResult = {
+    ok: true;
+    entry: PluginInstallEntry;
+    freshlyCloned: boolean;
+    varRewrite: VarRewriteReport;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Install a plugin from a previously-added marketplace into the user
+ * cache. Idempotent within a process: re-installing replaces the
+ * cached files and updates the manifest entry.
+ */
+export declare function installPlugin(pluginName: string, marketplaceName: string): Promise<InstallResult>;
+export interface UninstallResult {
+    ok: boolean;
+    removedFromManifest: boolean;
+    removedFromDisk: boolean;
+}
+export declare function uninstallPlugin(pluginName: string, marketplaceName: string): UninstallResult;
+export declare function listInstalled(): {
+    key: string;
+    entry: PluginInstallEntry;
+}[];