wordpress-hx-sdk

wordpress-hx-sdk is a typed Haxe SDK and build toolchain for authoring ordinary WordPress plugins, themes, blocks, editor extensions, REST APIs, and related native artifacts.

It is the application/site-level alternative for teams that want a Haxe-first development experience without replacing WordPress Core. A project may begin with typed interfaces to existing WordPress, PHP, plugin, and browser code, then move only the bounded implementations it chooses into Haxe. A new site may instead use Haxe/HXX as its complete maintained code and configuration surface. Both paths emit ordinary native WordPress artifacts; handwritten PHP and JavaScript are optional interoperability tools, not required authoring layers.

Haxe inline HXX is the primary UI surface: typed components, props, children, slots, WordPress helpers, design refs, and real Haxe expressions lower at compile time to proportionate native PHP/HTML or Genes TSX. The generic PHP compiler owns reusable typed markup lowering; the WordPress profile adds native hierarchy/helper ergonomics. No HXX parser, component registry, VDOM, or template runtime ships with a site. Existing templates and raw/native code remain explicit checked escape boundaries.

Canonical source: github.com/fullofcaffeine/wordpresshx.

Status: bootstrap / pre-feasibility. There is no released SDK, supported compatibility profile, installable package, or production-readiness claim yet. The feasibility gates in the product requirements document decide when any narrower claim becomes valid.

Claim records use the evidence terms inventoried, typed, generated, runtime-tested, and production-supported; no earlier term implies a later one. Vanilla wp70-release, opt-in gutenberg-forward-23.4, and any future WordPressHx provider result remain separate fields. See ADR-001 for the exact qualification and correction rules.

The intended build flow is:

Haxe declarations and source
          |
          v
validated semantic build plan
          |
          +--> native PHP and templates
          +--> strict TS/TSX/JS and assets
          +--> WordPress metadata and packages
          |
          v
unmodified vanilla WordPress and Gutenberg

ADR-006 now fixes the versioned, canonical semantic-plan and staged-emitter boundary behind this flow. Its passing contract fixture validates identity, exact-profile binding, source spans, schema extensions, and complete artifact traceability; macro collection and production emission remain dependency-gated implementation work.

ADR-007 now defines the next boundary: exact path-and-hash ownership, complete staging, manifest-last publication, durable journal/backups, deterministic recovery, manifest-only clean, and explicit ownership relinquishment. Its real-filesystem contract fixture passes; the production SDK-041 Haxe/CLI owner and platform/runtime claims remain separate work.

ADR-016 selects the project-local wphx command and its one-command wphx dev loop. A small generated bootstrap locates the Haxe site authority; an exact project lock, deterministic effective-input graph, stable stages/diagnostics, canonical JSONL events, compatible isolated Haxe server, last-good publication, and typed WordPress/Next service contract keep watch mode reproducible. The contract fixture passes, and SDK-043 now implements the bounded build/check/inspect/ clean/doctor command foundation with exact project discovery and fail-closed publication. SDK-044 now implements and locally production-gate verifies the real compile/watch core, isolated compiler lifecycle, last-good rebuilds, and clean compiler shutdown, typed service supervision, and automatic WordPress reload. External services now enter an SDK-owned process-tree boundary so shutdown reaches their workers and watchers. On POSIX, a live sentinel owns the process-group identity. The Windows implementation uses a narrow native helper that allocates a private hidden console, creates the user process suspended, assigns it to a kill-on-close Job Object, and resumes it only after ownership exists. Its focused hosted Windows process-tree corpus passes normal, forced, rapid-replacement, and abrupt-supervisor cleanup without killing an unrelated process. This is process-ownership evidence, not a claim that Windows watcher or generated-output durability is supported. Neither platform path forces the Haxe parent to kill a stored, potentially reused PID. A generated plugin now needs only its existing WordPress.plugin() authority for wphx dev to derive, install, activate, and reload it in the exact WordPress 7.0/MariaDB provider. Next.js remains an optional integration boundary rather than a core dependency.

The product is not a WordPress fork, a replacement runtime, a generic CMS abstraction, or a proprietary site builder. The SDK and the separate full wordpress-hx port may share released generic compiler packages and public contracts, but neither project may import the other's unpublished implementation internals or merge its compatibility claims.

