@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/plugins/pluginCommandHook.js

@@ -22,6 +22,9 @@
  *                             reference this via ${CODESHELL_PLUGIN_ROOT}
  *                             (varRewrite.ts rewrites CC's CLAUDE_PLUGIN_ROOT
  *                             to this name at install time).
+ *   PLUGIN_ROOT             — Codex-compatible alias for the installed root.
+ *   CODESHELL_PLUGIN_DATA   — stable writable state directory for this plugin.
+ *   PLUGIN_DATA             — Codex-compatible alias for the state directory.
  *   CODESHELL_HOOK_EVENT    — the codeshell-side event name (snake_case)
  *
  * We deliberately do NOT set CLAUDE_PLUGIN_ROOT here. Plugin scripts that
@@ -31,9 +34,21 @@
  * branch — not the CC one.
  */
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { MAX_HOOK_OUTPUT_BYTES } from "../hooks/hook-output.js";
+import { closeHookStdin, MAX_HOOK_STDIN_BYTES, writeHookStdin } from "../hooks/shell-runner.js";
 import { killChildTree } from "../runtime/spawn-common.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
+function codeShellHome() {
+    return process.env.CODE_SHELL_HOME || join(process.env.HOME ?? homedir(), ".code-shell");
+}
+export function resolvePluginDataPath(pluginKey) {
+    const stableKey = createHash("sha256").update(pluginKey).digest("hex");
+    return join(codeShellHome(), "plugin-data", stableKey);
+}
 /**
  * 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
@@ -60,34 +75,69 @@ function extractAdditionalContext(parsed) {
     }
     return null;
 }
+function extractExplicitDenial(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    const nested = obj.hookSpecificOutput && typeof obj.hookSpecificOutput === "object"
+        ? obj.hookSpecificOutput
+        : undefined;
+    const decision = obj.decision ?? obj.permissionDecision ?? nested?.decision ?? nested?.permissionDecision;
+    if (decision !== "deny" && decision !== "reject")
+        return null;
+    const message = obj.reason ??
+        obj.message ??
+        obj.permissionDecisionReason ??
+        nested?.reason ??
+        nested?.message ??
+        nested?.permissionDecisionReason;
+    return typeof message === "string" && message.trim() ? { message: message.trim() } : {};
+}
+function parseJson(stdout) {
+    if (!stdout)
+        return undefined;
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
- * 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.
+ * Run one plugin hook command. CC's exit-code 2 and explicit deny/reject JSON
+ * are normalized to the native HookResult deny contract. Other failures stay
+ * non-blocking so a broken plugin does 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) {
+export async function runPluginCommandHook(spec, ctx, abortSignal) {
     const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const signal = abortSignal ?? ctx.data.signal;
+    if (signal?.aborted)
+        return {};
     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
+            const pluginDataPath = spec.dataPath ?? resolvePluginDataPath(spec.pluginKey);
+            mkdirSync(pluginDataPath, { recursive: true, mode: 0o700 });
+            // Strip Claude-specific plugin vars 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.
+            // converted literal root/data references to CodeShell-native names;
+            // 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;
+            const { CLAUDE_PLUGIN_ROOT: _strippedRoot, CLAUDE_PLUGIN_DATA: _strippedData, ...parentEnv } = process.env;
             child = spawn(spec.command, [], {
                 shell: true,
                 env: {
                     ...parentEnv,
                     CODESHELL_PLUGIN_ROOT: spec.installPath,
+                    PLUGIN_ROOT: spec.installPath,
+                    CODESHELL_PLUGIN_DATA: pluginDataPath,
+                    PLUGIN_DATA: pluginDataPath,
                     CODESHELL_HOOK_EVENT: ctx.eventName,
                 },
             });
@@ -112,8 +162,14 @@ export async function runPluginCommandHook(spec, ctx) {
             if (settled)
                 return;
             settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
             resolve(value);
         };
+        const onAbort = () => {
+            killChildTree(child, 1000);
+            settle({});
+        };
         const timer = setTimeout(() => {
             // eslint-disable-next-line no-console
             console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} timed out after ${timeoutMs}ms`);
@@ -121,6 +177,9 @@ export async function runPluginCommandHook(spec, ctx) {
             killChildTree(child, 1000);
             settle({});
         }, timeoutMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
         child.stdout?.on("data", (chunk) => {
             stdoutBytes += chunk.length;
             if (stdoutBytes > MAX_HOOK_OUTPUT_BYTES) {
@@ -150,21 +209,29 @@ export async function runPluginCommandHook(spec, ctx) {
             console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} spawn error:`, err.message);
             settle({});
         });
-        child.on("close", (code) => {
-            clearTimeout(timer);
+        let stdinFinished = false;
+        let pendingClose;
+        const handleClose = (code) => {
             if (stdoutCapped) {
                 // eslint-disable-next-line no-console
                 console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} killed due to oversized stdout (> ${MAX_HOOK_OUTPUT_BYTES} bytes)`);
                 settle({});
                 return;
             }
+            const trimmed = stdout.trim();
+            const parsedForDecision = parseJson(trimmed);
+            const explicitDenial = extractExplicitDenial(parsedForDecision);
+            if (code === 2 || explicitDenial) {
+                const message = stderr.trim() || explicitDenial?.message || "Plugin denied this tool operation";
+                settle({ decision: "deny", messages: [message] });
+                return;
+            }
             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;
@@ -185,16 +252,64 @@ export async function runPluginCommandHook(spec, ctx) {
                 return;
             }
             settle({ messages: [additional] });
+        };
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            if (!stdinFinished && !stdoutCapped) {
+                pendingClose = { code };
+                return;
+            }
+            handleClose(code);
         });
+        const finishStdin = () => {
+            stdinFinished = true;
+            if (pendingClose && !settled) {
+                const { code } = pendingClose;
+                pendingClose = undefined;
+                handleClose(code);
+            }
+        };
         // 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.
+        let envelope;
         try {
-            child.stdin?.write(JSON.stringify({ eventName: ctx.eventName, data: ctx.data }));
-            child.stdin?.end();
+            envelope = JSON.stringify({ eventName: ctx.eventName, data: ctx.data });
         }
         catch {
-            // Child may have closed stdin already; not fatal.
+            closeHookStdin(child.stdin);
+            finishStdin();
+            return;
         }
+        if (Buffer.byteLength(envelope, "utf8") > MAX_HOOK_STDIN_BYTES) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} stdin exceeded ${MAX_HOOK_STDIN_BYTES} bytes; running without envelope`);
+            closeHookStdin(child.stdin);
+            finishStdin();
+            return;
+        }
+        setImmediate(() => {
+            void (async () => {
+                if (settled)
+                    return;
+                try {
+                    await writeHookStdin(child.stdin, envelope);
+                    finishStdin();
+                }
+                catch (error) {
+                    clearTimeout(timer);
+                    const err = error;
+                    const failure = {
+                        type: "stdin_error",
+                        code: typeof err?.code === "string" ? err.code : "UNKNOWN",
+                        message: err instanceof Error ? err.message : String(error),
+                    };
+                    // eslint-disable-next-line no-console
+                    console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} stdin error:`, failure.message);
+                    killChildTree(child, 1000);
+                    settle({ data: { hookFailure: failure } });
+                }
+            })();
+        });
     });
 }

package/dist/plugins/pluginCommandsLoader.d.ts

@@ -21,5 +21,24 @@ export interface PluginCommand {
     /** Absolute path to the .md file. */
     filePath: string;
 }
