Skip to content

Commit b6078d5

Browse files
ryanbas21claude
ryanbas21
and
claude
committed
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) <noreply@anthropic.com>
1 parent c80b519 commit b6078d5

2 files changed

Lines changed: 99 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 98 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,38 @@
11
# WolfCola DevTools
22

3-
**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.
4-
5-
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.
6-
7-
![Flow view with diagnosis banner and node rail](packages/devtools-extension/screenshots/Flow-Screen.png)
3+
A monorepo of developer tools — OIDC/OAuth 2.0 diagnostics, tree-shaking analysis, and more. Built with TypeScript, Effect, and pnpm workspaces.
84

95
---
106

117
## Packages
128

13-
| Package | Description | npm |
14-
| --- | --- | --- |
15-
| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private |
16-
| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private |
17-
| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private |
18-
| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private |
19-
| [`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) |
20-
| [`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) |
9+
### OIDC DevTools
10+
11+
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.
12+
13+
| Package | Description | npm |
14+
| --------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
15+
| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private |
16+
| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private |
17+
| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private |
18+
| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private |
19+
| [`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) |
20+
| [`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) |
21+
22+
### Tree-shaking tools
23+
24+
Analyze and enforce tree-shakeability across your packages — catch bundle-bloating patterns at authoring time and verify the result post-build.
25+
26+
| Package | Description | npm |
27+
| ------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
28+
| [`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) |
29+
| [`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) |
2130

2231
---
2332

2433
## Quick start
2534

26-
### Browser extension
35+
### OIDC browser extension
2736

2837
```bash
2938
pnpm install
@@ -33,7 +42,7 @@ pnpm build:firefox # Firefox
3342

3443
Load the extension as unpacked from `packages/devtools-extension/dist/` — see the [extension README](packages/devtools-extension) for full instructions.
3544

36-
### VS Code extension
45+
### OIDC VS Code extension
3746

3847
```bash
3948
pnpm install
@@ -56,16 +65,38 @@ In the VS Code window, run `Ctrl+Shift+P` → **"OIDC DevTools: Start Capture"**
5665

5766
See the [VS Code extension README](packages/vscode-extension) for detailed setup, troubleshooting, and the mock OIDC server for testing.
5867

59-
### Browser compatibility
68+
### Tree-shake check
6069

61-
| Browser | Minimum version |
62-
| --- | --- |
63-
| Chrome | 88+ (Manifest V3) |
70+
```bash
71+
pnpm add -D @wolfcola/treeshake-check
72+
pnpm treeshake-check
73+
```
74+
75+
### ESLint plugin
76+
77+
```bash
78+
pnpm add -D @wolfcola/eslint-plugin-treeshake
79+
```
80+
81+
```js
82+
// eslint.config.mjs
83+
import treeshake from '@wolfcola/eslint-plugin-treeshake';
84+
85+
export default [treeshake.configs.recommended];
86+
```
87+
88+
See each package README for full usage and configuration.
89+
90+
### Browser compatibility (OIDC extension)
91+
92+
| Browser | Minimum version |
93+
| ------- | -------------------------------------- |
94+
| Chrome | 88+ (Manifest V3) |
6495
| Firefox | 128+ (`world: "MAIN"` content scripts) |
6596

6697
### SDK integration (optional)
6798

68-
The extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge:
99+
The OIDC extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge:
69100

70101
```bash
71102
pnpm add @wolfcola/devtools-bridge
@@ -85,6 +116,8 @@ The bridge is a no-op when the extension is not installed.
85116

86117
## Architecture
87118

119+
### OIDC DevTools
120+
88121
```
89122
┌──────────────────────────────────────────────────────────┐
90123
│ Shared Packages │
@@ -110,26 +143,40 @@ Both consumers import the same annotators, diagnosis engine, and Elm UI from the
110143
- **Browser extension** → `chrome.devtools.network.onRequestFinished` + content script relay
111144
- **VS Code extension** → CDP `Network` domain + `Runtime.bindingCalled` for SDK events
112145

146+
### Tree-shaking tools
147+
148+
```
149+
┌───────────────────────────┐ ┌──────────────────────────────┐
150+
│ eslint-plugin-treeshake │ │ treeshake-check │
151+
│ │ │ │
152+
│ Per-file AST checks │───▶│ Full Rollup bundle build │
153+
│ Fast, heuristic │opt │ Ground-truth analysis │
154+
│ Editor squiggles + fix │ │ CLI + exit codes for CI │
155+
└───────────────────────────┘ └──────────────────────────────┘
156+
```
157+
158+
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.
159+
113160
---
114161

