@playola-radio/slipstream 0.1.0

package/dist/tui.js

@@ -0,0 +1,168 @@
+import { openLogCursor, parseLine } from "./log-reader.js";
+import { onDiskHighWater, sessionLogPath, listSessions, readRuntimeDescriptor } from "./store-reader.js";
+import { renderChange } from "./change-view.js";
+import { diskBlobSource, httpBlobSource } from "./blob-source.js";
+const sanitize = (s) => s.replace(/[\x00-\x1f\x7f-\x9f]/g, '�');
+const oneLine = async (ev) => [renderEvent(ev)];
+function makeRenderer(blob, view) {
+    return async (ev) => {
+        if (ev.type !== 'slipstream.file.changed.v1')
+            return [renderEvent(ev)];
+        return [...await renderChange(ev, blob, view), ''];
+    };
+}
+function snapshotLabel(snap) {
+    if (typeof snap !== 'object' || snap === null)
+        return '-';
+    const s = snap;
+    if (s.kind === 'content' && typeof s.sha256 === 'string')
+        return sanitize(s.sha256.slice(0, 7));
+    if (s.kind === 'absent')
+        return 'absent';
+    if (s.kind === 'unavailable')
+        return `unavailable:${sanitize(String(s.reason))}`;
+    return '-';
+}
+export function renderEvent(ev) {
+    const d = ev.data;
+    const path = typeof d.path === 'string' ? sanitize(d.path) : '-';
+    // Every externally-supplied display string is sanitized: a terminal escape in
+    // the event type or a reason must never reach the terminal.
+    const parts = [ev.seq.toString(), sanitize(ev.type), path];
+    if (ev.type === 'slipstream.file.changed.v1') {
+        parts.push(snapshotLabel(d.after));
+        // Surface the grouping hint the disk/HTTP readers carry in `data`, so a TUI
+        // reader sees which task a change belongs to (parity, not a new view).
+        if (typeof d.task_hint_id === 'string')
+            parts.push(`task/${sanitize(d.task_hint_id)}`);
+    }
+    else if (ev.type === 'slipstream.task.started.v1') {
+        // The declaration boundary: show its task and title in the path slot (a
+        // declaration names no path) so a TUI reader can correlate it with the
+        // `task/<id>` hint stamped on the changes that follow.
+        parts[2] = typeof d.task_id === 'string' ? `task/${sanitize(d.task_id)}` : '-';
+        if (typeof d.title === 'string')
+            parts.push(sanitize(d.title));
+    }
+    else if (ev.type === 'slipstream.capture.gap.v1') {
+        parts.push(`gap:${sanitize(String(d.reason ?? 'unknown'))}`);
+    }
+    return parts.join(' · ');
+}
+export async function replayFromDisk(storeDir, id, out, view) {
+    const render = view ? makeRenderer(diskBlobSource(storeDir), view) : oneLine;
+    const logPath = sessionLogPath(storeDir, id);
+    const H = await onDiskHighWater(logPath);
+    const cursor = await openLogCursor(logPath, 0n);
+    try {
+        for (;;) {
+            const batch = await cursor.readThrough(H);
+            if (!batch.length)
+                return;
+            for (const ev of batch)
+                for (const line of await render(ev))
+                    out(line);
+        }
+    }
+    finally {
+        await cursor.close();
+    }
+}
+/** Extract the SSE `data:` payload from a frame by real line delimiters (never a
+ *  `.`-regex, which would drop a payload containing a literal U+2028/U+2029). */
+export function sseDataLine(frame) {
+    for (const line of frame.split('\n')) {
+        if (line.startsWith('data: '))
+            return line.slice(6);
+    }
+    return undefined;
+}
+export async function runTui(argv, out) {
+    const disk = argv.includes('--disk');
+    const store = argFor(argv, '--store');
+    const session = argFor(argv, '--session');
+    const context = parseContext(argv);
+    if (context === undefined) {
+        out('usage: --context must be a non-negative integer');
+        return;
+    }
+    const view = argv.includes('--changes')
+        ? { context, full: argv.includes('--full') }
+        : undefined;
+    if (!store) {
+        out('usage: slipstream view --store <dir> [--session <id>] [--disk] [--changes] [--context N] [--full]');
+        return;
+    }
+    if (!session) {
+        for (const s of await listSessions(store))
+            out(`${s.id}  durable=${s.durableSeq}${s.removed ? '  (removed)' : ''}`);
+        return;
+    }
+    if (disk) {
+        await replayFromDisk(store, session, out, view);
+        return;
+    }
+    await followHttp(store, session, out, view);
+}
+const DEFAULT_CONTEXT = 3;
+function parseContext(argv) {
+    const i = argv.indexOf('--context');
+    if (i < 0)
+        return DEFAULT_CONTEXT;
+    const raw = argv[i + 1];
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+function argFor(argv, flag) {
+    const i = argv.indexOf(flag);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+async function followHttp(store, session, out, view) {
+    const desc = await readRuntimeDescriptor(store);
+    if (!desc) {
+        out('no usable reader (runtime descriptor missing or invalid); try --disk');
+        return;
+    }
+    const render = view ? makeRenderer(httpBlobSource(desc), view) : oneLine;
+    const url = new URL(`v1/sessions/${session}/events?after=0&follow=true`, desc.url);
+    let res;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 5000);
+    try {
+        res = await fetch(url, {
+            headers: { authorization: `Bearer ${desc.token}` }, redirect: 'error',
+            signal: ac.signal,
+        });
+    }
+    catch {
+        out('reader unavailable (connection failed or stale descriptor); try --disk');
+        return;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok || !res.body) {
+        out(`reader responded ${res.status}`);
+        return;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let acc = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        acc += decoder.decode(value, { stream: true });
+        let i;
+        while ((i = acc.indexOf('\n\n')) >= 0) {
+            const frame = acc.slice(0, i);
+            acc = acc.slice(i + 2);
+            const data = sseDataLine(frame);
+            if (data !== undefined)
+                for (const line of await render(parseLine(data)))
+                    out(line);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@playola-radio/slipstream",
+  "version": "0.1.0",
+  "description": "Live, honest stream of the file changes a coding agent makes in a worktree, so you can review as it works.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/playola-radio/slipstream.git"
+  },
+  "homepage": "https://github.com/playola-radio/slipstream#readme",
+  "bugs": {
+    "url": "https://github.com/playola-radio/slipstream/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "slipstream": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "contracts/interface/v2/schema.json",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md",
+    "README.md",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 'src/**/!(*.os).test.ts'",
+    "test:os": "node --test --test-concurrency=1 'src/**/*.os.test.ts'",
+    "test:tools": "node --test --test-concurrency=1 'tools/**/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "bench": "node src/bench.ts",
+    "slipstream": "node src/cli.ts",
+    "live-feed": "node tools/live-feed/cli.ts",
+    "identity-probe": "node tools/identity-probe/server.ts",
+    "bench:clips": "node src/clip-bench.ts",
+    "bench:fd5": "node tools/fd5-bench.ts",
+    "qa:daemon": "node tools/qa-daemon.ts",
+    "qa:check": "node tools/projection-check.ts acceptance",
+    "check:fold-release": "node tools/projection-check.ts fold-release",
+    "check:package": "node tools/package-check.ts"
+  },
+  "dependencies": {
+    "@parcel/watcher": "^2.5.1",
+    "tree-sitter-wasms": "0.1.13",
+    "web-tree-sitter": "0.25.10"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/schemas/projections/clip.v1.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://slipstream.dev/schemas/projections/clip.v1.json",
+  "title": "clip.v1",
+  "$comment": "A reader-derived public projection over the immutable before/after blobs of a file.changed event. It is NOT a log event and is never appended; it is a pure function of (before bytes, after bytes, projection_version), computed on demand and cached disposably. Spans reference the raw blob bytes by zero-based half-open byte offsets; a null span means NO corresponding span on that side (created/deleted content), never unreadable content. Unreadable/gone content is a non-ready status or a per-side `unavailable` method, each with an explicit reason. `projection_version` names the complete algorithm and is the cache key. Unknown fields permitted for forward compatibility.",
+  "type": "object",
+  "required": [
+    "change_seq",
+    "projection_version",
+    "status",
+    "clips"
+  ],
+  "properties": {
+    "change_seq": {
+      "type": "string",
+      "pattern": "^[1-9][0-9]*$",
+      "$comment": "The `seq` of the file.changed event this projection is derived from. Stamped on the response; never part of the cache key."
+    },
+    "projection_version": {
+      "const": "clip.v1",
+      "$comment": "Names the complete extraction algorithm and is the cache key. A dropped cache recomputes an identical result under the same version."
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "fallback",
+        "skipped",
+        "unavailable"
+      ],
+      "$comment": "`ready` = function-level clips (reserved for a later version). `fallback` = a diffable file rendered as changed byte ranges. `skipped` = no bounded clip could be produced (binary/oversize/no-change/etc.). `unavailable` = a referenced blob's content is gone or was never captured."
+    },
+    "fallback_reason": {
+      "type": "string",
+      "$comment": "Required for every status except `ready`. Explains why the projection is not `ready` (e.g. `function-extraction-unavailable`, `timeout`, `overloaded`, `binary`, `oversize`, a snapshot/blob reason)."
+    },
+    "clips": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/clip"
+      }
+    }
+  },
+  "if": {
+    "properties": {
+      "status": {
+        "const": "ready"
+      }
+    }
+  },
+  "then": {},
+  "else": {
+    "required": [
+      "fallback_reason"
+    ]
+  },
+  "$defs": {
+    "clip": {
+      "type": "object",
+      "required": [
+        "before",
+        "after"
+      ],
+      "properties": {
+        "before": {
+          "$ref": "#/$defs/side"
+        },
+        "after": {
+          "$ref": "#/$defs/side"
+        }
+      }
+    },
+    "side": {
+      "type": "object",
+      "required": [
+        "span",
+        "method"
+      ],
+      "properties": {
+        "span": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/span"
+            }
+          ],
+          "$comment": "null means NO corresponding span on this side (created/deleted content), never unreadable content."
+        },
+        "method": {
+          "enum": [
+            "changed-range",
+            "whole-file",
+            "absent",
+            "unavailable"
+          ],
+          "$comment": "`changed-range` = a real diff hunk. `whole-file` = the side could not be diffed (create/delete/diff-too-large/before-unavailable). `absent` = the path did not exist on this side. `unavailable` = the side's content is gone or was not captured."
+        },
+        "reason": {
+          "type": "string",
+          "$comment": "Present when the method needs one (e.g. `unavailable` carries the blob/snapshot reason)."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "unavailable"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "type": "null"
+              }
+            },
+            "required": [
+              "reason"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "absent"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "type": "null"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "whole-file"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "$ref": "#/$defs/span"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "span": {
+      "type": "object",
+      "required": [
+        "byte_start",
+        "byte_end",
+        "line_start",
+        "line_end",
+        "truncated"
+      ],
+      "properties": {
+        "byte_start": {
+          "type": "integer",
+          "minimum": 0,
+          "$comment": "Zero-based inclusive start byte offset into the raw blob."
+        },
+        "byte_end": {
+          "type": "integer",
+          "minimum": 0,
+          "$comment": "Zero-based exclusive end byte offset; the span is [byte_start, byte_end). Always lands on a UTF-8 boundary."
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1,
+          "$comment": "1-based inclusive first line covered."
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1,
+          "$comment": "1-based inclusive last line covered. Lines split on \\n (0x0a); a preceding \\r stays in the line (CRLF preserved); a trailing newline does not create a phantom last line."
+        },
+        "truncated": {
+          "type": "boolean",
+          "$comment": "True when the per-side line/byte budget clipped this span short of the full changed range."
+        }
+      }
+    }
+  }
+}

