@boxxy/cli 0.0.0 → 0.1.3

package/src/commands/attempt-commands.ts

@@ -0,0 +1,132 @@
+import type { BoxxyClient } from '@boxxy/contract';
+import { match } from 'ts-pattern';
+import {
+  buildAnswerResult,
+  buildErrorResult,
+  buildTextResult,
+} from '../cli/build-answer-result.ts';
+import { UsageError } from '../cli/usage-error.ts';
+import { exitCodes } from '../constants.ts';
+import type { CLIResult, Command } from '../types.ts';
+import { describeCloseOutProblem } from './describe-close-out-problem.ts';
+
+const evidenceKinds = ['test', 'ci-run', 'live-check'] as const;
+const waitMessage = 'no attempt for this session yet; try again in 5 seconds';
+
+// These commands run inside a session. None takes a session: the server finds the session from
+// the proven caller, and the command asks `attempt.current` for the attempt to name.
+export const attemptCommands: readonly Command[] = [
+  {
+    path: ['attempt', 'current'],
+    procedure: 'attempt.current',
+    summary: 'Shows the attempt of this session, its input and the schema of its close-out.',
+    options: {},
+    run: async (call) => {
+      const current = await call.client.attempt.current({});
+
+      return current.kind === 'attempt'
+        ? buildAnswerResult(current)
+        : buildErrorResult(waitMessage, exitCodes.retryLater);
+    },
+  },
+  {
+    path: ['attempt', 'evidence'],
+    procedure: 'attempt.evidence',
+    summary: 'Records one piece of evidence and prints its ID, to cite in the close-out.',
+    options: {
+      kind: { type: 'string' },
+      ref: { type: 'string' },
+      observed: { type: 'string' },
+    },
+    run: async (call) => {
+      const kind = call.args.requireOneOf('kind', evidenceKinds);
+      const ref = call.args.requireString('ref');
+
+      const attempt = await readCurrentAttempt(call.client);
+
+      if (attempt === null) {
+        return buildErrorResult(waitMessage, exitCodes.retryLater);
+      }
+
+      const answer = await call.client.attempt.evidence({
+        session: { attempt },
+        kind,
+        ref,
+        observed: call.args.string('observed'),
+      });
+
+      return describeEvidenceAnswer(answer);
+    },
+  },
+  {
+    path: ['attempt', 'close-out'],
+    procedure: 'attempt.closeOut',
+    summary: 'Sends the close-out, read as JSON from stdin. The first valid close-out is final.',
+    options: {},
+    run: async (call) => {
+      const text = await call.deps.readStdin();
+
+      const closeOut = parseJSON(text);
+
+      const attempt = await readCurrentAttempt(call.client);
+
+      if (attempt === null) {
+        return buildErrorResult(waitMessage, exitCodes.retryLater);
+      }
+
+      const answer = await call.client.attempt.closeOut({ session: { attempt }, closeOut });
+
+      return describeCloseOutAnswer(answer);
+    },
+  },
+];
+
+async function readCurrentAttempt(client: BoxxyClient): Promise<string | null> {
+  const current = await client.attempt.current({});
+
+  return current.kind === 'attempt' ? current.attempt.id : null;
+}
+
+type EvidenceAnswer = Awaited<ReturnType<BoxxyClient['attempt']['evidence']>>;
+
+function describeEvidenceAnswer(answer: EvidenceAnswer): CLIResult {
+  if (answer.kind === 'recorded') {
+    return buildTextResult(answer.factId);
+  }
+
+  const message = answer.reason === 'no-attempt' ? waitMessage : 'this attempt is over';
+
+  return buildErrorResult(message);
+}
+
+function parseJSON(text: string): unknown {
+  try {
+    const body: unknown = JSON.parse(text);
+
+    return body;
+  } catch {
+    throw new UsageError('stdin is not JSON');
+  }
+}
+
+type CloseOutAnswer = Awaited<ReturnType<BoxxyClient['attempt']['closeOut']>>;
+
+function describeCloseOutAnswer(answer: CloseOutAnswer): CLIResult {
+  return match(answer)
+    .with({ kind: 'recorded' }, (recorded) => buildTextResult(recorded.factId))
+    .with({ kind: 'rejected' }, (rejected) =>
+      buildErrorResult(
+        rejected.problems.map((problem) => describeCloseOutProblem(problem)).join('\n'),
+      ),
+    )
+    .with({ kind: 'refused', reason: 'no-attempt' }, () => buildErrorResult(waitMessage))
+    .with({ kind: 'refused', reason: 'already-closed-out' }, () =>
+      buildErrorResult(
+        'this attempt already has a close-out, and the first valid close-out is final',
+      ),
+    )
+    .with({ kind: 'refused', reason: 'not-current' }, () =>
+      buildErrorResult('this attempt is over'),
+    )
+    .exhaustive();
+}

