@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/library/library-requirements.md

@@ -0,0 +1,173 @@
+---
+name: library-requirements
+description: API contract stability, semver commitments, consumer compatibility, and breaking change policy for published libraries
+topics: [library, requirements, semver, api-contract, breaking-changes, compatibility]
+---
+
+Library requirements differ fundamentally from application requirements: every public API decision becomes a contract with downstream consumers who cannot easily update. Stability, predictability, and clear communication of change are the highest-priority concerns. A library that breaks its consumers silently, or without adequate notice, loses trust permanently.
+
+## Summary
+
+Library requirements must explicitly capture the public API surface and the stability guarantees attached to each part of it. Distinguish stable APIs (semver-protected), experimental APIs (no stability guarantee), and internal APIs (not for external use). Document breaking change policy, minimum supported runtime versions, and peer dependency expectations upfront. Requirements must include consumer use cases — not just feature descriptions — because API design is driven by how consumers will actually call the library.
+
+Key commitments to define:
+- Which exports are public and semver-protected
+- Which are experimental (`@alpha`, `@beta`, `@experimental`)
+- Minimum Node.js / runtime versions supported
+- Peer dependency version ranges and their constraints
+- Deprecation notice period before removal (recommended: 2+ major versions)
+- Supported environments (ESM-only, CJS-only, dual, browser, Node-only, universal)
+
+## Deep Guidance
+
+### API Contract as a First-Class Requirement
+
+The public API surface is a contract. Treat it with the same rigor as a legal agreement. Before writing any code, define:
+
+**What is public:**
+```
+Public API (semver-protected):
+- All named exports from the package root (index.ts)
+- All types and interfaces exported from the root
+- Constructor signatures, method names, parameter order, return types
+- Error types thrown by public methods
+- Event names and payload shapes (for event-emitter APIs)
+```
+
+**What is explicitly internal:**
+```
+Internal (not public, no stability guarantee):
+- Anything exported from /internal/* paths
+- _prefixed exports (by convention)
+- Anything documented as "implementation detail"
+- Test utilities not in a separate @scope/lib-test-utils package
+```
+
+**What is experimental:**
+```
+Experimental (may change without semver):
+- Exports tagged @alpha or @beta in JSDoc
+- Features behind feature flags
+- Exports from /experimental/* subpaths
+```
+
+Define these categories in your requirements document, not in code comments alone.
+
+### Semver Commitments
+
+Semver has precise semantics for libraries. Teams frequently misapply it:
+
+**PATCH (1.0.x):** Bug fixes only. No new APIs. No behavior changes for correct usage. A bug fix that changes observable behavior in a way consumers may depend on is a MINOR or MAJOR change.
+
+**MINOR (1.x.0):** Backward-compatible additions. New exports. New optional parameters (at the end of argument lists). New optional properties on config objects. Extending return types with additional optional fields. New overloads.
+
+**MAJOR (x.0.0):** Any breaking change. This includes:
+- Removing or renaming exports
+- Changing required parameter types or order
+- Narrowing accepted input types
+- Widening return types in ways that break type narrowing
+- Changing thrown error types
+- Dropping support for a previously supported Node.js version
+- Changing peer dependency minimum versions
+- Behavior changes that violate documented semantics
+
+A common mistake: treating TypeScript type-only changes as "not breaking." Changing a type from `string` to `string | null` is a breaking change for consumers who never account for null.
+
+### Consumer Compatibility Matrix
+
+Requirements must specify the compatibility matrix:
+
+```markdown
+## Runtime Support
+
+| Runtime        | Minimum Version | Status     |
+|----------------|-----------------|------------|
+| Node.js        | 18.0.0          | Supported  |
+| Node.js        | 20.0.0          | Supported  |
+| Node.js        | 22.0.0          | Supported  |
+| Bun            | 1.0.0           | Supported  |
+| Deno           | 1.40.0          | Experimental |
+| Browser (ESM)  | Modern (ES2020) | Supported  |
+
+## TypeScript Support
+
+Minimum TypeScript version: 5.0
+Bundled type definitions: Yes (.d.ts in dist/)
+```
+
+Define this matrix in requirements, not after the fact. Dropping Node 18 support is a major version bump — plan it deliberately.
+
+### Peer Dependency Policy
+
+Peer dependencies express "your project must also have X installed." They are fundamentally different from regular dependencies:
+
+**When to use peer dependencies:**
+- The library is an extension/plugin of another library (e.g., a React component library — React is a peer)
+- The library integrates with a framework the consumer already has
+- Bundling the dependency would create duplicate instances (React, any singleton library)
+
+**Peer dependency requirements to document:**
+```json
+{
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  }
+}
+```
+
+State in requirements: which peer deps are required vs. optional, and what happens if the consumer provides an incompatible version.
+
+### Breaking Change Policy
+
+Document your policy before you ship v1:
+
+**Recommended policy:**
+1. No breaking changes in patch or minor releases (strict semver)
+2. Deprecate before removing: at least one minor release with `@deprecated` JSDoc
+3. Major version bump for any breaking change, no matter how small
+4. Provide migration guide for every major version bump
+5. Maintain previous major version with security patches for N months after next major (define N upfront — 12 months is common)
+6. Communicate breaking changes in CHANGELOG.md with migration steps
+
+**Experimental API exception:**
+Experimental APIs tagged `@alpha` or `@beta` may break in minor or patch releases. Consumers opt in by using experimental exports. Document this explicitly.
+
+### Use-Case-Driven Requirements
+
+Library requirements fail when they describe features instead of consumer use cases. Write requirements from the consumer's perspective:
+
+**Weak (feature-centric):**
+> The library exports a `parse()` function that accepts a string and returns an object.
+
+**Strong (use-case-centric):**
+> A consumer building a configuration loader needs to: (1) parse a TOML string into a typed JavaScript object, (2) receive a typed parse error with line/column information if parsing fails, (3) validate the parsed object against a schema and receive typed validation errors. The API must be synchronous (no async) for use in module initialization.
+
+Use cases drive API design. The feature-centric description could be satisfied by dozens of different APIs; the use-case description constrains the design to what actually serves consumers.
+
+### Minimum Viable Requirements Checklist
+
+Before beginning library implementation:
+
+```
+[ ] Public API surface enumerated (all exports listed)
+[ ] Stability tier assigned to each export (stable / experimental / internal)
+[ ] Supported runtime versions documented
+[ ] Supported TypeScript versions documented
+[ ] Peer dependencies and version ranges documented
+[ ] Breaking change policy written
+[ ] Deprecation notice period specified
+[ ] Distribution format requirements (ESM, CJS, both, IIFE)
+[ ] Bundle size budget (if applicable — important for browser libraries)
+[ ] Tree-shaking requirement (yes/no and constraints)
+[ ] License and attribution requirements
+[ ] At least 3 concrete consumer use cases documented
+[ ] Error handling contract defined (throws vs. returns Result type)
+```
+
+This checklist is non-negotiable for any library that will have external consumers.

