npm - healix-runner - Versions diffs - 0.0.0-stage → 0.1.0 - Mend

healix-runner 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (47) hide show

package/README.md +38 -2
package/dist/Instance.d.ts +167 -0
package/dist/Instance.js +1 -0
package/dist/PlanRun.d.ts +71 -0
package/dist/PlanRun.js +1 -0
package/dist/WebRunnerServer.d.ts +118 -0
package/dist/WebRunnerServer.js +1 -0
package/dist/agents/AgentChat.d.ts +86 -0
package/dist/agents/AgentChat.js +1 -0
package/dist/agents/catalog.d.ts +29 -0
package/dist/agents/catalog.js +1 -0
package/dist/agents/contextPrompt.d.ts +13 -0
package/dist/agents/contextPrompt.js +1 -0
package/dist/agents/mcpBridge.d.ts +42 -0
package/dist/agents/mcpBridge.js +1 -0
package/dist/analytics.d.ts +161 -0
package/dist/analytics.js +1 -0
package/dist/bin.d.ts +2 -0
package/dist/bin.js +2 -0
package/dist/cli.d.ts +1 -0
package/dist/cli.js +1 -0
package/dist/confProbe.d.ts +4 -0
package/dist/confProbe.js +1 -0
package/dist/confProbeChild.d.ts +13 -0
package/dist/confProbeChild.js +1 -0
package/dist/discovery.d.ts +34 -0
package/dist/discovery.js +1 -0
package/dist/history.d.ts +59 -0
package/dist/history.js +1 -0
package/dist/httpClient.d.ts +18 -0
package/dist/httpClient.js +1 -0
package/dist/index.d.ts +11 -0
package/dist/index.js +1 -0
package/dist/plan.d.ts +65 -0
package/dist/plan.js +1 -0
package/dist/reports.d.ts +40 -0
package/dist/reports.js +1 -0
package/dist/runId.d.ts +1 -0
package/dist/runId.js +1 -0
package/dist/types.d.ts +307 -0
package/dist/types.js +1 -0
package/dist/ui.d.ts +11 -0
package/dist/ui.js +1 -0
package/docs/maintenance-in-the-web-runner.md +653 -0
package/docs/web-runner.md +373 -0
package/package.json +64 -4
package/resources/web-runner.html +4158 -0

