Workflows

Architecture work using Confluence

1. Check local source availability with npm run confluence:status.
2. If no cache exists, or current upstream state matters, run:

   mit-secrets run --profile rws-confluence-architecture -- \

     npm run confluence:sync

1. Search .cache/confluence/snapshots/<snapshot-id>/pages/ using ordinary

filesystem tools.

2. Record relevant page IDs and observed versions in authored architecture or

analysis conclusions.

3. Commit only authored work. Never add .cache/.

npm run confluence:reset performs the same safe synchronization while forcing a complete re-read. It does not erase the last usable snapshot before a replacement has passed generation and validation.

Portal runtime refresh

The deployment worker runs npm run confluence:sync -- --cache-root /cache/confluence on startup and on its configured cadence. Each run:

1. Discovers all INFRAARCH pages dynamically.
2. Fetches page storage and approved metadata with read-only requests.
3. Produces private source files and sanitized public artifacts.
4. Publishes a new current pointer atomically.
5. Retains the last good snapshot if collection or generation fails.
6. Keeps only current and previous generations after success.

The portal initially shows no pages when no current.json exists. A user-facing retry action rereads cache status; it does not trigger a privileged sync request. Operators wipe and resync by restarting the worker or running the reset command inside its controlled environment.

The portal additionally offers Sync from Confluence and Copy main cache. They call deployment-owned, same-origin control endpoints and poll their status; the application contains no OIDC or authorization policy. A deployment may truthfully return 401 when the user is not authorized or 404 when controls are not installed. Both actions atomically replace the runtime pointer only after success; there is no reset or wipe action in the portal.

The browser waits up to ten minutes. Reaching that client limit means the operation may still be running; users should refresh status before retrying.

For a local, sanitized-public-only copy from a portal runtime root, run:

npm run confluence:import -- --from https://portal.example/runtime/confluence \

  --cache-root .cache/confluence

Import needs no Confluence token. It validates current, manifest, navigation, the complete tree, and every inert page artifact before publication. Preview caches remain independent from the main cache; Copy main cache copies one validated immutable generation rather than mounting or sharing main storage.

Validation

npm run validate:confluence-cache

npm run validate:all

npm run test --workspace @rws-arch-wb/portal

npm run build:portal

npm run verify:portal-browser

npm run evidence:preview

The cache validator uses a hermetic fake Confluence server and proves pagination, retry behavior, sanitization, private searchability, atomic failure handling, reset semantics, retention, sanitized import rejection, and maximum-page guards.

Pull requests

Forgejo CI validates authored content and the content-free portal build. It does not receive a Confluence credential and does not synchronize real content. PR preview deployments build the branch and use their deployment-provided runtime cache configuration.