@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/wait/wait-until.d.ts

@@ -0,0 +1,20 @@
+export interface WaitOptions {
+    /** Total time (ms) to keep probing; 0 probes exactly once */
+    timeout: number;
+    /** Time (ms) between probes. @default 100 */
+    interval?: number;
+}
+export declare class WaitTimeoutError<T> extends Error {
+    readonly timeout: number;
+    /** Last completed probe result; undefined when no probe completed */
+    readonly last: T | undefined;
+    constructor(timeout: number, last: T | undefined);
+}
+/** Per-call timeout, else the active run's expect timeout, else config `expect.timeout`, else 5000 */
+export declare function resolveTimeout(perCall?: number): Promise<number>;
+/**
+ * Probes until `isDone(current, previous)` is true and resolves with that result.
+ * Always probes at least once; with `timeout > 0` every probe races the time left.
+ * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
+ */
+export declare function waitUntil<T>(probe: () => Promise<T>, isDone: (current: T, previous: T | undefined) => boolean, { timeout, interval }: WaitOptions): Promise<T>;

package/dist/wait/wait-until.js

@@ -0,0 +1,63 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { readConfig } from "../config/config.js";
+import { peekRunSettings } from "../config/run-settings.js";
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_INTERVAL = 100;
+export class WaitTimeoutError extends Error {
+    constructor(timeout, last) {
+        super(`Condition not met within ${timeout}ms`);
+        this.name = "WaitTimeoutError";
+        this.timeout = timeout;
+        this.last = last;
+    }
+}
+/** Per-call timeout, else the active run's expect timeout, else config `expect.timeout`, else 5000 */
+export async function resolveTimeout(perCall) {
+    if (perCall !== undefined)
+        return perCall;
+    const run = peekRunSettings();
+    if (run)
+        return run.expectTimeout;
+    return (await readConfig("expect"))?.timeout ?? DEFAULT_TIMEOUT;
+}
+const DEADLINE = Symbol("deadline");
+/**
+ * Races `probe()` against the time left. Resolves `{ value }` when the probe wins,
+ * DEADLINE when the time runs out first; probe errors reject as-is.
+ */
+function probeBefore(probe, remaining) {
+    const probing = probe();
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(DEADLINE), remaining);
+    });
+    // A probe that loses the race may still fail later; nobody is waiting for it any more
+    probing.catch(() => { });
+    return Promise.race([probing.then((value) => ({ value })), expired]).finally(() => clearTimeout(timer));
+}
+/**
+ * Probes until `isDone(current, previous)` is true and resolves with that result.
+ * Always probes at least once; with `timeout > 0` every probe races the time left.
+ * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
+ */
+export async function waitUntil(probe, isDone, { timeout, interval = DEFAULT_INTERVAL }) {
+    const deadline = Date.now() + timeout;
+    let previous;
+    for (let first = true;; first = false) {
+        const remaining = deadline - Date.now();
+        // Only start a probe while time remains; a later one could only lose the race
+        if (!first && remaining <= 0)
+            throw new WaitTimeoutError(timeout, previous);
+        // timeout 0 keeps the single probe un-raced so it always completes
+        const result = timeout > 0 ? await probeBefore(probe, remaining) : { value: await probe() };
+        if (result === DEADLINE)
+            throw new WaitTimeoutError(timeout, previous);
+        if (isDone(result.value, previous))
+            return result.value;
+        previous = result.value;
+        const left = deadline - Date.now();
+        if (left <= 0)
+            throw new WaitTimeoutError(timeout, previous);
+        await sleep(Math.min(interval, left));
+    }
+}

package/package.json

@@ -1,16 +1,37 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "",
-  "main": "index.js",
+  "main": "dist/api.js",
   "exports": {
-    ".": "./src/api.ts"
+    ".": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/run.d.ts",
+      "default": "./dist/runner/run.js"
+    },
+    "./steps": {
+      "types": "./dist/steps/index.d.ts",
+      "default": "./dist/steps/index.js"
+    },
+    "./recorder": {
+      "types": "./dist/recorder/index.d.ts",
+      "default": "./dist/recorder/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "dev": "tsx src/index.ts",
-    "build": "tsc",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-types.mjs",
     "test": "tsx --test --test-timeout=10000 \"src/**/*.test.ts\"",
-    "test:browser": "tsx --test --test-concurrency=1 \"src/**/*.browser-test.ts\""
+    "test:browser": "tsx --test --test-concurrency=1 \"src/**/*.browser-test.ts\"",
+    "test:cli": "tsx --test --test-concurrency=1 \"src/**/*.cli-test.ts\""
   },
   "keywords": [],
   "author": "",
