@wringer/core 0.0.0 → 0.1.1

package/src/find-own-value.ts

@@ -0,0 +1,8 @@
+// A key from outside the program, such as a target or stream named `constructor`, would read a
+// value every object inherits; only the record's own keys count.
+export function findOwnValue<Value>(
+  record: Readonly<Record<string, Value>>,
+  key: string,
+): Value | undefined {
+  return Object.hasOwn(record, key) ? record[key] : undefined;
+}

package/src/find-remote-stop-failure.ts

@@ -0,0 +1,19 @@
+import type { ProcessResult } from './run-process.ts';
+import { toWringerError } from './to-wringer-error.ts';
+
+// Names the first stop that failed to run or exited non-zero, or null when every stop worked.
+export function findRemoteStopFailure(
+  stops: readonly PromiseSettledResult<ProcessResult>[],
+): string | null {
+  for (const stop of stops) {
+    if (stop.status === 'rejected') {
+      return toWringerError(stop.reason).message;
+    }
+
+    if (stop.value.exitCode !== 0) {
+      return `the stop exited with code ${stop.value.exitCode}: ${stop.value.stderr.trim()}`;
+    }
+  }
+
+  return null;
+}

package/src/find-verdict-refusal.ts

@@ -0,0 +1,26 @@
+import { isDeepStrictEqual } from 'node:util';
+import type { RunView } from './build-run-view.ts';
+import { WringerError } from './wringer-error.ts';
+
+// `done` judged the run it read when it started. Its verdict stands only while the doctor it
+// trusted is still the latest, which holds while the drives it read still open the run's drives
+// since the doctor: a later doctor event empties that list.
+export function findVerdictRefusal(
+  read: RunView | undefined,
+  current: RunView | undefined,
+): WringerError | null {
+  const readDrives = read?.drivesAfterDoctor ?? [];
+
+  const stands =
+    current?.doctor === 'passed' &&
+    isDeepStrictEqual(current.drivesAfterDoctor.slice(0, readDrives.length), readDrives);
+
+  if (stands) {
+    return null;
+  }
+
+  return new WringerError('doctor-required', {
+    message: `The doctor ran again on run ${current?.runID ?? 'none'} while \`done\` judged it.`,
+    hint: 'Run `doctor`, then drive the feature again.',
+  });
+}

package/src/follow-process.ts

@@ -0,0 +1,147 @@
+import { buildSpawnError } from './build-spawn-error.ts';
+import { killProcessGroup } from './kill-process-group.ts';
+import { readStreamLines } from './read-stream-lines.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface FollowProcessRequest {
+  readonly argv: readonly string[];
+  readonly signal: AbortSignal;
+  readonly onLine: (line: string) => void;
+}
+
+export interface FollowResult {
+  readonly exitCode: number;
+
+  // The end of stderr, so a long follow keeps a bounded tail, such as ssh's reason it failed.
+  readonly stderr: string;
+}
+
+const stderrTailLength = 4096;
+
+// The command runs in a process group of its own, and the signal kills the whole group: a child
+// the command started, such as a `sleep` under `sh -c`, would otherwise keep stdout open, and the
+// follow would never end.
+export async function followProcess(request: FollowProcessRequest): Promise<FollowResult> {
+  const [command] = request.argv;
+  const executable = resolveExecutable(command);
+
+  const plan = pickFollowPlan({
+    argv: request.argv,
+    executable,
+    aborted: request.signal.aborted,
+  });
+
+  if (plan instanceof WringerError) {
+    throw plan;
+  }
+
+  if (!plan.start) {
+    return { exitCode: 0, stderr: '' };
+  }
+
+  const child = spawnFollowed(plan.argv);
+
+  // stderr is read as it comes, so a full pipe never stalls the command.
+  const stderr = readStreamTail(child.stderr, stderrTailLength);
+
+  const killGroup = (): void => {
+    killProcessGroup(child.pid);
+  };
+
+  request.signal.addEventListener('abort', killGroup, { once: true });
+
+  // A child the command left behind is killed as the command exits: it may hold stdout open, and
+  // nothing could stop it once the abort is unwired. A reader or callback that throws stops the
+  // group too, so nothing runs on unread.
+  const watchExit = async (): Promise<number> => {
+    const exitCode = await child.exited;
+
+    killGroup();
+
+    return exitCode;
+  };
+
+  const exited = watchExit();
+
+  try {
+    for await (const line of readStreamLines(child.stdout)) {
+      request.onLine(line);
+    }
+
+    const [exitCode, tail] = await Promise.all([exited, stderr]);
+
+    return { exitCode, stderr: tail };
+  } catch (error) {
+    killGroup();
+
+    await Promise.allSettled([child.exited, stderr]);
+
+    throw error;
+  } finally {
+    request.signal.removeEventListener('abort', killGroup);
+  }
+}
+
+function resolveExecutable(command: string | undefined): string | null {
+  if (command === undefined) {
+    return null;
+  }
+
+  return Bun.which(command);
+}
+
+interface FollowPlanInput {
+  readonly argv: readonly string[];
+  readonly executable: string | null;
+  readonly aborted: boolean;
+}
+
+type FollowPlan =
+  | { readonly start: false }
+  | { readonly start: true; readonly argv: readonly string[] };
+
+function pickFollowPlan(input: FollowPlanInput): FollowPlan | WringerError {
+  const [command, ...args] = input.argv;
+
+  if (command === undefined) {
+    return new WringerError('usage', { message: 'A follow 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.`,
+    });
+  }
+
+  if (input.aborted) {
+    return { start: false };
+  }
+
+  return { start: true, argv: [input.executable, ...args] };
+}
+
+function spawnFollowed(argv: readonly string[]) {
+  try {
+    return Bun.spawn([...argv], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      detached: true,
+    });
+  } catch (error) {
+    throw buildSpawnError(argv.join(' '), error);
+  }
+}
+
+async function readStreamTail(stream: ReadableStream<Uint8Array>, length: number): Promise<string> {
+  const decoder = new TextDecoder();
+
+  let tail = '';
+
+  for await (const chunk of stream) {
+    tail = `${tail}${decoder.decode(chunk, { stream: true })}`.slice(-length);
+  }
+
+  return `${tail}${decoder.decode()}`.slice(-length);
+}

