tamash-playwright 0.11.0-beta.8 → 0.11.0

package/.env.example

@@ -60,7 +60,7 @@ OLLAMA_API_KEY=
 # In other CI systems: set GITHUB_TOKEN (or COPILOT_GITHUB_TOKEN) to a PAT with "Copilot Requests".
 # COPILOT_SUBSCRIPTION_MODEL=mai-code-1-flash-picker
 
-# --- Cursor subscription (LOCAL DEVELOPMENT ONLY -- @beta) ---
+# --- Cursor subscription (LOCAL DEVELOPMENT ONLY -- experimental, prefer kiro/codex) ---
 # Requires: the `agent` CLI installed (curl https://cursor.com/install -fsS | bash) and signed in
 # via `agent login` (or CURSOR_API_KEY). Runs `agent -p --trust --mode ask --output-format json` --
 # `--mode ask` is Cursor's read-only Q&A mode, so a heal call can't edit files or run commands.

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); dates are when each version was published.
 
-## [0.11.0] - 2026-08-28
+## [0.11.0] - 2026-08-31
 
 ### Fixed
 
@@ -100,8 +100,8 @@ All notable changes to this project are documented here. Format loosely follows
   is an interactive assistant rather than a one-shot completion endpoint — given the heal prompt it
   often answers conversationally instead of with the required JSON, so the heal is declined more
   often than with `kiro`/`codex`. It's now invoked in the safest/best-effort form
-  (`agent -p --trust --mode ask --output-format json`, read-only) and still ships `@beta`; the docs
-  note `kiro`/`codex` are the steadier local-subscription options. Report issues if you hit them.
+  (`agent -p --trust --mode ask --output-format json`, read-only) and is marked **experimental**;
+  the docs point to `kiro`/`codex` as the steadier local-subscription options. Report issues.
   Also: the full e2e healing suite (12 tests) was run end to end against `copilot-subscription` and
   `ollama` — **12/12 each** — to confirm the parser rewrite and provider changes don't regress it.
 

package/README.md

@@ -190,7 +190,7 @@ A no-op if `copilot-subscription` was never used, so it's safe to add unconditio
 
 ### Using a Cursor, Kiro, or Codex subscription — local development only
 
-Three more subscription-based providers, all `@beta` and **local-development-only, never recommended for CI**, extending the same "use what you're already paying for" idea. Try them and open an issue if one misbehaves.
+Three more subscription-based providers, all **local-development-only, never recommended for CI**, extending the same "use what you're already paying for" idea. `kiro-subscription` and `codex-subscription` are verified healing real broken locators; `cursor-subscription` is experimental (see the note below).
 
 **Cursor** — needs the `agent` CLI (`curl https://cursor.com/install -fsS | bash`) and `agent login` (or `CURSOR_API_KEY`):
 

package/RELEASE-TESTING.md

