@boxxy/cli 0.0.0 → 0.1.3

package/README.md

@@ -5,17 +5,50 @@
     <a href="https://www.npmjs.com/package/@boxxy/cli"><img src="https://img.shields.io/npm/v/@boxxy/cli" alt="npm version"></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   </p>
-</div>
 
-The boxxy command line, which files tasks and starts the server.
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
 
-This version is a placeholder that exports only its package name, as `packageName`. The
-[boxxy README](https://github.com/zgeoff/boxxy#workspace) lists the workspace's packages.
+The `boxxy` command: one command for each procedure of the boxxy API, the close-out command that an
+agent runs inside a session, and the two hooks that bind a session and link its pull request.
 
 ## Install
 
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/cli) with Bun:
+
 ```bash
 bun add @boxxy/cli
 ```
 
 The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Usage
+
+Set the address of the server, then run a command:
+
+```bash
+BOXXY_URL=<server_url> boxxy item list --state ready
+```
+
+- `<server_url>` is the origin of the server's owner listener. In a worker session an atc auth
+  profile sets it to the broker's address.
+
+`boxxy --help` prints the usage line of every command. A command prints the server's answer as JSON
+and exits 0, exits 1 on a refusal or an error, and exits 2 on a wrong command line.
+
+## Features
+
+- `boxxy item`, `boxxy relation`, `boxxy defer`, `boxxy expedite`, `boxxy status` and the other
+  owner commands.
+- `boxxy attempt current`, `boxxy attempt evidence` and `boxxy attempt close-out`, for an agent in a
+  session.
+- `boxxy hook session-start` and `boxxy hook post-tool-use`, which the plug-in in `hook-plugin/`
+  runs.
+- `runCLI`, which runs one command line against dependencies the caller passes in.
+
+## Documentation
+
+[The CLI and the hooks](../../docs/design/boxxy/v1-cli.md) lists the environment, the exit codes and
+what each hook does.

package/dist/cli/build-answer-result.d.ts

@@ -0,0 +1,4 @@
+import type { CLIResult } from '../types.ts';
+export declare function buildAnswerResult(answer: unknown): CLIResult;
+export declare function buildTextResult(text: string, exitCode?: number): CLIResult;
+export declare function buildErrorResult(message: string, exitCode?: number): CLIResult;

package/dist/cli/format-help.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare function formatHelp(commands: readonly Command[], prefix: readonly string[]): string;

package/dist/cli/make-answer-run.d.ts

@@ -0,0 +1,2 @@
+import type { Command, CommandCall } from '../types.ts';
+export declare function makeAnswerRun(send: (call: CommandCall) => Promise<unknown>): Command['run'];

package/dist/cli/parse-command-args.d.ts

@@ -0,0 +1,2 @@
+import type { Command, CommandArgs } from '../types.ts';
+export declare function parseCommandArgs(command: Command, line: readonly string[]): CommandArgs;

package/dist/cli/pick-command.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from '../types.ts';
+export type PickedCommand = {
+    readonly kind: 'command';
+    readonly command: Command;
+    readonly words: readonly string[];
+} | {
+    readonly kind: 'help';
+    readonly prefix: readonly string[];
+} | {
+    readonly kind: 'unknown';
+    readonly word: string;
+};
+export declare function pickCommand(commands: readonly Command[], argv: readonly string[]): PickedCommand;

package/dist/cli/run-cli.d.ts

@@ -0,0 +1,2 @@
+import type { CLIDeps, CLIResult } from '../types.ts';
+export declare function runCLI(deps: CLIDeps, argv: readonly string[]): Promise<CLIResult>;

package/dist/cli/usage-error.d.ts

@@ -0,0 +1,3 @@
+export declare class UsageError extends Error {
+    readonly name = "UsageError";
+}

package/dist/commands/all-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const allCommands: readonly Command[];

package/dist/commands/attempt-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const attemptCommands: readonly Command[];

package/dist/commands/describe-close-out-problem.d.ts

@@ -0,0 +1,2 @@
+import type { CloseOutProblem } from '@boxxy/model';
+export declare function describeCloseOutProblem(problem: CloseOutProblem): string;

package/dist/commands/hook-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const hookCommands: readonly Command[];

package/dist/commands/item-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const itemCommands: readonly Command[];