package/src/commands/describe-close-out-problem.ts

@@ -0,0 +1,33 @@
+import type { CloseOutProblem } from '@boxxy/model';
+import { match } from 'ts-pattern';
+
+// One line for the agent to act on. The server lists every problem at once.
+export function describeCloseOutProblem(problem: CloseOutProblem): string {
+  return match(problem)
+    .with(
+      { kind: 'schema' },
+      (found) => `${found.path === '' ? '(body)' : found.path}: ${found.message}`,
+    )
+    .with({ kind: 'unknown-criterion' }, (found) => `unknown criterion ${found.criterion}`)
+    .with(
+      { kind: 'foreign-evidence' },
+      (found) => `evidence ${found.evidence} belongs to another attempt`,
+    )
+    .with(
+      { kind: 'built-without-evidence' },
+      (found) => `built criteria with no evidence: ${found.criteria.join(', ')}`,
+    )
+    .with({ kind: 'no-acceptance' }, () => 'the close-out lists no acceptance criterion')
+    .with({ kind: 'unknown-item' }, (found) => `unknown item ${found.item}`)
+    .with({ kind: 'unknown-kind' }, (found) => `unknown item kind ${found.itemKind}`)
+    .with(
+      { kind: 'refused-relation' },
+      (found) => `relation ${found.type} to ${found.target} refused: ${found.reason}`,
+    )
+    .with({ kind: 'phase-rule' }, (found) => found.message)
+    .with(
+      { kind: 'too-large' },
+      (found) => `the close-out is ${found.bytes} bytes as stored; the limit is ${found.max}`,
+    )
+    .exhaustive();
+}

package/src/commands/hook-commands.ts

@@ -0,0 +1,21 @@
+import { runPostToolUseHook } from '../hooks/run-post-tool-use-hook.ts';
+import { runSessionStartHook } from '../hooks/run-session-start-hook.ts';
+import type { Command } from '../types.ts';
+
+// The hook plug-in in the agent image runs these. Each reads Claude Code's hook payload on stdin.
+export const hookCommands: readonly Command[] = [
+  {
+    path: ['hook', 'session-start'],
+    procedure: 'attempt.bindSession',
+    summary: 'Fetches the pinned skills, then binds the agent session to its attempt.',
+    options: {},
+    run: runSessionStartHook,
+  },
+  {
+    path: ['hook', 'post-tool-use'],
+    procedure: 'attempt.recordPullRequest',
+    summary: 'Links the pull request that `gh pr create` printed to the attempt.',
+    options: {},
+    run: runPostToolUseHook,
+  },
+];

package/src/commands/item-commands.ts

