@bastani/atomic 0.5.0-1 → 0.5.0-2

package/src/services/system/agents.ts

@@ -0,0 +1,94 @@
+/**
+ * Merge-copy bundled Atomic agents from the installed package into the
+ * provider-native global roots.
+ *
+ * Mirrors `install_global_agents()` from the production install.sh /
+ * install.ps1 bootstrap installers. The bundled agent definitions ship
+ * with the npm package (see the `files` array in package.json) at:
+ *
+ *   <pkg-root>/.claude/agents      → ~/.claude/agents
+ *   <pkg-root>/.opencode/agents    → ~/.opencode/agents
+ *   <pkg-root>/.github/agents      → ~/.copilot/agents      (rename: github → copilot)
+ *   <pkg-root>/.github/lsp.json    → ~/.copilot/lsp-config.json  (rename per atomic-global-config.ts)
+ *
+ * Copy semantics: files sharing a name with a bundled file are overwritten;
+ * unrelated user-added files in those directories are preserved (the
+ * `copyDir()` helper iterates source entries, so anything not in the
+ * source is left untouched).
+ */
+
+import { join, dirname } from "path";
+import { homedir } from "os";
+import {
+  copyDir,
+  copyFile,
+  ensureDir,
+  pathExists,
+} from "@/services/system/copy.ts";
+
+/**
+ * Locate the package root by walking up from this module. Both in installed
+ * (`<pkg>/src/services/system/agents.ts`) and dev checkout layouts the
+ * package root is three directories up.
+ */
+function packageRoot(): string {
+  return join(import.meta.dir, "..", "..", "..");
+}
+
+/** Honors ATOMIC_SETTINGS_HOME so tests can point at a temp dir. */
+function homeRoot(): string {
+  return process.env.ATOMIC_SETTINGS_HOME ?? homedir();
+}
+
+interface AgentSyncPair {
+  /** Source path relative to package root. */
+  src: string;
+  /** Destination path relative to home root. */
+  dest: string;
+}
+
+const AGENT_DIR_PAIRS: AgentSyncPair[] = [
+  { src: ".claude/agents", dest: ".claude/agents" },
+  { src: ".opencode/agents", dest: ".opencode/agents" },
+  { src: ".github/agents", dest: ".copilot/agents" },
+];
+
+/**
+ * Sync bundled agents and the copilot lsp-config to the provider global
+ * roots. Throws on hard failures (a single sync failing); missing source
+ * directories are warned about and skipped, not thrown.
+ */
+export async function installGlobalAgents(): Promise<void> {
+  const pkg = packageRoot();
+  const home = homeRoot();
+
+  const warnings: string[] = [];
+  for (const pair of AGENT_DIR_PAIRS) {
+    const src = join(pkg, pair.src);
+    const dest = join(home, pair.dest);
+
+    if (!(await pathExists(src))) {
+      warnings.push(`bundled agents missing at ${src} — skipping ${dest}`);
+      continue;
+    }
+
+    await copyDir(src, dest);
+  }
+
+  // Surface skipped sources via a non-fatal thrown error only if ALL sources
+  // were missing. A partial miss (e.g. one provider folder absent in a dev
+  // checkout) is normal and shouldn't mark the step as failed. The spinner
+  // UI shows the thrown message beneath the failing row.
+  if (warnings.length === AGENT_DIR_PAIRS.length) {
+    throw new Error(warnings.join("\n"));
+  }
+
+  // Copilot's lsp.json is renamed to ~/.copilot/lsp-config.json on disk
+  // (see atomic-global-config.ts for the in-binary rename rationale).
+  const lspSrc = join(pkg, ".github", "lsp.json");
+  const lspDest = join(home, ".copilot", "lsp-config.json");
+  if (await pathExists(lspSrc)) {
+    await ensureDir(dirname(lspDest));
+    await copyFile(lspSrc, lspDest);
+  }
+}

package/src/services/system/auto-sync.ts

@@ -0,0 +1,131 @@
+/**
+ * Lazy first-run sync of tooling deps, bundled agents, and global skills.
+ *
+ * Why this exists: bun's package manager does NOT execute the top-level
+ * package's `postinstall` script on `bun add -g` / `bun update -g` — see
+ * `src/install/PackageManager/install_with_manager.zig` (the
+ * `!manager.options.global` guard around root lifecycle scripts). So
+ * there's no install-time hook we can register from `package.json`.
+ *
+ * Instead, we detect a fresh install or upgrade lazily on CLI startup by
+ * comparing the bundled `VERSION` constant against a marker file at
+ * `~/.atomic/.synced-version`. On a mismatch we run the same setup the
+ * production bootstrap installers (`install.sh` / `install.ps1`) provide:
+ *
+ *   1. Node.js / npm           (gates everything that needs npm/npx)
+ *   2. tmux / psmux            (terminal multiplexer for `chat` and `workflow`)
+ *   3. @playwright/cli         (global npm package used by skills)
+ *   4. @llamaindex/liteparse   (global npm package used by skills)
+ *   5. global agent configs    (~/.claude/agents, ~/.opencode/agents, ~/.copilot/agents, lsp-config.json)
+ *   6. global workflows        (~/.atomic/workflows/{hello,hello-parallel,ralph,...})
+ *   7. global skills           (npx skills add ...)
+ *
+ * Each step runs sequentially. Failures are collected and reported as a
+ * summary at the end, but never abort the run — partial setup matches the
+ * production installer's "best-effort" semantics. The marker is written
+ * after every run (success or partial) so we don't re-attempt the whole
+ * setup on every subsequent launch.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { VERSION } from "@/version.ts";
+import { COLORS } from "@/theme/colors.ts";
+import {
+  ensureNpmInstalled,
+  ensureTmuxInstalled,
+  upgradePlaywrightCli,
+  upgradeLiteparse,
+} from "@/lib/spawn.ts";
+import { installGlobalAgents } from "@/services/system/agents.ts";
+import { installGlobalWorkflows } from "@/services/system/workflows.ts";
+import { installGlobalSkills } from "@/services/system/skills.ts";
+import { runSteps, printSummary } from "@/services/system/install-ui.ts";
+
+/** Path to the version marker. Honors ATOMIC_SETTINGS_HOME for tests. */
+function syncMarkerPath(): string {
+  const home = process.env.ATOMIC_SETTINGS_HOME ?? homedir();
+  return join(home, ".atomic", ".synced-version");
+}
+
+/**
+ * True when running from an installed package (under `node_modules/`),
+ * false on a dev checkout. Avoids triggering a full global setup on every
+ * `bun run dev` in the repo.
+ */
+function isInstalledPackage(): boolean {
+  return import.meta.dir.includes("node_modules");
+}
+
+/**
+ * Write the version marker. Best-effort: a failed write just means the
+ * next launch will re-sync, which is wasteful but not broken.
+ */
+export async function markSynced(): Promise<void> {
+  try {
+    await Bun.write(syncMarkerPath(), VERSION);
+  } catch {
+    // Swallow — see docstring.
+  }
+}
+
+/**
+ * Sync tooling deps, bundled agents, and global skills if the marker
+ * doesn't match the bundled VERSION. No-op in dev checkouts and when the
+ * marker already matches the current version.
+ */
+export async function autoSyncIfStale(): Promise<void> {
+  if (!isInstalledPackage()) return;
+
+  let stored = "";
+  const marker = Bun.file(syncMarkerPath());
+  if (await marker.exists()) {
+    stored = (await marker.text()).trim();
+  }
+
+  if (stored === VERSION) return;
+
+  console.log(
+    `\n  ${COLORS.dim}Setting up atomic ${COLORS.reset}${COLORS.bold}v${VERSION}${COLORS.reset}${COLORS.dim}…${COLORS.reset}\n`,
+  );
+
+  // Ordering notes:
+  //  - Phase 1 (npm, tmux): core tools. npm comes first because
+  //    @playwright/cli, @llamaindex/liteparse, and `npx skills` all need it.
+  //    tmux/psmux is independent but installed sequentially to avoid
+  //    contention with system package-manager locks (apt-get, dnf, etc).
+  //  - Phase 2 (global npm packages): will fail loudly if Phase 1's npm
+  //    install failed, which is fine — the spinner summary records their
+  //    failure too.
+  //  - Phase 3 (bundled atomic content): file copies + npx skills install.
+  //
+  // Each step's failure is caught inside `runSteps` (not thrown), so
+  // subsequent steps still run even if one fails — matches install.sh's
+  // best-effort contract.
+  const results = await runSteps([
+    { label: "Node.js / npm",      fn: () => ensureNpmInstalled({ quiet: true }) },
+    { label: "tmux / psmux",       fn: () => ensureTmuxInstalled({ quiet: true }) },
+    { label: "@playwright/cli",    fn: upgradePlaywrightCli },
+    { label: "@llamaindex/liteparse", fn: upgradeLiteparse },
+    { label: "global agent configs",  fn: installGlobalAgents },
+    { label: "global workflows",      fn: installGlobalWorkflows },
+    { label: "global skills",         fn: installGlobalSkills },
+  ]);
+
+  // Always write the marker — partial setup is the production-installer
+  // contract. Re-running the bootstrap installer or `bun update -g
+  // @bastani/atomic` is the recovery path for a failed setup.
+  await markSynced();
+
+  console.log();
+  printSummary(results);
+
+  const failures = results.filter((r) => !r.ok);
+  if (failures.length > 0) {
+    console.log(
+      `\n  ${COLORS.dim}Re-run \`bun install -g @bastani/atomic\` after resolving the issues to retry.${COLORS.reset}\n`,
+    );
+  } else {
+    console.log();
+  }
+}

package/src/services/system/install-ui.ts

@@ -0,0 +1,158 @@
+/**
+ * Progress UI primitives for the first-run install flow (auto-sync).
+ *
+ * Renders a single persistent line:
+ *
+ *     ⠋ [██████▒▒▒▒▒▒] 3/7  tmux / psmux
+ *
+ * where the braille spinner animation is provided by `@clack/prompts`
+ * and the bracketed bar tracks overall step progress (completed / total).
+ * A final summary (✓/✗ per step) is printed after all steps finish, and
+ * any captured stderr/stdout from a failed step is shown beneath it.
+ *
+ * Kept intentionally small — this is not a general-purpose progress
+ * library, just what auto-sync needs to stop being visually noisy.
+ */
+
+import { spinner } from "@clack/prompts";
+import { COLORS } from "@/theme/colors.ts";
+
+const BAR_WIDTH = 18;
+const BAR_FILLED = "█";
+const BAR_EMPTY = "░";
+
+/**
+ * Semantic bar states:
+ *   progress → blue (Catppuccin accent; "in flight")
+ *   success  → green (universal "completed")
+ *   error    → red   (universal "failed")
+ *
+ * The empty track stays dim regardless — only the filled portion carries
+ * the status signal, which keeps the bar legible while still telegraphing
+ * the outcome at a glance.
+ */
+type BarState = "progress" | "success" | "error";
+
+function fillColor(state: BarState): string {
+  switch (state) {
+    case "success":
+      return COLORS.green;
+    case "error":
+      return COLORS.red;
+    case "progress":
+    default:
+      return COLORS.blue;
+  }
+}
+
+/** Render a bracketed step-progress bar. `completed` is capped at `total`. */
+function renderBar(
+  completed: number,
+  total: number,
+  state: BarState,
+): string {
+  const safeTotal = Math.max(1, total);
+  const ratio = Math.max(0, Math.min(1, completed / safeTotal));
+  const filled = Math.round(ratio * BAR_WIDTH);
+  const empty = BAR_WIDTH - filled;
+  return (
+    COLORS.bold +
+    fillColor(state) +
+    BAR_FILLED.repeat(filled) +
+    COLORS.reset +
+    COLORS.dim +
+    BAR_EMPTY.repeat(empty) +
+    COLORS.reset
+  );
+}
+
+function formatLine(
+  completed: number,
+  total: number,
+  label: string,
+  state: BarState = "progress",
+): string {
+  const bar = renderBar(completed, total, state);
+  const counter = `${COLORS.dim}${completed}/${total}${COLORS.reset}`;
+  return `${bar}  ${counter}  ${label}`;
+}
+
+export interface StepResult {
+  label: string;
+  ok: boolean;
+  /** Error message (if any) surfaced in the final summary. */
+  error?: string;
+}
+
+/**
+ * Runs a sequence of async steps with a single persistent spinner line
+ * showing stepped progress. Each step's failure is collected rather than
+ * thrown, mirroring auto-sync's "best-effort" contract.
+ *
+ * Returns the per-step results in submission order so the caller can
+ * render a summary.
+ */
+export async function runSteps(
+  steps: Array<{ label: string; fn: () => Promise<unknown> }>,
+): Promise<StepResult[]> {
+  const total = steps.length;
+  const results: StepResult[] = [];
+  const s = spinner();
+
+  // Start with 0/total so the user sees the bar immediately.
+  s.start(formatLine(0, total, steps[0]?.label ?? ""));
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]!;
+    s.message(formatLine(i, total, step.label));
+
+    try {
+      await step.fn();
+      results.push({ label: step.label, ok: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({ label: step.label, ok: false, error: message });
+    }
+  }
+
+  // Stop with a filled bar + final label so the user sees we reached the
+  // end rather than leaving the last in-flight step pinned. Bar color
+  // flips to the universal status colors: green when every step
+  // succeeded, red when any step failed. The per-step ✓/✗ rows printed
+  // afterwards provide the detailed breakdown.
+  const okCount = results.filter((r) => r.ok).length;
+  const allOk = okCount === total;
+  const finalLabel = allOk
+    ? `${COLORS.green}Setup complete${COLORS.reset}`
+    : `${COLORS.red}Setup finished with errors${COLORS.reset}`;
+  s.stop(formatLine(total, total, finalLabel, allOk ? "success" : "error"));
+
+  return results;
+}
+
+/**
+ * Print a compact per-step summary after `runSteps`. Successes render as
+ * a single dim line; failures render with a red cross and an indented
+ * excerpt of the captured error.
+ */
+export function printSummary(results: StepResult[]): void {
+  for (const result of results) {
+    if (result.ok) {
+      console.log(
+        `  ${COLORS.green}✓${COLORS.reset} ${COLORS.dim}${result.label}${COLORS.reset}`,
+      );
+    } else {
+      console.log(
+        `  ${COLORS.red}✗${COLORS.reset} ${result.label}`,
+      );
+      if (result.error) {
+        // Indent the first ~4 lines of the error so it reads as a nested
+        // block rather than wall-of-text.
+        const lines = result.error.split("\n").slice(0, 4);
+        for (const line of lines) {
+          console.log(`    ${COLORS.dim}${line}${COLORS.reset}`);
+        }
+      }
+    }
+  }
+}