@@ -18,10 +39,26 @@
   "type": "module",
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.2"
+    "tsx": "^4.21.0"
   },
   "dependencies": {
+    "typescript": "^6.0.2",
     "winston": "^3.19.0"
+  },
+  "types": "dist/api.d.ts",
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "bin": {
+    "samurai": "bin/samurai.mjs"
+  },
+  "peerDependencies": {
+    "tsx": "^4.21.0"
+  },
+  "peerDependenciesMeta": {
+    "tsx": {
+      "optional": true
+    }
   }
 }

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npx tsc *)"
-    ]
-  }
-}

package/.env.example

@@ -1,3 +0,0 @@
-# Copy to .env.<environment>, e.g. .env.staging. Never commit real values.
-# Tests read these as secrets.TEST_CARD; real environment variables win over this file.
-SAMURAI_SECRET_TEST_CARD=

package/.github/actions/setup/action.yml

@@ -1,16 +0,0 @@
-name: Setup
-description: Install bun, Node and the locked dependencies
-
-runs:
-  using: composite
-  steps:
-    - uses: oven-sh/setup-bun@v2
-      with:
-        bun-version: 1.3.0
-    # The test scripts run tsx on Node's test runner, which needs Node 22+ (fs/promises glob)
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 26
-    - name: Install dependencies
-      shell: bash
-      run: bun install --frozen-lockfile

package/.github/workflows/ci.yml

@@ -1,71 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-permissions:
-  contents: read
-
-jobs:
-  typecheck:
-    name: Typecheck
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup
-      - name: Typecheck
-        run: bunx tsc --noEmit -p .
-
-  unit:
-    name: Unit tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup
-      - name: Unit tests
-        run: bun run test
-
-  browser:
-    name: Browser tests (Firefox)
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup
-      - name: Firefox version
-        run: firefox --version
-      - name: Browser tests
-        timeout-minutes: 12
-        run: bun run test:browser
-      - name: Upload logs
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: browser-test-logs
-          path: |
-            logs/
-            result/
-          retention-days: 7
-          if-no-files-found: ignore
-
-  trunk:
-    name: Code quality (Trunk)
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      contents: read
-      checks: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      # Checks only what the PR or push changed; linters come from .trunk/trunk.yaml
-      - uses: trunk-io/trunk-action@v1

package/.trunk/configs/.markdownlint.yaml

@@ -1,2 +0,0 @@
-# Prettier friendly markdownlint config (all formatting rules disabled)
-extends: markdownlint/style/prettier

package/.trunk/configs/.yamllint.yaml

@@ -1,7 +0,0 @@
-rules:
-  quoted-strings:
-    required: only-when-needed
-    extra-allowed: ["{|}"]
-  key-duplicates: {}
-  octal-values:
-    forbid-implicit-octal: true

package/.trunk/configs/svgo.config.mjs

@@ -1,14 +0,0 @@
-export default {
-  plugins: [
-    {
-      name: "preset-default",
-      params: {
-        overrides: {
-          removeViewBox: false, // https://github.com/svg/svgo/issues/1128
-          sortAttrs: true,
-          removeOffCanvasPaths: true,
-        },
-      },
-    },
-  ],
-};

package/.trunk/trunk.yaml

@@ -1,34 +0,0 @@
-# This file controls the behavior of Trunk: https://docs.trunk.io/cli
-# To learn more about the format of this file, see https://docs.trunk.io/reference/trunk-yaml
-version: 0.1
-cli:
-  version: 1.25.0
-# Trunk provides extensibility via plugins. (https://docs.trunk.io/plugins)
-plugins:
-  sources:
-    - id: trunk
-      ref: v1.11.0
-      uri: https://github.com/trunk-io/plugins
-# Many linters and tools depend on runtimes - configure them here. (https://docs.trunk.io/runtimes)
-runtimes:
-  enabled:
-    - node@22.16.0
-    - python@3.14.4
-# This is the section where you manage your linters. (https://docs.trunk.io/check/configuration)
-lint:
-  enabled:
-    - checkov@3.3.22
-    - git-diff-check
-    - grype@0.119.0
-    - markdownlint@0.49.1
-    - osv-scanner@2.6.0
-    - prettier@3.9.9
-    - svgo@4.1.0
-    - trufflehog@3.97.9
-    - yamllint@1.38.0
-actions:
-  enabled:
-    - trunk-announce
-    - trunk-check-pre-push
-    - trunk-fmt-pre-commit
-    - trunk-upgrade-available