package/schemas/projections/clip.v2.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://slipstream.dev/schemas/projections/clip.v2.json",
+  "title": "clip.v2",
+  "$comment": "Reader-derived projection over immutable blobs and a closed language token. No log event, seq or policy_seq is appended. Spans cover raw UTF-8 bytes on whole-line boundaries. Pairing follows LCS diff correspondence, not semantic identity or move detection. Successful results are deterministic for pinned grammar versions; transient timing/availability outcomes are never cached.",
+  "type": "object",
+  "required": [
+    "change_seq",
+    "projection_version",
+    "status",
+    "clips"
+  ],
+  "properties": {
+    "change_seq": {
+      "type": "string",
+      "pattern": "^[1-9][0-9]*$",
+      "$comment": "The `seq` of the file.changed event this projection is derived from. Stamped on the response; never part of the cache key."
+    },
+    "projection_version": {
+      "const": "clip.v2",
+      "$comment": "Names the complete extraction algorithm and is the cache key. A dropped cache recomputes an identical result under the same version."
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "fallback",
+        "skipped",
+        "unavailable"
+      ],
+      "$comment": "ready: every changed segment is function-derived or a corresponding null side; fallback: at least one segment is not reliably enclosed by a function, parsing failed, or a soft timeout retained bounded ranges. Inspect per-side methods/reasons and truncated independently."
+    },
+    "fallback_reason": {
+      "type": "string",
+      "$comment": "Required unless ready: unsupported-language, no-enclosing-function, parse-error-in-enclosing-scope, extraction-budget-exhausted, timeout, and B1 availability/budget reasons. timeout is transient even with fallback clips."
+    },
+    "clips": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/clip"
+      }
+    }
+  },
+  "if": {
+    "properties": {
+      "status": {
+        "const": "ready"
+      }
+    }
+  },
+  "then": {},
+  "else": {
+    "required": [
+      "fallback_reason"
+    ]
+  },
+  "$defs": {
+    "clip": {
+      "type": "object",
+      "required": [
+        "before",
+        "after"
+      ],
+      "properties": {
+        "before": {
+          "$ref": "#/$defs/side"
+        },
+        "after": {
+          "$ref": "#/$defs/side"
+        }
+      }
+    },
+    "side": {
+      "type": "object",
+      "required": [
+        "span",
+        "method"
+      ],
+      "properties": {
+        "span": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/span"
+            }
+          ],
+          "$comment": "null means NO corresponding span on this side (created/deleted content), never unreadable content."
+        },
+        "method": {
+          "enum": [
+            "function",
+            "changed-range",
+            "whole-file",
+            "absent",
+            "unavailable"
+          ],
+          "$comment": "function: enclosing function rounded out to whole lines; changed-range: bounded diff range (null for no corresponding range); whole-file: no bounded diff; absent/unavailable: B1 dispositions."
+        },
+        "reason": {
+          "type": "string",
+          "$comment": "Present when the method needs one (e.g. `unavailable` carries the blob/snapshot reason)."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "unavailable"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "type": "null"
+              }
+            },
+            "required": [
+              "reason"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "absent"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "type": "null"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "whole-file"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "$ref": "#/$defs/span"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "function"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "span": {
+                "$ref": "#/$defs/span"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "span": {
+      "type": "object",
+      "required": [
+        "byte_start",
+        "byte_end",
+        "line_start",
+        "line_end",
+        "truncated"
+      ],
+      "properties": {
+        "byte_start": {
+          "type": "integer",
+          "minimum": 0,
+          "$comment": "Zero-based inclusive start byte offset into the raw blob."
+        },
+        "byte_end": {
+          "type": "integer",
+          "minimum": 0,
+          "$comment": "Zero-based exclusive end byte offset; the span is [byte_start, byte_end). Always lands on a UTF-8 boundary."
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1,
+          "$comment": "1-based inclusive first line covered."
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1,
+          "$comment": "1-based inclusive last line covered. Lines split on \\n (0x0a); a preceding \\r stays in the line (CRLF preserved); a trailing newline does not create a phantom last line."
+        },
+        "truncated": {
+          "type": "boolean",
+          "$comment": "True when the per-side line/byte budget clipped this span short of the full changed range."
+        }
+      }
+    }
+  }
+}