@@ -0,0 +1,140 @@
+import { makeAnswerRun } from '../cli/make-answer-run.ts';
+import type { Command } from '../types.ts';
+import { parseCriterionFlag } from './parse-criterion-flag.ts';
+
+const designModes = ['agent', 'attended'] as const;
+const itemStates = ['idea', 'ready', 'blocked', 'running', 'waiting', 'done', 'archived'] as const;
+
+export const itemCommands: readonly Command[] = [
+  {
+    path: ['item', 'file'],
+    procedure: 'item.file',
+    summary: 'Files a new item of work.',
+    options: {
+      repo: { type: 'string' },
+      title: { type: 'string' },
+      outcome: { type: 'string' },
+      acceptance: { type: 'string', multiple: true },
+      kind: { type: 'string' },
+      'design-mode': { type: 'string' },
+      'blocked-by': { type: 'string', multiple: true },
+      label: { type: 'string', multiple: true },
+    },
+    run: makeAnswerRun((call) =>
+      call.client.item.file({
+        repo: call.args.requireString('repo'),
+        title: call.args.requireString('title'),
+        outcome: call.args.requireString('outcome'),
+        acceptance: call.args.strings('acceptance'),
+        blockedBy: call.args.strings('blocked-by'),
+        labels: call.args.strings('label'),
+        kind: call.args.string('kind'),
+        designMode: call.args.oneOf('design-mode', designModes),
+      }),
+    ),
+  },
+  {
+    path: ['item', 'edit'],
+    procedure: 'item.edit',
+    summary: 'Replaces the given fields of an item. A flag that is left out changes nothing.',
+    options: {
+      title: { type: 'string' },
+      outcome: { type: 'string' },
+      acceptance: { type: 'string', multiple: true },
+      'design-mode': { type: 'string' },
+      label: { type: 'string', multiple: true },
+    },
+    run: makeAnswerRun((call) => {
+      const acceptance = call.args.strings('acceptance');
+      const labels = call.args.strings('label');
+
+      return call.client.item.edit({
+        item: call.args.positional(0, 'item'),
+        title: call.args.string('title'),
+        outcome: call.args.string('outcome'),
+        designMode: call.args.oneOf('design-mode', designModes),
+        acceptance:
+          acceptance.length === 0
+            ? undefined
+            : acceptance.map((entry) => parseCriterionFlag(entry)),
+        labels: labels.length === 0 ? undefined : labels,
+      });
+    }),
+  },
+  {
+    path: ['item', 'close'],
+    procedure: 'item.close',
+    summary: 'Closes an item and ends its live attempt. With --of, closes it as a duplicate.',
+    options: { reason: { type: 'string' }, of: { type: 'string' } },
+    run: makeAnswerRun((call) =>
+      call.client.item.close({
+        item: call.args.positional(0, 'item'),
+        reason: call.args.requireString('reason'),
+        of: call.args.string('of'),
+      }),
+    ),
+  },
+  {
+    path: ['item', 'retry'],
+    procedure: 'item.retry',
+    summary: 'Lifts a hold and resets the attempt counts. With --phase, sets the position.',
+    options: { phase: { type: 'string' } },
+    run: makeAnswerRun((call) =>
+      call.client.item.retry({
+        item: call.args.positional(0, 'item'),
+        phase: call.args.string('phase'),
+      }),
+    ),
+  },
+  {
+    path: ['item', 'wake'],
+    procedure: 'item.wake',
+    summary: 'Asks boxxy to wake the sleeping session of an item.',
+    options: {},
+    run: makeAnswerRun((call) => call.client.item.wake({ item: call.args.positional(0, 'item') })),
+  },
+  {
+    path: ['item', 'note'],
+    procedure: 'item.note',
+    summary: 'Appends a note to an item. The next attempt reads it.',
+    options: { text: { type: 'string' } },
+    run: makeAnswerRun((call) =>
+      call.client.item.note({
+        item: call.args.positional(0, 'item'),
+        text: call.args.requireString('text'),
+      }),
+    ),
+  },
+  {
+    path: ['item', 'show'],
+    procedure: 'item.get',
+    summary: 'Shows one item with its position, notes, attempts, relations and pull requests.',
+    options: {},
+    run: makeAnswerRun((call) => call.client.item.get({ item: call.args.positional(0, 'item') })),
+  },
+  {
+    path: ['item', 'list'],
+    procedure: 'item.list',
+    summary: 'Lists items, newest first, with filters.',
+    options: {
+      state: { type: 'string' },
+      repo: { type: 'string' },
+      phase: { type: 'string' },
+      text: { type: 'string' },
+      label: { type: 'string' },
+      limit: { type: 'string' },
+      after: { type: 'string' },
+    },
+    run: makeAnswerRun((call) =>
+      call.client.item.list({
+        state: call.args.oneOf('state', itemStates),
+        repo: call.args.string('repo'),
+        phase: call.args.string('phase'),
+        text: call.args.string('text'),
+        label: call.args.string('label'),
+        limit: call.args.integer('limit'),
+        after: call.args.string('after'),
+      }),
+    ),
+  },
+];

