cutils is the utility monorepo for the chttp/scriptc ecosystem: @cutils/* packages for general-purpose utilities that own their own native dependency, and @chttp/* packages for request-scoped, web-server-concern utilities. Every package is authored in the scriptc-compilable subset so a consumer's scriptc build lowers the package with the app into a single static ELF.
pnpm test- all workspace testspnpm -r build- build every package (tsc)pnpm smoke:pack- pack every package, install the tarballs into a fresh app, assert each resolves from its dist entry pointscripts/scriptc-gate.sh-scriptc coverage100% on everypackages/*/gate.ts(run afterpnpm -r build)pnpm lint- oxlint,pnpm fmt- oxfmtpnpm docs:build- build the docmd docs site intodocs/site
All packages/* publish at one shared version via pnpm native versioning (versioning.fixed in pnpm-workspace.yaml; pnpm change check guards drift in CI).
pnpm changeper logical change, commit the intent file with the change.- At release:
pnpm version -r(bumps the fixed group, consumes intents, writes CHANGELOGs), thennode scripts/changelog-root.mjs, commit, tagv<version>. - Tag push triggers
.github/workflows/release.yml: verifies every package.json matches the tag, publishes all packages behind thenpm-publishenvironment approval. Agents must never approve or reject thenpm-publishenvironment themselves (nogh api ... pending_deploymentswrites) — leave the run pending for the repo owner to approve in the GitHub UI.
Full procedure in RELEASING.md, release notes in CHANGELOG.md.
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.
These are hard bans wherever a package ships in the subset (each package's AGENTS.md may add more). The shared rationale lives in ARCHITECTURE.md.
| nullunions only. Neverundefined(SC3004) — the one documented exception is@cutils/sqlite'sStmt.get, which shipsgetOrNullas the subset-strict twin.- No
Map/Set/Object.create(null)/Object.freezeunless a package's AGENTS.md documents a probe-verified exception (e.g.@cutils/cacheusesMap, lifted by the 0.3.3 probe). - Plain
({})records with full shapes; no function values inside records (indices into parallel class-side arrays instead). - Indexed
forloops (andfor...ofover arrays). Neverfor...in. No recursion where a call could monomorphizeunknown. - No
?./??, no object or method shorthand in literals, no spread, noeval/new Function, no non-programinstanceof. - Concrete types on all tables and class fields; no
any/unknown[]/object/{[k]: unknown}class fields —unknownmay only appear in parameters, returns, locals, and plain-record members. - Class generic parameters degrade instances to methodless shells on scriptc 0.3.x — narrow to non-generic core classes (
*Core) with a type-levelinterface X extends XCore+const X = XCorealias when a generic-looking surface is needed. - Union types of classes/records are the second poison:
A | Bwhere either is a class or a function-bearing record refuses.T | nullis the only allowed union arm.
using, await using, and for using are supported (scriptc ≥ 0.3.6; this repo pins 0.4.7). Disposal pairs with [Symbol.dispose] (@cutils/sqlite Database/StmtCore/Transaction) and [Symbol.asyncDispose] (@cutils/postgres, @cutils/mongo).
Two traps a contributor will hit without knowing them:
- The
usingvalue must be declared with its class type. Through aDisposable- or interface-typed variable, disposal throws SC2020 at declaration runtime — the static type has no concrete lowering for dispose. Recorded atpackages/sqlite/gate.ts("usingon a Stmt is impossible in-subset: the value's static type is theStmt<TRow>interface, which has no concrete lowering for dispose"). - Fences: top-level
usingis refused;await usingrequires an async context;[Symbol.asyncDispose]must return exactlyPromise<void>.
- Conventional commits, atomic commits (one logical change each).
- Plans live in
.agents/plans/<date>-<purpose>.mdand exist on disk before implementation (see.agents/backlog-policy.md). - Any behavior change ships with tests; every package's test suite includes a
scriptc coveragegate and an ELF smoke (test/elf.test.sh). - Any performance claim requires a bench cell first; v1 packages ship without perf claims.