@tayo-dev/rtl 1.0.0 → 1.3.0-alpha.0

package/README.md

@@ -1,85 +1,133 @@
 # Taro
 
-Generate React Testing Library tests from Chrome Recorder recordings — automatically.
+Install Taro into Claude Code, OpenCode, Gemini CLI, or Codex, then generate React Testing Library tests from Testing Library Recorder recordings.
 
-## Introduction
+Taro ships as an installer-first package. The package entrypoint bootstraps runtime-native commands or skills into your agent environment, and the generated runtime surface still routes back to `taro generate` when you want Recorder-to-RTL output.
 
-Taro is a CLI tool that reads Chrome DevTools Recorder exports (JSON) and Testing Library Recorder JS files and generates RTL test files. It scores its own output, learns your project's test conventions from existing files, and stores per-project state in a local `.taro/` directory. No server, no cloud — just files.
+## Getting Started
 
-### Who it is for
+```bash
+npx @tayo-dev/rtl@latest
+```
 
-- React developers who write tests with `@testing-library/react`
-- Developers who use Chrome DevTools Recorder to capture user flows
-- Teams that want test coverage without spending hours writing boilerplate
+The installer prompts you to choose:
 
-### The problem it solves
+1. **Runtime** — Claude Code, OpenCode, Gemini CLI, Codex, or all
+2. **Location** — Global (all projects) or local (current project only)
 
-Recording a user flow in Chrome takes 30 seconds. Translating that recording into a well-structured RTL test takes 20–40 minutes and requires knowing which queries to use, how to assert, and how to match your project's test conventions. Taro closes that gap.
+Verify the install with the runtime-native help command:
 
-### How it works
+- Claude Code: `/@tayo-dev/rtl:help`
+- Gemini CLI: `/@tayo-dev/rtl:help`
+- OpenCode: `/@tayo-dev/rtl-help`
+- Codex: `$@tayo-dev/rtl-help`
 
-1. Record a user flow in Chrome DevTools → Recorder panel.
-2. Export via the Testing Library Recorder extension (`.js`) or as native Chrome Recorder JSON (`.json`).
-3. Run `taro generate ./recording.js`.
-4. Taro writes a `.test.tsx` file next to your recording, scored and convention-aware.
+> [!NOTE]
+> Codex installation uses skills under `skills/@tayo-dev/rtl-*/SKILL.md`, not prompt files.
 
-## Quick Start
+## Staying Updated
 
-### Prerequisites
+Re-run the installer package to refresh owned assets and repair missing ones:
 
-- Node.js 18 or later
-- A React project using `@testing-library/react`
-- Chrome DevTools Recorder (built into Chrome — no extension needed for JSON exports)
+```bash
+npx @tayo-dev/rtl@latest
+```
+
+Taro refreshes unchanged owned files automatically, restores missing owned files, and protects manual edits instead of overwriting them silently.
 
-### Step 1 — Install
+## Non-interactive Install
+
+Use runtime flags plus exactly one location flag to skip prompts:
 
 ```bash
-npm install --save-dev @tayo-dev/rtl
-# or use npx to skip install entirely
-npx @tayo-dev/rtl generate ./my-recording.js
+# Claude Code
+npx @tayo-dev/rtl@latest --claude --global
+npx @tayo-dev/rtl@latest --claude --local
+
+# OpenCode
+npx @tayo-dev/rtl@latest --opencode --global
+npx @tayo-dev/rtl@latest --opencode --local
+
+# Gemini CLI
+npx @tayo-dev/rtl@latest --gemini --global
+npx @tayo-dev/rtl@latest --gemini --local
+
+# Codex
+npx @tayo-dev/rtl@latest --codex --global
+npx @tayo-dev/rtl@latest --codex --local
+
+# All runtimes
+npx @tayo-dev/rtl@latest --all --global
+npx @tayo-dev/rtl@latest --all --local
 ```
 
-### Step 2 — Record a user flow
+Local installs write to hidden runtime directories in the current project:
 
