@atlassian/chippy 0.0.0-stage → 0.0.1-beta.1

package/lib/mcp-skill/references/operating-model.md

@@ -0,0 +1,128 @@
+# Chippy Operating Model
+
+Chippy works in four separated phases: **Observe → Define → Prove → Apply**. This is the enforcement layer for evidence-first work. Do not collapse these phases.
+
+Cynefin positions the work; OODA drives repeated evidence steps inside Prove. See [cynefin](cynefin.md) for the full positioning and iteration rules.
+
+| Phase | Position or iteration role |
+|---|---|
+| Observe | Use read-only orientation to exit ❓ Disorder and name the domain. If it is 🔥, stabilize before further analysis. |
+| Define | Frame the case in the language of the named domain — sensor question for 🔍, experiment hypothesis for 🌀. |
+| Prove | Repeat OODA inside the named domain. Run sensors in 🔍; run safe-to-fail experiments through an observable SUT in 🌀. Never demand 🔍 certainty from a 🌀 system. |
+| Apply | Separate from OODA Act. Allowed only when the proof packet meets the per-domain confidence rule, identifies a fix layer, and supplies repeatable verification. |
+
+| Phase | Purpose | Question | Output | May edit? |
+|---|---|---|---|---|
+| **Observe** | Anchor the symptom in runtime or source reality | What is actually there? | Observation anchor: page/client, probe/fiber/testId/interaction/load window, first signal | No |
+| **Define** | Name the observed thing and the invariant under test | What case did observation reveal? | Case definition: target, scope, invariant, suspected dimensions | No |
+| **Prove** | Gather evidence until the case is confirmed, falsified, or bounded | What does runtime/source evidence prove? | Proof packet: runtime + structure + source + signal facts, confidence, next gap | No |
+| **Apply** | Change source only after proof identifies a fix layer | What is the smallest source change that preserves the invariant? | Edit + same-signal verification | Yes, only after explicit proof |
+
+## OODA inside Prove
+
+The Prove phase repeats a bounded loop:
+
+1. **Observe** the smallest current signal.
+2. **Orient** it against the domain, invariant, accumulated facts, and next gap.
+3. **Decide** the next move permitted by the domain and documented command surface.
+4. **Act** by executing that evidence move, then update the proof packet.
+
+OODA Act can be read-only. It can also be a bounded stimulus or stabilizer when the domain permits one. It is never implicit authorization to edit source: only the Apply phase can do that. If new evidence changes the cause/effect posture, return to Observe, reposition, and continue with the new domain.
+
+## Observation contract
+
+Before defining the case, anchor it in observed data:
+
+```text
+Observation: <probe/fiber/interaction/load window/page state> shows <first concrete signal>.
+```
+
+Examples:
+
+```text
+Observation: probe 1 resolves to a status label with text "Done" under IssueHeader.
+```
+
+```text
+Observation: after arming Avalanche and clicking Save, commit 42 has high collateral under the Save panel.
+```
+
+## Case definition contract
+
+After observation, define the case in one sentence:
+
+```text
+Case: <visible/runtime symptom> violates <expected invariant> at <scope>.
+Need to prove: <prop | hook | provider | store | boundary | source | load/runtime wave>.
+```
+
+Examples:
+
+```text
+Case: clicking Save causes the whole panel to lag; invariant is one bounded update under the Save branch.
+Need to prove: whether the trigger is local state, context propagation, store restart, or missing memo boundary.
+```
+
+```text
+Case: this status label says Done; invariant is that displayed text comes from issue status data, not presentation fallback.
+Need to prove: which owner passes the label prop and where the value is derived.
+```
+
+## Proof packet contract
+
+A claim is not ready for Apply until it has a proof packet.
+
+```text
+Definition:
+  target: <probe/fiber/story/page/interaction>
+  invariant: <what should stay true>
+  scope: <component/subtree/page/load/interaction>
+
+Evidence:
+  runtime: <probe-dom/pages/snapshot/avalanche status/logged transition>
+  structure: <owners/parents/fiber/hook tree>
+  source: <file:line and render block>
+  signal: <prop value/hook primitive/context wave/commit stats>
+  fact split: <source fact | runtime fact | unknown bridge>
+
+Decision:
+  role: <source | boundary | collateral | provider | store | mount | unknown>
+  confidence: confirmed | likely | partial
+  next gap: <none or exact missing fact>
+```
+
+## Apply gate
+
+Apply is allowed when the proof packet answers four questions:
+
+1. **Case + evidence** — what invariant is in scope, and which runtime/source facts support it?
+2. **Signal movement** — for no-rush or emergent work, did the last tapped contract or safe-to-fail experiment move, reproduce, or falsify the observed failure?
+3. **Fix layer** — is the change above source, at a boundary, or below source?
+4. **Verification** — can the same measurement be repeated after edit, with confidence appropriate to the domain?
+
+If any gate fails, Chippy continues proving or reports the gap. Chippy does not patch while still discovering the essence.
+
+### Per-domain confidence rule
+
+Confidence is not a free-floating field. It is bounded by the Cynefin domain Observe declared. See [cynefin](cynefin.md).
+
+| Domain | Minimum confidence to Apply | Why |
+|---|---|---|
+| ✅ Clear | `confirmed` | Sense → categorize → respond. The answer is deterministic; anything less than `confirmed` means the situation was misclassified. Reposition first. |
+| 🔍 Complicated | `confirmed` | Sense → analyze → respond. The chain is knowable; `likely`/`partial` means analysis is incomplete — keep proving, do not apply. |
+| 🌀 Complex | `likely` is sufficient **iff** the experiment is repeatable | Probe → sense → respond. Emergent systems rarely produce `confirmed`. Apply is allowed when (a) the same safe-to-fail experiment yields the same outcome on rerun, and (b) the verification command in gate 4 *is* that repeatable experiment. Never apply on `partial` in 🌀. |
+| 🔥 Chaotic | — | Apply is forbidden. Stabilize first, then re-classify. |
+| ❓ Disorder | — | Apply is forbidden. Use read-only orientation to position first. |
+
+Rule of thumb: if the proof packet reports `confidence: partial`, Apply is never allowed. If it reports `confidence: likely` in 🌀, the verification command must be the *same* experiment that produced the `likely` reading.
+
+## Fixing is a separate capability
+
+Fixing is not a natural continuation of tracing. It is invoked only after Observe, Define, and Prove.
+
+```text
+Understand path: Observe → Define → Prove → Report essence
+Fix path:       Observe → Define → Prove → Apply → Verify
+```
+
+A user may ask for understanding only. In that case, stop after Prove and report the proof packet. Do not apply.

