@wringer/core 0.0.0 → 0.1.1

package/src/create-file-state.ts

@@ -0,0 +1,193 @@
+import { basename, join } from 'node:path';
+import { withFileLock } from '@zgeoff/std/with-file-lock';
+import { z } from 'zod';
+import { appendRunEvent } from './append-run-event.ts';
+import { buildManifestWrite } from './build-manifest-write.ts';
+import { buildRunView } from './build-run-view.ts';
+import type { RunView } from './build-run-view.ts';
+import { buildRunPaths, buildStatePaths } from './build-state-paths.ts';
+import type { StatePaths } from './build-state-paths.ts';
+import type { StateFileSystem } from './create-node-state-file-system.ts';
+import { getLockValue } from './get-lock-value.ts';
+import { parseRunLog } from './parse-run-log.ts';
+import { lateFailureEventSchema, runEventSchema, runIDSchema } from './run-events.ts';
+import type { LateFailureEvent, RunEvent, RunID } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+
+export const pointersSchema = z.strictObject({
+  currentRun: z.record(z.string(), runIDSchema),
+  target: z.string().optional(),
+  feature: z.string().optional(),
+  cursors: z.record(z.string(), z.number().int().nonnegative()),
+  cursorsRun: runIDSchema.optional(),
+});
+
+export type Pointers = z.infer<typeof pointersSchema>;
+
+export type RunViewRefusal = (run: RunView | undefined) => WringerError | null;
+
+export interface StatePort {
+  readonly paths: StatePaths;
+  readonly readPointers: () => Promise<Pointers>;
+  readonly withTargetLock: <T>(target: string, work: () => Promise<T>) => Promise<T>;
+  readonly writePointers: (change: (current: Pointers) => Pointers) => Promise<Pointers>;
+  readonly appendEvent: (runID: RunID, event: RunEvent) => Promise<void>;
+
+  // Rejects with the refusal, and writes nothing, when `refuse` returns one for the run as its log
+  // stands under the run's lock.
+  readonly appendEventUnless: (
+    runID: RunID,
+    event: RunEvent,
+    refuse: RunViewRefusal,
+  ) => Promise<void>;
+  readonly appendLateFailure: (event: LateFailureEvent) => Promise<void>;
+  readonly readRunEvents: (runID: RunID) => Promise<readonly RunEvent[]>;
+  readonly readRun: (runID: RunID) => Promise<RunView | undefined>;
+  readonly listRuns: () => Promise<readonly RunID[]>;
+  readonly writeManifest: (runID: RunID) => Promise<void>;
+  readonly readCursors: (runID: RunID) => Promise<Record<string, number>>;
+}
+
+export interface FileStateOptions {
+  readonly stateDir: string;
+  readonly lockTimeoutMs: number;
+  readonly fs: StateFileSystem;
+}
+
+export const eventSizeCapBytes = 64 * 1024;
+
+export function createFileState(options: FileStateOptions): StatePort {
+  const paths = buildStatePaths(options.stateDir);
+  const fs = options.fs;
+
+  const withLock = async <T>(name: string, work: () => Promise<T>): Promise<T> => {
+    const path = join(paths.locks, name);
+
+    await fs.createDirectory(paths.locks);
+
+    const result = await withFileLock(path, work, { waitMs: options.lockTimeoutMs });
+
+    return getLockValue(path, result);
+  };
+
+  const readPointers = async (): Promise<Pointers> => {
+    const text = await fs.readText(paths.state);
+
+    if (text === null) {
+      return { currentRun: {}, cursors: {} };
+    }
+
+    const parsed: unknown = JSON.parse(text);
+
+    return pointersSchema.parse(parsed);
+  };
+
+  const readRunEvents = async (runID: RunID): Promise<readonly RunEvent[]> => {
+    const text = await fs.readText(buildRunPaths(options.stateDir, runID).log);
+
+    return parseRunLog(text ?? '');
+  };
+
+  const readRun = async (runID: RunID): Promise<RunView | undefined> => {
+    const events = await readRunEvents(runID);
+
+    return buildRunView({ runID, events });
+  };
+
+  const appendCheckedEvent = async (
+    runID: RunID,
+    event: RunEvent,
+    refuse: RunViewRefusal | null,
+  ): Promise<void> => {
+    const parsed = runEventSchema.parse(event);
+    const line = `${JSON.stringify(parsed)}\n`;
+    const lineBytes = Buffer.byteLength(line);
+
+    if (lineBytes > eventSizeCapBytes) {
+      throw new WringerError('internal', {
+        message: `A ${event.type} event of ${lineBytes} bytes is over the log's cap of ${eventSizeCapBytes} bytes.`,
+      });
+    }
+
+    const runPaths = buildRunPaths(options.stateDir, runID);
+
+    await fs.createDirectory(runPaths.directory);
+
+    await appendRunEvent({
+      fs,
+      logPath: runPaths.log,
+      lockPath: runPaths.lock,
+      lockTimeoutMs: options.lockTimeoutMs,
+      line,
+      event: parsed,
+      refuse: refuse === null ? null : (events) => refuse(buildRunView({ runID, events })),
+    });
+  };
+
+  return {
+    paths,
+    readPointers,
+    withTargetLock: (target, work) => withLock(`target-${target}.lock`, work),
+    writePointers: (change) =>
+      withLock('state.lock', async () => {
+        const current = await readPointers();
+
+        const next = pointersSchema.parse(change(current));
+
+        await fs.writeTextAtomic(paths.state, `${JSON.stringify(next, null, 2)}\n`);
+
+        return next;
+      }),
+    appendEvent: (runID, event) => appendCheckedEvent(runID, event, null),
+    appendEventUnless: (runID, event, refuse) => appendCheckedEvent(runID, event, refuse),
+    appendLateFailure: (event) =>
+      withLock('late-failures.lock', async () => {
+        const parsed = lateFailureEventSchema.parse(event);
+
+        await fs.appendText(paths.lateFailures, `${JSON.stringify(parsed)}\n`);
+      }),
+    readRunEvents,
+    readRun,
+    listRuns: async () => {
+      const names = await fs.listNames(paths.runs);
+
+      return names.flatMap((name) => {
+        const parsed = runIDSchema.safeParse(name);
+
+        return parsed.success ? [parsed.data] : [];
+      });
+    },
+
+    // Under the run's lock, so a manifest built from an older read never replaces a newer one.
+    writeManifest: (runID) =>
+      withLock(basename(buildRunPaths(options.stateDir, runID).lock), async () => {
+        const view = await readRun(runID);
+
+        const plan = buildManifestWrite(buildRunPaths(options.stateDir, runID).manifest, view);
+
+        if (plan !== null) {
+          await fs.writeTextAtomic(plan.path, plan.text);
+        }
+      }),
+
+    // A cursor is a byte offset into a stream's NDJSON file, so reading the cursors costs one size
+    // read per stream, however long the streams grow.
+    readCursors: async (runID) => {
+      const streams = buildRunPaths(options.stateDir, runID).streams;
+
+      const names = await fs.listNames(streams);
+
+      const files = names.filter((name) => name.endsWith('.ndjson'));
+
+      const sizes = await Promise.all(
+        files.map(async (name) => {
+          const size = await fs.readFileSize(join(streams, name));
+
+          return [basename(name, '.ndjson'), size] as const;
+        }),
+      );
+
+      return Object.fromEntries(sizes);
+    },
+  };
+}

