@nurix/etna 0.19.17 → 0.19.19

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "a7791e9cf297",
+    "fingerprint": "8688786a5c30",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/harness.json

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "cc025f7950c3"
+  "digest": "7a392f55e225"
 }

package/data/harnesses/code/skills/brainstorm/README.md

@@ -6,7 +6,7 @@ correctly, the record stays readable at any pause, and the session ends with a h
 complete that the session folder is useless — it moves to history and the user deletes or
 commits it.
 
-> Spec (single source of truth): `docs/features/brainstorm-skill/` in the etna repo. The etna
+> Spec (single source of truth): `docs/architecture/skills/brainstorm/` in the etna repo. The etna
 > copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
 > `~/.claude/skills/brainstorm/` is a symlink to it.
 

package/data/harnesses/discover/CLAUDE.md

@@ -36,6 +36,24 @@ Agent name = dimension name. ⚠ = gated (needs user authorization before dispat
 
 ---
 
+## Step 0 — first run (tooling check)
+
+**Once per folder, before Mode 1.** Capture depth depends on host tooling most machines lack (`gron`, `trafilatura`, `mitmproxy`, `chrome-remote-interface`, …). On the first run in a corpus folder, check the state file `.claude/discover-tooling.json`:
+
+- **It exists** → tooling was already reviewed here — skip straight to Mode 1. **Never re-prompt in the same folder.**
+- **It's absent** → run the one-time check:
+  1. Read [`tooling-recommendations.md`](tooling-recommendations.md) (beside this file at the project root) — the Tier 1 (clean) and Tier 2 (gated) tool lists + the AVOID list.
+  2. **Validate what's already installed before recommending anything** — `command -v <tool>` per recommended tool (`npm ls -g <pkg>` for the Node libraries that ship no binary, e.g. `chrome-remote-interface`). Detection only — install nothing yourself.
+  3. **Recommend only the missing tools**, grouped **clean** (safe to install freely — offer the Tier-1 one-paste block) vs **gated** (first-party / user-owned / opt-in — surface the command but **never run it for the user**; these need the user in the loop). Never suggest anything on the AVOID list. If nothing is missing, say so in one line.
+  4. **Write `.claude/discover-tooling.json`** so the harness never asks again in this folder:
+     ```json
+     { "checked": "<ISO date>", "present": ["gron", "pandoc"], "missing": ["mitmproxy"], "recommended": true }
+     ```
+
+The state file is **host-local** (tools live on the machine, not the repo) — gitignore it in a shared folder; delete it to force a fresh check after installing a batch. This step never blocks a run: a user who declines proceeds to Mode 1 on whatever tooling is present, and a genuinely missing *preferred* capability is re-surfaced at the Mode 2 capability-gap checkpoint.
+
+---
+
 ## Mode 1 — Discovery
 
 Cheap, read-only. Scope the target, grade its access, detect which dimensions it exposes.

package/data/harnesses/discover/harness.json

@@ -5,7 +5,8 @@
   "files": [
     ".prettierignore",
     ".prettierrc.json",
-    ".vscode/settings.json"
+    ".vscode/settings.json",
+    "tooling-recommendations.md"
   ],
-  "digest": "a672787b9962"
+  "digest": "4e7fa848fe93"
 }

package/data/harnesses/discover/tooling-recommendations.md