-Open Chrome DevTools → Recorder panel → click "Start new recording" → perform your user flow (clicks, form fills, navigation) → click "End recording". Then either:
+- Claude Code: `./.claude/`
+- OpenCode: `./.opencode/`
+- Gemini CLI: `./.gemini/`
+- Codex: `./.codex/`
 
-- Export as JSON: click the export button → "JSON" → save as `recording.json`
-- Export via Testing Library Recorder extension: install the extension, click its export button, save as `recording.js`
+## Development Installation
 
-### Step 3 — Generate the test
+When you want to test the installer from a local checkout instead of the published package:
 
 ```bash
-# Using npx (no install required)
-npx @tayo-dev/rtl generate ./recording.js
+# Build the CLI
+npm run build
+
+# Exercise the installer from the built package entrypoint
+node dist/index.js --all --local
 
-# Or if installed globally
+# Or verify the publish boundary with a tarball
+env NPM_CONFIG_CACHE=/tmp/taro-npm-cache npm pack --pack-destination /tmp/taro-pack
+npx /tmp/taro-pack/tayo-dev-rtl-1.0.0.tgz --codex --local
+```
+
+The tarball flow is the closest match to what end users get from npm.
+
+## Generate RTL Tests
+
+After installation, use `taro generate` directly or call the runtime-native installed command/skill that routes to it.
+
+### Prerequisites
+
+- Node.js 18 or later
+- A React project using `@testing-library/react`
+- Chrome DevTools Recorder with the Testing Library Recorder extension installed
+
+### Record a user flow
+
+Open Chrome DevTools → Recorder panel → click "Start new recording" → perform your user flow → click "End recording". Then export via the Testing Library Recorder extension and save as `recording.js`.
+
+### Generate the test
+
+```bash
 taro generate ./recording.js
 ```
 
 Expected output:
 
-```
+```text
 Parsed: my user flow — 8 steps
 [taro] Score: 78/100 (B) — query: 80, assertions: 70, structure: 85
 Created: src/components/MyComponent.test.tsx
 [taro] ✓ post-write verified
 ```
 
-### What happens next
-
-Taro writes a `.test.tsx` file. On subsequent runs in the same project, it reads `.taro/conventions.json` to match your test style (import style, mock pattern, folder structure) automatically.
+On subsequent runs in the same project, Taro reads `.taro/conventions.json` to match your test style automatically.
 
 ## CLI Reference
 
 ### `taro generate <file>`
 
-Generates a React Testing Library test from a Chrome Recorder export.
+Generates a React Testing Library test from a Testing Library Recorder export.
 
 **Arguments:**
 
 | Argument | Description |
 |----------|-------------|
-| `<file>` | Path to the recording file. Accepts Chrome Recorder JSON exports (`.json`) or Testing Library Recorder JS files (`.js`). |
+| `<file>` | Path to the recording file. Accepts Testing Library Recorder JS files (`.js`). |
 
 **Options:**
 
@@ -95,50 +143,48 @@ Generates a React Testing Library test from a Chrome Recorder export.
 
 ```bash
 # Generate and write a test next to the recording
-taro generate ./recordings/checkout-flow.json
+taro generate ./recordings/checkout-flow.js
 
 # Preview without writing (dry run)
-taro generate --dry-run ./recordings/checkout-flow.json
+taro generate --dry-run ./recordings/checkout-flow.js
 
 # Write to a specific path
-taro generate --output src/__tests__/checkout.test.tsx ./recordings/checkout-flow.json
+taro generate --output src/__tests__/checkout.test.tsx ./recordings/checkout-flow.js
 
 # Overwrite an existing test
