@g9tm/app-pilot 0.0.0-stage → 0.1.0

package/src/har.ts

@@ -0,0 +1,148 @@
+// Recording and replaying the page's responses (plan v2 P1-05, research R3 — Playwright's routeFromHAR, minimal mode):
+// the app's fetch wrapper hands each finished response here while recording; `net.har {save}` gives a HAR 1.2 file to
+// the controller (it keeps it — never the app); `net.har {replay}` makes the wrapper answer from that file instead of the
+// network. Matching is by method + address (the first unused entry, then they cycle): enough to replay a screen; a POST
+// body is not part of the match (the wrapper's shaping hook sees no body).
+//
+//   net.har {record: true}            start (clears what was recorded)        net.har {record: false}   stop
+//   net.har {save: true}              → {har: {log: {version: '1.2', entries}}}
+//   net.har {replay: <har>, notFound: 'fallback' | 'abort'}                   net.har {replay: null}    stop replaying
+import { redactText, redactValue } from './blackbox.ts';
+import { emit } from './events.ts';
+import { PilotError } from './errors.ts';
+import { registerCommand } from './registry.ts';
+
+export interface HarResponse {
+  readonly status: number;
+  readonly mimeType: string;
+  readonly text: string;
+}
+
+interface Entry extends HarResponse {
+  readonly method: string;
+  readonly url: string;
+  readonly at: string;
+}
+
+const MAX_ENTRIES = 300;
+const MAX_TEXT = 256 * 1024;
+
+let recording = false;
+let recorded: Entry[] = [];
+let replay: { entries: Entry[]; used: Set<number>; notFound: 'fallback' | 'abort'; served: number; missed: number } | null = null;
+
+/** Whether the app's fetch wrapper should read and hand over response bodies now. */
+export function harRecording(): boolean {
+  return recording;
+}
+
+/** One finished response while recording: its body is redacted (tokens, secrets) and capped. */
+export function recordHarEntry(entry: { readonly method: string; readonly url: string; readonly status: number; readonly contentType?: string | null; readonly text: string }): void {
+  if (!recording || recorded.length >= MAX_ENTRIES) return;
+  recorded.push({
+    method: entry.method.toUpperCase(),
+    url: redactText(entry.url, 2_000),
+    status: entry.status,
+    mimeType: entry.contentType ?? 'application/json',
+    text: redactBody(entry.text),
+    at: new Date().toISOString(),
+  });
+}
+
+/** A JSON body is redacted by its keys (token, password, …: redactValue); anything else by its text (bearer tokens, JWTs). */
+function redactBody(text: string): string {
+  try {
+    return JSON.stringify(redactValue(JSON.parse(text), 24, MAX_TEXT)).slice(0, MAX_TEXT);
+  } catch {
+    return redactText(text, MAX_TEXT);
+  }
+}
+
+/**
+ * While replaying: the recorded answer for this request, `'abort'` (not in the file and notFound is abort — fail it as
+ * offline), or null (not replaying, or fall back to the network).
+ */
+export function harAnswer(method: string, url: string): HarResponse | 'abort' | null {
+  if (!replay) return null;
+  const m = method.toUpperCase();
+  const matching = replay.entries.map((e, i) => [e, i] as const).filter(([e]) => e.method === m && e.url === url);
+  if (matching.length === 0) {
+    replay.missed++;
+    return replay.notFound === 'abort' ? 'abort' : null;
+  }
+  // The first one not served yet; when all were, they cycle (a screen asked twice gets the same answers again).
+  let pick = matching.find(([, i]) => !replay!.used.has(i));
+  if (!pick) {
+    for (const [, i] of matching) replay.used.delete(i);
+    pick = matching[0]!;
+  }
+  replay.used.add(pick[1]);
+  replay.served++;
+  emit('net.shaped', { method: m, url, mode: 'replay' });
+  return { status: pick[0].status, mimeType: pick[0].mimeType, text: pick[0].text };
+}
+
+function toHar() {
+  return {
+    log: {
+      version: '1.2',
+      creator: { name: 'G9AppPilot', version: '1' },
+      entries: recorded.map((e) => ({
+        startedDateTime: e.at,
+        time: 0,
+        request: { method: e.method, url: e.url, httpVersion: 'HTTP/1.1', headers: [], queryString: [], cookies: [], headersSize: -1, bodySize: -1 },
+        response: { status: e.status, statusText: '', httpVersion: 'HTTP/1.1', headers: [], cookies: [], content: { size: e.text.length, mimeType: e.mimeType, text: e.text }, redirectURL: '', headersSize: -1, bodySize: -1 },
+        cache: {},
+        timings: { send: 0, wait: 0, receive: 0 },
+      })),
+    },
+  };
+}
+
+function fromHar(value: unknown): Entry[] {
+  const entries = (value as { log?: { entries?: unknown } } | null)?.log?.entries;
+  if (!Array.isArray(entries)) throw new PilotError('net.har replay needs a HAR file ({log: {entries: [...]}}) — what net.har {save} gave.', { code: 'BAD_ARGS' });
+  return entries.map((x, i) => {
+    const e = x as { request?: { method?: string; url?: string }; response?: { status?: number; content?: { mimeType?: string; text?: string } } };
+    if (!e.request?.url || !e.request.method || typeof e.response?.status !== 'number') throw new PilotError(`entries[${i}] has no request method/url or response status.`, { code: 'BAD_ARGS' });
+    return { method: e.request.method.toUpperCase(), url: e.request.url, status: e.response.status, mimeType: e.response.content?.mimeType ?? 'application/json', text: e.response.content?.text ?? '', at: '' };
+  });
+}
+
+/** `net.har` (scope stage). Returns the uninstaller. */
+export function installHar(): () => void {
+  return registerCommand(
+    'net.har',
+    (args) => {
+      if (typeof args.record === 'boolean') {
+        recording = args.record;
+        if (recording) recorded = [];
+        return { recording, entries: recorded.length };
+      }
+      if (args.save === true) return { entries: recorded.length, har: toHar() };
+      if ('replay' in args) {
+        if (args.replay === null) {
+          const was = replay;
+          replay = null;
+          return { replaying: false, served: was?.served ?? 0, missed: was?.missed ?? 0 };
+        }
+        const notFound = args.notFound === 'abort' ? 'abort' : 'fallback';
+        replay = { entries: fromHar(args.replay), used: new Set(), notFound, served: 0, missed: 0 };
+        return { replaying: true, entries: replay.entries.length, notFound };
+      }
+      return { recording, entries: recorded.length, replaying: replay !== null, served: replay?.served ?? 0, missed: replay?.missed ?? 0 };
+    },
+    {
+      scope: 'stage',
+      description: 'Records the page’s responses ({record: true|false}), gives them as a HAR 1.2 file ({save: true}), or answers from one ({replay: <har>, notFound: fallback|abort}; {replay: null} stops).',
+      example: { record: true },
+    },
+  );
+}
+
+/** For tests. */
+export function resetHarForTests(): void {
+  recording = false;
+  recorded = [];
+  replay = null;
+}

