@boxxy/cli 0.1.0 → 0.1.3

package/src/hooks/parse-hook-payload.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { UsageError } from '../cli/usage-error.ts';
+
+// The fields of the JSON that Claude Code writes to a hook's stdin, as far as boxxy reads them.
+// The other fields are dropped.
+export const sessionStartPayloadSchema = z.object({
+  session_id: z.string().min(1),
+  cwd: z.string().min(1),
+});
+
+// the Bash tool answers with an object that holds `stdout`
+const bashResponseSchema = z.object({ stdout: z.string().optional() });
+const toolResponseSchema = z.union([z.string(), bashResponseSchema]);
+const toolInputSchema = z.object({ command: z.string().optional() });
+
+export const postToolUsePayloadSchema = z.object({
+  tool_name: z.string(),
+  tool_input: toolInputSchema.optional(),
+  tool_response: toolResponseSchema.optional(),
+});
+
+export type PostToolUsePayload = z.infer<typeof postToolUsePayloadSchema>;
+
+export function parseHookPayload<Schema extends z.ZodType>(
+  schema: Schema,
+  text: string,
+): z.output<Schema> {
+  const body = parseJSON(text);
+  const parsed = schema.safeParse(body);
+
+  if (!parsed.success) {
+    const problem = parsed.error.message;
+
+    throw new UsageError(`the hook payload on stdin is not the one expected: ${problem}`);
+  }
+
+  return parsed.data;
+}
+
+function parseJSON(text: string): unknown {
+  try {
+    const payload: unknown = JSON.parse(text);
+
+    return payload;
+  } catch {
+    throw new UsageError('the hook payload on stdin is not JSON');
+  }
+}

package/src/hooks/pick-pull-request-url.ts

@@ -0,0 +1,21 @@
+import type { PostToolUsePayload } from './parse-hook-payload.ts';
+
+const createCommandPattern = /\bgh\s+pr\s+create\b/u;
+const pullRequestURLPattern = /https:\/\/[^\s/]+\/[^\s/]+\/[^\s/]+\/pull\/\d+/gu;
+
+// The pull request that a `gh pr create` call printed, or null for any other tool call. `gh`
+// prints the new pull request's URL last.
+export function pickPullRequestURL(payload: PostToolUsePayload): string | null {
+  if (payload.tool_name !== 'Bash') {
+    return null;
+  }
+
+  if (!createCommandPattern.test(payload.tool_input?.command ?? '')) {
+    return null;
+  }
+
+  const response = payload.tool_response;
+  const stdout = typeof response === 'string' ? response : (response?.stdout ?? '');
+
+  return stdout.match(pullRequestURLPattern)?.at(-1) ?? null;
+}

package/src/hooks/run-post-tool-use-hook.ts

@@ -0,0 +1,46 @@
+import { match } from 'ts-pattern';
+import { buildErrorResult, buildTextResult } from '../cli/build-answer-result.ts';
+import type { CLIResult, CommandCall } from '../types.ts';
+import { parseHookPayload, postToolUsePayloadSchema } from './parse-hook-payload.ts';
+import { pickPullRequestURL } from './pick-pull-request-url.ts';
+import { waitForAttempt } from './wait-for-attempt.ts';
+
+// the exit code that makes Claude Code show stderr to the agent after a tool call
+const tellAgent = 2;
+
+// `boxxy hook post-tool-use`. It runs after every Bash call and does nothing unless the call was
+// `gh pr create` and printed a pull request URL. It then links that pull request to the attempt.
+export async function runPostToolUseHook(call: CommandCall): Promise<CLIResult> {
+  const text = await call.deps.readStdin();
+
+  const payload = parseHookPayload(postToolUsePayloadSchema, text);
+  const url = pickPullRequestURL(payload);
+
+  if (url === null) {
+    return buildTextResult('');
+  }
+
+  const current = await waitForAttempt(call.client, call.deps);
+
+  if (current === null) {
+    return buildErrorResult('boxxy has no attempt for this session');
+  }
+
+  const answer = await call.client.attempt.recordPullRequest({
+    session: { attempt: current.attempt.id },
+    url,
+  });
+
+  return match(answer)
+    .with({ kind: 'linked' }, (linked) =>
+      buildTextResult(`boxxy linked ${linked.repo}#${linked.number} to this attempt`),
+    )
+    .with({ kind: 'retry' }, () =>
+      buildTextResult('boxxy could not read the pull request now and links it later'),
+    )
+    .with({ kind: 'refused', reason: 'linked-elsewhere' }, () =>
+      buildErrorResult('boxxy refused: this pull request belongs to another item', tellAgent),
+    )
+    .with({ kind: 'refused' }, (refused) => buildErrorResult(`boxxy refused: ${refused.reason}`))
+    .exhaustive();
+}

package/src/hooks/run-session-start-hook.ts

