@lardexx/arenacode 0.0.0-stage → 2.5.2

package/src/cli.js

@@ -0,0 +1,720 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  VERSION, CLIENT_NAME, configPath, readConfig, writeConfig, patchConfig, deviceId,
+  resolveUrl, resolveKey, openFolder,
+} = require('./config');
+const { Bridge } = require('./bridge');
+const { buildMeta, readProjectContext } = require('./meta');
+const { followTask } = require('./turn');
+const { c, write, ask, banner, truncate, indentLines } = require('./ui');
+
+const AGENT_PROMPT_FILE = path.join(__dirname, 'prompts', 'agent-prompt.md');
+
+const MODE_LINES = {
+  agent:
+    '[ArenaCode mode: agent]\n' +
+    'AGENT MODE (not plan mode). Carry the task out directly: do not make a plan, do not send ui plan, ' +
+    'do not write a plan. This line overrides any plan instruction from earlier tasks or from the chat, ' +
+    'even if you remember one. Work, verify each change, and reply.',
+  plan:
+    '[ArenaCode mode: plan]\n' +
+    'PLAN MODE. Send the plan first with `ui plan`: the steps, the files involved, the risks and what you ' +
+    'will not do. Then stop and wait for the user to approve it before acting.',
+};
+
+// --------------------------------------------------------------------------- //
+// argument parsing
+// --------------------------------------------------------------------------- //
+
+const BOOLEAN_FLAGS = new Set(['yes', 'json', 'help', 'quiet', 'version', 'confirm-writes', 'no-pc', 'piped']);
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('--')) {
+      const [rawName, inlineValue] = arg.slice(2).split('=');
+      const name = rawName.replace(/_/g, '-');
+      if (inlineValue !== undefined) {
+        flags[name] = inlineValue;
+        continue;
+      }
+      if (BOOLEAN_FLAGS.has(name)) {
+        flags[name] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[name] = next;
+        i += 1;
+      } else {
+        flags[name] = true;
+      }
+      continue;
+    }
+    if (arg.startsWith('-') && arg.length === 2) {
+      const map = { y: 'yes', h: 'help', j: 'json' };
+      flags[map[arg.slice(1)] || arg.slice(1)] = true;
+      continue;
+    }
+    positional.push(arg);
+  }
+  return { flags, positional };
+}
+
+// --------------------------------------------------------------------------- //
+// context helpers
+// --------------------------------------------------------------------------- //
+
+function context(flags) {
+  const cfg = readConfig();
+  const url = resolveUrl(cfg, flags.url);
+  const key = resolveKey(cfg, flags.key);
+  const folder = openFolder(cfg, flags.folder);
+  const device = deviceId(cfg);
+  return {
+    cfg,
+    url,
+    key,
+    folder,
+    device,
+    lang: flags.lang || cfg.lang || 'it',
+    mode: flags.mode === 'plan' ? 'plan' : flags.mode === 'agent' ? 'agent' : cfg.mode || 'agent',
+    pcAccess: flags['no-pc'] ? false : cfg.pc_access !== false,
+    yes: Boolean(flags.yes),
+    json: Boolean(flags.json),
+    confirmWrites: Boolean(flags['confirm-writes']),
+    idleTimeout: Number(flags['idle-timeout'] || cfg.idle_timeout || 180),
+    bridge: new Bridge(url, key, device),
+  };
+}
+
+function requireUrl(ctx) {
+  if (ctx.url) return true;
+  write('');
+  write(c.red('  no bridge URL configured.'));
+  write(`  ${c.gray('run:')} arenacode init        ${c.gray('or')}  arenacode config set url https://your-bridge.tunnl.gg`);
+  return false;
+}
+
+async function ensureAuth(ctx) {
+  const res = await ctx.bridge.authCheck();
+  if (res.status === 200) return true;
+  const reason = (res.json && (res.json.error || res.json.hint)) || `HTTP ${res.status}`;
+  write(c.red(`  auth failed: ${reason}`));
+  if (res.status === 403) write(c.gray('  this API key is bound to another PC: on the bridge run  keys unbind <ID>'));
+  if (res.status === 401) write(c.gray('  check the API key: arenacode config set key <API key>'));
+  return false;
+}
+
+// --------------------------------------------------------------------------- //
+// commands
+// --------------------------------------------------------------------------- //
+
+async function cmdInit(flags) {
+  banner(VERSION);
+  const cfg = readConfig();
+  write(c.gray(`  config file: ${configPath()}`));
+  write('');
+  const url = await ask(`  Bridge URL ${cfg.url ? c.gray(`[${cfg.url}]`) : ''}: `, { default: cfg.url });
+  const key = await ask(`  API key ${cfg.key ? c.gray('[configured]') : ''}: `, { default: cfg.key });
+  const folder = await ask(`  Open folder ${c.gray(`[${cfg.folder || process.cwd()}]`)}: `, { default: cfg.folder || process.cwd() });
+
+  const next = { ...cfg, url: String(url).replace(/\/+$/, ''), key: String(key), folder: path.resolve(String(folder) || process.cwd()) };
+  const file = writeConfig(next);
+  write(`  ${c.green('✓')} saved ${c.gray(file)}`);
+
+  const bridge = new Bridge(next.url, next.key, deviceId(next));
+  const health = await bridge.health();
+  if (health.status !== 200) {
+    write(c.red(`  ✗ bridge unreachable: ${(health.json && health.json.error) || health.status}`));
+    return 1;
+  }
+  write(`  ${c.green('✓')} bridge ${c.bold('v' + (health.json.version || '?'))} ${c.gray(health.json.public_url || '')}`);
+  const auth = await bridge.authCheck();
+  if (auth.status === 200) write(`  ${c.green('✓')} API key accepted`);
+  else write(c.red(`  ✗ API key rejected: ${(auth.json && auth.json.error) || auth.status}`));
+  write('');
+  write(`  ${c.gray('try:')} arenacode ask "list the files in my folder"`);
+  return 0;
+}
+
+function cmdConfig(positional, flags) {
+  const [action = 'show', key, ...rest] = positional;
+  const cfg = readConfig();
+  if (action === 'path') {
+    write(configPath());
+    return 0;
+  }
+  if (action === 'show') {
+    const shown = { ...cfg, key: cfg.key ? `${cfg.key.slice(0, 8)}…` : '' };
+    write(JSON.stringify(shown, null, 2));
+    write(c.gray(`# ${configPath()}`));
+    return 0;
+  }
+  if (action === 'set') {
+    const name = key;
+    const val = rest.join(' ');
+    if (!name || val === '') {
+      write('usage: arenacode config set <url|key|folder|lang|mode|pc_access> <value>');
+      return 2;
+    }
+    const patch = {};
+    if (name === 'pc_access') patch.pc_access = !['false', '0', 'no', 'off'].includes(String(val).toLowerCase());
+    else if (name === 'url') patch.url = String(val).replace(/\/+$/, '');
+    else patch[name] = val;
+    const file = patchConfig(patch);
+    write(`  ${c.green('✓')} ${name} saved ${c.gray(file)}`);
+    return 0;
+  }
+  if (action === 'clear') {
+    try {
+      fs.rmSync(configPath());
+    } catch {
+      /* ignore */
+    }
+    write(`  ${c.green('✓')} config removed`);
+    return 0;
+  }
+  write('usage: arenacode config [show|path|set <key> <value>|clear]');
+  return 2;
+}
+
+async function cmdPing(flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const health = await ctx.bridge.health();
+  if (health.status !== 200) {
+    write(c.red(`  ✗ bridge unreachable: ${(health.json && health.json.error) || health.status}`));
+    return 1;
+  }
+  const h = health.json;
+  if (ctx.json) {
+    write(JSON.stringify(h, null, 2));
+    return 0;
+  }
+  write('');
+  write(`  ${c.green('●')} bridge ${c.bold('v' + h.version)} ${c.gray(`· executor=${h.executor_mode} · terminal=${h.terminal ? 'on' : 'off'}`)}`);
+  write(`  ${c.gray('url')}      ${h.public_url || c.gray('(no tunnel)')}`);
+  write(`  ${c.gray('tasks')}    ${h.tasks.claimable} claimable · ${h.tasks.pending} pending · ${h.tasks.done} done`);
+  const auth = await ctx.bridge.authCheck();
+  write(`  ${auth.status === 200 ? c.green('✓') : c.red('✗')} auth ${auth.status === 200 ? 'ok' : (auth.json && auth.json.error) || auth.status}`);
+  return auth.status === 200 ? 0 : 1;
+}
+
+async function cmdDoctor(flags) {
+  const ctx = context(flags);
+  write('');
+  write(`  ${c.bold('arenacode doctor')}`);
+  const line = (ok, label, detail = '') => write(`  ${ok ? c.green('✓') : c.red('✗')} ${label.padEnd(18)} ${c.gray(detail)}`);
+  line(Number(process.versions.node.split('.')[0]) >= 18, 'node', process.version);
+  line(true, 'platform', `${process.platform} ${os.release()} ${os.arch()}`);
+  line(Boolean(ctx.url), 'bridge url', ctx.url || 'not configured');
+  line(true, 'config', configPath());
+  line(/^[A-Za-z0-9-]{8,128}$/.test(deviceId()), 'device id', deviceId().slice(0, 12) + '…');
+  line(fs.existsSync(ctx.folder), 'open folder', ctx.folder);
+  line(Boolean(require('./meta').which('git')), 'git', require('./meta').which('git') ? 'available' : 'missing');
+  if (ctx.url) {
+    const health = await ctx.bridge.health();
+    line(health.status === 200, 'bridge', health.status === 200 ? `v${health.json.version} ${health.json.public_url || ''}` : (health.json && health.json.error) || 'unreachable');
+    if (health.status === 200) {
+      const auth = await ctx.bridge.authCheck();
+      line(auth.status === 200, 'api key', auth.status === 200 ? 'accepted' : (auth.json && auth.json.error) || String(auth.status));
+    }
+  }
+  write('');
+  return 0;
+}
+
+function agentPrompt() {
+  try {
+    return fs.readFileSync(AGENT_PROMPT_FILE, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** POST /task exactly like the desktop client does. */
+async function createTask(ctx, instruction, { extraInstructions = '' } = {}) {
+  const meta = buildMeta(ctx.folder, { lang: ctx.lang, pcAccess: ctx.pcAccess, activeFile: '' });
+  const projectContext = readProjectContext(ctx.folder);
+  const body = {
+    instruction,
+    wait: 0,
+    meta,
+    agent_prompt: agentPrompt(),
+  };
+  if (projectContext) body.project_context = projectContext;
+  if (extraInstructions) body.instruction = `${instruction}\n\n${extraInstructions}`;
+
+  const res = await ctx.bridge.createTask(body);
+  if (res.status !== 202 && res.status !== 200) {
+    const reason = (res.json && (res.json.error || res.json.hint)) || `HTTP ${res.status}`;
+    throw new Error(reason);
+  }
+  return res.json.task_id;
+}
+
+async function runInstruction(ctx, text, { attachments = [] } = {}) {
+  let instruction = `${MODE_LINES[ctx.mode] || MODE_LINES.agent}\n${text}`;
+
+  if (attachments.length) {
+    const uploaded = [];
+    for (const file of attachments) {
+      const abs = path.resolve(file);
+      if (!fs.existsSync(abs)) {
+        write(c.yellow(`  ! missing attachment: ${file}`));
+        continue;
+      }
+      const name = `attachments/${Date.now()}-${path.basename(abs)}`;
+      const res = await ctx.bridge.upload(name, fs.readFileSync(abs));
+      if (res.status !== 200) {
+        write(c.yellow(`  ! upload failed: ${file}`));
+        continue;
+      }
+      uploaded.push(res.json.path);
+      write(`  ${c.green('↑')} ${c.gray(`${path.basename(abs)} → ${res.json.path} (${res.json.size} B)`)}`);
+    }
+    if (uploaded.length) instruction += `\n\n[attachments in the workspace: ${uploaded.join(', ')}]`;
+  }
+
+  let taskId = null;
+  const onSigint = async () => {
+    if (!taskId) process.exit(130);
+    write('');
+    write(c.yellow('  ■ stop requested…'));
+    await ctx.bridge.cancel(taskId);
+    process.exit(130);
+  };
+  process.once('SIGINT', onSigint);
+
+  try {
+    taskId = await createTask(ctx, instruction);
+    write(c.gray(`  task ${taskId}`));
+    const result = await followTask(ctx.bridge, taskId, {
+      folder: ctx.folder,
+      lang: ctx.lang,
+      yes: ctx.yes,
+      confirmWrites: ctx.confirmWrites,
+      idleTimeout: ctx.idleTimeout,
+    });
+
+    if (!result.streamed && result.output) {
+      write('');
+      write(indentLines(c.white(result.output.trim()), '  │ '));
+    }
+    if (result.error) write(`  ${c.red('✗')} ${c.red(result.error)}`);
+    return result.state === 'error' ? 1 : 0;
+  } finally {
+    process.removeListener('SIGINT', onSigint);
+  }
+}
+
+async function cmdAsk(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const text = positional.join(' ').trim();
+  if (!text) {
+    write('usage: arenacode ask "your instruction"');
+    return 2;
+  }
+  if (!(await ensureAuth(ctx))) return 1;
+  const attachments = flags.attach ? String(flags.attach).split(',').map((s) => s.trim()).filter(Boolean) : [];
+  write('');
+  write(`  ${c.bold('›')} ${c.white(truncate(text, 100))} ${c.gray(`· ${ctx.mode} · ${ctx.folder}`)}`);
+  return runInstruction(ctx, text, { attachments });
+}
+
+/** Full-screen TUI (opencode-style): timeline, input box, dialogs, local cards. */
+async function cmdUi(flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    write(c.red('  the TUI needs an interactive terminal.'));
+    write(c.gray('  inside a script or a pipe use: arenacode ask "…" or arenacode chat'));
+    return 1;
+  }
+  const { App } = require('./tui/app');
+  const app = new App({
+    url: ctx.url,
+    key: ctx.key,
+    folder: ctx.folder,
+    lang: ctx.lang,
+    mode: ctx.mode,
+    yes: ctx.yes,
+    confirmWrites: ctx.confirmWrites,
+  });
+  await app.start();
+  return 0;
+}
+
+async function cmdChat(flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  if (!(await ensureAuth(ctx))) return 1;
+  banner(VERSION);
+  write(`  ${c.gray('bridge')} ${ctx.url}   ${c.gray('folder')} ${ctx.folder}`);
+  write(`  ${c.gray('type a request · /help for commands · Ctrl+D to quit')}`);
+  write('');
+
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: process.stdin.isTTY });
+  const prompt = () => {
+    rl.setPrompt(c.cyan('  › '));
+    rl.prompt();
+  };
+
+  return new Promise((resolve) => {
+    prompt();
+    rl.on('line', async (line) => {
+      const input = line.trim();
+      if (!input) {
+        prompt();
+        return;
+      }
+      rl.pause();
+      try {
+        if (input === '/quit' || input === '/exit') {
+          rl.close();
+          return;
+        }
+        if (input === '/help') {
+          write(`  ${c.gray('/files [path]')}  list the bridge workspace     ${c.gray('/cat <path>')}  preview a file`);
+          write(`  ${c.gray('/mode agent|plan')}  switch mode          ${c.gray('/lang it|en|es')}  interface language`);
+          write(`  ${c.gray('/folder <dir>')}   change the open folder      ${c.gray('/ping')}  bridge status`);
+          write(`  ${c.gray('/tasks')}  queue           ${c.gray('/stop <id>')}  cancel a turn   ${c.gray('/quit')}`);
+          write('');
+        } else if (input === '/ping') {
+          await cmdPing({ ...flags });
+        } else if (input === '/tasks') {
+          await cmdTasks([], flags);
+        } else if (input.startsWith('/files')) {
+          await cmdFiles(input.split(/\s+/).slice(1), flags);
+        } else if (input.startsWith('/cat ')) {
+          await cmdCat([input.slice(5).trim()], flags);
+        } else if (input.startsWith('/mode ')) {
+          const mode = input.slice(6).trim() === 'plan' ? 'plan' : 'agent';
+          patchConfig({ mode });
+          ctx.mode = mode;
+          write(`  ${c.green('✓')} mode ${mode}`);
+        } else if (input.startsWith('/lang ')) {
+          const lang = input.slice(6).trim().slice(0, 2);
+          patchConfig({ lang });
+          ctx.lang = lang;
+          write(`  ${c.green('✓')} lang ${lang}`);
+        } else if (input.startsWith('/folder ')) {
+          const folder = path.resolve(input.slice(8).trim().replace(/^"|"$/g, ''));
+          patchConfig({ folder });
+          ctx.folder = folder;
+          write(`  ${c.green('✓')} folder ${folder}`);
+        } else if (input.startsWith('/stop')) {
+          const id = input.split(/\s+/)[1];
+          if (id) await cmdStop([id], flags);
+          else write(c.gray('  usage: /stop <task-id>'));
+        } else {
+          await runInstruction(ctx, input);
+        }
+      } catch (e) {
+        write(c.red(`  ✗ ${e.message}`));
+      }
+      write('');
+      rl.resume();
+      prompt();
+    });
+    rl.on('close', () => {
+      write('');
+      resolve(0);
+    });
+  });
+}
+
+async function cmdTasks(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const state = positional[0] || flags.state || 'all';
+  const res = await ctx.bridge.listTasks(state);
+  if (res.status !== 200) {
+    write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+    return 1;
+  }
+  if (ctx.json) {
+    write(JSON.stringify(res.json, null, 2));
+    return 0;
+  }
+  const tasks = res.json.tasks || [];
+  if (!tasks.length) {
+    write(c.gray('  (no tasks)'));
+    return 0;
+  }
+  for (const task of tasks) {
+    const when = new Date(task.created_at * 1000).toLocaleString();
+    const stateTone = task.state === 'done' ? 'green' : task.state === 'error' ? 'red' : task.state === 'cancelled' ? 'yellow' : 'cyan';
+    write(`  ${c[stateTone](task.state.padEnd(9))} ${c.gray(when)}  ${c.bold(task.id)}  ${c.gray(truncate(String(task.instruction).split('\n').slice(-1)[0], 60))}`);
+  }
+  return 0;
+}
+
+async function cmdStatus(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const id = positional[0];
+  if (!id) {
+    write('usage: arenacode status <task-id>');
+    return 2;
+  }
+  const res = await ctx.bridge.getTask(id);
+  if (res.status !== 200) {
+    write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+    return 1;
+  }
+  if (ctx.json) {
+    write(JSON.stringify(res.json, null, 2));
+    return 0;
+  }
+  const t = res.json;
+  write('');
+  write(`  ${c.bold(t.id)}  ${c.cyan(t.state)}  ${c.gray(new Date(t.created_at * 1000).toLocaleString())}`);
+  if (t.claimant) write(`  ${c.gray('claimant')} ${t.claimant}`);
+  if (t.error) write(`  ${c.red('error')}    ${t.error}`);
+  if (t.output) {
+    write('');
+    write(indentLines(String(t.output).trim(), '  │ '));
+  }
+  return 0;
+}
+
+async function cmdEvents(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const id = positional[0];
+  if (!id) {
+    write('usage: arenacode events <task-id>');
+    return 2;
+  }
+  const res = await ctx.bridge.getTask(id);
+  if (res.status !== 200) {
+    write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+    return 1;
+  }
+  const { Timeline } = require('./turn');
+  const timeline = new Timeline({ folder: ctx.folder, lang: ctx.lang });
+  for (const ev of res.json.events || []) timeline.render(ev);
+  timeline.newlineIfText();
+  write(c.gray(`  state: ${res.json.state}`));
+  return 0;
+}
+
+async function cmdStop(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  let id = positional[0];
+  if (!id) {
+    const res = await ctx.bridge.listTasks('all');
+    const live = (res.json.tasks || []).filter((t) => !['done', 'error', 'cancelled'].includes(t.state)).pop();
+    id = live && live.id;
+  }
+  if (!id) {
+    write(c.gray('  nothing to stop'));
+    return 0;
+  }
+  const res = await ctx.bridge.cancel(id);
+  if (res.status !== 200) {
+    write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+    return 1;
+  }
+  write(`  ${c.yellow('■')} stopped ${id}`);
+  return 0;
+}
+
+async function cmdFiles(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const rel = positional[0] || '';
+  const res = await ctx.bridge.fs(rel);
+  if (res.status !== 200) {
+    write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+    return 1;
+  }
+  if (ctx.json) {
+    write(JSON.stringify(res.json, null, 2));
+    return 0;
+  }
+  write(c.gray(`  ${res.json.root}/${res.json.path}`));
+  for (const entry of res.json.entries) {
+    const size = entry.type === 'dir' ? '<DIR>' : String(entry.size);
+    write(`  ${c.gray(size.padStart(9))}  ${entry.type === 'dir' ? c.cyan(entry.name + '/') : entry.name}`);
+  }
+  return 0;
+}
+
+async function cmdCat(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  const rel = positional[0];
+  if (!rel) {
+    write('usage: arenacode cat <path>');
+    return 2;
+  }
+  const res = await ctx.bridge.file(rel);
+  if (res.status !== 200) {
+    write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+    return 1;
+  }
+  if (res.json.binary) {
+    write(c.gray(`  binary file (${res.json.size} B)`));
+    return 0;
+  }
+  write(res.json.text);
+  return 0;
+}
+
+async function cmdAttach(positional, flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  if (!positional.length) {
+    write('usage: arenacode attach <file> [more files]');
+    return 2;
+  }
+  for (const file of positional) {
+    const abs = path.resolve(file);
+    if (!fs.existsSync(abs)) {
+      write(c.yellow(`  ! missing: ${file}`));
+      continue;
+    }
+    const name = `attachments/${Date.now()}-${path.basename(abs)}`;
+    const res = await ctx.bridge.upload(name, fs.readFileSync(abs));
+    if (res.status !== 200) {
+      write(c.red(`  ✗ ${(res.json && res.json.error) || res.status}`));
+      return 1;
+    }
+    write(`  ${c.green('↑')} ${res.json.path} ${c.gray(`(${res.json.size} B)`)}`);
+  }
+  return 0;
+}
+
+/** Handshake task the desktop client sends to check the bridge and vision. */
+async function cmdHandshake(flags) {
+  const ctx = context(flags);
+  if (!requireUrl(ctx)) return 1;
+  if (!(await ensureAuth(ctx))) return 1;
+  const instruction =
+    '[ArenaCode handshake] Vision check. The bridge creates the image, not you: do not write, copy or edit any PNG ' +
+    'or other image. Run `python3 agentctl.py vision-png <task id>`, open the PNG it prints and look at it, then run ' +
+    '`python3 agentctl.py --has-vision-enabled:true <task id>` if you can see and describe it, or ' +
+    '`--has-vision-enabled:false` if you cannot. Reply with one short sentence describing what you see, then go back ' +
+    'to listening.';
+  write('');
+  write(`  ${c.bold('handshake')} ${c.gray('· vision check')}`);
+  return runInstruction(ctx, instruction);
+}
+
+function help() {
+  banner(VERSION);
+  write(`  ${c.bold('usage')}  arenacode <command> [options]`);
+  write('');
+  write(`  ${c.cyan('setup')}`);
+  write(`    init                       configure URL + API key, test the connection`);
+  write(`    config [show|set|path]     read or change the saved configuration`);
+  write(`    ping                       bridge status and API key check`);
+  write(`    doctor                     local checks (node, git, folder, bridge)`);
+  write('');
+  write(`  ${c.cyan('chat')}`);
+  write(`    ask "instruction"          run one task and stream the timeline`);
+  write(`    ui                         full-screen TUI (default on a terminal)`);
+  write(`    chat                       plain line-by-line session`);
+  write(`    stop [task-id]             cancel the running turn (Stop)`);
+  write(`    handshake                  vision/handshake check task`);
+  write('');
+  write(`  ${c.cyan('inspect')}`);
+  write(`    tasks [state]              task queue on the bridge`);
+  write(`    status <task-id>           state and result of a task`);
+  write(`    events <task-id>           timeline of a task`);
+  write(`    files [path]               bridge workspace listing`);
+  write(`    cat <path>                 preview a file in the bridge workspace`);
+  write(`    attach <file…>             upload files to the bridge workspace`);
+  write('');
+  write(`  ${c.cyan('options')}`);
+  write(`    --folder <dir>             open folder (the project the agent works on)`);
+  write(`    --url <url> --key <key>    override the saved bridge settings`);
+  write(`    --mode agent|plan          task mode (default: ${c.gray('agent')})`);
+  write(`    --lang it|en|es            language for instructions and cards`);
+  write(`    --no-pc                    tell the agent the PC terminal is off`);
+  write(`    --yes                      run local commands without asking`);
+  write(`    --confirm-writes           ask before write/replace/rm/mv on your folder`);
+  write(`    --attach a,b               upload files with the task`);
+  write(`    --json                     raw JSON output where available`);
+  write('');
+  write(c.gray('  docs: https://github.com/  ·  bridge: arena-bridge 2.5.2'));
+  write('');
+  return 0;
+}
+
+// --------------------------------------------------------------------------- //
+
+async function main(argv) {
+  const { flags, positional } = parseArgs(argv);
+  const [command = 'chat', ...rest] = positional;
+
+  if (flags.version || command === 'version') {
+    write(VERSION);
+    return 0;
+  }
+  if (flags.help || command === 'help') return help();
+
+  switch (command) {
+    case 'init':
+      return cmdInit(flags);
+    case 'config':
+      return cmdConfig(rest, flags);
+    case 'ping':
+      return cmdPing(flags);
+    case 'doctor':
+      return cmdDoctor(flags);
+    case 'ask':
+      return cmdAsk(rest, flags);
+    case 'ui':
+    case 'tui':
+      return cmdUi(flags);
+    case 'chat':
+      return cmdChat(flags);
+    case 'tasks':
+      return cmdTasks(rest, flags);
+    case 'status':
+      return cmdStatus(rest, flags);
+    case 'events':
+      return cmdEvents(rest, flags);
+    case 'stop':
+      return cmdStop(rest, flags);
+    case 'files':
+      return cmdFiles(rest, flags);
+    case 'cat':
+      return cmdCat(rest, flags);
+    case 'attach':
+      return cmdAttach(rest, flags);
+    case 'handshake':
+      return cmdHandshake(flags);
+    default:
+      if (command.startsWith('-')) {
+        // `arenacode "instruction"` convenience form
+        return cmdAsk(positional, flags);
+      }
+      if ((command === 'chat' || command === undefined) && process.stdout.isTTY && process.stdin.isTTY) {
+        return cmdUi(flags);
+      }
+      write(c.red(`  unknown command: ${command}`));
+      help();
+      return 2;
+  }
+}
+
+module.exports = { main, parseArgs, MODE_LINES, createTask };