jourilo 0.1.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +111 -104
  2. package/package.json +1 -1
  3. package/plugin/.claude-plugin/icon.png +0 -0
  4. package/plugin/.claude-plugin/plugin.json +1 -1
  5. package/plugin/dist/jourilo.mjs +4422 -1337
  6. package/plugin/skills/accessibility/SKILL.md +1 -0
  7. package/plugin/skills/audit/SKILL.md +3 -3
  8. package/plugin/skills/compare/SKILL.md +1 -0
  9. package/plugin/skills/conversion/SKILL.md +1 -0
  10. package/plugin/skills/jourilo/SKILL.md +31 -10
  11. package/plugin/skills/jourilo/references/cli.md +38 -12
  12. package/plugin/skills/journeys/SKILL.md +1 -0
  13. package/plugin/skills/optimize/SKILL.md +6 -2
  14. package/plugin/skills/report/SKILL.md +3 -2
package/README.md CHANGED
@@ -1,148 +1,155 @@
1
- # Jourilo
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/brand/jourilo-wordmark-reversed.svg">
4
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/brand/jourilo-wordmark.svg" alt="Jourilo" width="260">
5
+ </picture>
6
+ </p>
2
7
 
3
- **AI-powered product experience & conversion engineering studio.** Jourilo drives a real browser through your
4
- product, finds UX, accessibility, performance and conversion problems with evidence, traces them to the code that
5
- causes them, applies safe fixes and proves the result with a before/after run.
8
+ <h3 align="center">Walk every journey. Find the friction. Prove the fix.</h3>
6
9
 
7
- Local-first · evidence-driven · no paid services required · works as a CLI and as a Claude Code plugin · Apache-2.0
10
+ <p align="center">
11
+ Jourilo uses your product in a real browser, shows where people get stuck with screenshot evidence,<br>
12
+ traces each problem to its root cause and proves every fix with a before/after run.<br>
13
+ A CLI and a Claude Code plugin. Local-first, open source.
14
+ </p>
8
15
 
9
- ![Jourilo report overview: defects by severity, conversion hypotheses kept separate, fixes grouped by root cause](docs/assets/report-overview.png)
16
+ <p align="center">
17
+ <a href="https://www.npmjs.com/package/jourilo"><img alt="npm" src="https://img.shields.io/npm/v/jourilo?color=875802&label=npm"></a>
18
+ <a href="https://github.com/cihantopac/jourilo/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cihantopac/jourilo/actions/workflows/ci.yml/badge.svg"></a>
19
+ <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-1c1a17"></a>
20
+ <img alt="Node.js ≥ 20.10" src="https://img.shields.io/badge/node-%E2%89%A5%2020.10-1c1a17">
21
+ </p>
10
22
 
11
- > Status: **0.1.0, pre-release.** Tested on macOS (Apple Silicon) with Chromium. See [Limitations](docs/LIMITATIONS.md)
12
- > for what is not covered yet.
23
+ <p align="center">
24
+ <a href="#install">Install</a> ·
25
+ <a href="#in-claude-code">Claude Code</a> ·
26
+ <a href="#audit--understand--fix--verify">How it works</a> ·
27
+ <a href="#benchmarks">Benchmarks</a> ·
28
+ <a href="docs/WORKFLOW.md">Guide</a> ·
29
+ <a href="docs/">Docs</a>
30
+ </p>
13
31
 
14
- ## What it does
32
+ <picture>
33
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-overview-dark.png">
34
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-overview.png" alt="The Jourilo report: verified defects, root causes, automatic fixes, manual review and conversion hypotheses as separate counts, then the highest-impact root causes with their screenshots">
35
+ </picture>
15
36
 
