mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
chore(docs): pin npx package versions in skill docs (Fixes #381)
Pin copy-pasteable npx invocations to explicit versions so agents executing them verbatim get reproducible behavior: - playwright docs: npx playwright@1.62.1 (SKILL.md, README.md, references 02-selectors / 05-ci-integration / 07-accessibility) - mermaid-diagrams: @mermaid-js/mermaid-cli@11.16.0 (SKILL.md, references/pdf-rendering-pipeline.md) - hugo-theme seo-outputs-testing: @axe-core/cli@4.13.0 - agent-skills using-scripts.md: strengthen version-pinning bullet into a normative rule for copy-pasteable commands Reword the anydoc cli-reference "Version pinning" prose so the anti-pattern is explained didactically without presenting an unpinned command as a recipe; the @0.1.6 house pin is unchanged. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
co-authored by
factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent
688611ec15
commit
b0845776a1
@@ -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.
|
||||
</Tab>
|
||||
|
||||
<Tab title="bunx">
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 <svg> tags inline in the markdown file
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+3
-3
@@ -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 <url>`, then harden the generated selectors into user-facing locators.
|
||||
- Generate starter tests with `npx playwright@1.62.1 codegen <url>`, 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> --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 |
|
||||
|
||||
@@ -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 <spec> --workers=1 --repeat-each=5`)
|
||||
1. Run the spec alone (`npx playwright@1.62.1 test <spec> --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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 <spec> --headed --slow-mo 300
|
||||
npx playwright@1.62.1 test <spec> --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`).
|
||||
|
||||
Reference in New Issue
Block a user