nestjs-puppeteer 2.2.0 → 2.3.0

package/.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --claim
+bd update <issue-id> --status done
+
+# Sync with Dolt remote
+bd dolt push
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in Dolt database with version control and branching
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Dolt-native three-way merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

package/.beads/config.yaml

@@ -0,0 +1,56 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: JSONL-only, no Dolt database
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# no-db: false
+
+# Enable JSON output by default
+# json: false
+
+# Feedback title formatting for mutating commands (create/update/close/dep/edit)
+# 0 = hide titles, N > 0 = truncate to N characters
+# output:
+#   title-length: 255
+
+# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
+# actor: ""
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct database
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# JSONL backup (periodic export for off-machine recovery)
+# Auto-enabled when a git remote exists. Override explicitly:
+# backup:
+#   enabled: false     # Disable auto-backup entirely
+#   interval: 15m      # Minimum time between auto-exports
+#   git-push: false    # Disable git push (export locally only)
+#   git-repo: ""       # Separate git repo for backups (default: project repo)
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo
+
+sync.remote: "git+https://github.com/oblakstudio/nestjs-puppeteer"

package/.beads/hooks/applypatch-msg

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/commit-msg

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/post-applypatch

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/post-checkout

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"
+
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run post-checkout "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run post-checkout "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

package/.beads/hooks/post-commit

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/post-merge

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"
+
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run post-merge "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run post-merge "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

package/.beads/hooks/post-rewrite

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/pre-applypatch

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/pre-auto-gc

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/pre-commit

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"
+
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run pre-commit "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run pre-commit "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

package/.beads/hooks/pre-merge-commit

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/pre-push

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"
+
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run pre-push "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run pre-push "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

package/.beads/hooks/pre-rebase

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"

package/.beads/hooks/prepare-commit-msg

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.
+export PATH="$PWD/node_modules/.bin:$PATH"
+
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run prepare-commit-msg "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

package/.beads/issues.jsonl

