Contributing

Repository layout, the CI gates a change must pass, and how to verify work locally before opening a pull request.

Repository layout #

Zero dependencies is a constraint, not an accident #

package.json lists no dependencies and no devDependencies. Please keep it that way. It is why install works on a phone with no build toolchain, and why there is no transitive supply chain to audit.

Working with serve-time patches #

Each patched bundle has a getPatched*Bundle() function that reads the file, performs exact string replacements against minified code, memoises the result and returns a Buffer.

const ANCHOR_FROM = 'exact minified substring from the built bundle';
const ANCHOR_TO   = 'replacement';

if (raw.includes(ANCHOR_FROM)) {
  raw = raw.replace(ANCHOR_FROM, ANCHOR_TO);
  console.log('[MyPatch] applied');
} else {
  console.warn('[MyPatch] anchor not found');
  _criticalPatchFailures.push('my-patch');   // surfaces as a UI banner
}

Three rules when adding one:

• Anchor against the minified file, not pretty-printed source. Two patches were silently dead for weeks because their anchors were written from formatted code.
• Always log both outcomes and push to _criticalPatchFailures on miss. A silent failure is the worst case.
• Add the asset to RUNTIME_PATCHED_ASSET_PATHS in both server.mjs and public/sw.js. Miss this and the file ships immutable, pinning the unpatched body in browsers for a year.

CI gates #

13 workflows. These are the ones that will block a pull request:

The two drift checkers #

Both exist because a real bug got past review, and both fail loudly rather than warning.

# does isotope-complete.sql still match the live schema?
npm run schema:drift

# are all dollar-quoted SQL bodies balanced?
npm run sql:quotes

Verifying a change locally #

# 1 — syntax
node --check server.mjs
node --check public/sw.js
bash -n bin/isotope

# 2 — restart and confirm every patch anchor still matches
bash bin/isotope restart && sleep 6
grep -iE 'anchor not found|String not found' ~/.isotope/logs/server.log   # want no output

# 3 — every patched bundle must return 200 and parse
for f in Community-CEnEgsrd useAuthStore-Aw1au7RF index-D1Y5F8Lk; do
  curl -s "http://127.0.0.1:3000/assets/$f.js" -o /tmp/b.js
  node --check /tmp/b.js || echo "PARSE FAIL $f"
done

# 4 — test suite
npm run test:auth-bridge
npm run test:runtime-glue
npm run docs:validate

Editing these docs #

Plain HTML in docs/, one stylesheet, one script, no build step. Pages share the chrome verbatim — if you change the topbar, drawer, sidebar or footer, change it in every page or navigation drifts.

Conventions:

• <h2 id="x"> is required — the table-of-contents rail is generated from those ids at runtime.
• Wrap code in <div class="codeblock" data-lang="bash"> and a copy button is attached automatically.
• Callouts use an icon plus a label, never colour alone.
• Use semantic classes, not inline styles. Colour lives in the token block at the top of site.css.

npm run docs:validate

Commits #

Conventional prefixes — fix:, feat:, chore:, docs:. The body matters more than the subject: state what was wrong, why it was wrong, and how the fix addresses it. A future reader needs the reasoning, not a restatement of the diff.

• Never commit .env — CI fails if it becomes tracked.
• Commit before running isotope update; it stashes a dirty tree.
• Do not force-push shared branches.

Known open items #