ashlrcode 1.0.0

package/src/setup.ts

@@ -0,0 +1,119 @@
+/**
+ * First-run setup wizard — interactive configuration for new users.
+ *
+ * Runs when no API key is configured. Walks through:
+ * 1. API key entry (xAI or Anthropic)
+ * 2. Model selection
+ * 3. Saves to ~/.ashlrcode/settings.json
+ */
+
+import chalk from "chalk";
+import { createInterface } from "readline";
+import { saveSettings, type Settings } from "./config/settings.ts";
+import type { ProviderRouterConfig } from "./providers/types.ts";
+
+export async function runSetupWizard(): Promise<Settings> {
+  console.log("");
+  console.log(chalk.bold.cyan("  Welcome to AshlrCode"));
+  console.log(chalk.dim("  Multi-provider AI coding agent CLI\n"));
+  console.log(chalk.dim("  Let's get you set up. This takes about 30 seconds.\n"));
+
+  // Step 1: Choose provider
+  console.log(chalk.bold("  Step 1: Choose your AI provider\n"));
+  console.log(chalk.dim("  1. ") + chalk.bold("xAI Grok") + chalk.dim(" — $0.20/$0.50 per M tokens, 2M context (recommended)"));
+  console.log(chalk.dim("  2. ") + chalk.bold("Anthropic Claude") + chalk.dim(" — $3/$15 per M tokens, 200K context"));
+  console.log(chalk.dim("  3. ") + chalk.bold("Both") + chalk.dim(" — xAI primary, Claude fallback\n"));
+
+  const providerChoice = await prompt(chalk.cyan("  Provider [1/2/3]: "));
+  const choice = providerChoice.trim() || "1";
+
+  // Step 2: API key(s)
+  let xaiKey = "";
+  let anthropicKey = "";
+
+  if (choice === "1" || choice === "3") {
+    console.log(chalk.dim("\n  Get an xAI API key at: https://console.x.ai/\n"));
+    xaiKey = await prompt(chalk.cyan("  xAI API key: "));
+    xaiKey = xaiKey.trim();
+  }
+
+  if (choice === "2" || choice === "3") {
+    console.log(chalk.dim("\n  Get a Claude API key at: https://console.anthropic.com/\n"));
+    anthropicKey = await prompt(chalk.cyan("  Anthropic API key: "));
+    anthropicKey = anthropicKey.trim();
+  }
+
+  if (!xaiKey && !anthropicKey) {
+    console.error(chalk.red("\n  At least one API key is required."));
+    process.exit(1);
+  }
+
+  // Step 3: Model selection
+  let model: string;
+  if (xaiKey) {
+    console.log(chalk.dim("\n  Step 2: Choose model\n"));
+    console.log(chalk.dim("  1. ") + chalk.bold("grok-4-1-fast-reasoning") + chalk.dim(" — best value, tool-calling optimized (recommended)"));
+    console.log(chalk.dim("  2. ") + chalk.bold("grok-4-0314") + chalk.dim(" — highest quality, higher cost"));
+    console.log(chalk.dim("  3. ") + chalk.bold("grok-3-fast") + chalk.dim(" — older, cheapest\n"));
+    const modelChoice = await prompt(chalk.cyan("  Model [1/2/3]: "));
+    const mc = modelChoice.trim() || "1";
+    model = mc === "2" ? "grok-4-0314" : mc === "3" ? "grok-3-fast" : "grok-4-1-fast-reasoning";
+  } else {
+    model = "claude-sonnet-4-6-20250514";
+  }
+
+  // Build settings
+  const providers: ProviderRouterConfig = xaiKey
+    ? {
+        primary: {
+          provider: "xai",
+          apiKey: xaiKey,
+          model,
+          baseURL: "https://api.x.ai/v1",
+        },
+        fallbacks: anthropicKey
+          ? [{ provider: "anthropic", apiKey: anthropicKey, model: "claude-sonnet-4-6-20250514" }]
+          : [],
+      }
+    : {
+        primary: {
+          provider: "anthropic",
+          apiKey: anthropicKey,
+          model,
+        },
+        fallbacks: [],
+      };
+
+  const settings: Settings = { providers, maxTokens: 8192 };
+
+  // Save
+  await saveSettings(settings);
+
+  console.log(chalk.green("\n  Setup complete!"));
+  console.log(chalk.dim(`  Provider: ${providers.primary.provider}`));
+  console.log(chalk.dim(`  Model: ${model}`));
+  console.log(chalk.dim(`  Config saved to: ~/.ashlrcode/settings.json`));
+  console.log(chalk.dim(`\n  Run ${chalk.bold("ac")} to start coding.\n`));
+
+  return settings;
+}
+
+/**
+ * Check if setup is needed (no API key from env or settings).
+ */
+export function needsSetup(settings: { providers: ProviderRouterConfig }): boolean {
+  return !settings.providers.primary.apiKey;
+}
+
+function prompt(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}

