Repository navigation
Feat: Add a Moca docs section synced from rossoctl/moca behind a publish guard - #227
Conversation
…uard The site gains a Moca docs instance at /moca/*, synced from rossoctl/moca:docs/ by scripts/sync-docs.sh, as the Docs section is from rossoctl/rossoctl. - The sync leaves out moca's design records (specs, notes, plans, archive, demos, ADRs, REORG-PLAN.md), so they stay off the pages and out of search. - Relative links that leave the published tree are rewritten to the file on GitHub (scripts/rewrite-repo-links.mjs). - Publish guard: any published file matching SBX[0-9] or a pattern in moca's docs/.publish-denylist skips the whole Moca section, with the files listed in the build log. With no moca/index.md the instance and its navbar item are not added, so the site builds exactly as before. Today's moca docs fail the guard, so merging this publishes nothing until rossoctl/moca lands content that passes it. - The Moca pages track moca's main branch; a banner on every Moca page says so (a DocVersionBanner wrapper; other instances are unchanged). Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
👷 Deploy request for animated-crumble-fb8862 pending review.Visit the deploys page to approve it
|
There was a problem hiding this comment.
🟡 Changes recommended
A malformed denylist can silently bypass the publication guard, and the link rewriter modifies links inside valid fenced code blocks.
2 open issues
What changed in this PR
Adds build-time plumbing for a Moca documentation section at /moca/*, alongside the existing synced docs. The section is enabled only when the sync produces moca/index.md.
Changes:
- Syncs Moca docs with design-record exclusions and a denylist-based publication guard.
- Adds conditional docs routing, an autogenerated sidebar, navigation, and a main-branch warning banner.
- Rewrites links outside the published tree to GitHub and documents sync and dispatch behavior.
Assisted-By: Claude Code
| File | Description |
|---|---|
src/theme/DocVersionBanner/index.tsx |
Adds a Moca-only main-branch warning; preserves other banners. |
sidebarsMoca.ts |
Defines the autogenerated Moca sidebar. |
scripts/sync-docs.sh |
Adds Moca fetching, exclusions, publication checks, and link rewriting. |
scripts/rewrite-repo-links.mjs |
Rewrites relative Markdown links outside the published tree. |
README.md |
Documents Moca publication rules and local preview options. |
docusaurus.config.ts |
Conditionally enables the Moca docs instance and navbar item. |
.gitignore |
Excludes generated Moca content from version control. |
.github/workflows/deploy.yaml |
Updates source comments and the sync step’s display name; execution is unchanged. |
Review effort: Balanced
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
I reviewed the sync step, the link rewriter, the Docusaurus instance/banner, and the docs. I reproduced the key claims against moca@main: after the exclusions, exactly 9 published files match SBX[0-9], so merging this leaves the site unchanged; every in-tree link in the published set resolves, and the rewriter's output (143 rewrites in 31 files) is sane.
Blocking: I agree with Copilot's comment on scripts/sync-docs.sh:177. The || true on the scan pipeline collapses grep exit 2 into "no leaks": one malformed ERE line in docs/.publish-denylist (for example (?i), or an unmatched [) makes the whole scan fail, the built-in SBX[0-9] included, and the build publishes. That contradicts the "no bypass" contract this PR is built on. Only exit 1 should mean clean; exit 2 or more should skip publication (or fail the build).
New, non-blocking findings are inline: the guard is not an MDX check, so the first guard-passing sync would fail the build as today's content stands; and the sidebar metadata the comment promises does not exist upstream.
Author: pdettori (MEMBER — maintainer)
Areas reviewed: Shell, Node/TypeScript, Docusaurus config/theme, GitHub Actions, docs
Agent/IDE config (.claude/.vscode): none
Commits: 1, all signed-off: yes
CI status: DCO and add-to-project pass; no build/typecheck job runs on PRs (deploy is main-only), so the only build evidence is the local testing in the PR body
| # Relative links that leave the published tree (to ../../deploy/..., the | ||
| # packages, or an excluded folder) would break on the site: point them at | ||
| # the file on GitHub instead. | ||
| node "$SCRIPT_DIR/rewrite-repo-links.mjs" "$MOCA_STAGE" docs "$MOCA_GH_BASE" "${MOCA_EXCLUDED[@]}" |
There was a problem hiding this comment.
Passing the guard is not enough to build this section yet. Docusaurus compiles these .md files as MDX, and moca's docs are GitHub-flavored Markdown: api/CHANGELOG.md has unescaped {id}/{build} in prose (lines 108, 109, 113, 117 at 6db4171, e.g. POST /v1/sandboxes/{id}/token), and sbx/security-review.md:68 has /v1/sandboxes/{id} in a table cell outside backticks. MDX turns {id} into a JS reference, so rendering throws ReferenceError: id is not defined (I reproduced this with @mdx-js/mdx 3); the first sync that passes the guard fails npm run build instead of publishing Moca. Both files are among today's 9 denylist hits, but scrubbing SBX names does not touch the braces.
Suggestion: escape the braces (or wrap those paths in backticks) in moca's content PR, and make the go-live gate a real build over the synced tree (a pull_request job here, or moca's CI), since the denylist only checks for banned strings.
There was a problem hiding this comment.
Thanks for checking this. It doesn't hold for this site, though. docusaurus.config.ts:78 sets markdown.format: 'detect', so .md files are parsed as CommonMark, not MDX; only .mdx is strict. @mdx-js/mdx on its own always compiles as MDX, which is why the reproduction threw.
To check, I built exactly the tree you cited: moca@6db4171's docs/ without the excluded design records, copied in without the guard.
npm run buildexited 0, with 0 errors.build/moca/api/CHANGELOG/index.htmlcontainsv1/sandboxes/{id}/tokenliterally.build/moca/sbx/security-review/index.htmlcontains/v1/sandboxes/{id}literally.
The risk is still real for a moca .mdx file, or if the site ever switches to format: 'mdx'. The proposal says to keep moca's docs .md.
On the gate: agreed, a real build is the stronger check, and the denylist only checks for banned strings. This repo's PRs get the Netlify preview build. For moca, I'd add a follow-up CI job that checks out rossoctl/.github, runs MOCA_SRC_REPO=$GITHUB_WORKSPACE npm run sync-docs && npm run build, and fails on errors. That way a moca docs PR can't break the site build. Should I add it to rossoctl/moca#884 or open it separately?
| import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; | ||
|
|
||
| // Moca section: autogenerated from the moca/ folder, synced from | ||
| // rossoctl/moca:docs/. Order and labels come from each folder's |
There was a problem hiding this comment.
The labels and order this comment promises do not exist upstream: moca@main has no _category_.json (0 files), no sidebar_position in any doc, and no front matter at all. Docusaurus then labels a category from a folder index.md when there is one (Concepts, Get started, Operations) and otherwise from the raw folder name — api, guides, reference, sbx — with everything alphabetical and root-level pages interleaved. Either add _category_.json (plus positions) in the content PR, or correct the comment.
There was a problem hiding this comment.
Right, the comment described the end state. Reworded in a473204: labels and order are set upstream by _category_.json and sidebar_position, which rossoctl/moca#884 adds (one _category_.json per folder: Get started, Sandbox service, Harness, Harness concepts, Guides, Deploy and operate, Day-2 operations, Reference, API, Project). Where they're missing, Docusaurus falls back to the folder's index.md title or the folder name, sorted alphabetically. With #884's tree, the sidebar renders in that order (checked in a local build).
…ode as written Review fixes for the Moca sync: - The publish guard read `grep ... || true`, so a scan that failed (exit 2: a malformed pattern in moca's docs/.publish-denylist, an unreadable file) looked like a clean one and published, built-in SBX[0-9] included. The guard now keeps grep's status: 1 publishes, 0 skips with the matching files listed, 2 or more skips with an ::error. - rewrite-repo-links.mjs split code blocks with one regex, so a four-backtick fence, an indented fence, or a fence inside a list item was treated as prose and its sample links rewritten. It now scans line by line with CommonMark's fence rules (``` or ~~~ of 3 or more, any indent; closed only by the same character, at least as long, with nothing after it) and leaves inline code spans alone too. - sidebarsMoca.ts no longer says the labels and order exist upstream: rossoctl/moca#884 adds them, and the comment says what Docusaurus does without them. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
check-docs-publish.sh tested `grep` with `if`, so a scan that failed (exit 2, e.g. a malformed pattern in docs/.publish-denylist) read as no match and passed. It now keeps grep's status: 1 passes, 0 fails with the matching lines, 2 or more fails as a broken scan. Same fix as the site's sync step (rossoctl/.github#227 review). Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
There was a problem hiding this comment.
🟡 Changes recommended
The publish guard can allow prohibited content in binary-looking Markdown, and list-prefixed code fences cause examples to be rewritten while subsequent prose links remain unchanged.
2 open issues
2 resolved since last review
Review effort: Balanced
| # itself failed (a malformed pattern in the denylist, an unreadable file), which says | ||
| # nothing about the content. Only 1 publishes: a failed scan is never a clean one. | ||
| scan_status=0 | ||
| leaks="$(grep -rIlE -f "$patterns" "$MOCA_STAGE")" || scan_status=$? |
| // fences inside list items count too; closed only by a fence of the same character, at least | ||
| // as long, with nothing after it, as CommonMark has it; an unclosed fence runs to the end of | ||
| // the file) and inline code spans (a run of N backticks up to the next run of exactly N). | ||
| const FENCE = /^\s*(`{3,}|~{3,})(.*)$/; |
… denylist rossoctl.dev gains a Moca section (/moca/*) synced from this repository's docs/ (rossoctl/.github#227). This adds the moca side: - .github/workflows/docs-dispatch.yaml sends the docs-updated repository_dispatch to rossoctl/.github on a push to docs/** on main, as rossoctl/rossoctl does, so a docs merge reaches the site within minutes rather than at the daily resync. It needs the SITE_DISPATCH_TOKEN secret; without it the job warns and exits 0. - docs/.publish-denylist lists what must never appear on the public site: the names of internal deployments (SBX0, SBX1, ...) and their cohorts. The site skips the whole Moca section while any published file matches, so nothing is published until the pages are clean. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
…b internal names The pages that go live at rossoctl.dev/moca (rossoctl/.github#227): - docs/index.md: what moca is, its two capabilities (the sandbox service and the harness), how they relate, which to use, and a path per audience. - docs/get-started/index.md: the "I want to..." chooser and the client install. - docs/sandbox/quickstart.md and docs/harness/quickstart.md: a first run of each capability. - docs/operate/index.md: which deployment delivers which capability. - README.md: trimmed to a funnel into these pages. - _category_.json per folder for the site's sidebar. Moca is open source for self-hosting, so the published pages no longer name internal deployments (SBX0, SBX1), cohorts or IBM-internal SSO: - docs/sbx/user-guide.md moves to docs/sandbox/user-guide.md (an unlisted stub stays at the old path, which deployed control planes print). - docs/sbx/security-review.md moves to docs/notes/. - docs/guides/oidc-login-w3id.md becomes the provider-neutral docs/guides/oidc-login.md. - openapi.yaml, the API changelog, the direct-client guide, its examples and the configuration reference cite specs by subject, not by internal name. Fixes from the docs audit: `docker compose down` keeps sessions and credentials (only `down -v` removes them); the sandbox service's signing key is rotated by removing the one key, as RUNBOOK §6 says, not the whole Secret; first-run no longer says async fan-out is unavailable on P6; the two top-level "moved to archive/" stubs are removed. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
check-docs-publish.sh tested `grep` with `if`, so a scan that failed (exit 2, e.g. a malformed pattern in docs/.publish-denylist) read as no match and passed. It now keeps grep's status: 1 passes, 0 fails with the matching lines, 2 or more fails as a broken scan. Same fix as the site's sync step (rossoctl/.github#227 review). Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Reviewed the incremental diff at a473204 only.
Guard: correct now — I reproduced all three outcomes with the new block: malformed denylist ([unclosed) makes grep exit 2, logs the ::error and leaves moca/ unpublished; a match exits 0, skips and lists the files; a clean tree exits 1 and publishes. Good to see the moca-side check fixed the same way in rossoctl/moca#884.
Rewriter: the line-based CommonMark scanner leaves the four-backtick fence (containing a ``` line), the two-space-indented list fence, the tilde fence in a list, the unclosed fence and single/double-backtick inline spans untouched. On today's staged moca tree it rewrites the same 143 links in 31 files as the previous version, so there is no prose regression.
Withdrawing my MDX comment: I missed markdown.format: 'detect' (docusaurus.config.ts:78); .md is parsed as CommonMark, so {id} is literal text and the build result in the thread stands. My reproduction used bare @mdx-js/mdx, which does not apply here. Sorry for the false positive — the residual risk applies only to a .mdx page (moca has none today) or a future switch of the format.
Copilot's two new items — I reproduced both and they are worth fixing, but I do not consider either blocking:
-Imakes a file that looks binary invisible to the guard: a stagedindex.mdcontaining a NUL byte followed bySBX7exits 1 and publishes. Using-a(still with-l) or refusing binary-looking files before publication closes it.- A fence opened on a list marker (
- ```lang) is not recognized, so its sample links are rewritten and the indented closing fence then suppresses the later prose links until the next fence. No published moca doc has this today (0 list-marker fences; blockquote fences only under the excludeddemos/), so a follow-up is fine.
Mergeable: yes, no conflicts with main. CI: DCO passes; no build/typecheck job runs on PRs. This approval clears the CHANGES_REQUESTED.
Author: pdettori (MEMBER — maintainer)
Areas reviewed: Shell, Node/TypeScript, docs (incremental)
Agent/IDE config (.claude/.vscode): none
Commits: 2, all signed-off: yes
CI status: DCO pass (no PR build job)
…b internal names The pages that go live at rossoctl.dev/moca (rossoctl/.github#227): - docs/index.md: what moca is, its two capabilities (the sandbox service and the harness), how they relate, which to use, and a path per audience. - docs/get-started/index.md: the "I want to..." chooser and the client install. - docs/sandbox/quickstart.md and docs/harness/quickstart.md: a first run of each capability. - docs/operate/index.md: which deployment delivers which capability. - README.md: trimmed to a funnel into these pages. - _category_.json per folder for the site's sidebar. Moca is open source for self-hosting, so the published pages no longer name internal deployments (SBX0, SBX1), cohorts or IBM-internal SSO: - docs/sbx/user-guide.md moves to docs/sandbox/user-guide.md (an unlisted stub stays at the old path, which deployed control planes print). - docs/sbx/security-review.md moves to docs/notes/. - docs/guides/oidc-login-w3id.md becomes the provider-neutral docs/guides/oidc-login.md. - openapi.yaml, the API changelog, the direct-client guide, its examples and the configuration reference cite specs by subject, not by internal name. Fixes from the docs audit: `docker compose down` keeps sessions and credentials (only `down -v` removes them); the sandbox service's signing key is rotated by removing the one key, as RUNBOOK §6 says, not the whole Secret; first-run no longer says async fan-out is unavailable on P6; the two top-level "moved to archive/" stubs are removed. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
check-docs-publish.sh tested `grep` with `if`, so a scan that failed (exit 2, e.g. a malformed pattern in docs/.publish-denylist) read as no match and passed. It now keeps grep's status: 1 passes, 0 fails with the matching lines, 2 or more fails as a broken scan. Same fix as the site's sync step (rossoctl/.github#227 review). Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>


Summary
This PR adds a Moca section to rossoctl.dev at
/moca/*. The content is synced at build time fromrossoctl/moca:docs/, the same way the Docs section comes fromrossoctl/rossoctl:docs/. It's step 1 of the moca docs migration: site plumbing only.Merging this publishes nothing yet. A publish guard skips the whole Moca section while any page matches moca's denylist, and today's moca docs don't pass it. The section goes live when a moca PR lands content that does.
Changes
scripts/sync-docs.sh, new step 4:rossoctl/moca(sparse checkout ofdocs/;MOCA_REFdefaults tomain,MOCA_SRC_REPOtakes a local clone) into the git-ignoredmoca/.specs/,notes/,plans/,archive/,demos/,adrs/,REORG-PLAN.md), so they stay off the pages and out of search.scripts/rewrite-repo-links.mjs. Code fences are left alone.SBX[0-9]or a pattern in moca'sdocs/.publish-denylist, the step skips Moca entirely, emits an Actions::warning, and lists the files. There is no bypass.docusaurus.config.ts: adds amocadocs instance (sidebarsMoca.ts, autogenerated) and a "Moca" navbar item. Both are added only whenmoca/index.mdexists. When the guard skipped the sync, the site builds exactly as before.src/theme/DocVersionBanner: a wrapper that shows "These pages track moca's main branch…" on Moca pages only. Other instances keep the stock banner.deploy.yamlcomments: document the new source, and thedocs-updateddispatch the moca repo will send.Testing
All local, on Node 26 with Docusaurus 3.10.1:
npm run typecheckrossoctl/moca@main(6db4171)moca/isn't created, and the build succeeds with no/mocaroutes and no navbar itemaiac-architecture.svgones; the banner shows on Moca pages and not on/docs/*; the "Moca" navbar item is present../../deploy/...and links into the excludedspecs/become GitHub URLs; in-tree links, absolute URLs, anchors and code fences are unchanged[unclosedline) withSBX1planted::errorand skips Moca; nothing publishedmoca@6db4171tree built without the guard (MDX question){id}paths inapi/CHANGELOG.mdandsbx/security-review.mdrender literally undermarkdown.format: 'detect'specs/page containing a denylisted term is excluded before the guard runs, so it isn't published and doesn't trip the guardFollow-ups
docs-dispatch.yaml(same as rossoctl/rossoctl's) anddocs/.publish-denylist: ci(docs): dispatch docs-updated to the rossoctl site; add the publish denylist moca#881. That repo needs aSITE_DISPATCH_TOKENsecret. Until it exists, the daily 06:17 UTC resync picks up changes./moca/*go live.Assisted-By: Claude Code