package/lib/mcp-skill/references/playwright-cli-setup.md

@@ -0,0 +1,105 @@
+# Chippy with `playwright-cli`
+
+Use this when there is no Chippy browser extension on the page (`playwright-cli` opens a vanilla Chromium).
+
+## What is Chippy on the page
+
+Chippy assets are served by the local Chippy helper:
+
+- `http://127.0.0.1:7823/__chippy/inject.mjs` — **preferred ESM bootstrap**. Import side-effect installs `window.__CHIPPY`, registers the page with the helper, auto-loads `window.__AVALANCHE__` from the ESM-safe `avalanche.es.js` asset, activates probes immediately, and installs a small in-page control panel. The module default export is `window.__CHIPPY`; named export `ready` resolves to `{ chippy, avalanche, connState, integration, activated, probesActive }` immediately after bootstrap.
+- `http://127.0.0.1:7823/__chippy/inject.js` — **classic-script bootstrap**. Installs `window.__CHIPPY` only.
+- `http://127.0.0.1:7823/__chippy/avalanche.iife.js` — **Chippy runtime for bridge / Avalanche-backed commands**. Installs `window.__AVALANCHE__` when the classic bootstrap is used.
+
+Both paths are Chippy. `playwright-cli` is only the transport that loads them into the page.
+
+The same ESM bootstrap is also valid for a real user-controlled browser tab when the page allows helper-served module import:
+
+```js
+import('http://127.0.0.1:7823/__chippy/inject.mjs')
+```
+
+In that mode the import is intended to be extension-equivalent for the current page: it activates probes immediately and installs the in-page Chippy controls.
+
+The equivalence lasts only for the current document. A full reload or navigation removes the imported runtime because no extension or Storybook host remains to inject it. The in-page import controls display this warning. The user—or Playwright—must run the import command again after every reload/navigation.
+
+## Steps
+
+1. Start the helper:
+
+   ```bash
+   ./scripts/chippy.sh start
+   ./scripts/chippy.sh health
+   ```
+
+2. Open or reuse one `playwright-cli` Chromium session on the target URL.
+
+3. Prefer the ESM bootstrap when module loading is available:
+
+   ```bash
+   yarn exec playwright-cli -s=<session> run-code "async page => {
+     await page.addScriptTag({
+       content: `
+         const script = document.createElement('script');
+         script.type = 'module';
+         script.textContent = \"import 'http://127.0.0.1:7823/__chippy/inject.mjs';\";
+         document.head.appendChild(script);
+       `,
+     });
+     await page.waitForTimeout(700);
+     return await page.evaluate(() => ({
+       hasChippy: !!window.__CHIPPY,
+       hasAvalanche: !!window.__AVALANCHE__,
+       href: location.href,
+     }));
+   }"
+   ```
+
+   Fallback: classic script injection when ESM import is not available:
+
+   ```bash
+   yarn exec playwright-cli -s=<session> run-code "async page => {
+     await page.addScriptTag({ url: 'http://127.0.0.1:7823/__chippy/inject.js' });
+     await page.waitForTimeout(500);
+     await page.addScriptTag({ url: 'http://127.0.0.1:7823/__chippy/avalanche.iife.js' });
+     await page.waitForTimeout(200);
+     return await page.evaluate(() => ({
+       hasChippy: !!window.__CHIPPY,
+       hasAvalanche: !!window.__AVALANCHE__,
+       href: location.href,
+     }));
+   }"
+   ```
+
+4. Confirm the page is connected:
+
+   ```bash
+   ./scripts/chippy.sh pages
+   ```
+
+   The connected page is the one whose URL matches the opened tab.
+
+5. Before the first Avalanche capture or analysis command, install the detector explicitly:
+
+   ```bash
+   ./scripts/chippy.sh avalanche-install <clientId>
+   ```
+
+   Both bootstraps load the Avalanche runtime; neither auto-installs its detector in this extension-free mode. Probe, fiber, and describe commands need only the loaded runtime and connection. Avalanche commands additionally need this install step.
+
+## Re-injection after reload
+
+A full reload wipes both globals and the `import` integration does not return by itself. Re-run steps 3–5 with the same bootstrap path (`inject.mjs` preferred; `inject.js` + `avalanche.iife.js` fallback). In a user-controlled tab, ask the user to run the console import again, then install Avalanche through Chippy. Verify connection with `chippy.sh pages`, not by checking `window.__chippyPageBridge`.
+
+## Common bridge failure
+
+If a bridge / Avalanche command returns:
+
+```text
+bridge module not loaded
+```
+
+The cause is missing `avalanche.iife.js`. Inject it (step 3 second `addScriptTag`) and retry.
+
+## Dispatcher replay ancestry (only when explicitly needed)
+
+Dispatcher-based component-structure paths (`explain-component`, `describe-component`, and `inspect-fiber-structure`) need the devtools-hook shim installed **before React evaluates**. With `playwright-cli` that means `addInitScript` before navigation, using the helper-served shim at `http://127.0.0.1:7823/__chippy/devtools-hook-shim.js`. Run the debug replay preflight before those commands. `avalanche-debug-hook` is different: it reads hook events passively captured during real renders and does not execute component bodies. Ordinary bridge work does not need dispatcher replay.

