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

package/dist/plugins/gitOps.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal `git` subprocess wrappers used by the plugin marketplace. Each
+ * function returns a discriminated union so callers can produce useful
+ * error messages without try/catching. Mirrors Claude Code's
+ * utils/plugins/marketplaceManager.ts:loadAndCacheMarketplace at the
+ * subset we need for the MVP.
+ *
+ * Subprocess lifecycle (spawn, timeout cascade, IO drain, byte cap) is
+ * centralized in {@link safeSpawn}; gitOps only owns the error-shape
+ * mapping into GitResult.
+ *
+ * Trust: gitOps is invoked from marketplace install/update actions that the
+ * user initiates by typing `/plugin install ...` (or the equivalent). It is
+ * NOT exposed to the LLM via tool calls, so it does not need permission
+ * classification. See docs/architecture/17 for the trust framing.
+ */
+import { safeSpawn } from "../runtime/safe-spawn.js";
+async function runGit(args, cwd, timeoutMs = 60_000) {
+    const r = await safeSpawn("git", args, {
+        cwd: cwd ?? process.cwd(),
+        env: process.env,
+        timeoutMs,
+    });
+    if (r.spawnFailed) {
+        return { ok: false, error: `git ${args.join(" ")} failed: ${r.error ?? "spawn failed"}` };
+    }
+    if (r.timedOut) {
+        return { ok: false, error: `git ${args.join(" ")} timed out after ${timeoutMs}ms` };
+    }
+    if (r.exitCode === 0) {
+        return { ok: true, stdout: r.stdout.trim() };
+    }
+    return {
+        ok: false,
+        error: `git ${args.join(" ")} exited ${r.exitCode}: ${r.stderr.trim() || "unknown error"}`,
+    };
+}
+export async function gitClone(url, destDir, options) {
+    const args = ["clone", "--depth", "1"];
+    if (options?.ref)
+        args.push("--branch", options.ref);
+    args.push("--", url, destDir);
+    return runGit(args);
+}
+export async function gitRevParseHead(repoDir) {
+    return runGit(["rev-parse", "HEAD"], repoDir);
+}
+export async function gitFetchAndReset(repoDir, ref) {
+    const fetchArgs = ["fetch", "--depth", "1", "origin"];
+    if (ref)
+        fetchArgs.push(ref);
+    const fetch = await runGit(fetchArgs, repoDir);
+    if (!fetch.ok)
+        return fetch;
+    return runGit(["reset", "--hard", ref ? `origin/${ref}` : "FETCH_HEAD"], repoDir);
+}
+/**
+ * Github source helper: convert "owner/repo" to an https clone URL.
+ */
+export function githubRepoToCloneUrl(repo) {
+    return `https://github.com/${repo}.git`;
+}

package/dist/plugins/installedPlugins.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Read/write ~/.code-shell/plugins/installed_plugins.json (V2 format).
+ * Byte-compatible with Claude Code's analogous file.
+ */
+import type { InstalledPluginsV2, PluginInstallEntry } from "./types.js";
+export declare function installedPluginsPath(): string;
+export declare function readInstalledPlugins(): InstalledPluginsV2;
+export declare function writeInstalledPlugins(data: InstalledPluginsV2): void;
+/**
+ * Append an install entry for `<plugin>@<marketplace>`. Multiple entries
+ * for the same key are allowed (different scopes); MVP only writes scope:"user".
+ */
+export declare function appendInstallEntry(key: string, entry: PluginInstallEntry): void;
+export declare function removeInstallEntries(key: string): boolean;
+export declare function pluginInstallKey(plugin: string, marketplace: string): string;

package/dist/plugins/installedPlugins.js

