// Use this skill whenever the user asks you to apply dependency update PRs from GitHub — Dependabot bumps, version updates in package.json, or merging dependency PRs. Use this even if the user just says "apply this PR" or "merge these PRs" and the PRs change package.json. This skill handles the dual-lockfile setup (bun.lock + package-lock.json), detects partially-applied PRs, catches stale lockfiles, resolves overlapping version bumps across multiple PRs, and runs the full validation suite after applying. Do not apply Rust/Cargo dependency PRs with this skill.
Use this skill whenever the user asks you to apply dependency update PRs from GitHub — Dependabot bumps, version updates in package.json, or merging dependency PRs. Use this even if the user just says "apply this PR" or "merge these PRs" and the PRs change package.json. This skill handles the dual-lockfile setup (bun.lock + package-lock.json), detects partially-applied PRs, catches stale lockfiles, resolves overlapping version bumps across multiple PRs, and runs the full validation suite after applying. Do not apply Rust/Cargo dependency PRs with this skill.
Apply Dependency PRs
Apply dependency update PRs from GitHub into the workspace, ensuring
correctness across the dual-lockfile setup and catching state mismatches.
Quick Checklist
After loading this skill, the agent should follow these phases:
Discovery: fetch PR diffs, compare against current workspace, detect stale
lockfiles
Planning: create a plan via manual-planning, surface open questions,
get user approval
Execution: edit package.json, run bun install, run
npm install --package-lock-only --legacy-peer-deps
Verification: grep lockfiles for correct versions, run type-check + lint
Commit: stage changed files, create commit with user identity,
message format Dependency Update: <short-summary>, no push
Gotchas
These are the mistakes that happen most often when applying dependency PRs.
Read before starting.
package-lock.json can be stale. If a previous PR was applied with
bun install alone, package-lock.json may still show an old version
number. Always read its first few lines to check. It will be regenerated as
a side effect of execution.
Dependabot PRs only touch package-lock.json. Dependabot uses npm, so
its PRs leave bun.lock untouched. You must regenerate bun.lock locally.
The npm command is NOT npm install. Use the canonical command:
npm install --package-lock-only --legacy-peer-deps. The --legacy-peer-deps
flag is mandatory because eslint-plugin-solid peers on eslint@^9 but the
project uses eslint@10.
One PR may already be applied. Always compare each PR's package.json
diff against the current package.json. Don't assume all PRs are pending.
Multiple PRs can overlap on the same dependency. When two PRs bump the
same package to different versions, take the highest version.
All project commands need cmd.exe /c. This repo is worked on from WSL
over a Windows checkout. Bare bun/npm from WSL may fail.
windows/webview2-com Cargo crates are tied to the Tauri version.
Do not bump these independently. Tauri's transitive deps (wry, tao,
tauri-runtime-wry) own the windows and webview2-com types passed to
our code. A version mismatch causes type-level incompatibilities
(e.g. PCWSTR/Interface/COREWEBVIEW2_WEB_RESOURCE_CONTEXT from
different windows-core versions won't unify). Only bump these when
the Tauri upgrade dictates it.
Check for pre-existing changes before starting. Run git status and
git diff --stat before any edits. Dangling changes from prior work can
contaminate the final change set and must be addressed separately.
npm install --package-lock-only can drop resolved/integrity fields.
With --legacy-peer-deps, npm may write lockfile entries for some transitive
packages that lack resolved and integrity hashes. The Flatpak CI's
generate-node-sources.mjs (line 152: if (!resolved || !integrity) continue)
skips these entries, causing npm ci --offline to fail with
npm error ... cache mode is 'only-if-cached' but no cached response is available.
Detection: after --package-lock-only, check for missing fields
(see Phase 4 step 4). Fix when detected: delete node_modules/, run
a full npm install --legacy-peer-deps to regenerate the lockfile with
complete entries, then bun install to sync bun.lock. In the common
case where all entries are complete, --package-lock-only is preferred
— it's faster and leaves node_modules/ untouched.
@tiptap/* packages are a monorepo — all must be the same version.
You cannot independently pin or downgrade one @tiptap package (e.g. pin
@tiptap/core to 3.23.5 while leaving @tiptap/extensions at 3.23.6).
The packages share internal TypeScript types (Node, Mark, Editor),
and a version mismatch creates duplicate copies in node_modules with
incompatible types — resulting in TS2322: Two different types with this name exist, but they are unrelated. To pin, pin ALL @tiptap/* packages
to the same exact version. If the pinned version's @tiptap/extensions
tarball is missing dist/ files (published incomplete), the pin is not
viable — revert and find a different fix for whatever the pin was meant
to address.
If the user provides URLs instead of numbers, extract the owner, repo, and
PR number from the URL. The owner/repo can be inferred from git remote -v
when not explicitly provided.
Extract the dependency versions from each PR diff. Focus on the
package.json changes: what packages are bumped, from what version to what
version. Ignore package-lock.json hunks during this comparison — the
lockfile is regenerated locally.
Compare against the current workspace. Read package.json and check
each dependency version from the PR. Categorize each PR:
Fully applied: all version bumps already present in package.json
Partially applied: some bumps present, others not
Not applied: no bumps from this PR are present
Check lockfile health. Read the first few lines of package-lock.json
to check its version. If it differs from the version in package.json,
flag it as stale. It will be corrected during npm install.
Check for overlapping changes. If multiple PRs modify the same
dependency to different versions, take the highest version from the
superset of all PRs. The lower-version PR will be auto-closed by
Dependabot once the base branch reflects the higher version — do not
ask the user whether to close it; just note it in the plan.
Phase 2: Planning
Load the manual-planning skill and produce a plan file in docs/
with a descriptive kebab-case name. The plan must follow the
manual-planning template structure exactly: metadata block with status,
Goal/Scope/Non-Goals, Assumptions, Open Questions, numbered tasks each
with Status/Objective/Steps/Validation/Notes, a Cleanup task, and a
Final Verification section. Each task's Validation field must list the
specific commands to run (not prose).
The plan must include these details:
Which PRs are already applied and which are pending
Which dependencies will change and their new versions
Lockfile strategy: both bun install and
npm install --package-lock-only --legacy-peer-deps will be run
Stale lockfile warning if detected in Phase 1
Expected changed files: only package.json, bun.lock, and
package-lock.json
Validation tasks: separate tasks for type-check, lint, and test:run,
each with the exact cmd.exe /c bun run <command> as its Validation
Surface only blocking questions before marking the plan
READY FOR APPROVAL:
Are there truly conflicting version bumps (two PRs targeting different
major versions of the same package)?
Is there a major version bump that could break the app?
Does Cargo.toml also need updates?
Do NOT ask operational questions (e.g., "should I close the superseded
PR?") — Dependabot auto-closes PRs when their base branch no longer
needs the bump after the higher version is applied.
Do not begin implementation until the user approves.
Phase 3: Execution
Edit package.json to apply all pending version bumps. Change only
version strings — do not reorder dependencies or alter formatting.
cmd.exe /c bun run type-check
cmd.exe /c bun run lint
cmd.exe /c bun run test:run
All three must exit with code 0.
Verify the file change set:
git diff --stat
Should show exactly three files: package.json, bun.lock, and
package-lock.json. Investigate any additional files.
Verify Flatpak lockfile integrity. The Flatpak CI build runs
npm ci --offline from a cache built by generate-node-sources.mjs,
which requires every node_modules/ entry to have resolved and
integrity fields. Check for missing entries:
Use the author's real name/email from git config user.name / git config user.email
(set GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME,
GIT_COMMITTER_EMAIL if needed). The commit message format is:
Dependency Update: <list of bumped packages>. Stage only the files
that were intentionally changed (typically package.json, bun.lock,
package-lock.json; for Cargo-only updates, Cargo.lock).
Scope Boundaries
Only npm/bun dependencies. For Cargo/Rust dependency updates, use
separate handling — this skill does not touch Cargo.toml or Cargo.lock.
When the user asks to merge a mixed batch of npm + Cargo PRs, apply the
npm PRs with this skill and handle the Cargo PRs separately with
cargo update for lock-only bumps and manual review for Cargo.toml
bumps (checking for diamond dependency conflicts against Tauri's transitive
deps). Note which PRs fall in each category in the plan.
E2E tests are out of scope for dependency bumps. Running
test:e2e is not required unless the bumped dependency is a Tauri API or
plugin that could affect IPC behavior.
Reference
For full details on the dual-lockfile requirement and the Flatpak pipeline:
