@bahulam/code 0.1.1

package/src/terminal/init.mjs

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const FILES = {
+  'README.md': `# .bahulam/ - project agent context
+
+Bahulam Code reads and writes here to keep state between sessions.
+
+## Files Bahulam Code writes
+- \`plan.md\` - current agent plan
+- \`goal.md\` - durable session goal
+- \`tasks/\` - task list
+- \`reports/*.md\` - end-of-turn mission reports
+- \`sessions/*.jsonl\` - turn transcripts
+- \`commands.log\` - command executions
+- \`approvals.log\` - HITL decisions
+- \`trust.json\` - approved patterns
+
+## Files you can write
+- \`config.json\` - project policy
+- \`project.md\` - durable project context
+- \`style.md\` - codebase conventions
+- \`hitl.md\` - approval guidance
+- \`skills/<name>/SKILL.md\` - reusable domain skills
+
+Format v1. Markdown files are intentionally hand-editable.
+`,
+  'config.json': JSON.stringify({
+    version: 1,
+    context: {
+      loadEveryTurn: ['KEPLER.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
+      showReloadNotice: true,
+    },
+    planning: { owner: 'auto', onUserEditedPlan: 'prefer_user_plan' },
+    tasks: { storage: 'project_markdown', syncTodoWrite: true, resumePrompt: true },
+    hitl: {
+      defaultScope: 'once',
+      allowSessionTrust: true,
+      allowProjectTrust: false,
+      reaskAfterMinutes: 30,
+    },
+    commands: {
+      enabled: ['map', 'probe', 'footprint', 'heal', 'align', 'distill', 'brief', 'rewind'],
+      dryRunDefault: false,
+    },
+  }, null, 2) + '\n',
+  'settings.json': JSON.stringify({
+    env: {},
+    permissions: {
+      shellAllowlist: ['git', 'npm', 'pnpm'],
+      editDenylist: ['**/*.env', 'secrets/**'],
+    },
+    hooks: {
+      UserPromptSubmit: [],
+      PreToolUse: [],
+      PostToolUse: [],
+      Stop: [],
+    },
+  }, null, 2) + '\n',
+  'KEPLER.md': `# Project
+
+## Quick Facts
+- Stack:
+- Test command:
+- Lint command:
+- Build command:
+
+## Key Directories
+
+## Code Style
+
+## Critical Rules
+`,
+  'project.md': '# Project Context\n\nAdd durable project context here.\n',
+  'style.md': '# Style\n\nAdd code and communication conventions here.\n',
+  'hitl.md': '# HITL Guidance\n\nAdd project-specific approval guidance here.\n',
+  'trust.json': JSON.stringify({ version: 1, rules: [] }, null, 2) + '\n',
+  'tasks/README.md': `# Bahulam Tasks
+
+Checklist files are read every turn.
+
+- \`backlog.md\` - pending tasks
+- \`active.md\` - current task
+- \`done.md\` - completed tasks
+- \`blocked.md\` - waiting on input
+`,
+  'tasks/backlog.md': '# Backlog\n\n',
+  'tasks/active.md': '# Active\n\n',
+  'tasks/done.md': '# Done\n\n',
+  'tasks/blocked.md': '# Blocked\n\n',
+  'skills/starter/SKILL.md': `---
+name: starter
+description: Project-specific conventions and setup notes. Use when onboarding to this repo.
+---
+
+# Starter Skill
+
+Add reusable project knowledge here.
+`,
+  'commands/onboard.md': `---
+name: onboard
+description: Explore the project and record onboarding notes.
+---
+
+# Onboard
+
+Context:
+$ARGUMENTS
+
+Explore the codebase, ask clarifying questions, and record useful notes in .bahulam/tasks/active.md.
+`,
+};
+
+export function scaffoldKeplerProject({ cwd = process.cwd(), force = false } = {}) {
+  const root = path.join(cwd, '.bahulam');
+  const written = [];
+  const skipped = [];
+  for (const [rel, content] of Object.entries(FILES)) {
+    const filePath = path.join(root, rel);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (fs.existsSync(filePath) && !force) {
+      skipped.push(filePath);
+      continue;
+    }
+    fs.writeFileSync(filePath, content);
+    written.push(filePath);
+  }
+
+  const gitignore = path.join(root, '.gitignore');
+  if (!fs.existsSync(gitignore) || force) {
+    fs.writeFileSync(gitignore, 'settings.local.json\nsessions/\nreports/\n*.log\n');
+    written.push(gitignore);
+  }
+
+  return { root, written, skipped };
+}
+
+export async function runInitCommand(args = [], { cwd = process.cwd() } = {}) {
+  const force = args.includes('--force');
+  const result = scaffoldKeplerProject({ cwd, force });
+  process.stderr.write(`\x1b[32m✓\x1b[0m Initialized .bahulam at ${result.root}\n`);
+  process.stderr.write(`  wrote ${result.written.length} files`);
+  if (result.skipped.length) process.stderr.write(`, skipped ${result.skipped.length} existing files`);
+  process.stderr.write('\n');
+}

package/src/terminal/main.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * Bahulam Code CLI — ANSI Terminal UI. Bahulam's coding agent.
+ * Zero React. Zero Ink. Zero flickering.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { startTerminalRepl } from './repl.mjs';
+import {
+  runSessionsCommand,
+  runStatsCommand,
+  runHistoryCommand,
+} from './analytics.mjs';
+import { parseArgs } from '../config/cli-args.mjs';
+import * as telemetry from '../telemetry/index.mjs';
+import { bahulamHome } from '../core/paths.mjs';
+import { TarangAuth as Auth } from '../auth/tarang-auth.mjs';
+
+// ── Subcommands ──
+
+const subcommand = process.argv[2];
+const subcommandArgs = process.argv.slice(3);
+
+function parseKeplerSubcommandArgs(command, argv) {
+  const parsed = {
+    command,
+    workflowSubcommand: null,
+    workflowSlug: null,
+    workflowFile: null,
+    workflowDir: null,
+    agentSubcommand: null,
+    agentSlug: null,
+    agentDir: null,
+    instruction: null,
+    pattern: null,
+    yes: false,
+    verbose: false,
+    debug: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--file':
+      case '-f':
+        parsed.workflowFile = argv[++i];
+        break;
+      case '--dir':
+        if (command === 'agent') parsed.agentDir = argv[++i];
+        else parsed.workflowDir = argv[++i];
+        break;
+      case '--instruction':
+      case '--input':
+      case '--print':
+      case '-p':
+        parsed.instruction = argv[++i];
+        break;
+      case '--pattern':
+        parsed.pattern = argv[++i];
+        break;
+      case '--yes':
+      case '-y':
+        parsed.yes = true;
+        break;
+      case '--verbose':
+      case '-v':
+        parsed.verbose = true;
+        break;
+      case '--debug':
+      case '-d':
+        parsed.debug = true;
+        parsed.verbose = true;
+        break;
+      default:
+        if (arg.startsWith('-')) break;
+        if (command === 'workflow') {
+          if (!parsed.workflowSubcommand) parsed.workflowSubcommand = arg;
+          else if (!parsed.workflowSlug) parsed.workflowSlug = arg;
+        } else if (command === 'agent') {
+          if (!parsed.agentSubcommand) parsed.agentSubcommand = arg;
+          else if (!parsed.agentSlug) parsed.agentSlug = arg;
+        }
+        break;
+    }
+  }
+
+  return parsed;
+}
+
+function detectInstallFirstRun() {
+  const markerPath = path.join(bahulamHome(), '.install_marker');
+  try {
+    if (fs.existsSync(markerPath)) return false;
+    fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });
+    return true;
+  } catch { return false; }
+}
+
+async function main() {
+  // ── Telemetry bootstrap ──
+  const _auth = new Auth();
+  const _creds = _auth.loadCredentials();
+  telemetry.configure(_creds.backendUrl, _creds.token);
+
+  // Fire install_first_run on first ever CLI invocation
+  if (detectInstallFirstRun()) {
+    telemetry.track('install_first_run', { version: process.env.npm_package_version || '' });
+  }
+
+  // Check day7_return — fire once per install
+  const configDir_ = bahulamHome();
+  const installMarker_ = path.join(configDir_, '.install_marker');
+  const returnFiredPath_ = path.join(configDir_, '.return_fired');
+  try {
+    if (fs.existsSync(installMarker_) && !fs.existsSync(returnFiredPath_)) {
+      const installTime = parseInt(fs.readFileSync(installMarker_, 'utf-8').trim(), 10);
+      if (!isNaN(installTime) && Date.now() - installTime >= 7 * 24 * 60 * 60 * 1000) {
+        telemetry.track('day7_return', {});
+        fs.writeFileSync(returnFiredPath_, '1', { mode: 0o600 });
+      }
+    }
+  } catch {}
+
+  if (subcommand === 'dashboard') {
+    // Launch Bahulam Pulse Next.js dashboard
+    const { spawn } = await import('node:child_process');
+    const { fileURLToPath } = await import('node:url');
+    const path = await import('node:path');
+    const cliPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'pulse', 'cli.js');
+    const child = spawn(process.execPath, [cliPath, ...subcommandArgs], {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    return;
+  }
+
+  if (subcommand === 'sessions') {
+    await runSessionsCommand(subcommandArgs);
+    return;
+  }
+
+  if (subcommand === 'stats') {
+    await runStatsCommand(subcommandArgs);
+    return;
+  }
+
+  if (subcommand === 'history') {
+    await runHistoryCommand(subcommandArgs);
+    return;
+  }
+
+  if (subcommand === 'init') {
+    const { runInitCommand } = await import('./init.mjs');
+    await runInitCommand(subcommandArgs);
+    return;
+  }
+
+  if (subcommand === 'skills' || subcommand === 'skill') {
+    const { runSkillsCommand } = await import('./skills.mjs');
+    try {
+      await runSkillsCommand(subcommandArgs);
+    } catch (err) {
+      process.stderr.write(`\x1b[31m✗ Skills command failed: ${err.message}\x1b[0m\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (subcommand === 'login') {
+    const { TarangAuth } = await import('../auth/tarang-auth.mjs');
+    const auth = new TarangAuth();
+    try {
+      telemetry.track('login_shown', { method: 'cli_subcommand' });
+      await auth.login();
+      telemetry.track('login_completed', { method: 'cli_subcommand' });
+      process.stderr.write('\x1b[32m✓ Login successful!\x1b[0m\n');
+      return;
+    } catch (err) {
+      process.stderr.write(`\x1b[31m✗ Login failed: ${err.message}\x1b[0m\n`);
+      process.exit(1);
+    }
+  }
+
+  if (subcommand === 'logout') {
+    const { TarangAuth } = await import('../auth/tarang-auth.mjs');
+    const auth = new TarangAuth();
+    const success = auth.logout();
+    if (success) {
+      process.stderr.write('\x1b[32m✓ Signed out. Credentials cleared.\x1b[0m\n');
+    } else {
+      process.stderr.write('\x1b[33m! No credentials to clear.\x1b[0m\n');
+    }
+    return;
+  }
+
+  if (subcommand === 'workflow') {
+    const { handleWorkflowCommand } = await import('../commands/workflow.mjs');
+    await handleWorkflowCommand(parseKeplerSubcommandArgs('workflow', subcommandArgs));
+    return;
+  }
+
+  if (subcommand === 'agent') {
+    const { handleAgentCommand } = await import('../commands/agent.mjs');
+    await handleAgentCommand(parseKeplerSubcommandArgs('agent', subcommandArgs));
+    return;
+  }
+
+  if (subcommand === 'version' || subcommand === '--version' || subcommand === '-v') {
+    const { createRequire } = await import('node:module');
+    const require = createRequire(import.meta.url);
+    const { version } = require('../../package.json');
+    process.stdout.write(`Bahulam Code v${version}\n`);
+    return;
+  }
+
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    process.stderr.write(`
+  \x1b[1m\x1b[36mBahulam Code\x1b[0m — Bahulam's coding agent — bahulam.ai
+
+  \x1b[1mUsage:\x1b[0m
+    bahulam                        Start interactive REPL
+    bahulam "instruction"          Run a single instruction
+    bahulam --headless -p "x"      Non-interactive: auto-approve, JSONL output
+    bahulam --headless -p "x" --vision screenshot.png
+                              Attach an image via the vision analysis pipeline
+    bahulam --resume               Resume last conversation
+    bahulam dashboard              Open analytics dashboard
+    bahulam login                  Sign in via browser
+    bahulam logout                 Sign out and clear credentials
+    bahulam init                   Scaffold .bahulam config, memory, hooks, tasks
+    bahulam version                Show version
+
+  \x1b[1mAnalytics:\x1b[0m
+    bahulam sessions               List recent local sessions
+    bahulam stats                  Show aggregate local session stats
+    bahulam history                Show recent prompt history
+
+  \x1b[1mSkills:\x1b[0m
+    bahulam skills list [--all|--project]
+    bahulam skills view <name> [resource]
+    bahulam skills install <path-or-git-url> [--project] [--force]
+    bahulam skills update <name> [--project]
+    bahulam skills remove <name> [--project]
+
+  \x1b[1mREPL Commands:\x1b[0m
+    /help                   Show available commands
+    /stats                  Session metrics (tokens, cost, tools)
+    /cost                   Detailed cost breakdown by model
+    /model [role] [model]   Show or set session model override
+    /history                Conversation history
+    /new                    Start a new session
+    /clear                  Clear conversation history
+    /safety                 Show safety guardrail status
+    /revoke                 Revoke auto-approvals
+    /explore <query>        Spawn read-only codebase explorer
+    /review <query>         Spawn code review agent
+    /architect <query>      Spawn architecture planning agent
+    /agents create <name>   Create project-local user-defined agent YAML
+    /agents edit <name>     Open a local agent YAML in your editor
+    /agents sync [name]     Sync all or one local agent to Supabase
+    /attach <image-path>    Attach an image to next prompt
+    /attach clipboard       Attach image copied to macOS/Windows clipboard
+    /exit                   Exit the REPL
+
+  \x1b[1mKeyboard:\x1b[0m
+    Esc                     Cancel current execution
+    Space                   Pause / resume execution
+    Ctrl+C                  Exit
+
+  \x1b[1mEnvironment:\x1b[0m
+    TARANG_ENV              Set backend (local, treetop, production)
+    ANTHROPIC_API_KEY       Direct Anthropic API key
+    OPENROUTER_API_KEY      OpenRouter API key
+    BAHULAM_CONFIG_DIR        Override config directory (default: ~/.bahulam)
+    KEPLER_CONFIG_DIR         Legacy config directory override
+    KEPLER_RECONNECT_MAX_ELAPSED_MS
+                            Max reconnect window for dropped streams
+    BAHULAM_TTY_MODE=stable Scrollback-safe transcript if fixed dock redraws leak
+    KEPLER_BLOCK_SEPARATOR  Tool/content separator: space, dotted, or off
+
+  \x1b[2mDocs: https://bahulam.ai\x1b[0m
+`);
+    return;
+  }
+
+  // ── Headless mode (benchmarks, automation) ──
+  const args = parseArgs(process.argv.slice(2));
+  if (args.prompt && (process.argv.includes('--headless') || !process.stdin.isTTY)) {
+    const { runHeadless } = await import('../core/headless.mjs');
+    await runHeadless({
+      instruction: args.prompt,
+      model: args.model,
+      timeout: args.timeout || (args.maxTurns ? args.maxTurns * 60 : 600),
+      verbose: args.verbose,
+      cacheReport: args.cacheReport,
+      local: args.local,
+      vision: args.vision,
+    });
+    return;
+  }
+
+  await startTerminalRepl();
+}
+
+main().catch(err => {
+  process.stderr.write(`\x1b[31mFatal: ${err.message}\x1b[0m\n`);
+  process.exit(1);
+});

package/src/terminal/repl-ask-form.mjs

@@ -0,0 +1,120 @@
+/**
+ * Interactive ask_user form — rendered when the agent calls the ask_user
+ * tool mid-turn to get direction (architecture choice, design decision,
+ * ambiguous next step, conflicting instructions, …).
+ *
+ * Same raw-stdin overlay pattern as repl-model-form.mjs: pause readline,
+ * raw mode on, redraw in place, restore on exit. Two input modes:
+ *   list — ↑↓ move across options (+ an "Other" row), Enter selects,
+ *          Esc declines (agent proceeds with its own judgment)
+ *   text — the "Other" row opens a free-text line; Enter submits,
+ *          Esc returns to the list
+ */
+
+import { c } from './ansi.mjs';
+import { fitAnsiLine, writeOverlayFrame, eraseOverlayFrame } from './repl-format.mjs';
+
+const OTHER_SENTINEL = '__other__';
+
+/**
+ * @param {object} opts
+ * @param {object|null} opts.rl       readline instance to pause/resume
+ * @param {string} opts.question      the question to display
+ * @param {string[]} opts.options     2-4 option labels from the agent
+ * @param {string} [opts.context]     optional one-line context above the question
+ * @returns {Promise<{answer: string, source: 'option'|'free_text'}|null>}
+ *          null = user declined (Esc) — the agent should proceed on its own
+ */
+export async function askUserForm({ rl, question, options, context }) {
+  if (!process.stdin.isTTY) return null;
+  if (rl) rl.pause();
+
+  const optionRows = (options || []).map(o => String(o || '').trim()).filter(Boolean);
+  const rows = [...optionRows, OTHER_SENTINEL];
+
+  return await new Promise((resolve) => {
+    const wasRaw = process.stdin.isRaw;
+    let cursor = 0;
+    let renderedLines = 0;
+    let mode = 'list';   // 'list' | 'text'
+    let freeText = '';
+
+    const render = () => {
+      const cols = Math.max(60, process.stderr.columns || 120);
+      const lines = [];
+      lines.push(`  ${c.bold('Agent question')} ${c.dim('· pick an option or type your own · Esc to let the agent decide')}`);
+      if (context) {
+        lines.push(fitAnsiLine(`  ${c.dim(String(context))}`, cols - 1));
+      }
+      lines.push('');
+      lines.push(fitAnsiLine(`  ${c.brand('?')} ${c.bold(String(question || ''))}`, cols - 1));
+      lines.push('');
+      rows.forEach((row, i) => {
+        const active = i === cursor;
+        const marker = active ? c.brand('▸') : ' ';
+        if (row === OTHER_SENTINEL) {
+          if (mode === 'text' && active) {
+            lines.push(fitAnsiLine(`  ${marker} ${c.brand('Other:')} ${freeText}${c.brand('▎')}`, cols - 1));
+          } else {
+            lines.push(fitAnsiLine(`  ${marker} ${active ? c.brand('Other — type your own answer') : c.dim('Other — type your own answer')}`, cols - 1));
+          }
+        } else {
+          lines.push(fitAnsiLine(`  ${marker} ${active ? c.brand(row) : row}`, cols - 1));
+        }
+      });
+      lines.push('');
+      lines.push(fitAnsiLine(
+        mode === 'text'
+          ? `  ${c.dim('type your answer · Enter submit · Esc back to options')}`
+          : `  ${c.dim('↑↓ move · Enter select · Esc decline (agent decides)')}`,
+        cols - 1,
+      ));
+      writeOverlayFrame(renderedLines, lines);
+      renderedLines = lines.length;
+    };
+
+    const cleanup = (value) => {
+      process.stdin.removeListener('data', onData);
+      process.stdin.setRawMode(wasRaw || false);
+      eraseOverlayFrame(renderedLines);
+      if (rl) rl.resume();
+      resolve(value);
+    };
+
+    const onData = (data) => {
+      const key = data.toString('utf8');
+
+      if (mode === 'text') {
+        if (key === '\x1b') { mode = 'list'; freeText = ''; render(); return; }
+        if (key === '\x03') { cleanup(null); return; }
+        if (key === '\r' || key === '\n') {
+          const answer = freeText.trim();
+          if (answer) { cleanup({ answer, source: 'free_text' }); }
+          return;
+        }
+        if (key === '\x7f' || key === '\b') { freeText = freeText.slice(0, -1); render(); return; }
+        // Ignore other escape sequences (arrows etc.) while typing.
+        if (key.startsWith('\x1b')) return;
+        const printable = [...key].filter(ch => ch >= ' ').join('');
+        if (printable) { freeText += printable; render(); }
+        return;
+      }
+
+      // list mode
+      if (key === '\x1b' || key === '\x03' || key === 'q') { cleanup(null); return; }
+      if (key === '\r' || key === '\n') {
+        const row = rows[cursor];
+        if (row === OTHER_SENTINEL) { mode = 'text'; freeText = ''; render(); return; }
+        cleanup({ answer: row, source: 'option' });
+        return;
+      }
+      if (key === '\x1b[A') { cursor = Math.max(0, cursor - 1); render(); return; }
+      if (key === '\x1b[B') { cursor = Math.min(rows.length - 1, cursor + 1); render(); return; }
+    };
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+    render();
+  });
+}

package/src/terminal/repl-explore.mjs

@@ -0,0 +1,44 @@
+/**
+ * Explore-run classifier — pure category lookup for the read/list/search/index
+ * tool bursts that get collapsed into one animated summary line during a
+ * sub-agent run.
+ *
+ * These functions are stateless. The mutable run state (counts, recent
+ * paths, lineActive flag) still lives in repl.mjs during the split.
+ */
+
+const EXPLORE_TOOL_CATEGORY = new Map([
+  ['read_file', 'read'], ['read', 'read'], ['read_files', 'read'],
+  ['read_batch', 'read'], ['get_file_info', 'read'],
+  // analyze_code is the "cheap 10x-lighter than read_file" tool the system
+  // prompt tells the agent to prefer for structure lookups. Burst usage is
+  // as common as read bursts, so classify it as a read for collapse.
+  ['analyze_code', 'read'],
+  ['list_files', 'list'], ['glob', 'list'], ['ls', 'list'],
+  ['search_code', 'search'], ['search_files', 'search'], ['grep', 'search'],
+  // validate_* tools are read-only structure/build checks the agent chains
+  // during post-write verification. They fit naturally in a search-ish bucket
+  // ("checking") rather than opening a discrete card per call.
+  ['validate_file', 'search'], ['validate_structure', 'search'],
+  ['index_project', 'index'], ['register_project', 'index'],
+  ['get_project_overview', 'index'],
+]);
+
+export function exploreCollapseEnabled() {
+  return process.env.KEPLER_EXPLORE_COLLAPSE !== '0';
+}
+
+export function isExploreTool(tool) {
+  if (!exploreCollapseEnabled()) return false;
+  return EXPLORE_TOOL_CATEGORY.has(String(tool || '').toLowerCase());
+}
+
+export function exploreCategory(tool) {
+  return EXPLORE_TOOL_CATEGORY.get(String(tool || '').toLowerCase()) || 'explore';
+}
+
+// Test-only accessor so unit tests can enumerate the recognized tools
+// without importing the private Map.
+export function _knownExploreTools() {
+  return [...EXPLORE_TOOL_CATEGORY.keys()];
+}