package/dist/commands/parse-criterion-flag.d.ts

@@ -0,0 +1,4 @@
+export declare function parseCriterionFlag(entry: string): {
+    id?: string;
+    text: string;
+};

package/dist/commands/plan-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const planCommands: readonly Command[];

package/dist/commands/relation-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const relationCommands: readonly Command[];

package/dist/commands/report-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const reportCommands: readonly Command[];

package/dist/commands/runner-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../types.ts';
+export declare const runnerCommands: readonly Command[];

package/dist/constants.d.ts

@@ -0,0 +1,17 @@
+export declare const exitCodes: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly retryLater: 2;
+};
+export declare const callerWait: {
+    readonly tries: 6;
+    readonly delayMs: 5000;
+};
+export declare const envNames: {
+    readonly url: 'BOXXY_URL';
+    readonly skillsURL: 'BOXXY_SKILLS_URL';
+};
+export declare const defaultSkillsURL = "https://github.com";
+export declare const skillsRepoFolder = "skills";
+export declare const workspaceSkillsFolder = ".claude/skills";

package/dist/create-client.d.ts

@@ -0,0 +1,3 @@
+import type { BoxxyClient } from '@boxxy/contract';
+import type { CLIDeps } from './types.ts';
+export declare function createClient(deps: CLIDeps): BoxxyClient;

package/dist/hooks/install-skills.d.ts

@@ -0,0 +1,14 @@
+import type { CLIDeps } from '../types.ts';
+interface SkillsPin {
+    readonly source: string;
+    readonly ref: string;
+}
+export interface InstallSkillsInput {
+    readonly pin: SkillsPin | null;
+    readonly names: readonly string[];
+    readonly workspace: string;
+    readonly baseURL: string;
+    readonly runGit: CLIDeps['runGit'];
+}
+export declare function installSkills(input: InstallSkillsInput): Promise<string[]>;
+export {};

