Skip to main content

Supported Dependency Migrations

Use when replacing unsupported dependency chains.

Purpose​

Migrate applications away from unsupported direct or transitive packages without hiding warnings, forcing unproven versions, or weakening runtime and packaging contracts.

A deprecation notice and an unsupported module are not automatically the same condition. Classify current maintenance/support status and the user's policy first. For this user, deprecation is acceptable only while the module remains maintained and supported; unsupported modules and warning suppression are not acceptable.

Workflow​

  1. Capture a clean-install log and count warnings programmatically.
  2. Before sending a human to a target OS, inspect every direct native dependency's published os, cpu, engines, prebuild matrix, and support statement for that exact target. Run the smallest clean-install probe first; do not make the operator discover a deterministic platform exclusion after a long handoff.
  3. Map every warned or rejected name@version to its direct owner with npm explain, npm ls --all, lockfile ancestry, and registry/package metadata.
  4. Separate installed modules from absent peer-only lock metadata and runtime dependencies from build-only tooling.
  5. Evaluate stable maintained replacements. Reject suppression, forced audit upgrades, ignored platform checks, and prereleases unless explicitly approved.
  6. Preserve behavior with focused RED→GREEN tests before changing implementation.
  7. Add an enforceable installed-state policy and CI gate.
  8. Verify clean install, dependency tree, focused tests, full suite, build, packaged contents, and each native target.
  9. Bind independent reviews to the exact immutable head; mutation expires verdicts.

When a security-sensitive native dependency owns a durable file format, do not fold its replacement into a broad warning-cleanup PR. Create a separate dependency-ordered program: freeze old-driver fixtures and effective format parameters; prove an adapter against untouched files; cut production over; convert integration helpers; run crash/no-plaintext tests; validate packaged native artifacts; execute native human gates; then make the final adoption/rollback decision. Only the foundation task is initially claimable.

Core Rules​

  • A successful install is not proof that unsupported packages are absent.
  • A lockfile-only policy is not proof of the physical installation.
  • An absent peer record may remain in lock metadata without being installed.
  • An override must be exact and API-compatible, with target-specific behavior tested.
  • Preserve retained descriptors, path ownership, stream errors, memory bounds, and fail-closed cleanup.
  • Keep broad dependency migration separate from unrelated reviewed security changes.
  • Do not call a packaging change merge-ready until each required native platform is exercised.
  • Interpret native-build failures causally: if clean install fails, later command not found, missing build output, and absent installer errors are cascading symptoms, not separate defects. Stop at the first failed prerequisite and never recommend a forced install for a runtime native module.
  • Run typecheck, lint, and tests independently; the final status of semicolon-separated commands proves only the final command.

Detailed npm Reference​

See references/npm-supported-dependency-migrations.md for physical-tree policy design, symlink boundaries, fixtures, artifact inspection, and the verification ladder.

See references/encrypted-native-database-migrations.md when a native binding owns encrypted database files, key/profile semantics, or cross-platform packaged delivery.

Completion Criteria​

  • Clean installation evidence has an explicit warning count.
  • Every targeted unsupported package is absent from the physical tree and packaged artifact.
  • Replacement APIs pass focused behavioral tests.
  • Policy tests include adversarial physical-tree and malformed-metadata fixtures.
  • Full tests, typecheck, lint, audit policy, and application build pass.
  • Native package/install/launch gates are recorded per target OS.
  • Exact-head independent review verdicts are visible and current.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/engineering/supported-dependency-migrations/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/supported-dependency-migrations/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

Published by Muse · 2026-10-04.