diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9137a74..65cf7f6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -15,7 +15,7 @@ "skills": [ "./skills/reverse-engineering-saas" ], - "version": "0.2.0" + "version": "0.3.0" } ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index 022455f..1f44176 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 0.3.0 (2026-10-16) + +Fixes for the gaps found by the first real study (Pipedrive, L3, `examples/pipedrive/`). + +- Handoff: `pack-kb.mjs` keeps `sandbox/ledger.csv` in the zip with object IDs and locations blanked and URLs replaced by `[url]`. An unzipped handoff now passes `check-kb --closing`, and `L-###` references in the KB resolve. +- Baseline counts cover only the container and the operator's records since the first ledger row, by filter or count endpoint, never by pulling full record lists. Teardown compares those counts. `environment.md` records the filter. +- L3: when the container cannot be private, set each record's visibility to the operator only. An unattended session that starts during the team's working hours writes only when the team cannot see the records; otherwise it does the phases without writes first. +- "Stop and skip": deleting your own ledger items inside the sandbox is exempt from the "cannot be undone" stop when the dialog names only those items. +- `mask.js`: selectors become CSS rules that also blur elements rendered later (popovers, dropdowns), until `clear()`. Placeholders that match a pattern are blurred, and `placeholders: true` blurs all of them. Invalid selectors are reported. New "Masking" section in `extraction.md`. +- Report: `build-report.mjs` turns the knowledge base into `REPORT.html`, the main report a person reads. One self-contained page (images embedded, IDs linked, no scripts, no network), with summary, decisions, barriers, build plan, screens, rules, data model, tokens and an evidence gallery. `pack-kb.mjs` writes it and puts it in the zip, and the skill sends it with the zip. +- `tools.md`: Claude in Chrome notes. Long `javascript_tool` results are read through an offscreen `
` and `get_page_text`. Use `api-shapes.js` when `read_network_requests` misses app calls. Never load scripts from a local server in the user's tab. Check state after each click in a background window. Where `save_to_disk` screenshots land. + ## 0.2.0 (2026-10-16) - Handoff: `pack-kb.mjs` packs the knowledge base into a zip with `BUILD.md`, a build brief for any coding agent. It checks the KB first, leaves out `sandbox/` and `log/` unless `--full`, and needs no dependencies. diff --git a/README.md b/README.md index 598d98c..baaf90c 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Want to rebuild a product your team relies on, or launch a competitor in your market? Ask your agent to study it with RES. The agent explores the product in a test environment, records every change it makes, and writes what it learns to files: screens and states, business rules with evidence, the data model, API shapes, design tokens, and what could stop the clone from launching, such as integrations that need approval, licenses and certifications. -At the end you get a zip. Unzip it, give the folder to any coding agent, and it starts from `BUILD.md`. +At the end you get two files. `REPORT.html` is the report you read: one page with the summary, the decisions you need to make, launch barriers, the build plan, every screen and rule, the data model, design tokens and the evidence. The zip is for your coding agent: unzip it, give it the folder, and it starts from `BUILD.md`. RES is one agent skill with plain Markdown templates and a few dependency-free Node.js scripts. It adds about 130 tokens to every session and about 4,600 when it runs (measured with `claude plugin details`). @@ -71,7 +71,7 @@ Study Pipedrive so my team can rebuild it for the Brazilian market. Use the trial profile, and don't ask me anything until you're done. ``` -Replace the product, the market and the scope with your own. The agent creates `re-/` in its working directory, works through the phases below, and sends you `re--handoff-.zip` when it finishes. To continue later, start a session in the same directory and say "Continue the Pipedrive study." +Replace the product, the market and the scope with your own. The agent creates `re-/` in its working directory, works through the phases below, and sends you `REPORT.html` and `re--handoff-.zip` when it finishes. To continue later, start a session in the same directory and say "Continue the Pipedrive study." ### Use the scripts directly @@ -85,6 +85,10 @@ node skills/reverse-engineering-saas/scripts/init-kb.mjs --product "Acme CRM" -- node skills/reverse-engineering-saas/scripts/check-kb.mjs re-acme-crm ``` +```bash +node skills/reverse-engineering-saas/scripts/build-report.mjs re-acme-crm +``` + ```bash node skills/reverse-engineering-saas/scripts/pack-kb.mjs re-acme-crm ``` @@ -111,7 +115,7 @@ flowchart LR D --> E[Deep dive
one feature at a time] E -->|next feature| E E --> F[Synthesis:
PRD, parity, barriers] - F --> G[Close and
handoff zip] + F --> G[Close:
report and zip] ``` | Phase | What happens | @@ -122,7 +126,7 @@ flowchart LR | 4 Map | Every screen and route; stack and design tokens | | 5 Deep dive | One feature at a time: fixtures, states, rules, persistence, network, written to disk before the next feature | | 6 Synthesis | Data model, design tokens, barriers, PRD, parity tests | -| 7 Close | Restore what changed, pass `check-kb`, send the handoff zip | +| 7 Close | Restore what changed, pass `check-kb`, send `REPORT.html` and the handoff zip | The knowledge base on disk is the agent's only memory, so a study can span many sessions and survive context limits. Every statement carries its evidence: `[obs]` seen in the product, `[net]` captured on the network, `[doc]` from public documentation, `[inf]` an inference with an open question. @@ -138,6 +142,7 @@ The knowledge base on disk is the agent's only memory, so a study can span many | Design | Color, type, spacing, radius, shadow and motion tokens, mapped to the product's CSS variables | `design/` | | Production barriers | Integrations that need approval, licenses, certifications, distribution gatekeepers and moats, with severity, market weight, lead time and mitigation | `clone/barriers.md` | | Build plan | Requirements, parity tests derived from the rules, what to copy, avoid and improve | `clone/` | +| Report | `REPORT.html`: one self-contained page a person reads, with images embedded and every ID linked | KB root | | Handoff | `BUILD.md`, a brief for any coding agent: read order, rules as tests, what not to copy | zip root | A rule: @@ -218,7 +223,7 @@ Yes. Tell it not to ask you anything. It records what needs you under "Needs hum
How do I give the result to my developers? -Ask for the handoff, or wait for the end of the study. The agent sends a zip with the knowledge base and `BUILD.md`. Account details (`sandbox/`, `log/`) stay out of the zip. +Ask for the handoff, or wait for the end of the study. The agent sends `REPORT.html` for people and a zip with the knowledge base and `BUILD.md` for coding agents. Account details (`sandbox/`, `log/`) stay out of the zip, except a copy of the change ledger without object IDs, locations or URLs.
@@ -249,7 +254,7 @@ That depends on the product's terms and your jurisdiction. RES records the relev ## Status -Version 0.2.0. The method was tested with scenario runs on subagents, before and after each change to the skill, and the scripts with automated tests on Node.js 22 and 24. It has not yet been run end to end on a real product. Example studies of ClickUp and Pipedrive are planned. Reports from real runs are welcome: open a [study report](https://github.com/alextnetto/res/issues/new?template=study_report.yml). +Version 0.3.0. The method was tested with scenario runs on subagents, before and after each change to the skill, and the scripts with automated tests on Node.js 22 and 24. It has not yet been run end to end on a real product. Example studies of ClickUp and Pipedrive are planned. Reports from real runs are welcome: open a [study report](https://github.com/alextnetto/res/issues/new?template=study_report.yml). ## Responsible use diff --git a/docs/testing.md b/docs/testing.md index 5fe82e0..25ef17d 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -16,8 +16,8 @@ npm test | File | What it checks | |---|---| -| `tests/page-scripts.test.mjs` | Runs the five page scripts in headless Chromium against `tests/fixture.html` with mocked API and WebSocket traffic. Asserts component tags, routes, token-to-variable mapping, endpoint templates, JSON shapes, GraphQL operations, WebSocket frames, masking, annotation, and that the fake names, emails, IDs and storage values on the test page do not appear in the results | -| `tests/kb-scripts.test.mjs` | Creates a knowledge base with `init-kb.mjs` and checks the main `check-kb.mjs` rules: unresolved references, rules and barriers without evidence, malformed tags, placeholder IDs, duplicates, broken links, `[inf]` without a question, missing "Not tested" sections, ledger validation, `fixture` and `human` rows, `--closing`, evidence index, entity rows, coverage rows and counts, `--next`, `--help`, the default KB directory, and `--git` with and without a git identity, and `pack-kb.mjs` (zip validated with Python's `zipfile`, private folders left out, `--full`, `--force`) | +| `tests/page-scripts.test.mjs` | Runs the five page scripts in headless Chromium against `tests/fixture.html` with mocked API and WebSocket traffic. Asserts component tags, routes, token-to-variable mapping, endpoint templates, JSON shapes, GraphQL operations, WebSocket frames, masking (including selector rules for elements rendered later, and placeholders), annotation, and that the fake names, emails, IDs and storage values on the test page do not appear in the results | +| `tests/kb-scripts.test.mjs` | Creates a knowledge base with `init-kb.mjs` and checks the main `check-kb.mjs` rules: unresolved references, rules and barriers without evidence, malformed tags, placeholder IDs, duplicates, broken links, `[inf]` without a question, missing "Not tested" sections, ledger validation, `fixture` and `human` rows, `--closing`, evidence index, entity rows, coverage rows and counts, `--next`, `--help`, the default KB directory, and `--git` with and without a git identity, `build-report.mjs` (sections, embedded images, linked IDs, escaped HTML, no scripts), and `pack-kb.mjs` (zip validated with Python's `zipfile`, private folders left out, the ledger kept without IDs, locations or URLs, the unzipped handoff passing `check-kb --closing`, `--full`, `--force`) | To reuse an existing Playwright install instead of `npm install`, set `PLAYWRIGHT_MODULE=/path/to/node_modules/playwright`. diff --git a/package-lock.json b/package-lock.json index 17d3526..8e9ed30 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "res", - "version": "0.2.0", + "version": "0.3.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "res", - "version": "0.2.0", + "version": "0.3.0", "license": "MIT", "devDependencies": { "playwright": "1.64.0" diff --git a/package.json b/package.json index 55b64bc..40c3be4 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "engines": { "node": ">=22" }, - "version": "0.2.0", + "version": "0.3.0", "license": "MIT", "repository": { "type": "git", diff --git a/skills/reverse-engineering-saas/SKILL.md b/skills/reverse-engineering-saas/SKILL.md index 4a151d1..3e0dd4f 100644 --- a/skills/reverse-engineering-saas/SKILL.md +++ b/skills/reverse-engineering-saas/SKILL.md @@ -7,7 +7,7 @@ description: Use when studying a SaaS web product from the outside in order to r ## Overview -The output is a knowledge base (KB) on disk from which a team that never used the product can rebuild it and take it to production, delivered at the end as a zip the user can hand to any coding agent. Two rules are absolute: +The output is a knowledge base (KB) on disk from which a team that never used the product can rebuild it and take it to production. It is delivered as `REPORT.html`, the report a person reads, and a zip the user can hand to any coding agent. Two rules are absolute: 1. **The exploration never damages the user's production data and never reaches a real person.** 2. **Every statement in the KB carries its evidence.** @@ -58,6 +58,8 @@ When the user asked for a test environment and no L1 exists: create L2 if free, At L3, "inside the sandbox" means the container plus records the agent created with the `[RE]` prefix that link only to sandbox records (a person created from a sandbox deal). When other members can see the container, remove all A2 records, the container included, at the end of every session, and in unattended mode finish the teardown before the team's working hours. +An unattended L3 session that starts during the team's working hours (from the charter; otherwise 08:00 to 18:00 on weekdays in the account's time zone) writes only when the team cannot see the records: a private container, or records set to operator-only visibility (`references/safety.md`, L3). The container's name may stay visible. Otherwise do the phases without writes first (recon, map) and put the writes under "Next actions" for a session outside working hours. In both cases keep the sandbox up as briefly as possible and tear it down in the same session. Record the start time and the choice in `environment.md`. + ### Action classes and what each level allows | Class | Examples | @@ -109,20 +111,22 @@ Check persistence by reloading. Never experiment on shared views: rebuild the ca Do not click through. Log the item as `blocked` and move on when you see: billing, upgrade or trial dialogs; any "send", "invite", "notify", "share", "apply to all" or "cannot be undone"; login, 2FA or CAPTCHA prompts; a location mismatch; any change that appears outside the sandbox. +Exception: deleting your own ledger items inside the sandbox. Their delete dialogs often say the action cannot be undone. Confirm when the dialog names only those items, sends or notifies nothing, and the write gate passes. A dialog that would also delete or change anything else is still a stop. + In unattended mode never ask the user. Write the item under "Needs human" in `STATUS.md` and continue. "Don't ask me anything" changes how blocks are reported. It does not widen what you may touch. After a mistake: undo it at once if the undo itself reaches nobody, then add a ledger row with class `incident`, what happened and what remains. If the undo would notify someone again (unassigning, deleting a comment), leave it and write it under "Needs human". Procedure: `references/safety.md`. ### Preflight: before the first write at L2 or L3 -Record in `environment.md`: members who could be notified; active automations, webhooks, integrations, email and calendar sync in the write scope; plan and trial end date; baseline counts of the main record types. If any automation, webhook, integration or sync would fire on records in the write scope, do not write there. Checklist: `references/safety.md`. +Record in `environment.md`: members who could be notified; active automations, webhooks, integrations, email and calendar sync in the write scope; plan and trial end date; baseline counts of the container and of the operator's own records, by filter or count endpoint, never by pulling full record lists. If any automation, webhook, integration or sync would fire on records in the write scope, do not write there. Checklist: `references/safety.md`. ### Data rules - Fake data only. Prefix every created name with `[RE]`. Emails at `example.com`. No real customer or teammate names. - KB text never contains real personal or customer data. When documenting production configuration (field options, automation conditions, filters), replace real values with placeholders such as `[customer]` or `[person]`. - Assign records to the operator or to nobody. -- At L3 and L4, run `scripts/page/mask.js` before each screenshot that can show real data. A screenshot that shows unmasked personal data is deleted at once and retaken; it never enters the KB. +- At L3 and L4, run `scripts/page/mask.js` before each screenshot that can show real data. Pass the containers of popovers, menus and lists as `selectors`: they stay masked when they render later. Company configuration (type names, reasons, field labels) matches no pattern: pass it as `names` or crop it out. A screenshot that shows unmasked personal data is deleted at once and retaken; it never enters the KB. Procedures for each level, the ledger format, teardown and incidents: `references/safety.md`. @@ -172,9 +176,11 @@ Paste the file content into the browser's JavaScript tool. Each script returns J | `scripts/page/inventory.js` | Framework, component tag names, test IDs, ARIA roles, internal route patterns, third-party SDKs | | `scripts/page/tokens.js` | CSS variables and the most frequent colors, type sizes, radii, spacing and shadows | | `scripts/page/api-shapes.js` | Installs a recorder; `__re.api.dump()` returns endpoint templates and JSON shapes; set `__re.api.enumSamples = false` to drop the short enum values too | -| `scripts/page/mask.js` | Blurs emails, phones, money, Brazilian tax IDs, small avatars, given names and given selectors; `__re.mask.clear()` removes it | +| `scripts/page/mask.js` | Blurs emails, phones, money, Brazilian tax IDs, small avatars, given names, matching placeholders, and given selectors as CSS rules that also cover elements rendered later; `__re.mask.clear()` removes it | | `scripts/page/annotate.js` | Numbered outlines on given elements for anatomy screenshots | +To show progress before the end, run `node /scripts/build-report.mjs ` and send `REPORT.html`. + Tool-specific notes (saving screenshots, network, profiles, drag and drop): `references/extraction.md` and `references/tools.md`. ## Close a session @@ -184,7 +190,7 @@ Tool-specific notes (saving screenshots, network, profiles, drag and drop): `ref 3. Write `log/-s.md`. 4. Run `node /scripts/check-kb.mjs ` and fix every error. 5. At the end of the study only: tear down from the ledger, compare baseline counts, list residuals in `STATUS.md`, then run `check-kb --closing`. -6. Hand off: run `node /scripts/pack-kb.mjs ` and send the zip to the user in the chat. Attach it with the agent's file-sending tool when there is one; otherwise give its path. The zip holds the KB and `BUILD.md`, a brief any coding agent can follow, and leaves out `sandbox/` and `log/`. With the zip, send the three-line summary from `STATUS.md`, the "Needs human" list, and one line: "Unzip it and give the folder to a coding agent, starting at BUILD.md." +6. Hand off: run `node /scripts/pack-kb.mjs `. It writes `REPORT.html` (one self-contained page: summary, barriers, build plan, screens, rules, data model, tokens, evidence) and the zip. Send both to the user in the chat, the report first as the main deliverable. Attach them with the agent's file-sending tool when there is one; otherwise give their paths. The zip holds the KB and `BUILD.md`, a brief any coding agent can follow, and leaves out `sandbox/` and `log/` except a copy of the ledger without object IDs, locations or URLs. With them, send the three-line summary from `STATUS.md`, the "Needs human" list, and one line: "Open REPORT.html to read the study; unzip the zip and give the folder to a coding agent, starting at BUILD.md." The study ends when coverage is complete or the user says to stop. When the user stops early, write the Phase 6 files from what exists, close, and pack: `STATUS.md` tells the reader what is missing. At L1 the trial account may keep its fixtures as `kept` ("trial kept for the developers"); ending the trial is the user's action. `pack-kb` runs the regular check, so rows marked `human` do not block the handoff; list them under "Needs human". diff --git a/skills/reverse-engineering-saas/references/extraction.md b/skills/reverse-engineering-saas/references/extraction.md index 6f00f69..b2904c6 100644 --- a/skills/reverse-engineering-saas/references/extraction.md +++ b/skills/reverse-engineering-saas/references/extraction.md @@ -4,7 +4,9 @@ Read the script file and pass its full content to the browser's JavaScript tool (`javascript_tool`, `browser_evaluate`, `evaluate_script`). Each script attaches functions to `window.__re` and returns a JSON-serializable result. Save the result as `evidence/EV-###- as text\n- Evidence: [obs EV-001]\n'); + appendFileSync(join(kb, 'clone/barriers.md'), '\n### BR-001 Example barrier\n- Severity: blocks launch (until approved)\n- Evidence: [doc SRC-001]\n'); + appendFileSync(join(kb, 'sources.md'), '| SRC-001 | Docs | https://example.com/docs | docs | 2026-10-16 | x |\n'); + const result = run('build-report.mjs', kb); + assert.equal(result.status, 0, result.stderr); + const html = readFileSync(join(kb, 'REPORT.html'), 'utf8'); + assert.match(html, /Acme CRM: reverse engineering report<\/title>/); + for (const id of ['summary', 'barriers', 'screens', 'rules', 'evidence', 'S-001', 'R-001', 'BR-001', 'EV-001', 'EV-002', 'F-001', 'SRC-001']) { + assert.match(html, new RegExp(`id="${id}"`), `anchor ${id}`); + } + assert.match(html, /<a href="#R-001">R-001<\/a>/); + assert.match(html, /<img src="data:image\/png;base64,/); + assert.equal((html.match(/data:image\/png;base64,/g) || []).length, 1, 'each image is embedded once'); + assert.match(html, /<span class="chip red">blocks launch<\/span> \(until approved\)/); + assert.match(html, /<span class="chip amber">blocked: drag<\/span>/); + assert.match(html, /<ul><li>Item<ul><li>Nested item<\/li><\/ul><\/li>/); + assert.match(html, /<script>alert\(1\)<\/script>/); + assert.doesNotMatch(html, /<script|<link|https?:\/\/[^"]*\.(js|css)/i, 'no scripts or external resources'); + assert.equal(run('build-report.mjs', '--help').status, 0); + + const out = join(dir, 'report.zip'); + assert.equal(run('pack-kb.mjs', kb, '--out', out).status, 0); + assert.ok(readZip(out).names.includes('re-acme/REPORT.html')); }); test('pack-kb refuses a KB with errors unless --force', () => { diff --git a/tests/page-scripts.test.mjs b/tests/page-scripts.test.mjs index 1ff4a89..d240203 100644 --- a/tests/page-scripts.test.mjs +++ b/tests/page-scripts.test.mjs @@ -147,6 +147,43 @@ test('mask blurs personal data and clear removes it', async () => { assert.equal(await page.evaluate(() => document.querySelectorAll('.__re-masked').length), 0); }); +test('mask rules cover elements rendered later, and placeholders', async () => { + await page.evaluate(script('mask.js')); + const result = await page.evaluate(() => { + const field = document.createElement('input'); + field.id = 'owner'; + field.placeholder = 'maria@cliente.com.br'; + document.querySelector('main').append(field); + return window.__re.mask.apply({ selectors: ['.popover', '..bad'] }); + }); + assert.equal(result.byReason['placeholder email'], 1); + assert.deepEqual(result.invalidSelectors, ['..bad']); + assert.deepEqual(result.rules, { selectors: 1, placeholders: false }); + const placeholderColor = (id) => page.evaluate((target) => getComputedStyle(document.getElementById(target), '::placeholder').color, id); + assert.equal(await placeholderColor('owner'), 'rgba(0, 0, 0, 0)'); + + // The .popover rule from the first call stays; placeholders: true adds a rule for every placeholder. + await page.evaluate(() => window.__re.mask.apply({ placeholders: true })); + const popoverFilter = await page.evaluate(() => { + const popover = document.createElement('div'); + popover.className = 'popover'; + popover.textContent = 'Lost reason: [customer] churned'; + const later = document.createElement('input'); + later.id = 'later'; + later.placeholder = 'Activity type: Visit'; + document.body.append(popover, later); + return getComputedStyle(popover).filter; + }); + assert.match(popoverFilter, /blur/, 'a popover rendered after apply() is blurred'); + assert.equal(await placeholderColor('later'), 'rgba(0, 0, 0, 0)'); + + await page.evaluate(() => window.__re.mask.clear()); + assert.equal(await page.evaluate(() => getComputedStyle(document.querySelector('.popover')).filter), 'none'); + assert.notEqual(await placeholderColor('later'), 'rgba(0, 0, 0, 0)'); + assert.deepEqual(await page.evaluate(() => window.__re.mask.rules), { selectors: [], placeholders: false }); + await page.evaluate(() => document.querySelectorAll('#owner, #later, .popover').forEach((element) => element.remove())); +}); + test('annotate outlines regions and reports missing selectors', async () => { await page.evaluate(script('annotate.js')); const result = await page.evaluate(() => window.__re.annotate(['header', 'main', '.missing']));