@gravitylabsllc/porthole 0.1.0 → 0.2.0

package/src/args.ts

@@ -0,0 +1,177 @@
+// Copyright 2026 Gravity Labs
+// SPDX-License-Identifier: Apache-2.0
+import { readFile } from "node:fs/promises";
+import { TRACE_VERSION, type Trace } from "./trace.js";
+
+/**
+ * Argument validators shared by cli.ts (`porthole ui`, `porthole capture`)
+ * and capture.ts (`capture`, `report`, `compare`).
+ *
+ * GRA-93 fixed the CLI's silent argument handling but, inside that ticket's
+ * `Owns`, wrote `parsePort` twice — once per file that needed it — rather
+ * than add a third file neither ticket owned. That was the right call for
+ * that ticket alone. It is exactly the shape that produced GRA-87
+ * (`findAdb` existed twice and neither copy read `local.properties`): two
+ * copies agree until the day someone changes one of them, and the
+ * disagreement is silent because each copy has its own tests. This module
+ * is that follow-up — one definition per validator, imported by both
+ * commands, so 0.2.0's new commands reach for the same rules everyone else
+ * did.
+ */
+
+/** A parse failure that names what was wrong, for the caller to print and exit on. */
+export interface ParseError {
+  message: string;
+}
+
+/**
+ * A port a device or a browser can plausibly reach. `--port` used to be
+ * `Number(argv[++i])` with no check at all: a missing value is `NaN`, and a
+ * `NaN` port is not a refusal, it is a listener that never connects to
+ * anything while printing nothing to say why. Below 1024 needs privileges
+ * this process does not have on most platforms; above 65535 does not exist;
+ * a fraction is a typo, not a port.
+ */
+export function parsePort(raw: string | undefined, option: string): number | ParseError {
+  if (raw === undefined || raw === "") {
+    return { message: `${option} needs a port number` };
+  }
+  // A port is a run of decimal digits, nothing else: `Number()` also accepts
+  // " 8677 " (trims whitespace), "1e4" (scientific notation) and "0x2000"
+  // (hex) as finite integers, none of which anyone typed on purpose.
+  if (/^-?\d+$/.test(raw)) {
+    const value = Number(raw);
+    if (value < 1024 || value > 65535) {
+      return { message: `${option} ${raw} is out of range (must be 1024-65535)` };
+    }
+    return value;
+  }
+  if (/^-?\d+\.\d+$/.test(raw)) {
+    return { message: `${option} ${raw} must be a whole number` };
+  }
+  return { message: `${option} ${JSON.stringify(raw)} is not a number` };
+}
+
+/**
+ * A device-uptime millisecond value — `porthole save`'s `--from`/`--to`.
+ * Same shape discipline as `parsePort`: a run of decimal digits only, so
+ * `"1e4"` or `" 100 "` (both finite per `Number()`) are refused rather than
+ * silently accepted. Unlike a port, 0 is a legitimate value (the very start
+ * of the uptime clock) and there is no upper bound — a session can run for
+ * days.
+ */
+export function parseMillis(raw: string | undefined, option: string): number | ParseError {
+  if (raw === undefined || raw === "") {
+    return { message: `${option} needs a millisecond value` };
+  }
+  if (/^\d+$/.test(raw)) return Number(raw);
+  if (/^\d+\.\d+$/.test(raw)) {
+    return { message: `${option} ${raw} must be a whole number` };
+  }
+  return { message: `${option} ${JSON.stringify(raw)} is not a number` };
+}
+
+/**
+ * A relative lookback for `porthole save --since`: `10m`, `90s`, `2h`, or a
+ * bare millisecond count — the ticket's own examples, all a single unit, so
+ * a compound duration like `1h30m` is refused rather than half-parsed.
+ * Returns milliseconds.
+ */
+export function parseDuration(raw: string | undefined, option: string): number | ParseError {
+  if (raw === undefined || raw === "") {
+    return { message: `${option} needs a duration (e.g. 10m, 90s, 2h, or a millisecond count)` };
+  }
+  const MULTIPLIER_MS: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 };
+  const bare = /^\d+$/.test(raw) ? { value: Number(raw), unitMs: 1 } : null;
+  const suffixed = /^(\d+)(ms|s|m|h)$/.exec(raw);
+  const parsed = bare ?? (suffixed ? { value: Number(suffixed[1]), unitMs: MULTIPLIER_MS[suffixed[2]] } : null);
+  if (!parsed) {
+    return {
+      message: `${option} ${JSON.stringify(raw)} is not a duration (use 10m, 90s, 2h, or a millisecond count)`,
+    };
+  }
+  if (parsed.value <= 0) {
+    return { message: `${option} ${raw} must be positive` };
+  }
+  return parsed.value * parsed.unitMs;
+}
+
+const FAIL_ON_VALUES = ["nothing", "error", "regression"] as const;
+
+export type FailOn = (typeof FAIL_ON_VALUES)[number];
+
+/**
+ * `--fail-on` used to be `argv[++i] as CaptureOptions["failOn"]` — a cast, not
+ * a check. A typo like `regresion` compiled, ran, and turned the CI gate off
+ * without saying a word: the worst failure mode here is a green build. This
+ * validates against the real union and names the accepted values so the typo
+ * is caught at the command line instead of at the postmortem.
+ */
+export function parseFailOn(raw: string | undefined): FailOn | ParseError {
+  if (raw !== undefined && (FAIL_ON_VALUES as readonly string[]).includes(raw)) {
+    return raw as FailOn;
+  }
+  return {
+    message: `--fail-on must be one of: ${FAIL_ON_VALUES.join(", ")} (got ${JSON.stringify(raw ?? null)})`,
+  };
+}
+
+/**
+ * A required string option's value must actually be there — and must not be
+ * the next flag left dangling because this one's value was omitted.
+ * `--scenario` at the end of the command line and `--scenario --port 8677`
+ * were both silently accepted before: the first became `undefined` with no
+ * complaint, the second swallowed `--port` as the scenario name and left
+ * `8677` to be rejected later as a nonsense option, blaming the wrong flag.
+ */
+export function requiredValue(raw: string | undefined, option: string): string | ParseError {
+  if (raw === undefined || raw === "--" || raw.startsWith("--")) {
+    return { message: `${option} needs a value` };
+  }
+  return raw;
+}
+
+/** Thrown by readTrace; the message is written straight to stderr, so it earns its keep alone. */
+export class TraceReadError extends Error {}
+
+/**
+ * Reads and validates a trace file, refusing anything that is not one, rather
+ * than letting a missing file, truncated JSON, or a trace from a version this
+ * build does not understand fall through as an unhandled rejection and a raw
+ * stack trace — which is what a CI operator would have gotten instead of the
+ * one sentence they need.
+ */
+export async function readTrace(file: string): Promise<Trace> {
+  let content: string;
+  try {
+    content = await readFile(file, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new TraceReadError(`no such file: ${file}`);
+    throw new TraceReadError(`could not read ${file}: ${(error as Error).message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new TraceReadError(`${file} is not valid JSON`);
+  }
+
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof (parsed as Record<string, unknown>).porthole !== "number"
+  ) {
+    throw new TraceReadError(`${file} is not a porthole trace (missing "porthole" version field)`);
+  }
+
+  const version = (parsed as Trace).porthole;
+  if (version !== TRACE_VERSION) {
+    throw new TraceReadError(
+      `${file} is trace version ${version}, which this build (version ${TRACE_VERSION}) does not understand`,
+    );
+  }
+
+  return parsed as Trace;
+}

package/src/capture.ts

@@ -0,0 +1,292 @@
+// Copyright 2026 Gravity Labs
+// SPDX-License-Identifier: Apache-2.0
+import { spawn } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { DeviceClient, isConnected, type ConnectionState, type DeviceEvent } from "./device.js";
+import { renderComparison, renderReport, shouldColor } from "./report.js";
+import { buildTrace, resolveProfile, type Trace } from "./trace.js";
+import { parseFailOn, parsePort, readTrace, requiredValue, type FailOn } from "./args.js";
+
+/**
+ * Recording a run with nobody watching.
+ *
+ * Wrapping a child process is the shape because it asks nothing of whatever is
+ * driving the app: connectedAndroidTest, Maestro, a shell script and an agentic
+ * driver are all just a command. The process lifetime is the capture window,
+ * which means there is no protocol to version and no way to leave a capture
+ * running.
+ */
+
+export interface CaptureOptions {
+  port: number;
+  serial?: string;
+  scenario: string;
+  out: string;
+  driver?: string;
+  withEvents: boolean;
+  failOn: FailOn;
+  forward: boolean;
+  baseline?: string;
+  command: string[];
+}
+
+export const CAPTURE_USAGE = `
+porthole capture — record a run and write a trace
+
+  porthole capture --scenario <name> [options] -- <command to run>
+
+  --scenario <name>   what this run is, and what a baseline is matched against
+  --out <file>        where to write the trace (default porthole-trace.json)
+  --driver <name>     what drove the app; compare warns when two runs differ
+  --with-events       include the raw event stream. Large.
+  --fail-on <what>    nothing (default), error, or regression
+  --baseline <file>   compare against this trace when done
+  --port <n>          device port (default 8677)
+  --serial <id>       adb device serial
+  --no-forward        skip 'adb forward'; use it if the bridge is already up
+
+  porthole report <trace.json>
+  porthole compare <baseline.json> <trace.json>
+
+The command runs to completion with the porthole recording. Its exit code is
+passed through unless --fail-on fires first.
+`;
+
+/**
+ * Waits for the device to answer, so a capture does not silently record
+ * nothing.
+ *
+ * GRA-157 AC5: this used to resolve the instant the socket connected, before
+ * hello had a chance to land — DeviceClient set state = "connected" on
+ * socket connect and issued the hello request without awaiting it, so a
+ * capture that started recording right here could finish with `hello: null`
+ * for a run it had already reported as connected. That is now structurally
+ * impossible without any change to this function: DeviceClient's "state"
+ * event does not fire "connected" until hello has actually resolved (see
+ * device.ts's setState()/connect()), and this only resolves `true` on that
+ * exact event, so by the time it does, `device.hello` below is guaranteed
+ * non-null. Waiting through the new "handshaking" state in between is free —
+ * this function was never told which non-"connected" states exist, and does
+ * not need to be now either.
+ */
+async function awaitConnection(device: DeviceClient, timeoutMs = 10_000): Promise<boolean> {
+  // GRA-162: routed through isConnected() rather than `=== "connected"` so
+  // that a fifth ConnectionState fails `tsc` here instead of this function
+  // just never resolving true for it.
+  if (isConnected(device.state)) return true;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), timeoutMs);
+    device.on("state", (state: ConnectionState) => {
+      if (isConnected(state)) {
+        clearTimeout(timer);
+        resolve(true);
+      }
+    });
+  });
+}
+
+export async function capture(options: CaptureOptions): Promise<number> {
+  const device = new DeviceClient("127.0.0.1", options.port);
+  const events: DeviceEvent[] = [];
+  device.on("event", (event: DeviceEvent) => events.push(event));
+  device.start();
+
+  const connected = await awaitConnection(device);
+  if (!connected) {
+    device.stop();
+    process.stderr.write(device.notConnectedMessage() + "\n");
+    return 1;
+  }
+  process.stderr.write(`recording "${options.scenario}"\n`);
+
+  const startedAt = Date.now();
+  const exitCode = await run(options.command);
+  const durationMs = Date.now() - startedAt;
+
+  // The last events are still in flight when the child exits.
+  await new Promise((resolve) => setTimeout(resolve, 750));
+  // Non-null here unless the app disconnected again during the run — a real,
+  // separate risk (the process under test crashed or was reinstalled mid-run)
+  // that this ticket does not attempt to paper over. It is no longer possible
+  // for this to be null merely because we asked too early: awaitConnection()
+  // above only returns once DeviceClient has actually set hello (GRA-157).
+  const hello = device.hello as Record<string, unknown> | null;
+  device.stop();
+
+  // GRA-185: `capture` has no window narrower than the whole run, so
+  // `windowTo: Infinity` — a profile emitted anywhere in `events` (in
+  // practice, `DeviceCollector`'s one startup event) counts, exactly as it
+  // always has here.
+  const profile = resolveProfile({ liveEvents: events, windowTo: Number.POSITIVE_INFINITY, sessionProfile: null, hello });
+  const trace = buildTrace({
+    scenario: options.scenario,
+    driver: options.driver,
+    events,
+    hello,
+    durationMs,
+    withEvents: options.withEvents,
+    profile,
+  });
+
+  await writeFile(options.out, JSON.stringify(trace, null, 2));
+  // stderr, not stdout — this is the summary `porthole capture` prints
+  // alongside the child command's own output, so it colours against stderr's
+  // own TTY-ness, which can differ from stdout's (e.g. `capture ... | tee log`).
+  process.stderr.write(`\n${renderReport(trace, { color: shouldColor(process.stderr) })}`);
+  process.stderr.write(`\nwrote ${options.out} (${events.length} events)\n`);
+
+  let regressed = false;
+  if (options.baseline) {
+    try {
+      const before = await readTrace(options.baseline);
+      const comparison = renderComparison(before, trace);
+      process.stderr.write(`\n${comparison.text}`);
+      regressed = comparison.regressed;
+    } catch (error) {
+      // Same hazard as `porthole compare` reading its two files, just reached
+      // from a capture that asked to be checked against a baseline inline. A
+      // baseline we could not read is not evidence either way, so it is
+      // reported and the comparison is skipped rather than crashing the run
+      // that was otherwise recorded successfully.
+      process.stderr.write(`${(error as Error).message}\n`);
+    }
+  }
+
+  const hasError = trace.findings.some((finding) => finding.severity === "error");
+  if (options.failOn === "error" && hasError) return 1;
+  if (options.failOn === "regression" && regressed) return 1;
+  return exitCode;
+}
+
+/** Runs the child with its output passed straight through. */
+function run(command: string[]): Promise<number> {
+  if (command.length === 0) return Promise.resolve(0);
+  return new Promise((resolve) => {
+    // No shell. Passing an argv array through one concatenates it unescaped,
+    // which mangles any argument containing a space and turns the command into
+    // an injection point. A caller who wants a shell asks for one by name:
+    // `-- bash -c "..."`.
+    const child = spawn(command[0], command.slice(1), { stdio: "inherit" });
+    child.on("error", (error) => {
+      process.stderr.write(`could not run ${command[0]}: ${error.message}\n`);
+      resolve(127);
+    });
+    child.on("close", (code) => resolve(code ?? 0));
+  });
+}
+
+export async function report(file: string): Promise<number> {
+  let trace: Trace;
+  try {
+    trace = await readTrace(file);
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n`);
+    return 2;
+  }
+  process.stdout.write(renderReport(trace, { color: shouldColor(process.stdout) }));
+  return 0;
+}
+
+export async function compare(baseline: string, file: string): Promise<number> {
+  let before: Trace;
+  let after: Trace;
+  try {
+    before = await readTrace(baseline);
+    after = await readTrace(file);
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n`);
+    return 2;
+  }
+  const comparison = renderComparison(before, after);
+  process.stdout.write(comparison.text);
+  // A refusal is not a pass. Exiting 0 would turn a gate that compared nothing
+  // into a green build, which is the one outcome worse than a red one.
+  if (comparison.refused) return 2;
+  return comparison.regressed ? 1 : 0;
+}
+
+export function parseCapture(argv: string[]): CaptureOptions {
+  const options: CaptureOptions = {
+    port: 8677,
+    scenario: "capture",
+    out: "porthole-trace.json",
+    withEvents: false,
+    failOn: "nothing",
+    forward: true,
+    command: [],
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      options.command = argv.slice(i + 1);
+      break;
+    } else if (arg === "--scenario") {
+      const value = requiredValue(argv[++i], "--scenario");
+      if (typeof value !== "string") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.scenario = value;
+    } else if (arg === "--out") {
+      // Validated here, before `capture()` is ever called: a bad --out used
+      // to fail only after the recording had already happened, so the run was
+      // lost *and* the operator got a raw stack trace instead of a sentence.
+      const value = requiredValue(argv[++i], "--out");
+      if (typeof value !== "string") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.out = value;
+    } else if (arg === "--driver") {
+      // Previously `argv[++i]` raw: `--driver --serial abc` swallowed
+      // "--serial" as the driver name and left "abc" to be rejected next as
+      // a nonsense option — blaming the wrong token for the actual mistake.
+      const value = requiredValue(argv[++i], "--driver");
+      if (typeof value !== "string") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.driver = value;
+    } else if (arg === "--baseline") {
+      const value = requiredValue(argv[++i], "--baseline");
+      if (typeof value !== "string") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.baseline = value;
+    } else if (arg === "--with-events") options.withEvents = true;
+    else if (arg === "--fail-on") {
+      const value = parseFailOn(argv[++i]);
+      if (typeof value !== "string") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.failOn = value;
+    } else if (arg === "--port") {
+      const value = parsePort(argv[++i], "--port");
+      if (typeof value !== "number") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.port = value;
+    } else if (arg === "--serial") {
+      // Same hazard as --driver above: a raw argv[++i] blames the wrong
+      // token when the value is missing or is actually the next flag.
+      const value = requiredValue(argv[++i], "--serial");
+      if (typeof value !== "string") {
+        process.stderr.write(`${value.message}\n`);
+        process.exit(2);
+      }
+      options.serial = value;
+    } else if (arg === "--no-forward") options.forward = false;
+    else if (arg === "--help" || arg === "-h") {
+      process.stdout.write(CAPTURE_USAGE);
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown option: ${arg}\n${CAPTURE_USAGE}`);
+      process.exit(2);
+    }
+  }
+  return options;
+}