@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/plugins/loadPluginHooks.js

@@ -30,22 +30,24 @@
  *   PreCompact         → pre_compact
  *   Notification       → notification
  *   Stop               → on_session_end
- *   SubagentStop       → (skipped — codeshell sub-agents don't surface this event)
+ *   SubagentStop       → notification (implied matcher on kind ^agent_(completed|failed|cancelled)$)
  *
  * matcher semantics:
  *   SessionStart    — matches against ctx.data.source ("startup"|"resume"|"clear"|"compact")
  *   PreToolUse /
  *   PostToolUse     — matches against ctx.data.toolName
+ *   Notification /
+ *   SubagentStop    — matches against ctx.data.kind (agent_* terminal states,
+ *                     approval_requested/resolved, mcp_server_*, …)
  *   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";
+import { inspectPluginHooks, pluginHookApprovalState, verifyPluginHookIntegrity, } from "./pluginHookIntegrity.js";
 /** Priority for plugin hooks — between built-in (100) and settings (50). */
 const PLUGIN_HOOK_PRIORITY = 80;
 const EVENT_NAME_MAP = {
@@ -56,31 +58,24 @@ const EVENT_NAME_MAP = {
     PreCompact: "pre_compact",
     Notification: "notification",
     Stop: "on_session_end",
-    SubagentStop: null,
+    // Sub-agent terminal states surface on the notification hook with
+    // kind "agent_completed" / "agent_failed" / "agent_cancelled"; the matcher
+    // filters on that kind, so SubagentStop maps to a kind-filtered
+    // notification subscription (notify-only — codeshell sub-agent stops are
+    // not interceptable the way CC's SubagentStop is).
+    SubagentStop: "notification",
+};
+/** CC events whose codeshell notification `kind` the matcher defaults to when absent. */
+const IMPLIED_NOTIFICATION_KIND = {
+    SubagentStop: "^agent_(completed|failed|cancelled)$",
 };
-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) {
+export function matcherAccepts(event, matcher, ctx) {
     if (!matcher)
         return true;
     let re;
@@ -88,8 +83,9 @@ function matcherAccepts(event, matcher, ctx) {
         re = new RegExp(matcher);
     }
     catch {
-        // Bad regex — be permissive (matches CC's "log + drop" behavior).
-        return true;
+        // Runtime definitions are pre-validated, but direct callers still fail
+        // closed if they supply an invalid expression.
+        return false;
     }
     if (event === "on_session_start") {
         const source = ctx.data.source;
@@ -103,12 +99,36 @@ function matcherAccepts(event, matcher, ctx) {
             return false;
         return re.test(toolName);
     }
+    if (event === "notification") {
+        // Notification fan-in carries a `kind` discriminator (agent_* terminal
+        // states, approval_requested/resolved, mcp_server_*…). Matcher filters on
+        // it so a subscriber only wakes for the kinds it cares about.
+        const kind = ctx.data.kind;
+        if (typeof kind !== "string")
+            return true;
+        return re.test(kind);
+    }
     return true;
 }
 function pluginNameFromKey(key) {
     const at = key.lastIndexOf("@");
     return at > 0 ? key.slice(0, at) : key;
 }
+function* iteratePluginHooks(definition) {
+    for (const rawEvent of Object.keys(definition.hooks)) {
+        const event = EVENT_NAME_MAP[rawEvent];
+        for (const group of definition.hooks[rawEvent] ?? []) {
+            for (const command of group.hooks) {
+                yield {
+                    rawEvent,
+                    event,
+                    matcher: group.matcher,
+                    command,
+                };
+            }
+        }
+    }
+}
 /**
  * Stable identity for ONE plugin-provided hook, used as the record key in
  * `capabilityOverrides.pluginHooks` (per-hook project off-switch). Derived
@@ -147,49 +167,42 @@ export function loadPluginHooks(registry, disabledPlugins = [], disabledPluginHo
             continue;
         for (const entry of entries) {
             const installPath = entry.installPath;
-            if (!installPath || !existsSync(installPath))
+            if (!installPath)
                 continue;
-            const raw = readHooksJson(installPath);
-            if (!raw?.hooks)
+            const snapshot = inspectPluginHooks(installPath);
+            const approval = pluginHookApprovalState(entry, snapshot);
+            if (approval === "pending" || approval === "changed" || approval === "none") {
+                // Pending and changed executable definitions fail closed. The rest of
+                // the plugin remains available; hook-free installs have nothing to load.
                 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))
+            }
+            if (!snapshot.definition)
+                continue;
+            for (const hook of iteratePluginHooks(snapshot.definition)) {
+                if (disabledHookSet.has(pluginHookKey({
+                    plugin: pluginNameFromKey(key),
+                    rawEvent: hook.rawEvent,
+                    command: hook.command.command,
+                }))) {
                     continue;
-                for (const group of groups) {
-                    const commands = group.hooks ?? [];
-                    for (const cmd of commands) {
-                        if (cmd.type !== "command" || typeof cmd.command !== "string") {
-                            continue;
-                        }
-                        if (disabledHookSet.has(pluginHookKey({
-                            plugin: pluginNameFromKey(key),
-                            rawEvent: eventNameRaw,
-                            command: cmd.command,
-                        }))) {
-                            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}`);
-                    }
                 }
+                const commandLine = hook.command.command;
+                const timeoutMs = hook.command.timeoutMs;
+                // A CC event that maps onto a SHARED codeshell event (SubagentStop
+                // → notification) gets an implied kind-matcher, so it only fires
+                // for the notification kinds that correspond to the CC semantics.
+                const matcher = hook.matcher ?? IMPLIED_NOTIFICATION_KIND[hook.rawEvent];
+                const handler = async (ctx) => {
+                    if (!matcherAccepts(hook.event, matcher, ctx))
+                        return {};
+                    return runPluginCommandHook({
+                        command: commandLine,
+                        installPath,
+                        pluginKey: key,
+                        timeoutMs,
+                    }, ctx);
+                };
+                registry.register(hook.event, handler, PLUGIN_HOOK_PRIORITY, `plugin:${pluginNameFromKey(key)}:${hook.rawEvent}`);
             }
         }
     }
@@ -211,32 +224,30 @@ export function listPluginHooks(disabledPlugins = []) {
         const disabled = disabledSet.has(plugin);
         for (const entry of entries) {
             const installPath = entry.installPath;
-            if (!installPath || !existsSync(installPath))
+            if (!installPath)
                 continue;
-            const raw = readHooksJson(installPath);
-            if (!raw?.hooks)
+            const snapshot = inspectPluginHooks(installPath);
+            const integrity = verifyPluginHookIntegrity(entry, snapshot);
+            const approval = pluginHookApprovalState(entry, snapshot);
+            if (!snapshot.definition)
                 continue;
-            for (const [eventNameRaw, groups] of Object.entries(raw.hooks)) {
-                const mapped = EVENT_NAME_MAP[eventNameRaw];
-                if (mapped === null || mapped === undefined)
-                    continue;
-                if (!Array.isArray(groups))
-                    continue;
-                for (const group of groups) {
-                    for (const cmd of group.hooks ?? []) {
-                        if (cmd.type !== "command" || typeof cmd.command !== "string")
-                            continue;
-                        out.push({
-                            plugin,
-                            event: mapped,
-                            rawEvent: eventNameRaw,
-                            command: cmd.command,
-                            matcher: group.matcher,
-                            disabled,
-                            key: pluginHookKey({ plugin, rawEvent: eventNameRaw, command: cmd.command }),
-                        });
-                    }
-                }
+            for (const hook of iteratePluginHooks(snapshot.definition)) {
+                out.push({
+                    installKey: key,
+                    plugin,
+                    event: hook.event,
+                    rawEvent: hook.rawEvent,
+                    command: hook.command.command,
+                    matcher: hook.matcher,
+                    disabled,
+                    integrity,
+                    approval,
+                    key: pluginHookKey({
+                        plugin,
+                        rawEvent: hook.rawEvent,
+                        command: hook.command.command,
+                    }),
+                });
             }
         }
     }

package/dist/plugins/pluginAutomationTemplates.d.ts

@@ -0,0 +1,18 @@
+import type { CronJob, CronScheduler } from "../automation/scheduler.js";
+export declare const MAX_PLUGIN_AUTOMATIONS = 256;
+export interface InstantiatePluginAutomationTemplateOptions {
+    scheduler: Pick<CronScheduler, "create" | "list">;
+    installKey: string;
+    templateId: string;
+    expectedRevision: string;
+    cwd?: string;
+    /** Effective project/global disable list computed by the host for this cwd. */
+    disabledPluginNames: ReadonlySet<string>;
+    maxJobs?: number;
+}
+/**
+ * Copy an installed plugin template into a standalone cron job. This never
+ * runs during install/update and never trusts executable fields supplied by a
+ * renderer or protocol client.
+ */
+export declare function instantiatePluginAutomationTemplate(options: InstantiatePluginAutomationTemplateOptions): CronJob;

package/dist/plugins/pluginAutomationTemplates.js

@@ -0,0 +1,50 @@
+import { loadPluginAutomationTemplateContributions } from "./pluginCatalog.js";
+export const MAX_PLUGIN_AUTOMATIONS = 256;
+/**
+ * Copy an installed plugin template into a standalone cron job. This never
+ * runs during install/update and never trusts executable fields supplied by a
+ * renderer or protocol client.
+ */
+export function instantiatePluginAutomationTemplate(options) {
+    if (typeof options.installKey !== "string" || !options.installKey) {
+        throw new Error("installKey is required");
+    }
+    if (typeof options.templateId !== "string" || !options.templateId) {
+        throw new Error("templateId is required");
+    }
+    if (!/^[a-f0-9]{64}$/.test(options.expectedRevision)) {
+        throw new Error("automation template revision is invalid");
+    }
+    const contribution = loadPluginAutomationTemplateContributions().find((entry) => entry.installKey === options.installKey && entry.template.id === options.templateId);
+    if (!contribution) {
+        throw new Error(`automation template not found: ${options.installKey}/${options.templateId}`);
+    }
+    if (contribution.template.workspace === "current" && !options.cwd) {
+        throw new Error("this automation template requires a current project");
+    }
+    if (contribution.revision !== options.expectedRevision) {
+        throw new Error("automation template changed after review; review it again before creating");
+    }
+    if (options.disabledPluginNames.has(contribution.pluginName)) {
+        throw new Error(`plugin is disabled for this project: ${contribution.pluginName}`);
+    }
+    const maxJobs = options.maxJobs ?? MAX_PLUGIN_AUTOMATIONS;
+    if (!Number.isSafeInteger(maxJobs) || maxJobs <= 0) {
+        throw new Error("maxJobs must be a positive safe integer");
+    }
+    if (options.scheduler.list().length >= maxJobs) {
+        throw new Error(`automation limit reached (${maxJobs})`);
+    }
+    const template = contribution.template;
+    return options.scheduler.create(template.title.default, template.schedule, template.prompt, {
+        ...(template.workspace === "current" && options.cwd ? { cwd: options.cwd } : {}),
+        ...(template.timezone ? { timezone: template.timezone } : {}),
+        permissionLevel: template.permissionLevel,
+        templateSource: {
+            installKey: options.installKey,
+            templateId: options.templateId,
+            revision: contribution.revision,
+            ...(contribution.pluginVersion ? { pluginVersion: contribution.pluginVersion } : {}),
+        },
+    });
+}

package/dist/plugins/pluginCatalog.d.ts

@@ -0,0 +1,45 @@
+import { type PluginAutomationTemplate, type CanonicalPluginManifest as CanonicalPluginManifestData } from "./installer/types.js";
+import type { InstalledPluginsV2 } from "./types.js";
+/** Core-owned, trusted view of one installed plugin. */
+export interface PluginCatalogEntry {
+    installKey: string;
+    name: string;
+    marketplace: string | null;
+    installPath: string;
+    version: string;
+    installedAt: string;
+    lastUpdated: string;
+    manifest: CanonicalPluginManifestData | null;
+    /** Reusable scheduled-task templates. They never instantiate during install. */
+    automationTemplates: readonly PluginAutomationTemplate[];
+}
+export interface LoadPluginCatalogOptions {
+    /** Override points make the loader reusable by isolated hosts and deterministic tests. */
+    root?: string;
+    installed?: InstalledPluginsV2;
+}
+export interface PluginAutomationTemplateContribution {
+    kind: "automation-template";
+    installKey: string;
+    pluginName: string;
+    marketplace: string | null;
+    installPath: string;
+    pluginVersion?: string;
+    revision: string;
+    template: PluginAutomationTemplate;
+}
+/**
+ * Stable content revision used to bind a user review to the exact template
+ * instantiated later. Install paths and timestamps are intentionally excluded.
+ */
+export declare function pluginAutomationTemplateRevision(installKey: string, template: PluginAutomationTemplate): string;
+/**
+ * Load the installed plugin catalog at the core boundary.
+ *
+ * Installed state is user-writable, so paths are realpath-contained before any
+ * manifest is exposed. Multiple scope rows for one install key collapse to the
+ * first safe entry, matching the current single-user-scope runtime contract.
+ */
+export declare function loadPluginCatalog(options?: LoadPluginCatalogOptions): PluginCatalogEntry[];
+/** Load reusable automation templates without creating or enabling any jobs. */
+export declare function loadPluginAutomationTemplateContributions(options?: LoadPluginCatalogOptions): PluginAutomationTemplateContribution[];

package/dist/plugins/pluginCatalog.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readInstalledPlugins } from "./installedPlugins.js";
+import { pluginsRoot } from "./installer/paths.js";
+import { CANONICAL_PLUGIN_MANIFEST_FILE, CanonicalPluginManifest, } from "./installer/types.js";
+import { resolveSafePluginPath } from "./pluginInstaller.js";
+/**
+ * Stable content revision used to bind a user review to the exact template
+ * instantiated later. Install paths and timestamps are intentionally excluded.
+ */
+export function pluginAutomationTemplateRevision(installKey, template) {
+    return createHash("sha256")
+        .update("codeshell-plugin-automation-template-v1")
+        .update("\0")
+        .update(installKey)
+        .update("\0")
+        .update(JSON.stringify(template))
+        .digest("hex");
+}
+function readCanonicalManifest(installPath) {
+    const file = join(installPath, CANONICAL_PLUGIN_MANIFEST_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        return CanonicalPluginManifest.parse(JSON.parse(readFileSync(file, "utf-8")));
+    }
+    catch {
+        return null;
+    }
+}
+function identityFromInstallKey(installKey, manifest) {
+    const at = installKey.lastIndexOf("@");
+    if (at > 0 && at < installKey.length - 1) {
+        return { name: installKey.slice(0, at), marketplace: installKey.slice(at + 1) };
+    }
+    return { name: manifest?.name ?? installKey, marketplace: null };
+}
+/**
+ * Load the installed plugin catalog at the core boundary.
+ *
+ * Installed state is user-writable, so paths are realpath-contained before any
+ * manifest is exposed. Multiple scope rows for one install key collapse to the
+ * first safe entry, matching the current single-user-scope runtime contract.
+ */
+export function loadPluginCatalog(options = {}) {
+    const root = options.root ?? pluginsRoot();
+    const installed = options.installed ?? readInstalledPlugins();
+    const catalog = [];
+    const loadedKeys = new Set();
+    for (const installKey of Object.keys(installed.plugins).sort()) {
+        for (const entry of installed.plugins[installKey] ?? []) {
+            if (loadedKeys.has(installKey))
+                break;
+            const installPath = resolveSafePluginPath(entry.installPath, root);
+            if (!installPath)
+                continue;
+            const manifest = readCanonicalManifest(installPath);
+            const identity = identityFromInstallKey(installKey, manifest);
+            catalog.push({
+                installKey,
+                ...identity,
+                installPath,
+                version: entry.version,
+                installedAt: entry.installedAt,
+                lastUpdated: entry.lastUpdated,
+                manifest,
+                automationTemplates: manifest?.automations?.templates ?? [],
+            });
+            loadedKeys.add(installKey);
+        }
+    }
+    return catalog;
+}
+/** Load reusable automation templates without creating or enabling any jobs. */
+export function loadPluginAutomationTemplateContributions(options = {}) {
+    return loadPluginCatalog(options).flatMap((plugin) => plugin.automationTemplates.map((template) => ({
+        kind: "automation-template",
+        installKey: plugin.installKey,
+        pluginName: plugin.name,
+        marketplace: plugin.marketplace,
+        installPath: plugin.installPath,
+        ...(plugin.manifest?.version ? { pluginVersion: plugin.manifest.version } : {}),
+        revision: pluginAutomationTemplateRevision(plugin.installKey, template),
+        template,
+    })));
+}

package/dist/plugins/pluginCommandHook.d.ts

@@ -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
@@ -38,17 +41,20 @@ export interface PluginCommandHookSpec {
     installPath: string;
     /** Plugin install key (`name@marketplace`), used for log lines. */
     pluginKey: string;
+    /** Stable writable plugin data directory; primarily an injection point for tests/hosts. */
+    dataPath?: string;
     /** Per-hook override; falls back to DEFAULT_TIMEOUT_MS. */
     timeoutMs?: number;
 }
+export declare function resolvePluginDataPath(pluginKey: string): string;
 /**
- * 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 declare function runPluginCommandHook(spec: PluginCommandHookSpec, ctx: HookContext): Promise<HookResult>;
+export declare function runPluginCommandHook(spec: PluginCommandHookSpec, ctx: HookContext, abortSignal?: AbortSignal): Promise<HookResult>;