@ishlabs/cli 0.15.0 → 0.17.0

package/dist/lib/study-events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SSE consumer for the backend's per-study event stream.
+ *
+ * Used by `study run --wait` to wake up the poll loop as soon as a tester
+ * status / interaction event arrives, instead of waiting for the next poll
+ * tick. The canonical truth source remains `GET /studies/{id}` — SSE here
+ * only shortens the latency between a backend event and the next status
+ * fetch; the poll fallback still runs on a slow timer in case events are
+ * missed.
+ *
+ * Best-effort:
+ *  - Mints a short-lived stream token (POST /auth/stream-token).
+ *  - Opens `GET /studies/{id}/events?token=…` via `fetch` and streams the
+ *    response body.
+ *  - Returns (silently exits the iterator) on any failure — token mint
+ *    503 (server not configured), endpoint 503 (broker offline on this
+ *    instance), network error, abort. The caller's polling rhythm is the
+ *    safety net; we never raise.
+ *
+ * Stream-token TTL is 1h on the backend. For runs longer than that the
+ * fetch will end (server closes); the caller falls back to pure polling
+ * for the remainder.
+ */
+import { ApiClient, ApiError } from "./api-client.js";
+export interface StudyEvent {
+    type: string;
+    study_id: string;
+    iteration_id?: string | null;
+    tester_id?: string | null;
+    interaction_id?: string | null;
+    frame_id?: string | null;
+    frame_version_id?: string | null;
+    tester_status?: string | null;
+    ts: string;
+    seq: number;
+    payload?: unknown;
+}
+/**
+ * Async generator that yields parsed StudyEvents from the backend SSE
+ * stream. Exits silently (without throwing) on failure or abort — callers
+ * MUST have a polling fallback that drives correctness.
+ */
+export declare function streamStudyEvents(client: ApiClient, studyId: string, signal: AbortSignal): AsyncGenerator<StudyEvent, void, void>;
+/** Type narrower used by callers to skip the synthetic LAG marker. */
+export declare function isLagEvent(event: StudyEvent): boolean;
+export { ApiError };

package/dist/lib/study-events.js

@@ -0,0 +1,126 @@
+/**
+ * SSE consumer for the backend's per-study event stream.
+ *
+ * Used by `study run --wait` to wake up the poll loop as soon as a tester
+ * status / interaction event arrives, instead of waiting for the next poll
+ * tick. The canonical truth source remains `GET /studies/{id}` — SSE here
+ * only shortens the latency between a backend event and the next status
+ * fetch; the poll fallback still runs on a slow timer in case events are
+ * missed.
+ *
+ * Best-effort:
+ *  - Mints a short-lived stream token (POST /auth/stream-token).
+ *  - Opens `GET /studies/{id}/events?token=…` via `fetch` and streams the
+ *    response body.
+ *  - Returns (silently exits the iterator) on any failure — token mint
+ *    503 (server not configured), endpoint 503 (broker offline on this
+ *    instance), network error, abort. The caller's polling rhythm is the
+ *    safety net; we never raise.
+ *
+ * Stream-token TTL is 1h on the backend. For runs longer than that the
+ * fetch will end (server closes); the caller falls back to pure polling
+ * for the remainder.
+ */
+import { ApiError } from "./api-client.js";
+/**
+ * Async generator that yields parsed StudyEvents from the backend SSE
+ * stream. Exits silently (without throwing) on failure or abort — callers
+ * MUST have a polling fallback that drives correctness.
+ */
+export async function* streamStudyEvents(client, studyId, signal) {
+    let token;
+    try {
+        const minted = await client.post("/auth/stream-token", { scope: `study:${studyId}:read` });
+        token = minted.token;
+    }
+    catch (err) {
+        // 503 = server not configured for realtime; anything else = transient.
+        // Either way, fall back silently.
+        void err;
+        return;
+    }
+    const url = `${client.apiBase}/studies/${studyId}/events?token=${encodeURIComponent(token)}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { Accept: "text/event-stream" },
+            signal,
+        });
+    }
+    catch (err) {
+        void err;
+        return;
+    }
+    if (!response.ok || response.body === null) {
+        // 503 = broker not running on this instance; anything else = unexpected.
+        // Caller's polling rhythm handles it.
+        return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            buffer += decoder.decode(value, { stream: true });
+            // SSE framing: events are separated by blank lines. A line beginning
+            // with ":" is a comment (heartbeat) and is ignored.
+            let sep = buffer.indexOf("\n\n");
+            while (sep !== -1) {
+                const block = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                const event = parseEventBlock(block);
+                if (event !== null)
+                    yield event;
+                sep = buffer.indexOf("\n\n");
+            }
+        }
+    }
+    catch (err) {
+        void err;
+        return;
+    }
+    finally {
+        // Best-effort cancel; ignore errors if the connection is already gone.
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+function parseEventBlock(block) {
+    // Skip comment-only blocks (e.g. `: ping - …`).
+    const lines = block.split(/\r?\n/);
+    let data = null;
+    for (const line of lines) {
+        if (line.startsWith(":") || line.length === 0)
+            continue;
+        if (line.startsWith("data:")) {
+            // Per SSE spec the value starts after the optional single space.
+            const value = line.slice(5).replace(/^ /, "");
+            data = data === null ? value : data + "\n" + value;
+        }
+        // We intentionally ignore `event:` and `id:` here — the type and seq
+        // are also present inside the JSON payload, which is the canonical
+        // form. Reading them from the framing too would just be redundant.
+    }
+    if (data === null)
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/** Type narrower used by callers to skip the synthetic LAG marker. */
+export function isLagEvent(event) {
+    return event.type === "stream.lag";
+}
+// Re-export ApiError so callers don't need a separate import path when
+// branching on whether the stream is available.
+export { ApiError };

package/dist/lib/types.d.ts

@@ -82,7 +82,6 @@ export interface Study {
     source_study_id?: string;
     assignments?: Assignment[];
     interview_questions?: InterviewQuestion[];
-    frames?: unknown[];
     iterations?: Iteration[];
     created_at: string;
     updated_at: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
@@ -10,7 +10,10 @@
     "build": "tsc",
     "patch:playwright": "node scripts/patch-playwright-core.mjs",
     "build:binary": "npm run patch:playwright && bun build --compile --external chromium-bidi --external electron src/index.ts --outfile ish",
+    "build:skills-repo": "npm run build && node scripts/generate-skills-repo.mjs",
+    "verify:skills-parity": "npm run build && node scripts/verify-skills-parity.mjs",
     "dev": "tsc --watch",
+    "test": "npm run build && node --test \"tests/*.test.mjs\"",
     "prepublishOnly": "npm run build"
   },
   "engines": {