overlord-cli 3.5.0

package/bin/_cli/index.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import { runAttachCommand } from './attach.mjs';
+import { runAuthCommand } from './auth.mjs';
+import { runLauncherCommand } from './launcher.mjs';
+import { runCreateCommand, runPromptCommand } from './new-ticket.mjs';
+import { runProtocolCommand } from './protocol.mjs';
+import { runDoctorCommand, runSetupCommand } from './setup.mjs';
+import { runTicketCommand } from './ticket.mjs';
+import { runTicketsCommand } from './tickets.mjs';
+
+function printHelp(primaryCommand) {
+  console.log(`Overlord CLI
+
+Primary command: ${primaryCommand}
+
+Usage:
+  ${primaryCommand} attach [ticketId] [agent]  Search tickets and launch an agent (interactive)
+  ${primaryCommand} create "<objective>"       Create a ticket with numbered project selection
+  ${primaryCommand} prompt "<objective>"       Create a ticket, then launch an agent on it
+  ${primaryCommand} auth <subcommand>          Login, logout, or check auth status
+  ${primaryCommand} tickets <subcommand>       Create or list tickets
+  ${primaryCommand} ticket <subcommand>        Work with a single ticket
+  ${primaryCommand} protocol <subcommand>      Agent workflow commands
+  ${primaryCommand} connect <agent>            Launch an agent on a ticket
+  ${primaryCommand} restart <agent>            Resume an agent session
+  ${primaryCommand} context                    Print ticket context (requires TICKET_ID)
+  ${primaryCommand} setup <agent|all>          Install Overlord agent connector
+  ${primaryCommand} doctor                     Validate installed agent connectors
+  ${primaryCommand} help                       Show this help message
+
+Agents:
+  Use ${primaryCommand} protocol help for ticket lifecycle commands.
+
+Auth:
+  ${primaryCommand} auth login               Authorize CLI via browser
+  ${primaryCommand} auth status              Show login status
+  ${primaryCommand} auth logout              Remove stored credentials
+
+Tickets:
+  ${primaryCommand} create "..." [options]
+  ${primaryCommand} prompt "..." [options]
+  ${primaryCommand} tickets create "..." [options]
+  ${primaryCommand} tickets list [--status <status>]
+
+Ticket:
+  ${primaryCommand} ticket context <ticketId>
+
+Run a subcommand with --help for more detail.
+`);
+}
+
+export async function runCli({ primaryCommand }) {
+  const [command, ...rest] = process.argv.slice(2);
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printHelp(primaryCommand);
+    return;
+  }
+
+  // Attach command (interactive ticket search + agent launcher)
+  if (command === 'attach') {
+    await runAttachCommand(rest);
+    return;
+  }
+
+  if (command === 'create') {
+    await runCreateCommand(rest);
+    return;
+  }
+
+  if (command === 'prompt') {
+    await runPromptCommand(rest);
+    return;
+  }
+
+  // Auth group
+  if (command === 'auth') {
+    await runAuthCommand(rest[0], rest.slice(1));
+    return;
+  }
+
+  // Tickets (plural) group
+  if (command === 'tickets') {
+    await runTicketsCommand(rest[0], rest.slice(1));
+    return;
+  }
+
+  // Ticket (singular) group
+  if (command === 'ticket') {
+    await runTicketCommand(rest[0], rest.slice(1));
+    return;
+  }
+
+  // Protocol group
+  if (command === 'protocol') {
+    await runProtocolCommand(rest[0], rest.slice(1));
+    return;
+  }
+
+  if (command === 'setup') {
+    await runSetupCommand(rest);
+    return;
+  }
+
+  if (command === 'doctor') {
+    await runDoctorCommand();
+    return;
+  }
+
+  // Launcher commands (`run` / `resume` kept as legacy aliases)
+  if (
+    command === 'connect' ||
+    command === 'restart' ||
+    command === 'run' ||
+    command === 'resume' ||
+    command === 'context'
+  ) {
+    await runLauncherCommand(command, rest);
+    return;
+  }
+
+  console.error(`Unknown command: ${command}\n`);
+  printHelp(primaryCommand);
+  process.exit(1);
+}

