@wringer/core 0.0.0 → 0.1.1

package/src/build-promised-object-reads.ts

@@ -0,0 +1,48 @@
+import type { GitRequest } from './run-git.ts';
+
+export interface PromisedObjectReadInput {
+  readonly root: string;
+  readonly mergeBase: string;
+
+  // The text of `git config --list -z` in the repo.
+  readonly configList: string;
+}
+
+// The fingerprint's own git folder cannot fetch, so in a partial clone the repo's own git reads
+// each base object the diff will need first: a diff of the working tree reads the same objects.
+export function buildPromisedObjectReads(input: PromisedObjectReadInput): GitRequest[] {
+  if (!isPartialClone(input.configList)) {
+    return [];
+  }
+
+  return [
+    {
+      cwd: input.root,
+      args: [
+        'diff',
+        '--binary',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--output=/dev/null',
+        input.mergeBase,
+      ],
+    },
+  ];
+}
+
+const promisorPattern = /^remote\..+\.promisor$/u;
+
+const trueValues = new Set(['', 'true', 'yes', 'on', '1']);
+
+// `config --list -z` prints each entry as the key, a newline and the value, ending in a NUL. A
+// partial clone marks its remote as a promisor, and older clones also set the extension.
+function isPartialClone(configList: string): boolean {
+  return configList.split('\0').some((entry) => {
+    const [key = '', value = ''] = entry.split('\n');
+
+    return (
+      key === 'extensions.partialclone' ||
+      (promisorPattern.test(key) && trueValues.has(value.toLowerCase()))
+    );
+  });
+}

package/src/build-report.ts

@@ -0,0 +1,55 @@
+import type { FeatureStatus, Report, Verdict } from './report-schema.ts';
+import type { FeatureDefinition } from './types.ts';
+
+export interface ReportInput {
+  readonly base: string;
+  readonly fingerprint: string;
+  readonly features: readonly FeatureDefinition[];
+  readonly changedPaths: readonly string[];
+  readonly verdicts: ReadonlyMap<string, Verdict>;
+}
+
+// Each feature whose paths the branch changes needs a verdict at the current fingerprint. A feature
+// the branch leaves alone is `unchanged`, whatever its verdict.
+export function buildReport(input: ReportInput): Report {
+  const features = input.features.map((feature) => {
+    const changed = input.changedPaths.some((path) =>
+      feature.paths.some((pattern) => new Bun.Glob(pattern).match(path)),
+    );
+
+    const verdict = input.verdicts.get(feature.name) ?? null;
+
+    return {
+      name: feature.name,
+      changed,
+      status: pickFeatureStatus(changed, verdict, input.fingerprint),
+      verdict,
+    };
+  });
+
+  return {
+    version: 1,
+    base: input.base,
+    fingerprint: input.fingerprint,
+    complete: features.every(
+      (feature) => feature.status === 'verified' || feature.status === 'unchanged',
+    ),
+    features,
+  };
+}
+
+function pickFeatureStatus(
+  changed: boolean,
+  verdict: Verdict | null,
+  fingerprint: string,
+): FeatureStatus {
+  if (!changed) {
+    return 'unchanged';
+  }
+
+  if (verdict === null) {
+    return 'missing';
+  }
+
+  return verdict.fingerprint === fingerprint ? 'verified' : 'stale';
+}

package/src/build-run-handle.ts

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+import { buildRunPaths } from './build-state-paths.ts';
+import type { RunHandle } from './types.ts';
+
+export function buildRunHandle(stateDir: string, runID: string): RunHandle {
+  const paths = buildRunPaths(stateDir, runID);
+
+  return {
+    id: runID,
+    paths,
+    childLog: (name) => ({ path: join(paths.children, `${name}.log`) }),
+  };
+}

package/src/build-run-view.ts