package/src/commands/parse-criterion-flag.ts

@@ -0,0 +1,13 @@
+const keptPattern = /^\[(?<id>[^\]\s]+)\]\s+(?<text>\S.*)$/u;
+
+// One `--acceptance` value of `item edit`. `[c-3] text` keeps the criterion c-3, with its
+// evidence, and gives it the text. Any other value is a new criterion.
+export function parseCriterionFlag(entry: string): { id?: string; text: string } {
+  const groups = keptPattern.exec(entry)?.groups;
+
+  if (groups?.['id'] === undefined || groups['text'] === undefined) {
+    return { text: entry };
+  }
+
+  return { id: groups['id'], text: groups['text'] };
+}

package/src/commands/plan-commands.ts

@@ -0,0 +1,49 @@
+import { makeAnswerRun } from '../cli/make-answer-run.ts';
+import type { Command } from '../types.ts';
+
+export const planCommands: readonly Command[] = [
+  {
+    path: ['defer'],
+    procedure: 'plan.defer',
+    summary: 'Holds an item back from dispatch until a time, or until undefer.',
+    options: { until: { type: 'string' }, reason: { type: 'string' } },
+    run: makeAnswerRun((call) =>
+      call.client.plan.defer({
+        item: call.args.positional(0, 'item'),
+        reason: call.args.requireString('reason'),
+        until: call.args.string('until'),
+      }),
+    ),
+  },
+  {
+    path: ['undefer'],
+    procedure: 'plan.undefer',
+    summary: 'Ends the deferral of an item.',
+    options: {},
+    run: makeAnswerRun((call) =>
+      call.client.plan.undefer({ item: call.args.positional(0, 'item') }),
+    ),
+  },
+  {
+    path: ['expedite'],
+    procedure: 'plan.expedite',
+    summary: 'Puts items at the front of their pools, in the order given.',
+    options: { reason: { type: 'string' }, expires: { type: 'string' } },
+    run: makeAnswerRun((call) =>
+      call.client.plan.expedite({
+        items: call.args.positionalsFrom(0, 'item'),
+        reason: call.args.requireString('reason'),
+        expires: call.args.string('expires'),
+      }),
+    ),
+  },
+  {
+    path: ['unexpedite'],
+    procedure: 'plan.unexpedite',
+    summary: 'Ends the expedite of an item.',
+    options: {},
+    run: makeAnswerRun((call) =>
+      call.client.plan.unexpedite({ item: call.args.positional(0, 'item') }),
+    ),
+  },
+];

package/src/commands/relation-commands.ts

@@ -0,0 +1,31 @@
+import { makeAnswerRun } from '../cli/make-answer-run.ts';
+import type { Command } from '../types.ts';
+
+export const relationCommands: readonly Command[] = [
+  {
+    path: ['relation', 'add'],
+    procedure: 'relation.add',
+    summary: 'Adds a relation from one item to another, such as "blocks".',
+    options: {},
+    run: makeAnswerRun((call) =>
+      call.client.relation.add({
+        source: call.args.positional(0, 'source'),
+        type: call.args.positional(1, 'type'),
+        target: call.args.positional(2, 'target'),
+      }),
+    ),
+  },
+  {
+    path: ['relation', 'remove'],
+    procedure: 'relation.remove',
+    summary: 'Removes a relation between two items.',
+    options: {},
+    run: makeAnswerRun((call) =>
+      call.client.relation.remove({
+        source: call.args.positional(0, 'source'),
+        type: call.args.positional(1, 'type'),
+        target: call.args.positional(2, 'target'),
+      }),
+    ),
+  },
+];

package/src/commands/report-commands.ts

@@ -0,0 +1,23 @@
+import { makeAnswerRun } from '../cli/make-answer-run.ts';
+import type { Command } from '../types.ts';
+
+export const reportCommands: readonly Command[] = [
+  {
+    path: ['cost'],
+    procedure: 'report.cost',
+    summary: 'Shows what one item cost, from pepys.',
+    options: {},
+    run: makeAnswerRun((call) =>
+      call.client.report.cost({ item: call.args.positional(0, 'item') }),
+    ),
+  },
+  {
+    path: ['times'],
+    procedure: 'report.stageTimes',
+    summary: 'Shows how long one item took in each step, from pepys.',
+    options: {},
+    run: makeAnswerRun((call) =>
+      call.client.report.stageTimes({ item: call.args.positional(0, 'item') }),
+    ),
+  },
+];

