draco-cli 0.0.0-stage → 3.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anuj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Draco CLI
+
+![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green)
+![License: MIT](https://img.shields.io/badge/License-MIT-green)
+![Author: Anuj Mhatre](https://img.shields.io/badge/Author-Anuj%20Mhatre-orange)
+
+## Why We Built This
+
+Developers need AI coding assistance directly in their terminal without switching contexts. Draco CLI provides a zero-login, terminal-first AI coding agent powered by the OpenCode Zen API.
+
+## What It Does
+
+- Interactive REPL for AI-assisted coding in the terminal
+- One-shot mode for quick questions: `draco "explain this error"`
+- Auto-apply file edits with configurable approval levels
+- Session persistence and resume with `--continue`
+- MCP server integration for extended tool capabilities
+- Multiple model support via `--model` flag
+
+## How It Was Built
+
+- **Runtime:** Node.js 18+ with CommonJS modules
+- **API:** OpenAI-compatible (OpenCode Zen)
+- **Interface:** readline-based terminal UI with color support
+- **Architecture:** Modular (CLI args, session management, providers, tools)
+- **MCP:** Model Context Protocol for tool integrations
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g draco-cli
+
+# Or run directly
+node bin/draco.js
+
+# One-shot mode
+draco "write a Python hello world"
+
+# With specific model
+draco --model=gpt-4 "refactor this function"
+```
+
+**Environment Variables:**
+```bash
+export OPENCODE_ZEN_KEY="your-api-key"
+export DRACO_MODEL="nemotron-3-ultra-free"
+export DRACO_APPROVALS="suggest"  # suggest | auto-edit | full-auto
+```
+
+## Project Structure
+
+```
+draco-cli/
+├── bin/
+│   └── draco.js          # Entry point
+├── src/
+│   ├── index.js          # Main orchestrator
+│   ├── config.js         # Configuration management
+│   ├── cli/              # Args parsing, REPL, line queue
+│   ├── core/             # Session management
+│   ├── providers/        # AI provider integrations
+│   ├── tools/            # File/shell tools
+│   ├── integrations/     # MCP client
+│   └── ui/               # Terminal UI utilities
+├── package.json          # Dependencies
+└── ARCHITECTURE.md       # Detailed architecture docs
+```
+
+## Test Results
+
+Manual CLI testing. No automated test suite (interactive terminal project).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/bin/draco.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/index.js');
+
+main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,32 @@
-{
-  "name": "draco-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "draco-cli",
+  "version": "3.0.2",
+  "description": "Draco — a zero-login, terminal-first AI coding agent for the OpenCode Zen API.",
+  "license": "MIT",
+  "author": "Anuj",
+  "bin": {
+    "draco": "./bin/draco.js"
+  },
+  "main": "src/index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "coding-agent",
+    "opencode",
+    "zen",
+    "terminal",
+    "agent"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/draco.js"
+  }
+}

package/src/cli/args.js

@@ -0,0 +1,28 @@
+'use strict';
+
+function parseArgs(argv) {
+  const flags = { model: undefined, yolo: false, version: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--version' || a === '-v') flags.version = true;
+    else if (a === '--yolo') flags.yolo = true;
+    else if (a === '--continue' || a === '-c') flags.continueSession = true;
+    else if (a === '--suggest') flags.approvals = 'suggest';
+    else if (a === '--auto-edit') flags.approvals = 'auto-edit';
+    else if (a === '--full-auto') flags.approvals = 'full-auto';
+    else if (a.startsWith('--model=')) flags.model = a.slice('--model='.length);
+    else if (a === '--model') {
+      if (i + 1 >= argv.length) throw new Error('--model requires a value.');
+      flags.model = argv[++i];
+    } else if (a.startsWith('-') && a !== '-') {
+      throw new Error(`Unknown option: ${a}`);
+    } else {
+      flags.promptArgs = flags.promptArgs || [];
+      flags.promptArgs.push(a);
+    }
+  }
+  return flags;
+}
+
+module.exports = { parseArgs };

package/src/cli/command-registry.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { SlashCommand } = require('./slash-commands');
+
+class CommandRegistry {
+  constructor() {
+    this.commands = new Map();
+    this.aliases = new Map();
+    this.groups = new Map();
+  }
+
+  register(command) {
+    if (!(command instanceof SlashCommand)) {
+      throw new Error('Command must be an instance of SlashCommand');
+    }
+
+    this.commands.set(command.name, command);
+
+    for (const alias of command.aliases) {
+      this.aliases.set(alias, command.name);
+    }
+
+    const group = command.group || 'General';
+    if (!this.groups.has(group)) {
+      this.groups.set(group, []);
+    }
+    this.groups.get(group).push(command.name);
+
+    return this;
+  }
+
+  unregister(name) {
+    const command = this.commands.get(name) || this.getCommand(this.aliases.get(name));
+    if (!command) return false;
+
+    this.commands.delete(command.name);
+    for (const alias of command.aliases) {
+      this.aliases.delete(alias);
+    }
+
+    const group = this.groups.get(command.group);
+    if (group) {
+      const idx = group.indexOf(command.name);
+      if (idx !== -1) group.splice(idx, 1);
+    }
+
+    return true;
+  }
+
+  getCommand(name) {
+    if (!name) return null;
+    const resolvedName = this.aliases.get(name) || name;
+    return this.commands.get(resolvedName) || null;
+  }
+
+  async execute(name, args, context) {
+    const command = this.getCommand(name);
+    if (!command) {
+      return { success: false, error: `Unknown command: ${name}` };
+    }
+
+    try {
+      if (command.middleware && command.middleware.length > 0) {
+        for (const middleware of command.middleware) {
+          const result = await middleware(args, context);
+          if (result === false) {
+            return { success: false, error: 'Middleware rejected command' };
+          }
+        }
+      }
+
+      const result = await command.execute(args, context);
+      return { success: true, result };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  listCommands() {
+    const commands = [];
+    for (const [name, command] of this.commands) {
+      commands.push({
+        name,
+        description: command.description,
+        group: command.group,
+        aliases: command.aliases,
+        usage: command.usage,
+      });
+    }
+    return commands;
+  }
+
+  listByGroup() {
+    const grouped = {};
+    for (const [group, commandNames] of this.groups) {
+      grouped[group] = commandNames.map((name) => {
+        const cmd = this.commands.get(name);
+        return {
+          name,
+          description: cmd.description,
+          usage: cmd.usage,
+        };
+      });
+    }
+    return grouped;
+  }
+
+  findCommands(query) {
+    const results = [];
+    const lowerQuery = query.toLowerCase();
+
+    for (const [name, command] of this.commands) {
+      if (
+        name.toLowerCase().includes(lowerQuery) ||
+        command.description.toLowerCase().includes(lowerQuery)
+      ) {
+        results.push({
+          name,
+          description: command.description,
+          group: command.group,
+          usage: command.usage,
+        });
+      }
+    }
+
+    return results;
+  }
+}
+
+module.exports = { CommandRegistry };

package/src/cli/line-queue.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// One permanent 'line' listener feeding a queue + waiter list; nextLine() serves
+// both the main prompt and nested confirmations in arrival order so no piped or
+// pasted input line is ever dropped.
+function createLineQueue(rl) {
+  const queue = [];
+  const waiters = [];
+  const state = { closed: false };
+
+  rl.on('line', (line) => {
+    const w = waiters.shift();
+    if (w) w.resolve(line);
+    else queue.push(line);
+  });
+
+  rl.on('close', () => {
+    state.closed = true;
+    while (waiters.length) waiters.shift().resolve(null);
+  });
+
+  function nextLine() {
+    if (queue.length > 0) return Promise.resolve(queue.shift());
+    if (state.closed) return Promise.resolve(null);
+    return new Promise((resolve) => waiters.push({ resolve }));
+  }
+
+  function isClosed() {
+    return state.closed;
+  }
+
+  return { nextLine, isClosed };
+}
+
+module.exports = { createLineQueue };

package/src/cli/oneshot.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const ui = require('../ui/terminal.js');
+
+async function runOneShot({ prompt, agent }) {
+  try {
+    process.stdout.write(`${ui.c.green}➜${ui.c.reset} ${prompt}\n`);
+    ui.divider();
+    await agent.runTurn(prompt);
+    return 0;
+  } catch (e) {
+    ui.error(e && e.message ? e.message : String(e));
+    return 1;
+  }
+}
+
+module.exports = { runOneShot };

package/src/cli/repl.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const path = require('path');
+const config = require('../config.js');
+const ui = require('../ui/terminal.js');
+const { handle, EXIT } = require('./slash-commands.js');
+
+async function runRepl({ cfg, rl, lineQueue, agent, mcp }) {
+  const nextLine = lineQueue.nextLine;
+  const rt = { cfg, agent, mcp };
+  const basename = path.basename(cfg.workspaceRoot);
+
+  try {
+    while (true) {
+      if (!lineQueue.isClosed()) {
+        rl.setPrompt(ui.promptText(basename));
+        rl.prompt();
+      }
+      const line = await nextLine();
+      if (line === null) break;
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      ui.divider();
+      let result;
+      try {
+        result = await handle(trimmed, rt);
+      } catch (e) {
+        ui.error(e && e.message ? e.message : String(e));
+        continue;
+      }
+      if (result === EXIT) break;
+      if (result === false) {
+        await agent.runTurn(trimmed).catch((e) => {
+          ui.error(e && e.message ? e.message : String(e));
+        });
+      }
+    }
+  } finally {
+    ui.info('Goodbye.');
+    try {
+      rl.close();
+    } catch {}
+  }
+}
+
+module.exports = { runRepl };

package/src/cli/slash-commands.js

@@ -0,0 +1,271 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const api = require('../providers/openai-compatible.js');
+const { listSessions } = require('../core/sessions-store.js');
+const { APPROVAL_MODES } = require('../core/approvals.js');
+const config = require('../config.js');
+const ui = require('../ui/terminal.js');
+
+const EXIT = Symbol('exit');
+
+const HELP_LINES = [
+  'Commands:',
+  '  /help                  Show this help',
+  '  /models                List models from the live registry (cached list on failure)',
+  '  /model [id]            Show or switch the active model (persists)',
+  '  /approvals [mode]      suggest | auto-edit | full-auto (persists)',
+  '  /yolo [on|off]         Shortcut for full-auto vs suggest',
+  '  /sessions              List saved conversation sessions',
+  '  /resume [n]            Resume a saved session in place',
+  '  /compact               Summarize the conversation to free context',
+  '  /usage                 Session usage stats',
+  '  /retry                 Resend your last message',
+  '  /config                Show effective configuration',
+  '  /clear                 Reset the conversation (keeps the system prompt)',
+  '  /init                  Generate an AGENTS.md project-instructions file',
+  '  /version               Print version',
+  '  /quit, /exit           Leave Draco',
+];
+
+function helpText(cfg) {
+  const lines = HELP_LINES.slice();
+  if (!cfg.searchApiKey) {
+    lines.push(
+      '',
+      `${ui.c.gray}Web search uses DuckDuckGo (no key needed). Set DRACO_SEARCH_API_KEY to use Brave.${ui.c.reset}`
+    );
+  }
+  return lines.join('\n');
+}
+
+function describeSession(entry, i) {
+  const d = entry.data;
+  const firstUser = (d.messages.find((m) => m.role === 'user' && typeof m.content === 'string') || {}).content;
+  let preview = firstUser ? String(firstUser).replace(/\s+/g, ' ').slice(0, 48) : '(no prompt yet)';
+  return `${String(i + 1).padStart(2)}  ${d.cwd}  ${ui.c.gray}${(d.updatedAt || '').slice(0, 16).replace('T', ' ')}${ui.c.reset}  ${d.model}\n    ${ui.c.dim}${preview}${ui.c.reset}`;
+}
+
+async function handle(line, rt) {
+  if (!line.startsWith('/')) return false;
+  const [cmdRaw, ...rest] = line.trim().split(/\s+/);
+  const cmd = cmdRaw.toLowerCase();
+  const arg = rest.join(' ').trim();
+  const cfg = rt.cfg;
+
+  switch (cmd) {
+    case '/help':
+      process.stdout.write(helpText(cfg) + '\n');
+      return true;
+
+    case '/version':
+      process.stdout.write(`Draco CLI v${cfg.version}\n`);
+      return true;
+
+    case '/models': {
+      ui.info('Fetching model registry…');
+      try {
+        const ids = await api.listModels(cfg);
+        for (const id of ids) {
+          const marker = id === rt.agent.activeModel ? `${ui.c.green}*${ui.c.reset} ` : '  ';
+          process.stdout.write(`${marker}${id}\n`);
+        }
+        process.stdout.write(
+          `${ui.c.gray}(active marked with *; some accounts use an "opencode/" prefix — switch with /model opencode/<id>)${ui.c.reset}\n`
+        );
+      } catch (e) {
+        ui.error(
+          `Could not fetch live registry (${e.message || e}). Showing cached known free models:`
+        );
+        for (const id of config.KNOWN_FREE_MODELS) {
+          const marker = id === rt.agent.activeModel ? `${ui.c.green}*${ui.c.reset} ` : '  ';
+          process.stdout.write(`${marker}${id}\n`);
+        }
+      }
+      return true;
+    }
+
+    case '/model': {
+      if (!arg) {
+        process.stdout.write(`Active model: ${rt.agent.activeModel}\n`);
+        return true;
+      }
+      rt.agent.setModel(arg);
+      try {
+        config.persistConfig({ model: arg });
+        ui.success(`Model set to ${arg} (persisted to ${cfg.configFile}).`);
+      } catch (e) {
+        ui.error(`Model switched to ${arg} for this session, but persisting failed: ${e.message}`);
+      }
+      return true;
+    }
+
+    case '/yolo': {
+      const next = arg === 'on' ? 'full-auto' : arg === 'off' ? 'suggest' : (cfg.approvals === 'full-auto' ? 'suggest' : 'full-auto');
+      cfg.approvals = next;
+      cfg.yolo = next === 'full-auto';
+      try {
+        config.persistConfig({ approvals: next });
+      } catch {}
+      if (next === 'full-auto') ui.warn('FULL-AUTO — shell commands run without confirmation. Use with care.');
+      else ui.success(`Approval mode: ${next}.`);
+      return true;
+    }
+
+    case '/approvals': {
+      const modes = APPROVAL_MODES;
+      if (!arg) {
+        process.stdout.write(
+          [
+            `Approval mode: ${cfg.approvals}`,
+            '',
+            `${ui.c.bold}suggest${ui.c.reset}    ask before file writes AND shell commands`,
+            `${ui.c.bold}auto-edit${ui.c.reset}  apply file edits automatically, still ask before shell`,
+            `${ui.c.bold}full-auto${ui.c.reset}  everything runs without asking`,
+          ].join('\n') + '\n'
+        );
+        return true;
+      }
+      const mode = arg.toLowerCase();
+      if (!modes.includes(mode)) {
+        ui.error(`Unknown mode "${arg}". Use one of: ${modes.join(', ')}.`);
+        return true;
+      }
+      cfg.approvals = mode;
+      cfg.yolo = mode === 'full-auto';
+      try {
+        config.persistConfig({ approvals: mode });
+        ui.success(`Approval mode: ${mode} (persisted).`);
+      } catch {
+        ui.success(`Approval mode: ${mode} (this session).`);
+      }
+      return true;
+    }
+
+    case '/sessions': {
+      const sessions = listSessions();
+      if (!sessions.length) {
+        ui.info('No saved sessions yet. Conversations auto-save as you chat.');
+        return true;
+      }
+      process.stdout.write(sessions.map((s, i) => describeSession(s, i)).join('\n') + '\n');
+      return true;
+    }
+
+    case '/resume': {
+      const sessions = listSessions();
+      if (!sessions.length) {
+        ui.info('No saved sessions to resume.');
+        return true;
+      }
+      const idx = parseInt(arg, 10);
+      if (!Number.isInteger(idx) || idx < 1 || idx > sessions.length) {
+        process.stdout.write(sessions.map((s, i) => describeSession(s, i)).join('\n') + '\n');
+        ui.info('Run /resume <number> to restore one.');
+        return true;
+      }
+      const chosen = sessions[idx - 1];
+      if (rt.agent.importSession(chosen.data)) {
+        ui.success(`Resumed session from ${chosen.data.cwd} (${chosen.data.model}).`);
+      } else {
+        ui.error('That session could not be restored.');
+      }
+      return true;
+    }
+
+    case '/compact': {
+      await rt.agent.compact();
+      return true;
+    }
+
+    case '/usage': {
+      const u = rt.agent.getUsage();
+      const lines = [
+        `messages in context:  ${u.messages}`,
+        `turns this session:   ${u.turns}`,
+        `response characters:  ${u.outputChars}`,
+        `approx output tokens: ~${Math.round(u.outputChars / 4)}`,
+      ];
+      process.stdout.write(lines.join('\n') + '\n');
+      return true;
+    }
+
+    case '/init': {
+      const target = path.join(cfg.workspaceRoot, 'AGENTS.md');
+      if (fs.existsSync(target)) {
+        ui.warn('AGENTS.md already exists here — edit it directly.');
+        return true;
+      }
+      const template = [
+        `# AGENTS.md`,
+        '',
+        `Instructions for Draco (and other coding agents) working in this repository.`,
+        '',
+        '## Project overview',
+        '- What this project does:',
+        '',
+        '## Build & test commands',
+        '- Install:',
+        '- Build:',
+        '- Test:',
+        '',
+        '## Conventions',
+        '- Language/framework:',
+        '- Style rules:',
+        '- Files or directories never to modify:',
+        '',
+      ].join('\n');
+      try {
+        fs.writeFileSync(target, template);
+        ui.success(`Created ${target}. Fill it in — Draco reads it automatically every session.`);
+      } catch (e) {
+        ui.error(`Could not write AGENTS.md: ${e.message}`);
+      }
+      return true;
+    }
+
+    case '/config': {
+      const k = cfg.apiKey;
+      const masked = k
+        ? (k.length > 10 ? `${k.slice(0, 4)}…${k.slice(-4)}` : '•••')
+        : 'not set';
+      const mcpCount = rt.mcp ? rt.mcp.listTools().length : 0;
+      const lines = [
+        `version:       ${cfg.version}`,
+        `endpoint:      ${cfg.apiBase}`,
+        `model:         ${rt.agent.activeModel}`,
+        `approvals:     ${cfg.approvals}`,
+        `fallbackChain: ${cfg.fallbackChain.join(' -> ')}`,
+        `search:        ${cfg.searchApiKey ? `${cfg.searchProvider} (key set)` : 'duckduckgo (keyless)'}`,
+        `mcp tools:     ${mcpCount}`,
+        `workspaceRoot: ${cfg.workspaceRoot}`,
+        `config file:   ${cfg.configFile}`,
+        `api key:       ${masked} (${cfg.keySource || 'unknown source'})`,
+      ];
+      process.stdout.write(lines.map((l) => `${ui.c.gray}${l}${ui.c.reset}`).join('\n') + '\n');
+      return true;
+    }
+
+    case '/clear':
+      rt.agent.reset();
+      rt.agent.clearSavedSession();
+      ui.success('Conversation cleared.');
+      return true;
+
+    case '/retry':
+      await rt.agent.retry();
+      return true;
+
+    case '/quit':
+    case '/exit':
+      return EXIT;
+
+    default:
+      ui.error(`Unknown command "${cmdRaw}". Type /help for commands.`);
+      return true;
+  }
+}
+
+module.exports = { handle, EXIT };
+