@wringer/core 0.1.0 → 0.1.2

package/src/builtins/build-lifecycle-commands.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import { buildBuiltinCommand } from '../build-commands.ts';
+import type { BuiltinCommandSpec, RegisteredCommand } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+import { runDataSchema, startRun } from './start-run.ts';
+import type { RunData } from './start-run.ts';
+import { stopDataSchema } from './stop-data-schema.ts';
+import type { StopData } from './stop-data-schema.ts';
+import { stopRun } from './stop-run.ts';
+
+export const launchReadyTimeoutMs = 120_000;
+const startArgsSchema = z.strictObject({ restart: z.boolean().default(false) });
+
+type StartArgs = z.infer<typeof startArgsSchema>;
+
+// `up` and `down` own a launch target's app; `attach` and `detach` never stop an attach target's
+// app. None of them writes to the app, so all four run on a read-only target.
+export function buildLifecycleCommands(): readonly RegisteredCommand[] {
+  const up: BuiltinCommandSpec<StartArgs, RunData> = {
+    path: ['up'],
+    summary: 'Start a run of a launch target: its app, browser and stream recorders',
+    args: startArgsSchema,
+    data: runDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    timeoutMs: launchReadyTimeoutMs + 10_000,
+    run: (args, ctx) => {
+      if (ctx.target.mode !== 'launch') {
+        throw new WringerError('usage', {
+          message: `Target ${ctx.targetName} is an attach target.`,
+          hint: `Run \`attach --target ${ctx.targetName}\`.`,
+        });
+      }
+
+      return startRun(ctx, {
+        command: 'up',
+        restart: args.restart,
+        readyTimeoutMs: launchReadyTimeoutMs,
+      });
+    },
+  };
+
+  const attach: BuiltinCommandSpec<StartArgs, RunData> = {
+    path: ['attach'],
+    summary: "Start a run on an attach target's app, without owning the app",
+    args: startArgsSchema,
+    data: runDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    timeoutMs: launchReadyTimeoutMs + 10_000,
+    run: (args, ctx) => {
+      if (ctx.target.mode !== 'attach') {
+        throw new WringerError('usage', {
+          message: `Target ${ctx.targetName} is a launch target.`,
+          hint: `Run \`up --target ${ctx.targetName}\`.`,
+        });
+      }
+
+      return startRun(ctx, {
+        command: 'attach',
+        restart: args.restart,
+        readyTimeoutMs: launchReadyTimeoutMs,
+      });
+    },
+  };
+
+  const down: BuiltinCommandSpec<Record<string, never>, StopData> = {
+    path: ['down'],
+    summary: "Stop the launch target's run and its app",
+    args: z.strictObject({}),
+    data: stopDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: (_args, ctx) => {
+      if (ctx.target.mode !== 'launch') {
+        throw new WringerError('usage', {
+          message: `Target ${ctx.targetName} is an attach target.`,
+          hint: `Run \`detach --target ${ctx.targetName}\`.`,
+        });
+      }
+
+      return stopRun(ctx);
+    },
+  };
+
+  const detach: BuiltinCommandSpec<Record<string, never>, StopData> = {
+    path: ['detach'],
+    summary: "End the attach target's run, leaving its app running",
+    args: z.strictObject({}),
+    data: stopDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: (_args, ctx) => {
+      if (ctx.target.mode !== 'attach') {
+        throw new WringerError('usage', {
+          message: `Target ${ctx.targetName} is a launch target.`,
+          hint: `Run \`down --target ${ctx.targetName}\`.`,
+        });
+      }
+
+      return stopRun(ctx);
+    },
+  };
+
+  return [
+    buildBuiltinCommand(up),
+    buildBuiltinCommand(attach),
+    buildBuiltinCommand(down),
+    buildBuiltinCommand(detach),
+  ];
+}

package/src/builtins/build-state-commands.ts