package/content/knowledge/library/library-security.md

@@ -0,0 +1,257 @@
+---
+name: library-security
+description: Supply chain security, dependency auditing, npm provenance, SBOM, and security policy for published libraries
+topics: [library, security, supply-chain, npm-provenance, sbom, dependency-auditing, cve]
+---
+
+Library security is supply chain security. When a library is published to npm and installed by thousands of projects, a single compromised release or a malicious dependency can propagate vulnerabilities to all consumers simultaneously. The 2021 `ua-parser-js` incident and the 2022 `node-ipc` sabotage demonstrated that even widely-used libraries with established maintainers can be compromised. Library authors bear a responsibility to their consumers that application developers do not — a security failure in a library is a security failure for every project that depends on it.
+
+## Summary
+
+Library security encompasses four areas: dependency hygiene (minimal, audited, regularly updated dependencies), publish security (protected npm accounts, CI-based publishing with provenance), input validation (libraries that process untrusted input must handle malformed data safely), and disclosure (responsible vulnerability reporting process for consumers to report issues). Enable npm provenance on all published packages. Pin GitHub Actions to commit SHAs. Keep devDependencies patched and runtime dependencies minimal.
+
+Core security practices:
+- `npm audit` in CI — fail on high/critical vulnerabilities
+- npm publish with `--provenance` for attestation
+- Two-factor authentication on npm account
+- Pin GitHub Actions to commit SHAs, not tags
+- SECURITY.md with disclosure process
+- Minimal runtime dependencies (each dep is an attack surface)
+
+## Deep Guidance
+
+### Dependency Auditing
+
+Every dependency is a trust decision. Minimize trust surface:
+
+**In CI, fail on vulnerabilities:**
+```yaml
+# .github/workflows/ci.yml
+- name: Security audit
+  run: npm audit --audit-level=high
+  # Fails if any high or critical CVEs are found in dependencies
+```
+
+**Regular automated updates:**
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      devDependencies:
+        dependency-type: development
+```
+
+Dependabot opens PRs for dependency updates weekly. Review them and merge; don't let them accumulate. Stale dependencies accumulate vulnerabilities.
+
+**Audit devDependencies too:**
+```bash
+# npm audit includes devDependencies by default
+npm audit
+
+# Check only production dependencies (what consumers install)
+npm audit --omit=dev
+```
+
+A vulnerability in a devDependency can compromise your CI pipeline and inject malicious code into the published package even if consumers never install the devDependency.
+
+### npm Provenance
+
+npm provenance creates a cryptographic link between a published package and the GitHub Actions workflow that built it. Consumers can verify that `my-library@1.0.0` was built from exactly commit `abc123` by the expected workflow:
+
+```yaml
+# .github/workflows/release.yml
+jobs:
+  release:
+    permissions:
+      id-token: write  # Required for provenance
+      contents: read
+    steps:
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+After publishing with `--provenance`, consumers can verify:
+```bash
+npm audit signatures my-library
+# Verifies: Attestation verified for my-library@1.0.0
+```
+
+Provenance is essential for libraries installed in security-sensitive environments. Enable it on all public packages.
+
+### npm Account Security
+
+The npm account is the most critical attack surface for library security:
+
+1. **Enable 2FA (mandatory):** npm.com → Account Settings → Two-Factor Authentication → Enable for auth and publishing
+2. **Use Granular Access Tokens:** Create a publish token with `Automation` type and scope to specific packages only
+3. **Rotate tokens regularly:** Invalidate and recreate publish tokens quarterly
+4. **Use trusted publishing** (npm + GitHub Actions OIDC): Eliminates long-lived tokens entirely:
+
+```bash
+# npm trusted publishing: configure in npm package settings, then:
+npm publish --provenance
+# No NPM_TOKEN secret needed — GitHub OIDC provides the auth
+```
+
+Trusted publishing is the most secure approach — there is no token to steal, rotate, or accidentally expose in logs.
+
+### Pinning GitHub Actions to Commit SHAs
+
+GitHub Actions tags (like `actions/checkout@v4`) can be moved by the action author, making them effectively mutable. A compromised action author could update `v4` to inject malicious code. Pin to commit SHAs:
+
+```yaml
+# BAD: tag can be moved
+- uses: actions/checkout@v4
+- uses: actions/setup-node@v4
+
+# GOOD: pinned to specific commit
+- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+- uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af  # v4.1.0
+```
+
+Use a tool like `renovate` or `pin-github-action` to automate SHA pinning and updates:
+
+```bash
+npx pin-github-action .github/workflows/*.yml
+```
+
+This converts all `@v4` references to pinned SHAs and creates a comment with the resolved version.
+
+### Input Validation and Denial of Service
+
+Libraries that parse untrusted input must handle malformed data defensively:
+
+**ReDoS (Regular Expression Denial of Service):**
+```typescript
+// VULNERABLE: catastrophic backtracking on malformed input
+const emailRegex = /^([a-zA-Z0-9]+)*@/
+
+// SAFE: linear time regex or use a dedicated library
+import { isEmail } from 'validator'  // battle-tested input validation library
+```
+
+Test regex performance with adversarial inputs:
+```bash
+npx vuln-regex-detector 'your regex here'
+```
+
+**Size limits for inputs:**
+```typescript
+export function parseConfig(input: string, options?: ParseOptions): Config {
+  const maxSize = options?.maxSize ?? 1_048_576  // 1 MB default
+
+  if (Buffer.byteLength(input, 'utf-8') > maxSize) {
+    throw new ParseError(
+      `Input exceeds maximum size of ${maxSize} bytes`,
+      0, 0
+    )
+  }
+  // ... parse
+}
+```
+
+**Prototype pollution prevention:**
+```typescript
+// When merging user-provided objects, guard against prototype pollution
+function mergeOptions<T extends object>(defaults: T, overrides: unknown): T {
+  if (typeof overrides !== 'object' || overrides === null) return defaults
+  // Guard against __proto__, constructor, prototype keys
+  const safe = Object.fromEntries(
+    Object.entries(overrides as Record<string, unknown>)
+      .filter(([key]) => key !== '__proto__' && key !== 'constructor' && key !== 'prototype')
+  )
+  return { ...defaults, ...safe }
+}
+```
+
+### SECURITY.md and Disclosure Policy
+
+Every library must have a SECURITY.md file documenting how to report vulnerabilities:
+
+```markdown
+<!-- SECURITY.md -->
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 2.x     | Yes       |
+| 1.x     | Security fixes only until 2025-01-01 |
+| < 1.0   | No        |
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Please report vulnerabilities via GitHub's private vulnerability reporting:
+https://github.com/org/my-library/security/advisories/new
+
+Or email: security@example.com
+
+Include:
+- Description of the vulnerability
+- Steps to reproduce
+- Impact assessment
+- Affected versions
+
+**Response timeline:**
+- Acknowledgment: within 48 hours
+- Initial assessment: within 7 days
+- Fix + disclosure: within 90 days (coordinated disclosure)
+
+We follow [responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure).
+```
+
+### Software Bill of Materials (SBOM)
+
+For libraries used in regulated industries (healthcare, finance, government), consumers may require an SBOM — a machine-readable list of all dependencies:
+
+```yaml
+# .github/workflows/release.yml
+- name: Generate SBOM
+  uses: anchore/sbom-action@v0
+  with:
+    format: spdx-json
+    artifact-name: sbom.spdx.json
+
+- name: Attach SBOM to release
+  uses: softprops/action-gh-release@v2
+  with:
+    files: sbom.spdx.json
+```
+
+This generates a SPDX-format SBOM and attaches it to the GitHub Release. Consumers in regulated environments can use this to verify the library's dependency chain.
+
+### Secret Detection
+
+Never accidentally publish secrets in the library source:
+
+```bash
+# Add git-secrets or similar to pre-commit hooks
+brew install git-secrets
+git secrets --install
+git secrets --register-aws
+
+# Or use gitleaks:
+brew install gitleaks
+gitleaks protect --staged  # Pre-commit check
+```
+
+In CI:
+```yaml
+- name: Scan for secrets
+  uses: trufflesecurity/trufflehog@main
+  with:
+    path: ./
+    base: ${{ github.event.repository.default_branch }}
+```
+
+Never include `.env` files, API keys, private keys, or credentials in the published package. The `files` field in `package.json` is the allowlist — everything else is excluded. Verify with `npm pack --dry-run`.