oxcgen

Generate and normalize TypeScript and JavaScript through native Oxc/Oxlint policy before publishing source. Authored implementation files are TypeScript (.ts and .mts). Oxc builds the installable JavaScript into lib/.

Local use

bash scripts/bootstrap-local.sh
./dev npm run docs:preview

Bootstrap already runs release validation and installed-consumer checks. Node 24.20.0 is selected by ./dev. The native build uses pinned Oxc Rust and TypeScript-Go sources; revisions, archive checksums, Cargo.lock and go.sum are retained. package-lock.json owns the actual npm dependency tree. Keep vendor/ with source checkouts: the pinned Pi development dependency installs from a local tarball with the corrected AI dependency bundled. See LOCAL_SETUP.md and vendor/README.md; ./dev npm ci is the dependency-only reinstall command once the runtime is selected.

Generation

import { createOxcgen } from 'oxcgen';
const project = await createOxcgen({ cwd: process.cwd() });
try {
  await project.generate({
    files: [{ path: 'src/answer.ts', construction: {
      declarations: [{ kind: 'const', name: 'answer', type: 'number', value: 42 }],
    }}],
    publish: true,
  });
} finally {
  await project.close();
}

The built-in normalizers handle typescript/no-floating-promises, typescript/no-unsafe-assignment, and import/no-cycle. Semantic choices require explicit intent: awaiting a promise, introducing an unknown boundary or runtime validator, or permitting a proven type-only import. Other rules remain native acceptance constraints. Invalid candidates are rejected before publication.

Rust resolves effective per-file policy using the pinned initialized Oxlint implementation, including external JavaScript plugin options and provenance. The persistent Go host owns checked TypeScript programs and bounded type queries for immutable snapshot epochs. The verifier checks unchanged consumers alongside changed files, including creation and deletion overlays. No JavaScript TypeScript checker is used for generation; TypeScript 6 is a development dependency for Blume.

React compilation runs before lowering for the project's React 19 scope. Authored TSX and compiled JSX are separate artifacts. Compiled bytes must pass .oxlint.compiled.config.ts before they are returned as policy-verified artifacts. Verification sees accepted authored snapshot overlays, including new/deleted dependencies. Module-level React accounting is retained; per-function outcomes and recoverable bailouts are unavailable in the pinned NAPI.

inspect() returns version/hash/epoch-bound AST, native type facts, program membership and import graph sections. Queries require the prior snapshot identity; AST pagination limits returned projections, not pre-construction AST memory.

Publication and agents

Publication uses expected hashes, a cooperative lock and durable transaction journals. recoverPublications({cwd}) rolls back an interrupted transaction and refuses conflicting later edits. Visibility is per-file rename, not globally atomic across multiple files.

runRestrictedAgent provides OS-enforced project write restrictions on macOS and Linux (Landlock ABI 3+). Its JSONL broker allows publication only through generation and verification. Merely setting required mode or installing AGENTS.md does not restrict unrelated editors or agents. Enforcement is explicitly launched.

The Pi extension routes managed edit/write candidates and retains verification reports. Required-mode reports reuse publication receipts and edit diffs show normalized published bytes. /lint, /lint list, /lint show <id> and /lint check <literal-path> inspect or refresh reports. These overrides do not intercept shell or arbitrary filesystem writers.

oxcgen mcp serves the same capabilities to any Model Context Protocol host over stdio, as nine tools: oxcgen_doctor, oxcgen_catalog, oxcgen_policy, oxcgen_inspect, oxcgen_verify, oxcgen_facts, oxcgen_generate, oxcgen_publish and oxcgen_recover. Each tool advertises the request schema the engine already validates, so the published manifest cannot drift from the validator. A rejected candidate writes nothing. An MCP server answers its host's requests and cannot veto that host's own write tools, so required mode still depends on the host routing managed writes through oxcgen.

zed/ holds a Zed extension that registers oxcgen as a context server. It bundles nothing: it runs the project's own node_modules/.bin/oxcgen, falling back to PATH. It is not published to Zed's registry; install it as a dev extension.

Evidence

oxcgen is published to npm with optional per-platform binary packages (oxcgen-darwin-arm64, oxcgen-linux-arm64, oxcgen-linux-x64); npm installs only the one matching the consumer's os/cpu. See VALIDATION_STATUS.md. Original failed runs are retained in .oxcgen/local-runs/ when present. Local tests include test doubles; test:integration uses real dependencies. Production docs, browser checks, native benchmarks and the Docker clean-install runner have separate logs. The docs site deploys to GitHub Pages.