@@ -17,7 +17,7 @@ currently covered · N/A not applicable to that column.
 | Core action healing (click/fill/check/selectOption/etc.) | Any wrapped Playwright action retries against a healed locator on failure. | ✅ Extensive unit + e2e coverage (many repro specs) | ✅ Every CI run exercises this against the sample repos' own broken locators |
 | Master on/off switch (`HEALER_ENABLED=false`) | A broken locator fails exactly like vanilla Playwright when healing is off; a working locator is unaffected either way. | ✅ Permanent e2e (`healing-disabled.e2e.spec.ts`) — **found with zero coverage anywhere in this repo, ever, until asked directly whether "with and without AI healing" had actually been tested** | ❌ Neither CI workflow runs with healing disabled (`apply-heals`'s own verification step does, but only to confirm an already-applied fix works standalone — not the same as testing a genuinely broken locator with healing off) |
 | `.describe()` context | Human-readable label chained onto a locator, used as the AI's primary description. | ✅ Used throughout the test suite | ✅ Both sample repos' tests use it |
-| Automatic variable-name description fallback | `extractVariableName` (raw identifier) + `decodeVariableName` (decoded phrase + type hint) when `.describe()` isn't called. | ✅ 10+10 unit tests, permanent e2e spec | ❌ Not yet — this release's beta hasn't been pushed to either sample repo's CI yet |
+| Automatic variable-name description fallback | `extractVariableName` (raw identifier) + `decodeVariableName` (decoded phrase + type hint) when `.describe()` isn't called. | ✅ 10+10 unit tests, permanent e2e spec | 🔎 Exercised on every sample-repo CI heal (it's the description path when `.describe()` is absent), no dedicated assertion |
 | Search-scoped snapshots | Sends a narrower excerpt of the accessibility tree when the description matches exactly one node, instead of the full page. | ✅ Live-verified (measured token reduction across several real cases) | 🔎 Silently exercised on every CI heal (it's the default first path), but no dedicated CI assertion checks it specifically |
 | `near` strategy (nameless field via label) | Resolves an unlabeled field by climbing to a shared ancestor and finding the one plausible-role sibling. | ✅ e2e (`aic-form-healing`, `employee-id-healing`) | ✅ Indirectly — the sample repos' own Employee Id field is exactly this shape |
 | `adjacent` strategy (same-row disambiguation) | Precise sibling match when `near`'s ancestor search would find more than one same-role candidate. | ✅ e2e (`adjacent-sibling-healing`) + unit | ❌ No sample test currently has this shape |
@@ -36,14 +36,14 @@ currently covered · N/A not applicable to that column.
 | `getDurable()` | Resolves any locator (e.g. `aria-ref=...`) to a durable, reusable equivalent. | ✅ e2e (`get-durable-*-repro`, 4 specs incl. concurrency) | ❌ No CI sample test calls it directly |
 | Provider: `ollama` | API-key provider, Ollama Cloud. | ✅ Verified this session (live calls, real token counts) | ✅ Both CI workflows now run a `test-ollama` job, confirmed green |
 | Provider: `ollama-local` | Self-hosted Ollama server; `OLLAMA_LOCAL_API_KEY` optional, unlike `ollama`'s required key. | ✅ Verified against a genuine local Ollama installation this session (real `ollama serve`, `qwen2.5:0.5b` pulled and warmed) — confirmed the default `OLLAMA_LOCAL_BASE_URL`, real request/response round-trip (including correct token-usage extraction), and that the real server both works with no `Authorization` header and tolerates one being sent unnecessarily; also confirmed end-to-end via the real `doctor` CLI, not just a direct provider call. (A synthetic fake-HTTP-server test preceded this and is superseded by it.) | ❌ Not used in either CI workflow (no self-hosted Ollama instance available in CI) |
-| Multi-agent skill (`skills/tamash-playwright/`) | Local review/apply/verify/land workflow for AI coding assistants, plus adapters for Claude Code, Kiro, Cursor, Copilot, and `AGENTS.md`-reading tools. | ✅ Exercised end-to-end by real, unbriefed agents in isolated environments (no prior tamash-playwright knowledge given) — three separate walkthroughs: (1) a project with real `doctor` `[WARN]`s → correctly routed to `onboarding.md`, fixed 6 missing `.describe()`s, and correctly stopped at the Page Object gate rather than "fixing" files it verified were intentionally non-POM demos; (2) a `doctor`-clean project with a real broken locator → correctly routed to `heal.md`, ran the full RUN→REVIEW→APPLY→VERIFY loop unattended, and correctly stopped at LAND rather than committing anything; (3) a from-scratch project with zero `tamash-playwright` presence → correctly installed and configured it from the published package's own docs (the skill doesn't exist in any published version yet, confirmed), proved real healing by deliberately breaking a locator and watching it recover live, and in doing so found a real bug now fixed (see CHANGELOG: `doctor`'s connectivity check was decoupled from the real `actionTimeout`). Six genuine documentation bugs found and fixed across all three runs, not just "read for plausibility." | ❌ Not used in either CI workflow (nothing to run in CI — this is consumed by an agent, not by the test suite) |
+| Multi-agent skill (`skills/tamash-playwright/`) | Local review/apply/verify/land workflow for AI coding assistants, plus adapters for Claude Code, Kiro, Cursor, Copilot, and `AGENTS.md`-reading tools. | ✅ Exercised end-to-end by real, unbriefed agents in isolated environments (no prior tamash-playwright knowledge given) — three separate walkthroughs: (1) a project with real `doctor` `[WARN]`s → correctly routed to `onboarding.md`, fixed 6 missing `.describe()`s, and correctly stopped at the Page Object gate rather than "fixing" files it verified were intentionally non-POM demos; (2) a `doctor`-clean project with a real broken locator → correctly routed to `heal.md`, ran the full RUN→REVIEW→APPLY→VERIFY loop unattended, and correctly stopped at LAND rather than committing anything; (3) a from-scratch project with zero `tamash-playwright` presence → correctly installed and configured it from the published package's own docs, proved real healing by deliberately breaking a locator and watching it recover live, and in doing so found a real bug now fixed (see CHANGELOG: `doctor`'s connectivity check was decoupled from the real `actionTimeout`). Six genuine documentation bugs found and fixed across all three runs, not just "read for plausibility." | ❌ Not used in either CI workflow (nothing to run in CI — this is consumed by an agent, not by the test suite) |
 | Provider: `openai` | API-key provider. | ✅ Re-verified live this release (`doctor` connectivity, real key) | ❌ Not used in either CI workflow |
 | Provider: `anthropic` | API-key provider. | ✅ Re-verified live this release (`doctor` connectivity, real key) | ❌ Not used in either CI workflow |
 | Provider: `gemini` | API-key provider. | ⚠️ Key authenticates and the model responds correctly (verified with a raw request, real `200 OK`), but `gemini-3.6-flash` took 50+ seconds to answer a trivial prompt — far beyond `doctor`'s 15s timeout and this repo's real `actionTimeout: 8000`ms, so it fails both `doctor` and real healing as currently configured, despite the key itself being valid | ❌ Not used in either CI workflow |
 | Provider: `claude-subscription` | No API key — uses a Claude subscription. | ✅ Verified this session | ✅ The Playwright sample repo's CI uses this as its default provider |
 | Provider: `copilot-subscription` | No API key — uses a GitHub Copilot subscription. | ✅ Verified this session | ✅ The Cucumber sample repo's CI uses this as its default provider |
 | Provider: `kiro-subscription` / `codex-subscription` | Local-development-only subscription providers (Kiro, Codex) — `child_process` wrappers, no official SDK. | ✅ **Both verified end to end, authenticated (2026-08-31)** — real `kiro-cli` v2.20.1 and `codex-cli` 0.151; `doctor` `[OK] Connected`; `codex` passed a full `npx playwright test` heal-and-recover (broken locator → `HEALED [provider=codex-subscription]` → test green, cache cleared); `kiro` passed the same single-test heal. Verifying them found four bugs, all fixed (see CHANGELOG). Not yet exercised: full `npx playwright test` for `kiro`, and `suggestActionTactic` for both. | ❌ Local-only by design, never in CI |
