diff --git a/agent-skills/references/using-scripts.md b/agent-skills/references/using-scripts.md index 4f2cf34..1b3bb67 100644 --- a/agent-skills/references/using-scripts.md +++ b/agent-skills/references/using-scripts.md @@ -47,7 +47,7 @@ When an existing package already does what you need, you can reference it direct * Bundled with Node.js — no extra install needed. * Downloads the package, runs it, and caches it for future use. - * Pin versions with `npx package@version` for reproducibility. + * **Pin versions for any command an agent will copy-paste** (`npx package@version`, e.g. `npx eslint@9.0.0`) so the command behaves the same over time — never leave a copy-pasteable `npx` invocation unpinned. diff --git a/anydoc/references/cli-reference.md b/anydoc/references/cli-reference.md index 7a76560..9a27050 100644 --- a/anydoc/references/cli-reference.md +++ b/anydoc/references/cli-reference.md @@ -112,11 +112,11 @@ curl -s https://example.com/paper.pdf | npx -y @firecrawl/anydoc@0.1.6 - # URL ### Version pinning Always pin the version: `npx -y @firecrawl/anydoc@0.1.6`. An unpinned -`npx -y @firecrawl/anydoc` floats to the latest published tag, so conversions -are not reproducible across time. All behavior in this skill is documented -against **0.1.6**. The `-y` flag answers npx's "Ok to proceed?" install prompt -non-interactively; without it, bare `npx @firecrawl/anydoc` will prompt on a -cold cache. +invocation (`npx -y @firecrawl/anydoc` with no `@version` suffix) floats to the +latest published tag, so conversions are not reproducible across time. All +behavior in this skill is documented against **0.1.6**. The `-y` flag answers +npx's "Ok to proceed?" install prompt non-interactively — omitting it means npx +asks for confirmation before installing a cold-cache package. ### First run and offline behavior diff --git a/hugo-theme/references/seo-outputs-testing.md b/hugo-theme/references/seo-outputs-testing.md index 4b5ec7b..d184f5e 100644 --- a/hugo-theme/references/seo-outputs-testing.md +++ b/hugo-theme/references/seo-outputs-testing.md @@ -305,7 +305,7 @@ jobs: - name: Accessibility audit run: | - npx @axe-core/cli http://localhost:1313/ --exit --stdout || true + npx @axe-core/cli@4.13.0 http://localhost:1313/ --exit --stdout || true ``` @@ -315,7 +315,7 @@ jobs: |------|---------|-------------| | `html5validator` | HTML spec compliance | `pip install html5validator` | | `broken-link-checker` | Dead links | `npm install broken-link-checker` | -| `@axe-core/cli` | Accessibility | `npx @axe-core/cli` | +| `@axe-core/cli` | Accessibility | `npx @axe-core/cli@4.13.0` | | `hugo --templateMetrics` | Template performance | Built-in CLI flag | | `hugo --renderToMemory` | Build without writing to disk | `hugo --renderToMemory --gc` | | `hugo mod verify` | Module integrity | Built-in | diff --git a/mermaid-diagrams/SKILL.md b/mermaid-diagrams/SKILL.md index ca28be1..1a440b7 100644 --- a/mermaid-diagrams/SKILL.md +++ b/mermaid-diagrams/SKILL.md @@ -33,7 +33,7 @@ Mermaid code blocks (```mermaid```) do NOT render in the Pandoc → HTML → Pup **For any diagram destined for PDF output:** 1. Create the diagram as a standalone .mmd file -2. Pre-render to SVG: `npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg --width 800` +2. Pre-render to SVG: `npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg --width 800` 3. Choose one embedding method: use raw inline SVG by default, or base64 data URIs when the renderer corrupts raw SVG. 4. Strip hardcoded `max-width` pixel values from the SVG tags 5. Use `flowchart TD` (portrait) not `flowchart LR` (landscape) — see `references/portrait-layout.md` @@ -116,9 +116,9 @@ See `references/c4-to-flowchart.md` for worked examples of all three C4 levels. ### CLI (mmdc) — for PDF/SVG/PNG output ```bash -npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg -npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.pdf +npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg +npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.png +npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.pdf ``` Requires Puppeteer + Chromium (~1.7GB). Use the Docker image for isolated rendering: diff --git a/mermaid-diagrams/references/pdf-rendering-pipeline.md b/mermaid-diagrams/references/pdf-rendering-pipeline.md index c9fe845..27491a6 100644 --- a/mermaid-diagrams/references/pdf-rendering-pipeline.md +++ b/mermaid-diagrams/references/pdf-rendering-pipeline.md @@ -8,7 +8,7 @@ This reference captures the lessons from a session where six PDF iterations were ```bash # Step 1: Pre-render all Mermaid diagrams to SVG -npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg --width 800 +npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg --width 800 # Step 2: Embed SVGs in markdown (NOT as data URI img tags) # Use raw tags inline in the markdown file diff --git a/playwright/README.md b/playwright/README.md index 230e9f4..9dbc3b6 100644 --- a/playwright/README.md +++ b/playwright/README.md @@ -30,11 +30,11 @@ bash scripts/pwrun report --report test-results/test-results.json --json # Scaffold a new suite (copy the templates into your project) cp templates/playwright.config.ts templates/example.spec.ts templates/accessibility.spec.ts . npm i -D @playwright/test -npx playwright install -npx playwright test +npx playwright@1.62.1 install +npx playwright@1.62.1 test ``` -The `--help` output documents every flag and works without Node. Set `BASE_URL` to override the smoke target; `scripts/pwrun smoke --url http://localhost:3000 --json` runs a delegated pass through `npx playwright test`. +The `--help` output documents every flag and works without Node. Set `BASE_URL` to override the smoke target; `scripts/pwrun smoke --url http://localhost:3000 --json` runs a delegated pass through `npx playwright@1.62.1 test`. ## Triggers diff --git a/playwright/SKILL.md b/playwright/SKILL.md index 76ac003..e90619a 100644 --- a/playwright/SKILL.md +++ b/playwright/SKILL.md @@ -75,7 +75,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig ## CI integration -- Install browsers and OS deps on the runner (`npx playwright install --with-deps`), pin the Playwright version, and cache `~/.cache/ms-playwright`. +- Install browsers and OS deps on the runner (`npx playwright@1.62.1 install --with-deps`), pin the Playwright version, and cache `~/.cache/ms-playwright`. - Configure `webServer`, `retries` (retry flaky tests on CI only), and `trace: 'on-first-retry'` so failures are debuggable. Report with `html`/`json`/`github` and upload artifacts on failure. - Triage CI failures from the JSON report with `scripts/pwrun report --json` — it summarizes stats, failing specs, and error messages without opening a browser. Full CI recipes: `references/05-ci-integration.md`. @@ -94,7 +94,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig ## Headed debugging - Run headed (`--headed`), slow the action with `--slow-mo`, or drop into the inspector with `--debug` / `PWDEBUG=1` and the `page.pause()` breakpoint. -- Generate starter tests with `npx playwright codegen `, then harden the generated selectors into user-facing locators. +- Generate starter tests with `npx playwright@1.62.1 codegen `, then harden the generated selectors into user-facing locators. - When a test fails: read the trace (`--trace on`), which records network, DOM snapshots, and console for the failed action. Use `scripts/pwrun report --report --json` first to see the failure summary. - Debugging workflows live in `references/07-accessibility-and-debugging.md`. @@ -124,7 +124,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig |---|---| | Toolchain is present | `scripts/pwrun doctor --json` reports node, @playwright/test, and browsers available | | Suite is understood | `scripts/pwrun inventory --json` lists config and spec files | -| A test passes | `npx playwright test` exit 0 on the targeted spec (or `smoke` delegation) | +| A test passes | `npx playwright@1.62.1 test` exit 0 on the targeted spec (or `smoke` delegation) | | A CI failure is explained | `scripts/pwrun report --report test-results.json --json` names the failing specs and errors | | Accessibility is covered | An axe scan runs with zero violations of the declared severity, and aria snapshots match | | No regressions in the covered flows | The suite ran under the configured workers/sharding with expected/flaky/unexpected counts recorded | diff --git a/playwright/references/02-selectors.md b/playwright/references/02-selectors.md index b980323..c5f0a46 100644 --- a/playwright/references/02-selectors.md +++ b/playwright/references/02-selectors.md @@ -43,7 +43,7 @@ await card.getByRole('button', { name: 'Add to cart' }).click(); A flaky test is a bug report about your selectors, not a request for more `waitForTimeout`. When a test passes sometimes: -1. Run the spec alone (`npx playwright test --workers=1 --repeat-each=5`) +1. Run the spec alone (`npx playwright@1.62.1 test --workers=1 --repeat-each=5`) to measure flakiness deterministically. 2. Use `--debug` or the trace to see what the failing action actually resolved. Common causes: diff --git a/playwright/references/05-ci-integration.md b/playwright/references/05-ci-integration.md index e9be522..d3b6130 100644 --- a/playwright/references/05-ci-integration.md +++ b/playwright/references/05-ci-integration.md @@ -19,8 +19,8 @@ jobs: - uses: actions/setup-node@v4 with: { node-version: 20, cache: npm } - run: npm ci - - run: npx playwright install --with-deps chromium - - run: npx playwright test + - run: npx playwright@1.62.1 install --with-deps chromium + - run: npx playwright@1.62.1 test - if: failure() uses: actions/upload-artifact@v4 with: @@ -31,7 +31,7 @@ jobs: ## Non-negotiables -1. **Install browsers with OS deps**: `npx playwright install --with-deps` (not +1. **Install browsers with OS deps**: `npx playwright@1.62.1 install --with-deps` (not bare `install`) on Linux runners; `--with-deps` installs the system libraries Chromium/Firefox/WebKit need. 2. **Pin and cache**: @@ -77,7 +77,7 @@ strategy: matrix: shard: [1/4, 2/4, 3/4, 4/4] steps: - - run: npx playwright test --shard=${{ matrix.shard }} + - run: npx playwright@1.62.1 test --shard=${{ matrix.shard }} ``` Merge reports from all shards with `playwright merge-reports` (see diff --git a/playwright/references/07-accessibility-and-debugging.md b/playwright/references/07-accessibility-and-debugging.md index 2e1a0f2..254c283 100644 --- a/playwright/references/07-accessibility-and-debugging.md +++ b/playwright/references/07-accessibility-and-debugging.md @@ -42,7 +42,7 @@ await expect(page).toMatchAriaSnapshot(` - These read like spec assertions ("the heading is X, the button is Y") and catch regressions in structure, labels, and semantics — not just contrast. - They are stable: inline text changes show up as a reviewable diff. -- **Update deliberately.** Run `npx playwright test --update-snapshots` only +- **Update deliberately.** Run `npx playwright@1.62.1 test --update-snapshots` only after inspecting what changed; never blind-update to make CI green (hard boundary in `SKILL.md`). - Requires Playwright 1.49+ (see `00-source-index.md` for version notes). @@ -56,14 +56,14 @@ When a test fails or a locator matches nothing: 2. **Run headed with slow-mo** to watch the actual page: ```bash - npx playwright test --headed --slow-mo 300 + npx playwright@1.62.1 test --headed --slow-mo 300 ``` 3. **The inspector** (`--debug` or `PWDEBUG=1`) pauses before each action and shows the current locator; `page.pause()` drops a breakpoint mid-test. 4. **Codegen** to prototype a flow quickly: ```bash - npx playwright codegen https://example.com + npx playwright@1.62.1 codegen https://example.com ``` Generate starter tests, then harden the emitted selectors into user-facing locators (`02-selectors.md`).