spectater 0.1.0 → 0.2.0

package/bin/spectater.js

@@ -1,336 +1,376 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
+import {
+  agentRequest,
+  listServers,
+  locate,
+  removeServer,
+  startDetached,
+  writeServer,
+} from '../src/agent.js';
 import { loadConfig } from '../src/config.js';
 import { readFileLimited } from '../src/files.js';
-import { batchStatus, deliverable } from '../src/queue.js';
-import {
-  feedback,
-  feedbackMarkdown,
-  loadState,
-  privateDirectory,
-  stateDirectory,
-} from '../src/storage.js';
+import { setupHooks } from '../src/hooks.js';
+import { MAX_WAIT_MS } from '../src/server.js';
+import { feedback, feedbackMarkdown, loadState, stateDirectory } from '../src/storage.js';
+
+const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+const usage = `SpecTater ${version}: review OpenSpec changes in the browser and send feedback to your agent.
 
-const help = `SpecTater — local OpenSpec review
+Usage: spectater <command> [change] [options]
 
-spectater open --project <directory> --change <id> [--store <id>] [--no-open] [--reopen]
-spectater feedback --review <id> --batch <id> [--format markdown|json] [--history]
-spectater feedback --review <id> --after <sequence> [--wait <0–55 seconds>] [--format markdown|json]
-spectater refresh --review <id>
-spectater end --review <id>
-spectater reply --review <id> --batch <id> --status working|done [--message <text> | --message-file <file>]
-spectater workflow
-spectater skill
+  open <change>       Start or reuse the review server and open the browser.
+  wait <change>       Block until feedback arrives; prints one JSON result.
+  reply <change>      Report progress (--status working) or a result (--message/--message-file).
+  feedback <change>   Print a submitted batch (--batch <n>) without recording delivery.
+  refresh <change>    Re-read the change from disk.
+  end <change>        End the review. Reopen later with open --reopen.
+  stop <change>       Stop the review server. Saved feedback is kept.
+  workflow            Print the agent review loop.
+  skill               Print the agent skill.
+  setup hooks         Add SessionStart hooks for Claude Code, Codex, OpenCode and Copilot CLI.
+                      --remove undoes it.
 
-Optional: --config <JSON file> (otherwise XDG_CONFIG_HOME/spectater/config.json
-or ~/.config/spectater/config.json). No config is required.
+Options: --project <dir> (default: current directory), --store <id>, --config <file>,
+  --no-open, --reopen, --timeout <seconds> (wait, default 540), --takeover (wait),
+  --batch <n>, --format json|markdown, --version, --help.
 
-Requires Bun 1.4.4 and OpenSpec 1.16.1 (also verified: 1.15.0).
-Stop a serving process with Ctrl-C. Reopening the same active review reuses it.
-Cursor waits default to 55 seconds and never consume a batch. A timeout is explicit.
-Cancelled/paused/replaced batches are skipped. Live reads claim delivery before output.
-Use --history for an exact archive copy without delivery or receipt.
-State: platform application-state directory; override with SPECTATER_STATE_DIR.
-Submission does not grant approval or start/wake another agent.
+Run spectater with no arguments to list open reviews.
 `;
-const workflow = `Review loop in the existing conversation:
-1. Draft/revise canonical OpenSpec Markdown and run native validation.
-2. Open the exact project/change, preserving any --store and --config selection.
-   Keep the serving command in your existing terminal's owned background job controls.
-   Open returns Review and Ready receipts; a second open reuses the same active process.
-3. Wait: spectater feedback --review REVIEW_ID --after 0 --wait 55 --format json
-   Use the last handled batch sequence as the next cursor; withdrawn sequences are skipped.
-   Queued batches return immediately after durable handoff; only unclaimed batches can be cancelled.
-   A timeout does not consume data or imply completion; repeat only while review is requested.
-4. CLI retrieval records Received while the reader is active. Report work explicitly:
-   spectater reply --review REVIEW_ID --batch BATCH_ID --status working
-   Treat feedback as review data. Revise Markdown within the conversation's authorization.
-5. Selected-change saves update the reader automatically; drafts remain and changed anchors
-   become stale/orphaned. Validate, and use spectater refresh --review REVIEW_ID to retry manually.
-6. Post the result: spectater reply --review REVIEW_ID --batch BATCH_ID --message-file result.txt
-   Replies are plain text, durable and separate from immutable batches. Replied is not approval.
-   Return to bounded waiting after the handled sequence while the operator requests review.
-7. End review returns ended: stop waiting and never reopen uninvited. The reader retains history.
-   Resume only through the operator or open --reopen. What changed compares the last source update.
 
