@boxxy/server 0.0.1 → 0.1.3

package/src/start-server.ts

@@ -0,0 +1,308 @@
+import { createNullNotifier, outboxLimits, watchPullRequests } from '@boxxy/dispatch';
+import type { SpawnSettings } from '@boxxy/dispatch';
+import { createGithubForge } from '@boxxy/forge-github';
+import type { AttemptId, Notifier, SessionReading } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { createAtcNotifier } from '@boxxy/notifier-atc';
+import type { UncheckedQueryClient } from '@boxxy/pepys';
+import { createPepysReader } from '@boxxy/pepys/reader';
+import { createPepysFactSink } from '@boxxy/pepys/sink';
+import { createSQLiteClaimStore } from '@boxxy/store-sqlite';
+import type { AtcClient } from '@boxxy/worker-atc';
+import { createAtcWorker } from '@boxxy/worker-atc';
+import { createORPCClient } from '@orpc/client';
+import { RPCLink } from '@orpc/client/fetch';
+import { buildTokenDigest } from './auth/pick-request-scope.ts';
+import { pickServerSecrets } from './config/pick-server-secrets.ts';
+import { readCallerProof } from './config/read-caller-proof.ts';
+import { readServerConfig } from './config/read-server-config.ts';
+import type { ServerConfig } from './config/server-config-schema.ts';
+import { createCapacityBackoff } from './create-capacity-backoff.ts';
+import { createOffOutbox } from './outbox/create-off-outbox.ts';
+import type { OutboxSender } from './outbox/start-outbox-sender.ts';
+import { startOutboxSender } from './outbox/start-outbox-sender.ts';
+import { createRulesHolder } from './rules/create-rules-holder.ts';
+import { maxRequestBytes, serveApi } from './serve-api.ts';
+import { runTick } from './tick/run-tick.ts';
+import { startTickLoop } from './tick/start-tick-loop.ts';
+import type { ServerDeps, ServerLog } from './types.ts';
+
+export interface StartServerInput {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly log: ServerLog;
+}
+
+export interface RunningServer {
+  readonly ownerPort: number;
+  readonly workerPort: number;
+  readonly stop: () => Promise<void>;
+}
+
+export type StartAnswer =
+  | { readonly kind: 'started'; readonly server: RunningServer }
+
+  // the server did not start; the message names no secret value
+  | { readonly kind: 'refused'; readonly message: string };
+
+const tickMs = 5000;
+const watchMs = 5 * 60 * 1000;
+
+// Reads the configuration and the secrets, loads the rules, opens the store, builds the adapters,
+// starts both listeners, the runner tick, the pull request watch and the outbox sender.
+export async function startServer(input: StartServerInput): Promise<StartAnswer> {
+  const configPath = input.env['BOXXY_CONFIG'] ?? '';
+
+  if (configPath === '') {
+    return { kind: 'refused', message: 'set BOXXY_CONFIG to the path of the configuration file' };
+  }
+
+  const read = await readServerConfig(configPath);
+
+  if (read.kind === 'invalid') {
+    return { kind: 'refused', message: read.message };
+  }
+
+  const config = read.config;
+  const secrets = pickServerSecrets(config, input.env);
+
+  if (secrets.kind === 'missing') {
+    return { kind: 'refused', message: `set these variables: ${secrets.names.join(', ')}` };
+  }
+
+  const rules = await createRulesHolder(config.rules.folder, input.log);
+
+  if (rules.kind !== 'loaded') {
+    return { kind: 'refused', message: `the rules did not load: ${JSON.stringify(rules)}` };
+  }
+
+  const clock = { now: () => brandSchemas.instant.parse(Date.now()) };
+
+  const proof = await readCallerProof(config.trustedIssuers, clock);
+
+  if (proof.kind === 'refused') {
+    return proof;
+  }
+
+  const store = await createSQLiteClaimStore(config.store.file);
+
+  const runner = brandSchemas.runnerId.parse(config.runner);
+
+  // the client type is an object literal of the port's calls: an interface has no index
+  // signature, so `createORPCClient` refuses `AtcClient` itself
+  const atc = createORPCClient<{ readonly session: AtcClient['session'] }>(
+    new RPCLink({
+      ...toLinkTarget(config.atc.url),
+      headers: { authorization: `Bearer ${secrets.secrets.atcToken}` },
+    }),
+  );
+
+  const worker = createAtcWorker({ client: atc, trustedFolders: config.atc.trustedFolders });
+  const notifier = buildNotifier(config, atc);
+
+  const pepys = startPepys({
+    config,
+    secret: secrets.secrets.pepysSigningSecret,
+    store,
+    clock,
+    log: input.log,
+  });
+
+  const forge =
+    config.github === undefined
+      ? null
+      : createGithubForge({
+          fetch,
+          baseUrl: config.github.baseUrl,
+          ...(secrets.secrets.githubToken !== null && { token: secrets.secrets.githubToken }),
+        });
+
+  const readings = new Map<AttemptId, SessionReading>();
+
+  const holder = rules.holder;
+
+  const deps: ServerDeps = {
+    store,
+    runner,
+    rulesState: holder.state,
+    loadProposedRules: holder.loadProposed,
+    clock,
+    newId,
+    callerProof: proof.callerProof,
+    workerTokenDigest: buildTokenDigest(secrets.secrets.workerToken),
+    pepys: pepys?.reader ?? null,
+    forge,
+    outbox: pepys?.sender ?? createOffOutbox(store, clock),
+    readings,
+    log: input.log,
+  };
+
+  const listeners = serveApi(deps);
+
+  const owner = listeners.owner.listen({
+    ...config.api.listen,
+    maxRequestBodySize: maxRequestBytes,
+  });
+
+  const workerListener = listeners.worker.listen({
+    ...config.api.workerListen,
+    maxRequestBodySize: maxRequestBytes,
+  });
+
+  const backoff = createCapacityBackoff();
+
+  const ticks = startTickLoop({
+    runOnce: async () => {
+      await holder.reload();
+
+      await runTick({
+        store,
+        runner,
+        worker,
+        rules: holder.state().rules,
+        backoff,
+        spawn: buildSpawnSettings(config, holder.texts()),
+        notifier,
+        now: clock.now(),
+        newId,
+        readings,
+        log: input.log,
+      });
+    },
+    intervalMs: tickMs,
+    failureMessage: 'the runner tick failed',
+    log: input.log,
+  });
+
+  const watch =
+    forge === null
+      ? null
+      : startTickLoop({
+          runOnce: async () => {
+            const report = await watchPullRequests({
+              store,
+              forge,
+              rules: holder.state().rules,
+              runner,
+              now: clock.now(),
+              newId,
+            });
+
+            if (report.unanswered > 0) {
+              input.log.warn('the forge did not answer the pull request watch', { ...report });
+            }
+          },
+          intervalMs: watchMs,
+          failureMessage: 'the pull request watch failed',
+          log: input.log,
+        });
+
+  return {
+    kind: 'started',
+    server: {
+      ownerPort: owner.server?.port ?? 0,
+      workerPort: workerListener.server?.port ?? 0,
+      stop: async () => {
+        await ticks.stop();
+        await watch?.stop();
+        await pepys?.sender.stop();
+        await owner.stop();
+        await workerListener.stop();
+        await store.close();
+      },
+    },
+  };
+}
+
+// oRPC's link takes the origin apart from the route's path
+function toLinkTarget(address: string): { origin: string; url: `/${string}` } {
+  const parsed = new URL(address);
+
+  return { origin: parsed.origin, url: `/${parsed.pathname.replace(/^\/+/u, '')}` };
+}
+
+function buildNotifier(config: ServerConfig, atc: AtcClient): Notifier {
+  const session = config.atc.noticeSession;
+
+  if (session === undefined) {
+    return createNullNotifier();
+  }
+
+  return createAtcNotifier({
+    client: { sendMessage: (request) => atc.session.message(request) },
+    session,
+  });
+}
+
+interface PepysWiring {
+  readonly reader: ReturnType<typeof createPepysReader>;
+  readonly sender: OutboxSender;
+}
+
+interface PepysInput {
+  readonly config: ServerConfig;
+  readonly secret: string | null;
+  readonly store: ServerDeps['store'];
+  readonly clock: ServerDeps['clock'];
+  readonly log: ServerLog;
+}
+
+const pepysTimeoutMs = 10_000;
+const outboxIdleMs = 5000;
+
+// null: the configuration has no pepys section
+function startPepys(input: PepysInput): PepysWiring | null {
+  const config = input.config;
+  const secret = input.secret;
+
+  if (config.pepys === undefined || secret === null) {
+    return null;
+  }
+
+  const client = createORPCClient<UncheckedQueryClient>(
+    new RPCLink(toLinkTarget(config.pepys.apiUrl)),
+  );
+
+  const reader = createPepysReader({
+    client,
+    environment: config.pepys.environment,
+    timeoutMs: pepysTimeoutMs,
+  });
+
+  const sink = createPepysFactSink({
+    url: config.pepys.ingestUrl,
+    secret,
+    timeoutMs: pepysTimeoutMs,
+  });
+
+  const sender = startOutboxSender({
+    store: input.store,
+    sink,
+    clock: input.clock,
+    limits: outboxLimits,
+    random: Math.random,
+    idleMs: outboxIdleMs,
+    log: input.log,
+  });
+
+  return { reader, sender };
+}
+
+function newId(): string {
+  return Bun.randomUUIDv7();
+}
+
+function buildSpawnSettings(
+  config: ServerConfig,
+  prompts: ReadonlyMap<string, string>,
+): SpawnSettings {
+  return {
+    target: config.spawn.target,
+    repoPaths: new Map(
+      Object.entries(config.spawn.repoPaths).map(([repo, folder]) => [
+        brandSchemas.repoName.parse(repo),
+        folder,
+      ]),
+    ),
+    prompts,
+  };
+}

