@tayo-dev/rtl 1.3.1 → 1.4.1

package/assets/codex/@tayo-dev/rtl-generate/references/state-schema.md

@@ -0,0 +1,119 @@
+# Unified State Schema
+
+Stored at:
+.tayo/state.json
+
+Purpose:
+Persistent, self-evolving knowledge graph of the repository and Tayo runs.
+
+Rules:
+- Must remain project-agnostic.
+- Must never store secrets.
+- Must store evidence and confidence for learned signals.
+- Must remain bounded in size.
+
+---
+
+## Storage Limits
+
+Recommended caps:
+
+* conventions evidence per signal: 50
+* sampledFiles per scan: 50
+* surface scan files per run: 5
+* generatedTests entries: 200 (rotate oldest)
+* auth recipes: 10 (keep by scope recency)
+
+---
+
+## Schema
+
+```jsonc
+{
+  "version": 1,
+
+  "meta": {
+    "createdAt": "ISO-8601",
+    "updatedAt": "ISO-8601",
+    "tayoVersion": "string"
+  },
+
+  "conventions": {
+    "signals": {}
+  },
+
+  "auth": {
+    "recipes": []
+  },
+
+  "mockStore": {
+    "rootDir": "string | null",
+    "importHint": "string | null",
+    "resources": [
+      { "name": "string", "file": "string", "exports": ["string"], "updatedAt": "ISO-8601" }
+    ]
+  },
+
+  "generatedTests": [
+    {
+      "recordingHash": "sha256:...",
+      "recordingUrl": "string",
+      "sourceFile": "string",
+      "testFile": "string",
+      "dependencies": { "apiCalls": ["string"], "hooks": ["string"] },
+      "quality": {
+        "overall": 0,
+        "grade": "F|D|C|B|A",
+        "dimensions": {
+          "robustness": 0,
+          "readability": 0,
+          "assertionStrength": 0,
+          "mockFidelity": 0,
+          "maintainability": 0
+        },
+        "signals": {
+          "usesCssSelectors": false,
+          "usesTestId": false,
+          "usesRoleQueries": false,
+          "hasMeaningfulAssertions": false,
+          "hasDeterministicFixtures": false,
+          "hasProviderWrapper": false,
+          "hasUiLibraryReimplementation": false
+        },
+        "reasons": [
+          { "dimension": "string", "delta": 0, "reason": "string" }
+        ]
+      },
+      "verification": {
+        "mockAudit": {
+          "forbiddenReimplementations": ["string"],
+          "allowedBoundaryMocks": ["string"]
+        },
+        "checkpoint": {
+          "status": "none|approval_required",
+          "reason": "string|null",
+          "blockedWrites": false
+        }
+      },
+      "discovery": {
+        "surfaceScan": {
+          "count": 0,
+          "selectedFiles": ["string"],
+          "skippedExpansions": ["string"],
+          "limitedByBudget": false
+        }
+      },
+      "createdAt": "ISO-8601"
+    }
+  ]
+}
+```
+
+---
+
+## Checkpoint Write Rule
+
+When `verification.checkpoint.status` is `approval_required`:
+
+- Tayo must not append a new generatedTests history entry.
+- Tayo must output checkpoint details and stop write operations for generated tests/state history.

package/assets/codex/@tayo-dev/rtl-generate/references/test-index.md

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "generated": [
+    {
+      "recording_hash": "sha256:...",
+      "recording_url": "...",
+      "source_file": "...",
+      "test_file": "...",
+      "created_at": "ISO-8601"
+    }
+  ]
+}

package/assets/codex/@tayo-dev/rtl-generate/references/verification-gate.md