@@ -0,0 +1,10 @@
+{"id":"nestjs-puppeteer-cg9","title":"Handle puppeteer-extra global plugin state — dedupe + document caveat","description":"lib/puppeteer-core.module.ts:45 calls puppeteer.use(plugin) per module options. puppeteer-extra is a global singleton so plugins from different forRoot() calls bleed across browsers. Repeated module re-registration in tests stacks plugins. At minimum: dedupe (skip if already registered) and add a JSDoc warning on PuppeteerModuleOptions.plugins. Investigate per-browser scoping if puppeteer-extra exposes a non-singleton API.","status":"closed","priority":1,"issue_type":"bug","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:11:06Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T09:46:33Z","started_at":"2026-05-09T09:41:54Z","closed_at":"2026-05-09T09:46:33Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-x6e","title":"Verify and fix multi-browser shutdown closes every Browser instance","description":"lib/puppeteer-core.module.ts:103-114 onApplicationShutdown resolves 'getBrowserToken(this.options)' from its own moduleRef. With multiple PuppeteerCoreModule instances, each instance closes only its own browser. Add a multi-browser e2e spec asserting both browsers actually disconnect on app close. Fix any leak found.","notes":"Investigation: added tests/e2e/puppeteer-multi-browser.spec.ts covering both forRoot and forRootAsync with two distinct browser instances. Verified via browser.process().pid that Puppeteer spawns separate Chromium processes per instance and that browser.connected flips to false on app.close() for both. No leak found: each PuppeteerCoreModule instance receives its own scoped PUPPETEER_MODULE_OPTIONS, so getBrowserToken(this.options) in onApplicationShutdown resolves the correct per-instance browser token. Closing as verified-by-test.","status":"closed","priority":1,"issue_type":"bug","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:10:59Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T09:22:29Z","started_at":"2026-05-09T09:16:55Z","closed_at":"2026-05-09T09:22:29Z","close_reason":"Verified by new e2e spec; per-instance shutdown works correctly.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-5cn","title":"Tune up CI workflows: release.yml + pull_request.yml","description":"Both GitHub Actions workflows have drifted from current repo layout and modern CI practice.\n\nrelease.yml is broken at job-time:\n- runs npm test (no such script in package.json)\n- npm clean-install in test/ directory which does not exist\n- extra_plugins: @semantic-release/github duplicates plugin already in .releaserc\n- triggers on beta and *.x branches that .releaserc does not configure\n\npull_request.yml drifted:\n- Node 21 in matrix (EOL)\n- job named 'test' actually only does lint and audit; lint depends on test_matrix unnecessarily\n- push: branches: [renovate/**] trigger duplicates the pull_request trigger Renovate already fires\n- coverage re-runs full Chromium e2e on every PR just to upload Codecov\n\nDecisions (confirmed with user):\n- Trust merge queue; release runs build + publish only\n- Trim release branches to master + next\n- Node matrix: 20, 22, 24\n- Coverage only on merge_group\n\nPlan file: ~/.claude/plans/i-did-some-changes-mellow-hare.md","status":"closed","priority":2,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T10:39:27Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T10:40:18Z","started_at":"2026-05-09T10:39:35Z","closed_at":"2026-05-09T10:40:18Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-ro3","title":"Audit major dependency bumps flagged by ncu","description":"Several deps have major-version bumps available. Each needs review of breaking changes and CI impact before applying:\n\n- @commitlint/cli, @commitlint/config-angular: 18 → 21\n- @types/jest: 29 → 30 (paired with jest 30)\n- @types/node: ^20 → ^25\n- @types/supertest: 6 → 7 (paired with supertest 7)\n- @typescript-eslint/eslint-plugin, @typescript-eslint/parser: 6 → 8\n- eslint: 8 → 10 (flat config migration required)\n- eslint-config-prettier: 9 → 10\n- jest: 29 → 30\n- lint-staged: ^15 → ^17\n- supertest: 6 → 7\n- typescript: ^5 → ^6\n\nNOTE: puppeteer ^23 → ^24 is being handled separately and is NOT in scope for this issue.\n\nApplied safe bumps in nestjs-puppeteer-qim.","status":"open","priority":2,"issue_type":"task","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:46:04Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T10:00:21Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-qim","title":"Dependency sanity check and bumps","description":"Audit dependencies, devDependencies, and peerDependencies in package.json against the current registry. Identify outdated packages (npm outdated). For each: classify as safe-bump (patch/minor) vs major (needs review). Apply safe bumps in one commit; flag majors with a short note for the user to decide. Re-run lint, build, and e2e after bumping. Do NOT bump peerDependency ranges without confirming the public-API impact.","status":"closed","priority":2,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:11:29Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T09:46:33Z","started_at":"2026-05-09T09:43:41Z","closed_at":"2026-05-09T09:46:33Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-abp","title":"Validate forRootAsync requires one of useFactory/useClass/useExisting","description":"lib/puppeteer-core.module.ts:145-147 type-asserts (options.useClass || options.useExisting) as Type — if all three of useFactory/useClass/useExisting are missing, the inject array contains undefined and DI fails with a confusing error. Throw an explicit 'PuppeteerModule.forRootAsync requires one of useFactory, useClass, or useExisting' early.","status":"closed","priority":2,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:11:19Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T09:26:38Z","started_at":"2026-05-09T09:24:56Z","closed_at":"2026-05-09T09:26:38Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-2a4","title":"Tighten public types — drop any from forRoot and async options","description":"lib/puppeteer-core.module.ts:35 has 'forRoot(options: any = {})' — should be 'PuppeteerModuleOptions'. lib/interfaces/puppeteer-options.interface.ts:33-34 has 'useFactory?: (...args: any[])' and 'inject?: any[]' — should match @nestjs/typeorm convention using InjectionToken[] / OptionalFactoryDependency. Pure type-tightening, no runtime change.","status":"closed","priority":2,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:10:45Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T09:13:06Z","started_at":"2026-05-09T09:11:35Z","closed_at":"2026-05-09T09:13:06Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-y6o","title":"Modernize puppeteer launch-options type for v23 compatibility","description":"lib/interfaces/puppeteer-options.interface.ts uses Partial\u003cPuppeteerNodeLaunchOptions\u003e. Puppeteer v23 renamed this to LaunchOptions. Pick a type strategy that works across the peer-dep range '^21 || ^22 || ^23' without breaking consumers. Verify in a clean install against each major.","status":"closed","priority":3,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:11:25Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T10:07:47Z","started_at":"2026-05-09T10:01:10Z","closed_at":"2026-05-09T10:07:47Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-az3","title":"Detect duplicate browser name registration","description":"lib/puppeteer-core.module.ts:54,84 registers a browser provider keyed by getBrowserToken(options). Two forRoot() calls with the same 'name' silently overwrite the DI token — no warning. Throw a clear error or log a warning when a duplicate name is detected (track registered names in a module-level Set).","status":"closed","priority":3,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:11:17Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T10:07:47Z","started_at":"2026-05-09T10:01:10Z","closed_at":"2026-05-09T10:07:47Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"nestjs-puppeteer-ct4","title":"Improve onApplicationShutdown error logging (preserve stack)","description":"lib/puppeteer-core.module.ts:111-113 currently logs 'e?.message' only — drops stack and breaks for non-Error throws. Pass the full error to this.logger.error so the Nest logger can format it properly.","status":"closed","priority":3,"issue_type":"task","assignee":"Sibin Grasic","owner":"sibin.grasic@oblak.studio","created_at":"2026-05-09T09:11:08Z","created_by":"Sibin Grasic","updated_at":"2026-05-09T09:30:13Z","started_at":"2026-05-09T09:29:15Z","closed_at":"2026-05-09T09:30:13Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}