package/src/commands/runner-commands.ts

@@ -0,0 +1,45 @@
+import { makeAnswerRun } from '../cli/make-answer-run.ts';
+import type { Command } from '../types.ts';
+
+// The commands that act on the server as a whole.
+export const runnerCommands: readonly Command[] = [
+  {
+    path: ['status'],
+    procedure: 'runner.status',
+    summary: 'Shows the limits, the live attempts, the strays, the unsent notices and the outbox.',
+    options: {},
+    run: makeAnswerRun((call) => call.client.runner.status({})),
+  },
+  {
+    path: ['runner', 'pause'],
+    procedure: 'runner.pause',
+    summary: 'Pauses the runner. It starts no new attempt until resume.',
+    options: {},
+    run: makeAnswerRun((call) => call.client.runner.pause({})),
+  },
+  {
+    path: ['runner', 'resume'],
+    procedure: 'runner.resume',
+    summary: 'Resumes the runner.',
+    options: {},
+    run: makeAnswerRun((call) => call.client.runner.resume({})),
+  },
+  {
+    path: ['outbox', 'retry'],
+    procedure: 'outbox.retry',
+    summary: 'Clears the park mark of every parked outbox row.',
+    options: {},
+    run: makeAnswerRun((call) => call.client.outbox.retry({})),
+  },
+  {
+    path: ['rules', 'dry-run'],
+    procedure: 'rules.dryRun',
+    summary: 'Shows where each open item would stand under a rules file. It writes nothing.',
+    options: {},
+    run: makeAnswerRun(async (call) => {
+      const rules = await call.deps.readFile(call.args.positional(0, 'file'));
+
+      return call.client.rules.dryRun({ rules });
+    }),
+  },
+];

package/src/constants.ts

@@ -0,0 +1,19 @@
+// 2 means the command line is wrong, or the server has no attempt for this session yet
+export const exitCodes = { ok: 0, failed: 1, usage: 2, retryLater: 2 } as const;
+
+// The session-start hook can run before the server knows the session's caller, because the runner
+// stores the caller after the worker answers the start. The hook asks again for this long.
+export const callerWait = { tries: 6, delayMs: 5000 } as const;
+
+// where the server's address is read from, and where a deployment points the skills fetch
+export const envNames = {
+  url: 'BOXXY_URL',
+  skillsURL: 'BOXXY_SKILLS_URL',
+} as const;
+
+export const defaultSkillsURL = 'https://github.com';
+
+// the folder of the skills repository that holds one folder per skill, and the folder of the
+// workspace that the agent reads skills from
+export const skillsRepoFolder = 'skills';
+export const workspaceSkillsFolder = '.claude/skills';

package/src/create-client.ts

@@ -0,0 +1,50 @@
+import type { BoxxyClient } from '@boxxy/contract';
+import { createORPCClient } from '@orpc/client';
+import { RPCLink } from '@orpc/client/fetch';
+import { UsageError } from './cli/usage-error.ts';
+import { envNames } from './constants.ts';
+import type { CLIDeps } from './types.ts';
+
+// The typed client of the server's RPC route. It sends no token and no identity header: on the
+// owner's path the listener needs none, and in a session the broker adds both on the way out. The
+// client uses the platform's fetch unless a test passes `send`.
+export function createClient(deps: CLIDeps): BoxxyClient {
+  const address = deps.env[envNames.url];
+
+  if (address === undefined || address === '') {
+    throw new UsageError(`${envNames.url} is not set`);
+  }
+
+  const target = parseServerAddress(address);
+
+  const link = new RPCLink({
+    origin: target.origin,
+    url: target.url,
+    ...makeLinkOptions(deps.send),
+  });
+
+  return createORPCClient<BoxxyClient>(link);
+}
+
+function parseServerAddress(address: string): { origin: string; url: `/${string}` } {
+  const parsed = URL.parse(address);
+
+  if (parsed === null || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+    throw new UsageError(`${envNames.url} is not an http or https address`);
+  }
+
+  const route = `${parsed.pathname.replace(/\/+$/u, '')}/rpc`.replace(/^\/+/u, '');
+
+  return { origin: parsed.origin, url: `/${route}` };
+}
+
+// the link sends through the platform's fetch unless it is given another way to send
+function makeLinkOptions(send: CLIDeps['send']) {
+  if (send === undefined) {
+    return {};
+  }
+
+  const sendRequest = (url: string, init: RequestInit) => send(new Request(url, init));
+
+  return { fetch: sendRequest };
+}

