docs(web-demo): add consumer config matrix for retail and UI

.github/workflows/ci.yml

@@ -127,7 +127,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        check: ['lint', 'format', 'commit-lint', 'dependencies']
+        check: ['lint', 'format', 'commit-lint', 'dependencies', 'scripts']
 
     steps:
       - uses: socketdev/action@v1
@@ -174,6 +174,10 @@ jobs:
         if: matrix.check == 'dependencies'
         run: yarn run check-deps
 
+      - name: Test Root Scripts
+        if: matrix.check == 'scripts'
+        run: yarn run test:scripts
+
       # We conciously do not audit dependencies as a PR step since errors are typically
       # unrelated to the PR changes. This check is performed in `publish.yml`.
 

CLAUDE.md

@@ -75,6 +75,8 @@ For modules that need browser support (especially those using `@bitgo/wasm-utxo`
 ### Commits
 BitGoJS uses conventional commits. All commits MUST pass the spec described in `commitlint.config.js`.
 
+Every commit needs a footer issue reference (`references-empty: never`). Web Experience side work without a Linear ticket may use `WEB-000` in the footer (junk-drawer reference, same pattern as `BTC-000` / `CSHLD-000`). Branches named `WEB-000-*` get `TICKET: WEB-000` appended automatically by `scripts/prepare-commit-msg.js`.
+
 ### TypeScript Guidelines
 - **Avoid `any` type**: Use specific types, interfaces, or union types instead of `any`. If absolutely necessary, prefer `unknown` and use type guards for safety.
 

commitlint.config.js

@@ -74,6 +74,7 @@ module.exports = {
         'WAL-',
         'WCN-',
         'WCI-',
+        'WEB-',
         'COIN-',
         'COINS-',
         'COINFLP-',

modules/web-demo/README.md

@@ -1,13 +1,63 @@
 # web-demo
 
-This module serves as an example on how you can integrate the BitGo SDK into your own UI.
+Reference UI for integrating the BitGo SDK in the browser. Routes mirror problems solved in production apps (**bitgo-retail**, **bitgo-ui**) using SDK packages directly — no private `@bitgo-private/*` dependencies.
 
-## Usage
+## Quick start
 
-In order to start the server, run the following command after having already run `yarn install` in the root of the repo.
+From the BitGoJS repo root (after `yarn install`):
 
-```
+```bash
+cd modules/web-demo
 yarn dev
 ```
 
-This will spin up a server serving the UI at [localhost:8080](localhost:8080).
+Opens [localhost:8080](http://localhost:8080).
+
+## Consumer config matrix
+
+Production apps bundle the SDK differently. web-demo will support **consumer profiles** (via `CONSUMER_PROFILE` env) so each profile documents one real-world setup. Profiles are added incrementally; only `classic-webpack` is active today.
+
+| Profile | Status | Mirrors | Bundler | WASM | SDK auth |
+| --- | --- | --- | --- | --- | --- |
+| `classic-webpack` | **active** (default) | bitgo-ui classic app, default web-demo | Webpack + [`webpack/bitgojs.config.js`](../../webpack/bitgojs.config.js) | Partial ESM aliases in shared config | Access token or `/webcrypto-auth` |
+| `retail-browser` | planned | bitgo-retail web (`MOBILE_MODE` off) | Webpack profile | Full `@bitgo/wasm-*` ESM paths, DKLS/cardano browser swaps | `WebCryptoHmacStrategy` + `requestIdPrefix` |
+| `retail-mobile-stub` | planned | bitgo-retail mobile webview | Webpack profile | Empty WASM shims (no heavy signing WASM) | Bridge / token (documented only) |
+| `direct-sdk` | planned | bitgo-retail mock server, `examples/ts` | Either | Per profile | `BitGoAPI` + `customRootURI`, no Express |
+| `express-proxy` | planned | Self-hosted Express users | Either | Per profile | Local Express signing proxy |
+
+**Planned usage** (not wired yet):
+
+```bash
+yarn dev                                          # classic-webpack
+CONSUMER_PROFILE=retail-browser yarn dev          # future
+CONSUMER_PROFILE=retail-mobile-stub yarn dev      # future
+```
+
+### What each production app solved
+
+| Problem | bitgo-retail | bitgo-ui | web-demo route |
+| --- | --- | --- | --- |
+| Browser WASM loading | Vite ESM aliases for `@bitgo/wasm-utxo`, `wasm-ton`, `wasm-mps` | Webpack aliases (similar) | `/wasm-miniscript` |
+| HMAC without raw token in storage | `WebCryptoHmacStrategy` + IndexedDB | Classic token flow | `/webcrypto-auth` |
+| Passkey PRF wallet flows | `@bitgo-private/web-client` (retail); SDK: `@bitgo/passkey-crypto` | Partial | `/passkey-demo` |
+| Keycard generation | `@bitgo/key-card` in wallet create / migration | Keycard flows | `/keycard` |
+| Lazy coin registration | `retail-sdk-client/coinFactory` | `~/utils/coinFactory` | `/coins` |
+| Token enable prebuild | React Query + `PrebuildTransactionResult` | `useBuildTokenEnablementMutation` | planned `/token-enable` |
+
+## Demo routes
+
+| Path | Description |
+| --- | --- |
+| `/` | Home |
+| `/bitgo-js` | BitGo SDK object inspect |
+| `/bitgo-api` | BitGoAPI usage |
+| `/coins` | Coin factory / registration |
+| `/keycard` | Keycard download fixtures |
+| `/wasm-miniscript` | WASM miniscript smoke |
+| `/ecdsachallenge` | ECDSA challenge generation |
+| `/webcrypto-auth` | WebCrypto HMAC strategy + IndexedDB session |
+| `/passkey-demo` | Passkey register / attach / wallet (uses `@bitgo/passkey-crypto`) |
+
+## Contributing
+
+Owned by **@BitGo/web-experience** (`CODEOWNERS`). Prefer small PRs: one profile, one route, or one README section at a time. See the local BitGoJS side-improvements plan for micro-PR sizing.

package.json

@@ -278,7 +278,8 @@
     "precommit": "lint-staged",
     "lint-fix": "lerna run lint --parallel -- --fix",
     "prepare-commit-msg": "node ./scripts/prepare-commit-msg.js",
-    "test:prepare-release": "mocha --require tsx ./scripts/tests/prepareRelease/prepare-release-main.test.ts"
+    "test:prepare-release": "mocha --require tsx ./scripts/tests/prepareRelease/prepare-release-main.test.ts",
+    "test:scripts": "mocha './scripts/tests/**/*.test.js'"
   },
   "dependencies": {
     "axios": "1.16.1",

scripts/prepare-commit-msg.js

@@ -5,28 +5,58 @@ const childProcess = require('child_process');
 const fs = require('fs');
 const exec = promisify(childProcess.exec);
 
-// ex WP-1234
-const branchRegex = /([A-Z]+-)(\d+)/;
+// Build regex from commitlint's known issuePrefixes so arbitrary branch segments
+// (e.g. "release-2-hotfix") don't produce bogus TICKET footers.
+let issuePrefixes;
+try {
+  issuePrefixes = require('../commitlint.config.js').parserPreset.parserOpts.issuePrefixes;
+} catch (_) {
+  issuePrefixes = [];
+}
+const escapedPrefixes = issuePrefixes
+  .filter((p) => p !== '#')
+  .map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+// Anchored at branch start; case-insensitive so "web-000-desc" matches "WEB-"
+// null when no prefixes are configured — avoids ^()(\d+) matching bare-digit branches.
+const branchRegex =
+  escapedPrefixes.length > 0 ? new RegExp(`^(${escapedPrefixes.join('|')})(\\d+)`, 'i') : null;
 // ex TICKET: WP-1234
 const commitRegex = /(ticket|issue):\s(\S+)/gim;
 
+function extractTicket(branch) {
+  if (!branchRegex) return null;
+  const found = branch.match(branchRegex);
+  return found ? found[0].toUpperCase() : null;
+}
+
+// Given the existing commit message and a ticket, return the message with a
+// TICKET footer appended, or null when no change is needed (no ticket, or the
+// message already contains a ticket/issue footer). Pure so it is unit-testable.
+function appendTicketFooter(data, ticket) {
+  if (!ticket) {
+    return null;
+  }
+  // Reset lastIndex: commitRegex is global, so .test() is stateful across calls.
+  commitRegex.lastIndex = 0;
+  if (commitRegex.test(data)) {
+    return null;
+  }
+  return `${data}\nTICKET: ${ticket}\n`;
+}
+
 async function main() {
   const commitMsgFilepath = process.argv[2];
   try {
     const branch = (await exec(`git branch --show-current`)).stdout.trim();
-    const found = branch.match(branchRegex);
-    // Do not append message if branch name does not match regex
-    if (!found.length) {
-      return;
-    }
-    const ticket = found[0];
+    const ticket = extractTicket(branch);
     const data = fs.readFileSync(commitMsgFilepath, 'utf8');
-    // Exit if ticket is already in commit footer
-    if (data.match(commitRegex)) {
+    const updated = appendTicketFooter(data, ticket);
+    if (updated === null) {
       return;
     }
-    fs.writeFileSync(commitMsgFilepath, `${data}\nTICKET: ${ticket}\n`);
+    fs.writeFileSync(commitMsgFilepath, updated);
   } catch (e) {}
 }
 
-main();
+module.exports = { extractTicket, appendTicketFooter };
+if (require.main === module) main();

scripts/tests/prepare-commit-msg.test.js

@@ -0,0 +1,58 @@
+const assert = require('assert');
+const { extractTicket, appendTicketFooter } = require('../prepare-commit-msg');
+
+describe('extractTicket', () => {
+  it('extracts uppercase ticket from uppercase branch', () => {
+    assert.strictEqual(extractTicket('WEB-000-my-feature'), 'WEB-000');
+  });
+
+  it('extracts and uppercases ticket from lowercase branch', () => {
+    assert.strictEqual(extractTicket('web-000-my-feature'), 'WEB-000');
+  });
+
+  it('extracts WP ticket', () => {
+    assert.strictEqual(extractTicket('WP-1234-some-work'), 'WP-1234');
+  });
+
+  it('returns null for branches without a known prefix', () => {
+    assert.strictEqual(extractTicket('release-2-hotfix'), null);
+    assert.strictEqual(extractTicket('main'), null);
+    assert.strictEqual(extractTicket('feature-no-ticket'), null);
+  });
+
+  it('is anchored at branch start (ignores prefixes mid-name)', () => {
+    assert.strictEqual(extractTicket('feature/WEB-000-x'), null);
+  });
+
+  it('returns null for prefix without digits (WEB-foo)', () => {
+    assert.strictEqual(extractTicket('WEB-foo'), null);
+  });
+
+  it('returns null for empty branch', () => {
+    assert.strictEqual(extractTicket(''), null);
+  });
+});
+
+describe('appendTicketFooter', () => {
+  it('appends a TICKET footer when none is present', () => {
+    assert.strictEqual(appendTicketFooter('feat: add thing', 'WEB-000'), 'feat: add thing\nTICKET: WEB-000\n');
+  });
+
+  it('returns null when ticket is null (branch had no match)', () => {
+    assert.strictEqual(appendTicketFooter('feat: add thing', null), null);
+  });
+
+  it('returns null when a TICKET footer already exists', () => {
+    assert.strictEqual(appendTicketFooter('feat: add thing\n\nTICKET: WEB-000', 'WEB-000'), null);
+  });
+
+  it('returns null when an ISSUE footer already exists (any case)', () => {
+    assert.strictEqual(appendTicketFooter('feat: add thing\n\nissue: WEB-111', 'WEB-000'), null);
+  });
+
+  it('is not stateful across repeated calls (global-regex lastIndex safe)', () => {
+    // Guards against RegExp.lastIndex leaking between .test() invocations.
+    assert.strictEqual(appendTicketFooter('feat: a', 'WEB-000'), 'feat: a\nTICKET: WEB-000\n');
+    assert.strictEqual(appendTicketFooter('feat: b', 'WEB-000'), 'feat: b\nTICKET: WEB-000\n');
+  });
+});