@exodus/xqa 1.14.1 → 1.14.2

package/README.md

@@ -14,12 +14,20 @@ The tool manages configuration, project initialization, session state tracking,
 
 Initialize a new xqa project in the current directory.
 
-Creates a `.xqa/` directory with templates and subdirectories for specs, designs, and suites. Installs the `xqa-spec` skill for creating test specs.
+Creates a `.xqa/` directory with `app.md` and `explore.md` templates plus subdirectories for specs, designs, and suites. Installs bundled xqa skills.
 
 ```bash
 xqa init
 ```
 
+### update
+
+Update installed xqa skills to the current CLI version.
+
+```bash
+xqa update
+```
+
 ### explore [prompt]
 
 Run the explorer agent; omit prompt for a full breadth-first sweep.
@@ -31,44 +39,73 @@ xqa explore                          # breadth-first exploration
 xqa explore "test the login flow"    # focused exploration
 xqa explore -v prompt,screen         # verbose output for categories
 xqa explore -v                       # verbose output for all categories
+xqa explore -t 600                   # override explorer timeout (seconds)
+xqa explore --debug                  # log timing and event details to stderr
 ```
 
-Flag: `-v, --verbose [categories]` — Log categories (prompt, tools, screen, memory). Default: all if flag is present without value.
+Flags:
+
+- `-v, --verbose [categories]` — Log categories (prompt, tools, screen, memory). Default: all if flag is present without value.
+- `-t, --timeout <seconds>` — Explorer timeout in seconds (overrides `QA_EXPLORE_TIMEOUT_SECONDS`).
+- `--debug` — Log timing and event details to stderr.
 
 ### spec [spec-file]
 
 Run the explorer agent against a spec file.
 
-Loads a spec markdown file from `.xqa/specs/` (or an absolute path) and executes the agent against it. Spec files define entry points, steps, and optional timeouts. Omit the argument to pick from available specs interactively.
+Loads a spec markdown file from `.xqa/specs/` (or an absolute path) and executes the agent against it. Omit the argument to pick from available specs interactively.
 
 ```bash
 xqa spec                                      # interactive spec picker
-xqa spec .xqa/specs/authentication.test.md   # explicit spec file
+xqa spec .xqa/specs/authentication.test.md    # explicit spec file
 xqa spec -v tools,memory                      # verbose output
+xqa spec --debug                              # debug logging
 ```
 
-Flag: `-v, --verbose [categories]` — Same as explore.
+Flags:
+
+- `-v, --verbose [categories]` — Same as explore.
+- `--debug` — Log timing and event details to stderr.
 
 Spec file format (YAML frontmatter + markdown):
 
 ```markdown
 ---
 feature: 'Feature Name'
-entry: 'Screen name or navigation path'
 timeout: 300
 ---
 
 # Spec content
 ```
 
+Frontmatter fields: `feature` (required), `timeout` (optional, seconds).
+
+### run
+
+Run a test suite or a set of spec files in parallel across booted simulators.
+
+Exactly one of `--suite` or `--spec` is required.
+
+```bash
+xqa run --suite smoke                         # run .xqa/suites/smoke.suite.json
+xqa run --spec 'specs/**/*.test.md'           # run matching spec files
+xqa run --suite smoke --debug                 # debug logging
+```
+
+Flags:
+
+- `--suite <name>` — Name of the suite (`<name>.suite.json`) under `.xqa/suites/`.
+- `--spec <globs...>` — Glob patterns matching spec files, resolved from the xqa directory.
+- `--debug` — Log timing and event details to stderr.
+
 ### review [findings-path]
 
 Review findings and mark false positives.
 
-Interactive session for triaging findings generated by explore or spec runs. Displays findings with confidence scores, steps, and screenshots. Mark findings as false positives (with optional reason) or undo previous dismissals. Saves dismissals to `.xqa/dismissals.json`. Defaults to the last findings path if omitted.
+Interactive session for triaging findings generated by explore or spec runs. Mark findings as dismissed (with optional reason) or undo previous dismissals. Dismissals are written to `dismissals.json` next to the `.xqa` directory (override with `QA_DISMISSALS_PATH`). Defaults to the last findings path if omitted.
 
 ```bash