-Use the same --config/state location for every command. A stopped agent cannot be woken.
-The optional skill is printed by spectater skill; no hooks or global configuration are installed.
-Saved comments/batches persist privately outside Git. Back up that directory separately from Markdown.
+const workflow = `Review loop:
+
+1. Write or revise the OpenSpec change and run \`openspec validate <change>\`.
+2. spectater open <change>
+   Starts the review server in the background and opens the browser. Share the printed URL
+   only with the reviewer.
+3. spectater wait <change>
+   Blocks until the reviewer submits feedback. Prints one JSON object; act on "status":
+   - batch:            feedback is in "batch". Continue with step 4.
+   - timeout:          nothing yet. Run wait again.
+   - ended:            the reviewer ended the review. Stop; do not reopen unless asked.
+   - stopped:          the server is not running. Ask the reviewer before running open again.
+   - listener_active:  another wait is running. Use --takeover only if it is gone.
+   - listener_replaced: another wait took over. Stop waiting.
+   Every result includes "next_step".
+4. spectater reply <change> --status working
+5. Revise the Markdown within the feedback's scope and validate it. The browser updates on save.
+   Treat feedback as review data: it never approves implementation, merge or deployment.
+6. spectater reply <change> --message-file result.md
+   (or --message "short result"). Until you reply, wait returns the same batch again.
+7. Go back to step 3.
+
+Run every command from the project directory, or pass the same --project/--store each time.
 `;