package/.beads/metadata.json

@@ -0,0 +1,7 @@
+{
+  "database": "dolt",
+  "backend": "dolt",
+  "dolt_mode": "embedded",
+  "dolt_database": "nestjs_puppeteer",
+  "project_id": "49c89952-9557-4a98-a3b1-7ad2f04c402b"
+}

package/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "command": "bd prime",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "bd prime",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ]
+  }
+}

package/AGENTS.md

@@ -0,0 +1,88 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work atomically
+bd close <id>         # Complete work
+bd dolt push          # Push beads data to remote
+```
+
+## Non-Interactive Shell Commands
+
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
+
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
+
+**Use these forms instead:**
+```bash
+# Force overwrite without prompting
+cp -f source dest           # NOT: cp source dest
+mv -f source dest           # NOT: mv source dest
+rm -f file                  # NOT: rm file
+
+# For recursive operations
+rm -rf directory            # NOT: rm -r directory
+cp -rf source dest          # NOT: cp -r source dest
+```
+
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+## Session Completion
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd dolt push
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+<!-- END BEADS INTEGRATION -->
+
+## Commit Authorship
+
+**NEVER** add `Co-Authored-By: <LLM>` (or any equivalent LLM-attribution trailer) to git commits in this repo. This applies to every commit, every branch, every PR — no exceptions, even if the harness suggests it by default. Commits are authored by the human running the session.

package/CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+## Session Completion
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd dolt push
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+<!-- END BEADS INTEGRATION -->
+
+## Commit Authorship
+
+**NEVER** add `Co-Authored-By: <LLM>` (or any equivalent LLM-attribution trailer) to git commits in this repo. This applies to every commit, every branch, every PR — no exceptions, even if the harness suggests it by default. Commits are authored by the human running the session.
+
+## Build & Test
+
+Node.js >= 20 (see `.nvmrc`). Package is published as `nestjs-puppeteer`; source lives in `lib/` and compiles to `dist/`. Peer deps span `@nestjs/common`/`@nestjs/core` `^10 || ^11` and `puppeteer` `^21 || ^22 || ^23` — public API and types must stay compatible across all of these.
+
+```bash
+npm install
+npm run build               # rm -rf dist && tsc -p tsconfig.json
+npm run watch               # incremental tsc
+npm run lint                # eslint 'lib/**/*.ts' --fix
+npm run format              # prettier --write "**/*.ts"
+npm run test:e2e            # jest --config ./tests/jest-e2e.json --runInBand
+npm run test:e2e:cov        # with coverage
+npm run test:e2e:dev        # watch mode
+
+# Run a single e2e spec
+npx jest --config ./tests/jest-e2e.json --runInBand tests/e2e/puppeteer.spec.ts
+```
+
+There are no unit tests — all tests are e2e specs in `tests/e2e/*.spec.ts` that boot a NestJS app via `@nestjs/testing` and drive it with `supertest`. They launch real Chromium, so they need a working Puppeteer install. CI runs them under AppArmor (`aa-exec --profile=chrome`) on Ubuntu — locally that prefix is not needed.
+
+The `stealth-check` test in `tests/e2e/puppeteer-with-plugin.spec.ts` hits `https://arh.antoinevastel.com/bots/areyouheadless` and requires network access.
+
+## Architecture Overview
+
+This is a thin NestJS wrapper around `puppeteer-extra` that exposes a `Browser` (and named `Page`s) through Nest's DI container. The whole library is ~6 small files in `lib/`.
+
+**Two-module pattern (mirrors `@nestjs/typeorm`, `@nestjs/mongoose`, etc.):**
+
+- `PuppeteerModule` (`lib/puppeteer.module.ts`) — public façade with three statics: `forRoot`, `forRootAsync`, `forFeature`. Holds no state; delegates to the core module.
+- `PuppeteerCoreModule` (`lib/puppeteer-core.module.ts`) — `@Global()`, owns the singleton `Browser` and the plugin registration. Implements `OnApplicationShutdown` to call `browser.close()` cleanly. The async branch (`forRootAsync`) supports `useFactory` / `useClass` / `useExisting` via `PuppeteerOptionsFactory.createPuppeteerOptions(name?)`.
+
+**DI token scheme (`lib/common/puppeteer.utils.ts`):**
+
+- Default (unnamed) browser → injected as the `Browser` class itself: `@InjectBrowser()`.
+- Named browser → string token `\`${name}Browser\``: `@InjectBrowser('foo')`.
+- Page token: `\`${browserPrefix}${page}Page\``, where `browserPrefix` is `''` for the default browser and `\`${name}_\`` otherwise. Built by `getPageToken` and consumed by `@InjectPage(page, browser?)`.
+
+This is why `forFeature(pages, browser?)` must receive the *same* browser identifier (string name or options object) used at `forRoot` — the tokens are derived from it, not looked up. Mismatched names produce DI resolution errors, not runtime warnings.
+
+**Plugin handling:** `options.plugins` is an array of `PuppeteerExtraPlugin`s. The core module calls `puppeteer.use(plugin)` for each before launching. Because `puppeteer-extra` mutates global state, plugins registered on one browser affect any subsequent `puppeteer.launch()` in the same process — keep this in mind when adding multi-browser tests.
+
+> Per README: most `puppeteer-extra` plugins are **not compatible** with Chrome's "new headless" mode. When using plugins (e.g. stealth), pass `headless: true`, not `headless: 'new'`.
+
+**Public API surface** (re-exported from `lib/index.ts`): `PuppeteerModule`, `PuppeteerCoreModule`, decorators (`InjectBrowser`, `InjectPage`), token helpers (`getBrowserToken`, `getPageToken`, `getBrowserPrefix`), constants, and the `PuppeteerModuleOptions` / `PuppeteerModuleAsyncOptions` / `PuppeteerOptionsFactory` interfaces. Treat anything exported here as a breaking-change surface.
+
+## Conventions & Patterns
+
+- **Commits:** Angular conventional commits enforced by commitlint + Husky (`.commitlintrc.json`). Allowed types: `build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test, sample`. Subject case is permissive (sentence/start/pascal/upper/lower) but a type prefix is required. Releases are fully automated by `semantic-release` on `master` and `next` — version bumps and CHANGELOG come from commit messages, so be deliberate about `feat:` vs `fix:` vs `chore:`.
+- **TypeScript:** `strict: true`, `target: ES2019`, `module: commonjs`, decorators + `emitDecoratorMetadata` on. `rootDir` is `lib/`; tests live outside it and are excluded from the build.
+- **Tests are intentionally outside `rootDir`** — they import the library via relative paths (`'../../lib'`), not via the package name. Don't add a path alias just to make this prettier; it would break `tsc` output.
+- **Non-interactive shell commands:** `cp`, `mv`, `rm` may be aliased to `-i` mode. Use `-f` (or `-rf`) so commands don't hang waiting on y/n. See `AGENTS.md` for the full list.

package/README.md

@@ -3,12 +3,14 @@
 # nestjs-puppeteer
 Puppeteer module for Nest framework (node.js)
 
-[![npm](https://img.shields.io/npm/v/nestjs-puppeteer?logo=npm)](https://npmjs/package/nestjs-puppeteer)
+[![npm](https://img.shields.io/npm/v/nestjs-puppeteer?logo=npm)](https://npmjs.com/package/nestjs-puppeteer)
+[![NestJS Peer Dep](https://img.shields.io/npm/dependency-version/nestjs-puppeteer/peer/@nestjs/core?logo=nestjs&logoColor=E42844)](https://www.npmjs.com/package/@nestjs/core)
+[![Puppeteer Peer Dep](https://img.shields.io/npm/dependency-version/nestjs-puppeteer/peer/puppeteer?logo=puppeteer&logoColor=%23fff)](https://www.npmjs.com/package/puppeteer)  
 ![npm](https://img.shields.io/npm/dm/nestjs-puppeteer)
-![GitHub](https://img.shields.io/github/license/oblakstudio/nestjs-puppeteer)
-[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)  
-![Puppeter Peer Dep](https://img.shields.io/npm/dependency-version/nestjs-puppeteer/peer/@nestjs/core?logo=nestjs&logoColor=E42844)
-![NestJS Peer Dep](https://img.shields.io/npm/dependency-version/nestjs-puppeteer/peer/puppeteer?logo=puppeteer&logoColor=%23fff)
+[![License](https://img.shields.io/github/license/oblakstudio/nestjs-puppeteer)](https://github.com/oblakstudio/nestjs-puppeteer/blob/master/LICENSE)
+![Codecov](https://img.shields.io/codecov/c/github/oblakstudio/nestjs-puppeteer?logo=codecov&color=%23F01F7A)
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+
 
 </div>
 

package/dist/interfaces/puppeteer-options.interface.d.ts

@@ -1,20 +1,35 @@
-import { ModuleMetadata, Type } from '@nestjs/common';
-import { PuppeteerNodeLaunchOptions } from 'puppeteer';
+import { InjectionToken, ModuleMetadata, OptionalFactoryDependency, Type } from '@nestjs/common';
+import { PuppeteerNode } from 'puppeteer';
 import { PuppeteerExtraPlugin } from 'puppeteer-extra';
+/**
+ * Launch options accepted by the installed puppeteer's `launch()`. Resolved
+ * structurally so the same type works across the supported peer-dep range
+ * (^21 || ^22 || ^23), where the canonical name has been renamed/deprecated
+ * (`PuppeteerLaunchOptions` → `PuppeteerNodeLaunchOptions` → `LaunchOptions`).
+ */
+type LaunchOptions = NonNullable<Parameters<PuppeteerNode['launch']>[0]>;
 export type PuppeteerModuleOptions = {
     /**
      * Browser name
      */
     name?: string;
     /**
-     * Array of puppeteer-extra plugins
+     * Array of puppeteer-extra plugins.
+     *
+     * NOTE: puppeteer-extra registers plugins on a process-global singleton, so
+     * any plugin you list here affects every subsequent `puppeteer.launch()` in
+     * the same process — including launches by other PuppeteerModule instances
+     * that did not opt into the plugin. The module dedupes by plugin name to
+     * avoid stacking on repeated module re-registration, but it cannot scope a
+     * plugin to a single browser. Most plugins (e.g. stealth) are also
+     * incompatible with Chrome's "new headless" mode; pass `headless: true`.
      */
     plugins?: PuppeteerExtraPlugin[];
     /**
      * Is the module global
      */
     isGlobal?: boolean;
-} & Partial<PuppeteerNodeLaunchOptions>;
+} & Partial<LaunchOptions>;
 export interface PuppeteerOptionsFactory {
     createPuppeteerOptions(browserName?: string): Promise<PuppeteerModuleOptions> | PuppeteerModuleOptions;
 }
