@klhapp/skillmux 0.5.0 → 1.0.0

package/src/completions.ts

@@ -1,14 +1,37 @@
 export type ShellType = "bash" | "zsh" | "fish";
 
+const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
+  { name: "context", description: "Manage connection contexts" },
+  { name: "config", description: "Manage configuration" },
+  { name: "calibrate", description: "Manage policy calibration" },
+  { name: "serve", description: "Start MCP server" },
+  { name: "index", description: "Rebuild local search index" },
+  { name: "sync", description: "Synchronize vault skills" },
+  { name: "init", description: "Configure this machine and its clients" },
+  { name: "project", description: "Configure project-scoped skills" },
+  { name: "target", description: "Manage advanced skill-delivery targets" },
+  { name: "core", description: "Pin/unpin skills into [core]" },
+  { name: "report", description: "Generate usage stats" },
+  { name: "scan", description: "Audit skills for issues" },
+  { name: "install", description: "Install skills into vault" },
+  { name: "eval", description: "Evaluate search accuracy" },
+  { name: "doctor", description: "Check runtime health" },
+  { name: "skill", description: "Show which root resolves a skill_id" },
+  { name: "local-vault", description: "Manage local_vault_paths discoverability markers" },
+  { name: "models", description: "Manage local models" },
+  { name: "completions", description: "Generate shell completions" },
+];
+
 export function generateCompletions(shell: ShellType): string {
   if (shell === "bash") {
+    const opts = [...TOP_LEVEL_COMMANDS.map((c) => c.name), "--context", "--server", "--json", "--allow-insecure", "--verbose", "--dry-run", "--help"].join(" ");
     return `# bash completion for skillmux
 _skillmux_completions() {
     local cur prev opts
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
-    opts="context config calibrate serve index sync init report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
+    opts="${opts}"
 
     if [ "$COMP_CWORD" -eq 1 ]; then
         COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
@@ -28,9 +51,18 @@ _skillmux_completions() {
         completions)
             COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
             ;;
-        manifest)
+        core)
             COMPREPLY=( $(compgen -W "pin unpin" -- "$cur") )
             ;;
+        skill)
+            COMPREPLY=( $(compgen -W "which" -- "$cur") )
+            ;;
+        project)
+            COMPREPLY=( $(compgen -W "init list show add-path remove-path pin unpin attach detach" -- "$cur") )
+            ;;
+        target)
+            COMPREPLY=( $(compgen -W "list show add remove" -- "$cur") )
+            ;;
         local-vault)
             COMPREPLY=( $(compgen -W "init" -- "$cur") )
             ;;
@@ -42,7 +74,10 @@ _skillmux_completions() {
             ;;
     esac
     if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
-        COMPREPLY=( $(compgen -W "--client --target --path --vault --core --migrate-full-vault --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--client --target --dir --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
+    if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
+        COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
     fi
 }
 complete -F _skillmux_completions skillmux
@@ -50,41 +85,51 @@ complete -F _skillmux_completions skillmux
   }
 
   if (shell === "zsh") {
+    const commands = TOP_LEVEL_COMMANDS.map((c) => `        '${c.name}:${c.description}'`).join("\n");
     return `#compdef skillmux
 _skillmux() {
     local -a commands
     commands=(
-        'context:Manage connection contexts'
-        'config:Manage configuration'
-        'calibrate:Manage policy calibration'
-        'serve:Start MCP server'
-        'index:Rebuild local search index'
-        'sync:Synchronize vault skills'
-        'init:Initialize project targets'
-        'report:Generate usage stats'
-        'scan:Audit skills for issues'
-        'install:Install skills into vault'
-        'eval:Evaluate search accuracy'
-        'doctor:Check runtime health'
-        'which:Show which root resolves a skill_id'
-        'manifest:Pin/unpin skills into [core] or [project.*]'
-        'local-vault:Manage local_vault_paths discoverability markers'
-        'models:Manage local models'
-        'completions:Generate shell completions'
+${commands}
     )
     if (( CURRENT == 2 )); then
         _describe -t commands 'skillmux command' commands
     elif [[ "$words[2]" == "init" ]]; then
-        _arguments \
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \
-          '*--target[select a target]:target:(agent-skills claude-code codex custom)' \
-          '--path[custom target directory]:directory:_directories' \
-          '--vault[vault directory]:directory:_directories' \
-          '*--core[seed a core skill]:skill id:' \
-          '--migrate-full-vault[convert a full-vault symlink to managed pins]' \
-          '--yes[apply without prompts]' \
-          '--dry-run[print the plan without writing]' \
+        _arguments \\
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \\
+          '*--target[select a delivery target]:target:(agent-skills claude-code codex custom)' \\
+          '--dir[custom target directory]:directory:_directories' \\
+          '--vault[vault directory]:directory:_directories' \\
+          '*--core[seed a core skill]:skill id:' \\
+          '--migrate-full-vault[convert a full-vault symlink to managed pins]' \\
+          '--no-instructions[skip managed instruction files]' \\
+          '--no-sync[save setup without synchronizing targets]' \\
+          '--interactive[force guided setup]' \\
+          '--yes[apply without prompts]' \\
+          '--dry-run[print the plan without writing]' \\
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "project" && "$words[3]" == "init" ]]; then
+        _arguments \\
+          '1:project directory:_directories' \\
+          '--name[project group name]:group:' \\
+          '*--skill[project skill]:skill id:' \\
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \\
+          '*--target[select an advanced target]:target:' \\
+          '--no-sync[save setup without synchronizing targets]' \\
+          '--interactive[force guided setup]' \\
+          '--yes[apply without prompts]' \\
+          '--dry-run[print the plan without writing]' \\
           '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
+        _values 'project command' init list show add-path remove-path pin unpin attach detach
+    elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
+        _values 'target command' list show add remove
+    elif [[ "$words[2]" == "skill" && CURRENT == 3 ]]; then
+        _values 'skill command' which
+    elif [[ "$words[2]" == "core" && CURRENT == 3 ]]; then
+        _values 'core command' pin unpin
+    elif [[ "$words[2]" == "local-vault" && CURRENT == 3 ]]; then
+        _values 'local-vault command' init
     fi
 }
 _skillmux "$@"
