From dd7e9eb514305073c55811cfa99145dd164f96ab Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Wed, 3 Jun 2026 08:10:26 +0200 Subject: [PATCH 1/3] chore: sync update-deps skill --- .agents/skills/update-deps/SKILL.md | 177 ++++++++++++++++++++++++++++ .ai/shared | 2 +- .claude/commands/update-deps.md | 172 +++++++++++++++++++++++++++ 3 files changed, 350 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/update-deps/SKILL.md create mode 100644 .claude/commands/update-deps.md diff --git a/.agents/skills/update-deps/SKILL.md b/.agents/skills/update-deps/SKILL.md new file mode 100644 index 0000000..7b4df26 --- /dev/null +++ b/.agents/skills/update-deps/SKILL.md @@ -0,0 +1,177 @@ +--- +name: update-deps +description: "Review and update third-party dependencies. Use this when asked to upgrade packages, survey new minor or major releases for useful features, assess whether a repository can adopt them, or validate whether a release looks suspicious before bumping it." +--- + +# Update Dependencies + +Review and update third-party dependencies. Use this when asked +to upgrade packages, survey new minor or major releases for +useful features, assess whether a repository can adopt them, or +validate whether a release looks suspicious before bumping it. + +## Scope + +Default to Bun packages, Cargo crates, and Docker base images. +Expand to GitHub Actions when the request mentions them or the +affected files live in `.github/`. + +Stella repositories may already have automated controls such as: + +- `bunfig.toml` minimum release age rules +- dependency review workflows for license and vulnerability checks +- SBOM or provenance workflows that regenerate dependency artifacts + +Do not duplicate those checks manually unless the user asks for +an audit or the automation looks stale or broken. + +## Arguments + +`$ARGUMENTS` should describe the dependency scope, desired risk +level, and whether to actually apply changes or only prepare a +recommendation. + +Helpful extras when available: + +- package names, ecosystem, or files +- patch-only, minor, major, or mixed +- whether to optimize for new features, risk reduction, or + vulnerability remediation + +If the request is vague, default to: + +1. all outdated dependencies in scope +2. coherent ecosystem-sized batches +3. one commit per validated batch + +## Instructions + +1. **Establish the version source of truth**: + - root `package.json` `catalog`, `catalogs`, and `resolutions` + - workspace `package.json` files + - `bun.lock` + - `Cargo.toml` and `Cargo.lock` + - `.github/dependabot.yml` for grouping expectations + - `.github/workflows/*.yml` for GitHub Action pins + - Dockerfiles and base image digests + +2. **Inventory outdated candidates**: + - run `bun outdated --recursive` for Bun packages + - run `cargo outdated --root-deps-only` for Cargo crates. If + `cargo-outdated` is missing, prefer `cargo binstall + cargo-outdated` when available (prebuilt binary, seconds) + over `cargo install cargo-outdated` (compiles from source, + several minutes). As a fallback, use `cargo update --dry-run` + plus targeted `cargo search` / `cargo info` checks + - inspect open dependency PRs if the request is about triage + rather than local edits + - include GitHub Actions only when the request covers them + +3. **Plan the full sweep, then batch it**: + - cover all outdated dependencies in the requested scope, not + just the first safe batch + - split the work into coherent ecosystem or library-family + batches + - follow existing Dependabot grouping where possible + - avoid mixing high-risk majors with routine minors in the + same commit + - use one commit per validated batch so rollback stays easy + +4. **Classify upgrade risk before touching code**: + - patch: usually lowest risk + - minor: check new features and silent behavior changes + - major: assume migration work + - `0.x` minor: treat as potentially breaking + +5. **Read official upgrade sources**: + - changelog or release notes + - migration guide + - breaking changes + - peer dependency, engine, runtime, and module-format changes + + Prefer official docs, releases, and package metadata over blog + posts or third-party summaries. + +6. **Scan the codebase for adoption opportunities**: + - search current usage with `rg` + - look for deprecated APIs, local workarounds, compatibility + shims, TODOs, or comments the new release could remove + - if a new version unlocks a better pattern, identify the + concrete files that could adopt it now + +7. **Check suspicious-release signals before adopting a fresh version**: + - start with cheap metadata checks first + - release age relative to repository quarantine rules + - publisher, maintainer, repository, or homepage change + - missing or unusual git tag or release notes + - new `preinstall`, `install`, `postinstall`, or `prepare` + scripts + - new native binaries or bundled blobs + + Only escalate to tarball and file-tree inspection when the + metadata looks odd, the package is high risk, or the user + explicitly wants a supply-chain review. That deeper pass can + cover: + - sudden tarball size or file-tree jump + - obfuscated files + - package contents that differ materially from prior releases + without explanation + + Good defaults: + + ```bash + bun info @ --json + npm view @ + bun pm untrusted + ``` + + Use tarball inspection when the metadata looks odd or the + release is high risk. + +8. **Apply the change at the real source of truth**: + - prefer root `catalog`, `catalogs`, or `resolutions` updates + over per-workspace drift + - update GitHub Actions by commit SHA, not floating tags + - keep Docker images pinned by digest + - for Cargo, prefer `cargo update -p ` when the + existing semver range already covers the new version; edit + `Cargo.toml` only when bumping past the range + - after each batch passes validation, commit that batch before + moving to the next one + +9. **Review the lockfile delta**: + - use `bun update`, or edit manifests and run `bun install` + - for Cargo, run `cargo update` and read the `Cargo.lock` diff + the same way (unexpected transitive additions or replacements) + - read the `bun.lock` diff for unexpected transitive additions, + dependency replacement, or new script-bearing packages + - if the new tree introduces untrusted packages with scripts, + inspect them before trusting anything + +10. **Validate in layers**: + - run the smallest focused checks for the affected ecosystem + first + - then run repo checks relevant to the touched surfaces + - for Bun package updates, default to `bun run lint`, `bun run + typecheck`, and the relevant tests + - for Cargo updates, run `cargo check` and `cargo test` when + crates touch logic, not just deps + - verify generated artifacts explicitly when the upgraded + dependency affects them + +11. **Prefer removal and consolidation over passive growth**: + - if the upgrade makes a local helper, polyfill, or wrapper + obsolete, remove it + - if several packages now overlap, prefer the one already + aligned with the codebase + +12. **Report back with**: + - the full batch plan + - current and target versions + - risk level + - why the upgrade is worth taking now + - concrete adoption opportunities found in the codebase + - suspicious-release assessment + - validation run + - commit created for each completed batch + - follow-up work for deferred or blocked majors diff --git a/.ai/shared b/.ai/shared index 37a139e..ddb6f1b 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit 37a139ea018e14e6fe8a3363fd04c92e8c146b8e +Subproject commit ddb6f1bb034861790522fc3075be9c9864e287f9 diff --git a/.claude/commands/update-deps.md b/.claude/commands/update-deps.md new file mode 100644 index 0000000..643fbd3 --- /dev/null +++ b/.claude/commands/update-deps.md @@ -0,0 +1,172 @@ +# Update Dependencies + +Review and update third-party dependencies. Use this when asked +to upgrade packages, survey new minor or major releases for +useful features, assess whether a repository can adopt them, or +validate whether a release looks suspicious before bumping it. + +## Scope + +Default to Bun packages, Cargo crates, and Docker base images. +Expand to GitHub Actions when the request mentions them or the +affected files live in `.github/`. + +Stella repositories may already have automated controls such as: + +- `bunfig.toml` minimum release age rules +- dependency review workflows for license and vulnerability checks +- SBOM or provenance workflows that regenerate dependency artifacts + +Do not duplicate those checks manually unless the user asks for +an audit or the automation looks stale or broken. + +## Arguments + +`$ARGUMENTS` should describe the dependency scope, desired risk +level, and whether to actually apply changes or only prepare a +recommendation. + +Helpful extras when available: + +- package names, ecosystem, or files +- patch-only, minor, major, or mixed +- whether to optimize for new features, risk reduction, or + vulnerability remediation + +If the request is vague, default to: + +1. all outdated dependencies in scope +2. coherent ecosystem-sized batches +3. one commit per validated batch + +## Instructions + +1. **Establish the version source of truth**: + - root `package.json` `catalog`, `catalogs`, and `resolutions` + - workspace `package.json` files + - `bun.lock` + - `Cargo.toml` and `Cargo.lock` + - `.github/dependabot.yml` for grouping expectations + - `.github/workflows/*.yml` for GitHub Action pins + - Dockerfiles and base image digests + +2. **Inventory outdated candidates**: + - run `bun outdated --recursive` for Bun packages + - run `cargo outdated --root-deps-only` for Cargo crates. If + `cargo-outdated` is missing, prefer `cargo binstall + cargo-outdated` when available (prebuilt binary, seconds) + over `cargo install cargo-outdated` (compiles from source, + several minutes). As a fallback, use `cargo update --dry-run` + plus targeted `cargo search` / `cargo info` checks + - inspect open dependency PRs if the request is about triage + rather than local edits + - include GitHub Actions only when the request covers them + +3. **Plan the full sweep, then batch it**: + - cover all outdated dependencies in the requested scope, not + just the first safe batch + - split the work into coherent ecosystem or library-family + batches + - follow existing Dependabot grouping where possible + - avoid mixing high-risk majors with routine minors in the + same commit + - use one commit per validated batch so rollback stays easy + +4. **Classify upgrade risk before touching code**: + - patch: usually lowest risk + - minor: check new features and silent behavior changes + - major: assume migration work + - `0.x` minor: treat as potentially breaking + +5. **Read official upgrade sources**: + - changelog or release notes + - migration guide + - breaking changes + - peer dependency, engine, runtime, and module-format changes + + Prefer official docs, releases, and package metadata over blog + posts or third-party summaries. + +6. **Scan the codebase for adoption opportunities**: + - search current usage with `rg` + - look for deprecated APIs, local workarounds, compatibility + shims, TODOs, or comments the new release could remove + - if a new version unlocks a better pattern, identify the + concrete files that could adopt it now + +7. **Check suspicious-release signals before adopting a fresh version**: + - start with cheap metadata checks first + - release age relative to repository quarantine rules + - publisher, maintainer, repository, or homepage change + - missing or unusual git tag or release notes + - new `preinstall`, `install`, `postinstall`, or `prepare` + scripts + - new native binaries or bundled blobs + + Only escalate to tarball and file-tree inspection when the + metadata looks odd, the package is high risk, or the user + explicitly wants a supply-chain review. That deeper pass can + cover: + - sudden tarball size or file-tree jump + - obfuscated files + - package contents that differ materially from prior releases + without explanation + + Good defaults: + + ```bash + bun info @ --json + npm view @ + bun pm untrusted + ``` + + Use tarball inspection when the metadata looks odd or the + release is high risk. + +8. **Apply the change at the real source of truth**: + - prefer root `catalog`, `catalogs`, or `resolutions` updates + over per-workspace drift + - update GitHub Actions by commit SHA, not floating tags + - keep Docker images pinned by digest + - for Cargo, prefer `cargo update -p ` when the + existing semver range already covers the new version; edit + `Cargo.toml` only when bumping past the range + - after each batch passes validation, commit that batch before + moving to the next one + +9. **Review the lockfile delta**: + - use `bun update`, or edit manifests and run `bun install` + - for Cargo, run `cargo update` and read the `Cargo.lock` diff + the same way (unexpected transitive additions or replacements) + - read the `bun.lock` diff for unexpected transitive additions, + dependency replacement, or new script-bearing packages + - if the new tree introduces untrusted packages with scripts, + inspect them before trusting anything + +10. **Validate in layers**: + - run the smallest focused checks for the affected ecosystem + first + - then run repo checks relevant to the touched surfaces + - for Bun package updates, default to `bun run lint`, `bun run + typecheck`, and the relevant tests + - for Cargo updates, run `cargo check` and `cargo test` when + crates touch logic, not just deps + - verify generated artifacts explicitly when the upgraded + dependency affects them + +11. **Prefer removal and consolidation over passive growth**: + - if the upgrade makes a local helper, polyfill, or wrapper + obsolete, remove it + - if several packages now overlap, prefer the one already + aligned with the codebase + +12. **Report back with**: + - the full batch plan + - current and target versions + - risk level + - why the upgrade is worth taking now + - concrete adoption opportunities found in the codebase + - suspicious-release assessment + - validation run + - commit created for each completed batch + - follow-up work for deferred or blocked majors From 8b36de77ea4b877c138e229d0f540cda037b7c31 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Wed, 3 Jun 2026 09:47:58 +0200 Subject: [PATCH 2/3] fix: sync update-deps workspace command --- .agents/skills/update-deps/SKILL.md | 2 +- .ai/shared | 2 +- .claude/commands/update-deps.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.agents/skills/update-deps/SKILL.md b/.agents/skills/update-deps/SKILL.md index 7b4df26..a135da6 100644 --- a/.agents/skills/update-deps/SKILL.md +++ b/.agents/skills/update-deps/SKILL.md @@ -56,7 +56,7 @@ If the request is vague, default to: - Dockerfiles and base image digests 2. **Inventory outdated candidates**: - - run `bun outdated --recursive` for Bun packages + - run `bun outdated --filter="*"` for Bun workspace packages - run `cargo outdated --root-deps-only` for Cargo crates. If `cargo-outdated` is missing, prefer `cargo binstall cargo-outdated` when available (prebuilt binary, seconds) diff --git a/.ai/shared b/.ai/shared index ddb6f1b..b8fb902 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit ddb6f1bb034861790522fc3075be9c9864e287f9 +Subproject commit b8fb90292c146337c9a0e49b987fbbe999e54308 diff --git a/.claude/commands/update-deps.md b/.claude/commands/update-deps.md index 643fbd3..81b091e 100644 --- a/.claude/commands/update-deps.md +++ b/.claude/commands/update-deps.md @@ -51,7 +51,7 @@ If the request is vague, default to: - Dockerfiles and base image digests 2. **Inventory outdated candidates**: - - run `bun outdated --recursive` for Bun packages + - run `bun outdated --filter="*"` for Bun workspace packages - run `cargo outdated --root-deps-only` for Cargo crates. If `cargo-outdated` is missing, prefer `cargo binstall cargo-outdated` when available (prebuilt binary, seconds) From 4ffbe6927015d3725f78e1750d993f062eed84b8 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Wed, 3 Jun 2026 10:27:07 +0200 Subject: [PATCH 3/3] fix: sync update-deps metadata command --- .agents/skills/update-deps/SKILL.md | 3 +-- .ai/shared | 2 +- .claude/commands/update-deps.md | 3 +-- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.agents/skills/update-deps/SKILL.md b/.agents/skills/update-deps/SKILL.md index a135da6..96f0a4e 100644 --- a/.agents/skills/update-deps/SKILL.md +++ b/.agents/skills/update-deps/SKILL.md @@ -120,8 +120,7 @@ If the request is vague, default to: Good defaults: ```bash - bun info @ --json - npm view @ + npm view @ --json bun pm untrusted ``` diff --git a/.ai/shared b/.ai/shared index b8fb902..2519c1c 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit b8fb90292c146337c9a0e49b987fbbe999e54308 +Subproject commit 2519c1c1bc7fd3ec09a846624968ed496e6dd79f diff --git a/.claude/commands/update-deps.md b/.claude/commands/update-deps.md index 81b091e..3d34668 100644 --- a/.claude/commands/update-deps.md +++ b/.claude/commands/update-deps.md @@ -115,8 +115,7 @@ If the request is vague, default to: Good defaults: ```bash - bun info @ --json - npm view @ + npm view @ --json bun pm untrusted ```