@@ -0,0 +1,93 @@
+# Verification Gate
+
+Goal:
+Prevent Tayo from claiming success unless the generated test is demonstrably runnable
+and compliant with mock-boundary policy.
+
+Rules:
+
+- Prefer running real project commands if they can be detected.
+- If commands cannot be detected, run minimal checks and clearly log limitations.
+- Always run static mock audit before runtime checks.
+
+---
+
+## Static Mock Audit (Required)
+
+Run an AST/text audit on the generated test before typecheck/test/lint.
+
+Detect:
+
+- `vi.mock(...)` / `jest.mock(...)` blocks that replace UI-library modules
+  (for example design-system packages such as `@digitax/components`).
+- Broad object-return replacement patterns that provide custom component
+  implementations for UI libraries.
+
+Allowed:
+
+- boundary-safe targets: data/auth/router/env/local-child modules.
+
+If forbidden replacement is detected:
+
+- set checkpoint status to `approval_required`
+- set `blockedWrites = true`
+- record offending targets in `verification.mockAudit.forbiddenReimplementations`
+- do not write generated test file
+- do not mutate `.tayo/state.json` generated-test history
+- output:
+  - violation reason
+  - exact offending target(s)
+  - minimal alternatives attempted/available
+
+---
+
+## Preferred Checks (in order)
+
+1. Static mock audit (required)
+2. Typecheck (if tsconfig exists and command discoverable)
+3. Run test for the generated file (framework-aware)
+4. Lint the generated file (eslint if available)
+
+---
+
+## Command Detection (project-agnostic heuristics)
+
+Tayo may attempt to infer commands by checking:
+
+- package.json scripts (if readable/locatable)
+- presence of vitest/jest dependencies in lockfiles or package manifests
+
+If no reliable detection:
+
+- Log: `Verification commands not detected; minimal validation only.`
+- Minimal validation must include:
+  - file can be imported
+  - no syntax errors
+  - TypeScript types are not obviously invalid (best-effort)
+
+---
+
+## Repair Pass (single iteration only)
+
+If verification fails:
+
+- apply one repair attempt:
+  - switch getByRole → findByRole for async
+  - add missing await for userEvent
+  - fix obvious import alias mismatch based on conventions signals
+  - add lightweight env polyfill for browser gaps (for example `ResizeObserver`)
+- rerun verification once
+
+Never loop indefinitely.
+Never claim success if still failing.
+
+---
+
+## Output Contract
+
+- `Verification: Passed` only if all required checks pass and no checkpoint is active.
+- `Verification: Failed` if runtime checks fail or checkpoint is active.
+- If checkpoint is active, output must include:
+  - `Checkpoint: approval_required`
+  - `Blocked writes: true`
+  - violation reason and offending targets.

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

@@ -1,12 +1,10 @@
 ---
 name: "@tayo-dev/rtl-help"
-description: "Show the packaged Tayo Codex skill surface and the expected help entrypoint."
+description: "Route Codex users to the correct packaged Tayo skill and explain the installed Codex entrypoints. Use when the user asks how to use Tayo in Codex, which Tayo skill to invoke, whether installation worked, or whether they need generate, conventions, or mocks guidance."
 ---
 
 # 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`.
@@ -17,9 +15,25 @@ Invoke this skill with `$@tayo-dev/rtl-help`.
 - `$@tayo-dev/rtl-conventions` for convention-aware generation guidance
 - `$@tayo-dev/rtl-mocks` for mock and fixture review
 
+## Routing guide
+
+- Use `$@tayo-dev/rtl-generate` when the user already has a Testing Library Recorder `.js` export and wants a test generated.
+- Use `$@tayo-dev/rtl-conventions` when the user asks why generated output follows a certain style, file location, import pattern, or helper setup.
+- Use `$@tayo-dev/rtl-mocks` when the generated test needs API, router, auth, fixture, or provider boundary guidance.
+
 ## 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.
+1. Confirm whether the user needs generation, convention diagnosis, or mock guidance.
+2. Ask for the recording path or generated test path only if that input is still missing.
+3. Choose the matching packaged Tayo skill.
+4. For generation, use `$@tayo-dev/rtl-generate`. Tayo writes `{recording-name}.test.tsx` next to the `.js` recording and refuses to overwrite an existing file.
+5. Report the generated file path if generation ran, the score, and blockers that still require manual cleanup.
+
+## Response contract
+
+Return:
+
+- the correct Tayo skill or runtime entrypoint
+- the next runtime action to take
+- any missing input required before proceeding
+- any blocker that prevents safe generation or review

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

@@ -1,22 +1,68 @@
 ---
 name: "@tayo-dev/rtl-mocks"
-description: "Review mock targets, fixture shape, and post-generation follow-up for Tayo output."
+description: "Review mock targets, provider boundaries, fixture shape, and post-generation follow-up for Tayo output. Use when a generated RTL test needs API mocking, router/auth/context setup, fixture guidance, or when the user asks why Tayo suggested certain mocks."
 ---
 
 # Tayo Mocks
 
-Use `$@tayo-dev/rtl-mocks` when the user needs help understanding mock recommendations or fixture strategy around generated RTL tests.
+Invoke this skill with `$@tayo-dev/rtl-mocks`.
 