package/src/get-lock-value.ts

@@ -0,0 +1,17 @@
+import type { FileLockResult } from '@zgeoff/std/with-file-lock';
+import { match } from 'ts-pattern';
+import { WringerError } from './wringer-error.ts';
+
+// The value the locked work returned, or an environment error when another holder kept the lock
+// at `path` past the wait.
+export function getLockValue<Value>(path: string, result: FileLockResult<Value>): Value {
+  return match(result)
+    .with({ kind: 'ran' }, (ran) => ran.value)
+    .with({ kind: 'busy' }, () => {
+      throw new WringerError('environment', {
+        message: `Another wringer command holds the lock ${path}.`,
+        hint: 'Wait for the other command to end, then run this one again.',
+      });
+    })
+    .exhaustive();
+}

package/src/get-target.ts

@@ -0,0 +1,15 @@
+import type { TargetDefinition, Wringer } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export function getTarget(wringer: Wringer, name: string): TargetDefinition {
+  const target = wringer.targets.get(name);
+
+  if (target === undefined) {
+    throw new WringerError('usage', {
+      message: `The repo has no target named ${name}.`,
+      hint: `Pick one of: ${[...wringer.targets.keys()].join(', ')}.`,
+    });
+  }
+
+  return target;
+}

package/src/host.ts

