@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/plugins/installer/parseSource.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { valid as validSemver, validRange as validSemverRange } from "semver";
 import { githubRepoToCloneUrl } from "../gitOps.js";
 import { PluginInstallError } from "./types.js";
 /** SSH shorthand `git@host:org/repo.git` — has a `:` after the `git@host` part. */
@@ -9,6 +10,51 @@ function isRemote(s) {
     const lower = s.toLowerCase();
     return lower.startsWith("github:") || /^[a-z][a-z0-9+.-]*:\/\//i.test(s) || isSshUrl(s);
 }
+const MAX_NPM_PACKAGE_NAME = 214;
+const MAX_NPM_SELECTOR = 128;
+const NPM_PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const NPM_DIST_TAG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Parse the intentionally small npm Phase-A source grammar. */
+export function parseNpmPluginSource(input) {
+    if (!input.startsWith("npm:")) {
+        throw new PluginInstallError("npm plugin source must start with npm:");
+    }
+    const spec = input.slice("npm:".length);
+    let packageName = spec;
+    let selector = "latest";
+    // Scoped names contain their own leading '@'. A selector separator is only
+    // an '@' after the slash; unscoped names use their last '@'.
+    const selectorAt = spec.startsWith("@")
+        ? (() => {
+            const slash = spec.indexOf("/");
+            return slash < 0 ? -1 : spec.lastIndexOf("@") > slash ? spec.lastIndexOf("@") : -1;
+        })()
+        : spec.lastIndexOf("@");
+    if (selectorAt >= 0) {
+        packageName = spec.slice(0, selectorAt);
+        selector = spec.slice(selectorAt + 1);
+    }
+    if (packageName.length === 0 ||
+        packageName.length > MAX_NPM_PACKAGE_NAME ||
+        !NPM_PACKAGE_NAME.test(packageName)) {
+        throw new PluginInstallError(`invalid public npm package name: ${packageName || "(empty)"}`);
+    }
+    const exact = validSemver(selector);
+    if (selector.length === 0 ||
+        selector.length > MAX_NPM_SELECTOR ||
+        (!exact && (!NPM_DIST_TAG.test(selector) || validSemverRange(selector) !== null))) {
+        throw new PluginInstallError(`npm selector must be an exact version or dist-tag (ranges are not supported): ${selector || "(empty)"}`);
+    }
+    const inferredName = packageName.split("/").pop() ?? packageName;
+    return {
+        kind: "npm",
+        packageName,
+        selector: exact ?? selector,
+        selectorKind: exact ? "exact" : "tag",
+        raw: input,
+        inferredName,
+    };
+}
 function unsafeTransport(input) {
     const scheme = input.match(/^([a-z][a-z0-9+.-]*):\/\//i)?.[1]?.toLowerCase();
     if (!scheme)
@@ -37,6 +83,8 @@ function lastSegment(p) {
     return p.split("/").filter(Boolean).pop() ?? p;
 }
 export function parseSource(input, options = {}) {
+    if (input.startsWith("npm:"))
+        return parseNpmPluginSource(input);
     if (!isRemote(input)) {
         return { kind: "local", path: resolve(input) };
     }

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

@@ -0,0 +1,101 @@
+import { type InstallLocalOptions, type LocalPluginSourceInput } from "./installFromArchive.js";
+import { PluginInstallError } from "./types.js";
+export type LocalPluginPreviewWarningKind = "executable-hooks" | "stdio-mcp" | "network-mcp" | "automation-templates" | "external-links" | "media";
+export interface LocalPluginPreviewWarning {
+    count: number;
+    kind: LocalPluginPreviewWarningKind;
+    severity: "warning" | "info";
+}
+export interface LocalPluginHookPreview {
+    command: string;
+    commandTruncated: boolean;
+    event: string;
+    matcher?: string;
+    matcherTruncated?: boolean;
+}
+export interface LocalPluginMcpPreview {
+    command?: string;
+    commandTruncated?: boolean;
+    name: string;
+    transport: "stdio" | "sse" | "streamable-http";
+    url?: string;
+    urlTruncated?: boolean;
+}
+export interface LocalPluginAutomationTemplatePreview {
+    description?: string;
+    id: string;
+    permissionLevel: "read-only" | "workspace-write" | "full";
+    prompt: string;
+    promptTruncated: boolean;
+    schedule: string;
+    timezone?: string;
+    title: {
+        default: string;
+        en?: string;
+        "zh-CN"?: string;
+    };
+    workspace: "current" | "none";
+}
+export interface LocalPluginMediaPreview {
+    composerIcon?: string;
+    logo?: string;
+    logoDark?: string;
+    screenshots: string[];
+}
+export interface LocalPluginInterfacePreview {
+    brandColor?: string;
+    capabilities: string[];
+    category?: string;
+    defaultPrompt: string[];
+    developerName?: string;
+    displayName?: string;
+    externalLinks: Array<{
+        kind: "website" | "privacy" | "terms";
+        url: string;
+    }>;
+    longDescription?: string;
+    media: LocalPluginMediaPreview;
+    shortDescription?: string;
+}
+export interface LocalPluginPreview {
+    agents: string[];
+    alreadyInstalled: boolean;
+    commands: string[];
+    format: "cc" | "codex";
+    hooks: LocalPluginHookPreview[];
+    installedVersion?: string;
+    interface: LocalPluginInterfacePreview;
+    mcpServers: LocalPluginMcpPreview[];
+    name: string;
+    automationTemplates: LocalPluginAutomationTemplatePreview[];
+    reviewToken: string;
+    skills: Array<{
+        description?: string;
+        name: string;
+    }>;
+    source: {
+        kind: "dir" | "zip";
+        label: string;
+    };
+    version?: string;
+    warnings: LocalPluginPreviewWarning[];
+}
+export declare class LocalPluginReviewChangedError extends PluginInstallError {
+    constructor();
+}
+/**
+ * Inspect a local directory/zip through the exact runtime projection used by
+ * install. No plugin root or installed registry is mutated.
+ */
+export declare function previewLocalPlugin(input: LocalPluginSourceInput): Promise<LocalPluginPreview>;
+/**
+ * Install exactly the source tree represented by a review token.
+ *
+ * A private, symlink-free snapshot closes the gap between re-review and
+ * installation: after its projection matches the token, the installer reads
+ * only that snapshot, never the caller-owned directory or archive again.
+ */
+export declare function installReviewedLocalPlugin(input: LocalPluginSourceInput, expectedReviewToken: string, installedAt: string, options?: InstallLocalOptions): Promise<{
+    dir: string;
+    name: string;
+}>;

package/dist/plugins/installer/preview.js

@@ -0,0 +1,336 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, lstat, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { parseFrontmatter } from "../../skills/frontmatter.js";
+import { readInstalledPlugins } from "../installedPlugins.js";
+import { inspectPluginHooks } from "../pluginHookIntegrity.js";
+import { deriveName, installLocalPlugin, normalizePluginName, withLocalPluginSourceRoot, } from "./installFromArchive.js";
+import { readPluginMcp } from "./loadPluginMcp.js";
+import { pluginInstallDir } from "./paths.js";
+import { assertBoundedPluginSource, projectPluginSource } from "./projectPluginSource.js";
+import { PluginInstallError } from "./types.js";
+const MAX_PREVIEW_ITEMS = 256;
+const MAX_PREVIEW_SKILL_BYTES = 512 * 1024;
+const MAX_PREVIEW_TEXT = 240;
+const MAX_PREVIEW_DESCRIPTION = 300;
+const MAX_PREVIEW_MCP_BYTES = 1024 * 1024;
+export class LocalPluginReviewChangedError extends PluginInstallError {
+    constructor() {
+        super("Plugin source changed after review. Review it again before installing.");
+        this.name = "LocalPluginReviewChangedError";
+    }
+}
+function truncated(value, max = MAX_PREVIEW_TEXT) {
+    if (value.length <= max)
+        return { text: value, truncated: false };
+    return { text: `${value.slice(0, Math.max(0, max - 1))}…`, truncated: true };
+}
+function ensureItemBound(kind, count) {
+    if (count > MAX_PREVIEW_ITEMS) {
+        throw new PluginInstallError(`plugin declares more than ${MAX_PREVIEW_ITEMS} ${kind}; preview refused`);
+    }
+}
+async function listMarkdownNames(root, recursive) {
+    if (!existsSync(root))
+        return [];
+    const names = [];
+    const walk = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory() && recursive) {
+                await walk(path);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            names.push(relative(root, path).replaceAll(sep, "/").replace(/\.md$/, ""));
+            ensureItemBound("entries", names.length);
+        }
+    };
+    await walk(root);
+    return names.sort();
+}
+async function listSkills(root) {
+    if (!existsSync(root))
+        return [];
+    const output = [];
+    for (const entry of (await readdir(root, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const skillFile = join(root, entry.name, "SKILL.md");
+        if (!existsSync(skillFile) || !(await stat(skillFile)).isFile())
+            continue;
+        const info = await stat(skillFile);
+        if (info.size > MAX_PREVIEW_SKILL_BYTES) {
+            throw new PluginInstallError(`skills/${entry.name}/SKILL.md exceeds ${MAX_PREVIEW_SKILL_BYTES} bytes`);
+        }
+        const { frontmatter } = parseFrontmatter(await readFile(skillFile, "utf-8"));
+        const description = typeof frontmatter.description === "string"
+            ? truncated(frontmatter.description, MAX_PREVIEW_DESCRIPTION).text
+            : undefined;
+        output.push({ name: entry.name, ...(description ? { description } : {}) });
+        ensureItemBound("skills", output.length);
+    }
+    return output;
+}
+function listHooks(projectionRoot) {
+    const snapshot = inspectPluginHooks(projectionRoot);
+    if (snapshot.state === "invalid") {
+        throw new PluginInstallError(`invalid plugin hooks: ${snapshot.error ?? "unknown error"}`);
+    }
+    const hooks = [];
+    for (const [event, groups] of Object.entries(snapshot.definition?.hooks ?? {})) {
+        for (const group of groups ?? []) {
+            const matcher = group.matcher ? truncated(group.matcher) : null;
+            for (const hook of group.hooks) {
+                const command = truncated(hook.command);
+                hooks.push({
+                    event,
+                    command: command.text,
+                    commandTruncated: command.truncated,
+                    ...(matcher
+                        ? {
+                            matcher: matcher.text,
+                            matcherTruncated: matcher.truncated,
+                        }
+                        : {}),
+                });
+                ensureItemBound("hooks", hooks.length);
+            }
+        }
+    }
+    return hooks;
+}
+async function assertCcMcpPreviewComplete(projectionRoot, normalizedCount) {
+    const path = join(projectionRoot, ".mcp.json");
+    if (!existsSync(path))
+        return;
+    const info = await lstat(path);
+    if (info.isSymbolicLink() || !info.isFile() || info.size > MAX_PREVIEW_MCP_BYTES) {
+        throw new PluginInstallError("plugin .mcp.json is not a bounded regular file");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(path, "utf-8"));
+    }
+    catch (error) {
+        throw new PluginInstallError(`invalid plugin .mcp.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new PluginInstallError("plugin .mcp.json root must be an object");
+    }
+    const raw = "mcpServers" in parsed ? parsed.mcpServers : parsed;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new PluginInstallError("plugin .mcp.json mcpServers must be an object");
+    }
+    if (Object.keys(raw).length !== normalizedCount) {
+        throw new PluginInstallError("plugin .mcp.json contains invalid MCP server declarations");
+    }
+}
+async function listMcp(projectionRoot, pluginName, format) {
+    const configs = readPluginMcp(projectionRoot, pluginName);
+    if (format === "cc") {
+        await assertCcMcpPreviewComplete(projectionRoot, Object.keys(configs).length);
+    }
+    const output = Object.entries(configs)
+        .map(([key, config]) => {
+        const transport = config.transport ??
+            (config.url && !config.command ? "streamable-http" : "stdio");
+        const command = config.command ? truncated(config.command) : null;
+        const url = config.url ? truncated(config.url) : null;
+        return {
+            name: key.startsWith(`${pluginName}:`) ? key.slice(pluginName.length + 1) : key,
+            transport: transport === "sse" || transport === "streamable-http" ? transport : "stdio",
+            ...(command ? { command: command.text, commandTruncated: command.truncated } : {}),
+            ...(url ? { url: url.text, urlTruncated: url.truncated } : {}),
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    ensureItemBound("MCP servers", output.length);
+    return output;
+}
+function interfacePreview(value) {
+    const externalLinks = [];
+    if (value?.websiteURL)
+        externalLinks.push({ kind: "website", url: value.websiteURL });
+    if (value?.privacyPolicyURL) {
+        externalLinks.push({ kind: "privacy", url: value.privacyPolicyURL });
+    }
+    if (value?.termsOfServiceURL) {
+        externalLinks.push({ kind: "terms", url: value.termsOfServiceURL });
+    }
+    return {
+        capabilities: [...(value?.capabilities ?? [])],
+        defaultPrompt: [...(value?.defaultPrompt ?? [])],
+        externalLinks,
+        media: {
+            ...(value?.composerIcon ? { composerIcon: value.composerIcon } : {}),
+            ...(value?.logo ? { logo: value.logo } : {}),
+            ...(value?.logoDark ? { logoDark: value.logoDark } : {}),
+            screenshots: [...(value?.screenshots ?? [])],
+        },
+        ...(value?.displayName ? { displayName: value.displayName } : {}),
+        ...(value?.shortDescription ? { shortDescription: value.shortDescription } : {}),
+        ...(value?.longDescription ? { longDescription: value.longDescription } : {}),
+        ...(value?.developerName ? { developerName: value.developerName } : {}),
+        ...(value?.category ? { category: value.category } : {}),
+        ...(value?.brandColor ? { brandColor: value.brandColor } : {}),
+    };
+}
+function warningsFor(hooks, mcpServers, automationTemplates, metadata) {
+    const warnings = [];
+    if (hooks.length > 0) {
+        warnings.push({ kind: "executable-hooks", severity: "warning", count: hooks.length });
+    }
+    const stdio = mcpServers.filter((server) => server.transport === "stdio").length;
+    const network = mcpServers.length - stdio;
+    if (stdio > 0)
+        warnings.push({ kind: "stdio-mcp", severity: "warning", count: stdio });
+    if (network > 0)
+        warnings.push({ kind: "network-mcp", severity: "warning", count: network });
+    if (automationTemplates.length > 0) {
+        warnings.push({
+            kind: "automation-templates",
+            severity: "warning",
+            count: automationTemplates.length,
+        });
+    }
+    if (metadata.externalLinks.length > 0) {
+        warnings.push({
+            kind: "external-links",
+            severity: "info",
+            count: metadata.externalLinks.length,
+        });
+    }
+    const mediaCount = Number(Boolean(metadata.media.composerIcon)) +
+        Number(Boolean(metadata.media.logo)) +
+        Number(Boolean(metadata.media.logoDark)) +
+        metadata.media.screenshots.length;
+    if (mediaCount > 0) {
+        warnings.push({ kind: "media", severity: "info", count: mediaCount });
+    }
+    return warnings;
+}
+async function digestProjection(root) {
+    const hash = createHash("sha256").update("codeshell-local-plugin-review-v1").update("\0");
+    const canonicalRoot = await realpath(root);
+    const walk = async (directory) => {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(directory, entry.name);
+            const rel = relative(canonicalRoot, path).replaceAll(sep, "/");
+            // rewritePluginVars intentionally stamps this explanatory breadcrumb
+            // with the current time. It does not affect runtime capabilities and
+            // must not make two reviews of unchanged source produce different tokens.
+            if (rel === ".code-shell-installed.json")
+                continue;
+            hash.update(rel).update("\0");
+            const info = await lstat(path);
+            if (info.isDirectory()) {
+                hash.update("dir\0");
+                await walk(path);
+            }
+            else if (info.isSymbolicLink()) {
+                const target = await readlink(path);
+                hash.update("link\0").update(target).update("\0");
+            }
+            else if (info.isFile()) {
+                hash
+                    .update("file\0")
+                    .update(await readFile(path))
+                    .update("\0");
+            }
+        }
+    };
+    await walk(canonicalRoot);
+    return hash.digest("hex");
+}
+function installedVersion(name) {
+    const entries = readInstalledPlugins().plugins[`${name}@local`] ?? [];
+    return entries.at(-1)?.version;
+}
+/**
+ * Inspect a local directory/zip through the exact runtime projection used by
+ * install. No plugin root or installed registry is mutated.
+ */
+export async function previewLocalPlugin(input) {
+    return withLocalPluginSourceRoot(input, async (sourceRoot) => {
+        const name = normalizePluginName(await deriveName(sourceRoot));
+        const projectionRoot = await mkdtemp(join(tmpdir(), "cs-plugin-preview-"));
+        try {
+            const projected = await projectPluginSource(sourceRoot, projectionRoot, name);
+            const skills = await listSkills(join(projectionRoot, "skills"));
+            const commands = await listMarkdownNames(join(projectionRoot, "commands"), false);
+            const agents = await listMarkdownNames(join(projectionRoot, "agents"), true);
+            const hooks = listHooks(projectionRoot);
+            const mcpServers = await listMcp(projectionRoot, name, projected.format);
+            const automationTemplates = (projected.canonicalManifest.automations?.templates ?? []).map((template) => {
+                const prompt = truncated(template.prompt, 500);
+                return {
+                    id: template.id,
+                    title: template.title,
+                    ...(template.description ? { description: template.description } : {}),
+                    schedule: template.schedule,
+                    prompt: prompt.text,
+                    promptTruncated: prompt.truncated,
+                    ...(template.timezone ? { timezone: template.timezone } : {}),
+                    permissionLevel: template.permissionLevel,
+                    workspace: template.workspace,
+                };
+            });
+            const metadata = interfacePreview(projected.canonicalManifest.interface);
+            const reviewToken = await digestProjection(projectionRoot);
+            const exists = existsSync(pluginInstallDir(name));
+            const currentInstalledVersion = exists ? installedVersion(name) : undefined;
+            return {
+                name,
+                format: projected.format,
+                ...(projected.version ? { version: projected.version } : {}),
+                source: { kind: input.kind, label: basename(input.path) },
+                alreadyInstalled: exists,
+                ...(currentInstalledVersion ? { installedVersion: currentInstalledVersion } : {}),
+                reviewToken,
+                skills,
+                commands,
+                agents,
+                hooks,
+                mcpServers,
+                automationTemplates,
+                interface: metadata,
+                warnings: warningsFor(hooks, mcpServers, automationTemplates, metadata),
+            };
+        }
+        finally {
+            await rm(projectionRoot, { recursive: true, force: true });
+        }
+    });
+}
+/**
+ * Install exactly the source tree represented by a review token.
+ *
+ * A private, symlink-free snapshot closes the gap between re-review and
+ * installation: after its projection matches the token, the installer reads
+ * only that snapshot, never the caller-owned directory or archive again.
+ */
+export async function installReviewedLocalPlugin(input, expectedReviewToken, installedAt, options) {
+    if (!/^[a-f0-9]{64}$/.test(expectedReviewToken)) {
+        throw new PluginInstallError("local plugin review token is invalid");
+    }
+    return withLocalPluginSourceRoot(input, async (sourceRoot) => {
+        const snapshotContainer = await mkdtemp(join(tmpdir(), "cs-plugin-reviewed-"));
+        const snapshotRoot = join(snapshotContainer, "source");
+        try {
+            await assertBoundedPluginSource(sourceRoot);
+            await cp(sourceRoot, snapshotRoot, { recursive: true, errorOnExist: true });
+            const snapshotPreview = await previewLocalPlugin({ kind: "dir", path: snapshotRoot });
+            if (snapshotPreview.reviewToken !== expectedReviewToken) {
+                throw new LocalPluginReviewChangedError();
+            }
+            return await installLocalPlugin({ kind: "dir", path: snapshotRoot }, installedAt, snapshotPreview.name, options);
+        }
+        finally {
+            await rm(snapshotContainer, { recursive: true, force: true });
+        }
+    });
+}

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

@@ -0,0 +1,14 @@
+import { type CanonicalPluginManifest as CanonicalPluginManifestData } from "./types.js";
+export interface ProjectedPluginSource {
+    canonicalManifest: CanonicalPluginManifestData;
+    format: "cc" | "codex";
+    version?: string;
+}
+/** Bound local directory input before copying or parsing author-controlled files. */
+export declare function assertBoundedPluginSource(sourceDir: string): Promise<void>;
+/**
+ * Build the same CodeShell-native projection used by installation, without
+ * touching the plugin root or installed registry. The destination must be a
+ * private temporary/staging directory owned by the caller.
+ */
+export declare function projectPluginSource(sourceDir: string, destinationRoot: string, name: string): Promise<ProjectedPluginSource>;

package/dist/plugins/installer/projectPluginSource.js

@@ -0,0 +1,140 @@
+import { existsSync } from "node:fs";
+import { cp, lstat, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { rewritePluginVars } from "../varRewrite.js";
+import { convertCodexAgentsDirectory } from "./codex/convertAgents.js";
+import { copyCodexCommands } from "./codex/convertCommands.js";
+import { copyCodexHooks } from "./codex/convertHooks.js";
+import { resolveCodexMcpServers } from "./codex/convertMcp.js";
+import { copyCodexSkills } from "./codex/convertSkills.js";
+import { detectPluginFormat } from "./detectFormat.js";
+import { normalizePluginMcpMap } from "./loadPluginMcp.js";
+import { normalizePluginManifest } from "./normalizeManifest.js";
+import { CodexPluginManifest, PluginInstallError, } from "./types.js";
+import { PANEL_APP_MANIFEST_FILE } from "../../panel-apps/manifest.js";
+const MAX_PLUGIN_SOURCE_ENTRIES = 10_000;
+const MAX_PLUGIN_SOURCE_BYTES = 256 * 1024 * 1024;
+const MAX_PLUGIN_SOURCE_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_PLUGIN_SOURCE_DEPTH = 32;
+const MAX_PLUGIN_SOURCE_RELATIVE_PATH = 1_024;
+const MAX_PLUGIN_MANIFEST_BYTES = 1024 * 1024;
+async function assertBoundedTreeEntry(root, directory, depth, budget) {
+    if (depth > MAX_PLUGIN_SOURCE_DEPTH) {
+        throw new PluginInstallError(`plugin source exceeds the maximum directory depth ${MAX_PLUGIN_SOURCE_DEPTH}`);
+    }
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        budget.entries += 1;
+        if (budget.entries > MAX_PLUGIN_SOURCE_ENTRIES) {
+            throw new PluginInstallError(`plugin source contains more than ${MAX_PLUGIN_SOURCE_ENTRIES} entries`);
+        }
+        const path = join(directory, entry.name);
+        const rel = relative(root, path);
+        if (rel.length > MAX_PLUGIN_SOURCE_RELATIVE_PATH) {
+            throw new PluginInstallError(`plugin source path exceeds ${MAX_PLUGIN_SOURCE_RELATIVE_PATH} characters`);
+        }
+        const info = await lstat(path);
+        if (info.isSymbolicLink()) {
+            throw new PluginInstallError(`plugin source must not contain symbolic links; link escapes the stable review boundary: ${rel}`);
+        }
+        if (info.isDirectory()) {
+            await assertBoundedTreeEntry(root, path, depth + 1, budget);
+            continue;
+        }
+        if (!info.isFile()) {
+            throw new PluginInstallError(`plugin source contains an unsupported file type: ${rel}`);
+        }
+        if (info.size > MAX_PLUGIN_SOURCE_FILE_BYTES) {
+            throw new PluginInstallError(`plugin source file exceeds ${MAX_PLUGIN_SOURCE_FILE_BYTES} bytes: ${rel}`);
+        }
+        budget.bytes += info.size;
+        if (budget.bytes > MAX_PLUGIN_SOURCE_BYTES) {
+            throw new PluginInstallError(`plugin source exceeds the ${MAX_PLUGIN_SOURCE_BYTES} byte size limit`);
+        }
+    }
+}
+/** Bound local directory input before copying or parsing author-controlled files. */
+export async function assertBoundedPluginSource(sourceDir) {
+    let root;
+    try {
+        root = await realpath(sourceDir);
+    }
+    catch {
+        throw new PluginInstallError(`source is not a readable directory: ${sourceDir}`);
+    }
+    if (!(await stat(root)).isDirectory()) {
+        throw new PluginInstallError(`source is not a directory: ${sourceDir}`);
+    }
+    await assertBoundedTreeEntry(root, root, 0, { bytes: 0, entries: 0 });
+}
+async function readBoundedJson(path) {
+    const info = await stat(path);
+    if (!info.isFile() || info.size > MAX_PLUGIN_MANIFEST_BYTES) {
+        throw new PluginInstallError(`plugin manifest must be a regular file no larger than ${MAX_PLUGIN_MANIFEST_BYTES} bytes`);
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("manifest root must be an object");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof PluginInstallError)
+            throw error;
+        throw new PluginInstallError(`invalid plugin manifest: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Build the same CodeShell-native projection used by installation, without
+ * touching the plugin root or installed registry. The destination must be a
+ * private temporary/staging directory owned by the caller.
+ */
+export async function projectPluginSource(sourceDir, destinationRoot, name) {
+    if (existsSync(join(sourceDir, PANEL_APP_MANIFEST_FILE))) {
+        throw new PluginInstallError(`Panel App packages use a separate installer; remove ${PANEL_APP_MANIFEST_FILE} from the agent plugin source`);
+    }
+    await assertBoundedPluginSource(sourceDir);
+    const format = detectPluginFormat(sourceDir);
+    let version;
+    await cp(sourceDir, destinationRoot, { recursive: true });
+    if (format === "codex") {
+        const manifest = CodexPluginManifest.parse(await readBoundedJson(join(sourceDir, ".codex-plugin", "plugin.json")));
+        version = manifest.version;
+        await copyCodexSkills(sourceDir, destinationRoot);
+        await convertCodexAgentsDirectory(sourceDir, destinationRoot, name);
+        await copyCodexCommands(sourceDir, destinationRoot);
+        await copyCodexHooks(sourceDir, destinationRoot, manifest.hooks);
+        const servers = resolveCodexMcpServers(sourceDir, manifest.mcpServers);
+        const keyed = {};
+        for (const [serverName, config] of Object.entries(servers)) {
+            const key = `${name}:${serverName}`;
+            keyed[key] = { ...config, name: key };
+        }
+        if (Object.keys(keyed).length > 0) {
+            const normalized = normalizePluginMcpMap(keyed, name, true);
+            if (Object.keys(normalized).length !== Object.keys(keyed).length) {
+                throw new PluginInstallError("invalid plugin MCP server declaration");
+            }
+            await writeFile(join(destinationRoot, "mcp-servers.json"), JSON.stringify(normalized, null, 2));
+        }
+    }
+    else {
+        const manifestPath = join(sourceDir, ".claude-plugin", "plugin.json");
+        if (existsSync(manifestPath)) {
+            const manifest = await readBoundedJson(manifestPath);
+            version =
+                typeof manifest.version === "string" && manifest.version.length > 0
+                    ? manifest.version
+                    : undefined;
+        }
+    }
+    const canonicalManifest = await normalizePluginManifest(sourceDir, {
+        name,
+        version,
+        format,
+        destinationRoot,
+    });
+    rewritePluginVars(destinationRoot);
+    return { canonicalManifest, format, version };
+}