@wappy_ai/core 0.1.0

package/dist/semver.js

@@ -0,0 +1,34 @@
+/**
+ * Minimal semver-range check: supports "*", exact "x.y.z", "~x.y.z", "^x.y.z".
+ * Core stays dependency-light (zod + nothing else, CLAUDE.md) — swap for the
+ * `semver` package if a plugin ever needs a richer range grammar.
+ */
+function parse(version) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!m)
+        throw new Error(`semver: invalid version "${version}"`);
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+export function satisfiesRange(version, range) {
+    const r = range.trim();
+    if (r === "*" || r === "")
+        return true;
+    const [vMaj, vMin, vPat] = parse(version);
+    if (r.startsWith("^")) {
+        const [rMaj, rMin, rPat] = parse(r.slice(1));
+        if (vMaj !== rMaj)
+            return false;
+        if (rMaj > 0)
+            return vMin > rMin || (vMin === rMin && vPat >= rPat);
+        // 0.x.y: caret only allows patch bumps within the same minor (npm semantics).
+        if (rMin > 0)
+            return vMin === rMin && vPat >= rPat;
+        return vMin === 0 && vPat === rPat;
+    }
+    if (r.startsWith("~")) {
+        const [rMaj, rMin, rPat] = parse(r.slice(1));
+        return vMaj === rMaj && vMin === rMin && vPat >= rPat;
+    }
+    const [rMaj, rMin, rPat] = parse(r);
+    return vMaj === rMaj && vMin === rMin && vPat === rPat;
+}

package/dist/setup-manifest.d.ts

@@ -0,0 +1,20 @@
+/** One idempotent install step contributed by a part (ledger persistence is M2). */
+export interface SetupStep {
+    id: string;
+    description: string;
+    envKeys?: string[];
+}
+/** Declared by each part/plugin; core aggregates these into the state ledger (§5). */
+export interface SetupManifest {
+    part: string;
+    steps: SetupStep[];
+}
+export interface AggregatedStep extends SetupStep {
+    part: string;
+}
+export interface AggregatedSetup {
+    steps: AggregatedStep[];
+    envKeys: string[];
+}
+/** Flattens manifests into one step list (attributed to their part) + the deduped env key set. */
+export declare function aggregateSetupManifests(manifests: SetupManifest[]): AggregatedSetup;

package/dist/setup-manifest.js

@@ -0,0 +1,19 @@
+/** Flattens manifests into one step list (attributed to their part) + the deduped env key set. */
+export function aggregateSetupManifests(manifests) {
+    const steps = [];
+    const envKeys = new Set();
+    const seen = new Set();
+    for (const manifest of manifests) {
+        for (const step of manifest.steps) {
+            const key = `${manifest.part}:${step.id}`;
+            if (seen.has(key)) {
+                throw new Error(`aggregateSetupManifests: duplicate step "${step.id}" in part "${manifest.part}"`);
+            }
+            seen.add(key);
+            steps.push({ ...step, part: manifest.part });
+            for (const envKey of step.envKeys ?? [])
+                envKeys.add(envKey);
+        }
+    }
+    return { steps, envKeys: [...envKeys] };
+}

package/dist/state/drift.d.ts

@@ -0,0 +1,9 @@
+import type { State } from "./schema.js";
+export type DriftStatus = "clean" | "modified" | "missing";
+export interface DriftEntry {
+    path: string;
+    part: string;
+    status: DriftStatus;
+}
+/** Compares each tracked generated file's stored hash against its current content on disk (doctor, SPEC §5). */
+export declare function detectDrift(state: State, projectRoot: string): DriftEntry[];

package/dist/state/drift.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Compares each tracked generated file's stored hash against its current content on disk (doctor, SPEC §5). */
+export function detectDrift(state, projectRoot) {
+    return state.generatedFiles.map((f) => {
+        const abs = join(projectRoot, f.path);
+        if (!existsSync(abs))
+            return { path: f.path, part: f.part, status: "missing" };
+        const actual = createHash("sha256").update(readFileSync(abs)).digest("hex");
+        return { path: f.path, part: f.part, status: actual === f.sha256 ? "clean" : "modified" };
+    });
+}