package/dist/hooks/parse-hook-payload.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare const sessionStartPayloadSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    cwd: z.ZodString;
+}, z.core.$strip>;
+export declare const postToolUsePayloadSchema: z.ZodObject<{
+    tool_name: z.ZodString;
+    tool_input: z.ZodOptional<z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    tool_response: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export type PostToolUsePayload = z.infer<typeof postToolUsePayloadSchema>;
+export declare function parseHookPayload<Schema extends z.ZodType>(schema: Schema, text: string): z.output<Schema>;

package/dist/hooks/pick-pull-request-url.d.ts

@@ -0,0 +1,2 @@
+import type { PostToolUsePayload } from './parse-hook-payload.ts';
+export declare function pickPullRequestURL(payload: PostToolUsePayload): string | null;

package/dist/hooks/run-post-tool-use-hook.d.ts

@@ -0,0 +1,2 @@
+import type { CLIResult, CommandCall } from '../types.ts';
+export declare function runPostToolUseHook(call: CommandCall): Promise<CLIResult>;

package/dist/hooks/run-session-start-hook.d.ts

@@ -0,0 +1,2 @@
+import type { CLIResult, CommandCall } from '../types.ts';
+export declare function runSessionStartHook(call: CommandCall): Promise<CLIResult>;

package/dist/hooks/wait-for-attempt.d.ts

@@ -0,0 +1,6 @@
+import type { BoxxyClient } from '@boxxy/contract';
+import type { CLIDeps } from '../types.ts';
+export type CurrentAttempt = Extract<Awaited<ReturnType<BoxxyClient['attempt']['current']>>, {
+    kind: 'attempt';
+}>;
+export declare function waitForAttempt(client: BoxxyClient, deps: Pick<CLIDeps, 'sleep'>): Promise<CurrentAttempt | null>;

package/dist/index.d.ts

@@ -1 +1,3 @@
-export { packageName } from './package-name.ts';
+export { runCLI } from './cli/run-cli.ts';
+export { runGit } from './run-git.ts';
+export type { CLIDeps, CLIResult, GitResult } from './types.ts';

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/run-git.d.ts

@@ -0,0 +1,2 @@
+import type { GitResult } from './types.ts';
+export declare function runGit(args: readonly string[], folder?: string): Promise<GitResult>;

package/dist/test-utils/build-mock-cli-deps.d.ts

@@ -0,0 +1,2 @@
+import type { CLIDeps } from '../types.ts';
+export declare function buildMockCLIDeps(env: CLIDeps['env']): CLIDeps;

package/dist/test-utils/create-skills-repo.d.ts

@@ -0,0 +1,10 @@
+export interface SkillsRepoInput {
+    readonly folder: string;
+    readonly skills: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+export interface SkillsRepo {
+    readonly baseURL: string;
+    readonly source: string;
+    readonly ref: string;
+}
+export declare function createSkillsRepo(input: SkillsRepoInput): Promise<SkillsRepo>;

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+import type { ParseArgsOptionsConfig } from 'node:util';
+import type { BoxxyClient, ProcedureName } from '@boxxy/contract';
+export interface GitResult {
+    readonly exitCode: number;
+    readonly output: string;
+}
+export interface CLIDeps {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly send?: (request: Request) => Promise<Response>;
+    readonly readStdin: () => Promise<string>;
+    readonly readFile: (path: string) => Promise<string>;
+    readonly runGit: (args: readonly string[], folder?: string) => Promise<GitResult>;
+    readonly sleep: (durationMs: number) => Promise<void>;
+    readonly now: () => number;
+}
+export interface CLIResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandArgs {
+    positional: (index: number, label: string) => string;
+    positionalsFrom: (index: number, label: string) => string[];
+    string: (name: string) => string | undefined;
+    requireString: (name: string) => string;
+    strings: (name: string) => string[];
+    integer: (name: string) => number | undefined;
+    oneOf: <Choice extends string>(name: string, choices: readonly Choice[]) => Choice | undefined;
+    requireOneOf: <Choice extends string>(name: string, choices: readonly Choice[]) => Choice;
+}
+export interface CommandCall {
+    readonly client: BoxxyClient;
+    readonly args: CommandArgs;
+    readonly deps: CLIDeps;
+}
+export interface Command {
+    readonly path: readonly string[];
+    readonly procedure: ProcedureName;
+    readonly summary: string;
+    readonly options: ParseArgsOptionsConfig;
+    readonly run: (call: CommandCall) => Promise<CLIResult>;
+}

package/hook-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "boxxy-hooks",
+  "description": "Binds a boxxy agent session to its attempt, and links the pull request that the agent opens"
+}

package/hook-plugin/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [{ "type": "command", "command": "boxxy hook session-start" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "boxxy hook post-tool-use" }]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/cli",
-  "version": "0.0.0",
+  "version": "0.1.3",
   "description": "The boxxy command line",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/apps/cli#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -10,9 +10,14 @@
     "url": "git+https://github.com/zgeoff/boxxy.git",
     "directory": "apps/cli"
   },
+  "bin": {
+    "boxxy": "./src/main.ts"
+  },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/test-utils",
+    "hook-plugin",
     "dist"
   ],
   "type": "module",
@@ -20,7 +25,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -29,6 +35,13 @@
     "build": "rm -rf dist && tsrs -p tsconfig.build.json",
     "typecheck": "tsrs --noEmit"
   },
