feat(check-parser): bundle .npmrc in Playwright Check Suite bundles by default [RED-691] [show] (#1394)

* feat(check-parser): bundle .npmrc in Playwright Check Suite bundles by default [RED-691]

Playwright Check Suites run the user's own package-manager install in the
Checkly cloud. When a project uses an alternate/private npm registry configured
in .npmrc, that file was only bundled if the user manually listed it in the
`include` prop; otherwise the install resolved against the default registry and
private packages failed to resolve.

Route .npmrc through the same workspace/package-files machinery that already
bundles the lockfile and pnpm-workspace.yaml: emit the .npmrc at the workspace
root and every workspace-member package root as a `workspace-npmrc` local
dependency, gated on non-restricted parsing so only Playwright Check Suites are
affected (browser/multistep/API checks are unchanged). This is exactly the set
a package manager reads (project .npmrc is consulted from the install directory
upward, never from subdirectories below it).

Feed the same root + member .npmrc set into the workspace cache hash so a
registry change invalidates the bundle cache. The bundled set and the hashed
set are identical by construction, so a bundled .npmrc is always reflected in
the cache key. Projects without an .npmrc hash byte-identically as before.

Note: adding `npmrc:` records to the workspace cache hash diverges from
terraform-provider-checkly's composeBundleChecksum for projects that have an
.npmrc, until the provider mirrors the record type (flagged in a code comment).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(ai-context): note .npmrc is bundled automatically for Playwright Check Suites [RED-691]

.npmrc no longer needs a manual `include` entry — the workspace-root and
package-root .npmrc are bundled by default. Warn to reference credentials via
${NPM_TOKEN} rather than embedding plaintext tokens (since the file is now
uploaded automatically), and clarify that a .npmrc below a package root is not
bundled. Replace the now-obsolete `include: ["../.npmrc"]` example with a
non-code-asset example.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: sorccu

packages/cli/src/ai-context/references/configure-playwright-checks.md

@@ -9,10 +9,10 @@
 ## Dependencies
 
 - Use the user's `package.json` and lock file for dependencies. Do not add dependency declarations to check code.
-- For private packages or custom registries, include the registry config file, usually `.npmrc`, with `include`.
-- The `.npmrc` should reference a Checkly environment variable such as `${NPM_TOKEN}`. Tell the user that the token must exist in Checkly before `deploy` or `trigger`.
+- For private packages or custom registries, `.npmrc` is bundled automatically — the workspace-root `.npmrc` and any `.npmrc` beside a package's `package.json` are included by default. You do not need to add `.npmrc` to `include`.
+- The `.npmrc` should reference a Checkly environment variable such as `${NPM_TOKEN}`. Tell the user that the token must exist in Checkly before `deploy` or `trigger`. Because `.npmrc` is uploaded automatically, warn users to reference credentials via environment variables (`${NPM_TOKEN}`) rather than embedding plaintext tokens.
 - Use `installCommand` only when the default package-manager install command is not enough.
-- In Checkly CLI v8.0.0 and later, `include` patterns resolve relative to the Playwright config directory, not the project root. If `playwrightConfigPath` points to a subdirectory, adjust `include` globs. Example: `playwrightConfigPath: "./e2e/playwright.config.ts"` with root `.npmrc` needs `include: ["../.npmrc"]`.
+- In Checkly CLI v8.0.0 and later, `include` patterns resolve relative to the Playwright config directory, not the project root. If `playwrightConfigPath` points to a subdirectory, adjust `include` globs. Example: `playwrightConfigPath: "./e2e/playwright.config.ts"` with a root fixture at `fixtures/data.json` needs `include: ["../fixtures/data.json"]`.
 
 ## Install troubleshooting
 
@@ -40,8 +40,8 @@ import { PlaywrightCheck } from "checkly/constructs"
 new PlaywrightCheck("checkout-suite", {
   name: "Checkout suite",
   playwrightConfigPath: "./e2e/playwright.config.ts",
-  // Include root .npmrc for private package or registry auth.
-  include: ["../.npmrc"],
+  // .npmrc is bundled automatically for private packages or registry auth —
+  // no include entry needed.
 })
 ```
 - `playwrightConfigPath` is resolved **relative to the `.check.ts` file that declares the construct**, not the project root. If your check lives in `monitoring/suites.check.ts` and your config in `playwright.config.ts` at the repo root, use `'../playwright.config.ts'`.

packages/cli/src/services/check-parser/__tests__/cache-hash.spec.ts

@@ -149,6 +149,95 @@ describe('composeCacheHash', () => {
     expect(without).not.toBe(withMember)
   })
 
+  test('omitting npmrcs matches passing an empty array (no-op)', () => {
+    const root = buf('{"name":"root"}')
+    const lockfile = { name: 'package-lock.json', hash: sha256('lock') }
+    expect(composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      excludedFields: ['version'],
+    })).toBe(composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [],
+      excludedFields: ['version'],
+    }))
+  })
+
+  test('adding a root .npmrc changes the hash', () => {
+    const root = buf('{"name":"root"}')
+    const lockfile = { name: 'package-lock.json', hash: sha256('lock') }
+    const without = composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      excludedFields: ['version'],
+    })
+    const withNpmrc = composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [{ path: '.npmrc', hash: sha256('registry=https://example.com/') }],
+      excludedFields: ['version'],
+    })
+    expect(without).not.toBe(withNpmrc)
+  })
+
+  test('changing .npmrc content changes the hash', () => {
+    const root = buf('{"name":"root"}')
+    const lockfile = { name: 'package-lock.json', hash: sha256('lock') }
+    const a = composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [{ path: '.npmrc', hash: sha256('registry=https://a.example.com/') }],
+      excludedFields: ['version'],
+    })
+    const b = composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [{ path: '.npmrc', hash: sha256('registry=https://b.example.com/') }],
+      excludedFields: ['version'],
+    })
+    expect(a).not.toBe(b)
+  })
+
+  test('adding a member .npmrc changes the hash', () => {
+    const root = buf('{"name":"root"}')
+    const lockfile = { name: 'package-lock.json', hash: sha256('lock') }
+    const rootOnly = composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [{ path: '.npmrc', hash: sha256('root-npmrc') }],
+      excludedFields: ['version'],
+    })
+    const withMember = composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [
+        { path: '.npmrc', hash: sha256('root-npmrc') },
+        { path: 'apps/main/.npmrc', hash: sha256('member-npmrc') },
+      ],
+      excludedFields: ['version'],
+    })
+    expect(rootOnly).not.toBe(withMember)
+  })
+
+  test('input order of npmrcs does not affect the hash', () => {
+    const root = buf('{"name":"root"}')
+    const lockfile = { name: 'package-lock.json', hash: sha256('lock') }
+    const a = { path: '.npmrc', hash: sha256('root-npmrc') }
+    const b = { path: 'apps/main/.npmrc', hash: sha256('member-npmrc') }
+    expect(composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [b, a],
+      excludedFields: ['version'],
+    })).toBe(composeCacheHash({
+      lockfile,
+      packageJsons: [{ path: 'package.json', raw: root }],
+      npmrcs: [a, b],
+      excludedFields: ['version'],
+    }))
+  })
+
   test('lockfile content change changes the hash', () => {
     const root = buf('{"name":"root"}')
     const a = composeCacheHash({
@@ -192,6 +281,11 @@ describe('composeCacheHash', () => {
   // and the same excluded fields must produce this exact digest in
   // terraform-provider-checkly's composeBundleChecksum. If you change this
   // fixture, mirror the change in the TF provider's test suite.
+  //
+  // NOTE: composeCacheHash also hashes `npmrc:` records (added for .npmrc
+  // bundling). This fixture has no .npmrc so the digest is unchanged, but
+  // projects that DO have an .npmrc will hash differently until the TF
+  // provider mirrors the npmrc record type.
   test('matches the cross-language parity fixture digest', () => {
     const lockfileBytes = buf('{"lockfileVersion":3}\n')
     const rootPackageJson = buf([

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/.npmrc

@@ -0,0 +1,2 @@
+registry=https://registry.example.com/
+//registry.example.com/:_authToken=${NPM_TOKEN}

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/apps/main/.npmrc

@@ -0,0 +1 @@
+@scope:registry=https://npm.example.com/

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/apps/main/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "main",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "license": "ISC"
+}

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/apps/main/playwright.config.js

@@ -0,0 +1,5 @@
+const { defineConfig } = require('@playwright/test')
+
+module.exports = defineConfig({
+  testDir: './tests'
+})

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/apps/main/tests/.npmrc

@@ -0,0 +1,4 @@
+; A .npmrc in a subdirectory that is not a workspace package root. Package
+; managers never read .npmrc from below the install directory, so this must NOT
+; be bundled.
+registry=https://should-not-be-bundled.example.com/

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/apps/main/tests/foo.spec.js

@@ -0,0 +1,2 @@
+// A test that pulls in no dependencies; the point of this fixture is to
+// exercise .npmrc bundling, not the import graph.

packages/cli/src/services/check-parser/__tests__/check-parser-fixtures/npmrc-example/package-lock.json

@@ -0,0 +1,10 @@
+{
+  "name": "npmrc-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "license": "ISC",
+  "workspaces": [
+    "apps/*"
+  ]
+}