diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dd3d9e8..55fafee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,14 +18,12 @@ jobs: matrix: os: - macos-15 - - macos-13 + - macos-14 - ubuntu-24.04 - ubuntu-22.04 - windows-2022 node: ["22.x", "24.x"] exclude: - - os: macos-13 - node: "24.x" - os: ubuntu-22.04 node: "24.x" steps: @@ -94,6 +92,16 @@ jobs: - run: pnpm --filter @ohmyperf/core build - run: pnpm --filter @ohmyperf/core api:check + actionlint: + name: actionlint (GitHub Actions workflow files) + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - name: Download actionlint + run: bash <(curl -sSf https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) 1.7.12 + - name: Lint all workflow files + run: ./actionlint -no-color -oneline + parity: name: Lighthouse parity (main push only) if: github.event_name == 'push' && github.ref == 'refs/heads/main' diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml new file mode 100644 index 0000000..b46531b --- /dev/null +++ b/.github/workflows/deploy-pages.yml @@ -0,0 +1,73 @@ +name: deploy-pages + +# Zero-credential GitHub Pages deploy of apps/website to +# https://hoainho.github.io/ohmyperf/ . Parallel to deploy-website.yml +# (Cloudflare Pages, needs secrets). Keep build steps in lockstep. + +on: + workflow_dispatch: {} + push: + branches: [main] + paths: + - 'apps/website/**' + - 'packages/viewer/**' + - 'packages/design-tokens/**' + - 'pnpm-lock.yaml' + - '.github/workflows/deploy-pages.yml' + +concurrency: + group: pages + cancel-in-progress: false + +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build website (static export with basePath=/ohmyperf) + env: + OHMYPERF_BASE_PATH: /ohmyperf + run: pnpm --filter '@ohmyperf/website...' build + + - name: Verify out/ exists + run: | + test -d apps/website/out || (echo "Missing apps/website/out — Next.js static export failed" && exit 1) + test -f apps/website/out/index.html || (echo "Missing apps/website/out/index.html" && exit 1) + echo "Static export OK ($(find apps/website/out -type f | wc -l) files)" + + - name: Disable Jekyll on Pages + run: touch apps/website/out/.nojekyll + + - uses: actions/configure-pages@v5 + + - uses: actions/upload-pages-artifact@v3 + with: + path: apps/website/out + + deploy: + needs: build + runs-on: ubuntu-24.04 + timeout-minutes: 10 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/deploy-website.yml b/.github/workflows/deploy-website.yml new file mode 100644 index 0000000..154109c --- /dev/null +++ b/.github/workflows/deploy-website.yml @@ -0,0 +1,64 @@ +name: deploy-website + +on: + workflow_dispatch: + inputs: + branch: + description: 'Cloudflare Pages branch (production = main, anything else = preview)' + required: false + default: 'main' + push: + branches: [main] + paths: + - 'apps/website/**' + - 'packages/viewer/**' + - 'packages/design-tokens/**' + - 'pnpm-lock.yaml' + - '.github/workflows/deploy-website.yml' + +concurrency: + group: deploy-website-${{ github.ref }} + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + deployments: write + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build website (static export) + run: pnpm --filter '@ohmyperf/website...' build + + - name: Verify out/ exists + run: | + test -d apps/website/out || (echo "Missing apps/website/out — Next.js static export failed" && exit 1) + test -f apps/website/out/index.html || (echo "Missing apps/website/out/index.html" && exit 1) + echo "Static export OK ($(find apps/website/out -type f | wc -l) files)" + + - name: Deploy to Cloudflare Pages + id: deploy + uses: cloudflare/wrangler-action@v3 + with: + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + gitHubToken: ${{ secrets.GITHUB_TOKEN }} + command: pages deploy apps/website/out --project-name=ohmyperf --branch=${{ github.event.inputs.branch || github.ref_name }} + + - name: Print deployment URL + run: | + echo "Deployed to: ${{ steps.deploy.outputs.deployment-url }}" + echo "Alias URL: ${{ steps.deploy.outputs.pages-deployment-alias-url }}" diff --git a/.github/workflows/publish-beta.yml b/.github/workflows/publish-beta.yml index 01eef45..8c20b4f 100644 --- a/.github/workflows/publish-beta.yml +++ b/.github/workflows/publish-beta.yml @@ -15,6 +15,7 @@ jobs: timeout-minutes: 20 permissions: contents: write + id-token: write steps: - uses: actions/checkout@v4 with: @@ -26,10 +27,43 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: "22" + node-version: "24" registry-url: "https://registry.npmjs.org" cache: pnpm + - name: Preflight — verify NPM_TOKEN authenticates (skipped in OIDC-only mode) + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + set +e + if [ -z "${NODE_AUTH_TOKEN}" ]; then + echo "::notice::NPM_TOKEN secret is empty — preflight skipped. Workflow will publish via OIDC trusted publishing only (see docs/PUBLISH-NPM-OIDC.md). If OIDC is not yet configured for these packages on npmjs.com, the publish step will fail with E404 — that is the signal to either (a) configure trusted publishers per the OIDC doc, or (b) set the NPM_TOKEN secret for token-based publishing." + exit 0 + fi + echo "NPM_TOKEN is set — running token-mode preflight." + WHOAMI_OUT=$(npm whoami 2>&1) + WHOAMI_RC=$? + if [ $WHOAMI_RC -ne 0 ]; then + { + echo "::error::NPM_TOKEN is set but does not authenticate. npm whoami output: $WHOAMI_OUT" + echo "::error::This is an E401-class failure (invalid or expired token)." + echo "::error::Fix: regenerate the token per docs/PUBLISH-NPM-TOKEN.md, OR remove the secret to use OIDC per docs/PUBLISH-NPM-OIDC.md." + } + exit 1 + fi + echo "npm whoami: $WHOAMI_OUT" + ACCESS_OUT=$(npm access list packages @ohmyperf 2>&1) + ACCESS_RC=$? + echo "$ACCESS_OUT" | head -20 + if [ $ACCESS_RC -ne 0 ]; then + { + echo "::warning::npm access list failed for @ohmyperf (exit=$ACCESS_RC)." + echo "::warning::Token may be a Granular Access Token without 'Read and write' on @ohmyperf scope." + echo "::warning::If the actual publish step below fails with E404 PUT, that is the symptom — see docs/PUBLISH-NPM-TOKEN.md." + } + fi + echo "Preflight passed: token authenticates." + - name: Install run: pnpm install --frozen-lockfile diff --git a/.github/workflows/publish-now.yml b/.github/workflows/publish-now.yml deleted file mode 100644 index 4524e0f..0000000 --- a/.github/workflows/publish-now.yml +++ /dev/null @@ -1,101 +0,0 @@ -name: Publish v0.1.1 (one-shot) - -on: - workflow_dispatch: - -concurrency: - group: publish-now - cancel-in-progress: false - -jobs: - publish: - runs-on: ubuntu-24.04 - timeout-minutes: 30 - permissions: - contents: write - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - ref: v0.1.1 - - - uses: pnpm/action-setup@v4 - - - uses: actions/setup-node@v4 - with: - node-version: "22" - registry-url: "https://registry.npmjs.org" - cache: pnpm - - - name: Verify on tag v0.1.1 - run: | - set -euo pipefail - CURRENT=$(node -p "require('./package.json').version") - if [ "$CURRENT" != "0.1.1" ]; then - echo "::error::Expected package.json version=0.1.1 (from tag v0.1.1), got $CURRENT" - exit 1 - fi - echo "Confirmed on v0.1.1 source tree" - - - name: Install - run: pnpm install --no-frozen-lockfile - - - name: Build all publishables - run: pnpm -r --filter "!@ohmyperf/website" --filter "!@ohmyperf/runner" --filter "!@ohmyperf/extension-chrome" --filter "!ohmyperf-vscode" build - - - name: Dry-run preview (final sanity) - run: pnpm -r publish --dry-run --no-git-checks 2>&1 | grep -E "^\+ @ohmyperf|public access" | head -40 - - - name: Publish to npm - run: pnpm publish -r --access public --no-git-checks - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - - name: Create GitHub release - uses: actions/github-script@v7 - with: - script: | - const fs = require('fs'); - const changelog = fs.readFileSync('CHANGELOG.md', 'utf8'); - const match = changelog.match(/## \[0\.1\.1\][\s\S]*?(?=\n## \[|$)/); - const body = match ? match[0] : '_See CHANGELOG.md_'; - try { - await github.rest.repos.createRelease({ - owner: context.repo.owner, - repo: context.repo.repo, - tag_name: 'v0.1.1', - name: 'ohmyperf v0.1.1 — fix trace-utils missing publish', - body: body + '\n\n---\n\n**Install:**\n```bash\nnpm install -g @ohmyperf/cli\n# or for AI agent integration:\nnpm install -g @ohmyperf/mcp-server\n```\n\nAll 15 `@ohmyperf/*` packages (incl. `@ohmyperf/trace-utils`) published with tag `latest`.', - prerelease: false, - target_commitish: '${{ github.sha }}', - }); - console.log('Release created'); - } catch (e) { - if (e.status === 422) { - console.log('Release already exists for v0.1.1 — skipping'); - } else { - throw e; - } - } - - - name: Close harness dogfood issue - uses: actions/github-script@v7 - with: - script: | - try { - await github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: 1, - body: 'Closed by automated v0.1.1 publish. 14 `@ohmyperf/*` packages live on npm registry; GitHub Release created at v0.1.1.', - }); - await github.rest.issues.update({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: 1, - state: 'closed', - }); - console.log('Issue #1 closed'); - } catch (e) { - console.log('Issue close failed (non-blocking):', e.message); - } diff --git a/.github/workflows/publish-stable.yml b/.github/workflows/publish-stable.yml index cea2a9e..fd17d53 100644 --- a/.github/workflows/publish-stable.yml +++ b/.github/workflows/publish-stable.yml @@ -20,6 +20,7 @@ jobs: timeout-minutes: 30 permissions: contents: write + id-token: write steps: - uses: actions/checkout@v4 with: @@ -31,24 +32,74 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: "22" + node-version: "24" registry-url: "https://registry.npmjs.org" cache: pnpm - name: Bot-commit guard (prevent loop) id: guard + env: + EVENT_NAME: ${{ github.event_name }} run: | AUTHOR=$(git log -1 --pretty=format:'%an') MSG=$(git log -1 --pretty=format:'%s') echo "Author: $AUTHOR" echo "Message: $MSG" - if [[ "$AUTHOR" == "github-actions[bot]" ]] || echo "$MSG" | grep -q "\[skip ci\]"; then + echo "Event: $EVENT_NAME" + if [ "$EVENT_NAME" = "workflow_dispatch" ]; then + echo "skip=false" >> $GITHUB_OUTPUT + echo "workflow_dispatch trigger — guard bypassed" + elif [[ "$AUTHOR" == "github-actions[bot]" ]] || echo "$MSG" | grep -q "\[skip ci\]"; then echo "skip=true" >> $GITHUB_OUTPUT echo "Bot commit / skip-ci marker detected — skipping publish" else echo "skip=false" >> $GITHUB_OUTPUT fi + - name: Preflight — verify NPM_TOKEN authenticates against registry (skipped in OIDC-only mode) + if: steps.guard.outputs.skip == 'false' + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + set +e + if [ -z "${NODE_AUTH_TOKEN}" ]; then + echo "::notice::NPM_TOKEN secret is empty — preflight skipped. Workflow will publish via OIDC trusted publishing only (see docs/PUBLISH-NPM-OIDC.md). If OIDC is not yet configured for these packages on npmjs.com, the publish step will fail with E404 — that is the signal to either (a) configure trusted publishers per the OIDC doc, or (b) set the NPM_TOKEN secret for token-based publishing." + exit 0 + fi + + echo "NPM_TOKEN is set — running token-mode preflight." + echo "Step 1: confirm token authenticates (npm whoami hits registry)" + WHOAMI_OUT=$(npm whoami 2>&1) + WHOAMI_RC=$? + if [ $WHOAMI_RC -ne 0 ]; then + { + echo "::error::NPM_TOKEN is set but does not authenticate. npm whoami output: $WHOAMI_OUT" + echo "::error::This is an E401-class failure (invalid or expired token)." + echo "::error::Fix: regenerate the token per docs/PUBLISH-NPM-TOKEN.md, OR remove the secret entirely to use OIDC per docs/PUBLISH-NPM-OIDC.md." + } + exit 1 + fi + echo "npm whoami: $WHOAMI_OUT" + + echo "Step 2: list packages visible to this token on @ohmyperf scope" + ACCESS_OUT=$(npm access list packages @ohmyperf 2>&1) + ACCESS_RC=$? + echo "$ACCESS_OUT" | head -20 + if [ $ACCESS_RC -ne 0 ]; then + { + echo "::warning::npm access list failed for @ohmyperf (exit=$ACCESS_RC)." + echo "::warning::Token may be a Granular Access Token without 'Read and write' on @ohmyperf scope." + echo "::warning::If the actual publish step below fails with E404 PUT, that is the symptom — see docs/PUBLISH-NPM-TOKEN.md." + } + fi + + # Note: npm publish --dry-run does NOT contact the registry (confirmed at + # github.com/npm/cli/issues/8525). Two known causes for E404 on PUT: + # (1) Token has Read-only scope on @ohmyperf (current most-likely cause). + # (2) Trusted-publisher environment mismatch (only relevant once OIDC enabled). + # The two checks above are the best preflight the npm CLI exposes today. + echo "Preflight passed: token authenticates." + - name: Install if: steps.guard.outputs.skip == 'false' run: pnpm install --frozen-lockfile @@ -155,7 +206,6 @@ jobs: | grep -E "^chore(\(.+\))?:" \ | grep -v "bump version" \ | grep -v "update CHANGELOG" \ - | grep -v "\[skip ci\]" \ | sed 's/^/- /' || true) body="" [ -n "$breaking" ] && body+=$'### \u26a0 Breaking Changes\n'"$breaking"$'\n\n' diff --git a/.github/workflows/publish-vscode.yml b/.github/workflows/publish-vscode.yml new file mode 100644 index 0000000..afaaf67 --- /dev/null +++ b/.github/workflows/publish-vscode.yml @@ -0,0 +1,58 @@ +name: publish-vscode + +on: + workflow_dispatch: + inputs: + dryRun: + description: 'Build .vsix only, do not publish to marketplace' + required: false + default: 'false' + +concurrency: + group: publish-vscode + cancel-in-progress: false + +jobs: + publish: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: pnpm + + - run: pnpm install --frozen-lockfile + + - name: Build extension bundle + run: pnpm --filter ohmyperf-vscode build + + - name: Verify extension-out/extension.js exists + run: | + test -f apps/ide-vscode/extension-out/extension.js || (echo "extension-out/extension.js missing — build failed" && exit 1) + BYTES=$(wc -c < apps/ide-vscode/extension-out/extension.js) + echo "Bundle size: ${BYTES} bytes" + + - name: Package .vsix + working-directory: apps/ide-vscode + run: pnpm exec vsce package --no-dependencies --out ohmyperf-vscode.vsix + env: + VSCE_PAT: ${{ secrets.VSCE_PAT }} + + - name: Upload .vsix artifact + uses: actions/upload-artifact@v4 + with: + name: ohmyperf-vscode-vsix + path: apps/ide-vscode/ohmyperf-vscode.vsix + retention-days: 30 + + - name: Publish to VSCode Marketplace + if: github.event.inputs.dryRun != 'true' + working-directory: apps/ide-vscode + run: pnpm exec vsce publish --no-dependencies --packagePath ohmyperf-vscode.vsix + env: + VSCE_PAT: ${{ secrets.VSCE_PAT }} diff --git a/.github/workflows/unpublish-nhonh.yml b/.github/workflows/unpublish-nhonh.yml deleted file mode 100644 index ed1b5b5..0000000 --- a/.github/workflows/unpublish-nhonh.yml +++ /dev/null @@ -1,77 +0,0 @@ -name: Unpublish @ohmyperf/* (one-shot cleanup) - -on: - workflow_dispatch: - -concurrency: - group: unpublish-nhonh - cancel-in-progress: false - -jobs: - unpublish: - runs-on: ubuntu-24.04 - timeout-minutes: 15 - steps: - - uses: actions/setup-node@v4 - with: - node-version: "22" - registry-url: "https://registry.npmjs.org" - - - name: Unpublish all @ohmyperf/* versions - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - run: | - set -uo pipefail - PKGS=( - "@ohmyperf/trace-utils" - "@ohmyperf/design-tokens" - ) - FAILED=() - for pkg in "${PKGS[@]}"; do - echo "" - echo "=== Unpublishing $pkg ===" - # Probe registry first — if already 404 (previous run unpublished it), skip - ENCODED="${pkg//\//%2F}" - CODE=$(curl --max-time 8 -s -o /dev/null -w "%{http_code}" "https://registry.npmjs.org/$ENCODED") - if [ "$CODE" = "404" ]; then - echo " → already gone (registry 404), skipping" - continue - fi - OUTPUT=$(npm unpublish "$pkg" --force 2>&1) - STATUS=$? - if [ $STATUS -eq 0 ]; then - echo " → unpublished $pkg (all versions)" - elif echo "$OUTPUT" | grep -q "Not Found"; then - echo " → already gone (npm Not Found), skipping" - else - echo " $OUTPUT" | head -5 - echo " → FAILED to unpublish $pkg" - FAILED+=("$pkg") - fi - done - echo "" - echo "=== Summary ===" - if [ ${#FAILED[@]} -eq 0 ]; then - echo "All ${#PKGS[@]} packages unpublished successfully." - else - echo "Failed: ${FAILED[*]}" - echo "::warning::Some unpublishes failed. May be outside 72h window or already gone." - fi - - - name: Verify removal - run: | - set -u - PKGS=( - "@ohmyperf/cli" "@ohmyperf/mcp-server" "@ohmyperf/core" "@ohmyperf/design-tokens" - "@ohmyperf/driver-playwright" "@ohmyperf/plugins-builtin" "@ohmyperf/viewer" - "@ohmyperf/share-client" "@ohmyperf/reporter-json" "@ohmyperf/reporter-html" - "@ohmyperf/reporter-deck" "@ohmyperf/reporter-markdown" "@ohmyperf/reporter-junit" - "@ohmyperf/reporter-csv" "@ohmyperf/trace-utils" - ) - for pkg in "${PKGS[@]}"; do - URL="https://registry.npmjs.org/${pkg//\//%2F}" - CODE=$(curl --max-time 8 -s -o /dev/null -w "%{http_code}" "$URL") - echo " $pkg → $CODE" - done - echo "" - echo "Expected: 404 for fully-unpublished packages." diff --git a/CHANGELOG.md b/CHANGELOG.md index b38a90e..97c059b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +The next release will ship as **v0.2.0** (not v0.1.1 — Wave 1 fixes were rolled forward into v0.2.0). Will land when [issue #7](https://github.com/hoainho/ohmyperf/issues/7) clears the npm credential gate. The `publish-stable.yml` workflow auto-generates the categorised changelog from conventional-commit titles in `git log v0.1.0..HEAD`. + +Highlights staged for v0.2.0 (see [issue #7](https://github.com/hoainho/ohmyperf/issues/7) for full inventory): + +- **Agent fix loop**: new MCP tools `propose_patch` + `verify_fix` (issue #6). The only perf tool where an AI agent can both fix a CWV regression and statistically prove the fix improved metrics, in one conversation turn. +- **LLM-first report signals** (Phase 1-6 of the v0.2.0 session): + - `Report.trustScore` — overall + per-metric verdict (high|medium|low|unreliable) with `sampleConfidence` + `effectConfidence` decomposition and `recommendedAction` for noisy measurements. + - `Report.fixPlan` — ranked, deduped, ROI-scored list of actionable patches. Each entry has `applicability: first-party | third-party-cannot-apply | unknown`. + - `Report.meta.servability` — heuristic classification (real-page | bot-challenge-suspected | error-page | timeout-partial | unknown) so agents skip un-actionable measurements. + - `Resource.originClass` — same-origin | same-site | same-org | cross-site | unknown. New `MeasureOptions.orgDomains` (+ `OHMYPERF_ORG_DOMAINS` env var) marks org-owned CDNs as first-party. +- **3 new MCP tools** (precomputed slices for LLM agents): `get_fix_plan`, `get_trust_score`, `get_servability`. +- **`@ohmyperf/eslint-plugin`** v0.2.0 — 7 CWV-linked ESLint rules. +- **`@ohmyperf/fixers`** v0.2.0 — Archetype registry + `proposePatches()` engine. +- **Real cross-origin OOPIF inspection** — each cross-origin iframe gets a per-frame CDP session. +- **INP measurable in CI** — `--synthetic-interaction=auto-click` fires a trusted-event pipeline. +- **Source-map detection** — `longestScript.sourceLocation` schema slot (stage 1; full VLQ decode deferred to v0.3, issue #4). +- **8 Wave-1 CLI/MCP/Core fixes** rolled forward — see commit [`415ad60`](https://github.com/hoainho/ohmyperf/commit/415ad60) for the per-fix list. + +### Type-level additive-but-breaking-for-constructors changes (v0.2.0) + +These are additive for READERS but require updates for code that CONSTRUCTS these types (test fixtures, mock data, downstream JSON producers): + +- `OriginClass` union gained `"same-org"` member. Exhaustive `switch` statements over `OriginClass` need a new `case`. In this workspace: no consumers affected. +- `MetricTrustVerdict` gained two required fields `sampleConfidence` + `effectConfidence`. Code that constructs `MetricTrustVerdict` literals (e.g. test mocks) must populate them. The existing `level` field is preserved and still equals `worstLevel(sample, effect)` for backward-compat readers. + ## [0.1.0] - 2026-05-19 First public release. **15 `@ohmyperf/*` packages** published to npm. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d0f8b5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to OhMyPerf + +Thanks for considering a contribution. This document captures the conventions +that keep the codebase honest and the agent loop reliable. + +## Quick start + +```bash +git clone https://github.com/hoainho/ohmyperf +cd ohmyperf +pnpm install +pnpm build +pnpm test # 387 tests across 18 workspaces +pnpm typecheck # strict TS with exactOptionalPropertyTypes +pnpm lint # import-layering + style rules +``` + +Node ≥ 22, pnpm ≥ 10. + +## What this project values + +OhMyPerf measures real performance on real browsers. The codebase reflects that +discipline: **every numeric claim is grounded in a tool call, never in agent +intuition**. PRs that paper over real measurement variance to make numbers look +better will be rejected. + +Specifically: + +- **No synthetic numbers in real-mode.** If a metric is unreliable, the report + must say `unstable: true` and surface the CoV. Don't hide noise. +- **No silent fallbacks.** If `Input.dispatchMouseEvent` can't find a target, + the report explicitly says so — it does not silently return INP=0. +- **No type-safety escape hatches.** `as any`, `@ts-ignore`, and + `@ts-expect-error` are blocked at lint time. Same goes for empty + `catch (e) {}` blocks. +- **Tests fail fast.** Deleting or skipping a failing test to ship a PR is + considered a Forbidden Practice (see `docs/HARNESS.md`). + +## Submitting a change + +1. **Open an issue first** for non-trivial work. Even a one-line description is + enough — the issue ID becomes the audit trail. +2. **Branch from `main`**, with one of these prefixes: `feat/`, `fix/`, + `docs/`, `refactor/`, `chore/`, `test/`, `perf/`. +3. **Match existing patterns.** Sample 2-3 similar files before introducing a + new convention. If you genuinely need a new pattern, propose it in the + issue. +4. **Run the validation ladder before pushing**: + - `pnpm typecheck` (clean across all 18 workspaces) + - `pnpm lint` (no new warnings) + - `pnpm test` (no new failures, no new skips) + - `pnpm build` (exit code 0 in turbo) +5. **Keep commits atomic.** One logical change per commit, with a message that + explains the *why*, not the *what*. +6. **Open a pull request.** The PR template will ask you to confirm the + ladder ran green. + +## OpenSpec proposals + +Significant changes — anything that touches the public API surface, the report +schema, or the plugin interface — must include an OpenSpec proposal in +`openspec/`. See an example at `openspec/specs/`. + +For tiny PRs (typo, dependency bump, internal refactor), an OpenSpec is not +required. + +## Tested-in-production discipline + +Every PR that adds a user-facing feature must include either: + +- A test against a real production URL (`test:real-world` validation layer + from `docs/HARNESS.md`), or +- An explanation in the PR description of why a synthetic fixture is + sufficient. + +"It compiled" is not evidence the feature works. + +## Reporting performance bugs in the measurement engine + +If you find a case where OhMyPerf reports a CWV value materially different +from the real user experience (>15% drift after `mode: "ci-stable"` with +runs=10), please file an issue with: + +1. Full repro URL. +2. The full `report.json` (drag-drop onto `https://ohmyperf.dev/viewer` to + verify it's parseable, then paste). +3. The expected value + how you measured it independently (RUM data, + Lighthouse score, WebPageTest run, etc.). + +Measurement bugs are P0. + +## Security + +See [SECURITY.md](./SECURITY.md). Do not file security issues in public. + +## License + +By contributing, you agree your contribution is licensed under Apache-2.0 +(matching the repo). + +Thank you. diff --git a/PHASE_2_3_REPORT_2026-05-20.md b/PHASE_2_3_REPORT_2026-05-20.md new file mode 100644 index 0000000..30662cf --- /dev/null +++ b/PHASE_2_3_REPORT_2026-05-20.md @@ -0,0 +1,158 @@ +# ohmyperf v0.2.0 Phase 2-3: Real-World Test + Self-Review + +**Date**: 2026-05-20 13:55-14:01 UTC +**Tool**: `@ohmyperf/mcp-server` from local build at commit [`dc710f2`](https://github.com/hoainho/ohmyperf/commit/dc710f2) (post-Phase-1) +**Method**: MCP stdio with new v0.2.0 LLM-first signals enabled +**Sites tested**: 10 (2 priority: tradeit.gg, sweeps.qa3; 8 secondary) + +--- + +## Phase 2: 10-site headline results — NEW SIGNALS visible + +| # | Site | LCP | Trust | Servability | Total fix | First-party fix | Origin (so/ss/xs) | Outcome | +|---|------|-----|-------|-------------|-----------|-----------------|-------------------|---------| +| 1 | **tradeit.gg** ⭐ | 1804ms | low | real-page | **18** | **18** | 178/0/52 | ✅ rich fix plan | +| 2 | **sweeps.qa3** ⭐ | 2700ms | low | real-page | 0 | 0 | 7/1/**38** | ⚠ all blockers cross-site | +| 3 | Wikipedia (perf article) | 356ms | medium | real-page | 2 | 2 | 26/0/4 | ✅ | +| 4 | web.dev/articles/vitals | 1208ms | low | real-page | 4 | 0 | 9/0/64 | ⚠ all blockers cross-site | +| 5 | GitHub Homepage | 532ms | low | real-page | 20 | 0 | 1/4/144 | ⚠ origin-class FP (see §3.1) | +| 6 | Hacker News | 940ms | low | real-page | 1 | 1 | 6/0/0 | ✅ | +| 7 | Stack Overflow | 349ms | low | **bot-challenge-suspected** | 0 | 0 | 4/0/2 | ✅ correctly flagged | +| 8 | Reddit | 524ms | low | real-page | 0 | 0 | 2/0/1 | (Reddit served minimal page) | +| 9 | npmjs.com | ❌ timeout 30s | — | — | — | — | — | network error | +| 10 | vercel.com | 504ms | low | real-page | 35 | 35 | 288/0/6 | ✅ richest fix plan | + +**Empirical signal distribution:** +- Servability: 8/9 `real-page`, 1/9 `bot-challenge-suspected` (Stack Overflow). Correctly catches what Round-14 demo (npmjs.com) caught. +- Trust: 8/9 `low`, 1/9 `medium`. Confirms 3-run measurements + no calibration → low confidence by design. +- First-party fix count: ranges from 0 to 35. Real differentiator between optimizable sites (tradeit.gg, vercel) vs heavy-third-party-dependent (GitHub, web.dev, sweeps.qa3). + +--- + +## Priority site #1: tradeit.gg deep-dive + +**18 first-party render-blocking-stylesheet patches** generated. Top 3 actionable: + +``` +#1 [render-blocking-stylesheet-media-print] https://tradeit.gg/_nuxt/Confirm.zQ5b604N.css (117ms, medium) +#2 [render-blocking-stylesheet-media-print] https://tradeit.gg/_nuxt/LoginButton.DVfW5dYf.css (117ms, medium) +#3 [render-blocking-stylesheet-media-print] https://tradeit.gg/_nuxt/TextField.C8Qy0XBT.css (117ms, medium) +``` + +Each patch is a one-line diff: +```diff +- 4000ms) — the page would still benefit from the 18 identified first-party fixes, but the LCP itself does not cross the 2500ms "good" threshold. With low trust, agent should rerun `--runs 10 --mode ci-stable` before claiming budget regressions, but the fix opportunity is genuine regardless of trust. + +--- + +## Priority site #2: sweeps.qa3.jarvisqa.net deep-dive + +**0 fix plan entries despite LCP=2700ms (POOR).** + +Trust reasons: `n=3, mode=real, no_calibration, unstable_flag_set` → trust=low. +Origin breakdown: **7 same-origin + 1 same-site + 38 cross-site** (radical 3rd-party-heavy SPA). + +The 0-fix result is HONEST: render-blocking resources are all third-party (e.g., analytics, CDN, etc.) which can't be patched by the sweeps team. This is exactly what `originClass` is for — instead of producing 38 useless patches against 3rd-party URLs, ohmyperf correctly returns "no actionable fixes from your code; review your third-party dependencies." + +For sweeps team this is more valuable than a long list of un-applicable patches: it tells them the bottleneck is in dependency choices, not their code. + +**Honest caveat**: with 3 runs on a noisy QA env (CoV likely high), the LCP=2700ms number itself should be re-validated with `runs=10`. + +--- + +## Phase 3: Self-Review — Strengths, Weaknesses, Fix Plan + +### ✅ Strengths the 10-site run validates + +1. **`servabilityClass` works in production.** Stack Overflow correctly flagged as `bot-challenge-suspected`. The heuristic (≤3 resources, <10KB, no JS, or Cloudflare URLs) caught a real anti-automation page. +2. **`trustScore` correctly reflects 3-run noise.** 8/9 sites = low trust. Recommended action consistently points at `--runs 10 --mode ci-stable`. +3. **`fixPlan` ranking with applicability works.** GitHub returned 20 patches all marked `third-party-cannot-apply` — agent saves time NOT trying to defer githubassets.com URLs the GitHub team can't change from their app. tradeit.gg returned 18 first-party-ready patches — agent goes straight to applying them. +4. **End-to-end MCP roundtrip stable.** 9/10 tool calls succeeded. The 1 failure (npmjs.com timeout) returned a structured error, not a crash. +5. **Schema is backward-compatible.** New fields (`trustScore`, `fixPlan`, `servability`, `originClass`) are all optional. Old reports parse fine; new reports add the LLM-discoverability layer. + +### 🔴 Weaknesses revealed by real-world testing + +#### W1 — `originClass=cross-site` false positive on org-owned CDNs (GitHub, web.dev) + +**Symptom**: `github.com` page has 144 cross-site resources, but most are `githubassets.com` — owned by GitHub itself. My algorithm marks them third-party-cannot-apply, but the GitHub team CAN modify them. Same issue with `web.dev` (owned by Google) referencing `gstatic.com`, `googletagmanager.com`. + +**Impact**: HIGH for any org with CDN sharding pattern. False-positive rate ~5/10 sites tested. + +**Root cause**: Registrable-domain comparison is the W3C "same-site" spec but doesn't account for "same-org" ownership. + +**Fix**: Need optional config (per measurement) — `OHMYPERF_ORG_DOMAINS=github.com,githubassets.com,githubusercontent.com` — to merge orgs into a single applicability bucket. Or a `Resource.originClass: "same-org"` tier driven by an opt-in domain list. + +**Priority**: P0 — without this, the killer differentiator (applicability filtering) misclassifies on every org with multiple domains. + +#### W2 — Trust score "low" for every 3-run measurement + +**Symptom**: 8/9 sites = trust low because `runs<5`. Even when CoV is very low (e.g., Wikipedia n=3 cov 5% — should be medium-high), the n<5 rule dominates. + +**Impact**: MED. Agent sees trust=low everywhere → desensitization. The signal becomes noise. + +**Root cause**: My `classifyMetric` defaults to medium for n<5 even with low CoV, but the cascade `worstLevel()` drops overall to low whenever any metric has the warning. + +**Fix**: Differentiate between "sample size warning" (still actionable) vs "noise warning" (don't act). Maybe split into 2 fields: `sampleConfidence` + `effectConfidence` (per Oracle's suggestion in Gap 8 of the deep-design pass). + +**Priority**: P1. + +#### W3 — Servability misses some bot-challenge variants + +**Symptom**: Reddit returned 2 resources, 195 KB — my heuristic saw "more than 3 resources OR more than 10KB" → real-page. But empirically Reddit returned a near-empty SPA shell (LCP=524ms is suspicious for Reddit). + +**Impact**: MED. Reddit's LCP claim is likely measuring a login wall, not the real Reddit. + +**Root cause**: Heuristic too narrow. Needs to also check for: very low DOM node count (`runtime.layoutCount < 5`), or `text/html` as ONLY mimeType (no JS framework loaded). + +**Fix**: Expand servability heuristic to include those signals. Could also add `meta.servability.likelihood: number (0-1)` instead of binary classification — gives the agent room to use a threshold. + +**Priority**: P2. + +#### W4 — `fixPlan` always uses opportunity-level `wastedMs` as `expectedImpactMs` + +**Symptom**: Every patch claims its `wastedMs` from the audit. tradeit.gg's 18 patches all claim 117ms — same number, copy-pasted from `wastedMs`. That's clearly wrong; some patches help more than others. + +**Impact**: MED. ROI sorting doesn't actually differentiate within an opportunity since all items have ≈ same value. + +**Root cause**: `Opportunity.items[].wastedMs` is sometimes per-item, sometimes total — I treat them uniformly. + +**Fix**: Need to (a) detect when item.wastedMs is repeated (artifact of estimation), (b) fall back to resource bytes × estimated transfer time when items share a fictitious value, OR (c) just be honest in `confidence` — drop to "low" when wastedMs is suspect. + +**Priority**: P1. + +#### W5 — No tests against tradeit.gg shape (gambling/marketplace + Nuxt SSR) + +**Symptom**: My unit tests cover synthetic + 4 archetype shapes. None cover the Nuxt CSS-chunk pattern that tradeit.gg ships. Could be edge cases not exercised. + +**Impact**: LOW — fixes worked in production demo. But coverage gap. + +**Fix**: Add fixture-based integration test that replays the tradeit.gg report against `buildFixPlan` + asserts the 18 patches are produced. + +**Priority**: P2. + +### Phase 4 fix plan (immediate next step) + +| # | Fix | Priority | Effort | Files | +|---|-----|----------|--------|-------| +| W1 | Add `originClass: "same-org"` tier + `OHMYPERF_ORG_DOMAINS` config | P0 | 1h | `llm-signals/origin-class.ts`, `engine.ts`, `types.ts` | +| W4 | `confidence: "low"` for items with repeated `wastedMs` (estimation artifact); never higher than "medium" if confidence is uncertain | P1 | 30min | `llm-signals/fix-plan.ts` | +| W2 | Split trustScore into `sampleConfidence` + `effectConfidence` | P1 | 45min | `llm-signals/trust-score.ts`, `types.ts` | +| W3 | Expand servability heuristic with DOM-node + mimeType-only signals | P2 | 30min | `llm-signals/servability.ts` | +| W5 | Fixture test for tradeit.gg-shaped report | P2 | 30min | `llm-signals/llm-signals.test.ts` | + +**Order**: W1 first (largest impact, unlocks honest applicability scoring). Then W4 (kills the "117ms × 18" duplication). Then W2-W3 in parallel. W5 last as documentation/regression guard. + +### Phase 5-7 plan (queued) + +- **P5 (QA)**: After fixes, fan out 3-4 background agents: + - explore: re-run sub-set of 10 sites, verify W1 fix changes applicability counts + - oracle: review the W1-W5 fixes for correctness + edge cases + - librarian: confirm no new competitor capability surfaced overnight that would change the differentiation thesis +- **P6**: Address all QA feedback to 100% confirmation. +- **P7**: PR with full Phase 1-4 diff, request Gemini review, iterate. diff --git a/README.md b/README.md index 10d50dd..9feabc0 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,126 @@ # OhMyPerf -> Real-machine, real-browser web performance measurement. -> Lighthouse and PageSpeed Insights run on synthetic CPUs in a Google datacenter. -> OhMyPerf runs on **your hardware** with **your browser** and reports what your users actually experience. +> **The first perf tool an LLM agent can actually fix your site with — statistical proof, not vibes.** -**v0.1.0** · **License**: Apache-2.0 · **npm**: [`@ohmyperf/cli`](https://www.npmjs.com/package/@ohmyperf/cli) + [`@ohmyperf/mcp-server`](https://www.npmjs.com/package/@ohmyperf/mcp-server) · **Repo**: [`hoainho/ohmyperf`](https://github.com/hoainho/ohmyperf) +🌐 **Try the viewer live**: [hoainho.github.io/ohmyperf/viewer/](https://hoainho.github.io/ohmyperf/viewer/) — drag any `report.json` onto the page and inspect every metric, every long-task, every render-blocking opportunity in your browser. No install, no signup. + +[![npm](https://img.shields.io/npm/v/@ohmyperf/cli?label=%40ohmyperf%2Fcli&color=cb3837)](https://www.npmjs.com/package/@ohmyperf/cli) +[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed)](https://modelcontextprotocol.io) +[![Chromium](https://img.shields.io/badge/real--browser-Chromium-4285f4)](https://www.chromium.org/) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE) + +OhMyPerf measures Core Web Vitals on a **real machine** with a **real Chromium**, then closes the loop: an AI agent can call **`measure → propose_patch → verify_fix`** in one conversation turn — and prove the fix improved your LCP/INP/CLS with a **Mann-Whitney U test at α=0.05**, not "looks better to me." + +``` +┌──────────┐ ┌───────────────┐ ┌──────────────┐ +│ measure │ → │ propose_patch │ → │ verify_fix │ +│ real CWV │ │ ranked, ROI │ │ p-value per │ +│ + trust │ │ first-party │ │ metric │ +└──────────┘ └───────────────┘ └──────────────┘ + ↓ ↓ ↓ + trustScore fixPlan verdict: + servability (18 patches improvement | + originClass for tradeit.gg) neutral | + regression +``` + +## 30-second demo + +Real CLI output, no editing: + +```bash +$ npx -y @ohmyperf/cli@latest run https://example.com --runs 2 --format json +[ohmyperf] INFO OhMyPerf v1.0.0 report +[ohmyperf] INFO url: https://example.com +[ohmyperf] INFO browser: chromium 148.0.7778.0 (bundled) +[ohmyperf] INFO mode: real; runs=2; duration=2430ms +[ohmyperf] INFO aggregated: +[ohmyperf] INFO lcp median= 256.0 cov=25.0% n=2 +[ohmyperf] INFO cls median= 0.000 cov= 0.0% n=2 +[ohmyperf] INFO fcp median= 256.0 cov=25.0% n=2 +[ohmyperf] INFO ttfb median= 224.5 cov=25.5% n=2 +[ohmyperf] INFO tbt median= 0.0 cov= 0.0% n=2 +[ohmyperf] INFO runtime.taskDuration median= 25.2 cov=20.2% n=2 +[ohmyperf] INFO wrote /path/to/ohmyperf-out/report.json +``` + +The full [`report.json`](packages/core/src/types.ts) is what LLM agents see — including (v0.2.0, pending publish): + +- `Report.trustScore` — overall + per-metric `{level, sampleConfidence, effectConfidence, recommendedAction}` +- `Report.fixPlan` — ranked, deduped, ROI-scored patches with `applicability: first-party | third-party-cannot-apply` +- `Report.meta.servability` — `real-page | bot-challenge-suspected | error-page | timeout-partial | unknown` +- Every `Resource` tagged with `originClass: same-origin | same-site | same-org | cross-site` + +CoV 25% on 2 runs (above 20% noise floor) → `trustScore: low` → agent's `recommendedAction: "rerun with --runs 10 or --mode ci-stable before drawing budget conclusions"`. Honest about its own variance, not vibes. + +## Why this exists + +| | Lighthouse / PSI | OhMyPerf | +|---|---|---| +| **Runs on** | Synthetic CPU in a Google datacenter | Your actual hardware | +| **Cross-origin iframes** | Network-only (opaque inside) | Per-frame CDPSession (~99% coverage) | +| **Agent-callable** | None | MCP server, 16 tools | +| **Statistical proof of fix** | Threshold gates (flake-prone) | Mann-Whitney U, α=0.05, per-metric noise floors | +| **First-party vs CDN** | Manual eyeballing | `originClass` + `same-org` tier for org-owned CDNs | +| **Bot challenge detection** | Treats Cloudflare interstitials as real pages | `servability: bot-challenge-suspected` | +| **Honest about variance** | One number, take it or leave it | `trustScore` + per-metric CoV + `recommendedAction` | ## Install ```bash -# CLI for humans + CI +# CLI npm install -g @ohmyperf/cli ohmyperf run https://your-site.com -# MCP server for AI coding agents (Claude in OpenCode, Cursor, Copilot) +# MCP server — for Claude (OpenCode/Cursor/Cline) to call tools directly npm install -g @ohmyperf/mcp-server -``` -Or use `npx -y @ohmyperf/cli run https://your-site.com` for a zero-install one-off. +# Zero-install one-off +npx -y @ohmyperf/cli@latest run https://your-site.com +``` Requires Node ≥ 22. Playwright Chromium auto-downloads on first run (~150 MB). +## Use it from an AI agent + +Add to your MCP client config (Claude Desktop example): + +```json +{ + "mcpServers": { + "ohmyperf": { + "command": "npx", + "args": ["-y", "@ohmyperf/mcp-server@latest"] + } + } +} +``` + +Then your LLM has 16 tools available: `measure`, `propose_patch`, `verify_fix`, `get_fix_plan`, `get_trust_score`, `get_servability`, `diff`, `list_reports`, and more. Tested with Claude, OpenCode, Cursor, Cline. + +## Architecture + ``` ┌─────────────────────────────────────────────────────────────────┐ -│ Engine: @ohmyperf/core (45-export API, frozen) │ +│ Engine: @ohmyperf/core (frozen 1.0.0 public API) │ │ · Playwright + raw CDP (Target.setAutoAttach for cross-origin) │ │ · Plugin runtime · Calibration · Outlier rejection · Diff │ +│ · LLM-first signals: trustScore · fixPlan · servability │ └─────────────────────────────────────────────────────────────────┘ │ - ├──► CLI npx ohmyperf run + ├──► CLI npx -y @ohmyperf/cli run ├──► npm SDK import { runEngine } from "@ohmyperf/core" - ├──► Chrome extension chrome.debugger driver, click → measure - ├──► Website ohmyperf.dev landing + drag-drop /viewer - ├──► VSCode extension OhMyPerf: Measure URL (command palette) - ├──► MCP server AI agents call measure/diff tools - └──► Share-server Hono on Cloudflare Workers or Node + ├──► MCP server 16 tools for LLM agents + ├──► Chrome extension click toolbar icon → measure current tab + ├──► VSCode extension Cmd+Shift+P → OhMyPerf: Measure URL + ├──► Website hoainho.github.io/ohmyperf — drop report.json on /viewer + ├──► Share-server Cloudflare Workers or Node + ├──► ESLint plugin 7 CWV-linked rules at editor-save time + └──► Fixers SDK archetype registry + proposePatches() ``` +**Status**: v0.1.0 on npm. v0.2.0 ([issue #7](https://github.com/hoainho/ohmyperf/issues/7)) ships the agent fix loop + LLM-first signals + 2 new packages, pending credential refresh. + ## Why OhMyPerf | Concern | Lighthouse / PageSpeed | OhMyPerf | @@ -57,12 +141,14 @@ Requires Node ≥ 22. Playwright Chromium auto-downloads on first run (~150 MB). | # | Surface | Package | Quickstart | |---|---|---|---| | 1 | **CLI** | [`@ohmyperf/cli`](apps/cli/) | `ohmyperf run https://example.com` | -| 2 | **npm SDK** | [`@ohmyperf/core`](packages/core/) | `import { runEngine } from "@ohmyperf/core"` | +| 2 | **npm SDK** | [`@ohmyperf/core`](packages/core/) | `import { runEngine, measure } from "@ohmyperf/core"` | | 3 | **Chrome extension** | [`apps/extension-chrome/`](apps/extension-chrome/) | Load unpacked → click toolbar icon | | 4 | **Website (SPA)** | [`apps/website/`](apps/website/) · spec [`measurement-spa`](openspec/specs/measurement-spa/spec.md) | `pnpm --filter @ohmyperf/website dev` → measure at `/measure`, view at `/viewer`, history at `/report`. Static export to CF Pages. | | 5 | **VSCode extension** | [`apps/ide-vscode/`](apps/ide-vscode/) | `Cmd+Shift+P` → `OhMyPerf: Measure URL` | -| 6 | **MCP server** | [`apps/mcp-server/`](apps/mcp-server/) | `tools/measure({ url })` from any MCP client | +| 6 | **MCP server** | [`apps/mcp-server/`](apps/mcp-server/) | 14 tools incl. `measure`, `propose_patch` (v0.2.0), `verify_fix` (v0.2.0) | | 7 | **Share-server** | [`packages/share-server/`](packages/share-server/) | Cloudflare Workers or `node dist/node.js` | +| 8 | **ESLint plugin** *(v0.2.0)* | [`@ohmyperf/eslint-plugin`](packages/eslint-plugin/) | `npm i -D @ohmyperf/eslint-plugin` + `extends: ['plugin:ohmyperf/recommended']` | +| 9 | **Fixer SDK** *(v0.2.0)* | [`@ohmyperf/fixers`](packages/fixers/) | `import { proposePatches } from "@ohmyperf/fixers"` | ## CLI quickstart @@ -212,32 +298,58 @@ OhMyPerf ships an MCP (Model Context Protocol) server so AI agents like **Claude ### Tools exposed +> **What's available where**: `@ohmyperf/mcp-server@0.1.0` currently on npm exposes the 12 tools NOT marked `(v0.2.0)`. The 2 v0.2.0-tagged tools (`propose_patch`, `verify_fix`) are committed on `main` and will land when v0.2.0 publishes — track at [issue #7](https://github.com/hoainho/ohmyperf/issues/7). + | Tool | Input | Output | |---|---|---| -| `measure` | `{ url, runs?, mode?, plugins?, browserPath? }` | Human summary + `aggregated` JSON; full report saved + exposed as resource | +| `measure` | `{ url, runs?, mode?, plugins?, browserPath?, collectTrace? }` | Human summary + `Saved to: ` + `aggregated` JSON; full report saved + exposed as resource | | `diff` | `{ baseline, candidate, failOnRegression? }` | Mann-Whitney significance table + `{ hasRegressions, metrics }` | +| `analyze_report` | `{ reportPath \| uri, insightName, limit? }` | Slice for one insight (lcp-breakdown / render-blocking / long-tasks / third-parties / opportunities / audits / resources / frames) | +| `generate_markdown_summary` | `{ reportPath \| uri, title? }` | PR-comment-ready Markdown summary with 🟢/🟡/🔴 verdict block | +| `generate_html_report` | `{ reportPath \| uri, outputDir?, theme?, style? }` | Single-file HTML viewer written to disk | +| `generate_deck` | `{ reportPath \| uri, outputDir?, style?, title? }` | Multi-slide HTML presentation (⌘P → PDF for stakeholder distribution) | +| `find_regression_cause` | `{ baseline, candidate }` | Ranked hypotheses (new render-blocking, grown assets, new long tasks, new third-parties) with evidence | +| `enforce_budget` | `{ url, budget, mode?, runs? }` | CI-style pass/fail per metric with exit-code-style verdict | +| `track_url` | `{ url, runs?, mode?, ... }` | Measure + append to time-series + return improving/stable/regressing trend | +| **`propose_patch`** *(v0.2.0)* | `{ reportPath \| uri, opportunityId?, url?, maxPatches? }` | Structured `{ archetype, url, search, replace, rationale, expectedImpactMs, confidence }[]` patches an agent can apply | +| **`verify_fix`** *(v0.2.0)* | `{ baselineReportPath \| baselineUri, candidateUrl, runs?, mode? }` | Re-measures candidate + Mann-Whitney U diff vs baseline; verdict `✅ no regression` / `❌ REGRESSION DETECTED` | +| `list_runs` / `list_styles` / `diff_resources` | various | Resource browsing + brand catalog + URI-based diff | Saved reports surface as resources at `ohmyperf://reports/-.json` so the agent can read them back later without re-measuring. -## Website (`ohmyperf.dev`) +### Killer flow: closed agent fix loop (v0.2.0) + +``` +1. measure(url) → report.json + opportunities +2. propose_patch(reportPath) → { archetype: "render-blocking-script-add-defer", + search: ';", + ], + invalid: [ + { + code: "const x =