@htekdev/actions-debugger 1.0.53 → 1.0.54

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.
@@ -0,0 +1,95 @@
1
+ id: caching-artifacts-037
2
+ title: "upload-artifact if-no-files-found defaults to 'warn' — empty upload succeeds, download job fails"
3
+ category: caching-artifacts
4
+ severity: silent-failure
5
+ tags:
6
+ - upload-artifact
7
+ - if-no-files-found
8
+ - artifacts
9
+ - silent
10
+ - warn
11
+ - download
12
+ patterns:
13
+ - regex: 'No files were found with the provided path'
14
+ flags: i
15
+ - regex: 'No artifact uploads were performed'
16
+ flags: i
17
+ - regex: 'was not found for the associated workflow run'
18
+ flags: i
19
+ error_messages:
20
+ - "No files were found with the provided path: ./dist. No artifacts will be uploaded."
21
+ - "Warning: No files were found with the provided path: build/"
22
+ - "No artifact uploads were performed."
23
+ - "Error: An artifact named build-output was not found for the associated workflow run."
24
+ root_cause: |
25
+ The if-no-files-found input of actions/upload-artifact defaults to warn, not error.
26
+ When the upload path: glob matches no files — because the build directory is missing,
27
+ a glob pattern is wrong, the working-directory setting differs from the upload path,
28
+ or a preceding build step failed silently — the upload step logs a warning message and
29
+ exits with code 0 (success).
30
+
31
+ The calling workflow sees a green upload step in the UI. The problem only surfaces in
32
+ the downstream job that calls actions/download-artifact, which fails with an error like
33
+ "An artifact named X was not found for the associated workflow run."
34
+
35
+ Developers spend time debugging the download step or the job that uses the artifact when
36
+ the real problem — the build not producing output — occurred earlier, often in a different
37
+ job. The default warn behavior exists for optional artifacts, but it is a frequent source
38
+ of confusion for required CI artifacts.
39
+ fix: |
40
+ Set if-no-files-found: error on every upload step where the artifact is required.
41
+ The upload step will immediately fail with a descriptive error message that names the
42
+ missing path, pointing directly to the correct job.
43
+
44
+ Reserve warn or ignore only for genuinely optional artifacts — for example, test
45
+ screenshots that only exist when tests fail, or coverage reports that may be skipped
46
+ in some build configurations.
47
+ fix_code:
48
+ - language: yaml
49
+ label: "Correct: fail immediately when required build output is missing"
50
+ code: |
51
+ - name: Upload build artifacts
52
+ uses: actions/upload-artifact@v4
53
+ with:
54
+ name: build-output
55
+ path: ./dist/
56
+ if-no-files-found: error # Fail here — not in the downstream download job
57
+ - language: yaml
58
+ label: "Optional artifact — keep warn or ignore"
59
+ code: |
60
+ - name: Upload test screenshots (optional — only exist on test failure)
61
+ if: failure()
62
+ uses: actions/upload-artifact@v4
63
+ with:
64
+ name: test-screenshots
65
+ path: ./test-results/screenshots/
66
+ if-no-files-found: ignore # OK — screenshots only exist when tests fail
67
+ - language: yaml
68
+ label: "Verify build output before uploading"
69
+ code: |
70
+ - name: Verify dist/ was built
71
+ run: |
72
+ if [ ! -d "./dist" ] || [ -z "$(ls -A ./dist)" ]; then
73
+ echo "ERROR: dist/ directory is empty or missing"
74
+ exit 1
75
+ fi
76
+
77
+ - name: Upload build artifacts
78
+ uses: actions/upload-artifact@v4
79
+ with:
80
+ name: build-output
81
+ path: ./dist/
82
+ if-no-files-found: error
83
+ prevention:
84
+ - "Default to if-no-files-found: error in all CI pipeline templates for required artifacts"
85
+ - "Note that upload path: is relative to GITHUB_WORKSPACE, not the step's working-directory setting"
86
+ - "Add an explicit build verification step before upload to fail fast with a clear message"
87
+ - "Audit existing workflows: any upload-artifact step without if-no-files-found: error is a silent failure risk"
88
+ - "When a build step uses continue-on-error: true, verify it did not silently skip output generation before uploading"
89
+ docs:
90
+ - url: "https://github.com/actions/upload-artifact#inputs"
91
+ label: "actions/upload-artifact: Input parameters reference"
92
+ - url: "https://github.com/actions/upload-artifact/blob/main/RELEASES.md"
93
+ label: "actions/upload-artifact: Release notes"
94
+ - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
95
+ label: "GitHub Docs: Storing and sharing data from a workflow"
@@ -0,0 +1,108 @@
1
+ id: permissions-auth-039
2
+ title: "setup-node registry-url creates .npmrc but NODE_AUTH_TOKEN not set → npm E401"
3
+ category: permissions-auth
4
+ severity: error
5
+ tags:
6
+ - setup-node
7
+ - npm
8
+ - registry
9
+ - authentication
10
+ - publish
11
+ - node_auth_token
12
+ patterns:
13
+ - regex: 'npm ERR! code E401'
14
+ flags: i
15
+ - regex: 'npm ERR! 401 Unauthorized'
16
+ flags: i
17
+ - regex: 'npm ERR! need auth'
18
+ flags: i
19
+ - regex: 'npm error code EBADAUTH'
20
+ flags: i
21
+ error_messages:
22
+ - "npm ERR! code E401"
23
+ - "npm ERR! 401 Unauthorized - PUT https://registry.npmjs.org/@scope/package-name"
24
+ - "npm ERR! need auth You need to authorize this machine using `npm adduser`"
25
+ - "npm error code EBADAUTH"
26
+ root_cause: |
27
+ When registry-url is set in actions/setup-node, the action generates an .npmrc file
28
+ containing a token placeholder line such as:
29
+ //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
30
+
31
+ The variable name NODE_AUTH_TOKEN is hardcoded in this template and must be supplied
32
+ as an environment variable at runtime on every step that communicates with the registry.
33
+
34
+ If the npm publish or npm install step does not declare
35
+ `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` in its env: block, the placeholder expands
36
+ to an empty string. npm sends an unauthenticated request and receives HTTP 401
37
+ Unauthorized from the registry.
38
+
39
+ The setup-node step itself succeeds with no warnings — there is no validation that
40
+ NODE_AUTH_TOKEN will be set. The 401 only surfaces during the npm command, misleading
41
+ developers to investigate the token or registry configuration rather than the missing
42
+ env: declaration.
43
+ fix: |
44
+ Add NODE_AUTH_TOKEN to the env: block of every step that runs npm commands against the
45
+ authenticated registry. The variable name must be exactly NODE_AUTH_TOKEN — npm reads
46
+ it directly from the .npmrc template generated by setup-node.
47
+
48
+ For GitHub Packages (npm.pkg.github.com), use secrets.GITHUB_TOKEN.
49
+ For npmjs.com, use a dedicated automation token stored as a repository secret (e.g. NPM_TOKEN).
50
+
51
+ If all registry requests — including npm install of private scoped packages — need
52
+ authentication (not just publish), also set always-auth: true in the setup-node step.
53
+ fix_code:
54
+ - language: yaml
55
+ label: "Correct: NODE_AUTH_TOKEN on the publish step"
56
+ code: |
57
+ - name: Set up Node.js
58
+ uses: actions/setup-node@v4
59
+ with:
60
+ node-version: '20'
61
+ registry-url: 'https://registry.npmjs.org'
62
+
63
+ - name: Publish to npm
64
+ run: npm publish
65
+ env:
66
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
67
+ - language: yaml
68
+ label: "GitHub Packages registry variant"
69
+ code: |
70
+ - name: Set up Node.js
71
+ uses: actions/setup-node@v4
72
+ with:
73
+ node-version: '20'
74
+ registry-url: 'https://npm.pkg.github.com'
75
+ scope: '@your-org'
76
+
77
+ - name: Publish to GitHub Packages
78
+ run: npm publish
79
+ env:
80
+ NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
81
+ - language: yaml
82
+ label: "Private package install with always-auth"
83
+ code: |
84
+ - name: Set up Node.js
85
+ uses: actions/setup-node@v4
86
+ with:
87
+ node-version: '20'
88
+ registry-url: 'https://npm.pkg.github.com'
89
+ scope: '@your-org'
90
+ always-auth: true # Send auth on all requests, not just publish
91
+
92
+ - name: Install dependencies (includes private scoped packages)
93
+ run: npm ci
94
+ env:
95
+ NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
96
+ prevention:
97
+ - "Every npm step that interacts with an authenticated registry must declare NODE_AUTH_TOKEN in its env: block"
98
+ - "Setting registry-url in setup-node does NOT automatically forward any secrets to npm — the env: mapping is always required"
99
+ - "Use always-auth: true in setup-node when npm install (not just publish) must authenticate, such as for private scoped packages"
100
+ - "Store your npm automation token as a repository secret: Settings → Secrets and variables → Actions → New repository secret"
101
+ - "For GitHub Packages, NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} is sufficient — no separate token needed"
102
+ docs:
103
+ - url: "https://github.com/actions/setup-node#publishing-to-npmjs-and-github-packages-registries"
104
+ label: "actions/setup-node: Publishing to registries"
105
+ - url: "https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry"
106
+ label: "GitHub Docs: Working with the npm registry"
107
+ - url: "https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow"
108
+ label: "npm Docs: Using private packages in CI/CD"
@@ -0,0 +1,93 @@
1
+ id: runner-environment-111
2
+ title: "setup-node node-version: 'latest' silently upgrades to new Node.js major, breaking engines field"
3
+ category: runner-environment
4
+ severity: silent-failure
5
+ tags:
6
+ - setup-node
7
+ - node-version
8
+ - latest
9
+ - engines
10
+ - breaking-change
11
+ - major-version
12
+ - semver
13
+ patterns:
14
+ - regex: 'The engine "node" is incompatible with this module'
15
+ flags: i
16
+ - regex: 'EBADENGINE.*Unsupported engine'
17
+ flags: i
18
+ - regex: 'npm warn EBADENGINE'
19
+ flags: i
20
+ - regex: 'engine.*node.*incompatible.*Expected version'
21
+ flags: i
22
+ error_messages:
23
+ - "error The engine \"node\" is incompatible with this module. Expected version \">=18 <21\". Got \"23.x.x\""
24
+ - "npm warn EBADENGINE Unsupported engine { required: { node: '>=16 <20' }, current: { node: 'v22.0.0' } }"
25
+ - "npm error code EBADENGINE"
26
+ - "error This package requires Node.js >= 18.0.0 and <= 22.x"
27
+ root_cause: |
28
+ When node-version: 'latest' is used in actions/setup-node, the action resolves the
29
+ alias against the official Node.js release schedule manifest on every workflow run.
30
+ When Node.js releases a new major version (e.g. v23.0.0, v24.0.0), the next run silently
31
+ downloads and activates the new major without any warning in the setup-node step output.
32
+
33
+ Packages that declare an engines constraint in their package.json (e.g.
34
+ engines: { node: ">=18 <22" }) then fail during npm install or yarn install with
35
+ EBADENGINE because the newly installed version exceeds the accepted range.
36
+
37
+ The setup-node step itself succeeds and logs the installed version; the failure only
38
+ appears downstream when the package manager processes the engines field. Because the
39
+ workflow ran successfully for months before the Node.js major release, developers
40
+ are not expecting a version bump and may incorrectly blame a dependency change.
41
+
42
+ Native addons and frameworks that have not yet published compatibility updates for the
43
+ new major can also fail during postinstall or build steps.
44
+ fix: |
45
+ Pin to a specific LTS major version string (e.g. '20', '22') rather than 'latest'.
46
+ LTS majors receive security patches but do not automatically jump to a new major.
47
+
48
+ Alternatively, use the node-version-file input to read the version from a .nvmrc or
49
+ .node-version file committed to the repository. This keeps the Node.js version
50
+ consistent between local development and CI and makes version upgrades explicit
51
+ (a PR changes the version file).
52
+ fix_code:
53
+ - language: yaml
54
+ label: "Pin to a specific LTS major (recommended)"
55
+ code: |
56
+ - name: Set up Node.js
57
+ uses: actions/setup-node@v4
58
+ with:
59
+ node-version: '22' # Pinned LTS major — will not jump to Node 24 automatically
60
+ cache: 'npm'
61
+ - language: yaml
62
+ label: "Use .nvmrc for repo-defined version shared with local dev"
63
+ code: |
64
+ # .nvmrc (committed to repository root)
65
+ # 22.x
66
+
67
+ - name: Set up Node.js
68
+ uses: actions/setup-node@v4
69
+ with:
70
+ node-version-file: '.nvmrc' # Same version in local dev and CI
71
+ cache: 'npm'
72
+ - language: yaml
73
+ label: "Pin with explicit patch version for maximum reproducibility"
74
+ code: |
75
+ - name: Set up Node.js
76
+ uses: actions/setup-node@v4
77
+ with:
78
+ node-version: '22.13.1' # Exact patch — fully reproducible but requires manual updates
79
+ cache: 'npm'
80
+ prevention:
81
+ - "Never use node-version: 'latest' in production or long-lived CI workflows — pin to an LTS major"
82
+ - "Prefer '18', '20', or '22' (active LTS) — these receive security patches without surprise major bumps"
83
+ - "Use node-version-file pointing to .nvmrc to keep local development and CI on the same version"
84
+ - "Use Renovate or Dependabot to automate controlled Node.js upgrades with a PR and changelog review"
85
+ - "Test new Node.js majors in a dedicated branch before adopting them in main CI"
86
+ - "Declare an engines field in package.json to make your Node.js version requirement explicit and testable"
87
+ docs:
88
+ - url: "https://github.com/actions/setup-node#supported-version-syntax"
89
+ label: "actions/setup-node: Supported version syntax"
90
+ - url: "https://nodejs.org/en/about/previous-releases"
91
+ label: "Node.js: Release schedule and LTS versions"
92
+ - url: "https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines"
93
+ label: "npm: package.json engines field documentation"
@@ -0,0 +1,100 @@
1
+ id: silent-failures-054
2
+ title: "Windows CRLF line endings in committed scripts cause bad interpreter error on Linux runners"
3
+ category: silent-failures
4
+ severity: error
5
+ tags:
6
+ - checkout
7
+ - crlf
8
+ - line-endings
9
+ - windows
10
+ - bash
11
+ - gitattributes
12
+ - bad-interpreter
13
+ patterns:
14
+ - regex: 'bad interpreter.*No such file or directory'
15
+ flags: i
16
+ - regex: '\^M: command not found'
17
+ flags: ''
18
+ - regex: '/bin/bash\^M'
19
+ flags: ''
20
+ - regex: '\r: command not found'
21
+ flags: ''
22
+ error_messages:
23
+ - "/bin/bash^M: bad interpreter: No such file or directory"
24
+ - "^M: command not found"
25
+ - ": /bin/sh^M: bad interpreter: No such file or directory"
26
+ - "syntax error: unexpected end of file"
27
+ root_cause: |
28
+ Shell scripts, Python files, and other text files committed from Windows workstations
29
+ where core.autocrlf is false (or not configured) retain Windows CRLF (\r\n) line endings.
30
+ actions/checkout preserves committed bytes exactly — it does not normalize line endings.
31
+
32
+ On a Linux runner, the kernel reads the shebang line #!/bin/bash\r as the interpreter
33
+ path /bin/bash^M (with a literal carriage return appended). No file with that name exists,
34
+ so the kernel returns "bad interpreter: No such file or directory." The error message
35
+ looks like a missing binary or path problem, masking the true cause: CRLF line endings.
36
+
37
+ This is a classic silent failure because:
38
+ - The developer's Windows machine runs the script correctly
39
+ - The checkout step succeeds with no warnings about line endings
40
+ - The failure only manifests when the script is executed on a Linux runner
41
+ - Most text editors hide the ^M characters, so the file looks normal in review
42
+ fix: |
43
+ Add a .gitattributes file to the repository root specifying LF normalization for text
44
+ files. This instructs Git to store files with LF endings in the repository regardless
45
+ of the committer's OS or local git configuration.
46
+
47
+ After adding .gitattributes, re-normalize all tracked files: stage all files with the
48
+ renormalize flag (e.g. `add --renormalize .` via the CLI), then commit the result.
49
+ Without this step, already-committed CRLF files remain unchanged.
50
+
51
+ Also add a CI detection step to catch any future regressions before they reach main.
52
+ fix_code:
53
+ - language: yaml
54
+ label: ".gitattributes — enforce LF for scripts and text files"
55
+ code: |
56
+ # .gitattributes (add to repository root)
57
+
58
+ # Normalize all text files to LF in the repository
59
+ * text=auto eol=lf
60
+
61
+ # Explicitly enforce LF for scripts and config files
62
+ *.sh text eol=lf
63
+ *.bash text eol=lf
64
+ *.py text eol=lf
65
+ *.yml text eol=lf
66
+ *.yaml text eol=lf
67
+ *.json text eol=lf
68
+
69
+ # Keep CRLF for Windows-specific files
70
+ *.bat text eol=crlf
71
+ *.cmd text eol=crlf
72
+ - language: yaml
73
+ label: "CI step to detect CRLF in shell and Python scripts"
74
+ code: |
75
+ - name: Check for CRLF line endings in scripts
76
+ runs-on: ubuntu-latest
77
+ steps:
78
+ - uses: actions/checkout@v4
79
+ - name: Detect CRLF
80
+ run: |
81
+ found=$(find . -name '*.sh' -o -name '*.py' -o -name '*.yml' | \
82
+ xargs file 2>/dev/null | grep CRLF || true)
83
+ if [ -n "$found" ]; then
84
+ echo "ERROR: CRLF line endings detected in the following files:"
85
+ echo "$found"
86
+ exit 1
87
+ fi
88
+ prevention:
89
+ - "Add .gitattributes with `* text=auto eol=lf` to every repository that may be edited on Windows"
90
+ - "Re-normalize existing files after adding .gitattributes: use the CLI `add --renormalize .` flag, then commit"
91
+ - "Configure the autocrlf setting on Windows development machines: set core.autocrlf=input so CRLF is converted to LF on commit"
92
+ - "Configure your editor (VS Code, Notepad++, JetBrains) to use LF line endings for shell and YAML files by default"
93
+ - "Add a CRLF detection step in CI to fail PRs that introduce Windows line endings into script files"
94
+ docs:
95
+ - url: "https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings"
96
+ label: "GitHub Docs: Configuring Git to handle line endings"
97
+ - url: "https://git-scm.com/docs/gitattributes"
98
+ label: "Git: gitattributes documentation"
99
+ - url: "https://github.com/actions/checkout/issues/135"
100
+ label: "actions/checkout Issue #135: Line ending normalization"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htekdev/actions-debugger",
3
- "version": "1.0.53",
3
+ "version": "1.0.54",
4
4
  "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",