-| Provider: `cursor-subscription` | Local-only subscription provider (Cursor `agent` CLI), `@beta`. | ⚠️ **Partial (2026-08-31)** — `doctor` → `[OK] Connected`, and a real `suggestSelector` returns the correct `{strategy:"ref"}` on many calls. But in a real `npx playwright test` run the heal was declined (`stage=ai_declined`): Cursor's `agent` is an interactive assistant that frequently answers conversationally instead of with JSON, and does so more often than `kiro`/`codex`. Tried `--mode ask`, `--output-format json`, empty `--workspace` — the behaviour is the model's. Shipped `@beta` for user feedback with the safest invocation (`--trust --mode ask --output-format json`, read-only); docs note `kiro`/`codex` are steadier. | ❌ Not in CI |
+| Provider: `cursor-subscription` | Local-only subscription provider (Cursor `agent` CLI), experimental. | ⚠️ **Partial (2026-08-31)** — `doctor` → `[OK] Connected`, and a real `suggestSelector` returns the correct `{strategy:"ref"}` on many calls. But in a real `npx playwright test` run the heal was declined (`stage=ai_declined`): Cursor's `agent` is an interactive assistant that frequently answers conversationally instead of with JSON, and does so more often than `kiro`/`codex`. Tried `--mode ask`, `--output-format json`, empty `--workspace` — the behaviour is the model's. Kept for user feedback with the safest invocation (`--trust --mode ask --output-format json`, read-only); docs mark it experimental and point to `kiro`/`codex`. | ❌ Not in CI |
 | Provider: `tamash` (no AI) | Zero-dependency rule-based healing. | ✅ Verified against the full test suite in both sample repos (all files, cleared cache, run twice each for stability) | ✅ `test-tamash` added to and passing in both sample repos' CI |
 | Non-`@playwright/test` runner support (`bindPageActions`/`bindContext`) | Manual binding for Cucumber, Jest, or a plain script. | ✅ Live-verified via the Cucumber sample repo, this session | ✅ The Cucumber sample repo's entire CI run *is* this |
 | `waitFor()`/`dragTo`/`drop`/`expect()` exclusions | Deliberately never healed — state checks and two-sided actions can't be safely guessed at. | ✅ e2e (`wait-for-not-healed`) | ❌ No CI sample test currently exercises these specifically |