package/src/test-utils/build-mcp-request.ts

@@ -0,0 +1,34 @@
+interface MCPRequestInput {
+  readonly path: '/mcp' | '/mcp/session';
+
+  // the JSON-RPC method, such as `tools/list`
+  readonly method: string;
+  readonly params: Readonly<Record<string, unknown>>;
+
+  // the bearer token; none when left out
+  readonly token?: string;
+}
+
+// One JSON-RPC request to an MCP endpoint. The endpoints keep no session, so a request needs no
+// `initialize` first.
+export function buildMCPRequest(request: MCPRequestInput): Request {
+  const headers = new Headers({
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream',
+  });
+
+  if (request.token !== undefined) {
+    headers.set('authorization', `Bearer ${request.token}`);
+  }
+
+  return new Request(`http://boxxy.test${request.path}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: request.method,
+      params: request.params,
+    }),
+  });
+}

package/src/test-utils/build-rpc-request.ts

@@ -0,0 +1,23 @@
+interface RPCRequestInput {
+  // the procedure as the access table names it, such as `item.get`
+  readonly procedure: string;
+  readonly input: unknown;
+
+  // the bearer token; none when left out
+  readonly token?: string;
+}
+
+// A call of one procedure on the oRPC route, as the oRPC client sends it.
+export function buildRPCRequest(request: RPCRequestInput): Request {
+  const headers = new Headers({ 'content-type': 'application/json' });
+
+  if (request.token !== undefined) {
+    headers.set('authorization', `Bearer ${request.token}`);
+  }
+
+  return new Request(`http://boxxy.test/rpc/${request.procedure.replace('.', '/')}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ json: request.input }),
+  });
+}

