usesteady 0.1.0-alpha.1

package/bin/use-steady.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * usesteady — bin wrapper.
+ *
+ * Imports the compiled CLI entry point from dist/.
+ * No tsx or TypeScript runtime needed — tsc produces plain JS.
+ */
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const entry = resolve(__dirname, "../dist/src/shell/cli/use-steady.js");
+await import(pathToFileURL(entry).href);

package/dist/server-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * PI-4 Iteration 1: Live-run store — file-backed persistence for active WorkflowRuns.
+ *
+ * ── Purpose ────────────────────────────────────────────────────────────────────
+ *
+ *   Replaces the raw in-memory Map in server.ts with a Map that is backed by
+ *   one JSON file per active run in {storeDir}/live-runs/{runId}.json.
+ *
+ *   On server startup, loadLiveRuns() repopulates the in-memory map from disk
+ *   so active runs survive server restart or tsx crash.
+ *
+ * ── File layout ────────────────────────────────────────────────────────────────
+ *
+ *   {storeDir}/
+ *     live-runs/
+ *       {runId}.json    # { run: WorkflowRun, workspaceRoot: string }
+ *     envelopes.log     # existing UCP log — unchanged by this module
+ *     index.json        # existing UCP index — unchanged by this module
+ *
+ * ── Design invariants ──────────────────────────────────────────────────────────
+ *
+ *   1. WorkflowPlugins (adapter class instances) are NOT serialized.
+ *      On restore, plugins are recreated from workspaceRoot using the same
+ *      code path as POST /api/workflow/start.
+ *   2. Writes are atomic: write to {runId}.json.tmp, then rename.
+ *      A crash mid-write leaves at most a stale .tmp file, never a corrupt .json.
+ *   3. A corrupt or missing run file is skipped silently; other runs are unaffected.
+ *   4. deleteLiveRun is called after maybePersistTerminal so the live-run file
+ *      is cleaned up once the terminal run is in the UCP history log.
+ *   5. This module has no authority. It only persists and restores run state.
+ *      It never transitions phases, skips approvals, or affects execution.
+ */
+import type { WorkflowRun, WorkflowPlugins } from "./src/workflow/types.js";
+/**
+ * LiveRunEntry — the shape the server holds in memory for each active run.
+ *
+ * Replaces the server.ts-local RunEntry definition. The only difference
+ * from the old RunEntry is that this type is the canonical definition and
+ * imported by server.ts rather than defined there.
+ */
+export type LiveRunEntry = {
+    run: WorkflowRun;
+    plugins: WorkflowPlugins;
+    workspaceRoot: string;
+};
+/**
+ * Persist an active run to disk (atomic write).
+ *
+ * Called after every store.set in server.ts. Never throws — errors are
+ * logged to stderr and swallowed so persistence failure cannot block a
+ * workflow transition.
+ */
+export declare function saveLiveRun(storeDir: string, runId: string, run: WorkflowRun, workspaceRoot: string): void;
+/**
+ * Remove a run's live-run file after it has been persisted to UCP history.
+ *
+ * Called from maybePersistTerminal in server.ts. Never throws.
+ */
+export declare function deleteLiveRun(storeDir: string, runId: string): void;
+/**
+ * Load all active runs from disk into a Map.
+ *
+ * Called once at server startup to repopulate the in-memory store.
+ * Corrupt or missing files are skipped with a stderr warning.
+ * Returns an empty Map if the live-runs directory does not exist.
+ */
+export declare function loadLiveRuns(storeDir: string): Map<string, LiveRunEntry>;
+//# sourceMappingURL=server-store.d.ts.map

package/dist/server-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-store.d.ts","sourceRoot":"","sources":["../server-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAgBH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI5E;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAY,WAAW,CAAC;IAC3B,OAAO,EAAQ,eAAe,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAoCF;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAO,MAAM,EACrB,KAAK,EAAU,MAAM,EACrB,GAAG,EAAY,WAAW,EAC1B,aAAa,EAAE,MAAM,GACpB,IAAI,CAWN;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOnE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAgCxE"}

package/dist/server-store.js

