T-SWJZ-markdown-contract-core-subpath-revendor
Status: planning/backlog · Impact: low · Complexity: medium
The shell layer’s markdown-contract → dist/core vite alias (T-S0TW)
is a workaround for a missing upstream export: the package root re-exports
the corpus runner (node:fs/node:path), and there is no ./core subpath
naming the browser-safe half. Ship the subpath upstream, re-vendor, and
delete the alias. Blocking that today is a trap in the re-vendor flow
itself: a naive run downgrades the package and drops an API a consumer
depends on.
| Location | Role today |
|---|---|
vendor/markdown-contract-0.2.1.tgz | Hand-composed artifact (mc 0.2.0 + splitFrontmatter restored); byte-identical copy at solutions/determined/vendor/ |
solutions/determined/scripts/update-markdown-contract.sh | Re-vendor script: clones upstream main, builds packages/core, npm packs whatever version that manifest carries — today 0.1.0, a downgrade from the composed 0.2.1 that silently drops splitFrontmatter (used by solutions/determined/apps/vault-triage/src/config.ts) |
solutions/determined/packages/shell/nuxt.config.ts | Carries the vite alias pointing the bare specifier at dist/core/index.js for every product’s browser build |
solutions/determined/packages/vault-contracts/ | 13 schema modules import { contract } from 'markdown-contract' — the package-root specifier the alias rewrites |
Upstream (/Users/sksizer2/Developer/markdown-contract, packages/core)
already keeps src/core/ and src/runner/ separate; its exports map has
., ./declarative, ./cli, ./cli/run — no ./core.
Proposed
Section titled “Proposed”Upstream markdown-contract exports the browser-safe contract core at
./core (no node:* in its transitive graph), with splitFrontmatter
landed on main and the version bumped past the composed 0.2.1. The
repo vendors that release, vault-contracts schema modules import
markdown-contract/core, and the shell alias is deleted.
Approach
Section titled “Approach”- Upstream: land
splitFrontmatteronmain, add the./coresubpath export, bumppackages/coreto0.2.2, tag. - Fix
update-markdown-contract.sh: fail if the packed version is not newer than the vendored one; write both vendor copies (rootvendor/andsolutions/determined/vendor/), or collapse to one dir and update the tenfile:specs together. - Re-vendor; bump every
file:dependant;bun install. - Rewrite the 13
vault-contractsschema-module imports tomarkdown-contract/core; keepcorpus.ts/check.tson the root. - Delete the shell alias;
bun run proto:buildgreen without it.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
vendor/markdown-contract-0.2.1.tgz | delete | Replaced by the split-exports release |
solutions/determined/vendor/markdown-contract-0.2.1.tgz | delete | Same |
solutions/determined/scripts/update-markdown-contract.sh | modify | Downgrade guard; handle both vendor locations |
solutions/determined/packages/vault-contracts/ | modify | Schema imports move to markdown-contract/core |
solutions/determined/packages/shell/nuxt.config.ts | modify | Delete the alias block |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1:
bun run proto:buildinsolutions/determinedexits 0 with nomarkdown-contractvite alias anywhere in the repo. - AC-2:
update-markdown-contract.shrefuses to vendor a version older than the one in place. - AC-3:
apps/vault-triagestill typechecks (itssplitFrontmatterimport survives the re-vendor).
Out of scope
Section titled “Out of scope”- Publishing markdown-contract to npm (the vendor README’s documented exit path) — a bigger call than this cleanup.
Dependencies
Section titled “Dependencies”- Upstream repo access (
/Users/sksizer2/Developer/markdown-contract) — the split happens there first.
Discovery context
Section titled “Discovery context”- Surfaced fixing
T-S0TW: the alias hoist was chosen over the upstream split precisely because the re-vendor flow would downgrade 0.2.1 → 0.1.0 and dropsplitFrontmatter.