package/src/hooks/install-skills.ts

@@ -0,0 +1,116 @@
+import { cp, mkdir, mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { skillsRepoFolder, workspaceSkillsFolder } from '../constants.ts';
+import type { CLIDeps } from '../types.ts';
+
+interface SkillsPin {
+  // the repository, as owner/name
+  readonly source: string;
+
+  // one full commit
+  readonly ref: string;
+}
+
+export interface InstallSkillsInput {
+  // the rules' pin; null when the rules have none
+  readonly pin: SkillsPin | null;
+  readonly names: readonly string[];
+
+  // the folder the agent works in; the skills land in its `.claude/skills`
+  readonly workspace: string;
+
+  // where `<owner>/<name>.git` is fetched from
+  readonly baseURL: string;
+  readonly runGit: CLIDeps['runGit'];
+}
+
+const sourcePattern = /^[\w.-]+\/[\w.-]+$/u;
+const refPattern = /^[0-9a-f]{40,64}$/u;
+
+// Copies each named skill at the pin into the workspace and returns the names that are not there
+// afterwards. A skill is there when its folder holds a `SKILL.md`. A fetch that fails leaves every
+// name missing, because the attempt cannot tell a skill it lacks from one it could not read.
+export async function installSkills(input: InstallSkillsInput): Promise<string[]> {
+  if (input.names.length === 0) {
+    return [];
+  }
+
+  const pin = input.pin;
+
+  if (pin === null || !sourcePattern.test(pin.source) || !refPattern.test(pin.ref)) {
+    return [...input.names];
+  }
+
+  const scratch = await mkdtemp(join(tmpdir(), 'boxxy-skills-'));
+
+  try {
+    const fetched = await runFetch(input, scratch, pin);
+
+    if (!fetched) {
+      return [...input.names];
+    }
+
+    const missing: string[] = [];
+
+    for (const name of input.names) {
+      if (!(await installSkill(input, scratch, name))) {
+        missing.push(name);
+      }
+    }
+
+    return missing;
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+
+async function runFetch(
+  input: InstallSkillsInput,
+  scratch: string,
+  pin: SkillsPin,
+): Promise<boolean> {
+  const init = await input.runGit(['init', '--quiet', scratch]);
+
+  if (init.exitCode !== 0) {
+    return false;
+  }
+
+  const fetched = await input.runGit(
+    ['fetch', '--quiet', '--depth', '1', `${input.baseURL}/${pin.source}.git`, pin.ref],
+    scratch,
+  );
+
+  return fetched.exitCode === 0;
+}
+
+const namePattern = /^[a-z0-9][a-z0-9._-]*$/u;
+
+async function installSkill(
+  input: InstallSkillsInput,
+  scratch: string,
+  name: string,
+): Promise<boolean> {
+  if (!namePattern.test(name)) {
+    return false;
+  }
+
+  const checkout = await input.runGit(
+    ['checkout', '--quiet', 'FETCH_HEAD', '--', `${skillsRepoFolder}/${name}`],
+    scratch,
+  );
+
+  if (checkout.exitCode !== 0) {
+    return false;
+  }
+
+  const target = join(input.workspace, workspaceSkillsFolder, name);
+
+  await rm(target, { recursive: true, force: true });
+  await mkdir(dirname(target), { recursive: true });
+  await cp(join(scratch, skillsRepoFolder, name), target, { recursive: true });
+
+  const skillFile = await stat(join(target, 'SKILL.md')).catch(() => null);
+
+  return skillFile?.isFile() === true;
+}