@@ -92,22 +137,36 @@ _skillmux "$@"
   }
 
   if (shell === "fish") {
+    const topLevel = TOP_LEVEL_COMMANDS.map(
+      (c) => `complete -c skillmux -n "__fish_use_subcommand" -a ${c.name} -d "${c.description}"`,
+    ).join("\n");
     return `# fish completion for skillmux
 complete -c skillmux -f
-complete -c skillmux -n "__fish_use_subcommand" -a context -d "Manage connection contexts"
-complete -c skillmux -n "__fish_use_subcommand" -a config -d "Manage configuration"
-complete -c skillmux -n "__fish_use_subcommand" -a calibrate -d "Manage policy calibration"
-complete -c skillmux -n "__fish_use_subcommand" -a serve -d "Start MCP server"
-complete -c skillmux -n "__fish_use_subcommand" -a completions -d "Generate shell completions"
+${topLevel}
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a target"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l path -r -d "Custom target directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a delivery target"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l dir -r -d "Custom target directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-instructions -d "Skip managed instruction files"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-sync -d "Save without synchronizing"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l interactive -d "Force guided setup"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l yes -d "Apply without prompts"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l dry-run -d "Print the plan without writing"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l json -d "Emit a JSON envelope"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show add-path remove-path pin unpin attach detach" -d "Manage projects"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced delivery target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
+complete -c skillmux -n "__fish_seen_subcommand_from core" -a "pin unpin" -d "Manage [core] pins"
+complete -c skillmux -n "__fish_seen_subcommand_from skill" -a "which" -d "Show which root resolves a skill_id"
+complete -c skillmux -n "__fish_seen_subcommand_from local-vault" -a "init" -d "Initialize a local_vault_paths marker"
 `;
   }
 

package/src/config-watcher.ts

