argsbarg 1.4.2 → 1.5.0

package/src/index.test.ts

@@ -19,12 +19,14 @@ import {
 } from "./mcp/tools.ts";
 import { applyShellEnv, loadEnvFile } from "./mcp/env.ts";
 import { buildToolCallSuccess } from "./mcp/result.ts";
+import { generateSkillBundle } from "./skill/generate.ts";
+import { cliSkillInstall } from "./skill/install.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
 import { cliValidateRoot } from "./validate.ts";
 import { expect, test } from "bun:test";
 import { $ } from "bun";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -775,6 +777,7 @@ test("collectMcpTools lists user leaf commands only", () => {
   expect(names).toContain("stat_owner_lookup");
   expect(names).toContain("read");
   expect(names).not.toContain("hidden");
+  expect(names).not.toContain("install");
   expect(names).not.toContain("mcp");
   expect(names).not.toContain("completion");
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -807,18 +810,49 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
-test("reserved command name mcp is rejected", () => {
+test("reserved command name install is rejected", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
     commands: [
       {
-        key: "mcp",
+        key: "install",
         description: "bad",
         handler: () => {},
       },
     ],
   };
+  expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: install/);
+});
+
+test("top-level command name mcp is allowed without mcpServer", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "mcp",
+        description: "user command",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).not.toThrow();
+});
+
+test("top-level command name mcp is rejected when mcpServer is set", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    mcpServer: {},
+    commands: [
+      {
+        key: "mcp",
+        description: "user command",
+        handler: () => {},
+      },
+    ],
+  };
   expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: mcp/);
 });
 