-xqa review                                      # use last findings file
+xqa review                                     # use last findings file
 xqa review .xqa/output/findings-abc123.json    # explicit path
 ```
 
@@ -93,26 +130,35 @@ xqa completion bash  # generate bash completions
 xqa completion zsh   # generate zsh completions
 ```
 
-### Suite hooks
+### Suite config
 
-Suite config files may declare a `beforeEach` hook that runs before every work item on every simulator. Use this for project-owned setup (wallet provisioning, cache warming, login seeding).
+Suite files live at `.xqa/suites/<name>.suite.json` and declare the work items plus optional hooks.
 
 ```json
 {
   "specs": ["specs/send.test.md"],
+  "freestyle": [{ "prompt": "explore settings", "timeoutSeconds": 300 }],
   "hooks": {
     "beforeEach": {
       "script": "qa/prepare-sim.mjs",
-      "env": { "APP_PROFILE": "funded" }
+      "env": { "APP_PROFILE": "funded" },
+      "timeoutSeconds": 120
     }
   }
 }
 ```
 
+Fields:
+
+- `specs` (optional) — glob patterns resolved from the xqa directory.
+- `freestyle` (optional) — either a positive integer (N empty entries) or an array of `{ prompt?, timeoutSeconds }` entries.
+- At least one of `specs` or `freestyle` must resolve to a work item.
+- `hooks.beforeEach` (optional) — runs before every work item on every simulator. Use for project-owned setup (wallet provisioning, cache warming, login seeding).
+
 The hook script is invoked as a Node child process. It receives:
 
 - Inherited `process.env`
-- Suite-declared `env` (merged below reserved keys)
+- Suite-declared `env` overlaid with reserved keys (reserved wins)
 - Reserved xqa-owned keys: `XQA_SIM_UDID`, `XQA_ITEM_ID`, `XQA_ITEM_TYPE`, `XQA_ITEM_NAME`, `XQA_SUITE`, and (when item type is `spec`) `XQA_SPEC_PATH`
 
 Suite-declared `env` cannot override reserved keys — the parser rejects such configs.
@@ -121,7 +167,7 @@ Contract:
 
 - Exit 0 → proceed with item.
 - Non-zero exit → item marked failed, `executeItem` skipped, counts toward simulator-unhealthy threshold.
-- 120s timeout (not configurable in v1).
+- Default 120s timeout, overridable via `hooks.beforeEach.timeoutSeconds`.
 - Honors the suite abort signal.
 
 ## Configuration
@@ -133,15 +179,17 @@ Configuration is loaded from environment variables and `.env.local`:
 - `QA_RUN_ID` (optional) — Custom run identifier; defaults to auto-generated
 - `QA_EXPLORE_TIMEOUT_SECONDS` (optional) — Exploration timeout in seconds
 - `QA_BUILD_ENV` (optional) — Build environment: `dev` or `prod` (default: prod)
+- `QA_DISMISSALS_PATH` (optional) — Override the dismissals file path used by `xqa review`
 
 ## Architecture
 
 Key files and directories:
 
 - `src/index.ts` — CLI entry point; wires commander commands and manages graceful shutdown via process locks
-- `src/commands/` — Command implementations (init, explore, spec, review, analyse, completion)
-- `src/core/` — Pure functions: spec parsing, completion generation, verbose option parsing, last-path tracking
-- `src/shell/` — I/O wrappers: file reading, device discovery, app context loading
+- `src/commands/` — Command implementations (init, update, explore, spec, review, analyse, completion)
+- `src/suite/` — Suite runner: config parsing, work-item building, worker pool, hooks
+- `src/core/` — Pure functions: completion generation, verbose/timeout option parsing, last-path tracking
+- `src/shell/` — I/O wrappers: app/explore context reading, debug logging, display factory, preflight, xqa directory discovery
 - `src/config.ts`, `src/config-schema.ts` — Configuration loading and validation with Zod
 - `src/review-session.ts` — Interactive finding review loop with dismissal tracking
 - `src/spec-frontmatter.ts` — Spec markdown frontmatter parsing (YAML)
