@wringer/core 0.1.0 → 0.1.2

package/src/open-drive.ts

@@ -0,0 +1,151 @@
+import { join } from 'node:path';
+import { buildRunHandle } from './build-run-handle.ts';
+import type { RunView } from './build-run-view.ts';
+import { buildServiceKey } from './build-service-key.ts';
+import { collectDriverConfigs } from './collect-driver-configs.ts';
+import { createEvidenceWriter } from './create-evidence-writer.ts';
+import type { Access } from './host.ts';
+import { makeFence } from './make-fence.ts';
+import { makeDriverExec, makeRepoExec } from './make-fenced-exec.ts';
+import type {
+  Drive,
+  Emit,
+  EvidenceFiles,
+  OpenedDriver,
+  SupervisorPort,
+  TargetDefinition,
+  Wringer,
+} from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface DriveRequest {
+  readonly wringer: Wringer;
+  readonly root: string;
+  readonly stateDir: string;
+  readonly targetName: string;
+  readonly target: TargetDefinition;
+  readonly access: Access;
+  readonly hint: string;
+  readonly run: RunView;
+  readonly feature: string | null;
+  readonly cursors: Readonly<Record<string, number>>;
+  readonly signal: AbortSignal;
+
+  // When `signal` fires, in ms since the epoch on the `now` clock.
+  readonly deadlineAt: number;
+  readonly now: () => Date;
+  readonly emit: Emit;
+  readonly files: EvidenceFiles;
+  readonly callSupervisor: SupervisorPort['call'];
+}
+
+export const unassignedFeature = 'unassigned';
+
+// Every client and exec handed to a command body goes through the fence for `access`, so a body
+// that writes on a read-only target is refused at the call, whatever the command declared.
+export function openDrive(request: DriveRequest): Drive {
+  const run = buildRunHandle(request.stateDir, request.run.runID);
+
+  const evidence = createEvidenceWriter({
+    root: request.root,
+    directory: join(run.paths.features, request.feature ?? unassignedFeature),
+    now: request.now,
+    files: request.files,
+  });
+
+  const execOptions = {
+    host: request.target.host,
+    access: request.access,
+    hint: request.hint,
+    signal: request.signal,
+  };
+
+  const fence = makeFence({ access: request.access, hint: request.hint });
+
+  const entries = collectDriverConfigs(request.wringer, request.target, {
+    target: request.targetName,
+    endpoints: request.run.endpoints,
+    run,
+  });
+
+  const drivers = new Map<string, OpenedDriver>(
+    entries.map((entry) => [
+      entry.name,
+      entry.configured.open({
+        target: request.targetName,
+        access: request.access,
+        endpoints: request.run.endpoints,
+        run,
+        exec: makeDriverExec(execOptions),
+        evidence: evidence.writer,
+        cursors: request.cursors,
+        signal: request.signal,
+        timeLeftMs: () => Math.max(0, request.deadlineAt - request.now().getTime()),
+        fence,
+        service: (service) => ({
+          call: (method, args) =>
+            request.callSupervisor({
+              socket: getSocket(request.run),
+              request: {
+                service: buildServiceKey(entry.name, service),
+                method,
+                args,
+                deadlineAt: request.deadlineAt,
+              },
+              signal: request.signal,
+            }),
+        }),
+      }),
+    ]),
+  );
+
+  const clients = Object.fromEntries(
+    request.wringer.drivers.map((driver) => [
+      driver.name,
+      drivers.get(driver.name)?.client ?? buildMissingClient(driver.name, request.targetName),
+    ]),
+  );
+
+  return {
+    drivers,
+    evidence: evidence.collected,
+    ctx: {
+      target: request.targetName,
+      access: request.access,
+      feature: request.feature,
+      endpoints: request.run.endpoints,
+      drivers: clients,
+      exec: makeRepoExec(execOptions),
+      evidence: evidence.writer,
+      signal: request.signal,
+      emit: request.emit,
+    },
+  };
+}
+
+function getSocket(run: RunView): string {
+  if (run.supervisor === null) {
+    throw new WringerError('not-running', {
+      message: 'The run has no supervisor.',
+      hint: 'Run `up --restart`, or `attach` again, to start a new run.',
+    });
+  }
+
+  return run.supervisor.socket;
+}
+
+// A target that gives a driver no config still gets an entry for it, so repo code typed against
+// every driver reaches a clear refusal at the first call instead of reading undefined.
+function buildMissingClient(driver: string, target: string): unknown {
+  return new Proxy(
+    {},
+    {
+      get: () => {
+        throw new WringerError('usage', {
+          message: `Target ${target} gives the ${driver} driver no config.`,
+          hint: `Add a ${driver} entry to the drivers of target ${target}.`,
+        });
+      },
+    },
+  );
+}

