TML-2519: prisma-next-upgrade and prisma-next-extension-upgrade skills#508
Merged
wmadden merged 17 commits intoMay 15, 2026
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughIntroduces user and extension upgrade skills with docs and 0.7→0.8 placeholders, adds a coverage-check CLI with tests and CI wiring, enforces exact ChangesUpgrade skill mechanism and workspace coordination
Sequence Diagram(s)sequenceDiagram
participant Dev
participant CI
participant Coverage as check-upgrade-coverage.mjs
participant Skills as upgrade-skill packages
Dev->>CI: Open PR with code touching examples/extensions
CI->>Coverage: Run --mode pr against origin/main
Coverage->>Skills: Verify upgrades/<transition>/ exists
Coverage-->>CI: Report violations or success
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 20
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (2)
packages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.md-7-9 (1)
7-9:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove PR-specific transition-history text from published instructions.
Line 7–9 ties this durable file to a future PR/rebase narrative instead of current-state behavior.
Suggested doc fix
-This directory is a placeholder so that the publish gate has a real -directory to verify against. The first real upgrade-instructions -entries land via PR `#502`'s rebase onto this PR. +No user-side migration actions are required for 0.6 → 0.7 at this time. +`changes: []` intentionally marks this transition as a no-op.As per coding guidelines: "
packages/**/*.md: Update design docs to reflect the current state only, not the transition history or legacy approaches."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.md` around lines 7 - 9, Remove the PR-specific transition-history text that ties the file to "PR `#502`" and the rebase narrative; instead replace the lines starting with "This directory is a placeholder..." and the following sentence about "The first real upgrade-instructions entries land via PR `#502`'s rebase onto this PR" with a neutral, current-state description (e.g., "This directory is a placeholder used by the publish gate to verify a real directory exists; upgrade instructions will be added here when available.") so the markdown reflects only present behavior.packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md-7-9 (1)
7-9:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove PR-specific placeholder text from shipped instructions.
This package file will be published; referencing “PR
#502’s rebase” will go stale and is not actionable for consumers. Keep the placeholder transition-state only.Proposed edit
-This directory is a placeholder so that the publish gate has a real -directory to verify against. The first real upgrade-instructions -entries land via PR `#502`'s rebase onto this PR. +No upgrade-instruction entries are recorded for this transition yet. +Add entries to `changes` when a downstream-breaking translation is required.As per coding guidelines, “
packages/**/*.md: Update design docs to reflect the current state only, not the transition history or legacy approaches.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md` around lines 7 - 9, The instructions.md contains PR-specific placeholder text ("PR `#502`'s rebase") that must be removed; edit packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md to strip any mention of PR numbers or transition history and replace with neutral placeholder wording (e.g., "This directory is a placeholder for upgrade instructions" or similar) so the file only reflects the current shipped state and not actionable or transient PR references.
🧹 Nitpick comments (1)
scripts/check-upgrade-coverage.mjs (1)
227-264: ⚡ Quick winMake substrate coverage checks data-driven to prevent rule drift.
The
examples/andpackages/3-extensions/blocks duplicate the same control flow. A small declarative rule table would make future substrate additions safer and clearer.As per coding guidelines, “
scripts/**/*.mjs: Prefer declarative data structures over hardcoded conditionals for validation rules, constraints, and configuration logic.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/check-upgrade-coverage.mjs` around lines 227 - 264, Duplicate conditional blocks checking examples and extensions should be replaced with a data-driven table; create an array (e.g., const substrateRules = [{watchPath: 'examples/', substrate: 'examples/', pkgRoot: USER_SKILL_PKG}, {watchPath: 'packages/3-extensions/', substrate: 'packages/3-extensions/', pkgRoot: EXT_SKILL_PKG}]) and then inside the sameMinor branch iterate substrateRules, call diffPaths(repoRoot, prev, head, [rule.watchPath], path => !isGeneratedExamplePath(path)), and if diff length > 0 compute requiredDir = `${rule.pkgRoot}/upgrades/${coverageTransition}` and use existsSync to push the same violations object (with substrate: rule.substrate and sampleDiffPaths: diff.slice(0,5)) into violations; keep existing symbols (sameMinor, diffPaths, isGeneratedExamplePath, USER_SKILL_PKG, EXT_SKILL_PKG, coverageTransition, violations) so behavior is unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/cipherstash-integration/package.json`:
- Around line 19-30: The package.json dependency specifiers were updated to use
workspace:0.7.0 (e.g., "@prisma-next/adapter-postgres",
"@prisma-next/extension-cipherstash", "@prisma-next/tsconfig", etc.) but the
pnpm lockfile was not regenerated, causing pnpm install --frozen-lockfile to
fail; run pnpm install to regenerate pnpm-lock.yaml (or pnpm install
--lockfile-only), verify the lock contains the new workspace:0.7.0 entries, and
commit the updated pnpm-lock.yaml alongside the package.json changes so the
lockfile and manifest are in sync.
In `@examples/prisma-next-demo-sqlite/package.json`:
- Around line 18-32: The package.json dependency specifier changes (e.g.
"@prisma-next/adapter-sqlite", "@prisma-next/tsconfig" and the other
"@prisma-next/*" entries) were committed without updating the lockfile, causing
CI to fail under pnpm install --frozen-lockfile; regenerate pnpm-lock.yaml
locally (run pnpm install) so the lockfile matches these updated specifiers and
commit the updated pnpm-lock.yaml alongside the package.json changes.
In `@package.json`:
- Line 51: The package manifest was modified for the dependency
"@prisma-next/tsconfig": "workspace:0.7.0" but the lockfile is out of sync; run
a fresh lockfile regeneration (e.g., run pnpm install locally or pnpm install
--lockfile-only) to update pnpm-lock.yaml, verify pnpm install --frozen-lockfile
succeeds, and commit the updated lockfile alongside the package.json change so
CI no longer fails.
In `@packages/0-shared/extension-upgrade-skill/SKILL.md`:
- Around line 99-101: The doc currently tells readers to update the
`@prisma-next/extension-upgrade-skill` entry to `<to>`, which conflicts with
Step 0 and can cause downgrades; change the wording in SKILL.md (the paragraph
around the `@prisma-next/extension-upgrade-skill` mention) to instruct
maintainers to keep the extension-upgrade skill pinned to `@latest` (not
`<to>`), and explicitly reference Step 0 so the doc clarifies that the skill
must remain `@latest` to avoid applying stale instructions.
In `@packages/0-shared/upgrade-skill/SKILL.md`:
- Around line 122-124: The docs currently instruct rewriting the
`@prisma-next/upgrade-skill` entry to <to>, which would downgrade/pin the skill;
instead, update the guidance so the dependency rewrite skips changing the
`@prisma-next/upgrade-skill` package (do not replace its version with <to>) and
explicitly state to preserve/ensure it remains `@latest` (or the existing version)
so cumulative instruction fixes aren’t lost; reference the
`@prisma-next/upgrade-skill` token and the <to> placeholder and adjust the
surrounding sentences (the paragraph that currently says "Also update the
`@prisma-next/upgrade-skill` entry itself to `<to>`") to instruct skipping or
preserving that entry.
In `@packages/1-framework/1-core/config/package.json`:
- Around line 19-21: The package.json manifest was updated to use
workspace:0.7.0 for the packages "@prisma-next/contract",
"@prisma-next/framework-components", and "@prisma-next/utils", causing lockfile
drift; regenerate the pnpm lockfile from the repository root by running pnpm
install (or pnpm install --prefer-frozen-lockfile then pnpm install to update)
so pnpm-lock.yaml matches these specifiers, then commit the updated
pnpm-lock.yaml alongside the package.json changes so CI passes (ensure the
lockfile reflects workspace:0.7.0 for those three packages).
In `@packages/1-framework/2-authoring/psl-printer/package.json`:
- Around line 19-24: The pnpm lockfile is out of sync with the updated manifest
pins in package.json (the devDependency specifiers for
"@prisma-next/psl-parser", "@prisma-next/tsconfig", "@prisma-next/tsdown" and
the dependency "@prisma-next/framework-components"); run pnpm install to
regenerate pnpm-lock.yaml (or pnpm install --lockfile-only) so the lockfile
reflects those workspace:0.7.0 pins, verify the updated pnpm-lock.yaml contains
the new specifiers, and commit the regenerated pnpm-lock.yaml alongside your
package.json change.
In `@packages/2-mongo-family/1-foundation/mongo-value/package.json`:
- Around line 20-21: The package manifest was updated to use workspace:0.7.0 for
the dependencies "@prisma-next/tsconfig" and "@prisma-next/tsdown" but the
lockfile wasn't regenerated; run pnpm install to refresh pnpm-lock.yaml (or pnpm
install --lockfile-only) so the new workspace specifiers are reflected, verify
the lockfile changes include the updated specifiers, and commit the updated
pnpm-lock.yaml alongside the package.json change.
In `@packages/2-mongo-family/6-transport/mongo-lowering/package.json`:
- Around line 19-25: The package.json was updated to use workspace:0.7.0 for
several packages (e.g. "@prisma-next/framework-components",
"@prisma-next/mongo-query-ast", "@prisma-next/mongo-wire", and devDeps
"@prisma-next/tsconfig", "@prisma-next/tsdown") but pnpm-lock.yaml was not
updated; run pnpm install (or pnpm install --lockfile-only) to regenerate the
lockfile so the lock matches the new workspace:0.7.0 specifiers and commit the
updated pnpm-lock.yaml so CI passing pnpm install --frozen-lockfile succeeds.
In `@packages/2-sql/2-authoring/contract-psl/package.json`:
- Around line 19-25: Regenerate the pnpm lockfile to match the updated workspace
pins: run pnpm install (or pnpm install --lockfile-only) to refresh
pnpm-lock.yaml after changing the dependency specifiers like
"@prisma-next/config", "@prisma-next/contract", "@prisma-next/psl-parser",
"@prisma-next/sql-contract", "@prisma-next/sql-contract-ts",
"@prisma-next/framework-components", and "@prisma-next/utils" (and the noted
`@prisma-next/tsconfig` entries), verify pnpm install --frozen-lockfile succeeds,
and commit the updated pnpm-lock.yaml alongside the manifest changes.
In `@packages/3-extensions/arktype-json/package.json`:
- Around line 18-23: The package manifests were changed to use workspace:0.7.0
for dependencies like "@prisma-next/contract",
"@prisma-next/contract-authoring", "@prisma-next/family-sql",
"@prisma-next/framework-components", "@prisma-next/sql-relational-core", and
"@prisma-next/sql-runtime", but the pnpm lockfile is out of sync causing CI
failures; run pnpm install (or pnpm install --lockfile-only) from the repo root
to regenerate pnpm-lock.yaml, verify the lockfile updates include the
workspace:0.7.0 entries (also check the similar edits referenced at lines
28-31), then add and commit the updated pnpm-lock.yaml to this PR.
In `@packages/3-extensions/sql-orm-client/package.json`:
- Around line 21-28: The package dependency specifiers were changed to
workspace:0.7.0 (e.g., "@prisma-next/contract", "@prisma-next/sql-runtime",
"@prisma-next/utils"); regenerate the pnpm lockfile so the lock matches these
new workspace specifiers, commit the updated pnpm-lock.yaml, and re-run CI. To
fix: run pnpm install (or pnpm install --lockfile-only) at repository root to
update pnpm-lock.yaml, verify the lockfile contains the workspace:0.7.0 entries
for the same "@prisma-next/*" packages shown in the diff, and commit the updated
lockfile; repeat the same regeneration for the other affected package groups
referenced (lines 31-41) if they have similar specifier changes.
In `@packages/3-targets/6-adapters/sqlite/package.json`:
- Around line 22-36: The package.json workspace dependency specifiers were
changed but the pnpm lockfile wasn't updated; run pnpm install (or pnpm install
--lockfile-only) to regenerate pnpm-lock.yaml so the new specifiers (e.g.,
"@prisma-next/cli", "@prisma-next/contract", "@prisma-next/target-sqlite" and
the other "@prisma-next/*" entries referenced) are reflected, then commit the
updated pnpm-lock.yaml to the PR (also repeat for the other affected
package.json edits mentioned for lines 40-44).
In `@scripts/check-upgrade-coverage.mjs`:
- Around line 236-257: The current checks use existsSync on
`${repoRoot}/${requiredDir}` (where requiredDir is built from EXT_SKILL_PKG or
USER_SKILL_PKG + `/upgrades/${coverageTransition}`) which only inspects the
working tree; instead, ensure you verify that instructions.md exists in the
target ref (head or prev used by diffPaths) by querying the git tree at that ref
(e.g., via `git cat-file -e <ref>:<path>` or a helper like gitShowFileExists)
for `${requiredDir}/instructions.md` and push a violation if that file is
missing; update both example and extension branches (the blocks handling
examplesDiff and extDiff) to replace existsSync checks with a git-ref-aware
existence check so the rule validates the file in the commit being compared
rather than the local checkout.
In `@test/e2e/framework/package.json`:
- Around line 17-18: The package.json in test/e2e/framework has `@prisma-next`
dependencies pinned to "workspace:0.7.0" (e.g., entries for
"@prisma-next/tsconfig" and "@prisma-next/utils"); update these dependency
versions to "workspace:*" (and apply the same change to any other `@prisma-next/`*
entries in the file between lines 26-50) so test package manifests use the
workspace:* protocol instead of a fixed workspace version.
In `@test/integration/package.json`:
- Around line 22-60: The package.json in the test package incorrectly pins many
`@prisma-next/`* dependencies to "workspace:0.7.0"; update each `@prisma-next`
dependency (e.g., "@prisma-next/adapter-postgres", "@prisma-next/cli",
"@prisma-next/contract", "@prisma-next/driver-postgres", "@prisma-next/emitter",
"@prisma-next/extension-arktype-json", "@prisma-next/extension-cipherstash",
"@prisma-next/extension-paradedb", "@prisma-next/extension-pgvector",
"@prisma-next/family-sql", "@prisma-next/ids", "@prisma-next/migration-tools",
"@prisma-next/operations", "@prisma-next/postgres", "@prisma-next/psl-parser",
"@prisma-next/sql-contract", "@prisma-next/sql-contract-emitter",
"@prisma-next/sql-contract-psl", "@prisma-next/sql-contract-ts",
"@prisma-next/sql-orm-client", "@prisma-next/sql-builder",
"@prisma-next/sql-relational-core", "@prisma-next/sql-runtime",
"@prisma-next/target-postgres", "@prisma-next/adapter-mongo",
"@prisma-next/driver-mongo", "@prisma-next/family-mongo",
"@prisma-next/mongo-codec", "@prisma-next/mongo-contract",
"@prisma-next/mongo-contract-psl", "@prisma-next/mongo-value",
"@prisma-next/mongo-contract-ts", "@prisma-next/mongo-orm",
"@prisma-next/mongo-query-builder", "@prisma-next/mongo-query-ast",
"@prisma-next/mongo-runtime", "@prisma-next/target-mongo", "@prisma-next/utils",
"@prisma-next/vite-plugin-contract-emit" (and the additional entries noted at
lines 64-68) to use "workspace:*" instead of "workspace:0.7.0" so the test
package follows the workspace:* protocol.
In `@test/integration/test/fixtures/cli/cli-e2e-test-app/package.json`:
- Around line 6-21: The package.json fixture lists many `@prisma-next/`*
dependencies pinned to a specific workspace:0.7.0; update each listed dependency
(e.g., "@prisma-next/adapter-mongo", "@prisma-next/adapter-postgres",
"@prisma-next/cli", "@prisma-next/driver-mongo", "@prisma-next/driver-postgres",
"@prisma-next/family-mongo", "@prisma-next/family-sql",
"@prisma-next/framework-components", "@prisma-next/mongo-contract",
"@prisma-next/mongo-contract-ts", "@prisma-next/mongo-orm",
"@prisma-next/mongo-query-ast", "@prisma-next/sql-contract-ts",
"@prisma-next/target-mongo", "@prisma-next/target-postgres",
"@prisma-next/utils") to use the workspace:* protocol instead of the fixed
version (replace "workspace:0.7.0" with "workspace:*") so the test fixture
follows the guideline to use workspace:* for test package.json dependencies.
In `@test/integration/test/fixtures/cli/cli-integration-test-app/package.json`:
- Around line 6-22: The package.json dependency entries for the `@prisma-next/`*
packages are pinned to "workspace:0.7.0" which violates the test manifest rule
to use the workspace:* protocol; change each dependency string for
`@prisma-next/adapter-mongo`, `@prisma-next/adapter-postgres`, `@prisma-next/cli`,
`@prisma-next/contract`, `@prisma-next/framework-components`,
`@prisma-next/driver-postgres`, `@prisma-next/family-mongo`,
`@prisma-next/family-sql`, `@prisma-next/mongo`, `@prisma-next/mongo-contract-psl`,
`@prisma-next/mongo-contract-ts`, `@prisma-next/postgres`,
`@prisma-next/sql-contract`, `@prisma-next/sql-contract-ts`,
`@prisma-next/target-mongo`, `@prisma-next/target-postgres`, and `@prisma-next/utils`
from "workspace:0.7.0" to "workspace:*" so the test package.json uses the
workspace protocol.
In `@test/integration/test/fixtures/cli/cli-test-app/package.json`:
- Around line 6-10: The package.json in the test fixture uses pinned workspace
versions for `@prisma-next` packages which violates the test guideline; update the
dependency entries "@prisma-next/adapter-postgres", "@prisma-next/cli",
"@prisma-next/family-sql", "@prisma-next/sql-contract-ts", and
"@prisma-next/target-postgres" to use the workspace:* protocol (i.e., replace
"workspace:0.7.0" with "workspace:*") so the fixture follows the requirement
that test package.json files use workspace:* for workspace dependencies.
In `@test/utils/package.json`:
- Around line 16-20: The test package.json has two dependencies changed from the
required test protocol to fixed versions; revert the "@prisma-next/tsconfig" and
"@prisma-next/tsdown" entries back to use the workspace:* protocol (i.e., set
their versions to "workspace:*") so test packages follow the guideline; locate
the two entries for "@prisma-next/tsconfig" and "@prisma-next/tsdown" in
test/utils/package.json and update their version strings accordingly.
---
Minor comments:
In
`@packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md`:
- Around line 7-9: The instructions.md contains PR-specific placeholder text
("PR `#502`'s rebase") that must be removed; edit
packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md to
strip any mention of PR numbers or transition history and replace with neutral
placeholder wording (e.g., "This directory is a placeholder for upgrade
instructions" or similar) so the file only reflects the current shipped state
and not actionable or transient PR references.
In `@packages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.md`:
- Around line 7-9: Remove the PR-specific transition-history text that ties the
file to "PR `#502`" and the rebase narrative; instead replace the lines starting
with "This directory is a placeholder..." and the following sentence about "The
first real upgrade-instructions entries land via PR `#502`'s rebase onto this PR"
with a neutral, current-state description (e.g., "This directory is a
placeholder used by the publish gate to verify a real directory exists; upgrade
instructions will be added here when available.") so the markdown reflects only
present behavior.
---
Nitpick comments:
In `@scripts/check-upgrade-coverage.mjs`:
- Around line 227-264: Duplicate conditional blocks checking examples and
extensions should be replaced with a data-driven table; create an array (e.g.,
const substrateRules = [{watchPath: 'examples/', substrate: 'examples/',
pkgRoot: USER_SKILL_PKG}, {watchPath: 'packages/3-extensions/', substrate:
'packages/3-extensions/', pkgRoot: EXT_SKILL_PKG}]) and then inside the
sameMinor branch iterate substrateRules, call diffPaths(repoRoot, prev, head,
[rule.watchPath], path => !isGeneratedExamplePath(path)), and if diff length > 0
compute requiredDir = `${rule.pkgRoot}/upgrades/${coverageTransition}` and use
existsSync to push the same violations object (with substrate: rule.substrate
and sampleDiffPaths: diff.slice(0,5)) into violations; keep existing symbols
(sameMinor, diffPaths, isGeneratedExamplePath, USER_SKILL_PKG, EXT_SKILL_PKG,
coverageTransition, violations) so behavior is unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: ccf3f686-bb3b-476a-b8fc-e0cb9d3749a1
⛔ Files ignored due to path filters (3)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlprojects/prisma-next-agent-skill/plans/upgrade-skill-plan.mdis excluded by!projects/**projects/prisma-next-agent-skill/specs/upgrade-skill.spec.mdis excluded by!projects/**
📒 Files selected for processing (100)
.agents/skills/record-upgrade-instructions/SKILL.md.github/workflows/ci.yml.github/workflows/publish.ymlexamples/cipherstash-integration/package.jsonexamples/mongo-blog-leaderboard/package.jsonexamples/mongo-demo/package.jsonexamples/multi-extension-monorepo/package.jsonexamples/paradedb-demo/package.jsonexamples/prisma-next-cloudflare-worker/package.jsonexamples/prisma-next-demo-sqlite/package.jsonexamples/prisma-next-demo/package.jsonexamples/prisma-next-postgis-demo/package.jsonexamples/react-router-demo/package.jsonexamples/retail-store/package.jsonpackage.jsonpackages/0-config/tsdown/package.jsonpackages/0-shared/extension-upgrade-skill/README.mdpackages/0-shared/extension-upgrade-skill/SKILL.mdpackages/0-shared/extension-upgrade-skill/bin/prisma-next-check-pins.mjspackages/0-shared/extension-upgrade-skill/package.jsonpackages/0-shared/extension-upgrade-skill/test/check-pins.test.mjspackages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.mdpackages/0-shared/upgrade-skill/README.mdpackages/0-shared/upgrade-skill/SKILL.mdpackages/0-shared/upgrade-skill/package.jsonpackages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.mdpackages/1-framework/0-foundation/contract/package.jsonpackages/1-framework/0-foundation/utils/package.jsonpackages/1-framework/1-core/config/package.jsonpackages/1-framework/1-core/errors/package.jsonpackages/1-framework/1-core/framework-components/package.jsonpackages/1-framework/1-core/operations/package.jsonpackages/1-framework/1-core/ts-render/package.jsonpackages/1-framework/2-authoring/contract/package.jsonpackages/1-framework/2-authoring/ids/package.jsonpackages/1-framework/2-authoring/psl-parser/package.jsonpackages/1-framework/2-authoring/psl-printer/package.jsonpackages/1-framework/3-tooling/cli/package.jsonpackages/1-framework/3-tooling/emitter/package.jsonpackages/1-framework/3-tooling/migration/package.jsonpackages/1-framework/3-tooling/prisma-next/package.jsonpackages/1-framework/3-tooling/vite-plugin-contract-emit/package.jsonpackages/2-mongo-family/1-foundation/mongo-codec/package.jsonpackages/2-mongo-family/1-foundation/mongo-contract/package.jsonpackages/2-mongo-family/1-foundation/mongo-value/package.jsonpackages/2-mongo-family/2-authoring/contract-psl/package.jsonpackages/2-mongo-family/2-authoring/contract-ts/package.jsonpackages/2-mongo-family/3-tooling/emitter/package.jsonpackages/2-mongo-family/3-tooling/mongo-schema-ir/package.jsonpackages/2-mongo-family/4-query/query-ast/package.jsonpackages/2-mongo-family/5-query-builders/orm/package.jsonpackages/2-mongo-family/5-query-builders/query-builder/package.jsonpackages/2-mongo-family/6-transport/mongo-lowering/package.jsonpackages/2-mongo-family/6-transport/mongo-wire/package.jsonpackages/2-mongo-family/7-runtime/package.jsonpackages/2-mongo-family/9-family/package.jsonpackages/2-sql/1-core/contract/package.jsonpackages/2-sql/1-core/errors/package.jsonpackages/2-sql/1-core/operations/package.jsonpackages/2-sql/1-core/schema-ir/package.jsonpackages/2-sql/2-authoring/contract-psl/package.jsonpackages/2-sql/2-authoring/contract-ts/package.jsonpackages/2-sql/3-tooling/emitter/package.jsonpackages/2-sql/4-lanes/query-builder/package.jsonpackages/2-sql/4-lanes/relational-core/package.jsonpackages/2-sql/4-lanes/sql-builder/package.jsonpackages/2-sql/5-runtime/package.jsonpackages/2-sql/9-family/package.jsonpackages/3-extensions/arktype-json/package.jsonpackages/3-extensions/cipherstash/package.jsonpackages/3-extensions/middleware-telemetry/package.jsonpackages/3-extensions/mongo/package.jsonpackages/3-extensions/paradedb/package.jsonpackages/3-extensions/pgvector/package.jsonpackages/3-extensions/postgis/package.jsonpackages/3-extensions/postgres/package.jsonpackages/3-extensions/sql-orm-client/package.jsonpackages/3-extensions/sqlite/package.jsonpackages/3-mongo-target/1-mongo-target/package.jsonpackages/3-mongo-target/2-mongo-adapter/package.jsonpackages/3-mongo-target/3-mongo-driver/package.jsonpackages/3-targets/3-targets/postgres/package.jsonpackages/3-targets/3-targets/sqlite/package.jsonpackages/3-targets/6-adapters/postgres/package.jsonpackages/3-targets/6-adapters/sqlite/package.jsonpackages/3-targets/7-drivers/postgres/package.jsonpackages/3-targets/7-drivers/sqlite/package.jsonscripts/check-publish-deps-pn-pins.test.mjsscripts/check-publish-deps.mjsscripts/check-upgrade-coverage.mjsscripts/check-upgrade-coverage.test.mjsscripts/set-version-utils.test.tsscripts/set-version-utils.tsscripts/set-version.tstest/e2e/framework/package.jsontest/integration/package.jsontest/integration/test/fixtures/cli/cli-e2e-test-app/package.jsontest/integration/test/fixtures/cli/cli-integration-test-app/package.jsontest/integration/test/fixtures/cli/cli-test-app/package.jsontest/utils/package.json
wmadden
changed the title
wmadden
changed the title
wmadden
added a commit
that referenced
this pull request
May 15, 2026
…mplate Updates the create-pr skill to reflect the lessons surfaced while opening PR #508: - Consult `.github/PULL_REQUEST_TEMPLATE.md` first; fold its required headers (`## Linked issue`, `## Testing performed`, `## Checklist`) into the body. - Reorder the required-structure section so `## Reviewer notes` lands near the top (it is the most useful section to a skimming reviewer). - Add multi-flow and system-design variants of `## How it fits together` / `## Behavior changes & evidence` for PRs that ship a system rather than an observable behavior change. - Add a separate Step 5 fresh-eyes self-review pass with concrete checks (grounding first, lead with decision, alternatives at the end, jargon grounded by example, reviewer notes near the top, do not presuppose the spec, no duplicate content with the commits). - Add a Step 6 DCO sign-off check (`git log ... %(trailers...)`) before push, with `git rebase --signoff $BASE_BRANCH` as the retroactive fix while SHA rewrites are still safe. - Extend Don't Do with: do not presuppose the spec (no raw AC-IDs / FR-IDs); do not put alternatives anywhere but the final section; do not push without the DCO check. Aligns `.github/PULL_REQUEST_TEMPLATE.md` PR-title checklist with the skill convention (`TML-NNNN: <title>`) instead of the conflicting conventional-commit form. Real merged-PR titles use both today; the skill is the source of truth and the template now points to it. Refs: TML-2519 Signed-off-by: Will Madden <madden@prisma.io>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/create-pr/SKILL.md:
- Around line 72-77: Normalize the PR reference syntax in
.agents/skills/create-pr/SKILL.md by choosing a single canonical form and
applying it everywhere: replace bare "Refs" with the canonical "Refs:" (with a
colon) under the "## Linked issue" header and in all example/template snippets
so generated PR bodies consistently use "Refs:
[TICKET_ID](https://linear.app/...)" and include any prerequisite/follow-up PR
links in the same "Refs:" line; update the skill's recommended structure and any
sample outputs in the file to match this canonical "Refs:" format.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 9ff973c9-1f54-4882-8f5b-801ca67f67a6
📒 Files selected for processing (2)
.agents/skills/create-pr/SKILL.md.github/PULL_REQUEST_TEMPLATE.md
✅ Files skipped from review due to trivial changes (1)
- .github/PULL_REQUEST_TEMPLATE.md
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
packages/0-shared/extension-upgrade-skill/SKILL.md (1)
66-66:⚠️ Potential issue | 🟠 Major | ⚡ Quick winResolve the
@latestvs<to>conflict for the skill package.Line 66 instructs bumping
@prisma-next/extension-upgrade-skillto<to>, which contradicts Step 0 and can downgrade the runner to stale instructions mid-upgrade.Suggested doc fix
-1. **Bump `@prisma-next/*` deps.** Rewrite every `@prisma-next/*` entry in the extension's `package.json` to the exact `<to>` version (no caret, no tilde, no `workspace:` specifier in a published spec — see the exact-pin rule below). All entries advance to the same version. Cover whichever dep field(s) the extension uses today — `dependencies` and/or `peerDependencies` — and any `optionalDependencies`. Also update the `@prisma-next/extension-upgrade-skill` entry itself to `<to>` (so the skill content matches the target). +1. **Bump `@prisma-next/*` deps.** Rewrite every `@prisma-next/*` entry in the extension's `package.json` to the exact `<to>` version (no caret, no tilde, no `workspace:` specifier in a published spec — see the exact-pin rule below). All entries advance to the same version. Cover whichever dep field(s) the extension uses today — `dependencies` and/or `peerDependencies` — and any `optionalDependencies`. Keep `@prisma-next/extension-upgrade-skill` at `@latest` per Step 0 (do not rewrite it to `<to>`).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/0-shared/extension-upgrade-skill/SKILL.md` at line 66, The doc currently instructs rewriting every `@prisma-next/`* entry to the exact <to> version and also says to update `@prisma-next/extension-upgrade-skill` to <to>, which conflicts with Step 0 and risks downgrading the running skill; update the SKILL.md text in the "Bump `@prisma-next/*` deps." step to explicitly exclude `@prisma-next/extension-upgrade-skill` (or state to keep it at `@latest` as per Step 0) so only extension runtime deps are pinned to <to>, and keep the extension-upgrade-skill package reference at `@latest` to ensure the runner stays on the newest instructions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@packages/0-shared/extension-upgrade-skill/SKILL.md`:
- Line 66: The doc currently instructs rewriting every `@prisma-next/`* entry to
the exact <to> version and also says to update
`@prisma-next/extension-upgrade-skill` to <to>, which conflicts with Step 0 and
risks downgrading the running skill; update the SKILL.md text in the "Bump
`@prisma-next/*` deps." step to explicitly exclude
`@prisma-next/extension-upgrade-skill` (or state to keep it at `@latest` as per Step
0) so only extension runtime deps are pinned to <to>, and keep the
extension-upgrade-skill package reference at `@latest` to ensure the runner stays
on the newest instructions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 2f06c1e7-216b-47a5-a3e2-b85654e80a98
📒 Files selected for processing (7)
.agents/skills/record-upgrade-instructions/SKILL.mdpackages/0-shared/extension-upgrade-skill/README.mdpackages/0-shared/extension-upgrade-skill/SKILL.mdpackages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.mdpackages/0-shared/upgrade-skill/README.mdpackages/0-shared/upgrade-skill/SKILL.mdpackages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.md
✅ Files skipped from review due to trivial changes (6)
- packages/0-shared/upgrade-skill/README.md
- packages/0-shared/extension-upgrade-skill/README.md
- packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md
- packages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.md
- packages/0-shared/upgrade-skill/SKILL.md
- .agents/skills/record-upgrade-instructions/SKILL.md
wmadden
changed the title
wmadden
changed the title
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
scripts/check-upgrade-coverage.mjs (1)
221-245: ⚡ Quick winPrefer a declarative substrate-rule table over duplicated conditionals.
The examples/extensions coverage checks encode rule mapping in hardcoded branches. A small declarative rules array plus one loop is easier to extend and less error-prone.
As per coding guidelines, "Prefer declarative data structures (JSON/config files) over hardcoded conditionals for validation rules, constraints, and configuration logic in dependency-cruiser and build configurations."Refactor sketch
+const COVERAGE_RULES = [ + { substrate: 'examples/', skillPkg: USER_SKILL_PKG }, + { substrate: 'packages/3-extensions/', skillPkg: EXT_SKILL_PKG }, +]; + - const examplesDiff = diffPaths(repoRoot, prev, head, ['examples/']); - if (examplesDiff.length > 0) { - const requiredDir = `${USER_SKILL_PKG}/upgrades/${coverageTransition}`; - if (!existsSync(`${repoRoot}/${requiredDir}`)) { - violations.push({ - rule: 'coverage', - substrate: 'examples/', - requiredDir, - sampleDiffPaths: examplesDiff.slice(0, 5), - }); - } - } - - const extDiff = diffPaths(repoRoot, prev, head, ['packages/3-extensions/']); - if (extDiff.length > 0) { - const requiredDir = `${EXT_SKILL_PKG}/upgrades/${coverageTransition}`; - if (!existsSync(`${repoRoot}/${requiredDir}`)) { - violations.push({ - rule: 'coverage', - substrate: 'packages/3-extensions/', - requiredDir, - sampleDiffPaths: extDiff.slice(0, 5), - }); - } - } + for (const { substrate, skillPkg } of COVERAGE_RULES) { + const touched = diffPaths(repoRoot, prev, head, [substrate]); + if (touched.length === 0) continue; + const requiredDir = `${skillPkg}/upgrades/${coverageTransition}`; + if (!existsSync(`${repoRoot}/${requiredDir}`)) { + violations.push({ + rule: 'coverage', + substrate, + requiredDir, + sampleDiffPaths: touched.slice(0, 5), + }); + } + }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/check-upgrade-coverage.mjs` around lines 221 - 245, Replace the duplicated coverage checks with a declarative rules array and a single loop: create an array of rule objects mapping substrate ('examples/' and 'packages/3-extensions/'), package base (USER_SKILL_PKG and EXT_SKILL_PKG), and any other metadata, then iterate over that array to call diffPaths(repoRoot, prev, head, [substrate]) and check existsSync(`${repoRoot}/${pkgBase}/upgrades/${coverageTransition}`); on missing directory push the same violations entry into violations. Reference diffPaths, examplesDiff/extDiff logic, violations, USER_SKILL_PKG, EXT_SKILL_PKG, coverageTransition and existsSync when replacing the two hardcoded branches.scripts/check-upgrade-coverage.test.mjs (1)
114-205: ⚡ Quick winAdd a regression test where
--headis not the checked-out commit.Current integration tests always use
--head HEAD, so ref-vs-working-tree existence bugs won’t be caught. Add one case that runs against an older--headcommit after changing the working tree/HEAD tip.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/check-upgrade-coverage.test.mjs` around lines 114 - 205, Tests currently only call runScript with '--head', 'HEAD' which misses ref-vs-working-tree bugs; add a regression test that uses runScript(['--prev', prev, '--head', oldHead]) where oldHead is a commit SHA (from git('rev-parse', 'HEAD') saved earlier) that is not the current checked-out tip, and then modify the working tree after that saved commit (e.g., writeRepoFile to change examples/demo/src/main.ts and commitAll to advance HEAD) so runScript is invoked with a --head pointing to the older SHA while the working tree has newer changes; locate similar tests in this file and follow the pattern used in the existing cases (use writePackageJson, writeRepoFile, commitAll, git('rev-parse', 'HEAD'), runScript and assert on result.status/stderr) to assert the script correctly reports missing upgrade-skill/extension-upgrade-skill paths when --head is an older commit.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/check-upgrade-coverage.mjs`:
- Around line 92-96: The function coverageTransitionLabel incorrectly treats
cases where head.minor === prev.minor as steady-state even if head.major !==
prev.major; update coverageTransitionLabel to only call
inFlightTransitionLabel(head) when both head.major === prev.major AND head.minor
=== prev.minor, otherwise call transitionLabel(prev, head). Locate the
coverageTransitionLabel function and modify its conditional to compare both
major and minor on head and prev.
---
Nitpick comments:
In `@scripts/check-upgrade-coverage.mjs`:
- Around line 221-245: Replace the duplicated coverage checks with a declarative
rules array and a single loop: create an array of rule objects mapping substrate
('examples/' and 'packages/3-extensions/'), package base (USER_SKILL_PKG and
EXT_SKILL_PKG), and any other metadata, then iterate over that array to call
diffPaths(repoRoot, prev, head, [substrate]) and check
existsSync(`${repoRoot}/${pkgBase}/upgrades/${coverageTransition}`); on missing
directory push the same violations entry into violations. Reference diffPaths,
examplesDiff/extDiff logic, violations, USER_SKILL_PKG, EXT_SKILL_PKG,
coverageTransition and existsSync when replacing the two hardcoded branches.
In `@scripts/check-upgrade-coverage.test.mjs`:
- Around line 114-205: Tests currently only call runScript with '--head', 'HEAD'
which misses ref-vs-working-tree bugs; add a regression test that uses
runScript(['--prev', prev, '--head', oldHead]) where oldHead is a commit SHA
(from git('rev-parse', 'HEAD') saved earlier) that is not the current
checked-out tip, and then modify the working tree after that saved commit (e.g.,
writeRepoFile to change examples/demo/src/main.ts and commitAll to advance HEAD)
so runScript is invoked with a --head pointing to the older SHA while the
working tree has newer changes; locate similar tests in this file and follow the
pattern used in the existing cases (use writePackageJson, writeRepoFile,
commitAll, git('rev-parse', 'HEAD'), runScript and assert on
result.status/stderr) to assert the script correctly reports missing
upgrade-skill/extension-upgrade-skill paths when --head is an older commit.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 48f775e3-61af-46e7-928f-0b293305c232
⛔ Files ignored due to path filters (2)
projects/prisma-next-agent-skill/plans/upgrade-skill-plan.mdis excluded by!projects/**projects/prisma-next-agent-skill/specs/upgrade-skill.spec.mdis excluded by!projects/**
📒 Files selected for processing (5)
.agents/skills/record-upgrade-instructions/SKILL.mdpackages/0-shared/extension-upgrade-skill/upgrades/0.7-to-0.8/instructions.mdpackages/0-shared/upgrade-skill/upgrades/0.7-to-0.8/instructions.mdscripts/check-upgrade-coverage.mjsscripts/check-upgrade-coverage.test.mjs
✅ Files skipped from review due to trivial changes (3)
- packages/0-shared/extension-upgrade-skill/upgrades/0.7-to-0.8/instructions.md
- packages/0-shared/upgrade-skill/upgrades/0.7-to-0.8/instructions.md
- .agents/skills/record-upgrade-instructions/SKILL.md
Comment on lines
+92
to
+96
| export function coverageTransitionLabel(head, prev) { | ||
| if (head.minor === prev.minor) { | ||
| return inFlightTransitionLabel(head); | ||
| } | ||
| return transitionLabel(prev, head); |
Contributor
There was a problem hiding this comment.
Handle major-version changes in the PR steady-state check.
coverageTransitionLabel treats head.minor === prev.minor as steady-state even when majors differ, which can compute the wrong transition for major jumps.
Suggested fix
export function coverageTransitionLabel(head, prev) {
- if (head.minor === prev.minor) {
+ if (head.major === prev.major && head.minor === prev.minor) {
return inFlightTransitionLabel(head);
}
return transitionLabel(prev, head);
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| export function coverageTransitionLabel(head, prev) { | |
| if (head.minor === prev.minor) { | |
| return inFlightTransitionLabel(head); | |
| } | |
| return transitionLabel(prev, head); | |
| export function coverageTransitionLabel(head, prev) { | |
| if (head.major === prev.major && head.minor === prev.minor) { | |
| return inFlightTransitionLabel(head); | |
| } | |
| return transitionLabel(prev, head); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/check-upgrade-coverage.mjs` around lines 92 - 96, The function
coverageTransitionLabel incorrectly treats cases where head.minor === prev.minor
as steady-state even if head.major !== prev.major; update
coverageTransitionLabel to only call inFlightTransitionLabel(head) when both
head.major === prev.major AND head.minor === prev.minor, otherwise call
transitionLabel(prev, head). Locate the coverageTransitionLabel function and
modify its conditional to compare both major and minor on head and prev.
Contributor
Author
There was a problem hiding this comment.
Valid edge case — when head.major > prev.major (e.g. 0.8 → 1.0), head.minor < prev.minor, so the current comparison is accidentally correct but fragile. Not blocking this PR (which targets 0.x only), deferring to TML-2529: https://linear.app/prisma-company/issue/TML-2529/check-upgrade-coverage-handle-major-version-transitions-in
Contributor
There was a problem hiding this comment.
@wmadden, good point — the accidental correctness relies on minor resetting to 0 after a major bump (semver convention), so the equality check naturally fails for 0.8 → 1.0. It holds today but would silently break if, say, the tooling ever allowed 1.0 → 1.0 after a major bump without resetting the minor. Tracking it in TML-2529 makes sense; happy to defer.
✏️ Learnings added
Learnt from: wmadden
Repo: prisma/prisma-next PR: 508
File: scripts/check-upgrade-coverage.mjs:92-96
Timestamp: 2026-05-15T15:29:38.242Z
Learning: In `scripts/check-upgrade-coverage.mjs`, `coverageTransitionLabel` uses `head.minor === prev.minor` to detect PR steady-state. For major-version bumps (e.g., 0.8 → 1.0), head.minor (0) is always < prev.minor (8), so the check is accidentally correct (falls through to `transitionLabel`), but it is fragile — it relies on semver convention that minor resets to 0 on a major bump. The proper fix (also checking `head.major === prev.major`) is tracked in TML-2529: https://linear.app/prisma-company/issue/TML-2529/check-upgrade-coverage-handle-major-version-transitions-in. The PR targets 0.x only, so this is not blocking.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
Contributor
Author
|
A22a On it. 👍 (removing PR-specific placeholder text from upgrade instruction files) |
Contributor
Author
|
A22a Done in 9eeb4e155. ✅ Updated placeholder upgrade instructions to current-state wording and removed PR-history references. |
Contributor
Author
|
A24a On it. 👍 (clarifying @latest handling for @prisma-next/extension-upgrade-skill) |
Contributor
Author
|
A24a Done in 7481758cc. ✅ Clarified that @prisma-next/extension-upgrade-skill stays at @latest per Step 0 and is excluded from rewrites. |
…TML-2519) Apply the discussion-driven amendments to the upgrade-skill spec and write the project plan that drives the implementation. Spec amendments: - Drop the recipe-freeze rule (FR21). Upgrade instructions are mutable forever; bug fixes are normal PRs and propagate via the cumulative-set property. Replaced by a narrower new-entries-go-in-the-in-flight- directory check (file-add-level). - Drop the separate @prisma-next/extension-pin-check workspace package and the programmatic checkInstalledExtensionPins API. The pin-check CLI (prisma-next-check-pins) ships as a bin of @prisma-next/ extension-upgrade-skill. The user-side pre-flight is SKILL.md prose, not code: agent reads prisma-next.config.ts to find extensions, then per-extension package.json for the pinned PN version. - Hard requirement codified: no cross-package dependency between the two upgrade skills (FR4a). Cross-audience entries are duplicated. - Rename recipe -> upgrade instructions throughout: directories recipes/ -> upgrades/, files recipe.md -> instructions.md, in-repo skill record-recipe -> record-upgrade-instructions, CI gate check:recipe-coverage -> check:upgrade-coverage. - Workspace tier 0-shared/ for the two leaf publish-only skill packages (no deps in either direction; same treatment as 0-config). - In-repo skill at .agents/skills/record-upgrade-instructions/ (NFR4 conformant, first inhabitant of the .agents/ tree). - FR26 publish-time exact-pin mechanic: workspace:<literal-version> everywhere; pnpm publish rewrites to exact pins; set-version.ts extended to rewrite specs in lockstep with the version field; check-publish-deps.mjs extended to verify exact pinning. Plan structure: five milestones (workspace skeletons, pin-check CLI, in-repo skill, CI gate, publish-time exact-pin mechanic). Each milestone names its validation gate. All work ships in a single PR. Signed-off-by: Will Madden <madden@prisma.io>
Introduces the new `packages/0-shared/` tier (alongside `0-config`) and populates it with the two leaf publish-only workspace packages that will be distributed via npm as agent skills: - `@prisma-next/upgrade-skill` — for users of Prisma Next. Its `SKILL.md` carries the consumer-facing flow: Step 0 ensure-latest, the FR27 pre-flight that reads `prisma-next.config.ts` and each installed extension's pinned `@prisma-next/*` version before refusing to upgrade past the lowest pin, role detection, version detection, the per-minor transition chain, and the bump → install → instructions → validate → commit per-step loop. - `@prisma-next/extension-upgrade-skill` — for extension authors. Same shape minus the user-side pre-flight, plus a `pnpm exec prisma-next-check-pins` sanity check after each bump step. Declares a `bin` for `prisma-next-check-pins`; the bin file is a stub for this milestone (real CLI lands next). Both packages ship a placeholder `upgrades/0.6-to-0.7/instructions.md` with `changes: []` so the publish gate has a real directory to verify against; the first real entries land via PR #502's rebase. Neither package declares the other as any kind of dependency (satisfies the hard requirement that the two skills have no cross-package dep). The `0-shared` tier mirrors `0-config`'s precedent: not registered in `architecture.config.json` (and therefore not enumerated by `dependency-cruiser.config.mjs` either) — the packages have no runtime dependencies and are not imported by any other workspace package, so they need no module-group entry. `pnpm-workspace.yaml` already covers them via `packages/**`; no additional wiring is needed. m1 of the upgrade-skill mechanism (TML-2519). The placeholder `SKILL.md` bodies, README content, and stub bin are the substrate the next milestones will fill in. Signed-off-by: Will Madden <madden@prisma.io>
Replaces the m1 stub with the real CLI that enforces the exact-pin
rule for Prisma Next extensions:
- Every `@prisma-next/*` entry across `dependencies`,
`peerDependencies`, and `optionalDependencies` must be a single
exact-version string matching `^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$`
(pre-release suffixes permitted; operators, ranges, `workspace:`
specifiers, and wildcards forbidden).
- All `@prisma-next/*` entries must resolve to the same version.
On success, exits 0 with no output. On failure, prints one line per
offending entry naming `<field>.<name> = <observed-spec> — <rule>`,
plus a summary header naming the offending package and the violation
count, then exits 1.
Plain ESM `.mjs`, no compile step. Imports from `node:fs`,
`node:path`, `node:process` per the spec's NFR9 (no runtime deps
beyond node built-ins, deliberately keeping this package's
zero-dependency / zero-build property intact).
Adds `node --test`-based unit tests at `test/check-pins.test.mjs`
matching the workspace's `.mjs` test precedent
(`scripts/lint-workflow-triggers.test.mjs`). Tests cover both pass
cases (single-version exact pins, pre-release suffixes, no PN deps,
mixed non-PN deps, all three dep fields) and rejection cases
(operator forms `^`, `~`, `>=`, `0.7.x`, `*`, `x`; every workspace
specifier form `workspace:*`, `workspace:^`, `workspace:~`,
`workspace:0.7.0`; mismatched versions across two entries;
peerDependencies-only violation while dependencies is clean; error
output shape carries field+name+spec+rule per violation).
`scripts.test` added to the package's `package.json` as
`node --test test/*.test.mjs`. The package still ships no
`devDependencies` (AC23 stays clean — neither skill package depends
on the other).
Decisions worth recording:
- The CLI uses `node:path` per the orchestrator's explicit
resume-prompt instruction. The workspace's `use-pathe-for-paths`
cursor rule prefers `pathe`, but `pathe` would require declaring a
dependency, which contradicts the package's zero-dependency
property. The orchestrator's explicit instruction wins for this
package; surface for review.
- The test file uses `node:path` for the same reason (a `pathe`
devDependency would be the only dep this package declares).
- Single-version rule reports every entry as a violation when the
pin set diverges, rather than picking one as the "canonical" pin
and flagging the rest — there is no canonical choice, the user
has to decide, and naming every divergent entry makes the fix
obvious.
m2 of the upgrade-skill mechanism (TML-2519).
Signed-off-by: Will Madden <madden@prisma.io>
Fires on PRs in this repo that make a breaking change to Prisma Next, instructing the change-making agent to author the matching upgrade-instructions entry in `@prisma-next/upgrade-skill` and/or `@prisma-next/extension-upgrade-skill` before merging. Detection signals are mechanical and tied to one destination per substrate: - diff in `examples/` → user-skill entry (`packages/0-shared/upgrade-skill/upgrades/<from>-to-<to>/`). - diff in `packages/3-extensions/` → extension-skill entry (`packages/0-shared/extension-upgrade-skill/upgrades/<from>-to-<to>/`). - both → both packages, duplicated entries and colocated scripts. The authoring workflow is seven steps: determine in-flight minor from `package.json` on the PR branch (no `npm view`); identify touched substrates; find-or-create the directory in each destination; write the entry into `instructions.md`'s `changes[]` array; author any colocated scripts; validate by execution against the matching substrate; commit on the PR branch. Validation by execution is the quality bar — for user-skill entries, revert `examples/` to pre-PR, run the entry, verify `pnpm test:examples` green and the substrate diff matches the PR-branch state. For extension-skill entries, same flow with `packages/3-extensions/` and `pnpm test --filter='./packages/3-extensions/*'`. The reviewer never has to vouch for cases they did not run. Body also carries: PR commit shape (entry directory + post- instructions substrate state + PR-description naming); the rebase scenario (a topic branch carried across a version-bump PR re-runs step 1 against the new in-flight minor; existing adds in old transition directories may stay because the new-entries CI check only blocks adds in stale directories); and the cross-audience duplication policy (copy scripts across both packages, do not symlink, do not introduce a cross-dep). A worked example walks through the PR that refactors `@prisma-next/migration-tools` types and breaks both the cipherstash extension and the cipherstash-integration example, showing how the agent routes the entry to both skill packages. Authored to be terse and operational (~310 lines). No transient project IDs in the body. Style mirrors `.agents/skills/publish- npm-version/SKILL.md`. m3 of the upgrade-skill mechanism (TML-2519). Signed-off-by: Will Madden <madden@prisma.io>
Adds a workspace-script gate that enforces two related invariants on every PR and every release: 1. Coverage. A diff in `examples/` (excluding mechanically-regenerated contract artefacts) requires a matching `upgrades/<prev>-to-<head>/` directory in `packages/0-shared/upgrade-skill/`. A diff in `packages/3-extensions/` requires the symmetric directory in `packages/0-shared/extension-upgrade-skill/`. Same-minor bumps (patch releases) skip the coverage check. 2. New-entries-in-in-flight-directory. File adds under either skill package's `upgrades/` tree must land in the in-flight transition directory `(headMinor - 1)-to-headMinor` keyed off the head ref's `package.json`. Modifications and removals are unrestricted, so bug fixes to old upgrade-instructions land via normal PRs. The script is plain ESM `.mjs` using `node:` built-ins + git; no runtime dependencies. It supports `--mode pr` (defaults `--prev` to `origin/main`) and `--mode publish` (defaults `--prev` to the most recent `v[0-9]*` tag). Both modes accept explicit `--head` / `--prev` overrides; `--json` emits a structured result envelope. Wired into: - `pnpm check:upgrade-coverage` (root `package.json`). - `pnpm test:scripts` (the test file extends the existing `node --test` list). - `.github/workflows/ci.yml` (lint job, after `pnpm test:scripts`). The lint job gains `fetch-depth: 0` plus an explicit `git fetch origin main` so `git diff origin/main..HEAD` resolves. - `.github/workflows/publish.yml` (between `check:publish-deps` and the actual `pnpm -r publish`). Tests cover all the gate-relevant acceptance criteria via synthetic git fixtures in ephemeral tmpdirs: same-minor skipping, missing user and extension entries, both-substrates-required, generated-paths exclusion, publish-mode tag resolution, stale-add rejection, in-flight-add acceptance, modification carve-out, and the "in-flight minor reads from package.json on head" invariant. Signed-off-by: Will Madden <madden@prisma.io>
….7.0 Rewrites every `@prisma-next/*` dependency, peerDependency, devDependency, and optionalDependency entry across `packages/`, `examples/`, and `test/` from `workspace:*` to `workspace:0.7.0` (literal-version form). pnpm rewrites `workspace:<X.Y.Z>` to exactly `X.Y.Z` at publish time, which is the mechanism that gives every published `@prisma-next/*` package an exact-version pin on its `@prisma-next/*` siblings — the `prisma-next-check-pins` invariant, enforced for in-flight workspace specs in the next two commits. Workspace-internal behaviour is unchanged: `workspace:0.7.0` and `workspace:*` both resolve to the local workspace package, so dev installs and the package graph see exactly the same thing as before. `pnpm install` updates `pnpm-lock.yaml` only in `specifier:` fields (workspace:* → workspace:0.7.0); resolved versions and integrity hashes do not move. Migration was applied via a one-shot JSON-aware rewrite (kept under `wip/` and not committed); the durable per-publish version of the same operation is folded into `scripts/set-version.ts` in the next commit. Two `@prisma-next/tsconfig` README code samples still read `workspace:*`. They are markdown samples documenting the legacy form in the package READMEs themselves and are intentionally not rewritten. The two new `0-shared` skill packages have no `@prisma-next/*` dependencies and are unaffected. Signed-off-by: Will Madden <madden@prisma.io>
`scripts/set-version.ts` is invoked by `bump-minor.ts` and by `publish.yml` to stamp every workspace `package.json` with the release version. Until now it rewrote only the `version` field; this extension also rewrites every `@prisma-next/*` entry whose spec begins with `workspace:` to `workspace:<new-version>` across all four dep fields (dependencies, peerDependencies, devDependencies, optionalDependencies). That keeps the workspace dep specs in lockstep with the published version on every bump and every release, so the next release run inherits the exact-pin guarantee from the previous commit's migration: pnpm rewrites `workspace:<X.Y.Z>` to exactly `X.Y.Z` at publish time, giving every published `@prisma-next/*` package an exact-version pin on its `@prisma-next/*` siblings. The pure rewrite logic lives in `scripts/set-version-utils.ts` so it can be unit-tested without spawning a synthetic pnpm workspace fixture (matches the `determine-version-utils.ts` precedent). The new tests at `scripts/set-version-utils.test.ts` (wired into `pnpm test:scripts`) cover: A) no-PN-dep packages are untouched, B) mixed `workspace:*` / `workspace:<old>` specs are rewritten in lockstep, C) re-running with the same version is a no-op (idempotent), the rewrite spans every dep field, non-workspace `@prisma-next/*` pins (e.g. `^0.7.0` from a published install) are deliberately left alone, non-`@prisma-next/*` workspace deps are left alone, and sparse manifests (no dep-field objects) are tolerated. Signed-off-by: Will Madden <madden@prisma.io>
Extends `scripts/check-publish-deps.mjs` with a second rule on top of the existing workspace:/catalog: leak check: every `@prisma-next/*` entry in `dependencies`, `peerDependencies`, or `optionalDependencies` of a published tarball must be a single exact version `X.Y.Z` (an optional semver pre-release suffix like `-dev.5` or `-rc.2` is permitted). Carets, tildes, ranges, wildcards, and disjunctions all fail. `devDependencies` is excluded — those do not ship to consumers, so an imprecise spec there cannot break the consumer's type-identity invariant the pin check protects. Combined with the previous `workspace:<X.Y.Z>` source-manifest migration, this is the mechanism that gives every published `@prisma-next/*` package an exact pin on its `@prisma-next/*` siblings: pnpm rewrites `workspace:<X.Y.Z>` to exactly `X.Y.Z` at publish time, and this gate refuses to ship any tarball that deviates from that shape — whether by accident (a hand-edited `^0.7.0` slipped in) or by tooling regression (a future change to the version-stamp pipeline that produces a range instead of a pin). Output formatting: violations from both rules are surfaced under each offending package, prefixed `[leak]` or `[pin]` so it's obvious which discipline caught it. Specs already flagged as `workspace:` / `catalog:` leaks are intentionally not double-reported by the pin rule. Tests at `scripts/check-publish-deps-pn-pins.test.mjs` (wired into `pnpm test:scripts`) cover: exact versions and pre-release suffixes pass; every common imprecise form fails (`^`, `~`, `>=`, `>`, `x`, `*`, `||`, ranges); the pin rule covers peer/optional in addition to dependencies; devDependencies are skipped; non-`@prisma-next/*` deps are skipped; cross-field violations (clean deps, range in peerDeps) are caught; workspace:/catalog: specs are deferred to the leak rule rather than double-reported. Signed-off-by: Will Madden <madden@prisma.io>
…mplate Updates the create-pr skill to reflect the lessons surfaced while opening PR #508: - Consult `.github/PULL_REQUEST_TEMPLATE.md` first; fold its required headers (`## Linked issue`, `## Testing performed`, `## Checklist`) into the body. - Reorder the required-structure section so `## Reviewer notes` lands near the top (it is the most useful section to a skimming reviewer). - Add multi-flow and system-design variants of `## How it fits together` / `## Behavior changes & evidence` for PRs that ship a system rather than an observable behavior change. - Add a separate Step 5 fresh-eyes self-review pass with concrete checks (grounding first, lead with decision, alternatives at the end, jargon grounded by example, reviewer notes near the top, do not presuppose the spec, no duplicate content with the commits). - Add a Step 6 DCO sign-off check (`git log ... %(trailers...)`) before push, with `git rebase --signoff $BASE_BRANCH` as the retroactive fix while SHA rewrites are still safe. - Extend Don't Do with: do not presuppose the spec (no raw AC-IDs / FR-IDs); do not put alternatives anywhere but the final section; do not push without the DCO check. Aligns `.github/PULL_REQUEST_TEMPLATE.md` PR-title checklist with the skill convention (`TML-NNNN: <title>`) instead of the conflicting conventional-commit form. Real merged-PR titles use both today; the skill is the source of truth and the template now points to it. Refs: TML-2519 Signed-off-by: Will Madden <madden@prisma.io>
Reflow the seven markdown files added on this branch so each prose paragraph is a single source line, leaving rendering to the editor / GitHub. Hard wraps at ~70 chars made diffs noisy and reflows awkward, per `markdown-no-artificial-line-wraps`. Files reflowed: - packages/0-shared/upgrade-skill/README.md - packages/0-shared/upgrade-skill/SKILL.md - packages/0-shared/upgrade-skill/upgrades/0.6-to-0.7/instructions.md - packages/0-shared/extension-upgrade-skill/README.md - packages/0-shared/extension-upgrade-skill/SKILL.md - packages/0-shared/extension-upgrade-skill/upgrades/0.6-to-0.7/instructions.md - .agents/skills/record-upgrade-instructions/SKILL.md The execution plan (projects/prisma-next-agent-skill/plans/upgrade-skill-plan.md) was already in soft-wrap form; left untouched. Headings, ordered/ unordered lists, frontmatter blocks, code fences, and the detection-signals table are preserved verbatim. Refs: TML-2519 Signed-off-by: Will Madden <madden@prisma.io>
The package.json `version` field on a given ref is the *currently published* version, not the next in-flight target. The in-flight transition is therefore `<head.minor>-to-<head.minor + 1>`, and the in-flight directory in each skill package follows the same shape. Cascade across the script + tests + placeholder artefacts + the in-repo authoring skill prose: - check-upgrade-coverage.mjs: `inFlightTransitionLabel(head)` now returns head→head+1 (function of head only). `coverageTransitionLabel(head, prev)` returns the in-flight transition in PR-mode steady-state and `prev→head` in publish mode. The new-entries rule accepts either label so files added across a publish-mode bump can describe either the release shipping or the next in-flight release. Drop the GENERATED_BASENAMES exclusion: format changes to emitted artefacts (contract.json / contract.d.ts) are themselves upgrade instructions; consumer-invisible regenerations are recorded with `changes: []`. Drop the patch-only carve-out for the same reason. - check-upgrade-coverage.test.mjs: rewrite around the new semantic. Add coverage for PR-mode steady-state, publish-mode allow-both, and the no-exclusion-for-generated-artefacts rule. - Rename placeholder directories `upgrades/0.6-to-0.7/` → `upgrades/0.7-to-0.8/` in both 0-shared skill packages, and update their frontmatter `from`/`to` accordingly. Currently published is 0.7.0, so the in-flight transition is 0.7→0.8. - record-upgrade-instructions SKILL.md: rewrite the authoring-workflow step that derives the directory name, the rebase scenario, the worked example, and the JSON-artefact carve-out paragraph (now: any substrate diff requires an entry). Signed-off-by: Will Madden <madden@prisma.io>
Update the project spec and plan to match the corrected in-flight transition semantic (head-to-head+1, derived from the currently-published version in package.json) and the dropped carve-outs (no patch-skip, no generated-paths exclusion). Concrete updates: section "The in-flight transition — derived from package.json"; FR10 step 1 + rebase scenario; FR13 (publish gate; coverage transition is now mode-aware: PR-mode steady-state collapses to in-flight, publish mode is prev→head); FR21 (new-entries rule accepts coverage OR in-flight); NFR4 (patch policy without script-level skip); ACs 1, 3, 4, 5, 11, 15-18, 28; the "Decisions resolved during refinement" notes for placeholder + first-non-placeholder sequencing; placeholder paths in m1 plan tasks. Signed-off-by: Will Madden <madden@prisma.io>
Regenerate pnpm-lock.yaml after workspace literal-version specifier changes so frozen installs remain reproducible. Signed-off-by: Will Madden <madden@prisma.io>
Replace placeholder text with current-state wording so published upgrade instruction files do not depend on PR history. Signed-off-by: Will Madden <madden@prisma.io>
Clarify the dependency bump step so @prisma-next/extension-upgrade-skill stays at @latest per Step 0 instead of being rewritten to <to>. Signed-off-by: Will Madden <madden@prisma.io>
Rebase merged in new @prisma-next/* workspace deps (e.g. @prisma-next/middleware-cache, replacing @prisma-next/middleware-telemetry on this branch). Re-applying the workspace-pin migration on the merged source bumps every workspace specifier in the lockfile from `workspace:*` to `workspace:0.7.0` to match the now-pinned package.json files. Signed-off-by: Will Madden <madden@prisma.io>
wmadden
force-pushed
the
tml-2519-upgrade-skill-mechanism-user-extension-pin-check
branch
from
a325319 to
194f218
Compare
@prisma-next/extension-upgrade-skill
@prisma-next/upgrade-skill
@prisma-next/mongo-runtime
@prisma-next/family-mongo
@prisma-next/sql-runtime
@prisma-next/family-sql
@prisma-next/extension-arktype-json
@prisma-next/extension-cipherstash
@prisma-next/middleware-cache
@prisma-next/mongo
@prisma-next/extension-paradedb
@prisma-next/extension-pgvector
@prisma-next/extension-postgis
@prisma-next/postgres
@prisma-next/sql-orm-client
@prisma-next/sqlite
@prisma-next/target-mongo
@prisma-next/adapter-mongo
@prisma-next/driver-mongo
@prisma-next/contract
@prisma-next/utils
@prisma-next/config
@prisma-next/errors
@prisma-next/framework-components
@prisma-next/operations
@prisma-next/ts-render
@prisma-next/contract-authoring
@prisma-next/ids
@prisma-next/psl-parser
@prisma-next/psl-printer
@prisma-next/cli
@prisma-next/emitter
@prisma-next/migration-tools
prisma-next
@prisma-next/vite-plugin-contract-emit
@prisma-next/mongo-codec
@prisma-next/mongo-contract
@prisma-next/mongo-value
@prisma-next/mongo-contract-psl
@prisma-next/mongo-contract-ts
@prisma-next/mongo-emitter
@prisma-next/mongo-schema-ir
@prisma-next/mongo-query-ast
@prisma-next/mongo-orm
@prisma-next/mongo-query-builder
@prisma-next/mongo-lowering
@prisma-next/mongo-wire
@prisma-next/sql-contract
@prisma-next/sql-errors
@prisma-next/sql-operations
@prisma-next/sql-schema-ir
@prisma-next/sql-contract-psl
@prisma-next/sql-contract-ts
@prisma-next/sql-contract-emitter
@prisma-next/sql-lane-query-builder
@prisma-next/sql-relational-core
@prisma-next/sql-builder
@prisma-next/target-postgres
@prisma-next/target-sqlite
@prisma-next/adapter-postgres
@prisma-next/adapter-sqlite
@prisma-next/driver-postgres
@prisma-next/driver-sqlite
commit: |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/0-shared/extension-upgrade-skill/SKILL.md`:
- Line 66: The instruction at Step 1 is ambiguous about whether to rewrite
`@prisma-next/*` deps to an exact `<to>` or retain `workspace:` for in-repo
extensions; update the SKILL.md text so that the `Bump `@prisma-next/`* deps.`
step explicitly says: for in-tree (monorepo) extensions keep the
`workspace:<to>` specifier (e.g., `workspace:0.7.0`) to match repository
conventions, while for external extensions write the exact `<to>` version (no
caret/tilde); also retain the special-case note that
`@prisma-next/extension-upgrade-skill` should stay at `@latest` per Step 0.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 2d927ac3-d997-4b99-8c8f-ffc1fa3643c0
⛔ Files ignored due to path filters (3)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlprojects/prisma-next-agent-skill/plans/upgrade-skill-plan.mdis excluded by!projects/**projects/prisma-next-agent-skill/specs/upgrade-skill.spec.mdis excluded by!projects/**
📒 Files selected for processing (102)
.agents/skills/create-pr/SKILL.md.agents/skills/record-upgrade-instructions/SKILL.md.github/PULL_REQUEST_TEMPLATE.md.github/workflows/ci.yml.github/workflows/publish.ymlexamples/cipherstash-integration/package.jsonexamples/mongo-blog-leaderboard/package.jsonexamples/mongo-demo/package.jsonexamples/multi-extension-monorepo/package.jsonexamples/paradedb-demo/package.jsonexamples/prisma-next-cloudflare-worker/package.jsonexamples/prisma-next-demo-sqlite/package.jsonexamples/prisma-next-demo/package.jsonexamples/prisma-next-postgis-demo/package.jsonexamples/react-router-demo/package.jsonexamples/retail-store/package.jsonpackage.jsonpackages/0-config/tsdown/package.jsonpackages/0-shared/extension-upgrade-skill/README.mdpackages/0-shared/extension-upgrade-skill/SKILL.mdpackages/0-shared/extension-upgrade-skill/bin/prisma-next-check-pins.mjspackages/0-shared/extension-upgrade-skill/package.jsonpackages/0-shared/extension-upgrade-skill/test/check-pins.test.mjspackages/0-shared/extension-upgrade-skill/upgrades/0.7-to-0.8/instructions.mdpackages/0-shared/upgrade-skill/README.mdpackages/0-shared/upgrade-skill/SKILL.mdpackages/0-shared/upgrade-skill/package.jsonpackages/0-shared/upgrade-skill/upgrades/0.7-to-0.8/instructions.mdpackages/1-framework/0-foundation/contract/package.jsonpackages/1-framework/0-foundation/utils/package.jsonpackages/1-framework/1-core/config/package.jsonpackages/1-framework/1-core/errors/package.jsonpackages/1-framework/1-core/framework-components/package.jsonpackages/1-framework/1-core/operations/package.jsonpackages/1-framework/1-core/ts-render/package.jsonpackages/1-framework/2-authoring/contract/package.jsonpackages/1-framework/2-authoring/ids/package.jsonpackages/1-framework/2-authoring/psl-parser/package.jsonpackages/1-framework/2-authoring/psl-printer/package.jsonpackages/1-framework/3-tooling/cli/package.jsonpackages/1-framework/3-tooling/emitter/package.jsonpackages/1-framework/3-tooling/migration/package.jsonpackages/1-framework/3-tooling/prisma-next/package.jsonpackages/1-framework/3-tooling/vite-plugin-contract-emit/package.jsonpackages/2-mongo-family/1-foundation/mongo-codec/package.jsonpackages/2-mongo-family/1-foundation/mongo-contract/package.jsonpackages/2-mongo-family/1-foundation/mongo-value/package.jsonpackages/2-mongo-family/2-authoring/contract-psl/package.jsonpackages/2-mongo-family/2-authoring/contract-ts/package.jsonpackages/2-mongo-family/3-tooling/emitter/package.jsonpackages/2-mongo-family/3-tooling/mongo-schema-ir/package.jsonpackages/2-mongo-family/4-query/query-ast/package.jsonpackages/2-mongo-family/5-query-builders/orm/package.jsonpackages/2-mongo-family/5-query-builders/query-builder/package.jsonpackages/2-mongo-family/6-transport/mongo-lowering/package.jsonpackages/2-mongo-family/6-transport/mongo-wire/package.jsonpackages/2-mongo-family/7-runtime/package.jsonpackages/2-mongo-family/9-family/package.jsonpackages/2-sql/1-core/contract/package.jsonpackages/2-sql/1-core/errors/package.jsonpackages/2-sql/1-core/operations/package.jsonpackages/2-sql/1-core/schema-ir/package.jsonpackages/2-sql/2-authoring/contract-psl/package.jsonpackages/2-sql/2-authoring/contract-ts/package.jsonpackages/2-sql/3-tooling/emitter/package.jsonpackages/2-sql/4-lanes/query-builder/package.jsonpackages/2-sql/4-lanes/relational-core/package.jsonpackages/2-sql/4-lanes/sql-builder/package.jsonpackages/2-sql/5-runtime/package.jsonpackages/2-sql/9-family/package.jsonpackages/3-extensions/arktype-json/package.jsonpackages/3-extensions/cipherstash/package.jsonpackages/3-extensions/middleware-cache/package.jsonpackages/3-extensions/mongo/package.jsonpackages/3-extensions/paradedb/package.jsonpackages/3-extensions/pgvector/package.jsonpackages/3-extensions/postgis/package.jsonpackages/3-extensions/postgres/package.jsonpackages/3-extensions/sql-orm-client/package.jsonpackages/3-extensions/sqlite/package.jsonpackages/3-mongo-target/1-mongo-target/package.jsonpackages/3-mongo-target/2-mongo-adapter/package.jsonpackages/3-mongo-target/3-mongo-driver/package.jsonpackages/3-targets/3-targets/postgres/package.jsonpackages/3-targets/3-targets/sqlite/package.jsonpackages/3-targets/6-adapters/postgres/package.jsonpackages/3-targets/6-adapters/sqlite/package.jsonpackages/3-targets/7-drivers/postgres/package.jsonpackages/3-targets/7-drivers/sqlite/package.jsonscripts/check-publish-deps-pn-pins.test.mjsscripts/check-publish-deps.mjsscripts/check-upgrade-coverage.mjsscripts/check-upgrade-coverage.test.mjsscripts/set-version-utils.test.tsscripts/set-version-utils.tsscripts/set-version.tstest/e2e/framework/package.jsontest/integration/package.jsontest/integration/test/fixtures/cli/cli-e2e-test-app/package.jsontest/integration/test/fixtures/cli/cli-integration-test-app/package.jsontest/integration/test/fixtures/cli/cli-test-app/package.jsontest/utils/package.json
✅ Files skipped from review due to trivial changes (47)
- packages/0-shared/extension-upgrade-skill/upgrades/0.7-to-0.8/instructions.md
- packages/2-sql/1-core/errors/package.json
- packages/2-mongo-family/1-foundation/mongo-codec/package.json
- packages/2-mongo-family/1-foundation/mongo-value/package.json
- packages/2-sql/2-authoring/contract-psl/package.json
- packages/2-mongo-family/3-tooling/mongo-schema-ir/package.json
- packages/2-sql/4-lanes/query-builder/package.json
- packages/3-targets/6-adapters/postgres/package.json
- packages/1-framework/0-foundation/contract/package.json
- packages/2-mongo-family/1-foundation/mongo-contract/package.json
- packages/1-framework/2-authoring/contract/package.json
- packages/3-extensions/sql-orm-client/package.json
- packages/0-shared/upgrade-skill/package.json
- packages/1-framework/1-core/ts-render/package.json
- packages/3-extensions/sqlite/package.json
- packages/2-mongo-family/6-transport/mongo-lowering/package.json
- packages/2-sql/1-core/operations/package.json
- test/integration/test/fixtures/cli/cli-e2e-test-app/package.json
- packages/1-framework/0-foundation/utils/package.json
- .github/PULL_REQUEST_TEMPLATE.md
- packages/3-mongo-target/1-mongo-target/package.json
- packages/2-sql/4-lanes/relational-core/package.json
- packages/1-framework/2-authoring/ids/package.json
- packages/2-sql/4-lanes/sql-builder/package.json
- examples/prisma-next-demo-sqlite/package.json
- packages/1-framework/1-core/errors/package.json
- packages/3-mongo-target/3-mongo-driver/package.json
- packages/1-framework/3-tooling/migration/package.json
- packages/1-framework/3-tooling/cli/package.json
- packages/3-extensions/cipherstash/package.json
- packages/1-framework/3-tooling/prisma-next/package.json
- packages/2-mongo-family/4-query/query-ast/package.json
- test/integration/test/fixtures/cli/cli-integration-test-app/package.json
- packages/0-shared/upgrade-skill/README.md
- packages/2-mongo-family/5-query-builders/orm/package.json
- packages/1-framework/2-authoring/psl-printer/package.json
- packages/2-mongo-family/3-tooling/emitter/package.json
- packages/0-shared/upgrade-skill/upgrades/0.7-to-0.8/instructions.md
- packages/2-sql/1-core/schema-ir/package.json
- examples/multi-extension-monorepo/package.json
- packages/2-mongo-family/9-family/package.json
- packages/0-shared/extension-upgrade-skill/README.md
- test/integration/test/fixtures/cli/cli-test-app/package.json
- packages/3-targets/7-drivers/sqlite/package.json
- packages/2-sql/5-runtime/package.json
- scripts/check-upgrade-coverage.mjs
- .agents/skills/record-upgrade-instructions/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (52)
- packages/2-sql/9-family/package.json
- packages/3-extensions/postgres/package.json
- packages/2-mongo-family/7-runtime/package.json
- examples/mongo-blog-leaderboard/package.json
- packages/2-mongo-family/5-query-builders/query-builder/package.json
- packages/0-config/tsdown/package.json
- packages/2-mongo-family/2-authoring/contract-ts/package.json
- examples/prisma-next-postgis-demo/package.json
- examples/paradedb-demo/package.json
- scripts/set-version.ts
- test/utils/package.json
- packages/2-sql/1-core/contract/package.json
- packages/1-framework/1-core/config/package.json
- packages/2-sql/2-authoring/contract-ts/package.json
- .github/workflows/publish.yml
- packages/1-framework/2-authoring/psl-parser/package.json
- packages/3-mongo-target/2-mongo-adapter/package.json
- scripts/set-version-utils.test.ts
- scripts/check-publish-deps-pn-pins.test.mjs
- packages/0-shared/extension-upgrade-skill/bin/prisma-next-check-pins.mjs
- packages/3-extensions/paradedb/package.json
- package.json
- examples/react-router-demo/package.json
- packages/3-targets/7-drivers/postgres/package.json
- packages/3-extensions/pgvector/package.json
- packages/1-framework/1-core/operations/package.json
- .github/workflows/ci.yml
- packages/0-shared/extension-upgrade-skill/package.json
- examples/prisma-next-cloudflare-worker/package.json
- packages/1-framework/3-tooling/vite-plugin-contract-emit/package.json
- packages/2-mongo-family/2-authoring/contract-psl/package.json
- packages/2-mongo-family/6-transport/mongo-wire/package.json
- packages/3-targets/3-targets/sqlite/package.json
- packages/1-framework/3-tooling/emitter/package.json
- packages/3-extensions/arktype-json/package.json
- packages/0-shared/extension-upgrade-skill/test/check-pins.test.mjs
- scripts/check-publish-deps.mjs
- packages/1-framework/1-core/framework-components/package.json
- scripts/set-version-utils.ts
- packages/3-targets/6-adapters/sqlite/package.json
- examples/prisma-next-demo/package.json
- examples/cipherstash-integration/package.json
- test/e2e/framework/package.json
- packages/3-extensions/mongo/package.json
- examples/mongo-demo/package.json
- examples/retail-store/package.json
- packages/0-shared/upgrade-skill/SKILL.md
- packages/3-targets/3-targets/postgres/package.json
- test/integration/package.json
- packages/3-extensions/postgis/package.json
- packages/2-sql/3-tooling/emitter/package.json
- scripts/check-upgrade-coverage.test.mjs
Resolves a CodeRabbit ambiguity in the per-step flow: the published skill targets external extension authors (their own repo, @prisma-next/* from npm, exact-pin form). In-tree extensions inside the prisma-next monorepo don't run this skill — they're bumped via pnpm bump-minor / set-version.ts. Note that up front and tighten the bump-step example. Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 15, 2026
…mplate Updates the create-pr skill to reflect the lessons surfaced while opening PR #508: - Consult `.github/PULL_REQUEST_TEMPLATE.md` first; fold its required headers (`## Linked issue`, `## Testing performed`, `## Checklist`) into the body. - Reorder the required-structure section so `## Reviewer notes` lands near the top (it is the most useful section to a skimming reviewer). - Add multi-flow and system-design variants of `## How it fits together` / `## Behavior changes & evidence` for PRs that ship a system rather than an observable behavior change. - Add a separate Step 5 fresh-eyes self-review pass with concrete checks (grounding first, lead with decision, alternatives at the end, jargon grounded by example, reviewer notes near the top, do not presuppose the spec, no duplicate content with the commits). - Add a Step 6 DCO sign-off check (`git log ... %(trailers...)`) before push, with `git rebase --signoff $BASE_BRANCH` as the retroactive fix while SHA rewrites are still safe. - Extend Don't Do with: do not presuppose the spec (no raw AC-IDs / FR-IDs); do not put alternatives anywhere but the final section; do not push without the DCO check. Aligns `.github/PULL_REQUEST_TEMPLATE.md` PR-title checklist with the skill convention (`TML-NNNN: <title>`) instead of the conflicting conventional-commit form. Real merged-PR titles use both today; the skill is the source of truth and the template now points to it. Refs: TML-2519 Signed-off-by: Will Madden <madden@prisma.io>
wmadden
deleted the
tml-2519-upgrade-skill-mechanism-user-extension-pin-check
branch
This was referenced May 17, 2026
Merged
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linked issue
Refs TML-2519. Builds on the package.json-as-source-of-truth refactor in TML-2518. The first non-trivial upgrade-instruction entries land in PR #502, rebased on top of this PR.
At a glance
We're publishing two new agent skills to npm. A user upgrading Prisma Next runs:
npx skills add @prisma-next/upgrade-skill@latest # then asks their agent: "upgrade Prisma Next to 0.8"The agent reads the skill's
SKILL.md, detects the user's current version frompnpm-lock.yaml, builds a chain of one-minor steps (0.6 → 0.7 → 0.8), and for each step loads the matchingupgrades/<from>-to-<to>/instructions.mdfrom the skill, applies it, runs the project's typecheck + tests, and commits.An entry's on-disk shape (this is what PR #502 will land — this PR ships
changes: []placeholders so the publish gate has something real to verify against). Currently published is0.7.0, so the in-flight transition is0.7 → 0.8:Extension authors install a parallel skill (
@prisma-next/extension-upgrade-skill) that walks the same flow against the SPI surface and additionally enforces an exact-pin rule on every@prisma-next/*dep. The pin-check is a singlebinshipped from the same skill:The decision
We're treating each
(from, to)Prisma Next upgrade as a versioned, npm-published, agent-readable artefact instead of a one-off PR-description recipe or a wiki page. Motivation: the framework is moving fast, every breaking PR risks silently desynchronising users and extension authors, and the pre-mechanism workaround was per-PR manual outreach (Slack, issues, migration notes) that doesn't scale and isn't auditable.The deliverables:
@prisma-next/upgrade-skill— for app authors. Bumps@prisma-next/*deps, walksinstructions.mdper minor step, validates with the project's own tests, commits one minor at a time.@prisma-next/extension-upgrade-skill— for extension authors. Same flow against the SPI surface; additionally shipsprisma-next-check-pinsas abinfor use in extension CI.record-upgrade-instructionsskill (.agents/skills/record-upgrade-instructions/SKILL.md) — guides a change-author writing a breaking PR to add the rightinstructions.mdentry to the right published skill.check:upgrade-coverageCI gate (scripts/check-upgrade-coverage.mjs) — fails any PR that breaksexamples/orpackages/3-extensions/without a matching entry, and fails any PR that adds a new file to a staleupgrades/<X>-to-<Y>/directory instead of the in-flight one.@prisma-next/*dep is nowworkspace:0.7.0(literal-version form); pnpm rewrites that to exact0.7.0at publish time;scripts/set-version.tskeeps these in lockstep with theversionfield on every bump;scripts/check-publish-deps.mjsverifies the published tarballs.How the user flow works
prisma-next.config.ts, enumeratesextensionPacks, then reads each extension'snode_modules/<pkg>/package.jsonto find its pinned@prisma-next/*version. The lowest pin is the highest reachable target. If the user asked for higher, halt and surface the lagging extension(s).pnpm-lock.yaml. Detect to-version from the user's flag ornpm view @prisma-next/postgres dist-tags.latest.0.6 → 0.8becomes two steps.<to>,pnpm install, load the matchinginstructions.md, run any colocatedscript:s and apply prose changes, validate with the project's ownpnpm typecheck && pnpm test, commit. Halt on failure — never auto-roll-back.@latest. The skill is mutable forever — every release contains the cumulative set of all(from, to)entries with the latest version of each. Step 0 of the SKILL.md is "ensure this skill is@latestand reload."Full prose:
packages/0-shared/upgrade-skill/SKILL.md.How the change-author flow works
When we (Prisma Next maintainers) ship a breaking change:
examples/(user-facing) orpackages/3-extensions/(SPI-facing) — or both.record-upgrade-instructionsskill, which:Mfrom the PR branch'spackage.json. The in-flight transition isM → M+1.examples/change → entry inpackages/0-shared/upgrade-skill/upgrades/<M>-to-<M+1>/;packages/3-extensions/change → entry inpackages/0-shared/extension-upgrade-skill/upgrades/<M>-to-<M+1>/. Cross-audience PRs duplicate.instructions.md+ colocated script(s).git restore --source=origin/main -- examples/to revert the substrate, run the entry against the reverted state, verify the result matches the PR-branch state and the test suite is green.check:upgrade-coveragefails ifexamples/orpackages/3-extensions/diffs are present without a matching entry (in any path, including the conventional generated artefacts — there's no carve-out), and fails if any new file lands in a staleupgrades/<X>-to-<Y>/directory.Full prose:
.agents/skills/record-upgrade-instructions/SKILL.md.How the publish-time exact-pin mechanic works
Extensions must declare every
@prisma-next/*dep as a single exact version (no^,~,workspace:*, etc.) and all of them must agree. This is the contract the user-skill's pre-flight relies on.Implementation:
@prisma-next/*workspace dep isworkspace:0.7.0(literal-version form). The migration touched 79package.jsonfiles / 885 spec entries (commitrefactor(workspace)).workspace:0.7.0→0.7.0(no caret) in the published tarball.scripts/set-version.tsrewrites bothversionfields and everyworkspace:<X.Y.Z>spec on every@prisma-next/*dep, in lockstep, on every invocation.pnpm bump-minor→ 0.8.0 also rewrites all theworkspace:0.7.0toworkspace:0.8.0automatically.scripts/check-publish-deps.mjspacks every publishable tarball and asserts every@prisma-next/*entry is exactX.Y.Z. Re-ran against this PR's HEAD: 63 tarballs, 0 violations.Reviewer notes (the gotchas)
record-upgrade-instructionsSKILL.md, and the spec/plan. The current state (upgrades/0.7-to-0.8/placeholders,inFlightTransitionLabel(head)returninghead→head+1) is the corrected one. If you spot any lingering0.6-to-0.7reference outside an explicit "stale-directory" example, flag it.package.jsonfiles). Spot-check any extension'spackage.json. The transformation was applied via a one-shot script (wip/m5/migrate-workspace-specs.mjs, gitignored — the durable mechanism isset-version.ts's extension).check:upgrade-coveragedistinguishes two transition labels:inflightTransitionis purelyheadMinor → headMinor + 1(a function of head'spackage.jsonalone — head is the currently-published version, in-flight is the next one).coverageTransitionmatchesinflightTransitionin PR-mode steady-state (prev.minor === head.minor) and isprev → headin publish mode (where the bump-PR has just landed). The new-entries rule accepts either label, so files added across a publish-mode bump can describe either the release shipping now or the next in-flight release. There is no script-level carve-out for "generated paths" or for patch-only ranges — a substrate diff is a substrate diff, and consumer-invisible regenerations are recorded withchanges: [].@prisma-next/tsconfigand@prisma-next/tsdownREADME installation samples still mentionworkspace:*. Those are markdown describing the legacy install pattern; the actual workspacepackage.jsonfiles are migrated. Out of scope here; flag for follow-up.ECONNRESETflake inpnpm test:packages(@prisma-next/adapter-postgresintegration suite) reproduces across multiple rounds and on pre-m5 commits in isolation. Likely a local docker / connection-pool issue. Out of scope here; worth a separate investigation.scripts/test files don't run in CI today (check-publish-deps.test.mjs,validate-package-manifests.test.mjs). The new test files added here are wired intotest:scripts. A follow-up could widentest:scriptsto pick up the two pre-existing files.projects/prisma-next-agent-skill/specs/upgrade-skill.spec.md,plans/upgrade-skill-plan.md) are intentionally retained for review — they migrate to durable docs at project close-out.What lands in this PR
The 8 commits decompose into reviewable slices:
docs(project)feat(0-shared)packages/0-shared/workspace tier. Placeholderinstructions.md(changes: []) + stub bin.feat(extension-upgrade-skill)prisma-next-check-pinsCLI (88 LOC) + 18node --testcases.feat(skills).agents/skills/record-upgrade-instructions/SKILL.md(312 lines).feat(scripts)check:upgrade-coveragescript (280 LOC) + 16 test cases + wiring intoci.ymlandpublish.yml.refactor(workspace)workspace:*→workspace:0.7.0migration (1765/1765 line balance, plus pnpm-lock specifier rewrite).feat(set-version)scripts/set-version.tsextension + 7 unit tests.feat(check-publish-deps)[pin]rule on top of the existing[leak]rule + 14 unit tests.fix(upgrade-skill)record-upgrade-instructionsSKILL.md. Also drops the GENERATED_BASENAMES + patch-only carve-outs (any substrate diff requires an entry; consumer-invisible regenerations ship withchanges: []).docs(upgrade-skill)19 of 28 spec acceptance criteria are PASS in this PR. The remaining 9 are spec-deferred until PR #502 lands non-placeholder content (end-to-end consumer-flow ACs) or to publish-time observation (matched-versions AC). Full scoreboard in the spec.
Verification
Run on the final HEAD:
pnpm install✓pnpm typecheck✓ (134 turbo tasks)pnpm test:scripts✓ (70 cases incl. the rewritten coverage-check fixtures + m4/m5/m2 additions)pnpm test:packages✓ on rerun (recurring postgresECONNRESETflake — see reviewer notes)pnpm check:publish-deps✓ (63 tarballs, 0 leaks, 0 pin violations)pnpm check:upgrade-coverage✓ (vacuous — this PR has no substrate diff)pnpm build✓pnpm lint:deps✓ (872 modules, 0 violations)pnpm lint:manifests✓ (63 publishable packages)pnpm lint:workflows✓Alternatives considered
prisma-next-check-pins). Splitting forces no-cross-dep, which costs us per-PR duplication for cross-audience entries (PR TML-2512: drop inlined fromContract/toContract from migration.json #502's shape) — accepted as a deliberate price.@prisma-next/extension-pin-checkpackage for the CLI. Rejected: it would have been a single 88-line script in its own published package. Folding it into@prisma-next/extension-upgrade-skillas abinis one fewer publish unit and the audience is identical.SKILL.mdprose instructing the agent to readprisma-next.config.ts+ per-extensionnode_modules/<pkg>/package.jsondirectly.upgrades/<X>-to-<Y>/directories. Rejected: it would have blocked bug-fixes to old entries. Instead, instructions are mutable forever and consumers always pull@latest. The narrower "new file adds must land in the in-flight directory" check catches misrouting without blocking bug-fixes.publishConfig.dependenciesoverlay or a new publish-time rewrite script to enforce exact pins. Rejected in favour ofworkspace:<literal-version>everywhere, which leverages pnpm's existing publish-rewrite behaviour and adds no new publish-time scripts. Decision logged inwip/unattended-decisions.md.patheinstead ofnode:pathin the pin-check CLI. Rejected: the skill packages are deliberately zero-dep andnode:pathis sufficient. Decision logged.See the spec for the full set of decisions and acceptance criteria.
Checklist
git commit -s).TML-NNNN: <title>form (per.claude/skills/create-pr/SKILL.mdand the updated.github/PULL_REQUEST_TEMPLATE.md).Summary by CodeRabbit
Release Notes
New Features
@prisma-next/upgrade-skillfor semi-automated minor-version upgrades in consumer projects with per-step validation and rollback guidance.@prisma-next/extension-upgrade-skillfor extension authors to upgrade dependencies with structured error reporting.prisma-next-check-pinsCLI to enforce exact version pinning across Prisma Next dependencies.Documentation
Chores
0.7.0across all packages.