16
- | | |
17
- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
- | **Understand** | `discover` maps a repository (Next.js, Nuxt, SvelteKit, Astro, Remix, React/Vue Router, Laravel, Flutter web, static sites, monorepos) or a live site: routes, dev command, design system, i18n, auth, payments, analytics, roles and candidate journeys. Every fact names the file or page it came from. |
19
- | **Audit in a real browser** | Playwright + axe-core 4.14 (WCAG 2.0–2.2 A/AA), a keyboard-only walk (focus visible, focus obscured, traps), target size, reflow at 320 px, horizontal overflow, input purpose, paste blocking, form error feedback, lab Web Vitals (LCP, CLS, FCP, TTFB, TBT; INP during journeys), JavaScript errors and failed requests — on desktop and mobile. |
20
- | **Journeys** | Reusable JSON scenarios with explicit success criteria, suggested from what the site actually contains, run with a screenshot per step. A safety policy never pays, deletes or cancels on non-local hosts. |
21
- | **Conversion** | CTA prominence and clarity, value proposition, trust signals, signup/checkout friction, pricing clarity — always reported as **hypotheses**, never as predicted lifts, with experiment plans and the statistics to read real results. |
22
- | **Fix and verify** | Findings point to likely source lines. `optimize` previews minimal fixes as diffs and applies them only with `--apply` after a git checkpoint. `verify` repeats the exact scope and reports fixed, new and persisting problems. |
23
- | **Report** | A self-contained HTML _Experience Observatory_ (screenshots with highlighted elements, reproduction steps, standards, sources, journeys, before/after), plus Markdown for PRs and SARIF for code scanning. |
37
+ ## It walks the journey, step by step
24
38
 
25
- What Jourilo does **not** do: invent observations, give a single "UX score", claim WCAG compliance from an automated
26
- run, or predict conversion gains. Each finding is labelled _measured_, _observed_, _heuristic_, _AI inference_ or
27
- _user input_.
39
+ Jourilo signs up, checks out and follows calls to action like a person would, with a real screenshot of every step.
40
+ When a journey breaks, you see exactly where.
28
41
 
29
- ## Quick start
42
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-journeys.png" alt="A sign-up journey on mobile: the form is filled in, Submit is clicked, the page resets, and the goal 'leaves the form page' is not met">
30
43
 
31
- Requires Node.js ≥ 20.10. Jourilo is not on npm yet; install from the repository.
44
+ ## Evidence you can see
32
45
 
33
- ```bash
34
- git clone https://github.com/cihantopac/jourilo && cd jourilo && npm install
35
- ```
46
+ Every finding comes with the element outlined on its screenshot, the measured values, the WCAG criterion, reproduction
47
+ steps and the likely source line. Findings with one cause are grouped into one fix. Verified defects, items that need a
48
+ person and conversion hypotheses are always kept apart, and there is no made-up overall score.
36
49
 
37
- ```bash
38
- node plugin/dist/jourilo.mjs setup
39
- ```
50
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-finding.png" alt="A finding: the page scrolls sideways at 390 px, with the measured widths, WCAG 1.4.10, the CSS rule that causes it and the element highlighted on the mobile screenshot">
51
+
52
+ ## Audit → Understand → Fix → Verify
53
+
54
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/workflow.png" alt="Four steps: audit in a real browser, understand by root cause, fix with approved patches or a repair prompt, verify with a before/after run">
55
+
56
+ ## Fix it yourself, automatically or with your agent
57
+
58
+ - **Automatic fixes** for mechanical defects (missing `lang`, viewport, autocomplete, focus styles, paste blocking,
59
+ image sizes, placeholder labels): `jourilo optimize` previews minimal diffs and writes them only with `--apply`, as
60
+ one reversible change.
61
+ - **Repair prompts** for everything else: select findings or root causes in the report and copy or download an
62
+ editable Markdown prompt for Claude Code or any coding agent. It carries ids, pages, screenshots, likely source files
63
+ and reproduction steps, and asks the agent to revalidate, change as little as possible, add regression tests and
64
+ verify with Jourilo.
65
+ - **Experiment briefs** for conversion hypotheses, never code changes or promised lifts.
66
+
67
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-prompt.png" alt="The repair prompt dialog: an editable Markdown brief with copy and download buttons, generated from three selected findings">
68
+
69
+ ## Prove it
70
+
71
+ `jourilo verify` repeats the same pages, viewports and journeys and shows what is fixed, new or still present, with the
72
+ same region of the page before and after.
73
+
74
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-before-after.png" alt="Before / after: 14 fixed, 0 new, 18 still present, with before and after crops of each fixed problem">
40
75
 
