@wringer/core 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 the wringer authors
+Copyright (c) 2026 Geoff Whatley
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -9,8 +9,9 @@
 
 The core of wringer, a verification framework that each repo wraps in its own CLI.
 
-Every wringer command writes one JSON envelope. The package exports the envelope's version number,
-which a consumer checks before it reads the rest of the envelope.
+Every wringer command writes one JSON envelope, and a streaming command writes NDJSON events before
+it. The envelope carries `wringer: 1`, so a consumer checks the version before it reads the rest.
+The package publishes the envelope's JSON Schema as `@wringer/core/envelope.schema.json`.
 
 ## Install
 
@@ -19,3 +20,71 @@ bun add @wringer/core
 ```
 
 The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Usage
+
+A repo builds its registry with the typed builder, then hands it to a CLI adapter:
+
+```ts
+import { createWringer, local } from '@wringer/core';
+
+export const registry = createWringer({ name: 'shop' })
+  .target('local', {
+    mode: 'launch',
+    access: 'read-write',
+    host: local(),
+    launch: () => ({
+      command: ['bun', 'run', 'dev'],
+      ready: (line) => (line['event'] === 'listening' ? { web: 'http://127.0.0.1:3000' } : null),
+    }),
+  })
+  .feature({ name: 'checkout', summary: 'Pay for the cart', paths: ['src/checkout/**'] })
+  .build();
+```
+
+Add drivers with `.use(...)`. `bindDrivers(drivers)` returns `defineAction`, `defineTarget`,
+`defineCommand` and `defineCheck`, typed against those drivers, so a repo can define each one in its
+own file.
+
+## Features
+
+- The typed builder. Each action and command declares `effect: 'read' | 'write'`, and is a write
+  unless it says otherwise.
+- Read-only targets: each driver client and exec refuses a write there with `read-only` and the
+  target's hint. A target's driver config lists the writes it grants.
+- One supervisor process per run, which owns the app and every driver service.
+- The built-in commands, from `up` and `doctor` to `done`, `report` and `gate`.
+- The envelope's zod schema, and the JSON Schema built from it.
+- A closed set of error codes, each mapped to one exit code.
+- Run state on disk: `state.json` holds pointers, and each run's `log.ndjson` holds its events.
+- The fingerprint: `git patch-id --verbatim` of the working tree against the merge base, which stays
+  the same across a commit and across a clean rebase that leaves the 3 lines around each change as
+  they were. A rebase that changes those lines changes the fingerprint, because the hash keeps the
+  diff's context. It needs git 2.39 or later. Only the tracked files and git's defaults shape it:
+  the config, attributes and ignore files of the clone, the user and the system never apply, so the
+  same change gets the same fingerprint in any clone. A clone whose config converts a file as git
+  adds it, such as `core.autocrlf` or a clean filter, can get another fingerprint once the change is
+  committed; the verdict then reads as stale, never as fresh. A sparse checkout, a linked worktree,
+  a shallow or partial clone and a detached HEAD get the fingerprint of the same change in a full
+  clone, and a file on disk that the index marks skip-worktree counts as any other. A repo with no
+  commit, a shallow clone that lacks the merge base, and a submodule that holds work it has not
+  committed fail with an `environment` error.
+- Two hosts for exec: `local()`, and `ssh()` with an argv prefix in layers, quoted once per shell
+  layer. Each host also follows a long-running command, such as `tail -F`, line by line.
+
+## Error codes
+
+A command that passes exits `0`. A command that fails puts one of these in the envelope's
+`error.code`, and exits with its exit code:
+
+| Code                 | Exit | Meaning                                        |
+| -------------------- | ---- | ---------------------------------------------- |
+| `check-failed`       | 1    | A check or an assertion failed.                |
+| `usage`              | 2    | The command or its arguments are not valid.    |
+| `read-only`          | 3    | A read-only target refused a write.            |
+| `doctor-required`    | 3    | The doctor has not passed on the current run.  |
+| `not-running`        | 3    | The target has no running run.                 |
+| `target-not-allowed` | 3    | The command does not run on this target.       |
+| `environment`        | 4    | A tool, a host or the network failed.          |
+| `internal`           | 4    | wringer failed; the stack is in the run's log. |
+| `timeout`            | 5    | The command ran past its deadline.             |

package/dist/answer-supervisor-connection.d.ts

@@ -0,0 +1,8 @@
+import type { Duplex } from 'node:stream';
+import type { SupervisorRequest } from './supervisor-protocol.ts';
+export type SupervisorRequestHandler = (request: SupervisorRequest, signal: AbortSignal) => Promise<unknown>;
+export interface SupervisorConnectionOptions {
+    readonly answerRequest: SupervisorRequestHandler;
+    readonly onTransportError: (error: unknown) => void;
+}
+export declare function answerSupervisorConnection(connection: Duplex, options: SupervisorConnectionOptions, closing: AbortSignal): Promise<void>;

package/dist/app-machine.d.ts

@@ -0,0 +1,76 @@
+import type { Endpoints } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+interface AppMachineInput {
+    readonly readyTimeoutMs: number;
+    readonly reportCrash: (reason: string) => void;
+    readonly killGroup: () => void;
+    readonly stopApp: () => Promise<void>;
+}
+export type AppStart = {
+    readonly kind: 'pending';
+} | {
+    readonly kind: 'ready';
+    readonly endpoints: Endpoints;
+} | {
+    readonly kind: 'failed';
+    readonly failure: WringerError;
+};
+interface AppContext extends AppMachineInput {
+    readonly start: AppStart;
+    readonly logFailure: string | null;
+    readonly stopFailure: WringerError | null;
+}
+type AppEvent = {
+    readonly type: 'ready';
+    readonly endpoints: Endpoints;
+} | {
+    readonly type: 'exited';
+    readonly exitCode: number;
+} | {
+    readonly type: 'log.failed';
+    readonly reason: string;
+} | {
+    readonly type: 'abort';
+} | {
+    readonly type: 'stop';
+};
+export declare const appMachine: import("xstate").StateMachine<AppContext, AppEvent, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<null, {
+        readonly run: () => Promise<void>;
+    }, import("xstate").EventObject>> | undefined;
+}, {
+    src: "stopApp";
+    logic: import("xstate").PromiseActorLogic<null, {
+        readonly run: () => Promise<void>;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "failStart";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "failStartOnTimeout";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "keepEndpoints";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "keepLogFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "killGroup";
+    params: unknown;
+} | {
+    type: "reportCrash";
+    params: unknown;
+}, never, "readyTimeout", "crashed" | "failingStart" | "running" | "startFailed" | "starting" | "stopped" | "stopping", string, AppMachineInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    states: {
+        readonly starting: {};
+        readonly failingStart: {};
+        readonly startFailed: {};
+        readonly running: {};
+        readonly crashed: {};
+        readonly stopping: {};
+        readonly stopped: {};
+    };
+}, import("xstate").MetaObject>;
+export {};

package/dist/append-run-event.d.ts

@@ -0,0 +1,16 @@
+import type { StateFileSystem } from './create-node-state-file-system.ts';
+import type { RunEvent, RunEventType } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+export interface AppendRunEventRequest {
+    readonly fs: StateFileSystem;
+    readonly logPath: string;
+    readonly lockPath: string;
+    readonly lockTimeoutMs: number;
+    readonly line: string;
+    readonly event: RunEvent;
+    readonly refuse: ((events: readonly RunEvent[]) => WringerError | null) | null;
+}
+export declare function appendRunEvent(request: AppendRunEventRequest): Promise<boolean>;
+export type RunStatus = 'starting' | 'running' | 'crashed' | 'ended';
+export declare function findRunStatusMove(eventType: RunEventType): RunStatus | null;
+export declare function canMoveRunStatus(from: RunStatus, to: RunStatus): boolean;

package/dist/bind-drivers.d.ts

@@ -0,0 +1,9 @@
+import type { ActionDefinition, AnyDrivers, CheckDefinition, CommandSpec, TargetDefinition } from './types.ts';
+export interface BoundHelpers<Ds extends AnyDrivers> {
+    readonly drivers: Ds;
+    readonly defineAction: <Input, Data>(action: ActionDefinition<Input, Data, Ds>) => ActionDefinition<Input, Data, Ds>;
+    readonly defineTarget: <Target extends TargetDefinition<Ds>>(target: Target) => Target;
+    readonly defineCommand: <Args, Data>(spec: CommandSpec<Args, Data, Ds>) => CommandSpec<Args, Data, Ds>;
+    readonly defineCheck: <Input, Data>(check: CheckDefinition<Input, Data, Ds>) => CheckDefinition<Input, Data, Ds>;
+}
+export declare function bindDrivers<const Ds extends AnyDrivers>(drivers: Ds): BoundHelpers<Ds>;

package/dist/build-commands.d.ts

@@ -0,0 +1,5 @@
+import type { ActionDefinition, AnyDrivers, BuiltinCommandSpec, CheckDefinition, CommandSpec, RegisteredCommand, RunnableRepoCheck } from './types.ts';
+export declare function buildBuiltinCommand<Args, Data>(spec: BuiltinCommandSpec<Args, Data>): RegisteredCommand;
+export declare function buildRepoCommand<Args, Data, Ds extends AnyDrivers>(spec: CommandSpec<Args, Data, Ds>, targets: readonly string[] | undefined, driverNames: readonly string[]): RegisteredCommand;
+export declare function buildActionCommand<Input, Data, Ds extends AnyDrivers>(action: ActionDefinition<Input, Data, Ds>, driverNames: readonly string[]): RegisteredCommand;
+export declare function buildRepoCheck<Input, Data, Ds extends AnyDrivers>(check: CheckDefinition<Input, Data, Ds>, driverNames: readonly string[]): RunnableRepoCheck;

package/dist/build-envelope-json-schema.d.ts

@@ -0,0 +1 @@
+export declare function buildEnvelopeJSONSchema(): Record<string, unknown>;

package/dist/build-envelope.d.ts

@@ -0,0 +1,16 @@
+import type { Envelope, Evidence } from './envelope.ts';
+import type { WringerError } from './wringer-error.ts';
+export interface EnvelopeInput {
+    readonly command: string;
+    readonly target: string | null;
+    readonly instance: string | null;
+    readonly feature: string | null;
+    readonly sha: string | null;
+    readonly durationMs: number;
+    readonly data: unknown;
+    readonly evidence: readonly Evidence[];
+    readonly cursors: Readonly<Record<string, number>>;
+    readonly truncatedPath: string | null;
+    readonly error: WringerError | null;
+}
+export declare function buildEnvelope(input: EnvelopeInput): Envelope;

package/dist/build-launch-guard.d.ts

@@ -0,0 +1 @@
+export declare function buildLaunchGuard(setprivPath: string | null): readonly string[];

package/dist/build-manifest-write.d.ts

@@ -0,0 +1,6 @@
+import type { RunView } from './build-run-view.ts';
+export interface ManifestWrite {
+    readonly path: string;
+    readonly text: string;
+}
+export declare function buildManifestWrite(path: string, view: RunView | undefined): ManifestWrite | null;

package/dist/build-promised-object-reads.d.ts

@@ -0,0 +1,7 @@
+import type { GitRequest } from './run-git.ts';
+export interface PromisedObjectReadInput {
+    readonly root: string;
+    readonly mergeBase: string;
+    readonly configList: string;
+}
+export declare function buildPromisedObjectReads(input: PromisedObjectReadInput): GitRequest[];

package/dist/build-report.d.ts

@@ -0,0 +1,10 @@
+import type { 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>;
+}
+export declare function buildReport(input: ReportInput): Report;

package/dist/build-run-handle.d.ts

@@ -0,0 +1,2 @@
+import type { RunHandle } from './types.ts';
+export declare function buildRunHandle(stateDir: string, runID: string): RunHandle;

package/dist/build-run-view.d.ts

@@ -0,0 +1,29 @@
+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 declare function buildRunView(input: BuildRunViewInput): RunView | undefined;

package/dist/build-service-key.d.ts

@@ -0,0 +1 @@
+export declare function buildServiceKey(driver: string, service: string): string;

package/dist/build-shut-down-steps.d.ts

@@ -0,0 +1,14 @@
+import type { RunEvent } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+export interface ShutDownFacts {
+    readonly crashReason: string | null;
+    readonly gaveUpOnStartup: boolean;
+    readonly failures: readonly string[];
+    readonly at: string;
+}
+export interface ShutDownSteps {
+    readonly abortCommands: boolean;
+    readonly events: readonly RunEvent[];
+    readonly failure: WringerError | null;
+}
+export declare function buildShutDownSteps(facts: ShutDownFacts): ShutDownSteps;

package/dist/build-skip-worktree-marks.d.ts

@@ -0,0 +1,7 @@
+import type { GitRequest } from './run-git.ts';
+export interface SkipWorktreeMarkInput {
+    readonly root: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly taggedEntries: Uint8Array;
+}
+export declare function buildSkipWorktreeMarks(input: SkipWorktreeMarkInput): GitRequest[];

package/dist/build-spawn-error.d.ts

@@ -0,0 +1,2 @@
+import { WringerError } from './wringer-error.ts';
+export declare function buildSpawnError(command: string, error: unknown): WringerError;

package/dist/build-state-paths.d.ts

@@ -0,0 +1,21 @@
+import type { RunID } from './run-events.ts';
+export interface StatePaths {
+    readonly root: string;
+    readonly state: string;
+    readonly locks: string;
+    readonly runs: string;
+    readonly lateFailures: string;
+}
+export declare function buildStatePaths(stateDir: string): StatePaths;
+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;
+    readonly lock: string;
+}
+export declare function buildRunPaths(stateDir: string, runID: RunID): RunPaths;

package/dist/build-submodule-adds.d.ts

@@ -0,0 +1,7 @@
+import type { GitRequest } from './run-git.ts';
+export interface SubmoduleAddInput {
+    readonly root: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly stagedEntries: Uint8Array;
+}
+export declare function buildSubmoduleAdds(input: SubmoduleAddInput): GitRequest[];

package/dist/builtins/build-doctor-command.d.ts

@@ -0,0 +1,2 @@
+import type { RegisteredCommand } from '../types.ts';
+export declare function buildDoctorCommand(): RegisteredCommand;

package/dist/builtins/build-exec-command.d.ts

@@ -0,0 +1,2 @@
+import type { RegisteredCommand } from '../types.ts';
+export declare function buildExecCommand(): RegisteredCommand;

package/dist/builtins/build-lifecycle-commands.d.ts

@@ -0,0 +1,3 @@
+import type { RegisteredCommand } from '../types.ts';
+export declare const launchReadyTimeoutMs = 120000;
+export declare function buildLifecycleCommands(): readonly RegisteredCommand[];

package/dist/builtins/build-state-commands.d.ts

@@ -0,0 +1,2 @@
+import type { RegisteredCommand } from '../types.ts';
+export declare function buildStateCommands(): readonly RegisteredCommand[];

package/dist/builtins/build-use-pointers.d.ts

@@ -0,0 +1,9 @@
+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;
+    readonly cursors: Readonly<Record<string, number>>;
+    readonly runID: RunID | undefined;
+}
+export declare function buildUsePointers(current: Pointers, change: UseChange): Pointers;

package/dist/builtins/build-verdict-commands.d.ts

@@ -0,0 +1,2 @@
+import type { RegisteredCommand } from '../types.ts';
+export declare function buildVerdictCommands(): readonly RegisteredCommand[];

package/dist/builtins/call-run-supervisor.d.ts

@@ -0,0 +1,5 @@
+import type { RunView } from '../build-run-view.ts';
+import type { SupervisorPort } from '../types.ts';
+export type SupervisorReach = 'answered' | 'gone';
+export declare function callRunSupervisor(supervisor: SupervisorPort, run: RunView, method: 'ping' | 'stop', signal: AbortSignal): Promise<SupervisorReach>;
+export declare function isSupervisorGone(error: unknown): boolean;

package/dist/builtins/pick-doctor-outcome.d.ts

@@ -0,0 +1,13 @@
+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;
+    readonly failure: WringerError | null;
+}
+export declare function pickDoctorOutcome(results: readonly CheckResult[], at: string): DoctorOutcome;
+export {};

package/dist/builtins/pick-start-action.d.ts

@@ -0,0 +1,10 @@
+import type { RunStatus } from '../append-run-event.ts';
+import type { SupervisorReach } from './call-run-supervisor.ts';
+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';
+export declare function pickStartAction(facts: StartFacts): StartAction;

package/dist/builtins/pick-stop-plan.d.ts

@@ -0,0 +1,14 @@
+import type { RunView } from '../build-run-view.ts';
+import type { SupervisorReach } from './call-run-supervisor.ts';
+import type { StopData } from './stop-data-schema.ts';
+export interface StopInput {
+    readonly runID: string | undefined;
+    readonly status: RunView['status'] | undefined;
+    readonly reach: SupervisorReach;
+}
+export interface StopPlan {
+    readonly data: StopData;
+    readonly markCrashed: boolean;
+    readonly clearPointer: boolean;
+}
+export declare function pickStopPlan(input: StopInput): StopPlan;

package/dist/builtins/start-run.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { BuiltinContext } from '../types.ts';
+export declare const runDataSchema: z.ZodObject<{
+    run: z.ZodString;
+    target: z.ZodString;
+    status: z.ZodEnum<{
+        crashed: "crashed";
+        ended: "ended";
+        running: "running";
+        starting: "starting";
+    }>;
+    endpoints: z.ZodRecord<z.ZodString, z.ZodString>;
+    services: z.ZodArray<z.ZodString>;
+    reused: z.ZodBoolean;
+}, z.core.$strict>;
+export type RunData = z.infer<typeof runDataSchema>;
+export interface StartRunRequest {
+    readonly command: 'up' | 'attach';
+    readonly restart: boolean;
+    readonly readyTimeoutMs: number;
+}
+export declare function startRun(ctx: BuiltinContext, request: StartRunRequest): Promise<RunData>;

package/dist/builtins/stop-data-schema.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const stopDataSchema: z.ZodObject<{
+    run: z.ZodNullable<z.ZodString>;
+    stopped: z.ZodBoolean;
+}, z.core.$strict>;
+export type StopData = z.infer<typeof stopDataSchema>;

package/dist/builtins/stop-run.d.ts

@@ -0,0 +1,3 @@
+import type { BuiltinContext } from '../types.ts';
+import type { StopData } from './stop-data-schema.ts';
+export declare function stopRun(ctx: BuiltinContext): Promise<StopData>;

package/dist/call-supervisor.d.ts

@@ -0,0 +1,10 @@
+import type { SupervisorRequest } from './supervisor-protocol.ts';
+import { WringerError } from './wringer-error.ts';
+export interface SupervisorCall {
+    readonly socket: string;
+    readonly request: SupervisorRequest;
+    readonly signal: AbortSignal;
+}
+export declare function callSupervisor(call: SupervisorCall): Promise<unknown>;
+export declare const supervisorCancelWaitMs = 2000;
+export declare function buildUnconfirmedError(): WringerError;

package/dist/cap-data.d.ts

@@ -0,0 +1,17 @@
+import type { Evidence } from './envelope.ts';
+import type { EvidenceFiles } from './types.ts';
+import type { WringerError } from './wringer-error.ts';
+export declare const dataCapBytes: number;
+export interface CapRequest {
+    readonly root: string;
+    readonly directory: string;
+    readonly now: () => Date;
+    readonly files: EvidenceFiles;
+}
+export interface CappedData {
+    readonly data: unknown;
+    readonly evidence: readonly Evidence[];
+    readonly truncatedPath: string | null;
+    readonly failure: WringerError | null;
+}
+export declare function capData(data: unknown, request: CapRequest): Promise<CappedData>;

package/dist/collect-driver-configs.d.ts

@@ -0,0 +1,7 @@
+import type { ConfiguredDriver, DriverConfigContext, TargetDefinition, Wringer } from './types.ts';
+export interface ConfiguredEntry {
+    readonly name: string;
+    readonly serviceNames: readonly string[];
+    readonly configured: ConfiguredDriver;
+}
+export declare function collectDriverConfigs(wringer: Wringer, target: TargetDefinition, ctx: DriverConfigContext): readonly ConfiguredEntry[];

package/dist/create-directory.d.ts

@@ -0,0 +1 @@
+export declare function createDirectory(path: string): Promise<void>;

package/dist/create-evidence-writer.d.ts

@@ -0,0 +1,13 @@
+import type { Evidence } from './envelope.ts';
+import type { EvidenceFiles, EvidenceWriter } from './types.ts';
+export interface EvidenceWriterOptions {
+    readonly root: string;
+    readonly directory: string;
+    readonly now: () => Date;
+    readonly files: EvidenceFiles;
+}
+export interface CollectingEvidenceWriter {
+    readonly writer: EvidenceWriter;
+    readonly collected: readonly Evidence[];
+}
+export declare function createEvidenceWriter(options: EvidenceWriterOptions): CollectingEvidenceWriter;

package/dist/create-file-state.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { RunView } from './build-run-view.ts';
+import type { StatePaths } from './build-state-paths.ts';
+import type { StateFileSystem } from './create-node-state-file-system.ts';
+import type { LateFailureEvent, RunEvent, RunID } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+export declare const pointersSchema: z.ZodObject<{
+    currentRun: z.ZodRecord<z.ZodString, z.ZodString>;
+    target: z.ZodOptional<z.ZodString>;
+    feature: z.ZodOptional<z.ZodString>;
+    cursors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    cursorsRun: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+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>;
+    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 declare const eventSizeCapBytes: number;
+export declare function createFileState(options: FileStateOptions): StatePort;

package/dist/create-log-writer.d.ts

@@ -0,0 +1,5 @@
+export interface LogWriter {
+    readonly append: (text: string) => Promise<void>;
+    readonly close: () => Promise<void>;
+}
+export declare function createLogWriter(appendLog: (text: string) => Promise<void>): LogWriter;

package/dist/create-node-repo-host.d.ts

@@ -0,0 +1,2 @@
+import type { RepoHost } from './types.ts';
+export declare function createNodeRepoHost(): RepoHost;

package/dist/create-node-state-file-system.d.ts

@@ -0,0 +1,10 @@
+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 declare function createNodeStateFileSystem(): StateFileSystem;

package/dist/create-repo-state.d.ts

@@ -0,0 +1,2 @@
+import type { StatePort } from './create-file-state.ts';
+export declare function createRepoState(root: string, stateDir: string): StatePort;

package/dist/create-socket-folder.d.ts

@@ -0,0 +1 @@
+export declare function createSocketFolder(preferredSocket: string): Promise<string>;

package/dist/create-wringer.d.ts

@@ -0,0 +1,17 @@
+import type { ActionDefinition, AnyDriver, AnyDrivers, CheckDefinition, CommandSpec, FeatureDefinition, HookHandlers, TargetDefinition, Wringer } from './types.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;
+}
+export declare function createWringer(options: WringerOptions): WringerBuilder<readonly []>;
+export declare const defaultStateDir = ".wringer";