@@ -14,6 +14,7 @@ export const LIVE_RELOAD_KEYS = new Set([
   "inference.thresholds.match_score",
   "inference.thresholds.match_margin",
   "inference.thresholds.candidate_floor",
+  "inference.calibration.run_id",
   "recall.k_lexical",
   "recall.k_vector",
   "thresholds.candidate_limit",
@@ -53,6 +54,47 @@ const DEBOUNCE_MS = 300;
 const STABLE_STAT_INTERVAL_MS = 80;
 const STABLE_STAT_MAX_TRIES = 8;
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function changedConfigKeys(
+  previous: Record<string, unknown>,
+  next: Record<string, unknown>,
+  prefix = "",
+): string[] {
+  const changed: string[] = [];
+  const keys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+
+  for (const key of keys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const previousValue = previous[key];
+    const nextValue = next[key];
+    if (!(key in previous) || !(key in next)) {
+      if (isRecord(previousValue) || isRecord(nextValue)) {
+        changed.push(
+          ...changedConfigKeys(
+            isRecord(previousValue) ? previousValue : {},
+            isRecord(nextValue) ? nextValue : {},
+            path,
+          ),
+        );
+      } else {
+        changed.push(path);
+      }
+      continue;
+    }
+
+    if (isRecord(previousValue) && isRecord(nextValue)) {
+      changed.push(...changedConfigKeys(previousValue, nextValue, path));
+    } else if (JSON.stringify(previousValue) !== JSON.stringify(nextValue)) {
+      changed.push(path);
+    }
+  }
+
+  return changed;
+}
+
 /**
  * Watch the parent directory of a TOML config file for changes.
  * Parent-dir watching catches both direct writes (change events) and
@@ -79,6 +121,7 @@ export class ConfigWatcher {
   private constructor(
     private readonly tomlPath: string,
     private readonly opts: ConfigWatcherOptions,
+    private activeConfig: Config,
   ) {
     const dir = dirname(tomlPath);
     const filename = tomlPath.split(/[/\\]/).pop()!;
@@ -110,7 +153,8 @@ export class ConfigWatcher {
     tomlPath: string,
     opts: ConfigWatcherOptions,
   ): Promise<ConfigWatcher> {
-    return new ConfigWatcher(tomlPath, opts);
+    const activeConfig = await loadConfig(tomlPath);
+    return new ConfigWatcher(tomlPath, opts, activeConfig);
   }
 
   private scheduleReload(): void {
@@ -130,10 +174,27 @@ export class ConfigWatcher {
 
     try {
       const config = await loadConfig(this.tomlPath);
+      const restartRequiredKeys = changedConfigKeys(
+        this.activeConfig as unknown as Record<string, unknown>,
+        config as unknown as Record<string, unknown>,
+      )
+        .filter((key) => !LIVE_RELOAD_KEYS.has(key))
+        .sort();
+
+      if (restartRequiredKeys.length > 0) {
+        this.status = {
+          ...this.status,
+          last_reload_error: null,
+          restart_required_keys: restartRequiredKeys,
+        };
+        return;
+      }
+
+      this.activeConfig = config;
       this.status = {
         last_successful_reload_at: new Date().toISOString(),
         last_reload_error: null,
-        restart_required_keys: this.status.restart_required_keys,
+        restart_required_keys: [],
       };
       this.opts.onReload(config);
     } catch (err) {

package/src/doctor.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { createClients } from "./clients";
 import { embeddingDimension, expandHome } from "./config";
-import { resolveManifestPath } from "./manifest";
+import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
 import type { Config } from "./types";
 import { findShadowedSkills } from "./vault";
@@ -62,6 +62,24 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
     });
   }
 
+  const vaultPath = expandHome(config.vault_path);
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) {
+    checks.push({ name: "manifest", ok: true, detail: "not yet initialized" });
+  } else {
+    try {
+      const manifest = parseManifest(await Bun.file(manifestPath).text());
+      validateManifest(manifest, vaultPath, config.local_vault_paths.map(expandHome));
+      checks.push({ name: "manifest", ok: true, detail: manifestPath });
+    } catch (error) {
+      checks.push({
+        name: `manifest:${manifestPath}`,
+        ok: false,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
   try {
     mkdirSync(expandHome(config.state_dir), { recursive: true });
     const probe = Bun.file(expandHome(`${config.state_dir}/.doctor`));

package/src/init-clients.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -17,6 +18,11 @@ export const SUPPORTED_CLIENT_IDS = [
 export type ClientId = (typeof SUPPORTED_CLIENT_IDS)[number];
 export type DeliveryMode = "managed-pins" | "full-vault" | "mcp";
 
+export interface DetectedClient {
+  client: ClientId;
+  evidence: string;
+}
+
 interface ClientDefinition {
   id: ClientId;
   surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
@@ -69,6 +75,31 @@ const CLIENTS: Record<ClientId, ClientDefinition> = {
   "skillmux-mcp": { id: "skillmux-mcp", deliveryMode: "mcp" },
 };
 
+export function detectInstalledClients(
+  options: {
+    home?: string;
+    codexHome?: string;
+    exists?: (path: string) => boolean;
+  } = {},
+): DetectedClient[] {
+  const home = options.home ?? homedir();
+  const codexHome = options.codexHome ?? join(home, ".codex");
+  const exists = options.exists ?? existsSync;
+  const candidates: Array<[ClientId, string]> = [
+    ["claude-code", join(home, ".claude")],
+    ["codex", codexHome],
+    ["gemini-cli", join(home, ".gemini")],
+    ["opencode", join(home, ".config", "opencode")],
+    ["github-copilot", join(home, ".config", "github-copilot")],
+    ["windsurf", join(home, ".codeium", "windsurf")],
+    ["goose", join(home, ".config", "goose")],
+    ["hermes", join(home, ".hermes")],
+  ];
+  return candidates
+    .filter(([, evidence]) => exists(evidence))
+    .map(([client, evidence]) => ({ client, evidence }));
+}
+
 function surfacePath(
   surfaceId: NonNullable<ClientDefinition["surfaceId"]>,
   options: { home: string; codexHome?: string },

package/src/manifest.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { expandHome } from "./config";
@@ -32,7 +32,7 @@ const targetSchema = z.object({
 const manifestSchema = z.object({
   core: z.object({ skills: z.array(skillIdSchema) }).strict(),
   project: z.record(groupNameSchema, projectGroupSchema).optional(),
-  targets: z.record(groupNameSchema, targetSchema),
+  targets: z.record(groupNameSchema, targetSchema).default({}),
 }).strict();
 
 export type ProjectGroup = z.infer<typeof projectGroupSchema>;
@@ -94,6 +94,16 @@ export function serializeManifest(manifest: Manifest): string {
   return `${sections.join("\n\n")}\n`;
 }
 
+export function writeManifestAtomic(path: string, manifest: Manifest): void {
+  const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, serializeManifest(manifest), "utf8");
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}
+
 function findExistingPin(manifest: Manifest, skillId: string): string | null {
   if (manifest.core.skills.includes(skillId)) return "[core]";
   for (const [groupName, group] of Object.entries(manifest.project ?? {})) {
@@ -167,6 +177,95 @@ export function unpinProject(manifest: Manifest, skillId: string, group: string)
   };
 }
 
+export interface UpsertProjectOptions {
+  name: string;
+  paths: string[];
+  skills: string[];
+  targets: string[];
+}
+
+export function upsertProject(manifest: Manifest, options: UpsertProjectOptions): Manifest {
+  if (!groupNameSchema.safeParse(options.name).success) {
+    throw new Error(
+      `invalid group name "${options.name}" — must match /^[a-z][a-z0-9_-]*$/ (max 64 chars)`,
+    );
+  }
+
+  const existingGroup = manifest.project?.[options.name] ?? { paths: [], skills: [] };
+  for (const skillId of options.skills) {
+    if (!skillIdSchema.safeParse(skillId).success) {
+      throw new Error(`invalid skill ID "${skillId}"`);
+    }
+    if (existingGroup.skills.includes(skillId)) continue;
+    const existing = findExistingPin(manifest, skillId);
+    if (existing) throw new Error(`skill "${skillId}" already pinned in ${existing}`);
+  }
+
+  const targets = { ...manifest.targets };
+  for (const targetName of options.targets) {
+    const target = targets[targetName];
+    if (!target) throw new Error(`target "${targetName}" does not exist`);
+    targets[targetName] = {
+      ...target,
+      project_groups: [...new Set([...target.project_groups, options.name])],
+    };
+  }
+
+  return {
+    ...manifest,
+    project: {
+      ...manifest.project,
+      [options.name]: {
+        paths: [...new Set([...existingGroup.paths, ...options.paths])],
+        skills: [...new Set([...existingGroup.skills, ...options.skills])],
+      },
+    },
+    targets,
+  };
+}
+
+export function updateProjectPaths(
+  manifest: Manifest,
+  group: string,
+  changes: { add?: string[]; remove?: string[] },
+): Manifest {
+  const existingGroup = manifest.project?.[group];
+  if (!existingGroup) throw new Error(`[project.${group}] does not exist`);
+  const removed = new Set(changes.remove ?? []);
+  const paths = [...new Set([...existingGroup.paths, ...(changes.add ?? [])])]
+    .filter((path) => !removed.has(path));
+  return {
+    ...manifest,
+    project: {
+      ...manifest.project,
+      [group]: { ...existingGroup, paths },
+    },
+  };
+}
+
+export function updateProjectTargets(
+  manifest: Manifest,
+  group: string,
+  changes: { attach?: string[]; detach?: string[] },
+): Manifest {
+  if (!manifest.project?.[group]) throw new Error(`[project.${group}] does not exist`);
+  const attach = new Set(changes.attach ?? []);
+  const detach = new Set(changes.detach ?? []);
+  const requested = new Set([...attach, ...detach]);
+  for (const target of requested) {
+    if (!manifest.targets[target]) throw new Error(`target "${target}" does not exist`);
+  }
+  return {
+    ...manifest,
+    targets: Object.fromEntries(Object.entries(manifest.targets).map(([name, target]) => {
+      let groups = target.project_groups;
+      if (attach.has(name)) groups = [...new Set([...groups, group])];
+      if (detach.has(name)) groups = groups.filter((item) => item !== group);
+      return [name, { ...target, project_groups: groups }];
+    })),
+  };
+}
+
 export interface ManifestValidationResult {
   notes: string[];
 }

package/src/output.ts

@@ -36,33 +36,31 @@ export function formatJsonEnvelope<T>(opts: {
   };
 }
 
-export function mapExitCode(err: unknown): number {
-  if (!err) return 0;
-  const msg = err instanceof Error ? err.message : String(err);
-  const lower = msg.toLowerCase();
-
-  if (
-    lower.includes("conflict") ||
-    lower.includes("revision") ||
-    lower.includes("externally managed") ||
-    lower.includes("config_revision_conflict") ||
-    lower.includes("config_externally_managed")
-  ) {
-    return 4;
+export class CliError extends Error {
+  exitCode: number;
+
+  constructor(message: string, exitCode: number) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
   }
+}
 
-  if (
-    lower.includes("unreachable") ||
-    lower.includes("failed to reach") ||
-    lower.includes("unauthorized") ||
-    lower.includes("unauthenticated") ||
-    lower.includes("401") ||
-    lower.includes("403") ||
-    lower.includes("connection refused")
-  ) {
-    return 3;
+export function emitSuccess<T>(
+  ctx: { isJson: boolean; target?: ResolvedTarget | string | { name: string; server: string } },
+  data: T,
+  renderText: () => void,
+): void {
+  if (ctx.isJson) {
+    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target ?? "local", data })));
+  } else {
+    renderText();
   }
+}
 
+export function mapExitCode(err: unknown): number {
+  if (!err) return 0;
+  if (err instanceof CliError) return err.exitCode;
   return 2;
 }
 
@@ -110,12 +108,11 @@ export function suggestCorrection(input: string, candidates: string[]): string |
   return bestMatch;
 }
 
-export function isInteractive(): boolean {
-  return (
-    process.stdout.isTTY === true &&
-    !process.env.NO_COLOR &&
-    process.env.TERM !== "dumb"
-  );
+export function isInteractive(
+  env: NodeJS.ProcessEnv = process.env,
+  stdoutIsTTY = process.stdout.isTTY,
+): boolean {
+  return stdoutIsTTY === true && env.TERM !== "dumb";
 }
 
 export function renderTargetBanner(target: ResolvedTarget): void {

package/src/project-setup.ts

@@ -0,0 +1,36 @@
+import { resolve } from "node:path";
+
+interface ResolveProjectDirectoryOptions {
+  cwd?: string;
+  findGitRoot?: (cwd: string) => string | null;
+}
+
+function findGitRoot(cwd: string): string | null {
+  const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return null;
+  const root = result.stdout.toString().trim();
+  return root || null;
+}
+
+export function resolveProjectDirectory(
+  explicitPath?: string,
+  options: ResolveProjectDirectoryOptions = {},
+): string {
+  const cwd = options.cwd ?? process.cwd();
+  if (explicitPath) return resolve(explicitPath);
+  const gitRoot = (options.findGitRoot ?? findGitRoot)(cwd);
+  return resolve(gitRoot ?? cwd);
+}
+
+export function suggestProjectName(directoryName: string): string {
+  const slug = directoryName
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  const prefixed = /^[a-z]/.test(slug) ? slug : `project-${slug || "workspace"}`;
+  return prefixed.slice(0, 64).replace(/-+$/g, "");
+}