package/README.md CHANGED Viewed

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# healix-runner
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **Healix web runner** — run [WebdriverIO](https://webdriver.io) specs in parallel and watch
+every one live in a browser, on top of [`wdio-healix-service`](https://www.npmjs.com/package/wdio-healix-service).
+```bash
+npm i -D healix-runner
+npx healix-runner              # http://127.0.0.1:7171 — or: healix web
+```
+- **Live terminal columns** — one per spec × device: the console, a Test log tree and the
+  screenshots, as the worker produces them. Columns, Grid and Focus layouts; finished runs fold
+  into strips.
+- **Maintenance in the browser** — a session column pauses on a missing locator and offers the
+  terminal's choices and keys (retry, replace, ignore, screenshot, page source, try a line, exit).
+- **AI assistant** — ask **Claude Code** or **GitHub Copilot** (over the Agent Client Protocol)
+  about a column. The agent gets the column's trace and exception and reaches the app through
+  the project's **Healix MCP**; every action that changes something waits for your click.
+  Multi-turn, stoppable, with take-over.
+- **Reports** — the project's Allure results (suite reports, runs in progress, or a folder you
+  open): summary, filters, step timeline with screenshots and playback.
+- **Maintenance and Insights** — failures grouped by cause across runs and devices, locator
+  repairs and their verification, pass rate, flaky tests, time waiting on a person.
+- **Plans** and **History** — stacked executions with their own configs; every batch recorded
+  under `.healix/history` and reviewable later.
+```bash
+npx healix-runner --port 8080 --max 6
+npx healix-runner --host 0.0.0.0              # reachable from other machines — prints a token
+npx healix-runner --plan nightly --once       # CI: run a saved plan, exit with its result
+npx healix-runner --help
+```
+**Agents** are optional. Claude Code needs `npm i -D @agentclientprotocol/claude-agent-acp` and a
+signed-in Claude Code; Copilot needs the Copilot CLI on PATH, signed in. They are offered only
+while the runner is bound to loopback.
+Requires `wdio-healix-service` ≥ 0.49.0 in the project. Full documentation:
+[docs/web-runner.md](docs/web-runner.md).

package/dist/Instance.d.ts ADDED Viewed

@@ -0,0 +1,167 @@
+import type { InstanceStatus, InstanceView, TimelineItem } from './types.js';
+/**
+ * `run`     — CI-identical observation: the spec runs as it would on a build agent and a
+ *             maintenance dialog fails fast. The only mode plans contain.
+ * `session` — the interactive session with the browser in place of the terminal: no menu,
+ *             tests parked for dispatch, locator failures held as pendingMaintenance. A
+ *             green session is authoring progress, never acceptance.
+ */
+export type InstanceMode = 'run' | 'session';
+export interface InstanceOptions {
+    mode?: InstanceMode;
+    /**
+     * Session only: once the suite is loaded, send run-all so the tests run in sequence
+     * without anyone choosing them. A missing locator still pauses for a decision, and a
+     * failing test stops the sequence with the session menu open — the existing run-all rule.
+     */
+    autoRun?: boolean;
+    spec: string;
+    conf: string;
+    projectRoot: string;
+    /** Preferred worker API port. The worker may land elsewhere; we read the truth from the registry. */
+    port: number;
+    /** Extra environment for the child (e.g. a platform/device override). */
+    env?: Record<string, string>;
+    /** Set when this run is one spec of one stage of a plan. */
+    plan?: {
+        runId: string;
+        stageIndex: number;
+        stageName: string;
+    };
+    /** The recorded batch this column belongs to, when history is being written. */
+    batchId?: string | null;
+    /**
+     * Instances sharing a group key are counted against the group's own limit as well as the
+     * server's, which is how a stage says "at most two of my specs at a time".
+     */
+    group?: {
+        key: string;
+        limit: number;
+    };
+    /** Called for every new timeline item, in order. */
+    onItems: (inst: Instance, items: TimelineItem[]) => void;
+    /** Called whenever the header state changes (status, activity, counts …). */
+    onChange: (inst: Instance) => void;
+    /** Registers a screenshot path as servable and returns its URL. */
+    publishArtifact: (absPath: string) => string;
+}
+export declare class Instance {
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly launchRequestId: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * This column's run id (HEALIX_RUN_ID): names its Allure results folder
+     * (`allure-results/run-<id>`) and is recorded in every suite report it produces, which is
+     * how the Reports view finds this column's report. Minted here, unique per column.
+     */
+    readonly runId: string;
+    readonly mode: InstanceMode;
+    readonly autoRun: boolean;
+    /**
+     * Handed to a session's worker through the environment and sent back on every request
+     * the runner forwards for a person. It is what lets the worker tell a human at this
+     * page from an agent; it never reaches the browser.
+     */
+    private readonly humanToken;
+    readonly spec: string;
+    readonly conf: string;
+    readonly plan: InstanceOptions['plan'] | null;
+    readonly group: InstanceOptions['group'] | null;
+    readonly projectRoot: string;
+    readonly startedAt: string;
+    readonly batchId: string | null;
+    /**
+     * Where this column's worker spills its NDJSON console. Every instance is its own
+     * `wdio run`, so every worker calls itself 0-0 and they would all append to the same
+     * file — the id keeps them apart.
+     */
+    readonly consoleLogFile: string;
+    status: InstanceStatus;
+    endedAt: string | null;
+    exitCode: number | null;
+    port: number | null;
+    /** The registry's launchId — the `sessionId` the Healix MCP addresses this worker by. */
+    launchId: string | null;
+    pid: number | null;
+    device: string | null;
+    platform: string | null;
+    suite: string | null;
+    activity: InstanceView['activity'];
+    waitingForHuman: InstanceView['waitingForHuman'];
+    pendingMaintenance: InstanceView['pendingMaintenance'];
+    readonly items: TimelineItem[];
+    readonly raw: string[];
+    private seq;
+    private counts;
+    private child;
+    private stopping;
+    private following;
+    private mirroring;
+    /** Text of lines mirrored from stdout, so the same line arriving on the API stream is dropped once. */
+    private readonly mirrored;
+    private readonly opts;
+    private stdoutRest;
+    private stderrRest;
+    private consoleLogSeen;
+    constructor(opts: InstanceOptions);
+    view(): InstanceView;
+    start(): void;
+    /**
+     * Find this child's worker in the session registry. Matching on our own
+     * launchRequestId — never on port or spec — is what keeps a leftover registry file
+     * from a previous run, or a sibling instance that landed on our preferred port after
+     * an EADDRINUSE bump, from being adopted as ours.
+     */
+    private discover;
+    private follow;
+    /** Fold the worker's /healix/status into the column header. */
+    private applyStatus;
+    /**
+     * Auto-run: wait for the session to have loaded its suite, then ask it to run everything
+     * once. The worker registers before its spec is loaded, so the test list is the signal
+     * that "run all" has something to run. Gives up quietly after a while: the session menu
+     * is still there to start by hand.
+     */
+    private startRunAll;
+    /**
+     * Forward one call to this instance's worker on behalf of the person at the page.
+     * Only a session has a human to speak for, and the caller (WebRunnerServer) has already
+     * checked the route against its allow-list — this method trusts nothing else.
+     */
+    callWorker(method: 'GET' | 'POST', pathAndQuery: string, body?: unknown, timeoutMs?: number): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    private ingestEntries;
+    /** Split a chunk into whole lines; returns the unterminated remainder. */
+    private ingestRaw;
+    /**
+     * Ask the worker to shut down cleanly first — that lets WDIO close the driver session,
+     * flush Allure and run afterHooks. Only a worker that ignores it gets killed.
+     */
+    stop(): Promise<void>;
+    /**
+     * Kill exactly this instance's own subtree. On Windows `/T` walks DOWN from the shell we
+     * spawned (its wdio worker, driver and browser), never up to the runner; on POSIX the
+     * child is its own group leader, so the negative pid reaches the same set.
+     */
+    private kill;
+    private isOver;
+    private finish;
+    private system;
+    /**
+     * A line written into this column by the runner on someone else's behalf — an agent's
+     * tool call through the Healix MCP, say. It is part of the column's record like any other.
+     */
+    annotate(text: string, level?: 'agent' | 'system', event?: Record<string, unknown>): void;
+    /** The column's timeline as it is now (the in-memory window). */
+    timeline(): TimelineItem[];
+    private make;
+    private push;
+    /**
+     * The NDJSON spill this instance wrote, once it exists — the complete, un-rolled
+     * history, which the board links to per column. `view()` is called on every header
+     * change and once a second for the elapsed clocks, so the stat is cached: the file
+     * appears exactly once and never goes away underneath a live run.
+     */
+    consoleLogPath(): string | null;
+}

package/dist/Instance.js ADDED Viewed

@@ -0,0 +1 @@