Skip to content

Latest commit

 

History

History
62 lines (42 loc) · 5.5 KB

AGENTS.md

File metadata and controls

62 lines (42 loc) · 5.5 KB

chttp AGENTS.md

chttp is a minimal HTTP router for node:http, async-first, zero dependencies, authored in the scriptc compilable subset so the same source compiles to a single native ELF. Workspace: packages/router (runtime) and packages/unplugin (build-time route-lowering plugin).

Commands

  • pnpm test - all workspace tests
  • pnpm --filter @chttp/router build - build runtime package
  • pnpm smoke:pack - pack router and val, compile the tarballs to an ELF with scriptc, curl it (run pnpm -r build first)
  • pnpm lint - oxlint (type-aware)
  • pnpm fmt - oxfmt
  • pnpm --filter @chttp/unplugin test - plugin tests
  • pnpm docs:build - build docs site
  • bash scripts/scriptc-gate.sh - 100% static coverage on all five scriptc gates (chttp-html, chttp-stream, chttp-val, static/gate, chttp-fetch). Every API change in packages/router is gated on this staying at 100%.

Releases

All packages/* publish at one shared version via pnpm native versioning (versioning.fixed in pnpm-workspace.yaml; pnpm change check guards drift in CI).

  1. pnpm change per logical change, commit the intent file with the change.
  2. At release: pnpm version -r (bumps the fixed group, consumes intents, writes CHANGELOGs), commit, tag v<version>.
  3. Tag push triggers .github/workflows/release.yml: verifies every package.json matches the tag, publishes all nine.

Full procedure in RELEASING.md, release notes in CHANGELOG.md (root entry generated by node scripts/changelog-root.mjs).

Publish and pack with pnpm only (pnpm publish, pnpm pack), never npm publish or npm pack. Internal ranges are workspace:^ and only pnpm rewrites them to real semver ranges in the tarball; npm would ship the workspace: protocol and break installs.

Scriptc subset rules (packages/router/src)

These are hard bans. The full rationale lives in ARCHITECTURE.md section 0.

  • Handlers/middleware may return a Promise; dispatch settles a non-settled chain result by awaiting it inside settleChain (the package's only async function; fire-and-forget). Sync-complete results — undefined, null, or the c object — keep a zero-microtask path via isSettled. NEVER detect promises by reading .then as a value (typeof r.then silently lowers to undefined), instanceof Promise (SC1090), or a union mixing Promise/non-Promise arms (SC2009).
  • | null unions only. Never undefined (SC3004).
  • No Object.create(null)/Object.freeze. Plain ({}) records only. Classes only for the router's entity types (Ctx, ReqView, sinks, HttpError).
  • Indexed for loops (and for...of over arrays). Never for...in.
  • No new Function/eval, no non-program instanceof, no object/method-shorthand.
  • Concrete types on all route/middleware tables; no any[]/unknown[] (SC1090).

contracts/route-contract.md is the frozen seam contract between runtime and generated dispatch. Do not diverge from it.

Typed client (src/client.ts)

  • Generic method calls dispatch only through ClientCore receivers — generic signatures on the Client<App> interface are signature-only to scriptc (SC1090). ELF consumers bind const c: ClientCore = createClient(u); gate apps do the same.
  • Record<ParamKey<P>, string> may appear only in the interface's .d.ts surface — any program code that names or converts it (assignment, as, field copy) fails SC2003/SC2009. That's why class method params take ClientInputCore, and ParamKey checking is Node-side only.
  • Reading a missing record key throws at runtime under scriptc ("record has no key" — typed slots can't represent undefined). Probe optional headers/fields with Object.prototype.hasOwnProperty.call(rec, k) before indexing, matching ReqView.
  • Overload signatures don't monomorphize (only the implementation signature does) — don't use them for subset code.
  • node:tls connect(port, host, {servername, rejectUnauthorized}) lowers as of 0.3.3 (verified in the gate); new URL lowers.

Conventions

  • Conventional commits, atomic commits (one logical change each).
  • Any handler or dispatch change ships with tests.
  • Any performance claim requires re-running the relevant bench cell first. bench/RESULTS-v2.md is the baseline.
  • Plugin work is fixture-first: fixtures/vite-app must build before an emit change lands. See packages/unplugin/AGENTS.md.

Web Standards compat

app.fetch(req: Request) → Promise<Response> is the canonical entry. app.handler() is a thin Node adapter around it. Both compile to a native ELF — the bench/apps/chttp-fetch.ts gate must stay at 100% static coverage.

No-bluff rule. Any sentence in user-facing docs (README, docs/, comments, or release notes) claiming chttp is "Web Standards compatible", "drops into the Hono ecosystem", or "runs on Cloudflare Workers" must be backed by a passing test. The gate for the Hono claim specifically is examples/integrations/hono-middleware/test/logger.test.ts — it imports logger from hono/logger unmodified, fires a real Request through app.fetch, and asserts the inbound log line. If that test is removed or skipped without a replacement, the matching sentence in the README must be removed in the same PR. PR review enforces this; no exceptions.

The full surface is documented in ARCHITECTURE.md under "Response sink and the two surfaces". The new ResponseSink class (packages/router/src/sink.ts) is the single seam that lets the same Ctx produce either a ServerResponse write or a Web Response finalization. Both subclasses stay inside the scriptc subset.