@wringer/core 0.0.0 → 0.1.1

package/src/read-stream-line-batches.ts

@@ -0,0 +1,28 @@
+export const streamLineCapChars = 64 * 1024;
+
+// Yields the whole lines of each chunk together, so a caller can handle a chunk's lines in one
+// step. A line longer than the cap keeps its first characters and drops the rest up to its
+// newline, so a source that prints without a newline cannot grow the buffer without bound.
+export async function* readStreamLineBatches(
+  stream: ReadableStream<Uint8Array>,
+): AsyncGenerator<readonly string[], void, undefined> {
+  const decoder = new TextDecoder();
+
+  let pending = '';
+
+  for await (const chunk of stream) {
+    const lines = `${pending}${decoder.decode(chunk, { stream: true })}`.split('\n');
+
+    pending = (lines.pop() ?? '').slice(0, streamLineCapChars);
+
+    if (lines.length > 0) {
+      yield lines.map((line) => line.slice(0, streamLineCapChars));
+    }
+  }
+
+  pending = `${pending}${decoder.decode()}`.slice(0, streamLineCapChars);
+
+  if (pending !== '') {
+    yield [pending];
+  }
+}

package/src/read-stream-lines.ts

@@ -0,0 +1,11 @@
+import { readStreamLineBatches } from './read-stream-line-batches.ts';
+
+export { streamLineCapChars } from './read-stream-line-batches.ts';
+
+export async function* readStreamLines(
+  stream: ReadableStream<Uint8Array>,
+): AsyncGenerator<string, void, undefined> {
+  for await (const batch of readStreamLineBatches(stream)) {
+    yield* batch;
+  }
+}

package/src/read-text.ts

@@ -0,0 +1,5 @@
+import { readFile } from 'node:fs/promises';
+
+export function readText(path: string): Promise<string> {
+  return readFile(path, 'utf8');
+}

package/src/read-verdicts.ts

@@ -0,0 +1,57 @@
+import { join } from 'node:path';
+import type { StatePort } from './create-file-state.ts';
+import type { Envelope } from './envelope.ts';
+import { verdictSchema } from './report-schema.ts';
+import type { Verdict } from './report-schema.ts';
+import type { RepoHost } from './types.ts';
+
+export const doneCommand = 'done';
+
+// Merges the verdicts of every run in the worktree: the latest `done` per feature wins.
+export async function readVerdicts(
+  state: StatePort,
+  host: Pick<RepoHost, 'readText'>,
+  root: string,
+): Promise<ReadonlyMap<string, Verdict>> {
+  const runs = await state.listRuns();
+  const events = await Promise.all(runs.map((runID) => state.readRunEvents(runID)));
+
+  const envelopes = events
+    .flat()
+    .flatMap((event) =>
+      event.type === 'envelope' && event.envelope.command === doneCommand && event.envelope.ok
+        ? [event.envelope]
+        : [],
+    );
+
+  const verdicts = await Promise.all(
+    envelopes.map((envelope) => readVerdict(host, envelope, root)),
+  );
+
+  const latest = new Map<string, Verdict>();
+
+  for (const verdict of verdicts
+    .flat()
+    .toSorted((left, right) => left.at.localeCompare(right.at))) {
+    latest.set(verdict.feature, verdict);
+  }
+
+  return latest;
+}
+
+// A verdict over the data cap sits in the payload file the envelope names, not in the envelope.
+async function readVerdict(
+  host: Pick<RepoHost, 'readText'>,
+  envelope: Envelope,
+  root: string,
+): Promise<readonly Verdict[]> {
+  const payload =
+    envelope.truncatedPath === undefined
+      ? null
+      : await host.readText(join(root, envelope.truncatedPath));
+
+  const data: unknown = payload === null ? envelope.data : JSON.parse(payload);
+  const parsed = verdictSchema.safeParse(data);
+
+  return parsed.success ? [parsed.data] : [];
+}

package/src/remove-directory.ts

@@ -0,0 +1,6 @@
+import { rm } from 'node:fs/promises';
+
+// Removes the folder and everything in it; a folder that is already gone is no error.
+export async function removeDirectory(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: true });
+}

package/src/remove-file.ts

@@ -0,0 +1,6 @@
+import { rm } from 'node:fs/promises';
+
+// A file that is already gone is no error.
+export async function removeFile(path: string): Promise<void> {
+  await rm(path, { force: true });
+}

package/src/render-report-markdown.ts

@@ -0,0 +1,53 @@
+import type { Report } from './report-schema.ts';
+
+export const reportBlockOpen = '<!-- wringer-report v1';
+export const reportBlockClose = '-->';
+
+const statusLabels = {
+  verified: 'verified',
+  stale: 'stale: verified at an older fingerprint',
+  missing: 'missing: no verdict',
+  unchanged: 'unchanged',
+} as const;
+
+// The readable summary comes first, then the JSON report in a hidden block that `gate` reads back.
+// JSON never holds `-->`, because every `>` in it is escaped.
+export function renderReportMarkdown(report: Report): string {
+  const lines = [
+    '## wringer report',
+    '',
+    `Fingerprint \`${report.fingerprint}\` against \`${report.base}\`: ${report.complete ? 'every changed feature is verified' : 'some changed features need a verdict'}.`,
+    '',
+    '| Feature | Status | Evidence |',
+    '| --- | --- | --- |',
+    ...report.features.map(
+      (feature) =>
+        `| ${feature.name} | ${statusLabels[feature.status]} | ${formatEvidence(feature.verdict?.evidence ?? [])} |`,
+    ),
+    '',
+    reportBlockOpen,
+    JSON.stringify(report).replaceAll('>', String.raw`\u003e`),
+    reportBlockClose,
+    '',
+  ];
+
+  return lines.join('\n');
+}
+
+function formatEvidence(
+  evidence: readonly {
+    readonly kind: string;
+    readonly path: string;
+    readonly url?: string | undefined;
+  }[],
+): string {
+  if (evidence.length === 0) {
+    return '-';
+  }
+
+  return evidence
+    .map((item) =>
+      item.url === undefined ? `${item.kind} \`${item.path}\`` : `[${item.kind}](${item.url})`,
+    )
+    .join(', ');
+}

package/src/report-schema.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { evidenceSchema } from './envelope.ts';
+
+const linkedEvidenceSchema = evidenceSchema.extend({ url: z.string().optional() });
+
+export const verdictSchema = z.strictObject({
+  feature: z.string(),
+  fingerprint: z.string(),
+  run: z.string(),
+  at: z.iso.datetime(),
+  evidence: z.array(linkedEvidenceSchema),
+});
+
+export type Verdict = z.infer<typeof verdictSchema>;
+
+const featureStatusSchema = z.enum(['verified', 'stale', 'missing', 'unchanged']);
+
+export type FeatureStatus = z.infer<typeof featureStatusSchema>;
+
+const featureReportSchema = z.strictObject({
+  name: z.string(),
+  changed: z.boolean(),
+  status: featureStatusSchema,
+  verdict: verdictSchema.nullable(),
+});
+
+// The report is the one contract that leaves the worktree: the PR body carries it, and `gate` reads
+// it back in CI. Its `version` changes only with a change a reader of an older report must handle.
+export const reportSchema = z.strictObject({
+  version: z.literal(1),
+  base: z.string(),
+  fingerprint: z.string(),
+  complete: z.boolean(),
+  features: z.array(featureReportSchema),
+});
+
+export type Report = z.infer<typeof reportSchema>;

package/src/run-events.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { envelopeSchema } from './envelope.ts';
+
+export const runIDSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{2,40}$/u);
+
+export type RunID = z.infer<typeof runIDSchema>;
+
+export const modeSchema = z.enum(['launch', 'attach']);
+
+export type Mode = z.infer<typeof modeSchema>;
+
+export const endpointsSchema = z.record(z.string(), z.string());
+
+export type Endpoints = z.infer<typeof endpointsSchema>;
+
+export const checkResultSchema = z.strictObject({
+  name: z.string(),
+  status: z.enum(['passed', 'failed']),
+  durationMs: z.number().int().nonnegative(),
+  code: z.string().nullable(),
+  message: z.string().nullable(),
+});
+
+export type CheckResult = z.infer<typeof checkResultSchema>;
+
+const at = z.iso.datetime();
+
+// A command's work that failed after the envelope had already answered with a timeout.
+export const lateFailureEventSchema = z.strictObject({
+  type: z.literal('late-failure'),
+  at,
+  command: z.string(),
+  code: z.string(),
+  message: z.string(),
+});
+
+export type LateFailureEvent = z.infer<typeof lateFailureEventSchema>;
+
+export const runEventSchema = z.discriminatedUnion('type', [
+  z.strictObject({
+    type: z.literal('run-started'),
+    at,
+    target: z.string(),
+    mode: modeSchema,
+    fingerprint: z.string(),
+  }),
+  z.strictObject({
+    type: z.literal('supervisor-ready'),
+    at,
+    pid: z.number().int(),
+    socket: z.string(),
+  }),
+  z.strictObject({ type: z.literal('launch-ready'), at, endpoints: endpointsSchema }),
+  z.strictObject({ type: z.literal('service-ready'), at, service: z.string() }),
+  z.strictObject({ type: z.literal('run-ready'), at }),
+  z.strictObject({
+    type: z.enum(['doctor-passed', 'doctor-failed']),
+    at,
+    results: z.array(checkResultSchema),
+  }),
+  z.strictObject({ type: z.literal('envelope'), at, drive: z.boolean(), envelope: envelopeSchema }),
+  z.strictObject({ type: z.literal('internal-error'), at, command: z.string(), stack: z.string() }),
+
+  lateFailureEventSchema,
+  z.strictObject({ type: z.literal('crashed'), at, reason: z.string() }),
+  z.strictObject({ type: z.literal('run-ended'), at }),
+]);
+
+export type RunEvent = z.infer<typeof runEventSchema>;
+
+export type RunEventType = RunEvent['type'];

package/src/run-git.ts

@@ -0,0 +1,49 @@
+import { runProcess, runProcessBytes } from './run-process.ts';
+import type { ProcessResult } from './run-process.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface GitRequest {
+  readonly cwd: string;
+  readonly args: readonly string[];
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  readonly stdin?: string | Uint8Array | undefined;
+}
+
+export async function runGit(request: GitRequest): Promise<ProcessResult> {
+  const result = await runProcess({
+    argv: ['git', ...request.args],
+    cwd: request.cwd,
+    env: request.env,
+    stdin: request.stdin,
+  });
+
+  if (result.exitCode !== 0) {
+    throw buildGitFailure(request, result.exitCode, result.stderr);
+  }
+
+  return result;
+}
+
+// Returns stdout as the bytes git wrote. A path or a line that is not UTF-8 would lose its bytes
+// in a decoded string.
+export async function runGitBytes(request: GitRequest): Promise<Uint8Array> {
+  const result = await runProcessBytes({
+    argv: ['git', ...request.args],
+    cwd: request.cwd,
+    env: request.env,
+    stdin: request.stdin,
+  });
+
+  if (result.exitCode !== 0) {
+    throw buildGitFailure(request, result.exitCode, result.stderr);
+  }
+
+  return result.stdout;
+}
+
+function buildGitFailure(request: GitRequest, exitCode: number, stderr: string): WringerError {
+  return new WringerError('environment', {
+    message: `git ${request.args[0] ?? ''} failed: ${stderr.trim()}`,
+    data: { exitCode, stderr },
+  });
+}

package/src/run-process.ts

