Project Hub Demo

The hosted demo

Nothing in Demo/ reimplements the hub. The build runs the real Hub/hub.mjs against a fictional workspace, crawls every response it produces, and writes those out beside an unmodified copy of Hub/index.html. That is the entire design, and the property worth protecting: if the scanner changes, the demo changes with it, or the build fails loudly.

Which is why the demo build is wired into test.yml as an integration test, not just into the deploy. A red demo build usually means the interface moved, not that the demo broke.

node Demo/build-demo.mjs          # Node 18.17+ and Git. --keep leaves Demo/.build to inspect

Both Demo/.build and Demo/site are gitignored. Nothing generated is committed.

1. The five phases

Two details in phase 1-3 that are load-bearing:

• The configs are written at build time, never committed, so no config in the repo carries a path that is only true on one machine.
• GIT_CONFIG_GLOBAL/GIT_CONFIG_SYSTEM point at an empty file and GIT_AUTHOR_* is fixture-wide. The fixture repos cannot pick up the build machine's identity, signing keys or hooks, and no commit in the demo carries a real person's name or address.
• HOME/USERPROFILE are overridden because the scanner reads os.homedir() for the user CLI roots. Without it the published demo would show the build machine's skills.

2. The literal contract with index.html

Phase 5 rewrites Hub/index.html through sub(find, replace, expected), which throws if the match count is not exactly expected:

[!IMPORTANT] expected 4x "…" found 3 is not a demo bug. It means someone changed an asset URL in index.html, and the assertion caught it before it shipped a demo that half works. Fix the sub() call in the same commit as the interface change. See the project-hub-client skill.

Asset URLs cannot go through the shim because they are element attributes, not fetches — an <img src> never reaches patched fetch. They are rewritten to DEMO_ASSET(id), whose slug rule ([^A-Za-z0-9._-] → _) is implemented twice, in slug() in the build and in assetPath() in demo.js, because an <img src> cannot wait for a manifest to load. Change one and you must change the other; the build throws on a slug collision rather than silently overwriting a captured file.

3. What the shim answers, and what it refuses

demo.js is a classic script loaded before the app module, so fetch is already patched by the time the first request runs. It intercepts same-origin /api/* only, keyed by keyOf(url) — the same key the build recorded, with fresh and download dropped because neither changes the bytes.

Two endpoints answer honestly rather than failing:

• /api/open → 501 with a sentence saying opening files needs a local hub. A hosted page has no filesystem, and a status nobody can read is worse than a plain refusal.
• /api/pictures → 404, because no Pictures root is configured in the fixture.

Keep that pattern for anything new: say what is absent, do not let it look broken. The demo README's "what is real, and what is not" table is part of the deliverable — update it whenever this changes.

4. Changing the fixture

Ordinary markdown and config under Demo/Workspace/ and Demo/Home/, read by the same scanner that reads a user's. Rebuild to see it.

• New workspace → a folder under Workspace/Projects/ plus an entry in PROJECT_CONFIGS. There are three on purpose — one server mounting several workspaces is a thing worth showing, and one scopes by groups while two scope by pathPrefix so both forms are exercised.
• New repo → the folder plus a row in REPOS (dir, branch, state, author, commit). state is genuinely produced: ahead is an extra local commit, behind pushes one then resets back off it, dirty writes an uncommitted file. The mix is deliberate — a table where every row says clean demonstrates nothing.
• Repos/Draft/ has no .git by convention, so drafts are correctly absent from REPOS.
• Everything invented: every workspace, repo, person and domain is fictional, and commits use team@example.dev. Keep it that way.

5. Publishing

.github/workflows/demo.yml runs the same command on any push to main touching Hub/ or Demo/, and deploys Demo/site to Pages (concurrency: pages, a queued run supersedes an older one). The domain comes from Demo/static/CNAME; Pages must be set to "GitHub Actions" as its source in repo settings or the workflow has nowhere to publish. .nojekyll is written because Jekyll would drop underscore-prefixed paths and add nothing.

test.yml's demo-build job additionally asserts the capture is not empty and holds more than 100 API responses — the failure a green build would otherwise miss is a build that happily writes an empty site because the fixture stopped being found.

6. Checklist

1. node Demo/build-demo.mjs locally before pushing anything that touches Hub/ or Demo/.
2. A sub() failure → fix the sub() call, not the assertion count alone; confirm the rewritten interface still works.
3. New file extension in the fixture → TEXT/BINARY in the build and DOC_FILE / kindOfFile() in hub.mjs, or the node captures nothing.
4. New workspace or repo → the folder and its PROJECT_CONFIGS / REPOS row.
5. Serve Demo/site with a static server to check it — file:// cannot work, the shim answers root-relative paths.
6. --keep to inspect .build when the capture looks wrong.
7. Changed what the demo can or cannot do → update the table in Demo/README.md.

7. Anti-patterns

• Hand-editing anything in Demo/site. It is generated and gitignored; fix the build.
• Faking a response the hub never produced. The capture's whole value is that it came from the real scanner.
• Loosening a sub() count to make the build pass. That assertion is the regression test.
• Letting a missing capability fail silently. 501/404 with a sentence, like /api/open.
• Real names, real domains, or a real person's commits in the fixture.
• Committing a config with an absolute path. Phase 1 writes them for a reason.

Related