Automattic / Automattic/wp-codebox

Reduce WP Codebox to one contained runtime execution boundary

Open
#2,429 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
16
Forks
4
Avg merge
59m
Merged PRs (30d)
131

Description

## Problem

WP Codebox has a clear architectural boundary: materialize a contained WordPress runtime, execute controlled work, and return verifiable artifacts. Its implementation surface now also includes multiple workload systems, overlapping execution envelopes, cross-language contract copies, host orchestration, and runtime-specific deployment machinery.

Measured on `main` at v0.26.1:

- `runtime-core`: 141 source files / 40,990 lines
- `runtime-playground`: 95 source files / 44,571 lines
- CLI: 61 source files / 26,787 lines
- WordPress adapter: 81 PHP source files / 34,856 lines
- 68 registered runtime commands
- 654 distinct versioned `wp-codebox/*/vN` schema identifiers across TypeScript, PHP, and docs
- 82 root package scripts and 190 root dependencies

The durable boundary in `docs/architecture.md` says Codebox is a runtime and artifact substrate, not a product, queue, evaluation harness, site generator, deploy service, or agent framework. The code should converge on that boundary.

## Desired shape

One canonical typed execution request enters Codebox. Codebox selects one independently built runtime backend, enforces policy, materializes inputs, executes, captures a minimal verifiable artifact bundle, and returns one canonical typed result. Parent systems own jobs, retries, review, apply, promotion, publication, and product policy.

```text
Host / Homeboy
-> canonical execution request
-> Codebox runtime boundary
-> independently built runtime backend
<- canonical result + artifact references + workspace delta
-> review / verify / apply / publish
```

Runtime implementations may stay in this monorepo. Each runtime must have its own dependency graph, build, tests, package artifact, and release readiness gate. The main CLI should depend only on the runtime or runtimes it actually embeds.

## Workstreams

- #2430 completes per-runtime build, test, dependency, and package isolation, beginning with `runtime-cloudflare`.
- #2431 collapses overlapping recipe, task, workload, package, plan, episode, and fanout request/result surfaces behind one canonical execution boundary.
- #2433 generates language and transport adapters from canonical contracts instead of maintaining TypeScript, PHP, browser, CLI, and Ability copies.
- Reduce the WordPress plugin to a thin host adapter.
- #2434 moves optional fuzzing, adversarial campaign, benchmark, and specialized quality systems out of `runtime-core` into composable extension packages.
- #2432 reduces the mandatory artifact contract to integrity, provenance, workspace delta, command results, and evidence references.
- Migrate known consumers, then remove compatibility aliases and obsolete execution paths rather than retaining permanent dual contracts.

## Existing trackers

- #1827 owns the Homeboy/Codebox orchestration authority split.
- #2402 completed the first gate/discovery correction.
- #1250, #1703, and #2384 track CLI/plugin release artifact and version-skew failures.
- #1838 tracks the Cloudflare runtime implementation, not its build isolation from the main CLI/runtime lane.

## Acceptance criteria

- The architecture map names one canonical request/result path and package ownership is mechanically enforced.
- Each runtime can install, build, test, and package without installing unrelated runtime dependencies.
- The main CLI artifact does not contain Cloudflare runtime code or dependencies.
- Host adapters translate transports but do not independently orchestrate execution lifecycle.
- Optional workload systems consume core contracts without expanding the mandatory core/CLI surface.
- Known consumers use canonical contracts and obsolete aliases/paths are deleted.
- Repository metrics show a material reduction in core, CLI, and WordPress-adapter maintenance surface.

## AI assistance

- **Model:** OpenAI gpt-5.6-sol
- **Tool:** OpenCode
- **Used for:** Inspected repository boundaries and measured source, contract, command, dependency, and test surfaces; searched existing issues; and drafted the consolidation tracker under Chris Huber's direction.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with docs/architecture.md and the linked workstreams #2430, #2431, #2432, #2433, and #2434 to map the proposed execution boundary and package ownership. Inspect the runtime, CLI, and WordPress adapter surfaces described in the issue before choosing a focused workstream. Done means the canonical path and ownership are enforced, unrelated runtime dependencies are isolated, obsolete paths are removed, and the stated acceptance criteria are met.

Written by the indexing model from the issue text.

Assessment

Tech stack
php, typescript, wordpress
Domain
backend, build-system, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.