@@ -0,0 +1,56 @@
+/**
+ * Read/write ~/.code-shell/plugins/installed_plugins.json (V2 format).
+ * Byte-compatible with Claude Code's analogous file.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+export function installedPluginsPath() {
+    return join(userHome(), ".code-shell", "plugins", "installed_plugins.json");
+}
+const EMPTY = { version: 2, plugins: {} };
+export function readInstalledPlugins() {
+    const path = installedPluginsPath();
+    if (!existsSync(path))
+        return { version: 2, plugins: {} };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (raw && typeof raw === "object" && raw.version === 2 && raw.plugins && typeof raw.plugins === "object") {
+            return raw;
+        }
+    }
+    catch {
+        // Corrupt — treat as empty so the user can re-install.
+    }
+    return { version: 2, plugins: {} };
+}
+export function writeInstalledPlugins(data) {
+    const path = installedPluginsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+/**
+ * Append an install entry for `<plugin>@<marketplace>`. Multiple entries
+ * for the same key are allowed (different scopes); MVP only writes scope:"user".
+ */
+export function appendInstallEntry(key, entry) {
+    const data = readInstalledPlugins();
+    const list = data.plugins[key] ?? [];
+    list.push(entry);
+    data.plugins[key] = list;
+    writeInstalledPlugins(data);
+}
+export function removeInstallEntries(key) {
+    const data = readInstalledPlugins();
+    if (!(key in data.plugins))
+        return false;
+    delete data.plugins[key];
+    writeInstalledPlugins(data);
+    return true;
+}
+export function pluginInstallKey(plugin, marketplace) {
+    return `${plugin}@${marketplace}`;
+}

package/dist/plugins/knownMarketplaces.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Read/write ~/.code-shell/plugins/known_marketplaces.json.
+ * File format is byte-compatible with Claude Code's analogous file.
+ */
+import type { KnownMarketplaces, KnownMarketplace } from "./types.js";
+export declare function knownMarketplacesPath(): string;
+export declare function readKnownMarketplaces(): KnownMarketplaces;
+export declare function writeKnownMarketplaces(data: KnownMarketplaces): void;
+export declare function upsertKnownMarketplace(name: string, entry: KnownMarketplace): void;
+export declare function removeKnownMarketplace(name: string): boolean;

package/dist/plugins/knownMarketplaces.js

@@ -0,0 +1,46 @@
+/**
+ * Read/write ~/.code-shell/plugins/known_marketplaces.json.
+ * File format is byte-compatible with Claude Code's analogous file.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+export function knownMarketplacesPath() {
+    return join(userHome(), ".code-shell", "plugins", "known_marketplaces.json");
+}
+export function readKnownMarketplaces() {
+    const path = knownMarketplacesPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            return raw;
+        }
+    }
+    catch {
+        // Corrupted file: treat as empty so the caller can recover by re-adding.
+    }
+    return {};
+}
+export function writeKnownMarketplaces(data) {
+    const path = knownMarketplacesPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+export function upsertKnownMarketplace(name, entry) {
+    const data = readKnownMarketplaces();
+    data[name] = entry;
+    writeKnownMarketplaces(data);
+}
+export function removeKnownMarketplace(name) {
+    const data = readKnownMarketplaces();
+    if (!(name in data))
+        return false;
+    delete data[name];
+    writeKnownMarketplaces(data);
+    return true;
+}

package/dist/plugins/loadPluginHooks.d.ts

@@ -0,0 +1,52 @@
+/**
+ * loadPluginHooks — scan every installed plugin's hooks/hooks.json and
+ * register the command-type hooks with the engine's HookRegistry.
+ *
+ * Plugin hooks.json schema (Claude Code-compatible):
+ *
+ *   {
+ *     "hooks": {
+ *       "<EventName>": [
+ *         {
+ *           "matcher": "<regex>",      // optional; semantics depend on event
+ *           "hooks": [
+ *             {
+ *               "type": "command",
+ *               "command": "...",      // ${CODESHELL_PLUGIN_ROOT} placeholder
+ *               "async": false,        // currently ignored (always sync await)
+ *               "timeout_ms": 60000    // optional override
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * Event-name mapping (CC PascalCase → codeshell snake_case):
+ *   SessionStart       → on_session_start
+ *   UserPromptSubmit   → user_prompt_submit
+ *   PreToolUse         → pre_tool_use
+ *   PostToolUse        → post_tool_use
+ *   PreCompact         → pre_compact
+ *   Notification       → notification
+ *   Stop               → on_session_end
+ *   SubagentStop       → (skipped — codeshell sub-agents don't surface this event)
+ *
+ * matcher semantics:
+ *   SessionStart    — matches against ctx.data.source ("startup"|"resume"|"clear"|"compact")
+ *   PreToolUse /
+ *   PostToolUse     — matches against ctx.data.toolName
+ *   other events    — matcher is currently ignored (the CC spec doesn't
+ *                     define matcher semantics for them either)
+ *
+ * Errors are swallowed per-plugin: a malformed hooks.json from one plugin
+ * must not block other plugins from loading.
+ */
+import type { HookRegistry } from "../hooks/registry.js";
+/**
+ * Walk installed plugins and register their command hooks. Safe to call
+ * multiple times — the caller is responsible for not double-registering
+ * (HookRegistry has no de-dup; the engine constructor calls this exactly
+ * once after creating the registry).
+ */
+export declare function loadPluginHooks(registry: HookRegistry): void;