@@ -157,6 +205,8 @@ Core error discriminated unions:
 - `XqaDirectoryError` — No .xqa directory found (XQA_NOT_INITIALIZED)
 - `SpecFrontmatterError` — Malformed spec markdown (MISSING_FRONTMATTER, MISSING_FIELD, PARSE_ERROR)
 - `LastPathError` — No findings path provided and no prior session (NO_ARG_AND_NO_STATE)
+- `SuiteConfigError` — Suite config JSON malformed or schema-invalid (INVALID_SUITE_CONFIG)
+- `HookError` — Suite hook failure (HOOK_SPAWN_FAILED, HOOK_EXIT_NONZERO, HOOK_TIMEOUT, HOOK_ABORTED)
 
 ## Development
 
@@ -231,20 +281,39 @@ src/
 
   commands/
     init-command.ts           # Project initialization
+    update-command.ts         # Skill updates
+    install-skills.ts         # Bundled skill installer
     explore-command.ts        # Breadth-first exploration
     spec-command.ts           # Spec-based exploration
+    spec-resolver.ts          # Spec file discovery and parsing
     review-command.ts         # Finding triage workflow
     analyse-command.ts        # Video analysis
     completion-command.ts     # Shell completion generation
+    item-events.ts            # Start/complete/fail event emitters
 
   core/
     parse-verbose.ts          # Verbose flag parsing
+    parse-timeout-seconds.ts  # Timeout flag parsing
     completion-generator.ts   # Bash/zsh completion script generation
     last-path.ts              # Last findings path tracking
 
   shell/
     app-context.ts            # Read app.md and explore.md
     xqa-directory.ts          # Locate .xqa directory
+    preflight.ts              # Environment preflight checks
+    ffmpeg-check.ts           # ffmpeg availability probe
+    display-factory.ts        # Solo and suite display factories
+    debug-logger.ts           # Debug event logging
+    debug-agent-events.ts     # Agent event debug formatter
+    debug-suite-events.ts     # Suite event debug formatter
+    debug-logger-core.ts      # Pure logging helpers
+    trigger-abort.ts          # Abort signal plumbing
+
+  suite/
+    types.ts                  # Suite work-item and findings types
+    core/                     # Pure: config parser, item builders, hook env, queue
+    shell/                    # I/O: worker pool, hook runner, findings writer
+    commands/                 # run-command, execute-item, suite-run-context
 
   __tests__/
     *.test.ts                 # Test files co-located with src/

package/dist/xqa.cjs

@@ -52351,27 +52351,13 @@ var DEFAULT_LONG_PRESS_DURATION_MS = 500;
 var MS_PER_SECOND = 1e3;
 var DEFAULT_SWIPE_DURATION_SECONDS = 0.1;
 var ENTER_KEY_CODE = "0x28";
-var TAP_SCHEMA = { x: external_exports.number(), y: external_exports.number() };
-var LONG_PRESS_SCHEMA = { x: external_exports.number(), y: external_exports.number(), duration: external_exports.number().optional() };
-var SWIPE_SCHEMA = {
-  x_start: external_exports.number(),
-  y_start: external_exports.number(),
-  x_end: external_exports.number(),
-  y_end: external_exports.number(),
-  duration: external_exports.number().positive().optional().describe(
-    "Gesture duration in seconds. Smaller values (e.g. 0.1) produce a flick that scrolls lists and dismisses sheets; larger values (e.g. 0.5+) produce a slow drag suitable for reordering or panning. Defaults to 0.1s (flick)."
-  )
-};
-var TYPE_TEXT_SCHEMA = { text: external_exports.string(), submit: external_exports.boolean().optional() };
-var PRESS_BUTTON_SCHEMA = {
-  button: external_exports.enum(["HOME", "LOCK", "SIRI", "SIDE_BUTTON", "APPLE_PAY"])
-};
 function errorResult2(error48) {
   return {
     content: [{ type: "text", text: `Error: ${String(error48.cause)}` }],
     isError: true
   };
 }
+var TAP_SCHEMA = { x: external_exports.number(), y: external_exports.number() };
 function buildTapArguments(resolvedUdid, input) {
   return ["ui", "tap", "--udid", resolvedUdid, String(input.x), String(input.y)];
 }
@@ -52406,6 +52392,23 @@ async function handleDoubleTap(input) {
     ]
   };
 }
