sync-viewer-symlinks

Synchronize symlinks in site/viewer/lib/ so that the site viewer picks up all shared modules from src/viewer/assets/lib/.

Context

The site viewer (site/viewer/) shares most of its JavaScript and CSS with the agent viewer (src/viewer/assets/). Shared files are kept as symlinks in site/viewer/lib/ pointing into src/viewer/assets/lib/. A small set of site-specific files are standalone (not symlinked).

When new files are added to src/viewer/assets/lib/, the corresponding symlink in site/viewer/lib/ must be created manually. This skill detects and fixes any missing symlinks.

Standalone files (never symlinked)

Only these two top-level files in site/viewer/lib/ are site-specific real files (site keeps its own copy):

• script.js — site-specific entry point
• viewer_api.js — site-specific API transport layer (calls the in-browser WASM registry instead of the HTTP backend)

Everything else — including data.js — is a same-name symlink into src/viewer/assets/lib/. (There is no data_base.js; that was an older architecture. dashboards.js no longer exists.)

Coverage can be per-file OR a directory symlink

Most of site/viewer/lib/ is per-file symlinks, but some subtrees are covered by a directory symlink — e.g. site/viewer/lib/embed -> ../../../src/viewer/assets/lib/embed — which serves every file underneath it. So the invariant is resolution, not per-file-symlink presence: every shared module must resolve at the same relative path under site/viewer/lib/.

A tool that looks only for a per-file symlink (or a find that doesn't descend through a directory symlink) will false-flag files under a directory symlink. Test with [ -e "$link" ] (follows all symlinks), never [ -L ]. CAUTION: because site/viewer/lib/embed is a directory symlink into src/, writing to site/viewer/lib/embed/X writes through it into src/…/embed/X — never mkdir/ln inside a directory-symlinked path.

Enforced in CI

scripts/check-viewer-symlinks.sh implements this (resolution-based) check and runs on every PR via .github/workflows/viewer-symlinks.yml. Run it locally before pushing a viewer change: bash scripts/check-viewer-symlinks.sh.

Steps

1. Scan src/viewer/assets/lib/ recursively for all .js and .css files

2. For each source file, determine the expected path in site/viewer/lib/:

   • Skip the standalone top-level files script.js, viewer_api.js
   • Everything else → same relative path, which must resolve ([ -e ]) via either a per-file symlink or a covering directory symlink

3. Check whether the expected symlink exists and points to the correct target. Compute the relative path from the symlink location back to the source file (e.g., ../../../src/viewer/assets/lib/charts/chart.js for a file in site/viewer/lib/charts/).

4. Create any missing symlinks. Create parent directories if needed. Report each symlink created.

5. Detect any stale symlinks in site/viewer/lib/ that point to non-existent source files, and report them (but don't delete without asking).

6. Stage newly created symlinks with git add.

7. Report a summary: how many symlinks checked, how many created, any stale links found.

Pre-commit hook

A Claude Code hook at .claude/settings.json runs .claude/scripts/pre-commit-check.sh before every git commit. It blocks the commit if:

• Any shared viewer module fails to resolve under site/viewer/lib/
• Dashboard JSON is out of date with Rust definitions (only when src/viewer/dashboard/ or src/viewer/plot.rs files are staged)

The hook wiring (.claude/settings.json) is per-checkout Claude Code config, so the hook only fires for local Claude Code users — that is exactly why the symlink check is also enforced in CI (viewer-symlinks.yml → scripts/check-viewer-symlinks.sh), which is the binding gate for every PR. To set up the local hook on a fresh checkout, create .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/scripts/pre-commit-check.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

And copy or recreate .claude/scripts/pre-commit-check.sh (see the existing copy in this repo's working tree for reference).