Skip to content

browser-runtime-dependency-audit.md

Latest commit

 

History

History
95 lines (72 loc) · 7.35 KB

browser-runtime-dependency-audit.md

File metadata and controls

95 lines (72 loc) · 7.35 KB

Browser Runtime Dependency Audit

This audit classifies dependencies by their role in the generic WP Codebox substrate. The dependency boundary is intentionally product-agnostic: host products may pass runtime ingredients into a sandbox, but WP Codebox dependencies must be justified by sandbox runtime, packaging, browser, build, or smoke-test needs.

Workspace Packages

Package Role Shipped Surface
@automattic/wp-codebox-core Runtime contract substrate. Defines backend-neutral policies, command registry, recipes, artifacts, task input, browser interaction shapes, and workspace policy helpers. Published package and bundled CLI release artifact. No WordPress or browser backend dependency.
@automattic/wp-codebox-playground Playground backend. Starts WordPress Playground, runs controlled WordPress commands, browser commands, previews, snapshots, and artifact capture. Published package and bundled CLI release artifact. Depends on @wp-playground/cli and playwright.
@automattic/wp-codebox-cli Runtime CLI. Parses recipes and command inputs, invokes the runtime packages, and writes artifact evidence. Published package, bundled CLI release artifact, and WordPress plugin vendor CLI bundle.
wp-codebox-wordpress-plugin WordPress plugin packaging. Registers parent-site abilities and the optional browser runtime script. Plugin zip only; not an npm runtime package.

Root Dependencies By Role

The root package acts as the installable workspace and release-staging package. Its dependency list intentionally includes direct pins for the CLI runtime plus the production dependency graph needed when packaging a self-contained CLI for the WordPress plugin zip.

Role Dependencies Why They Belong In WP Codebox
Runtime CLI @automattic/wp-codebox-cli, @automattic/wp-codebox-core, @automattic/wp-codebox-playground Local workspace package links and the package graph shipped in the CLI release artifact.
Playground backend @wp-playground/cli The Node backend that boots disposable WordPress Playground runtimes for CLI execution, previews, mounts, blueprints, and WP command execution.
Browser actions playwright Drives browser-backed runtime commands such as browser actions, probes, screenshots, and page metrics against a Playground preview.
WordPress plugin packaging node-linux-x64 and node-linux-arm64 fetched by scripts/package-release-artifact.ts; root production dependencies installed with npm install --omit=dev --omit=optional --ignore-scripts inside the release staging directory The plugin zip vendors a CLI bundle and a Node runtime fallback so a parent WordPress site can execute WP Codebox without relying on host package-manager setup.
Build, test, and smoke typescript, tsx, @types/node; shell tools used by scripts: npm, zip, unzip, tar TypeScript compilation and repo-local smoke scripts. These are development/build requirements, not browser runtime requirements.
Generated assets packages/runtime-*/dist, packages/cli/dist, dist/release/wp-codebox-cli, dist/wp-codebox-cli-*.tar.gz, packages/wordpress-plugin/dist/wp-codebox.zip Generated by npm run build, npm run release:package, and npm run package:wordpress-plugin. Release artifacts are rebuilt during release and are not source-of-truth dependencies.
Browser runtime asset packages/wordpress-plugin/assets/browser-runtime.js Checked-in plugin asset enqueued by the WordPress plugin and copied into the plugin zip. It uses the Playground browser client passed by the caller and has no npm dependency.
Transitive Playground dependencies Examples from npm ls: express, @wp-playground/storage, isomorphic-git, octokit, fs-extra, ws, tmp, semver, yargs Inherited from @wp-playground/cli and its storage/server stack. They are reviewed as part of the Playground backend provenance unless WP Codebox imports them directly.

Direct Runtime Imports

Runtime source imports are narrow:

Dependency Import Location Classification
@wp-playground/cli packages/runtime-playground/src/playground-cli-runner.ts Playground backend runtime dependency.
playwright packages/runtime-playground/src/browser-command-runners.ts; types in browser helper modules Browser actions runtime dependency.

The remaining production dependencies in the root manifest are either workspace package links, inherited dependencies made explicit for release staging, or transitive packages installed for the self-contained CLI bundle.

Browser Runtime Asset Boundary

packages/wordpress-plugin/assets/browser-runtime.js is checked in and packaged into the WordPress plugin zip. It attaches window.wpCodeboxBrowser and provides generic helpers for writing temporary PHP runner scripts through a caller-provided Playground browser client. Its built-in defaults are WP Codebox sandbox paths:

Default Value Classification
Runner directory /wordpress/wp-content/uploads/wp-codebox/runner Generic Playground WordPress uploads path for temporary runner scripts.
Runner URL base /wp-content/uploads/wp-codebox/runner Matching browser request path inside the Playground site.

The asset does not encode product-specific plugin slugs, project defaults, artifact targets, or control-plane assumptions. Callers provide recipes, task payloads, dependencies, and artifact files at runtime.

Packaging And Smoke Coverage

Packaging coverage is intentional:

  1. npm run build compiles the runtime packages and CLI package.
  2. npm pack --workspace @automattic/wp-codebox-cli --dry-run --json proves the CLI package includes compiled dist files and omits TypeScript source.
  3. npm run package:wordpress-plugin builds the plugin zip from source files, checked-in plugin assets, and the staged CLI release bundle.
  4. npm run package-distribution-smoke asserts the CLI pack shape and plugin zip shape, including the browser runtime asset and vendored CLI/Node runtime path.
  5. npm run browser-runtime-operation-smoke executes the checked-in browser runtime asset in a VM and verifies the generic operation helpers.
  6. npm run wordpress-plugin-smoke verifies the browser Playground session ability and runtime dependency metadata shape.

Provenance And Transfer Review

Transfer review should evaluate dependency provenance at these boundaries:

  1. Direct WP Codebox runtime dependencies: @wp-playground/cli and playwright.
  2. Build/dev dependencies: typescript, tsx, and @types/node.
  3. Release-staged production dependency graph installed into the CLI bundle.
  4. Node runtime tarballs fetched for plugin packaging (node-linux-x64, node-linux-arm64) and the fallback host Node path.
  5. Checked-in browser runtime asset and generated dist outputs rebuilt from source.

Security and license review should use the lockfile and packaged artifact smoke output as evidence. Product-specific dependencies should remain caller-provided runtime ingredients, not WP Codebox package dependencies.

Follow-Up Actions

No dependency move, removal, or new pin is required from this audit. If transfer review later rejects a package in the direct runtime, build/dev, release-staged, or Node-runtime bucket, track that as a focused follow-up against the affected boundary instead of adding host-product-specific code to WP Codebox.