package/dist/plugins/loadPluginHooks.js

@@ -0,0 +1,162 @@
+/**
+ * loadPluginHooks — scan every installed plugin's hooks/hooks.json and
+ * register the command-type hooks with the engine's HookRegistry.
+ *
+ * Plugin hooks.json schema (Claude Code-compatible):
+ *
+ *   {
+ *     "hooks": {
+ *       "<EventName>": [
+ *         {
+ *           "matcher": "<regex>",      // optional; semantics depend on event
+ *           "hooks": [
+ *             {
+ *               "type": "command",
+ *               "command": "...",      // ${CODESHELL_PLUGIN_ROOT} placeholder
+ *               "async": false,        // currently ignored (always sync await)
+ *               "timeout_ms": 60000    // optional override
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * Event-name mapping (CC PascalCase → codeshell snake_case):
+ *   SessionStart       → on_session_start
+ *   UserPromptSubmit   → user_prompt_submit
+ *   PreToolUse         → pre_tool_use
+ *   PostToolUse        → post_tool_use
+ *   PreCompact         → pre_compact
+ *   Notification       → notification
+ *   Stop               → on_session_end
+ *   SubagentStop       → (skipped — codeshell sub-agents don't surface this event)
+ *
+ * matcher semantics:
+ *   SessionStart    — matches against ctx.data.source ("startup"|"resume"|"clear"|"compact")
+ *   PreToolUse /
+ *   PostToolUse     — matches against ctx.data.toolName
+ *   other events    — matcher is currently ignored (the CC spec doesn't
+ *                     define matcher semantics for them either)
+ *
+ * Errors are swallowed per-plugin: a malformed hooks.json from one plugin
+ * must not block other plugins from loading.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readInstalledPlugins } from "./installedPlugins.js";
+import { runPluginCommandHook } from "./pluginCommandHook.js";
+/** Priority for plugin hooks — between built-in (100) and settings (50). */
+const PLUGIN_HOOK_PRIORITY = 80;
+const EVENT_NAME_MAP = {
+    SessionStart: "on_session_start",
+    UserPromptSubmit: "user_prompt_submit",
+    PreToolUse: "pre_tool_use",
+    PostToolUse: "post_tool_use",
+    PreCompact: "pre_compact",
+    Notification: "notification",
+    Stop: "on_session_end",
+    SubagentStop: null,
+};
+function readHooksJson(installPath) {
+    const path = join(installPath, "hooks", "hooks.json");
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            return raw;
+        }
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(`[plugin-hooks] failed to parse ${path}:`, err.message);
+    }
+    return null;
+}
+/**
+ * Per-event matcher logic. Returns true when the hook should fire.
+ *
+ * We only consult the matcher for events where CC defines its semantics;
+ * for others we always fire (matcher is treated as advisory metadata only).
+ */
+function matcherAccepts(event, matcher, ctx) {
+    if (!matcher)
+        return true;
+    let re;
+    try {
+        re = new RegExp(matcher);
+    }
+    catch {
+        // Bad regex — be permissive (matches CC's "log + drop" behavior).
+        return true;
+    }
+    if (event === "on_session_start") {
+        const source = ctx.data.source;
+        if (typeof source !== "string")
+            return true;
+        return re.test(source);
+    }
+    if (event === "pre_tool_use" || event === "post_tool_use") {
+        const toolName = ctx.data.toolName;
+        if (typeof toolName !== "string")
+            return false;
+        return re.test(toolName);
+    }
+    return true;
+}
+function pluginNameFromKey(key) {
+    const at = key.lastIndexOf("@");
+    return at > 0 ? key.slice(0, at) : key;
+}
+/**
+ * Walk installed plugins and register their command hooks. Safe to call
+ * multiple times — the caller is responsible for not double-registering
+ * (HookRegistry has no de-dup; the engine constructor calls this exactly
+ * once after creating the registry).
+ */
+export function loadPluginHooks(registry) {
+    const data = readInstalledPlugins();
+    for (const [key, entries] of Object.entries(data.plugins)) {
+        for (const entry of entries) {
+            const installPath = entry.installPath;
+            if (!installPath || !existsSync(installPath))
+                continue;
+            const raw = readHooksJson(installPath);
+            if (!raw?.hooks)
+                continue;
+            for (const [eventNameRaw, groups] of Object.entries(raw.hooks)) {
+                const mapped = EVENT_NAME_MAP[eventNameRaw];
+                if (mapped === null || mapped === undefined) {
+                    // Unmapped event name (e.g. SubagentStop) — silently skip; logging
+                    // every unknown event for every plugin would be noisy.
+                    continue;
+                }
+                if (!Array.isArray(groups))
+                    continue;
+                for (const group of groups) {
+                    const commands = group.hooks ?? [];
+                    for (const cmd of commands) {
+                        if (cmd.type !== "command" || typeof cmd.command !== "string") {
+                            continue;
+                        }
+                        const commandLine = cmd.command;
+                        const timeoutMs = cmd.timeout_ms;
+                        const matcher = group.matcher;
+                        const handler = async (ctx) => {
+                            if (!matcherAccepts(mapped, matcher, ctx))
+                                return {};
+                            return runPluginCommandHook({
+                                command: commandLine,
+                                installPath,
+                                pluginKey: key,
+                                timeoutMs,
+                            }, ctx);
+                        };
+                        registry.register(mapped, handler, PLUGIN_HOOK_PRIORITY, `plugin:${pluginNameFromKey(key)}:${eventNameRaw}`);
+                    }
+                }
+            }
+        }
+    }
+}