-taro generate --force ./recordings/checkout-flow.json
+taro generate --force ./recordings/checkout-flow.js
 ```
 
 **Output file naming:**
-If `--output` is not provided, Taro derives the output path from the input file: `{input-dir}/{input-basename}.test.tsx`. For example, `./recordings/login.json` → `./recordings/login.test.tsx`.
+If `--output` is not provided, Taro derives the output path from the input file: `{input-dir}/{input-basename}.test.tsx`. For example, `./recordings/login.js` → `./recordings/login.test.tsx`.
 
 **Supported input formats:**
-- Chrome Recorder JSON (`.json`) — exported directly from Chrome DevTools Recorder
 - Testing Library Recorder JS (`.js`) — exported via the Testing Library Recorder Chrome extension; detected by `.js` extension or `@jest-environment-options` header
 
 ## Worked Example
 
-### Input: Chrome Recorder export (`login-flow.json`)
-
-Here is a typical Chrome Recorder JSON export capturing a login flow.
-
-```json
-{
-  "title": "login flow",
-  "steps": [
-    { "type": "navigate", "url": "http://localhost:3000/login" },
-    { "type": "click", "selectors": [["aria/Email address"]] },
-    { "type": "change", "value": "user@example.com", "selectors": [["#email"]] },
-    { "type": "click", "selectors": [["aria/Password"]] },
-    { "type": "change", "value": "secret123", "selectors": [["#password"]] },
-    { "type": "click", "selectors": [["aria/Sign in[role=\"button\"]"]] },
-    { "type": "waitForElement", "selectors": [["aria/Welcome back"]] }
-  ]
-}
+### Input: Testing Library Recorder export (`login-flow.js`)
+
+Here is a typical Testing Library Recorder export capturing a login flow.
+
+```js
+import { screen } from '@testing-library/dom'
+import userEvent from '@testing-library/user-event'
+
+test('login flow', async () => {
+  await userEvent.click(screen.getByRole('textbox', { name: 'Email address' }))
+  await userEvent.type(screen.getByRole('textbox', { name: 'Email address' }), 'user@example.com')
+  await userEvent.click(screen.getByRole('textbox', { name: 'Password' }))
+  await userEvent.type(screen.getByRole('textbox', { name: 'Password' }), 'secret123')
+  await userEvent.click(screen.getByRole('button', { name: 'Sign in' }))
+  await userEvent.click(screen.getByText('Welcome back'))
+})
 ```
 
 ### Command
 
 ```bash
-taro generate ./login-flow.json
+taro generate ./login-flow.js
 ```
 
 ### Terminal output