The longer-term architecture should compose with the maintainer's broader Haxe compiler and framework family through portable Haxe contracts, versioned semantic-plan/artifact schemas, immutable compiler packages, and independent evidence receipts. It must not acquire floating dependencies on sibling repositories merely to simulate that future integration.

Product authority

The canonical planning source is wordpress-hx-sdk-product-requirements.md. It defines the exact-profile MVP, architecture, feasibility gates, risk register, evidence contract, and bounded 90-day sequence.

Work is tracked in the repository's beads database:

bd prime
bd ready
bd show wordpresshx-sdk-000

The imported roadmap uses stable IDs matching the PRD (SDK-000 through SDK-111), explicit ADR beads (ADR-001 through ADR-022), and gate epics (G0 through G8).

Bootstrap check

The only repository-wide executable check at this stage validates the policy/layout skeleton and rejects direct dependencies on full-port internals:

bash scripts/check-repository.sh
bash scripts/ownership/test.sh
bash scripts/project-cli/test.sh
bash scripts/project-cli/test-production.sh
bash scripts/determinism/test-production.sh
bd lint
bd dep cycles

Compiler, profile, PHP, browser, WordPress, and package checks will be added by their dependency-gated beads; this bootstrap does not pretend those toolchains already exist.

Local safety hooks

Install and verify the tracked hooks in every clone or worktree:

bash scripts/hooks/install.sh
bash scripts/hooks/test.sh

They pin Haxe Formatter 1.18.0 and Gitleaks 8.30.0, format staged Haxe, reject machine-local paths, scan staged changes, and scan complete reachable history before push. Synchronize Beads through bash scripts/beads/push-safe.sh so decoded issue state and history are scanned before the separate Dolt ref is published.

Compiler direction

• PHP: continue the custom Reflaxe PHP compiler originating in wordpresshx-port as an independently structured generic package under compiler/reflaxe.php in this monorepo during 0.x. The SDK must not import the port's Core linker, original-path replacement machinery, or internal source paths. ADR-004 defines the boundary and later extraction triggers.
• Browser: use the sibling genes-ts project as the compiler authority. Any required change must be generalized in an isolated upstream worktree, protected by a non-WordPress regression fixture and the relevant full upstream suite, and submitted upstream before this repository pins it.

The browser-compiler selection baseline is the immutable genes-ts v1.33.0 release. SDK-031 preserves the historical v1.36.3 strict-fixture evidence, G2.5 preserves the v1.38.0 typed-linked-carrier adoption, and the active Gutenberg/browser package now pins v1.41.4 with the generalized React/hook foundation from upstream PR #74. Exact commits, trees, package digests, upstream PR/CI, and clean replays are recorded in the browser compiler pin. These are compiler-input and bounded fixture claims, not yet a complete WordPress browser support claim.

SDK-032 now layers typed Haxe inline markup over that boundary for the exact wp70-release React/Gutenberg profile. Its Haxe-only registration-proof page exercises Button, Notice, hooks, state, context, DOM refs, mouse and keyboard events, fragments, conditions, loops, and closed spreads, then verifies the generated TSX, real React runtime, accessibility structure, visual bundle, and source maps. SDK-033 adds exact dependency/asset/translation output, SDK-034 adds a real-Chromium browser trace CLI with exact esbuild composition and an authenticated two-stage fallback, and SDK-035 proves the bounded strict/classic Genes differential. Source correlation through the final official @wordpress/scripts entry also passes; remaining G2 follow-ups stay separately tracked, so G2 is not yet closed.

See CONTRIBUTING.md for the working agreement and docs/ for the documentation map.

Policies

• Governance
• Security
• Support
• Contribution workflow
• Provisional licensing review packet
• Release status

No repository-wide license or public distribution grant exists. ADR-020 now has a provenance-bound provisional GPL-2.0-or-later recommendation, generated-output origin model, component inventory, and machine-checked publication blocker; it remains proposed pending a named qualified reviewer, product-owner approval, and SDK-002 artifact/notice proof. Run python3 scripts/licenses/test-license-policy.py to verify that the inventory is complete and publication still exits closed.