@@ -0,0 +1,120 @@
+import { match } from 'ts-pattern';
+import { canMoveRunStatus, findRunStatusMove } from './append-run-event.ts';
+import type { RunStatus } from './append-run-event.ts';
+import type { Envelope } from './envelope.ts';
+import type { CheckResult, Endpoints, Mode, RunEvent, RunID } from './run-events.ts';
+
+export type DoctorState = 'none' | 'passed' | 'failed';
+
+export interface SupervisorInfo {
+  readonly pid: number;
+  readonly socket: string;
+}
+
+export interface RunView {
+  readonly runID: RunID;
+  readonly target: string;
+  readonly mode: Mode;
+  readonly fingerprint: string;
+  readonly status: RunStatus;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly crashReason: string | null;
+  readonly endpoints: Endpoints;
+  readonly services: readonly string[];
+  readonly supervisor: SupervisorInfo | null;
+  readonly doctor: DoctorState;
+  readonly doctorResults: readonly CheckResult[];
+  readonly drivesAfterDoctor: readonly Envelope[];
+}
+
+export interface BuildRunViewInput {
+  readonly runID: RunID;
+  readonly events: readonly RunEvent[];
+}
+
+export function buildRunView(input: BuildRunViewInput): RunView | undefined {
+  const [first, ...rest] = input.events;
+
+  if (first?.type !== 'run-started') {
+    return undefined;
+  }
+
+  const initial: RunView = {
+    runID: input.runID,
+    target: first.target,
+    mode: first.mode,
+    fingerprint: first.fingerprint,
+    status: 'starting',
+    startedAt: first.at,
+    endedAt: null,
+    crashReason: null,
+    endpoints: {},
+    services: [],
+    supervisor: null,
+    doctor: 'none',
+    doctorResults: [],
+    drivesAfterDoctor: [],
+  };
+
+  return rest.reduce((view, event) => buildNextRunView(view, event), initial);
+}
+
+function buildNextRunView(view: RunView, event: RunEvent): RunView {
+  const moved = buildMovedRunView(view, event);
+
+  return match(event)
+    .returnType<RunView>()
+    .with({ type: 'launch-ready' }, (ready) =>
+      view.status === 'starting' ? { ...moved, endpoints: ready.endpoints } : moved,
+    )
+    .with({ type: 'service-ready' }, (ready) => ({
+      ...moved,
+      services: [...moved.services, ready.service],
+    }))
+    .with({ type: 'supervisor-ready' }, (ready) => ({
+      ...moved,
+      supervisor: { pid: ready.pid, socket: ready.socket },
+    }))
+    .with({ type: 'doctor-passed' }, (doctor) => ({
+      ...moved,
+      doctor: 'passed',
+      doctorResults: doctor.results,
+      drivesAfterDoctor: [],
+    }))
+    .with({ type: 'doctor-failed' }, (doctor) => ({
+      ...moved,
+      doctor: 'failed',
+      doctorResults: doctor.results,
+      drivesAfterDoctor: [],
+    }))
+    .with({ type: 'envelope' }, (logged) =>
+      logged.drive && moved.doctor === 'passed'
+        ? { ...moved, drivesAfterDoctor: [...moved.drivesAfterDoctor, logged.envelope] }
+        : moved,
+    )
+    .with({ type: 'crashed' }, (crashed) =>
+      moved === view ? view : { ...moved, crashReason: crashed.reason },
+    )
+    .with({ type: 'run-ended' }, (ended) =>
+      moved === view ? view : { ...moved, endedAt: ended.at },
+    )
+    .with(
+      { type: 'run-started' },
+      { type: 'run-ready' },
+      { type: 'internal-error' },
+      { type: 'late-failure' },
+      () => moved,
+    )
+    .exhaustive();
+}
+
+function buildMovedRunView(view: RunView, event: RunEvent): RunView {
+  const next = findRunStatusMove(event.type);
+
+  if (next === null || !canMoveRunStatus(view.status, next)) {
+    return view;
+  }
+
+  return { ...view, status: next };
+}

package/src/build-service-key.ts

@@ -0,0 +1,4 @@
+// A service is keyed `<driver>/<service>`, so two drivers can each run a service of one name.
+export function buildServiceKey(driver: string, service: string): string {
+  return `${driver}/${service}`;
+}

package/src/build-shut-down-steps.ts

@@ -0,0 +1,54 @@
+import type { RunEvent } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface ShutDownFacts {
+  readonly crashReason: string | null;
+
+  // True when the stop stopped waiting for a startup that ignored the abort.
+  readonly gaveUpOnStartup: boolean;
+
+  // Each part whose cleanup failed, with why.
+  readonly failures: readonly string[];
+  readonly at: string;
+}
+
+export interface ShutDownSteps {
+  readonly abortCommands: boolean;
+  readonly events: readonly RunEvent[];
+
+  // What the stop's caller gets once the final events are written.
+  readonly failure: WringerError | null;
+}
+
+const unfinishedStartup = 'the startup had not finished when the stop stopped waiting for it';
+
+// A cleanup the deadline gave up on can leave its command running, so the commands of the parts
+// that came up end only once every such part has stopped. A failed cleanup, or a startup the stop
+// gave up on, makes the stop a crash, so the log and the stop's caller name what may still run.
+export function buildShutDownSteps(facts: ShutDownFacts): ShutDownSteps {
+  const leftovers = [
+    ...(facts.gaveUpOnStartup ? [unfinishedStartup] : []),
+    ...(facts.failures.length === 0 ? [] : [`cleanup failed for ${facts.failures.join('; ')}`]),
+  ];
+
+  const reasons = [...(facts.crashReason === null ? [] : [facts.crashReason]), ...leftovers];
+
+  const event: RunEvent =
+    reasons.length === 0
+      ? { type: 'run-ended', at: facts.at }
+      : { type: 'crashed', at: facts.at, reason: reasons.join('; ') };
+
+  const failure =
+    leftovers.length === 0
+      ? null
+      : new WringerError('environment', {
+          message: `The run ended, and a part may still be up: ${leftovers.join('; ')}.`,
+          hint: 'Stop each part the message names by hand before the next `up`.',
+        });
+
+  return {
+    abortCommands: !facts.gaveUpOnStartup,
+    events: [event],
+    failure,
+  };
+}

