playground-design-system/docs/vendoring-and-re-sync.md

Vendoring and re-sync

Status: decision recorded 2026-08-27. The re-sync script is recoverable but not yet restored — see Current state for what a consumer can and cannot do today.

This document answers three questions raised by a consumer repo on 2026-08-26: whether a current re-sync path exists, whether vendoring is still the recommended consumer model, and where MANIFEST.json's source field should point now that the marketplace is a polyrepo.

Every number below was measured against ground truth on 2026-08-27, not recalled. The measurements are listed in Verification log so a reader can re-run them.

Background

Until 2026-06-18 the marketplace was a monorepo. This design system lived at shared/playground-design-system/, and scripts/sync-design-system.mjs vendored it into each plugin's playground/vendor/playground-design-system/. Commit e84dffd ("thin catalog to manifest + docs (polyrepo migration complete)") deleted both paths in the same change. This repo was extracted as a sibling with the CSS files at its root and a fresh 17-commit history.

Consumer documentation kept pointing at the monorepo layout, so the instructions it gave named a directory and a script that no longer existed anywhere.

Decision

1. Is vendoring still the recommended model? Yes.

This is settled first, because the other two answers depend on it.

The measurement supports keeping it. Three and a half months after the last sync, in both consumers, 26 of 27 vendored files are byte-identical to this repo's current content, and each MANIFEST.json still matches its own files exactly — no consumer has edited a vendored file locally. The one file that differs is this repo's own README.md, which documents the system rather than being part of what it delivers.

Vendoring did what it promised: the consumers stayed standalone and kept rendering correctly when the source moved out from under them. What broke was the documentation pointing at the mechanism, not the mechanism.

Nothing replaces it. A git submodule or an npm package would contradict the Non-goals in README.md: no build step, no bundler, no package registry, and a Playground that opens from file:// with only the CSS files alongside it.

2. Is there a current re-sync path? Not yet — but the script is not lost.

scripts/sync-design-system.mjs is absent from the entire marketplace tree today. It survives in full in the catalog repo's history, which carries the pre-migration monorepo history (977 commits). It can be read back with:

git -C <marketplace>/catalog show e84dffd^:scripts/sync-design-system.mjs

It is 225 lines, has no npm dependencies, and — this matters — it was already prepared for the polyrepo split before the split happened. It accepts --source <dir> and --target <dir>, both of which override the hardcoded monorepo paths, and its own comment says the --target flag exists "so the script still works once plugins/<name> no longer exists in-repo (post-migration / extracted repo)". It also has a --check mode that re-hashes a consumer's vendored tree against its committed MANIFEST.json and exits non-zero on drift, needing no source at all.

So restoring it is recovery, not new development, and it belongs in this repo — the mechanism vendors from the design system, so the design system owns it.

It cannot be restored unchanged, and that is why no command is published here yet. The script walks its source directory and copies everything it finds. In the monorepo, shared/playground-design-system/ contained only the design system. This repo's root contains the design system plus the repo apparatus: STATE.md, LICENSE, SECURITY.md, .git/, docs/, and playground-examples/. A naive --source . would vendor all of it into both consumers — including STATE.md, which is deliberately gitignored and must never reach a public mirror.

Restoration therefore needs an explicit source boundary — an allowlist of the 27 delivered files, or a dist/ directory the script reads from. Choosing between those is the next decision, and it is a real one; publishing a --source . command today would be a guess that leaks.

3. Where should MANIFEST.json's source point? Here — but not yet.

This is not the consumer's business alone: the field is written by this repo's script and describes this repo's source, so the value is ours to define.

The important finding is that source_commit is not merely unreachable — it is false. Both consumers record source_commit: c1b7bad3899c5cfe9ff90663003609b018aa79a0, but the vendored tree contains components-tier4-project-view.css, and that file demonstrably did not exist in c1b7bad. The sync labelled its output with the marketplace's HEAD while copying the working tree, which at that moment held a v0.6.0 file that had not been committed yet.

The consequence for repair: do not fix the field by translating the path. Rewriting shared/playground-design-system/ to this repo's name while keeping c1b7bad would turn an obviously stale pointer into a plausible false one, and a plausible false pointer is worse — it stops inviting the check that would catch it.

The correct order is: restore the script with a source boundary, run one re-sync, and let the script write a truthful manifest in which source_commit is this repo's HEAD — reachable from this repo, unlike c1b7bad. Until then, a visibly stale field is the more honest state.

One correction to the premise this question arrived with: the lineage is not severed. c1b7bad is unreachable from this repo and from either consumer, but it is alive in catalog. "Nobody can compute how far behind a vendored copy is" does not hold — it was computed, and the answer is one file.

Current state

What a consumer can do today, with no script:

• Verify integrity — re-hash the vendored files against the SHA-256 values in the copy's own MANIFEST.json. This needs nothing but the consumer's own checkout and answers "has anyone edited the vendored copy locally?"
• Measure drift against this repo — hash each vendored file (stripping the /* Code generated by sync-design-system.mjs; DO NOT EDIT. */ header line that the sync injects into every .css) and compare against the file of the same name at this repo's root.

What a consumer cannot do today: re-sync with one command. That is pending the source-boundary decision above.

MANIFEST.json should be left alone in the meantime.

Verification log

Measured 2026-08-27 against ground truth. <marketplace> is the polyrepo root.

Claim	How it was checked	Result
sync-design-system.mjs absent from the marketplace	find over the tree, maxdepth 5, .git/node_modules pruned	0 hits. Denominator: the same query returned 836 .mjs files; known-positive control found catalog/scripts/check-versions.mjs, so the query can find.
shared/ absent	find -type d -name 'shared*', maxdepth 3	0 hits
Two consumers vendor the system	find -type d -name playground-design-system, maxdepth 4	ms-ai-architect and llm-security, 27 files + MANIFEST.json each
c1b7bad unreachable from this repo	git cat-file -t	fatal: could not get object info. Known-positive control on this repo's HEAD returned commit.
c1b7bad reachable from catalog	git -C catalog cat-file -t	commit — 2026-05-15, monorepo history, 977 commits
The monorepo commit held both deleted paths	git -C catalog ls-tree -r c1b7bad	shared/playground-design-system/ (26 files) and scripts/sync-design-system.mjs both present
Both paths died in the migration	git -C catalog log --diff-filter=D	e84dffd, 2026-06-18, deleted both
source_commit is false	git -C catalog cat-file -e c1b7bad:shared/playground-design-system/components-tier4-project-view.css	path does not exist in c1b7bad. Known-positive control on components-tier3.css in the same commit succeeded.
No local drift in either consumer	SHA-256 of each vendored file vs its own MANIFEST.json	both MANIFEST OK, 27/27
Drift vs this repo	SHA-256 vs this repo's root, generated-header stripped from .css	26/27 identical in both consumers; README.md the only difference
The recovered script supports polyrepo	read of git show e84dffd^:scripts/sync-design-system.mjs	--source, --target, --check all present and honoured in main()

Not verified: whether catalog's history is itself mirrored anywhere off this machine. The recovery path above assumes a local catalog checkout.