@@ -0,0 +1,26 @@
+import type { ProcessResult } from './run-process.ts';
+
+export type Access = 'read-write' | 'read-only';
+
+export interface HostRequest {
+  readonly argv: readonly string[];
+  readonly access: Access;
+  readonly stdin?: string | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+export interface FollowRequest {
+  readonly argv: readonly string[];
+  readonly access: Access;
+  readonly signal: AbortSignal;
+  readonly onLine: (line: string) => void;
+}
+
+export interface Host {
+  readonly kind: 'local' | 'ssh';
+  readonly run: (request: HostRequest) => Promise<ProcessResult>;
+
+  // Runs a long-lived command, such as `tail -F`, and hands each line of its stdout to `onLine`
+  // until the command exits or the signal fires. Resolves with the command's exit code.
+  readonly follow: (request: FollowRequest) => Promise<number>;
+}

package/src/index.ts

@@ -1 +1,74 @@
+export { bindDrivers } from './bind-drivers.ts';
+export type { BoundHelpers } from './bind-drivers.ts';
+export { buildEnvelope } from './build-envelope.ts';
+export type { EnvelopeInput } from './build-envelope.ts';
+export { buildEnvelopeJSONSchema } from './build-envelope-json-schema.ts';
+export { buildRunView } from './build-run-view.ts';
+export type { DoctorState, RunView, SupervisorInfo } from './build-run-view.ts';
+export { buildRunPaths, buildStatePaths } from './build-state-paths.ts';
+export type { RunPaths, StatePaths } from './build-state-paths.ts';
+export { createDirectory } from './create-directory.ts';
+export { createFileState, eventSizeCapBytes, pointersSchema } from './create-file-state.ts';
+export type { FileStateOptions, Pointers, StatePort } from './create-file-state.ts';
+export { createNodeStateFileSystem } from './create-node-state-file-system.ts';
+export { createRepoState } from './create-repo-state.ts';
+export type { StateFileSystem } from './create-node-state-file-system.ts';
+export { createWringer, defaultStateDir } from './create-wringer.ts';
+export type { WringerBuilder, WringerOptions } from './create-wringer.ts';
+export { defineDriver } from './define-driver.ts';
+export { findOwnValue } from './find-own-value.ts';
+export type { DriverDefinition, DriverFactory } from './define-driver.ts';
+export { dataCapBytes } from './cap-data.ts';
+export { defaultTimeoutMs, dispatch } from './dispatch.ts';
+export type { DispatchResult } from './dispatch.ts';
+
+export {
+  envelopeErrorSchema,
+  envelopeSchema,
+  evidenceSchema,
+  streamEventSchema,
+} from './envelope.ts';
+
+export type { Envelope, Evidence, StreamEvent } from './envelope.ts';
 export { envelopeVersion } from './envelope-version.ts';
+export { defaultMessageFor, errorCodes, exitCodeFor } from './error-codes.ts';
+export type { ErrorCode, ExitCode } from './error-codes.ts';
+export type { Access, FollowRequest, Host, HostRequest } from './host.ts';
+export { isErrorCode } from './is-error-code.ts';
+export { launchLineSchema } from './launch-line-schema.ts';
+export type { LaunchLine } from './launch-line-schema.ts';
+export { local } from './local.ts';
+export { defaultRefusalHint } from './make-fence.ts';
+export { makeProcessSupervisorPort } from './make-process-supervisor-port.ts';
+export type { ProcessSupervisorOptions } from './make-process-supervisor-port.ts';
+export { emptyFingerprint } from './parse-patch-id.ts';
+export { parseReportBlock } from './parse-report-block.ts';
+export type { ReportBlockResult } from './parse-report-block.ts';
+export { readFingerprint } from './read-fingerprint.ts';
+export type { FingerprintHost, FingerprintRequest } from './read-fingerprint.ts';
+export { readStreamLines } from './read-stream-lines.ts';
+export { readText } from './read-text.ts';
+export { renderReportMarkdown } from './render-report-markdown.ts';
+export { reportSchema, verdictSchema } from './report-schema.ts';
+export type { FeatureStatus, Report, Verdict } from './report-schema.ts';
+
+export {
+  checkResultSchema,
+  endpointsSchema,
+  modeSchema,
+  runEventSchema,
+  runIDSchema,
+} from './run-events.ts';
+
+export type { CheckResult, Endpoints, Mode, RunEvent, RunID } from './run-events.ts';
+export { runProcess } from './run-process.ts';
+export type { ProcessRequest, ProcessResult } from './run-process.ts';
+export type { RunStatus } from './append-run-event.ts';
+export { runSupervisorProcess } from './run-supervisor-process.ts';
+export { ssh } from './ssh.ts';
+export type { PrefixLayer, SSHOptions } from './ssh.ts';
+export { supervisorCommandName } from './supervisor-protocol.ts';
+export type * from './types.ts';
+export { createNodeRepoHost } from './create-node-repo-host.ts';
+export { WringerError } from './wringer-error.ts';
+export type { WringerErrorDetails } from './wringer-error.ts';

package/src/is-error-code.ts

@@ -0,0 +1,3 @@
+export function isErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && 'code' in error && error.code === code;
+}

package/src/keep-cancelled-call.ts

@@ -0,0 +1,21 @@
+// Keeps a call in `cancelled` only when the command's deadline fires while the call still runs. A
+// call that failed earlier, such as at a doctor check's own deadline, never answers for the timeout.
+export function keepCancelledCall(
+  cancelled: Promise<unknown>[],
+  calling: Promise<unknown>,
+  signal: AbortSignal,
+): void {
+  const onAbort = (): void => {
+    cancelled.push(calling);
+  };
+
+  signal.addEventListener('abort', onAbort, { once: true });
+
+  const forget = async (): Promise<void> => {
+    await Promise.allSettled([calling]);
+
+    signal.removeEventListener('abort', onAbort);
+  };
+
+  void forget();
+}

package/src/kill-process-group.ts

@@ -0,0 +1,13 @@
+import { isErrorCode } from './is-error-code.ts';
+
+// Kills a child spawned with `detached: true` together with every process it started: a negative
+// PID names the process group. The group may already be gone.
+export function killProcessGroup(pid: number, signal: NodeJS.Signals = 'SIGKILL'): void {
+  try {
+    process.kill(-pid, signal);
+  } catch (error) {
+    if (!isErrorCode(error, 'ESRCH')) {
+      throw error;
+    }
+  }
+}

package/src/launch-line-schema.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+
+// Each line a launched app prints to stdout reaches the plan's `ready` as one of these.
+export const launchLineSchema = z.record(z.string(), z.unknown());
+
+export type LaunchLine = Readonly<z.infer<typeof launchLineSchema>>;

package/src/listen-supervisor-socket.ts

@@ -0,0 +1,75 @@
+import { chmod } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import type { Socket } from 'node:net';
+import { answerSupervisorConnection } from './answer-supervisor-connection.ts';
+import type { SupervisorConnectionOptions } from './answer-supervisor-connection.ts';
+import { raceDeadline } from './race-deadline.ts';
+import { removeFile } from './remove-file.ts';
+
+export interface SupervisorSocketOptions extends SupervisorConnectionOptions {
+  readonly path: string;
+}
+
+export interface SupervisorSocket {
+  // Stops taking connections, ends each one that sent no request, and settles once every answer
+  // has flushed, or after `graceMs`, when it destroys each connection still open: a service call
+  // that never settles would otherwise hold the process open.
+  readonly close: (graceMs: number) => Promise<void>;
+}
+
+// The socket's folder is owner-only already; the socket itself is too before the first request.
+export async function listenSupervisorSocket(
+  options: SupervisorSocketOptions,
+): Promise<SupervisorSocket> {
+  await removeFile(options.path);
+
+  const closing = new AbortController();
+  const answers = new Set<Promise<void>>();
+  const connections = new Set<Socket>();
+
+  // An answer catches its own failures, so it never rejects. A connection stays open after its
+  // answer until the client closes its side, so it is tracked until it closes.
+  const track = async (connection: Socket): Promise<void> => {
+    connections.add(connection);
+
+    connection.once('close', () => {
+      connections.delete(connection);
+    });
+
+    const answer = answerSupervisorConnection(connection, options, closing.signal);
+
+    answers.add(answer);
+
+    await answer;
+
+    answers.delete(answer);
+  };
+
+  const server = createServer((connection) => {
+    void track(connection);
+  });
+
+  const listening = Promise.withResolvers<undefined>();
+
+  server.once('error', listening.reject);
+
+  server.listen(options.path, () => {
+    listening.resolve(undefined);
+  });
+
+  await listening.promise;
+  await chmod(options.path, 0o600);
+
+  return {
+    close: async (graceMs) => {
+      server.close();
+      closing.abort();
+
+      await Promise.allSettled([raceDeadline(Promise.all(answers), AbortSignal.timeout(graceMs))]);
+
+      for (const connection of connections) {
+        connection.destroy();
+      }
+    },
+  };
+}

package/src/local.ts

@@ -0,0 +1,20 @@
+import { followProcess } from './follow-process.ts';
+import type { Host } from './host.ts';
+import { runProcess } from './run-process.ts';
+
+export function local(): Host {
+  return {
+    kind: 'local',
+    run: (request) =>
+      runProcess({ argv: request.argv, stdin: request.stdin, signal: request.signal }),
+    follow: async (request) => {
+      const followed = await followProcess({
+        argv: request.argv,
+        signal: request.signal,
+        onLine: request.onLine,
+      });
+
+      return followed.exitCode;
+    },
+  };
+}

package/src/make-fence.ts

@@ -0,0 +1,27 @@
+import type { Access } from './host.ts';
+import type { Fence } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export const defaultRefusalHint = 'This target is read-only. Stop and report the write you needed.';
+
+export interface FenceOptions {
+  readonly access: Access;
+  readonly hint: string;
+}
+
+// Default-deny: on a read-only target, every call whose effect is not `read` is refused before it
+// runs. The driver states the effect, with the target's grants already applied.
+export function makeFence(options: FenceOptions): Fence {
+  return (call) => (args) => {
+    if (options.access === 'read-only' && call.effect(args) !== 'read') {
+      return Promise.reject(
+        new WringerError('read-only', {
+          message: `${call.describe(args)} is a write, and the target is read-only.`,
+          hint: options.hint,
+        }),
+      );
+    }
+
+    return call.run(args);
+  };
+}

package/src/make-fenced-exec.ts

@@ -0,0 +1,52 @@
+import type { Access, Host } from './host.ts';
+import type { DriverExec, RepoExec } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface FencedExecOptions {
+  readonly host: Host;
+  readonly access: Access;
+  readonly hint: string;
+  readonly signal: AbortSignal;
+}
+
+// Repo code has no way to mark a raw exec as a read, so a read-only target refuses every one. A
+// driver states the effect of each of its own execs.
+export function makeRepoExec(options: FencedExecOptions): RepoExec {
+  return (argv, execOptions) => {
+    if (options.access === 'read-only') {
+      return Promise.reject(
+        new WringerError('read-only', {
+          message: `Raw exec of ${argv[0] ?? 'a command'} is refused on a read-only target.`,
+          hint: options.hint,
+        }),
+      );
+    }
+
+    return options.host.run({
+      argv,
+      access: options.access,
+      stdin: execOptions?.stdin,
+      signal: options.signal,
+    });
+  };
+}
+
+export function makeDriverExec(options: FencedExecOptions): DriverExec {
+  return (argv, effect, execOptions) => {
+    if (options.access === 'read-only' && effect !== 'read') {
+      return Promise.reject(
+        new WringerError('read-only', {
+          message: `${argv[0] ?? 'A command'} is a write, and the target is read-only.`,
+          hint: options.hint,
+        }),
+      );
+    }
+
+    return options.host.run({
+      argv,
+      access: options.access,
+      stdin: execOptions?.stdin,
+      signal: options.signal,
+    });
+  };
+}

package/src/make-process-supervisor-port.ts

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildRunPaths } from './build-state-paths.ts';
+import { callSupervisor } from './call-supervisor.ts';
+import { buildSupervisorArgv } from './supervisor-protocol.ts';
+import type { SupervisorPort } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface ProcessSupervisorOptions {
+  readonly selfCommand: readonly string[];
+  readonly root: string;
+  readonly stateDir: string;
+}
+
+// The supervisor is the repo's own CLI started again with a hidden command, detached in its own
+// process group, so it outlives the command that started it and loads the same registry. Calls
+// reach it over its Unix socket.
+export function makeProcessSupervisorPort(options: ProcessSupervisorOptions): SupervisorPort {
+  return {
+    call: callSupervisor,
+    start: (request) => {
+      const paths = buildRunPaths(join(options.root, options.stateDir), request.runID);
+
+      mkdirSync(paths.directory, { recursive: true });
+
+      const log = openSync(paths.supervisorLog, 'a');
+      const [command = 'bun', ...args] = options.selfCommand;
+      const started = Promise.withResolvers<void>();
+
+      const child = spawn(
+        command,
+        [
+          ...args,
+          ...buildSupervisorArgv({
+            runID: request.runID,
+            target: request.target,
+            root: options.root,
+          }),
+        ],
+        { cwd: options.root, detached: true, stdio: ['ignore', log, log] },
+      );
+
+      // A command that cannot start, such as one missing from the PATH, fails after spawn returns.
+      child.once('spawn', () => {
+        started.resolve();
+      });
+
+      child.once('error', (error) => {
+        started.reject(
+          new WringerError('environment', {
+            message: `The supervisor did not start: ${error.message}`,
+            hint: `Check that ${command} runs from ${options.root}.`,
+          }),
+        );
+      });
+
+      child.unref();
+
+      closeSync(log);
+
+      return started.promise;
+    },
+  };
+}