Skip to content

transfer-namespace-plan.md

Latest commit

 

History

History
176 lines (149 loc) · 8.62 KB

transfer-namespace-plan.md

File metadata and controls

176 lines (149 loc) · 8.62 KB

Transfer Namespace Plan

Historical note: this is a transfer planning record, not the current onboarding path or recipe contract reference. Start with README.md, architecture.md, and recipe-contract.md for current docs.

WP Codebox is moving from personal ownership assumptions toward Automattic ownership. This plan inventories the current personal namespace assumptions and defines the mechanical update path once the target package namespace and repository URL are chosen.

This is a planning document, not a rename. The repository does not currently contain evidence that fixes the final npm scope or canonical Automattic repo URL, so shipped code should keep its current names until those decisions are explicit.

Architecture Gate

WP Codebox must remain a generic, consumer-agnostic WordPress sandbox substrate. Namespace transfer work must separate WP Codebox ownership and package naming from product-specific consumers.

  • Generic WP Codebox contracts may name WP Codebox schemas, commands, package roles, plugin metadata, artifact shapes, and runtime backends.
  • Product-specific consumers may appear only as external examples, migration inventory, or caller-owned integrations.
  • Product, importer, compiler, benchmark, orchestration, company, and personal project names must not become WP Codebox package names, schema names, default runtime assumptions, or artifact contract fields.
  • External consumer docs should describe those projects as callers that pass recipes, mounts, runtime dependencies, and apply adapters into WP Codebox.

Decisions Required Before Rename

  • GitHub repository owner and URL: likely an Automattic-owned repository, but the exact canonical URL is not knowable from this repo alone.
  • npm package scope: choose the public scope for all WP Codebox packages, such as an Automattic-owned scope or another approved WordPress-adjacent scope.
  • Published compatibility policy: confirm whether any @chubes4/* packages have been published and need deprecation, forwarding packages, or compatibility release notes.
  • WordPress plugin ownership metadata: choose final Plugin URI, Author, and optional Author URI values for the plugin header.
  • Release authority: decide whether npm packages, the WordPress plugin zip, and standalone CLI tarballs are published from one coordinated release or separate release lanes.
  • External consumer migration policy: decide how callers update imports, fixture URLs, mounted repo metadata, and docs without making those consumers part of the WP Codebox contract.

Current Inventory

Package Names And Imports

  • packages/runtime-core/package.json names @automattic/wp-codebox-core.
  • packages/runtime-playground/package.json names @automattic/wp-codebox-playground and depends on @automattic/wp-codebox-core.
  • packages/cli/package.json names @automattic/wp-codebox-cli and depends on the core and Playground packages under the @chubes4 scope.
  • Root package.json depends on all three workspace packages under the @chubes4 scope.
  • package-lock.json mirrors the same workspace package names.
  • TypeScript imports in packages/cli/src, packages/runtime-playground/src, and scripts/*-smoke.ts import @automattic/wp-codebox-core or @automattic/wp-codebox-playground.
  • Compiled packages/*/dist files include the same package import strings and must be regenerated by npm run build after a package rename.

Repository URLs And Ownership Metadata

  • homeboy.json uses https://github.com/Automattic/wp-codebox.git as remote_url.
  • packages/wordpress-plugin/wp-codebox.php uses https://github.com/Automattic/wp-codebox as Plugin URI and Automattic as Author.
  • packages/wordpress-plugin/src/class-wp-codebox-artifacts.php references https://github.com/Automattic/wp-codebox/issues/176 for generic verifier issue guidance.
  • README and package docs include @chubes4 install/import examples and github.com/Automattic/wp-codebox issue URLs.
  • Generated-release packaging copies root and package package.json files into dist/release/wp-codebox-cli, so release metadata inherits the package names from source package manifests.

Docs And Examples

  • README.md names @automattic/wp-codebox-cli, @automattic/wp-codebox-core, and @automattic/wp-codebox-playground in install, release, smoke, and import examples.
  • README.md also links external example consumers such as wp-gym, world-of-wordpress, and wp-site-generator. These should remain external examples only; they are not WP Codebox namespace candidates.
  • packages/cli/README.md installs @automattic/wp-codebox-cli and references @automattic/wp-codebox-core.
  • packages/wordpress-plugin/README.md uses a https://github.com/Automattic/wp-codebox/issues/29 example issue URL in task context.
  • examples/recipes/cookbook/theme-block-editor-theme/style.css uses the personal WP Codebox repository as Theme URI.
  • examples/recipes/cookbook/README.md links external Extra Chill repositories as cookbook examples. Keep them framed as external fixtures/consumers, not as transfer targets.

Generated Artifact Metadata And Fixtures

  • tests/fixtures/task-input-normalization.json preserves github.com/Automattic/wp-codebox issue URLs in normalized task context.
  • tests/smoke-wordpress-plugin.php uses Automattic/wp-codebox repo and PR URLs in apply-adapter fixtures, audit assertions, and pending-action payloads.
  • tests/smoke-wordpress-plugin.php may include fake consumer plugin paths for component path behavior. Treat fixture names as external-consumer inventory; they should not define a WP Codebox contract.
  • Existing artifact schemas such as wp-codebox/*/v1, command ids such as wp-codebox.agent-sandbox-run, and the wp-codebox CLI binary are generic WP Codebox identifiers and should remain stable unless a separate API versioning decision says otherwise.

Target Shape

Use one generic WP Codebox package family under the approved target npm scope:

  • <target-scope>/wp-codebox-core
  • <target-scope>/wp-codebox-playground
  • <target-scope>/wp-codebox-cli

Use one canonical generic repository URL for WP Codebox docs, plugin metadata, release metadata, and issue links:

  • <target-repo-url> for repository links.
  • <target-repo-url>/issues/<number> for WP Codebox issue references that remain meaningful after transfer.
  • External consumer repositories should keep their own URLs only where docs are explicitly showing external examples.

Mechanical Update Checklist

After the target npm scope and repository URL are confirmed:

  • Update package names and internal workspace dependencies in package.json, packages/cli/package.json, packages/runtime-core/package.json, and packages/runtime-playground/package.json.
  • Run npm install to refresh package-lock.json with the new workspace package names.
  • Update TypeScript imports in packages/cli/src, packages/runtime-playground/src, and smoke scripts from @chubes4/* to the target package names.
  • Update package-related README install, import, smoke, and release examples.
  • Update homeboy.json remote_url after the canonical repo URL is known.
  • Update the WordPress plugin header Plugin URI, Author, and optional Author URI to the approved Automattic values.
  • Update generic WP Codebox issue URLs in docs, source comments, tests, and fixtures to the canonical repo URL where the issue numbers transfer cleanly.
  • Update generated fixture metadata such as source_ref when it is intended to describe WP Codebox source, while leaving external consumer refs intact.
  • Rebuild generated dist output with npm run build so compiled imports match the source package names.
  • Rebuild the WordPress plugin zip with npm run package:wordpress-plugin.
  • Run npm run smoke -- --group package to verify npm packing and plugin zip contents after the rename.
  • Run npm run check before publishing or tagging a release candidate.

Compatibility Notes

  • If @automattic/wp-codebox-* packages were already published, publish deprecation notices or compatibility packages according to the chosen npm migration policy.
  • If consumers pin @chubes4 imports, update those consumers in their own repos; do not add product-specific aliases to WP Codebox core.
  • If old artifact bundles contain Automattic/wp-codebox provenance, preserve them as historical evidence. New generated artifacts should use the target repo URL once the transfer rename lands.
  • Keep schema identifiers under wp-codebox/*/v1 because they describe the product-neutral WP Codebox contract, not the repository owner.