argsbarg 4.0.4 → 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);
@@ -72,6 +74,17 @@ describe("claude plugin", () => {
       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,6 +12,7 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
@@ -22,7 +23,7 @@ import { applyPluginSkillHint } from "../skill/hint.ts";
 import type { CliMcpBundleConfig, CliProgram } from "../types.ts";
 import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
 import { mcpServerId } from "./tools.ts";
-import { zipStore } from "./zip.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;
 }

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 () => {

package/src/parse.test.ts

@@ -614,7 +614,7 @@ test("cliSchemaExport resolves program key in install notes", () => {
 
   const json = cliSchemaJson(root);
   expect(json).not.toContain("{argsbarg:program}");
-  expect(json).toContain("myapp install --all --yes");
+  expect(json).toContain("myapp install --yes");
 });
 
 test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
@@ -1124,6 +1124,17 @@ test("install config on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
 });
 
+test("install.prefix is rejected", () => {
+  const root = {
+    key: "app",
+    version: "0.0.0",
+    description: "",
+    install: { prefix: "/opt/bin" },
+    handler: () => {},
+  } as unknown as CliProgram;
+  expect(() => cliValidateProgram(root)).toThrow(/install\.prefix removed/);
+});
+
 test("generateSkillBundle includes frontmatter and compact command index", () => {
   const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
   expect(bundle.dirName).toBe("nested_ts");

package/src/paths/host.ts

@@ -21,20 +21,20 @@ export function expandTilde(path: string): string {
   return path;
 }
 
+/** Display path using `~/` when under the user home directory. */
+export function displayHomePath(absolutePath: string, home = userHome()): string {
+  if (home.length > 0 && absolutePath.startsWith(home)) {
+    return `~${absolutePath.slice(home.length)}`;
+  }
+  return absolutePath;
+}
+
 /** XDG config base directory (`$XDG_CONFIG_HOME` or `~/.config`). */
 export function xdgConfigHome(home = userHome()): string {
   return process.env.XDG_CONFIG_HOME ?? join(home, ".config");
 }
 
-/** Windows `%APPDATA%` (or `~/AppData/Roaming`). */
-export function appDataHome(home = userHome()): string {
-  return process.env.APPDATA ?? join(home, "AppData", "Roaming");
-}
-
-/** OS-appropriate base directory for app config files. */
-export function appConfigHome(home = userHome()): string {
-  if (process.platform === "win32") {
-    return appDataHome(home);
-  }
-  return xdgConfigHome(home);
+/** App config library root (`~/.local/lib`). */
+export function appConfigLibHome(home = userHome()): string {
+  return join(home, ".local", "lib");
 }

package/src/paths/remove-empty-dir.ts

@@ -0,0 +1,13 @@
+import { existsSync, readdirSync, rmdirSync } from "node:fs";
+
+/** Removes a directory when it exists and is empty. Returns true when removed. */
+export function removeEmptyDir(path: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    if (readdirSync(path).length > 0) return false;
+    rmdirSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/skill/generate.ts

@@ -13,8 +13,10 @@ import {
 } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
+import type { SkillTarget } from "./naming.ts";
+import { skillDirNameForTarget, skillFrontmatterName } from "./naming.ts";
 
-export type SkillTarget = "cursor" | "claude";
+export type { SkillTarget } from "./naming.ts";
 
 export interface SkillBundle {
   dirName: string;
@@ -103,7 +105,7 @@ function buildConfigurationSection(root: CliProgram): string[] {
 
 /** Builds SKILL.md body for the given target. */
 function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
-  const name = sanitizeToolSegment(root.key);
+  const name = skillFrontmatterName(root.key, target);
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
 
@@ -161,7 +163,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       "Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).",
       "",
     );
-  } else {
+  } else if (target === "claude") {
     lines.push(
       "## Claude Code",
       "",
@@ -171,6 +173,18 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       `- Bundled files in this directory are available via \`\${CLAUDE_SKILL_DIR}\` when the skill runs.`,
       "",
     );
+  } else if (target === "codex") {
+    lines.push(
+      "## Codex",
+      "",
+      `- Global: \`~/.codex/skills/${dirName}/\``,
+      "- Enable skills in `~/.codex/config.toml` if required.",
+      "",
+    );
+  } else if (target === "opencode") {
+    lines.push("## OpenCode", "", `- Global: \`~/.config/opencode/skills/${dirName}/\``, "");
+  } else {
+    lines.push("## OpenClaw", "", `- Global: \`~/.openclaw/skills/${dirName}/\``, "");
   }
 
   return lines.join("\n");
@@ -231,7 +245,7 @@ export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
 
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */
 export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
-  const dirName = sanitizeToolSegment(root.key);
+  const dirName = skillDirNameForTarget(root.key, target);
   return {
     dirName,
     skillMd: buildSkillMd(root, target, dirName),