argsbarg 7.0.10 → 7.1.0

package/src/help.test.ts

@@ -12,6 +12,7 @@ import {
   cliPositionalLabel,
   cliResolveNotes,
   schemaToYamlLines,
+  visibleWidth,
 } from "./help.ts";
 import { testProgram } from "./test/fixtures.ts";
 
@@ -214,6 +215,41 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("Output Schema");
   });
 
+  /** Tests that TTY help table boxes constrain line lengths to terminal width without wrapping border characters. */
+  test("TTY help table boxes fit terminal width without overflow", () => {
+    const origColumns = process.stdout.columns;
+    try {
+      process.stdout.columns = 120;
+      const root = testProgram({
+        key: "doc",
+        version: "1.0.0",
+        description: "Test application.",
+        commands: [
+          {
+            key: "query",
+            description:
+              "Query the body tape. Prints apply-shaped YAML `{ documentId, tabs: [{ tabId, ops: [], nodes }] }` (or JSON with --json). Fill ops and pipe to apply.",
+            handler: () => {},
+          },
+          {
+            key: "markdown-insert",
+            description:
+              "Insert markdown into a Google Doc tab as native DOM elements (headings, lists, code, tables).",
+            handler: () => {},
+          },
+        ],
+      });
+      const help = cliHelpRender(cliPresentationRoot(root), [], false, { isTTY: true });
+      const boxLines = help.split("\n").filter((l) => l.includes("╭") || l.includes("│") || l.includes("╰"));
+      expect(boxLines.length).toBeGreaterThan(0);
+      for (const line of boxLines) {
+        expect(visibleWidth(line)).toBe(120);
+      }
+    } finally {
+      process.stdout.columns = origColumns;
+    }
+  });
+
   /** Tests that non-TTY help automatically includes output schema in YAML by default. */
   test("non-TTY help automatically includes output schema in YAML by default", () => {
     const root = testProgram({

package/src/help.ts

@@ -82,7 +82,7 @@ function isOutputTTY(useStderr: boolean): boolean {
 // ── Width Helpers ─────────────────────────────────────────────────────────────
 
 /** Counts display columns, skipping ANSI SGR sequences. */
-function visibleWidth(s: string): number {
+export function visibleWidth(s: string): number {
   let w = 0;
   let i = 0;
   while (i < s.length) {
@@ -230,19 +230,26 @@ interface HelpRow {
 }
 
 /** Renders a free-text or notes box with a Unicode border and `title` header. */
-function renderTextBox(title: string, lines: string[], hw: number, color: boolean): string[] {
+function renderTextBox(
+  /** Section title to render in the top border. */
+  title: string,
+  /** Lines of text to display inside the box. */
+  lines: string[],
+  /** Available terminal column width. */
+  hw: number,
+  /** Whether ANSI color styling is enabled. */
+  color: boolean,
+): string[] {
   if (lines.length === 0) return [];
 
   const titleLead = color
     ? style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ")
     : `${kBoxH} ${title} `;
 
-  let contentWidth = visibleWidth(titleLead) + 1;
+  let contentWidth = Math.max(visibleWidth(titleLead) + 1, hw - 4);
   for (const line of lines) {
     contentWidth = Math.max(contentWidth, visibleWidth(line));
   }
-  contentWidth = Math.max(hw - 2, contentWidth);
-  contentWidth = Math.min(contentWidth, hw - 4);
 
   const borderWidth = contentWidth + 2;
   const headerFill = Math.max(1, borderWidth - visibleWidth(titleLead));
@@ -265,7 +272,16 @@ function renderTextBox(title: string, lines: string[], hw: number, color: boolea
 }
 
 /** Renders a two-column label/description table in a box (options, subcommands, positionals). */
-function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boolean): string[] {
+function renderTableBox(
+  /** Section title to render in the top border. */
+  title: string,
+  /** Table rows containing labels and descriptions to format. */
+  rows: HelpRow[],
+  /** Available terminal column width. */
+  hw: number,
+  /** Whether ANSI color styling is enabled. */
+  color: boolean,
+): string[] {
   if (rows.length === 0) return [];
 
   let labelWidth = 0;
@@ -273,10 +289,15 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     labelWidth = Math.max(labelWidth, visibleWidth(row.label));
   }
 
-  const titleChunk = `${kBoxH} ${title} `;
-  const minimumContentWidth = Math.max(visibleWidth(titleChunk) + 1, labelWidth + 2 + 18);
-  let contentWidth = Math.max(hw - 2, minimumContentWidth);
-  const descWidth = Math.max(1, contentWidth - labelWidth - 2);
+  let titleLead: string;
+  if (color) {
+    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
+  } else {
+    titleLead = `${kBoxH} ${title} `;
+  }
+
+  const targetContentWidth = Math.max(visibleWidth(titleLead) + 1, hw - 4);
+  const descWidth = Math.max(1, targetContentWidth - labelWidth - 2);
 
   const bodyLines: string[] = [];
   for (const row of rows) {
@@ -289,18 +310,10 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     }
   }
 
-  let titleLead: string;
-  if (color) {
-    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
-  } else {
-    titleLead = `${kBoxH} ${title} `;
-  }
-
-  contentWidth = Math.max(contentWidth, visibleWidth(titleLead) + 1);
+  let contentWidth = targetContentWidth;
   for (const line of bodyLines) {
     contentWidth = Math.max(contentWidth, visibleWidth(line));
   }
-  contentWidth = Math.min(contentWidth, hw - 4);
 
   const borderWidth = contentWidth + 2;
   const headerFill = Math.max(1, borderWidth - visibleWidth(titleLead));

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 });
+  }
+}