lynkeus-protocol 0.2.0 → 0.3.0

package/lib/index.d.ts

@@ -31,6 +31,11 @@ export type Element = {
     /** Masked (`•`) when the field is a secure entry. */
     value?: string;
     placeholder?: string;
+    /** The size its text is set in, in points, and whether it is bold: what makes text "large" when its contrast is judged. */
+    font?: {
+        size: number;
+        bold?: boolean;
+    };
     focused?: boolean;
     /** Index of the nearest listed ancestor, when there is one. */
     parent?: number;
@@ -333,6 +338,8 @@ export type Response = {
 export type HelloEvent = {
     event: 'hello';
     protocolVersion: number;
+    /** The lynkeus-agent release in the app; absent from agents before it was sent. */
+    agentVersion?: string;
     platform: 'ios' | 'android' | string;
     native: boolean;
     commands: string[];
@@ -350,3 +357,4 @@ export type AuthEvent = {
     token?: string;
 };
 export type AgentEvent = HelloEvent | NavigationEvent;
+export * from './run.js';

package/lib/index.js

@@ -1,2 +1,3 @@
 /** JSON-RPC-shaped messages over a WebSocket the app opens towards the driver; docs/PROTOCOL.md has the prose. */
 export const PROTOCOL_VERSION = 1;
+export * from './run.js';

package/lib/run.d.ts

@@ -0,0 +1,114 @@
+/**
+ * What a run of cases leaves behind: a directory anything can read without
+ * knowing how the run was made.
+ *
+ *   run.json            a RunManifest
+ *   cases.jsonl         one RunCase per line, one line per attempt, in the order they ran
+ *   <case id>/…         what a case's steps point at: frames, a film
+ *
+ * Whoever writes it is an engine; whoever reads it (a report, a dashboard, a
+ * script) depends on this file and on nothing else. A field is only ever
+ * added. Anything that would change the meaning of an existing field raises
+ * RUN_SCHEMA, and a reader refuses a schema it does not know.
+ */
+export declare const RUN_SCHEMA = 1;
+/** Where an event was observed: inside the app, or by the backend the app talks to. */
+export type RunEventOrigin = 'app' | 'server';
+export type RunEvent = {
+    origin: RunEventOrigin;
+    name: string;
+    props?: Record<string, unknown>;
+    /** Who it was sent to, when the engine can tell: 'mixpanel', 'datadog', … */
+    provider?: string;
+    /** The route the app was on, for an event observed in the app. */
+    route?: string;
+    /** ISO 8601, when the source says. */
+    at?: string;
+    /** The request that caused it, for a server event: what files it under a step. */
+    requestId?: string;
+};
+/** `unsupported`: the host the run was on has no way to do the step; it says nothing about the app. */
+export type RunStepStatus = 'passed' | 'failed' | 'skipped' | 'unsupported';
+/**
+ * What the backend did for a step, from the traces it exported: the request the step's app sent, and the
+ * queries, jobs and calls out it set off. One per span, in the order they began; `depth` nests them.
+ */
+export type RunBackendSpan = {
+    name: string;
+    /** server, client, internal, producer or consumer, as OpenTelemetry says. */
+    kind: string;
+    /** Milliseconds after the step began. */
+    at: number;
+    ms: number;
+    depth: number;
+    /** The service that exported it, when it says. */
+    service?: string;
+    error?: string;
+    /** What it did: method, route, status, table, job class, host called. */
+    attributes?: Record<string, string | number | boolean>;
+};
+export type RunStep = {
+    /** The step as the case words it. */
+    step: string;
+    status: RunStepStatus;
+    ms: number;
+    error?: string;
+    /** Which part of the case it belongs to. */
+    section?: 'setup' | 'steps';
+    events?: RunEvent[];
+    /** A frame taken once the step was done, relative to the run directory. */
+    screenshot?: string;
+    /** The second of the case's film this step starts at. */
+    videoS?: number;
+    /** What the backend did for it, when the backend exports traces to the run. */
+    backend?: RunBackendSpan[];
+};
+export type RunCase = {
+    id: string;
+    title?: string;
+    description?: string;
+    /** The case file, relative to where the run was started. */
+    file: string;
+    /** 1 for the first try; a case that failed and ran again has a line for each. */
+    attempt: number;
+    /** `unsupported`: one of its steps could not be done on this host, so it proved nothing here. */
+    result: 'passed' | 'failed' | 'unsupported';
+    /** ISO 8601. */
+    startedAt: string;
+    ms: number;
+    steps: RunStep[];
+    /** Why it failed, as rules read off the screen, the requests and the trace. */
+    diagnosis?: string[];
+    /** When a step failed: the screen, the requests since the case began, and why. */
+    evidence?: {
+        screen?: string;
+        requests?: string[];
+        why?: string;
+    };
+    /** The case's film, relative to the run directory. */
+    video?: string;
+};
+export type RunManifest = {
+    schema: typeof RUN_SCHEMA;
+    /** ISO 8601. */
+    startedAt: string;
+    /** Absent while the run is going, or when it was cut short. */
+    finishedAt?: string;
+    /** What the app said it runs on: 'ios', 'android', … */
+    platform?: string;
+    /** Whether the app ran on a device or simulator (true) or hosted without one. */
+    native?: boolean;
+    /** Where the run was made from, when it was a git checkout. */
+    git?: {
+        branch?: string;
+        commit?: string;
+    };
+    /** Cases by their last attempt. */
+    totals?: {
+        cases: number;
+        passed: number;
+        failed: number;
+        unsupported: number;
+        retried: number;
+    };
+};

package/lib/run.js

@@ -0,0 +1,14 @@
+/**
+ * What a run of cases leaves behind: a directory anything can read without
+ * knowing how the run was made.
+ *
+ *   run.json            a RunManifest
+ *   cases.jsonl         one RunCase per line, one line per attempt, in the order they ran
+ *   <case id>/…         what a case's steps point at: frames, a film
+ *
+ * Whoever writes it is an engine; whoever reads it (a report, a dashboard, a
+ * script) depends on this file and on nothing else. A field is only ever
+ * added. Anything that would change the meaning of an existing field raises
+ * RUN_SCHEMA, and a reader refuses a schema it does not know.
+ */
+export const RUN_SCHEMA = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus-protocol",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Wire contract between an app running lynkeus-agent and whatever drives it.",
   "type": "module",
   "main": "./lib/index.js",
@@ -13,7 +13,8 @@
   },
   "files": [
     "lib",
-    "src"
+    "src",
+    "!**/__tests__"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -22,14 +23,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jonamischener/lynkeus.git",
+    "url": "git+https://github.com/lynkeushq/lynkeus.git",
     "directory": "packages/protocol"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "tsx": "^4.19.2",
     "typescript": "^6.0.3"
   },
-  "homepage": "https://github.com/jonamischener/lynkeus#readme"
+  "homepage": "https://github.com/lynkeushq/lynkeus#readme"
 }

package/src/index.ts

@@ -30,6 +30,8 @@ export type Element = {
   /** Masked (`•`) when the field is a secure entry. */
   value?: string;
   placeholder?: string;
+  /** The size its text is set in, in points, and whether it is bold: what makes text "large" when its contrast is judged. */
+  font?: { size: number; bold?: boolean };
   focused?: boolean;
   /** Index of the nearest listed ancestor, when there is one. */
   parent?: number;
@@ -179,6 +181,8 @@ export type Response = { id: number; result: unknown } | { id: number; error: {
 export type HelloEvent = {
   event: 'hello';
   protocolVersion: number;
+  /** The lynkeus-agent release in the app; absent from agents before it was sent. */
+  agentVersion?: string;
   platform: 'ios' | 'android' | string;
   native: boolean;
   commands: string[];
@@ -189,3 +193,5 @@ export type NavigationEvent = { event: 'navigation'; route?: string };
 /** The driver's first message. `session` is random per driver process, so the app can tell a reconnect (whose resent requests it may have answered) from a new driver reusing request ids. */
 export type AuthEvent = { event: 'auth'; session: string; token?: string };
 export type AgentEvent = HelloEvent | NavigationEvent;
+
+export * from './run.js';

package/src/run.ts

@@ -0,0 +1,108 @@
+/**
+ * What a run of cases leaves behind: a directory anything can read without
+ * knowing how the run was made.
+ *
+ *   run.json            a RunManifest
+ *   cases.jsonl         one RunCase per line, one line per attempt, in the order they ran
+ *   <case id>/…         what a case's steps point at: frames, a film
+ *
+ * Whoever writes it is an engine; whoever reads it (a report, a dashboard, a
+ * script) depends on this file and on nothing else. A field is only ever
+ * added. Anything that would change the meaning of an existing field raises
+ * RUN_SCHEMA, and a reader refuses a schema it does not know.
+ */
+export const RUN_SCHEMA = 1;
+
+/** Where an event was observed: inside the app, or by the backend the app talks to. */
+export type RunEventOrigin = 'app' | 'server';
+
+export type RunEvent = {
+  origin: RunEventOrigin;
+  name: string;
+  props?: Record<string, unknown>;
+  /** Who it was sent to, when the engine can tell: 'mixpanel', 'datadog', … */
+  provider?: string;
+  /** The route the app was on, for an event observed in the app. */
+  route?: string;
+  /** ISO 8601, when the source says. */
+  at?: string;
+  /** The request that caused it, for a server event: what files it under a step. */
+  requestId?: string;
+};
+
+/** `unsupported`: the host the run was on has no way to do the step; it says nothing about the app. */
+export type RunStepStatus = 'passed' | 'failed' | 'skipped' | 'unsupported';
+
+/**
+ * What the backend did for a step, from the traces it exported: the request the step's app sent, and the
+ * queries, jobs and calls out it set off. One per span, in the order they began; `depth` nests them.
+ */
+export type RunBackendSpan = {
+  name: string;
+  /** server, client, internal, producer or consumer, as OpenTelemetry says. */
+  kind: string;
+  /** Milliseconds after the step began. */
+  at: number;
+  ms: number;
+  depth: number;
+  /** The service that exported it, when it says. */
+  service?: string;
+  error?: string;
+  /** What it did: method, route, status, table, job class, host called. */
+  attributes?: Record<string, string | number | boolean>;
+};
+
+export type RunStep = {
+  /** The step as the case words it. */
+  step: string;
+  status: RunStepStatus;
+  ms: number;
+  error?: string;
+  /** Which part of the case it belongs to. */
+  section?: 'setup' | 'steps';
+  events?: RunEvent[];
+  /** A frame taken once the step was done, relative to the run directory. */
+  screenshot?: string;
+  /** The second of the case's film this step starts at. */
+  videoS?: number;
+  /** What the backend did for it, when the backend exports traces to the run. */
+  backend?: RunBackendSpan[];
+};
+
+export type RunCase = {
+  id: string;
+  title?: string;
+  description?: string;
+  /** The case file, relative to where the run was started. */
+  file: string;
+  /** 1 for the first try; a case that failed and ran again has a line for each. */
+  attempt: number;
+  /** `unsupported`: one of its steps could not be done on this host, so it proved nothing here. */
+  result: 'passed' | 'failed' | 'unsupported';
+  /** ISO 8601. */
+  startedAt: string;
+  ms: number;
+  steps: RunStep[];
+  /** Why it failed, as rules read off the screen, the requests and the trace. */
+  diagnosis?: string[];
+  /** When a step failed: the screen, the requests since the case began, and why. */
+  evidence?: { screen?: string; requests?: string[]; why?: string };
+  /** The case's film, relative to the run directory. */
+  video?: string;
+};
+
+export type RunManifest = {
+  schema: typeof RUN_SCHEMA;
+  /** ISO 8601. */
+  startedAt: string;
+  /** Absent while the run is going, or when it was cut short. */
+  finishedAt?: string;
+  /** What the app said it runs on: 'ios', 'android', … */
+  platform?: string;
+  /** Whether the app ran on a device or simulator (true) or hosted without one. */
+  native?: boolean;
+  /** Where the run was made from, when it was a git checkout. */
+  git?: { branch?: string; commit?: string };
+  /** Cases by their last attempt. */
+  totals?: { cases: number; passed: number; failed: number; unsupported: number; retried: number };
+};

package/src/__tests__/shape.test.ts

@@ -1,52 +0,0 @@
-import assert from 'node:assert/strict';
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { test } from 'node:test';
-import { fileURLToPath } from 'node:url';
-
-import { PROTOCOL_VERSION } from '../index.js';
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-const source = fs.readFileSync(path.join(here, '..', 'index.ts'), 'utf8');
-const frozenFile = path.join(here, '..', '..', 'shape.json');
-const agentProtocol = fs.readFileSync(path.join(here, '..', '..', '..', 'agent', 'src', 'protocol.ts'), 'utf8');
-
-const SHAPES = ['ElementKind', 'HiddenReason', 'Frame', 'Element', 'Screen', 'Scope', 'Target'];
-
-const declaration = (name: string): string => {
-  const start = source.search(new RegExp(`export type ${name}\\b`));
-  assert.notEqual(start, -1, `no export type ${name} in the protocol`);
-  let depth = 0;
-  for (let i = start; i < source.length; i++) {
-    const c = source[i];
-    if (c === '{' || c === '(') depth++;
-    else if (c === '}' || c === ')') depth--;
-    else if (c === ';' && depth === 0) return source.slice(start, i + 1);
-  }
-  return source.slice(start);
-};
-
-const normalized = (text: string) =>
-  text
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .replace(/\/\/.*$/gm, '')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-const hash = createHash('sha1')
-  .update(SHAPES.map((n) => normalized(declaration(n))).join('\n'))
-  .digest('hex');
-const agentVersion = Number(/PROTOCOL_VERSION = (\d+)/.exec(agentProtocol)?.[1]);
-
-test('the protocol shapes change only on purpose', () => {
-  if (process.env.UPDATE_PROTOCOL_SHAPE === '1') fs.writeFileSync(frozenFile, `${JSON.stringify({ version: PROTOCOL_VERSION, hash }, null, 2)}\n`);
-  const frozen = JSON.parse(fs.readFileSync(frozenFile, 'utf8')) as { version: number; hash: string };
-  assert.equal(
-    hash,
-    frozen.hash,
-    `${SHAPES.join(', ')} changed. A change a driver of version ${frozen.version} would misread needs PROTOCOL_VERSION bumped; an optional field it can ignore does not. Either way, record the decision with UPDATE_PROTOCOL_SHAPE=1.`,
-  );
-  assert.equal(PROTOCOL_VERSION, frozen.version, 'PROTOCOL_VERSION moved without recording the shape it belongs to (UPDATE_PROTOCOL_SHAPE=1)');
-  assert.equal(agentVersion, PROTOCOL_VERSION, "lynkeus-agent's own PROTOCOL_VERSION must equal this one");
-});