115162
## Network-first OIDC intelligence
116163

117-
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.
164+
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.
118165

119166
**Well-known discovery** — parses `/.well-known/openid-configuration` responses and matches subsequent requests against discovered endpoints.
120167

121168
**OIDC semantic annotation:**
122169

123-
| Phase | Extracted data |
124-
| --- | --- |
125-
| **discovery** | Issuer, all discovered endpoints |
126-
| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` |
127-
| **par** | `request_uri`, `expires_in`, pushed parameters |
128-
| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` |
129-
| **userinfo** | User profile data |
130-
| **revocation** | Token revocation status |
131-
| **introspection** | Token validity |
132-
| **end-session** | Logout status |
170+
| Phase | Extracted data |
171+
| ----------------- | ---------------------------------------------------------------- |
172+
| **discovery** | Issuer, all discovered endpoints |
173+
| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` |
174+
| **par** | `request_uri`, `expires_in`, pushed parameters |
175+
| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` |
176+
| **userinfo** | User profile data |
177+
| **revocation** | Token revocation status |
178+
| **introspection** | Token validity |
179+
| **end-session** | Logout status |
133180

134181
**DPoP detection (RFC 9449)** — detects `DPoP` proof JWTs, `token_type: "DPoP"`, `use_dpop_nonce` errors, and `DPoP-Nonce` headers.
135182

@@ -141,15 +188,15 @@ The extension automatically detects and annotates OIDC/OAuth 2.0 traffic without
141188

142189
Every captured event is run through a rule engine that produces flow-level and per-event diagnostics with severity ratings and numbered remediation steps.
143190

144-
| Category | Examples |
145-
| --- | --- |
146-
| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials |
147-
| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs |
148-
| **Flow config** | Node error/failure status, connector errors, policy-not-found |
149-
| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch |
150-
| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse |
151-
| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch |
152-
| **PAR** | Missing `request_uri`, inline params alongside `request_uri` |
191+
| Category | Examples |
192+
| --------------- | ----------------------------------------------------------------------------------- |
193+
| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials |
194+
| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs |
195+
| **Flow config** | Node error/failure status, connector errors, policy-not-found |
196+
| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch |
197+
| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse |
198+
| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch |
199+
| **PAR** | Missing `request_uri`, inline params alongside `request_uri` |
153200

154201
---
155202

@@ -174,20 +221,20 @@ Canvas-based flow lifecycle visualization with layout variants for DaVinci, Jour
174221
```bash
175222
pnpm install
176223
pnpm build # build all packages
177-
pnpm test # vitest (308 tests)
224+
pnpm test # vitest
178225
pnpm typecheck # TypeScript type checking
179226
pnpm lint # eslint
180227
```
181228

182-
| Script | Description |
183-
| --- | --- |
184-
| `pnpm build` | Build all packages |
185-
| `pnpm test` | Run all unit tests |
186-
| `pnpm typecheck` | TypeScript type checking |
187-
| `pnpm lint` | Lint all packages |
188-
| `pnpm changeset` | Create a changeset for versioning |
189-
| `pnpm version` | Apply changesets and bump versions |
190-
| `pnpm release` | Build and publish to npm |
229+
| Script | Description |
230+
| ---------------- | ---------------------------------- |
231+
| `pnpm build` | Build all packages |
232+
| `pnpm test` | Run all unit tests |
233+
| `pnpm typecheck` | TypeScript type checking |
234+
| `pnpm lint` | Lint all packages |
235+
| `pnpm changeset` | Create a changeset for versioning |
236+
| `pnpm version` | Apply changesets and bump versions |
237+
| `pnpm release` | Build and publish to npm |
191238

192239
### Tech stack
193240

@@ -202,7 +249,7 @@ pnpm lint # eslint
202249

203250
## Security and privacy
204251

205-
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.
252+
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.
206253

207254
---
208255

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "wolfcola-devtools",
33
"version": "0.0.0",
44
"private": true,
5-
"description": "WolfCola DevTools — Chrome extension and SDK bridges",
5+
"description": "WolfCola DevTools — OIDC diagnostics, tree-shaking analysis, and developer tools",
66
"license": "MIT",
77
"repository": {
88
"type": "git",

0 commit comments

Comments
 (0)