Skip to content

Feat: Add a Moca docs section synced from rossoctl/moca behind a publish guard - #227

Merged
pdettori merged 2 commits into
rossoctl:mainfrom
pdettori:feat/moca-docs-instance
Nov 18, 2026
Merged

pdettori merged 2 commits into
rossoctl:mainfrom
pdettori:feat/moca-docs-instance

Conversation

@pdettori

@pdettori pdettori commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR adds a Moca section to rossoctl.dev at /moca/*. The content is synced at build time from rossoctl/moca:docs/, the same way the Docs section comes from rossoctl/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:
    • Clones rossoctl/moca (sparse checkout of docs/; MOCA_REF defaults to main, MOCA_SRC_REPO takes a local clone) into the git-ignored moca/.
    • 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.
    • Rewrites relative links that leave the published tree to the file on GitHub, using the new scripts/rewrite-repo-links.mjs. Code fences are left alone.
    • Publish guard: if any file to be published matches SBX[0-9] or a pattern in moca's docs/.publish-denylist, the step skips Moca entirely, emits an Actions ::warning, and lists the files. There is no bypass.
  • docusaurus.config.ts: adds a moca docs instance (sidebarsMoca.ts, autogenerated) and a "Moca" navbar item. Both are added only when moca/index.md exists. 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.
  • README and deploy.yaml comments: document the new source, and the docs-updated dispatch the moca repo will send.

Testing

All local, on Node 26 with Docusaurus 3.10.1:

Case Result
npm run typecheck passes
Sync against rossoctl/moca@main (6db4171) Guard fires on 9 files, moca/ isn't created, and the build succeeds with no /moca routes and no navbar item
Sync from a local moca tree with the proposed new pages (66 pages) Build succeeds; the only 2 warnings are the existing aiac-architecture.svg ones; the banner shows on Moca pages and not on /docs/*; the "Moca" navbar item is present
Link rewrite ../../deploy/... and links into the excluded specs/ become GitHub URLs; in-tree links, absolute URLs, anchors and code fences are unchanged
Malformed denylist (a [unclosed line) with SBX1 planted grep exits 2, the sync emits an ::error and skips Moca; nothing published
Code in links (review) Links inside 4-backtick, indented, tilde and list-nested fences, and inside inline code spans, are left as written; prose links are rewritten
moca@6db4171 tree built without the guard (MDX question) Build exits 0; {id} paths in api/CHANGELOG.md and sbx/security-review.md render literally under markdown.format: 'detect'
Excluded design records A specs/ page containing a denylisted term is excluded before the guard runs, so it isn't published and doesn't trip the guard

Follow-ups

  • rossoctl/moca: a docs-dispatch.yaml (same as rossoctl/rossoctl's) and docs/.publish-denylist: ci(docs): dispatch docs-updated to the rossoctl site; add the publish denylist moca#881. That repo needs a SITE_DISPATCH_TOKEN secret. Until it exists, the daily 06:17 UTC resync picks up changes.
  • rossoctl/moca: the new landing, quickstart and operate pages, plus scrubbing the pages the guard flags. This is the PR that makes /moca/* go live.

Assisted-By: Claude Code

…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>
@netlify

netlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

👷 Deploy request for animated-crumble-fb8862 pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit a473204

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread scripts/sync-docs.sh Resolved
Comment thread scripts/rewrite-repo-links.mjs Resolved

@ingpaolodettori-dev ingpaolodettori-dev left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread scripts/sync-docs.sh
# 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[@]}"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 build exited 0, with 0 errors.
  • build/moca/api/CHANGELOG/index.html contains v1/sandboxes/{id}/token literally.
  • build/moca/sbx/security-review/index.html contains /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?

Comment thread sidebarsMoca.ts Outdated
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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 15:32
pdettori added a commit to pdettori/moca that referenced this pull request Nov 18, 2026
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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread scripts/sync-docs.sh
# 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,})(.*)$/;
pdettori added a commit to pdettori/moca that referenced this pull request Nov 18, 2026
… 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>
pdettori added a commit to pdettori/moca that referenced this pull request Nov 18, 2026
…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>
pdettori added a commit to pdettori/moca that referenced this pull request Nov 18, 2026
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 ingpaolodettori-dev left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. -I makes a file that looks binary invisible to the guard: a staged index.md containing a NUL byte followed by SBX7 exits 1 and publishes. Using -a (still with -l) or refusing binary-looking files before publication closes it.
  2. 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 excluded demos/), 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)

@pdettori
pdettori merged commit eeec4b1 into rossoctl:main Nov 18, 2026
1 check passed
@github-project-automation github-project-automation Bot moved this from New/ToDo to Done in Rossoctl Issue Prioritization Nov 18, 2026
pdettori added a commit to pdettori/moca that referenced this pull request Nov 18, 2026
…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>
pdettori added a commit to pdettori/moca that referenced this pull request Nov 18, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants