@agilno-tech/rivet 0.1.0-alpha.0

package/src/cli/output.js

@@ -0,0 +1,174 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * Stable process exit codes. These numeric values are part of the CLI contract.
+ */
+export const EXIT_CODES = Object.freeze({
+  SUCCESS: 0,
+  INVALID_INPUT: 1,
+  MISSING_CONFIGURATION: 2,
+  BLOCKED_AUTHORITY: 3,
+  FAILED_GATE: 4,
+  PROVIDER_UNAVAILABLE: 5,
+  REPOSITORY_CONFLICT: 6,
+  INTERNAL_ERROR: 7,
+});
+
+export const MAX_JSON_OUTPUT_BYTES = 64 * 1024;
+const MIN_JSON_OUTPUT_BYTES = 128;
+const outputErrorSubscriptions = new WeakMap();
+
+export class CliError extends Error {
+  constructor(safeMessage, code = 'INTERNAL_ERROR', { cause } = {}) {
+    super(safeMessage, { cause });
+    this.name = 'CliError';
+    this.safeMessage = safeMessage;
+    this.code = Object.hasOwn(EXIT_CODES, code) ? code : 'INTERNAL_ERROR';
+    this.exitCode = EXIT_CODES[this.code];
+  }
+}
+
+/** Buffers machine output so the process boundary can commit exactly one object. */
+export function createJsonOutputBoundary(maxBytes = MAX_JSON_OUTPUT_BYTES) {
+  const outputBudget = Number.isFinite(maxBytes)
+    ? Math.min(MAX_JSON_OUTPUT_BYTES, Math.max(MIN_JSON_OUTPUT_BYTES, maxBytes))
+    : MAX_JSON_OUTPUT_BYTES;
+  let bufferedWrite = null;
+  let attempted = false;
+  let violated = false;
+
+  const rejectWrite = () => {
+    violated = true;
+    throw new Error('Invalid output in JSON mode');
+  };
+  const output = Object.freeze({
+    log: rejectWrite,
+    warn: rejectWrite,
+    error: rejectWrite,
+    json(value, stream = 'stdout') {
+      if (attempted || (stream !== 'stdout' && stream !== 'stderr')) {
+        rejectWrite();
+      }
+      attempted = true;
+      let serializedValue;
+      try {
+        const serialized = JSON.stringify(value);
+        if (Buffer.byteLength(serialized, 'utf8') + 1 > outputBudget) rejectWrite();
+        serializedValue = JSON.parse(serialized);
+      } catch {
+        rejectWrite();
+      }
+      if (
+        serializedValue === null
+        || Array.isArray(serializedValue)
+        || typeof serializedValue !== 'object'
+      ) {
+        rejectWrite();
+      }
+      bufferedWrite = { value: serializedValue, stream };
+    },
+  });
+
+  return Object.freeze({
+    output,
+    commit(target, exitCode) {
+      const expectedStream = exitCode === EXIT_CODES.SUCCESS ? 'stdout' : 'stderr';
+      if (violated || !bufferedWrite || bufferedWrite.stream !== expectedStream) {
+        throw new Error('Invalid output in JSON mode');
+      }
+      target.json(bufferedWrite.value, bufferedWrite.stream);
+    },
+  });
+}
+
+export function createOutput({ stdout = process.stdout, stderr = process.stderr } = {}) {
+  const listeners = new Set();
+  let detachStreams = null;
+  const notifyOutputError = () => {
+    for (const listener of listeners) {
+      try { listener(); } catch { /* output failure observers cannot affect publication */ }
+    }
+  };
+  const attachStream = stream => {
+    if (!stream || typeof stream.on !== 'function' || typeof stream.off !== 'function') return () => {};
+    const onError = () => notifyOutputError();
+    stream.on('error', onError);
+    return () => {
+      try { stream.off('error', onError); } catch { /* stream cleanup is best effort */ }
+    };
+  };
+  const subscribe = listener => {
+    listeners.add(listener);
+    if (listeners.size === 1) {
+      let detachStdout = () => {};
+      let detachStderr = () => {};
+      try {
+        detachStdout = attachStream(stdout);
+        if (stderr !== stdout) detachStderr = attachStream(stderr);
+      } catch {
+        listeners.delete(listener);
+        detachStdout();
+        detachStderr();
+        return null;
+      }
+      detachStreams = () => { detachStdout(); detachStderr(); };
+    }
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      listeners.delete(listener);
+      if (listeners.size === 0 && detachStreams) {
+        detachStreams();
+        detachStreams = null;
+      }
+    };
+  };
+  const writeLine = (stream, value = '') => {
+    try { stream.write(`${String(value)}\n`); }
+    catch {
+      notifyOutputError();
+      throw new Error('Output publication failed.');
+    }
+  };
+
+  const output = Object.freeze({
+    log: value => writeLine(stdout, value),
+    warn: value => writeLine(stderr, value),
+    error: value => writeLine(stderr, value),
+    json(value, stream = 'stdout') {
+      writeLine(stream === 'stderr' ? stderr : stdout, JSON.stringify(value));
+    },
+  });
+  outputErrorSubscriptions.set(output, subscribe);
+  return output;
+}
+
+/** Subscribes only outputs created by createOutput; listener receives no raw stream error. */
+export function observeOutputErrors(output, listener) {
+  if (typeof listener !== 'function') return null;
+  const subscribe = outputErrorSubscriptions.get(output);
+  if (!subscribe) return null;
+  try { return subscribe(listener); } catch { return null; }
+}
+
+/** JSON-mode errors are one object on stderr; human-readable errors use stderr text. */
+export function emitCliError(output, error, { json = false } = {}) {
+  const cliError = error instanceof CliError
+    ? error
+    : new CliError('Unexpected rivet failure.', 'INTERNAL_ERROR');
+
+  if (json) {
+    output.json({
+      ok: false,
+      error: {
+        code: cliError.code,
+        exitCode: cliError.exitCode,
+        message: cliError.safeMessage,
+      },
+    }, 'stderr');
+  } else {
+    output.error(`ERROR: ${cliError.safeMessage}`);
+  }
+  return cliError.exitCode;
+}

package/src/cli/parse-args.js

@@ -0,0 +1,246 @@
+const COMMANDS = new Set([
+  'doctor',
+  'support',
+  'delivery',
+  'evidence',
+  'feature',
+  'goals',
+  'init',
+  'install',
+  'models',
+  'integrations',
+  'repositories',
+  'orchestrate',
+  'preflight',
+  'protocols',
+  'run',
+  'status',
+  'setup',
+  'uninstall',
+  'verify',
+  'work',
+  'task',
+  'worktrees',
+]);
+
+const LEGACY_COMMANDS = new Set(['init', 'install', 'uninstall']);
+const NESTED_COMMANDS = new Set(['delivery', 'feature', 'goals', 'integrations', 'repositories', 'models', 'orchestrate', 'protocols', 'task', 'work', 'worktrees']);
+const FLAG_NAME = /^[a-z][a-z0-9-]*$/;
+const LEGACY_OPTIONS = {
+  init: {
+    boolean: new Set(['json', 'overwrite', 'write']),
+    valued: new Set(['project', 'remote', 'checks-json', 'dependencies-json']),
+  },
+  install: {
+    boolean: new Set(['all', 'claude', 'codex', 'global', 'json', 'minimal', 'project-runtime']),
+    valued: new Set(['target', 'project']),
+  },
+  uninstall: {
+    boolean: new Set(['all', 'claude', 'codex', 'global', 'json', 'minimal', 'project-runtime']),
+    valued: new Set(['target', 'project']),
+  },
+};
+const STRICT_OPTIONS = {
+  delivery: { boolean: new Set(['json']), valued: new Set(['project', 'run', 'remote', 'provider', 'method', 'title', 'body']) },
+  repositories: { boolean: new Set(['json']), valued: new Set(['project', 'remote', 'provider', 'review']) },
+  integrations: { boolean: new Set(['json']), valued: new Set(['project', 'host-inventory-json']) },
+  protocols: {
+    boolean: new Set(['json', 'include-drafts', 'include-retired', 'publish']),
+    valued: new Set(['expected-revision', 'expected-digest', 'from', 'project']),
+  },
+  work: {
+    boolean: new Set(['json']),
+    valued: new Set([
+      'action', 'action-json', 'decomposition', 'decomposition-json', 'result-json', 'expected-runtime-version', 'expected-version', 'project', 'result',
+      'request', 'request-text', 'ticket', 'tracker', 'host-context-json', 'acceptance-criteria', 'run',
+    ]),
+  },
+  run: {
+    boolean: new Set(['details']),
+    valued: new Set(['project', 'harness']),
+  },
+  task: {
+    boolean: new Set(['details']),
+    valued: new Set(['project', 'run']),
+  },
+  setup: {
+    boolean: new Set(['global', 'write', 'json']),
+    valued: new Set(['project', 'target', 'remote', 'checks-json', 'dependencies-json']),
+  },
+  models: {
+    boolean: new Set(['json']),
+    valued: new Set(['profile', 'roles', 'role', 'project']),
+  },
+  support: {
+    boolean: new Set(['json', 'probe-harnesses', 'save']),
+    valued: new Set(['project']),
+  },
+  doctor: {
+    boolean: new Set(['json']),
+    valued: new Set(['project']),
+  },
+  feature: {
+    boolean: new Set(['json']),
+    valued: new Set([
+      'client', 'expected-version', 'project', 'proposal-digest', 'request', 'request-text', 'ticket', 'tracker', 'acceptance-criteria', 'run',
+    ]),
+  },
+  preflight: {
+    boolean: new Set(['json']),
+    valued: new Set(['project', 'mode']),
+  },
+  status: {
+    boolean: new Set(['json']),
+    valued: new Set(['fixture', 'port']),
+  },
+};
+const NO_POSITIONAL_COMMANDS = new Set(['doctor', 'support', 'init', 'install', 'preflight', 'setup', 'uninstall']);
+
+function targetSet(target) {
+  const normalized = typeof target === 'string' ? target.toLowerCase() : target;
+  if (normalized === 'both') return new Set(['claude', 'codex']);
+  if (normalized === 'claude' || normalized === 'codex') return new Set([normalized]);
+  return null;
+}
+
+function sameSet(left, right) {
+  return left.size === right.size && [...left].every(value => right.has(value));
+}
+
+function validateTargetSelectors(command, flags) {
+  if (!['install', 'uninstall', 'setup'].includes(command)) return;
+  const aliases = new Set();
+  if (flags.claude) aliases.add('claude');
+  if (flags.codex) aliases.add('codex');
+  const explicit = targetSet(flags.target);
+  if (flags.target !== undefined && !explicit) {
+    throw new ArgumentError("Invalid --target value. Use 'claude', 'codex', or 'both'.");
+  }
+  if (aliases.size > 0 && explicit && !sameSet(aliases, explicit)) {
+    throw new ArgumentError('Conflicting target selectors');
+  }
+}
+
+export class ArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ArgumentError';
+  }
+}
+
+export function parseArgs(argv) {
+  if (!Array.isArray(argv) || argv.some(argument => typeof argument !== 'string')) {
+    throw new TypeError('CLI arguments must be an array of strings');
+  }
+
+  const [command = null, ...tokens] = argv;
+  if (command === null) {
+    return { command: null, subcommand: null, operands: [], flags: {} };
+  }
+  if (!command || command.startsWith('-')) {
+    throw new ArgumentError('A command must be provided before flags');
+  }
+  if (!COMMANDS.has(command)) {
+    throw new ArgumentError(`Unknown command '${command}'`);
+  }
+
+  const flags = {};
+  const positionals = [];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.startsWith('--')) {
+      // Legacy parsing never supported `--`; reject it explicitly instead of
+      // ambiguously treating subsequent tokens as flags or operands.
+      if (token === '--') {
+        throw new ArgumentError("End-of-options separator '--' is not supported");
+      }
+      const body = token.slice(2);
+      const separator = body.indexOf('=');
+      const name = separator === -1 ? body : body.slice(0, separator);
+      let value = separator === -1 ? true : body.slice(separator + 1);
+      if (!FLAG_NAME.test(name) || (value === '' && !(command === 'delivery' && positionals[0] === 'review-update' && name === 'body' && separator !== -1))) {
+        throw new ArgumentError(`Malformed flag '${token}'`);
+      }
+      if (Object.hasOwn(flags, name)) {
+        throw new ArgumentError(`Duplicate flag '--${name}'`);
+      }
+      if (name === 'json' && value !== true) {
+        throw new ArgumentError("Flag '--json' does not take a value");
+      }
+      const commandOptions = LEGACY_OPTIONS[command] ?? STRICT_OPTIONS[command];
+      if (commandOptions) {
+        if (!commandOptions.boolean.has(name) && !commandOptions.valued.has(name)) {
+          throw new ArgumentError(`Unknown option '--${name}' for command '${command}'`);
+        }
+        if (commandOptions.boolean.has(name) && value !== true) {
+          throw new ArgumentError(`Flag '--${name}' does not take a value`);
+        }
+        if (commandOptions.valued.has(name) && value === true) {
+          if ((['task', 'work'].includes(command) && name === 'run') || command === 'delivery' || command === 'repositories' || command === 'integrations' || command === 'setup' || command === 'protocols' || ((command === 'install' || command === 'uninstall') && name === 'project') || command === 'init' || command === 'doctor' || command === 'support' || command === 'feature' || command === 'preflight' || command === 'status') {
+            const next = tokens[index + 1];
+            if (typeof next === 'string' && next.length > 0 && !next.startsWith('-')) {
+              value = next;
+              index += 1;
+            } else {
+              throw new ArgumentError(`Flag '--${name}' requires a value`);
+            }
+          } else {
+            throw new ArgumentError(`Flag '--${name}' requires a value`);
+          }
+        }
+      }
+      flags[name] = value;
+    } else if (!token || token.startsWith('-')) {
+      throw new ArgumentError(`Malformed argument '${token}'`);
+    } else {
+      positionals.push(token);
+    }
+  }
+
+  if (['feature', 'work'].includes(command) && flags.run !== undefined) {
+    const lifecycle = command === 'feature'
+      ? ['start', 'status', 'resume', 'cancel'] : ['prepare', 'next', 'status', 'submit', 'verify', 'recover'];
+    if (!lifecycle.includes(positionals[0])) throw new ArgumentError('--run is only supported for an existing run.');
+    if (positionals.length !== 1) throw new ArgumentError('Use one run selector: --run or a positional run ID.');
+  }
+
+  validateTargetSelectors(command, flags);
+  if (['install', 'uninstall', 'setup'].includes(command) && flags.global && flags.project !== undefined) {
+    throw new ArgumentError('--global and --project cannot be combined');
+  }
+  if (['install', 'uninstall'].includes(command)) {
+    if (flags.project !== undefined && !flags.minimal) throw new ArgumentError('--project requires --minimal');
+    if (flags.minimal && flags.all) throw new ArgumentError('--minimal and --all cannot be combined');
+  }
+
+  if (command === 'init' && flags.overwrite && !flags.write) {
+    throw new ArgumentError("Flag '--overwrite' requires '--write'");
+  }
+
+  if (NO_POSITIONAL_COMMANDS.has(command) && positionals.length > 0) {
+    throw new ArgumentError(`Command '${command}' does not accept positional arguments`);
+  }
+  if (command === 'status' && positionals.length !== 1) {
+    throw new ArgumentError("Command 'status' requires exactly one instance ID");
+  }
+  if (NESTED_COMMANDS.has(command) && positionals.length === 0) {
+    throw new ArgumentError(`Command '${command}' requires a subcommand`);
+  }
+  if (command === 'protocols' && !['add', 'import', 'validate', 'find', 'show', 'update', 'retire'].includes(positionals[0])) {
+    throw new ArgumentError('Unsupported protocol subcommand');
+  }
+  if (command === 'work' && !['propose', 'prepare', 'next', 'status', 'submit', 'verify', 'recover'].includes(positionals[0])) {
+    throw new ArgumentError('Unsupported work subcommand');
+  }
+  if (command === 'task' && !['status', 'start', 'approve', 'resume', 'deps', 'recover'].includes(positionals[0])) {
+    throw new ArgumentError('Unsupported task subcommand');
+  }
+
+  return {
+    command,
+    subcommand: NESTED_COMMANDS.has(command) ? positionals.shift() : null,
+    operands: positionals,
+    flags,
+  };
+}

