fix(ADR-0046): serve package docs at runtime, not just in the compiled artifact#1808
Merged
Merged
Conversation
…d artifact Package docs (src/docs/*.md) compiled into a bundle never reached the runtime: GET /meta/doc returned [] and docs were invisible in the console even though os build produced them and a pure-artifact boot served them. Root cause (two gaps on the two load paths): 1. os dev / os serve load metadata from objectstack.config.ts via defineStack(), which never carries the markdown docs — those are a compile-time augmentation (compile.ts step 3d). serve.ts now collects src/docs/*.md into the stack on the config-load path as well (collection only, additive, never blocks boot), so docs serve in dev exactly as from a built artifact. Verified: showcase /meta/doc returns showcase_index + showcase_docs_guide on a config boot. 2. The MetadataPlugin artifact loader's ARTIFACT_FIELD_TO_TYPE omitted docs -> doc, so the bundle's docs array was dropped on that path. Added the mapping for parity with the ObjectQL engine's metadataArrayKeys, plus a _parseAndRegisterArtifact regression test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
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
2 participants
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.
Problem
Package docs (
src/docs/*.md, ADR-0046) compiled into a bundle never reached the runtime.GET /meta/docreturned{"type":"doc","items":[]}and docs were invisible in the console — even thoughos buildproduced them and a pure-artifact boot served them fine. This is the actual reason "the showcase has no docs": the data was never there to render.Root cause — two gaps, one per load path
os dev/os serve(config-load path). With anobjectstack.config.tspresent, serve re-derives metadata fromdefineStack(...). The markdown docs are not part ofdefineStack— they're a compile-time augmentation (compile.tsstep 3d,collectAndLintDocs). So the dev/serve path loaded zero docs.serve.tsnow collectssrc/docs/*.mdinto the stack on the config-load path too — collection only (additive; never blocks boot).MetadataPlugin artifact loader.
ARTIFACT_FIELD_TO_TYPE(packages/metadata/src/plugin.ts) omitteddocs → doc, so the bundle'sdocsarray was skipped on that load path. Added the mapping for parity with the ObjectQL engine'smetadataArrayKeys, plus a_parseAndRegisterArtifactregression test.Verification (live)
/meta/docbeforeos dev/serve(config)items:[]showcase_index,showcase_docs_guideservicePayloadnow carriesdocsintoregisterApp; list + single-item (/meta/doc/showcase_indexwith content) both resolve.@objectstack/metadata9/9 tests pass (incl. new regression); CLI typecheck clean.Scope
Backend/runtime only. The console-side docs portal + nav entry is a separate objectui PR.
🤖 Generated with Claude Code