-## Focus
+## Boundary Review Workflow
 
-- 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
+1. Identify the external boundaries the generated test crosses.
+2. Keep only the minimum mocks needed to make the user flow deterministic.
+3. Align with the repo's existing mock stack before proposing new patterns.
+4. Decide whether each mock should stay inline or move into a shared fixture or helper.
 
-## Output
+## Inline vs Extract Decision
+
+- **Same mock target in 1 test file** → keep inline (`vi.mock` in module scope of that file)
+- **Same mock target in 2+ test files** → extract to a shared fixture or `__mocks__` factory
+- **Provider wrappers** (router, auth, query client) → always extract to a shared render helper
+
+## Mock Instability Patterns to Fix
+
+Tayo detects and flags two instability patterns:
+
+**`recreated-factory`** — `vi.mock()` or `jest.mock()` is declared inside `it()`/`test()` bodies. This recreates the module factory on every test run and produces inconsistent state.
+- Fix: move `vi.mock('...')` to module scope (outside all test callbacks).
+
+**`per-test-churn`** — `clearAllMocks`/`resetAllMocks` is called repeatedly alongside many `mockReturnValue`/`mockResolvedValue` calls, which means mock configuration is torn down and rebuilt per test.
+- Fix: consolidate shared mock state in `beforeEach`, use `mockReturnValueOnce` for per-test overrides only.
+
+## Mutation Lifecycle Coverage
+
+When the recorded flow involves a mutation (submit, save, create, update, delete), the generated test should cover all three stages:
+
+| Stage | What to assert | Mock setup |
+|-------|----------------|------------|
+| `loading` | Submit button is disabled, spinner/pending indicator visible | Before `mockResolvedValue` resolves |
+| `success` | Success message, redirect, or updated value visible | `mockResolvedValue(...)` |
+| `error` | `role="alert"` error message visible | `mockRejectedValue(new Error(...))` |
+
+If only one or two stages are present in the generated output, explain what the missing stages should assert.
+
+## Common Boundaries
+
+- network and data-fetching clients (fetch, axios, React Query, SWR, tRPC)
+- router and navigation hooks (`useRouter`, `useNavigate`)
+- auth or session providers (`useAuth`, `useSession`)
+- feature flags and runtime config
+- time, randomness, and browser APIs (`Date.now`, `Math.random`, `localStorage`)
+
+## Guardrails
+
+- do not invent API shapes, endpoints, or fixture payloads without evidence from the repo
+- prefer existing fixtures, factories, and render wrappers over new one-off helpers
+- call out provider requirements separately from pure data mocks
+- separate blocking mock requirements from optional cleanup
+
+## Output Contract
 
 Summarize:
 
-- the mock targets that matter
-- the preferred mocking pattern
+- the mock targets that matter and whether each should be inline or extracted
+- which instability patterns were detected and the specific fix
+- whether mutation lifecycle coverage is complete or which stages are missing
+- the fixture shape or shared helper to reuse
 - any manual follow-up still required after generation

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

@@ -1,10 +1,32 @@
-description = "Generate RTL tests from Recorder exports with Taro"
+description = "Generate RTL tests from Recorder exports with Tayo"
 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.