+function createTapTool(udid = "booted") {
+  return _x(
+    "tap",
+    "Tap on the screen at the given coordinates.",
+    TAP_SCHEMA,
+    async ({ x, y: y6 }) => handleTap({ udid, x, y: y6 })
+  );
+}
+function createDoubleTapTool(udid = "booted") {
+  return _x(
+    "double_tap",
+    "Double-tap on the screen at the given coordinates.",
+    TAP_SCHEMA,
+    async ({ x, y: y6 }) => handleDoubleTap({ udid, x, y: y6 })
+  );
+}
+var LONG_PRESS_SCHEMA = { x: external_exports.number(), y: external_exports.number(), duration: external_exports.number().optional() };
 function buildLongPressArguments(resolvedUdid, input) {
   return [
     "ui",
@@ -52434,8 +52437,39 @@ async function handleLongPress(input) {
     ]
   };
 }
+function createLongPressTool(udid = "booted") {
+  return _x(
+    "long_press",
+    "Long-press on the screen at the given coordinates.",
+    LONG_PRESS_SCHEMA,
+    async ({ x, y: y6, duration: duration3 }) => handleLongPress({ udid, x, y: y6, duration: duration3 ?? DEFAULT_LONG_PRESS_DURATION_MS })
+  );
+}
+var SWIPE_SCHEMA = {
+  x_start: external_exports.number(),
+  y_start: external_exports.number(),
+  x_end: external_exports.number(),
+  y_end: external_exports.number(),
+  duration: external_exports.number().positive().optional().describe(
+    "Seconds for the full gesture. Velocity = distance / duration \u2014 raise duration at fixed distance to slow the gesture and reduce momentum. Default 0.1s (flick) works for short lists; raise to 0.4\u20130.8 for controlled scrolling on long lists where the flick overshoots."
+  ),
+  delta: external_exports.number().positive().optional().describe(
+    "Pixel distance between interpolated touch points along the swipe path. Smaller values (e.g. 5) produce a denser event stream \u2014 smoother motion and more controllable stop-velocity, recommended when combining with a raised duration to tame long-list overshoot. Larger values produce coarser strokes. Omit to use idb defaults."
+  )
+};
+function toSwipeInput(udid, params) {
+  return {
+    udid,
+    xStart: params.x_start,
+    yStart: params.y_start,
+    xEnd: params.x_end,
+    yEnd: params.y_end,
+    duration: params.duration ?? DEFAULT_SWIPE_DURATION_SECONDS,
+    delta: params.delta
+  };
+}
 function buildSwipeArguments(resolvedUdid, input) {
-  return [
+  const arguments_ = [
     "ui",
     "swipe",
     "--udid",
@@ -52447,6 +52481,10 @@ function buildSwipeArguments(resolvedUdid, input) {
     "--duration",
     String(input.duration)
   ];
+  if (input.delta !== void 0) {
+    arguments_.push("--delta", String(input.delta));
+  }
+  return arguments_;
 }
 async function handleSwipe(input) {
   const result = await resolveUdid(input.udid).andThen(
@@ -52464,6 +52502,15 @@ async function handleSwipe(input) {
     ]
   };
 }
+function createSwipeTool(udid = "booted") {
+  return _x(
+    "swipe",
+    "Swipe on the screen from one point to another. Default duration 0.1s produces a flick \u2014 use for scrolling lists, dismissing sheets, triggering paging. Use duration 0.5+ for slow drag (reorder, pan). For long lists where default flick overshoots: shorten swipe distance AND raise duration to 0.4\u20130.8 to lower velocity; optionally lower delta for denser touch events and a more controllable stop. Omitting duration uses the flick default.",
+    SWIPE_SCHEMA,
+    async (params) => handleSwipe(toSwipeInput(udid, params))
+  );
+}
+var TYPE_TEXT_SCHEMA = { text: external_exports.string(), submit: external_exports.boolean().optional() };
 async function handleTypeText({ udid, text, submit }) {
   const result = await resolveUdid(udid).andThen((resolvedUdid) => {
     const typeResult = runCommand("idb", ["ui", "text", "--udid", resolvedUdid, text]);
@@ -52479,6 +52526,17 @@ async function handleTypeText({ udid, text, submit }) {
   }
   return { content: [{ type: "text", text: `Typed: ${text}` }] };
 }
+function createTypeTextTool(udid = "booted") {
+  return _x(
+    "type_text",
+    "Type text into the currently focused element.",
+    TYPE_TEXT_SCHEMA,
+    async ({ text, submit }) => handleTypeText({ udid, text, submit: submit ?? false })
+  );
+}
+var PRESS_BUTTON_SCHEMA = {
+  button: external_exports.enum(["HOME", "LOCK", "SIRI", "SIDE_BUTTON", "APPLE_PAY"])
+};
 async function handlePressButton(udid, button) {
   const result = await resolveUdid(udid).andThen(
     (resolvedUdid) => runCommand("idb", ["ui", "button", "--udid", resolvedUdid, button])
@@ -52488,56 +52546,6 @@ async function handlePressButton(udid, button) {
   }
   return { content: [{ type: "text", text: `Pressed button: ${button}` }] };
 }
-function createTapTool(udid = "booted") {
-  return _x(
-    "tap",
-    "Tap on the screen at the given coordinates.",
-    TAP_SCHEMA,
-    async ({ x, y: y6 }) => handleTap({ udid, x, y: y6 })
-  );
-}
-function createDoubleTapTool(udid = "booted") {
-  return _x(
-    "double_tap",
-    "Double-tap on the screen at the given coordinates.",
-    TAP_SCHEMA,
-    async ({ x, y: y6 }) => handleDoubleTap({ udid, x, y: y6 })
-  );
-}
-function createLongPressTool(udid = "booted") {
-  return _x(
-    "long_press",
-    "Long-press on the screen at the given coordinates.",
-    LONG_PRESS_SCHEMA,
-    async ({ x, y: y6, duration: duration3 }) => handleLongPress({ udid, x, y: y6, duration: duration3 ?? DEFAULT_LONG_PRESS_DURATION_MS })
-  );
-}
-function toSwipeInput(udid, params) {
-  return {
-    udid,
-    xStart: params.x_start,
-    yStart: params.y_start,
-    xEnd: params.x_end,
-    yEnd: params.y_end,
-    duration: params.duration ?? DEFAULT_SWIPE_DURATION_SECONDS
-  };
-}
-function createSwipeTool(udid = "booted") {
-  return _x(
-    "swipe",
-    "Swipe on the screen from one point to another. `duration` (seconds) controls gesture velocity: the default 0.1s produces a flick that scrolls lists, dismisses sheets and triggers paging; pass a larger value (e.g. 0.5+) for a slow drag suitable for reordering or panning. Omitting `duration` uses the flick default.",
-    SWIPE_SCHEMA,
-    async (params) => handleSwipe(toSwipeInput(udid, params))
-  );
-}
-function createTypeTextTool(udid = "booted") {
-  return _x(
-    "type_text",
-    "Type text into the currently focused element.",
-    TYPE_TEXT_SCHEMA,
-    async ({ text, submit }) => handleTypeText({ udid, text, submit: submit ?? false })
-  );
-}
 function createPressButtonTool(udid = "booted") {
   return _x(
     "press_button",
@@ -76515,7 +76523,7 @@ function resolveXqaDirectory() {
   return result.value;
 }
 var program2 = new Command();
-program2.name("xqa").description("AI-powered QA agent CLI").version(`${"1.14.1"}${false ? ` (dev build +${"18d343b"})` : ""}`);
+program2.name("xqa").description("AI-powered QA agent CLI").version(`${"1.14.2"}${false ? ` (dev build +${"5d87cb5"})` : ""}`);
 program2.command("init").description("Initialize a new xqa project in the current directory").action(() => {
   runInitCommand();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/xqa",
-  "version": "1.14.1",
+  "version": "1.14.2",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -26,11 +26,11 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.1",
     "zod": "^3.0.0",
+    "@qa-agents/display": "0.0.0",
+    "@qa-agents/eslint-config": "0.0.0",
     "@qa-agents/explorer": "0.0.0",
     "@qa-agents/mobile-ios": "0.0.0",
     "@qa-agents/pipeline": "0.0.0",
-    "@qa-agents/display": "0.0.0",
-    "@qa-agents/eslint-config": "0.0.0",
     "@qa-agents/shared": "0.0.0",
     "@qa-agents/typescript-config": "0.0.0"
   },