package/src/cli/project-discovery.js

@@ -0,0 +1,70 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+import { loadProjectConfig } from '../config/load.js';
+import { runArgv } from '../discovery/tools.js';
+import { CliError } from './output.js';
+
+function fail(message) { throw new CliError(message, 'MISSING_CONFIGURATION'); }
+
+async function gitRoot(directory, runner, env) {
+  const result = await runner(await gitExecutable(env), ['rev-parse', '--show-toplevel'], {
+    cwd: directory, shell: false, timeoutMs: 3_000, maxOutputBytes: 4 * 1024,
+  });
+  const output = typeof result?.stdout === 'string' ? result.stdout.trim() : '';
+  if (result?.code !== 0 || result?.timedOut || result?.truncated?.stdout
+    || !output.startsWith('/') || /[\u0000\r\n]/.test(output)) {
+    fail('Run this command from a Git project configured by rivet setup, or pass --project.');
+  }
+  return realpath(output);
+}
+
+export async function gitExecutable(env) {
+  const configured = env.RIVET_GIT_EXECUTABLE;
+  if (configured !== undefined) {
+    if (!configured.startsWith('/') || /[\u0000\r\n]/.test(configured)) fail('Configured Git executable is invalid.');
+    try { return await realpath(configured); }
+    catch { fail('Configured Git executable is unavailable.'); }
+  }
+  for (const candidate of ['/opt/homebrew/bin/git', '/usr/local/bin/git', '/usr/bin/git']) {
+    try { return await realpath(candidate); } catch {}
+  }
+  fail('Git is unavailable. Install Git or set RIVET_GIT_EXECUTABLE to its absolute path.');
+}
+
+export async function resolveConfiguredProject(cwd, explicit, options = {}) {
+  if (typeof cwd !== 'string' || !cwd.startsWith('/')
+    || (explicit !== undefined && (typeof explicit !== 'string' || !explicit || /[\u0000\r\n]/.test(explicit)))) {
+    throw new CliError('Project path is invalid.', 'INVALID_INPUT');
+  }
+  let selected;
+  try { selected = await realpath(resolve(cwd, explicit ?? '.')); }
+  catch { fail('Project directory was not found. Run from a configured project or pass --project.'); }
+  const root = await gitRoot(selected, options.runner ?? runArgv, options.env ?? process.env);
+  if (explicit !== undefined && selected !== root) {
+    throw new CliError('--project must name the configured Git project root.', 'INVALID_INPUT');
+  }
+  if (explicit === undefined) {
+    const inside = relative(root, selected);
+    if (inside === '..' || inside.startsWith(`..${sep}`)) fail('Current directory is outside the Git project.');
+    let ancestor = selected;
+    while (ancestor !== root) {
+      const nested = await lstat(join(ancestor, '.rivet')).catch(error => {
+        if (error?.code === 'ENOENT') return null;
+        throw error;
+      });
+      if (nested !== null) fail('A nested .rivet configuration is present. Pass the intended project root explicitly.');
+      ancestor = dirname(ancestor);
+    }
+  }
+  let configured;
+  try {
+    const marker = await lstat(join(root, '.rivet'));
+    if (!marker.isDirectory() || marker.isSymbolicLink()) fail('Project .rivet configuration is unsafe.');
+    configured = await loadProjectConfig(root);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    fail('Rivet is not configured in this Git project. Run rivet setup --write first.');
+  }
+  return Object.freeze({ root, config: configured });
+}