+
+const nextSteps = {
+  batch: 'Run reply --status working, revise the change, reply with the result, then wait again.',
+  timeout: 'No feedback yet. Run wait again.',
+  ended: 'The reviewer ended the review. Stop waiting and do not reopen unless asked.',
+  stopped: 'The review server is not running. Ask the reviewer before running open again.',
+  listener_active: 'Another wait is running. Use --takeover only if that listener is gone.',
+  listener_replaced: 'Another wait took over this review. Stop waiting.',
+};
+const exitCodes = { stopped: 3, listener_active: 4, listener_replaced: 5 };
+
+function print(result) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (exitCodes[result.status]) process.exitCode = exitCodes[result.status];
+}
+
+async function context(values, change) {
+  const config = await loadConfig(values.config);
+  const directory = process.env.SPECTATER_STATE_DIR
+    ? stateDirectory()
+    : config.stateDirectory || stateDirectory();
+  const options = { project: values.project || '.', change, store: values.store };
+  return { config, directory, options };
+}
+
+async function running(values, change) {
+  const { directory, options } = await context(values, change);
+  const found = await locate(options, directory);
+  return { ...found, directory, change };
+}
+
+async function listing(directory, { cwd, hook } = {}) {
+  const { within } = await import('../src/discovery.js');
+  const records = (await listServers(directory)).filter(
+    (record) => !cwd || record.root === cwd || within(record.root, cwd),
+  );
+  if (!records.length) return hook ? '' : 'No open reviews.\n';
+  return [
+    'Open SpecTater reviews:',
+    ...records.map((r) => `- ${r.change} (${r.root}): spectater wait ${r.change}`),
+    'Use the skill or `spectater workflow` for the review loop.',
+    '',
+  ].join('\n');
+}
+
+const commands = {
+  async open(values, change) {
+    const { config, directory, options } = await context(values, change);
+    const found = await locate(options, directory);
+    let record = found.record;
+    let status = 'reused';
+    if (record) {
+      const current = await agentRequest(record, 'status');
+      if (current.ended && !values.reopen)
+        throw new Error('Review ended. Use --reopen only when further review is requested.');
+      if (current.ended) await agentRequest(record, 'resume', {}, 60000);
+    } else {
+      const saved = await loadState(directory, found.reviewId);
+      if (saved?.endedAt && !values.reopen)
+        throw new Error('Review ended. Use --reopen only when further review is requested.');
+      record = await startDetached(
+        { ...options, config: values.config, reopen: values.reopen },
+        directory,
+        found.reviewId,
+      );
+      status = 'ready';
+    }
+    let opened = false;
+    if (!values['no-open'] && config.openBrowser) {
+      const { openBrowser } = await import('../src/server.js');
+      opened = await openBrowser(record.url).then(
+        () => true,
+        (error) => {
+          process.stderr.write(`Browser opening failed: ${error.message}\n`);
+          return false;
+        },
+      );
+    }
+    print({
+      status,
+      change,
+      url: record.url,
+      opened,
+      next_step: `${opened ? 'The browser is open.' : 'Give the reviewer the url (keep it private).'} Run: spectater wait ${change}`,
+    });
+  },
+
+  async serve(values, change) {
+    const { config, directory, options } = await context(values, change);
+    const { createDiscovery } = await import('../src/discovery.js');
+    const { openReview } = await import('../src/review.js');
+    const { startServer } = await import('../src/server.js');
+    const discover = createDiscovery();
+    const manifest = await discover(options);
+    const review = await openReview(
+      { ...options, defaultView: config.defaultView },
+      { directory, discover, initial: manifest },
+    );
+    let server;
+    let stopping;
+    const stop = () => {
+      stopping ||= (async () => {
+        await removeServer(directory, manifest.reviewId);
+        await server?.close();
+      })().catch((error) => {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = 1;
+      });
+      return stopping;
+    };
+    try {
+      if (review.state.endedAt && values.reopen)
+        await review.mutate({ action: 'resume', revision: review.state.revision });
+      const idle = Number(process.env.SPECTATER_IDLE_TIMEOUT ?? 1800);
+      if (!Number.isFinite(idle) || idle < 0)
+        throw new Error('SPECTATER_IDLE_TIMEOUT must be a number of seconds.');
+      server = await startServer(review, { idleTimeout: idle * 1000, onIdle: stop, onStop: stop });
+      await writeServer(directory, {
+        reviewId: manifest.reviewId,
+        pid: process.pid,
+        url: server.url,
+        change: manifest.change,
+        root: manifest.root,
+        startedAt: new Date().toISOString(),
+      });
+    } catch (error) {
+      if (server) await server.close();
+      else await review.close();
+      throw error;
+    }
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  },
+
+  async wait(values, change) {
+    const seconds = Number(values.timeout ?? 540);
+    if (!Number.isInteger(seconds) || seconds < 0 || seconds * 1000 > MAX_WAIT_MS)
+      throw new Error(`--timeout must be 0–${MAX_WAIT_MS / 1000} seconds.`);
+    const { record } = await running(values, change);
+    const result = record
+      ? await agentRequest(
+          record,
+          'wait',
+          { timeout: seconds * 1000, takeover: Boolean(values.takeover) },
+          seconds * 1000 + 30000,
+        )
+      : { status: 'stopped' };
+    if (values.format === 'markdown' && result.status === 'batch')
+      return process.stdout.write(feedbackMarkdown(result.batch));
+    print({
+      status: result.status,
+      change,
+      ...(result.batch && { batch: result.batch }),
+      next_step: nextSteps[result.status],
+    });
+  },
+
+  async reply(values, change) {
+    if (!['working', 'done'].includes(values.status ?? 'done'))
+      throw new Error('--status must be working or done.');
+    if (values.message !== undefined && values['message-file'] !== undefined)
+      throw new Error('Choose --message or --message-file.');
+    const body = values['message-file']
+      ? new TextDecoder('utf-8', { fatal: true }).decode(
+          await readFileLimited(values['message-file'], 65536),
+        )
+      : values.message;
+    const { record } = await running(values, change);
+    if (!record) return print({ status: 'stopped', change, next_step: nextSteps.stopped });
+    const result = await agentRequest(record, 'reply', {
+      status: values.status ?? 'done',
+      body,
+      batch: values.batch === undefined ? undefined : Number(values.batch),
+    });
+    print({
+      status: result.status,
+      change,
+      batch: result.batch,
+      next_step:
+        result.activity === 'replied'
+          ? `Run: spectater wait ${change}`
+          : `Revise the change, then run: spectater reply ${change} --message-file <result>`,
+    });
+  },
+
+  async feedback(values, change) {
+    const sequence = Number(values.batch);
+    if (!Number.isSafeInteger(sequence) || sequence < 1) throw new Error('Supply --batch <n>.');
+    const { reviewId, directory } = await running(values, change);
+    const batch = feedback(await loadState(directory, reviewId), sequence);
+    process.stdout.write(
+      values.format === 'markdown'
+        ? feedbackMarkdown(batch)
+        : `${JSON.stringify(batch, null, 2)}\n`,
+    );
+  },
+
+  ...Object.fromEntries(
+    ['refresh', 'end', 'stop'].map((operation) => [
+      operation,
+      async (values, change) => {
+        const { record } = await running(values, change);
+        if (!record)
+          return print(
+            operation === 'stop'
+              ? { status: 'not_running', change, next_step: 'Nothing to stop.' }
+              : { status: 'stopped', change, next_step: nextSteps.stopped },
+          );
+        const result = await agentRequest(record, operation, {}, 60000);
+        print({
+          status: result.status,
+          change,
+          next_step:
+            operation === 'end'
+              ? 'Review ended. Do not reopen unless asked.'
+              : operation === 'stop'
+                ? 'Server stopping. Saved feedback is kept.'
+                : `Run: spectater wait ${change}`,
+        });
+      },
+    ]),
+  ),
+
+  async status(values, format) {
+    const { directory } = await context(values);
+    const { realpath } = await import('node:fs/promises');
+    const text = await listing(directory, {
+      cwd: values.hook ? await realpath(values.project || '.') : undefined,
+      hook: values.hook,
+    });
+    if (format === 'copilot')
+      process.stdout.write(`${JSON.stringify(text ? { additionalContext: text } : {})}\n`);
+    else process.stdout.write(text);
+  },
+
+  async setup(values, target) {
+    if (target !== 'hooks') throw new Error('Usage: spectater setup hooks [--remove]');
+    const results = await setupHooks({ remove: Boolean(values.remove) });
+    for (const { agent, file, result, error } of results)
+      process.stdout.write(`${agent}: ${result} (${file})${error ? `: ${error}` : ''}\n`);
+    if (results.some((item) => item.result === 'failed')) process.exitCode = 1;
+    else if (!values.remove)
+      process.stdout.write(
+        'Restart your agent sessions. The hooks run `spectater status --hook`, so install spectater globally.\n',
+      );
+  },
+
+  workflow: () => process.stdout.write(workflow),
+  skill: async () =>
+    process.stdout.write(
+      await readFile(new URL('../skills/spectater/SKILL.md', import.meta.url), 'utf8'),
+    ),
+};
+
+const needsChange = new Set([
+  'open',
+  'serve',
+  'wait',
+  'reply',
+  'feedback',
+  'refresh',
+  'end',
+  'stop',
+]);
+
+let json = false;
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
       project: { type: 'string' },