package/dist/state/errors.d.ts

@@ -0,0 +1,14 @@
+/** The state file exists but can't be trusted (unreadable, malformed JSON, or fails schema after migration). */
+export declare class StateCorruptError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** The state file's schemaVersion is newer than this core build understands. Never silently downgrade. */
+export declare class StateVersionTooNewError extends Error {
+    readonly foundVersion: number;
+    readonly supportedVersion: number;
+    constructor(foundVersion: number, supportedVersion: number);
+}
+export declare class LockTimeoutError extends Error {
+    constructor(message: string);
+}

package/dist/state/errors.js

@@ -0,0 +1,26 @@
+/** The state file exists but can't be trusted (unreadable, malformed JSON, or fails schema after migration). */
+export class StateCorruptError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "StateCorruptError";
+    }
+}
+/** The state file's schemaVersion is newer than this core build understands. Never silently downgrade. */
+export class StateVersionTooNewError extends Error {
+    foundVersion;
+    supportedVersion;
+    constructor(foundVersion, supportedVersion) {
+        super(`state file schemaVersion ${foundVersion} is newer than this @wappy_ai/core build supports (${supportedVersion}); upgrade @wappy_ai/core (and the CLI) before continuing`);
+        this.foundVersion = foundVersion;
+        this.supportedVersion = supportedVersion;
+        this.name = "StateVersionTooNewError";
+    }
+}
+export class LockTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LockTimeoutError";
+    }
+}

package/dist/state/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./errors.js";
+export * from "./schema.js";
+export * from "./io.js";
+export * from "./lock.js";
+export * from "./migrations.js";
+export * from "./load.js";
+export * from "./step-runner.js";
+export * from "./manifest.js";
+export * from "./drift.js";
+export * from "./reset.js";
+export * from "./version-skew.js";

package/dist/state/index.js

@@ -0,0 +1,11 @@
+export * from "./errors.js";
+export * from "./schema.js";
+export * from "./io.js";
+export * from "./lock.js";
+export * from "./migrations.js";
+export * from "./load.js";
+export * from "./step-runner.js";
+export * from "./manifest.js";
+export * from "./drift.js";
+export * from "./reset.js";
+export * from "./version-skew.js";

package/dist/state/io.d.ts

@@ -0,0 +1,11 @@
+import { type State } from "./schema.js";
+/**
+ * Write temp file (same directory, so rename is on one filesystem) + fsync + rename over the
+ * target. rename(2) is atomic: a reader of `path` always sees either the old content or the new
+ * content in full, never a partial write — even if the process dies mid-write, only the orphaned
+ * temp file is affected, not `path`. State is parsed through StateSchema first, so anything not
+ * in the schema (e.g. an accidentally-attached env *value*) is stripped before it ever reaches disk.
+ */
+export declare function writeStateAtomic(path: string, state: State): void;
+/** Raw parsed JSON (any schema version) — null if no state file exists yet. Throws StateCorruptError if unreadable/not-JSON. */
+export declare function readRawState(path: string): unknown;

package/dist/state/io.js

@@ -0,0 +1,54 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+import { StateSchema } from "./schema.js";
+import { StateCorruptError } from "./errors.js";
+/**
+ * Write temp file (same directory, so rename is on one filesystem) + fsync + rename over the
+ * target. rename(2) is atomic: a reader of `path` always sees either the old content or the new
+ * content in full, never a partial write — even if the process dies mid-write, only the orphaned
+ * temp file is affected, not `path`. State is parsed through StateSchema first, so anything not
+ * in the schema (e.g. an accidentally-attached env *value*) is stripped before it ever reaches disk.
+ */
+export function writeStateAtomic(path, state) {
+    const clean = StateSchema.parse(state);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+    const fd = openSync(tmp, "w");
+    try {
+        writeFileSync(fd, JSON.stringify(clean, null, 2));
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw e;
+    }
+}
+/** Raw parsed JSON (any schema version) — null if no state file exists yet. Throws StateCorruptError if unreadable/not-JSON. */
+export function readRawState(path) {
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        throw new StateCorruptError(`cannot read state file at ${path}: ${e.message}`, e);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new StateCorruptError(`state file at ${path} is not valid JSON`, e);
+    }
+}