package/src/idle.ts

@@ -0,0 +1,125 @@
+// The app's busy tracker (`ui.waitIdle`, `app.busy`): every in-flight unit of work registers a reason while it runs —
+// HTTP requests (`http:GET /api/items`), sync phases, sheet / popup / page animations (`ui:sheet:open`), start-up steps,
+// explicit scopes. Idle = no reason for `quietForMs` continuously. Always on and cheap (a Map insert/delete per unit), so
+// the code paths an automation measures are the production ones; only the bridge that reads it is test-build-only.
+// Platform-free: the app feeds it (an HTTP client's `busy` option, a host's sheet/popup motion), the bridge reads it.
+
+interface BusyEntry {
+  readonly reason: string;
+  readonly sinceMs: number;
+}
+
+const active = new Map<number, BusyEntry>();
+let seq = 0;
+let lastChangeMs = Date.now();
+const listeners = new Set<() => void>();
+
+function changed() {
+  lastChangeMs = Date.now();
+  for (const l of Array.from(listeners)) l();
+}
+
+/** Marks `reason` busy until the returned function is called (idempotent). */
+export function beginBusy(reason: string): () => void {
+  const id = ++seq;
+  active.set(id, { reason, sinceMs: Date.now() });
+  changed();
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    active.delete(id);
+    changed();
+  };
+}
+
+/** Busy while the promise is pending. */
+export function trackBusy<T>(reason: string, promise: Promise<T>): Promise<T> {
+  const end = beginBusy(reason);
+  return promise.finally(end);
+}
+
+/** Busy for a fixed time (animations whose end is not observable). */
+export function busyFor(reason: string, ms: number): void {
+  const end = beginBusy(reason);
+  setTimeout(end, ms);
+}
+
+/** The tracker in the shape `createHttpClient({ busy })` expects. */
+export const busyTracker = { begin: beginBusy };
+
+/** A reason open longer than this is shown as a suspected leak — it still counts. */
+export const BUSY_SUSPECT_MS = 3 * 60_000;
+
+export interface BusySnapshot {
+  readonly idle: boolean;
+  /**
+   * `reason (12.3s)` per open reason, oldest first: a name open more than once says how
+   * many times (`×2`), one open past BUSY_SUSPECT_MS ends in ` — suspected leak`. Digits are ASCII whatever the app's
+   * language — a log reader parses them.
+   */
+  readonly reasons: string[];
+  /** How long the oldest open reason has been running (0 when idle): a runner tells a working app from a stuck one. */
+  readonly oldestMs: number;
+  /** ms since the last begin/end. */
+  readonly quietMs: number;
+}
+
+export function busySnapshot(nowMs = Date.now()): BusySnapshot {
+  const byReason = new Map<string, { since: number; count: number }>();
+  for (const e of active.values()) {
+    const g = byReason.get(e.reason);
+    if (g) {
+      g.count++;
+      g.since = Math.min(g.since, e.sinceMs);
+    } else byReason.set(e.reason, { since: e.sinceMs, count: 1 });
+  }
+  const groups = [...byReason.entries()].sort((a, b) => a[1].since - b[1].since);
+  return {
+    idle: groups.length === 0,
+    reasons: groups.map(([reason, g]) => {
+      const ms = nowMs - g.since;
+      return `${reason}${g.count > 1 ? ` ×${g.count}` : ''} (${(ms / 1000).toFixed(1)}s)${ms > BUSY_SUSPECT_MS ? ' — suspected leak' : ''}`;
+    }),
+    oldestMs: groups.length > 0 ? nowMs - (groups[0] as [string, { since: number }])[1].since : 0,
+    quietMs: nowMs - lastChangeMs,
+  };
+}
+
+/**
+ * Resolves when nothing has been busy for `quietForMs` continuously; rejects after `timeoutMs` with
+ * "Wait for idle timed out after 30s. Still busy: …" — the wording runners classify as an automation failure.
+ */
+export function waitIdle(quietForMs: number, timeoutMs: number): Promise<void> {
+  const started = Date.now();
+  return new Promise<void>((resolve, reject) => {
+    const tick = () => {
+      const now = Date.now();
+      const snap = busySnapshot(now);
+      if (snap.idle && snap.quietMs >= quietForMs) {
+        resolve();
+        return;
+      }
+      if (now - started >= timeoutMs) {
+        const secs = Math.round(timeoutMs / 1000);
+        reject(
+          new Error(
+            snap.idle
+              ? `Wait for idle timed out after ${secs}s. The app kept changing state (quiet only ${snap.quietMs} ms).`
+              : `Wait for idle timed out after ${secs}s. Still busy: ${snap.reasons.join(', ')}.`,
+          ),
+        );
+        return;
+      }
+      setTimeout(tick, 40);
+    };
+    tick();
+  });
+}
+
+export function subscribeBusy(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+// @g9tm/app-pilot — the platform-free core of G9AppPilot: the command registry and its manifest, scopes, the dispatch
+// order, actionable errors, the page's event batching, the busy tracker, the lease, the tap recorder, the black box (logs, requests, stores, database, failure traces) and the always-awake oracles. No Lynx, no
+// native code: @g9tm/app-pilot-lynx connects it to a Lynx host. pilot/AiGuides/00 is the map.
+export { optionalBool, optionalInt, optionalString, requireString } from './args.ts';
+export { addGate, dispatch, onAnswer, type PilotAnswer, type PilotAnswerObserver, type PilotGateHook, type PilotRequest } from './dispatch.ts';
+export { failureOf, PilotError, type PilotErrorCategory, type PilotErrorOptions, type PilotFailure } from './errors.ts';
+export { emit, eventChannelOn, eventsConnected, flush, type EventSink, onEmit, type PilotEvent, setEventChannel, setEventChannels, setEventSink } from './events.ts';
+export {
+  type CommandMeta,
+  commandHandler,
+  commandNames,
+  commandScope,
+  manifest,
+  type ManifestEntry,
+  onCommandsChanged,
+  type PilotArgs,
+  type PilotContext,
+  type PilotHandler,
+  registerCommand,
+  resetRegistryForTests,
+} from './registry.ts';
+export { defaultScope, type PilotScope, SCOPES, scopeAllows } from './scopes.ts';
+export {
+  beginBusy,
+  BUSY_SUSPECT_MS,
+  busyFor,
+  type BusySnapshot,
+  busySnapshot,
+  busyTracker,
+  subscribeBusy,
+  trackBusy,
+  waitIdle,
+} from './idle.ts';
+export { installLease, type InstallLeaseOptions, LEASE_RENEW_MS, leaseGate, leaseHolder, resetLeaseForTests } from './lease.ts';
+export {
+  CANDIDATE_GAP_MS,
+  FIELD_TYPES,
+  flowStepOf,
+  MAX_STEPS,
+  PASSIVE_CAPACITY,
+  PilotRecorder,
+  pilotRecorder,
+  type RecordedKind,
+  type RecordedStep,
+  recordCommand,
+  type RecorderPort,
+  recordEvent,
+  registerRecorderCommands,
+  SAME_TAP_MS,
+  SUGGEST_WITHIN_MS,
+  type SuggestedCheck,
+} from './recorder.ts';
+
+export {
+  type BlackboxOptions,
+  captureTrace,
+  installBlackbox,
+  type LogEntry,
+  type LogLevel,
+  type NetEntry,
+  type PilotTrace,
+  onLogRecorded,
+  recordLog,
+  recordNet,
+  redactText,
+  redactValue,
+  registerDbQuery,
+  registerStore,
+  registerTraceSection,
+  resetBlackboxForTests,
+  Ring,
+  type TrailEntry,
+} from './blackbox.ts';
+
+export {
+  BUSY_LEAK_MS,
+  checkScreen,
+  DEFAULT_ORACLE_RULES,
+  installOracles,
+  latinDigitsInPersian,
+  looksLikeKey,
+  offScreenControls,
+  type OracleOptions,
+  type OracleSeverity,
+  type OracleViolation,
+  rawKeysOnScreen,
+  registerScreenCheck,
+  reportViolation,
+  resetOraclesForTests,
+  type ScreenCheck,
+  type ScreenContext,
+  type ScreenFinding,
+  type ScreenNode,
+  unlabeledControls,
+} from './oracles.ts';
+
+export { checkTokenValue, type DesignRegistry, type DesignToken, installDesign } from './design.ts';
+
+export { harRecording, recordHarEntry } from './har.ts';
+export { createVitalsWatch, heartbeatClock, installVitals, type VitalsOptions, type VitalsReading, type VitalsStall } from './vitals.ts';
+export { installStage, onPilotFlag, onSocketDrop, pilotFlag, resetStageForTests, type Shape, type ShapeMode, type ShapeRule, shapeRequest, shapeSocket } from './stage.ts';
+
+export const PILOT_PROTOCOL = 2;
+export const PILOT_VERSION = '0.1.0';
+export { installPilotConfig, type PilotConfig, type PilotConfigStore, pilotConfigOn, pilotConfigValue } from './config.ts';

package/src/lease.ts

@@ -0,0 +1,145 @@
+// The lease: one controller drives the device at a time. `lease.acquire {owner, ttlSeconds}` returns a lease id; while a
+// lease is held, every command must carry it (the request's `leaseId`) or it is refused — never interleaved into somebody
+// else's run. A command with the valid id renews the lease; an unused one expires by itself.
+//
+//   installLease()         registers lease.acquire / release / status and the gate (once; returns the uninstall). The
+//                          gate joins the others in the order it is installed: add an earlier gate first.
+//   leaseGate(cmd, id)     the gate itself, for a host that orders its own gates
+//
+// A PURE READ passes without the lease (plan v2 P2-15): a registered observe command not declared mutating, minus the
+// HEAVY ones that hold the device's threads or change a counter (a screenshot, the screen model, a trace, a raw CDP
+// call). Reading moves nothing in somebody else's run; a watcher (a live view, an agent's perf.vitals) is not
+// refused while a runner holds the device.
+import { addGate } from './dispatch.ts';
+import { PilotError } from './errors.ts';
+import { optionalInt, optionalString } from './args.ts';
+import { isPureRead, registerCommand } from './registry.ts';
+
+interface Lease {
+  readonly leaseId: string;
+  readonly owner: string;
+  expiresAtMs: number;
+  commandsServed: number;
+}
+
+let lease: Lease | null = null;
+
+/** A command with the valid lease id keeps the lease for this long again. */
+export const LEASE_RENEW_MS = 5 * 60 * 1000;
+
+const FREE_COMMANDS: ReadonlySet<string> = new Set(['lease.acquire', 'lease.status']);
+/** Observe commands that still need the lease: they take the device's time or reset what they read. */
+export const LEASED_READS: ReadonlySet<string> = new Set([
+  'ui.screenshot',
+  'screen.capture',
+  'screen.model',
+  'trace.capture',
+  'devtool.cdp',
+  'devtool.probe',
+  'perf.frameStats',
+]);
+const freeWithoutLease = (command: string) => FREE_COMMANDS.has(command) || (isPureRead(command) && !LEASED_READS.has(command));
+
+function newLeaseId(): string {
+  let s = '';
+  for (let i = 0; i < 4; i++) s += Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, '0');
+  return s;
+}
+
+/** Null when [command] may run under the current lease (renewing it), else the refusal. Lazily expired. */
+export function leaseGate(command: string, leaseId: string | null): string | null {
+  if (lease && Date.now() > lease.expiresAtMs) lease = null;
+  if (!lease || freeWithoutLease(command)) {
+    if (lease && leaseId === lease.leaseId) {
+      lease.expiresAtMs = Date.now() + LEASE_RENEW_MS;
+      lease.commandsServed++;
+    }
+    return null;
+  }
+  if (leaseId !== lease.leaseId) {
+    return `The device is leased to "${lease.owner}" and this command carries no lease id. Command "${command}" was refused rather than interleaved into somebody else's run.`;
+  }
+  lease.expiresAtMs = Date.now() + LEASE_RENEW_MS;
+  lease.commandsServed++;
+  return null;
+}
+
+/** Who holds the device now, or null. */
+export function leaseHolder(): { readonly owner: string; readonly expiresInSeconds: number } | null {
+  if (!lease || Date.now() > lease.expiresAtMs) return null;
+  return { owner: lease.owner, expiresInSeconds: Math.round((lease.expiresAtMs - Date.now()) / 1000) };
+}
+
+export interface InstallLeaseOptions {
+  /** Also add the gate (default true). False: the host calls [leaseGate] from its own gate, in its own order. */
+  readonly gate?: boolean;
+}
+
+let installed: (() => void) | null = null;
+
+export function installLease(options: InstallLeaseOptions = {}): () => void {
+  if (installed) return installed;
+  const offs = [
+    registerCommand(
+      'lease.acquire',
+      (args) => {
+        const owner = optionalString(args, 'owner') ?? 'runner';
+        const ttl = Math.min(Math.max(optionalInt(args, 'ttlSeconds', 300), 1), 1800);
+        if (lease && Date.now() <= lease.expiresAtMs && lease.owner !== owner) {
+          const secs = Math.round((lease.expiresAtMs - Date.now()) / 1000);
+          throw new PilotError(`The device is already leased to "${lease.owner}" for another ${secs}s. Wait, or ask them to release it.`, {
+            code: 'LEASE_HELD',
+            category: 'lease',
+            hint: 'lease.status says who holds it and for how long.',
+          });
+        }
+        lease = { leaseId: newLeaseId(), owner, expiresAtMs: Date.now() + ttl * 1000, commandsServed: 0 };
+        return { leaseId: lease.leaseId, owner, ttlSeconds: ttl };
+      },
+      { scope: 'drive', mutating: false, description: 'Takes the device for one controller.', example: { owner: 'runner', ttlSeconds: 300 } },
+    ),
+    registerCommand(
+      'lease.release',
+      (args, ctx) => {
+        const id = optionalString(args, 'leaseId') ?? ctx.leaseId;
+        if (!lease) return { released: false, note: 'No lease was held.' };
+        if (id !== lease.leaseId) {
+          throw new PilotError(`The lease is held by "${lease.owner}"; a different lease id cannot release it.`, { code: 'LEASE_HELD', category: 'lease' });
+        }
+        const served = lease.commandsServed;
+        const owner = lease.owner;
+        lease = null;
+        return { released: true, owner, commandsServed: served };
+      },
+      { scope: 'drive', mutating: false, description: 'Gives the device back.' },
+    ),
+    registerCommand(
+      'lease.status',
+      () =>
+        lease && Date.now() <= lease.expiresAtMs
+          ? { held: true, leaseId: lease.leaseId, owner: lease.owner, expiresInSeconds: Math.round((lease.expiresAtMs - Date.now()) / 1000), commandsServed: lease.commandsServed }
+          : { held: false },
+      { scope: 'observe', description: 'Who holds the device, if anybody.' },
+    ),
+  ];
+  const offGate =
+    options.gate === false
+      ? () => undefined
+      : addGate((request) => {
+          // lease.release may name its lease in its arguments instead of the request (the id it is giving back).
+          const argId = request.command === 'lease.release' && typeof request.args?.['leaseId'] === 'string' ? (request.args['leaseId'] as string) : null;
+          const refused = leaseGate(request.command, request.leaseId ?? argId);
+          return refused ? { ok: false, error: refused, code: 'LEASE', category: 'lease', hint: 'Send the leaseId lease.acquire returned, or lease.status to see who holds it.' } : null;
+        });
+  installed = () => {
+    offs.forEach((off) => off());
+    offGate();
+    installed = null;
+  };
+  return installed;
+}
+
+/** Tests: forget the lease. */
+export function resetLeaseForTests(): void {
+  lease = null;
+}