@sapiom/harness 0.0.0 → 0.1.1

package/dist/core/macros.js

@@ -0,0 +1,59 @@
+export const DEFAULT_MACROS = [
+    {
+        id: "run_local",
+        label: "Run local",
+        icon: "Play",
+        requiresWorkflow: true,
+        action: {
+            kind: "inject",
+            submit: true,
+            text: "cd {{workflow.path}} && sapiom agents run --target local",
+        },
+    },
+    {
+        id: "deploy",
+        label: "Deploy",
+        icon: "Cloud",
+        requiresWorkflow: true,
+        action: {
+            kind: "inject",
+            submit: true,
+            text: "cd {{workflow.path}} && sapiom agents deploy",
+        },
+    },
+    {
+        id: "prod_run",
+        label: "Prod run",
+        icon: "Zap",
+        requiresWorkflow: true,
+        action: {
+            kind: "inject",
+            submit: true,
+            text: "cd {{workflow.path}} && sapiom agents run --target prod",
+        },
+    },
+    {
+        id: "open_prod",
+        label: "Open prod",
+        icon: "ExternalLink",
+        requiresWorkflow: true,
+        action: {
+            kind: "open-url",
+            url: "https://app.sapiom.ai/workflows/{{workflow.definitionId}}",
+        },
+    },
+    {
+        // One-click force refresh of the bound workflow's canvas: re-runs the
+        // deterministic, zero-LLM structure render (core/canvas-render.ts —
+        // instant, cache-invalidated) AND re-spawns the bounded AI enrichment
+        // task (core/canvas-enrich.ts, a headless background run that returns
+        // validated JSON annotations, never HTML) — all server-side, without
+        // touching the session's pty. A cheap no-op when the session is unbound.
+        id: "visualize",
+        label: "Visualize",
+        icon: "Sparkles",
+        requiresWorkflow: false,
+        action: { kind: "render-canvas" },
+    },
+];
+//# sourceMappingURL=macros.js.map

package/dist/core/macros.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"macros.js","sourceRoot":"","sources":["../../src/core/macros.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,MAAM;QACZ,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,0DAA0D;SACjE;KACF;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,8CAA8C;SACrD;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,KAAK;QACX,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,yDAAyD;SAChE;KACF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,cAAc;QACpB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,2DAA2D;SACjE;KACF;IACD;QACE,sEAAsE;QACtE,oEAAoE;QACpE,sEAAsE;QACtE,sEAAsE;QACtE,qEAAqE;QACrE,yEAAyE;QACzE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,UAAU;QAChB,gBAAgB,EAAE,KAAK;QACvB,MAAM,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE;KAClC;CACF,CAAC"}

package/dist/core/path-safety.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The absolute path of `name` as a direct child of `root`, or null when
+ * `name` is anything other than one plain path segment — separators, ".",
+ * "..", absolute paths, or anything else that could resolve outside `root`.
+ * (Extracted from the generated-dir retention policy, which relies on it to
+ * refuse deleting anything but a direct child of its own root.)
+ */
+export declare function childPath(root: string, name: string): string | null;
+/**
+ * Resolves `candidate` (relative to `root`, or absolute) and confirms the
+ * result stays within `root`. Returns the resolved absolute path, or null if
+ * it escapes — whether via a `..` climb, an absolute path, or a different
+ * drive. `root` itself counts as inside.
+ *
+ * Containment is decided with `path.relative`: the relative path from the
+ * resolved root to the resolved candidate begins with `..` (or is itself
+ * absolute) exactly when the candidate lies outside the root — the standard,
+ * analyzer-recognized shape for a path-traversal barrier.
+ */
+export declare function resolveWithinRoot(root: string, candidate: string): string | null;
+/**
+ * True when `p` contains an upward-traversal (`..`) path segment. Segment
+ * aware: a name that merely *contains* ".." (e.g. "a..b") is not a match.
+ *
+ * Use as a defense-in-depth assertion on an already-resolved absolute path
+ * for endpoints that legitimately accept an arbitrary absolute path (a
+ * filesystem browser, an explicit "connect this directory") and so have no
+ * single root to confine to. A fully resolved path never retains a `..`
+ * segment, so this rejects nothing legitimate — it makes the "normalization
+ * left no traversal behind" guarantee explicit and local to the sink.
+ */
+export declare function hasTraversalSegment(p: string): boolean;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/core/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../src/core/path-safety.ts"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/core/path-safety.js