package/docs/superpowers/bidi-roadmap.md

@@ -1,60 +0,0 @@
-# WebDriver BiDi adoption — roadmap
-
-Date: 2026-09-29
-Source: https://www.w3.org/TR/webdriver-bidi/
-Status: all 15 specs (0 to 14) are implemented.
-
-Each item links to its spec in `docs/superpowers/specs/`. Order respects dependencies (`←`).
-
-## Todo
-
-### Phase 0 — prerequisite
-- [x] **0. Foundation** — connector error replies, command typings, refcounted subscriptions, context tree, `newPage` fix — [spec](specs/2026-09-29-bidi-foundation-design.md)
-
-### Phase 1 — locator core
-- [x] **1. `script.callFunction` (+ `script.disown`)** ← 0 — [spec](specs/2026-09-29-script-call-function-design.md)
-- [x] **2. `script.addPreloadScript`** ← 0, 1 — [spec](specs/2026-09-29-preload-scripts-design.md)
-- [x] **3. `browsingContext.locateNodes`** ← 1 (2 optional) — [spec](specs/2026-09-29-locate-nodes-design.md)
-- [x] **4. `input.setFiles`** ← 1, 3 — [spec](specs/2026-09-29-set-files-design.md)
-
-### Phase 2 — waiting correctness
-- [x] **5. Network tracking + real network idle** ← 0 — [spec](specs/2026-09-29-network-tracking-design.md)
-- [x] **6. Navigation waits (`navigate` wait, load events, reload)** ← 0, 5 — [spec](specs/2026-09-29-navigation-waits-design.md)
-- [x] **7. User prompts (`handleUserPrompt`)** ← 0 — [spec](specs/2026-09-29-user-prompts-design.md)
-- [x] **8. Logs and page errors (`log.entryAdded`)** ← 0, 1 — [spec](specs/2026-09-29-logs-and-errors-design.md)
-
-### Phase 3 — features
-- [x] **9. Network interception (mock / block / modify)** ← 0, 5 — [spec](specs/2026-09-29-network-interception-design.md)
-- [x] **10. Network data (cache control, response bodies)** ← 5 — [spec](specs/2026-09-29-network-data-design.md)
-- [x] **11. Page API completeness (viewport, reload, history, close, pdf, screenshot)** ← 0, 1 — [spec](specs/2026-09-29-page-api-design.md)
-- [x] **12. User contexts + storage** ← 0 — [spec](specs/2026-09-29-contexts-and-storage-design.md)
-
-### Phase 4 — nice to have
-- [x] **13. Emulation** ← 12 — [spec](specs/2026-09-29-emulation-design.md)
-- [x] **14. Downloads + file dialogs** ← 0, 4 — [spec](specs/2026-09-29-downloads-and-file-dialogs-design.md)
-
-## Dependency graph
-
-```
-0 ─┬─ 1 ─┬─ 2
-   │     ├─ 3 ── 4 ── 14
-   │     ├─ 8
-   │     └─ 11
-   ├─ 5 ─┬─ 6
-   │     ├─ 9
-   │     └─ 10
-   ├─ 7
-   └─ 12 ── 13
-```
-
-## Deliberately skipped
-
-`webExtension.*`, `session.end`, `script.getRealms`, `script.removePreloadScript` as public API (used internally only), `network.continueWithAuth` (folded into spec 9 as a follow-up).
-
-## Cross-cutting rules for every spec
-
-- Test-first: each unit test before its implementation, using `src/testing/stub-connector.ts`; browser tests in `*.browser-test.ts` (`npm run test:browser`).
-- Any feature that needs an event subscribes through the refcounted API from spec 0, never a bare `session.subscribe`.
-- Every command a feature sends must be typed in `BiDiCommands` (spec 0 lists the missing ones).
-- Timeouts resolve through `resolveTimeout` (actions/assertions) or the navigation timeout from spec 6 (navigation); no unbounded waits.
-- Browser support is verified against Firefox (the only `SupportedBrowser` today). A command Firefox lacks is documented in its spec and surfaced as `UnsupportedOperationError`, not a hang.