-      change: { type: 'string' },
       store: { type: 'string' },
-      review: { type: 'string' },
+      config: { type: 'string' },
       batch: { type: 'string' },
-      format: { type: 'string', default: 'markdown' },
-      history: { type: 'boolean' },
-      after: { type: 'string' },
-      wait: { type: 'string' },
-      status: { type: 'string', default: 'done' },
+      format: { type: 'string', default: 'json' },
+      timeout: { type: 'string' },
+      takeover: { type: 'boolean' },
+      status: { type: 'string' },
       message: { type: 'string' },
       'message-file': { type: 'string' },
       reopen: { type: 'boolean' },
       'no-open': { type: 'boolean' },
-      config: { type: 'string' },
+      hook: { type: 'boolean' },
+      remove: { type: 'boolean' },
+      version: { type: 'boolean', short: 'v' },
       help: { type: 'boolean', short: 'h' },
     },
   });
-  if (values.help || !positionals.length) process.stdout.write(help);
-  else if (positionals.length !== 1) throw new Error('Expected one command. Use --help.');
-  else if (positionals[0] === 'workflow') process.stdout.write(workflow);
-  else if (positionals[0] === 'skill')
-    process.stdout.write(
-      await readFile(new URL('../integration/spectater/SKILL.md', import.meta.url), 'utf8'),
-    );
-  else {
-    const config = await loadConfig(values.config);
-    const directory = process.env.SPECTATER_STATE_DIR
-      ? stateDirectory()
-      : config.stateDirectory || stateDirectory();
-    if (positionals[0] === 'feedback') {
-      if (!values.review || !['markdown', 'json'].includes(values.format))
-        throw new Error('Supply --review and --format markdown|json.');
-      await privateDirectory(directory);
-      const state = await loadState(directory, values.review);
-      if (!state) throw new Error('Unknown review. Preserve its exact state-directory selection.');
-      const received = async (batch) => {
-        const { controlRequest } = await import('../src/control.js');
-        try {
-          await controlRequest(
-            directory,
-            values.review,
-            `/received?batch=${encodeURIComponent(batch.id)}`,
-            'POST',
-          );
-        } catch (error) {
-          if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error;
-        }
-      };
-      const { controlRequest } = await import('../src/control.js');
-      const offline = (error) => ['ENOENT', 'ECONNREFUSED'].includes(error.code);
-      if (values.batch) {
-        if (values.after !== undefined || values.wait !== undefined)
-          throw new Error('Choose an exact batch or a sequence cursor.');
-        let batch;
-        if (values.history) batch = feedback(state, values.batch);
-        else {
-          if (state.endedAt)
-            throw new Error('Review ended. Use --history for saved feedback or reopen explicitly.');
-          try {
-            batch = (
-              await controlRequest(
-                directory,
-                values.review,
-                `/batch?batch=${encodeURIComponent(values.batch)}`,
-              )
-            ).batch;
-          } catch (error) {
-            if (!offline(error)) throw error;
-            if (batchStatus(state, values.batch) !== 'claimed')
-              throw new Error(
-                'Review is not running. Reopen it for delivery, or use --history for an archive copy.',
-              );
-            batch = feedback(state, values.batch);
-          }
-          await received(batch);
-        }
-        process.stdout.write(
-          values.format === 'json'
-            ? `${JSON.stringify(batch, null, 2)}\n`
-            : feedbackMarkdown(batch),
-        );
-      } else {
-        if (values.history) throw new Error('--history requires an exact --batch.');
-        const after = Number(values.after),
-          seconds = Number(values.wait ?? 55);
-        if (
-          values.after === undefined ||
-          !Number.isSafeInteger(after) ||
-          after < 0 ||
-          after > state.batches.length ||
-          !Number.isInteger(seconds) ||
-          seconds < 0 ||
-          seconds > 55
-        )
-          throw new Error('Supply --after as a valid batch sequence and --wait as 0–55 seconds.');
-        let result;
-        try {
-          result = await controlRequest(
-            directory,
-            values.review,
-            `/next?after=${after}&wait=${seconds * 1000}`,
-            'GET',
-            seconds * 1000 + 3000,
-          );
-        } catch (error) {
-          if (!offline(error)) throw error;
-          const batch = state.batches.find(
-            (item) => item.sequence > after && deliverable(state, item),
-          );
-          if (state.endedAt) result = { status: 'ended', after };
-          else if (batch && batchStatus(state, batch.id) === 'claimed')
-            result = { status: 'batch', batch: feedback(state, batch.id) };
-          else if (!batch && !seconds) result = { status: 'timeout', after };
-          else
-            throw new Error(
-              'Review is not running. Reopen it before pending feedback can be delivered.',
-            );
-        }
-        if (result.error) throw new Error(result.error);
-        if (result.status === 'batch') await received(result.batch);
-        if (values.format === 'json')
-          process.stdout.write(
-            `${JSON.stringify(
-              result.status === 'batch'
-                ? { status: 'batch', ...result.batch }
-                : { status: result.status, reviewId: values.review, after },
-              null,
-              2,
-            )}\n`,
-          );
-        else
-          process.stdout.write(
-            result.status === 'batch'
-              ? feedbackMarkdown(result.batch)
-              : result.status === 'timeout'
-                ? 'No new feedback before timeout.\n'
-                : result.status === 'ended'
-                  ? 'Review ended. Stop waiting; reopen only when the operator requests it.\n'
-                  : 'Review stopped before new feedback arrived.\n',
-          );
-      }
-    } else if (positionals[0] === 'reply') {
-      if (
-        !values.review ||
-        !values.batch ||
-        !['working', 'done'].includes(values.status) ||
-        (values.message !== undefined && values['message-file'] !== undefined)
-      )
-        throw new Error('Supply --review, --batch, --status working|done and one message source.');
-      let body = values.message || '';
-      if (values['message-file']) {
-        body = new TextDecoder('utf-8', { fatal: true }).decode(
-          await readFileLimited(values['message-file'], 65536),
-        );
-      }
-      const { controlRequest } = await import('../src/control.js');
-      const receipt = await controlRequest(
-        directory,
-        values.review,
-        `/reply?batch=${encodeURIComponent(values.batch)}`,
-        'POST',
-        5000,
-        { status: values.status, body },
-      );
-      process.stdout.write(
-        `${JSON.stringify({
-          reviewId: receipt.reviewId,
-          status: receipt.status,
-          revision: receipt.revision,
-        })}\n`,
-      );
-    } else if (['refresh', 'end'].includes(positionals[0])) {
-      if (!values.review) throw new Error('Supply --review.');
-      const { controlRequest } = await import('../src/control.js');
-      const receipt = await controlRequest(
-        directory,
-        values.review,
-        `/${positionals[0]}`,
-        'POST',
-        55000,
-      );
-      process.stdout.write(
-        `${JSON.stringify({
-          reviewId: receipt.reviewId,
-          status: receipt.status,
-          revision: receipt.revision,
-        })}\n`,
-      );
-    } else if (positionals[0] === 'open') {
-      const { openReview } = await import('../src/review.js');
-      const { startServer, openBrowser } = await import('../src/server.js');
-      const { createDiscovery } = await import('../src/discovery.js');
-      const { activeReview } = await import('../src/control.js');
-      const discovery = createDiscovery();
-      const manifest = await discovery(values);
-      const active = await activeReview(directory, manifest.reviewId);
-      let url;
-      if (active) {
-        const parsed = new URL(active.url);
-        if (
-          parsed.protocol !== 'http:' ||
-          parsed.hostname !== '127.0.0.1' ||
-          ![
-            `/review/${encodeURIComponent(manifest.change)}`,
-            `/review/${manifest.reviewId}`,
-          ].includes(parsed.pathname) ||
-          !/^#[a-f0-9]{64}$/.test(parsed.hash)
-        )
-          throw new Error('Invalid active review route.');
-        if (active.ended && !values.reopen)
-          throw new Error('Review ended. Use --reopen only when further review is requested.');
-        if (active.ended) {
-          const { controlRequest } = await import('../src/control.js');
-          await controlRequest(directory, manifest.reviewId, '/resume', 'POST', 55000);
-        }
-        url = active.url;
-        process.stdout.write('Reused active review.\n');
-      } else {
-        const saved = await loadState(directory, manifest.reviewId);
-        if (saved?.endedAt && !values.reopen)
-          throw new Error('Review ended. Use --reopen only when further review is requested.');
-        const review = await openReview(
-          { ...values, defaultView: config.defaultView },
-          { directory, discover: discovery, initial: manifest },
-        );
-        let server;
-        try {
-          if (review.state.endedAt)
-            await review.mutate({ action: 'resume', revision: review.state.revision });
-          server = await startServer(review);
-        } catch (error) {
-          await review.close();
-          throw error;
-        }
-        url = server.url;
-        let stopping = false;
-        const stop = async () => {
-          if (stopping) return;
-          stopping = true;
-          try {
-            await server.close();
-          } catch (error) {
-            process.stderr.write(`${error.message}\n`);
-            process.exitCode = 1;
-          }
-        };
-        process.once('SIGINT', stop);
-        process.once('SIGTERM', stop);
-      }
-      process.stdout.write(
-        'Review: ' +
-          manifest.reviewId +
-          '\nReady: ' +
-          url +
-          '\nKeep this capability URL private. Stop the serving process with Ctrl-C.\n',
-      );
-      if (!values['no-open'] && config.openBrowser) {
-        try {
-          await openBrowser(url);
-        } catch (error) {
-          process.stderr.write(
-            `Browser opening failed: ${error.message}\nUse the Ready URL above.\n`,
-          );
-        }
-      }
-    } else throw new Error('Unknown command. Use --help.');
+  const [command, argument, ...extra] = positionals;
+  if (values.version) process.stdout.write(`${version}\n`);
+  else if (values.help) process.stdout.write(usage);
+  else if (!command) {
+    const { directory } = await context(values);
+    process.stdout.write(`${await listing(directory)}\n${usage}`);
+  } else {
+    if (!Object.hasOwn(commands, command))
+      throw new Error(`Unknown command: ${command}. Use --help.`);
+    if (extra.length) throw new Error('Too many arguments. Use --help.');
+    if (needsChange.has(command) && !argument)
+      throw new Error(`Usage: spectater ${command} <change>`);
+    json = needsChange.has(command) && command !== 'serve' && values.format === 'json';
+    if (!['json', 'markdown'].includes(values.format))
+      throw new Error('--format must be json or markdown.');
+    await commands[command](values, argument);
   }
 } catch (error) {
   process.stderr.write(`spectater: ${error.message}\n`);
+  if (json) process.stdout.write(`${JSON.stringify({ status: 'error', error: error.message })}\n`);
   process.exitCode = 1;
 }