chore: import upstream snapshot with attribution

.github/workflows/build-extension.yml

@@ -0,0 +1,66 @@
+name: Build Chrome Extension
+
+on:
+  push:
+    branches: [ "main" ]
+    tags: [ "ext-v*" ]
+    paths:
+      - 'extension/**'
+      - '.github/workflows/build-extension.yml'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'extension/**'
+      - '.github/workflows/build-extension.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'npm'
+          cache-dependency-path: extension/package-lock.json
+
+      - name: Install extension dependencies
+        run: npm ci
+        working-directory: extension
+
+      - name: Build extension
+        run: npm run build
+        working-directory: extension
+
+      - name: Prepare extension package
+        run: npm run package:release -- --out ../extension-package
+        working-directory: extension
+
+      - name: Create Extension ZIP
+        run: |
+          EXT_VERSION=$(node -p "require('./extension/package.json').version")
+          cd extension-package
+          zip -r ../opencli-extension-v${EXT_VERSION}.zip .
+
+      - name: Upload Artifacts (Action Run)
+        uses: actions/upload-artifact@v7
+        with:
+          name: opencli-extension-build
+          path: opencli-extension-v*.zip
+          retention-days: 7
+
+      - name: Attach to GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v3.0.0
+        with:
+          files: opencli-extension-v*.zip
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -0,0 +1,173 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: '0 8 * * 1'  # Weekly Monday 08:00 UTC — smoke tests
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Fast gate: typecheck + build ──
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Build
+        run: npm run build
+
+      # Guard: committed cli-manifest.json must match the one build regenerates.
+      # Prevents silent drift where unrelated adapter entries vanish or change
+      # across PRs (agent hits unexpected manifest diff → surgical-merge churn).
+      - name: Check cli-manifest.json is up-to-date
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          if ! git diff --exit-code -- cli-manifest.json; then
+            echo "::error::cli-manifest.json is out of sync with the source. Run 'npm run build' and commit the result."
+            exit 1
+          fi
+
+      # Guard: adapter rows must not silently emit keys omitted from `columns`.
+      # Existing findings are tracked in scripts/silent-column-drop-baseline.json;
+      # this gate rejects newly introduced drops while allowing incremental cleanup.
+      - name: Check silent column drops
+        if: runner.os == 'Linux'
+        run: npm run check:silent-column-drop
+
+      # Guard: adapters should fail with typed errors instead of silently
+      # returning empty arrays, clamping user input, or inventing sentinel data.
+      # Existing findings are tracked in scripts/typed-error-lint-baseline.json.
+      - name: Check typed-error lint baseline
+        if: runner.os == 'Linux'
+        run: npm run check:typed-error-lint
+
+  # ── Unit tests (vitest shard) ──
+  # PR: ubuntu + Node 22 only (fast feedback, 2 jobs).
+  # Push to main/dev: full matrix for cross-platform/cross-version coverage (12 jobs).
+  unit-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && fromJSON('["ubuntu-latest","macos-latest","windows-latest"]') || fromJSON('["ubuntu-latest"]') }}
+        node-version: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && fromJSON('["22"]') || fromJSON('["22"]') }}
+        shard: [1, 2]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests (Node ${{ matrix.node-version }}, shard ${{ matrix.shard }}/2)
+        run: npx vitest run --project unit --project extension --reporter=verbose --shard=${{ matrix.shard }}/2
+
+  # ── Bun compatibility check ──
+  bun-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests under Bun
+        run: bun vitest run --project unit --reporter=verbose
+
+  # Adapter tests are pure unit tests — OS doesn't affect results. Gated off
+  # `pull_request` to keep PR CI under ~2 minutes; adapter authors run focused
+  # tests locally before pushing, and `push` to main / nightly cron / manual
+  # dispatch still guard the merged state.
+  adapter-test:
+    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run focused adapter tests
+        run: npm run test:adapter -- --reporter=verbose
+
+  # ── Smoke tests (scheduled / manual only) ──
+  smoke-test:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # NOTE: Windows excluded — browser-actions/setup-chrome hangs during
+        # Chrome MSI installation on Windows runners (known issue).
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Chrome
+        uses: ./.github/actions/setup-chrome
+        id: setup-chrome
+
+      - name: Build
+        run: npm run build
+
+      - name: Run smoke tests (Linux, via xvfb)
+        if: runner.os == 'Linux'
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run tests/smoke/ --reporter=verbose
+
+      - name: Run smoke tests (macOS / Windows)
+        if: runner.os != 'Linux'
+        run: npx vitest run tests/smoke/ --reporter=verbose
+    timeout-minutes: 15

.github/workflows/doc-check.yml

@@ -0,0 +1,36 @@
+name: Doc Check
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+concurrency:
+  group: doc-check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Adapter doc coverage ──
+  doc-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check adapter doc coverage
+        run: bash scripts/check-doc-coverage.sh --strict
+
+  # ── VitePress build validation ──
+  docs-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs (catches broken links & sidebar refs)
+        run: npm run docs:build

.github/workflows/docs.yml

@@ -0,0 +1,17 @@
+name: Trigger Website Rebuild (Docs Updated)
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**']
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger opencli-website rebuild
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.WEBSITE_DEPLOY_TOKEN }}
+          repository: jackwener/opencli-website
+          event-type: docs-updated

.github/workflows/e2e-headed.yml