package/src/build-skip-worktree-marks.ts

@@ -0,0 +1,36 @@
+import type { GitRequest } from './run-git.ts';
+
+export interface SkipWorktreeMarkInput {
+  readonly root: string;
+  readonly env: Readonly<Record<string, string>>;
+
+  // The bytes of `git ls-files -t -z` over the repo's own index.
+  readonly taggedEntries: Uint8Array;
+}
+
+const skipWorktreeTag = 'S ';
+
+// A sparse checkout leaves a file outside it out of the working tree and marks its entry
+// skip-worktree; without the mark on the temporary index, `add --all` would stage the file as
+// deleted. latin1 maps each byte to one character, so a path that is not UTF-8 keeps its bytes.
+export function buildSkipWorktreeMarks(input: SkipWorktreeMarkInput): GitRequest[] {
+  const paths = Buffer.from(input.taggedEntries)
+    .toString('latin1')
+    .split('\0')
+    .flatMap((entry) =>
+      entry.startsWith(skipWorktreeTag) ? [`${entry.slice(skipWorktreeTag.length)}\0`] : [],
+    );
+
+  if (paths.length === 0) {
+    return [];
+  }
+
+  return [
+    {
+      cwd: input.root,
+      args: ['update-index', '-z', '--skip-worktree', '--stdin'],
+      stdin: Buffer.from(paths.join(''), 'latin1'),
+      env: input.env,
+    },
+  ];
+}

package/src/build-spawn-error.ts

@@ -0,0 +1,12 @@
+import { WringerError } from './wringer-error.ts';
+
+// A spawn that fails, such as for a working folder that does not exist, is a fault of the
+// environment the command runs in.
+export function buildSpawnError(command: string, error: unknown): WringerError {
+  const reason = error instanceof Error ? error.message : String(error);
+
+  return new WringerError('environment', {
+    message: `${command} did not start: ${reason}`,
+    hint: `Check that ${command} and its working folder exist.`,
+  });
+}

package/src/build-state-paths.ts

@@ -0,0 +1,53 @@
+import { join } from 'node:path';
+import type { RunID } from './run-events.ts';
+
+export interface StatePaths {
+  readonly root: string;
+  readonly state: string;
+  readonly locks: string;
+  readonly runs: string;
+
+  // The late failures of commands that ran with no run, whose log would otherwise take them.
+  readonly lateFailures: string;
+}
+
+export function buildStatePaths(stateDir: string): StatePaths {
+  return {
+    root: stateDir,
+    state: join(stateDir, 'state.json'),
+    locks: join(stateDir, 'locks'),
+    runs: join(stateDir, 'runs'),
+    lateFailures: join(stateDir, 'late-failures.ndjson'),
+  };
+}
+
+export interface RunPaths {
+  readonly directory: string;
+  readonly manifest: string;
+  readonly log: string;
+  readonly socket: string;
+  readonly supervisorLog: string;
+  readonly streams: string;
+  readonly children: string;
+  readonly features: string;
+
+  // The lock every writer of the run's log and manifest holds.
+  readonly lock: string;
+}
+
+export function buildRunPaths(stateDir: string, runID: RunID): RunPaths {
+  const statePaths = buildStatePaths(stateDir);
+  const directory = join(statePaths.runs, runID);
+
+  return {
+    lock: join(statePaths.locks, `run-${runID}.lock`),
+    directory,
+    manifest: join(directory, 'manifest.json'),
+    log: join(directory, 'log.ndjson'),
+    socket: join(directory, 'supervisor', 'sock'),
+    supervisorLog: join(directory, 'supervisor.log'),
+    streams: join(directory, 'streams'),
+    children: join(directory, 'children'),
+    features: join(directory, 'features'),
+  };
+}

package/src/build-submodule-adds.ts

