@ravshansbox/pi-next-issue 2.21.1 → 3.0.0

package/index.ts

@@ -1,102 +1,41 @@
-import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
-import { must, type RunOptions } from './src/exec.ts';
+import { answerAll, type Gh } from './src/answer.ts';
+import { shared } from './src/clients.ts';
+import { errorText } from './src/errors.ts';
+import { must } from './src/exec.ts';
 import { repoRoot } from './src/git.ts';
+import type { Progress, Question } from './src/protocol.ts';
+import { startRun, statusOf, toggle } from './src/run.ts';
 import {
-  type Progress,
-  type Question,
-  spawnWorker,
-  WorkerClient,
-  type WorkerEvent,
-  workerPaths,
-} from './src/worker.ts';
+  cannotNote,
+  formatQuestions,
+  formatStatus,
+  handledNotes,
+  type Note,
+  questionNotes,
+  statusNote,
+} from './src/status.ts';
+import { spawnWorker, workerPaths } from './src/spawn-worker.ts';
+import { WorkerClient, type WorkerEvent } from './src/worker.ts';
 
 export type Options = {
   client: (root: string) => WorkerClient;
   root: (cwd: string) => Promise<string>;
-  gh: (args: string[], options: RunOptions) => Promise<string>;
+  gh: Gh;
 };
 
-const KEY = Symbol.for('pi-next-issue');
 const STATUS_KEY = 'next-issue';
 const QUESTIONS_KEY = 'next-issue-questions';
+const RENDER_MS = 1000;
 const QUESTIONS_MS = 60_000;
-const RETRY = 'Retry';
-const GUIDE = 'Retry with guidance';
-const GIVE_UP = 'Give up';
 