package/dist/plugins/marketplaceManager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Marketplace lifecycle: add (clone + validate + persist), remove
+ * (delete from disk + manifest), list, load (read marketplace.json on
+ * demand). Mirrors Claude Code's utils/plugins/marketplaceManager.ts
+ * at the MVP subset (github + git sources only, no auto-update,
+ * no policy blocking, no GCS mirror).
+ */
+import type { MarketplaceSource, PluginMarketplace } from "./types.js";
+export declare function marketplacesRoot(): string;
+export declare function marketplaceDir(name: string): string;
+export type AddMarketplaceResult = {
+    ok: true;
+    name: string;
+    marketplace: PluginMarketplace;
+    replaced: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Adds a marketplace by cloning it (or refreshing if already present
+ * with the same source), validating its marketplace.json, and writing
+ * an entry into known_marketplaces.json.
+ */
+export declare function addMarketplace(name: string, source: MarketplaceSource): Promise<AddMarketplaceResult>;
+/**
+ * Removes a marketplace: deletes the cached clone and the manifest entry.
+ * Returns whether anything was actually removed.
+ */
+export declare function removeMarketplace(name: string): boolean;
+/**
+ * Loads a previously-added marketplace's manifest from disk. Returns null
+ * if the marketplace is unknown or the manifest is gone (caller can
+ * report to user).
+ */
+export declare function loadMarketplace(name: string): PluginMarketplace | null;
+export interface ListedMarketplace {
+    name: string;
+    source: MarketplaceSource;
+    installLocation: string;
+    lastUpdated: string;
+    pluginCount: number;
+}
+/**
+ * Lists all known marketplaces with a quick plugin count read from each
+ * cached manifest. Marketplaces whose manifest is missing or invalid
+ * show pluginCount: -1 so the caller can flag them.
+ */
+export declare function listMarketplaces(): ListedMarketplace[];

package/dist/plugins/marketplaceManager.js

@@ -0,0 +1,142 @@
+/**
+ * Marketplace lifecycle: add (clone + validate + persist), remove
+ * (delete from disk + manifest), list, load (read marketplace.json on
+ * demand). Mirrors Claude Code's utils/plugins/marketplaceManager.ts
+ * at the MVP subset (github + git sources only, no auto-update,
+ * no policy blocking, no GCS mirror).
+ */
+import { existsSync, readFileSync, rmSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { gitClone, gitFetchAndReset, githubRepoToCloneUrl } from "./gitOps.js";
+import { readKnownMarketplaces, upsertKnownMarketplace, removeKnownMarketplace, } from "./knownMarketplaces.js";
+import { validateMarketplace } from "./schemas.js";
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+export function marketplacesRoot() {
+    return join(userHome(), ".code-shell", "plugins", "marketplaces");
+}
+export function marketplaceDir(name) {
+    return join(marketplacesRoot(), name);
+}
+function marketplaceJsonPath(name) {
+    return join(marketplaceDir(name), ".claude-plugin", "marketplace.json");
+}
+function sourceToCloneUrl(source) {
+    return source.source === "github" ? githubRepoToCloneUrl(source.repo) : source.url;
+}
+/**
+ * Adds a marketplace by cloning it (or refreshing if already present
+ * with the same source), validating its marketplace.json, and writing
+ * an entry into known_marketplaces.json.
+ */
+export async function addMarketplace(name, source) {
+    const dir = marketplaceDir(name);
+    const known = readKnownMarketplaces();
+    const existing = known[name];
+    const sameSource = existing &&
+        JSON.stringify(existing.source) === JSON.stringify(source) &&
+        existsSync(dir);
+    if (sameSource) {
+        // Refresh: pull latest. Best-effort; if fetch fails we still try to
+        // validate the existing checkout.
+        const ref = source.source === "git" ? undefined : undefined; // MVP: default branch
+        await gitFetchAndReset(dir, ref);
+    }
+    else {
+        // Fresh clone (delete first if a stale directory exists).
+        if (existsSync(dir))
+            rmSync(dir, { recursive: true, force: true });
+        mkdirSync(marketplacesRoot(), { recursive: true });
+        const clone = await gitClone(sourceToCloneUrl(source), dir);
+        if (!clone.ok) {
+            return { ok: false, error: clone.error };
+        }
+    }
+    const manifestPath = marketplaceJsonPath(name);
+    if (!existsSync(manifestPath)) {
+        rmSync(dir, { recursive: true, force: true });
+        return {
+            ok: false,
+            error: `Marketplace ${name}: .claude-plugin/marketplace.json not found in the cloned repository.`,
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    }
+    catch (e) {
+        rmSync(dir, { recursive: true, force: true });
+        return {
+            ok: false,
+            error: `Marketplace ${name}: failed to parse marketplace.json: ${e.message}`,
+        };
+    }
+    const v = validateMarketplace(raw);
+    if (!v.ok) {
+        rmSync(dir, { recursive: true, force: true });
+        return { ok: false, error: `Marketplace ${name}: ${v.error}` };
+    }
+    const entry = {
+        source,
+        installLocation: dir,
+        lastUpdated: new Date().toISOString(),
+    };
+    upsertKnownMarketplace(name, entry);
+    return { ok: true, name, marketplace: v.value, replaced: Boolean(existing) };
+}
+/**
+ * Removes a marketplace: deletes the cached clone and the manifest entry.
+ * Returns whether anything was actually removed.
+ */
+export function removeMarketplace(name) {
+    const removed = removeKnownMarketplace(name);
+    const dir = marketplaceDir(name);
+    if (existsSync(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    return removed;
+}
+/**
+ * Loads a previously-added marketplace's manifest from disk. Returns null
+ * if the marketplace is unknown or the manifest is gone (caller can
+ * report to user).
+ */
+export function loadMarketplace(name) {
+    const known = readKnownMarketplaces();
+    if (!known[name])
+        return null;
+    const manifestPath = marketplaceJsonPath(name);
+    if (!existsSync(manifestPath))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const v = validateMarketplace(raw);
+    return v.ok ? v.value : null;
+}
+/**
+ * Lists all known marketplaces with a quick plugin count read from each
+ * cached manifest. Marketplaces whose manifest is missing or invalid
+ * show pluginCount: -1 so the caller can flag them.
+ */
+export function listMarketplaces() {
+    const known = readKnownMarketplaces();
+    const out = [];
+    for (const [name, entry] of Object.entries(known)) {
+        const mp = loadMarketplace(name);
+        out.push({
+            name,
+            source: entry.source,
+            installLocation: entry.installLocation,
+            lastUpdated: entry.lastUpdated,
+            pluginCount: mp ? mp.plugins.length : -1,
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/plugins/parseMarketplaceInput.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+import type { MarketplaceSource } from "./types.js";
+/**
+ * Returns the parsed source, or null when the input does not match any
+ * supported pattern. Callers should show a usage hint on null.
+ */
+export declare function parseMarketplaceInput(input: string): MarketplaceSource | null;
+/**
+ * Derive a stable marketplace name from a source. Used as the filesystem
+ * directory and the key in known_marketplaces.json.
+ */
+export declare function deriveMarketplaceName(source: MarketplaceSource): string;