Developing against a checkout

When this applies

Work on @evolve-framework, @evolve-storefront or evolve-contrib packages from inside an Evolve project, through task vendor-evolve, which links a checkout under vendor/ into the workspace. Use when a change needs unpublished framework or storefront code, when the user says link, unlink, vendor or vendor-evolve, when pnpm-workspace.yaml shows workspace:* overrides or vendor.sh: marker comments, or when a type error names two copies of the same package after linking. Not for client projects that only consume published packages.

task vendor-evolve runs a project against a checkout of evolve-framework, evolve-storefront or evolve-contrib instead of the published packages. The checkout sits under vendor/, which git ignores apart from its README, so its branches and uncommitted work belong to the developer.

task vendor-evolve -- link [framework|storefront|contrib|all]   # clones what is missing, installs
task vendor-evolve -- status
task vendor-evolve -- unlink                                     # installs too
task vendor-evolve -- update [framework|storefront|contrib|all]  # git pull in the checkouts

--no-install skips the install that link, unlink and update end with. The project’s CONTRIBUTING.md describes the mechanism for people; this skill is what an agent needs on top.

What linking changes

Only pnpm-workspace.yaml, and the lockfile through the install:

Change	Why
vendor/<repo>/packages/* added to packages:	turbo only sees workspace members
Every package of the checkout the project uses → workspace:*	the override is what makes every consumer resolve the checkout
The storefront’s catalog entries the project lacks, copied in	storefront packages name their dependencies as catalog:
Shared dependencies → the linked package’s own version	otherwise pnpm installs two copies whose types do not match
…except across a major, and for the names in KEEP	the project’s own code is bound to its major or exact version

Each changed line carries a # vendor.sh: was … note and each added line sits between # vendor.sh: markers. The lockfile from before linking is kept in vendor/ and restored on unlink, so a round trip leaves no diff.

Rules while linked

• Never commit pnpm-workspace.yaml or pnpm-lock.yaml. status says which mode the workspace is in; workspace:* overrides or vendor.sh: markers mean linked. Unlink before committing anything in the project itself.
• Commit and push package changes from the checkout, vendor/<repo>, on a branch of that repository. It is a normal clone with its own remote.
• Run a linked package’s scripts from the project root, as pnpm --filter @evolve-framework/<name> run tsc. Inside vendor/, pnpm reads that repository’s own packageManager, which the project’s minimumReleaseAge may refuse.
• pnpm tsc and pnpm test skip vendor/. Check a linked package with its own scripts, and in its own repository before opening a pull request there.
• Run the app on the host: pnpm dev, with task docker:services for the infrastructure. task docker:dev mounts the host’s node_modules under vendor/, which hold the host’s binaries.

Reading failures

• The app does not compile, or the supergraph does not compose. Linked main can be ahead of the versions the project is written against. Separate drift (the project has to adapt, as it would on the next version bump) from a defect in the package (fix it in the checkout). A composition error over two subgraphs is worth checking in the package’s schema: its own repository may compose only one.
• “Type X is not assignable to type X”, or a module state that seems to reset. Two copies of one package. Find them under node_modules/.pnpm; a dependency the linked package shares with the project but that link did not override is the usual cause. Relinking re-derives the overrides.
• The project breaks only while linked, in a package of its own (an instrumentation hook that throws, a missing export). An override forced one of the project’s own dependencies onto the linked package’s version, and an override replaces every copy in the tree. Across a major link already leaves both copies; for a same-major break, add the name to KEEP in scripts/vendor.sh and relink.
• A checkout is cloned but not linked. The project depends on none of its packages yet. Add the dependency to the consuming package.json and link again.