@wringer/core 0.1.0 → 0.1.2

package/dist/read-launch-host.d.ts

@@ -0,0 +1,26 @@
+import type { SupervisorSocket, SupervisorSocketOptions } from './listen-supervisor-socket.ts';
+import type { ProcessRequest, ProcessResult } from './run-process.ts';
+export interface AppSpawnOptions {
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface AppProcess {
+    readonly pid: number;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    readonly exited: Promise<number>;
+}
+export interface LaunchHost {
+    readonly guard: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly spawnApp: (argv: readonly string[], options: AppSpawnOptions) => AppProcess;
+    readonly appendLog: (path: string, text: string) => Promise<void>;
+    readonly createDirectory: (path: string) => Promise<void>;
+    readonly createSocketFolder: (preferredSocket: string) => Promise<string>;
+    readonly removeDirectory: (path: string) => Promise<void>;
+    readonly listenSupervisorSocket: (options: SupervisorSocketOptions) => Promise<SupervisorSocket>;
+    readonly killProcessGroup: (pid: number, signal?: NodeJS.Signals) => void;
+    readonly runProcess: (request: ProcessRequest) => Promise<ProcessResult>;
+}
+export declare function readLaunchHost(): LaunchHost;

package/dist/read-pid-namespace.d.ts

@@ -0,0 +1 @@
+export declare function readPIDNamespace(): string;

package/dist/read-stream-line-batches.d.ts

@@ -0,0 +1,2 @@
+export declare const streamLineCapChars: number;
+export declare function readStreamLineBatches(stream: ReadableStream<Uint8Array>): AsyncGenerator<readonly string[], void, undefined>;

package/dist/read-stream-lines.d.ts

@@ -0,0 +1,2 @@
+export { streamLineCapChars } from './read-stream-line-batches.ts';
+export declare function readStreamLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string, void, undefined>;

package/dist/read-text.d.ts

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

package/dist/read-verdicts.d.ts

@@ -0,0 +1,5 @@
+import type { StatePort } from './create-file-state.ts';
+import type { Verdict } from './report-schema.ts';
+import type { RepoHost } from './types.ts';
+export declare const doneCommand = "done";
+export declare function readVerdicts(state: StatePort, host: Pick<RepoHost, 'readText'>, root: string): Promise<ReadonlyMap<string, Verdict>>;

package/dist/remove-directory.d.ts

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

package/dist/remove-file.d.ts

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

package/dist/render-report-markdown.d.ts

@@ -0,0 +1,4 @@
+import type { Report } from './report-schema.ts';
+export declare const reportBlockOpen = "<!-- wringer-report v1";
+export declare const reportBlockClose = "-->";
+export declare function renderReportMarkdown(report: Report): string;

package/dist/report-schema.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export declare const verdictSchema: z.ZodObject<{
+    feature: z.ZodString;
+    fingerprint: z.ZodString;
+    run: z.ZodString;
+    at: z.ZodISODateTime;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        path: z.ZodString;
+        sha256: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Verdict = z.infer<typeof verdictSchema>;
+declare const featureStatusSchema: z.ZodEnum<{
+    missing: "missing";
+    stale: "stale";
+    unchanged: "unchanged";
+    verified: "verified";
+}>;
+export type FeatureStatus = z.infer<typeof featureStatusSchema>;
+export declare const reportSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    base: z.ZodString;
+    fingerprint: z.ZodString;
+    complete: z.ZodBoolean;
+    features: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        changed: z.ZodBoolean;
+        status: z.ZodEnum<{
+            missing: "missing";
+            stale: "stale";
+            unchanged: "unchanged";
+            verified: "verified";
+        }>;
+        verdict: z.ZodNullable<z.ZodObject<{
+            feature: z.ZodString;
+            fingerprint: z.ZodString;
+            run: z.ZodString;
+            at: z.ZodISODateTime;
+            evidence: z.ZodArray<z.ZodObject<{
+                kind: z.ZodString;
+                path: z.ZodString;
+                sha256: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Report = z.infer<typeof reportSchema>;
+export {};

package/dist/run-events.d.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+export declare const runIDSchema: z.ZodString;
+export type RunID = z.infer<typeof runIDSchema>;
+export declare const modeSchema: z.ZodEnum<{
+    attach: "attach";
+    launch: "launch";
+}>;
+export type Mode = z.infer<typeof modeSchema>;
+export declare const endpointsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type Endpoints = z.infer<typeof endpointsSchema>;
+export declare const checkResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+    }>;
+    durationMs: z.ZodNumber;
+    code: z.ZodNullable<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type CheckResult = z.infer<typeof checkResultSchema>;
+export declare const lateFailureEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"late-failure">;
+    at: z.ZodISODateTime;
+    command: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type LateFailureEvent = z.infer<typeof lateFailureEventSchema>;
+export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"run-started">;
+    at: z.ZodISODateTime;
+    target: z.ZodString;
+    mode: z.ZodEnum<{
+        attach: "attach";
+        launch: "launch";
+    }>;
+    fingerprint: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"supervisor-ready">;
+    at: z.ZodISODateTime;
+    pid: z.ZodNumber;
+    socket: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"launch-ready">;
+    at: z.ZodISODateTime;
+    endpoints: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"service-ready">;
+    at: z.ZodISODateTime;
+    service: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"run-ready">;
+    at: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodEnum<{
+        "doctor-failed": "doctor-failed";
+        "doctor-passed": "doctor-passed";
+    }>;
+    at: z.ZodISODateTime;
+    results: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>;
+        durationMs: z.ZodNumber;
+        code: z.ZodNullable<z.ZodString>;
+        message: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"envelope">;
+    at: z.ZodISODateTime;
+    drive: z.ZodBoolean;
+    envelope: z.ZodObject<{
+        wringer: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        target: z.ZodNullable<z.ZodString>;
+        instance: z.ZodNullable<z.ZodString>;
+        feature: z.ZodNullable<z.ZodString>;
+        sha: z.ZodNullable<z.ZodString>;
+        durationMs: z.ZodNumber;
+        data: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+        evidence: z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            path: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+        cursors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        truncated: z.ZodOptional<z.ZodLiteral<true>>;
+        truncatedPath: z.ZodOptional<z.ZodString>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodEnum<{
+                "check-failed": "check-failed";
+                "doctor-required": "doctor-required";
+                environment: "environment";
+                internal: "internal";
+                "not-running": "not-running";
+                "read-only": "read-only";
+                "target-not-allowed": "target-not-allowed";
+                timeout: "timeout";
+                usage: "usage";
+            }>;
+            message: z.ZodString;
+            hint: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"internal-error">;
+    at: z.ZodISODateTime;
+    command: z.ZodString;
+    stack: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"late-failure">;
+    at: z.ZodISODateTime;
+    command: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"crashed">;
+    at: z.ZodISODateTime;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"run-ended">;
+    at: z.ZodISODateTime;
+}, z.core.$strict>], "type">;
+export type RunEvent = z.infer<typeof runEventSchema>;
+export type RunEventType = RunEvent['type'];

package/dist/run-git.d.ts

@@ -0,0 +1,9 @@
+import type { ProcessResult } from './run-process.ts';
+export interface GitRequest {
+    readonly cwd: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    readonly stdin?: string | Uint8Array | undefined;
+}
+export declare function runGit(request: GitRequest): Promise<ProcessResult>;
+export declare function runGitBytes(request: GitRequest): Promise<Uint8Array>;

package/dist/run-process.d.ts

@@ -0,0 +1,19 @@
+export interface ProcessRequest {
+    readonly argv: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    readonly stdin?: string | Uint8Array | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface ProcessResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function runProcess(request: ProcessRequest): Promise<ProcessResult>;
+export interface ProcessBytesResult {
+    readonly exitCode: number;
+    readonly stdout: Uint8Array;
+    readonly stderr: string;
+}
+export declare function runProcessBytes(request: ProcessRequest): Promise<ProcessBytesResult>;

package/dist/run-supervisor-process.d.ts

@@ -0,0 +1,2 @@
+import type { Wringer } from './types.ts';
+export declare function runSupervisorProcess(wringer: Wringer, argv: readonly string[]): Promise<void>;

package/dist/run-supervisor.d.ts

@@ -0,0 +1,16 @@
+import type { StatePort } from './create-file-state.ts';
+import type { LaunchHost } from './read-launch-host.ts';
+import type { Wringer } from './types.ts';
+export interface SupervisorOptions {
+    readonly wringer: Wringer;
+    readonly launchHost: LaunchHost;
+    readonly state: StatePort;
+    readonly runID: string;
+    readonly target: string;
+    readonly readyTimeoutMs: number;
+    readonly stopWaitMs: number;
+    readonly now: () => Date;
+    readonly reportError: (message: string) => void;
+    readonly signal?: AbortSignal | undefined;
+}
+export declare function runSupervisor(options: SupervisorOptions): Promise<void>;

package/dist/settle-dispatch-answer.d.ts

@@ -0,0 +1,9 @@
+import type { EnvelopeInput } from './build-envelope.ts';
+import type { Envelope } from './envelope.ts';
+import type { ExitCode } from './error-codes.ts';
+import type { WringerError } from './wringer-error.ts';
+export interface DispatchAnswer {
+    readonly envelope: Envelope;
+    readonly exitCode: ExitCode;
+}
+export declare function settleDispatchAnswer(input: EnvelopeInput, logFailure: WringerError | null): DispatchAnswer;

package/dist/settle-envelope.d.ts

@@ -0,0 +1,16 @@
+import type { EnvelopeInput } from './build-envelope.ts';
+import type { CappedData } from './cap-data.ts';
+import type { Evidence } from './envelope.ts';
+import type { EnvelopePayload } from './pick-envelope-payload.ts';
+export interface EnvelopeFacts {
+    readonly command: string;
+    readonly target: string | null;
+    readonly instance: string | null;
+    readonly feature: string | null;
+    readonly sha: string | null;
+    readonly durationMs: number;
+    readonly driveEvidence: readonly Evidence[];
+    readonly payload: EnvelopePayload;
+    readonly capped: CappedData;
+}
+export declare function settleEnvelope(facts: EnvelopeFacts): EnvelopeInput;

package/dist/ssh.d.ts

@@ -0,0 +1,12 @@
+import type { Host } from './host.ts';
+export interface PrefixLayer {
+    readonly argv: readonly string[];
+    readonly shell: boolean;
+}
+export interface SSHOptions {
+    readonly destination: string;
+    readonly readOnlyUser?: string;
+    readonly prefix?: readonly PrefixLayer[];
+    readonly binary?: string;
+}
+export declare function ssh(options: SSHOptions): Host;

package/dist/start-launch.d.ts

@@ -0,0 +1,20 @@
+import type { LaunchHost } from './read-launch-host.ts';
+import type { Endpoints } from './run-events.ts';
+import type { LaunchPlan } from './types.ts';
+export interface LaunchRequest {
+    readonly host: LaunchHost;
+    readonly plan: LaunchPlan;
+    readonly logPath: string;
+    readonly readyTimeoutMs: number;
+    readonly signal: AbortSignal;
+    readonly onCrash: (reason: string) => void;
+    readonly onStopFailed: (reason: string) => void;
+    readonly stopGraceMs: number;
+}
+export interface Launch {
+    readonly endpoints: Endpoints;
+    readonly stop: () => Promise<void>;
+}
+export declare const appStopGraceMs = 5000;
+export declare function startLaunch(request: LaunchRequest): Promise<Launch>;
+export declare const appStopLimitMs: number;

package/dist/start-services.d.ts

@@ -0,0 +1,16 @@
+import type { Endpoints } from './run-events.ts';
+import type { RunHandle, ServiceInstance, TargetDefinition, Wringer } from './types.ts';
+export interface ServicesRequest {
+    readonly wringer: Wringer;
+    readonly targetName: string;
+    readonly target: TargetDefinition;
+    readonly endpoints: Endpoints;
+    readonly run: RunHandle;
+    readonly hint: string;
+    readonly signal: AbortSignal;
+    readonly commandSignal: AbortSignal;
+    readonly startupCommandSignal: AbortSignal;
+    readonly started: Map<string, ServiceInstance>;
+    readonly onReady: (key: string) => Promise<void>;
+}
+export declare function startServices(request: ServicesRequest): Promise<void>;

package/dist/supervisor-machine.d.ts

@@ -0,0 +1,78 @@
+import type { WringerError } from './wringer-error.ts';
+export interface ShutDownPlan {
+    readonly crashReason: string | null;
+    readonly gaveUpOnStartup: boolean;
+}
+interface SupervisorMachineInput {
+    readonly stopWaitMs: number;
+    readonly startUp: () => Promise<void>;
+    readonly abortStartup: () => void;
+    readonly shutDown: (plan: ShutDownPlan) => Promise<WringerError | null>;
+    readonly cleanUpLate: () => Promise<void>;
+}
+interface SupervisorContext extends SupervisorMachineInput {
+    readonly crashReason: string | null;
+    readonly gaveUpOnStartup: boolean;
+    readonly startupSettled: boolean;
+    readonly failure: WringerError | null;
+}
+type SupervisorEvent = {
+    readonly type: 'stop';
+    readonly reason: string | null;
+} | {
+    readonly type: 'startup.done';
+} | {
+    readonly type: 'startup.failed';
+    readonly reason: string;
+};
+interface RunInput<Input, Output> {
+    readonly run: (input: Input) => Promise<Output>;
+    readonly input: Input;
+}
+export declare const supervisorMachine: import("xstate").StateMachine<SupervisorContext, SupervisorEvent, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<null, RunInput<null, void>, import("xstate").EventObject> | import("xstate").PromiseActorLogic<WringerError | null, RunInput<ShutDownPlan, WringerError | null>, import("xstate").EventObject>> | undefined;
+}, {
+    src: "cleanUpLate";
+    logic: import("xstate").PromiseActorLogic<null, RunInput<null, void>, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "shutDown";
+    logic: import("xstate").PromiseActorLogic<WringerError | null, RunInput<ShutDownPlan, WringerError | null>, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "startUp";
+    logic: import("xstate").PromiseActorLogic<null, RunInput<null, void>, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "abortStartup";
+    params: unknown;
+} | {
+    type: "giveUpOnStartup";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "keepStartupFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "keepStopReason";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "settleStartup";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "gaveUpOnStartup";
+    params: unknown;
+} | {
+    type: "startupSettled";
+    params: unknown;
+}, "stopWait", "cleaningUpLate" | "closed" | "ended" | "running" | "shuttingDown" | "starting" | "waitingForStartup", string, SupervisorMachineInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    states: {
+        readonly starting: {};
+        readonly running: {};
+        readonly waitingForStartup: {};
+        readonly shuttingDown: {};
+        readonly closed: {};
+        readonly cleaningUpLate: {};
+        readonly ended: {};
+    };
+}, import("xstate").MetaObject>;
+export {};

package/dist/supervisor-protocol.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const supervisorRequestSchema: z.ZodObject<{
+    service: z.ZodString;
+    method: z.ZodString;
+    args: z.ZodUnknown;
+    deadlineAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SupervisorRequest = z.infer<typeof supervisorRequestSchema>;
+export declare const supervisorResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            "check-failed": "check-failed";
+            "doctor-required": "doctor-required";
+            environment: "environment";
+            internal: "internal";
+            "not-running": "not-running";
+            "read-only": "read-only";
+            "target-not-allowed": "target-not-allowed";
+            timeout: "timeout";
+            usage: "usage";
+        }>;
+        message: z.ZodString;
+        hint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "ok">;
+export type SupervisorResponse = z.infer<typeof supervisorResponseSchema>;
+export declare const supervisorServiceName = "supervisor";
+export declare const supervisorCommandName = "__wringer-supervisor";
+export declare const supervisorArgsSchema: z.ZodPipe<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTransform<{
+    runID: string;
+    target: string;
+    root: string;
+}, [string, string, string]>>;
+export interface SupervisorArgvInput {
+    readonly runID: string;
+    readonly target: string;
+    readonly root: string;
+}
+export declare function buildSupervisorArgv(args: SupervisorArgvInput): readonly string[];

package/dist/to-wringer-error.d.ts

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