+Generate a React Testing Library test from a Testing Library Recorder JS export.
+
+Process:
+1. Confirm the recording file path and extension (.js only).
+2. Tayo writes {recording-name}.test.tsx next to the recording. If that file already exists, stop and tell the user to rename or delete it before rerunning generation.
+3. Run `tayo __generate <recording-file>`.
+4. Parse the score and work through any required manual fixes.
+
+Scoring dimensions (Grade: A>=90, B>=80, C>=70, D>=60, F<60; below 80 or QUAL-02 failure = manual review required):
+- Query (30%): getByRole > getByLabelText > getByText > getByPlaceholderText > getByTestId. Each tayo-query-checkpoint: comment deducts 3pts (cap -40).
+- Assertions (25%): toHaveValue/toBeChecked/toHaveTextContent/toBeVisible = full credit. toBeInTheDocument = 30% credit. No assertions = 0.
+- Structure (20%): render(<App />) -25, tayo-boundary-warning: -20, describe() block +20, each extra it() +15.
+- Boundary (25%): leaf-render-boundary -35, inline-hook-mock -30, helper-embedded-assertion -20, positional-control-selection -15.
+
+Boundary issue fixes:
+- leaf-render-boundary: render the page/module that owns the trigger and dialog lifecycle, not the *Form/*Dialog directly.
+- inline-hook-mock: move use*Query/use*Mutation mocks to a shared fixture or raise the render boundary.
+- helper-embedded-assertion: assertions belong in the it() body; helpers handle setup/navigation only.
+- positional-control-selection: replace getAllByRole(...)[n] with within() scoping or a more specific accessible name.
+
+Post-generation checklist:
+1. Fix render(<App />) — render the narrowest component that owns the flow.
+2. Resolve tayo-query-checkpoint: comments — apply the query hierarchy above.
+3. Upgrade toBeInTheDocument() — use toHaveTextContent(), toHaveValue(), or toBeVisible().
+4. Fix tayo-boundary-warning: comments per the boundary issue fixes above.
+
+Report: command run, generated file path, score + grade, manual review status, top blockers, and which checklist steps apply with specific guidance.
 """

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

@@ -5,7 +5,7 @@ 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.
+3. For generation, direct them to /@tayo-dev/rtl:generate with a Testing Library Recorder `.js` export.
+4. Tell them Tayo writes `{recording-name}.test.tsx` next to the recording and will not overwrite an existing file.
 5. When generation runs, report the score and generated file path.
 """

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

@@ -1,11 +1,37 @@
 ---
-description: Generate RTL tests from Recorder exports with Taro
+description: Generate RTL tests from Recorder exports with Tayo
 ---
 
 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.
+Generate a React Testing Library test from a Testing Library Recorder JS export.
+
+## Process
+
+1. Confirm the recording file path and extension (`.js` only).
+2. Tayo writes `{recording-name}.test.tsx` next to the recording. If that file already exists, stop and tell the user to rename or delete it before rerunning generation.
+3. Run `tayo __generate <recording-file>`.
+4. Parse the score output and work through any required manual fixes.
+
+## Scoring
+
+Tayo scores on four weighted dimensions. Grade: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F < 60. Score below 80 or QUAL-02 failure → "Manual review required".
+
+**Query (30%):** `getByRole` = best, `getByLabelText` = good, `getByText` = fine, `getByPlaceholderText` = fallback, `getByTestId` = last resort. Each `tayo-query-checkpoint:` comment deducts 3pts.
+
+**Assertions (25%):** `toHaveValue`/`toBeChecked`/`toHaveTextContent`/`toBeVisible` = full credit. `toBeInTheDocument` = 30% credit.
+
+**Structure (20%):** `render(<App />)` −25, `tayo-boundary-warning:` −20. `describe()` block +20.
+
+**Boundary (25%):** `leaf-render-boundary` −35, `inline-hook-mock` −30, `helper-embedded-assertion` −20, `positional-control-selection` −15.
+
+## Post-Generation Checklist
+
+1. Fix `render(<App />)` — render the narrowest component that owns the flow.
+2. Resolve `// tayo-query-checkpoint:` comments — apply the query hierarchy above.
+3. Upgrade `toBeInTheDocument()` — use `toHaveTextContent()`, `toHaveValue()`, or `toBeVisible()`.
+4. Fix `tayo-boundary-warning:` — see boundary penalties for specific fixes.
+
+## Response
+
+Report: command run, generated file path, score + grade, manual review status, top blockers, and which checklist steps apply.

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

@@ -7,6 +7,6 @@ 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.
+3. For generation, direct them to `/@tayo-dev/rtl-generate` with a Testing Library Recorder `.js` export.
+4. Tell them Tayo writes `{recording-name}.test.tsx` next to the recording and will not overwrite an existing file.
 5. When generation runs, report the score and generated file path.

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

@@ -1,13 +1,7 @@
 /**
  * Generate command
- * Full pipeline: parse → validate → generate → write
- * Converts Recorder exports into React Testing Library test files.
+ * Internal runtime-only generation pipeline for Testing Library Recorder JS exports.
  */
 import { Command } from 'commander';
-export interface GenerateOptions {
-    output?: string;
-    dryRun?: boolean;
-    force?: boolean;
-}
 export declare function createGenerateCommand(): Command;
 //# sourceMappingURL=generate.d.ts.map

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;AA+CnC,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AA2lBD,wBAAgB,qBAAqB,IAAI,OAAO,CAqL/C"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA44BnC,wBAAgB,qBAAqB,IAAI,OAAO,CAmK/C"}