package/dist/state/load.d.ts

@@ -0,0 +1,23 @@
+import type { State } from "./schema.js";
+/**
+ * No interactive I/O here (MILESTONES.md B: core never prompts) — a not-ok result is the "offer",
+ * for a CLI/caller to present and act on (e.g. call reset()). Anything that goes wrong reading or
+ * migrating the file becomes `corrupt` except a too-new schemaVersion, which gets its own distinct
+ * result (the fix is "upgrade", not "reset").
+ */
+export type LoadResult = {
+    ok: true;
+    state: State | null;
+} | {
+    ok: false;
+    corrupt: true;
+    path: string;
+    reason: string;
+} | {
+    ok: false;
+    tooNew: true;
+    path: string;
+    foundVersion: number;
+    supportedVersion: number;
+};
+export declare function loadState(path: string): LoadResult;

package/dist/state/load.js

@@ -0,0 +1,23 @@
+import { readRawState } from "./io.js";
+import { migrate } from "./migrations.js";
+import { StateVersionTooNewError } from "./errors.js";
+export function loadState(path) {
+    let raw;
+    try {
+        raw = readRawState(path);
+    }
+    catch (e) {
+        return { ok: false, corrupt: true, path, reason: e.message };
+    }
+    if (raw === null)
+        return { ok: true, state: null };
+    try {
+        return { ok: true, state: migrate(raw) };
+    }
+    catch (e) {
+        if (e instanceof StateVersionTooNewError) {
+            return { ok: false, tooNew: true, path, foundVersion: e.foundVersion, supportedVersion: e.supportedVersion };
+        }
+        return { ok: false, corrupt: true, path, reason: e.message };
+    }
+}

package/dist/state/lock.d.ts