@@ -185,59 +231,11 @@ describe('login flow', () => {
 
 > **Note:** The component import path (`../LoginPage`) is a placeholder. Taro generates a comment in the file indicating where to update it.
 
-## Using Taro as a Claude Code Skill
-
-### Overview
-
-Taro works naturally as a Claude Code skill. You can instruct Claude to run `taro generate` on a recording file and it will generate the test, report the score, and surface any quality hints — all in a single agent turn.
-
-### Option A: Direct invocation (no setup required)
-
-Claude Code can invoke Taro directly using the Bash tool. No skill configuration is needed — Claude calls npx inline. Simply give Claude a prompt like:
-
-```
-Run: npx @tayo-dev/rtl generate ./recordings/checkout-flow.js
-Then report the score and the path of the generated file.
-```
-
-### Option B: Register as a Claude Code skill
-
-Registering Taro as a skill lets Claude invoke it by name without knowing the full command.
+## Agent Usage
 
-**Step 1** — Create the skill file at `.claude/skills/taro/SKILL.md` in your project:
-
-```markdown
-# Taro — RTL Test Generator
-
-## Purpose
-Generate a React Testing Library test from a Chrome Recorder export.
-
-## Invocation
-Run: taro generate <recording-file>
-
-## Flags
-- `--dry-run` (-d): Preview the generated test without writing to disk
-- `--output <path>` (-o): Override the output file path
-- `--force` (-f): Overwrite an existing test file
-
-## Output
-Writes `{recording-name}.test.tsx` next to the recording file.
-Reports score (0-100) and any quality hints.
-```
-
-**Step 2** — Ensure Taro is installed in the project:
-
-```bash
-npm install --save-dev @tayo-dev/rtl
-```
-
-**Step 3** — Ask Claude to use the skill:
-
-```
-Use the taro skill to generate a test from ./recordings/login-flow.js
-```
+After installation, each runtime gets a namespaced help entrypoint plus a generate command or skill that routes back to `taro generate`.
 
-### Tips for agent use
+### Tips
 
 - Use `--dry-run` first to preview output before committing generated files
 - If you record multiple flows, run Taro on each to build up convention state in `.taro/conventions.json` — later runs benefit from earlier ones

package/assets/claude/commands/@tayo-dev/rtl/generate.md

@@ -0,0 +1,15 @@
+---
+name: "@tayo-dev/rtl:generate"
+description: "Generate RTL tests from Recorder exports with Taro"
+---
+
+<objective>
+Generate a React Testing Library test from a Recorder export.
+</objective>
+
+<process>
+1. Confirm the recording path before running anything destructive.
+2. Run `taro generate <recording-file>` by default.
+3. Add `--dry-run`, `--output <path>`, or `--force` only when the user asks for them or the context requires them.
+4. Report the generated file path and score output.
+</process>

package/assets/claude/commands/@tayo-dev/rtl/help.md

@@ -0,0 +1,16 @@
+---
+name: "@tayo-dev/rtl:help"
+description: "Show @tayo-dev/rtl install and generation help"
+---
+
+<objective>
+Help the user install and use @tayo-dev/rtl from Claude Code.
+</objective>
+
+<process>
+1. Explain that `/@tayo-dev/rtl:help` is the installed help entrypoint for @tayo-dev/rtl.
+2. For installation or updates, tell the user to run `npx @tayo-dev/rtl@latest`.
+3. For test generation, use `/@tayo-dev/rtl:generate` or run `taro generate <recording-file>`.
+4. Mention `--dry-run`, `--output <path>`, and `--force` only when they fit the request.
+5. When generation runs, report the score and generated file path.
+</process>

package/assets/codex/@tayo-dev/rtl-conventions/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: "@tayo-dev/rtl-conventions"
+description: "Explain how Tayo learns project test conventions and how to keep them stable."
+---
+
+# Tayo Conventions
+
+Use `$@tayo-dev/rtl-conventions` when the user asks why generated tests follow a certain style or how `.taro/conventions.json` affects output.
+
+## Focus
+
+- explain that Tayo learns local test conventions from the codebase
+- call out when `.taro/conventions.json` will influence generated imports, mocks, and file placement
+- recommend `--dry-run` when the user wants to inspect convention alignment before writing files
+
+## Guardrails
+
+- prefer existing project conventions over generic defaults
+- surface missing context instead of inventing project-specific patterns

package/assets/codex/@tayo-dev/rtl-generate/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: "@tayo-dev/rtl-generate"
+description: "Generate React Testing Library tests from Recorder exports with Tayo."
+---
+
+# Tayo Generate
+
+Use `$@tayo-dev/rtl-generate` when the user wants to turn a Recorder export into a React Testing Library test.
+
+## Inputs
+
+- path to the recording file
+- optional `--output <path>`
+- optional `--dry-run`
+- optional `--force`
+
+## Execution
+
+Run `taro generate <recording-file>` with the requested flags.
+
+## Response contract
+
+Report:
+
+- the generated test path
+- the Tayo score
+- any follow-up work required to fix component imports or flaky selectors

package/assets/codex/@tayo-dev/rtl-help/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: "@tayo-dev/rtl-help"
+description: "Show the packaged Tayo Codex skill surface and the expected help entrypoint."
+---
+
+# Tayo Codex Help
+
+Use this skill when you need the Codex-facing entrypoint for Tayo or you need to route the user to the right packaged skill.
+
+## Entrypoint
+
+Invoke this skill with `$@tayo-dev/rtl-help`.
+
+## Installed skill surface
+
+- `$@tayo-dev/rtl-generate` for Recorder-to-RTL generation
+- `$@tayo-dev/rtl-conventions` for convention-aware generation guidance
+- `$@tayo-dev/rtl-mocks` for mock and fixture review
+
+## Default workflow
+
+1. Confirm the recording path or test target.
+2. Choose the matching packaged Tayo skill.
+3. If direct CLI execution is appropriate, run `taro generate <recording-file>` with any requested flags.
+4. Report the generated file path, score, and any blocking issues.

package/assets/codex/@tayo-dev/rtl-mocks/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: "@tayo-dev/rtl-mocks"
+description: "Review mock targets, fixture shape, and post-generation follow-up for Tayo output."
+---
+
+# Tayo Mocks
+
+Use `$@tayo-dev/rtl-mocks` when the user needs help understanding mock recommendations or fixture strategy around generated RTL tests.
+
+## Focus
+
+- identify the API or data boundaries that need mocks
+- explain whether the mock should stay inline or move to a shared fixture
+- keep recommendations aligned with the project's current test stack
+
+## Output
+
+Summarize:
+
+- the mock targets that matter
+- the preferred mocking pattern
+- any manual follow-up still required after generation

package/assets/gemini/commands/@tayo-dev/rtl/generate.toml

@@ -0,0 +1,10 @@
+description = "Generate RTL tests from Recorder exports with Taro"
+prompt = """
+You are the installed /@tayo-dev/rtl:generate command for @tayo-dev/rtl.
+
+Generate a React Testing Library test from a Recorder export.
+1. Confirm the recording path before running anything destructive.
+2. Run `taro generate <recording-file>` by default.
+3. Add `--dry-run`, `--output <path>`, or `--force` only when the user asks for them or the context requires them.
+4. Report the generated file path and score output.
+"""

package/assets/gemini/commands/@tayo-dev/rtl/help.toml

@@ -0,0 +1,11 @@
+description = "Show @tayo-dev/rtl install and generation help"
+prompt = """
+You are the installed /@tayo-dev/rtl:help command for @tayo-dev/rtl.
+
+When the user wants help:
+1. Explain that /@tayo-dev/rtl:help is the runtime-native help entrypoint.
+2. For installation or updates, tell them to run `npx @tayo-dev/rtl@latest`.
+3. For generation, direct them to /@tayo-dev/rtl:generate or `taro generate <recording-file>`.
+4. Mention `--dry-run`, `--output <path>`, and `--force` only when they match the request.
+5. When generation runs, report the score and generated file path.
+"""

package/assets/opencode/commands/@tayo-dev/rtl-generate.md

@@ -0,0 +1,11 @@
+---
+description: Generate RTL tests from Recorder exports with Taro
+---
+
+You are the installed `/@tayo-dev/rtl-generate` command for `@tayo-dev/rtl`.
+
+Generate a React Testing Library test from a Recorder export.
+1. Confirm the recording path before running anything destructive.
+2. Run `taro generate <recording-file>` by default.
+3. Add `--dry-run`, `--output <path>`, or `--force` only when the user asks for them or the context requires them.
+4. Report the generated file path and score output.

package/assets/opencode/commands/@tayo-dev/rtl-help.md

@@ -0,0 +1,12 @@
+---
+description: Show @tayo-dev/rtl install and generation help
+---
+
+You are the installed `/@tayo-dev/rtl-help` command for `@tayo-dev/rtl`.
+
+When the user wants help:
+1. Explain that `/@tayo-dev/rtl-help` is the runtime-native help entrypoint.
+2. For installation or updates, tell them to run `npx @tayo-dev/rtl@latest`.
+3. For generation, direct them to `/@tayo-dev/rtl-generate` or `taro generate <recording-file>`.
+4. Mention `--dry-run`, `--output <path>`, and `--force` only when they match the request.
+5. When generation runs, report the score and generated file path.

package/dist/cli/commands/generate.d.ts

@@ -1,7 +1,7 @@
 /**
  * Generate command
  * Full pipeline: parse → validate → generate → write
- * Converts Chrome Recorder exports into React Testing Library test files.
+ * Converts Recorder exports into React Testing Library test files.
  */
 import { Command } from 'commander';
 export interface GenerateOptions {

package/dist/cli/commands/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAwCnC,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAiQD,wBAAgB,qBAAqB,IAAI,OAAO,CA4P/C"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAyCnC,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAsUD,wBAAgB,qBAAqB,IAAI,OAAO,CA0H/C"}