@@ -0,0 +1,55 @@
+import { match } from 'ts-pattern';
+import { buildErrorResult, buildTextResult } from '../cli/build-answer-result.ts';
+import { defaultSkillsURL, envNames } from '../constants.ts';
+import type { CLIResult, CommandCall } from '../types.ts';
+import { installSkills } from './install-skills.ts';
+import { parseHookPayload, sessionStartPayloadSchema } from './parse-hook-payload.ts';
+import { waitForAttempt } from './wait-for-attempt.ts';
+
+// `boxxy hook session-start`. It asks which attempt the session carries, fetches the skills that
+// the attempt's recipe lists at the rules' pin into the workspace, and binds the agent session to
+// the attempt. A skill that is absent after the fetch goes to the server, which ends the attempt.
+export async function runSessionStartHook(call: CommandCall): Promise<CLIResult> {
+  const text = await call.deps.readStdin();
+
+  const payload = parseHookPayload(sessionStartPayloadSchema, text);
+
+  const current = await waitForAttempt(call.client, call.deps);
+
+  if (current === null) {
+    return buildErrorResult('boxxy has no attempt for this session');
+  }
+
+  const missing = await installSkills({
+    pin: current.skills.pin,
+    names: current.skills.names,
+    workspace: payload.cwd,
+    baseURL: call.deps.env[envNames.skillsURL] ?? defaultSkillsURL,
+    runGit: call.deps.runGit,
+  });
+
+  const answer = await call.client.attempt.bindSession({
+    session: {
+      attempt: current.attempt.id,
+      agentSession: payload.session_id,
+      product: 'claude_code',
+    },
+    seenAt: new Date(call.deps.now()).toISOString(),
+    missingSkills: missing.length === 0 ? undefined : missing,
+  });
+
+  return match(answer)
+    .with({ kind: 'bound' }, { kind: 'held' }, () => buildTextResult(''))
+    .with({ kind: 'skill-missing' }, () =>
+      buildErrorResult(
+        `boxxy ends this attempt: the skills ${missing.join(', ')} are not in the pinned skills repository`,
+      ),
+    )
+    .with({ kind: 'no-attempt' }, { kind: 'not-current' }, (refused) =>
+      buildErrorResult(`boxxy did not bind this session: ${refused.kind}`),
+    )
+    .with({ kind: 'fault' }, (fault) =>
+      buildErrorResult(`this agent session is bound to attempt ${fault.holder}`),
+    )
+    .exhaustive();
+}

package/src/hooks/wait-for-attempt.ts

@@ -0,0 +1,29 @@
+import type { BoxxyClient } from '@boxxy/contract';
+import { callerWait } from '../constants.ts';
+import type { CLIDeps } from '../types.ts';
+
+export type CurrentAttempt = Extract<
+  Awaited<ReturnType<BoxxyClient['attempt']['current']>>,
+  { kind: 'attempt' }
+>;
+
+// The attempt of this session, or null when the server still has none after the wait. The runner
+// stores a session's caller after the worker answers the start, and a hook can run before that.
+export async function waitForAttempt(
+  client: BoxxyClient,
+  deps: Pick<CLIDeps, 'sleep'>,
+): Promise<CurrentAttempt | null> {
+  for (let attempt = 1; attempt <= callerWait.tries; attempt += 1) {
+    const current = await client.attempt.current({});
+
+    if (current.kind === 'attempt') {
+      return current;
+    }
+
+    if (attempt < callerWait.tries) {
+      await deps.sleep(callerWait.delayMs);
+    }
+  }
+
+  return null;
+}

package/src/index.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/src/main.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+import { readFile } from 'node:fs/promises';
+import { runCLI } from './cli/run-cli.ts';
+import { runGit } from './run-git.ts';
+
+// The entry of the `boxxy` command: the real environment, stdin, files and git, given to `runCLI`.
+const result = await runCLI(
+  {
+    env: process.env,
+    readStdin: () => Bun.stdin.text(),
+    readFile: (path) => readFile(path, 'utf8'),
+    runGit,
+    sleep: (durationMs) => Bun.sleep(durationMs),
+    now: () => Date.now(),
+  },
+  process.argv.slice(2),
+);
+
+process.stdout.write(result.stdout);
+process.stderr.write(result.stderr);
+process.exit(result.exitCode);

package/src/run-git.ts

@@ -0,0 +1,22 @@
+import type { GitResult } from './types.ts';
+
+// Runs `git` and waits for it. Output and errors come back as one text.
+export async function runGit(args: readonly string[], folder?: string): Promise<GitResult> {
+  const child = Bun.spawn(['git', ...args], {
+    ...(folder === undefined ? {} : { cwd: folder }),
+
+    // git never waits for a password: a hook has no one to answer
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    stdout: 'pipe',
+    stderr: 'pipe',
+    stdin: 'ignore',
+  });
+
+  const [output, errors, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+
+  return { exitCode, output: `${output}${errors}` };
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+import type { ParseArgsOptionsConfig } from 'node:util';
+import type { BoxxyClient, ProcedureName } from '@boxxy/contract';
+
+export interface GitResult {
+  readonly exitCode: number;
+  readonly output: string;
+}
+
+// Everything the CLI reads from or does to the machine. `main.ts` builds the real one.
+export interface CLIDeps {
+  readonly env: Readonly<Record<string, string | undefined>>;
+
+  // sends a request to the server. Only a test passes it; the real CLI lets the client use the
+  // platform's fetch, so `HTTPS_PROXY` applies
+  readonly send?: (request: Request) => Promise<Response>;
+  readonly readStdin: () => Promise<string>;
+  readonly readFile: (path: string) => Promise<string>;
+
+  // runs `git` with the arguments, in the given folder when there is one
+  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;
+}
+
+// The flags and words of one command line, read through the command's option table.
+export interface CommandArgs {
+  // the word at the position; throws a usage error naming `label` when it is missing
+  positional: (index: number, label: string) => string;
+
+  // every word from the position on, at least one
+  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 {
+  // the words that name the command, such as `['item', 'file']`
+  readonly path: readonly string[];
+  readonly procedure: ProcedureName;
+  readonly summary: string;
+  readonly options: ParseArgsOptionsConfig;
+  readonly run: (call: CommandCall) => Promise<CLIResult>;
+}

package/dist/package-name.d.ts

@@ -1 +0,0 @@
-export declare const packageName = "@boxxy/cli";

package/src/package-name.ts

@@ -1 +0,0 @@
-export const packageName = '@boxxy/cli';