-export function formatQuestions(count: number): string {
-  return `${count} ${count === 1 ? 'question' : 'questions'} waiting`;
-}
-
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function shared(create: (root: string) => WorkerClient, root: string): WorkerClient {
-  const store = globalThis as Record<symbol, Map<string, WorkerClient> | undefined>;
-  const clients = (store[KEY] ??= new Map());
-  let client = clients.get(root);
-  if (client === undefined) {
-    client = create(root);
-    clients.set(root, client);
-  }
-  return client;
-}
-
-function duration(ms: number): string {
-  const seconds = Math.max(0, Math.floor(ms / 1000));
-  const minutes = Math.floor(seconds / 60);
-  return minutes > 0 ? `${minutes}m${String(seconds % 60).padStart(2, '0')}s` : `${seconds}s`;
-}
-
-function outcomes(progress: Progress): string {
-  const done = progress.handled.filter((item) => item.outcome === 'done').length;
-  const human = progress.handled.filter((item) => item.outcome === 'needs-human').length;
-  const failed = progress.handled.filter((item) => item.outcome === 'error').length;
-  const parts = [`${done} done`];
-  if (human > 0) {
-    parts.push(`${human} needs a human`);
-  }
-  if (failed > 0) {
-    parts.push(`${failed} failed`);
-  }
-  return parts.join(', ');
-}
-
-const OUTCOME_NOTES = { done: 'done', 'needs-human': 'needs a human', error: 'failed' } as const;
-
-export function formatStatus(progress: Progress, now: number): string {
-  const running = progress.issues ?? [];
-  switch (progress.status) {
-    case 'running': {
-      if (running.length === 0) {
-        return 'looking for issues';
-      }
-      const count = progress.open === undefined ? '' : `/${progress.open}`;
-      const lines = running.map((item) => {
-        const parts = [`#${item.issue}${count}`, item.stage ?? 'prepare', `${item.tools} tools`];
-        if (item.startedAt !== undefined) {
-          parts.push(duration(now - item.startedAt));
-        }
-        return parts.join(' · ');
-      });
-      return lines.join(' | ');
-    }
-    case 'stopping': {
-      const issues = running.map((item) => `#${item.issue}`);
-      return `${issues.length === 0 ? '#?' : issues.join(' ')} · stopping`;
-    }
-    case 'stopped':
-      return `stopped: ${outcomes(progress)}`;
-    case 'finished':
-      return `finished: ${outcomes(progress)}`;
-    case 'failed':
-      return `failed: ${progress.error ?? 'unknown error'}`;
-  }
+function background(callback: () => void, ms: number): ReturnType<typeof setInterval> {
+  const timer = setInterval(callback, ms);
+  timer.unref?.();
+  return timer;
 }
 
 function packageVersion(): string {
@@ -128,15 +67,23 @@ export function createExtension(options: Options) {
     let status: Progress['status'] | undefined;
     let baseline = false;
 
+    const clientOf = (root: string) => shared(options.client, root);
+
     const current = (): Progress | undefined =>
-      root === undefined ? undefined : shared(options.client, root).runs[root];
+      root === undefined ? undefined : clientOf(root).runs[root];
+
+    const remember = (progress: Progress | undefined) => {
+      handled = progress?.handled.length ?? 0;
+      status = progress?.status;
+    };
+
+    const dim = (text: string) => (coloured && ui !== undefined ? ui.theme.fg('dim', text) : text);
 
     const render = () => {
       const progress = current();
       if (ui === undefined || progress === undefined) {
         return;
       }
-      const dim = (text: string) => (coloured ? ui!.theme.fg('dim', text) : text);
       ui.setStatus(STATUS_KEY, dim(formatStatus(progress, Date.now())));
     };
 
@@ -144,71 +91,71 @@ export function createExtension(options: Options) {
       if (ui === undefined || waiting === undefined) {
         return;
       }
-      const text = formatQuestions(waiting.length);
       ui.setStatus(
         QUESTIONS_KEY,
-        waiting.length === 0 ? undefined : coloured ? ui.theme.fg('dim', text) : text,
+        waiting.length === 0 ? undefined : dim(formatQuestions(waiting.length)),
       );
     };
 
+    const tell = (note: Note | undefined) => {
+      if (note !== undefined) {
+        ui?.notify(note.text, note.level);
+      }
+    };
+
     const onQuestions = (questions: Question[]) => {
       const known = waiting;
       waiting = questions.map((question) => question.issue);
-      for (const question of questions) {
-        if (known !== undefined && !known.includes(question.issue)) {
-          ui?.notify(`next-issue: #${question.issue} has a question: ${question.title}`, 'warning');
-        }
-      }
+      questionNotes(questions, known).forEach(tell);
       paintQuestions();
     };
 
     const askQuestions = () => {
       if (root !== undefined) {
-        shared(options.client, root).send({ type: 'questions', root });
+        clientOf(root).send({ type: 'questions', root });
       }
     };
 
-    const onProgress = (progress: Progress | undefined) => {
-      if (progress === undefined) {
+    const announce = (progress: Progress) => {
+      if (progress.status === status) {
         return;
       }
+      status = progress.status;
+      tell(statusNote(progress));
+    };
+
+    const notifyHandled = (progress: Progress) => {
       if (progress.handled.length < handled) {
         handled = 0;
       }
-      for (const item of progress.handled.slice(handled)) {
-        ui?.notify(
-          `next-issue: #${item.issue} ${OUTCOME_NOTES[item.outcome]}`,
-          item.outcome === 'done' ? 'info' : 'warning',
-        );
-      }
+      handledNotes(progress, handled).forEach(tell);
       handled = progress.handled.length;
-      if (progress.status !== status) {
-        status = progress.status;
-        if (status === 'finished') {
-          ui?.notify('next-issue finished', 'info');
-        } else if (status === 'stopped') {
-          ui?.notify('next-issue stopped', 'info');
-        } else if (status === 'failed') {
-          ui?.notify(`next-issue failed: ${progress.error ?? 'unknown error'}`, 'error');
-        }
+    };
+
+    const onProgress = (progress: Progress | undefined) => {
+      if (progress === undefined) {
+        return;
       }
+      notifyHandled(progress);
+      announce(progress);
       render();
     };
 
     const onEvent = (event: WorkerEvent) => {
-      if (event.type === 'runs' && baseline) {
-        baseline = false;
+      if (event.type === 'runs') {
         const progress = root === undefined ? undefined : event.runs[root];
-        handled = progress?.handled.length ?? 0;
-        status = progress?.status;
-        render();
-        askQuestions();
-      } else if (event.type === 'runs') {
-        onProgress(root === undefined ? undefined : event.runs[root]);
+        if (baseline) {
+          baseline = false;
+          remember(progress);
+          render();
+          askQuestions();
+        } else {
+          onProgress(progress);
+        }
       } else if (event.type === 'questions' && event.root === root) {
         onQuestions(event.questions);
       } else if (event.type === 'error' && event.root === root) {
-        ui?.notify(`next-issue cannot start: ${event.message}`, 'error');
+        tell(cannotNote('start', event.message));
       }
     };
 
@@ -217,10 +164,8 @@ export function createExtension(options: Options) {
       if (root === undefined) {
         return;
       }
-      const client = shared(options.client, root);
-      const progress = current();
-      handled = progress?.handled.length ?? 0;
-      status = progress?.status;
+      const client = clientOf(root);
+      remember(current());
       waiting = client.questions[root]?.map((question) => question.issue);
       baseline = !client.connected;
       unsubscribe = client.subscribe(onEvent);
@@ -234,10 +179,8 @@ export function createExtension(options: Options) {
     const show = (ctx: ExtensionContext) => {
       ui = ctx.ui;
       coloured = ctx.mode === 'tui';
-      timer ??= setInterval(render, 1000);
-      timer.unref?.();
-      poll ??= setInterval(askQuestions, QUESTIONS_MS);
-      poll.unref?.();
+      timer ??= background(render, RENDER_MS);
+      poll ??= background(askQuestions, QUESTIONS_MS);
     };
 
     pi.on('session_start', async (_event, ctx) => {
@@ -250,20 +193,16 @@ export function createExtension(options: Options) {
         return;
       }
       follow();
-      await shared(options.client, root).attach();
+      await clientOf(root).attach();
     });
 
     pi.on('session_shutdown', async () => {
       unsubscribe?.();
       unsubscribe = undefined;
-      if (timer !== undefined) {
-        clearInterval(timer);
-        timer = undefined;
-      }
-      if (poll !== undefined) {
-        clearInterval(poll);
-        poll = undefined;
-      }
+      clearInterval(timer);
+      timer = undefined;
+      clearInterval(poll);
+      poll = undefined;
       ui = undefined;
     });
 
@@ -273,42 +212,11 @@ export function createExtension(options: Options) {
         show(ctx);
         follow();
       }
-      const client = shared(options.client, root);
+      const client = clientOf(root);
       await client.ensure();
       return { client, root, progress: client.runs[root] };
     };
 
-    const going = (progress: Progress | undefined): progress is Progress =>
-      progress?.status === 'running' || progress?.status === 'stopping';
-
-    const accepted = (client: WorkerClient, root: string, signal: AbortSignal | undefined) =>
-      new Promise<void>((resolve, reject) => {
-        const finish = (error?: Error) => {
-          stop();
-          signal?.removeEventListener('abort', abort);
-          if (error === undefined) {
-            resolve();
-          } else {
-            reject(error);
-          }
-        };
-        const abort = () => finish(new Error('next_issue_start was cancelled'));
-        const stop = client.subscribe((event) => {
-          if (event.type === 'error' && event.root === root) {
-            finish(new Error(event.message));
-          } else if (event.type === 'closed') {
-            finish(new Error('the worker closed the connection'));
-          } else if (event.type === 'runs' && going(event.runs[root])) {
-            finish();
-          }
-        });
-        if (signal?.aborted) {
-          abort();
-        } else {
-          signal?.addEventListener('abort', abort, { once: true });
-        }
-      });
-
     pi.registerTool({
       name: 'next_issue_start',
       label: 'Start next-issue',
@@ -318,32 +226,10 @@ export function createExtension(options: Options) {
       parameters: Type.Object({}),
       async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
         const { client, root, progress } = await connect(ctx);
-        if (going(progress)) {
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `A run of ${root} is going already, so nothing started: ${formatStatus(progress, Date.now())}. It picks up new issues by itself.`,
-              },
-            ],
-            details: { started: false, root },
-          };
-        }
-        const accepting = accepted(client, root, signal);
-        client.send({ type: 'start', root, merge: true });
-        await accepting;
-        return {
-          content: [{ type: 'text', text: `Started a next-issue run of ${root}.` }],
-          details: { started: true, root },
-        };
+        return startRun(client, root, progress, signal);
       },
     });
 
-    const report = (text: string, root: string) => ({
-      content: [{ type: 'text' as const, text }],
-      details: { root },
-    });
-
     pi.registerTool({
       name: 'next_issue_status',
       label: 'next-issue status',
@@ -353,120 +239,27 @@ export function createExtension(options: Options) {
       parameters: Type.Object({}),
       async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
         const root = await options.root(ctx.cwd);
-        const client = shared(options.client, root);
-        await client.attach();
-        if (!client.connected) {
-          return report('no worker is running', root);
-        }
-        const progress = client.runs[root];
-        if (progress === undefined) {
-          return report(`no run of ${root}`, root);
-        }
-        const lines = [
-          formatStatus(progress, Date.now()),
-          ...progress.handled.map((item) => `#${item.issue} ${OUTCOME_NOTES[item.outcome]}`),
-        ];
-        return report(lines.join('\n'), root);
+        return statusOf(clientOf(root), root);
       },
     });
 
-    const fresh = (client: WorkerClient, root: string) =>
-      new Promise<Question[]>((resolve, reject) => {
-        const id = randomUUID();
-        const stop = client.subscribe((event) => {
-          if (event.type === 'questions' && event.root === root && event.id === id) {
-            stop();
-            resolve(event.questions);
-          } else if (event.type === 'questions-error' && event.root === root && event.id === id) {
-            stop();
-            reject(new Error(event.message));
-          } else if (event.type === 'closed') {
-            stop();
-            reject(new Error('the worker closed the connection'));
-          }
-        });
-        client.send({ type: 'questions', root, id });
-      });
-
-    const reply = async (root: string, question: Question, choice: string, guidance: string) => {
-      const threads: Array<[string, number]> = [['issue', question.issue]];
-      if (question.pr !== undefined) {
-        threads.push(['pr', question.pr]);
-      }
-      const repo = ['--repo', question.repo];
-      if (choice === GUIDE) {
-        const [kind, number] = threads.at(-1)!;
-        await options.gh([kind, 'comment', String(number), ...repo, '--body-file', '-'], {
-          cwd: root,
-          input: guidance,
-        });
-      }
-      const labels = ['--remove-label', question.labels.needsHuman];
-      if (choice === GIVE_UP) {
-        labels.push('--add-label', question.labels.skip);
-      }
-      for (const [kind, number] of threads) {
-        await options.gh([kind, 'edit', String(number), ...repo, ...labels], { cwd: root });
-      }
-    };
-
-    const answer = async (ctx: ExtensionContext) => {
-      const { client, root } = await connect(ctx);
-      const passed = new Set<number>();
-      for (;;) {
-        const question = (await fresh(client, root)).find((item) => !passed.has(item.issue));
-        if (question === undefined) {
-          if (passed.size === 0) {
-            ctx.ui.notify('next-issue: no questions waiting', 'info');
-          }
-          return;
-        }
-        passed.add(question.issue);
-        const choice = await ctx.ui.select(
-          `#${question.issue} ${question.title}\n\n${question.reason || 'No reason given.'}`,
-          [RETRY, GUIDE, GIVE_UP],
-        );
-        if (choice === undefined) {
-          return;
-        }
-        let guidance = '';
-        if (choice === GUIDE) {
-          guidance = (await ctx.ui.editor(`Guidance for #${question.issue}`))?.trim() ?? '';
-          if (guidance === '') {
-            return;
-          }
-        }
-        await reply(root, question, choice, guidance);
-        ctx.ui.notify(
-          `next-issue: #${question.issue} ${choice === GIVE_UP ? 'given up' : 'will be retried'}`,
-          'info',
-        );
-      }
-    };
-
     pi.registerCommand('next-issue', {
       description:
         'Start or stop working through the GitHub issues of this repository, or answer the waiting questions with "answer"',
       getArgumentCompletions: (prefix) =>
         'answer'.startsWith(prefix) ? [{ value: 'answer', label: 'answer' }] : null,
       handler: async (args, ctx) => {
-        if (args.trim() === 'answer') {
-          try {
-            await answer(ctx);
-          } catch (error) {
-            ctx.ui.notify(`next-issue cannot answer: ${errorText(error)}`, 'error');
-          }
-          return;
-        }
+        const answering = args.trim() === 'answer';
         try {
           const { client, root, progress } = await connect(ctx);
-          if (going(progress)) {
-            client.send({ type: 'stop', root });
+          if (answering) {
+            await answerAll(ctx.ui, options.gh, client, root);
           } else {
-            client.send({ type: 'start', root, merge: true });
+            toggle(client, root, progress);
           }
         } catch (error) {
-          ctx.ui.notify(`next-issue cannot start: ${errorText(error)}`, 'error');
+          const note = cannotNote(answering ? 'answer' : 'start', errorText(error));
+          ctx.ui.notify(note.text, note.level);
         }
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravshansbox/pi-next-issue",
-  "version": "2.21.1",
+  "version": "3.0.0",
   "description": "Pi extension that works through GitHub issues with the next-issue worker",
   "license": "MIT",
   "type": "module",

package/src/answer.ts

@@ -0,0 +1,89 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { RunOptions } from './exec.ts';
+import type { Question } from './protocol.ts';
+import { fresh } from './requests.ts';
+import type { WorkerClient } from './worker.ts';
+
+export type Gh = (args: string[], options: RunOptions) => Promise<string>;
+
+const RETRY = 'Retry';
+const GUIDE = 'Retry with guidance';
+const GIVE_UP = 'Give up';
+
+type Answer = { choice: string; guidance: string };
+
+function threadsOf(question: Question): Array<[string, number]> {
+  const issue: [string, number] = ['issue', question.issue];
+  return question.pr === undefined ? [issue] : [issue, ['pr', question.pr]];
+}
+
+function promptOf(question: Question): string {
+  return `#${question.issue} ${question.title}\n\n${question.reason || 'No reason given.'}`;
+}
+
+function answeredOf(question: Question, choice: string): string {
+  return `next-issue: #${question.issue} ${choice === GIVE_UP ? 'given up' : 'will be retried'}`;
+}
+
+function labelsOf(question: Question, choice: string): string[] {
+  const remove = ['--remove-label', question.labels.needsHuman];
+  return choice === GIVE_UP ? [...remove, '--add-label', question.labels.skip] : remove;
+}
+
+async function reply(
+  gh: Gh,
+  root: string,
+  question: Question,
+  { choice, guidance }: Answer,
+): Promise<void> {
+  const threads = threadsOf(question);
+  const repo = ['--repo', question.repo];
+  if (choice === GUIDE) {
+    const [kind, number] = threads.at(-1)!;
+    await gh([kind, 'comment', String(number), ...repo, '--body-file', '-'], {
+      cwd: root,
+      input: guidance,
+    });
+  }
+  const labels = labelsOf(question, choice);
+  for (const [kind, number] of threads) {
+    await gh([kind, 'edit', String(number), ...repo, ...labels], { cwd: root });
+  }
+}
+
+async function ask(ui: ExtensionContext['ui'], question: Question): Promise<Answer | undefined> {
+  const choice = await ui.select(promptOf(question), [RETRY, GUIDE, GIVE_UP]);
+  if (choice === undefined) {
+    return undefined;
+  }
+  if (choice !== GUIDE) {
+    return { choice, guidance: '' };
+  }
+  const guidance = (await ui.editor(`Guidance for #${question.issue}`))?.trim() ?? '';
+  return guidance === '' ? undefined : { choice, guidance };
+}
+
+export async function answerAll(
+  ui: ExtensionContext['ui'],
+  gh: Gh,
+  client: WorkerClient,
+  root: string,
+): Promise<void> {
+  const passed = new Set<number>();
+  for (;;) {
+    const question = (await fresh(client, root)).find((item) => !passed.has(item.issue));
+    if (question === undefined) {
+      if (passed.size === 0) {
+        ui.notify('next-issue: no questions waiting', 'info');
+      }
+      return;
+    }
+    passed.add(question.issue);
+    const answer = await ask(ui, question);
+    if (answer === undefined) {
+      return;
+    }
+    await reply(gh, root, question, answer);
+    ui.notify(answeredOf(question, answer.choice), 'info');
+  }
+}

package/src/clients.ts

@@ -0,0 +1,14 @@
+import type { WorkerClient } from './worker.ts';
+
+const KEY = Symbol.for('pi-next-issue');
+
+export function shared(create: (root: string) => WorkerClient, root: string): WorkerClient {
+  const store = globalThis as Record<symbol, Map<string, WorkerClient> | undefined>;
+  const clients = (store[KEY] ??= new Map());
+  let client = clients.get(root);
+  if (client === undefined) {
+    client = create(root);
+    clients.set(root, client);
+  }
+  return client;
+}

package/src/errors.ts

@@ -0,0 +1,3 @@
+export function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/exec.ts

@@ -1,15 +1,14 @@
 import { spawn } from 'node:child_process';
 
-export type Result = { code: number; stdout: string; stderr: string };
+type Result = { code: number; stdout: string; stderr: string };
 
-export type RunOptions = { cwd: string; input?: string; signal?: AbortSignal };
+export type RunOptions = { cwd: string; input?: string };
 
-export function run(command: string, args: string[], options: RunOptions): Promise<Result> {
+function run(command: string, args: string[], options: RunOptions): Promise<Result> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       cwd: options.cwd,
       stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
-      ...(options.signal === undefined ? {} : { signal: options.signal }),
     });
     let stdout = '';
     let stderr = '';

package/src/protocol.ts

@@ -0,0 +1,93 @@
+export type RunStatus = 'running' | 'stopping' | 'finished' | 'stopped' | 'failed';
+
+export type Handled = { issue: number; outcome: 'done' | 'needs-human' | 'error' };
+
+export type IssueProgress = {
+  issue: number;
+  title?: string;
+  stage?: string;
+  tools: number;
+  lastTool?: string;
+  startedAt?: number;
+};
+
+export type Progress = {
+  status: RunStatus;
+  issues: IssueProgress[];
+  handled: Handled[];
+  open?: number;
+  error?: string;
+};
+
+export type Question = {
+  issue: number;
+  title: string;
+  reason: string;
+  url: string;
+  repo: string;
+  pr?: number;
+  labels: { needsHuman: string; skip: string };
+};
+
+export type ClientMessage =
+  | { type: 'hello'; version: string }
+  | { type: 'start'; root: string; merge: boolean }
+  | { type: 'stop'; root: string }
+  | { type: 'questions'; root: string; id?: string };
+
+export type WorkerMessage =
+  | { type: 'hello'; version: string }
+  | { type: 'runs'; runs: Record<string, Progress> }
+  | { type: 'questions'; root: string; questions: Question[]; id?: string }
+  | { type: 'questions-error'; root: string; message: string; id?: string }
+  | { type: 'error'; root: string; message: string };
+
+export function going(progress: Progress | undefined): progress is Progress {
+  return progress?.status === 'running' || progress?.status === 'stopping';
+}
+
+export function isNewer(candidate: string, current: string): boolean {
+  const { core: left, prerelease: leftPrerelease } = parseVersion(candidate);
+  const { core: right, prerelease: rightPrerelease } = parseVersion(current);
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) {
+      return difference > 0;
+    }
+  }
+  return isNewerPrerelease(leftPrerelease, rightPrerelease);
+}
+
+function isNewerPrerelease(left: string[], right: string[]): boolean {
+  if (left.length === 0 || right.length === 0) {
+    return left.length === 0 && right.length > 0;
+  }
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const leftPart = left[index];
+    const rightPart = right[index];
+    if (leftPart === undefined || rightPart === undefined) {
+      return rightPart === undefined;
+    }
+    if (leftPart === rightPart) {
+      continue;
+    }
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      return Number(leftPart) > Number(rightPart);
+    }
+    if (leftNumeric || rightNumeric) {
+      return rightNumeric;
+    }
+    return leftPart > rightPart;
+  }
+  return false;
+}
+
+function parseVersion(version: string): { core: number[]; prerelease: string[] } {
+  const [core = '', ...rest] = version.replace(/\+.*$/, '').split('-');
+  return {
+    core: core.split('.').map(Number),
+    prerelease: rest.length > 0 ? rest.join('-').split('.') : [],
+  };
+}

package/src/requests.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+import { going, type Question } from './protocol.ts';
+import { CLOSED, type WorkerClient } from './worker.ts';
+
+export function accepted(
+  client: WorkerClient,
+  root: string,
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const finish = (error?: Error) => {
+      stop();
+      signal?.removeEventListener('abort', abort);
+      if (error === undefined) {
+        resolve();
+      } else {
+        reject(error);
+      }
+    };
+    const abort = () => finish(new Error('next_issue_start was cancelled'));
+    const stop = client.subscribe((event) => {
+      if (event.type === 'error' && event.root === root) {
+        finish(new Error(event.message));
+      } else if (event.type === 'closed') {
+        finish(new Error(CLOSED));
+      } else if (event.type === 'runs' && going(event.runs[root])) {
+        finish();
+      }
+    });
+    if (signal?.aborted) {
+      abort();
+    } else {
+      signal?.addEventListener('abort', abort, { once: true });
+    }
+  });
+}
+
+export function fresh(client: WorkerClient, root: string): Promise<Question[]> {
+  return new Promise<Question[]>((resolve, reject) => {
+    const id = randomUUID();
+    const ours = (event: { root: string; id?: string }) => event.root === root && event.id === id;
+    const stop = client.subscribe((event) => {
+      if (event.type === 'closed') {
+        stop();
+        reject(new Error(CLOSED));
+      } else if (event.type === 'questions' && ours(event)) {
+        stop();
+        resolve(event.questions);
+      } else if (event.type === 'questions-error' && ours(event)) {
+        stop();
+        reject(new Error(event.message));
+      }
+    });
+    client.send({ type: 'questions', root, id });
+  });
+}

package/src/run.ts

@@ -0,0 +1,51 @@
+import { going, type Progress } from './protocol.ts';
+import { accepted } from './requests.ts';
+import { formatStatus, handledNote } from './status.ts';
+import type { WorkerClient } from './worker.ts';
+
+function report<Details>(text: string, details: Details) {
+  return { content: [{ type: 'text' as const, text }], details };
+}
+
+export async function statusOf(client: WorkerClient, root: string) {
+  await client.attach();
+  if (!client.connected) {
+    return report('no worker is running', { root });
+  }
+  const progress = client.runs[root];
+  if (progress === undefined) {
+    return report(`no run of ${root}`, { root });
+  }
+  const lines = [formatStatus(progress, Date.now()), ...progress.handled.map(handledNote)];
+  return report(lines.join('\n'), { root });
+}
+
+function sendStart(client: WorkerClient, root: string): void {
+  client.send({ type: 'start', root, merge: true });
+}
+
+export async function startRun(
+  client: WorkerClient,
+  root: string,
+  progress: Progress | undefined,
+  signal: AbortSignal | undefined,
+) {
+  if (going(progress)) {
+    return report(
+      `A run of ${root} is going already, so nothing started: ${formatStatus(progress, Date.now())}. It picks up new issues by itself.`,
+      { started: false, root },
+    );
+  }
+  const accepting = accepted(client, root, signal);
+  sendStart(client, root);
+  await accepting;
+  return report(`Started a next-issue run of ${root}.`, { started: true, root });
+}
+
+export function toggle(client: WorkerClient, root: string, progress: Progress | undefined): void {
+  if (going(progress)) {
+    client.send({ type: 'stop', root });
+  } else {
+    sendStart(client, root);
+  }
+}

package/src/spawn-worker.ts

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function workerArgs(version: string): string[] {
+  return ['-y', `next-issue@${version === '0.0.0' ? 'latest' : version}`, 'serve'];
+}
+
+export function workerPaths(root: string): { socketPath: string; logPath: string } {
+  const stateDir = join(root, '.next-issue');
+  return {
+    socketPath: join(stateDir, 'worker.sock'),
+    logPath: join(stateDir, 'worker.log'),
+  };
+}
+
+export function spawnWorker(root: string, version: string): void {
+  const { logPath } = workerPaths(root);
+  mkdirSync(dirname(logPath), { recursive: true });
+  const log = openSync(logPath, 'a');
+  try {
+    const child = spawn('npx', workerArgs(version), {
+      cwd: root,
+      detached: true,
+      stdio: ['ignore', log, log],
+    });
+    child.on('error', () => {});
+    child.unref();
+  } finally {
+    closeSync(log);
+  }
+}

package/src/status.ts

@@ -0,0 +1,97 @@
+import type { Handled, IssueProgress, Progress, Question } from './protocol.ts';
+
+function duration(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  const minutes = Math.floor(seconds / 60);
+  return minutes > 0 ? `${minutes}m${String(seconds % 60).padStart(2, '0')}s` : `${seconds}s`;
+}
+
+const OUTCOME_NOTES = { done: 'done', 'needs-human': 'needs a human', error: 'failed' } as const;
+
+type Outcome = keyof typeof OUTCOME_NOTES;
+
+function outcomes(progress: Progress): string {
+  const count = (outcome: Outcome): number =>
+    progress.handled.filter((item) => item.outcome === outcome).length;
+  return (Object.keys(OUTCOME_NOTES) as Outcome[])
+    .filter((outcome) => outcome === 'done' || count(outcome) > 0)
+    .map((outcome) => `${count(outcome)} ${OUTCOME_NOTES[outcome]}`)
+    .join(', ');
+}
+
+function failedNote(progress: Progress): string {
+  return `failed: ${progress.error ?? 'unknown error'}`;
+}
+
+export function handledNote(item: Handled): string {
+  return `#${item.issue} ${OUTCOME_NOTES[item.outcome]}`;
+}
+
+export type Note = { text: string; level: 'info' | 'warning' | 'error' };
+
+export function statusNote(progress: Progress): Note | undefined {
+  if (progress.status === 'finished' || progress.status === 'stopped') {
+    return { text: `next-issue ${progress.status}`, level: 'info' };
+  }
+  if (progress.status === 'failed') {
+    return { text: `next-issue ${failedNote(progress)}`, level: 'error' };
+  }
+  return undefined;
+}
+
+export function cannotNote(action: 'start' | 'answer', message: string): Note {
+  return { text: `next-issue cannot ${action}: ${message}`, level: 'error' };
+}
+
+export function handledNotes(progress: Progress, from: number): Note[] {
+  return progress.handled.slice(from).map((item) => ({
+    text: `next-issue: ${handledNote(item)}`,
+    level: item.outcome === 'done' ? 'info' : 'warning',
+  }));
+}
+
+export function questionNotes(questions: Question[], known: number[] | undefined): Note[] {
+  if (known === undefined) {
+    return [];
+  }
+  return questions
+    .filter((question) => !known.includes(question.issue))
+    .map((question) => ({
+      text: `next-issue: #${question.issue} has a question: ${question.title}`,
+      level: 'warning',
+    }));
+}
+
+export function formatQuestions(count: number): string {
+  return `${count} ${count === 1 ? 'question' : 'questions'} waiting`;
+}
+
+function issueLine(item: IssueProgress, count: string, now: number): string {
+  const parts = [`#${item.issue}${count}`, item.stage ?? 'prepare', `${item.tools} tools`];
+  if (item.startedAt !== undefined) {
+    parts.push(duration(now - item.startedAt));
+  }
+  return parts.join(' · ');
+}
+
+export function formatStatus(progress: Progress, now: number): string {
+  const running = progress.issues ?? [];
+  switch (progress.status) {
+    case 'running': {
+      if (running.length === 0) {
+        return 'looking for issues';
+      }
+      const count = progress.open === undefined ? '' : `/${progress.open}`;
+      return running.map((item) => issueLine(item, count, now)).join(' | ');
+    }
+    case 'stopping': {
+      const issues = running.map((item) => `#${item.issue}`);
+      return `${issues.length === 0 ? '#?' : issues.join(' ')} · stopping`;
+    }
+    case 'stopped':
+    case 'finished':
+      return `${progress.status}: ${outcomes(progress)}`;
+    case 'failed':
+      return failedNote(progress);
+  }
+}

package/src/worker.ts

@@ -1,58 +1,15 @@
-import { spawn } from 'node:child_process';
-import { closeSync, mkdirSync, openSync } from 'node:fs';
-import { dirname, join } from 'node:path';
 import WebSocket from 'ws';
-
-export type RunStatus = 'running' | 'stopping' | 'finished' | 'stopped' | 'failed';
-
-export type Handled = { issue: number; outcome: 'done' | 'needs-human' | 'error' };
-
-export type IssueProgress = {
-  issue: number;
-  title?: string;
-  stage?: string;
-  tools: number;
-  lastTool?: string;
-  startedAt?: number;
-};
-
-export type Progress = {
-  status: RunStatus;
-  issues: IssueProgress[];
-  handled: Handled[];
-  open?: number;
-  error?: string;
-};
-
-export type Question = {
-  issue: number;
-  title: string;
-  reason: string;
-  url: string;
-  repo: string;
-  pr?: number;
-  labels: { needsHuman: string; skip: string };
-};
-
-export type ClientMessage =
-  | { type: 'hello'; version: string }
-  | { type: 'start'; root: string; merge: boolean }
-  | { type: 'stop'; root: string }
-  | { type: 'questions'; root: string; id?: string };
-
-export type WorkerMessage =
-  | { type: 'hello'; version: string }
-  | { type: 'runs'; runs: Record<string, Progress> }
-  | { type: 'questions'; root: string; questions: Question[]; id?: string }
-  | { type: 'questions-error'; root: string; message: string; id?: string }
-  | { type: 'error'; root: string; message: string };
-
-export type WorkerEvent =
-  | { type: 'runs'; runs: Record<string, Progress> }
-  | { type: 'questions'; root: string; questions: Question[]; id?: string }
-  | { type: 'questions-error'; root: string; message: string; id?: string }
-  | { type: 'error'; root: string; message: string }
-  | { type: 'closed' };
+import { errorText } from './errors.ts';
+import {
+  type ClientMessage,
+  going,
+  isNewer,
+  type Progress,
+  type Question,
+  type WorkerMessage,
+} from './protocol.ts';
+
+export type WorkerEvent = Exclude<WorkerMessage, { type: 'hello' }> | { type: 'closed' };
 
 export type WorkerOptions = {
   socketPath: string;
@@ -66,56 +23,9 @@ const START_TIMEOUT_MS = 120_000;
 const RECONNECT_MS = 5_000;
 const POLL_MS = 200;
 
-export function isNewer(candidate: string, current: string): boolean {
-  const [leftCore = '', ...leftRest] = candidate.replace(/\+.*$/, '').split('-');
-  const [rightCore = '', ...rightRest] = current.replace(/\+.*$/, '').split('-');
-  const left = leftCore.split('.').map(Number);
-  const right = rightCore.split('.').map(Number);
-  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
-    const difference = (left[index] ?? 0) - (right[index] ?? 0);
-    if (difference !== 0) {
-      return difference > 0;
-    }
-  }
-  const leftPrerelease = leftRest.length > 0 ? leftRest.join('-').split('.') : [];
-  const rightPrerelease = rightRest.length > 0 ? rightRest.join('-').split('.') : [];
-  if (leftPrerelease.length === 0 || rightPrerelease.length === 0) {
-    return leftPrerelease.length === 0 && rightPrerelease.length > 0;
-  }
-  for (let index = 0; index < Math.max(leftPrerelease.length, rightPrerelease.length); index += 1) {
-    const leftPart = leftPrerelease[index];
-    const rightPart = rightPrerelease[index];
-    if (leftPart === undefined || rightPart === undefined) {
-      return rightPart === undefined;
-    }
-    if (leftPart === rightPart) {
-      continue;
-    }
-    const leftNumeric = /^\d+$/.test(leftPart);
-    const rightNumeric = /^\d+$/.test(rightPart);
-    if (leftNumeric && rightNumeric) {
-      return Number(leftPart) > Number(rightPart);
-    }
-    if (leftNumeric || rightNumeric) {
-      return rightNumeric;
-    }
-    return leftPart > rightPart;
-  }
-  return false;
-}
-
-export function workerArgs(version: string): string[] {
-  return ['-y', `next-issue@${version === '0.0.0' ? 'latest' : version}`, 'serve'];
-}
-
-export function workerPaths(root: string): { socketPath: string; logPath: string } {
-  return {
-    socketPath: join(root, '.next-issue', 'worker.sock'),
-    logPath: join(root, '.next-issue', 'worker.log'),
-  };
-}
+export const CLOSED = 'the worker closed the connection';
 
-export function checkSocketPath(path: string, platform = process.platform): void {
+function checkSocketPath(path: string, platform = process.platform): void {
   const size = platform === 'linux' ? 108 : 104;
   const length = Buffer.byteLength(path);
   if (length >= size) {
@@ -125,20 +35,11 @@ export function checkSocketPath(path: string, platform = process.platform): void
   }
 }
 
-export function spawnWorker(root: string, version: string): void {
-  const { logPath } = workerPaths(root);
-  mkdirSync(dirname(logPath), { recursive: true });
-  const log = openSync(logPath, 'a');
+function parseMessage(text: string): WorkerMessage | undefined {
   try {
-    const child = spawn('npx', workerArgs(version), {
-      cwd: root,
-      detached: true,
-      stdio: ['ignore', log, log],
-    });
-    child.on('error', () => {});
-    child.unref();
-  } finally {
-    closeSync(log);
+    return JSON.parse(text) as WorkerMessage;
+  } catch {
+    return undefined;
   }
 }
 
@@ -160,6 +61,22 @@ export class WorkerClient {
     this.options = options;
   }
 
+  private get startTimeoutMs(): number {
+    return this.options.startTimeoutMs ?? START_TIMEOUT_MS;
+  }
+
+  private get reconnectMs(): number {
+    return this.options.reconnectMs ?? RECONNECT_MS;
+  }
+
+  private get busy(): boolean {
+    return Object.values(this.runs).some(going);
+  }
+
+  private get outdated(): boolean {
+    return this.workerVersion !== undefined && isNewer(this.options.version, this.workerVersion);
+  }
+
   get connected(): boolean {
     return this.socket?.readyState === WebSocket.OPEN;
   }
@@ -182,22 +99,11 @@ export class WorkerClient {
 
   async ensure(): Promise<void> {
     if (!this.connected) {
-      this.connecting ??= this.start().finally(() => {
-        this.connecting = undefined;
-      });
-      await this.connecting;
+      await this.connect();
     }
-    if (this.workerVersion !== undefined && isNewer(this.options.version, this.workerVersion)) {
-      const busy = Object.values(this.runs).some(
-        (run) => run.status === 'running' || run.status === 'stopping',
-      );
-      if (!busy) {
-        await this.waitForClose();
-        this.connecting ??= this.start().finally(() => {
-          this.connecting = undefined;
-        });
-        await this.connecting;
-      }
+    if (this.outdated && !this.busy) {
+      await this.waitForClose();
+      await this.connect();
     }
   }
 
@@ -210,6 +116,13 @@ export class WorkerClient {
     socket?.terminate();
   }
 
+  private connect(): Promise<void> {
+    this.connecting ??= this.start().finally(() => {
+      this.connecting = undefined;
+    });
+    return this.connecting;
+  }
+
   private async start(): Promise<void> {
     checkSocketPath(this.options.socketPath);
     try {
@@ -218,7 +131,11 @@ export class WorkerClient {
     } catch {
       this.options.spawnWorker(this.options.version);
     }
-    const deadline = Date.now() + (this.options.startTimeoutMs ?? START_TIMEOUT_MS);
+    await this.waitForStart();
+  }
+
+  private async waitForStart(): Promise<void> {
+    const deadline = Date.now() + this.startTimeoutMs;
     for (;;) {
       await delay(POLL_MS);
       try {
@@ -226,9 +143,7 @@ export class WorkerClient {
         return;
       } catch (error) {
         if (Date.now() >= deadline) {
-          throw new Error(
-            `the next-issue worker did not start: ${error instanceof Error ? error.message : String(error)}`,
-          );
+          throw new Error(`the next-issue worker did not start: ${errorText(error)}`);
         }
       }
     }
@@ -244,52 +159,59 @@ export class WorkerClient {
         }
       });
       socket.on('message', (data) => {
-        let message: WorkerMessage;
-        try {
-          message = JSON.parse(String(data)) as WorkerMessage;
-        } catch {
+        const message = parseMessage(String(data));
+        if (message === undefined) {
           return;
         }
-        if (message.type === 'hello') {
-          this.workerVersion = message.version;
-        } else if (message.type === 'runs') {
-          this.runs = message.runs;
-          this.emit({ type: 'runs', runs: message.runs });
-          if (!hello) {
-            hello = true;
-            resolve();
-          }
-        } else if (message.type === 'questions') {
-          this.questions[message.root] = message.questions;
-          this.emit(message);
-        } else if (message.type === 'error' || message.type === 'questions-error') {
-          this.emit(message);
+        this.receive(message);
+        if (message.type === 'runs' && !hello) {
+          hello = true;
+          resolve();
         }
       });
       socket.once('open', () => {
         this.socket = socket;
-        socket.send(JSON.stringify({ type: 'hello', version: this.options.version }));
+        this.send({ type: 'hello', version: this.options.version });
       });
       socket.once('close', () => {
-        if (this.socket === socket) {
-          this.socket = undefined;
-          this.emit({ type: 'closed' });
-          this.scheduleReconnect();
-        }
+        this.release(socket);
         if (!hello) {
-          reject(new Error('the worker closed the connection'));
+          reject(new Error(CLOSED));
         }
       });
     });
   }
 
+  private release(socket: WebSocket): void {
+    if (this.socket !== socket) {
+      return;
+    }
+    this.socket = undefined;
+    this.emit({ type: 'closed' });
+    this.scheduleReconnect();
+  }
+
+  private receive(message: WorkerMessage): void {
+    if (message.type === 'hello') {
+      this.workerVersion = message.version;
+    } else if (message.type === 'runs') {
+      this.runs = message.runs;
+      this.emit(message);
+    } else if (message.type === 'questions') {
+      this.questions[message.root] = message.questions;
+      this.emit(message);
+    } else if (message.type === 'error' || message.type === 'questions-error') {
+      this.emit(message);
+    }
+  }
+
   private waitForClose(): Promise<void> {
     const socket = this.socket;
     if (socket === undefined || socket.readyState === WebSocket.CLOSED) {
       return Promise.resolve();
     }
     return new Promise((resolve) => {
-      const timer = setTimeout(resolve, this.options.startTimeoutMs ?? START_TIMEOUT_MS);
+      const timer = setTimeout(resolve, this.startTimeoutMs);
       socket.once('close', () => {
         clearTimeout(timer);
         resolve();
@@ -306,7 +228,7 @@ export class WorkerClient {
       if (!this.connected && this.connecting === undefined) {
         void this.attach();
       }
-    }, this.options.reconnectMs ?? RECONNECT_MS);
+    }, this.reconnectMs);
     this.reconnectTimer.unref?.();
   }