package/src/create-log-writer.ts

@@ -0,0 +1,38 @@
+export interface LogWriter {
+  // Settles with the append's own result. An append after `close` writes nothing.
+  readonly append: (text: string) => Promise<void>;
+
+  // Settles once each append that came before it has, so nothing reaches the log after it.
+  readonly close: () => Promise<void>;
+}
+
+// Each append waits for the one before it, so the app's stdout and stderr reach the log one chunk
+// at a time, and a close knows the last write.
+export function createLogWriter(appendLog: (text: string) => Promise<void>): LogWriter {
+  let closed = false;
+  let last: Promise<unknown> = Promise.resolve();
+
+  const writeAfter = async (previous: Promise<unknown>, text: string): Promise<void> => {
+    await previous;
+    await appendLog(text);
+  };
+
+  return {
+    append: (text) => {
+      if (closed) {
+        return Promise.resolve();
+      }
+
+      const writing = writeAfter(last, text);
+
+      last = Promise.allSettled([writing]);
+
+      return writing;
+    },
+    close: async () => {
+      closed = true;
+
+      await last;
+    },
+  };
+}

package/src/create-node-repo-host.ts

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import { createDirectory } from './create-directory.ts';
+import { readText } from './read-text.ts';
+import { removeDirectory } from './remove-directory.ts';
+import { runGit, runGitBytes } from './run-git.ts';
+import type { RepoHost } from './types.ts';
+import { writeNewFile } from './write-new-file.ts';
+
+// The commands' view of this machine's git and disk, for an entry point to pass in.
+export function createNodeRepoHost(): RepoHost {
+  return {
+    runGit,
+    runGitBytes,
+    removeDirectory,
+    readText,
+    createDirectory,
+    writeNewFile,
+    readBytes: readFile,
+  };
+}

