@bastani/atomic 0.5.0-1

package/src/sdk/workflows.ts

@@ -0,0 +1,85 @@
+/**
+ * atomic/workflows
+ *
+ * Workflow SDK for defining multi-session agent workflows.
+ * Workflows are defined as a chain of .session() calls and compiled
+ * into a WorkflowDefinition consumed by the Atomic CLI runtime.
+ */
+
+export { defineWorkflow, WorkflowBuilder } from "./define-workflow.ts";
+
+export type {
+  AgentType,
+  Transcript,
+  SavedMessage,
+  SaveTranscript,
+  SessionContext,
+  SessionOptions,
+  WorkflowOptions,
+  WorkflowDefinition,
+} from "./types.ts";
+
+// Re-export native SDK types for convenience
+export type { SessionEvent as CopilotSessionEvent } from "@github/copilot-sdk";
+export type { SessionPromptResponse as OpenCodePromptResponse } from "@opencode-ai/sdk/v2";
+export type { SessionMessage as ClaudeSessionMessage } from "@anthropic-ai/claude-agent-sdk";
+
+// Providers
+export { createClaudeSession, claudeQuery, clearClaudeSession, validateClaudeWorkflow } from "./providers/claude.ts";
+export type { ClaudeSessionOptions, ClaudeQueryOptions, ClaudeQueryResult, ClaudeValidationWarning } from "./providers/claude.ts";
+
+export { validateCopilotWorkflow } from "./providers/copilot.ts";
+export type { CopilotValidationWarning } from "./providers/copilot.ts";
+
+export { validateOpenCodeWorkflow } from "./providers/opencode.ts";
+export type { OpenCodeValidationWarning } from "./providers/opencode.ts";
+
+// Runtime — tmux utilities
+export {
+  isTmuxInstalled,
+  getMuxBinary,
+  resetMuxBinaryCache,
+  isInsideTmux,
+  createSession,
+  createWindow,
+  createPane,
+  sendLiteralText,
+  sendSpecialKey,
+  sendKeysAndSubmit,
+  capturePane,
+  capturePaneVisible,
+  capturePaneScrollback,
+  killSession,
+  killWindow,
+  sessionExists,
+  attachSession,
+  switchClient,
+  getCurrentSession,
+  attachOrSwitch,
+  selectWindow,
+  waitForOutput,
+  tmuxRun,
+  normalizeTmuxCapture,
+  normalizeTmuxLines,
+  paneLooksReady,
+  paneHasActiveTask,
+  paneIsIdle,
+  waitForPaneReady,
+  attemptSubmitRounds,
+} from "./runtime/tmux.ts";
+
+// Runtime — workflow discovery
+export {
+  AGENTS,
+  discoverWorkflows,
+  findWorkflow,
+  WORKFLOWS_GITIGNORE,
+} from "./runtime/discovery.ts";
+export type { DiscoveredWorkflow } from "./runtime/discovery.ts";
+
+// Runtime — workflow loader pipeline
+export { WorkflowLoader } from "./runtime/loader.ts";
+
+// Runtime — workflow executor
+export { executeWorkflow } from "./runtime/executor.ts";
+export type { WorkflowRunOptions } from "./runtime/executor.ts";

package/src/services/config/atomic-config.ts

