argsbarg 7.0.11 → 7.1.0

package/src/mcp/bundle.ts

@@ -9,6 +9,7 @@ import { basename, join, resolve } from "node:path";
 import { buildProgramUserConfig } from "../config/manifest.ts";
 import type { CliMcpBundleConfig, CliProgram } from "../core/types.ts";
 import { packClaudePlugin } from "./claude.ts";
+import { packCursorPlugin } from "./cursor.ts";
 import { collectMcpTools, mcpServerId } from "./tools.ts";
 import { zipStore } from "./zip.ts";
 
@@ -148,10 +149,15 @@ export function packMcpBundle(program: CliProgram, opts: PackMcpBundleOpts = {})
 }
 
 /** Runs `mcp bundle`: writes enabled dist artifacts; prints one path per line. */
-export function runMcpBundle(program: CliProgram): void {
+export function runMcpBundle(
+  /** CLI program schema. */
+  program: CliProgram,
+): void {
   const mcp = program.mcpServer;
-  if (!mcp?.mcpd && !mcp?.claudePlugin) {
-    throw new Error("mcp bundle: enable mcpServer.mcpd and/or mcpServer.claudePlugin on the program root.");
+  if (!mcp?.mcpd && !mcp?.claudePlugin && !mcp?.cursorPlugin) {
+    throw new Error(
+      "mcp bundle: enable mcpServer.mcpd, mcpServer.claudePlugin, and/or mcpServer.cursorPlugin on the program root.",
+    );
   }
 
   const lines: string[] = [];
@@ -161,5 +167,8 @@ export function runMcpBundle(program: CliProgram): void {
   if (mcp.claudePlugin) {
     lines.push(packClaudePlugin(program));
   }
+  if (mcp.cursorPlugin) {
+    lines.push(packCursorPlugin(program));
+  }
   process.stdout.write(`${lines.join("\n")}\n`);
 }

package/src/mcp/claude.test.ts

@@ -8,13 +8,8 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync }
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CliProgram } from "../core/types.ts";
-import {
-  defaultClaudePluginPaths,
-  generatePluginManifest,
-  generatePluginMcpJson,
-  packClaudePlugin,
-  pluginName,
-} from "./claude.ts";
+import { defaultClaudePluginPaths, generatePluginManifest, generatePluginMcpJson, packClaudePlugin } from "./claude.ts";
+import { pluginName } from "./plugin-shared.ts";
 
 const configFixture: CliProgram = {
   key: "myapp",

package/src/mcp/claude.ts

@@ -3,50 +3,29 @@ Packs a Claude Code plugin zip from a compiled CLI binary.
 Internal module — not exported from index.ts.
 */
 
-import {
-  cpSync,
-  type Dirent,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join, relative, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { buildPluginMcpEnvMapping, buildProgramUserConfig } from "../config/manifest.ts";
-import type { CliMcpBundleConfig, CliProgram } from "../core/types.ts";
-import { generatePluginSkillBundle } from "../skill/generate.ts";
-import { applyPluginSkillHint } from "../skill/hint.ts";
+import type { CliProgram } from "../core/types.ts";
 import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
+import { collectZipEntries, defaultAuthor, pluginName, stagePluginSkills } from "./plugin-shared.ts";
 import { mcpServerId } from "./tools.ts";
-import { type ZipFileEntry, zipStore } from "./zip.ts";
+import { zipStore } from "./zip.ts";
 
+/** Base distribution output directory relative to workspace root. */
 const DIST_DIR = "dist";
-const CLAUDE_PLUGIN_DIR = "claude-plugin";
-
-/** Kebab-case plugin name for plugin.json (Claude Code requires kebab-case). */
-export function pluginName(program: CliProgram): string {
-  return program.key
-    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-    .replace(/[^a-zA-Z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .toLowerCase();
-}
 
-function defaultAuthor(bundle?: CliMcpBundleConfig): {
-  name: string;
-  email?: string;
-  url?: string;
-} {
-  return bundle?.author ?? { name: "Unknown" };
-}
+/** Output subdirectory name under dist for Claude Code plugin archives. */
+const CLAUDE_PLUGIN_DIR = "claude-plugin";
 
 /** Default plugin zip output under cwd. */
-export function defaultClaudePluginPaths(program: CliProgram, cwd = process.cwd()) {
+export function defaultClaudePluginPaths(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Working directory (defaults to cwd). */
+  cwd = process.cwd(),
+) {
   const binaryName = program.key;
   const dist = join(cwd, DIST_DIR);
   const name = pluginName(program);
@@ -58,7 +37,12 @@ export function defaultClaudePluginPaths(program: CliProgram, cwd = process.cwd(
 }
 
 /** Generates `.claude-plugin/plugin.json` object. */
-export function generatePluginManifest(program: CliProgram, _binaryName: string): Record<string, unknown> {
+export function generatePluginManifest(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Staged executable name. */
+  _binaryName: string,
+): Record<string, unknown> {
   const bundle = program.mcpServer?.bundle;
   const manifest: Record<string, unknown> = {
     name: pluginName(program),
@@ -75,7 +59,12 @@ export function generatePluginManifest(program: CliProgram, _binaryName: string)
 }
 
 /** Generates plugin `.mcp.json` stdio server config. */
-export function generatePluginMcpJson(program: CliProgram, binaryName: string): Record<string, unknown> {
+export function generatePluginMcpJson(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Staged executable name. */
+  binaryName: string,
+): Record<string, unknown> {
   const mcp: Record<string, unknown> = {
     command: `\${CLAUDE_PLUGIN_ROOT}/bin/${binaryName}`,
     args: ["mcp"],
@@ -89,35 +78,23 @@ export function generatePluginMcpJson(program: CliProgram, binaryName: string):
   };
 }
 
-function collectZipEntries(rootDir: string, dir = rootDir): ZipFileEntry[] {
-  const entries: ZipFileEntry[] = [];
-  for (const ent of readdirSync(dir, { withFileTypes: true }) as Dirent[]) {
-    const full = join(dir, ent.name);
-    if (ent.isDirectory()) {
-      entries.push(...collectZipEntries(rootDir, full));
-      continue;
-    }
-    if (!ent.isFile()) {
-      continue;
-    }
-    const rel = relative(rootDir, full).split("\\").join("/");
-    const stMode = statSync(full).mode;
-    const entry: ZipFileEntry = { name: rel, data: readFileSync(full) };
-    if (stMode & 0o111) {
-      entry.unixMode = stMode;
-    }
-    entries.push(entry);
-  }
-  return entries;
-}
-
-function writePluginTree(pluginRoot: string, program: CliProgram, binaryPath: string, binaryName: string): void {
-  const bundle = generatePluginSkillBundle(program);
-  const skillMd = applyPluginSkillHint(program, bundle.skillMd);
-
+/**
+ * Stages directory tree for Claude Code plugin: manifest, .mcp.json, binary, and skills.
+ */
+function writePluginTree(
+  /** Staging root directory. */
+  pluginRoot: string,
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Absolute path to compiled binary. */
+  binaryPath: string,
+  /** Executable filename. */
+  binaryName: string,
+  /** Working directory containing repository sources. */
+  cwd: string,
+): void {
   mkdirSync(join(pluginRoot, ".claude-plugin"), { recursive: true });
   mkdirSync(join(pluginRoot, "bin"), { recursive: true });
-  mkdirSync(join(pluginRoot, "skills", bundle.dirName), { recursive: true });
 
   writeFileSync(
     join(pluginRoot, ".claude-plugin", "plugin.json"),
@@ -128,14 +105,19 @@ function writePluginTree(pluginRoot: string, program: CliProgram, binaryPath: st
     `${JSON.stringify(generatePluginMcpJson(program, binaryName), null, 2)}\n`,
   );
   cpSync(binaryPath, join(pluginRoot, "bin", binaryName), { mode: 0o755 });
-  writeFileSync(join(pluginRoot, "skills", bundle.dirName, "SKILL.md"), skillMd);
+  stagePluginSkills(pluginRoot, program, cwd);
 }
 
 /**
  * Writes `dist/claude-plugin/<name>.zip` with manifests, binary, and skill bundle.
  * Requires the compiled binary to exist.
  */
-export function packClaudePlugin(program: CliProgram, opts: PackMcpBundleOpts = {}): string {
+export function packClaudePlugin(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Packaging options. */
+  opts: PackMcpBundleOpts = {},
+): string {
   const cwd = opts.cwd ?? process.cwd();
   const defaults = defaultClaudePluginPaths(program, cwd);
   const mcpDefaults = defaultMcpBundlePaths(program, cwd);
@@ -149,7 +131,7 @@ export function packClaudePlugin(program: CliProgram, opts: PackMcpBundleOpts =
 
   const staging = mkdtempSync(join(tmpdir(), "claude-plugin-"));
   try {
-    writePluginTree(staging, program, binaryPath, binaryName);
+    writePluginTree(staging, program, binaryPath, binaryName, cwd);
     const zip = zipStore(collectZipEntries(staging));
     mkdirSync(join(pluginZipPath, ".."), { recursive: true });
     writeFileSync(pluginZipPath, zip);

package/src/mcp/cursor.test.ts

@@ -0,0 +1,151 @@
+/*
+Tests for mcp/cursor module behavior.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { execSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CliProgram } from "../core/types.ts";
+import {
+  defaultCursorPluginPaths,
+  generateCursorPluginManifest,
+  generateCursorPluginMcpJson,
+  packCursorPlugin,
+} from "./cursor.ts";
+import { pluginName } from "./plugin-shared.ts";
+
+const configFixture: CliProgram = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "Demo.",
+  mcpServer: {
+    enabled: true,
+    bundle: {
+      author: { name: "Author", email: "author@example.com" },
+      displayName: "My Application",
+      homepage: "https://example.com",
+      license: "MIT",
+      repository: "https://github.com/example/myapp",
+    },
+  },
+  appConfig: {
+    entries: {
+      apiToken: {
+        description: "Token from settings.",
+        env: "API_TOKEN",
+        required: true,
+        sensitive: true,
+      },
+    },
+  },
+  commands: [{ key: "run", description: "Run.", handler: () => {} }],
+};
+
+/** Tests for cursor plugin. */
+describe("cursor plugin", () => {
+  test("pluginName is kebab-case", () => {
+    expect(pluginName({ ...configFixture, key: "MyApp" })).toBe("my-app");
+  });
+
+  test("generateCursorPluginManifest includes bundle metadata and variables", () => {
+    const manifest = generateCursorPluginManifest(configFixture, "myapp");
+    expect(manifest.name).toBe("myapp");
+    expect(manifest.displayName).toBe("My Application");
+    expect(manifest.homepage).toBe("https://example.com");
+    expect(manifest.repository).toBe("https://github.com/example/myapp");
+    expect(manifest.license).toBe("MIT");
+    const variables = manifest.variables as {
+      type: string;
+      properties: Record<string, { type: string; description: string }>;
+      required: string[];
+    };
+    expect(variables.type).toBe("object");
+    expect(variables.properties.API_TOKEN?.description).toBe("Token from settings.");
+    expect(variables.required).toContain("API_TOKEN");
+  });
+
+  test("generateCursorPluginMcpJson uses CURSOR_PLUGIN_ROOT and mcpServers wrapper", () => {
+    const json = generateCursorPluginMcpJson(configFixture, "myapp");
+    const servers = json.mcpServers as Record<string, { command: string; args: string[]; env: Record<string, string> }>;
+    const entry = servers.myapp;
+    expect(entry).toBeDefined();
+    expect(entry?.command).toBe("${CURSOR_PLUGIN_ROOT}/bin/myapp");
+    expect(entry?.args).toEqual(["mcp"]);
+    expect(entry?.env?.API_TOKEN).toBe("${API_TOKEN}");
+  });
+
+  test("defaultCursorPluginPaths", () => {
+    const cwd = "/tmp/work";
+    const paths = defaultCursorPluginPaths(configFixture, cwd);
+    expect(paths.pluginZipPath).toBe(join(cwd, "dist", "cursor-plugin", "myapp.zip"));
+    expect(paths.binaryPath).toBe(join(cwd, "dist", "myapp"));
+  });
+
+  test("packCursorPlugin writes zip with manifests, binary, and generated skill", () => {
+    const work = mkdtempSync(join(tmpdir(), "cursor-plugin-test-"));
+    try {
+      const dist = join(work, "dist");
+      mkdirSync(dist, { recursive: true });
+      const binaryPath = join(dist, "myapp");
+      writeFileSync(binaryPath, "#!/bin/sh\n", { mode: 0o755 });
+      const paths = defaultCursorPluginPaths(configFixture, work);
+      packCursorPlugin(configFixture, { cwd: work, binaryPath });
+      const zip = readFileSync(paths.pluginZipPath);
+      expect(zip.length).toBeGreaterThan(0);
+      const zipText = zip.toString("utf8");
+      expect(zipText).toContain("skills/myapp/SKILL.md");
+      expect(zipText).toContain("MCP toolset");
+
+      writeFileSync(join(work, "out.zip"), zip);
+      const extract = join(work, "extract");
+      mkdirSync(extract, { recursive: true });
+      execSync("unzip -o -q ../out.zip", { cwd: extract });
+      const binMode = statSync(join(extract, "bin", "myapp")).mode & 0o777;
+      expect(binMode & 0o111).not.toBe(0);
+
+      const pluginJson = JSON.parse(readFileSync(join(extract, ".cursor-plugin", "plugin.json"), "utf8")) as {
+        name: string;
+      };
+      expect(pluginJson.name).toBe("myapp");
+
+      const mcpJson = JSON.parse(readFileSync(join(extract, "mcp.json"), "utf8")) as {
+        mcpServers: Record<string, { command: string }>;
+      };
+      expect(mcpJson.mcpServers.myapp?.command).toBe("${CURSOR_PLUGIN_ROOT}/bin/myapp");
+    } finally {
+      rmSync(work, { recursive: true, force: true });
+    }
+  });
+
+  test("packCursorPlugin preserves repository skills when present in cwd", () => {
+    const work = mkdtempSync(join(tmpdir(), "cursor-plugin-skill-"));
+    try {
+      const dist = join(work, "dist");
+      mkdirSync(dist, { recursive: true });
+      const binaryPath = join(dist, "myapp");
+      writeFileSync(binaryPath, "#!/bin/sh\n", { mode: 0o755 });
+
+      const repoSkillDir = join(work, "skills", "myapp");
+      mkdirSync(repoSkillDir, { recursive: true });
+      writeFileSync(join(repoSkillDir, "SKILL.md"), "# Custom Hand-Crafted Skill\nSpecial instructions here.");
+      writeFileSync(join(repoSkillDir, "reference.md"), "# Extra Reference Material");
+
+      const paths = defaultCursorPluginPaths(configFixture, work);
+      packCursorPlugin(configFixture, { cwd: work, binaryPath });
+
+      writeFileSync(join(work, "out.zip"), readFileSync(paths.pluginZipPath));
+      const extract = join(work, "extract");
+      mkdirSync(extract, { recursive: true });
+      execSync("unzip -o -q ../out.zip", { cwd: extract });
+
+      const skillContent = readFileSync(join(extract, "skills", "myapp", "SKILL.md"), "utf8");
+      expect(skillContent).toContain("Custom Hand-Crafted Skill");
+      const refContent = readFileSync(join(extract, "skills", "myapp", "reference.md"), "utf8");
+      expect(refContent).toContain("Extra Reference Material");
+    } finally {
+      rmSync(work, { recursive: true, force: true });
+    }
+  });
+});

package/src/mcp/cursor.ts

@@ -0,0 +1,155 @@
+/*
+Packs a Cursor plugin zip from a compiled CLI binary.
+Internal module — not exported from index.ts.
+*/
+
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { buildCursorPluginMcpEnvMapping, buildCursorPluginVariables } from "../config/manifest.ts";
+import type { CliProgram } from "../core/types.ts";
+import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
+import { collectZipEntries, defaultAuthor, pluginName, stagePluginSkills } from "./plugin-shared.ts";
+import { mcpServerId } from "./tools.ts";
+import { zipStore } from "./zip.ts";
+
+/** Base distribution output directory relative to workspace root. */
+const DIST_DIR = "dist";
+
+/** Output subdirectory name under dist for Cursor plugin archives. */
+const CURSOR_PLUGIN_DIR = "cursor-plugin";
+
+/** Default Cursor plugin zip output under cwd. */
+export function defaultCursorPluginPaths(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Working directory (defaults to cwd). */
+  cwd = process.cwd(),
+) {
+  const binaryName = program.key;
+  const dist = join(cwd, DIST_DIR);
+  const name = pluginName(program);
+  return {
+    pluginZipPath: join(dist, CURSOR_PLUGIN_DIR, `${name}.zip`),
+    binaryPath: join(dist, binaryName),
+    binaryName,
+  };
+}
+
+/** Generates `.cursor-plugin/plugin.json` object. */
+export function generateCursorPluginManifest(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Staged executable name. */
+  _binaryName: string,
+): Record<string, unknown> {
+  const bundle = program.mcpServer?.bundle;
+  const manifest: Record<string, unknown> = {
+    name: pluginName(program),
+    version: program.version,
+    description: program.description,
+    author: defaultAuthor(bundle),
+  };
+  if (bundle?.displayName) {
+    manifest.displayName = bundle.displayName;
+  }
+  if (bundle?.homepage) {
+    manifest.homepage = bundle.homepage;
+  }
+  if (bundle?.repository) {
+    manifest.repository = bundle.repository;
+  }
+  if (bundle?.license) {
+    manifest.license = bundle.license;
+  }
+  const variables = buildCursorPluginVariables(program);
+  if (variables) {
+    manifest.variables = variables;
+  }
+  return manifest;
+}
+
+/** Generates plugin `mcp.json` stdio server config for Cursor. */
+export function generateCursorPluginMcpJson(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Staged executable name. */
+  binaryName: string,
+): Record<string, unknown> {
+  const mcp: Record<string, unknown> = {
+    command: `\${CURSOR_PLUGIN_ROOT}/bin/${binaryName}`,
+    args: ["mcp"],
+  };
+  const env = buildCursorPluginMcpEnvMapping(program);
+  if (env) {
+    mcp.env = env;
+  }
+  return {
+    mcpServers: {
+      [mcpServerId(program)]: mcp,
+    },
+  };
+}
+
+/**
+ * Stages directory tree for Cursor plugin: manifest, mcp.json, binary, and skills.
+ */
+function writePluginTree(
+  /** Staging root directory. */
+  pluginRoot: string,
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Absolute path to compiled binary. */
+  binaryPath: string,
+  /** Executable filename. */
+  binaryName: string,
+  /** Working directory containing repository sources. */
+  cwd: string,
+): void {
+  mkdirSync(join(pluginRoot, ".cursor-plugin"), { recursive: true });
+  mkdirSync(join(pluginRoot, "bin"), { recursive: true });
+
+  writeFileSync(
+    join(pluginRoot, ".cursor-plugin", "plugin.json"),
+    `${JSON.stringify(generateCursorPluginManifest(program, binaryName), null, 2)}\n`,
+  );
+  writeFileSync(
+    join(pluginRoot, "mcp.json"),
+    `${JSON.stringify(generateCursorPluginMcpJson(program, binaryName), null, 2)}\n`,
+  );
+  cpSync(binaryPath, join(pluginRoot, "bin", binaryName), { mode: 0o755 });
+  stagePluginSkills(pluginRoot, program, cwd);
+}
+
+/**
+ * Writes `dist/cursor-plugin/<name>.zip` with manifests, binary, and skill bundle.
+ * Requires the compiled binary to exist.
+ */
+export function packCursorPlugin(
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Packaging options. */
+  opts: PackMcpBundleOpts = {},
+): string {
+  const cwd = opts.cwd ?? process.cwd();
+  const defaults = defaultCursorPluginPaths(program, cwd);
+  const mcpDefaults = defaultMcpBundlePaths(program, cwd);
+  const binaryPath = resolve(cwd, opts.binaryPath ?? mcpDefaults.binaryPath);
+  const pluginZipPath = resolve(cwd, defaults.pluginZipPath);
+  const binaryName = basename(binaryPath);
+
+  if (!existsSync(binaryPath)) {
+    throw new Error(`Binary not found: ${binaryPath}. Build with compile first (expected dist/${program.key}).`);
+  }
+
+  const staging = mkdtempSync(join(tmpdir(), "cursor-plugin-"));
+  try {
+    writePluginTree(staging, program, binaryPath, binaryName, cwd);
+    const zip = zipStore(collectZipEntries(staging));
+    mkdirSync(join(pluginZipPath, ".."), { recursive: true });
+    writeFileSync(pluginZipPath, zip);
+    return pluginZipPath;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}

package/src/mcp/hidden-mcpb.test.ts

@@ -222,11 +222,44 @@ describe("mcp bundle", () => {
     }
   });
 
+  /** RunMcpBundle with cursorPlugin only prints plugin path. */
+  test("runMcpBundle with cursorPlugin only prints plugin path", () => {
+    const work = mkdtempSync(join(tmpdir(), "mcpb-run-cursor-"));
+    const stdout: string[] = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdout.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      return true;
+    }) as typeof process.stdout.write;
+    const fixture: CliProgram = {
+      ...hiddenFixture,
+      mcpServer: { enabled: true, cursorPlugin: true },
+    };
+    try {
+      const dist = join(work, "dist");
+      mkdirSync(dist, { recursive: true });
+      writeFileSync(join(dist, "myapp"), "#!/bin/sh\n", { mode: 0o755 });
+      const prevCwd = process.cwd();
+      process.chdir(work);
+      try {
+        runMcpBundle(fixture);
+      } finally {
+        process.chdir(prevCwd);
+      }
+      const lines = stdout.join("").trim().split("\n");
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain("cursor-plugin");
+    } finally {
+      process.stdout.write = orig;
+      rmSync(work, { recursive: true, force: true });
+    }
+  });
+
   test("runMcpBundle errors when no bundle flags enabled", () => {
     const fixture: CliProgram = {
       ...hiddenFixture,
       mcpServer: { enabled: true },
     };
-    expect(() => runMcpBundle(fixture)).toThrow(/mcpd/);
+    expect(() => runMcpBundle(fixture)).toThrow(/cursorPlugin/);
   });
 });

package/src/mcp/plugin-shared.ts

@@ -0,0 +1,107 @@
+/*
+Shared utilities and staging helpers for Claude Code and Cursor plugin packages.
+Internal module — not exported from index.ts.
+*/
+
+import {
+  cpSync,
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join, relative, resolve } from "node:path";
+import type { CliMcpBundleConfig, CliProgram } from "../core/types.ts";
+import { generatePluginSkillBundle } from "../skill/generate.ts";
+import { applyPluginSkillHint } from "../skill/hint.ts";
+import { sanitizeToolSegment } from "./tools.ts";
+import type { ZipFileEntry } from "./zip.ts";
+
+/**
+ * Traverses a staging directory recursively and gathers ZIP entries preserving executable permissions.
+ */
+export function collectZipEntries(
+  /** Directory containing the staged files. */
+  rootDir: string,
+  /** Subdirectory currently being traversed (defaults to rootDir). */
+  dir = rootDir,
+): ZipFileEntry[] {
+  const entries: ZipFileEntry[] = [];
+  for (const ent of readdirSync(dir, { withFileTypes: true }) as Dirent[]) {
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      entries.push(...collectZipEntries(rootDir, full));
+      continue;
+    }
+    if (!ent.isFile()) {
+      continue;
+    }
+    const rel = relative(rootDir, full).split("\\").join("/");
+    const stMode = statSync(full).mode;
+    const entry: ZipFileEntry = { name: rel, data: readFileSync(full) };
+    if (stMode & 0o111) {
+      entry.unixMode = stMode;
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Returns author metadata from bundle config or fallback defaults.
+ */
+export function defaultAuthor(
+  /** Optional bundle configuration. */
+  bundle?: CliMcpBundleConfig,
+): {
+  name: string;
+  email?: string;
+  url?: string;
+} {
+  return bundle?.author ?? { name: "Unknown" };
+}
+
+/**
+ * Generates kebab-case plugin name for plugin manifests.
+ */
+export function pluginName(
+  /** CLI program schema. */
+  program: CliProgram,
+): string {
+  return program.key
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+/**
+ * Stages repository skill directory if present, or writes a generated MCP routing skill.
+ */
+export function stagePluginSkills(
+  /** Plugin staging root directory. */
+  pluginRoot: string,
+  /** CLI program schema. */
+  program: CliProgram,
+  /** Working directory containing repository sources. */
+  cwd: string,
+): void {
+  const dirName = sanitizeToolSegment(program.key);
+  const repoSkillDir = program.mcpServer?.bundle?.skillsDir
+    ? resolve(cwd, program.mcpServer.bundle.skillsDir)
+    : join(cwd, "skills", dirName);
+
+  if (existsSync(repoSkillDir) && statSync(repoSkillDir).isDirectory()) {
+    const targetDir = join(pluginRoot, "skills", dirName);
+    mkdirSync(join(targetDir, ".."), { recursive: true });
+    cpSync(repoSkillDir, targetDir, { recursive: true });
+  } else {
+    const bundle = generatePluginSkillBundle(program);
+    const skillMd = applyPluginSkillHint(program, bundle.skillMd);
+    mkdirSync(join(pluginRoot, "skills", bundle.dirName), { recursive: true });
+    writeFileSync(join(pluginRoot, "skills", bundle.dirName, "SKILL.md"), skillMd);
+  }
+}