package/src/skills/loader.ts

@@ -0,0 +1,78 @@
+/**
+ * Skill loader — reads skill definitions from .md files.
+ *
+ * Loads from:
+ * 1. Built-in skills: prompts/skills/*.md (shipped with AshlrCode)
+ * 2. User skills: ~/.ashlrcode/skills/*.md
+ * 3. Project skills: .ashlrcode/skills/*.md (per-project)
+ */
+
+import { existsSync } from "fs";
+import { readFile, readdir } from "fs/promises";
+import { join, resolve } from "path";
+import { getConfigDir } from "../config/settings.ts";
+import type { SkillDefinition } from "./types.ts";
+
+const BUILT_IN_DIR = resolve(import.meta.dir, "../../prompts/skills");
+
+export async function loadSkills(cwd: string): Promise<SkillDefinition[]> {
+  const skills: SkillDefinition[] = [];
+  const seen = new Set<string>();
+
+  // Load from all sources (project overrides user overrides built-in)
+  const dirs = [
+    BUILT_IN_DIR,
+    join(getConfigDir(), "skills"),
+    join(cwd, ".ashlrcode", "skills"),
+  ];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+
+    const files = await readdir(dir);
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+
+      const content = await readFile(join(dir, file), "utf-8");
+      const skill = parseSkillFile(content);
+      if (skill) {
+        // Later sources override earlier ones
+        if (seen.has(skill.name)) {
+          const idx = skills.findIndex((s) => s.name === skill.name);
+          if (idx >= 0) skills[idx] = skill;
+        } else {
+          seen.add(skill.name);
+          skills.push(skill);
+        }
+      }
+    }
+  }
+
+  return skills;
+}
+
+function parseSkillFile(content: string): SkillDefinition | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return null;
+
+  const frontmatter = match[1]!;
+  const prompt = match[2]!.trim();
+
+  const name = extractField(frontmatter, "name");
+  const description = extractField(frontmatter, "description");
+  const trigger = extractField(frontmatter, "trigger");
+
+  if (!name || !trigger) return null;
+
+  return {
+    name,
+    description: description ?? name,
+    trigger,
+    prompt,
+  };
+}
+
+function extractField(frontmatter: string, field: string): string | null {
+  const match = frontmatter.match(new RegExp(`^${field}:\\s*(.+)$`, "m"));
+  return match?.[1]?.trim() ?? null;
+}

package/src/skills/registry.ts

@@ -0,0 +1,78 @@
+/**
+ * Skill registry — lookup and expansion of slash commands.
+ */
+
+import type { SkillDefinition } from "./types.ts";
+
+export class SkillRegistry {
+  private skills = new Map<string, SkillDefinition>();
+
+  register(skill: SkillDefinition): void {
+    this.skills.set(skill.trigger, skill);
+    // Also register by name for convenience
+    if (!skill.trigger.startsWith("/")) {
+      this.skills.set(`/${skill.name}`, skill);
+    }
+  }
+
+  registerAll(skills: SkillDefinition[]): void {
+    for (const skill of skills) {
+      this.register(skill);
+    }
+  }
+
+  /**
+   * Look up a skill by trigger (e.g. "/commit").
+   */
+  get(trigger: string): SkillDefinition | undefined {
+    return this.skills.get(trigger);
+  }
+
+  /**
+   * Check if a string is a skill trigger.
+   */
+  isSkill(input: string): boolean {
+    const trigger = input.split(" ")[0]!;
+    return this.skills.has(trigger);
+  }
+
+  /**
+   * Expand a skill invocation into its full prompt.
+   * Supports {{args}} template variable.
+   */
+  expand(input: string): string | null {
+    const parts = input.split(" ");
+    const trigger = parts[0]!;
+    const args = parts.slice(1).join(" ").trim();
+
+    const skill = this.skills.get(trigger);
+    if (!skill) return null;
+
+    let prompt = skill.prompt;
+    if (args) {
+      prompt = prompt.replace(/\{\{args\}\}/g, args);
+      // Also append args if no template variable
+      if (!skill.prompt.includes("{{args}}")) {
+        prompt += `\n\nAdditional context: ${args}`;
+      }
+    }
+
+    return prompt;
+  }
+
+  /**
+   * List all registered skills.
+   */
+  getAll(): SkillDefinition[] {
+    // Deduplicate (same skill registered under trigger and /name)
+    const seen = new Set<string>();
+    const skills: SkillDefinition[] = [];
+    for (const [, skill] of this.skills) {
+      if (!seen.has(skill.name)) {
+        seen.add(skill.name);
+        skills.push(skill);
+      }
+    }
+    return skills;
+  }
+}

