saffron-ai 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saffron-ai",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Gherkin-native AI-fallback test runner: zero-token cached replay, runtime AI healing, honest reports",
   "scripts": {
     "test": "vitest run",
@@ -55,6 +55,7 @@
   "files": [
     "dist-pkg",
     "skills",
+    "textmate",
     "README.md",
     "LICENSE"
   ]

package/skills/saffron/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: saffron
-description: Write, run, and maintain end-to-end UI tests with Saffron — a Gherkin-native runner where an AI agent records each scenario once and every later run replays at zero tokens. Use when creating or editing .feature / .saffron files, defining StepSets, reviewing .saffron/cache proposals, running `saffron run`, or when the user mentions Saffron, Gherkin scenarios, step sets, cached replay, or `saffron.config.json`.
+description: Write, run, and maintain end-to-end UI tests with Saffron, a Gherkin-native runner where an AI agent records each scenario once and every later run replays at zero tokens. Use when creating or editing .feature / .saffron files, defining StepSets, reviewing .saffron/cache proposals, running `saffron run`, or when the user mentions Saffron, Gherkin scenarios, step sets, cached replay, or `saffron.config.json`.
 license: Saffron Free Use License v1.0 (see the saffron-ai package LICENSE)
 metadata:
   author: saffron-ai
@@ -12,14 +12,14 @@ metadata:
 Saffron runs plain-Gherkin scenarios in a real browser. There are **no
 step definitions and no glue code**: on the first run an AI agent performs
 each step and records what it did into a JSON cache; every later run
-replays that cache with plain Playwright — zero AI calls, zero tokens,
+replays that cache with plain Playwright: zero AI calls, zero tokens,
 ~100 ms per scenario. When the UI drifts, the agent heals the failing
 step mid-run and files a reviewable proposal.
 
 Your job when writing tests is to make that economy work. Three rules
 matter more than everything else:
 
-## 1. Exact step text is the cache identity — reuse the vocabulary
+## 1. Exact step text is the cache identity: reuse the vocabulary
 
 A step is looked up by its exact wording. `When I visit the login page`
 and `When I open the login page` are two different steps: the second one
@@ -37,25 +37,25 @@ npx saffron steps --json          # machine-readable
 Prefer a `●` recorded wording verbatim. Quoted values may differ freely
 (`I enter "admin"` seeds from `I enter "bob"`), so parameterize with
 quotes rather than inventing new phrasings. `saffron init` registers the
-`saffron` MCP server with Claude Code, Cursor and VS Code — its
+`saffron` MCP server with Claude Code, Cursor and VS Code; its
 `search_steps` / `list_step_sets` tools give the same answer without a
 shell.
 
-## 2. `Then` steps are sacred — write them as the verdict
+## 2. `Then` steps are sacred: write them as the verdict
 
 Saffron never heals an assertion: the agent may help *reach* a `Then`,
 never make it pass. So `Then` lines must state exactly what must be true,
-with stable text — never volatile values (prices, dates, counters). Put
+with stable text, never volatile values (prices, dates, counters). Put
 the final assertions **last**; the trailing block of `Then` steps is
 strict under every policy. Use `Given`/`When` for actions.
 
 ## 3. Never bake volatile or secret values into files
 
-- Secrets: `{env:VAR}` — `When I enter "{env:ADMIN_PASSWORD}" in the password field`.
-- Dates: write intent, not literals — "1 day from today" records as `{date+1}`.
-- Dynamic display values: capture and compare — `I record the total as "first"` … `"first" should differ from the displayed total`.
+- Secrets: `{env:VAR}`, as in `When I enter "{env:ADMIN_PASSWORD}" in the password field`.
+- Dates: write intent, not literals: "1 day from today" records as `{date+1}`.
+- Dynamic display values: capture and compare, e.g. `I record the total as "first"` … `"first" should differ from the displayed total`.
 
-## Writing a scenario — the shape that records cleanly
+## Writing a scenario: the shape that records cleanly
 
 ```gherkin
 Feature: Checkout
@@ -78,7 +78,7 @@ Guidelines the recorder rewards:
 - Name the page or control in the step (`on the checkout page`, `the "Save" button`).
 - Data belongs in tables and doc strings, not in prose (see references).
 - Conditional wording (`if prompted`) records as a no-op when absent.
-- Real-world furniture just works — say it: dialogs ("and confirm the
+- Real-world furniture just works if you say it: dialogs ("and confirm the
   dialog"), uploads ("upload the file "x.txt" as the attachment"),
   drag-and-drop ("drag the card onto the done column"), iframes
   (interact normally), network waits ("wait for the order API to return
@@ -90,7 +90,7 @@ Guidelines the recorder rewards:
 changes, and you gain the `StepSet:` keyword.
 
 ```gherkin
-StepSet: Complete guest information            # define — colon, like Scenario:
+StepSet: Complete guest information            # define: colon, like Scenario:
     Given I am on the guest information page
     When I enter guest name "Chathuranga"
     And I click the continue button
@@ -98,11 +98,11 @@ StepSet: Complete guest information            # define — colon, like Scenario
 
 Scenario: Checkout happy path
     Given I am on the cart page
-    StepSet Complete guest information         # invoke — no colon, like a step
+    StepSet Complete guest information         # invoke: no colon, like a step
     Then I am on the checkout page
 ```
 
-- Definition: `StepSet: <name>`. Invocation: `StepSet <name>` — the bare
+- Definition: `StepSet: <name>`. Invocation: `StepSet <name>`, the bare
   name without the keyword is a silent parse error.
 - Names are project-wide unique; sets resolve across files; no nesting.
 - Application-wide flows (login, cookie banner) live in a sets-only
@@ -119,6 +119,7 @@ npx saffron run --no-agent               # replay only (CI without AI access)
 npx saffron accept                       # list pending proposals
 npx saffron accept --all                 # promote verified proposals to caches
 npx saffron report                       # open the HTML report
+npx saffron run --rerecord --filter @t   # a recording is wrong: record it fresh
 ```
 
 Results: **green** = cached pass · **yellow** = passed with AI recording
@@ -142,11 +143,11 @@ re-record (mostly seeded from existing step recordings).
 | Put a password literal in a step | `{env:VAR}` |
 | Sleep/wait "for 3 seconds" | Wait for a UI signal or an API response |
 | One 30-step scenario | Several 5–10 step scenarios + StepSets |
-| Edit cache JSON to fix a test | Edit the scenario text; re-run |
+| Edit cache JSON to fix a test | Edit the scenario text and re-run, or `saffron run --rerecord` if the recording itself is wrong |
 
 ## References
 
-- [Syntax cheat sheet](references/syntax.md) — tables, doc strings,
+- [Syntax cheat sheet](references/syntax.md): tables, doc strings,
   outlines, secrets, dates, network waits, page furniture, StepSets.
-- [Configuration & CI](references/config.md) — `saffron.config.json`,
+- [Configuration & CI](references/config.md): `saffron.config.json`,
   flags, `--strict`, cross-browser, workers, heal model, secrets setup.

package/skills/saffron/references/config.md

@@ -39,12 +39,13 @@ your-project/
 |---|---|
 | `baseURL` | App under test; steps say "the login page", not full URLs |
 | `storageState` | Playwright storage-state JSON so replays and the agent start authenticated (`npx playwright open --save-storage=.auth/state.json <url>`) |
-| `strict` | Yellow (passed-with-adaptation) exits 1 until reviewed — cached-green-only CI |
+| `retries` | Extra attempts per action with backoff before a step fails and the agent heals (default 1). Not a scenario re-run; reports show a `retried ×N` chip |
+| `strict` | Yellow (passed-with-adaptation) exits 1 until reviewed: cached-green-only CI |
 | `assertionPolicy` | `strict` (default) or `adaptable-mid`; the final assertion block is always strict |
 | `verifyProposals` | Proof-replay every recording zero-AI before filing (default true) |
 | `reuseSteps` | Seed new recordings from existing step recordings (default true) |
 | `snapshotMode` | `none` (default, ~60% fewer AI calls) or `full` for highly dynamic pages |
-| `browser` | `chromium` / `firefox` / `webkit` — replay runs anywhere; recording and healing use Chromium |
+| `browser` | `chromium` / `firefox` / `webkit`: replay runs anywhere; recording and healing use Chromium |
 | `workers` | Parallel replay workers; agent work stays sequential |
 | `healModel` | Cheaper model for heal sessions only |
 
@@ -68,7 +69,7 @@ preflight (e.g. a missing `{env:VAR}`).
 
 Recording and healing need Claude credentials: `ANTHROPIC_API_KEY`, or a
 Claude Code login on the machine. Replay-only runs (`--no-agent`) need
-none — that is the normal CI mode once caches are committed.
+none: that is the normal CI mode once caches are committed.
 
 ## Recommended CI
 
@@ -83,8 +84,8 @@ credentials), review proposals in PRs like snapshot updates.
 ## Reading a report
 
 Per scenario: status, duration, AI calls and tokens (including prompt
-cache reads/writes — the real bill), adaptation narrative, cache diff and
+cache reads/writes: the real bill), adaptation narrative, cache diff and
 suggested feature edit for yellows, drift chips when page fingerprints no
 longer match. Trends vs. the previous run and 20-run sparklines come from
 `.saffron/history.jsonl`; **chronic** scenarios (healing repeatedly) are
