Automattic / Automattic/wp-codebox
Generate language and transport adapters from canonical contracts
- Dominant language
- TypeScript
- Stars
- 16
- Forks
- 4
- Avg merge
- 59m
- Merged PRs (30d)
- 131
Description
Parent: #2429
## Problem
The same public concepts are represented across TypeScript exports, JSON schemas, PHP arrays and DTO builders, WordPress Ability descriptors, WP-CLI wrappers, browser SDK DTOs, and prose documentation. The repository currently contains hundreds of versioned schema names and WordPress adapter code devoted to schema and result normalization.
This duplication makes every contract change a multi-language synchronization task and encourages compatibility aliases instead of migration and deletion.
## Desired shape
Maintain canonical machine-readable contracts in one owner package. Generate transport/language adapters where generation is mechanical, and keep handwritten code only for behavior that genuinely differs by environment.
Generated or mechanically verified outputs should include:
- JSON Schema;
- TypeScript types and validators;
- PHP schema/DTO definitions used by the WordPress adapter;
- Ability input/output descriptors;
- CLI and browser SDK contract manifests;
- concise reference documentation.
## Acceptance criteria
- Every public schema has one declared canonical source.
- PHP, TypeScript, browser, CLI, and Ability surfaces prove parity against that source in one contract test lane.
- Ability aliases are inventoried with known consumers and a bounded removal release.
- New compatibility aliases require an identified persisted/external compatibility need and a removal plan.
- Generated files are reproducible and checked for drift.
- Handwritten schema duplication in the WordPress plugin is materially reduced.
- Public documentation links to generated contract references rather than restating complete schemas in multiple files.
## AI assistance
- **Model:** OpenAI gpt-5.6-sol
- **Tool:** OpenCode
- **Used for:** Measured cross-language contract proliferation and drafted the canonical-source and adapter-generation work under Chris Huber's direction.
Contributor guide
No contributing guide indexed for this repository
Research direction
No files, tests, or entry points are named. Start by locating the owner package and inventorying the TypeScript, PHP, JSON Schema, Ability, CLI, browser SDK, and documentation surfaces described; use the proposed contract test lane and reproducibility checks to define done.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, typescript, wordpress
- Domain
- backend-api-design, documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100