41
- `setup` downloads Playwright's Chromium (one time, ~150 MB). Alternatively use an installed Chrome with
42
- `--browser chrome`.
76
+ ## One file, any screen, two languages
43
77
 
44
- Audit a local static build (served on 127.0.0.1) and map findings to its source:
78
+ The report is a single offline HTML file. It follows the browser's language and theme, and you can switch between
79
+ English and Turkish and between light, dark and system appearance.
80
+
81
+ <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-mobile.png" alt="The report on two phones: English in the light theme and Turkish in the dark theme">
82
+
83
+ ## Install
84
+
85
+ Requires Node.js ≥ 20.10.
45
86
 
46
87
  ```bash
47
- node plugin/dist/jourilo.mjs audit ./dist --repo .
88
+ npm install -g jourilo
48
89
  ```
49
90
 
50
- Audit a running app or a website (read-only, respects robots.txt):
91
+ ```bash
92
+ jourilo setup
93
+ ```
51
94
 
52
95
  ```bash
53
- node plugin/dist/jourilo.mjs audit http://localhost:3000 --viewports desktop,mobile,reflow
96
+ jourilo audit http://localhost:3000 --repo .
54
97
  ```
55
98
 
56
- The report is written to `.jourilo/runs/<run-id>/report.html` (git-ignored). Add `--json` to any command for
57
- machine-readable output.
99
+ `setup` downloads Playwright's Chromium once. The report is written to `.jourilo/runs/<run-id>/report.html`.
100
+ More commands and the full loop: [docs/WORKFLOW.md](docs/WORKFLOW.md) and the [CLI reference](docs/CLI.md).
58
101
 
59
- ### Claude Code plugin
102
+ ## In Claude Code
60
103
 
61
104
  ```text
62
105
  /plugin marketplace add cihantopac/jourilo
63
106
  /plugin install jourilo@jourilo
64
107
  ```
65
108
 
66
- Then use `/jourilo:jourilo <url or path>` for the full workflow, or `/jourilo:discover`, `/jourilo:audit`,
67
- `/jourilo:journeys`, `/jourilo:accessibility`, `/jourilo:conversion`, `/jourilo:optimize`, `/jourilo:compare`,
68
- `/jourilo:report`, `/jourilo:experiment`. Claude Code namespaces plugin commands, so a bare `/jourilo` is available
69
- by installing the personal skill: `jourilo agent install claude-skill --write`. See [docs/PLUGIN.md](docs/PLUGIN.md).
70
-
71
- Other agents: `jourilo agent install codex --write` (adds a section to `AGENTS.md`) or `cursor`
72
- (`.cursor/rules/jourilo.mdc`).
73
-
74
- ## The improvement loop
75
-
76
- ```bash
77
- jourilo audit http://localhost:3000 --repo . # evidence + likely source lines
78
- jourilo journeys suggest latest # edit .jourilo/journeys/*.json
79
- jourilo journeys run --base http://localhost:3000 # step screenshots, success criteria
80
- jourilo optimize latest --repo . # preview minimal diffs (dry run)
81
- jourilo optimize latest --repo . --apply # git checkpoint, then write
82
- jourilo verify <baseline-run> # same scope again: fixed / new / persisting
83
- jourilo rollback latest --yes # undo if needed
84
- ```
85
-
86
- Measured on the seeded demo app (`fixtures/sites/acme-saas`): `verify` after `optimize --apply` reported 11 findings
87
- fixed and 0 new; on a page with a late-loading image, adding the measured image size took mobile CLS from 0.121 to 0.
88
- Fixes are idempotent and fully reversible (see [docs/EVALUATION.md](docs/EVALUATION.md)).
109
+ Then `/jourilo:jourilo https://your-site.dev` or `/jourilo:jourilo .` for a repository. Claude answers in a few lines
110
+ (blocked journeys, three priorities, the fixes available, the report path and one next step) and keeps the evidence in
111
+ the report. All commands: [docs/PLUGIN.md](docs/PLUGIN.md).
89
112
 
