Submodule Guide

This monorepo is consumed by parent repos (e.g., inspect_scout, inspect_ai) as a git submodule. This guide covers the submodule workflow for frontend contributors working in a parent repo.

Examples below use inspect_scout paths. The same patterns apply to any parent repo that embeds this monorepo as a submodule — just substitute the path:

• inspect_scout: src/inspect_scout/_view/ts-mono/
• inspect_ai: src/inspect_ai/_view/ts-mono/

How It Works

The parent repo pins this monorepo to a specific commit via a git submodule. The built dist/ is committed to the parent repo, so Python-only contributors and end users need no Node.js — they get the frontend automatically.

Only frontend contributors need to be aware of the submodule workflow.

One-Time Setup

Already have a clone, or just ran git clone without extra flags

The submodule directory exists but is empty. Run:

cd <parent-repo-root>
git submodule update --init
cd <submodule-path>
pnpm install

Cloning for the first time (and want submodules right away)

git clone --recurse-submodules <parent-repo-url>
cd <parent-repo-root>/<submodule-path>
pnpm install

Configure automatic submodule updates (strongly recommended)

By default, git pull in the parent updates the submodule pointer but does not update the submodule's working tree. This means your local code can silently fall out of sync. Set this once to avoid that entirely:

git config submodule.recurse true

With this setting, git pull automatically updates the submodule working tree to match the pinned commit. Without it, you must manually run git submodule update after every pull.

Development Workflows

UI-only changes

Changes that don't touch the Python API.

1. Branch in both repos:

   # Parent repo
   git checkout -b feature/my-ui-change
   
   # Monorepo (submodule)
   cd <submodule-path>
   git checkout -b feature/my-ui-change

2. Develop in the submodule (pnpm dev or pnpm watch), editing files under apps/ or packages/.

3. Build the production bundle:

   pnpm build  # outputs to the parent repo's dist/ path

4. Commit and push the monorepo branch, then open a PR:

   git add .
   git commit -m "feat: description of the change"
   git push origin feature/my-ui-change

5. Merge the monorepo PR through its normal review process. The PR may be squash-merged or rebased — that's fine.

6. Update the submodule to the merged commit. This is the critical step — switch to main and pull so the submodule is on a branch (not detached HEAD) at the commit that landed:

   cd <submodule-path>
   git checkout main
   git pull

7. Commit the submodule bump and dist in the parent repo:

   cd <parent-repo-root>
   git add <dist-path> <submodule-path>
   git commit -m "feat: description of the change"
   git push origin feature/my-ui-change

8. Merge the parent repo PR. CI validates that dist/ matches the submodule pointer.

Coordinated API + UI changes

Changes that require new or modified Python API endpoints.

1. Update the Python API models
2. Re-export the OpenAPI schema:

   .venv/bin/python scripts/export_openapi_schema.py

3. Regenerate TypeScript types (the types:generate script lives in apps/scout, not the monorepo root):

   cd <submodule-path>/apps/scout
   pnpm types:generate

4. Develop the frontend against the new types (pnpm dev)
5. Build and commit as in the UI-only workflow above, including the updated openapi.json and generated.ts

Using SSH Instead of HTTPS

The submodule URL in .gitmodules is HTTPS (works for everyone, including CI). To use SSH locally:

git config submodule.<submodule-path>.url git@github.com:<org>/<monorepo>.git

This is local-only and won't affect other contributors.

Git Commands Reference

All commands run from the parent repo root. The git -C <path> flag runs a git command as if you'd cd'd into that directory.

You can also keep a dedicated terminal cd'd into the submodule for day-to-day frontend work — whatever feels natural.

# Initialize the submodule (once)
git submodule update --init

# Update submodule after git pull
git submodule update

# Check which commit the submodule points to
git submodule status

# Advance submodule to latest upstream commit
git -C <submodule-path> pull

# Run any git command in the submodule from the parent root
git -C <submodule-path> status
git -C <submodule-path> log --oneline -5

# Auto-update submodule on pull (set once)
git config submodule.recurse true

FAQ / Troubleshooting

Q: I pulled but the frontend looks stale or broken.

You probably need to update the submodule working tree:

git submodule update

If you want this to happen automatically, set git config submodule.recurse true.

Q: The submodule is in "detached HEAD" state — is that normal?

Yes. The parent repo pins the submodule to a specific commit. When you run git submodule update, it checks out that exact commit, which results in a detached HEAD. To do development work, create a branch inside the submodule first.

Q: How do I check if my submodule is out of sync?

git submodule status

A + prefix means the submodule working tree is at a different commit than what the parent repo expects.

Q: CI says dist/ is mismatched — what do I do?

Rebuild from the submodule and commit the result:

cd <submodule-path>
pnpm install
pnpm build
cd <parent-repo-root>
git add <dist-path>
git commit -m "Rebuild dist"

Q: CI says openapi.json is mismatched — what do I do?

Re-export the schema from the Python API:

.venv/bin/python scripts/export_openapi_schema.py
git add <openapi-json-path>
git commit -m "Re-export openapi.json"

Q: CI says generated.ts is mismatched — what do I do?

Regenerate types from the committed openapi.json:

cd <submodule-path>/apps/scout
pnpm types:generate

Then commit the updated generated.ts in the monorepo.

Q: Markdown shows as raw source (and images, highlighting, links are missing) where I render shared components.

Rich rendering in @tsmono/react and @tsmono/inspect-components is opt-in: outside a ContentTrustProvider, content is treated as untrusted and shown as plain text. Wrap the tree in <ContentTrustProvider value="trusted"> (from @tsmono/react/components) for content you trust, or derive the value from the log it came from (logContentTrust(header) from @tsmono/inspect-components/content), as the Inspect viewer does.