package/src/create-node-state-file-system.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { appendFile, readdir, rename, stat, truncate, writeFile } from 'node:fs/promises';
+import { readOptionalText } from '@zgeoff/std';
+import { createDirectory } from './create-directory.ts';
+import { isErrorCode } from './is-error-code.ts';
+
+// The file operations the run state needs. A missing file or folder reads as null or as no names;
+// every other failure, such as EACCES or EIO, rejects.
+export interface StateFileSystem {
+  readonly readText: (path: string) => Promise<string | null>;
+  readonly listNames: (directory: string) => Promise<readonly string[]>;
+  readonly readFileSize: (path: string) => Promise<number>;
+  readonly createDirectory: (path: string) => Promise<void>;
+  readonly appendText: (path: string, text: string) => Promise<void>;
+  readonly truncateFile: (path: string, length: number) => Promise<void>;
+  readonly writeTextAtomic: (path: string, text: string) => Promise<void>;
+}
+
+export function createNodeStateFileSystem(): StateFileSystem {
+  return {
+    readText: async (path) => {
+      const text = await readOptionalText(path);
+
+      return text ?? null;
+    },
+    listNames: async (directory) => {
+      try {
+        return await readdir(directory);
+      } catch (error) {
+        if (isErrorCode(error, 'ENOENT')) {
+          return [];
+        }
+
+        throw error;
+      }
+    },
+    createDirectory,
+    appendText: appendFile,
+    readFileSize: async (path) => {
+      const info = await stat(path);
+
+      return info.size;
+    },
+    truncateFile: truncate,
+    writeTextAtomic: async (path, text) => {
+      const temporary = `${path}.${randomUUID()}.tmp`;
+
+      await writeFile(temporary, text, { flag: 'wx' });
+      await rename(temporary, path);
+    },
+  };
+}

package/src/create-repo-state.ts

@@ -0,0 +1,15 @@
+import { join } from 'node:path';
+import { createFileState } from './create-file-state.ts';
+import type { StatePort } from './create-file-state.ts';
+import { createNodeStateFileSystem } from './create-node-state-file-system.ts';
+
+const lockTimeoutMs = 30_000;
+
+// The run state on disk under the repo's state folder, for an entry point to pass in.
+export function createRepoState(root: string, stateDir: string): StatePort {
+  return createFileState({
+    stateDir: join(root, stateDir),
+    lockTimeoutMs,
+    fs: createNodeStateFileSystem(),
+  });
+}

package/src/create-socket-folder.ts