-flagged — re-record those instead of paying for heals again.
+flagged: re-record those instead of paying for heals again.

package/skills/saffron/references/syntax.md

@@ -18,7 +18,7 @@ trailing block of assertions is always strict; under the opt-in
 
 ## Scenario Outlines
 
-One cache serves every row — `<param>` placeholders stay in the cache and
+One cache serves every row: `<param>` placeholders stay in the cache and
 resolve per row at replay.
 
 ```gherkin
@@ -71,7 +71,7 @@ When I leave a note
 Then the saved note should be shown
 ```
 
-## Secrets — `{env:VAR}`
+## Secrets: `{env:VAR}`
 
 ```gherkin
 When I enter "{env:ADMIN_USER}" in the username field
@@ -81,7 +81,7 @@ And I enter "{env:ADMIN_PASSWORD}" in the password field
 Resolved from the environment (or a git-ignored `.env`; real env wins) at
 replay. Caches, proposals, reports and history contain only the token;
 a missing variable fails fast by name. Honest note: during the *first*
-recording the agent types the real value once — use rotatable staging
+recording the agent types the real value once: use rotatable staging
 credentials.
 
 ## Dates and dynamic values
@@ -99,7 +99,7 @@ And the total should match "NOK [\d,]+"
 And the "Book" link should point to "/booking"
 ```
 