package/src/cli/task-confirmation.js

@@ -0,0 +1,38 @@
+import { createInterface } from 'node:readline/promises';
+
+// Plan review has no reading deadline. EOF, stream errors and cancellation all
+// decline; callers still revalidate the approved state before any mutation.
+export async function readTaskAnswer(message, {input = process.stdin, output = process.stdout, signal} = {}) {
+  if (signal?.aborted) return '';
+  const readline = createInterface({input, output});
+  let decline;
+  const ended = new Promise(resolve => { decline = () => resolve(''); });
+  const abort = () => { decline(); readline.close(); };
+  readline.once('close', decline);
+  readline.on('error', decline);
+  input.once('error', decline);
+  output.once('error', decline);
+  signal?.addEventListener('abort', abort, {once:true});
+  try {
+    const answer = await Promise.race([readline.question(message), ended]);
+    return signal?.aborted ? '' : String(answer).trim();
+  } catch { return ''; }
+  finally {
+    signal?.removeEventListener('abort', abort);
+    input.removeListener('error', decline);
+    output.removeListener('error', decline);
+    readline.close();
+  }
+}
+
+export async function confirmTaskAction(message, options) {
+  return /^(?:y|yes)$/i.test(await readTaskAnswer(message, options));
+}
+
+export async function selectTaskOption(question, streams = {}) {
+  const prompt = `${question.message}\n${question.choices.map((choice,index)=>`  ${index+1}. ${choice.label}`).join('\n')}\nNumber (blank to leave): `;
+  const answer = await readTaskAnswer(prompt, {...streams,signal:question.signal});
+  if (!/^[1-9][0-9]*$/.test(answer)) return null;
+  const index = Number(answer)-1;
+  return Number.isSafeInteger(index) && index < question.choices.length ? question.choices[index].value : null;
+}

