@ravshansbox/pi-next-issue 5.6.3 → 6.0.1

package/README.md

@@ -12,8 +12,10 @@ It needs `git`, `npx` and an authenticated [`gh`](https://cli.github.com/). It w
 
 Run this in pi, inside a git repository:
 
-- `/next-issue` starts a run of this repository when none is going, and stops the run when one is going. A stop takes effect after the current round, and the issue keeps its saved state, so the next run resumes it.
-- The `next_issue_start` tool lets the model start a run. When no run is going, it starts a run like `/next-issue`. When a run is going, it starts nothing and reports the current run, which picks up new issues by itself. It never stops a run, and it does not ask for confirmation. Its result says whether it started a run.
+- `/next-issue start [flags]` starts a run of this repository when none is going. The flags are those of the `next-issue` CLI: `--once`, `--max <n>`, `--watch`, `--hunt`, `--reset`, `--verbose` and `--quiet`. For example, `/next-issue start --hunt` hunts for bugs and keeps watching, like `next-issue --hunt`. The worker refuses any other argument, or a command such as `init`, and a note says why. When a run is going, a note says so, and nothing starts or restarts.
+- `/next-issue stop` stops the run of this repository. A stop takes effect after the current round, and the issue keeps its saved state, so the next run resumes it. When no run is going, a note says so.
+- `/next-issue` with no argument shows the usage: `start [flags]`, `stop` and `answer`. Pi suggests these as you type after `/next-issue `.
+- The `next_issue_start` tool lets the model start a run. It takes an optional `args` array with the same flags as `/next-issue start`. When no run is going, it starts a run like `/next-issue start`. When a run is going, it starts nothing and reports the current run, which picks up new issues by itself. It never stops a run, and it does not ask for confirmation. Its result says whether it started a run.
 - The `next_issue_status` tool lets the model see the run of this repository. It returns the footer line, then one line per handled issue with its outcome, for example `#190 done`. When the worker has no run of this repository, it returns `no run of <root>`. When no worker is going, it returns `no worker is running` and does not start one. It reports no other repository.
 
 The footer shows each running issue with the number of open issues at the latest fetch, its stage, the number of tool calls and the time spent on it, for example `#12/7 · review 2/5 · 37 tools · 4m12s | #13/7 · implement · 5 tools · 40s`. The open count includes the running issues and open issues the run skips. It leaves out closed issues that the run resumes after their change landed. A stage with a limited number of rounds shows the round and its limit: `review 2/5`, `review fix 2/5`, `checks fix 1/5` or `commit fix 1/10`. Other lines read, for example, `looking for issues`, `finished: 2 done` or `stopped: 1 done, 1 needs a human`. After a run ends, it keeps the last summary. In the terminal, it uses the dim colour of the theme, like the rest of the footer. A note appears when an issue is done, needs a human or fails while pi is open. Pi does not repeat the notes of a run that ended before it opened.
@@ -22,17 +24,17 @@ The footer shows each running issue with the number of open issues at the latest
 
 When an issue waits for a person, with the `needsHuman` label of the [config](../next-issue/README.md), the footer shows the count, for example `2 questions waiting`, and a note appears once for each new question. Neither interrupts what you do. Pi asks the worker for the list when it connects and every minute, and the worker also sends it after each issue of a run. A question answered on GitHub or in another pi leaves the count with the next list.
 
-Run `/next-issue answer` to go through the waiting questions one at a time. Pi suggests `answer` as you type after `/next-issue `. Each shows the issue, the title and the reason of the hand-over. Choose:
+Run `/next-issue answer` to go through the waiting questions one at a time. Each shows the issue, the title and the reason of the hand-over. Choose:
 
 - **Retry**: takes the `needsHuman` label off the issue, so the next run resumes it.
 - **Retry with guidance**: asks for text, posts it as a comment on the issue, where the worker reads it, then takes the `needsHuman` label off.
 - **Give up**: takes the `needsHuman` label off the issue and adds the `skip` label.
 
-Press Escape, or leave the guidance empty, to stop. Pi reads the list again before each question, so it skips a question answered elsewhere in the meantime. The worker sends the repository and the label names with each question, from `next-issue.config.json` and its `remote`. Pi uses `gh` for the comment and the labels.
+Press Escape, or leave the guidance empty, to stop. Pi reads the list again before each question, so it skips a question answered elsewhere in the meantime. The worker sends the repository and the label names with each question, from `.next-issue/config.json` and its `remote`. Pi uses `gh` for the comment and the labels.
 
 ## Create an issue
 
-The package ships the `create-issue` skill. Ask pi to write an issue, ask for a change in a repository with `next-issue.config.json`, or run `/skill:create-issue <problem>`. Pi then:
+The package ships the `create-issue` skill. Ask pi to write an issue, ask for a change in a repository with `.next-issue/config.json`, or run `/skill:create-issue <problem>`. Pi then:
 
 1. restates the problem, reads the code when the problem touches it, and finds the open issues that must be done first;
 2. asks numbered questions until none is open;
@@ -47,7 +49,7 @@ Pi does not implement the issue in that session. The worker does the work. The b
 
 ## Worker
 
-The extension does no work itself. On `/next-issue` or `next_issue_start` it connects to the `next-issue` worker of the repository on the socket file `.next-issue/worker.sock` in the repository. When no worker answers, it starts one in the repository with `npx -y next-issue@<version> serve`, where `<version>` is the version of the extension, or `latest` when the extension runs from a source checkout with version `0.0.0`, in the background, and writes the output of the worker to `.next-issue/worker.log` in the repository. When the path of the socket file is too long for the system, the extension says so and starts nothing.
+The extension does no work itself. On `/next-issue start`, `stop` or `answer`, or `next_issue_start`, it connects to the `next-issue` worker of the repository on the socket file `.next-issue/worker.sock` in the repository. When no worker answers, it starts one in the repository with `npx -y next-issue@<version> serve`, and passes the flags of each start to it, where `<version>` is the version of the extension, or `latest` when the extension runs from a source checkout with version `0.0.0`, in the background, and writes the output of the worker to `.next-issue/worker.log` in the repository. When the path of the socket file is too long for the system, the extension says so and starts nothing.
 
 - Each repository has its own worker. Every pi in a repository shares the worker of that repository and shows its run, whoever started it. A run, restart or upgrade in one repository never affects another.
 - Opening pi does not start a worker. It only shows a run when a worker is going.

package/index.ts

@@ -8,8 +8,9 @@ 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 { requestStart, requestStop, startRun, statusOf } from './src/run.ts';
 import {
+  type Action,
   cannotNote,
   formatQuestions,
   formatStatus,
@@ -31,6 +32,13 @@ const STATUS_KEY = 'next-issue';
 const QUESTIONS_KEY = 'next-issue-questions';
 const RENDER_MS = 1000;
 const QUESTIONS_MS = 60_000;
+const SUBCOMMANDS: Action[] = ['start', 'stop', 'answer'];
+const FLAGS = '--once, --max <n>, --watch, --hunt, --reset, --verbose, --quiet';
+const USAGE = [
+  '/next-issue start [flags]  start a run of this repository, with flags from: ' + FLAGS,
+  '/next-issue stop           stop the run of this repository after the current round',
+  '/next-issue answer         answer the waiting questions',
+].join('\n');
 
 function background(callback: () => void, ms: number): ReturnType<typeof setInterval> {
   const timer = setInterval(callback, ms);
@@ -220,13 +228,18 @@ export function createExtension(options: Options) {
     pi.registerTool({
       name: 'next_issue_start',
       label: 'Start next-issue',
-      description:
-        'Start a next-issue run of the GitHub issues of this repository when none is going. Starts the worker when needed. When a run is going, starts nothing and reports that run, which picks up new issues by itself.',
+      description: `Start a next-issue run of the GitHub issues of this repository when none is going. Starts the worker when needed. When a run is going, starts nothing and reports that run, which picks up new issues by itself. Optional args take the flags ${FLAGS}, for example ["--hunt"] to hunt for bugs and keep watching.`,
       promptSnippet: 'Start a next-issue run of this repository when none is going',
-      parameters: Type.Object({}),
-      async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+      parameters: Type.Object({
+        args: Type.Optional(
+          Type.Array(Type.String(), {
+            description: `Flags for the run, from: ${FLAGS}`,
+          }),
+        ),
+      }),
+      async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         const { client, root, progress } = await connect(ctx);
-        return startRun(client, root, progress, signal);
+        return startRun(client, root, progress, params.args ?? [], signal);
       },
     });
 
@@ -244,22 +257,33 @@ export function createExtension(options: Options) {
     });
 
     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,
+      description: `"start [flags]" starts working through the GitHub issues of this repository, with flags from ${FLAGS}. "stop" stops the run. "answer" answers the waiting questions`,
+      getArgumentCompletions: (prefix) => {
+        const matches = SUBCOMMANDS.filter((name) => name.startsWith(prefix));
+        return matches.length === 0 ? null : matches.map((name) => ({ value: name, label: name }));
+      },
       handler: async (args, ctx) => {
-        const answering = args.trim() === 'answer';
+        const [subcommand, ...flags] = args.trim().split(/\s+/).filter(Boolean);
+        if (subcommand === undefined || !SUBCOMMANDS.includes(subcommand as Action)) {
+          ctx.ui.notify(USAGE, 'info');
+          return;
+        }
+        const notify = (note: Note | undefined) => {
+          if (note !== undefined) {
+            ctx.ui.notify(note.text, note.level);
+          }
+        };
         try {
           const { client, root, progress } = await connect(ctx);
-          if (answering) {
+          if (subcommand === 'answer') {
             await answerAll(ctx.ui, options.gh, client, root);
+          } else if (subcommand === 'stop') {
+            notify(requestStop(client, root, progress));
           } else {
-            toggle(client, root, progress);
+            notify(requestStart(client, root, progress, flags));
           }
         } catch (error) {
-          const note = cannotNote(answering ? 'answer' : 'start', errorText(error));
-          ctx.ui.notify(note.text, note.level);
+          notify(cannotNote(subcommand as Action, errorText(error)));
         }
       },
     });

package/package.json

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

package/skills/create-issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-issue
-description: Turn a problem into a clear GitHub issue that the next-issue worker can claim. Use when the user wants to write, file or create an issue, or asks for a change to the code of a repository that has `next-issue.config.json`.
+description: Turn a problem into a clear GitHub issue that the next-issue worker can claim. Use when the user wants to write, file or create an issue, or asks for a change to the code of a repository that has `.next-issue/config.json`.
 ---
 
 # Create an issue

package/src/protocol.ts

@@ -30,7 +30,7 @@ export type Question = {
 
 export type ClientMessage =
   | { type: 'hello'; version: string }
-  | { type: 'start'; root: string }
+  | { type: 'start'; root: string; args?: string[] }
   | { type: 'stop'; root: string }
   | { type: 'questions'; root: string; id?: string };
 

package/src/run.ts

@@ -1,6 +1,6 @@
 import { going, type Progress } from './protocol.ts';
 import { accepted } from './requests.ts';
-import { formatStatus, handledNote } from './status.ts';
+import { formatStatus, handledNote, type Note } from './status.ts';
 import type { WorkerClient } from './worker.ts';
 
 function report<Details>(text: string, details: Details) {
@@ -20,32 +20,51 @@ export async function statusOf(client: WorkerClient, root: string) {
   return report(lines.join('\n'), { root });
 }
 
-function sendStart(client: WorkerClient, root: string): void {
-  client.send({ type: 'start', root });
+function sendStart(client: WorkerClient, root: string, args: string[]): void {
+  client.send(args.length === 0 ? { type: 'start', root } : { type: 'start', root, args });
+}
+
+function goingAlready(root: string, progress: Progress): string {
+  return `A run of ${root} is going already, so nothing started: ${formatStatus(progress, Date.now())}. It picks up new issues by itself.`;
 }
 
 export async function startRun(
   client: WorkerClient,
   root: string,
   progress: Progress | undefined,
+  args: string[],
   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 },
-    );
+    return report(goingAlready(root, progress), { started: false, root });
   }
   const accepting = accepted(client, root, signal);
-  sendStart(client, root);
+  sendStart(client, root, args);
   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 {
+export function requestStart(
+  client: WorkerClient,
+  root: string,
+  progress: Progress | undefined,
+  args: string[],
+): Note | undefined {
   if (going(progress)) {
-    client.send({ type: 'stop', root });
-  } else {
-    sendStart(client, root);
+    return { text: goingAlready(root, progress), level: 'info' };
+  }
+  sendStart(client, root, args);
+  return undefined;
+}
+
+export function requestStop(
+  client: WorkerClient,
+  root: string,
+  progress: Progress | undefined,
+): Note | undefined {
+  if (!going(progress)) {
+    return { text: `No run of ${root} is going.`, level: 'info' };
   }
+  client.send({ type: 'stop', root });
+  return undefined;
 }

package/src/status.ts

@@ -39,7 +39,9 @@ export function statusNote(progress: Progress): Note | undefined {
   return undefined;
 }
 
-export function cannotNote(action: 'start' | 'answer', message: string): Note {
+export type Action = 'start' | 'stop' | 'answer';
+
+export function cannotNote(action: Action, message: string): Note {
   return { text: `next-issue cannot ${action}: ${message}`, level: 'error' };
 }