argsbarg 1.4.3 → 2.0.0

package/src/index.ts

@@ -13,12 +13,13 @@ export { CliContext } from "./context.ts";
 export { cliErrWithHelp, cliRun } from "./runtime";
 export { CliFallbackMode, CliOptionKind, CliSchemaValidationError } from "./types.ts";
 export type {
-  CliCommand,
+  CliProgram,
   CliHandler,
   CliInvocation,
   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 { CliProgram } 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: CliProgram, 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: CliProgram, 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 { CliProgram } 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: CliProgram, 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 { CliProgram } 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 { CliProgram } 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: CliProgram,
+  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: CliProgram,
+  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: CliProgram, 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 };

package/src/install/install.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { CliProgram } from "../types.ts";
+import { detectInstalledArtifacts } from "./detect-installed.ts";
+import { resolveInstallPaths } from "./paths.ts";
+import { buildInstallPlan } from "./plan.ts";
+import { printInstallStatus } from "./status.ts";
+import { parseInstallOpts } from "./index.ts";
+
+const fixture: CliProgram = {
+  key: "testapp",
+  description: "Test",
+  mcpServer: { name: "testapp" },
+  handler: () => {},
+};
+
+let home: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "argsbarg-install-"));
+  prevHome = process.env.HOME;
+  process.env.HOME = home;
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.HOME;
+  else process.env.HOME = prevHome;
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("install paths", () => {
+  test("resolveInstallPaths honors prefix", () => {
+    const paths = resolveInstallPaths(fixture, { prefix: join(home, "custom", "bin") });
+    expect(paths.binaryPath).toBe(join(home, "custom", "bin", "testapp"));
+  });
+
+  test("fish completion uses XDG_CONFIG_HOME", () => {
+    const xdg = join(home, "xdg");
+    process.env.XDG_CONFIG_HOME = xdg;
+    const paths = resolveInstallPaths(fixture, {});
+    expect(paths.fishCompletion).toBe(join(xdg, "fish", "completions", "testapp.fish"));
+  });
+});
+
+describe("detect installed", () => {
+  test("detects binary and completions", () => {
+    const paths = resolveInstallPaths(fixture, {});
+    mkdirSync(paths.bindir, { recursive: true });
+    writeFileSync(paths.binaryPath, "fake", "utf8");
+    mkdirSync(join(home, ".bash_completion.d"), { recursive: true });
+    writeFileSync(paths.bashCompletion, "# bash", "utf8");
+
+    const detected = detectInstalledArtifacts(paths);
+    expect(detected.binary).toBe(true);
+    expect(detected.bashCompletion).toBe(true);
+    expect(detected.zshCompletion).toBe(false);
+  });
+});
+
+describe("install plan", () => {
+  test("buildInstallPlan --all includes binary", () => {
+    const paths = resolveInstallPaths(fixture, {});
+    const plan = buildInstallPlan(fixture, paths, parseInstallOpts({ all: "1" }));
+    expect(plan.some((a) => a.kind === "binary")).toBe(true);
+  });
+});
+
+describe("install status", () => {
+  test("printInstallStatus human output", () => {
+    const paths = resolveInstallPaths(fixture, {});
+    mkdirSync(paths.bindir, { recursive: true });
+    writeFileSync(paths.binaryPath, "fake", "utf8");
+
+    const chunks: string[] = [];
+    const orig = process.stdout.write;
+    process.stdout.write = ((s: string) => {
+      chunks.push(s);
+      return true;
+    }) as typeof process.stdout.write;
+    try {
+      printInstallStatus(fixture, {});
+      const out = chunks.join("");
+      expect(out).toContain("Installed artifacts for testapp");
+      expect(out).toContain(paths.binaryPath);
+    } finally {
+      process.stdout.write = orig;
+    }
+  });
+
+  test("printInstallStatus json output", () => {
+    const paths = resolveInstallPaths(fixture, {});
+    mkdirSync(join(home, ".cursor"), { recursive: true });
+    writeFileSync(
+      paths.cursorMcpPath,
+      JSON.stringify({ mcpServers: { testapp: { command: "testapp", args: ["mcp"] } } }),
+      "utf8",
+    );
+
+    const chunks: string[] = [];
+    const orig = process.stdout.write;
+    process.stdout.write = ((s: string) => {
+      chunks.push(s);
+      return true;
+    }) as typeof process.stdout.write;
+    try {
+      printInstallStatus(fixture, { json: true });
+      const data = JSON.parse(chunks.join(""));
+      expect(data.cursorMcp).toContain("mcp.json");
+    } finally {
+      process.stdout.write = orig;
+    }
+  });
+});
+
+describe("parseInstallOpts", () => {
+  test("json implies yes in validate path via cliInstall", () => {
+    const opts = parseInstallOpts({ json: "1", all: "1" });
+    expect(opts.json).toBe(true);
+    expect(opts.all).toBe(true);
+  });
+});