package/src/skills/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Skill types — slash commands that expand into full prompts.
+ */
+
+export interface SkillDefinition {
+  name: string;
+  description: string;
+  trigger: string; // e.g. "/commit"
+  prompt: string; // The full prompt template
+  args?: string; // Optional args passed by user
+}

package/src/state/file-history.ts

@@ -0,0 +1,264 @@
+/**
+ * File snapshot/undo system — saves file state before edits.
+ *
+ * Supports:
+ *  - Per-file snapshots before every Write/Edit operation
+ *  - Multi-file undo (undo all changes from a turn)
+ *  - Disk persistence at ~/.ashlrcode/file-history/<session-id>/
+ *  - Handles newly-created files (undo = delete)
+ */
+
+import { readFile, writeFile, mkdir, readdir, unlink } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { getConfigDir } from "../config/settings.ts";
+
+export interface FileSnapshot {
+  id: string;
+  filePath: string;
+  content: string; // Original content before modification ("" means file didn't exist)
+  timestamp: string;
+  tool: string; // Which tool made the change (Write, Edit, Bash)
+  turnNumber: number;
+}
+
+export class FileHistoryStore {
+  private snapshots: FileSnapshot[] = [];
+  private sessionId: string;
+  private persistDir: string;
+
+  constructor(sessionId: string) {
+    this.sessionId = sessionId;
+    this.persistDir = join(getConfigDir(), "file-history", sessionId);
+  }
+
+  /**
+   * Capture a snapshot before a file is modified.
+   * If the file doesn't exist yet, records an empty snapshot so undo can delete it.
+   */
+  async capture(filePath: string, tool: string, turnNumber: number): Promise<void> {
+    const baseSnapshot = {
+      id: `snap-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+      filePath,
+      timestamp: new Date().toISOString(),
+      tool,
+      turnNumber,
+    };
+
+    let content: string;
+    try {
+      content = await readFile(filePath, "utf-8");
+    } catch (err: any) {
+      if (err?.code === "ENOENT") {
+        // File doesn't exist (or was deleted between check and read) — undo means delete
+        const snapshot: FileSnapshot = { ...baseSnapshot, content: "" };
+        this.snapshots.push(snapshot);
+        this.persistSnapshot(snapshot).catch(() => {});
+        return;
+      }
+      throw err;
+    }
+
+    const snapshot: FileSnapshot = { ...baseSnapshot, content };
+    this.snapshots.push(snapshot);
+    this.persistSnapshot(snapshot).catch(() => {});
+  }
+
+  /**
+   * Undo the last file modification.
+   * If the snapshot content is empty, the file was newly created — delete it.
+   */
+  async undoLast(): Promise<{ filePath: string; restored: boolean } | null> {
+    const snapshot = this.snapshots.pop();
+    if (!snapshot) return null;
+
+    if (snapshot.content === "") {
+      // File was newly created — delete it
+      await unlink(snapshot.filePath).catch(() => {});
+    } else {
+      await writeFile(snapshot.filePath, snapshot.content, "utf-8");
+    }
+
+    // Remove persisted snapshot
+    this.removePersistedSnapshot(snapshot.id).catch(() => {});
+
+    return { filePath: snapshot.filePath, restored: true };
+  }
+
+  /**
+   * Undo all changes from a specific turn (in reverse order).
+   */
+  async undoTurn(turnNumber: number): Promise<string[]> {
+    const turnSnapshots = this.snapshots.filter(s => s.turnNumber === turnNumber);
+    const restored: string[] = [];
+
+    // Restore in reverse order so multi-edit sequences unwind correctly
+    for (const snap of turnSnapshots.reverse()) {
+      if (snap.content === "") {
+        await unlink(snap.filePath).catch(() => {});
+      } else {
+        await writeFile(snap.filePath, snap.content, "utf-8");
+      }
+      restored.push(snap.filePath);
+      this.snapshots = this.snapshots.filter(s => s.id !== snap.id);
+      this.removePersistedSnapshot(snap.id).catch(() => {});
+    }
+
+    return restored;
+  }
+
+  /**
+   * Restore a specific file to its most recent snapshot.
+   */
+  async restore(filePath: string): Promise<boolean> {
+    // Find the most recent snapshot for this file
+    let idx = -1;
+    for (let i = this.snapshots.length - 1; i >= 0; i--) {
+      if (this.snapshots[i]!.filePath === filePath) {
+        idx = i;
+        break;
+      }
+    }
+    if (idx === -1) return false;
+
+    const snapshot = this.snapshots[idx]!;
+    if (snapshot.content === "") {
+      await unlink(snapshot.filePath).catch(() => {});
+    } else {
+      await writeFile(snapshot.filePath, snapshot.content, "utf-8");
+    }
+
+    this.snapshots.splice(idx, 1);
+    this.removePersistedSnapshot(snapshot.id).catch(() => {});
+    return true;
+  }
+
+  /**
+   * Get list of files with snapshots available.
+   */
+  getSnapshotFiles(): Array<{ path: string; count: number; lastModified: string }> {
+    const byFile = new Map<string, FileSnapshot[]>();
+    for (const snap of this.snapshots) {
+      const arr = byFile.get(snap.filePath) ?? [];
+      arr.push(snap);
+      byFile.set(snap.filePath, arr);
+    }
+    const files: Array<{ path: string; count: number; lastModified: string }> = [];
+    for (const [path, snaps] of byFile) {
+      files.push({
+        path,
+        count: snaps.length,
+        lastModified: snaps[snaps.length - 1]!.timestamp,
+      });
+    }
+    return files;
+  }
+
+  /**
+   * Get undo history (most recent first).
+   */
+  getHistory(): FileSnapshot[] {
+    return [...this.snapshots].reverse();
+  }
+
+  /**
+   * Check if a file has snapshots.
+   */
+  hasSnapshot(filePath: string): boolean {
+    return this.snapshots.some(s => s.filePath === filePath);
+  }
+
+  /**
+   * Get number of undoable operations.
+   */
+  get undoCount(): number {
+    return this.snapshots.length;
+  }
+
+  /**
+   * Clear all snapshots.
+   */
+  clear(): void {
+    this.snapshots = [];
+  }
+
+  /** Persist a snapshot to disk. */
+  private async persistSnapshot(snap: FileSnapshot): Promise<void> {
+    await mkdir(this.persistDir, { recursive: true });
+    await writeFile(
+      join(this.persistDir, `${snap.id}.json`),
+      JSON.stringify(snap),
+      "utf-8"
+    );
+  }
+
+  /** Remove a persisted snapshot from disk. */
+  private async removePersistedSnapshot(id: string): Promise<void> {
+    const filePath = join(this.persistDir, `${id}.json`);
+    if (existsSync(filePath)) {
+      await unlink(filePath).catch(() => {});
+    }
+  }
+
+  /** Load persisted snapshots from disk (for session resume). */
+  async loadFromDisk(): Promise<void> {
+    if (!existsSync(this.persistDir)) return;
+    const files = await readdir(this.persistDir);
+    for (const file of files.filter(f => f.endsWith(".json"))) {
+      try {
+        const raw = await readFile(join(this.persistDir, file), "utf-8");
+        this.snapshots.push(JSON.parse(raw) as FileSnapshot);
+      } catch {
+        // Ignore corrupt snapshot files
+      }
+    }
+    this.snapshots.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  }
+
+  /** Clean up all persisted snapshots for this session. */
+  async cleanup(): Promise<void> {
+    if (!existsSync(this.persistDir)) return;
+    const files = await readdir(this.persistDir);
+    for (const file of files) {
+      await unlink(join(this.persistDir, file)).catch(() => {});
+    }
+  }
+}
+
+// ── Module-level singleton accessor ─────────────────────────────
+
+let _instance: FileHistoryStore | null = null;
+
+export function setFileHistory(store: FileHistoryStore): void {
+  _instance = store;
+}
+
+export function getFileHistory(): FileHistoryStore | null {
+  return _instance;
+}
+
+/**
+ * @deprecated Use getFileHistory() instead. Kept for backward compatibility.
+ */
+export const fileHistory = {
+  async snapshot(filePath: string): Promise<void> {
+    if (_instance) {
+      await _instance.capture(filePath, "unknown", 0);
+    }
+  },
+  async restore(filePath: string): Promise<boolean> {
+    if (_instance) {
+      return _instance.restore(filePath);
+    }
+    return false;
+  },
+  getSnapshotFiles() {
+    return _instance?.getSnapshotFiles() ?? [];
+  },
+  hasSnapshot(filePath: string): boolean {
+    return _instance?.hasSnapshot(filePath) ?? false;
+  },
+  clear(): void {
+    _instance?.clear();
+  },
+};

package/src/telemetry/event-log.ts

@@ -0,0 +1,116 @@
+/**
+ * Local event telemetry — ring-buffer event log for debugging.
+ * Events stored to ~/.ashlrcode/telemetry/events.jsonl
+ * No external transmission — purely local diagnostics.
+ */
+
+import { appendFile, mkdir, readFile, stat, rename, unlink } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { getConfigDir } from "../config/settings.ts";
+
+export type EventType =
+  | "session_start" | "session_end"
+  | "turn_start" | "turn_end"
+  | "tool_start" | "tool_end" | "tool_error"
+  | "agent_spawn" | "agent_complete"
+  | "compact" | "dream"
+  | "error" | "retry" | "circuit_breaker"
+  | "permission_granted" | "permission_denied"
+  | "kairos_tick" | "kairos_start" | "kairos_stop";
+
+interface TelemetryEvent {
+  type: EventType;
+  timestamp: string;
+  sessionId?: string;
+  data?: Record<string, unknown>;
+}
+
+const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB per file
+const MAX_FILES = 5; // Keep 5 rotated files
+
+function getTelemetryDir(): string {
+  return join(getConfigDir(), "telemetry");
+}
+
+function getEventLogPath(): string {
+  return join(getTelemetryDir(), "events.jsonl");
+}
+
+let _sessionId: string | null = null;
+
+export function initTelemetry(sessionId: string): void {
+  _sessionId = sessionId;
+}
+
+export async function logEvent(type: EventType, data?: Record<string, unknown>): Promise<void> {
+  const event: TelemetryEvent = {
+    type,
+    timestamp: new Date().toISOString(),
+    sessionId: _sessionId ?? undefined,
+    data,
+  };
+
+  try {
+    const dir = getTelemetryDir();
+    await mkdir(dir, { recursive: true });
+    const path = getEventLogPath();
+    await appendFile(path, JSON.stringify(event) + "\n", "utf-8");
+
+    // Rotate if too large
+    if (existsSync(path)) {
+      const s = await stat(path);
+      if (s.size > MAX_FILE_SIZE) {
+        await rotateLog(path);
+      }
+    }
+  } catch {
+    // Never let telemetry crash the app
+  }
+}
+
+async function rotateLog(path: string): Promise<void> {
+  const dir = getTelemetryDir();
+  // Delete the oldest file before shifting to prevent unbounded growth
+  const oldestPath = join(dir, `events.${MAX_FILES}.jsonl`);
+  if (existsSync(oldestPath)) await unlink(oldestPath).catch(() => {});
+  // Shift existing rotated files
+  for (let i = MAX_FILES - 1; i >= 1; i--) {
+    const from = join(dir, `events.${i}.jsonl`);
+    const to = join(dir, `events.${i + 1}.jsonl`);
+    if (existsSync(from)) {
+      await rename(from, to).catch(() => {});
+    }
+  }
+  // Move current to .1
+  await rename(path, join(dir, "events.1.jsonl")).catch(() => {});
+}
+
+/**
+ * Read recent events for debugging.
+ */
+export async function readRecentEvents(count: number = 100): Promise<TelemetryEvent[]> {
+  const path = getEventLogPath();
+  if (!existsSync(path)) return [];
+
+  const content = await readFile(path, "utf-8");
+  const lines = content.trim().split("\n").filter(Boolean);
+  const events: TelemetryEvent[] = [];
+
+  for (const line of lines.slice(-count)) {
+    try { events.push(JSON.parse(line)); } catch {}
+  }
+
+  return events;
+}
+
+/**
+ * Format events for display.
+ */
+export function formatEvents(events: TelemetryEvent[]): string {
+  return events.map(e => {
+    const time = new Date(e.timestamp).toLocaleTimeString();
+    const data = e.data ? ` ${JSON.stringify(e.data).slice(0, 80)}` : "";
+    return `  ${time} ${e.type}${data}`;
+  }).join("\n");
+}