@@ -0,0 +1,63 @@
+/**
+ * Shared filesystem path-safety guards.
+ *
+ * The harness runs on the user's own machine on the user's own inputs
+ * (workflow directories, a session cwd, a canvas sub-path), so the threat
+ * here isn't a remote attacker crossing a privilege boundary — it's ordinary
+ * footguns: a `..` segment, an absolute path where a relative one was meant,
+ * or a symlink that quietly resolves a user-derived value outside the
+ * directory a feature intended to confine it to. Each helper turns "a path
+ * that might escape" into "a path proven to stay put, or null", so callers
+ * reject rather than silently reach outside — and each guard is written in a
+ * form static analysis recognizes as neutralizing path-traversal taint.
+ */
+import * as path from "node:path";
+/**
+ * The absolute path of `name` as a direct child of `root`, or null when
+ * `name` is anything other than one plain path segment — separators, ".",
+ * "..", absolute paths, or anything else that could resolve outside `root`.
+ * (Extracted from the generated-dir retention policy, which relies on it to
+ * refuse deleting anything but a direct child of its own root.)
+ */
+export function childPath(root, name) {
+    if (!name || name === "." || name === "..")
+        return null;
+    const resolved = path.resolve(root, name);
+    if (path.dirname(resolved) !== root || path.basename(resolved) !== name)
+        return null;
+    return resolved;
+}
+/**
+ * Resolves `candidate` (relative to `root`, or absolute) and confirms the
+ * result stays within `root`. Returns the resolved absolute path, or null if
+ * it escapes — whether via a `..` climb, an absolute path, or a different
+ * drive. `root` itself counts as inside.
+ *
+ * Containment is decided with `path.relative`: the relative path from the
+ * resolved root to the resolved candidate begins with `..` (or is itself
+ * absolute) exactly when the candidate lies outside the root — the standard,
+ * analyzer-recognized shape for a path-traversal barrier.
+ */
+export function resolveWithinRoot(root, candidate) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, candidate);
+    const relative = path.relative(resolvedRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        return null;
+    return resolved;
+}
+/**
+ * True when `p` contains an upward-traversal (`..`) path segment. Segment
+ * aware: a name that merely *contains* ".." (e.g. "a..b") is not a match.
+ *
+ * Use as a defense-in-depth assertion on an already-resolved absolute path
+ * for endpoints that legitimately accept an arbitrary absolute path (a
+ * filesystem browser, an explicit "connect this directory") and so have no
+ * single root to confine to. A fully resolved path never retains a `..`
+ * segment, so this rejects nothing legitimate — it makes the "normalization
+ * left no traversal behind" guarantee explicit and local to the sink.
+ */
+export function hasTraversalSegment(p) {
+    return /(?:^|[/\\])\.\.(?:[/\\]|$)/.test(p);
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/core/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.js","sourceRoot":"","sources":["../../src/core/path-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,SAAiB;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACvD,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAS;IAC3C,OAAO,4BAA4B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/core/paths.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Small path helper shared across the harness's core modules (session
+ * manager, adapters, analytics store): the contract (`src/shared/types.ts`)
+ * expresses well-known paths with a leading `~`.
+ */
+/** Expand a leading `~` (home directory) in a path, then resolve to absolute. */
+export declare function expandHome(path: string): string;
+/** Absolute locations of every piece of persistent harness state, all rooted
+ *  under one directory. See resolveStatePaths(). */
+export interface HarnessStatePaths {
+    root: string;
+    machineId: string;
+    sessions: string;
+    workflows: string;
+    events: string;
+    settings: string;
+    generated: string;
+    sampleProject: string;
+}
+/**
+ * Resolves the full set of persistent-state locations under a single root.
+ * Defaults to the real HARNESS_HOME (`~/.sapiom/harness`) — the CLI's
+ * behavior is unchanged — while tests and scripted checks pass a scratch
+ * directory so a server boot can never touch the developer's real state.
+ */
+export declare function resolveStatePaths(stateRoot?: string): HarnessStatePaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;oDACoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAYvE"}

package/dist/core/paths.js

@@ -0,0 +1,43 @@
+/**
+ * Small path helper shared across the harness's core modules (session
+ * manager, adapters, analytics store): the contract (`src/shared/types.ts`)
+ * expresses well-known paths with a leading `~`.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { HARNESS_HOME, HARNESS_PATHS } from "../shared/types.js";
+/** Expand a leading `~` (home directory) in a path, then resolve to absolute. */
+export function expandHome(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return resolve(homedir(), path.slice(2));
+    return resolve(path);
+}
+/** The path of `entry` relative to HARNESS_HOME — HARNESS_PATHS expresses
+ *  every well-known file as `${HARNESS_HOME}/<name>`, and deriving the name
+ *  here (instead of repeating it) keeps HARNESS_PATHS the single source of
+ *  truth for what the files are called. */
+function relativeToHome(entry) {
+    return entry.slice(HARNESS_HOME.length + 1);
+}
+/**
+ * Resolves the full set of persistent-state locations under a single root.
+ * Defaults to the real HARNESS_HOME (`~/.sapiom/harness`) — the CLI's
+ * behavior is unchanged — while tests and scripted checks pass a scratch
+ * directory so a server boot can never touch the developer's real state.
+ */
+export function resolveStatePaths(stateRoot) {
+    const root = expandHome(stateRoot ?? HARNESS_HOME);
+    return {
+        root,
+        machineId: join(root, relativeToHome(HARNESS_PATHS.machineId)),
+        sessions: join(root, relativeToHome(HARNESS_PATHS.sessions)),
+        workflows: join(root, relativeToHome(HARNESS_PATHS.workflows)),
+        events: join(root, relativeToHome(HARNESS_PATHS.events)),
+        settings: join(root, relativeToHome(HARNESS_PATHS.settings)),
+        generated: join(root, relativeToHome(HARNESS_PATHS.generated)),
+        sampleProject: join(root, relativeToHome(HARNESS_PATHS.sampleProject)),
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjE,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAeD;;;2CAG2C;AAC3C,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAkB;IAClD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC;IACnD,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5D,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACxD,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5D,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/core/port-detector.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Dev-server port detection (workstream W5's backend slice).
+ *
+ * The Preview pane's "Preview :PORT" chip (CanvasPane.tsx) lights up from a
+ * `port.detected` bus message. This is the detector behind that signal: feed
+ * it raw text — pty output chunks as they arrive, or a `tool.call` event's
+ * command/output — per session, and it calls `onPort` once per distinct
+ * (session, port) `localhost:<port>` reference it finds. The integrator
+ * wires `feed()` to both the pty output stream and the analytics ingest
+ * pipeline, and broadcasts `{type: "port.detected", harnessSessionId, port,
+ * url}` on /ws/events from `onPort`.
+ */
+export interface PortDetectorDeps {
+    onPort(harnessSessionId: string, port: number, url: string): void;
+    /** Ports considered the harness's own infrastructure — a match against one
+     *  of these is silently dropped (not even recorded as "seen") rather than
+     *  broadcast as a discovery. Known ports at construction time; more can be
+     *  added later via `addExcludedPort` (e.g. an ephemeral `port: 0` only
+     *  resolves to its real bound port after the server starts listening,
+     *  which happens after this detector is already constructed). */
+    excludedPorts?: Iterable<number>;
+}
+/**
+ * Extracts the port a URL string actually resolves to, including the
+ * protocol's implicit default when none is written out explicitly (`new
+ * URL(...).port` is `""` in that case, not the real port) — used to exclude
+ * the analytics collector's own port from detection.
+ */
+export declare function portFromUrl(rawUrl: string): number | null;
+/**
+ * Stateful, streaming-safe: a match that touches the very end of the
+ * buffered text is held back rather than finalized, in case more digits are
+ * still arriving in the next chunk (so this is safe to feed byte-for-byte
+ * pty output, not just complete lines). Call `flush()` after feeding a
+ * discrete, already-complete string (e.g. one tool.call event's output) —
+ * see its doc comment for why that's necessary. Dedupes per (session, port)
+ * so a port that keeps appearing in output only ever fires `onPort` once —
+ * permanently for the session's lifetime (not a TTL): `reset()` is what
+ * clears it, on session exit, so a reused session id starts clean.
+ */
+export declare class PortDetector {
+    private readonly deps;
+    private readonly buffers;
+    private readonly seenPorts;
+    private readonly excludedPorts;
+    constructor(deps: PortDetectorDeps);
+    /** Exclude a port discovered after construction — e.g. the harness's own
+     *  actual bound port, which is only known once the HTTP server resolves
+     *  its `listen()` call (relevant for an ephemeral `port: 0`). */
+    addExcludedPort(port: number): void;
+    feed(chunk: string, harnessSessionId: string): void;
+    private tryEmit;
+    /**
+     * Finalizes whatever's currently held back for a session, immediately.
+     * `feed()` deliberately withholds a match touching the end of the buffered
+     * text in case more digits are still arriving — correct for a live pty
+     * byte stream, but wrong for a single discrete, complete string (e.g. one
+     * `tool.call` event's already-finished output) where no "next chunk" is
+     * ever coming: without this, a port at the very end of that string (a
+     * common shape — "...started server on http://localhost:5544") would be
+     * held pending forever and `onPort` would never fire. Call this right
+     * after `feed()` whenever the fed text is known to be complete.
+     */
+    flush(harnessSessionId: string): void;
+    /** Drops buffered/dedupe state for a session — call on session exit/kill so
+     *  a reused session id (e.g. a fresh session in the same slot) starts clean. */
+    reset(harnessSessionId: string): void;
+}
+//# sourceMappingURL=port-detector.d.ts.map

package/dist/core/port-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-detector.d.ts","sourceRoot":"","sources":["../../src/core/port-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE;;;;;qEAKiE;IACjE,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQzD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAc;gBAEf,IAAI,EAAE,gBAAgB;IAInD;;qEAEiE;IACjE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAInC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAqBnD,OAAO,CAAC,OAAO;IAiBf;;;;;;;;;;OAUG;IACH,KAAK,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAYrC;oFACgF;IAChF,KAAK,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;CAItC"}

package/dist/core/port-detector.js

@@ -0,0 +1,121 @@
+/**
+ * Dev-server port detection (workstream W5's backend slice).
+ *
+ * The Preview pane's "Preview :PORT" chip (CanvasPane.tsx) lights up from a
+ * `port.detected` bus message. This is the detector behind that signal: feed
+ * it raw text — pty output chunks as they arrive, or a `tool.call` event's
+ * command/output — per session, and it calls `onPort` once per distinct
+ * (session, port) `localhost:<port>` reference it finds. The integrator
+ * wires `feed()` to both the pty output stream and the analytics ingest
+ * pipeline, and broadcasts `{type: "port.detected", harnessSessionId, port,
+ * url}` on /ws/events from `onPort`.
+ */
+const PORT_PATTERN_SOURCE = String.raw `(?:https?://)?localhost:(\d{2,5})\b`;
+/** Long enough to hold the literal "localhost:" anchor split across a chunk
+ *  boundary, plus a few digits either side. */
+const TAIL_SAFETY = 24;
+/**
+ * Extracts the port a URL string actually resolves to, including the
+ * protocol's implicit default when none is written out explicitly (`new
+ * URL(...).port` is `""` in that case, not the real port) — used to exclude
+ * the analytics collector's own port from detection.
+ */
+export function portFromUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        if (url.port)
+            return Number(url.port);
+        return url.protocol === "https:" ? 443 : 80;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stateful, streaming-safe: a match that touches the very end of the
+ * buffered text is held back rather than finalized, in case more digits are
+ * still arriving in the next chunk (so this is safe to feed byte-for-byte
+ * pty output, not just complete lines). Call `flush()` after feeding a
+ * discrete, already-complete string (e.g. one tool.call event's output) —
+ * see its doc comment for why that's necessary. Dedupes per (session, port)
+ * so a port that keeps appearing in output only ever fires `onPort` once —
+ * permanently for the session's lifetime (not a TTL): `reset()` is what
+ * clears it, on session exit, so a reused session id starts clean.
+ */
+export class PortDetector {
+    constructor(deps) {
+        this.deps = deps;
+        this.buffers = new Map();
+        this.seenPorts = new Map();
+        this.excludedPorts = new Set(deps.excludedPorts ?? []);
+    }
+    /** Exclude a port discovered after construction — e.g. the harness's own
+     *  actual bound port, which is only known once the HTTP server resolves
+     *  its `listen()` call (relevant for an ephemeral `port: 0`). */
+    addExcludedPort(port) {
+        this.excludedPorts.add(port);
+    }
+    feed(chunk, harnessSessionId) {
+        const combined = (this.buffers.get(harnessSessionId) ?? "") + chunk;
+        const regex = new RegExp(PORT_PATTERN_SOURCE, "g");
+        let match;
+        let pendingFrom = null;
+        while ((match = regex.exec(combined))) {
+            const end = match.index + match[0].length;
+            if (end === combined.length) {
+                // Could still be growing (more digits due next chunk) — hold it back.
+                pendingFrom = match.index;
+                break;
+            }
+            this.tryEmit(harnessSessionId, Number(match[1]));
+        }
+        const retainFrom = pendingFrom ?? Math.max(0, combined.length - TAIL_SAFETY);
+        this.buffers.set(harnessSessionId, combined.slice(retainFrom));
+    }
+    tryEmit(harnessSessionId, port) {
+        if (!Number.isInteger(port) || port <= 0 || port > 65535)
+            return;
+        // Never even recorded as "seen" — an excluded port isn't a real
+        // discovery, so it shouldn't consume per-session dedupe state either.
+        if (this.excludedPorts.has(port))
+            return;
+        let ports = this.seenPorts.get(harnessSessionId);
+        if (!ports) {
+            ports = new Set();
+            this.seenPorts.set(harnessSessionId, ports);
+        }
+        if (ports.has(port))
+            return;
+        ports.add(port);
+        this.deps.onPort(harnessSessionId, port, `http://localhost:${port}`);
+    }
+    /**
+     * Finalizes whatever's currently held back for a session, immediately.
+     * `feed()` deliberately withholds a match touching the end of the buffered
+     * text in case more digits are still arriving — correct for a live pty
+     * byte stream, but wrong for a single discrete, complete string (e.g. one
+     * `tool.call` event's already-finished output) where no "next chunk" is
+     * ever coming: without this, a port at the very end of that string (a
+     * common shape — "...started server on http://localhost:5544") would be
+     * held pending forever and `onPort` would never fire. Call this right
+     * after `feed()` whenever the fed text is known to be complete.
+     */
+    flush(harnessSessionId) {
+        const pending = this.buffers.get(harnessSessionId);
+        if (!pending)
+            return;
+        const regex = new RegExp(PORT_PATTERN_SOURCE, "g");
+        let match;
+        while ((match = regex.exec(pending))) {
+            this.tryEmit(harnessSessionId, Number(match[1]));
+        }
+        this.buffers.delete(harnessSessionId);
+    }
+    /** Drops buffered/dedupe state for a session — call on session exit/kill so
+     *  a reused session id (e.g. a fresh session in the same slot) starts clean. */
+    reset(harnessSessionId) {
+        this.buffers.delete(harnessSessionId);
+        this.seenPorts.delete(harnessSessionId);
+    }
+}
+//# sourceMappingURL=port-detector.js.map

package/dist/core/port-detector.js.map

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