@@ -0,0 +1,152 @@
+import { join, relative } from 'node:path';
+import { z } from 'zod';
+import { buildBuiltinCommand } from '../build-commands.ts';
+import { buildRunPaths } from '../build-state-paths.ts';
+import { findOwnValue } from '../find-own-value.ts';
+import { unassignedFeature } from '../open-drive.ts';
+import type { BuiltinCommandSpec, RegisteredCommand } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+import { buildUsePointers } from './build-use-pointers.ts';
+
+const statusDataSchema = z.strictObject({
+  target: z.string(),
+  mode: z.enum(['launch', 'attach']),
+  access: z.enum(['read-write', 'read-only']),
+  instance: z.string().nullable(),
+  status: z.enum(['none', 'starting', 'running', 'crashed', 'ended']),
+  doctor: z.enum(['none', 'passed', 'failed']),
+  feature: z.string().nullable(),
+  evidence: z.string().nullable(),
+  endpoints: z.record(z.string(), z.string()),
+  services: z.array(z.string()),
+  cursors: z.record(z.string(), z.number()),
+});
+
+type StatusData = z.infer<typeof statusDataSchema>;
+
+const useArgsSchema = z.strictObject({
+  feature: z.string().min(1).optional(),
+  target: z.string().min(1).optional(),
+});
+
+type UseArgs = z.infer<typeof useArgsSchema>;
+
+const useDataSchema = z.strictObject({
+  target: z.string().nullable(),
+  feature: z.string().nullable(),
+  cursors: z.record(z.string(), z.number()),
+});
+
+type UseData = z.infer<typeof useDataSchema>;
+
+const featureEntrySchema = z.strictObject({
+  name: z.string(),
+  summary: z.string(),
+  paths: z.array(z.string()),
+  current: z.boolean(),
+});
+
+const featuresDataSchema = z.strictObject({ features: z.array(featureEntrySchema) });
+
+type FeaturesData = z.infer<typeof featuresDataSchema>;
+
+// `status`, `use` and `features` read and set the worktree's own state, never the target's, so they
+// run without a run and on a read-only target.
+export function buildStateCommands(): readonly RegisteredCommand[] {
+  const status: BuiltinCommandSpec<Record<string, never>, StatusData> = {
+    path: ['status'],
+    summary:
+      'Show the target, its run, the doctor state, the feature, the evidence folder and cursors',
+    args: z.strictObject({}),
+    data: statusDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: async (_args, ctx) => {
+      const paths = ctx.run === undefined ? undefined : buildRunPaths(ctx.stateDir, ctx.run.runID);
+
+      return {
+        target: ctx.targetName,
+        mode: ctx.target.mode,
+        access: ctx.target.access,
+        instance: ctx.run?.runID ?? null,
+        status: ctx.run?.status ?? 'none',
+        doctor: ctx.run?.doctor ?? 'none',
+        feature: ctx.feature,
+        evidence:
+          paths === undefined
+            ? null
+            : relative(ctx.session.root, join(paths.features, ctx.feature ?? unassignedFeature)),
+        endpoints: ctx.run?.endpoints ?? {},
+        services: [...(ctx.run?.services ?? [])],
+        cursors: ctx.run === undefined ? {} : await ctx.state.readCursors(ctx.run.runID),
+      };
+    },
+  };
+
+  const use: BuiltinCommandSpec<UseArgs, UseData> = {
+    path: ['use'],
+    summary: 'Set the current feature or target for later commands',
+    args: useArgsSchema,
+    data: useDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: async (args, ctx) => {
+      if (
+        args.feature !== undefined &&
+        !ctx.wringer.features.some((feature) => feature.name === args.feature)
+      ) {
+        throw new WringerError('usage', {
+          message: `The feature map has no feature named ${args.feature}.`,
+          hint: 'Run `features` to list them.',
+        });
+      }
+
+      if (args.target !== undefined && !ctx.wringer.targets.has(args.target)) {
+        throw new WringerError('usage', {
+          message: `The repo has no target named ${args.target}.`,
+        });
+      }
+
+      // The cursors belong to the target the pointers name after this command, which `--target`
+      // may change.
+      const before = await ctx.state.readPointers();
+
+      const runID = findOwnValue(before.currentRun, args.target ?? ctx.targetName);
+      const cursors = runID === undefined ? {} : await ctx.state.readCursors(runID);
+
+      const pointers = await ctx.state.writePointers((current) =>
+        buildUsePointers(current, {
+          target: args.target,
+          feature: args.feature,
+          cursors,
+          runID,
+        }),
+      );
+
+      return { target: pointers.target ?? null, feature: pointers.feature ?? null, cursors };
+    },
+  };
+
+  const features: BuiltinCommandSpec<Record<string, never>, FeaturesData> = {
+    path: ['features'],
+    summary: "List the repo's feature map, with each feature's paths",
+    args: z.strictObject({}),
+    data: featuresDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: (_args, ctx) =>
+      Promise.resolve({
+        features: ctx.wringer.features.map((feature) => ({
+          name: feature.name,
+          summary: feature.summary,
+          paths: [...feature.paths],
+          current: feature.name === ctx.feature,
+        })),
+      }),
+  };
+
+  return [buildBuiltinCommand(status), buildBuiltinCommand(use), buildBuiltinCommand(features)];
+}

