From b6078d59fdf02ea23b0589bfb48da04691863468 Mon Sep 17 00:00:00 2001 From: Ryan Bas Date: Mon, 11 May 2026 21:52:31 -0600 Subject: [PATCH] docs: reframe root README as monorepo with tree-shaking tools The repo has expanded beyond OIDC DevTools to include treeshake-check and eslint-plugin-treeshake. Restructure the README to present an umbrella monorepo with grouped package tables, quick-start sections for each tool domain, and an architecture diagram for the tree-shaking toolchain. Update the root package.json description accordingly. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 149 +++++++++++++++++++++++++++++++++------------------ package.json | 2 +- 2 files changed, 99 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index e3aa9e7..904847c 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,38 @@ # WolfCola DevTools -**Captures, correlates, and diagnoses** OIDC/OAuth 2.0 authentication flows in real time — works standalone with any OIDC provider or as an enhanced companion to the Ping Identity SDK. - -Available as a **browser DevTools panel** (Chrome & Firefox) and a **VS Code extension** (via Chrome DevTools Protocol). Both share the same annotation engine, diagnosis rules, and Elm UI. - -![Flow view with diagnosis banner and node rail](packages/devtools-extension/screenshots/Flow-Screen.png) +A monorepo of developer tools — OIDC/OAuth 2.0 diagnostics, tree-shaking analysis, and more. Built with TypeScript, Effect, and pnpm workspaces. --- ## Packages -| Package | Description | npm | -| --- | --- | --- | -| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private | -| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private | -| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private | -| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private | -| [`devtools-bridge`](packages/devtools-bridge) | SDK adapter — emits events from DaVinci, Journey, and OIDC clients | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-bridge)](https://www.npmjs.com/package/@wolfcola/devtools-bridge) | -| [`devtools-types`](packages/devtools-types) | Effect Schema definitions for AuthEvent, FlowState | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-types)](https://www.npmjs.com/package/@wolfcola/devtools-types) | +### OIDC DevTools + +Captures, correlates, and diagnoses OIDC/OAuth 2.0 authentication flows in real time — works standalone with any OIDC provider or as an enhanced companion to the Ping Identity SDK. Available as a browser DevTools panel and a VS Code extension. + +| Package | Description | npm | +| --------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private | +| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private | +| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private | +| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private | +| [`devtools-bridge`](packages/devtools-bridge) | SDK adapter — emits events from DaVinci, Journey, and OIDC clients | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-bridge)](https://www.npmjs.com/package/@wolfcola/devtools-bridge) | +| [`devtools-types`](packages/devtools-types) | Effect Schema definitions for AuthEvent, FlowState | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-types)](https://www.npmjs.com/package/@wolfcola/devtools-types) | + +### Tree-shaking tools + +Analyze and enforce tree-shakeability across your packages — catch bundle-bloating patterns at authoring time and verify the result post-build. + +| Package | Description | npm | +| ------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| [`treeshake-check`](packages/treeshake-check) | CLI & library — checks whether a package can be fully tree-shaken by Rollup | [![npm](https://img.shields.io/npm/v/@wolfcola/treeshake-check)](https://www.npmjs.com/package/@wolfcola/treeshake-check) | +| [`eslint-plugin-treeshake`](packages/eslint-plugin-treeshake) | ESLint plugin that flags code patterns known to break tree-shaking | [![npm](https://img.shields.io/npm/v/@wolfcola/eslint-plugin-treeshake)](https://www.npmjs.com/package/@wolfcola/eslint-plugin-treeshake) | --- ## Quick start -### Browser extension +### OIDC browser extension ```bash pnpm install @@ -33,7 +42,7 @@ pnpm build:firefox # Firefox Load the extension as unpacked from `packages/devtools-extension/dist/` — see the [extension README](packages/devtools-extension) for full instructions. -### VS Code extension +### OIDC VS Code extension ```bash pnpm install @@ -56,16 +65,38 @@ In the VS Code window, run `Ctrl+Shift+P` → **"OIDC DevTools: Start Capture"** See the [VS Code extension README](packages/vscode-extension) for detailed setup, troubleshooting, and the mock OIDC server for testing. -### Browser compatibility +### Tree-shake check -| Browser | Minimum version | -| --- | --- | -| Chrome | 88+ (Manifest V3) | +```bash +pnpm add -D @wolfcola/treeshake-check +pnpm treeshake-check +``` + +### ESLint plugin + +```bash +pnpm add -D @wolfcola/eslint-plugin-treeshake +``` + +```js +// eslint.config.mjs +import treeshake from '@wolfcola/eslint-plugin-treeshake'; + +export default [treeshake.configs.recommended]; +``` + +See each package README for full usage and configuration. + +### Browser compatibility (OIDC extension) + +| Browser | Minimum version | +| ------- | -------------------------------------- | +| Chrome | 88+ (Manifest V3) | | Firefox | 128+ (`world: "MAIN"` content scripts) | ### SDK integration (optional) -The extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge: +The OIDC extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge: ```bash pnpm add @wolfcola/devtools-bridge @@ -85,6 +116,8 @@ The bridge is a no-op when the extension is not installed. ## Architecture +### OIDC DevTools + ``` ┌──────────────────────────────────────────────────────────┐ │ Shared Packages │ @@ -110,26 +143,40 @@ Both consumers import the same annotators, diagnosis engine, and Elm UI from the - **Browser extension** → `chrome.devtools.network.onRequestFinished` + content script relay - **VS Code extension** → CDP `Network` domain + `Runtime.bindingCalled` for SDK events +### Tree-shaking tools + +``` +┌───────────────────────────┐ ┌──────────────────────────────┐ +│ eslint-plugin-treeshake │ │ treeshake-check │ +│ │ │ │ +│ Per-file AST checks │───▶│ Full Rollup bundle build │ +│ Fast, heuristic │opt │ Ground-truth analysis │ +│ Editor squiggles + fix │ │ CLI + exit codes for CI │ +└───────────────────────────┘ └──────────────────────────────┘ +``` + +The ESLint plugin provides fast, per-file feedback during development. `treeshake-check` runs a full Rollup build for ground-truth verification in CI. When `bundleCheck: true` is set in the ESLint plugin, it delegates to `treeshake-check` and maps results back to source locations. + --- ## Network-first OIDC intelligence -The extension automatically detects and annotates OIDC/OAuth 2.0 traffic without any SDK integration. It works out of the box with **any OIDC provider** — Ping Identity, Auth0, Okta, Keycloak, or any spec-compliant authorization server. +The OIDC extension automatically detects and annotates OIDC/OAuth 2.0 traffic without any SDK integration. It works out of the box with **any OIDC provider** — Ping Identity, Auth0, Okta, Keycloak, or any spec-compliant authorization server. **Well-known discovery** — parses `/.well-known/openid-configuration` responses and matches subsequent requests against discovered endpoints. **OIDC semantic annotation:** -| Phase | Extracted data | -| --- | --- | -| **discovery** | Issuer, all discovered endpoints | -| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` | -| **par** | `request_uri`, `expires_in`, pushed parameters | -| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` | -| **userinfo** | User profile data | -| **revocation** | Token revocation status | -| **introspection** | Token validity | -| **end-session** | Logout status | +| Phase | Extracted data | +| ----------------- | ---------------------------------------------------------------- | +| **discovery** | Issuer, all discovered endpoints | +| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` | +| **par** | `request_uri`, `expires_in`, pushed parameters | +| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` | +| **userinfo** | User profile data | +| **revocation** | Token revocation status | +| **introspection** | Token validity | +| **end-session** | Logout status | **DPoP detection (RFC 9449)** — detects `DPoP` proof JWTs, `token_type: "DPoP"`, `use_dpop_nonce` errors, and `DPoP-Nonce` headers. @@ -141,15 +188,15 @@ The extension automatically detects and annotates OIDC/OAuth 2.0 traffic without Every captured event is run through a rule engine that produces flow-level and per-event diagnostics with severity ratings and numbered remediation steps. -| Category | Examples | -| --- | --- | -| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials | -| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs | -| **Flow config** | Node error/failure status, connector errors, policy-not-found | -| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch | -| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse | -| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch | -| **PAR** | Missing `request_uri`, inline params alongside `request_uri` | +| Category | Examples | +| --------------- | ----------------------------------------------------------------------------------- | +| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials | +| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs | +| **Flow config** | Node error/failure status, connector errors, policy-not-found | +| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch | +| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse | +| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch | +| **PAR** | Missing `request_uri`, inline params alongside `request_uri` | --- @@ -174,20 +221,20 @@ Canvas-based flow lifecycle visualization with layout variants for DaVinci, Jour ```bash pnpm install pnpm build # build all packages -pnpm test # vitest (308 tests) +pnpm test # vitest pnpm typecheck # TypeScript type checking pnpm lint # eslint ``` -| Script | Description | -| --- | --- | -| `pnpm build` | Build all packages | -| `pnpm test` | Run all unit tests | -| `pnpm typecheck` | TypeScript type checking | -| `pnpm lint` | Lint all packages | -| `pnpm changeset` | Create a changeset for versioning | -| `pnpm version` | Apply changesets and bump versions | -| `pnpm release` | Build and publish to npm | +| Script | Description | +| ---------------- | ---------------------------------- | +| `pnpm build` | Build all packages | +| `pnpm test` | Run all unit tests | +| `pnpm typecheck` | TypeScript type checking | +| `pnpm lint` | Lint all packages | +| `pnpm changeset` | Create a changeset for versioning | +| `pnpm version` | Apply changesets and bump versions | +| `pnpm release` | Build and publish to npm | ### Tech stack @@ -202,7 +249,7 @@ pnpm lint # eslint ## Security and privacy -The extension requests only `storage` and `clipboardWrite`/`clipboardRead` — no `cookies`, `webRequest`, `tabs`, or other sensitive APIs. Content scripts use a two-world architecture to prevent arbitrary page code from injecting messages into the background script. All SDK events are decoded through `AuthEventSchema` (Effect Schema) before reaching the EventStore — malformed payloads are dropped. Captured data is stored locally and never transmitted off-device. +The OIDC extension requests only `storage` and `clipboardWrite`/`clipboardRead` — no `cookies`, `webRequest`, `tabs`, or other sensitive APIs. Content scripts use a two-world architecture to prevent arbitrary page code from injecting messages into the background script. All SDK events are decoded through `AuthEventSchema` (Effect Schema) before reaching the EventStore — malformed payloads are dropped. Captured data is stored locally and never transmitted off-device. --- diff --git a/package.json b/package.json index f2880f5..437a0b8 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "wolfcola-devtools", "version": "0.0.0", "private": true, - "description": "WolfCola DevTools — Chrome extension and SDK bridges", + "description": "WolfCola DevTools — OIDC diagnostics, tree-shaking analysis, and developer tools", "license": "MIT", "repository": { "type": "git",