@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.1

package/dist/plugins/installer/loadPluginMcp.js

@@ -5,6 +5,32 @@ function pluginNameFromKey(key) {
     const at = key.lastIndexOf("@");
     return at > 0 ? key.slice(0, at) : key;
 }
+/**
+ * Layer a user override's supplement fields onto a plugin server config.
+ *
+ * Only env/credential fields are picked — command/args/url/transport are
+ * deliberately NOT carried, because those are the plugin's identity and must
+ * keep coming from the plugin manifest so a plugin update can change them
+ * without the user being stuck on a stale shadow copy. This explicit pick is
+ * defense-in-depth on top of the schema's `.strict()`, so a hand-edited
+ * settings file can never smuggle those fields in.
+ */
+function applyOverride(pluginConfig, override) {
+    if (!override)
+        return pluginConfig;
+    const supplement = {};
+    if (override.env !== undefined)
+        supplement.env = override.env;
+    if (override.envVars !== undefined)
+        supplement.envVars = override.envVars;
+    if (override.credentialRef !== undefined)
+        supplement.credentialRef = override.credentialRef;
+    if (override.bearerTokenEnvVar !== undefined)
+        supplement.bearerTokenEnvVar = override.bearerTokenEnvVar;
+    if (override.envHeaders !== undefined)
+        supplement.envHeaders = override.envHeaders;
+    return { ...pluginConfig, ...supplement };
+}
 /**
  * Read a single plugin's MCP servers, already keyed `<plugin>:<server>`.
  *
@@ -52,8 +78,15 @@ function readPluginMcp(installPath, pluginName) {
  * Merge each registered plugin's MCP servers into a copy of `base`.
  * Plugin keys are `<plugin>:<server>`. A key already present in `base`
  * (user-configured) is NOT overwritten. Disabled plugins are skipped.
+ *
+ * `overrides` lets the user *supplement* a plugin server's env/credential
+ * fields without editing the plugin's manifest: for a plugin-sourced server,
+ * the override's {@link OVERRIDE_FIELDS} are layered on top (override wins),
+ * while command/args/url/transport stay from the plugin. Overrides do NOT
+ * apply to user-added (base) servers — those are edited via `mcpServers`
+ * directly — and an override for an unknown/disabled server has no effect.
  */