package/src/cli/task-presentation.js

@@ -0,0 +1,22 @@
+const STATES = Object.freeze({
+  proposed: 'Plan saved, waiting for your approval',
+  approved: 'Plan approved, ready to start',
+  running: 'Work is in progress',
+  blocked: 'Work paused and needs attention',
+  'awaiting-final-approval': 'Changes passed checks and are ready for your review',
+  completed: 'Completed',
+  cancelled: 'Cancelled',
+});
+export function taskState(value) { return STATES[value] ?? 'Inspect task status for the next step'; }
+export function failureGuidance(code, command) {
+  const task = ['run','task','feature','work'].includes(command);
+  switch(code) {
+    case 'INVALID_INPUT': return 'Check rivet --help for everyday commands, or rivet --help --advanced for harness commands.';
+    case 'MISSING_CONFIGURATION': return 'Run rivet doctor from your project. If it is not configured yet, preview rivet setup first.';
+    case 'BLOCKED_AUTHORITY': return 'Review the denied operation in your coding harness and request permission for that exact operation.';
+    case 'FAILED_GATE': return task ? 'Run rivet task status to inspect the failed checks. Fix the reported cause before continuing with rivet task resume.' : 'Run rivet doctor and resolve the reported failing check before retrying.';
+    case 'PROVIDER_UNAVAILABLE': return 'Check the reported harness or provider installation, authentication and permissions, then retry.';
+    case 'REPOSITORY_CONFLICT': return task ? 'Inspect rivet task status and your checkout. Preserve existing edits and follow the reported recovery step before retrying.' : 'Inspect the reported repository or saved-state conflict. Preserve existing edits before retrying.';
+    default: return 'Review the diagnostic report and attach it with reproduction steps at https://github.com/Agilno-Tech/rivet/issues/new.';
+  }
+}