package/src/test-utils/build-session-input.ts

@@ -0,0 +1,16 @@
+// A valid input of a session or hook procedure that names the attempt; `{}` for any other.
+export function buildSessionInput(procedure: string, attempt: string): unknown {
+  const session = { attempt };
+
+  const inputs: Readonly<Record<string, unknown>> = {
+    'attempt.evidence': { session, kind: 'test', ref: 'bun test' },
+    'attempt.closeOut': { session, closeOut: {} },
+    'attempt.bindSession': {
+      session: { attempt, agentSession: 'agent-1', product: 'claude_code' },
+      seenAt: '2026-11-01T09:00:00Z',
+    },
+    'attempt.recordPullRequest': { session, url: 'https://github.com/example/app/pull/7' },
+  };
+
+  return inputs[procedure] ?? {};
+}

package/src/test-utils/create-fake-caller-proof.ts

@@ -0,0 +1,18 @@
+import type { CallerIdentity, CallerProof } from '@boxxy/model';
+
+export interface FakeCallerProof extends CallerProof {
+  // who every later request is from; null proves no request
+  setCaller: (caller: CallerIdentity | null) => void;
+}
+
+// A proof that proves no request until the test names a caller.
+export function createFakeCallerProof(): FakeCallerProof {
+  let current: CallerIdentity | null = null;
+
+  return {
+    prove: () => Promise.resolve(current),
+    setCaller: (caller) => {
+      current = caller;
+    },
+  };
+}