package/src/open-runless-drive.ts

@@ -0,0 +1,71 @@
+import { join } from 'node:path';
+import { createEvidenceWriter } from './create-evidence-writer.ts';
+import type { Access } from './host.ts';
+import { makeRepoExec } from './make-fenced-exec.ts';
+import type { Drive, Emit, EvidenceFiles, TargetDefinition, Wringer } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface RunlessDriveRequest {
+  readonly wringer: Wringer;
+  readonly root: string;
+  readonly stateDir: string;
+  readonly targetName: string;
+  readonly target: TargetDefinition;
+  readonly access: Access;
+  readonly hint: string;
+  readonly feature: string | null;
+  readonly signal: AbortSignal;
+  readonly now: () => Date;
+  readonly emit: Emit;
+  readonly files: EvidenceFiles;
+}
+
+// A repo command that declares it needs no run still gets the fenced exec and an evidence folder.
+// Its driver clients refuse at the first call, because no run holds their services.
+export function openRunlessDrive(request: RunlessDriveRequest): Drive {
+  const evidence = createEvidenceWriter({
+    root: request.root,
+    directory: join(request.stateDir, 'payloads'),
+    now: request.now,
+    files: request.files,
+  });
+
+  const clients = Object.fromEntries(
+    request.wringer.drivers.map((driver) => [driver.name, buildRunlessClient(driver.name)]),
+  );
+
+  return {
+    drivers: new Map(),
+    evidence: evidence.collected,
+    ctx: {
+      target: request.targetName,
+      access: request.access,
+      feature: request.feature,
+      endpoints: {},
+      drivers: clients,
+      exec: makeRepoExec({
+        host: request.target.host,
+        access: request.access,
+        hint: request.hint,
+        signal: request.signal,
+      }),
+      evidence: evidence.writer,
+      signal: request.signal,
+      emit: request.emit,
+    },
+  };
+}
+
+function buildRunlessClient(driver: string): unknown {
+  return new Proxy(
+    {},
+    {
+      get: () => {
+        throw new WringerError('not-running', {
+          message: `The ${driver} driver needs a running run, and this command runs without one.`,
+          hint: 'Set `needsRun` on the command, or start a run with `up` or `attach`.',
+        });
+      },
+    },
+  );
+}

package/src/parse-launch-line.ts

@@ -0,0 +1,19 @@
+import type { LaunchLine } from './launch-line-schema.ts';
+import { launchLineSchema } from './launch-line-schema.ts';
+
+// A line that holds no JSON object, such as plain text or a JSON array, reaches `ready` as its text.
+export function parseLaunchLine(line: string): LaunchLine {
+  const parsed = launchLineSchema.safeParse(parseJSON(line));
+
+  return parsed.success ? parsed.data : { message: line };
+}
+
+function parseJSON(line: string): unknown {
+  try {
+    const parsed: unknown = JSON.parse(line);
+
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}

package/src/parse-patch-id.ts

@@ -0,0 +1,8 @@
+export const emptyFingerprint = 'empty';
+
+// `patch-id` prints the ID and the commit it read, or nothing for an empty diff.
+export function parsePatchID(stdout: string): string {
+  const [patchID = ''] = stdout.trim().split(' ');
+
+  return patchID === '' ? emptyFingerprint : patchID;
+}

package/src/parse-report-block.ts

@@ -0,0 +1,39 @@
+import { reportBlockClose, reportBlockOpen } from './render-report-markdown.ts';
+import { reportSchema } from './report-schema.ts';
+import type { Report } from './report-schema.ts';
+
+export type ReportBlockResult =
+  | { readonly ok: true; readonly report: Report }
+  | { readonly ok: false; readonly reason: string };
+
+export function parseReportBlock(body: string): ReportBlockResult {
+  const start = body.lastIndexOf(reportBlockOpen);
+
+  if (start === -1) {
+    return { ok: false, reason: 'The PR body holds no wringer report block.' };
+  }
+
+  const end = body.indexOf(reportBlockClose, start + reportBlockOpen.length);
+
+  if (end === -1) {
+    return { ok: false, reason: 'The wringer report block in the PR body is not closed.' };
+  }
+
+  const text = body.slice(start + reportBlockOpen.length, end).trim();
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: 'The wringer report block does not hold valid JSON.' };
+  }
+
+  const report = reportSchema.safeParse(parsed);
+
+  return report.success
+    ? { ok: true, report: report.data }
+    : {
+        ok: false,
+        reason: `The wringer report block does not match the report schema: ${report.error.message}`,
+      };
+}