-export function mergePluginMcpServers(base, disabledPlugins = []) {
+export function mergePluginMcpServers(base, disabledPlugins = [], overrides = {}) {
     const disabled = new Set(disabledPlugins);
     const merged = { ...base };
     const data = readInstalledPlugins();
@@ -66,7 +99,7 @@ export function mergePluginMcpServers(base, disabledPlugins = []) {
             for (const [k, cfg] of Object.entries(servers)) {
                 if (k in merged)
                     continue; // user / earlier wins
-                merged[k] = cfg;
+                merged[k] = applyOverride(cfg, overrides[k]);
             }
         }
     }

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

@@ -0,0 +1,24 @@
+/**
+ * Prune a plugin's orphaned entries from a settings object's `disabledSkills`
+ * (entries shaped `name:skill`) and `disabledPlugins` (bare `name`). Called on
+ * uninstall so a removed plugin leaves no dangling disable flags behind.
+ *
+ * Pure + immutable: returns a NEW object (shallow clone) with the two arrays
+ * replaced by filtered copies. Settings lacking these fields pass through
+ * unchanged. A plugin name that is a prefix of another (`mimi-video` vs
+ * `mimi-video-pro`) only matches its own exact name / `name:` prefix.
+ */
+export interface PrunableSettings {
+    disabledSkills?: string[];
+    disabledPlugins?: string[];
+    [key: string]: unknown;
+}
+export declare function pruneDisabledEntriesForPlugin<T extends PrunableSettings>(settings: T, pluginName: string): T;
+/**
+ * Read the user settings.json (under {@link userHome}, so HOME-isolated tests
+ * are honored), prune the plugin's orphaned disable entries, and write back —
+ * only when something actually changed. Never throws: a missing/corrupt file or
+ * any IO error is swallowed (uninstall already succeeded; settings cleanup is
+ * best-effort). Atomic write via .tmp + rename mirrors SettingsManager.
+ */
+export declare function pruneDisabledSettingsForPlugin(pluginName: string): void;

package/dist/plugins/installer/pruneDisabled.js

@@ -0,0 +1,73 @@
+/**
+ * Prune a plugin's orphaned entries from a settings object's `disabledSkills`
+ * (entries shaped `name:skill`) and `disabledPlugins` (bare `name`). Called on
+ * uninstall so a removed plugin leaves no dangling disable flags behind.
+ *
+ * Pure + immutable: returns a NEW object (shallow clone) with the two arrays
+ * replaced by filtered copies. Settings lacking these fields pass through
+ * unchanged. A plugin name that is a prefix of another (`mimi-video` vs
+ * `mimi-video-pro`) only matches its own exact name / `name:` prefix.
+ */
+import { writeFileSync, mkdirSync, existsSync, readFileSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Resolve the user's home dir, preferring `process.env.HOME` so HOME-isolated
+ * tests (and runtime overrides) take effect — same contract as
+ * SettingsManager.userHome and installer/paths.ts, without dragging in the
+ * settings module's heavier transitive deps.
+ */
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+export function pruneDisabledEntriesForPlugin(settings, pluginName) {
+    const skillPrefix = `${pluginName}:`;
+    const out = { ...settings };
+    if (Array.isArray(settings.disabledSkills)) {
+        out.disabledSkills = settings.disabledSkills.filter((s) => !s.startsWith(skillPrefix));
+    }
+    if (Array.isArray(settings.disabledPlugins)) {
+        out.disabledPlugins = settings.disabledPlugins.filter((p) => p !== pluginName);
+    }
+    return out;
+}
+/**
+ * Read the user settings.json (under {@link userHome}, so HOME-isolated tests
+ * are honored), prune the plugin's orphaned disable entries, and write back —
+ * only when something actually changed. Never throws: a missing/corrupt file or
+ * any IO error is swallowed (uninstall already succeeded; settings cleanup is
+ * best-effort). Atomic write via .tmp + rename mirrors SettingsManager.
+ */
+export function pruneDisabledSettingsForPlugin(pluginName) {
+    try {
+        const path = join(userHome(), ".code-shell", "settings.json");
+        if (!existsSync(path))
+            return;
+        let current;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            current = parsed;
+        }
+        catch {
+            return; // corrupt file — leave it alone
+        }
+        const pruned = pruneDisabledEntriesForPlugin(current, pluginName);
+        const changed = JSON.stringify(pruned.disabledSkills) !== JSON.stringify(current.disabledSkills) ||
+            JSON.stringify(pruned.disabledPlugins) !== JSON.stringify(current.disabledPlugins);
+        if (!changed)
+            return;
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+        // mode 0o600 — settings.json can hold plaintext API keys, so the pruned
+        // rewrite must stay owner-only (matching settings/manager.ts), not fall back
+        // to the umask default 0o644 (world-readable). The tmp IS the final file
+        // after renameSync, so the mode must be set at create time, not via chmod.
+        writeFileSync(tmp, JSON.stringify(pruned, null, 2), { encoding: "utf-8", mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch {
+        // best-effort cleanup — never fail the uninstall over settings IO
+    }
+}

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

@@ -30,18 +30,21 @@ export declare const CSMeta: z.ZodObject<{
     version: z.ZodOptional<z.ZodString>;
     source: z.ZodString;
     installedAt: z.ZodString;
+    commit: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     source: string;
     name: string;
-    format: "codex" | "cc";
+    format: "cc" | "codex";
     installedAt: string;
     version?: string | undefined;
+    commit?: string | undefined;
 }, {
     source: string;
     name: string;
-    format: "codex" | "cc";
+    format: "cc" | "codex";
     installedAt: string;
     version?: string | undefined;
+    commit?: string | undefined;
 }>;
 export type CSMeta = z.infer<typeof CSMeta>;
 export declare class PluginInstallError extends Error {

package/dist/plugins/installer/types.js

@@ -18,6 +18,7 @@ export const CSMeta = z.object({
     version: z.string().optional(),
     source: z.string(),
     installedAt: z.string(),
+    commit: z.string().optional(), // remote (git) source: the HEAD SHA we installed
 });
 export class PluginInstallError extends Error {
     constructor(message) {

package/dist/plugins/installer/uninstall.js

@@ -2,6 +2,7 @@ import { existsSync, rmSync } from "node:fs";
 import { pluginInstallDir, assertSafePluginName } from "./paths.js";
 import { removeInstallEntries, pluginInstallKey } from "../installedPlugins.js";
 import { PluginInstallError } from "./types.js";
+import { pruneDisabledSettingsForPlugin } from "./pruneDisabled.js";
 /** Remove a locally-installed plugin dir + its installed_plugins.json entry. */
 export function uninstallPluginByName(name) {
     assertSafePluginName(name);
@@ -11,4 +12,7 @@ export function uninstallPluginByName(name) {
     }
     rmSync(dir, { recursive: true, force: true });
     removeInstallEntries(pluginInstallKey(name, "local"));
+    // Clear orphaned disable flags (disabledSkills "name:skill" /
+    // disabledPlugins "name") so a removed plugin leaves no dangling entries.
+    pruneDisabledSettingsForPlugin(name);
 }

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

@@ -0,0 +1,14 @@
+/**
+ * Reject path traversal ("zip slip"): a malicious archive can carry entries
+ * like `../../etc/foo` that escape the extraction root. We normalize and
+ * require the resolved path to stay within `destDir`.
+ */
+export declare function safeJoin(destDir: string, entryName: string): string;
+/**
+ * Extract a .zip into destDir (must already exist). Streams each entry to disk
+ * so a large archive doesn't buffer in memory. Directory entries (trailing
+ * "/") just create the dir; symlinks and other special entries are skipped —
+ * we only materialize regular files and directories, which is all a plugin
+ * needs and keeps the surface safe.
+ */
+export declare function extractZip(zipPath: string, destDir: string): Promise<void>;

package/dist/plugins/installer/unzip.js

@@ -0,0 +1,82 @@
+import { createRequire } from "node:module";
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join, normalize, sep } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { PluginInstallError } from "./types.js";
+let _yauzl;
+function yauzl() {
+    if (!_yauzl) {
+        _yauzl = createRequire(import.meta.url ?? __filename)("yauzl");
+    }
+    return _yauzl;
+}
+/**
+ * Reject path traversal ("zip slip"): a malicious archive can carry entries
+ * like `../../etc/foo` that escape the extraction root. We normalize and
+ * require the resolved path to stay within `destDir`.
+ */
+export function safeJoin(destDir, 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);
+    if (target !== normalize(destDir) && !target.startsWith(root)) {
+        throw new PluginInstallError(`refusing zip entry that escapes target: ${entryName}`);
+    }
+    return target;
+}
+/**
+ * Extract a .zip into destDir (must already exist). Streams each entry to disk
+ * so a large archive doesn't buffer in memory. Directory entries (trailing
+ * "/") just create the dir; symlinks and other special entries are skipped —
+ * we only materialize regular files and directories, which is all a plugin
+ * needs and keeps the surface safe.
+ */
+export async function extractZip(zipPath, destDir) {
+    const zip = await openZip(zipPath);
+    try {
+        await drainEntries(zip, destDir);
+    }
+    finally {
+        zip.close();
+    }
+}
+function openZip(zipPath) {
+    return new Promise((resolve, reject) => {
+        yauzl().open(zipPath, { lazyEntries: true }, (err, z) => {
+            if (err || !z) {
+                reject(new PluginInstallError(`cannot open zip: ${err?.message ?? "unknown"}`));
+                return;
+            }
+            resolve(z);
+        });
+    });
+}
+function drainEntries(zip, destDir) {
+    return new Promise((resolve, reject) => {
+        zip.on("error", (e) => reject(e));
+        zip.on("end", () => resolve());
+        zip.on("entry", (entry) => {
+            const onErr = (e) => reject(e);
+            // Directory entry — yauzl signals these with a trailing slash.
+            if (/\/$/.test(entry.fileName)) {
+                mkdir(safeJoin(destDir, entry.fileName), { recursive: true })
+                    .then(() => zip.readEntry())
+                    .catch(onErr);
+                return;
+            }
+            const outPath = safeJoin(destDir, entry.fileName);
+            zip.openReadStream(entry, (err, stream) => {
+                if (err || !stream) {
+                    onErr(new PluginInstallError(`cannot read zip entry ${entry.fileName}: ${err?.message ?? "unknown"}`));
+                    return;
+                }
+                mkdir(dirname(outPath), { recursive: true })
+                    .then(() => pipeline(stream, createWriteStream(outPath)))
+                    .then(() => zip.readEntry())
+                    .catch(onErr);
+            });
+        });
+        zip.readEntry();
+    });
+}

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

@@ -2,6 +2,20 @@ export interface UpdateResult {
     updated: boolean;
     reason: string;
 }
+/**
+ * Reinstall a plugin atomically: a failed update leaves the OLD plugin intact.
+ *
+ * The installers (installPluginFromPath / installPluginFromSource) build into a
+ * temp dir then rename into pluginInstallDir(name), and THROW if the final dir
+ * already exists. So we must free the final dir *before* installing — we do that
+ * by renaming the live dir to a sibling backup. On success we drop the backup;
+ * 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.
+ */
+export declare function reinstallAtomic(name: string, source: string, doInstall: () => Promise<unknown>): Promise<void>;
 /**
  * Reinstall a plugin from its recorded source.
  *

package/dist/plugins/installer/update.js

@@ -1,12 +1,62 @@
 import { existsSync, readFileSync } from "node:fs";
+import { rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { detectPluginFormat } from "./detectFormat.js";
 import { pluginInstallDir } from "./paths.js";
-import { uninstallPluginByName } from "./uninstall.js";
 import { installPluginFromPath } from "./install.js";
 import { installPluginFromSource } from "./installFromSource.js";
 import { parseSource } from "./parseSource.js";
+import { pluginInstallKey, readInstalledPlugins, removeInstallEntries, writeInstalledPlugins } from "../installedPlugins.js";
 import { CodexPluginManifest, CSMeta, PluginInstallError } from "./types.js";
+/**
+ * Reinstall a plugin atomically: a failed update leaves the OLD plugin intact.
+ *
+ * The installers (installPluginFromPath / installPluginFromSource) build into a
+ * temp dir then rename into pluginInstallDir(name), and THROW if the final dir
+ * already exists. So we must free the final dir *before* installing — we do that
+ * by renaming the live dir to a sibling backup. On success we drop the backup;
+ * 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.
+ */
+export async function reinstallAtomic(name, source, doInstall) {
+    const dir = pluginInstallDir(name);
+    const backup = `${dir}.bak-${process.pid}`;
+    // 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();
+    }
+    catch (err) {
+        // Roll back: drop any partial install, restore the old dir + its entries.
+        await rm(dir, { recursive: true, force: true });
+        await rename(backup, dir);
+        if (savedEntries) {
+            // Restore in a single read-modify-write rather than one append per entry,
+            // which both narrows the race window against any concurrent writer and
+            // avoids re-appending onto whatever partial state doInstall() may have
+            // left for this key.
+            const data = readInstalledPlugins();
+            data.plugins[key] = savedEntries;
+            writeInstalledPlugins(data);
+        }
+        throw new PluginInstallError(`update failed; the old version of '${name}' was kept: ` +
+            `${err instanceof Error ? err.message : String(err)}. Source: ${source}.`);
+    }
+    // Success — drop the backup (best-effort; a leftover backup is harmless but
+    // we clean it up so it never shows up in the plugins root).
+    await rm(backup, { recursive: true, force: true });
+}
 /**
  * Reinstall a plugin from its recorded source.
  *
@@ -25,18 +75,7 @@ export async function updatePluginByName(name, installedAt, force) {
     const parsed = parseSource(meta.source);
     if (parsed.kind === "remote") {
         // No local version to diff against — always re-clone and reinstall.
-        // uninstall-then-install isn't atomic: if the reinstall fails (clone
-        // error, bad plugin) the old copy is already gone. We can't roll back the
-        // removal, but we surface a clear error instead of leaving silent
-        // inconsistency.
-        uninstallPluginByName(name);
-        try {
-            await installPluginFromSource(parsed, name, installedAt);
-        }
-        catch (err) {
-            throw new PluginInstallError(`update failed and '${name}' was removed during reinstall: ` +
-                `${err instanceof Error ? err.message : String(err)}. Reinstall it from ${meta.source}.`);
-        }
+        await reinstallAtomic(name, meta.source, () => installPluginFromSource(parsed, name, installedAt));
         return { updated: true, reason: "reinstalled from git source" };
     }
     if (!existsSync(meta.source)) {
@@ -53,13 +92,6 @@ export async function updatePluginByName(name, installedAt, force) {
             return { updated: false, reason: "CC plugin needs --force to reinstall" };
         }
     }
-    uninstallPluginByName(name);
-    try {
-        await installPluginFromPath(meta.source, name, installedAt);
-    }
-    catch (err) {
-        throw new PluginInstallError(`update failed and '${name}' was removed during reinstall: ` +
-            `${err instanceof Error ? err.message : String(err)}. Reinstall it from ${meta.source}.`);
-    }
+    await reinstallAtomic(name, meta.source, () => installPluginFromPath(meta.source, name, installedAt));
     return { updated: true, reason: "reinstalled" };
 }

package/dist/plugins/loadPluginHooks.d.ts

@@ -42,7 +42,21 @@
  * 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 { HookRegistry } from "../hooks/registry.js";
+/**
+ * Stable identity for ONE plugin-provided hook, used as the record key in
+ * `capabilityOverrides.pluginHooks` (per-hook project off-switch). Derived
+ * from content (`plugin:RawEvent:command`) rather than scan order so it
+ * survives plugin reinstalls and hooks.json reordering. Two entries that
+ * differ only by matcher collide — acceptable: toggling one toggles both,
+ * and identical commands on the same event are in practice the same hook.
+ */
+export declare function pluginHookKey(hook: {
+    plugin: string;
+    rawEvent: string;
+    command: string;
+}): string;
 /**
  * Walk installed plugins and register their command hooks. Safe to call
  * multiple times — the caller is responsible for not double-registering
@@ -55,5 +69,37 @@ import type { HookRegistry } from "../hooks/registry.js";
  * also suppresses its SessionStart injection — not just its Skill-tool
  * entries. Without this, `disabledPlugins` only filtered the skill list and
  * the plugin's hooks still fired regardless.
+ *
+ * `disabledPluginHooks` is the fine-grained per-hook switch — a list of
+ * {@link pluginHookKey} keys (folded from the project's
+ * `capabilityOverrides.pluginHooks` by readDisabledLists). A matching hook
+ * is skipped while the rest of the plugin keeps working.
+ */
+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 {
+    /** Source plugin name (bare, no @marketplace). */
+    plugin: string;
+    /** Mapped codeshell event name. */
+    event: HookEventName;
+    /** Original CC event name as written in hooks.json (for display). */
+    rawEvent: string;
+    /** The shell command the hook runs. */
+    command: string;
+    /** Optional matcher (regex) from the hooks.json group. */
+    matcher?: string;
+    /** Whether the owning plugin is currently disabled (its hooks don't fire). */
+    disabled: boolean;
+    /** Stable per-hook identity ({@link pluginHookKey}) — the record key the
+     *  UI writes to `capabilityOverrides.pluginHooks` to toggle just this hook. */
+    key: string;
+}
+/**
+ * Read-only counterpart to {@link loadPluginHooks}: scan installed plugins and
+ * RETURN their command hooks (instead of registering them), so the settings
+ * "钩子" page can show plugin-provided hooks alongside the user's hand-written
+ * ones, labelled by owner plugin. `disabledPlugins` doesn't filter the list —
+ * disabled plugins are still listed but flagged `disabled:true` (so the UI can
+ * show "由 xxx 插件提供（已禁用）"); pass it so that flag is accurate.
  */
-export declare function loadPluginHooks(registry: HookRegistry, disabledPlugins?: string[]): void;
+export declare function listPluginHooks(disabledPlugins?: string[]): PluginHookEntry[];

package/dist/plugins/loadPluginHooks.js

@@ -109,6 +109,17 @@ function pluginNameFromKey(key) {
     const at = key.lastIndexOf("@");
     return at > 0 ? key.slice(0, at) : key;
 }
+/**
+ * Stable identity for ONE plugin-provided hook, used as the record key in
+ * `capabilityOverrides.pluginHooks` (per-hook project off-switch). Derived
+ * from content (`plugin:RawEvent:command`) rather than scan order so it
+ * survives plugin reinstalls and hooks.json reordering. Two entries that
+ * differ only by matcher collide — acceptable: toggling one toggles both,
+ * and identical commands on the same event are in practice the same hook.
+ */
+export function pluginHookKey(hook) {
+    return `${hook.plugin}:${hook.rawEvent}:${hook.command}`;
+}
 /**
  * Walk installed plugins and register their command hooks. Safe to call
  * multiple times — the caller is responsible for not double-registering
@@ -121,10 +132,16 @@ function pluginNameFromKey(key) {
  * also suppresses its SessionStart injection — not just its Skill-tool
  * entries. Without this, `disabledPlugins` only filtered the skill list and
  * the plugin's hooks still fired regardless.
+ *
+ * `disabledPluginHooks` is the fine-grained per-hook switch — a list of
+ * {@link pluginHookKey} keys (folded from the project's
+ * `capabilityOverrides.pluginHooks` by readDisabledLists). A matching hook
+ * is skipped while the rest of the plugin keeps working.
  */
-export function loadPluginHooks(registry, disabledPlugins = []) {
+export function loadPluginHooks(registry, disabledPlugins = [], disabledPluginHooks = []) {
     const data = readInstalledPlugins();
     const disabledSet = new Set(disabledPlugins);
+    const disabledHookSet = new Set(disabledPluginHooks);
     for (const [key, entries] of Object.entries(data.plugins)) {
         if (disabledSet.has(pluginNameFromKey(key)))
             continue;
@@ -150,6 +167,13 @@ export function loadPluginHooks(registry, disabledPlugins = []) {
                         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;
@@ -170,3 +194,51 @@ export function loadPluginHooks(registry, disabledPlugins = []) {
         }
     }
 }
+/**
+ * Read-only counterpart to {@link loadPluginHooks}: scan installed plugins and
+ * RETURN their command hooks (instead of registering them), so the settings
+ * "钩子" page can show plugin-provided hooks alongside the user's hand-written
+ * ones, labelled by owner plugin. `disabledPlugins` doesn't filter the list —
+ * disabled plugins are still listed but flagged `disabled:true` (so the UI can
+ * show "由 xxx 插件提供（已禁用）"); pass it so that flag is accurate.
+ */
+export function listPluginHooks(disabledPlugins = []) {
+    const data = readInstalledPlugins();
+    const disabledSet = new Set(disabledPlugins);
+    const out = [];
+    for (const [key, entries] of Object.entries(data.plugins)) {
+        const plugin = pluginNameFromKey(key);
+        const disabled = disabledSet.has(plugin);
+        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)
+                    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 }),
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/plugins/marketplaceManager.d.ts

@@ -29,6 +29,13 @@ export type AddMarketplaceResult = {
  * an entry into known_marketplaces.json.
  */
 export declare function addMarketplace(name: string, source: MarketplaceSource): Promise<AddMarketplaceResult>;
+/**
+ * Refreshes a known marketplace: re-pulls its source so the cached
+ * marketplace.json reflects upstream (new plugins, version bumps). Reuses
+ * addMarketplace's same-source path (git fetch + reset). Returns an error if
+ * the marketplace isn't known.
+ */
+export declare function refreshMarketplace(name: string): Promise<AddMarketplaceResult>;
 /**
  * Removes a marketplace: deletes the cached clone and the manifest entry.
  * Returns whether anything was actually removed.

package/dist/plugins/marketplaceManager.js

@@ -11,6 +11,7 @@ import { homedir } from "node:os";
 import { gitClone, gitFetchAndReset, githubRepoToCloneUrl } from "./gitOps.js";
 import { readKnownMarketplaces, upsertKnownMarketplace, removeKnownMarketplace, } from "./knownMarketplaces.js";
 import { validateMarketplace } from "./schemas.js";
+import { assertSafePluginName } from "./installer/paths.js";
 function userHome() {
     return process.env.HOME ?? homedir();
 }
@@ -18,6 +19,11 @@ export function marketplacesRoot() {
     return join(userHome(), ".code-shell", "plugins", "marketplaces");
 }
 export function marketplaceDir(name) {
+    // Single choke point for add/remove/refresh (all derive `dir` from here and
+    // then gitClone / rmSync it). Validate `name` as one safe path segment so a
+    // `..` / separator / NUL can't escape marketplacesRoot. Normal derived names
+    // (lowercase repo tails) are unaffected; reuses the plugin segment guard.
+    assertSafePluginName(name);
     return join(marketplacesRoot(), name);
 }
 const CC_MANIFEST_REL = [".claude-plugin", "marketplace.json"];
@@ -118,6 +124,20 @@ export async function addMarketplace(name, source) {
     upsertKnownMarketplace(name, entry);
     return { ok: true, name, marketplace: v.value, replaced: Boolean(existing) };
 }
+/**
+ * Refreshes a known marketplace: re-pulls its source so the cached
+ * marketplace.json reflects upstream (new plugins, version bumps). Reuses
+ * addMarketplace's same-source path (git fetch + reset). Returns an error if
+ * the marketplace isn't known.
+ */
+export async function refreshMarketplace(name) {
+    const known = readKnownMarketplaces();
+    const entry = known[name];
+    if (!entry) {
+        return { ok: false, error: `Unknown marketplace: ${name}` };
+    }
+    return addMarketplace(name, entry.source);
+}
 /**
  * Removes a marketplace: deletes the cached clone and the manifest entry.
  * Returns whether anything was actually removed.