@wringer/core 0.1.0 → 0.1.2

package/dist/types.d.ts

@@ -0,0 +1,353 @@
+import type { z } from 'zod';
+import type { RunView } from './build-run-view.ts';
+import type { RunPaths } from './build-state-paths.ts';
+import type { SupervisorCall } from './call-supervisor.ts';
+import type { StatePort } from './create-file-state.ts';
+import type { Evidence } from './envelope.ts';
+import type { Access, Host } from './host.ts';
+import type { LaunchLine } from './launch-line-schema.ts';
+import type { FingerprintHost } from './read-fingerprint.ts';
+import type { Endpoints, RunID } from './run-events.ts';
+import type { ProcessResult } from './run-process.ts';
+export type Effect = 'read' | 'write';
+export type Emit = (event: string, data: unknown) => void;
+export interface EvidenceWriter {
+    readonly directory: string;
+    readonly writeFile: (kind: string, name: string, content: string | Uint8Array) => Promise<Evidence>;
+    readonly addFile: (kind: string, path: string) => Promise<Evidence>;
+}
+export interface ExecOptions {
+    readonly stdin?: string | undefined;
+}
+export type RepoExec = (argv: readonly string[], options?: ExecOptions) => Promise<ProcessResult>;
+export type DriverExec = (argv: readonly string[], effect: Effect, options?: ExecOptions) => Promise<ProcessResult>;
+export interface ChildLog {
+    readonly path: string;
+}
+export interface RunHandle {
+    readonly id: string;
+    readonly paths: RunPaths;
+    readonly childLog: (name: string) => ChildLog;
+}
+export interface DriverConfigContext {
+    readonly target: string;
+    readonly endpoints: Endpoints;
+    readonly run: RunHandle;
+}
+export interface ServiceCaller {
+    readonly call: (method: string, args: unknown) => Promise<unknown>;
+}
+export interface DriverSession<Options, TargetConfig> {
+    readonly target: string;
+    readonly access: Access;
+    readonly options: Options;
+    readonly config: TargetConfig;
+    readonly endpoints: Endpoints;
+    readonly run: RunHandle;
+    readonly exec: DriverExec;
+    readonly evidence: EvidenceWriter;
+    readonly cursors: Readonly<Record<string, number>>;
+    readonly signal: AbortSignal;
+    readonly timeLeftMs: () => number;
+    readonly service: (name: string) => ServiceCaller;
+}
+export interface ClientCall<Args, Result> {
+    readonly effect: (args: Args) => Effect;
+    readonly describe: (args: Args) => string;
+    readonly run: (args: Args) => Promise<Result>;
+}
+export type Fence = <Args, Result>(call: ClientCall<Args, Result>) => (args: Args) => Promise<Result>;
+export interface ServiceContext<Options, TargetConfig> {
+    readonly target: string;
+    readonly access: Access;
+    readonly options: Options;
+    readonly config: TargetConfig;
+    readonly endpoints: Endpoints;
+    readonly run: RunHandle;
+    readonly host: Host;
+    readonly exec: DriverExec;
+    readonly signal: AbortSignal;
+}
+export type ServiceMethod = (args: unknown, signal: AbortSignal) => Promise<unknown>;
+export interface ServiceInstance {
+    readonly methods: Readonly<Record<string, ServiceMethod>>;
+    readonly stop: () => Promise<void>;
+}
+export interface ServiceDefinition<Options, TargetConfig> {
+    readonly start: (ctx: ServiceContext<Options, TargetConfig>) => Promise<ServiceInstance>;
+}
+export interface CommandShape<Args, Data> {
+    readonly path: readonly string[];
+    readonly summary: string;
+    readonly args: z.ZodType<Args>;
+    readonly positionals?: readonly string[] | undefined;
+    readonly data: z.ZodType<Data>;
+    readonly effect?: Effect | undefined;
+    readonly needsRun?: boolean | undefined;
+    readonly needsDoctor?: boolean | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+export type CommandInfo = CommandShape<unknown, unknown> & {
+    readonly decideEffect?: unknown;
+};
+export interface DriverCommandContext<Options, TargetConfig, Client> {
+    readonly session: DriverSession<Options, TargetConfig>;
+    readonly client: Client;
+    readonly feature: string | null;
+    readonly emit: Emit;
+}
+export interface DriverCommandSpec<Args, Data, Options, TargetConfig, Client> extends CommandShape<Args, Data> {
+    readonly decideEffect?: ((args: Args, config: TargetConfig) => Effect) | undefined;
+    readonly run: (args: Args, ctx: DriverCommandContext<Options, TargetConfig, Client>) => Promise<Data>;
+}
+export type ArgsResult<Prepared> = {
+    readonly ok: true;
+    readonly prepared: Prepared;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export interface PreparedDriverCommand<Options, TargetConfig, Client> {
+    readonly decideEffect: (config: TargetConfig) => Effect;
+    readonly run: (ctx: DriverCommandContext<Options, TargetConfig, Client>) => Promise<unknown>;
+}
+export interface DriverCommand<Options, TargetConfig, Client> {
+    readonly info: CommandInfo;
+    readonly prepare: (raw: unknown) => ArgsResult<PreparedDriverCommand<Options, TargetConfig, Client>>;
+}
+export type DriverCommandHelper<Options, TargetConfig, Client> = <Args, Data>(spec: DriverCommandSpec<Args, Data, Options, TargetConfig, Client>) => DriverCommand<Options, TargetConfig, Client>;
+export interface DriverCheckDefinition<Options, TargetConfig, Client> {
+    readonly name: string;
+    readonly timeoutMs: number;
+    readonly run: (ctx: DriverCommandContext<Options, TargetConfig, Client>) => Promise<void>;
+}
+export interface SessionParts {
+    readonly target: string;
+    readonly access: Access;
+    readonly endpoints: Endpoints;
+    readonly run: RunHandle;
+    readonly exec: DriverExec;
+    readonly evidence: EvidenceWriter;
+    readonly cursors: Readonly<Record<string, number>>;
+    readonly signal: AbortSignal;
+    readonly timeLeftMs: () => number;
+    readonly fence: Fence;
+    readonly service: (name: string) => ServiceCaller;
+}
+export interface ServiceParts {
+    readonly target: string;
+    readonly access: Access;
+    readonly endpoints: Endpoints;
+    readonly run: RunHandle;
+    readonly host: Host;
+    readonly exec: DriverExec;
+    readonly signal: AbortSignal;
+}
+export interface PreparedRun {
+    readonly effect: Effect;
+    readonly run: (feature: string | null, emit: Emit) => Promise<unknown>;
+}
+export interface RunnableCheck {
+    readonly name: string;
+    readonly timeoutMs: number;
+    readonly run: (feature: string | null, emit: Emit) => Promise<void>;
+}
+export interface OpenedDriver {
+    readonly client: unknown;
+    readonly checks: readonly RunnableCheck[];
+    readonly prepare: (pathKey: string, raw: unknown) => ArgsResult<PreparedRun>;
+}
+export interface ConfiguredDriver {
+    readonly open: (parts: SessionParts) => OpenedDriver;
+    readonly startService: (name: string, parts: ServiceParts) => Promise<ServiceInstance>;
+}
+export interface DriverTypes<Client, ConfigInput> {
+    readonly client: Client;
+    readonly config: ConfigInput;
+}
+export interface Driver<Name extends string, Client, ConfigInput> {
+    readonly kind: 'driver';
+    readonly name: Name;
+    readonly commands: readonly CommandInfo[];
+    readonly serviceNames: readonly string[];
+    readonly configure: (input: unknown) => ArgsResult<ConfiguredDriver>;
+    readonly types?: DriverTypes<Client, ConfigInput>;
+}
+export type AnyDriver = Driver<string, unknown, unknown>;
+export type AnyDrivers = readonly AnyDriver[];
+export type DriverClients<Ds extends AnyDrivers> = {
+    readonly [D in Ds[number] as D['name']]: D extends Driver<string, infer Client, unknown> ? Client : never;
+};
+export type DriverConfigs<Ds extends AnyDrivers> = {
+    readonly [D in Ds[number] as D['name']]?: (ctx: DriverConfigContext) => D extends Driver<string, unknown, infer ConfigInput> ? ConfigInput : never;
+};
+export interface DriveContext<Ds extends AnyDrivers = AnyDrivers> {
+    readonly target: string;
+    readonly access: Access;
+    readonly feature: string | null;
+    readonly endpoints: Endpoints;
+    readonly drivers: DriverClients<Ds>;
+    readonly exec: RepoExec;
+    readonly evidence: EvidenceWriter;
+    readonly signal: AbortSignal;
+    readonly emit: Emit;
+}
+export interface CommandSpec<Args, Data, Ds extends AnyDrivers = AnyDrivers> extends CommandShape<Args, Data> {
+    readonly decideEffect?: ((args: Args) => Effect) | undefined;
+    readonly run: (args: Args, ctx: DriveContext<Ds>) => Promise<Data>;
+}
+export interface ActionDefinition<Input, Data, Ds extends AnyDrivers = AnyDrivers> {
+    readonly name: string;
+    readonly summary: string;
+    readonly effect: Effect;
+    readonly targets?: readonly string[] | undefined;
+    readonly input: z.ZodType<Input>;
+    readonly data: z.ZodType<Data>;
+    readonly timeoutMs?: number | undefined;
+    readonly run: (input: Input, ctx: DriveContext<Ds>) => Promise<Data>;
+}
+export interface CheckDefinition<Input, Data, Ds extends AnyDrivers = AnyDrivers> {
+    readonly name: string;
+    readonly input: z.ZodType<Input>;
+    readonly data: z.ZodType<Data>;
+    readonly timeoutMs: number;
+    readonly run: (input: Input, ctx: DriveContext<Ds>) => Promise<Data>;
+}
+export interface FeatureDefinition {
+    readonly name: string;
+    readonly summary: string;
+    readonly paths: readonly string[];
+}
+export interface UploadRequest {
+    readonly path: string;
+    readonly kind: string;
+    readonly sha256: string;
+}
+export interface HookHandlers {
+    readonly upload: (file: UploadRequest) => Promise<string>;
+}
+export interface LaunchContext {
+    readonly runDirectory: string;
+}
+export interface LaunchPlan {
+    readonly command: readonly string[];
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    readonly cwd?: string | undefined;
+    readonly ready: (line: LaunchLine) => Endpoints | null;
+    readonly stop?: readonly string[] | undefined;
+}
+interface TargetBase<Ds extends AnyDrivers> {
+    readonly access: Access;
+    readonly refusalHint?: string | undefined;
+    readonly host: Host;
+    readonly drivers?: DriverConfigs<Ds> | undefined;
+}
+export interface EndpointsContext {
+    readonly target: string;
+}
+export interface LaunchTarget<Ds extends AnyDrivers> extends TargetBase<Ds> {
+    readonly mode: 'launch';
+    readonly launch: (ctx: LaunchContext) => LaunchPlan;
+    readonly endpoints?: never;
+}
+export interface AttachTarget<Ds extends AnyDrivers> extends TargetBase<Ds> {
+    readonly mode: 'attach';
+    readonly endpoints?: ((ctx: EndpointsContext) => Endpoints | Promise<Endpoints>) | undefined;
+    readonly launch?: never;
+}
+export type TargetDefinition<Ds extends AnyDrivers = AnyDrivers> = LaunchTarget<Ds> | AttachTarget<Ds>;
+export interface Drive {
+    readonly ctx: DriveContext;
+    readonly drivers: ReadonlyMap<string, OpenedDriver>;
+    readonly evidence: readonly Evidence[];
+}
+export interface Deadline {
+    readonly signal: AbortSignal;
+    readonly at: number;
+}
+export interface BuiltinContext {
+    readonly wringer: Wringer;
+    readonly state: StatePort;
+    readonly session: Session;
+    readonly stateDir: string;
+    readonly targetName: string;
+    readonly target: TargetDefinition;
+    readonly run: RunView | undefined;
+    readonly feature: string | null;
+    readonly signal: AbortSignal;
+    readonly deadlineAt: number;
+    readonly now: () => Date;
+    readonly wait: (delayMs: number) => Promise<void>;
+    readonly emit: Emit;
+    readonly openDrive: (access: Access, deadline?: Deadline) => Drive;
+    readonly bindRun: (runID: RunID) => void;
+    readonly keepLate: (work: Promise<void>) => void;
+}
+export interface BuiltinCommandSpec<Args, Data> extends CommandShape<Args, Data> {
+    readonly run: (args: Args, ctx: BuiltinContext) => Promise<Data>;
+}
+export interface PreparedCommand<Ctx> {
+    readonly effect: Effect;
+    readonly run: (ctx: Ctx) => Promise<unknown>;
+}
+export type RegisteredCommand = {
+    readonly kind: 'repo';
+    readonly info: CommandInfo;
+    readonly targets: readonly string[] | undefined;
+    readonly prepare: (raw: unknown) => ArgsResult<PreparedCommand<DriveContext>>;
+} | {
+    readonly kind: 'builtin';
+    readonly info: CommandInfo;
+    readonly prepare: (raw: unknown) => ArgsResult<PreparedCommand<BuiltinContext>>;
+} | {
+    readonly kind: 'driver';
+    readonly info: CommandInfo;
+    readonly driver: string;
+};
+export interface RunnableRepoCheck {
+    readonly name: string;
+    readonly timeoutMs: number;
+    readonly run: (ctx: DriveContext) => Promise<void>;
+}
+export interface Wringer {
+    readonly name: string;
+    readonly stateDir: string;
+    readonly drivers: AnyDrivers;
+    readonly targets: ReadonlyMap<string, TargetDefinition>;
+    readonly commands: ReadonlyMap<string, RegisteredCommand>;
+    readonly checks: readonly RunnableRepoCheck[];
+    readonly features: readonly FeatureDefinition[];
+    readonly hooks: Partial<HookHandlers>;
+}
+export interface SupervisorStartRequest {
+    readonly runID: string;
+    readonly target: string;
+}
+export interface SupervisorPort {
+    readonly start: (request: SupervisorStartRequest) => Promise<void>;
+    readonly call: (call: SupervisorCall) => Promise<unknown>;
+}
+export interface OutputPort {
+    readonly writeLine: (line: string) => void;
+}
+export interface EvidenceFiles {
+    readonly createDirectory: (path: string) => Promise<void>;
+    readonly writeNewFile: (path: string, bytes: Uint8Array) => Promise<boolean>;
+    readonly readBytes: (path: string) => Promise<Uint8Array>;
+}
+export interface RepoHost extends FingerprintHost, EvidenceFiles {
+    readonly readText: (path: string) => Promise<string>;
+}
+export interface Session {
+    readonly root: string;
+    readonly state: StatePort;
+    readonly repoHost: RepoHost;
+    readonly target?: string | undefined;
+    readonly feature?: string | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly output: OutputPort;
+    readonly supervisor: SupervisorPort;
+    readonly now?: (() => Date) | undefined;
+    readonly wait?: ((delayMs: number) => Promise<void>) | undefined;
+}
+export {};

package/dist/wait-for-cancelled-calls.d.ts

@@ -0,0 +1,2 @@
+import type { WringerError } from './wringer-error.ts';
+export declare function waitForCancelledCalls(calls: readonly Promise<unknown>[]): Promise<WringerError | null>;

package/dist/wringer-error.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorCode } from './error-codes.ts';
+export interface WringerErrorDetails {
+    readonly message?: string;
+    readonly hint?: string;
+    readonly data?: unknown;
+}
+export declare class WringerError extends Error {
+    readonly code: ErrorCode;
+    readonly hint: string | undefined;
+    readonly data: unknown;
+    constructor(code: ErrorCode, details?: WringerErrorDetails);
+}

package/dist/write-envelope-log.d.ts

@@ -0,0 +1,11 @@
+import type { RunView } from './build-run-view.ts';
+import type { RunViewRefusal, StatePort } from './create-file-state.ts';
+import type { Envelope } from './envelope.ts';
+import type { WringerError } from './wringer-error.ts';
+export interface LogRequest {
+    readonly drive: boolean;
+    readonly failure: WringerError | null;
+    readonly now: () => Date;
+    readonly refuse: RunViewRefusal | null;
+}
+export declare function writeEnvelopeLog(state: StatePort, run: RunView, envelope: Envelope, request: LogRequest): Promise<WringerError | null>;

package/dist/write-late-failure.d.ts

@@ -0,0 +1,11 @@
+import type { StatePort } from './create-file-state.ts';
+import type { RunID } from './run-events.ts';
+import type { WringerError } from './wringer-error.ts';
+export interface LateFailureRequest {
+    readonly state: StatePort;
+    readonly runID: RunID | null;
+    readonly command: string;
+    readonly answered: WringerError | null;
+    readonly now: () => Date;
+}
+export declare function writeLateFailure(work: Promise<unknown>, request: LateFailureRequest): Promise<void>;

package/dist/write-new-file.d.ts

@@ -0,0 +1 @@
+export declare function writeNewFile(path: string, bytes: Uint8Array): Promise<boolean>;

package/envelope.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@wringer/core/envelope.schema.json",
+  "title": "wringer envelope",
+  "$defs": {
+    "envelope": {
+      "type": "object",
+      "properties": {
+        "wringer": {
+          "type": "number",
+          "const": 1
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "target": {
+          "type": ["string", "null"]
+        },
+        "instance": {
+          "type": ["string", "null"]
+        },
+        "feature": {
+          "type": ["string", "null"]
+        },
+        "sha": {
+          "type": ["string", "null"]
+        },
+        "durationMs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "data": {},
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "minLength": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              }
+            },
+            "required": ["kind", "path", "sha256"],
+            "additionalProperties": false
+          }
+        },
+        "cursors": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          }
+        },
+        "truncated": {
+          "type": "boolean",
+          "const": true
+        },
+        "truncatedPath": {
+          "type": "string"
+        },
+        "error": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "enum": [
+                    "check-failed",
+                    "usage",
+                    "read-only",
+                    "doctor-required",
+                    "not-running",
+                    "target-not-allowed",
+                    "environment",
+                    "internal",
+                    "timeout"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                },
+                "hint": {
+                  "type": ["string", "null"]
+                }
+              },
+              "required": ["code", "message", "hint"],
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "wringer",
+        "ok",
+        "command",
+        "target",
+        "instance",
+        "feature",
+        "sha",
+        "durationMs",
+        "data",
+        "evidence",
+        "cursors",
+        "error"
+      ],
+      "additionalProperties": false,
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "error": {
+              "type": "null"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "error": {
+              "type": "object"
+            }
+          }
+        }
+      ],
+      "dependentRequired": {
+        "truncated": ["truncatedPath"],
+        "truncatedPath": ["truncated"]
+      }
+    },
+    "streamEvent": {
+      "type": "object",
+      "properties": {
+        "wringer": {
+          "type": "number",
+          "const": 1
+        },
+        "event": {
+          "type": "string",
+          "minLength": 1
+        },
+        "data": {}
+      },
+      "required": ["wringer", "event", "data"],
+      "additionalProperties": false
+    }
+  },
+  "$ref": "#/$defs/envelope"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wringer/core",
-  "version": "0.1.0",
-  "description": "The core of wringer: the JSON envelope that every wringer command writes",
+  "version": "0.1.2",
+  "description": "The core of wringer: the envelope, the registry, the fence, the run state and the evidence",
   "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/core#readme",
   "bugs": "https://github.com/zgeoff/wringer/issues",
   "license": "MIT",
@@ -13,21 +13,37 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
-    "dist"
+    "dist",
+    "envelope.schema.json",
+    "!src/test-utils"
   ],
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./envelope.schema.json": "./envelope.schema.json",
+    "./test-utils/*": "./src/test-utils/*"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "rm -rf dist && tsrs -p tsconfig.build.json",
-    "typecheck": "tsrs --noEmit"
+    "typecheck": "tsrs --noEmit",
+    "schema": "bun scripts/write-envelope-schema.ts"
+  },
+  "dependencies": {
+    "@zgeoff/std": "0.4.3",
+    "ts-pattern": "5.9.2",
+    "xstate": "5.33.3",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@zgeoff/testing": "0.3.0",
+    "ajv": "8.20.0",
+    "tiny-invariant": "1.3.3"
   },
   "engines": {
     "bun": ">=1.3"