package/src/parse-run-log.ts

@@ -0,0 +1,34 @@
+import { runEventSchema } from './run-events.ts';
+import type { RunEvent } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+
+// An event counts once its line ends: the next append cuts a last line with no newline, even one
+// that parses, so a reader skips it too. A whole line that is no event is corruption.
+export function parseRunLog(text: string): readonly RunEvent[] {
+  const lines = text
+    .slice(0, text.lastIndexOf('\n') + 1)
+    .split('\n')
+    .slice(0, -1);
+
+  return lines.map((line, index) => {
+    const parsed = runEventSchema.safeParse(parseJSONLine(line));
+
+    if (!parsed.success) {
+      throw new WringerError('environment', {
+        message: `The run log is corrupt: line ${index + 1} is not a run event.`,
+      });
+    }
+
+    return parsed.data;
+  });
+}
+
+function parseJSONLine(line: string): unknown {
+  try {
+    const parsed: unknown = JSON.parse(line);
+
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}

package/src/pick-access-refusal.ts

@@ -0,0 +1,32 @@
+import type { Access } from './host.ts';
+import type { Effect } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface AccessInput {
+  readonly path: readonly string[];
+  readonly allowedTargets: readonly string[] | undefined;
+  readonly targetName: string;
+  readonly access: Access;
+  readonly effect: Effect;
+  readonly hint: string;
+}
+
+// A repo command may name the only targets it runs on, and a read-only target takes only reads.
+export function pickAccessRefusal(input: AccessInput): WringerError | null {
+  const commandText = `\`${input.path.join(' ')}\``;
+
+  if (input.allowedTargets !== undefined && !input.allowedTargets.includes(input.targetName)) {
+    return new WringerError('target-not-allowed', {
+      message: `${commandText} runs only on ${input.allowedTargets.join(', ')}.`,
+    });
+  }
+
+  if (input.access === 'read-only' && input.effect !== 'read') {
+    return new WringerError('read-only', {
+      message: `${commandText} is a write, and target ${input.targetName} is read-only.`,
+      hint: input.hint,
+    });
+  }
+
+  return null;
+}

package/src/pick-command-needs.ts

@@ -0,0 +1,29 @@
+import type { DoctorState } from './build-run-view.ts';
+import type { Mode } from './run-events.ts';
+
+export interface CommandNeedsFacts {
+  readonly isBuiltin: boolean;
+  readonly needsRun: boolean | undefined;
+  readonly needsDoctor: boolean | undefined;
+  readonly mode: Mode;
+  readonly doctor: DoctorState | undefined;
+}
+
+export interface CommandNeeds {
+  readonly needsRun: boolean;
+  readonly needsDoctor: boolean;
+  readonly readsFingerprint: boolean;
+}
+
+// A command that declares nothing needs a run and a doctor pass unless it is a built-in. A launched
+// app runs this worktree's code, so only a doctor pass on a launched run needs the fingerprint.
+export function pickCommandNeeds(facts: CommandNeedsFacts): CommandNeeds {
+  const needsRun = facts.needsRun ?? !facts.isBuiltin;
+  const needsDoctor = facts.needsDoctor ?? !facts.isBuiltin;
+
+  return {
+    needsRun,
+    needsDoctor,
+    readsFingerprint: needsDoctor && facts.mode === 'launch' && facts.doctor === 'passed',
+  };
+}

package/src/pick-command-plan.ts

@@ -0,0 +1,51 @@
+import type { RunView } from './build-run-view.ts';
+import { decideGuard } from './decide-guard.ts';
+import { pickDriveKind } from './pick-drive-kind.ts';
+import type { DriveKind } from './pick-drive-kind.ts';
+import type { Mode } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface CommandFacts {
+  readonly needsRun: boolean;
+  readonly needsDoctor: boolean;
+  readonly isRepoCommand: boolean;
+  readonly run: RunView | undefined;
+  readonly targetName: string;
+  readonly mode: Mode;
+  readonly fingerprintChanged: boolean;
+  readonly deadlinePassed: boolean;
+}
+
+export type CommandPlan =
+  | { readonly kind: 'refuse'; readonly failure: WringerError }
+  | {
+      readonly kind: 'run';
+      readonly driveKind: DriveKind;
+
+      // The command drives the app, so its envelope goes into the run's log as a drive.
+      readonly drive: boolean;
+    };
+
+// The envelope answers at the deadline without waiting for the command, so a body that would start
+// after it never starts.
+export function pickCommandPlan(facts: CommandFacts): CommandPlan {
+  const refusal = decideGuard(facts);
+
+  if (refusal !== null) {
+    return { kind: 'refuse', failure: refusal };
+  }
+
+  if (facts.deadlinePassed) {
+    return { kind: 'refuse', failure: new WringerError('timeout') };
+  }
+
+  return {
+    kind: 'run',
+    driveKind: pickDriveKind({
+      runStatus: facts.run?.status ?? null,
+      needsRun: facts.needsRun,
+      isRepoCommand: facts.isRepoCommand,
+    }),
+    drive: facts.needsRun && facts.needsDoctor,
+  };
+}

package/src/pick-context-target.ts

@@ -0,0 +1,22 @@
+export interface ContextTargetInput {
+  readonly targetNames: readonly string[];
+  readonly sessionTarget: string | undefined;
+  readonly savedTarget: string | undefined;
+  readonly commandKey: string;
+}
+
+// The target a command runs against: the one the session names, else the saved one, else the first.
+// A saved target the registry no longer has stays an error for every command but `use`, which skips
+// it, so `use --target` can always choose again.
+export function pickContextTarget(input: ContextTargetInput): string {
+  const [firstTarget = ''] = input.targetNames;
+
+  const savedTarget =
+    input.commandKey === 'use' &&
+    input.savedTarget !== undefined &&
+    !input.targetNames.includes(input.savedTarget)
+      ? undefined
+      : input.savedTarget;
+
+  return input.sessionTarget ?? savedTarget ?? firstTarget;
+}

package/src/pick-drive-kind.ts

@@ -0,0 +1,23 @@
+import type { RunStatus } from './append-run-event.ts';
+
+export interface DriveFacts {
+  readonly runStatus: RunStatus | null;
+  readonly needsRun: boolean;
+  readonly isRepoCommand: boolean;
+}
+
+export type DriveKind = 'run' | 'runless' | 'none';
+
+// A command that needs a run drives it, and so does a repo command that needs none while a run is
+// running, so it reaches the run's services. Any other repo command gets a drive with no run; a
+// built-in or driver command that needs no run reaches no drive.
+export function pickDriveKind(facts: DriveFacts): DriveKind {
+  if (
+    facts.runStatus !== null &&
+    (facts.needsRun || (facts.isRepoCommand && facts.runStatus === 'running'))
+  ) {
+    return 'run';
+  }
+
+  return !facts.needsRun && facts.isRepoCommand ? 'runless' : 'none';
+}

package/src/pick-envelope-context.ts

@@ -0,0 +1,10 @@
+// A command that ran on a run, such as a drive or the doctor, reports the run and feature it ran
+// under, even when another command moved the pointers meanwhile. Any other command reports the
+// state it left, such as the run `up` started.
+export function pickEnvelopeContext<Context>(
+  before: Context | null,
+  after: Context | null,
+  ranOnRun: boolean,
+): Context | null {
+  return ranOnRun ? before : after;
+}

package/src/pick-envelope-payload.ts

@@ -0,0 +1,28 @@
+import { WringerError } from './wringer-error.ts';
+
+export interface PayloadInput {
+  readonly data: unknown;
+  readonly commandFailure: WringerError | null;
+  readonly cursors: Readonly<Record<string, number>> | WringerError;
+}
+
+export interface EnvelopePayload {
+  readonly data: unknown;
+  readonly failure: WringerError | null;
+  readonly cursors: Readonly<Record<string, number>>;
+}
+
+// The command's own failure leads, and a cursor read that failed after it is the envelope's
+// failure. A failed command's envelope carries the data its error gives, such as the doctor's
+// results; an internal error's data is its stack, which goes to the run's log instead.
+export function pickEnvelopePayload(input: PayloadInput): EnvelopePayload {
+  const cursorsFailure = input.cursors instanceof WringerError ? input.cursors : null;
+  const cursors = input.cursors instanceof WringerError ? {} : input.cursors;
+  const failure = input.commandFailure ?? cursorsFailure;
+
+  if (failure === null) {
+    return { data: input.data, failure, cursors };
+  }
+
+  return { data: failure.code === 'internal' ? null : failure.data, failure, cursors };
+}

package/src/pick-envelope-run.ts

@@ -0,0 +1,25 @@
+import type { RunView } from './build-run-view.ts';
+
+export interface EnvelopeRunContext {
+  readonly targetName: string;
+  readonly run: RunView | undefined;
+}
+
+// A lifecycle command's envelope belongs to the run it bound under the target's lock. `down` clears
+// the pointer to the run it ended, so its envelope names that run from before the command, and a
+// command that moved to another target names only that target's run.
+export function pickEnvelopeRun(
+  before: EnvelopeRunContext | null,
+  settled: EnvelopeRunContext | null,
+  bound: RunView | null,
+): RunView | undefined {
+  if (bound !== null) {
+    return bound;
+  }
+
+  if (settled?.targetName !== before?.targetName) {
+    return settled?.run;
+  }
+
+  return settled?.run ?? before?.run;
+}

package/src/pick-envelope-target.ts

@@ -0,0 +1,10 @@
+import type { RunView } from './build-run-view.ts';
+
+// A lifecycle command that bound its envelope to a run reports that run's target, even when another
+// command moved the target pointer meanwhile; any other command reports its settled context's.
+export function pickEnvelopeTarget(
+  settled: { readonly targetName: string } | null,
+  bound: RunView | null,
+): string | null {
+  return bound?.target ?? settled?.targetName ?? null;
+}

package/src/pick-late-failure-write.ts

@@ -0,0 +1,44 @@
+import type { LateFailureEvent, RunID } from './run-events.ts';
+import { toWringerError } from './to-wringer-error.ts';
+import type { WringerError } from './wringer-error.ts';
+
+export interface LateFailureFacts {
+  readonly runID: RunID | null;
+  readonly command: string;
+  readonly answered: WringerError | null;
+  readonly at: Date;
+}
+
+export interface LateFailureWrite {
+  // With no run, the state folder's late-failure log takes the event.
+  readonly runID: RunID | null;
+  readonly event: LateFailureEvent;
+}
+
+// Null when the work succeeded, failed with the error the envelope already answered with, or ran
+// into the same deadline the envelope answered as a timeout, such as a body refused at its start.
+export function pickLateFailureWrite(
+  settled: PromiseSettledResult<unknown>,
+  facts: LateFailureFacts,
+): LateFailureWrite | null {
+  if (settled.status === 'fulfilled' || settled.reason === facts.answered) {
+    return null;
+  }
+
+  const failure = toWringerError(settled.reason);
+
+  if (failure.code === 'timeout' && facts.answered?.code === 'timeout') {
+    return null;
+  }
+
+  return {
+    runID: facts.runID,
+    event: {
+      type: 'late-failure',
+      at: facts.at.toISOString(),
+      command: facts.command,
+      code: failure.code,
+      message: failure.message,
+    },
+  };
+}

package/src/pick-log-refusal.ts

@@ -0,0 +1,18 @@
+import type { RunView } from './build-run-view.ts';
+import type { RunViewRefusal } from './create-file-state.ts';
+import type { Envelope } from './envelope.ts';
+import { findVerdictRefusal } from './find-verdict-refusal.ts';
+import { doneCommand } from './read-verdicts.ts';
+
+// Only a verdict that `done` gave needs the run, as it stands under the lock, to still match the
+// run `done` read.
+export function pickLogRefusal(
+  envelope: Envelope,
+  read: RunView | undefined,
+): RunViewRefusal | null {
+  if (envelope.command !== doneCommand || !envelope.ok) {
+    return null;
+  }
+
+  return (current) => findVerdictRefusal(read, current);
+}

package/src/pick-merge-base-failure.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { WringerError } from './wringer-error.ts';
+
+const gitFailureSchema = z.object({ exitCode: z.number(), stderr: z.string() });
+
+// `merge-base` exits 1 with nothing on stderr when the two share no commit, and also exits 1 when
+// it cannot read an ancestor, with the read error on stderr. Only the first means no shared commit.
+export function pickMergeBaseFailure(failure: unknown, noSharedCommit: WringerError): unknown {
+  const data = failure instanceof WringerError ? failure.data : undefined;
+  const parsed = gitFailureSchema.safeParse(data);
+
+  return parsed.success && parsed.data.exitCode === 1 && parsed.data.stderr.trim() === ''
+    ? noSharedCommit
+    : failure;
+}