Skip to content

docs(ui-merge): fold objectui.org into objectstack docs, K3 — generate the component reference for all 106 authorable components from sdui.manifest.json, with a drift check #27142

Closed
#27179
Closed
docs(ui-merge): fold objectui.org into objectstack docs, K3 — generate the component reference for all 106 authorable components from sdui.manifest.json, with a drift check#27142
#27179
Assignees
os-tesla
Labels
documentationImprovements or additions to documentationdomain:devxpm:dispatched

Description

@objectstack-fleet
objectstack-fleet
bot
opened on Oct 28, 2026

Filing gate ③ (maintainer-directed). In the "Restore objectui.org docs deploy" project thread (card thread of #26993), on 2026-10-28:

  • 03:24Z, on the decision card "objectui.org 文档站以后怎么处理?", Tesla chose 「B 并入 objectstack 文档站」. www.objectui.org stops being a separate site, and its docs fold into the objectstack docs site (content/docs, served at objectstack.ai/docs).
  • 03:24Z, Tesla asked 「objectui 文档全部需要保留吗？这需要评估并和我沟通」. The card thread then sorted the 183 pages under ui/content/docs one by one into keep, merge, generate and delete, and put four questions to Tesla.
  • 07:58Z, on that evaluation, Tesla answered 「VS Code 扩展 不会发布，其他同意」 and then 「你负责派卡执行」.

The fold is split into four cards. The first three can run in parallel; the fourth is blocked by them:

  • K1 moves the SDK pages.
  • K2 merges pages into existing ones.
  • K3 generates the component reference.
  • K4 retires the old site and adds the redirects.

This is card K3.

维护者速读

元数据作者在页面 JSON 里能用的组件,以根目录的 sdui.manifest.json 为准。这份清单由 CI 生成并校验,共 106 个组件,每个都带输入项的类型和说明。

objectui 站点只为其中 17 个手写了组件页,另外 89 个没有自己的组件页。本卡写一个生成脚本,从 manifest 生成 objectstack 文档站的「组件参考」,一次覆盖全部 106 个。生成之后,那 17 个手写页和组件索引页就不再需要,由 K4 删除。

生成物会有漂移检查:manifest 变了而参考页没重新生成,检查就红。

Wanted

  1. A generator script, for example scripts/gen-sdui-reference.mjs, with --self-test. It reads sdui.manifest.json and writes a component reference into content/docs:
    • one page per namespace, or one page per component, whichever reads better at 106 entries (the dev's call, stated in the PR);
    • each component listed with its type, its namespace, and its inputs as a table (name, type, description);
    • a header on each generated page saying it is generated and naming the command that regenerates it.
  2. The pages go in a new content/docs/ui/components/ section, linked from content/docs/ui/meta.json. If the generated pages fit an existing generated area's conventions better (for example content/docs/references/, whose pages are never hand-edited), use that instead and say why.
  3. A drift check: --check exits non-zero when the committed pages differ from what the manifest produces. Wire it in where sdui.manifest.json is already verified, so that a manifest change and its reference change land in one PR. If that wiring needs a .github/workflows/** edit, the PR is Tier H (draft until green, the maintainer merges); otherwise prefer a root package.json script that an existing check family already runs.
  4. The 17 hand-written pages this replaces (ui/content/docs/components/): basic/{icon,image,span,text}, complex/table, data-display/{alert,badge}, disclosure/accordion, form/{button,label} and layout/{box,card,container,flex,grid,stack,tabs}, plus components/index. The PR body records the URL each one maps to, for K4's redirect map. Where a hand page carries a worked example the manifest lacks, put it in the PR body's Acceptance notes and do not copy it into a generated page.

⛔ Do not delete the hand pages and do not touch ui/apps/site. That is K4's work.

Who acts

A domain:devx card thread. The surface is scripts/gen-sdui-reference.mjs (or the dev's name for it), content/docs/ui/components/**, content/docs/ui/meta.json and the root package.json scripts, plus the workflow line only if item 3 needs one. Serial constraint with K2: both may touch content/docs/ui/meta.json, so whichever lands second merges main.

Business reason. A metadata author placing a component in a page finds no page of its own for 89 of the 106 authorable components today; the inputs and their descriptions exist only inside the manifest file. A generated reference also cannot drift from the renderer the way the 17 hand pages could.

Acceptance

  • node scripts/gen-sdui-reference.mjs --self-test exits 0, and --check exits 0 on the PR head.
  • Hand-editing one generated line makes --check exit non-zero. Record that in the PR as a one-time ablation.
  • All 106 manifest types appear in the generated pages.
  • pnpm --filter @objectstack/docs build is green.

Duplicate search. The same query as the fold's other cards: 33 hits, the first 10 read (#26993, #27030, #27048, #26140, #26688, #24230, #25677, #26944, #25854, #26035). No card generates docs from sdui.manifest.json. New.

Size: M. Clause-②: no. Metadata-protocol: none.

Activity

  1. objectstack-fleet
    added
    documentationImprovements or additions to documentation
    domain:devx
    pm:dispatched
    on Oct 28, 2026
  2. objectstack-fleet
    assigned
    os-tesla
    on Oct 28, 2026

  3. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 28, 2026
    ContributorAuthor

    Claim: card thread "Restore objectui.org docs deploy", dispatch of #27142 (maintainer-directed: 「B 并入 objectstack 文档站」 03:24Z, 「VS Code 扩展 不会发布，其他同意」 and 「你负责派卡执行」 07:58Z, 2026-10-28, that thread)
    Session: session_01L9qibyAYPFxpNP4BCr7Z82 (dispatching thread) · dev: a new card thread the project coordinator opens for this card; it names its own session in its os-dev-report
    Account: os-tesla
    Branch: the dev card thread's platform-assigned claude/project-thread-* branch (mode:thread; the only branch it pushes)
    Worktree: the dev card thread's own checkout
    Domain: domain:devx
    Seat: domain:devx#1 (seat 1 by default; dispatched on the maintainer's instruction from a card thread, not from a lane seat)
    File surface: a new generator under scripts/ with --self-test/--check, content/docs/ui/components/** (or content/docs/references/ if justified), content/docs/ui/meta.json, root package.json scripts, and the one workflow line item 3 may need (that makes the PR Tier H); ⛔ no edits under ui/ (stop on breach; explain in the report)
    Container & model: M, mode:thread, model: opus (default; dispatch-gates --tier --repo objectstack-ai/objectstack on this surface prints no path-derived mandate), effort: high
    Clause-②: no
    Metadata-protocol: none
    Responsibility: n/a — not a defect card
    Thread-read: none
    Premise: holds (page lists measured on main 24351cfe, 2026-10-28 08:0xZ: 183 pages under ui/content/docs, guide/ci-cd-pipeline already retired by #27071)
    Serial constraints cleared: #27141 may also touch content/docs/ui/meta.json; whichever lands second merges main. Fold siblings: #27140, #27141 and #27142 run in parallel; #27145 is blocked by all three and does every deletion under ui/. Open PRs were not enumerated by path; the dev merges main before marking the PR ready.

    Generated by Claude Code

  4. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 28, 2026
    ContributorAuthor

    os-dev-report

    {
  "issue": 27142,
  "status": "done",
  "branch": "claude/project-thread-7ka124",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/27179",
  "session": "session_01L9qibwMyAnTNeas3ANYhyi",
  "premise_still_valid": true,
  "summary": "scripts/gen-sdui-reference.mjs renders content/docs/ui/components/ (7 namespace pages plus an index) from sdui.manifest.json: all 106 components, each input as a table row. --check reds on drift and runs as a new lint.yml step (Tier H). The directory is registered as generated in the docs-audit scope, the os-regen merge driver and the role-word skip list, which the gate sweep required. PR is draft; os-zhuang and hotlong are requested by CODEOWNERS.",
  "tests": "node scripts/gen-sdui-reference.mjs --self-test: 20 cases pass, 20 batteries at floor. --check on ca0a9747: 106 components on 7 pages. One-time ablation via scripts/ablation-replace.mjs (ui.mdx line 160 Required cell): --check exit 1 naming file and line; restored blob == HEAD. pnpm --filter @objectstack/docs build: VERDICT command-exit 0; next start serves /docs/ui/components (107 table rows) and /docs/ui/components/plugins (16 tables).",
  "gates": "dispatch-gates --ran on ca0a9747: 99 derived, 98 run green, 1 NOT MEASURED (check:dual-build-cjs-loads exit 3, needs a full workspace build; left to CI). First-run reds fixed in the PR and re-run green: check-section-landing-index, check:docs-audit-scope, check:merge-driver, check:role-word. check:pm-dispatch-gates red once mid-edit, green on the committed tree. CI check-runs: in_progress at report time.",
  "dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm",
  "mcp_calls": "2 — subscribe_pr_activity, pull_request_read (reads only)",
  "api_writes": "1 relay stroke so far — pr_create (#27179); this report comment is the second",
  "open_questions": [],
  "out_of_scope_findings": [
    "carrier: K2 #27141 · content/docs/ui/pages.mdx § Components lists record:chatter, element:image, element:record_picker, element:text_input (not in the public manifest) and omits record:discussion, element:definition-list, element:repeater; noted, not filed",
    "carrier: none · object-kanban cardFields description in the ui/ registry uses the ADR-0090 D3 reserved word role; noted, not filed"
  ]
}

    Generated by Claude Code

  5. os-zhuang
    closed this as completedin #27179on Oct 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationdomain:devxpm:dispatched

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions