Automattic / Automattic/wp-codebox

Generate language and transport adapters from canonical contracts

Open
#2,433 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.