@@ -0,0 +1,64 @@
+import type { GitRequest } from './run-git.ts';
+
+export interface SubmoduleAddInput {
+  // The repo root, where `ls-files` printed each path relative to.
+  readonly root: string;
+  readonly env: Readonly<Record<string, string>>;
+
+  // The bytes of `git ls-files --stage -z` over the temporary index.
+  readonly stagedEntries: Uint8Array;
+}
+
+const nul = Buffer.from([0]);
+
+// `add --all` skips a submodule that the repo's config marks `ignore = all` on newer git, so its
+// new commit would never reach the diff; `--force` stages it whatever the config says. The paths go
+// to git on stdin as the bytes `ls-files` printed, and as literal paths, so `lib[1]` is no glob.
+export function buildSubmoduleAdds(input: SubmoduleAddInput): GitRequest[] {
+  const paths = collectSubmodulePaths(Buffer.from(input.stagedEntries));
+
+  if (paths.length === 0) {
+    return [];
+  }
+
+  return [
+    {
+      cwd: input.root,
+      args: ['add', '--force', '--pathspec-from-file=-', '--pathspec-file-nul'],
+      env: { ...input.env, GIT_LITERAL_PATHSPECS: '1' },
+      stdin: Buffer.concat(paths.flatMap((path) => [path, nul])),
+    },
+  ];
+}
+
+const gitlinkPrefix = Buffer.from('160000 ');
+const tab = 0x09;
+
+// A path may hold a tab, so only the first tab ends the mode, object and stage.
+function collectSubmodulePaths(stagedEntries: Buffer): Buffer[] {
+  return collectEntries(stagedEntries).flatMap((entry) => {
+    const pathStart = entry.indexOf(tab) + 1;
+
+    if (pathStart === 0 || !entry.subarray(0, gitlinkPrefix.length).equals(gitlinkPrefix)) {
+      return [];
+    }
+
+    return [entry.subarray(pathStart)];
+  });
+}
+
+function collectEntries(stagedEntries: Buffer): Buffer[] {
+  const entries: Buffer[] = [];
+  let start = 0;
+
+  while (start < stagedEntries.length) {
+    const end = stagedEntries.indexOf(0, start);
+    const stop = end === -1 ? stagedEntries.length : end;
+
+    entries.push(stagedEntries.subarray(start, stop));
+
+    start = stop + 1;
+  }
+
+  return entries;
+}

