dependency-guard/AGENTS.md

Agent Guide

This repository is a security-sensitive npm supply-chain gate. Keep changes small, reviewable, dependency-free, and fail-closed.

Requirements

• Support Node.js 20 and newer using ESM and built-in APIs only.
• Do not add runtime or development npm dependencies.
• Use node:test; tests must not access live npm or GitHub services.
• Inject or mock HTTP and child-process boundaries in tests.
• Never execute dependency lifecycle scripts. Preserve --ignore-scripts on both npm ci and npm pack.
• Use argument-array child processes with shell: false and bounded timeouts.
• Never log or report tokens, headers, environment values, registry response bodies, attestation bundles, or other credentials.
• Preserve exact repository, commit, tag, signature, integrity, and maintainer checks.
• Do not silently trust packages that lack a normalized GitHub repository.
• Do not commit generated evidence reports, package archives, fixtures containing real project data, credentials, or tokens.

Project map

• bin/dependency-guard.js: executable entry point.
• lib/cli.js: commands and argument validation.
• lib/project.js: manifest/lock parsing and pre-install checks.
• lib/policy.js: policy defaults and validation.
• lib/verify.js: npm metadata, provenance, GitHub commit, and tag checks.
• lib/check.js: check orchestration and evidence report generation.
• lib/init.js: policy generation from exact locked direct versions.
• lib/util.js: URL normalization, bounded HTTP, process execution, and redaction.
• test/: offline unit and orchestration tests.
• action.yml: reusable Gitea composite action.

Workflow

1. Inspect git status --short and preserve unrelated worktree changes.
2. Read the implementation and nearest tests before editing.
3. Add denial-path tests for malformed or adversarial inputs.
4. Run npm test, then npm run check, then git diff --check.
5. Review every spawned npm argument list and every report field before finishing.

Do not commit or push unless explicitly requested.