@@ -0,0 +1,109 @@
+name: E2E Headed Chrome
+
+on:
+  # E2E removed from `pull_request` to keep PR feedback under ~2 minutes; PR-time
+  # protection is the CI workflow (typecheck / unit / lint / adapter / build).
+  # E2E still guards `main` directly, runs nightly, and on release tag push so
+  # protocol/CDP/extension contract regressions are caught before they ship.
+  push:
+    branches: [main, dev]
+    paths:
+      - 'extension/**'
+      - 'src/browser/**'
+      - 'src/daemon.ts'
+      - 'src/execution.ts'
+      - 'src/interceptor.ts'
+      - 'tests/e2e/**'
+      - 'tests/smoke/**'
+      - '.github/actions/setup-chrome/**'
+      - '.github/workflows/e2e-headed.yml'
+    tags: ['v*']
+  schedule:
+    # Daily 08:00 UTC — catch flake / Chrome-version drift even when no commits
+    # touched the watched paths recently.
+    - cron: '0 8 * * *'
+  workflow_dispatch:
+
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e-headed:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Gate placement by what each runner can run deterministically:
+        # - the real-browser extension smoke needs a Chrome that reliably runs
+        #   an MV3 extension, which only Linux+xvfb provides on hosted runners
+        #   (headed macOS crashes on Mach port rendezvous outside an Aqua
+        #   session; headless does not connect the extension SW there);
+        # - the daemon transport contracts need no browser and run blocking on
+        #   every OS, so macOS/Windows get a real gate, not a skipped one.
+        # macOS pinned to 15 while the macOS 26 image stabilizes.
+        os: [ubuntu-latest, macos-15, windows-latest]
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Linux runs the extension smoke and macOS runs the full real-site e2e
+      # suite; both need a real Chrome. Windows runs only the browser-free
+      # transport gate, and the setup-chrome action hangs on Windows anyway.
+      - name: Setup Chrome
+        if: runner.os != 'Windows'
+        uses: ./.github/actions/setup-chrome
+        id: setup-chrome
+
+      - name: Build
+        run: npm run build
+
+      - name: Build extension
+        run: npm run build --prefix extension
+
+      # Real-browser extension smoke: Linux under xvfb is the one hosted
+      # environment where a real Chrome reliably starts an MV3 extension, so
+      # this is the release-blocking browser gate. Headed (not headless):
+      # headless does not connect the extension service worker on hosted
+      # runners. See the matrix comment for why macOS/Windows don't run it.
+      - name: Run AX Chrome smoke (Linux, real extension via xvfb)
+        if: runner.os == 'Linux'
+        env:
+          CHROME_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+          OPENCLI_AX_E2E: '1'
+          OPENCLI_E2E_HEADED: '1'
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run --project e2e tests/e2e/browser-ax-chrome.test.ts --reporter=verbose
+
+      # Transport contract E2E: real daemon process + scripted fake extension.
+      # Pins the cross-layer contracts (waiter attach, deadline 408, dispatched
+      # disconnect, profile fallback, graceful shutdown) end to end with the
+      # actual daemon binary — no browser required, so this is the blocking
+      # gate on EVERY OS, including macOS and Windows.
+      - name: Run daemon transport contract E2E
+        run: npx vitest run --project e2e-fixed-port tests/e2e/daemon-transport.test.ts --reporter=verbose
+
+      - name: Run E2E tests (Linux, via xvfb)
+        if: runner.os == 'Linux'
+        env:
+          OPENCLI_AX_E2E: '0'
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run tests/e2e/ --reporter=verbose
+
+      # Real-site adapter e2e stays on Linux/macOS; Windows runs the two
+      # deterministic gates above (unit coverage in ci.yml already spans it).
+      - name: Run E2E tests (macOS)
+        if: runner.os == 'macOS'
+        env:
+          OPENCLI_AX_E2E: '0'
+        run: npx vitest run tests/e2e/ --reporter=verbose

.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      # Build before the manifest drift gate: adapter modules import
+      # @jackwener/opencli/* through package exports, which resolve to dist/.
+      # A fresh release checkout has no dist/ until the full build runs.
+      - name: Build package and verify cli-manifest.json is up-to-date
+        run: |
+          npm run build
+          if ! git diff --exit-code -- cli-manifest.json; then
+            echo "::error::cli-manifest.json drift detected at release time. Run 'npm run build' locally and commit the result before tagging."
+            exit 1
+          fi
+
+      - name: Install extension dependencies
+        run: npm ci
+        working-directory: extension
+
+      - name: Build extension
+        run: npm run build
+        working-directory: extension
+
+      - name: Package extension
+        run: npm run package:release -- --out ../extension-package
+        working-directory: extension
+
+      - name: Create extension ZIP
+        run: |
+          EXT_VERSION=$(jq -r .version extension/package.json)
+          cd extension-package
+          zip -r ../opencli-extension-v${EXT_VERSION}.zip .
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3.0.0
+        with:
+          generate_release_notes: true
+          files: |
+            opencli-extension-v*.zip
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Trigger website rebuild
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.WEBSITE_DEPLOY_TOKEN }}
+          repository: jackwener/opencli-website
+          event-type: version-released

.github/workflows/security.yml

@@ -0,0 +1,33 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: '0 9 * * 1'  # Weekly Monday 09:00 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: npm audit (production)
+        run: npm audit --omit=dev --audit-level=high