@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/plugins/pluginContent.js

@@ -5,17 +5,46 @@
  * actually installs (feedback#15). Read-only; reuses the same parsers the
  * loaders use so the inventory can't drift from what actually loads.
  */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { parseFrontmatter } from "../skills/frontmatter.js";
 import { listPluginHooks } from "./loadPluginHooks.js";
-import { mergePluginMcpServers } from "./installer/loadPluginMcp.js";
-function listMdNames(dir) {
-    if (!existsSync(dir))
+import { reviewPluginHooks } from "./pluginHookApproval.js";
+import { readPluginMcp } from "./installer/loadPluginMcp.js";
+import { CANONICAL_PLUGIN_MANIFEST_FILE, CanonicalPluginManifest, } from "./installer/types.js";
+import { pluginAutomationTemplateRevision } from "./pluginCatalog.js";
+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 listMdNames(installPath, dirName) {
+    const dir = resolveContainedPath(installPath, join(installPath, dirName));
+    if (!dir)
         return [];
     try {
         return readdirSync(dir)
-            .filter((f) => f.endsWith(".md"))
+            .filter((file) => {
+            if (!file.endsWith(".md"))
+                return false;
+            const target = resolveContainedPath(dir, join(dir, file));
+            if (!target)
+                return false;
+            try {
+                return statSync(target).isFile();
+            }
+            catch {
+                return false;
+            }
+        })
             .map((f) => f.replace(/\.md$/, ""))
             .sort();
     }
@@ -24,15 +53,18 @@ function listMdNames(dir) {
     }
 }
 function listSkills(installPath) {
-    const dir = join(installPath, "skills");
-    if (!existsSync(dir))
+    const dir = resolveContainedPath(installPath, join(installPath, "skills"));
+    if (!dir)
         return [];
     const out = [];
     try {
         for (const entry of readdirSync(dir).sort()) {
-            const skillMd = join(dir, entry, "SKILL.md");
             try {
-                if (!statSync(join(dir, entry)).isDirectory() || !existsSync(skillMd))
+                const skillDir = resolveContainedPath(dir, join(dir, entry));
+                if (!skillDir || !statSync(skillDir).isDirectory())
+                    continue;
+                const skillMd = resolveContainedPath(skillDir, join(skillDir, "SKILL.md"));
+                if (!skillMd || !statSync(skillMd).isFile())
                     continue;
                 const { frontmatter } = parseFrontmatter(readFileSync(skillMd, "utf-8"));
                 const desc = typeof frontmatter.description === "string" ? frontmatter.description : undefined;
@@ -54,30 +86,55 @@ function listSkills(installPath) {
  * 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 function describePluginContent(pluginName, installPath) {
+export function describePluginContent(pluginName, installPath, installKey) {
     const mcpPrefix = `${pluginName}:`;
-    let mcpServers = [];
-    try {
-        mcpServers = Object.keys(mergePluginMcpServers({}))
-            .filter((k) => k.startsWith(mcpPrefix))
-            .map((k) => k.slice(mcpPrefix.length))
-            .sort();
-    }
-    catch {
-        mcpServers = [];
-    }
-    let hooks = [];
-    try {
-        hooks = listPluginHooks().filter((h) => h.plugin === pluginName);
-    }
-    catch {
-        hooks = [];
-    }
+    const mcpServers = (() => {
+        try {
+            return Object.keys(readPluginMcp(installPath, pluginName))
+                .filter((k) => k.startsWith(mcpPrefix))
+                .map((k) => k.slice(mcpPrefix.length))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    })();
+    const hooks = (() => {
+        try {
+            return listPluginHooks().filter((h) => h.plugin === pluginName && (installKey === undefined || h.installKey === installKey));
+        }
+        catch {
+            return [];
+        }
+    })();
+    const hookReview = (() => {
+        if (!installKey)
+            return undefined;
+        try {
+            return reviewPluginHooks(installKey)[0];
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const manifest = (() => {
+        try {
+            return CanonicalPluginManifest.parse(JSON.parse(readFileSync(join(installPath, CANONICAL_PLUGIN_MANIFEST_FILE), "utf-8")));
+        }
+        catch {
+            return null;
+        }
+    })();
     return {
         skills: listSkills(installPath),
-        commands: listMdNames(join(installPath, "commands")),
-        agents: listMdNames(join(installPath, "agents")),
+        commands: listMdNames(installPath, "commands"),
+        agents: listMdNames(installPath, "agents"),
         hooks,
+        ...(hookReview ? { hookReview } : {}),
         mcpServers,
+        automationTemplates: (manifest?.automations?.templates ?? []).map((template) => ({
+            ...template,
+            revision: pluginAutomationTemplateRevision(installKey ?? pluginName, template),
+        })),
     };
 }

package/dist/plugins/pluginHookApproval.d.ts

@@ -0,0 +1,30 @@
+import { type PluginHookApprovalState } from "./pluginHookIntegrity.js";
+import type { StoredPluginHookReview } from "./types.js";
+export interface PluginHookApprovalResult {
+    installKey: string;
+    plugin: string;
+    status: PluginHookApprovalState;
+    changed: boolean;
+}
+export interface PluginHookReviewDiffItem {
+    change: "added" | "removed" | "changed" | "unchanged";
+    current?: StoredPluginHookReview;
+    previous?: StoredPluginHookReview;
+}
+export interface PluginHookReview {
+    installKey: string;
+    plugin: string;
+    status: PluginHookApprovalState;
+    baselineAvailable: boolean;
+    items: PluginHookReviewDiffItem[];
+    error?: string;
+}
+/** Review current hooks against the last explicitly approved per-command snapshot. */
+export declare function reviewPluginHooks(target: string): PluginHookReview[];
+/** Approve the exact install-time digest; changed-on-disk hooks cannot be blessed. */
+export declare function approvePluginHooks(target: string): PluginHookApprovalResult[];
+/**
+ * Revoke hook execution. Legacy entries are first migrated to a recorded
+ * digest so revocation fails closed instead of falling back to legacy trust.
+ */
+export declare function revokePluginHooks(target: string): PluginHookApprovalResult[];

package/dist/plugins/pluginHookApproval.js

@@ -0,0 +1,160 @@
+import { readInstalledPlugins, writeInstalledPlugins } from "./installedPlugins.js";
+import { inspectPluginHooks, pluginHookReviewSnapshot, pluginHookApprovalState, } from "./pluginHookIntegrity.js";
+function pluginNameFromKey(key) {
+    const at = key.lastIndexOf("@");
+    return at > 0 ? key.slice(0, at) : key;
+}
+function matchingInstallKeys(data, target) {
+    if (!target.trim())
+        throw new Error("plugin hook approval requires a plugin name or install key");
+    if (data.plugins[target])
+        return [target];
+    const matches = Object.keys(data.plugins).filter((key) => pluginNameFromKey(key) === target);
+    if (matches.length === 0)
+        throw new Error(`plugin "${target}" is not installed`);
+    if (matches.length > 1) {
+        throw new Error(`plugin "${target}" has multiple installs; use one of: ${matches.join(", ")}`);
+    }
+    return matches;
+}
+function result(installKey, entry, changed, snapshot) {
+    return {
+        installKey,
+        plugin: pluginNameFromKey(installKey),
+        status: pluginHookApprovalState(entry, snapshot),
+        changed,
+    };
+}
+function sameReviewHook(a, b) {
+    return (a.rawEvent === b.rawEvent &&
+        a.matcher === b.matcher &&
+        a.commandDigest === b.commandDigest &&
+        a.async === b.async &&
+        a.timeoutMs === b.timeoutMs);
+}
+function diffHookReview(current, previous) {
+    if (previous === undefined)
+        return current.map((hook) => ({ change: "added", current: hook }));
+    const unused = new Set(previous.map((_, index) => index));
+    const items = [];
+    for (const hook of current) {
+        const exact = [...unused].find((index) => sameReviewHook(hook, previous[index]));
+        if (exact !== undefined) {
+            unused.delete(exact);
+            items.push({ change: "unchanged", current: hook, previous: previous[exact] });
+            continue;
+        }
+        let changed = [...unused].find((index) => {
+            const old = previous[index];
+            return (old.rawEvent === hook.rawEvent &&
+                (old.commandDigest === hook.commandDigest || old.matcher === hook.matcher));
+        });
+        // If both command and matcher changed, pair the remaining command at the
+        // same event when that match is unambiguous instead of presenting a noisy
+        // remove+add pair.
+        if (changed === undefined) {
+            const sameEvent = [...unused].filter((index) => previous[index].rawEvent === hook.rawEvent);
+            if (sameEvent.length === 1)
+                changed = sameEvent[0];
+        }
+        if (changed !== undefined) {
+            unused.delete(changed);
+            items.push({ change: "changed", current: hook, previous: previous[changed] });
+            continue;
+        }
+        items.push({ change: "added", current: hook });
+    }
+    for (const index of unused)
+        items.push({ change: "removed", previous: previous[index] });
+    return items;
+}
+function review(installKey, entry) {
+    const snapshot = inspectPluginHooks(entry.installPath);
+    return {
+        installKey,
+        plugin: pluginNameFromKey(installKey),
+        status: pluginHookApprovalState(entry, snapshot),
+        baselineAvailable: entry.approvedHookSnapshot !== undefined,
+        items: diffHookReview(pluginHookReviewSnapshot(snapshot), entry.approvedHookSnapshot),
+        ...(snapshot.error ? { error: snapshot.error } : {}),
+    };
+}
+/** Review current hooks against the last explicitly approved per-command snapshot. */
+export function reviewPluginHooks(target) {
+    const data = readInstalledPlugins();
+    return matchingInstallKeys(data, target).flatMap((installKey) => (data.plugins[installKey] ?? []).map((entry) => review(installKey, entry)));
+}
+/** Approve the exact install-time digest; changed-on-disk hooks cannot be blessed. */
+export function approvePluginHooks(target) {
+    const data = readInstalledPlugins();
+    const keys = matchingInstallKeys(data, target);
+    const out = [];
+    let writeNeeded = false;
+    for (const installKey of keys) {
+        for (const entry of data.plugins[installKey] ?? []) {
+            let entryChanged = false;
+            const snapshot = inspectPluginHooks(entry.installPath);
+            if (snapshot.state === "invalid") {
+                throw new Error(`plugin "${installKey}" hooks definition is invalid and cannot be approved: ${snapshot.error ?? "unknown error"}`);
+            }
+            if (entry.hookDigest && snapshot.digest !== entry.hookDigest) {
+                throw new Error(`plugin "${installKey}" hooks changed after install; reinstall or update before approving`);
+            }
+            if (!entry.hookDigest) {
+                entry.hookDigest = snapshot.digest;
+                entryChanged = true;
+                writeNeeded = true;
+            }
+            if (entry.approvedHookDigest !== entry.hookDigest) {
+                entry.approvedHookDigest = entry.hookDigest;
+                entryChanged = true;
+                writeNeeded = true;
+            }
+            const nextReview = pluginHookReviewSnapshot(snapshot);
+            if (JSON.stringify(entry.approvedHookSnapshot) !== JSON.stringify(nextReview)) {
+                entry.approvedHookSnapshot = nextReview;
+                entryChanged = true;
+                writeNeeded = true;
+            }
+            out.push(result(installKey, entry, entryChanged, snapshot));
+        }
+    }
+    if (writeNeeded)
+        writeInstalledPlugins(data);
+    return out;
+}
+/**
+ * Revoke hook execution. Legacy entries are first migrated to a recorded
+ * digest so revocation fails closed instead of falling back to legacy trust.
+ */
+export function revokePluginHooks(target) {
+    const data = readInstalledPlugins();
+    const keys = matchingInstallKeys(data, target);
+    const out = [];
+    let writeNeeded = false;
+    for (const installKey of keys) {
+        for (const entry of data.plugins[installKey] ?? []) {
+            let entryChanged = false;
+            const snapshot = inspectPluginHooks(entry.installPath);
+            if (!entry.hookDigest) {
+                entry.hookDigest = snapshot.digest;
+                entryChanged = true;
+            }
+            if (snapshot.hasExecutableHooks || snapshot.state === "invalid") {
+                if (entry.approvedHookDigest !== undefined) {
+                    delete entry.approvedHookDigest;
+                    entryChanged = true;
+                }
+            }
+            else if (entry.approvedHookDigest !== entry.hookDigest) {
+                entry.approvedHookDigest = entry.hookDigest;
+                entryChanged = true;
+            }
+            writeNeeded ||= entryChanged;
+            out.push(result(installKey, entry, entryChanged, snapshot));
+        }
+    }
+    if (writeNeeded)
+        writeInstalledPlugins(data);
+    return out;
+}

package/dist/plugins/pluginHookIntegrity.d.ts

@@ -0,0 +1,69 @@
+import type { PluginInstallEntry, StoredPluginHookReview } from "./types.js";
+/** Hard limits for one canonical plugin hook definition. */
+export declare const MAX_PLUGIN_HOOK_FILE_BYTES = 1048576;
+export declare const MAX_PLUGIN_HOOK_EVENTS = 32;
+export declare const MAX_PLUGIN_HOOK_GROUPS = 128;
+export declare const MAX_PLUGIN_HOOK_COMMANDS = 256;
+export declare const MAX_PLUGIN_HOOK_EVENT_NAME_LENGTH = 128;
+export declare const MAX_PLUGIN_HOOK_COMMAND_LENGTH = 32768;
+export declare const MAX_PLUGIN_HOOK_MATCHER_LENGTH = 4096;
+export declare const MAX_PLUGIN_HOOK_TIMEOUT_MS = 600000;
+export declare const MAX_PLUGIN_HOOK_REVIEW_COMMAND_LENGTH = 4096;
+export declare const SUPPORTED_PLUGIN_HOOK_EVENTS: readonly ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PreCompact", "Notification", "Stop", "SubagentStop"];
+export type SupportedPluginHookEvent = (typeof SUPPORTED_PLUGIN_HOOK_EVENTS)[number];
+export interface ParsedPluginCommandHook {
+    command: string;
+    async?: boolean;
+    timeoutMs?: number;
+}
+export interface ParsedPluginHookGroup {
+    matcher?: string;
+    hooks: ParsedPluginCommandHook[];
+}
+export interface ParsedPluginHooksDefinition {
+    hooks: Partial<Record<SupportedPluginHookEvent, ParsedPluginHookGroup[]>>;
+}
+export interface PluginHooksSnapshot {
+    state: "absent" | "valid" | "invalid";
+    digest: string;
+    definition: ParsedPluginHooksDefinition | null;
+    hasExecutableHooks: boolean;
+    error?: string;
+}
+export type PluginHookIntegrity = "verified" | "changed" | "legacy";
+export type PluginHookApprovalState = "approved" | "pending" | "changed" | "legacy" | "none";
+/**
+ * Securely read and parse the one canonical hook file. All digest, approval,
+ * listing, and runtime decisions consume this snapshot so malformed or
+ * replaced files cannot be interpreted differently by separate code paths.
+ */
+export declare function inspectPluginHooks(installPath: string): PluginHooksSnapshot;
+/**
+ * Digest the exact canonical hooks file after it passes the bounded parser.
+ * Valid and absent definitions preserve the existing v1 digest contract;
+ * every invalid definition shares a fail-closed sentinel digest.
+ */
+export declare function pluginHooksDigest(installPath: string): string;
+/** Whether the bounded canonical definition currently contains an executable command hook. */
+export declare function pluginHasExecutableHooks(installPath: string): boolean;
+/** Build bounded, non-executable review metadata from one validated snapshot. */
+export declare function pluginHookReviewSnapshot(snapshot: PluginHooksSnapshot): StoredPluginHookReview[];
+/**
+ * Older installed_plugins.json entries predate hook digests and remain
+ * compatible as `legacy`. New entries fail closed when their effective hook
+ * file no longer matches the bytes approved by install/update.
+ */
+export declare function verifyPluginHookIntegrity(entry: PluginInstallEntry, snapshot?: PluginHooksSnapshot): PluginHookIntegrity;
+/**
+ * Runtime trust state for one installed plugin. Legacy entries stay compatible;
+ * new entries with executable hooks remain pending until the approved digest
+ * matches the install-time digest. Invalid definitions always fail closed as
+ * hook-free regardless of legacy state.
+ */
+export declare function pluginHookApprovalState(entry: PluginInstallEntry, snapshot?: PluginHooksSnapshot): PluginHookApprovalState;
+/**
+ * Integrity fields written at install/update. Hook-free packages approve the
+ * absent-hooks digest automatically; executable hooks require explicit trust.
+ * A previously approved identical digest remains approved across an update.
+ */
+export declare function pluginHookInstallRecord(installPath: string, previousEntries?: PluginInstallEntry[]): Pick<PluginInstallEntry, "hookDigest" | "approvedHookDigest" | "approvedHookSnapshot">;