@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/plugins/installer/codex/convertCommands.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
-import { readdir, mkdir, copyFile } from "node:fs/promises";
-import { join } from "node:path";
+import { copyFile, mkdir, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { PluginInstallError } from "../types.js";
 /**
  * Map a Codex plugin's slash commands into CC's `commands/` layout.
  *
@@ -10,37 +11,59 @@ import { join } from "node:path";
  * already scans `commands/*.md`. So the conversion is a flat copy of every
  * `.md` from `prompts/` (and any explicit `commands/`) into `dest/commands/`.
  *
- * Placeholder syntax differs (Codex `$1`/`$FILE` vs CC `$ARGUMENTS`) but the
- * body is copied verbatim — v1 inert, the same stance taken for `codex_`
- * agent fields (see convertAgents.ts). Non-`.md` files are ignored, matching
- * Codex's own behaviour. On a filename collision an explicit `commands/`
- * entry wins over `prompts/` (the more specific source).
+ * Placeholder syntax differs (Codex `$1`/`$FILE` vs CC `$ARGUMENTS`), so the
+ * body is copied verbatim and expanded at invocation time by
+ * `expandPluginCommandBody`. Non-`.md` files are ignored, matching Codex's
+ * own behaviour. On a filename collision an explicit `commands/` entry wins
+ * over `prompts/` (the more specific source).
  *
  * Async fs throughout: this runs in the Electron main process during install;
  * sync copies block the event loop and freeze the UI (see convertSkills.ts).
  */
 export async function copyCodexCommands(sourceDir, destDir) {
+    const sourceRoot = await realpath(sourceDir);
     // prompts/ first, then commands/ — later writes overwrite earlier, so an
     // explicit commands/ entry wins the collision.
-    const written = await copyMdFiles(join(sourceDir, "prompts"), join(destDir, "commands"));
-    await copyMdFiles(join(sourceDir, "commands"), join(destDir, "commands"), written);
+    const written = await copyMdFiles(sourceRoot, join(sourceDir, "prompts"), join(destDir, "commands"));
+    await copyMdFiles(sourceRoot, join(sourceDir, "commands"), join(destDir, "commands"), written);
 }
 /** Flat-copy *.md from srcDir into destDir; returns the set of basenames written. */
-async function copyMdFiles(srcDir, destDir, written = new Set()) {
+async function copyMdFiles(sourceRoot, srcDir, destDir, written = new Set()) {
     if (!existsSync(srcDir))
         return written;
+    const resolvedDir = await resolveContainedSource(sourceRoot, srcDir, srcDir);
     let ensuredDest = false;
-    for (const dirent of await readdir(srcDir, { withFileTypes: true })) {
+    for (const dirent of await readdir(resolvedDir, { withFileTypes: true })) {
         if (!dirent.isFile() && !dirent.isSymbolicLink())
             continue;
         if (!dirent.name.endsWith(".md"))
             continue;
+        const source = await resolveContainedSource(sourceRoot, join(resolvedDir, dirent.name), `${srcDir}/${dirent.name}`);
+        if (!(await stat(source)).isFile())
+            continue;
         if (!ensuredDest) {
             await mkdir(destDir, { recursive: true });
             ensuredDest = true;
         }
-        await copyFile(join(srcDir, dirent.name), join(destDir, dirent.name));
+        const destination = join(destDir, dirent.name);
+        if (resolve(source) !== resolve(destination)) {
+            await copyFile(source, destination);
+        }
         written.add(dirent.name);
     }
     return written;
 }
+async function resolveContainedSource(sourceRoot, candidate, label) {
+    let target;
+    try {
+        target = await realpath(candidate);
+    }
+    catch {
+        throw new PluginInstallError(`plugin command source not found: ${label}`);
+    }
+    const rel = relative(sourceRoot, target);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PluginInstallError(`plugin command source escapes plugin dir: ${label}`);
+    }
+    return target;
+}

package/dist/plugins/installer/codex/convertHooks.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert Codex plugin hook declarations into CodeShell's canonical
+ * `hooks/hooks.json` location.
+ *
+ * Codex accepts a path, an inline object, or an array mixing both. CodeShell's
+ * runtime intentionally has one loader path, so installation resolves and
+ * merges those declarations once. When the manifest omits `hooks`, the normal
+ * `hooks/hooks.json` copied from the source tree is already canonical.
+ */
+export declare function copyCodexHooks(sourceDir: string, destDir: string, declaration: string | Record<string, unknown> | Array<string | Record<string, unknown>> | undefined): Promise<void>;

package/dist/plugins/installer/codex/convertHooks.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { PluginInstallError } from "../types.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeHookDocument(value, label) {
+    if (!isRecord(value)) {
+        throw new PluginInstallError(`${label}: hooks declaration must be an object`);
+    }
+    const candidate = isRecord(value.hooks) ? value.hooks : value;
+    const hooks = {};
+    for (const [event, groups] of Object.entries(candidate)) {
+        if (!Array.isArray(groups)) {
+            throw new PluginInstallError(`${label}: hook event '${event}' must be an array`);
+        }
+        hooks[event] = groups;
+    }
+    return hooks;
+}
+async function readHookDocument(sourceDir, declaration) {
+    const base = await realpath(sourceDir);
+    const candidate = resolve(base, declaration);
+    const rel = relative(base, candidate);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PluginInstallError(`hooks ref escapes plugin dir: ${declaration}`);
+    }
+    if (!existsSync(candidate)) {
+        throw new PluginInstallError(`hooks ref not found: ${declaration}`);
+    }
+    let target;
+    try {
+        target = await realpath(candidate);
+    }
+    catch {
+        throw new PluginInstallError(`hooks ref not found: ${declaration}`);
+    }
+    const targetRel = relative(base, target);
+    if (targetRel === ".." || targetRel.startsWith(`..${sep}`) || isAbsolute(targetRel)) {
+        throw new PluginInstallError(`hooks ref escapes plugin dir: ${declaration}`);
+    }
+    try {
+        return normalizeHookDocument(JSON.parse(await readFile(target, "utf-8")), `hooks ref ${declaration}`);
+    }
+    catch (error) {
+        if (error instanceof PluginInstallError)
+            throw error;
+        throw new PluginInstallError(`invalid hooks json ${declaration}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function mergeHooks(target, source) {
+    for (const [event, groups] of Object.entries(source)) {
+        target[event] = [...(target[event] ?? []), ...groups];
+    }
+}
+/**
+ * Convert Codex plugin hook declarations into CodeShell's canonical
+ * `hooks/hooks.json` location.
+ *
+ * Codex accepts a path, an inline object, or an array mixing both. CodeShell's
+ * runtime intentionally has one loader path, so installation resolves and
+ * merges those declarations once. When the manifest omits `hooks`, the normal
+ * `hooks/hooks.json` copied from the source tree is already canonical.
+ */
+export async function copyCodexHooks(sourceDir, destDir, declaration) {
+    if (declaration === undefined)
+        return;
+    const declarations = Array.isArray(declaration) ? declaration : [declaration];
+    const merged = {};
+    for (const item of declarations) {
+        if (typeof item === "string") {
+            mergeHooks(merged, await readHookDocument(sourceDir, item));
+        }
+        else {
+            mergeHooks(merged, normalizeHookDocument(item, "inline hooks"));
+        }
+    }
+    const hooksDir = join(destDir, "hooks");
+    await mkdir(hooksDir, { recursive: true });
+    await writeFile(join(hooksDir, "hooks.json"), `${JSON.stringify({ hooks: merged }, null, 2)}\n`, "utf-8");
+}

package/dist/plugins/installer/codex/convertSkills.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
-import { readdir, readFile, cp } from "node:fs/promises";
-import { join } from "node:path";
+import { cp, lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { PluginInstallError } from "../types.js";
 const FRONTMATTER = /^---\s*\n[\s\S]*?\n---/;
 /**
@@ -18,16 +18,51 @@ export async function copyCodexSkills(sourceDir, destDir) {
     const skillsSrc = join(sourceDir, "skills");
     if (!existsSync(skillsSrc))
         return;
-    for (const dirent of await readdir(skillsSrc, { withFileTypes: true })) {
+    if ((await lstat(skillsSrc)).isSymbolicLink()) {
+        throw new PluginInstallError("skills directory must not be a symbolic link");
+    }
+    const sourceRoot = await realpath(sourceDir);
+    const resolvedSkillsRoot = await resolveContainedSkillSource(sourceRoot, skillsSrc, "skills");
+    await assertNoSkillSymlinks(resolvedSkillsRoot, resolvedSkillsRoot);
+    for (const dirent of await readdir(resolvedSkillsRoot, { withFileTypes: true })) {
         if (!dirent.isDirectory())
             continue;
-        const skillFile = join(skillsSrc, dirent.name, "SKILL.md");
+        const skillDir = await resolveContainedSkillSource(resolvedSkillsRoot, join(resolvedSkillsRoot, dirent.name), `skills/${dirent.name}`);
+        const skillFile = join(skillDir, "SKILL.md");
         if (!existsSync(skillFile))
             continue;
-        const raw = (await readFile(skillFile, "utf-8")).trim();
+        const resolvedSkillFile = await resolveContainedSkillSource(skillDir, skillFile, `skills/${dirent.name}/SKILL.md`);
+        if (!(await stat(resolvedSkillFile)).isFile())
+            continue;
+        const raw = (await readFile(resolvedSkillFile, "utf-8")).trim();
         if (!FRONTMATTER.test(raw)) {
             throw new PluginInstallError(`skills/${dirent.name}/SKILL.md: missing frontmatter`);
         }
     }
-    await cp(skillsSrc, join(destDir, "skills"), { recursive: true });
+    await cp(resolvedSkillsRoot, join(destDir, "skills"), { recursive: true });
+}
+async function resolveContainedSkillSource(root, candidate, label) {
+    let target;
+    try {
+        target = await realpath(candidate);
+    }
+    catch {
+        throw new PluginInstallError(`skill source not found: ${label}`);
+    }
+    const rel = relative(root, target);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PluginInstallError(`skill source escapes plugin dir: ${label}`);
+    }
+    return target;
+}
+async function assertNoSkillSymlinks(root, dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        const rel = relative(root, path);
+        if (entry.isSymbolicLink()) {
+            throw new PluginInstallError(`skill source must not contain symbolic links: skills/${rel}`);
+        }
+        if (entry.isDirectory())
+            await assertNoSkillSymlinks(root, path);
+    }
 }

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

@@ -1,7 +1,13 @@
+export interface InstallPluginFromPathOptions {
+    /** Trusted source identity to persist instead of the temporary projection input path. */
+    source?: string;
+    /** Trusted distribution version to persist instead of the plugin manifest version. */
+    version?: string;
+}
 /**
  * Install a local plugin directory into ~/.code-shell/plugins/<name>/.
  * Builds into a temp sibling dir, then renames into place — a conversion
  * failure leaves nothing behind. `installedAt` is passed in (caller stamps the
  * timestamp) to keep this function pure of the unavailable Date.now().
  */
-export declare function installPluginFromPath(sourceDir: string, name: string, installedAt: string): Promise<string>;
+export declare function installPluginFromPath(sourceDir: string, name: string, installedAt: string, options?: InstallPluginFromPathOptions): Promise<string>;

package/dist/plugins/installer/install.js

@@ -1,22 +1,21 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
-import { mkdir, writeFile, readFile, readdir, cp, rm, rename, } from "node:fs/promises";
-import { join, relative } from "node:path";
-import { detectPluginFormat } from "./detectFormat.js";
+import { mkdir, writeFile, rm, rename } from "node:fs/promises";
+import { join } from "node:path";
 import { pluginInstallDir, pluginsRoot, assertSafePluginName } from "./paths.js";
-import { CodexPluginManifest, PluginInstallError } from "./types.js";
-import { convertCodexAgentToml } from "./codex/convertAgents.js";
-import { resolveCodexMcpServers } from "./codex/convertMcp.js";
-import { copyCodexSkills } from "./codex/convertSkills.js";
-import { copyCodexCommands } from "./codex/convertCommands.js";
+import { PluginInstallError } from "./types.js";
 import { appendInstallEntry, pluginInstallKey } from "../installedPlugins.js";
-import { rewritePluginVars } from "../varRewrite.js";
+import { pluginHookInstallRecord } from "../pluginHookIntegrity.js";
+import { pluginMcpInstallRecord } from "../pluginMcpIntegrity.js";
+import { readPluginMcp } from "./loadPluginMcp.js";
+import { projectPluginSource } from "./projectPluginSource.js";
 /**
  * Install a local plugin directory into ~/.code-shell/plugins/<name>/.
  * Builds into a temp sibling dir, then renames into place — a conversion
  * failure leaves nothing behind. `installedAt` is passed in (caller stamps the
  * timestamp) to keep this function pure of the unavailable Date.now().
  */
-export async function installPluginFromPath(sourceDir, name, installedAt) {
+export async function installPluginFromPath(sourceDir, name, installedAt, options = {}) {
     assertSafePluginName(name);
     if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {
         throw new PluginInstallError(`source is not a directory: ${sourceDir}`);
@@ -26,45 +25,17 @@ export async function installPluginFromPath(sourceDir, name, installedAt) {
         throw new PluginInstallError(`plugin '${name}' already installed; uninstall first or rename the source`);
     }
     await mkdir(pluginsRoot(), { recursive: true });
-    const tmpDir = join(pluginsRoot(), `.tmp-${name}-${process.pid}`);
-    await rm(tmpDir, { recursive: true, force: true });
-    await mkdir(tmpDir, { recursive: true });
+    const tmpDir = join(pluginsRoot(), `.tmp-${name}-${process.pid}-${randomUUID()}`);
+    await mkdir(tmpDir);
     try {
-        const format = detectPluginFormat(sourceDir);
-        let meta;
-        if (format === "cc") {
-            // Async cp: a recursive copy of a whole plugin dir is the dominant cost
-            // here; awaiting it yields the event loop so the Electron main process
-            // keeps answering IPC (no UI freeze during install).
-            await cp(sourceDir, tmpDir, { recursive: true });
-            // Read the declared version from .claude-plugin/plugin.json so the
-            // install record (and the UI's "installed version" chip) shows e.g.
-            // "v0.1.0" instead of falling back to the literal "local". Best-effort:
-            // CC plugins commonly omit version, and the file may be absent/malformed.
-            const version = await readCcPluginVersion(sourceDir);
-            meta = { name, format: "cc", version, source: sourceDir, installedAt };
-        }
-        else {
-            const manifest = CodexPluginManifest.parse(JSON.parse(await readFile(join(sourceDir, ".codex-plugin", "plugin.json"), "utf-8")));
-            // skills (verbatim copy)
-            await copyCodexSkills(sourceDir, tmpDir);
-            // agents (TOML → MD)
-            await convertAgentsInto(sourceDir, tmpDir, name);
-            // prompts/ (+ commands/) → commands/ (Codex slash commands == CC commands)
-            await copyCodexCommands(sourceDir, tmpDir);
-            // mcp → mcp-servers.json keyed <plugin>:<server>
-            const servers = resolveCodexMcpServers(sourceDir, manifest.mcpServers);
-            const keyed = {};
-            for (const [serverName, cfg] of Object.entries(servers)) {
-                const key = `${name}:${serverName}`;
-                keyed[key] = { ...cfg, name: key };
-            }
-            if (Object.keys(keyed).length > 0) {
-                await writeFile(join(tmpDir, "mcp-servers.json"), JSON.stringify(keyed, null, 2));
-            }
-            meta = { name, format: "codex", version: manifest.version, source: sourceDir, installedAt };
-        }
-        rewritePluginVars(tmpDir);
+        const projected = await projectPluginSource(sourceDir, tmpDir, name);
+        const meta = {
+            name,
+            format: projected.format,
+            version: options.version ?? projected.version,
+            source: options.source ?? sourceDir,
+            installedAt,
+        };
         await writeFile(join(tmpDir, ".cs-meta.json"), JSON.stringify(meta, null, 2));
         await rename(tmpDir, finalDir);
         // Register so existing loaders (scanInstalledPlugins / loadPluginHooks)
@@ -76,6 +47,8 @@ export async function installPluginFromPath(sourceDir, name, installedAt) {
             version: meta.version ?? "local",
             installedAt,
             lastUpdated: installedAt,
+            ...pluginHookInstallRecord(finalDir),
+            ...pluginMcpInstallRecord(finalDir, Object.keys(readPluginMcp(finalDir, name)).length > 0),
         });
         return finalDir;
     }
@@ -84,42 +57,3 @@ export async function installPluginFromPath(sourceDir, name, installedAt) {
         throw err;
     }
 }
-/**
- * Best-effort read of a CC plugin's declared version from
- * <sourceDir>/.claude-plugin/plugin.json. Returns undefined when the file is
- * absent, unparseable, or has no string `version` — the caller then records the
- * install without a version (UI shows the source tag instead of a number).
- */
-async function readCcPluginVersion(sourceDir) {
-    try {
-        const raw = await readFile(join(sourceDir, ".claude-plugin", "plugin.json"), "utf-8");
-        const v = JSON.parse(raw).version;
-        return typeof v === "string" && v.length > 0 ? v : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Walk <sourceDir>/agents/**.toml → <destDir>/agents/**.md (structure preserved). */
-async function convertAgentsInto(sourceDir, destDir, pluginName) {
-    const agentsSrc = join(sourceDir, "agents");
-    if (!existsSync(agentsSrc))
-        return;
-    const walk = async (dir) => {
-        for (const dirent of await readdir(dir, { withFileTypes: true })) {
-            const abs = join(dir, dirent.name);
-            if (dirent.isDirectory()) {
-                await walk(abs);
-                continue;
-            }
-            if (!dirent.name.endsWith(".toml"))
-                continue;
-            const rel = relative(agentsSrc, abs).replace(/\.toml$/, ".md");
-            const outPath = join(destDir, "agents", rel);
-            await mkdir(join(outPath, ".."), { recursive: true });
-            const md = convertCodexAgentToml(await readFile(abs, "utf-8"), rel, pluginName);
-            await writeFile(outPath, md);
-        }
-    };
-    await walk(agentsSrc);
-}

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

@@ -9,6 +9,15 @@ export interface InstallLocalOptions {
      */
     overwrite?: boolean;
 }
+export interface LocalPluginSourceInput {
+    kind: "dir" | "zip";
+    path: string;
+}
+/**
+ * Resolve a directory/zip input to its actual plugin root. Zip extraction is
+ * private and always cleaned after the callback settles.
+ */
+export declare function withLocalPluginSourceRoot<T>(input: LocalPluginSourceInput, operation: (root: string) => Promise<T>): Promise<T>;
 /**
  * Install a local plugin from a .zip archive.
  *
@@ -34,10 +43,23 @@ export declare function installPluginFromArchive(zipPath: string, installedAt: s
  * a repo checkout whose plugin sits one level down, and so the name comes from
  * the manifest rather than forcing the caller to guess it.
  */
-export declare function installLocalPlugin(input: {
-    kind: "dir" | "zip";
-    path: string;
-}, installedAt: string, name?: string, options?: InstallLocalOptions): Promise<{
+export declare function installLocalPlugin(input: LocalPluginSourceInput, installedAt: string, name?: string, options?: InstallLocalOptions): Promise<{
     dir: string;
     name: string;
 }>;
+/**
+ * A plugin root is a dir that holds a recognizable manifest or component dir.
+ * Zip archives commonly wrap everything in a single top-level folder, so if
+ * `dir` itself isn't a plugin root but contains exactly one subdirectory, dive
+ * one level. Only one level — deeper nesting is treated as malformed.
+ */
+export declare function findPluginRoot(dir: string): Promise<string>;
+/** Read the `name` field from a CC or Codex manifest; fall back to the dir name. */
+export declare function deriveName(root: string): Promise<string>;
+/**
+ * Coerce an arbitrary derived name into a safe single path segment:
+ * lowercase, only [a-z0-9._-], collapse the rest to '-'. assertSafePluginName
+ * (called by installPluginFromPath) rejects separators outright; this makes a
+ * manifest name like "My Plugin" usable instead of erroring.
+ */
+export declare function normalizePluginName(raw: string): string;

package/dist/plugins/installer/installFromArchive.js

@@ -7,6 +7,38 @@ import { installPluginFromPath } from "./install.js";
 import { reinstallAtomic } from "./update.js";
 import { pluginInstallDir } from "./paths.js";
 import { PluginInstallError } from "./types.js";
+const MAX_LOCAL_PLUGIN_SOURCE_PATH = 4096;
+/**
+ * Resolve a directory/zip input to its actual plugin root. Zip extraction is
+ * private and always cleaned after the callback settles.
+ */
+export async function withLocalPluginSourceRoot(input, operation) {
+    if (!input ||
+        (input.kind !== "dir" && input.kind !== "zip") ||
+        typeof input.path !== "string" ||
+        input.path.length === 0 ||
+        input.path.length > MAX_LOCAL_PLUGIN_SOURCE_PATH ||
+        input.path.includes("\0")) {
+        throw new PluginInstallError("local plugin source is invalid");
+    }
+    if (input.kind === "dir") {
+        if (!existsSync(input.path) || !statSync(input.path).isDirectory()) {
+            throw new PluginInstallError(`source is not a directory: ${input.path}`);
+        }
+        return operation(await findPluginRoot(input.path));
+    }
+    if (!existsSync(input.path) || !statSync(input.path).isFile()) {
+        throw new PluginInstallError(`archive is not a file: ${input.path}`);
+    }
+    const tmp = await mkdtemp(join(tmpdir(), "cs-tmp-zip-"));
+    try {
+        await extractZip(input.path, tmp);
+        return await operation(await findPluginRoot(tmp));
+    }
+    finally {
+        await rm(tmp, { recursive: true, force: true });
+    }
+}
 /**
  * Install `root` as plugin `name`, atomically replacing an already-installed
  * plugin of the same name when `overwrite` is set. When no same-name plugin
@@ -35,22 +67,11 @@ async function installRootMaybeOverwrite(root, resolvedName, installedAt, overwr
  * caller stamps `installedAt` to keep this pure of the unavailable Date.now().
  */
 export async function installPluginFromArchive(zipPath, installedAt, name, options) {
-    if (!existsSync(zipPath) || !statSync(zipPath).isFile()) {
-        throw new PluginInstallError(`archive is not a file: ${zipPath}`);
-    }
-    const tmp = await mkdtemp(join(tmpdir(), "cs-tmp-zip-"));
-    try {
-        await extractZip(zipPath, tmp);
-        const root = await findPluginRoot(tmp);
+    return withLocalPluginSourceRoot({ kind: "zip", path: zipPath }, async (root) => {
         const resolvedName = normalizePluginName(name ?? (await deriveName(root)));
-        // Overwrite (when set) runs inside this try so the extracted `root` is still
-        // present while reinstallAtomic installs from it; the finally removes tmp.
         const dir = await installRootMaybeOverwrite(root, resolvedName, installedAt, options?.overwrite ?? false);
         return { dir, name: resolvedName };
-    }
-    finally {
-        await rm(tmp, { recursive: true, force: true });
-    }
+    });
 }
 /**
  * Unified local-install entry for the desktop/UI: takes either a directory or
@@ -62,16 +83,11 @@ export async function installPluginFromArchive(zipPath, installedAt, name, optio
  * the manifest rather than forcing the caller to guess it.
  */
 export async function installLocalPlugin(input, installedAt, name, options) {
-    if (input.kind === "zip") {
-        return installPluginFromArchive(input.path, installedAt, name, options);
-    }
-    if (!existsSync(input.path) || !statSync(input.path).isDirectory()) {
-        throw new PluginInstallError(`source is not a directory: ${input.path}`);
-    }
-    const root = await findPluginRoot(input.path);
-    const resolvedName = normalizePluginName(name ?? (await deriveName(root)));
-    const dir = await installRootMaybeOverwrite(root, resolvedName, installedAt, options?.overwrite ?? false);
-    return { dir, name: resolvedName };
+    return withLocalPluginSourceRoot(input, async (root) => {
+        const resolvedName = normalizePluginName(name ?? (await deriveName(root)));
+        const dir = await installRootMaybeOverwrite(root, resolvedName, installedAt, options?.overwrite ?? false);
+        return { dir, name: resolvedName };
+    });
 }
 /**
  * A plugin root is a dir that holds a recognizable manifest or component dir.
@@ -79,7 +95,7 @@ export async function installLocalPlugin(input, installedAt, name, options) {
  * `dir` itself isn't a plugin root but contains exactly one subdirectory, dive
  * one level. Only one level — deeper nesting is treated as malformed.
  */
-async function findPluginRoot(dir) {
+export async function findPluginRoot(dir) {
     if (looksLikePluginRoot(dir))
         return dir;
     const entries = await readdir(dir, { withFileTypes: true });
@@ -97,7 +113,7 @@ function looksLikePluginRoot(dir) {
         ["skills", "commands", "agents", "hooks"].some((d) => existsSync(join(dir, d))));
 }
 /** Read the `name` field from a CC or Codex manifest; fall back to the dir name. */
-async function deriveName(root) {
+export async function deriveName(root) {
     for (const rel of [
         [".claude-plugin", "plugin.json"],
         [".codex-plugin", "plugin.json"],
@@ -122,13 +138,14 @@ async function deriveName(root) {
  * (called by installPluginFromPath) rejects separators outright; this makes a
  * manifest name like "My Plugin" usable instead of erroring.
  */
-function normalizePluginName(raw) {
+export function normalizePluginName(raw) {
     const cleaned = raw
         .trim()
         .toLowerCase()
         .replace(/[^a-z0-9._-]+/g, "-")
         .replace(/^[-.]+|[-.]+$/g, "");
-    if (!cleaned)
+    if (!cleaned) {
         throw new PluginInstallError(`cannot derive a valid plugin name from: ${JSON.stringify(raw)}`);
+    }
     return cleaned;
 }

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

@@ -0,0 +1,31 @@
+import type { ParsedSource } from "./parseSource.js";
+export declare const NPM_PUBLIC_REGISTRY = "https://registry.npmjs.org";
+export declare const MAX_NPM_METADATA_BYTES: number;
+export interface ResolvedNpmPlugin {
+    packageName: string;
+    requestedSelector: string;
+    resolvedVersion: string;
+    tarballUrl: string;
+    integrity: string;
+}
+export type NpmPluginFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface NpmPluginInstallOptions {
+    /** Test seam; production always uses the platform fetch implementation. */
+    fetch?: NpmPluginFetch;
+}
+/** Resolve an exact version or dist-tag to an immutable public-registry snapshot. */
+export declare function resolveNpmPlugin(parsed: Extract<ParsedSource, {
+    kind: "npm";
+}>, options?: NpmPluginInstallOptions): Promise<ResolvedNpmPlugin>;
+/** Download a tarball with a compressed-byte cap and verify SHA-512 before use. */
+export declare function downloadVerifiedNpmTarball(resolution: ResolvedNpmPlugin, targetPath: string, options?: NpmPluginInstallOptions): Promise<void>;
+/**
+ * Install a self-contained plugin from the public npm registry. The resolved
+ * exact version is recorded as the source; Phase A deliberately has no npm
+ * dependency install, lifecycle execution, private registry, or auto-update.
+ */
+export declare function installPluginFromNpm(parsed: ParsedSource, name: string | undefined, installedAt: string, options?: NpmPluginInstallOptions): Promise<{
+    dir: string;
+    name: string;
+    resolution: ResolvedNpmPlugin;
+}>;