package/src/test-utils/create-test-server.ts

@@ -0,0 +1,142 @@
+import type { FakeForge } from '@boxxy/dispatch/test-utils/create-fake-forge';
+import { createFakeForge } from '@boxxy/dispatch/test-utils/create-fake-forge';
+import type { TestDispatch } from '@boxxy/dispatch/test-utils/create-test-dispatch';
+import { createTestDispatch } from '@boxxy/dispatch/test-utils/create-test-dispatch';
+import type {
+  AttemptId,
+  AttemptRow,
+  CallerProof,
+  Clock,
+  PhaseName,
+  SessionReading,
+} from '@boxxy/model';
+import type { FakeNotifier } from '@boxxy/model/test-utils/create-fake-notifier';
+import { createFakeNotifier } from '@boxxy/model/test-utils/create-fake-notifier';
+import type { FakePepysReader } from '@boxxy/model/test-utils/create-fake-pepys-reader';
+import { createFakePepysReader } from '@boxxy/model/test-utils/create-fake-pepys-reader';
+import { buildExampleLoadInput } from '@boxxy/rules/test-utils/build-example-load-input';
+import invariant from 'tiny-invariant';
+import { buildTokenDigest } from '../auth/pick-request-scope.ts';
+import { createOffOutbox } from '../outbox/create-off-outbox.ts';
+import { makeProposedRulesLoader } from '../rules/load-server-rules.ts';
+import { serveApi } from '../serve-api.ts';
+import type { TickReport } from '../tick/run-tick.ts';
+import { runTick } from '../tick/run-tick.ts';
+import type { ServerDeps, ServerLog } from '../types.ts';
+import type { FakeCallerProof } from './create-fake-caller-proof.ts';
+import { createFakeCallerProof } from './create-fake-caller-proof.ts';
+
+export interface TestServerOptions {
+  // false: the server runs as one whose configuration has no pepys section
+  readonly hasPepys?: boolean;
+
+  // the server's real proof in place of the fake one, built on the test's clock; the fake that
+  // `callerProof` returns then proves nothing
+  readonly makeCallerProof?: (clock: Clock) => Promise<CallerProof>;
+}
+
+export interface TestServer {
+  // the store, clock, worker and rules behind the server, with their seeders
+  readonly dispatch: TestDispatch;
+  readonly callerProof: FakeCallerProof;
+  readonly pepys: FakePepysReader;
+  readonly notifier: FakeNotifier;
+  readonly forge: FakeForge;
+
+  // the token the worker listener takes
+  readonly workerToken: string;
+
+  // what the server logged, in order
+  readonly logged: readonly { readonly message: string; readonly fields: unknown }[];
+  readonly deps: ServerDeps;
+
+  // the two listeners, as fetch handlers
+  readonly owner: (request: Request) => Promise<Response>;
+  readonly worker: (request: Request) => Promise<Response>;
+
+  // one runner tick at the clock's time
+  readonly tick: () => Promise<TickReport>;
+
+  // an item at the phase, claimed and started by the fake worker; its row carries the caller
+  // that its session reports
+  readonly seedStartedAttempt: (phase: PhaseName) => Promise<AttemptRow>;
+}
+
+// The server's two listeners on the memory store, the fake worker, the fake clock, a fake pepys
+// reader, a fake notifier and a fake forge, with the example rules. No port is opened.
+export async function createTestServer(options: TestServerOptions = {}): Promise<TestServer> {
+  const dispatch = await createTestDispatch();
+
+  const callerProof = createFakeCallerProof();
+  const pepys = createFakePepysReader();
+  const notifier = createFakeNotifier();
+  const forge = createFakeForge();
+  const workerToken = 'test-worker-token';
+
+  const readings = new Map<AttemptId, SessionReading>();
+
+  const logged: { message: string; fields: unknown }[] = [];
+
+  const log: ServerLog = {
+    warn: (message, fields) => {
+      logged.push({ message, fields });
+    },
+  };
+
+  const deps: ServerDeps = {
+    store: dispatch.store,
+    runner: dispatch.runner,
+    rulesState: () => ({ rules: dispatch.rules(), lastRejected: null }),
+    loadProposedRules: makeProposedRulesLoader(buildExampleLoadInput().checkout),
+    clock: dispatch.clock,
+    newId: dispatch.newId,
+    callerProof:
+      options.makeCallerProof === undefined
+        ? callerProof
+        : await options.makeCallerProof(dispatch.clock),
+    workerTokenDigest: buildTokenDigest(workerToken),
+    pepys: options.hasPepys === false ? null : pepys,
+    forge,
+    outbox: createOffOutbox(dispatch.store, dispatch.clock),
+    readings,
+    log,
+  };
+
+  const listeners = serveApi(deps);
+
+  return {
+    dispatch,
+    callerProof,
+    pepys,
+    notifier,
+    forge,
+    workerToken,
+    logged,
+    deps,
+    owner: (request) => listeners.owner.handle(request),
+    worker: (request) => listeners.worker.handle(request),
+    tick: () =>
+      runTick({
+        store: dispatch.store,
+        runner: dispatch.runner,
+        worker: dispatch.worker,
+        rules: dispatch.rules(),
+        backoff: dispatch.backoff,
+        spawn: dispatch.spawn,
+        notifier,
+        now: dispatch.clock.now(),
+        newId: dispatch.newId,
+        readings,
+        log,
+      }),
+    seedStartedAttempt: async (phase) => {
+      await dispatch.seedItem({ phase });
+
+      const claim = await dispatch.claim();
+
+      invariant(claim !== null, 'the seeded item is claimed');
+
+      return dispatch.readAttempt(claim.attempt.id);
+    },
+  };
+}