90
- | Finding with evidence and root cause | Journey storyboard |
91
- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
92
- | ![A finding with standard, reproduction steps, likely source line and the element highlighted on the screenshot](docs/assets/report-finding.png) | ![Journeys with a screenshot per step, success criteria and the step that failed](docs/assets/report-journeys.png) |
113
+ ## Benchmarks
93
114
 
94
- ## Detection quality
115
+ On the 955 [W3C ACT Rules](https://www.w3.org/WAI/standards-guidelines/act/rules/) test cases that map to WCAG criteria,
116
+ written by the ACT Rules Community Group and not for Jourilo (measured 2026-11-01; the detection engine is unchanged
117
+ in 1.1.0):
95
118
 
96
- **Fixture benchmark** (`jourilo bench`): sites with seeded problems and clean control pages. It fails on any miss,
97
- false positive or wrong root-cause file. 0.1.0, Chromium, macOS:
119
+ | | Precision | Recall | False positives |
120
+ | --------------------- | --------- | ------ | --------------- |
121
+ | Jourilo 1.0.0 | 93.9 % | 55.4 % | 11 |
122
+ | axe-core 4.14.0 alone | 93.6 % | 53.5 % | 11 |
98
123
 
99
- | Fixture | Seeded problems found | False positives |
100
- | ------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------- |
101
- | `acme-saas` (SaaS marketing, signup, login, slow and shifting pages) | 23 / 23 | 0 (root cause in the expected file 9 / 9) |
102
- | `tr-dukkan` (Turkish shop) | 8 / 8 | 0 |
103
- | `structure-lab` (form grouping, tables, image alternatives; broken and accessible versions) | 4 / 4 | 0 |
104
- | `widgets-lab` (dialog and disclosure; broken and accessible versions) | 3 / 3 | 0 |
105
- | `brand-site` (locked Markilo brand) | 3 / 3 | 0 |
106
- | `clean-shop` (control) | — | 0 |
124
+ Jourilo runs axe-core and adds its own keyboard-trap and focus-indicator checks. Many misses are criteria only a person
125
+ can judge, which every report lists. No automated run shows WCAG conformance. Method, fixture benchmark and a
126
+ comparison with Pa11y and Lighthouse: [docs/EVALUATION.md](docs/EVALUATION.md).
107
127
 
108
- These fixtures were written alongside the rules, so they show the rules work as designed. For an independent view,
109
- [`benchmarks/compare`](benchmarks/compare) runs Jourilo, Pa11y and Lighthouse on the 142 published test cases of the
110
- [GOV.UK accessibility tool audit](https://alphagov.github.io/accessibility-tool-audit/): error-level detections were
111
- Jourilo 54 (49 counted conservatively), Pa11y 38 and Lighthouse 34, with the same Chromium build. The metric is coarse
112
- and the comparison influenced Jourilo's rules; read the method and caveats in
113
- [docs/EVALUATION.md](docs/EVALUATION.md#comparison) before quoting it.
128
+ ## Safe by default
114
129
 
115
- ## Safety and privacy
130
+ Audits are read-only, respect robots.txt and run behind a network guard that keeps audited pages away from your
131
+ machine and network. Journeys never pay, delete or cancel on non-local hosts. Secrets are masked in screenshots and
132
+ redacted from reports. Details: [docs/PRIVACY.md](docs/PRIVACY.md) · [SECURITY.md](SECURITY.md).
116
133
 
117
- Normal audits are read-only. Crawling stays on the target origin, respects robots.txt and refuses private-network
118
- targets unless you pass `--allow-private`. Journeys block payments, purchases, deletions and cancellations on any
119
- non-local host; form submission on non-local hosts needs `--allow-submit`. Password, card and marked fields are masked
120
- in screenshots; tokens, keys, e-mail addresses and card numbers are redacted from logs and reports. Page content is
121
- treated as untrusted data and is always HTML-escaped in reports. Details: [docs/PRIVACY.md](docs/PRIVACY.md),
122
- [SECURITY.md](SECURITY.md).
134
+ ## The family
123
135
 
124
- ## Works with Markilo and Searvex (optional)
136
+ Jourilo works on its own and pairs with its siblings through a small, optional contract
137
+ ([docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)):
125
138
 
126
- If a project contains [Markilo](https://github.com/cihantopac/markilo) brand tokens, Jourilo checks buttons and fonts
127
- against the brand and never recommends changing a locked brand color. If it contains
128
- [Searvex](https://github.com/cihantopac/searvex) results, search findings for the same pages appear in the report.
129
- Both are read through a small, versioned, tool-neutral contract, `jourilo.context/v1`
130
- ([docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)). Neither is required.
139
+ - [**Relivaro**](https://github.com/cihantopac/relivaro) — code quality, security and release readiness.
140
+ - [**Searvex**](https://github.com/cihantopac/searvex) — SEO and AI-search findings; Jourilo shows them for the same pages.
141
+ - [**Markilo**](https://github.com/cihantopac/markilo) — brand identity; Jourilo checks against its tokens and never
142
+ changes a locked brand. Jourilo's own logo was made with Markilo.
131
143
 
132
144
  ## Documentation
133
145
 
134
- - [CLI reference](docs/CLI.md) (generated from the code)
135
- - [Architecture](docs/ARCHITECTURE.md) · [Decisions](docs/DECISIONS.md) · [Requirements and quality targets](docs/REQUIREMENTS.md)
136
- - [Journeys format](docs/JOURNEYS.md) · [Claude Code plugin and agents](docs/PLUGIN.md) · [Integrations](docs/INTEGRATIONS.md)
137
- - [Evaluation](docs/EVALUATION.md) · [Limitations](docs/LIMITATIONS.md) · [Roadmap](docs/ROADMAP.md) · [Progress log](docs/PROGRESS.md)
138
- - Research: [tool landscape](docs/research/landscape.md) · [standards reference](docs/research/standards.md)
139
-
140
- ## Contributing
146
+ [Guide](docs/WORKFLOW.md) · [CLI](docs/CLI.md) · [Plugin](docs/PLUGIN.md) · [Journeys](docs/JOURNEYS.md) ·
147
+ [Evaluation](docs/EVALUATION.md) · [Limitations](docs/LIMITATIONS.md) · [Architecture](docs/ARCHITECTURE.md) ·
148
+ [Decisions](docs/DECISIONS.md) · [Roadmap](docs/ROADMAP.md) · [Changelog](CHANGELOG.md)
141
149
 
142
- Bug reports, fixture sites with real-world UX problems and new rules are welcome. Start with
143
- [CONTRIBUTING.md](CONTRIBUTING.md). Every rule needs a fixture that proves it fires and a control that proves it does
144
- not.
150
+ Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Every rule needs a fixture that proves it fires and a
151
+ control that proves it does not.
145
152
 
146
153
  ## License
147
154
 
148
- [Apache-2.0](LICENSE). Bundled third-party code: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
155
+ [Apache-2.0](LICENSE). Bundled third-party code: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jourilo",
3
- "version": "0.1.0",
3
+ "version": "1.1.0",
4
4
  "description": "AI-powered product experience & conversion engineering studio: real-browser journeys, UX, accessibility, performance and conversion audits with evidence, root causes and verified fixes.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
package/plugin/.claude-plugin/icon.png ADDED
Binary file
package/plugin/.claude-plugin/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "jourilo",
3
3
  "displayName": "Jourilo",
4
- "version": "0.1.0",
4
+ "version": "1.1.0",
5
5
  "description": "AI-powered product experience & conversion engineering studio: discovers products and user journeys, operates real interfaces in Playwright, detects UX, accessibility (WCAG 2.2), performance and conversion problems with evidence, locates root causes, applies safe fixes and verifies them.",
6
6
  "author": {
7
7
  "name": "Cihan Topaç",