@@ -0,0 +1,124 @@
+/**
+ * Atomic configuration file utilities for persisting project settings.
+ *
+ * Project/source-control selections are stored in `.atomic/settings.json`.
+ * Resolution order:
+ * 1) local `.atomic/settings.json` (project override)
+ * 2) global `~/.atomic/settings.json` (default fallback)
+ */
+
+import { readFile, writeFile } from "fs/promises";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { type SourceControlType } from "@/services/config/index.ts";
+import { SETTINGS_SCHEMA_URL } from "@/services/config/settings-schema.ts";
+import { ensureDir } from "@/services/system/copy.ts";
+
+const SETTINGS_DIR = ".atomic";
+const SETTINGS_FILENAME = "settings.json";
+
+/**
+ * Atomic project configuration schema.
+ */
+export interface AtomicConfig {
+  /** Version of config schema */
+  version?: number;
+  /** Selected source control type */
+  scm?: SourceControlType;
+  /** Timestamp of last init */
+  lastUpdated?: string;
+}
+
+type JsonRecord = Record<string, unknown>;
+
+function getGlobalSettingsPath(): string {
+  const home = process.env.ATOMIC_SETTINGS_HOME ?? homedir();
+  return join(home, SETTINGS_DIR, SETTINGS_FILENAME);
+}
+
+function getLocalSettingsPath(projectDir: string): string {
+  return join(projectDir, SETTINGS_DIR, SETTINGS_FILENAME);
+}
+
+async function readJsonFile(path: string): Promise<JsonRecord | null> {
+  try {
+    return JSON.parse(await readFile(path, "utf-8")) as JsonRecord;
+  } catch {
+    return null;
+  }
+}
+
+function pickAtomicConfig(record: JsonRecord | null): AtomicConfig | null {
+  if (!record) return null;
+
+  const config: AtomicConfig = {};
+  const version = record.version;
+  const scm = record.scm;
+  const lastUpdated = record.lastUpdated;
+
+  if (typeof version === "number") config.version = version;
+  if (typeof scm === "string") config.scm = scm as SourceControlType;
+  if (typeof lastUpdated === "string") config.lastUpdated = lastUpdated;
+
+  return Object.keys(config).length > 0 ? config : null;
+}
+
+function mergeConfigs(...configs: Array<AtomicConfig | null>): AtomicConfig | null {
+  const merged: AtomicConfig = {};
+  for (const config of configs) {
+    if (!config) continue;
+    if (config.version !== undefined) merged.version = config.version;
+    if (config.scm !== undefined) merged.scm = config.scm;
+    if (config.lastUpdated !== undefined) merged.lastUpdated = config.lastUpdated;
+  }
+  return Object.keys(merged).length > 0 ? merged : null;
+}
+
+/**
+ * Read atomic config with local override semantics.
+ */
+export async function readAtomicConfig(projectDir: string): Promise<AtomicConfig | null> {
+  const localConfig = pickAtomicConfig(await readJsonFile(getLocalSettingsPath(projectDir)));
+  const globalConfig = pickAtomicConfig(await readJsonFile(getGlobalSettingsPath()));
+
+  // global < local settings
+  return mergeConfigs(globalConfig, localConfig);
+}
+
+/**
+ * Save project config to `.atomic/settings.json`.
+ */
+export async function saveAtomicConfig(
+  projectDir: string,
+  updates: Partial<AtomicConfig>
+): Promise<void> {
+  const localPath = getLocalSettingsPath(projectDir);
+
+  const localSettings = (await readJsonFile(localPath)) ?? {};
+  const localExistingConfig = pickAtomicConfig(localSettings);
+  const currentConfig = localExistingConfig ?? {};
+
+  const newConfig: AtomicConfig = {
+    ...currentConfig,
+    ...updates,
+    version: 1,
+    lastUpdated: new Date().toISOString(),
+  };
+
+  const nextSettings: JsonRecord = {
+    ...localSettings,
+    ...newConfig,
+    $schema: SETTINGS_SCHEMA_URL,
+  };
+
+  await ensureDir(dirname(localPath));
+  await writeFile(localPath, JSON.stringify(nextSettings, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Get selected SCM using local override + global fallback.
+ */
+export async function getSelectedScm(projectDir: string): Promise<SourceControlType | null> {
+  const config = await readAtomicConfig(projectDir);
+  return config?.scm ?? null;
+}

package/src/services/config/atomic-global-config.ts

@@ -0,0 +1,361 @@
+import { copyFile, lstat, readdir, rm, rmdir } from "fs/promises";
+import { join, resolve } from "path";
+import { homedir } from "os";
+
+import { AGENT_CONFIG, type AgentKey } from "@/services/config/index.ts";
+import { mergeJsonFile } from "@/lib/merge.ts";
+import { copyDir, ensureDir, pathExists } from "@/services/system/copy.ts";
+
+
+const ATOMIC_HOME_DIR = join(homedir(), ".atomic");
+
+const GLOBAL_AGENT_FOLDER_BY_KEY: Record<AgentKey, string> = {
+  claude: ".claude",
+  opencode: ".opencode",
+  copilot: ".copilot",
+};
+
+const TEMPLATE_AGENT_FOLDER_BY_KEY: Record<AgentKey, string> = {
+  claude: AGENT_CONFIG.claude.folder,
+  opencode: AGENT_CONFIG.opencode.folder,
+  copilot: AGENT_CONFIG.copilot.folder,
+};
+
+/**
+ * Per-agent subdirectories copied from the bundled template into the
+ * provider home. Only `agents/` now — skills ship via the skills CLI.
+ */
+const GLOBAL_SYNC_SUBDIRECTORIES = ["agents"] as const;
+
+/**
+ * Top-level files copied per agent. Copilot's lsp.json is renamed to
+ * lsp-config.json in the destination (see `GLOBAL_SYNC_DESTINATION_FILE_NAMES`).
+ */
+const GLOBAL_SYNC_FILES: Partial<Record<AgentKey, readonly string[]>> = {
+  copilot: ["lsp.json"],
+};
+
+const GLOBAL_SYNC_DESTINATION_FILE_NAMES: Partial<Record<AgentKey, Partial<Record<string, string>>>> = {
+  copilot: {
+    "lsp.json": "lsp-config.json",
+  },
+};
+
+/**
+ * Return the Atomic home directory used for global workflows/tools/settings.
+ */
+export function getAtomicHomeDir(): string {
+  return ATOMIC_HOME_DIR;
+}
+
+function resolveHomeDirFromAtomicHome(baseDir: string): string {
+  return resolve(baseDir, "..");
+}
+
+/**
+ * Get Atomic-managed provider config directories.
+ *
+ * Atomic now installs provider configs into the provider home roots while
+ * keeping Atomic-specific state under ~/.atomic.
+ */
+export function getAtomicManagedConfigDirs(baseDir: string = ATOMIC_HOME_DIR): string[] {
+  const homeDir = resolveHomeDirFromAtomicHome(baseDir);
+  return [
+    join(homeDir, GLOBAL_AGENT_FOLDER_BY_KEY.claude),
+    join(homeDir, GLOBAL_AGENT_FOLDER_BY_KEY.opencode),
+    join(homeDir, GLOBAL_AGENT_FOLDER_BY_KEY.copilot),
+  ];
+}
+
+/**
+ * Get the provider home-folder suffix for the given agent.
+ */
+export function getAtomicGlobalAgentFolder(agentKey: AgentKey): string {
+  return GLOBAL_AGENT_FOLDER_BY_KEY[agentKey];
+}
+
+/**
+ * Resolve the destination directory where Atomic installs provider configs.
+ */
+export function getAtomicManagedAgentDir(
+  agentKey: AgentKey,
+  baseDir: string = ATOMIC_HOME_DIR,
+): string {
+  return join(resolveHomeDirFromAtomicHome(baseDir), getAtomicGlobalAgentFolder(agentKey));
+}
+
+/**
+ * Get the bundled template folder for the given agent.
+ */
+export function getTemplateAgentFolder(agentKey: AgentKey): string {
+  return TEMPLATE_AGENT_FOLDER_BY_KEY[agentKey];
+}
+
+interface ManagedTreeEntries {
+  directories: string[];
+  files: string[];
+}
+
+async function collectManagedTreeEntries(
+  sourceDir: string,
+  exclude: readonly string[],
+  relativeDir: string = "",
+): Promise<ManagedTreeEntries> {
+  if (!(await pathExists(sourceDir))) {
+    return {
+      directories: [],
+      files: [],
+    };
+  }
+
+  const directories: string[] = [];
+  const files: string[] = [];
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const relativePath = relativeDir.length > 0
+      ? join(relativeDir, entry.name)
+      : entry.name;
+
+    if (exclude.includes(entry.name)) {
+      continue;
+    }
+
+    const normalizedRelativePath = relativePath.replace(/\\/g, "/");
+    if (exclude.some((excluded) =>
+      normalizedRelativePath === excluded.replace(/\\/g, "/") ||
+      normalizedRelativePath.startsWith(`${excluded.replace(/\\/g, "/")}/`)
+    )) {
+      continue;
+    }
+
+    const sourcePath = join(sourceDir, entry.name);
+    if (entry.isDirectory()) {
+      directories.push(relativePath);
+      const nestedEntries = await collectManagedTreeEntries(
+        sourcePath,
+        exclude,
+        relativePath,
+      );
+      directories.push(...nestedEntries.directories);
+      files.push(...nestedEntries.files);
+      continue;
+    }
+
+    if (entry.isFile() || entry.isSymbolicLink()) {
+      files.push(relativePath);
+    }
+  }
+
+  return { directories, files };
+}
+
+async function removeEmptyDirectoryIfPresent(pathToDirectory: string): Promise<void> {
+  try {
+    const stats = await lstat(pathToDirectory);
+    if (!stats.isDirectory()) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  const entries = await readdir(pathToDirectory);
+  if (entries.length === 0) {
+    await rmdir(pathToDirectory);
+  }
+}
+
+function getGlobalSyncDestinationFileName(agentKey: AgentKey, sourceFileName: string): string {
+  return GLOBAL_SYNC_DESTINATION_FILE_NAMES[agentKey]?.[sourceFileName] ?? sourceFileName;
+}
+
+async function syncManagedGlobalFile(
+  sourcePath: string,
+  destinationPath: string,
+): Promise<void> {
+  await ensureDir(resolve(destinationPath, ".."));
+
+  if (await pathExists(destinationPath)) {
+    await mergeJsonFile(sourcePath, destinationPath);
+    return;
+  }
+
+  await copyFile(sourcePath, destinationPath);
+}
+
+/**
+ * Remove only the Atomic-managed entries from provider-native global roots.
+ *
+ * Mirrors `syncAtomicGlobalAgentConfigs`: walks the bundled template for
+ * each agent and removes every file/directory it would have installed. Any
+ * legacy skills or tools left behind from previous Atomic versions are
+ * intentionally untouched — those are owned by the skills CLI now.
+ */
+export async function removeAtomicManagedGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR,
+): Promise<void> {
+  const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+
+  for (const agentKey of agentKeys) {
+    const sourceFolder = join(configRoot, getTemplateAgentFolder(agentKey));
+    const destinationFolder = getAtomicManagedAgentDir(agentKey, baseDir);
+    for (const subdirectory of GLOBAL_SYNC_SUBDIRECTORIES) {
+      const sourceSubdirectory = join(sourceFolder, subdirectory);
+      if (!(await pathExists(sourceSubdirectory))) {
+        continue;
+      }
+
+      const managedTree = await collectManagedTreeEntries(sourceSubdirectory, []);
+      const destinationSubdirectory = join(destinationFolder, subdirectory);
+
+      for (const relativeFile of managedTree.files) {
+        await rm(join(destinationSubdirectory, relativeFile), { force: true });
+      }
+
+      const managedDirectories = [...managedTree.directories].sort(
+        (left, right) => right.length - left.length,
+      );
+      for (const relativeDirectory of managedDirectories) {
+        await removeEmptyDirectoryIfPresent(join(destinationSubdirectory, relativeDirectory));
+      }
+      await removeEmptyDirectoryIfPresent(destinationSubdirectory);
+    }
+
+    const managedFiles = GLOBAL_SYNC_FILES[agentKey] ?? [];
+    for (const fileName of managedFiles) {
+      const sourceFilePath = join(sourceFolder, fileName);
+      if (!(await pathExists(sourceFilePath))) {
+        continue;
+      }
+
+      const destinationFilePath = join(
+        destinationFolder,
+        getGlobalSyncDestinationFileName(agentKey, fileName),
+      );
+      await rm(destinationFilePath, { force: true });
+    }
+
+    // Do NOT remove the top-level provider directory (e.g. ~/.claude, ~/.opencode,
+    // ~/.copilot) — Atomic does not own it and it may contain user-managed configs.
+  }
+}
+
+/**
+ * Sync bundled agent templates into provider-native global roots.
+ *
+ * Copies each agent's `agents/` directory plus a small set of top-level
+ * files (currently just Copilot's `lsp.json` → `lsp-config.json`). Skills
+ * are NOT synced from here — they are installed globally at install time
+ * via `npx skills add` from the git repo.
+ */
+export async function syncAtomicGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR,
+): Promise<void> {
+  await ensureDir(baseDir);
+
+  const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+  for (const agentKey of agentKeys) {
+    const sourceFolder = join(configRoot, getTemplateAgentFolder(agentKey));
+    if (!(await pathExists(sourceFolder))) continue;
+
+    const destinationFolder = getAtomicManagedAgentDir(agentKey, baseDir);
+    await ensureDir(destinationFolder);
+
+    for (const subdirectory of GLOBAL_SYNC_SUBDIRECTORIES) {
+      const sourceSubdir = join(sourceFolder, subdirectory);
+      if (await pathExists(sourceSubdir)) {
+        await copyDir(sourceSubdir, join(destinationFolder, subdirectory));
+      }
+    }
+
+    const managedFiles = GLOBAL_SYNC_FILES[agentKey] ?? [];
+    for (const fileName of managedFiles) {
+      const sourceFilePath = join(sourceFolder, fileName);
+      if (!(await pathExists(sourceFilePath))) continue;
+
+      const destinationFilePath = join(
+        destinationFolder,
+        getGlobalSyncDestinationFileName(agentKey, fileName),
+      );
+      await syncManagedGlobalFile(sourceFilePath, destinationFilePath);
+    }
+  }
+}
+
+/**
+ * Return true when every Atomic-bundled agent file is present at its
+ * destination in the provider-native global roots.
+ *
+ * This walks the bundled template for each agent and checks that every
+ * file (and the top-level files in `GLOBAL_SYNC_FILES`) has a matching
+ * entry under `~/.<agent>/`. A single missing file returns false so the
+ * caller can run a merge re-sync. User-added files in the destination
+ * that don't exist in the template are ignored — they never trigger a
+ * false-negative and they are never removed.
+ */
+export async function hasAtomicGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR,
+): Promise<boolean> {
+  const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+
+  for (const agentKey of agentKeys) {
+    const sourceFolder = join(configRoot, getTemplateAgentFolder(agentKey));
+    if (!(await pathExists(sourceFolder))) {
+      // No template for this agent in the config root — nothing to verify.
+      continue;
+    }
+
+    const destinationFolder = getAtomicManagedAgentDir(agentKey, baseDir);
+    if (!(await pathExists(destinationFolder))) return false;
+
+    for (const subdirectory of GLOBAL_SYNC_SUBDIRECTORIES) {
+      const sourceSubdir = join(sourceFolder, subdirectory);
+      if (!(await pathExists(sourceSubdir))) continue;
+
+      const managedTree = await collectManagedTreeEntries(sourceSubdir, []);
+      const destinationSubdir = join(destinationFolder, subdirectory);
+
+      for (const relativeFile of managedTree.files) {
+        if (!(await pathExists(join(destinationSubdir, relativeFile)))) {
+          return false;
+        }
+      }
+    }
+
+    const managedFiles = GLOBAL_SYNC_FILES[agentKey] ?? [];
+    for (const fileName of managedFiles) {
+      const sourceFilePath = join(sourceFolder, fileName);
+      if (!(await pathExists(sourceFilePath))) continue;
+
+      const destinationFilePath = join(
+        destinationFolder,
+        getGlobalSyncDestinationFileName(agentKey, fileName),
+      );
+      if (!(await pathExists(destinationFilePath))) return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Verify-and-repair entrypoint for user-facing commands (`atomic init`,
+ * `atomic chat`). If every bundled agent file is present at its
+ * destination, returns immediately without touching disk. Otherwise
+ * runs a merge re-sync, which fills the missing files from the local
+ * config data dir while leaving user-added files alone.
+ *
+ * This helper heals drift (e.g. a user deleted `~/.claude/agents/<foo>.md`).
+ */
+export async function ensureAtomicGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR,
+): Promise<void> {
+  if (await hasAtomicGlobalAgentConfigs(configRoot, baseDir)) return;
+  await syncAtomicGlobalAgentConfigs(configRoot, baseDir);
+}
+

package/src/services/config/config-path.ts

@@ -0,0 +1,19 @@
+/**
+ * Config path resolution.
+ *
+ * Two installation modes:
+ * 1. Source/Development: Running from source with `bun run src/cli.ts`
+ * 2. npm/bun installed: Installed via `bun add -g atomic`
+ */
+
+import { join } from "path";
+
+/**
+ * Get the root directory where config folders (.claude, .opencode, .github) are stored.
+ *
+ * Navigates up from the current file to the package/repo root:
+ * src/services/config/config-path.ts -> ../../.. -> root
+ */
+export function getConfigRoot(): string {
+  return join(import.meta.dir, "..", "..", "..");
+}