@@ -0,0 +1,19 @@
+import { type Clock } from "../clock.js";
+export interface LockOptions {
+    /** A lock older than this whose owning pid is dead is stale and can be taken over. Default 30s. */
+    staleMs?: number;
+    /** How long to wait for a live lock to free up before giving up. Default 5s. */
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/** true = acquired. false = someone else holds it (EEXIST). */
+export declare function tryAcquireLock(path: string, clock?: Pick<Clock, "now">): boolean;
+export declare function releaseLock(path: string): void;
+/**
+ * A lock is stale once it's older than staleMs AND its owning pid is no longer alive. This is
+ * also the crash-recovery path: nothing runs on SIGKILL, so a `finally`/exit-hook can never
+ * release the lock file for us — staleness detection on the NEXT acquire attempt is the only
+ * reliable way a killed holder's lock gets reclaimed.
+ */
+export declare function isLockStale(path: string, staleMs: number, clock?: Pick<Clock, "now">): boolean;
+export declare function withLock<T>(path: string, fn: () => Promise<T> | T, opts?: LockOptions, clock?: Clock): Promise<T>;

package/dist/state/lock.js

@@ -0,0 +1,85 @@
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { systemClock } from "../clock.js";
+import { LockTimeoutError } from "./errors.js";
+/** true = acquired. false = someone else holds it (EEXIST). */
+export function tryAcquireLock(path, clock = systemClock) {
+    try {
+        const fd = openSync(path, "wx");
+        try {
+            writeFileSync(fd, JSON.stringify({ pid: process.pid, acquiredAt: clock.now() }));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            return false;
+        throw e;
+    }
+}
+export function releaseLock(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+}
+function readLockContents(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null; // missing, or corrupt — both treated as stale by the caller
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // ESRCH = no such process (dead). EPERM = exists but owned by someone else (alive).
+        return e.code === "EPERM";
+    }
+}
+/**
+ * A lock is stale once it's older than staleMs AND its owning pid is no longer alive. This is
+ * also the crash-recovery path: nothing runs on SIGKILL, so a `finally`/exit-hook can never
+ * release the lock file for us — staleness detection on the NEXT acquire attempt is the only
+ * reliable way a killed holder's lock gets reclaimed.
+ */
+export function isLockStale(path, staleMs, clock = systemClock) {
+    const contents = readLockContents(path);
+    if (!contents)
+        return true;
+    if (clock.now() - contents.acquiredAt < staleMs)
+        return false;
+    return !isProcessAlive(contents.pid);
+}
+export async function withLock(path, fn, opts = {}, clock = systemClock) {
+    const staleMs = opts.staleMs ?? 30_000;
+    const timeoutMs = opts.timeoutMs ?? 5_000;
+    const pollMs = opts.pollMs ?? 20;
+    const deadline = clock.now() + timeoutMs;
+    for (;;) {
+        if (tryAcquireLock(path, clock))
+            break;
+        if (isLockStale(path, staleMs, clock)) {
+            releaseLock(path);
+            continue;
+        }
+        if (clock.now() >= deadline)
+            throw new LockTimeoutError(`timed out waiting for lock at ${path}`);
+        await clock.sleep(pollMs);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock(path);
+    }
+}

package/dist/state/manifest.d.ts

@@ -0,0 +1,18 @@
+import { type SetupManifest } from "../setup-manifest.js";
+import { type Clock } from "../clock.js";
+import { type State, type StatePart, type StateStep } from "./schema.js";
+export interface AppliedManifests {
+    state: State;
+    /** Steps that were in state but are no longer contributed by any registered part — reported, not silently dropped. */
+    removedSteps: Pick<StateStep, "id" | "part">[];
+}
+/**
+ * Reconciles the ledger against the currently-registered parts' SetupManifests: existing step/env
+ * statuses are preserved, newly-declared ones start `pending`/unfilled, and steps no longer
+ * contributed by anyone are pulled out of the active list (SPEC §5 "unknown/removed steps").
+ *
+ * Step ids are only unique WITHIN a part (aggregateSetupManifests dedupes on `part:id`, so two
+ * different parts may both declare a step called e.g. "creds") — every lookup here is keyed by
+ * the `part:id` pair via stepKey(), never by `id` alone.
+ */
+export declare function applyManifests(state: State, parts: StatePart[], manifests: SetupManifest[], clock?: Pick<Clock, "now">): AppliedManifests;

package/dist/state/manifest.js

@@ -0,0 +1,25 @@
+import { aggregateSetupManifests } from "../setup-manifest.js";
+import { systemClock } from "../clock.js";
+import { stepKey } from "./schema.js";
+/**
+ * Reconciles the ledger against the currently-registered parts' SetupManifests: existing step/env
+ * statuses are preserved, newly-declared ones start `pending`/unfilled, and steps no longer
+ * contributed by anyone are pulled out of the active list (SPEC §5 "unknown/removed steps").
+ *
+ * Step ids are only unique WITHIN a part (aggregateSetupManifests dedupes on `part:id`, so two
+ * different parts may both declare a step called e.g. "creds") — every lookup here is keyed by
+ * the `part:id` pair via stepKey(), never by `id` alone.
+ */
+export function applyManifests(state, parts, manifests, clock = systemClock) {
+    const aggregated = aggregateSetupManifests(manifests);
+    const activeKeys = new Set(aggregated.steps.map((s) => stepKey(s)));
+    const existingStepByKey = new Map(state.steps.map((s) => [stepKey(s), s]));
+    const steps = aggregated.steps.map((s) => existingStepByKey.get(stepKey(s)) ?? { id: s.id, part: s.part, status: "pending" });
+    const removedSteps = state.steps.filter((s) => !activeKeys.has(stepKey(s))).map((s) => ({ id: s.id, part: s.part }));
+    const existingEnvByName = new Map(state.envKeys.map((e) => [e.name, e]));
+    const envKeys = aggregated.envKeys.map((name) => existingEnvByName.get(name) ?? { name, required: true, filled: false });
+    return {
+        state: { ...state, parts: [...parts], steps, envKeys, updatedAt: clock.now() },
+        removedSteps,
+    };
+}

package/dist/state/migrations.d.ts

@@ -0,0 +1,11 @@
+import { type State } from "./schema.js";
+/**
+ * Validates and returns a typed State. Never downgrades: a schemaVersion newer than this build
+ * supports is refused (StateVersionTooNewError), not silently reinterpreted.
+ *
+ * v1 is the only schema version so far, so there is nothing to migrate FROM yet. When v2 lands,
+ * this becomes a chain: walk `raw` through one pure transform per version (1->2, 2->3, ...) up to
+ * STATE_SCHEMA_VERSION before the final StateSchema.safeParse below — add fixtures/state/v2.json
+ * alongside it so migrations.m2.test.ts's fixture loop covers the new step forever.
+ */
+export declare function migrate(raw: unknown): State;

package/dist/state/migrations.js

@@ -0,0 +1,28 @@
+import { STATE_SCHEMA_VERSION, StateSchema } from "./schema.js";
+import { StateCorruptError, StateVersionTooNewError } from "./errors.js";
+/**
+ * Validates and returns a typed State. Never downgrades: a schemaVersion newer than this build
+ * supports is refused (StateVersionTooNewError), not silently reinterpreted.
+ *
+ * v1 is the only schema version so far, so there is nothing to migrate FROM yet. When v2 lands,
+ * this becomes a chain: walk `raw` through one pure transform per version (1->2, 2->3, ...) up to
+ * STATE_SCHEMA_VERSION before the final StateSchema.safeParse below — add fixtures/state/v2.json
+ * alongside it so migrations.m2.test.ts's fixture loop covers the new step forever.
+ */
+export function migrate(raw) {
+    if (typeof raw !== "object" || raw === null || !("schemaVersion" in raw)) {
+        throw new StateCorruptError("state file is missing schemaVersion");
+    }
+    const version = raw.schemaVersion;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        throw new StateCorruptError(`state file has an invalid schemaVersion: ${JSON.stringify(version)}`);
+    }
+    if (version > STATE_SCHEMA_VERSION) {
+        throw new StateVersionTooNewError(version, STATE_SCHEMA_VERSION);
+    }
+    const parsed = StateSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new StateCorruptError(`state file failed validation: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return parsed.data;
+}

package/dist/state/reset.d.ts

@@ -0,0 +1,15 @@
+import { type Clock } from "../clock.js";
+import { type State } from "./schema.js";
+export type ResetScope = {
+    kind: "all";
+} | {
+    kind: "plugin";
+    name: string;
+};
+export interface ResetResult {
+    state: State;
+    /** Paths the caller (fs-touching layer, not core) should actually delete. */
+    filesToRemove: string[];
+}
+/** Never touches the filesystem itself — returns the paths to remove and the resulting state; the caller applies both. */
+export declare function reset(state: State, scope: ResetScope, clock?: Pick<Clock, "now">): ResetResult;

package/dist/state/reset.js

@@ -0,0 +1,19 @@
+import { systemClock } from "../clock.js";
+import { createEmptyState } from "./schema.js";
+/** Never touches the filesystem itself — returns the paths to remove and the resulting state; the caller applies both. */
+export function reset(state, scope, clock = systemClock) {
+    if (scope.kind === "all") {
+        return { state: createEmptyState(state.runId, clock), filesToRemove: state.generatedFiles.map((f) => f.path) };
+    }
+    const { name } = scope;
+    return {
+        state: {
+            ...state,
+            parts: state.parts.filter((p) => p.name !== name),
+            steps: state.steps.filter((s) => s.part !== name),
+            generatedFiles: state.generatedFiles.filter((f) => f.part !== name),
+            updatedAt: clock.now(),
+        },
+        filesToRemove: state.generatedFiles.filter((f) => f.part === name).map((f) => f.path),
+    };
+}

package/dist/state/schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { type Clock } from "../clock.js";
+/** .wappy/state.json schema v1 (SPEC §5). Bump this and add a migration (migrations.ts) to change the shape. */
+export declare const STATE_SCHEMA_VERSION = 1;
+export declare const StepStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    pending: "pending";
+    done: "done";
+}>;
+export declare const StateStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    part: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        done: "done";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StateStep = z.infer<typeof StateStepSchema>;
+export declare const StatePartSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strip>;
+export type StatePart = z.infer<typeof StatePartSchema>;
+/** Names + booleans only — an env key's actual value is never written to state (SPEC §5, §11). */
+export declare const EnvKeyStateSchema: z.ZodObject<{
+    name: z.ZodString;
+    required: z.ZodBoolean;
+    filled: z.ZodBoolean;
+}, z.core.$strip>;
+export type EnvKeyState = z.infer<typeof EnvKeyStateSchema>;
+export declare const GeneratedFileHashSchema: z.ZodObject<{
+    path: z.ZodString;
+    part: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strip>;
+export type GeneratedFileHash = z.infer<typeof GeneratedFileHashSchema>;
+export declare const StateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    parts: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        part: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            done: "done";
+        }>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    envKeys: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        required: z.ZodBoolean;
+        filled: z.ZodBoolean;
+    }, z.core.$strip>>;
+    lastStep: z.ZodNullable<z.ZodString>;
+    generatedFiles: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        part: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strip>>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type State = z.infer<typeof StateSchema>;
+/** Steps are only unique WITHIN a part (aggregateSetupManifests dedupes on `part:id`) — always key lookups by both. */
+export declare function stepKey(step: Pick<StateStep, "part" | "id">): string;
+export declare function createEmptyState(runId: string, clock?: Pick<Clock, "now">): State;

package/dist/state/schema.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { systemClock } from "../clock.js";
+/** .wappy/state.json schema v1 (SPEC §5). Bump this and add a migration (migrations.ts) to change the shape. */
+export const STATE_SCHEMA_VERSION = 1;
+export const StepStatusSchema = z.enum(["pending", "done", "failed"]);
+export const StateStepSchema = z.object({
+    id: z.string().min(1),
+    /** Which part contributed this step (SetupManifest.part) — scopes plugin-only reset. */
+    part: z.string().min(1),
+    status: StepStatusSchema,
+    error: z.string().optional(),
+});
+export const StatePartSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+});
+/** Names + booleans only — an env key's actual value is never written to state (SPEC §5, §11). */
+export const EnvKeyStateSchema = z.object({
+    name: z.string().min(1),
+    required: z.boolean(),
+    filled: z.boolean(),
+});
+export const GeneratedFileHashSchema = z.object({
+    path: z.string().min(1),
+    part: z.string().min(1),
+    sha256: z.string().min(1),
+});
+export const StateSchema = z.object({
+    schemaVersion: z.literal(STATE_SCHEMA_VERSION),
+    runId: z.string().min(1),
+    parts: z.array(StatePartSchema),
+    steps: z.array(StateStepSchema),
+    envKeys: z.array(EnvKeyStateSchema),
+    lastStep: z.string().nullable(),
+    generatedFiles: z.array(GeneratedFileHashSchema),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+});
+/** Steps are only unique WITHIN a part (aggregateSetupManifests dedupes on `part:id`) — always key lookups by both. */
+export function stepKey(step) {
+    return `${step.part}:${step.id}`;
+}
+export function createEmptyState(runId, clock = systemClock) {
+    const now = clock.now();
+    return {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        runId,
+        parts: [],
+        steps: [],
+        envKeys: [],
+        lastStep: null,
+        generatedFiles: [],
+        createdAt: now,
+        updatedAt: now,
+    };
+}