+export interface PluginCommandDescriptor {
+    name: string;
+    pluginName: string;
+    description: string;
+    argumentHint?: string;
+}
+/** Bounded prompt contribution limits shared by Desktop, TUI, and protocol hosts. */
+export declare const MAX_PLUGIN_COMMAND_FILE_BYTES: number;
+export declare const MAX_PLUGIN_COMMAND_ARGUMENT_CHARS: number;
+export declare const MAX_PLUGIN_COMMAND_EXPANDED_CHARS: number;
 export declare function scanPluginCommands(): PluginCommand[];
 export declare function invalidatePluginCommandsCache(): void;
+export declare function describePluginCommands(commands: readonly Pick<PluginCommand, "name" | "pluginName" | "description" | "argumentHint">[], disabledPluginNames?: ReadonlySet<string>): PluginCommandDescriptor[];
+/**
+ * Expand CC/CodeShell and deprecated Codex custom-prompt placeholders.
+ *
+ * Codex plugins in the wild still ship `prompts/*.md`, so compatibility needs
+ * `$1`…`$9`, named `KEY=value` placeholders, `$ARGUMENTS`, and `$$` literals
+ * even though new upstream workflows are expected to use skills.
+ */
+export declare function expandPluginCommandBody(body: string, rawArguments?: string): string;

package/dist/plugins/pluginCommandsLoader.js

@@ -5,12 +5,16 @@
  * 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 { closeSync, constants, existsSync, fstatSync, openSync, readdirSync, readSync, realpathSync, statSync, } from "node:fs";