-## Network-aware steps (no keywords — plain prose)
+## Network-aware steps (no keywords, plain prose)
 
 ```gherkin
 When I place the order and wait for the order API to return 201
@@ -152,7 +152,7 @@ Scenario: Checkout happy path
 - Names project-wide unique (also catches the colon typo at an
   invocation). Sets may contain tables, doc strings and `<param>`
   placeholders; no nesting; a set never runs standalone.
-- Shared flows go in `features/shared.steps.saffron` — a sets-only
+- Shared flows go in `features/shared.steps.saffron`, a sets-only
   library file with a `Feature:` header and no scenarios.
 - Assertions inside a set are checkpoints mid-scenario and part of the
   strict final block when the set is invoked last.

package/textmate/saffron/language-configuration.json

@@ -0,0 +1,16 @@
+{
+  "comments": {
+    "lineComment": "#"
+  },
+  "brackets": [
+    ["<", ">"]
+  ],
+  "autoClosingPairs": [
+    { "open": "\"", "close": "\"", "notIn": ["string"] },
+    { "open": "<", "close": ">" }
+  ],
+  "surroundingPairs": [
+    ["\"", "\""],
+    ["<", ">"]
+  ]
+}

package/textmate/saffron/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "saffron-textmate",
+  "displayName": "Saffron (TextMate bundle)",
+  "description": "Syntax highlighting for .saffron files \u2014 Gherkin plus StepSet. Import this folder in JetBrains: Settings \u2192 Editor \u2192 TextMate Bundles \u2192 +. Shipped inside the saffron-ai npm package.",
+  "version": "0.1.0",
+  "publisher": "saffron-ai",
+  "engines": {
+    "vscode": "^1.75.0"
+  },
+  "contributes": {
+    "languages": [
+      {
+        "id": "saffron",
+        "aliases": [
+          "Saffron"
+        ],
+        "extensions": [
+          ".saffron"
+        ],
+        "configuration": "./language-configuration.json"
+      }
+    ],
+    "grammars": [
+      {
+        "language": "saffron",
+        "scopeName": "source.saffron",
+        "path": "./syntaxes/saffron.tmLanguage.json"
+      }
+    ]
+  }
+}

package/textmate/saffron/syntaxes/saffron.tmLanguage.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "Saffron",
+  "scopeName": "source.saffron",
+  "patterns": [
+    {
+      "include": "#comment"
+    },
+    {
+      "include": "#tag"
+    },
+    {
+      "include": "#stepset-definition"
+    },
+    {
+      "include": "#block-keyword"
+    },
+    {
+      "include": "#stepset-invocation"
+    },
+    {
+      "include": "#step"
+    },
+    {
+      "include": "#docstring"
+    },
+    {
+      "include": "#table"
+    }
+  ],
+  "repository": {
+    "comment": {
+      "match": "^\\s*#.*$",
+      "name": "comment.line.number-sign.saffron"
+    },
+    "tag": {
+      "match": "@[^@\\s]+",
+      "name": "entity.name.tag.saffron"
+    },
+    "stepset-definition": {
+      "match": "^\\s*(StepSet)(:)\\s*(.*)$",
+      "captures": {
+        "1": {
+          "name": "keyword.control.stepset.saffron"
+        },
+        "2": {
+          "name": "punctuation.separator.saffron"
+        },
+        "3": {
+          "name": "entity.name.function.stepset.saffron"
+        }
+      }
+    },
+    "block-keyword": {
+      "match": "^\\s*(Feature|Background|Scenario Outline|Scenario Template|Scenario|Examples|Scenarios|Rule)(:)(.*)$",
+      "captures": {
+        "1": {
+          "name": "keyword.control.gherkin.saffron"
+        },
+        "2": {
+          "name": "punctuation.separator.saffron"
+        },
+        "3": {
+          "name": "entity.name.section.saffron"
+        }
+      }
+    },
+    "stepset-invocation": {
+      "match": "^\\s*(StepSet)\\s+([^:].*)$",
+      "captures": {
+        "1": {
+          "name": "keyword.control.stepset.saffron"
+        },
+        "2": {
+          "name": "entity.name.function.stepset.saffron"
+        }
+      }
+    },
+    "step": {
+      "match": "^\\s*(Given|When|Then|And|But|\\*)\\s(.*)$",
+      "captures": {
+        "1": {
+          "name": "keyword.other.step.saffron"
+        },
+        "2": {
+          "name": "string.unquoted.step-text.saffron",
+          "patterns": [
+            {
+              "match": "\"[^\"]*\"",
+              "name": "string.quoted.double.saffron"
+            },
+            {
+              "match": "<[^<>]+>",
+              "name": "variable.parameter.saffron"
+            }
+          ]
+        }
+      }
+    },
+    "docstring": {
+      "begin": "^\\s*\"\"\"",
+      "end": "^\\s*\"\"\"",
+      "name": "string.quoted.docstring.saffron"
+    },
+    "table": {
+      "match": "^\\s*\\|.*\\|\\s*$",
+      "name": "meta.table.saffron",
+      "captures": {
+        "0": {
+          "patterns": [
+            {
+              "match": "\\|",
+              "name": "punctuation.separator.table.saffron"
+            },
+            {
+              "match": "<[^<>]+>",
+              "name": "variable.parameter.saffron"
+            }
+          ]
+        }
+      }
+    }
+  },
+  "fileTypes": [
+    "saffron"
+  ]
+}