@@ -0,0 +1,168 @@
+import { buildSpawnError } from './build-spawn-error.ts';
+import { killProcessGroup } from './kill-process-group.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface ProcessRequest {
+  readonly argv: readonly string[];
+  readonly cwd?: string | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly stdin?: string | Uint8Array | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+export interface ProcessResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export async function runProcess(request: ProcessRequest): Promise<ProcessResult> {
+  const result = await runProcessBytes(request);
+
+  return { ...result, stdout: new TextDecoder().decode(result.stdout) };
+}
+
+export interface ProcessBytesResult {
+  readonly exitCode: number;
+  readonly stdout: Uint8Array;
+  readonly stderr: string;
+}
+
+// Keeps stdout as the bytes the command wrote, for output that must reach another command unchanged.
+export async function runProcessBytes(request: ProcessRequest): Promise<ProcessBytesResult> {
+  const env = { ...process.env, ...request.env };
+  const cwd = request.cwd ?? process.cwd();
+  const [command] = request.argv;
+  const executable = resolveExecutable(command, { PATH: env['PATH'] ?? '', cwd });
+
+  const plan = pickProcessPlan({
+    argv: request.argv,
+    executable,
+    aborted: hasAborted(request.signal),
+  });
+
+  if (plan instanceof WringerError) {
+    throw plan;
+  }
+
+  const child = startProcess(plan, { cwd, env, stdin: request.stdin });
+
+  const killGroup = (): void => {
+    killProcessGroup(child.pid);
+  };
+
+  request.signal?.addEventListener('abort', killGroup, { once: true });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).bytes(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+
+  request.signal?.removeEventListener('abort', killGroup);
+
+  const outcome = pickProcessOutcome({
+    command: plan.command,
+    aborted: hasAborted(request.signal),
+    result: { exitCode, stdout, stderr },
+  });
+
+  if (outcome instanceof WringerError) {
+    throw outcome;
+  }
+
+  return outcome;
+}
+
+interface ExecutableSearch {
+  readonly PATH: string;
+  readonly cwd: string;
+}
+
+// Bun.which resolves a relative command against the folder it is given, so it must be the folder
+// the command runs in.
+function resolveExecutable(command: string | undefined, search: ExecutableSearch): string | null {
+  if (command === undefined) {
+    return null;
+  }
+
+  return Bun.which(command, search);
+}
+
+interface ProcessPlanInput {
+  readonly argv: readonly string[];
+  readonly executable: string | null;
+  readonly aborted: boolean;
+}
+
+interface ProcessPlan {
+  readonly command: string;
+  readonly argv: readonly string[];
+}
+
+function pickProcessPlan(input: ProcessPlanInput): ProcessPlan | WringerError {
+  const [command, ...args] = input.argv;
+
+  if (command === undefined) {
+    return new WringerError('usage', { message: 'An exec needs a command.' });
+  }
+
+  if (input.executable === null) {
+    return new WringerError('environment', {
+      message: `The command ${command} is not on the PATH.`,
+      hint: `Install ${command}, or put it on the PATH.`,
+    });
+  }
+
+  // Bun.spawn throws a plain AbortError on a signal that has already fired.
+  if (input.aborted) {
+    return new WringerError('timeout', {
+      message: `${command} did not start: its deadline had passed.`,
+    });
+  }
+
+  return { command, argv: [input.executable, ...args] };
+}
+
+function hasAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
+interface StartOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly stdin?: string | Uint8Array | undefined;
+}
+
+// The command runs in a process group of its own, so the deadline also stops a child it started,
+// which would otherwise hold the output pipes open past the deadline.
+function startProcess(plan: ProcessPlan, options: StartOptions) {
+  try {
+    return Bun.spawn([...plan.argv], {
+      cwd: options.cwd,
+      env: { ...options.env },
+      stdin: options.stdin === undefined ? 'ignore' : Buffer.from(options.stdin),
+      stdout: 'pipe',
+      stderr: 'pipe',
+      detached: true,
+    });
+  } catch (error) {
+    throw buildSpawnError(plan.command, error);
+  }
+}
+
+interface ProcessOutcomeInput {
+  readonly command: string;
+  readonly aborted: boolean;
+  readonly result: ProcessBytesResult;
+}
+
+function pickProcessOutcome(input: ProcessOutcomeInput): ProcessBytesResult | WringerError {
+  if (input.aborted) {
+    return new WringerError('timeout', {
+      message: `${input.command} ran past its deadline and was stopped.`,
+    });
+  }
+
+  return input.result;
+}

package/src/run-supervisor-process.ts

@@ -0,0 +1,51 @@
+import { launchReadyTimeoutMs } from './builtins/build-lifecycle-commands.ts';
+import { createRepoState } from './create-repo-state.ts';
+import { readLaunchHost } from './read-launch-host.ts';
+import { runSupervisor } from './run-supervisor.ts';
+import { appStopLimitMs } from './start-launch.ts';
+import { supervisorArgsSchema } from './supervisor-protocol.ts';
+import type { Wringer } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+// One cleanup's wait covers the app's longest stop, with a second to spare.
+const stopWaitMs = appStopLimitMs + 1000;
+
+// The entry of the supervisor process: argv is what follows the hidden command name. The process
+// exits once its run has stopped.
+export async function runSupervisorProcess(
+  wringer: Wringer,
+  argv: readonly string[],
+): Promise<void> {
+  const parsed = supervisorArgsSchema.safeParse(argv);
+
+  if (!parsed.success) {
+    throw new WringerError('usage', { message: 'The supervisor needs a run ID, target and root.' });
+  }
+
+  const signalled = new AbortController();
+
+  process.once('SIGTERM', () => {
+    signalled.abort();
+  });
+
+  process.once('SIGINT', () => {
+    signalled.abort();
+  });
+
+  await runSupervisor({
+    wringer,
+    launchHost: readLaunchHost(),
+    state: createRepoState(parsed.data.root, wringer.stateDir),
+    runID: parsed.data.runID,
+    target: parsed.data.target,
+    readyTimeoutMs: launchReadyTimeoutMs,
+    stopWaitMs,
+    now: () => new Date(),
+
+    // The process that starts the supervisor sends its stderr to the supervisor's log.
+    reportError: (message) => {
+      process.stderr.write(`${message}\n`);
+    },
+    signal: signalled.signal,
+  });
+}