overlord-cli 0.2605101225.0

package/README.md

@@ -0,0 +1,128 @@
+# Overlord CLI
+
+`overlord-cli` is the packaged command-line interface for Overlord. It lets you launch agents on tickets, create new tickets, and manage the ticket lifecycle from the terminal.
+
+Website: [ovld.ai](https://ovld.ai)
+
+## Install
+
+Note: Use Node.js 20 or newer for every CLI install or update.
+
+Install it globally so the `ovld` and `overlord` commands are available on your `PATH`:
+
+```bash
+npm install -g overlord-cli
+
+#After installing, run 
+ovld setup all #to configure every supported connector (`ovld setup` alone is interactive)
+
+#for individual connectors, run `ovld setup <connector>`.
+ovld setup cursor
+ovld setup claude
+ovld setup codex
+ovld setup all
+```
+
+```bash
+# To update the CLI to the latest release, run:
+ovld update
+```
+## Usage
+
+```bash
+ovld help
+overlord help
+```
+
+### Auth
+```bash
+# Repair shared credentials first when a session already exists
+ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
+
+# Login to Overlord if repair does not restore access
+ovld auth login #opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
+ovld auth status # show current login status (use --verbose for redacted diagnostics)
+ovld auth logout # remove stored credentials
+```
+
+Desktop-installed wrappers default `OVERLORD_URL` to `https://www.ovld.ai` unless you override it explicitly.
+For local dev against the web app on port 3000, export the override before running auth or protocol commands:
+```bash
+export OVERLORD_URL=http://localhost:3000
+```
+
+Common commands:
+
+```bash
+ovld auth login
+ovld auth status
+ovld attach
+ovld create "Investigate the failing build" --agent codex
+ovld prompt "Draft a fix for the onboarding flow"
+ovld version
+ovld update
+ovld protocol discover-project
+ovld protocol attach --ticket-id <ticket_id>
+ovld protocol search-tickets --query "auth refactor" --status next-up,execute
+ovld protocol update --session-key <session-key> --ticket-id <ticket_id> --summary "Working on it" --phase execute
+ovld setup
+ovld setup codex
+ovld setup claude
+ovld setup cursor
+ovld setup gemini
+ovld setup all
+ovld doctor
+```
+
+## Requirements
+
+- Node.js 20 or newer
+- Access to an Overlord instance when using authenticated commands
+
+## Commands for Humans
+
+Find full CLI docs here: https://www.ovld.ai/docs/surfaces/cli
+
+Top-level commands (see `ovld help`):
+
+- `attach` - search tickets and launch an agent interactively (`ovld attach [ticketId] [agent]`)
+- `create` - create a ticket with numbered project selection; supports `--agent`, `--model`, `--delegate` (same delegate flags as `ovld protocol create`)
+- `prompt` - create a ticket, then launch an agent on it
+- `auth` - `login`, `status`, `repair` (shared Desktop/CLI credentials), or `logout`
+- `tickets` - `create` or `list` (optional `--status`)
+- `ticket` - `context <ticketId>` to print context for one ticket
+- `launch`, `restart` - launch or resume an agent session
+- `connect`, `run`, `resume` - legacy aliases for `launch` and `restart`
+- `setup` - install the Overlord connector for an agent; `ovld setup [agent|all]` (interactive with no args). `ovld setup claude` also performs the one-time v3.25.0 to v4 Claude plugin migration
+- `update` - install the latest CLI release from npm
+- `doctor` - validate installed connectors and check for CLI updates
+- `version` - print the installed CLI version
+
+## Commands for agents
+Agents can find docs here: https://www.ovld.ai/docs/for-agents
+
+`ovld protocol <subcommand>` is the surface agents and hooks use for ticket lifecycle work. Run `ovld protocol help` for flags, env fallbacks, and examples.
+
+- `auth-status` - return machine-readable auth status for agent runtimes
+- `discover-project` - resolve a project from the current (or given) working directory
+- `attach` - start a ticket session and return full working context
+- `connect` - start a lightweight session without full context
+- `load-context` - read ticket context without creating a session
+- `search-tickets` - find tickets by keyword, status, project, creator, or update date
+- `create` - create a draft ticket without attaching (standalone or follow-up)
+- `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
+- `update` - post progress, activity events, and optional change rationales
+- `record-change-rationales` - persist structured change rationales without a normal progress update
+- `ask` - post a blocking question and move the ticket to review
+- `permission-request` - notify Overlord that the agent is requesting tool permission
+- `read-context` - read shared persistent context for this ticket
+- `write-context` - write shared persistent context for future sessions
+- `deliver` - finish work, send artifacts, and move the ticket to review
+- `attachment-prepare-upload` - get a signed upload URL for an objective attachment
+- `attachment-finalize-upload` - finalize an uploaded objective attachment row after storage upload
+- `attachment-download-url` - get a signed download URL for an existing objective attachment
+- `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
+
+## License
+
+Permission is granted to use this software for any purpose, free of charge. You may not modify, distribute, sublicense, or sell copies of the software without explicit permission from the author.

package/bin/_cli/attach.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+
+/**
+ * `ovld attach` — interactive ticket search + agent launcher.
+ *
+ * Usage:
+ *   ovld attach                         # interactive: search tickets, pick agent
+ *   ovld attach <ticketId>              # skip ticket search, pick agent interactively
+ *   ovld attach <ticketId> <agent>      # non-interactive: launch immediately
+ */
+
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+import { runLauncherCommand } from './launcher.mjs';
+
+const AGENTS = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+const MAX_VISIBLE = 8;
+const SEARCH_DEBOUNCE_MS = 120;
+
+// ─── ANSI helpers ─────────────────────────────────────────────────────────────
+
+const hide = '\x1b[?25l';
+const show = '\x1b[?25h';
+
+const saveCursor = '\x1b7';
+const restoreCursor = '\x1b8';
+const eraseBelow = '\x1b[J';
+
+
+const dim = s => `\x1b[2m${s}\x1b[0m`;
+const bold = s => `\x1b[1m${s}\x1b[0m`;
+const cyan = s => `\x1b[36m${s}\x1b[0m`;
+const green = s => `\x1b[32m${s}\x1b[0m`;
+const gray = s => `\x1b[90m${s}\x1b[0m`;
+const yellow = s => `\x1b[33m${s}\x1b[0m`;
+const red = s => `\x1b[31m${s}\x1b[0m`;
+
+function truncate(str, max) {
+  if (!str) return '';
+  return str.length > max ? str.slice(0, max - 1) + '…' : str;
+}
+
+function statusColor(status) {
+  switch (status) {
+    case 'draft':
+      return dim(status);
+    case 'execute':
+      return cyan(status);
+    case 'review':
+      return yellow(status);
+    case 'complete':
+      return green(status);
+    case 'blocked':
+      return red(status);
+    default:
+      return gray(status ?? '?');
+  }
+}
+
+// ─── API ──────────────────────────────────────────────────────────────────────
+
+async function searchTickets(platformUrl, bearerToken, localSecret, organizationId, query) {
+  const res = await fetch(`${platformUrl}/api/protocol/search-tickets`, {
+    method: 'POST',
+    headers: {
+      ...buildAuthHeaders(bearerToken, localSecret, organizationId),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      includeCompleted: false,
+      query,
+      limit: MAX_VISIBLE
+    })
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to search tickets (${res.status}): ${await res.text()}`);
+  }
+
+  const data = await res.json();
+  return data.tickets ?? [];
+}
+
+// ─── Interactive prompt ───────────────────────────────────────────────────────
+
+/**
+ * Run an interactive list selector.
+ *
+ * In ticket mode (search callback provided), shows a search-as-you-type menu.
+ * In items mode (items array provided), shows a fixed list selector.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.label    - Label shown before the search input
+ * @param {string[]} [opts.items]  - Fixed list of choices (agent picker)
+ * @param {(query: string) => Promise<object[]>} [opts.search] - Ticket search callback
+ * @param {string}   [opts.prefix] - Text prepended to the input line (for UX context)
+ * @returns {Promise<string|object|null>} - Selected item/value, or null if cancelled
+ */
+function runInteractivePrompt({ label, items = [], search, prefix = '' }) {
+  return new Promise(resolve => {
+    const isTicketMode = typeof search === 'function';
+    let query = '';
+    let selectedIdx = 0;
+    let hasRendered = false;
+    let loading = isTicketMode;
+    let errorMessage = '';
+    let filteredItems = isTicketMode ? [] : items;
+    let activeRequestId = 0;
+    let debounceTimer = null;
+
+    function getFiltered() {
+      return filteredItems;
+    }
+
+    function renderTicketRow(t, active) {
+      const seq = String(t.ticket_sequence ?? '?').padStart(3, ' ');
+      const status = t.status ?? '?';
+      const title = truncate(t.title || t.objective || '(no title)', 55);
+      const marker = active ? cyan('▶') : ' ';
+      return `  ${marker} ${gray('#' + seq)} ${gray('[')}${statusColor(status)}${gray(']')} ${active ? bold(title) : title}`;
+    }
+
+    function renderAgentRow(agent, active) {
+      const marker = active ? cyan('▶') : ' ';
+      return `  ${marker} ${active ? bold(agent) : agent}`;
+    }
+
+    function render() {
+      const filtered = getFiltered();
+      const count = Math.min(filtered.length, MAX_VISIBLE);
+      // Clamp selected within visible range
+      if (selectedIdx >= count) selectedIdx = Math.max(0, count - 1);
+
+      const lines = [];
+
+      // Input line
+      if (prefix) {
+        lines.push(`  ${dim(prefix)}${query}${cyan('│')}`);
+      } else {
+        lines.push(`  ${gray(label + ':')} ${query}${cyan('│')}`);
+      }
+      lines.push('');
+
+      if (loading) {
+        lines.push(gray('  Searching tickets…'));
+      } else if (errorMessage) {
+        lines.push(red(`  ${errorMessage}`));
+      } else if (filtered.length === 0) {
+        lines.push(gray('  No matches'));
+      } else {
+        for (let i = 0; i < count; i++) {
+          lines.push(
+            isTicketMode
+              ? renderTicketRow(filtered[i], i === selectedIdx)
+              : renderAgentRow(filtered[i], i === selectedIdx)
+          );
+        }
+        if (filtered.length > MAX_VISIBLE) {
+          lines.push(gray(`  … ${filtered.length - MAX_VISIBLE} more — keep typing to narrow`));
+        }
+      }
+
+      lines.push('');
+      lines.push(dim('  ↑↓ navigate · type to filter · Enter select · Esc cancel'));
+
+      if (hasRendered) {
+        process.stdout.write(restoreCursor + eraseBelow);
+      }
+      process.stdout.write(saveCursor + lines.join('\n'));
+      hasRendered = true;
+    }
+
+    async function loadMatches(nextQuery) {
+      if (!isTicketMode) return;
+      const requestId = ++activeRequestId;
+      loading = true;
+      errorMessage = '';
+      render();
+
+      try {
+        const nextItems = await search(nextQuery);
+        if (requestId !== activeRequestId) return;
+        filteredItems = nextItems;
+      } catch (error) {
+        if (requestId !== activeRequestId) return;
+        filteredItems = [];
+        errorMessage = error instanceof Error ? error.message : 'Ticket search failed.';
+      } finally {
+        if (requestId !== activeRequestId) return;
+        loading = false;
+        render();
+      }
+    }
+
+    function scheduleLoad() {
+      if (!isTicketMode) return;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        void loadMatches(query);
+      }, SEARCH_DEBOUNCE_MS);
+    }
+
+    function cleanup() {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (hasRendered) {
+        process.stdout.write(restoreCursor + eraseBelow);
+      }
+      process.stdin.setRawMode(false);
+      process.stdin.removeAllListeners('data');
+      process.stdout.write(show);
+    }
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write(hide);
+    render();
+    scheduleLoad();
+
+    process.stdin.on('data', key => {
+      const filtered = getFiltered();
+      const count = Math.min(filtered.length, MAX_VISIBLE);
+
+      // Ctrl-C / Ctrl-D → exit
+      if (key === '\x03' || key === '\x04') {
+        cleanup();
+        process.exit(0);
+      }
+
+      // Escape (lone \x1b, not a sequence like \x1b[A)
+      if (key === '\x1b') {
+        cleanup();
+        resolve(null);
+        return;
+      }
+
+      // Enter → confirm selection
+      if (key === '\r' || key === '\n') {
+        if (loading || filtered.length === 0) return;
+        const item = filtered[selectedIdx] ?? filtered[0];
+        cleanup();
+        resolve(item);
+        return;
+      }
+
+      // Arrow up
+      if (key === '\x1b[A') {
+        selectedIdx = (selectedIdx - 1 + count) % Math.max(1, count);
+        render();
+        return;
+      }
+
+      // Arrow down
+      if (key === '\x1b[B') {
+        selectedIdx = (selectedIdx + 1) % Math.max(1, count);
+        render();
+        return;
+      }
+
+      // Backspace
+      if (key === '\x7f' || key === '\b') {
+        if (query.length > 0) {
+          query = query.slice(0, -1);
+          selectedIdx = 0;
+          if (isTicketMode) scheduleLoad();
+          else render();
+        }
+        return;
+      }
+
+      // Printable character → append to query
+      if (key.length === 1 && key >= ' ') {
+        query += key;
+        selectedIdx = 0;
+        if (isTicketMode) scheduleLoad();
+        else render();
+      }
+    });
+  });
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+export async function runAttachCommand(args) {
+  const [ticketIdArg, agentArg] = args;
+
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+
+  // ── Phase 1: Ticket selection ──────────────────────────────────────────────
+
+  let ticketId = ticketIdArg;
+  let ticketTitle = '';
+
+  if (!ticketId) {
+    process.stdout.write('\n');
+    process.stdout.write(bold('  ovld attach\n'));
+    process.stdout.write('\n');
+
+    const selectedTicket = await runInteractivePrompt({
+      label: 'Search tickets',
+      search: nextQuery =>
+        searchTickets(platformUrl, bearerToken, localSecret, organizationId, nextQuery)
+    });
+
+    if (!selectedTicket) {
+      process.stdout.write(dim('\n  Cancelled.\n\n'));
+      process.exit(0);
+    }
+
+    ticketId = selectedTicket.id;
+    ticketTitle = selectedTicket.title || selectedTicket.objective || '';
+  }
+
+  // ── Phase 2: Agent selection ───────────────────────────────────────────────
+
+  const shortId = ticketId.slice(-8).toUpperCase();
+
+  let agent = agentArg;
+
+  if (!agent) {
+    process.stdout.write('\n');
+    process.stdout.write(bold(`  ovld attach `) + cyan(shortId) + '\n');
+    if (ticketTitle) {
+      process.stdout.write(gray(`  ${truncate(ticketTitle, 60)}\n`));
+    }
+    process.stdout.write('\n');
+
+    agent = await runInteractivePrompt({
+      label: 'Agent',
+      items: AGENTS,
+      prefix: `ovld attach ${shortId} `
+    });
+
+    if (!agent) {
+      process.stdout.write(dim('\n  Cancelled.\n\n'));
+      process.exit(0);
+    }
+  }
+
+  if (!AGENTS.includes(agent)) {
+    console.error(`\nUnknown agent: "${agent}". Must be one of: ${AGENTS.join(', ')}`);
+    process.exit(1);
+  }
+
+  // ── Launch ─────────────────────────────────────────────────────────────────
+
+  process.stdout.write('\n');
+  process.stdout.write(
+    `  ${green('✓')} ${bold(agent)} ← ${truncate(ticketTitle || shortId, 55)}\n\n`
+  );
+
+  process.env.TICKET_ID = ticketId;
+  await runLauncherCommand('run', [agent]);
+}