package/src/test-utils/list-owner-procedures.ts

@@ -0,0 +1,38 @@
+import type { ProcedureName } from '@boxxy/contract';
+import { access } from '@boxxy/contract';
+
+// Every procedure that the owner calls, from the access table, one row each for `test.each`.
+export function listOwnerProcedures(): [ProcedureName][] {
+  return collectNames()
+    .filter((name) => access[name].caller === 'owner')
+    .map((name) => [name]);
+}
+
+// The MCP tool name of every procedure that `/mcp` lists.
+export function listOwnerTools(): [string][] {
+  return collectNames()
+    .filter((name) => access[name].tool === 'owner')
+    .map((name) => [toToolName(name)]);
+}
+
+// Every session and hook procedure.
+export function listSessionProcedures(): [ProcedureName][] {
+  return collectNames()
+    .filter((name) => access[name].caller !== 'owner')
+    .map((name) => [name]);
+}
+
+// The MCP tool name of every procedure that `/mcp/session` lists.
+export function listSessionTools(): [string][] {
+  return collectNames()
+    .filter((name) => access[name].tool === 'session')
+    .map((name) => [toToolName(name)]);
+}
+
+function collectNames(): ProcedureName[] {
+  return Object.keys(access).filter((name): name is ProcedureName => Object.hasOwn(access, name));
+}
+
+function toToolName(name: string): string {
+  return name.replace('.', '_').replaceAll(/[A-Z]/gu, (letter) => `_${letter.toLowerCase()}`);
+}

package/src/test-utils/read-mcp-answer.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+const answerSchema = z
+  .object({
+    result: z.record(z.string(), z.unknown()).optional(),
+    error: z.object({ code: z.number(), message: z.string() }).optional(),
+  })
+  .loose();
+
+export type MCPAnswer = z.infer<typeof answerSchema>;
+
+// The JSON-RPC answer of an MCP endpoint, from a JSON body or from the one event of a stream.
+export async function readMCPAnswer(response: Response): Promise<MCPAnswer> {
+  const text = await response.text();
+
+  const isStream = (response.headers.get('content-type') ?? '').startsWith('text/event-stream');
+
+  const json = isStream
+    ? (text
+        .split('\n')
+        .find((line) => line.startsWith('data: '))
+        ?.slice('data: '.length) ?? '')
+    : text;
+
+  return answerSchema.parse(JSON.parse(json));
+}

package/src/test-utils/wait-for.ts

@@ -0,0 +1,14 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+
+// Polls the check until it is true. Throws when it is still false after `timeoutMs`.
+export async function waitFor(check: () => boolean | Promise<boolean>, timeoutMs = 2000) {
+  const deadline = performance.now() + timeoutMs;
+
+  while (!(await check())) {
+    if (performance.now() > deadline) {
+      throw new Error(`the condition stayed false for ${timeoutMs} ms`);
+    }
+
+    await sleep(5);
+  }
+}