@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/plugins/installer/types.js

@@ -1,4 +1,90 @@
 import { z } from "zod";
+const PluginLocalizedTitle = z
+    .object({
+    default: z.string().min(1).max(120),
+    en: z.string().min(1).max(120).optional(),
+    "zh-CN": z.string().min(1).max(120).optional(),
+})
+    .strict();
+export const PluginAutomationTemplate = z
+    .object({
+    id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+    title: PluginLocalizedTitle,
+    description: z.string().min(1).max(500).optional(),
+    schedule: z.string().min(1).max(128),
+    prompt: z.string().min(1).max(32_768),
+    timezone: z.string().min(1).max(100).optional(),
+    permissionLevel: z.enum(["read-only", "workspace-write", "full"]).default("read-only"),
+    workspace: z.enum(["current", "none"]).default("current"),
+})
+    .strict();
+export const PluginAutomationsManifest = z
+    .object({
+    version: z.literal(1),
+    templates: z.array(PluginAutomationTemplate).max(32),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const ids = new Set();
+    for (const [index, template] of value.templates.entries()) {
+        if (ids.has(template.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["templates", index, "id"],
+                message: `duplicate automation template id: ${template.id}`,
+            });
+        }
+        ids.add(template.id);
+    }
+});
+const CodexHooksDeclaration = z.union([
+    z.string(),
+    z.record(z.any()),
+    z.array(z.union([z.string(), z.record(z.any())])),
+]);
+const HttpsPluginUrl = z
+    .string()
+    .url()
+    .max(2048)
+    .refine((value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && Boolean(url.hostname) && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}, { message: "plugin interface URL must use https" });
+export const PluginInterfaceMetadata = z
+    .object({
+    displayName: z.string().min(1).max(120).optional(),
+    shortDescription: z.string().min(1).max(300).optional(),
+    longDescription: z.string().min(1).max(4000).optional(),
+    developerName: z.string().min(1).max(160).optional(),
+    category: z.string().min(1).max(100).optional(),
+    capabilities: z.array(z.string().min(1).max(80)).max(32).optional(),
+    websiteURL: HttpsPluginUrl.optional(),
+    privacyPolicyURL: HttpsPluginUrl.optional(),
+    termsOfServiceURL: HttpsPluginUrl.optional(),
+    defaultPrompt: z.array(z.string().min(1).max(128)).max(3).optional(),
+    brandColor: z
+        .string()
+        .regex(/^#[0-9a-fA-F]{6}$/)
+        .optional(),
+    composerIcon: z.string().min(1).max(512).optional(),
+    logo: z.string().min(1).max(512).optional(),
+    logoDark: z.string().min(1).max(512).optional(),
+    screenshots: z.array(z.string().min(1).max(512)).max(3).optional(),
+})
+    .strip();
+/** CodeShell-only manifest overlay kept outside `.codex-plugin/plugin.json`. */
+export const CodeShellPluginOverlay = z
+    .object({
+    schemaVersion: z.literal(1),
+    automations: PluginAutomationsManifest.optional(),
+})
+    .strict();
+export const CODESHELL_PLUGIN_OVERLAY_FILE = ".codeshell-plugin/plugin.json";
 /** Codex `.codex-plugin/plugin.json`. v1 reads required fields; unknowns pass through. */
 export const CodexPluginManifest = z
     .object({
@@ -9,8 +95,22 @@ export const CodexPluginManifest = z
     mcpServers: z.union([z.string(), z.record(z.any())]).optional(),
     skills: z.string().optional(),
     agents: z.string().optional(),
+    hooks: CodexHooksDeclaration.optional(),
+    interface: PluginInterfaceMetadata.passthrough().optional(),
 })
     .passthrough();
+/** Trusted, normalized manifest written into an installed plugin directory. */
+export const CanonicalPluginManifest = z
+    .object({
+    schemaVersion: z.literal(1),
+    name: z.string().min(1),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    interface: PluginInterfaceMetadata.optional(),
+    automations: PluginAutomationsManifest.optional(),
+})
+    .strict();
+export const CANONICAL_PLUGIN_MANIFEST_FILE = ".cs-plugin-manifest.json";
 /** `.cs-meta.json` written into every installed plugin dir. */
 export const CSMeta = z.object({
     name: z.string(),

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

@@ -1,3 +1,8 @@
+export declare const MAX_PLUGIN_ZIP_BYTES: number;
+export declare const MAX_PLUGIN_ZIP_ENTRIES = 10000;
+export declare const MAX_PLUGIN_ZIP_EXTRACTED_BYTES: number;
+export declare const MAX_PLUGIN_ZIP_ENTRY_BYTES: number;
+export declare const MAX_PLUGIN_ZIP_ENTRY_NAME = 1024;
 /**
  * Reject path traversal ("zip slip"): a malicious archive can carry entries
  * like `../../etc/foo` that escape the extraction root. We normalize and
@@ -12,3 +17,9 @@ export declare function safeJoin(destDir: string, entryName: string): string;
  * needs and keeps the surface safe.
  */
 export declare function extractZip(zipPath: string, destDir: string): Promise<void>;
+/**
+ * Extract one repository-relative subtree from an archive with a single
+ * wrapper directory, as produced by GitHub source archives. Unrelated
+ * monorepo content is never materialized or counted against extracted limits.
+ */
+export declare function extractZipSubdirectory(zipPath: string, destDir: string, subdirectory?: string): Promise<void>;

package/dist/plugins/installer/unzip.js

@@ -1,9 +1,14 @@
 import { createRequire } from "node:module";
 import { createWriteStream } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
 import { dirname, join, normalize, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { PluginInstallError } from "./types.js";
+export const MAX_PLUGIN_ZIP_BYTES = 128 * 1024 * 1024;
+export const MAX_PLUGIN_ZIP_ENTRIES = 10_000;
+export const MAX_PLUGIN_ZIP_EXTRACTED_BYTES = 256 * 1024 * 1024;
+export const MAX_PLUGIN_ZIP_ENTRY_BYTES = 64 * 1024 * 1024;
+export const MAX_PLUGIN_ZIP_ENTRY_NAME = 1_024;
 let _yauzl;
 function yauzl() {
     if (!_yauzl) {
@@ -17,6 +22,14 @@ function yauzl() {
  * require the resolved path to stay within `destDir`.
  */
 export function safeJoin(destDir, entryName) {
+    if (entryName.length === 0 ||
+        entryName.length > MAX_PLUGIN_ZIP_ENTRY_NAME ||
+        entryName.includes("\0") ||
+        entryName.includes("\\") ||
+        entryName.startsWith("/") ||
+        /^[A-Za-z]:/.test(entryName)) {
+        throw new PluginInstallError(`refusing unsafe zip entry name: ${entryName}`);
+    }
     // Zip entries always use forward slashes; normalize to the host separator.
     const target = normalize(join(destDir, entryName));
     const root = normalize(destDir.endsWith(sep) ? destDir : destDir + sep);
@@ -33,6 +46,10 @@ export function safeJoin(destDir, entryName) {
  * needs and keeps the surface safe.
  */
 export async function extractZip(zipPath, destDir) {
+    const archive = await stat(zipPath);
+    if (!archive.isFile() || archive.size > MAX_PLUGIN_ZIP_BYTES) {
+        throw new PluginInstallError(`plugin zip must be a regular file no larger than ${MAX_PLUGIN_ZIP_BYTES} bytes`);
+    }
     const zip = await openZip(zipPath);
     try {
         await drainEntries(zip, destDir);
@@ -41,6 +58,61 @@ export async function extractZip(zipPath, destDir) {
         zip.close();
     }
 }
+/**
+ * Extract one repository-relative subtree from an archive with a single
+ * wrapper directory, as produced by GitHub source archives. Unrelated
+ * monorepo content is never materialized or counted against extracted limits.
+ */
+export async function extractZipSubdirectory(zipPath, destDir, subdirectory = "") {
+    const archive = await stat(zipPath);
+    if (!archive.isFile() || archive.size > MAX_PLUGIN_ZIP_BYTES) {
+        throw new PluginInstallError(`plugin zip must be a regular file no larger than ${MAX_PLUGIN_ZIP_BYTES} bytes`);
+    }
+    const normalizedSubdirectory = subdirectory.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (normalizedSubdirectory.startsWith("/") ||
+        normalizedSubdirectory.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new PluginInstallError(`refusing unsafe zip subdirectory: ${subdirectory}`);
+    }
+    let wrapper;
+    const prefix = normalizedSubdirectory ? `${normalizedSubdirectory}/` : "";
+    const zip = await openZip(zipPath);
+    try {
+        const selected = await drainEntries(zip, destDir, (entryName) => {
+            // Validate the original archive path before removing GitHub's generated
+            // top-level wrapper. safeJoin rejects traversal, absolute paths, NULs,
+            // drive letters, and backslashes.
+            safeJoin(destDir, entryName);
+            const slash = entryName.indexOf("/");
+            if (slash < 1)
+                return null;
+            const entryWrapper = entryName.slice(0, slash);
+            if (wrapper === undefined)
+                wrapper = entryWrapper;
+            else if (wrapper !== entryWrapper) {
+                throw new PluginInstallError("GitHub source archive contains multiple root directories");
+            }
+            const repositoryPath = entryName.slice(slash + 1);
+            if (!repositoryPath)
+                return null;
+            if (normalizedSubdirectory) {
+                if (repositoryPath !== normalizedSubdirectory && !repositoryPath.startsWith(prefix)) {
+                    return null;
+                }
+                const relativePath = repositoryPath === normalizedSubdirectory ? "" : repositoryPath.slice(prefix.length);
+                return relativePath || null;
+            }
+            return repositoryPath;
+        });
+        if (selected === 0) {
+            throw new PluginInstallError(normalizedSubdirectory
+                ? `GitHub source archive does not contain subdirectory: ${normalizedSubdirectory}`
+                : "GitHub source archive is empty");
+        }
+    }
+    finally {
+        zip.close();
+    }
+}
 function openZip(zipPath) {
     return new Promise((resolve, reject) => {
         yauzl().open(zipPath, { lazyEntries: true }, (err, z) => {
@@ -52,23 +124,65 @@ function openZip(zipPath) {
         });
     });
 }
-function drainEntries(zip, destDir) {
+function drainEntries(zip, destDir, mapEntryName = (entryName) => entryName) {
     return new Promise((resolve, reject) => {
-        zip.on("error", (e) => reject(e));
-        zip.on("end", () => resolve());
+        let entryCount = 0;
+        let extractedBytes = 0;
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            zip.close();
+            reject(error);
+        };
+        zip.on("error", fail);
+        zip.on("end", () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(entryCount);
+        });
         zip.on("entry", (entry) => {
-            const onErr = (e) => reject(e);
+            let entryName;
+            try {
+                entryName = mapEntryName(entry.fileName);
+            }
+            catch (error) {
+                fail(error);
+                return;
+            }
+            if (entryName === null) {
+                zip.readEntry();
+                return;
+            }
+            entryCount += 1;
+            if (entryCount > MAX_PLUGIN_ZIP_ENTRIES) {
+                fail(new PluginInstallError(`plugin zip contains more than ${MAX_PLUGIN_ZIP_ENTRIES} entries`));
+                return;
+            }
+            if (entryName.length > MAX_PLUGIN_ZIP_ENTRY_NAME ||
+                entry.uncompressedSize > MAX_PLUGIN_ZIP_ENTRY_BYTES) {
+                fail(new PluginInstallError(`plugin zip entry exceeds preview/install limits: ${entryName}`));
+                return;
+            }
+            extractedBytes += entry.uncompressedSize;
+            if (extractedBytes > MAX_PLUGIN_ZIP_EXTRACTED_BYTES) {
+                fail(new PluginInstallError(`plugin zip expands beyond ${MAX_PLUGIN_ZIP_EXTRACTED_BYTES} bytes`));
+                return;
+            }
+            const onErr = (e) => fail(e);
             // Directory entry — yauzl signals these with a trailing slash.
-            if (/\/$/.test(entry.fileName)) {
-                mkdir(safeJoin(destDir, entry.fileName), { recursive: true })
+            if (/\/$/.test(entryName)) {
+                mkdir(safeJoin(destDir, entryName), { recursive: true })
                     .then(() => zip.readEntry())
                     .catch(onErr);
                 return;
             }
-            const outPath = safeJoin(destDir, entry.fileName);
+            const outPath = safeJoin(destDir, entryName);
             zip.openReadStream(entry, (err, stream) => {
                 if (err || !stream) {
-                    onErr(new PluginInstallError(`cannot read zip entry ${entry.fileName}: ${err?.message ?? "unknown"}`));
+                    onErr(new PluginInstallError(`cannot read zip entry ${entryName}: ${err?.message ?? "unknown"}`));
                     return;
                 }
                 mkdir(dirname(outPath), { recursive: true })

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

@@ -15,8 +15,8 @@ export interface UpdatePluginOptions {
  * on failure we delete any partial install and rename the backup back.
  *
  * Async fs only — this runs in the Electron main process, so we never block the
- * event loop with sync fs. process.pid (not Date.now(), unavailable here) makes
- * the backup name unique.
+ * event loop with sync fs. A random sibling name keeps concurrent attempts
+ * from deleting or restoring each other's backup.
  */
 export declare function reinstallAtomic(name: string, source: string, doInstall: () => Promise<unknown>): Promise<void>;
 /**

package/dist/plugins/installer/update.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { rename, rm } from "node:fs/promises";
 import { join } from "node:path";
@@ -7,6 +8,9 @@ import { installPluginFromPath } from "./install.js";
 import { installPluginFromSource } from "./installFromSource.js";
 import { parseSource } from "./parseSource.js";
 import { pluginInstallKey, readInstalledPlugins, removeInstallEntries, writeInstalledPlugins, } from "../installedPlugins.js";
+import { pluginHookInstallRecord } from "../pluginHookIntegrity.js";
+import { pluginMcpInstallRecord } from "../pluginMcpIntegrity.js";
+import { readPluginMcp } from "./loadPluginMcp.js";
 import { CodexPluginManifest, CSMeta, PluginInstallError } from "./types.js";
 /**
  * Reinstall a plugin atomically: a failed update leaves the OLD plugin intact.
@@ -18,24 +22,56 @@ import { CodexPluginManifest, CSMeta, PluginInstallError } from "./types.js";
  * on failure we delete any partial install and rename the backup back.
  *
  * Async fs only — this runs in the Electron main process, so we never block the
- * event loop with sync fs. process.pid (not Date.now(), unavailable here) makes
- * the backup name unique.
+ * event loop with sync fs. A random sibling name keeps concurrent attempts
+ * from deleting or restoring each other's backup.
  */
 export async function reinstallAtomic(name, source, doInstall) {
     const dir = pluginInstallDir(name);
-    const backup = `${dir}.bak-${process.pid}`;
+    const backup = `${dir}.bak-${process.pid}-${randomUUID()}`;
     // Capture the existing install_plugins.json entries so a failed reinstall can
     // restore them (uninstall-then-install used to drop them on failure; here the
     // old plugin survives, so its registration must survive too).
     const key = pluginInstallKey(name, "local");
     const savedEntries = readInstalledPlugins().plugins[key];
-    await rm(backup, { recursive: true, force: true });
     await rename(dir, backup);
     // The installer re-adds the entry on success; remove the stale one first so a
     // successful reinstall doesn't accumulate a duplicate.
     removeInstallEntries(key);
     try {
         await doInstall();
+        if (savedEntries) {
+            const data = readInstalledPlugins();
+            const installed = data.plugins[key] ?? [];
+            let changed = false;
+            for (const entry of installed) {
+                const next = pluginHookInstallRecord(entry.installPath, savedEntries);
+                const nextMcp = pluginMcpInstallRecord(entry.installPath, Object.keys(readPluginMcp(entry.installPath, name)).length > 0, savedEntries);
+                if (entry.hookDigest !== next.hookDigest ||
+                    entry.approvedHookDigest !== next.approvedHookDigest ||
+                    JSON.stringify(entry.approvedHookSnapshot) !==
+                        JSON.stringify(next.approvedHookSnapshot) ||
+                    entry.mcpDigest !== nextMcp.mcpDigest ||
+                    entry.approvedMcpDigest !== nextMcp.approvedMcpDigest) {
+                    entry.hookDigest = next.hookDigest;
+                    if (next.approvedHookDigest)
+                        entry.approvedHookDigest = next.approvedHookDigest;
+                    else
+                        delete entry.approvedHookDigest;
+                    if (next.approvedHookSnapshot)
+                        entry.approvedHookSnapshot = next.approvedHookSnapshot;
+                    else
+                        delete entry.approvedHookSnapshot;
+                    entry.mcpDigest = nextMcp.mcpDigest;
+                    if (nextMcp.approvedMcpDigest)
+                        entry.approvedMcpDigest = nextMcp.approvedMcpDigest;
+                    else
+                        delete entry.approvedMcpDigest;
+                    changed = true;
+                }
+            }
+            if (changed)
+                writeInstalledPlugins(data);
+        }
     }
     catch (err) {
         // Roll back: drop any partial install, restore the old dir + its entries.
@@ -75,6 +111,9 @@ export async function updatePluginByName(name, installedAt, force, options = {})
     const parsed = parseSource(meta.source, {
         allowUnsafeTransport: options.allowUnsafeTransport === true,
     });
+    if (parsed.kind === "npm") {
+        throw new PluginInstallError("npm plugin auto-update is not available in Phase A; install an explicit npm:<package>@<version> source instead");
+    }
     if (parsed.kind === "remote") {
         // No local version to diff against — always re-clone and reinstall.
         await reinstallAtomic(name, meta.source, () => installPluginFromSource(parsed, name, installedAt));

package/dist/plugins/loadPluginHooks.d.ts

@@ -30,20 +30,31 @@
  *   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 type { HookEventName } from "../hooks/events.js";
+import type { HookContext, HookEventName } from "../hooks/events.js";
 import type { HookRegistry } from "../hooks/registry.js";
+import { type PluginHookApprovalState, type PluginHookIntegrity } from "./pluginHookIntegrity.js";
+/**
+ * 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).
+ */
+export declare function matcherAccepts(event: HookEventName, matcher: string | undefined, ctx: HookContext): boolean;
 /**
  * Stable identity for ONE plugin-provided hook, used as the record key in
  * `capabilityOverrides.pluginHooks` (per-hook project off-switch). Derived
@@ -78,6 +89,8 @@ export declare function pluginHookKey(hook: {
 export declare function loadPluginHooks(registry: HookRegistry, disabledPlugins?: string[], disabledPluginHooks?: string[]): void;
 /** A single plugin-provided hook, surfaced read-only to the settings UI. */
 export interface PluginHookEntry {
+    /** Full install key (`plugin@marketplace`) used by approval APIs. */
+    installKey: string;
     /** Source plugin name (bare, no @marketplace). */
     plugin: string;
     /** Mapped codeshell event name. */
@@ -90,6 +103,10 @@ export interface PluginHookEntry {
     matcher?: string;
     /** Whether the owning plugin is currently disabled (its hooks don't fire). */
     disabled: boolean;
+    /** Install-time integrity state for the executable hook definition. */
+    integrity: PluginHookIntegrity;
+    /** Explicit execution trust state. Pending/changed hooks do not register. */
+    approval: PluginHookApprovalState;
     /** Stable per-hook identity ({@link pluginHookKey}) — the record key the
      *  UI writes to `capabilityOverrides.pluginHooks` to toggle just this hook. */
     key: string;