saffron-ai 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+All notable changes to Saffron, in one place: the `saffron-ai` runner (npm),
+the VS Code extension (`ChathurangaJayasinghe.saffron-vscode`) and the
+JetBrains plugin (`ai.saffron.jetbrains`). Dates are publish dates.
+
+## 0.5.1
+
+Released 2026-09-14.
+
+Runner
+
+- Example suite: `.saffron` files only, with StepSets invoked both at the
+  start of scenarios and in the middle ("Recover from a locked-out
+  login", and a checkout set that carries a data table).
+
+Editors
+
+- Grammar: quoted arguments, `<placeholders>` and `{env:…}` / `{date…}`
+  tokens get their own scopes, so editors colour them like Cucumber
+  parameters instead of the whole step line. Ships in the VS Code
+  extension, the JetBrains plugin and the package's TextMate bundle.
+
+## 0.5.0
+
+Released 2026-09-14.
+
+Runner
+
+- Guided first run: `saffron init` offers to install the Saucedemo example
+  suite (`--examples` / `--no-examples`): five short scenarios against the
+  public demo shop, `{env:VAR}` credentials with a `.env.example`, a
+  Scenario Outline, a data table, and a StepSet in a library file, plus a
+  matching `saffron.config.json` with `retries: 1`. Only installs into an
+  empty `features/` directory. Documented as "Your first run".
+
+## 0.4.2
+
+Released 2026-09-13.
+
+Runner
+
+- `saffron run --rerecord`: discard the selected scenarios' caches and let
+  the agent record them fresh, seeded from the other recordings. The
+  sanctioned fix for a wrong recording instead of editing cache JSON.
+- The recorder understands every way the agent types (`fill`,
+  `pressSequentially`, `type`) and drops the clearing `fill('')` that
+  precedes typing into the same field. This was the cause of caches with an
+  empty value for a step that passes one.
+- A fill recorded with an empty value on a step that passes a value marks
+  the proposal UNVERIFIED with the reason, even if the proof replay passed.
+- `saffron accept --all` skips UNVERIFIED proposals; `--include-unverified`
+  overrides, and accepting a single file still works with a warning.
+- Retries are visible: a `retried ×N` chip per step in the report and a
+  `↻` line in the terminal. Retries stay per action with backoff; they are
+  not scenario re-runs.
+- Scenario Outline rows display as `(example N)`; report, terminal and docs
+  use plain punctuation throughout.
+- Reports and history carry the real package version.
+
+Docs and site
+
+- Documentation moved to the site's Docs section, generated from the
+  runner's markdown; the previous docs page became Features; the landing
+  page was trimmed.
+- Assertion policy documented on the Features page; cache lifecycle gained
+  the staleness and wrong-recording stages.
+
+## 0.4.1
+
+Released 2026-09-13.
+
+Runner
+
+- JetBrains highlighting without the plugin: the package ships the TextMate
+  grammar at `textmate/saffron` for Settings → Editor → TextMate Bundles.
+- `saffron lsp` run from a terminal prints the editor setup steps instead
+  of waiting silently for a client.
+
+Editors
+
+- JetBrains plugin 0.1.0 (Marketplace listing 34240): `.saffron` file type,
+  bundled grammar, `saffron lsp` wired through LSP4IJ automatically.
+- JetBrains plugin 0.1.1: the no-package fallback runs
+  `npx -p saffron-ai saffron lsp` (the bare `saffron` name resolves an
+  unrelated npm package); the install hint shows once per project; dark
+  theme file icon; verified on 2024.2 through 2026.2.
+- VS Code extension 0.1.3: plain punctuation in README, hover and
+  diagnostic messages.
+
+## 0.4.0
+
+Released 2026-09-13.
+
+Runner
+
+- Agent skill shipped in the package (`skills/saffron/SKILL.md` plus
+  reference sheets) following the Agent Skills specification.
+- `saffron init`: installs the skill into `.claude/skills` and
+  `.agents/skills` (Copilot and Cursor on request), registers the
+  `saffron mcp` server in `.mcp.json`, `.cursor/mcp.json` and
+  `.vscode/mcp.json`, appends a managed block to `AGENTS.md` (and
+  `CLAUDE.md` when present), and scaffolds `saffron.config.json`,
+  `features/` and the `.gitignore` entry.
+- Multi-tag `--filter` (OR semantics, comma-separated or repeated); scenario
+  tags are written to the report JSON and `history.jsonl` so external tools
+  can key results by a test-case tag.
+- `saffron --version` reports the real package version.
+
+Editors
+
+- VS Code extension 0.1.1: case- and spacing-tolerant `StepSet` keyword
+  completion plus a definition snippet.
+- VS Code extension 0.1.2: warning and quick fix when a set name is written
+  without the `StepSet` keyword.
+
+## 0.3.1
+
+Released 2026-08-15.
+
+- `saffron --version` no longer reports a hardcoded value.
+
+## 0.3.0
+
+Released 2026-08-12.
+
+Runner
+
+- Network-aware steps in plain prose: `waitForResponse` (healable) blocks
+  until a matching backend response, `expectResponse` (assertion, never
+  healed) audits that one occurred. Matchers: URL pattern, method, status
+  (exact or class), optional body pattern for polling waits. Waits match
+  from the triggering step onward, so "click and wait" never races.
+- Recording ergonomics: native dialogs, drag-and-drop and iframes record
+  live. The dialog auto-dismiss was the orchestrator's own launching
+  Playwright client, not the MCP; agent sessions now keep dialogs visible.
+- Positive assertions recorded without frame scoping fall back to searching
+  child frames; poll-based assertions sweep all candidates under one
+  deadline.
+
+Editors
+
+- VS Code extension 0.1.0 published to the Marketplace.
+
+## 0.2.0
+
+Released 2026-07-19.
+
+Runner
+
+- Secrets: `{env:VAR}` tokens resolve from the environment (or a
+  git-ignored `.env`) at replay; caches, proposals, reports and history are
+  masked back to the token; missing variables fail fast by name.
+- Action vocabulary for real-world pages: `handleDialog`, `uploadFile`,
+  `dragTo`, and iframe-scoped targets, replaying on Chromium, Firefox and
+  WebKit.
+- Cross-browser replay (`--browser firefox|webkit`), parallel replay
+  workers (`--workers N`), and a cheaper model for heal sessions
+  (`--heal-model`).
+
+## 0.1.0
+
+Released 2026-07-10.
+
+First public release, free for any use under the Saffron Free Use License.
+
+- Gherkin-native runner: an AI agent records each scenario once; later runs
+  replay with plain Playwright at zero tokens; runtime healing files
+  reviewable proposals; assertions are never healed.
+- Verified proposals (zero-AI proof replay), honest cost reporting, run
+  history and trends, chronic-scenario detection.
+- Level-1 step reuse: new recordings seed from every step already
+  recorded.
+- Data vocabulary: `<param>` placeholders, key/value and record tables,
+  doc strings, `{date±N}` templates, captured values.
+- Assertion policy: `strict` (default) or `adaptable-mid`; the final
+  assertion block is always strict.
+- Step sets and the `.saffron` dialect (`StepSet:`), project-wide library
+  files, parse-time expansion.
+- Step vocabulary tooling: `saffron steps`, `saffron mcp`, `saffron lsp`,
+  `saffron author`; behavior-proven duplicate wording detection.

package/README.md

@@ -33,10 +33,16 @@ Data tables and doc strings are first-class: 2-column key/value tables parameter
 ```bash
 npm install --save-dev saffron-ai
 npx playwright install chromium
-npx saffron init        # config + the Saffron agent skill for your AI assistants
+npx saffron init        # config + agent skill; offers the Saucedemo example suite
 npx saffron run
 ```
 
+No app of your own yet? `npx saffron init --examples` installs a handful
+of short `.saffron` scenarios against the public demo shop at saucedemo.com
+(login, a Scenario Outline, cart, checkout, StepSets at the start and in
+the middle of scenarios) so the first run records and replays something
+real.
+
 **Built for the AI era:** the package ships an [Agent Skill](https://agentskills.io) that teaches Claude Code, Codex, Cursor, Copilot and any skill-aware agent to write Saffron tests efficiently. Reuse recorded wordings, keep assertions sacred, secrets as `{env:VAR}`, so the tests your agents write replay at zero tokens instead of paying for near-duplicate recordings.
 
 CI tip: `saffron run --strict` treats yellow (passed-with-adaptation) as a
@@ -73,7 +79,7 @@ node dist/cli/index.js -p examples accept --all
 | `saffron mcp` | Serve the vocabulary to AI assistants over stdio MCP (`search_steps`, `list_step_sets`), e.g. `claude mcp add saffron -- npx saffron mcp`. |
 | `saffron author <prose-file> [-o out]` | Draft a `.saffron` feature file from plain-paragraph requirements, reusing the project's step vocabulary (AI; reports how many lines are seedable). |
 | `saffron lsp` | Run the Saffron language server over stdio for JetBrains (LSP4IJ/Ultimate), Neovim, any LSP editor: badge completion, StepSet go-to-definition, hover, diagnostics. Highlighting for JetBrains comes from the bundled TextMate grammar (`textmate/saffron` in the package); run `npx saffron lsp` in a terminal for setup steps. |
-| `saffron init [--agents list]` | Make the project agent-ready: installs the bundled **Saffron agent skill** into `.claude/skills` and `.agents/skills` (Copilot/Cursor via `--agents`), registers the `saffron mcp` server in `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json`, adds a managed block to `AGENTS.md`/`CLAUDE.md`, scaffolds config. |
+| `saffron init [--agents list] [--examples]` | Make the project agent-ready (`--examples` installs the Saucedemo example suite): installs the bundled **Saffron agent skill** into `.claude/skills` and `.agents/skills` (Copilot/Cursor via `--agents`), registers the `saffron mcp` server in `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json`, adds a managed block to `AGENTS.md`/`CLAUDE.md`, scaffolds config. |
 | `saffron report` | Open the latest HTML report. |
 
 Configuration lives in `saffron.config.json` at your project root:
@@ -137,6 +143,7 @@ far is in the roadmap's "Where we are" table.
 
 - [Website](https://saffron-ai.lovable.app): what Saffron is, the honesty rules, economics, quickstart
 - [Documentation](https://saffron-ai.lovable.app/docs): the cache lifecycle, step sets & the `.saffron` dialect, the step vocabulary, and the guarantees, with diagrams
+- [Changelog](CHANGELOG.md), also at https://saffron-ai.lovable.app/docs/changelog
 - [Issues & questions](https://github.com/s-chathuranga-j/saffron-ai/issues)
 - **Docs site**: `npm run docs` builds a self-contained page at
 ## License