package/src/install/mcp-config.ts

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { CliProgram } from "../types.ts";
+import { InstallPaths } from "./paths.ts";
+
+export interface McpServerEntry {
+  command: string;
+  args: string[];
+}
+
+export function expectedMcpEntry(root: CliProgram): McpServerEntry {
+  return { command: root.key, args: ["mcp"] };
+}
+
+function entriesEqual(a: McpServerEntry, b: McpServerEntry): boolean {
+  return a.command === b.command && JSON.stringify(a.args) === JSON.stringify(b.args);
+}
+
+/** Reads mcpServers[name] from a JSON config file, or undefined. */
+export function readMcpServerEntry(path: string, name: string): McpServerEntry | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8")) as { mcpServers?: Record<string, McpServerEntry> };
+    return data.mcpServers?.[name];
+  } catch {
+    return undefined;
+  }
+}
+
+/** Returns an error message when existing entry conflicts, or null if safe to merge. */
+export function checkMcpConflict(
+  path: string,
+  name: string,
+  expected: McpServerEntry,
+  yes: boolean,
+): string | null {
+  const existing = readMcpServerEntry(path, name);
+  if (existing && !entriesEqual(existing, expected) && !yes) {
+    return (
+      `MCP server "${name}" in ${path} differs from expected entry.\n` +
+      `  existing: ${JSON.stringify(existing)}\n` +
+      `  expected: ${JSON.stringify(expected)}\n` +
+      `Use --yes to overwrite.`
+    );
+  }
+  return null;
+}
+
+/** Merges MCP server entry into config file. */
+export function mergeMcpConfig(path: string, name: string, entry: McpServerEntry, dry: boolean): void {
+  if (dry) return;
+  let data: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    data = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+  }
+  const servers = (data.mcpServers as Record<string, McpServerEntry> | undefined) ?? {};
+  servers[name] = entry;
+  data.mcpServers = servers;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+/** Removes MCP server entry from config file (keeps file if other keys remain). */
+export function removeMcpConfig(path: string, name: string, dry: boolean): void {
+  if (dry || !existsSync(path)) return;
+  const data = JSON.parse(readFileSync(path, "utf8")) as { mcpServers?: Record<string, unknown> };
+  if (!data.mcpServers?.[name]) return;
+  delete data.mcpServers[name];
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+}

package/src/install/paths.ts

@@ -0,0 +1,69 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CliProgram } from "../types.ts";
+import { sanitizeToolSegment } from "../mcp/tools.ts";
+
+export interface InstallPaths {
+  bindir: string;
+  binaryPath: string;
+  bashCompletion: string;
+  zshCompletion: string;
+  fishCompletion: string;
+  cursorSkillDir: string;
+  claudeSkillDir: string;
+  cursorMcpPath: string;
+  claudeMcpPath: string;
+  bashRc: string;
+  zshRc: string;
+  mcpName: string;
+  skillDirName: string;
+}
+
+/** Resolves the user home directory (`$HOME` when set). */
+export function userHome(): string {
+  return process.env.HOME ?? homedir();
+}
+
+function expandTilde(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(userHome(), path.slice(2));
+  }
+  if (path === "~") {
+    return userHome();
+  }
+  return path;
+}
+
+/** Resolves the binary install directory from CLI flag, env, or config. */
+export function resolveBindir(root: CliProgram, prefix?: string): string {
+  const raw = prefix ?? process.env.INSTALL_PREFIX ?? root.install?.prefix;
+  if (raw) {
+    return expandTilde(raw);
+  }
+  return join(userHome(), ".local", "bin");
+}
+
+/** Resolves all install artifact paths for a program root. */
+export function resolveInstallPaths(root: CliProgram, opts: { prefix?: string }): InstallPaths {
+  const home = userHome();
+  const bindir = resolveBindir(root, opts.prefix);
+  const key = root.key;
+  const skillDirName = sanitizeToolSegment(root.key);
+  const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+
+  return {
+    bindir,
+    binaryPath: join(bindir, key),
+    bashCompletion: join(home, ".bash_completion.d", key),
+    zshCompletion: join(home, ".zsh", "completions", `_${key}`),
+    fishCompletion: join(xdgConfig, "fish", "completions", `${key}.fish`),
+    cursorSkillDir: join(home, ".cursor", "skills", skillDirName),
+    claudeSkillDir: join(home, ".claude", "skills", skillDirName),
+    cursorMcpPath: join(home, ".cursor", "mcp.json"),
+    claudeMcpPath: join(home, ".claude.json"),
+    bashRc: join(home, ".bashrc"),
+    zshRc: join(home, ".zshrc"),
+    mcpName: root.mcpServer?.name ?? root.key,
+    skillDirName,
+  };
+}