@@ -0,0 +1,133 @@
+/**
+ * PI-4 Iteration 1: Live-run store — file-backed persistence for active WorkflowRuns.
+ *
+ * ── Purpose ────────────────────────────────────────────────────────────────────
+ *
+ *   Replaces the raw in-memory Map in server.ts with a Map that is backed by
+ *   one JSON file per active run in {storeDir}/live-runs/{runId}.json.
+ *
+ *   On server startup, loadLiveRuns() repopulates the in-memory map from disk
+ *   so active runs survive server restart or tsx crash.
+ *
+ * ── File layout ────────────────────────────────────────────────────────────────
+ *
+ *   {storeDir}/
+ *     live-runs/
+ *       {runId}.json    # { run: WorkflowRun, workspaceRoot: string }
+ *     envelopes.log     # existing UCP log — unchanged by this module
+ *     index.json        # existing UCP index — unchanged by this module
+ *
+ * ── Design invariants ──────────────────────────────────────────────────────────
+ *
+ *   1. WorkflowPlugins (adapter class instances) are NOT serialized.
+ *      On restore, plugins are recreated from workspaceRoot using the same
+ *      code path as POST /api/workflow/start.
+ *   2. Writes are atomic: write to {runId}.json.tmp, then rename.
+ *      A crash mid-write leaves at most a stale .tmp file, never a corrupt .json.
+ *   3. A corrupt or missing run file is skipped silently; other runs are unaffected.
+ *   4. deleteLiveRun is called after maybePersistTerminal so the live-run file
+ *      is cleaned up once the terminal run is in the UCP history log.
+ *   5. This module has no authority. It only persists and restores run state.
+ *      It never transitions phases, skips approvals, or affects execution.
+ */
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, renameSync, } from "node:fs";
+import { join } from "node:path";
+import { CursorInProcessAdapter } from "./src/cursor/adapters/inprocess-adapter.js";
+import { ClaudeStubAdapter } from "./src/claude/adapters/stub-adapter.js";
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+function liveRunDir(storeDir) {
+    return join(storeDir, "live-runs");
+}
+function liveRunPath(storeDir, runId) {
+    return join(liveRunDir(storeDir), `${runId}.json`);
+}
+function ensureLiveRunDir(storeDir) {
+    const dir = liveRunDir(storeDir);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+// ─── Plugin factory (mirrors POST /api/workflow/start) ─────────────────────
+function makePlugins(workspaceRoot) {
+    const adapter = new CursorInProcessAdapter(workspaceRoot);
+    return {
+        cursor: adapter,
+        claude: ClaudeStubAdapter.accepted("web-api-stub"),
+        fs: adapter,
+    };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Persist an active run to disk (atomic write).
+ *
+ * Called after every store.set in server.ts. Never throws — errors are
+ * logged to stderr and swallowed so persistence failure cannot block a
+ * workflow transition.
+ */
+export function saveLiveRun(storeDir, runId, run, workspaceRoot) {
+    try {
+        ensureLiveRunDir(storeDir);
+        const disk = { run, workspaceRoot };
+        const tmpPath = liveRunPath(storeDir, runId) + ".tmp";
+        const finalPath = liveRunPath(storeDir, runId);
+        writeFileSync(tmpPath, JSON.stringify(disk), "utf8");
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        process.stderr.write(`[live-run-store] save failed for ${runId}: ${String(err)}\n`);
+    }
+}
+/**
+ * Remove a run's live-run file after it has been persisted to UCP history.
+ *
+ * Called from maybePersistTerminal in server.ts. Never throws.
+ */
+export function deleteLiveRun(storeDir, runId) {
+    try {
+        const path = liveRunPath(storeDir, runId);
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch (err) {
+        process.stderr.write(`[live-run-store] delete failed for ${runId}: ${String(err)}\n`);
+    }
+}
+/**
+ * Load all active runs from disk into a Map.
+ *
+ * Called once at server startup to repopulate the in-memory store.
+ * Corrupt or missing files are skipped with a stderr warning.
+ * Returns an empty Map if the live-runs directory does not exist.
+ */
+export function loadLiveRuns(storeDir) {
+    const dir = liveRunDir(storeDir);
+    const result = new Map();
+    if (!existsSync(dir))
+        return result;
+    let files;
+    try {
+        files = readdirSync(dir).filter(f => f.endsWith(".json") && !f.endsWith(".tmp.json"));
+    }
+    catch (err) {
+        process.stderr.write(`[live-run-store] readdirSync failed: ${String(err)}\n`);
+        return result;
+    }
+    for (const file of files) {
+        const runId = file.replace(/\.json$/, "");
+        try {
+            const raw = readFileSync(join(dir, file), "utf8");
+            const disk = JSON.parse(raw);
+            const entry = {
+                run: disk.run,
+                plugins: makePlugins(disk.workspaceRoot),
+                workspaceRoot: disk.workspaceRoot,
+            };
+            result.set(runId, entry);
+            process.stdout.write(`[live-run-store] restored ${runId} (${disk.run.phase})\n`);
+        }
+        catch (err) {
+            process.stderr.write(`[live-run-store] skipping corrupt file ${file}: ${String(err)}\n`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=server-store.js.map

package/dist/server-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-store.js","sourceRoot":"","sources":["../server-store.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * UseSteady API Server — Phase 11A-Web
+ *
+ * Thin Express bridge between the frozen core APIs and the React UI.
+ *
+ * ── Architecture rule ────────────────────────────────────────────────────────
+ *
+ *   This file is the only place in the web stack that touches Node.js-specific
+ *   APIs (fs, path) and the frozen coordinator/shell/history modules.
+ *   The React UI calls this server over HTTP; it never imports coordinator logic.
+ *
+ *   Authority model: unchanged. The server only calls functions that already
+ *   exist. It adds no decisions, no interpretations, no re-derivations.
+ *
+ * ── API contract ──────────────────────────────────────────────────────────────
+ *
+ *   POST /api/workflow/start              { spec, workspaceRoot? } → RunResponse
+ *   GET  /api/workflow/:runId            → RunResponse
+ *   GET  /api/workflow/:runId/events     → SSE stream of RunResponse events (PI-4 Iter 3)
+ *   POST /api/workflow/:runId/advance    → RunResponse  (transient "running" only)
+ *   POST /api/workflow/:runId/confirm    { yes: boolean } → RunResponse
+ *   POST /api/workflow/:runId/choose     { idx: number }  → RunResponse
+ *
+ *   GET  /api/history                → WorkflowHistorySummary[]
+ *   GET  /api/history/:runId         → WorkflowAuditRecord | 404
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   npx tsx server.ts
+ *   # or: npm run serve
+ *
+ *   Runs on http://localhost:3001 by default (UI proxies /api/ to it).
+ */
+export declare function startServer(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA2lBH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBjD"}