package/lib/mcp-skill/references/playwright-probes.md

@@ -0,0 +1,205 @@
+# Playwright probes
+
+How Chippy operates inside a Playwright-driven browser. Same shared runtime as
+the extension, different transport. No drag UI. AI-driven targets, not pixels.
+
+## What a probe is
+
+A probe is **a focus descriptor + a resolved target**. It is not a marker.
+
+```
+Probe {
+  id            string         // "p1", "p2", ...
+  intent        string|null    // optional human note
+  descriptor    {              // portable identity
+    dom: { tag, attrs, text, nearestTestId, siblingIndex }
+    component: { name, source, ownerNames }
+  }
+  resolved      {              // per-session, recomputed
+    confidence: "strict"|"high"|"medium"|"low"|"none"
+    candidateKind: "fiber"|"dom"
+    score: number
+    matches: { ...field flags }
+    component, dom, alternates[]
+    resolvedAt: iso
+  } | null
+  history[]     // confidence/score timeline
+  createdAt     iso
+}
+```
+
+Identity rules:
+
+- Descriptor is portable across windows, runs, browsers.
+- Resolved is per-session and re-derived on demand.
+- **Coordinates are never identity.**
+
+## Lifecycle
+
+1. **Acquire** — derive a descriptor (AI, prior browser, selector hint).
+2. **Resolve** — fiber-first candidates, DOM fallback, ranked.
+3. **Inspect** — DOM, fiber props, hooks, owners, styles.
+4. **Measure** — avalanche around an interaction.
+5. **Maybe Apply** — when user intent and the P-15/P-16 gate permit, edit source and reload/HMR.
+6. **Re-resolve** — confirm the probe still lands; compare.
+7. **Handoff** — extension client → Playwright client via helper.
+
+## Operations
+
+All operations live in:
+
+```
+./browser-scripts/playwright-probes.js
+```
+
+### Session
+- `launch({ browser, url, headless })`
+- `close(session)`
+- `goto(session, url, options?)`
+- `reload(session, options?)`
+
+### Probes
+- `defineProbe({ id, intent, descriptor })`
+- `registerProbe(session, probe)`
+- `captureFromNode(session, locator)`
+- `captureFromSelector(session, selector)`
+- `resolveProbe(session, probe, options?)`
+- `refreshProbe(session, probeId, options?)`
+- `listProbes(session)`
+- `removeProbe(session, probeId)`
+
+### Inspect
+- `probeDom(session, probe, parentLevel?)`
+- `probeOwners(session, probe)`
+- `probeOwner(session, probe, ownerIndex)`
+- `probeProps(session, probe, ownerIndex?)`
+- `probePropValue(session, probe, propName, ownerIndex?)`
+- `probeHooks(session, probe)`
+- `getComputedStyle(session, probe, parentLevel?)`
+
+### Measure (avalanche)
+
+The Playwright session connects to the helper as a normal client. All
+avalanche calls go through the helper HTTP API; the helper drives
+`__AVALANCHE__` on the page over the existing WS bridge. Playwright never
+calls `__AVALANCHE__` directly.
+
+Why route through the helper:
+- one transport and explicit detector-install path
+- one result format across extension and Playwright
+- one place to reason about cross-session capture state
+- helper is the context manager for everything Chippy does
+
+Read flow (each call):
+```
+Playwright → helper HTTP /api/pages/:clientId/avalanche
+    → WS to client → __CHIPPY.pageBridge.evalAvalanche
+    → __AVALANCHE__.<action>
+    → result back through WS → helper HTTP body → Playwright
+```
+
+How Playwright reads data:
+- `clientId` is read once via `__CHIPPY.pageBridge.getState().clientId`
+  and cached on the session
+- each avalanche call returns `{ ok, status, payload }` from the helper
+- `payload` is the standard helper avalanche response (`action`, `available`,
+  `status`, `payload`, etc.)
+- the actual data lives on the page in `__AVALANCHE__`; we only ever read it
+  through the helper
+
+Operations:
+- `avalanche(session, action, payload?)` — generic dispatcher
+- `avalancheStatus(session)`
+- `avalancheHotSources(session, limit?)`
+- `avalancheExport(session, lastN?)`
+- `reloadWithAvalanche(session, { settleMs?, hotLimit? })`
+
+Supported generic actions are `install`, `uninstall`, `reset`/`clear`, `status`, `export`, `export-last`, `debug-hook`, `hot-sources`, `commit-list`, `commit-peek`, and `describe-action`. The module still exports legacy `avalancheStart`, `avalancheStop`, and `avalancheMetrics` wrappers for compatibility; do not use them in new workflows. `avalancheStart` is only an alias for `install`, while `stop` and `metrics` are not actions on the current bridge contract.
+
+Helper base URL is `http://127.0.0.1:7823/__chippy` by default and can be
+overridden with `CHIPPY_HELPER_BASE`.
+
+### reloadWithAvalanche
+
+The packaged `launchSession(...)` path installs the Chippy bridge and Avalanche runtime via `addInitScript`, so both runtimes exist before page scripts on every reload. The detector still starts uninstalled in each new page realm. `reloadWithAvalanche` therefore reloads, waits for the new client, calls the Avalanche `install` action explicitly, then settles and reads evidence. It does not use helper origin-arming.
+
+Commits that occur before that post-reload install are not captured. Use this helper for post-install triggers and settled-state checks, not to claim complete initial-load coverage.
+
+Flow:
+1. `page.reload()` via Playwright
+2. wait for the reinjected runtime and a fresh `clientId`
+3. install the detector through the helper
+4. settle for `settleMs` (default 3000)
+5. read `status` and `hot-sources` through the helper
+
+Returns:
+```js
+{
+  previousClientId,
+  clientId,        // new clientId after reload
+  install,         // explicit detector-install response
+  status,          // helper avalanche-status response
+  hot,             // helper hot-sources response
+}
+```
+
+Notes:
+- requires the session to have been started with `launch(...)`, which uses
+  `installHelpers({ init: true })` under the hood
+- bump `settleMs` to 5000+ for heavy app loads
+- this packaged init-script loader and the ad-hoc `addScriptTag` flow are two Mode A bootstrap variants; both require detector installation and both miss commits before that install
+
+### Compare
+- `snapshotProbe(session, probe)`
+- `diffProbeSnapshots(a, b)`
+
+## Operating rules
+
+- **Probes are descriptors first.** Resolution is recomputed, not cached identity.
+- **Fiber beats DOM** when scoring matches.
+- **Strict identity wins** over fuzzy when both available.
+- **No coordinates as identity.** Pixels never cross window boundaries.
+- **Confidence is reported.** Low-confidence ops must be acknowledged.
+- **Re-resolve after** any reload, navigation, code edit, HMR, route change.
+- **Avalanche is per-session.** Probes interpret hot sources, not gate them.
+- **Browser is Chromium or WebKit.** Never user's Chrome.
+- **DRY:** the same shared runtime files power extension and Playwright.
+
+## Handoff from extension to Playwright
+
+Helper command:
+```
+./scripts/chippy.sh handoff-to-playwright <clientId> [url] [probeIdsCsv] [browserName] [headless]
+```
+
+What it does:
+1. Captures live probe descriptors from the source extension client.
+2. Launches Playwright Chromium and navigates to URL.
+3. Injects shared __CHIPPY runtime via `playwright-session.js`.
+4. Registers the new page as another helper client.
+5. Returns descriptors so Playwright probe code can resolve them.
+
+The Playwright session is then operated like any other helper client.
+
+## When to use Playwright vs extension
+
+Use the **extension**:
+- user is exploring
+- target is unclear
+- live page already has the right state
+- user needs to point at things
+
+Use **Playwright**:
+- iteration loop is repetitive (reload + interact + measure)
+- target is already known via descriptor
+- need a clean, controlled environment
+- need reproducibility across runs
+- user is not in front of the page
+
+Both share:
+- inspect-react.js
+- layout-lab.js
+- resolve-probes.js
+- probe-descriptor.js
+- avalanche.iife.js
+- chippy-page-bridge.js