package/src/builtins/build-use-pointers.ts

@@ -0,0 +1,26 @@
+import type { Pointers } from '../create-file-state.ts';
+import type { RunID } from '../run-events.ts';
+
+export interface UseChange {
+  readonly target: string | undefined;
+  readonly feature: string | undefined;
+
+  // The cursors of the run the pointers name after the change, or none when it names no run.
+  readonly cursors: Readonly<Record<string, number>>;
+  readonly runID: RunID | undefined;
+}
+
+// `use` keeps each pointer it is not given, and replaces the cursors with those of the run the
+// new target points at.
+export function buildUsePointers(current: Pointers, change: UseChange): Pointers {
+  const target = change.target ?? current.target;
+  const feature = change.feature ?? current.feature;
+
+  return {
+    currentRun: current.currentRun,
+    ...(target === undefined ? {} : { target }),
+    ...(feature === undefined ? {} : { feature }),
+    cursors: { ...change.cursors },
+    ...(change.runID === undefined ? {} : { cursorsRun: change.runID }),
+  };
+}

package/src/builtins/build-verdict-commands.ts

@@ -0,0 +1,266 @@
+import { isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+import { buildBuiltinCommand } from '../build-commands.ts';
+import { buildReport } from '../build-report.ts';
+import type { Evidence } from '../envelope.ts';
+import { parseReportBlock } from '../parse-report-block.ts';
+import { readChangedPaths } from '../read-changed-paths.ts';
+import { readDefaultBase } from '../read-default-base.ts';
+import { readFingerprint } from '../read-fingerprint.ts';
+import { doneCommand, readVerdicts } from '../read-verdicts.ts';
+import { renderReportMarkdown } from '../render-report-markdown.ts';
+import { reportSchema, verdictSchema } from '../report-schema.ts';
+import type { Report, Verdict } from '../report-schema.ts';
+import type { BuiltinCommandSpec, BuiltinContext, RegisteredCommand } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+
+const doneArgsSchema = z.strictObject({
+  feature: z.string().min(1).optional(),
+  base: z.string().min(1).optional(),
+});
+
+type DoneArgs = z.infer<typeof doneArgsSchema>;
+
+const reportArgsSchema = z.strictObject({ base: z.string().min(1).optional() });
+
+type ReportArgs = z.infer<typeof reportArgsSchema>;
+
+const reportDataSchema = z.strictObject({ report: reportSchema, markdown: z.string() });
+
+type ReportData = z.infer<typeof reportDataSchema>;
+
+const gateArgsSchema = z.strictObject({ base: z.string().min(1), bodyFile: z.string().min(1) });
+
+type GateArgs = z.infer<typeof gateArgsSchema>;
+
+const gateFailureSchema = z.strictObject({ name: z.string(), reason: z.string() });
+
+const gateDataSchema = z.strictObject({
+  fingerprint: z.string(),
+  failing: z.array(gateFailureSchema),
+});
+
+type GateData = z.infer<typeof gateDataSchema>;
+
+// `done` turns the evidence of one run into a verdict, `report` merges every verdict of the worktree
+// for the PR body, and `gate` checks that report again in CI, with a fingerprint it computes itself.
+export function buildVerdictCommands(): readonly RegisteredCommand[] {
+  const done: BuiltinCommandSpec<DoneArgs, Verdict> = {
+    path: [doneCommand],
+    summary:
+      'Record a verdict for a feature from its commands that touched the app since the doctor passed',
+    args: doneArgsSchema,
+    data: verdictSchema,
+    effect: 'read',
+    needsRun: true,
+    needsDoctor: false,
+    run: (args, ctx) => recordVerdict(args, ctx),
+  };
+
+  const report: BuiltinCommandSpec<ReportArgs, ReportData> = {
+    path: ['report'],
+    summary: 'Merge the verdicts into a report: JSON for a gate, Markdown with --human for the PR',
+    args: reportArgsSchema,
+    data: reportDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: async (args, ctx) => {
+      const built = await readReport(ctx, args.base);
+      const linked = await linkEvidence(ctx, built);
+
+      return { report: linked, markdown: renderReportMarkdown(linked) };
+    },
+  };
+
+  const gate: BuiltinCommandSpec<GateArgs, GateData> = {
+    path: ['gate'],
+    summary:
+      'Fail when a changed feature lacks a verdict at the current fingerprint in the PR body',
+    args: gateArgsSchema,
+    data: gateDataSchema,
+    effect: 'read',
+    needsRun: false,
+    needsDoctor: false,
+    run: (args, ctx) => checkGate(args, ctx),
+  };
+
+  return [buildBuiltinCommand(done), buildBuiltinCommand(report), buildBuiltinCommand(gate)];
+}
+
+async function recordVerdict(args: DoneArgs, ctx: BuiltinContext): Promise<Verdict> {
+  const feature = args.feature ?? ctx.feature;
+
+  if (feature === null) {
+    throw new WringerError('usage', {
+      message: 'No feature is set.',
+      hint: 'Pass `--feature <name>`, or run `use --feature <name>` first.',
+    });
+  }
+
+  if (ctx.run?.doctor !== 'passed') {
+    throw new WringerError('doctor-required', {
+      message: `The doctor has not passed on run ${ctx.run?.runID ?? 'none'}.`,
+      hint: 'Run `doctor`, then drive the feature again.',
+    });
+  }
+
+  // The run took its fingerprint against the default base, so the tree check uses that base; the
+  // verdict takes the base the PR's gate will use.
+  const defaultBase = await readDefaultBase(ctx.session.repoHost, ctx.session.root);
+  const treeFingerprint = await readCurrentFingerprint(ctx, defaultBase);
+
+  if (ctx.target.mode === 'launch' && treeFingerprint !== ctx.run.fingerprint) {
+    throw new WringerError('doctor-required', {
+      message: 'The working tree changed since this run started.',
+      hint: 'Run `up --restart` and `doctor`, then drive the feature again.',
+    });
+  }
+
+  const drives = ctx.run.drivesAfterDoctor.filter((envelope) => envelope.feature === feature);
+
+  if (drives.length === 0) {
+    throw new WringerError('check-failed', {
+      message: `No command of ${feature} that touches the app passed on run ${ctx.run.runID} since the doctor passed.`,
+      hint: `Drive the feature with \`--feature ${feature}\`, then run \`done\` again.`,
+    });
+  }
+
+  const fingerprint =
+    args.base === undefined || args.base === defaultBase
+      ? treeFingerprint
+      : await readCurrentFingerprint(ctx, args.base);
+
+  return {
+    feature,
+    fingerprint,
+    run: ctx.run.runID,
+    at: ctx.now().toISOString(),
+    evidence: drives.flatMap((envelope) => envelope.evidence),
+  };
+}
+
+function readCurrentFingerprint(ctx: BuiltinContext, base: string): Promise<string> {
+  return readFingerprint(ctx.session.repoHost, {
+    cwd: ctx.session.root,
+    base,
+    exclude: [ctx.wringer.stateDir],
+  });
+}
+
+async function readReport(ctx: BuiltinContext, givenBase: string | undefined): Promise<Report> {
+  const base = await readBase(ctx, givenBase);
+
+  const [fingerprint, changedPaths, verdicts] = await Promise.all([
+    readCurrentFingerprint(ctx, base),
+    readChangedPaths(ctx.session.repoHost, {
+      cwd: ctx.session.root,
+      base,
+      exclude: [ctx.wringer.stateDir],
+    }),
+    readVerdicts(ctx.state, ctx.session.repoHost, ctx.session.root),
+  ]);
+
+  return buildReport({ base, fingerprint, features: ctx.wringer.features, changedPaths, verdicts });
+}
+
+function readBase(ctx: BuiltinContext, givenBase: string | undefined): Promise<string> {
+  if (givenBase !== undefined) {
+    return Promise.resolve(givenBase);
+  }
+
+  return readDefaultBase(ctx.session.repoHost, ctx.session.root);
+}
+
+// The repo's upload hook turns each local evidence file into a link; the local files never leave
+// the worktree otherwise.
+async function linkEvidence(ctx: BuiltinContext, report: Report): Promise<Report> {
+  const upload = ctx.wringer.hooks.upload;
+
+  if (upload === undefined) {
+    return report;
+  }
+
+  const link = async (evidence: Evidence): Promise<Evidence & { readonly url?: string }> => ({
+    ...evidence,
+    url: await upload({ ...evidence, path: join(ctx.session.root, evidence.path) }),
+  });
+
+  const features = await Promise.all(
+    report.features.map(async (feature) => {
+      if (feature.verdict === null || feature.status !== 'verified') {
+        return feature;
+      }
+
+      const evidence = await Promise.all(feature.verdict.evidence.map((item) => link(item)));
+
+      return { ...feature, verdict: { ...feature.verdict, evidence } };
+    }),
+  );
+
+  return { ...report, features };
+}
+
+async function checkGate(args: GateArgs, ctx: BuiltinContext): Promise<GateData> {
+  const bodyPath = isAbsolute(args.bodyFile)
+    ? args.bodyFile
+    : join(ctx.session.root, args.bodyFile);
+
+  const body = await ctx.session.repoHost.readText(bodyPath);
+
+  const block = parseReportBlock(body);
+
+  const [fingerprint, changedPaths] = await Promise.all([
+    readCurrentFingerprint(ctx, args.base),
+    readChangedPaths(ctx.session.repoHost, {
+      cwd: ctx.session.root,
+      base: args.base,
+      exclude: [ctx.wringer.stateDir],
+    }),
+  ]);
+
+  const claimed = block.ok
+    ? block.report.features.flatMap((feature) =>
+        feature.verdict === null ? [] : [[feature.name, feature.verdict] as const],
+      )
+    : [];
+
+  const verdicts = new Map(claimed);
+
+  const computed = buildReport({
+    base: args.base,
+    fingerprint,
+    features: ctx.wringer.features,
+    changedPaths,
+    verdicts,
+  });
+
+  const failing = computed.features.flatMap((feature) => {
+    if (feature.status === 'missing') {
+      return [{ name: feature.name, reason: block.ok ? 'no verdict in the report' : block.reason }];
+    }
+
+    if (feature.status === 'stale') {
+      return [
+        {
+          name: feature.name,
+          reason: `verdict at ${feature.verdict?.fingerprint ?? ''}, tree at ${fingerprint}`,
+        },
+      ];
+    }
+
+    return [];
+  });
+
+  const data = { fingerprint, failing };
+
+  if (failing.length > 0) {
+    throw new WringerError('check-failed', {
+      message: `${failing.length} changed feature(s) lack a verdict at the current fingerprint: ${failing.map((feature) => feature.name).join(', ')}.`,
+      hint: 'Drive each feature, run `done` and `report --human`, and update the PR body.',
+      data,
+    });
+  }
+
+  return data;
+}

package/src/builtins/call-run-supervisor.ts

@@ -0,0 +1,40 @@
+import type { RunView } from '../build-run-view.ts';
+import { supervisorServiceName } from '../supervisor-protocol.ts';
+import type { SupervisorPort } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+
+export type SupervisorReach = 'answered' | 'gone';
+
+// `gone` only when nothing listens on the run's socket, or the run never got one. A call that times
+// out or fails in any other way may still reach a live supervisor later, so it rejects, and the
+// caller leaves the run as it is.
+export async function callRunSupervisor(
+  supervisor: SupervisorPort,
+  run: RunView,
+  method: 'ping' | 'stop',
+  signal: AbortSignal,
+): Promise<SupervisorReach> {
+  if (run.supervisor === null) {
+    return 'gone';
+  }
+
+  try {
+    await supervisor.call({
+      socket: run.supervisor.socket,
+      request: { service: supervisorServiceName, method, args: null },
+      signal,
+    });
+
+    return 'answered';
+  } catch (error) {
+    if (isSupervisorGone(error)) {
+      return 'gone';
+    }
+
+    throw error;
+  }
+}
+
+export function isSupervisorGone(error: unknown): boolean {
+  return error instanceof WringerError && error.code === 'not-running';
+}

package/src/builtins/pick-doctor-outcome.ts

@@ -0,0 +1,32 @@
+import type { CheckResult, RunEvent } from '../run-events.ts';
+import { WringerError } from '../wringer-error.ts';
+
+interface DoctorData {
+  readonly passed: boolean;
+  readonly results: CheckResult[];
+}
+
+export interface DoctorOutcome {
+  readonly event: RunEvent;
+  readonly data: DoctorData;
+
+  // Thrown after the event is written, so a failed doctor still lands in the run's log.
+  readonly failure: WringerError | null;
+}
+
+export function pickDoctorOutcome(results: readonly CheckResult[], at: string): DoctorOutcome {
+  const passed = results.every((result) => result.status === 'passed');
+  const data = { passed, results: [...results] };
+  const failed = results.filter((result) => result.status === 'failed');
+
+  return {
+    event: { type: passed ? 'doctor-passed' : 'doctor-failed', at, results: data.results },
+    data,
+    failure: passed
+      ? null
+      : new WringerError('check-failed', {
+          message: `The doctor failed: ${failed.map((result) => result.name).join(', ')}.`,
+          data,
+        }),
+  };
+}

package/src/builtins/pick-start-action.ts

@@ -0,0 +1,35 @@
+import type { RunStatus } from '../append-run-event.ts';
+import type { SupervisorReach } from './call-run-supervisor.ts';
+
+// What `up` has learned so far: the current run's status, and the answers of each call it made.
+export interface StartFacts {
+  readonly status: RunStatus | null;
+  readonly restart: boolean;
+  readonly ping: SupervisorReach | null;
+  readonly stop: SupervisorReach | null;
+}
+
+export type StartAction = 'ping' | 'stop' | 'reuse' | 'mark-crashed' | 'start';
+
+// `up` calls this after each step until it reuses the run or starts a new one. A run still
+// starting is one an earlier `up` gave up waiting for; it is replaced, never reused, so its app and
+// services are stopped first. A run whose supervisor is gone is marked crashed before the new start.
+export function pickStartAction(facts: StartFacts): StartAction {
+  if (facts.status !== 'running' && facts.status !== 'starting') {
+    return 'start';
+  }
+
+  if (facts.ping === null) {
+    return 'ping';
+  }
+
+  if (facts.ping === 'gone' || facts.stop === 'gone') {
+    return 'mark-crashed';
+  }
+
+  if (facts.status === 'running' && !facts.restart) {
+    return 'reuse';
+  }
+
+  return facts.stop === null ? 'stop' : 'start';
+}