react-foldkit-converter

A deterministic compiler for a deliberately restricted, typed React component profile. It parses TypeScript/TSX without executing application code, emits source-located IR, applies source-hashed adaptations, and generates canonical Foldkit modules.

This is not an arbitrary React application transpiler. Unknown lifecycle, state identity, dynamic composition, or runtime code-generation semantics fail closed.

Commands

react-foldkit sync      Mirror an explicitly pinned local upstream checkout.
react-foldkit analyze   Print canonical IR and diagnostics.
react-foldkit propose   Ask a project-scoped OMP ACP agent for an untrusted proposal.
react-foldkit promote   Validate a proposal twice and promote only deterministic output.
react-foldkit generate  Atomically replace generated sources.
react-foldkit verify    Regenerate twice and compare the checked-in tree.
react-foldkit check     Analyze, generate, and verify.

Every command except propose, promote, and sync is offline. propose gives OMP a disposable workspace and advertises only bounded file reads/writes through ACP. The agent cannot write accepted adaptations or generated output. promote treats its result as untrusted data and rejects stale hashes, orphaned patches, forbidden plugin imports, remaining errors, and nondeterministic generation.

Typed plugins are single-file, pure IR transforms. They run under Node's permission model with no network, filesystem writes, subprocesses, workers, or native addons; only the runner itself is readable. Runtime imports and dynamic imports are rejected before execution. Each plugin has a five-second limit, a 64 MiB heap limit, bounded output, and may not change IR cardinality, component identity, or source hashes. Set REACT_FOLDKIT_NODE only when the node executable is not on PATH; the executable must support --permission.

Configuration

{
  "schemaVersion": 1,
  "sourceRoot": "sources/current",
  "outputRoot": "src/generated",
  "acceptedPatchRoot": "adaptations/patches",
  "acceptedPluginRoot": "adaptations/plugins",
  "sourceLock": "sources/source-lock.json",
  "provenanceOutput": "provenance.json",
  "ompProfile": "react-foldkit"
}

Generated files are replaceable artifacts. Put every durable exception in a source mirror, declarative patch, reviewed capability, or typed plugin.

Determinism contract

For identical source bytes, config, accepted patches/plugins, converter revision, and toolchain lock, generate writes identical UTF-8 files, ordering, hashes, and diagnostics. Source mirrors are immutable by revision. Patches bind to the SHA-256 of the source file and must match exactly one component and diagnostic.

Development

bun install --frozen-lockfile
bun run ready

The repository uses TypeScript 7 for the toolchain and a separately pinned TypeScript 6 Compiler API alias. TypeScript 7 intentionally exposes its new compiler API under unstable entrypoints; keeping the parser on the stable API prevents an accidental frontend rewrite.