@@ -0,0 +1,24 @@
+import { chmod, mkdir, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+// Unix socket paths are capped near 108 bytes.
+const maxSocketPathBytes = 100;
+
+// Only the owner may reach the socket: its folder is owner-only before the socket exists, whatever
+// the umask. A path too long for a socket moves to a fresh owner-only folder in the temp folder,
+// which `mkdtemp` names at random so no other user can claim it first. Returns the socket's path.
+export async function createSocketFolder(preferredSocket: string): Promise<string> {
+  if (Buffer.byteLength(preferredSocket) <= maxSocketPathBytes) {
+    const folder = dirname(preferredSocket);
+
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    await chmod(folder, 0o700);
+
+    return preferredSocket;
+  }
+
+  const folder = await mkdtemp(join(tmpdir(), 'wringer-'));
+
+  return join(folder, 'sock');
+}

package/src/create-wringer.ts

@@ -0,0 +1,169 @@
+import { buildActionCommand, buildRepoCheck, buildRepoCommand } from './build-commands.ts';
+import { buildDoctorCommand } from './builtins/build-doctor-command.ts';
+import { buildExecCommand } from './builtins/build-exec-command.ts';
+import { buildLifecycleCommands } from './builtins/build-lifecycle-commands.ts';
+import { buildStateCommands } from './builtins/build-state-commands.ts';
+import { buildVerdictCommands } from './builtins/build-verdict-commands.ts';
+import type {
+  ActionDefinition,
+  AnyDriver,
+  AnyDrivers,
+  CheckDefinition,
+  CommandSpec,
+  FeatureDefinition,
+  HookHandlers,
+  RegisteredCommand,
+  RunnableRepoCheck,
+  TargetDefinition,
+  Wringer,
+} from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface WringerOptions {
+  readonly name: string;
+  readonly stateDir?: string | undefined;
+}
+
+export interface WringerBuilder<Ds extends AnyDrivers> {
+  readonly use: <const Added extends readonly AnyDriver[]>(
+    ...drivers: Added
+  ) => WringerBuilder<readonly [...Ds, ...Added]>;
+  readonly target: (name: string, target: TargetDefinition<Ds>) => WringerBuilder<Ds>;
+  readonly command: <Args, Data>(spec: CommandSpec<Args, Data, Ds>) => WringerBuilder<Ds>;
+  readonly action: <Input, Data>(action: ActionDefinition<Input, Data, Ds>) => WringerBuilder<Ds>;
+  readonly check: <Input, Data>(check: CheckDefinition<Input, Data, Ds>) => WringerBuilder<Ds>;
+  readonly feature: (...features: readonly FeatureDefinition[]) => WringerBuilder<Ds>;
+  readonly hook: <Name extends keyof HookHandlers>(
+    name: Name,
+    handler: HookHandlers[Name],
+  ) => WringerBuilder<Ds>;
+  readonly build: () => Wringer;
+}
+
+// Each call returns a new builder. `build` adds the built-in commands, refuses a duplicate command
+// path or target name, then freezes the registry.
+export function createWringer(options: WringerOptions): WringerBuilder<readonly []> {
+  return makeBuilder({
+    options,
+    drivers: [],
+    targets: [],
+    commands: [],
+    checks: [],
+    features: [],
+    hooks: {},
+  });
+}
+
+interface Parts {
+  readonly options: WringerOptions;
+  readonly drivers: readonly AnyDriver[];
+  readonly targets: readonly (readonly [string, TargetDefinition])[];
+  readonly commands: readonly ((driverNames: readonly string[]) => RegisteredCommand)[];
+  readonly checks: readonly ((driverNames: readonly string[]) => RunnableRepoCheck)[];
+  readonly features: readonly FeatureDefinition[];
+  readonly hooks: Partial<HookHandlers>;
+}
+
+function makeBuilder<Ds extends AnyDrivers>(parts: Parts): WringerBuilder<Ds> {
+  return {
+    // oxlint-disable-next-line zgeoff/function-verb -- the public builder API names this step `use`
+    use: (...drivers) => makeBuilder({ ...parts, drivers: [...parts.drivers, ...drivers] }),
+    target: (name, target) =>
+      makeBuilder({ ...parts, targets: [...parts.targets, [name, target]] }),
+    command: (spec) =>
+      makeBuilder({
+        ...parts,
+        commands: [...parts.commands, (names) => buildRepoCommand(spec, undefined, names)],
+      }),
+    action: (action) =>
+      makeBuilder({
+        ...parts,
+        commands: [...parts.commands, (names) => buildActionCommand(action, names)],
+      }),
+    check: (check) =>
+      makeBuilder({ ...parts, checks: [...parts.checks, (names) => buildRepoCheck(check, names)] }),
+    feature: (...features) => makeBuilder({ ...parts, features: [...parts.features, ...features] }),
+    hook: (name, handler) => makeBuilder({ ...parts, hooks: { ...parts.hooks, [name]: handler } }),
+    build: () => buildWringer(parts),
+  };
+}
+
+export const defaultStateDir = '.wringer';
+
+function buildWringer(parts: Parts): Wringer {
+  if (parts.targets.length === 0) {
+    throw new WringerError('usage', { message: 'A wringer CLI needs at least one target.' });
+  }
+
+  const driverNames = parts.drivers.map((driver) => driver.name);
+
+  // A run keys each driver's services by its name, so a second driver of one name would replace
+  // the first one's services and leave them running past the run.
+  const repeated = driverNames.find((name, index) => driverNames.indexOf(name) !== index);
+
+  if (repeated !== undefined) {
+    throw new WringerError('usage', {
+      message: `Two drivers are named \`${repeated}\`.`,
+      hint: 'Give each driver its own name.',
+    });
+  }
+
+  const driverCommands = parts.drivers.flatMap((driver) =>
+    driver.commands.map((info): RegisteredCommand => ({
+      kind: 'driver',
+      info,
+      driver: driver.name,
+    })),
+  );
+
+  // A driver command reaches its client through the run's services, so it cannot run without one.
+  const runless = driverCommands.find((command) => command.info.needsRun === false);
+
+  if (runless !== undefined) {
+    throw new WringerError('usage', {
+      message: `The driver command \`${runless.info.path.join(' ')}\` needs a run, because its client calls the run's services.`,
+      hint: 'Leave `needsRun` unset on a driver command.',
+    });
+  }
+
+  const registered = [
+    ...buildLifecycleCommands(),
+    ...buildStateCommands(),
+    ...buildVerdictCommands(),
+    buildDoctorCommand(),
+    buildExecCommand(),
+    ...driverCommands,
+    ...parts.commands.map((buildEntry) => buildEntry(driverNames)),
+  ];
+
+  return Object.freeze({
+    name: parts.options.name,
+    stateDir: parts.options.stateDir ?? defaultStateDir,
+    drivers: Object.freeze([...parts.drivers]),
+    targets: buildUniqueMap(parts.targets, 'target'),
+    commands: buildUniqueMap(
+      registered.map((command) => [command.info.path.join(' '), command] as const),
+      'command',
+    ),
+    checks: Object.freeze(parts.checks.map((buildEntry) => buildEntry(driverNames))),
+    features: Object.freeze([...parts.features]),
+    hooks: Object.freeze({ ...parts.hooks }),
+  });
+}
+
+function buildUniqueMap<Value>(
+  entries: readonly (readonly [string, Value])[],
+  kind: string,
+): ReadonlyMap<string, Value> {
+  const map = new Map<string, Value>();
+
+  for (const [key, value] of entries) {
+    if (map.has(key)) {
+      throw new WringerError('usage', { message: `Two ${kind}s share the name \`${key}\`.` });
+    }
+
+    map.set(key, value);
+  }
+
+  return map;
+}

package/src/decide-guard.ts

@@ -0,0 +1,47 @@
+import type { RunView } from './build-run-view.ts';
+import type { Mode } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface GuardInput {
+  readonly needsRun: boolean;
+  readonly needsDoctor: boolean;
+  readonly run: RunView | undefined;
+  readonly targetName: string;
+  readonly mode: Mode;
+  readonly fingerprintChanged: boolean;
+}
+
+// The doctor fails closed: a drive command runs only on a running run whose own log holds a doctor
+// pass. A launched app runs this worktree's code, so its pass also needs the tree unchanged since
+// launch; an attached app runs code from elsewhere.
+export function decideGuard(input: GuardInput): WringerError | null {
+  const start = input.mode === 'launch' ? 'up' : 'attach';
+
+  if (input.needsRun && input.run?.status !== 'running') {
+    return new WringerError('not-running', {
+      message: `Target ${input.targetName} has no running run.`,
+      hint: `Run \`${start} --target ${input.targetName}\` first.`,
+    });
+  }
+
+  if (!input.needsDoctor) {
+    return null;
+  }
+
+  if (input.run?.doctor !== 'passed') {
+    return new WringerError('doctor-required', {
+      message: `The doctor has not passed on run ${input.run?.runID ?? 'none'}.`,
+      hint: `Run \`doctor --target ${input.targetName}\`, and fix what it reports.`,
+    });
+  }
+
+  if (input.fingerprintChanged) {
+    return new WringerError('doctor-required', {
+      message:
+        'The working tree changed since this run started, so its doctor pass no longer holds.',
+      hint: 'Run `up --restart`, then `doctor`.',
+    });
+  }
+
+  return null;
+}