# CI Dependency Resolution Fix

## Summary

I fixed the failing Forgejo CI install by removing the GitHub git-commit dependency on `@electron/node-gyp` from lock resolution and forcing it through the npm package `@electron/node-gyp@^10.2.0-electron.2` via repository overrides.

## Changes Made

- Added an override in package.json: `@electron/node-gyp: ^10.2.0-electron.2`.
- Synchronized lock files so both roots resolve from the npm package instead of the short GitHub tarball ref: bun.lock and deployment/docker/workspace-root/bun.lock.
- Updated mirrored workspace package manifest: deployment/docker/workspace-root/package.json.
- Re-synced docker workspace files using `bun run sync:docker-workspace`.

## Context

CI was failing in dependency install with this error:

    error: failed to download @electron/node-gyp@github:electron/node-gyp#06b29aa ... 404 Not Found

In this environment, that endpoint is interpreted by the Forgejo git proxy and the short SHA is resolved against an unavailable internal mirror path. For a CI runner, this is a fragile install path.

## Important Implementation Details

- Using an override keeps all transitive graph consumers of `@electron/node-gyp` on the same npm release and avoids GitHub tarball URL resolution entirely.
- The lockfile entry moved from a git URL spec to `@electron/node-gyp@10.2.0-electron.2` with a resolved tarball checksum entry, which is stable in CI contexts.
- The Docker workspace copy was updated to avoid drift between root and deployment lock snapshots.

## Relevant Diff Snippets

    diff --git a/package.json b/package.json
    @@
       "overrides": {
         "postcss": "^8.5.15",
         "tar": "^7.5.15",
    -    "tmp": "^0.2.5"
    +    "tmp": "^0.2.5",
    +    "@electron/node-gyp": "^10.2.0-electron.2"
       },
    @@
     diff --git a/deployment/docker/workspace-root/package.json b/deployment/docker/workspace-root/package.json
    @@
       "overrides": {
         "postcss": "^8.5.15",
         "tar": "^7.5.15",
    -    "tmp": "^0.2.5"
    +    "tmp": "^0.2.5",
    +    "@electron/node-gyp": "^10.2.0-electron.2"
       },
    @@
     diff --git a/bun.lock b/bun.lock
    @@
    -    "@electron/node-gyp": ["@electron/node-gyp@github:electron/node-gyp#06b29aa", { "dependencies": { "env-paths": "^2.2.0", "exponential-backoff": "^3.1.1", "glob": "^8.1.0", "graceful-fs": "^4.2.6", "make-fetch-happen": "^10.2.1", "nopt": "^6.0.0", "proc-log": "^2.0.1", "semver": "^7.3.5", "tar": "^6.2.1", "which": "^2.0.2" }, "bin": "./bin/node-gyp.js" }, "electron-node-gyp-06b29aa"],
    +    "@electron/node-gyp": ["@electron/node-gyp@10.2.0-electron.2", "", { "dependencies": { "env-paths": "^2.2.0", "exponential-backoff": "^3.1.1", "glob": "^8.1.0", "graceful-fs": "^4.2.6", "make-fetch-happen": "^10.2.1", "nopt": "^6.0.0", "proc-log": "^2.0.1", "semver": "^7.3.5", "tar": "^6.2.1", "which": "^2.0.2" }, "bin": { "node-gyp": "bin/node-gyp.js" } }, "sha512-OhO6fwqpetMO1vWI3+J8mb3a4s4A405tgKoUCJsgd4nyQDdFh0VvZm+gj/Cc70iRLQoIYUfSaAgYSVwmLsQHig=="],
    @@
     diff --git a/deployment/docker/workspace-root/bun.lock b/deployment/docker/workspace-root/bun.lock
    @@
    -    "@electron/node-gyp": ["@electron/node-gyp@github:electron/node-gyp#06b29aa", { "dependencies": { "env-paths": "^2.2.0", "exponential-backoff": "^3.1.1", "glob": "^8.1.0", "graceful-fs": "^4.2.6", "make-fetch-happen": "^10.2.1", "nopt": "^6.0.0", "proc-log": "^2.0.1", "semver": "^7.3.5", "tar": "^6.2.1", "which": "^2.0.2" }, "bin": "./bin/node-gyp.js" }, "electron-node-gyp-06b29aa"],
    +    "@electron/node-gyp": ["@electron/node-gyp@10.2.0-electron.2", "", { "dependencies": { "env-paths": "^2.2.0", "exponential-backoff": "^3.1.1", "glob": "^8.1.0", "graceful-fs": "^4.2.6", "make-fetch-happen": "^10.2.1", "nopt": "^6.0.0", "proc-log": "^2.0.1", "semver": "^7.3.5", "tar": "^6.2.1", "which": "^2.0.2" }, "bin": { "node-gyp": "bin/node-gyp.js" } }, "sha512-OhO6fwqpetMO1vWI3+J8mb3a4s4A405tgKoUCJsgd4nyQDdFh0VvZm+gj/Cc70iRLQoIYUfSaAgYSVwmLsQHig=="],

Note: For this repository-required documentation rule, lockfile snippets were summarized directly because rendered `@pierre/diffs` output is very verbose with embedded style payloads for each file block.

## Expected Impact for End-Users

- Forgejo CI installs should no longer fail on unresolved `@electron/node-gyp` GitHub commit tarball lookups.
- Dependency install becomes deterministic using a versioned npm package artifact.
- Docker workspace and root lockfiles remain in sync.

## Validation

- `bun install` (lock refresh after override)
- `bun install --frozen-lockfile`
- `bun run typecheck`
- `bun run check:docker-workspace`
- `bun test`
- `bun --cwd=apps/web run build`

All checks completed successfully.

## Issues, Limitations, and Mitigations

- The transitive package `@electron/rebuild` still references the same GitHub commit in its dependency metadata, but override forces resolution to the npm package, which is now what the lock consumes in this repo.
- If another service writes lockfile with a different package-manager behavior, a re-sync is required. We already captured this in the workflow by syncing the docker workspace copy.

## Follow-up Work

- Watch one CI run on Forgejo to confirm the endpoint that caused 404 is fully gone.
- Consider a small dependency bump for `@electron/rebuild` if it later publishes a lockfile-safe package-only variant.
- Pin lockfile sync as a required step in any scripted dependency maintenance path.