package/src/services/system/skills.ts

@@ -15,25 +15,38 @@ const SCM_SKILLS_TO_REMOVE_GLOBALLY = [
   "sl-submit-diff",
 ] as const;
 
-async function runNpxSkills(args: string[]): Promise<boolean> {
+interface NpxSkillsResult {
+  ok: boolean;
+  /** Tail of captured stderr/stdout — surfaced by the spinner on failure. */
+  details: string;
+}
+
+async function runNpxSkills(args: string[]): Promise<NpxSkillsResult> {
   const npxPath = Bun.which("npx");
   if (!npxPath) {
-    console.warn("npx not found on PATH — skipping skills install");
-    return false;
+    return { ok: false, details: "npx not found on PATH" };
   }
 
+  // Capture stdout/stderr so the outer spinner UI owns terminal output and
+  // can surface the tail of any failure. `npx skills add` is otherwise
+  // very chatty.
   const proc = Bun.spawn([npxPath, "--yes", "skills", ...args], {
-    stdio: ["ignore", "inherit", "inherit"],
+    stdout: "pipe",
+    stderr: "pipe",
   });
-  const exitCode = await proc.exited;
-  return exitCode === 0;
+  const [stderr, stdout, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    new Response(proc.stdout).text(),
+    proc.exited,
+  ]);
+  const details = (stderr.trim() || stdout.trim()).slice(-800);
+  return { ok: exitCode === 0, details };
 }
 
 export async function installGlobalSkills(): Promise<void> {
   const agentFlags = SKILLS_AGENTS.flatMap((agent) => ["-a", agent]);
 
-  console.log("Installing bundled skills globally...");
-  const addOk = await runNpxSkills([
+  const addResult = await runNpxSkills([
     "add",
     SKILLS_REPO,
     "--skill",
@@ -42,26 +55,22 @@ export async function installGlobalSkills(): Promise<void> {
     ...agentFlags,
     "-y",
   ]);
-  if (!addOk) {
-    console.warn("Warning: 'npx skills add' exited non-zero (non-fatal)");
-    return;
+  if (!addResult.ok) {
+    throw new Error(`npx skills add failed: ${addResult.details}`);
   }
 
   const removeSkillFlags = SCM_SKILLS_TO_REMOVE_GLOBALLY.flatMap((skill) => [
     "--skill",
     skill,
   ]);
-  console.log(
-    "Removing source-control skill variants globally (added per-project by `atomic init`)...",
-  );
-  const removeOk = await runNpxSkills([
+  const removeResult = await runNpxSkills([
     "remove",
     ...removeSkillFlags,
     "-g",
     ...agentFlags,
     "-y",
   ]);
-  if (!removeOk) {
-    console.warn("Warning: 'npx skills remove' exited non-zero (non-fatal)");
+  if (!removeResult.ok) {
+    throw new Error(`npx skills remove failed: ${removeResult.details}`);
   }
 }

package/src/services/system/workflows.ts

@@ -0,0 +1,105 @@
+/**
+ * Sync bundled Atomic workflow templates from the installed package into
+ * the user's global `~/.atomic/workflows/` directory.
+ *
+ * Each bundled workflow directory (`hello/`, `hello-parallel/`, `ralph/`,
+ * etc.) is a full overwrite of its destination — `rm -rf` followed by a
+ * fresh copy — so files removed upstream don't linger after an upgrade.
+ * User-created workflows whose names don't collide with bundled names are
+ * left untouched (we only iterate the bundled source, never the user's
+ * destination).
+ *
+ * Root-level files (`tsconfig.json`, etc.) are also overwritten on each
+ * sync.
+ */
+
+import { join, sep } from "path";
+import { readdir, rm } from "fs/promises";
+import { homedir } from "os";
+import {
+  copyDir,
+  copyFile,
+  ensureDir,
+  pathExists,
+} from "@/services/system/copy.ts";
+import { assertPathWithinRoot } from "@/lib/path-root-guard.ts";
+
+/**
+ * Reject any entry name that could redirect a write outside destRoot.
+ * `readdir` should never return `.`, `..`, or names with separators, but
+ * this is a cheap belt-and-braces check in case the installed package has
+ * been tampered with or sits on an exotic filesystem.
+ */
+function isSafeEntryName(name: string): boolean {
+  if (name === "" || name === "." || name === "..") return false;
+  if (name.includes("/") || name.includes("\\")) return false;
+  if (sep !== "/" && name.includes(sep)) return false;
+  return true;
+}
+
+/**
+ * Locate the package root by walking up from this module. Both in installed
+ * (`<pkg>/src/services/system/workflows.ts`) and dev checkout layouts the
+ * package root is three directories up.
+ */
+function packageRoot(): string {
+  return join(import.meta.dir, "..", "..", "..");
+}
+
+/** Honors ATOMIC_SETTINGS_HOME so tests can point at a temp dir. */
+function homeRoot(): string {
+  return process.env.ATOMIC_SETTINGS_HOME ?? homedir();
+}
+
+/**
+ * Sync bundled workflow templates to `~/.atomic/workflows/`. Returns the
+ * number of bundled workflows installed (for logging). Best-effort on
+ * individual entries — readdir failures throw, per-entry copy failures
+ * propagate up to the caller (auto-sync's runStep).
+ */
+export async function installGlobalWorkflows(): Promise<void> {
+  const srcRoot = join(packageRoot(), ".atomic", "workflows");
+  const destRoot = join(homeRoot(), ".atomic", "workflows");
+
+  if (!(await pathExists(srcRoot))) {
+    // Treat a missing bundled source as a non-fatal skip: dev checkouts
+    // and partial installs legitimately hit this path. Surfaced via a
+    // thrown error so the spinner UI marks the step red with context.
+    throw new Error(`bundled workflows missing at ${srcRoot} — skipping ${destRoot}`);
+  }
+
+  await ensureDir(destRoot);
+
+  // Safety invariant: we enumerate the BUNDLED source, never the user's
+  // destination. This guarantees that `rm(dest)` can only ever target a
+  // path whose basename exists in the bundled workflows — user-created
+  // workflows with different names are structurally invisible to this loop.
+  const entries = await readdir(srcRoot, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!isSafeEntryName(entry.name)) {
+      console.warn(
+        `  skipping unsafe bundled workflow entry name: ${JSON.stringify(entry.name)}`,
+      );
+      continue;
+    }
+
+    const src = join(srcRoot, entry.name);
+    const dest = join(destRoot, entry.name);
+
+    // Belt-and-braces: confirm the computed destination actually lives
+    // inside destRoot. Throws if something conspired to produce an escape.
+    assertPathWithinRoot(destRoot, dest, "Workflow destination");
+
+    if (entry.isFile()) {
+      // Root files (tsconfig.json, etc.) — overwrite in place.
+      await copyFile(src, dest);
+    } else if (entry.isDirectory()) {
+      // Bundled workflow — full overwrite of the destination directory so
+      // files removed upstream don't linger across upgrades. User-created
+      // workflows under names that don't collide are untouched.
+      await rm(dest, { recursive: true, force: true });
+      await copyDir(src, dest);
+    }
+  }
+}

package/src/theme/colors.ts

@@ -11,6 +11,7 @@ const ANSI_CODES = {
   red: "\x1b[31m",
   green: "\x1b[32m",
   yellow: "\x1b[33m",
+  blue: "\x1b[34m",
 } as const;
 
 const NO_COLORS = {
@@ -20,6 +21,7 @@ const NO_COLORS = {
   red: "",
   green: "",
   yellow: "",
+  blue: "",
 } as const;
 
 export const COLORS = supportsColor() ? ANSI_CODES : NO_COLORS;

package/src/commands/cli/update.ts

@@ -1,46 +0,0 @@
-/**
- * Update command — upgrades atomic to the latest version via bun and
- * reinstalls global skills.
- *
- * Usage:
- *   atomic update
- */
-
-import { COLORS } from "@/theme/colors.ts";
-import { VERSION } from "@/version.ts";
-import { installGlobalSkills } from "@/services/system/skills.ts";
-
-export async function updateCommand(): Promise<number> {
-  const bunPath = Bun.which("bun");
-  if (!bunPath) {
-    console.error(`${COLORS.red}Error: bun is not installed.${COLORS.reset}`);
-    console.error("Install bun: https://bun.sh");
-    return 1;
-  }
-
-  console.log(`Current version: ${VERSION}`);
-  console.log("Updating atomic...\n");
-
-  // Upgrade the package
-  const proc = Bun.spawn([bunPath, "add", "-g", "atomic@latest"], {
-    stdio: ["ignore", "inherit", "inherit"],
-  });
-  const exitCode = await proc.exited;
-
-  if (exitCode !== 0) {
-    console.error(`\n${COLORS.red}Failed to update atomic (exit ${exitCode}).${COLORS.reset}`);
-    return 1;
-  }
-
-  // Reinstall global skills
-  console.log("\nUpdating skills...");
-  try {
-    await installGlobalSkills();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.warn(`\n${COLORS.yellow}Warning: failed to install skills: ${message}${COLORS.reset}`);
-  }
-
-  console.log(`\n${COLORS.green}Update complete.${COLORS.reset}`);
-  return 0;
-}