@@ -0,0 +1,119 @@
+# Tooling recommendations — what to install to improve capture & synthesis
+
+> The `discover` harness reads this file on **first run** (Step 0 in [`CLAUDE.md`](CLAUDE.md)): it detects which of these tools are already on the host, recommends only the **missing** ones (the gated ones only with you in the loop), and records the result in `.claude/discover-tooling.json` so it never re-prompts in this folder. Nothing here is installed automatically — the harness recommends, you decide.
+
+The host almost always arrives strong on languages and package managers (node, pnpm, python, uv, cargo, gh, jq, ripgrep) but **bare on capture/analysis tooling** — the tools below are what turn a shallow capture into a deep one.
+
+## How to read this
+
+- **clean** — passive / local-only; always in-bounds. Install freely.
+- **gated** — fine, but only **first-party / user-owned / opt-in** (you install the CA, you route _your own_ client, you own the keys). mitmproxy, websocat, CDP, subfinder/tlsx, frida-on-your-own-device.
+- **avoid** — crosses the harness bright line (active scanning / exploitation / third-party packet capture). Listed so they're _not_ added by reflex.
+
+The harness is for **spec-writing / integration / competitive analysis** — passive or first-party only, respect TOS/robots. No tool below changes that; the gated ones just need the user in the loop.
+
+---
+
+## Tier 1 — install now (clean, broad leverage)
+
+The highest-consensus, always-in-bounds tools. One paste:
+
+```bash
+# Homebrew (CLI analysis + data-wrangling + web→text)
+brew install gron pandoc ast-grep scc universal-ctags oasdiff fd yq dasel monolith tokei sevenzip
+# Rust
+cargo install htmlq
+# Python (via uv — pipx is absent; uv tool install is the path)
+uv tool install trafilatura && uv tool install griffe
+# Node global (JS/TS surface + bundle de-obfuscation + spec lint)
+npm i -g webcrack source-map-explorer @arethetypeswrong/cli publint @electron/asar typescript @stoplight/spectral-cli
+# Headless browser for JS-rendered docs/marketing (clean — your own headless instance)
+npm i -g playwright && npx playwright install chromium
+```
+
+| Tool | Unlocks | Dimensions served |
+| --- | --- | --- |
+| **gron** | flatten any JSON → greppable/diffable `path = value` (specs, captures, manifests, HAR, configs) | **7** (codebase, api, session, bundle, infra, wire, cross-cutting) |
+| **trafilatura** | boilerplate-stripped main-content + dates from HTML → clean markdown; feed/sitemap discovery | **4** (docs, website, community, infra) |
+| **pandoc** | deterministic HTML→GFM (headings, tables, code fences) at scale | 3 (docs, website, community) |
+| **ast-grep** | tree-sitter structural search/count across many files+langs (call sites, routes, exports) — catches what regex misses | 2 (codebase, bundle) |
+| **oasdiff** | structured breaking-vs-non-breaking OpenAPI diff — makes the published-vs-app-own diff machine-checked | 2 (api, cross-cutting) |
+| **webcrack** | un-minify / un-webpack / de-obfuscate SPA & Electron JS into readable modules | 2 (bundle, distribution) |
+| **scc** | instant LOC-by-language + complexity census of a fresh clone (JSON) — the codebase opening move | 1 (codebase) |
+| **universal-ctags** | real multi-lang JSON symbol index (the host's BSD ctags is broken for this) | 1 (codebase) |
+| **htmlq** | surgical CSS-selector extraction (pricing cards, feature tables) instead of regex | 1 (website) |
+| **source-map-explorer** | reassemble shipped `.map` → original `src/` tree (the `source-map-reassembly` method) | 1 (bundle) |
+| **spectral** | validate/resolve an OpenAPI/AsyncAPI spec → structured endpoint/security/$ref catalog | 1 (api) |
+| **griffe** | extract a PyPI package's full public API (the `.d.ts`-equivalent for Python) | 1 (packages) |
+| **@arethetypeswrong/cli + typescript + publint** | parse the real `.d.ts`/exports type graph + grade the publish surface (verbatim, not string-mined) | 1 (packages) |
+| **@electron/asar** | extract Electron `app.asar` → JS module tree (the distribution step the playbook names but can't run) | 1 (distribution) |
+| **fd / yq / dasel / monolith / tokei / sevenzip** | gitignore-aware file discovery · YAML/XML/TOML query · RSS/XML→JSON · single-file page archive · LOC cross-check · multi-format extract | several |
+
+---
+
+## Tier 2 — install when a run needs them (gated: first-party / passive-care)
+
+The capture lanes. In-bounds **only** for your own session / first-party clients / passive sources.
+
+```bash
+brew install mitmproxy websocat grpcurl subfinder tlsx testssl jadx apktool
+npm i -g chrome-remote-interface get-graphql-schema
+# one-time, user-run: expose a CDP port on your own Chrome (closes the WS-frame blind spot)
+#   open -na "Google Chrome" --args --remote-debugging-port=9222
+# mobile-only, your own device + opt-in:  uv tool install frida-tools
+```
+
+| Tool | Unlocks | Ethics note |
+| --- | --- | --- |
+| **mitmproxy** | decode full HTTPS + WebSocket flows of any **first-party** client (CLI/desktop/mobile/SDK) — wire-capture rung 3 keystone | user installs CA + routes _their own_ client only |
+| **chrome-remote-interface** | raw CDP client → `Network.webSocketFrameReceived`/`Created`, SSE, full bodies — **captures the on-load WS frames the browser MCP's HTTP-only `read_network_requests` drops** | your own logged-in session |
+| **websocat** | curl-for-WebSockets: connect/frame/replay/hexdump a realtime endpoint outside the browser | first-party endpoint |
+| **grpcurl** | list services + invoke RPCs via gRPC server reflection → readable op/message catalog | first-party endpoint |
+| **get-graphql-schema** | introspect a first-party GraphQL endpoint → full SDL | first-party endpoint |
+| **subfinder / tlsx / testssl.sh** | passive CT/DNS subdomain breadth + structured TLS posture (vs hand-rolled crt.sh + openssl text) | passive aggregation; respect rate limits |
+| **jadx / apktool** | decompile Android `.apk`/`.dex` → Java + decode `AndroidManifest`/resources (capability map) | public binary, read EULA |
+| **frida-tools** | cert-pinning bypass to capture **your own** mobile client's wire | your own device + opt-in only |
+
+**The single biggest unlock** for realtime targets: `chrome-remote-interface` + a Chrome `--remote-debugging-port` + `websocat` + `mitmproxy` together give `session`/`wire-capture` a real WebSocket/SSE capture path, instead of a client-side-remount workaround. The browser-MCP `read_network_requests` is HTTP-only — that's _why_ a realtime tap comes back empty until the remount trick.
+
+---
+
+## AVOID — do NOT install (crosses the harness bright line)
+
+Out-of-bounds for a spec-writing/competitive-analysis harness — listed so they aren't added by reflex:
+
+- **`nmap`, `masscan`, `naabu`** — active port sweeps / service-version probing of remote hosts.
+- **`nuclei`** — template-based remote vuln scanning.
+- **`sqlmap`** — injection/exploitation.
+- **`amass` (active mode)** — active DNS brute-forcing (its _passive_ mode overlaps subfinder; prefer subfinder).
+- **third-party `mitmproxy`, `frida` on devices you don't own, `socat` as a public relay** — third-party traffic interception is the line this harness will not cross.
+
+These stay absent by design; the recon ethics depend on it.
+
+---
+
+## Per-dimension view (gap → top pick)
+
+| Dimension | Biggest capability gap on a bare host | Top addition(s) |
+| --- | --- | --- |
+| **codebase** | no LOC census, no AST search; BSD ctags is broken | scc · ast-grep · universal-ctags (+ fd) |
+| **docs** | no HTML/MDX→md, no JS-render → client-rendered docs come back empty | pandoc · trafilatura · playwright |
+| **packages** | the real `.d.ts`/exports surface is string-mined, not parsed | typescript+attw+publint · griffe (Py) · yq |
+| **api** | can fetch a spec but can't lint/diff/introspect/exercise it | spectral · oasdiff · get-graphql-schema · grpcurl · websocat |
+| **website** | no JS-render, no clean table/text extraction → misses pricing/feature grids | trafilatura · htmlq · playwright |
+| **community** | no clean changelog/blog→text, no RSS→JSON | trafilatura · pandoc · dasel |
+| **session** | **structurally blind to WebSocket/SSE frames** (HTTP-only MCP, no CDP port) | chrome-remote-interface · mitmproxy · websocat |
+| **deployed-client-bundle** | minified/obfuscated blob stays opaque; no source-map reassembly | webcrack · source-map-explorer · ast-grep · gron |
+| **infra-backend-fingerprint** | shallow CT coverage, TLS posture by hand, sub-processor pages scraped raw | subfinder · tlsx · trafilatura (passive only) |
+| **wire-capture** | keystone mitmproxy + all non-browser replay/decode clients absent | mitmproxy · websocat · grpcurl |
+| **distribution-artifacts** | only CRX/Mach-O readable; no Electron/Android decoders | @electron/asar · jadx · apktool · webcrack · sevenzip |
+| **cross-cutting (synthesis)** | no structured diff for the N-way seam reconciliation; no out-of-band WS capture | gron · oasdiff · chrome-remote-interface · yq |
+
+---
+
+## Known install caveats
+
+- **`webcrack` needs Node 22.** Its hard dependency `isolated-vm` is a native (node-gyp) addon that fails to build against Node 26 (and `--omit=optional` doesn't help — the dep is non-optional). If it won't install, run it under a Node 22 LTS shim (`npx -y webcrack@latest …` in a Node-22 env), or lean on the already-clean `source-map-explorer` (the preferred `source-map-reassembly` path whenever the SPA ships `.map` files) + `ast-grep`. De-obfuscation of a _no-maps, minified_ bundle is the only gap this leaves.
+- **`chrome-remote-interface` is a library, not a CLI** — it installs as a Node module and is invoked from a script, not a shell binary. Detect it with `npm ls -g chrome-remote-interface`, not `command -v`.
+- **`pipx` is typically absent; use `uv tool install`** for Python CLIs (uv is present) — simpler than adding pipx.
+- **`playwright` is clean** (your own headless instance) and unblocks JS-rendered docs/marketing for `docs`+`website` without contending for the gated `session` Chrome.

package/data/harnesses/etna/harness.json

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "b93279e6959d"
+  "digest": "dbc9b25ecc8f"
 }

package/data/harnesses/etna/skills/brainstorm/README.md

@@ -6,7 +6,7 @@ correctly, the record stays readable at any pause, and the session ends with a h
 complete that the session folder is useless — it moves to history and the user deletes or
 commits it.
 
-> Spec (single source of truth): `docs/features/brainstorm-skill/` in the etna repo. The etna
+> Spec (single source of truth): `docs/architecture/skills/brainstorm/` in the etna repo. The etna
 > copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
 > `~/.claude/skills/brainstorm/` is a symlink to it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.17",
+    "version": "0.19.19",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {