argsbarg 4.0.3 → 4.1.0

package/src/install/uninstall.ts

@@ -1,164 +1,19 @@
 import { existsSync, rmSync } from "node:fs";
-import { resolveAppConfigPath, uninstallAppConfig } from "../config/file.ts";
 import type { CliProgram } from "../types.ts";
-import { uninstallBinary } from "./binary.ts";
-import { uninstallCompletions } from "./completions.ts";
-import { detectInstalledArtifacts } from "./detect-installed.ts";
-import { removeCodexMcpConfig } from "./mcp-codex.ts";
-import { removeMcpConfig } from "./mcp-config.ts";
-import { detectOpenCodeMcpConfigPath, removeOpenCodeMcpConfig } from "./mcp-opencode.ts";
-import { type InstallPaths, userHome } from "./paths.ts";
-import {
-  type InstallOpts,
-  wantsInstallBin,
-  wantsInstallCompletions,
-  wantsInstallMcp,
-  wantsInstallSkill,
-  wantsUninstallConfig,
-} from "./plan.ts";
+import type { InstallPaths } from "./paths.ts";
+import { buildUninstallPlanFromTargets } from "./target-plan-build.ts";
+import { skillTargetForUninstallSummary } from "./target-registry.ts";
+import type { InstallOpts, UninstallAction } from "./target-types.ts";
 
-export interface UninstallAction {
-  summary: string;
-  message: string;
-  run: () => string[];
-}
+export type { InstallActionKind, InstallOpts, UninstallAction } from "./target-types.ts";
 
-/** Builds uninstall actions for scoped targets (--all mirrors install --all). */
+/** Builds uninstall actions for scoped targets or --all (ignores install.targets on --all). */
 export function buildUninstallPlan(
   root: CliProgram,
   paths: InstallPaths,
   opts: InstallOpts,
 ): UninstallAction[] {
-  const detected = detectInstalledArtifacts(paths);
-  const dry = !!opts.dry;
-  const actions: UninstallAction[] = [];
-
-  if (wantsInstallBin(opts) && detected.binary) {
-    actions.push({
-      summary: `binary: ${paths.binaryPath}`,
-      message: `Removing binary ${paths.binaryPath}`,
-      run: () => uninstallBinary(root, paths, dry),
-    });
-  }
-
-  if (
-    wantsInstallCompletions(opts) &&
-    (detected.bashCompletion || detected.zshCompletion || detected.fishCompletion)
-  ) {
-    if (detected.bashCompletion) {
-      actions.push({
-        summary: `bash completion: ${paths.bashCompletion}`,
-        message: `Removing bash completion ${paths.bashCompletion}`,
-        run: () => uninstallCompletions(paths, dry).filter((p) => p === paths.bashCompletion),
-      });
-    }
-    if (detected.zshCompletion) {
-      actions.push({
-        summary: `zsh completion: ${paths.zshCompletion}`,
-        message: `Removing zsh completion ${paths.zshCompletion}`,
-        run: () => uninstallCompletions(paths, dry).filter((p) => p === paths.zshCompletion),
-      });
-    }
-    if (detected.fishCompletion) {
-      actions.push({
-        summary: `fish completion: ${paths.fishCompletion}`,
-        message: `Removing fish completion ${paths.fishCompletion}`,
-        run: () => uninstallCompletions(paths, dry).filter((p) => p === paths.fishCompletion),
-      });
-    }
-  }
-
-  if (wantsInstallSkill(opts) && detected.cursorSkill) {
-    actions.push({
-      summary: `cursor skill: ${paths.cursorSkillDir}/`,
-      message: `Removing Cursor skill ${paths.cursorSkillDir}/`,
-      run: () => [],
-    });
-  }
-
-  if (wantsInstallSkill(opts) && detected.claudeSkill) {
-    actions.push({
-      summary: `claude skill: ${paths.claudeSkillDir}/`,
-      message: `Removing Claude Code skill ${paths.claudeSkillDir}/`,
-      run: () => [],
-    });
-  }
-
-  if (wantsInstallMcp(opts, root)) {
-    if (detected.cursorMcp) {
-      actions.push({
-        summary: `cursor mcp: ${paths.cursorMcpPath}`,
-        message: `Removing MCP server "${paths.mcpName}" from ${paths.cursorMcpPath}`,
-        run: () => {
-          removeMcpConfig(paths.cursorMcpPath, paths.mcpName, dry);
-          return [paths.cursorMcpPath];
-        },
-      });
-    }
-    if (detected.claudeMcp) {
-      actions.push({
-        summary: `claude code mcp: ${paths.claudeMcpPath}`,
-        message: `Removing MCP server "${paths.mcpName}" from ${paths.claudeMcpPath}`,
-        run: () => {
-          removeMcpConfig(paths.claudeMcpPath, paths.mcpName, dry);
-          return [paths.claudeMcpPath];
-        },
-      });
-    }
-    if (detected.claudeDesktopMcp) {
-      actions.push({
-        summary: `claude desktop mcp: ${paths.claudeDesktopMcpPath}`,
-        message: `Removing MCP server "${paths.mcpName}" from ${paths.claudeDesktopMcpPath}`,
-        run: () => {
-          removeMcpConfig(paths.claudeDesktopMcpPath, paths.mcpName, dry);
-          return [paths.claudeDesktopMcpPath];
-        },
-      });
-    }
-    if (detected.opencodeMcp) {
-      const openCodePath =
-        detectOpenCodeMcpConfigPath(userHome(), paths.mcpName) ?? paths.opencodeMcpPath;
-      actions.push({
-        summary: `opencode mcp: ${openCodePath}`,
-        message: `Removing MCP server "${paths.mcpName}" from ${openCodePath}`,
-        run: () => {
-          removeOpenCodeMcpConfig(openCodePath, paths.mcpName, dry);
-          return [openCodePath];
-        },
-      });
-    }
-    if (detected.codexMcp) {
-      actions.push({
-        summary: `codex mcp: ${paths.codexConfigPath}`,
-        message: `Removing MCP server "${paths.mcpName}" from Codex via codex mcp remove`,
-        run: () => {
-          removeCodexMcpConfig(userHome(), paths.mcpName, dry);
-          return [paths.codexConfigPath];
-        },
-      });
-    }
-    if (detected.chatGptMcp) {
-      actions.push({
-        summary: `chatgpt desktop mcp: ${paths.chatGptMcpPath}`,
-        message: `Removing MCP server "${paths.mcpName}" from ${paths.chatGptMcpPath}`,
-        run: () => {
-          removeMcpConfig(paths.chatGptMcpPath, paths.mcpName, dry);
-          return [paths.chatGptMcpPath];
-        },
-      });
-    }
-  }
-
-  if (wantsUninstallConfig(opts, root)) {
-    const configPath = resolveAppConfigPath(root);
-    actions.push({
-      summary: `app config: ${configPath}`,
-      message: `Removing app config ${configPath}`,
-      run: () => (uninstallAppConfig(root, dry) ? [configPath] : []),
-    });
-  }
-
-  return actions;
+  return buildUninstallPlanFromTargets(root, paths, opts);
 }
 
 /** Rimraf skill directories during uninstall. */