@@ -123,7 +123,7 @@ After the fixes, verified live:
   returns correct answers on many calls, but a real `npx playwright test` heal was declined
   (`stage=ai_declined`) — Cursor's `agent` frequently answers conversationally rather than with
   JSON, more so than `kiro`/`codex`. Not tuned away by `--mode ask` / `--output-format json` /
-  empty `--workspace`. Ships `@beta` for user feedback; docs note `kiro`/`codex` are steadier.
+  empty `--workspace`. Kept as an experimental provider for user feedback; docs note `kiro`/`codex` are steadier.
 
 **Suite-level validation of this release's changes** (the `diagnose()` + `doctor` rework, the
 shared JSON-parser rewrite, `init-skill`, the CLI-provider fixes), run 2026-08-31 against a real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamash-playwright",
-  "version": "0.11.0-beta.8",
+  "version": "0.11.0",
   "description": "Plug and Play Self-healing for Playwright and automatically recovers broken selectors using an AI model (Ollama, OpenAI, Anthropic, Gemini, or a Claude/GitHub Copilot subscription).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/tamash-playwright/references/onboarding.md

@@ -18,9 +18,9 @@ Ask the user which they want — don't assume:
 - **Free, fastest to start**: Ollama Cloud (`HEALER_PROVIDER=ollama`) — a free API key from `ollama.com/settings/keys`.
 - **An API-key provider they already pay for**: `openai` / `anthropic` / `gemini`.
 - **A subscription they already have, no API key**: `claude-subscription` or `copilot-subscription` — work both locally and in CI (TypeScript only).
-- **A Cursor, Kiro, or Codex subscription instead**: `cursor-subscription` / `kiro-subscription` / `codex-subscription` (all `@beta`, TypeScript only) — **local development only, never CI** (no confirmed unattended-CI auth token). All three run their CLI in a read-only mode (Cursor `--mode ask`, Codex `codex exec`'s sandbox, Kiro grants no tool trust), so a heal call can't edit files or run commands. `kiro`/`codex` answer cleanly in a few seconds; `cursor`'s `agent` is an interactive assistant that sometimes replies conversationally instead of with JSON (`stage=ai_declined`), so `kiro`/`codex` are the smoother choice.
-- **Free, zero-AI, no network call**: `tamash` (currently `@beta` — `npm install tamash-playwright@beta`) — text-matches `.describe()` against the page's own accessibility tree, never guesses; a narrower success rate than an AI provider but no cost and no key at all.
-- **Their own self-hosted Ollama server**: `ollama-local` (also `@beta`) — same shape as `ollama` but points at their own server instead of Ollama Cloud; `OLLAMA_LOCAL_API_KEY` is optional, only needed if their deployment sits behind an auth gateway.
+- **A Kiro or Codex subscription instead**: `kiro-subscription` / `codex-subscription` (TypeScript only) — **local development only, never CI** (no confirmed unattended-CI auth token). Both run their CLI in a read-only mode (Codex `codex exec`'s sandbox, Kiro grants no tool trust), so a heal call can't edit files or run commands, and both answer cleanly in a few seconds. There's also `cursor-subscription`, but Cursor's `agent` is an interactive assistant that often replies conversationally instead of with the JSON the healer needs (`stage=ai_declined`) — prefer `kiro`/`codex`.
+- **Free, zero-AI, no network call**: `tamash` — text-matches `.describe()` against the page's own accessibility tree, never guesses; a narrower success rate than an AI provider but no cost and no key at all.
+- **Their own self-hosted Ollama server**: `ollama-local` — same shape as `ollama` but points at their own server instead of Ollama Cloud; `OLLAMA_LOCAL_API_KEY` is optional, only needed if their deployment sits behind an auth gateway.
 
 Write (or update) `.env` from `.env.example` with their choice. **Never handle the real API key value yourself** — write the variable name with an empty value and have the user paste the real key into the file directly. Never echo a key back in chat, a commit message, a log line, or a report.