@@ -1000,7 +1034,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");
+  expect(stderr.toString()).toContain("MCP is not enabled");
 });
 
 test("ctx.invocation is cli via cliRun", async () => {
@@ -1634,4 +1668,101 @@ test("mcpToolCallToArgv empty string varargs appends nothing", () => {
   const read = tools.find((t) => t.name === "read")!;
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "" });
   expect(argv).toEqual(["read"]);
+});
+
+// ── Skills ────────────────────────────────────────────────────────────────────
+
+test("install config on non-root node is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "",
+        install: { enabled: false },
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/install is only supported on the program root/);
+});
+
+test("generateSkillBundle includes frontmatter and command catalog", () => {
+  const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
+  expect(bundle.dirName).toBe("nested_ts");
+  expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
+  expect(bundle.skillMd).toContain("stat owner lookup");
+  expect(bundle.skillMd).toContain("nested.ts mcp");
+  expect(bundle.referenceMd).toContain("```json");
+  expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
+});
+
+test("cliSkillInstall writes project Cursor skill files", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  try {
+    const files = cliSkillInstall(nestedMcpFixture, "cursor", { rimraf: true });
+    expect(files.some((f) => f.includes(".cursor/skills/nested_ts/"))).toBe(true);
+    const skillDir = join(cwd, ".cursor", "skills", "nested_ts");
+    expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
+    expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("stat owner lookup");
+  } finally {
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test("cliSkillInstall global uses HOME skills directory", () => {
+  const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
+  const prevHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    const files = cliSkillInstall(nestedMcpFixture, "cursor", { global: true, rimraf: true });
+    expect(files.some((f) => f.includes(join(home, ".cursor", "skills", "nested_ts")))).toBe(true);
+    expect(existsSync(join(home, ".cursor", "skills", "nested_ts", "SKILL.md"))).toBe(true);
+  } finally {
+    if (prevHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = prevHome;
+    }
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("cliSkillInstall rimraf overwrites existing directory", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-dup-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  try {
+    cliSkillInstall(nestedMcpFixture, "cursor", { rimraf: true });
+    writeFileSync(join(cwd, ".cursor", "skills", "nested_ts", "SKILL.md"), "stale", "utf8");
+    const files = cliSkillInstall(nestedMcpFixture, "cursor", { rimraf: true });
+    expect(files.length).toBeGreaterThan(0);
+    expect(readFileSync(join(cwd, ".cursor", "skills", "nested_ts", "SKILL.md"), "utf8")).toContain(
+      "stat owner lookup",
+    );
+  } finally {
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test("cliSkillInstall claude target uses .claude/skills", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-claude-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  try {
+    const files = cliSkillInstall(nestedMcpFixture, "claude", { rimraf: true });
+    expect(files.some((f) => f.includes(".claude/skills/nested_ts/"))).toBe(true);
+    expect(readFileSync(join(cwd, ".claude", "skills", "nested_ts", "SKILL.md"), "utf8")).toContain(
+      "Claude Code",
+    );
+  } finally {
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
 });

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   CliMcpResource,
   CliMcpServerConfig,
   CliMcpToolConfig,
+  CliInstallConfig,
   CliOption,
   CliPositional,
 } from "./types.ts";

package/src/install/binary.ts

@@ -0,0 +1,82 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CliCommand } from "../types.ts";
+import { InstallPaths } from "./paths.ts";
+import {
+  buildPathRcBlock,
+  buildZshFpathRcBlock,
+  detectShells,
+  hasRcBlock,
+  removeRcBlock,
+} from "./shell.ts";
+
+export interface BinaryInstallResult {
+  changedFiles: string[];
+  patchedBashRc: boolean;
+  patchedZshRc: boolean;
+}
+
+/** Copies the running binary to the install path and patches rc files when shells are detected. */
+export function installBinary(root: CliCommand, paths: InstallPaths, dry: boolean): BinaryInstallResult {
+  const changed: string[] = [];
+  const shells = detectShells();
+  let patchedBashRc = false;
+  let patchedZshRc = false;
+
+  if (!dry) {
+    mkdirSync(paths.bindir, { recursive: true });
+    copyFileSync(process.execPath, paths.binaryPath);
+  }
+  changed.push(paths.binaryPath);
+
+  if (shells.bash && existsSync(dirname(paths.bashRc))) {
+    const block = buildPathRcBlock(root.key, paths.bindir);
+    let content = existsSync(paths.bashRc) ? readFileSync(paths.bashRc, "utf8") : "";
+    if (!hasRcBlock(content, root.key, "path")) {
+      if (!content.endsWith("\n") && content.length > 0) content += "\n";
+      content += block + "\n";
+      if (!dry) writeFileSync(paths.bashRc, content, "utf8");
+      changed.push(paths.bashRc);
+      patchedBashRc = true;
+    }
+  }
+
+  if (shells.zsh) {
+    const completionsDir = join(dirname(paths.zshCompletion));
+    const block = buildZshFpathRcBlock(root.key, completionsDir);
+    let content = existsSync(paths.zshRc) ? readFileSync(paths.zshRc, "utf8") : "";
+    if (!hasRcBlock(content, root.key, "fpath")) {
+      if (!content.endsWith("\n") && content.length > 0) content += "\n";
+      content += block + "\n";
+      if (!dry) writeFileSync(paths.zshRc, content, "utf8");
+      changed.push(paths.zshRc);
+      patchedZshRc = true;
+    }
+  }
+
+  return { changedFiles: changed, patchedBashRc, patchedZshRc };
+}
+
+/** Removes binary and rc marker blocks. */
+export function uninstallBinary(root: CliCommand, paths: InstallPaths, dry: boolean): string[] {
+  const changed: string[] = [];
+  if (existsSync(paths.binaryPath)) {
+    if (!dry) unlinkSync(paths.binaryPath);
+    changed.push(paths.binaryPath);
+  }
+
+  for (const [rcPath, tag] of [
+    [paths.bashRc, "path"],
+    [paths.zshRc, "fpath"],
+  ] as const) {
+    if (!existsSync(rcPath)) continue;
+    const content = readFileSync(rcPath, "utf8");
+    if (hasRcBlock(content, root.key, tag)) {
+      const next = removeRcBlock(content, root.key, tag);
+      if (!dry) writeFileSync(rcPath, next, "utf8");
+      changed.push(rcPath);
+    }
+  }
+
+  return changed;
+}

package/src/install/compiled.ts

@@ -0,0 +1,15 @@
+/** Test override: when set, `isCompiledExecutable()` returns this value instead of checking Bun.embeddedFiles. */
+let compiledOverride: boolean | null = null;
+
+/** @internal For tests only. */
+export function setCompiledExecutableOverride(value: boolean | null): void {
+  compiledOverride = value;
+}
+
+/** True when running as a `bun build --compile` binary (embedded files present). */
+export function isCompiledExecutable(): boolean {
+  if (compiledOverride !== null) {
+    return compiledOverride;
+  }
+  return (Bun.embeddedFiles?.length ?? 0) > 0;
+}

package/src/install/completions.ts

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { CliCommand } from "../types.ts";
+import { completionBashScript, completionFishScript, completionZshScript } from "../builtins/index.ts";
+import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { InstallPaths } from "./paths.ts";
+import { detectShells } from "./shell.ts";
+
+/** Writes shell completion scripts for detected shells. */
+export function installCompletions(root: CliCommand, paths: InstallPaths, dry: boolean): string[] {
+  const changed: string[] = [];
+  const shells = detectShells();
+  const schema = cliPresentationRoot(root);
+
+  if (shells.bash) {
+    if (!dry) {
+      mkdirSync(dirname(paths.bashCompletion), { recursive: true });
+      writeFileSync(paths.bashCompletion, completionBashScript(schema), "utf8");
+    }
+    changed.push(paths.bashCompletion);
+  }
+
+  if (shells.zsh) {
+    if (!dry) {
+      mkdirSync(dirname(paths.zshCompletion), { recursive: true });
+      writeFileSync(paths.zshCompletion, completionZshScript(schema), "utf8");
+    }
+    changed.push(paths.zshCompletion);
+  }
+
+  if (shells.fish) {
+    if (!dry) {
+      mkdirSync(dirname(paths.fishCompletion), { recursive: true });
+      writeFileSync(paths.fishCompletion, completionFishScript(schema), "utf8");
+    }
+    changed.push(paths.fishCompletion);
+  }
+
+  return changed;
+}
+
+/** Removes shell completion files. */
+export function uninstallCompletions(paths: InstallPaths, dry: boolean): string[] {
+  const changed: string[] = [];
+  for (const p of [paths.bashCompletion, paths.zshCompletion, paths.fishCompletion]) {
+    if (existsSync(p)) {
+      if (!dry) unlinkSync(p);
+      changed.push(p);
+    }
+  }
+  return changed;
+}

package/src/install/detect-installed.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import { CliCommand } from "../types.ts";
+import { InstallPaths } from "./paths.ts";
+
+export interface InstalledArtifacts {
+  binary: boolean;
+  bashCompletion: boolean;
+  zshCompletion: boolean;
+  fishCompletion: boolean;
+  cursorSkill: boolean;
+  claudeSkill: boolean;
+  cursorMcp: boolean;
+  claudeMcp: boolean;
+  bashRcPath: boolean;
+  zshRcFpath: boolean;
+}
+
+function mcpConfigHasServer(path: string, name: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8")) as { mcpServers?: Record<string, unknown> };
+    return data.mcpServers?.[name] !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/** Detects which install artifacts are currently present. */
+export function detectInstalledArtifacts(paths: InstallPaths): InstalledArtifacts {
+  return {
+    binary: existsSync(paths.binaryPath),
+    bashCompletion: existsSync(paths.bashCompletion),
+    zshCompletion: existsSync(paths.zshCompletion),
+    fishCompletion: existsSync(paths.fishCompletion),
+    cursorSkill: existsSync(paths.cursorSkillDir),
+    claudeSkill: existsSync(paths.claudeSkillDir),
+    cursorMcp: mcpConfigHasServer(paths.cursorMcpPath, paths.mcpName),
+    claudeMcp: mcpConfigHasServer(paths.claudeMcpPath, paths.mcpName),
+    bashRcPath: false,
+    zshRcFpath: false,
+  };
+}
+
+export interface InstallStatus {
+  binary?: string;
+  bashCompletion?: string;
+  zshCompletion?: string;
+  fishCompletion?: string;
+  cursorSkill?: string;
+  claudeSkill?: string;
+  cursorMcp?: string;
+  claudeMcp?: string;
+}
+
+/** Builds a status inventory from detected artifacts. */
+export function buildInstallStatus(paths: InstallPaths, detected: InstalledArtifacts): InstallStatus {
+  const status: InstallStatus = {};
+  if (detected.binary) status.binary = paths.binaryPath;
+  if (detected.bashCompletion) status.bashCompletion = paths.bashCompletion;
+  if (detected.zshCompletion) status.zshCompletion = paths.zshCompletion;
+  if (detected.fishCompletion) status.fishCompletion = paths.fishCompletion;
+  if (detected.cursorSkill) status.cursorSkill = paths.cursorSkillDir + "/";
+  if (detected.claudeSkill) status.claudeSkill = paths.claudeSkillDir + "/";
+  if (detected.cursorMcp) status.cursorMcp = `${paths.cursorMcpPath} (server "${paths.mcpName}")`;
+  if (detected.claudeMcp) status.claudeMcp = `${paths.claudeMcpPath} (server "${paths.mcpName}")`;
+  return status;
+}

package/src/install/index.ts

@@ -0,0 +1,196 @@
+import { readSync } from "node:fs";
+import { CliCommand } from "../types.ts";
+import { cliSkillInstall } from "../skill/install.ts";
+import { checkMcpConflict, expectedMcpEntry } from "./mcp-config.ts";
+import {
+  buildInstallPlan,
+  buildUpdatePlan,
+  type InstallAction,
+  type InstallOpts,
+} from "./plan.ts";
+import { resolveInstallPaths } from "./paths.ts";
+import { installErr, installInfo, installOut, printInstallStatus } from "./status.ts";
+import { buildUninstallPlan, uninstallSkillDir, type UninstallAction } from "./uninstall.ts";
+
+function parseInstallOpts(raw: Record<string, string>): InstallOpts {
+  const flag = (name: string) => raw[name] === "1";
+  return {
+    all: flag("all"),
+    bin: flag("bin"),
+    completions: flag("completions"),
+    skill: flag("skill"),
+    mcp: flag("mcp"),
+    update: flag("update"),
+    status: flag("status"),
+    uninstall: flag("uninstall"),
+    yes: flag("yes"),
+    dry: flag("dry"),
+    json: flag("json"),
+    quiet: flag("quiet"),
+    prefix: raw.prefix,
+  };
+}
+
+function validateOpts(opts: InstallOpts): string | null {
+  if (opts.quiet && opts.dry) {
+    return "--quiet cannot be combined with --dry.";
+  }
+  if (opts.quiet && !opts.yes && !opts.json && !opts.update) {
+    return "--quiet requires --yes (or --json / --update).";
+  }
+  if (opts.json) {
+    opts.yes = true;
+  }
+  if (opts.update) {
+    opts.bin = true;
+    opts.yes = true;
+  }
+
+  const mutationFlags = opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.update || opts.uninstall;
+  if (opts.status && mutationFlags) {
+    return "--status is mutually exclusive with install/update/uninstall targets.";
+  }
+  if (opts.update && (opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.uninstall || opts.status)) {
+    return "--update cannot be combined with other target flags.";
+  }
+  if (opts.uninstall && (opts.all || opts.update || opts.status)) {
+    return "--uninstall cannot be combined with --all, --update, or --status.";
+  }
+  if (!opts.status && !opts.update && !opts.uninstall) {
+    const hasTarget = opts.all || opts.bin || opts.completions || opts.skill || opts.mcp;
+    if (!hasTarget) {
+      return "Specify at least one target: --all, --bin, --completions, --skill, or --mcp.";
+    }
+  }
+  return null;
+}
+
+function promptConfirm(): boolean {
+  process.stderr.write("Continue? [y/N] ");
+  const buf = Buffer.alloc(256);
+  const n = readSync(0, buf, { length: 256 });
+  const ans = buf.toString("utf8", 0, n).trim();
+  return ans === "y" || ans === "Y";
+}
+
+function runSkillAction(
+  root: CliCommand,
+  kind: "cursor-skill" | "claude-skill",
+  opts: InstallOpts,
+): string[] {
+  const target = kind === "cursor-skill" ? "cursor" : "claude";
+  return cliSkillInstall(root, target, {
+    global: true,
+    rimraf: true,
+    dry: opts.dry,
+  });
+}
+
+function executePlan(
+  root: CliCommand,
+  actions: Array<InstallAction | UninstallAction>,
+  opts: InstallOpts,
+): string[] {
+  const changed: string[] = [];
+  for (const action of actions) {
+    installInfo(action.message, opts);
+    if ("kind" in action && (action.kind === "cursor-skill" || action.kind === "claude-skill")) {
+      changed.push(...runSkillAction(root, action.kind, opts));
+      continue;
+    }
+    if (!("kind" in action) && action.summary.startsWith("cursor skill")) {
+      const paths = resolveInstallPaths(root, opts);
+      changed.push(...uninstallSkillDir(paths.cursorSkillDir, !!opts.dry));
+      continue;
+    }
+    if (!("kind" in action) && action.summary.startsWith("claude skill")) {
+      const paths = resolveInstallPaths(root, opts);
+      changed.push(...uninstallSkillDir(paths.claudeSkillDir, !!opts.dry));
+      continue;
+    }
+    changed.push(...action.run());
+  }
+  return changed;
+}
+
+/** Main install command orchestrator. */
+export async function cliInstall(root: CliCommand, rawOpts: Record<string, string>): Promise<never> {
+  const opts = parseInstallOpts(rawOpts);
+  const err = validateOpts(opts);
+  if (err) {
+    installErr(err);
+    process.exit(1);
+  }
+
+  const paths = resolveInstallPaths(root, opts);
+
+  if (opts.status) {
+    printInstallStatus(root, opts);
+    process.exit(0);
+  }
+
+  // MCP conflict checks before planning
+  if (!opts.uninstall && root.mcpServer && (opts.all || opts.mcp)) {
+    const entry = expectedMcpEntry(root);
+    const yes = !!opts.yes;
+    for (const p of [paths.cursorMcpPath, paths.claudeMcpPath]) {
+      const conflict = checkMcpConflict(p, paths.mcpName, entry, yes);
+      if (conflict) {
+        installErr(conflict);
+        process.exit(1);
+      }
+    }
+  }
+
+  let actions: Array<InstallAction | UninstallAction>;
+  if (opts.uninstall) {
+    actions = buildUninstallPlan(root, paths, opts);
+  } else if (opts.update) {
+    actions = buildUpdatePlan(root, paths, opts);
+  } else {
+    actions = buildInstallPlan(root, paths, opts);
+  }
+
+  if (actions.length === 0) {
+    installErr("Nothing to do.");
+    process.exit(1);
+  }
+
+  if (!opts.quiet && !opts.json) {
+    installOut("About to " + (opts.uninstall ? "remove" : opts.update ? "update" : "install") + ":", opts);
+    for (const a of actions) {
+      installOut("  - " + a.summary, opts);
+    }
+  }
+
+  const autoYes = opts.yes || opts.json || opts.update;
+  if (!autoYes) {
+    if (!process.stdin.isTTY) {
+      installErr("Refusing to proceed without --yes (stdin is not a TTY).");
+      process.exit(1);
+    }
+    if (!promptConfirm()) {
+      installErr("Aborted.");
+      process.exit(1);
+    }
+  }
+
+  const changed = executePlan(root, actions, opts);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(changed, null, 2) + "\n");
+    process.exit(0);
+  }
+
+  if (!opts.quiet && changed.length > 0) {
+    const verb = opts.uninstall ? "Removed" : opts.update ? "Updated" : "Installed";
+    installOut(`${verb} ${changed.length} file(s).`, opts);
+    if (!opts.uninstall && (opts.all || opts.bin) && changed.some((p) => p === paths.bashRc || p === paths.zshRc || p === paths.binaryPath)) {
+      installOut("Open a new shell, or run: hash -r (bash) / rehash (zsh)", opts);
+    }
+  }
+
+  process.exit(0);
+}
+
+export { parseInstallOpts };