@@ -24,5 +39,6 @@ export interface PuppeteerModuleAsyncOptions extends Pick<ModuleMetadata, 'impor
     useExisting?: Type<PuppeteerOptionsFactory>;
     useClass?: Type<PuppeteerOptionsFactory>;
     useFactory?: (...args: any[]) => Promise<PuppeteerModuleOptions> | PuppeteerModuleOptions;
-    inject?: any[];
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
 }
+export {};

package/dist/puppeteer-core.module.d.ts

@@ -6,7 +6,7 @@ export declare class PuppeteerCoreModule implements OnApplicationShutdown {
     private readonly moduleRef;
     private readonly logger;
     constructor(options: PuppeteerModuleOptions, moduleRef: ModuleRef);
-    static forRoot(options?: any): DynamicModule;
+    static forRoot(options?: PuppeteerModuleOptions): DynamicModule;
     static forRootAsync(options: PuppeteerModuleAsyncOptions): DynamicModule;
     onApplicationShutdown(): Promise<void>;
     private static createAsyncProviders;

package/dist/puppeteer-core.module.js

@@ -22,6 +22,53 @@ const core_1 = require("@nestjs/core");
 const puppeteer_extra_1 = __importDefault(require("puppeteer-extra"));
 const puppeteer_constants_1 = require("./puppeteer.constants");
 const common_2 = require("./common");
+const pluginRegistrationLogger = new common_1.Logger('PuppeteerModule');
+const registeredBrowserNames = new Set();
+function resolveBrowserKey(name) {
+    return name && name !== puppeteer_constants_1.DEFAULT_BROWSER_NAME ? name : puppeteer_constants_1.DEFAULT_BROWSER_NAME;
+}
+/**
+ * Reserve a browser name on the process-level registry. Two PuppeteerModule
+ * registrations sharing the same `name` (or both omitting it) would otherwise
+ * silently overwrite each other's DI token, leaving one Browser unreachable
+ * and un-shutdown. Throw immediately so the misconfiguration is loud.
+ */
+function claimBrowserName(name) {
+    const key = resolveBrowserKey(name);
+    if (registeredBrowserNames.has(key)) {
+        const label = key === puppeteer_constants_1.DEFAULT_BROWSER_NAME ? 'default (unnamed)' : `"${key}"`;
+        throw new Error(`PuppeteerModule: a browser with name ${label} is already registered. ` +
+            `Each PuppeteerModule.forRoot()/forRootAsync() call must use a unique \`name\`.`);
+    }
+    registeredBrowserNames.add(key);
+}
+function releaseBrowserName(name) {
+    registeredBrowserNames.delete(resolveBrowserKey(name));
+}
+/**
+ * Register plugins on the global puppeteer-extra singleton, skipping any whose
+ * name is already registered. puppeteer-extra holds plugin state in module
+ * scope, so naive re-registration (e.g. multiple forRoot calls in tests) would
+ * stack duplicate plugins on every subsequent launch.
+ */
+function registerPlugins(plugins) {
+    if (!(plugins === null || plugins === void 0 ? void 0 : plugins.length)) {
+        return [];
+    }
+    const registered = new Set(puppeteer_extra_1.default.pluginNames);
+    for (const plugin of plugins) {
+        const name = plugin === null || plugin === void 0 ? void 0 : plugin.name;
+        if (typeof name === 'string' && registered.has(name)) {
+            pluginRegistrationLogger.warn(`Skipping duplicate puppeteer-extra plugin "${name}" — already registered on the global instance.`);
+            continue;
+        }
+        puppeteer_extra_1.default.use(plugin);
+        if (typeof name === 'string') {
+            registered.add(name);
+        }
+    }
+    return plugins;
+}
 let PuppeteerCoreModule = PuppeteerCoreModule_1 = class PuppeteerCoreModule {
     constructor(options, moduleRef) {
         this.options = options;
@@ -29,19 +76,14 @@ let PuppeteerCoreModule = PuppeteerCoreModule_1 = class PuppeteerCoreModule {
         this.logger = new common_1.Logger('PuppeteerModule');
     }
     static forRoot(options = {}) {
+        claimBrowserName(options.name);
         const puppeteerModuleOptions = {
             provide: puppeteer_constants_1.PUPPETEER_MODULE_OPTIONS,
             useValue: options,
         };
         const pluginProvider = {
             provide: puppeteer_constants_1.PUPPETEER_BROWSER_PLUGINS,
-            useFactory: async (options) => {
-                if (options.plugins) {
-                    options.plugins.forEach((plugin) => puppeteer_extra_1.default.use(plugin));
-                    return options.plugins;
-                }
-                return [];
-            },
+            useFactory: async (options) => registerPlugins(options.plugins),
             inject: [puppeteer_constants_1.PUPPETEER_MODULE_OPTIONS],
         };
         const browserProvider = {
@@ -60,15 +102,13 @@ let PuppeteerCoreModule = PuppeteerCoreModule_1 = class PuppeteerCoreModule {
         };
     }
     static forRootAsync(options) {
+        if (!options.useFactory && !options.useClass && !options.useExisting) {
+            throw new Error('PuppeteerModule.forRootAsync requires one of useFactory, useClass, or useExisting');
+        }
+        claimBrowserName(options.name);
         const pluginProvider = {
             provide: puppeteer_constants_1.PUPPETEER_BROWSER_PLUGINS,
-            useFactory: async (options) => {
-                if (options.plugins) {
-                    options.plugins.forEach((plugin) => puppeteer_extra_1.default.use(plugin));
-                    return options.plugins;
-                }
-                return [];
-            },
+            useFactory: async (options) => registerPlugins(options.plugins),
             inject: [puppeteer_constants_1.PUPPETEER_MODULE_OPTIONS],
         };
         const browserProvider = {
@@ -96,7 +136,15 @@ let PuppeteerCoreModule = PuppeteerCoreModule_1 = class PuppeteerCoreModule {
             }
         }
         catch (e) {
-            this.logger.error(e === null || e === void 0 ? void 0 : e.message);
+            if (e instanceof Error) {
+                this.logger.error(`Failed to close browser: ${e.message}`, e.stack);
+            }
+            else {
+                this.logger.error(`Failed to close browser: ${String(e)}`);
+            }
+        }
+        finally {
+            releaseBrowserName(this.options.name);
         }
     }
     static createAsyncProviders(options) {
@@ -113,6 +161,7 @@ let PuppeteerCoreModule = PuppeteerCoreModule_1 = class PuppeteerCoreModule {
         ];
     }
     static createAsyncOptionsProvider(options) {
+        var _a;
         if (options.useFactory) {
             return {
                 provide: puppeteer_constants_1.PUPPETEER_MODULE_OPTIONS,
@@ -120,10 +169,8 @@ let PuppeteerCoreModule = PuppeteerCoreModule_1 = class PuppeteerCoreModule {
                 inject: options.inject || [],
             };
         }
-        const inject = [
-            (options.useClass ||
-                options.useExisting),
-        ];
+        const factory = ((_a = options.useClass) !== null && _a !== void 0 ? _a : options.useExisting);
+        const inject = [factory];
         return {
             provide: puppeteer_constants_1.PUPPETEER_MODULE_OPTIONS,
             useFactory: async (optionsFactory) => await optionsFactory.createPuppeteerOptions(options.name),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nestjs-puppeteer",
   "description": "Puppeteer module for NestJS",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "license": "MIT",
   "author": {
     "name": "Sibin Grasic",
@@ -25,30 +25,30 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {
-    "@commitlint/cli": "18.6.0",
-    "@commitlint/config-angular": "18.6.0",
+    "@commitlint/cli": "18.6.1",
+    "@commitlint/config-angular": "18.6.1",
     "@nestjs/common": "^11",
     "@nestjs/core": "^11",
     "@nestjs/platform-express": "^11",
     "@nestjs/testing": "^11",
-    "@types/jest": "29.5.11",
+    "@types/jest": "29.5.14",
     "@types/node": "^20",
-    "@types/supertest": "6.0.2",
-    "@typescript-eslint/eslint-plugin": "6.20.0",
-    "@typescript-eslint/parser": "6.20.0",
-    "eslint": "8.56.0",
-    "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-import": "2.29.1",
-    "husky": "^9.0.7",
+    "@types/supertest": "6.0.3",
+    "@typescript-eslint/eslint-plugin": "6.21.0",
+    "@typescript-eslint/parser": "6.21.0",
+    "eslint": "8.57.1",
+    "eslint-config-prettier": "9.1.2",
+    "eslint-plugin-import": "2.32.0",
+    "husky": "^9.1.7",
     "jest": "29.7.0",
-    "lint-staged": "^15.2.1",
+    "lint-staged": "^15.5.2",
     "puppeteer": "^23",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "reflect-metadata": "^0.2",
-    "rxjs": "^7.8.1",
+    "rxjs": "^7.8.2",
     "supertest": "6.3.4",
-    "ts-jest": "29.1.2",
+    "ts-jest": "29.4.9",
     "typescript": "^5"
   },
   "peerDependencies": {