+  "dependencies": {
+    "@boxxy/contract": "0.1.3",
+    "@boxxy/model": "0.1.3",
+    "@orpc/client": "2.0.0-beta.50",
+    "ts-pattern": "5.9.2",
+    "zod": "4.6.7"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

package/src/cli/build-answer-result.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { exitCodes } from '../constants.ts';
+import type { CLIResult } from '../types.ts';
+
+// the answers that mean the server did not do what the command asked
+const refusalSchema = z.object({ kind: z.enum(['refused', 'rejected', 'fault']) });
+
+// The result of a command that prints the server's answer as JSON. A refusal prints the same
+// text and exits with 1, so a script can branch on the exit code.
+export function buildAnswerResult(answer: unknown): CLIResult {
+  return {
+    exitCode: refusalSchema.safeParse(answer).success ? exitCodes.failed : exitCodes.ok,
+    stdout: `${JSON.stringify(answer, null, 2)}\n`,
+    stderr: '',
+  };
+}
+
+export function buildTextResult(text: string, exitCode: number = exitCodes.ok): CLIResult {
+  return { exitCode, stdout: text === '' ? '' : `${text}\n`, stderr: '' };
+}
+
+export function buildErrorResult(message: string, exitCode: number = exitCodes.failed): CLIResult {
+  return { exitCode, stdout: '', stderr: `${message}\n` };
+}

package/src/cli/format-help.ts

@@ -0,0 +1,19 @@
+import { access } from '@boxxy/contract';
+import { envNames } from '../constants.ts';
+import type { Command } from '../types.ts';
+
+// The usage line and the summary of each command that starts with the prefix. The usage line is
+// the one the contract's access table holds.
+export function formatHelp(commands: readonly Command[], prefix: readonly string[]): string {
+  const lines = commands
+    .filter((command) => prefix.every((word, index) => command.path[index] === word))
+    .map((command) => `${access[command.procedure].cli}\n    ${command.summary}`);
+
+  return [
+    'usage: boxxy <command> [flags]',
+    '',
+    ...lines,
+    '',
+    `${envNames.url} is the address of the boxxy server.`,
+  ].join('\n');
+}

package/src/cli/make-answer-run.ts

@@ -0,0 +1,11 @@
+import type { Command, CommandCall } from '../types.ts';
+import { buildAnswerResult } from './build-answer-result.ts';
+
+// The `run` of a command that sends one call and prints the server's answer as JSON.
+export function makeAnswerRun(send: (call: CommandCall) => Promise<unknown>): Command['run'] {
+  return async (call) => {
+    const answer = await send(call);
+
+    return buildAnswerResult(answer);
+  };
+}

package/src/cli/parse-command-args.ts

@@ -0,0 +1,91 @@
+import { parseArgs } from 'node:util';
+import type { Command, CommandArgs } from '../types.ts';
+import { UsageError } from './usage-error.ts';
+
+// Reads the words after the command's name through the command's option table. An unknown flag, a
+// flag with no value or a missing word throws a usage error.
+export function parseCommandArgs(command: Command, line: readonly string[]): CommandArgs {
+  const parsed = parseLine(command, line);
+  const values: Readonly<Record<string, unknown>> = parsed.values;
+  const positionals = parsed.positionals;
+
+  const readStrings = (name: string): string[] => {
+    const value = values[name];
+
+    if (typeof value === 'string') {
+      return [value];
+    }
+
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    return value.filter((entry: unknown): entry is string => typeof entry === 'string');
+  };
+
+  const readString = (name: string): string | undefined => readStrings(name)[0];
+
+  const readOneOf = <Choice extends string>(
+    name: string,
+    choices: readonly Choice[],
+  ): Choice | undefined => {
+    const value = readString(name);
+    const choice = choices.find((candidate) => candidate === value);
+
+    if (value !== undefined && choice === undefined) {
+      throw new UsageError(`--${name} takes one of: ${choices.join(', ')}`);
+    }
+
+    return choice;
+  };
+
+  return {
+    positional: (index, label) => positionals[index] ?? failMissingWord(label),
+    positionalsFrom: (index, label) => {
+      const rest = positionals.slice(index);
+
+      return rest.length === 0 ? failMissingWord(label) : rest;
+    },
+    string: readString,
+    requireString: (name) => readString(name) ?? failMissingFlag(name),
+    strings: readStrings,
+    integer: (name) => {
+      const value = readString(name);
+
+      if (value === undefined) {
+        return value;
+      }
+
+      if (!/^\d+$/u.test(value)) {
+        throw new UsageError(`--${name} takes a whole number`);
+      }
+
+      return Number(value);
+    },
+    oneOf: readOneOf,
+    requireOneOf: (name, choices) => readOneOf(name, choices) ?? failMissingFlag(name),
+  };
+}
+
+function parseLine(command: Command, line: readonly string[]) {
+  try {
+    return parseArgs({
+      args: [...line],
+      options: command.options,
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    throw new UsageError(message);
+  }
+}
+
+function failMissingWord(label: string): never {
+  throw new UsageError(`missing <${label}>`);
+}
+
+function failMissingFlag(name: string): never {
+  throw new UsageError(`missing --${name}`);
+}

package/src/cli/pick-command.ts

@@ -0,0 +1,44 @@
+import type { Command } from '../types.ts';
+
+export type PickedCommand =
+  | { readonly kind: 'command'; readonly command: Command; readonly words: readonly string[] }
+
+  // the words name no command, or ask for help; `prefix` is the part that names a group
+  | { readonly kind: 'help'; readonly prefix: readonly string[] }
+  | { readonly kind: 'unknown'; readonly word: string };
+
+const helpWords = new Set(['help', '--help', '-h']);
+
+// Finds the command that the command line starts with. The rest of the line is its flags and
+// words.
+export function pickCommand(commands: readonly Command[], argv: readonly string[]): PickedCommand {
+  const [first] = argv;
+
+  if (first === undefined || helpWords.has(first)) {
+    return { kind: 'help', prefix: [] };
+  }
+
+  const command = commands.find((candidate) =>
+    candidate.path.every((word, index) => argv[index] === word),
+  );
+
+  if (command === undefined) {
+    return pickGroup(commands, argv);
+  }
+
+  const words = argv.slice(command.path.length);
+
+  return words.some((word) => helpWords.has(word))
+    ? { kind: 'help', prefix: command.path }
+    : { kind: 'command', command, words };
+}
+
+function pickGroup(commands: readonly Command[], argv: readonly string[]): PickedCommand {
+  const prefix = argv.filter((word) => !helpWords.has(word));
+
+  const isGroup = commands.some((candidate) =>
+    prefix.every((word, index) => candidate.path[index] === word),
+  );
+
+  return isGroup ? { kind: 'help', prefix } : { kind: 'unknown', word: argv[0] ?? '' };
+}

package/src/cli/run-cli.ts

@@ -0,0 +1,46 @@
+import { ORPCError } from '@orpc/client';
+import { allCommands } from '../commands/all-commands.ts';
+import { exitCodes } from '../constants.ts';
+import { createClient } from '../create-client.ts';
+import type { CLIDeps, CLIResult } from '../types.ts';
+import { buildErrorResult, buildTextResult } from './build-answer-result.ts';
+import { formatHelp } from './format-help.ts';
+import { parseCommandArgs } from './parse-command-args.ts';
+import { pickCommand } from './pick-command.ts';
+import { UsageError } from './usage-error.ts';
+
+// Runs one command line and returns what to print and the exit code. It prints and exits nothing,
+// so a test calls it with the server's listener as `deps.send`.
+export async function runCLI(deps: CLIDeps, argv: readonly string[]): Promise<CLIResult> {
+  const picked = pickCommand(allCommands, argv);
+
+  if (picked.kind === 'help') {
+    return buildTextResult(formatHelp(allCommands, picked.prefix));
+  }
+
+  if (picked.kind === 'unknown') {
+    return buildErrorResult(`unknown command: ${picked.word}`, exitCodes.usage);
+  }
+
+  try {
+    const args = parseCommandArgs(picked.command, picked.words);
+
+    return await picked.command.run({ client: createClient(deps), args, deps });
+  } catch (error) {
+    return describeFailure(error);
+  }
+}
+
+function describeFailure(error: unknown): CLIResult {
+  if (error instanceof UsageError) {
+    return buildErrorResult(`error: ${error.message}`, exitCodes.usage);
+  }
+
+  if (error instanceof ORPCError) {
+    const data = error.data === undefined ? '' : ` ${JSON.stringify(error.data)}`;
+
+    return buildErrorResult(`error: ${error.code}: ${error.message}${data}`);
+  }
+
+  return buildErrorResult(`error: ${error instanceof Error ? error.message : String(error)}`);
+}

package/src/cli/usage-error.ts

@@ -0,0 +1,4 @@
+// A mistake in the command line or the environment. The CLI prints the message and exits with 2.
+export class UsageError extends Error {
+  override readonly name = 'UsageError';
+}

package/src/commands/all-commands.ts

@@ -0,0 +1,19 @@
+import type { Command } from '../types.ts';
+import { attemptCommands } from './attempt-commands.ts';
+import { hookCommands } from './hook-commands.ts';
+import { itemCommands } from './item-commands.ts';
+import { planCommands } from './plan-commands.ts';
+import { relationCommands } from './relation-commands.ts';
+import { reportCommands } from './report-commands.ts';
+import { runnerCommands } from './runner-commands.ts';
+
+// One command for each procedure of the contract.
+export const allCommands: readonly Command[] = [
+  ...itemCommands,
+  ...relationCommands,
+  ...planCommands,
+  ...runnerCommands,
+  ...reportCommands,
+  ...attemptCommands,
+  ...hookCommands,
+];