feat: Zemu v0.50.0 - Container Pooling and Enhanced Error Handling (#552)

* feat: modernize Zemu codebase to Zondax standards (#547)

* modernize

* refactor: migrate to biome and standardize code style across project

* chore: update biome lint command and add fix script alias

* style: standardize quotes to single quotes and fix formatting

* refactor: replace forEach loops with for...of and remove unnecessary async keywords

* refactor: replace forEach loops with for...of and remove unnecessary async declarations

* ci: update workflow commands and disable coverage in ci-ts pipeline

* temporarily disable docker

* Modernize codebase (#548)

* activate testing in ci

* ci: remove frozen lockfile in CI workflow

* feat: implement container pooling and fix transport error handling (#551)

* feat: implement container pooling system for device emulation

* fix: address CodeRabbit review comments

- Fix YAML linting issues in GitHub workflow files
  - Remove trailing spaces in ci-ts.yaml
  - Add missing newlines at end of YAML files
- Fix typo: settingsNavnavLeftButton → settingsNavLeftButton
- Organize imports in containerPool.ts (external packages first)
- Remove unused model variable in cleanup() method
- Apply automated code formatting improvements

* fix: address additional CodeRabbit review comments

- Fix missing parentheses in tests/minapp/index.ts toString() call
- Add error handling to gRPC exchange promise chain
- Remove async modifier from globalsetup.ts (no await needed)
- Add race condition protection for pool initialization
- Document DEV_CERT_PRIVATE_KEY as development-only test key

* fix: resolve remaining CI issues and CodeRabbit comments

- Fix trailing spaces in .github/dependabot.yml
- Add missing await to async operations in tests/pullImageKillOld.ts
- Wrap async calls in IIFE to prevent CI hanging on cleanup

This should resolve the hanging CI build and address the remaining
CodeRabbit linting issues.

* fix: handle transport errors to fail fast instead of timing out

- Add error tracking in transport layer via proxy interceptor
- Create errors.ts with APDU status codes and error handling utilities
- Propagate critical transport errors in waitUntilScreenIs, waitUntilScreenIsNot, and waitForText
- Update getEvents to check for critical transport errors before making requests
- Add comprehensive tests to verify fast-fail behavior

Previously, when errors like 0x6984 (INVALID_DATA) or 0x6E00 (CLA_NOT_SUPPORTED) occurred,
Zemu would continue waiting for timeouts instead of failing immediately. Now these errors
are detected and cause immediate failure with clear error messages.

Fixes issue where transport errors were absorbed causing unnecessary timeout delays.

* fix: update error handling test to expect correct error code

The test was expecting 0x6984 (INVALID_DATA) but invalid CLA (0xFF) actually
triggers 0x6E00 (CLA_NOT_SUPPORTED) which is the correct behavior.

* fix: resolve linter issues

- Remove unused imports in test files
- Fix import organization in Zemu.ts
- Fix formatting (newlines at end of files)
- Apply Biome linter rules

All tests passing after linter fixes.

* feat: increase default container pool size to 2 for all devices

Changed default pool configuration from 1 to 2 containers per device type
(except nanos which was already 2). This provides better parallelism for
test suites that run multiple tests concurrently.

* fix: add explicit permissions to GitHub workflows

Address security warnings by adding explicit GITHUB_TOKEN permissions:
- ci-ts.yaml: contents: read (minimal permissions for CI)
- publish.yml: contents: read, packages: write (for npm publishing)

This follows GitHub security best practices to limit token permissions.

* fix: address CodeRabbit review comments

- Add missing newline at EOF in .github/workflows/publish.yml
- Replace console.log with proper error handling in buttons.ts
- Improve error handling in Zemu.ts close method with try-catch-finally
- Add setScrambleKey support to transport proxy for comprehensive error tracking
- Remove debugging console.log statements from tests
- Remove skipped test that was only for exploration
- Replace console.warn with process.stderr.write for cleaner logging

* test: align metadata and comments to CLA_NOT_SUPPORTED (0x6E00)

- Update test title to reference 0x6E00 (CLA_NOT_SUPPORTED) instead of 0x6984
- Update comment before transport.send to reference CLA_NOT_SUPPORTED
- Update comment on thrown error to reference CLA_NOT_SUPPORTED

This aligns test documentation with the actual error code (0x6E00) that
the test assertion validates, removing confusion about which error is
being tested.

* fix: correct property name from containerPooling to disablePool in tests

- Update tests/error-handling-simple.test.ts to use disablePool: true
- Update tests/error-handling.test.ts to use disablePool: true
- Update tests/error-handling-fixed.test.ts to use disablePool: true

The property name now matches the IStartOptions interface definition
which defines disablePool?: boolean, not containerPooling.

* fix: resolve ButtonKind errors for non-touch devices

- Create dummyButton constant to avoid calling getTouchElement for nanos/nanox/nanosp
- Add device type checks before calling getTouchElement in Zemu.ts navigation
- Fix TouchNavigation usage to check isTouchDevice before instantiation
- Non-touch devices now use ActionKind.RightClick with dummy button for navigation
- Remove hardcoded getTouchElement call in scheduleToNavElement function

This resolves 'Unsupported ButtonKind: nanos, 1' and 'Unsupported ButtonKind: nanos, 2' errors
when using ButtonKind.QuitAppButton and ButtonKind.SwipeContinueButton with Nano devices.

* feat: implement automatic container cleanup to prevent port conflicts

- Add cleanupStaleContainers() method to ContainerPool that runs before initialization
- Use Docker API to find and remove stale zemu containers automatically
- Enhanced global test setup with comprehensive process exit handlers
- Added handlers for SIGINT, SIGTERM, beforeExit, uncaughtException, and unhandledRejection
- Prevents port allocation conflicts by cleaning up leftover containers from previous runs
- No more manual container cleanup required - the library manages this automatically

This resolves port conflicts like 'Bind for 0.0.0.0:15000 failed: port is already allocated'
that occurred when containers weren't properly cleaned up from interrupted test runs.

* fix: add explicit support for prerelease tags while maintaining security

- Keep secure numeric-only patterns (rejecting unsafe CodeRabbit suggestion v*.*.*)
- Add explicit patterns for common prerelease formats:
  - v1.2.3-rc1, v1.2.3-rc2 (release candidates)
  - v1.2.3-beta.1, v1.2.3-beta.2 (beta releases)
  - v1.2.3-alpha.1, v1.2.3-alpha.2 (alpha releases)
- Maintain backwards compatibility with existing patterns
- General v[0-9]+.[0-9]+.[0-9]+-* pattern still covers other formats

This ensures -rc1 support while preventing dangerous patterns like v*.*.*
that could match malicious strings like vMALICIOUS.CODE.INJECTION-hack.

* refactor: simplify tag patterns with clear comments

- Use concise patterns with descriptive comments
- Main releases: v1, v1.2, v1.2.3
- Prereleases: v1.2.3-rc1, v1.2.3-beta.1, etc.
- Remove redundant explicit patterns - general v[0-9]+.[0-9]+.[0-9]+-* covers all prerelease formats
- Maintain security by requiring numeric versions only

* fix: improve error handling and code formatting in container pool initialization

* adjust github token permission settings

* feat: add comprehensive APDU error codes to errors module

- Add BUSY (0x9001) for device busy state
- Add EXECUTION_ERROR (0x6400) for execution failures
- Add EMPTY_BUFFER (0x6982) for empty buffer conditions
- Add OUTPUT_BUFFER_TOO_SMALL (0x6983) for buffer size issues
- Add TX_NOT_INITIALIZED (0x6987) for uninitialized transactions
- Add BAD_KEY_HANDLE (0x6A80) for invalid key handles
- Add SIGN_VERIFY_ERROR (0x6F01) for signature verification failures
- Update critical transport errors list with new error codes
- Add human-readable messages for all new error codes

* refactor: consolidate duplicate dummyButton definitions into single export

- Export dummyButton from buttons.ts module
- Remove duplicate definitions from Zemu.ts and actions.ts
- Update imports to use the shared dummyButton export
- Reduces code duplication and improves maintainability

* fix: update GitHub workflow permissions for npm publishing

- Change permissions from packages:write to id-token:write
- Required for npm provenance and OIDC authentication
- Addresses security recommendation from PR review

* docs: update README with latest features and improvements

- Update CI badge to point to new workflow (ci-ts.yaml)
- Add support for Stax and Flex devices in overview
- Update features list with container pooling and TypeScript support
- Add Vitest to supported test frameworks
- Include installation instructions with pnpm support
- Add quick start code example
- Highlight enhanced error handling capabilities

Author: jleni

.eslintrc.json

@@ -1,25 +1,25 @@
-# Basic dependabot.yml file with
-# minimum configuration for two package managers
-
 version: 2
 updates:
-  # Enable version updates for npm
   - package-ecosystem: "npm"
-    # Look for `package.json` and `lock` files in the `root` directory
     directory: "/"
-    # Check the npm registry for updates every day (weekdays)
     schedule:
       interval: "daily"
-    target-branch: dev
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 5
+    target-branch: "main"
+    groups:
+      all:
+        patterns: ["*"]
+    ignore:
+      # Ignore major version updates for stability
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
 
-  # Enable version updates for GitHub Actions
-  - package-ecosystem: 'github-actions'
-    directory: '/'
+  - package-ecosystem: "github-actions"
+    directory: "/"
     schedule:
-      interval: 'daily'
-      time: '11:00'
+      interval: "daily"
     commit-message:
-      prefix: 'chore'
-      prefix-development: 'chore'
-      include: 'scope'
-    target-branch: dev
+      prefix: "ci"
+    target-branch: "main"

.github/dependabot.yml

@@ -0,0 +1,51 @@
+name: CI-ts
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: "0 0 * * *" # Daily at midnight UTC
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.head.ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  ts-checks:
+    uses: zondax/_workflows/.github/workflows/_checks-ts.yaml@main
+    with:
+      package_manager: pnpm
+      node_version: "22"
+      enable_tests: false  # Disable tests here since they need Docker
+      enable_coverage: false
+      test_command: "test"
+      lint_command: "check"
+      format_command: "check"
+
+  test-with-docker:
+    runs-on: ubuntu-latest
+    needs: ts-checks
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 8
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - name: Install dependencies
+        run: pnpm install
+      - name: Run tests with Docker
+        run: pnpm test
+        env:
+          DISPLAY: :99

.github/workflows/ci-ts.yaml

@@ -1,55 +1,31 @@
-name: Publish package
+name: Publish NPM Package
 
 on:
   release:
-    types:
-      - created
+    types: [created]
+  push:
     tags:
-      - "v[0-9]+(\\.[0-9]+)*"
+      # Main release versions: v1, v1.2, v1.2.3
+      - "v[0-9]+"
+      - "v[0-9]+.[0-9]+"  
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      # Prerelease versions: v1.2.3-rc1, v1.2.3-beta.1, etc.
+      - "v[0-9]+.[0-9]+.[0-9]+-*"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write  # Required for npm provenance/OIDC
 
 jobs:
-  build-test:
-    name: Build and Test
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-      - name: Install node
-        uses: actions/setup-node@v4
-      - run: npm install -g yarn
-      - run: yarn install
-      - run: yarn build
-      - run: yarn test
+  publish-npm:
+    uses: zondax/_workflows/.github/workflows/_publish-npm.yaml@main
+    with:
+      timeout_minutes: 10
+      dry_run: false
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN_PUBLISH_AUTO }}
 
-  publish:
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    needs: [build-test]
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-      - name: Install node
-        uses: actions/setup-node@v4
-        with:
-          registry-url: "https://registry.npmjs.org"
-          scope: "@zondax"
-      - run: npm install -g yarn
-      - run: yarn install
-      - run: yarn build
-      - run: mv README-npm README.md
-      - name: Get latest release version number
-        id: get_version
-        run: echo "version=${GITHUB_REF##*/}" >> $GITHUB_OUTPUT
-      - name: Show version
-        run: echo ${{ steps.get_version.outputs.version }}
-      - name: Update tag
-        run: npm --no-git-tag-version version ${{ steps.get_version.outputs.version }}
-      - name: Publish package
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN_PUBLISH_AUTO }}

.github/workflows/main.yml

@@ -173,3 +173,5 @@ dist
 
 # Finder (MacOS) folder config
 .DS_Store
+tests/snapshots-tmp/
+

.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+[tools]
+node = "22"
+pnpm = "latest"
+
+[env]
+# Ensure pnpm uses the correct Node.js version
+NODE_ENV = "development"
+
+[tasks.install]
+description = "Install dependencies"
+run = "pnpm install"
+
+[tasks.build]
+description = "Build the project"
+run = "pnpm build"
+
+[tasks.test]
+description = "Run tests"
+run = "pnpm test"
+
+[tasks.check]
+description = "Run linting and formatting checks"
+run = "pnpm check"
+
+[tasks.dev]
+description = "Development setup"
+run = [
+  "pnpm install",
+  "pnpm check",
+  "pnpm build"
+]

.gitignore

@@ -0,0 +1 @@
+22