@@ -167,3 +22,12 @@ export function uninstallSkillDir(dir: string, dry: boolean): string[] {
   if (!dry) rmSync(dir, { recursive: true, force: true });
   return [`${dir}/`];
 }
+
+/** Skill directory for uninstall action summary prefix. */
+export function skillDirFromUninstallSummary(
+  summary: string,
+  paths: InstallPaths,
+): string | undefined {
+  const target = skillTargetForUninstallSummary(summary);
+  return target?.skillDir(paths);
+}

package/src/install/update.test.ts

@@ -1,5 +1,13 @@
 import { afterEach, beforeEach, expect, test } from "bun:test";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
@@ -68,10 +76,13 @@ test("runInstallMutation honors --from for binary copy", async () => {
   writeFileSync(source, "#!/bin/sh\necho hi\n", "utf8");
   chmodSync(source, 0o755);
 
+  const bindir = join(home, ".local", "bin");
+  mkdirSync(bindir, { recursive: true });
+  writeFileSync(join(bindir, "testapp"), "old\n", "utf8");
+
   const { changed } = await runInstallMutation(root, {
     reinstall: "1",
     yes: "1",
-    quiet: "1",
     from: source,
   });
 
@@ -90,6 +101,10 @@ test("Cli.invoke install --update uses hook and reinstalls", async () => {
     version: "2.0.0",
   }));
 
+  const bindir = join(home, ".local", "bin");
+  mkdirSync(bindir, { recursive: true });
+  writeFileSync(join(bindir, "testapp"), "old\n", "utf8");
+
   const result = await new Cli(root).invoke(["install", "--update"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Updated testapp 1.0.0 → 2.0.0");

package/src/install/update.ts

@@ -7,9 +7,7 @@ import { installErr } from "./status.ts";
 export async function cliUpdate(root: CliProgram): Promise<never> {
   const hook = root.install?.updateGetLatest;
   if (!hook) {
-    installErr(
-      "install --update is not configured. Set install.updateGetLatest on the program root.",
-    );
+    installErr("Remote updates are not supported by this app.");
     process.exit(1);
   }
 
@@ -23,7 +21,7 @@ export async function cliUpdate(root: CliProgram): Promise<never> {
   }
 
   if (!artifact.path || !existsSync(artifact.path)) {
-    installErr(`updateGetLatest returned missing binary: ${JSON.stringify(artifact.path)}`);
+    installErr("Update download did not return a valid app binary.");
     process.exit(1);
   }
 
@@ -38,7 +36,6 @@ export async function cliUpdate(root: CliProgram): Promise<never> {
     await runInstallMutation(root, {
       reinstall: "1",
       yes: "1",
-      quiet: "1",
       from: artifact.path,
     });
   } catch (err) {

package/src/invoke.test.ts

@@ -16,7 +16,13 @@ test("ctx.invocation is cli via Cli.run", async () => {
   const indexPath = join(import.meta.dir, "index.ts");
   const { stdout } = await $`bun -e ${`
 import { Cli, CliProgram } from ${JSON.stringify(indexPath)};
-const program = { key: "t", description: "d", version: "0.0.0", handler: (ctx) => console.log(ctx.invocation) };
+const program = {
+  key: "t",
+  description: "d",
+  version: "0.0.0",
+  install: { enabled: false },
+  handler: (ctx) => console.log(ctx.invocation),
+};
 await new Cli(program).run([]);
   `}`.quiet();
   expect(stdout.toString().trim()).toBe("cli");

package/src/mcp/bundle.ts

@@ -160,9 +160,21 @@ export function packMcpBundle(program: CliProgram, opts: PackMcpBundleOpts = {})
   }
 }
 
-/** Runs `mcp bundle`: writes `.mcpb` and Claude Code plugin zip; prints both paths. */
+/** Runs `mcp bundle`: writes enabled dist artifacts; prints one path per line. */
 export function runMcpBundle(program: CliProgram): void {
-  const mcpbPath = packMcpBundle(program);
-  const pluginPath = packClaudePlugin(program);
-  process.stdout.write(`${mcpbPath}\n${pluginPath}\n`);
+  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.",
+    );
+  }
+
+  const lines: string[] = [];
+  if (mcp.mcpd) {
+    lines.push(packMcpBundle(program));
+  }
+  if (mcp.claudePlugin) {
+    lines.push(packClaudePlugin(program));
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
 }

package/src/mcp/claude.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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 "../types.ts";
@@ -36,6 +37,7 @@ describe("claude plugin", () => {
   test("generatePluginManifest includes userConfig from program.appConfig", () => {
     const manifest = generatePluginManifest(configFixture, "myapp");
     expect(manifest.name).toBe("myapp");
+    expect(manifest.mcpServers).toBe(".mcp.json");
     const userConfig = manifest.userConfig as Record<string, Record<string, unknown>>;
     expect(userConfig.api_token?.description).toBe("Token from settings.");
     expect(userConfig.api_token?.sensitive).toBe(true);
@@ -55,7 +57,7 @@ describe("claude plugin", () => {
     expect(paths.pluginZipPath).toBe(join(cwd, "dist", "claude-plugin", "myapp.zip"));
   });
 
-  test("packClaudePlugin writes zip with expected entries", () => {
+  test("packClaudePlugin writes zip with MCP pointer skill only", () => {
     const work = mkdtempSync(join(tmpdir(), "claude-plugin-test-"));
     try {
       const dist = join(work, "dist");
@@ -64,8 +66,25 @@ describe("claude plugin", () => {
       writeFileSync(binaryPath, "#!/bin/sh\n", { mode: 0o755 });
       const paths = defaultClaudePluginPaths(configFixture, work);
       packClaudePlugin(configFixture, { cwd: work, binaryPath });
-      const zipPath = paths.pluginZipPath;
-      expect(readFileSync(zipPath).length).toBeGreaterThan(0);
+      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");
+      expect(zipText).toContain("Server id: `myapp`");
+      expect(zipText).not.toContain("skills/myapp/reference.md");
+      expect(zipText).not.toContain("Invoke via shell");
+
+      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, ".claude-plugin", "plugin.json"), "utf8"),
+      ) as { mcpServers: string };
+      expect(pluginJson.mcpServers).toBe(".mcp.json");
     } finally {
       rmSync(work, { recursive: true, force: true });
     }

package/src/mcp/claude.ts

@@ -12,17 +12,18 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join, relative, resolve } from "node:path";
 import { buildPluginMcpEnvMapping, buildProgramUserConfig } from "../config/manifest.ts";
-import { generateSkillBundle } from "../skill/generate.ts";
-import { applySkillBundleHints } from "../skill/hint.ts";
+import { generatePluginSkillBundle } from "../skill/generate.ts";
+import { applyPluginSkillHint } from "../skill/hint.ts";
 import type { CliMcpBundleConfig, CliProgram } from "../types.ts";
 import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
-import { mcpServerId, sanitizeToolSegment } from "./tools.ts";
-import { zipStore } from "./zip.ts";
+import { mcpServerId } from "./tools.ts";
+import { type ZipFileEntry, zipStore } from "./zip.ts";
 
 const DIST_DIR = "dist";
 const CLAUDE_PLUGIN_DIR = "claude-plugin";
@@ -67,6 +68,7 @@ export function generatePluginManifest(
     version: program.version,
     description: program.description,
     author: defaultAuthor(bundle),
+    mcpServers: ".mcp.json",
   };
   const userConfig = buildProgramUserConfig(program);
   if (userConfig) {
@@ -93,8 +95,8 @@ export function generatePluginMcpJson(
   };
 }
 
-function collectZipEntries(rootDir: string, dir = rootDir): { name: string; data: Buffer }[] {
-  const entries: { name: string; data: Buffer }[] = [];
+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()) {
@@ -105,7 +107,12 @@ function collectZipEntries(rootDir: string, dir = rootDir): { name: string; data
       continue;
     }
     const rel = relative(rootDir, full).split("\\").join("/");
-    entries.push({ name: rel, data: readFileSync(full) });
+    const stMode = statSync(full).mode;
+    const entry: ZipFileEntry = { name: rel, data: readFileSync(full) };
+    if (stMode & 0o111) {
+      entry.unixMode = stMode;
+    }
+    entries.push(entry);
   }
   return entries;
 }
@@ -116,13 +123,12 @@ function writePluginTree(
   binaryPath: string,
   binaryName: string,
 ): void {
-  const skillDirName = sanitizeToolSegment(program.key);
-  const bundle = generateSkillBundle(program, "claude");
-  const hinted = applySkillBundleHints(program, bundle.skillMd, bundle.referenceMd);
+  const bundle = generatePluginSkillBundle(program);
+  const skillMd = applyPluginSkillHint(program, bundle.skillMd);
 
   mkdirSync(join(pluginRoot, ".claude-plugin"), { recursive: true });
   mkdirSync(join(pluginRoot, "bin"), { recursive: true });
-  mkdirSync(join(pluginRoot, "skills", skillDirName), { recursive: true });
+  mkdirSync(join(pluginRoot, "skills", bundle.dirName), { recursive: true });
 
   writeFileSync(
     join(pluginRoot, ".claude-plugin", "plugin.json"),
@@ -133,8 +139,7 @@ function writePluginTree(
     `${JSON.stringify(generatePluginMcpJson(program, binaryName), null, 2)}\n`,
   );
   cpSync(binaryPath, join(pluginRoot, "bin", binaryName), { mode: 0o755 });
-  writeFileSync(join(pluginRoot, "skills", skillDirName, "SKILL.md"), hinted.skillMd);
-  writeFileSync(join(pluginRoot, "skills", skillDirName, "reference.md"), hinted.referenceMd);
+  writeFileSync(join(pluginRoot, "skills", bundle.dirName, "SKILL.md"), skillMd);
 }
 
 /**

package/src/mcp/tools.ts

@@ -3,6 +3,7 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for Cli.invoke.
 */
 
+import { docsMcpResources } from "../docs/mcp-resources.ts";
 import { cliResolveNotes } from "../help.ts";
 import { visibleOptions } from "../hidden.ts";
 import { collectOptionDefs } from "../parse.ts";
@@ -26,6 +27,8 @@ export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
 }
 
+export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "../docs/mcp-resources.ts";
+
 /** Sanitizes a command key segment for MCP tool names and server identity. */
 export function sanitizeToolSegment(key: string): string {
   return key.replace(/[^a-zA-Z0-9]/g, "_");
@@ -209,7 +212,7 @@ export function allMcpResources(root: CliProgram): McpResourceEntry[] {
     mimeType: r.mimeType ?? "text/plain",
     load: r.load,
   }));
-  return [builtIn, ...user];
+  return [builtIn, ...docsMcpResources(root), ...user];
 }
 
 /** Recursively collects MCP tool definitions from user leaf commands. */

package/src/mcp/zip.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "bun:test";
+import { execSync } from "node:child_process";
+import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { zipStore } from "./zip.ts";
+
+test("zipStore preserves unix executable mode on extract", () => {
+  const work = mkdtempSync(join(tmpdir(), "zip-exec-"));
+  const data = Buffer.from("#!/bin/sh\necho hi\n");
+  const zip = zipStore([{ name: "bin/tool", data, unixMode: 0o100755 }]);
+  writeFileSync(join(work, "plugin.zip"), zip);
+  execSync("unzip -o -q plugin.zip", { cwd: work });
+  const mode = statSync(join(work, "bin", "tool")).mode & 0o777;
+  expect(mode & 0o111).not.toBe(0);
+  expect(readFileSync(join(work, "bin", "tool"), "utf8")).toBe("#!/bin/sh\necho hi\n");
+});

package/src/mcp/zip.ts

@@ -2,6 +2,41 @@
 Minimal ZIP writer (store method, no compression) for MCPB and Claude plugin bundles.
 */
 
+/** Info-ZIP Unix UID/GID extra field (`0x7875`) for permission restore on extract. */
+function unixUxExtraField(uid: number, gid: number): Buffer {
+  const uidBuf = Buffer.alloc(4);
+  uidBuf.writeUInt32LE(uid >>> 0, 0);
+  const gidBuf = Buffer.alloc(4);
+  gidBuf.writeUInt32LE(gid >>> 0, 0);
+  const payload = Buffer.concat([Buffer.from([1, 4]), uidBuf, Buffer.from([4]), gidBuf]);
+  const header = Buffer.alloc(4);
+  header.writeUInt16LE(0x7875, 0);
+  header.writeUInt16LE(payload.length, 2);
+  return Buffer.concat([header, payload]);
+}
+
+/** Info-ZIP Unix permission extra field (`0x7855`). */
+function unixUpExtraField(unixMode: number): Buffer {
+  const payload = Buffer.alloc(5);
+  payload.writeUInt8(1, 0);
+  payload.writeUInt32LE(unixMode >>> 0, 1);
+  const header = Buffer.alloc(4);
+  header.writeUInt16LE(0x7855, 0);
+  header.writeUInt16LE(payload.length, 2);
+  return Buffer.concat([header, payload]);
+}
+
+function unixExtraFields(unixMode: number): Buffer {
+  const { uid, gid } = defaultUnixIds();
+  return Buffer.concat([unixUpExtraField(unixMode), unixUxExtraField(uid, gid)]);
+}
+
+function defaultUnixIds(): { uid: number; gid: number } {
+  const uid = typeof process.getuid === "function" ? process.getuid() : 501;
+  const gid = typeof process.getgid === "function" ? process.getgid() : 20;
+  return { uid, gid };
+}
+
 /** CRC-32 for ZIP local headers. */
 function crc32(data: Buffer): number {
   let crc = 0xffffffff;
@@ -18,8 +53,16 @@ function crc32(data: Buffer): number {
   return (crc ^ 0xffffffff) >>> 0;
 }
 
+/** One file entry for {@link zipStore}. */
+export interface ZipFileEntry {
+  name: string;
+  data: Buffer;
+  /** Unix permission bits (e.g. `0o755`). Encoded in ZIP external attributes when set. */
+  unixMode?: number;
+}
+
 /** Writes a minimal ZIP (store, no compression) with one or more files. */
-export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
+export function zipStore(files: ZipFileEntry[]): Buffer {
   const parts: Buffer[] = [];
   const central: Buffer[] = [];
   let offset = 0;
@@ -27,9 +70,11 @@ export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
   for (const file of files) {
     const nameBuf = Buffer.from(file.name, "utf8");
     const crc = crc32(file.data);
-    const local = Buffer.alloc(30 + nameBuf.length);
+    const unixMode = file.unixMode;
+    const extra = unixMode !== undefined ? unixExtraFields(unixMode) : Buffer.alloc(0);
+    const local = Buffer.alloc(30 + nameBuf.length + extra.length);
     local.writeUInt32LE(0x04034b50, 0);
-    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(unixMode !== undefined ? 10 : 20, 4);
     local.writeUInt16LE(0, 6);
     local.writeUInt16LE(0, 8);
     local.writeUInt16LE(0, 10);
@@ -38,13 +83,15 @@ export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
     local.writeUInt32LE(file.data.length, 18);
     local.writeUInt32LE(file.data.length, 22);
     local.writeUInt32LE(nameBuf.length, 26);
-    local.writeUInt16LE(0, 28);
+    local.writeUInt16LE(extra.length, 28);
     nameBuf.copy(local, 30);
+    extra.copy(local, 30 + nameBuf.length);
 
-    const centralHdr = Buffer.alloc(46 + nameBuf.length);
+    const centralHdr = Buffer.alloc(46 + nameBuf.length + extra.length);
     centralHdr.writeUInt32LE(0x02014b50, 0);
-    centralHdr.writeUInt16LE(20, 4);
-    centralHdr.writeUInt16LE(20, 6);
+    // macOS Info-ZIP stores version made by before version needed (non-APPNOTE layout).
+    centralHdr.writeUInt16LE(unixMode !== undefined ? 0x031e : 20, 4);
+    centralHdr.writeUInt16LE(unixMode !== undefined ? 10 : 20, 6);
     centralHdr.writeUInt16LE(0, 8);
     centralHdr.writeUInt16LE(0, 10);
     centralHdr.writeUInt16LE(0, 12);
@@ -53,13 +100,19 @@ export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
     centralHdr.writeUInt32LE(file.data.length, 20);
     centralHdr.writeUInt32LE(file.data.length, 24);
     centralHdr.writeUInt32LE(nameBuf.length, 28);
-    centralHdr.writeUInt16LE(0, 30);
+    centralHdr.writeUInt16LE(extra.length, 30);
     centralHdr.writeUInt16LE(0, 32);
     centralHdr.writeUInt16LE(0, 34);
     centralHdr.writeUInt16LE(0, 36);
-    centralHdr.writeUInt32LE(0, 38);
+    if (unixMode !== undefined) {
+      const externalAttr = (unixMode << 16) >>> 0;
+      centralHdr.writeUInt32LE(externalAttr, 38);
+    } else {
+      centralHdr.writeUInt32LE(0, 38);
+    }
     centralHdr.writeUInt32LE(offset, 42);
     nameBuf.copy(centralHdr, 46);
+    extra.copy(centralHdr, 46 + nameBuf.length);
 
     parts.push(local, file.data);
     central.push(centralHdr);

package/src/mcp.integration.test.ts

@@ -469,7 +469,7 @@ test("MCP ping returns empty result", async () => {
 test("minimal.ts mcp without opt-in fails", async () => {
   const { stderr, exitCode } = await $`bun run examples/minimal.ts mcp`.nothrow().quiet();
   expect(exitCode).toBe(1);
-  expect(stderr.toString()).toContain("MCP is not enabled");
+  expect(stderr.toString()).toContain("MCP is not available");
 });
 
 test("MCP resources/list includes custom resource", async () => {
@@ -480,9 +480,26 @@ test("MCP resources/list includes custom resource", async () => {
   const res = responses.get(10) as { result: { resources: { uri: string }[] } };
   const uris = res.result.resources.map((r) => r.uri);
   expect(uris).toContain("mcp_test://schema");
+  expect(uris).toContain("mcp_test://docs/readme");
   expect(uris).toContain("test://hello");
 });
 
+test("MCP resources/read returns docs topic resource body", async () => {
+  const responses = await mcpRequest(
+    [
+      {
+        jsonrpc: "2.0",
+        id: 13,
+        method: "resources/read",
+        params: { uri: "mcp_test://docs/readme" },
+      },
+    ],
+    { script: "examples/mcp-test.ts" },
+  );
+  const res = responses.get(13) as { result: { contents: { text: string }[] } };
+  expect(res.result.contents[0]?.text).toBe("# MCP test readme\n");
+});
+
 test("MCP resources/read returns custom resource body", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 11, method: "resources/read", params: { uri: "test://hello" } }],