package/bin/_cli/launcher.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+/**
+ * Agent launcher commands (run / resume / context).
+ * Extracted from the original _agent-launcher-cli.mjs.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+import { runAttachCommand } from './attach.mjs';
+
+async function fetchContext(platformUrl, agentToken, localSecret, ticketId) {
+  const url = `${platformUrl}/api/protocol/context/${ticketId}?context=cli`;
+  const response = await fetch(url, {
+    headers: buildAuthHeaders(agentToken, localSecret)
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch ticket context (${response.status}): ${await response.text()}`
+    );
+  }
+
+  return response.text();
+}
+
+const agentIdentifierMap = {
+  claude: 'claude-code',
+  codex: 'codex',
+  cursor: 'cursor',
+  gemini: 'gemini',
+  opencode: 'opencode'
+};
+
+const supportedAgents = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+
+function parseLauncherArgs(args) {
+  const positionals = [];
+  const flags = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx !== -1) {
+      flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      flags[key] = args[i + 1];
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+
+  return { positionals, flags };
+}
+
+async function runAgent(agent, mode = 'run') {
+  if (!agent || !supportedAgents.includes(agent)) {
+    console.error(
+      `Usage: ovld connect <agent> [--ticket-id <id>] | ovld restart <agent> [--ticket-id <id>]  (agent must be one of: ${supportedAgents.join(', ')})`
+    );
+    process.exit(1);
+  }
+
+  const ticketId = process.env.TICKET_ID;
+  if (!ticketId) {
+    console.error('Missing required environment variable: TICKET_ID');
+    process.exit(1);
+  }
+
+  const { platformUrl, agentToken, localSecret } = resolveAuth();
+  const context = await fetchContext(platformUrl, agentToken, localSecret, ticketId);
+
+  const childEnv = { ...process.env, AGENT_IDENTIFIER: agentIdentifierMap[agent] };
+
+  try {
+    if (agent === 'claude') {
+      if (mode === 'resume') {
+        const claudeSessionId = process.env.CLAUDE_SESSION_ID?.trim();
+        const args = claudeSessionId
+          ? ['--resume', claudeSessionId, context]
+          : ['--continue', context];
+        execFileSync('claude', args, { stdio: 'inherit', env: childEnv });
+      } else {
+        execFileSync(
+          'claude',
+          [
+            '--append-system-prompt',
+            context,
+            'Begin working on this ticket. Start by calling the attach endpoint, then proceed with the objective described in your system prompt.'
+          ],
+          { stdio: 'inherit', env: childEnv }
+        );
+      }
+    } else if (agent === 'codex') {
+      if (mode === 'resume') {
+        const codexSessionId = process.env.CODEX_SESSION_ID?.trim();
+        const args = codexSessionId
+          ? ['resume', codexSessionId, context]
+          : ['resume', '--last', context];
+        execFileSync('codex', args, { stdio: 'inherit', env: childEnv });
+      } else {
+        execFileSync('codex', [context], { stdio: 'inherit', env: childEnv });
+      }
+    } else if (agent === 'cursor') {
+      execFileSync('agent', [context], { stdio: 'inherit', env: childEnv });
+    } else if (agent === 'opencode') {
+      if (mode === 'resume') {
+        const openCodeSessionId = process.env.OPENCODE_SESSION_ID?.trim();
+        const args = openCodeSessionId
+          ? ['--continue', '--session', openCodeSessionId, '--prompt', context]
+          : ['--continue', '--prompt', context];
+        execFileSync('opencode', args, { stdio: 'inherit', env: childEnv });
+      } else {
+        execFileSync('opencode', ['--prompt', context], { stdio: 'inherit', env: childEnv });
+      }
+    } else {
+      execFileSync('gemini', [context], { stdio: 'inherit', env: childEnv });
+    }
+  } catch (error) {
+    const isResume = mode === 'resume';
+    const noSessionHint =
+      agent === 'claude'
+        ? `No prior Claude session was found. Start one with \`ovld connect claude --ticket-id <ticket-id>\` first.`
+        : agent === 'codex'
+          ? `No prior Codex session was found. Start one with \`ovld connect codex --ticket-id <ticket-id>\` first.`
+          : agent === 'opencode'
+            ? `No prior OpenCode session was found. Start one with \`ovld connect opencode --ticket-id <ticket-id>\` first.`
+          : '';
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (isResume && noSessionHint) {
+      console.error(`${message}\n${noSessionHint}`);
+    } else {
+      console.error(message);
+    }
+    process.exit(1);
+  }
+}
+
+async function printContext() {
+  const ticketId = process.env.TICKET_ID;
+  if (!ticketId) {
+    console.error('Missing required environment variable: TICKET_ID\n');
+    console.error('Usage: TICKET_ID=<id> ovld context');
+    console.error('       ovld ticket context <id>  (recommended)');
+    process.exit(1);
+  }
+
+  const { platformUrl, agentToken, localSecret } = resolveAuth();
+  const context = await fetchContext(platformUrl, agentToken, localSecret, ticketId);
+  process.stdout.write(context);
+}
+
+export async function runLauncherCommand(command, args) {
+  const normalizedCommand = command === 'connect' ? 'run' : command === 'restart' ? 'resume' : command;
+  const { positionals, flags } = parseLauncherArgs(args);
+  const ticketId = typeof flags['ticket-id'] === 'string' ? flags['ticket-id'].trim() : '';
+
+  if (ticketId) {
+    process.env.TICKET_ID = ticketId;
+  }
+
+  if (normalizedCommand === 'run') {
+    // If no ticket-id flag and no TICKET_ID env var, present interactive ticket search
+    if (!ticketId && !process.env.TICKET_ID) {
+      await runAttachCommand([undefined, positionals[0]]);
+      return;
+    }
+    await runAgent(positionals[0]);
+    return;
+  }
+
+  if (normalizedCommand === 'resume') {
+    await runAgent(positionals[0], 'resume');
+    return;
+  }
+
+  if (normalizedCommand === 'context') {
+    await printContext();
+    return;
+  }
+
+  // Should not happen if called correctly
+  console.error(`Unknown launcher command: ${command}`);
+  process.exit(1);
+}

package/bin/_cli/new-ticket.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+import { runLauncherCommand } from './launcher.mjs';
+
+const PROMPT_AGENTS = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+
+function parseFlags(args) {
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx !== -1) {
+      flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      flags[key] = args[i + 1];
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+
+  return { flags, positionals };
+}
+
+function buildUsage(commandName) {
+  if (commandName === 'prompt') {
+    return 'Usage: ovld prompt "<objective>" [--title "..."] [--acceptance-criteria "..."] [--available-tools "..."] [--execution-target agent|human] [--priority low|medium|high|urgent] [--project-id <id>] [--agent <agent>]';
+  }
+
+  return 'Usage: ovld create "<objective>" [--title "..."] [--acceptance-criteria "..."] [--available-tools "..."] [--execution-target agent|human] [--priority low|medium|high|urgent] [--project-id <id>]';
+}
+
+function ensureObjective(commandName, objective) {
+  if (objective) return;
+
+  console.error(`Error: objective is required.\n`);
+  console.error(buildUsage(commandName));
+  process.exit(1);
+}
+
+export function parseNumberedSelection(rawValue, count) {
+  const trimmed = rawValue.trim();
+  if (!trimmed) return null;
+  if (!/^\d+$/.test(trimmed)) return null;
+
+  const selected = Number.parseInt(trimmed, 10);
+  if (selected < 1 || selected > count) return null;
+
+  return selected - 1;
+}
+
+export function sortProjects(projects) {
+  return [...projects].sort((left, right) => {
+    const byOrganization = String(left.organizationName ?? '').localeCompare(
+      String(right.organizationName ?? '')
+    );
+    if (byOrganization !== 0) return byOrganization;
+
+    const byName = String(left.name ?? '').localeCompare(String(right.name ?? ''));
+    if (byName !== 0) return byName;
+
+    return String(left.id ?? '').localeCompare(String(right.id ?? ''));
+  });
+}
+
+function projectLabel(project) {
+  const organizationName = String(project.organizationName ?? '').trim();
+  return organizationName ? `${project.name} - ${organizationName}` : project.name;
+}
+
+async function promptForSelection({ items, label, prompt, renderItem }) {
+  if (!items.length) {
+    throw new Error(`No ${label.toLowerCase()} available.`);
+  }
+
+  const rl = readline.createInterface({ input, output });
+
+  try {
+    while (true) {
+      output.write(`\n${label}\n`);
+      items.forEach((item, index) => {
+        output.write(`  ${index + 1}. ${renderItem(item, index)}\n`);
+      });
+
+      const answer = await rl.question(`\n${prompt} `);
+      const selectedIndex = parseNumberedSelection(answer, items.length);
+      if (selectedIndex !== null) {
+        return items[selectedIndex];
+      }
+
+      output.write(`Enter a number between 1 and ${items.length}.\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function fetchProjects(platformUrl, agentToken, localSecret) {
+  const res = await fetch(`${platformUrl}/api/protocol/projects`, {
+    headers: buildAuthHeaders(agentToken, localSecret)
+  });
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(
+      `Failed to list projects (${res.status}): ${data.error ?? JSON.stringify(data)}`
+    );
+  }
+
+  return Array.isArray(data.projects) ? sortProjects(data.projects) : [];
+}
+
+async function createTicket(platformUrl, agentToken, localSecret, body) {
+  const res = await fetch(`${platformUrl}/api/protocol/tickets`, {
+    method: 'POST',
+    headers: {
+      ...buildAuthHeaders(agentToken, localSecret),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`Failed to create ticket (${res.status}): ${data.error ?? JSON.stringify(data)}`);
+  }
+
+  return data.ticket;
+}
+
+function resolveProject(projects, projectId) {
+  if (!projectId) return null;
+
+  const project = projects.find(candidate => candidate.id === projectId);
+  if (!project) {
+    throw new Error(`Unknown project ID: ${projectId}`);
+  }
+
+  return project;
+}
+
+function resolveAgent(agent) {
+  if (!agent) return null;
+
+  const normalizedAgent = agent.trim().toLowerCase();
+  if (!PROMPT_AGENTS.includes(normalizedAgent)) {
+    throw new Error(`Unknown agent: "${agent}". Must be one of: ${PROMPT_AGENTS.join(', ')}`);
+  }
+
+  return normalizedAgent;
+}
+
+async function runTicketCreationFlow(args, { commandName, launchAgent }) {
+  const { flags, positionals } = parseFlags(args);
+  const objective = String(flags.objective ?? positionals.join(' ')).trim();
+  ensureObjective(commandName, objective);
+
+  const { platformUrl, agentToken, localSecret } = resolveAuth();
+  const projects = await fetchProjects(platformUrl, agentToken, localSecret);
+
+  if (!projects.length) {
+    throw new Error('No projects available. Create a project first.');
+  }
+
+  const selectedProject =
+    resolveProject(projects, typeof flags['project-id'] === 'string' ? flags['project-id'] : '') ??
+    (await promptForSelection({
+      items: projects,
+      label: 'Projects',
+      prompt: 'Select a project by number:',
+      renderItem: project => projectLabel(project)
+    }));
+
+  const ticket = await createTicket(platformUrl, agentToken, localSecret, {
+    objective,
+    title: String(flags.title ?? ''),
+    acceptanceCriteria: String(flags['acceptance-criteria'] ?? ''),
+    availableTools: String(flags['available-tools'] ?? ''),
+    executionTarget: String(flags['execution-target'] ?? 'agent'),
+    priority: String(flags.priority ?? 'medium'),
+    projectId: selectedProject.id
+  });
+
+  if (!launchAgent) {
+    console.log(`ticket created with id ${ticket.id}`);
+    return;
+  }
+
+  const selectedAgent =
+    resolveAgent(typeof flags.agent === 'string' ? flags.agent : '') ??
+    (await promptForSelection({
+      items: PROMPT_AGENTS,
+      label: 'Agents',
+      prompt: 'Select an agent by number:',
+      renderItem: agent => agent
+    }));
+
+  process.env.TICKET_ID = ticket.id;
+  await runLauncherCommand('run', [selectedAgent, '--ticket-id', ticket.id]);
+}
+
+export async function runCreateCommand(args) {
+  if (args[0] === '--help' || args[0] === 'help') {
+    console.log(`${buildUsage('create')}
+
+Creates a ticket after interactive numbered project selection.
+
+Examples:
+  ovld create "Implement login page"
+  ovld create "Fix sync bug" --project-id <project-id>
+`);
+    return;
+  }
+
+  await runTicketCreationFlow(args, { commandName: 'create', launchAgent: false });
+}
+
+export async function runPromptCommand(args) {
+  if (args[0] === '--help' || args[0] === 'help') {
+    console.log(`${buildUsage('prompt')}
+
+Creates a ticket after interactive numbered project selection, then lets you pick an agent by number and launches it on the new ticket.
+
+Examples:
+  ovld prompt "Implement login page"
+  ovld prompt "Investigate flaky tests" --agent codex
+`);
+    return;
+  }
+
+  await runTicketCreationFlow(args, { commandName: 'prompt', launchAgent: true });
+}