package/src/builtins/build-doctor-command.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+import { buildBuiltinCommand } from '../build-commands.ts';
+import { checkResultSchema } from '../run-events.ts';
+import type { CheckResult } from '../run-events.ts';
+import { toWringerError } from '../to-wringer-error.ts';
+import type { BuiltinContext, Drive, RegisteredCommand } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+import { writeLateFailure } from '../write-late-failure.ts';
+import { pickDoctorOutcome } from './pick-doctor-outcome.ts';
+
+const doctorDataSchema = z.strictObject({
+  passed: z.boolean(),
+  results: z.array(checkResultSchema),
+});
+
+// The doctor runs every driver check and repo check on a read-only view of the target, so a check
+// can only read. Its result lands in the log of the run it read, so a late result never passes a
+// newer run.
+export function buildDoctorCommand(): RegisteredCommand {
+  return buildBuiltinCommand({
+    path: ['doctor'],
+    summary: 'Check the run is healthy; drive commands are refused until it passes',
+    args: z.strictObject({}),
+    data: doctorDataSchema,
+    effect: 'read',
+    needsRun: true,
+    needsDoctor: false,
+    run: async (_args, ctx) => {
+      const results: CheckResult[] = [];
+
+      for (const check of collectChecks(ctx, ctx.openDrive('read-only'))) {
+        const result = await runCheck(ctx, check);
+
+        results.push(result);
+        ctx.emit('check', result);
+      }
+
+      const outcome = pickDoctorOutcome(results, ctx.now().toISOString());
+      const runID = ctx.run?.runID ?? '';
+
+      await ctx.state.appendEvent(runID, outcome.event);
+      await ctx.state.writeManifest(runID);
+
+      if (outcome.failure !== null) {
+        throw outcome.failure;
+      }
+
+      return outcome.data;
+    },
+  });
+}
+
+interface PlannedCheck {
+  readonly name: string;
+  readonly timeoutMs: number;
+  readonly run: (drive: Drive) => Promise<void>;
+}
+
+// Each check runs in a drive of its own, whose clients and execs stop at the check's deadline.
+function collectChecks(ctx: BuiltinContext, drive: Drive): readonly PlannedCheck[] {
+  const driverChecks = [...drive.drivers].flatMap(([driverName, opened]) =>
+    opened.checks.map((check) => ({
+      name: `${driverName}.${check.name}`,
+      timeoutMs: check.timeoutMs,
+      run: (checkDrive: Drive) => runDriverCheck(ctx, checkDrive, driverName, check.name),
+    })),
+  );
+
+  const repoChecks = ctx.wringer.checks.map((check) => ({
+    name: check.name,
+    timeoutMs: check.timeoutMs,
+    run: (checkDrive: Drive) => check.run(checkDrive.ctx),
+  }));
+
+  return [...driverChecks, ...repoChecks];
+}
+
+function runDriverCheck(
+  ctx: BuiltinContext,
+  drive: Drive,
+  driverName: string,
+  checkName: string,
+): Promise<void> {
+  const check = drive.drivers.get(driverName)?.checks.find((each) => each.name === checkName);
+
+  if (check === undefined) {
+    return Promise.reject(
+      new WringerError('internal', {
+        message: `The ${driverName} driver lost its check ${checkName}.`,
+      }),
+    );
+  }
+
+  return check.run(ctx.feature, ctx.emit);
+}
+
+async function runCheck(ctx: BuiltinContext, check: PlannedCheck): Promise<CheckResult> {
+  const started = performance.now();
+  const deadline = AbortSignal.any([ctx.signal, AbortSignal.timeout(check.timeoutMs)]);
+  const deadlineAt = Math.min(ctx.deadlineAt, ctx.now().getTime() + check.timeoutMs);
+  const timedOut = Promise.withResolvers<never>();
+
+  // An abort listener added to a signal that already fired never runs, so the check would run on.
+  if (deadline.aborted) {
+    return {
+      name: check.name,
+      status: 'failed',
+      durationMs: 0,
+      code: 'timeout',
+      message: `${check.name} did not start: the doctor's deadline had passed.`,
+    };
+  }
+
+  const onAbort = (): void => {
+    timedOut.reject(
+      new WringerError('timeout', { message: `${check.name} ran past ${check.timeoutMs} ms.` }),
+    );
+  };
+
+  deadline.addEventListener('abort', onAbort, { once: true });
+
+  // A check that throws before it returns its promise fails like one that rejects.
+  const work = Promise.try(() =>
+    check.run(ctx.openDrive('read-only', { signal: deadline, at: deadlineAt })),
+  );
+
+  try {
+    await Promise.race([work, timedOut.promise]);
+
+    return {
+      name: check.name,
+      status: 'passed',
+      durationMs: Math.round(performance.now() - started),
+      code: null,
+      message: null,
+    };
+  } catch (error) {
+    const failure = toWringerError(error);
+
+    // The doctor answers at the check's timeout, while the check runs on in the run it read.
+    if (deadline.aborted) {
+      ctx.keepLate(
+        writeLateFailure(work, {
+          state: ctx.state,
+          runID: ctx.run?.runID ?? '',
+          command: `doctor ${check.name}`,
+          answered: null,
+          now: ctx.now,
+        }),
+      );
+    }
+
+    return {
+      name: check.name,
+      status: 'failed',
+      durationMs: Math.round(performance.now() - started),
+      code: failure.code,
+      message: failure.message,
+    };
+  } finally {
+    deadline.removeEventListener('abort', onAbort);
+  }
+}

package/src/builtins/build-exec-command.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { buildBuiltinCommand } from '../build-commands.ts';
+import type { RegisteredCommand } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+
+const execArgsSchema = z.strictObject({ argv: z.array(z.string()).min(1) });
+
+const execDataSchema = z.strictObject({
+  exitCode: z.number().int(),
+  stdout: z.string(),
+  stderr: z.string(),
+});
+
+// A raw exec could do anything, so it is always a write: a read-only target refuses it, and a repo
+// that needs a read there declares a read-only action.
+export function buildExecCommand(): RegisteredCommand {
+  return buildBuiltinCommand({
+    path: ['exec'],
+    summary: "Run a command through the target's host, local or ssh",
+    args: execArgsSchema,
+    positionals: ['argv'],
+    data: execDataSchema,
+    effect: 'write',
+    needsRun: true,
+    needsDoctor: true,
+    run: async (args, ctx) => {
+      const drive = ctx.openDrive(ctx.target.access);
+
+      const result = await drive.ctx.exec(args.argv);
+
+      if (result.exitCode !== 0) {
+        throw new WringerError('check-failed', {
+          message: `${args.argv[0] ?? 'The command'} exited with code ${result.exitCode}.`,
+          data: result,
+        });
+      }
+
+      return result;
+    },
+  });
+}