+import { isAbsolute, join, relative, sep } 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";
+/** Bounded prompt contribution limits shared by Desktop, TUI, and protocol hosts. */
+export const MAX_PLUGIN_COMMAND_FILE_BYTES = 256 * 1024;
+export const MAX_PLUGIN_COMMAND_ARGUMENT_CHARS = 32 * 1024;
+export const MAX_PLUGIN_COMMAND_EXPANDED_CHARS = 512 * 1024;
 function isENOENT(e) {
     return (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT");
 }
@@ -18,14 +22,34 @@ 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";
+    return code === "EACCES" || code === "EPERM" || code === "EIO" || code === "ELOOP";
 }
 function userHome() {
     return process.env.HOME ?? homedir();
 }
 function readCommandFile(filePath) {
+    let fd;
     try {
-        return readFileSync(filePath, "utf-8");
+        fd = openSync(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_PLUGIN_COMMAND_FILE_BYTES)
+            return null;
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const remaining = MAX_PLUGIN_COMMAND_FILE_BYTES + 1 - total;
+            if (remaining <= 0)
+                return null;
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
+            const bytesRead = readSync(fd, chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > MAX_PLUGIN_COMMAND_FILE_BYTES)
+                return null;
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        return Buffer.concat(chunks, total).toString("utf-8");
     }
     catch (e) {
         if (isENOENT(e))
@@ -37,6 +61,29 @@ function readCommandFile(filePath) {
         }
         throw e;
     }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/**
+ * Resolve a plugin contribution through symlinks and require it to remain
+ * inside its declared owner directory. Installed plugin trees are untrusted:
+ * without this check `commands -> /some/private/dir` or `command.md` symlinks
+ * could make the host read arbitrary local Markdown and expose it as a prompt.
+ */
+function resolveContainedPath(root, candidate) {
+    try {
+        const realRoot = realpathSync(root);
+        const realCandidate = realpathSync(candidate);
+        const rel = relative(realRoot, realCandidate);
+        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            return null;
+        return realCandidate;
+    }
+    catch {
+        return null;
+    }
 }
 function scanOnce() {
     const data = readInstalledPlugins();
@@ -51,14 +98,17 @@ function scanOnce() {
             const commandsDir = join(entry.installPath, "commands");
             if (!existsSync(commandsDir))
                 continue;
+            const resolvedCommandsDir = resolveContainedPath(entry.installPath, commandsDir);
+            if (!resolvedCommandsDir)
+                continue;
             let dirEntries;
             try {
-                dirEntries = readdirSync(commandsDir, { withFileTypes: true });
+                dirEntries = readdirSync(resolvedCommandsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
             }
             catch (e) {
                 if (isInaccessible(e)) {
                     // eslint-disable-next-line no-console
-                    console.warn(`[plugin-commands] cannot read ${commandsDir}: ${e.message}`);
+                    console.warn(`[plugin-commands] cannot read ${resolvedCommandsDir}: ${e.message}`);
                     continue;
                 }
                 throw e;
@@ -68,7 +118,17 @@ function scanOnce() {
                     continue;
                 if (!dirent.name.endsWith(".md"))
                     continue;
-                const filePath = join(commandsDir, dirent.name);
+                const filePath = resolveContainedPath(resolvedCommandsDir, join(resolvedCommandsDir, dirent.name));
+                if (!filePath)
+                    continue;
+                try {
+                    const fileStat = statSync(filePath);
+                    if (!fileStat.isFile() || fileStat.size > MAX_PLUGIN_COMMAND_FILE_BYTES)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
                 const raw = readCommandFile(filePath);
                 if (raw === null)
                     continue;
@@ -112,3 +172,117 @@ export function scanPluginCommands() {
 export function invalidatePluginCommandsCache() {
     memoized.cache.clear?.();
 }
+function parsePluginCommandArguments(input) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let escaping = false;
+    const push = () => {
+        if (current.length === 0)
+            return;
+        tokens.push(current);
+        current = "";
+    };
+    for (const character of input.trim()) {
+        if (escaping) {
+            current += character;
+            escaping = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (character === quote)
+                quote = null;
+            else
+                current += character;
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+            continue;
+        }
+        if (/\s/u.test(character)) {
+            push();
+            continue;
+        }
+        current += character;
+    }
+    if (escaping)
+        current += "\\";
+    push();
+    const positional = [];
+    const named = new Map();
+    for (const token of tokens) {
+        const assignment = /^([A-Z][A-Z0-9_]*)=(.*)$/u.exec(token);
+        if (assignment)
+            named.set(assignment[1], assignment[2]);
+        else
+            positional.push(token);
+    }
+    return { positional, named };
+}
+export function describePluginCommands(commands, disabledPluginNames = new Set()) {
+    return commands
+        .filter((command) => !disabledPluginNames.has(command.pluginName))
+        .map((command) => ({
+        name: command.name,
+        pluginName: command.pluginName,
+        description: command.description,
+        ...(command.argumentHint ? { argumentHint: command.argumentHint } : {}),
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+const PLUGIN_COMMAND_PLACEHOLDER = /\$\$|\$ARGUMENTS|\{args\}|\$([1-9])|\$([A-Z][A-Z0-9_]*)(?![A-Z0-9_])/gu;
+function pluginCommandReplacement(token, positionalIndex, namedPlaceholder, rawArguments, parsed) {
+    if (token === "$$")
+        return "$";
+    if (token === "$ARGUMENTS" || token === "{args}")
+        return rawArguments;
+    if (positionalIndex)
+        return parsed.positional[Number(positionalIndex) - 1] ?? "";
+    if (namedPlaceholder && parsed.named.has(namedPlaceholder)) {
+        return parsed.named.get(namedPlaceholder);
+    }
+    return token;
+}
+function assertExpansionBudget(body, rawArguments, parsed) {
+    if (Buffer.byteLength(body, "utf-8") > MAX_PLUGIN_COMMAND_FILE_BYTES) {
+        throw new Error(`plugin command body exceeds ${MAX_PLUGIN_COMMAND_FILE_BYTES} bytes`);
+    }
+    if (rawArguments.length > MAX_PLUGIN_COMMAND_ARGUMENT_CHARS) {
+        throw new Error(`plugin command arguments exceed ${MAX_PLUGIN_COMMAND_ARGUMENT_CHARS} characters`);
+    }
+    let projected = body.length;
+    for (const match of body.matchAll(PLUGIN_COMMAND_PLACEHOLDER)) {
+        projected +=
+            pluginCommandReplacement(match[0], match[1], match[2], rawArguments, parsed).length -
+                match[0].length;
+        if (projected > MAX_PLUGIN_COMMAND_EXPANDED_CHARS)
+            break;
+    }
+    if (projected > MAX_PLUGIN_COMMAND_EXPANDED_CHARS) {
+        throw new Error(`expanded plugin command exceeds ${MAX_PLUGIN_COMMAND_EXPANDED_CHARS} characters`);
+    }
+}
+/**
+ * Expand CC/CodeShell and deprecated Codex custom-prompt placeholders.
+ *
+ * Codex plugins in the wild still ship `prompts/*.md`, so compatibility needs
+ * `$1`…`$9`, named `KEY=value` placeholders, `$ARGUMENTS`, and `$$` literals
+ * even though new upstream workflows are expected to use skills.
+ */
+export function expandPluginCommandBody(body, rawArguments = "") {
+    if (rawArguments.length > MAX_PLUGIN_COMMAND_ARGUMENT_CHARS) {
+        throw new Error(`plugin command arguments exceed ${MAX_PLUGIN_COMMAND_ARGUMENT_CHARS} characters`);
+    }
+    const parsed = parsePluginCommandArguments(rawArguments);
+    assertExpansionBudget(body, rawArguments, parsed);
+    const expanded = body.replace(PLUGIN_COMMAND_PLACEHOLDER, (token, positionalIndex, namedPlaceholder) => pluginCommandReplacement(token, positionalIndex, namedPlaceholder, rawArguments, parsed));
+    if (expanded.length > MAX_PLUGIN_COMMAND_EXPANDED_CHARS) {
+        throw new Error(`expanded plugin command exceeds ${MAX_PLUGIN_COMMAND_EXPANDED_CHARS} characters`);
+    }
+    return expanded;
+}

package/dist/plugins/pluginContent.d.ts

@@ -6,6 +6,11 @@
  * loaders use so the inventory can't drift from what actually loads.
  */
 import { type PluginHookEntry } from "./loadPluginHooks.js";
+import { type PluginHookReview } from "./pluginHookApproval.js";
+import { type PluginAutomationTemplate } from "./installer/types.js";
+export type PluginAutomationTemplateDescriptor = PluginAutomationTemplate & {
+    revision: string;
+};
 export interface PluginContentInventory {
     /** skills/<name>/SKILL.md — name + frontmatter description when present. */
     skills: {
@@ -18,8 +23,12 @@ export interface PluginContentInventory {
     agents: string[];
     /** hooks/hooks.json entries (event + command), owner-filtered. */
     hooks: PluginHookEntry[];
+    /** Current hook definition compared with the last explicitly approved snapshot. */
+    hookReview?: PluginHookReview;
     /** MCP server names as merged (keyed `<plugin>:<server>` — bare name here). */
     mcpServers: string[];
+    /** Reusable scheduled-task templates; never instantiated automatically. */
+    automationTemplates: PluginAutomationTemplateDescriptor[];
 }
 /**
  * Inventory one plugin's contributions. `pluginName` is the bare name (no
@@ -27,4 +36,4 @@ export interface PluginContentInventory {
  * scanners the runtime loaders use (filtered to this plugin) so naming —
  * e.g. MCP's `<plugin>:<server>` record keys — matches what users see live.
  */
-export declare function describePluginContent(pluginName: string, installPath: string): PluginContentInventory;
+export declare function describePluginContent(pluginName: string, installPath: string, installKey?: string): PluginContentInventory;