diff --git a/.claude/skills/README.md b/.claude/skills/README.md index d146bea6..da43dbb0 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -17,4 +17,4 @@ These skills are opinionated about safety and never: run a package manager or `n Dependency installation and `npm run init` require consent. The init skill uses the declared dependencies; Composer's install hook already runs npm. Sibling dependency checkouts are maintainer work. After file changes, refresh the local graph with `graphify update .`. -Cleanup removes the Copilot-specific files under `.github` (`copilot-instructions.md`, `prompts/`, `instructions/`) and the starter's own repository files (`.gitattributes`, `CODEOWNERS`, the bug and feature issue forms and their `config.yml`, `labels.yml`, `SECURITY.md`); the `task` and `epic` issue templates, the PR template, `dependabot.yml`, and workflows stay. `sync-ai` restores only generated framework instructions. The Claude skills remain. Review these removals before personalizing a clone. +Cleanup removes the Copilot-specific files under `.github` (`copilot-instructions.md`, `prompts/`, `instructions/`) and the starter's own repository files (`.gitattributes`, `CODEOWNERS`, the bug and feature issue forms and their `config.yml`, `labels.yml`, `SECURITY.md`); the PR template, `dependabot.yml`, and workflows stay. `sync-ai` restores only generated framework instructions. The Claude skills remain. Review these removals before personalizing a clone. diff --git a/README.md b/README.md index 711caf0f..241801ff 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ This theme ships AI-assisted setup and feature scaffolding, kept in step across - **Claude Code:** retained skills in [`.claude/skills/`](.claude/skills/) — `/init`, `/scaffold`, and `/setup`. - **GitHub Copilot:** `/init` and `/scaffold` prompts are available while setting up this source repository. - - Initialization removes the Copilot-specific files under `.github` (`copilot-instructions.md`, `prompts/`, `instructions/`) and the starter's own repository files, such as `CODEOWNERS`, the issue forms and `SECURITY.md`; the `task` and `epic` issue templates, the PR template, and workflows stay. + - Initialization removes the Copilot-specific files under `.github` (`copilot-instructions.md`, `prompts/`, `instructions/`) and the starter's own repository files, such as `CODEOWNERS`, the issue forms and `SECURITY.md`; the PR template and workflows stay. - A committed knowledge graph in [`graphify-out/`](graphify-out/) lets AI assistants query the codebase's structure instead of reading it all; see [docs/internal/knowledge-graph.md](docs/internal/knowledge-graph.md) for how it's built and kept current. Shared conventions for all assistants live in [AGENTS.md](AGENTS.md). diff --git a/docs/hmr.md b/docs/hmr.md index a1679241..781e10da 100644 --- a/docs/hmr.md +++ b/docs/hmr.md @@ -56,7 +56,7 @@ Without `SCRIPT_DEBUG`, WordPress does not support Fast Refresh. 5. `start:blocks` starts a webpack dev server, using `webpack.blocks.config.js`. 6. JS/JSX changes to block components hot-swap in the editor without a full reload; block state is preserved. -`webpack.blocks.config.js` is a thin wrapper over `@wordpress/scripts`' default config. It exists only to strip the `devServer.proxy` option: webpack-dev-server v5 (pinned via the `overrides` block in `package.json`) requires `proxy` to be an array, while wp-scripts still emits the v4 object form, which v5 rejects with `options.proxy should be an array`. The wrapper also sets the dev-server port from `BLOCKS_DEV_SERVER_PORT`. +`webpack.blocks.config.js` is a thin wrapper over `@wordpress/scripts`' default config, which runs webpack-dev-server 6. It removes the `/build` proxy that wp-scripts adds: block HMR doesn't use it, and its target is hardcoded to `localhost:8887`, so with a custom port it would point at another server. The wrapper also sets the dev-server port from `BLOCKS_DEV_SERVER_PORT` and limits `allowedHosts` to `localhost` and `WP_HOST`. BrowserSync watches the following: @@ -175,4 +175,4 @@ This takes precedence over the auto-detected URL. **BrowserSync port**: BrowserSync requires its own port (3001) separate from your local site. Snippet mode keeps the site URL unchanged — proxy mode would change the URL and break WordPress redirects and cookie domains. -**WDS host validation**: WDS runs on `localhost:8887`. For custom local hostnames (e.g. `yoursite.local`), `allowedHosts: 'all'` is set in the webpack devServer config so the HMR WebSocket connection is accepted. +**WDS host validation**: WDS runs on `localhost:8887` by default. For custom local hostnames (e.g. `yoursite.local`), `webpack.blocks.config.js` sets `devServer.allowedHosts` to `localhost` plus your `WP_HOST` (rather than the blanket `all`) so the HMR WebSocket connection is accepted without exposing the dev server to DNS-rebinding. diff --git a/docs/initialization.md b/docs/initialization.md index d2c637ae..4c250288 100644 --- a/docs/initialization.md +++ b/docs/initialization.md @@ -60,7 +60,7 @@ npm run init -- --name="Acme Blog" --version=1.0.0 --yes --remove-examples | Optional features | HMR updates `.env.local`; Tailwind adds its entry/config and declarations. | | State | `.wp-scaffold.json` records identity and feature choices; do not hand-edit it. | | Autoload | Setup regenerates Composer's autoloader. | -| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, with the starter's own repository files: `.gitattributes`, `.github/CODEOWNERS`, the bug and feature issue forms and their `config.yml`, `.github/labels.yml`, `SECURITY.md`, and its release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-starter/`). A `composer create-project` copy never contains those repository files. The other workflows, the `task` and `epic` issue templates, the PR template, and `dependabot.yml` stay untouched. | +| Cleanup | Before the wrapper's final sync, the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` (including the starter POT file) are removed, with the starter's own repository files: `.gitattributes`, `.github/CODEOWNERS`, the bug and feature issue forms and their `config.yml`, `.github/labels.yml`, `SECURITY.md`, and its release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-starter/`). A `composer create-project` copy never contains those repository files. The other workflows, the PR template, and `dependabot.yml` stay untouched. | | AI instructions | After a successful change, the wrapper runs `sync-ai`; in a standalone project with the framework installed, it refreshes the generated framework PHP instructions. It does not restore the removed prompts or theme-specific rules. | | Retained files | Theme source, `bin/`, Claude skills, documentation, and test infrastructure remain; files belonging to removed example sets do not. | diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index f187759d..6a59d5d4 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -18,7 +18,7 @@ If an installation route or feature cannot be exercised, report the missing prer ### Cleanup checks -Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the starter's own repository files (`.gitattributes`, `.github/CODEOWNERS`, the bug and feature issue forms and their `config.yml`, `.github/labels.yml`, `SECURITY.md`) and its release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-starter/`), while the other workflows, the `task` and `epic` issue templates, and the PR template stay untouched. In a `composer create-project` copy, confirm those repository files were never there: `.gitattributes` export-ignores them, and its list must match `cleanup.targets` in `bin/scaffold.config.js`. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. +Check that the Copilot-specific `.github` files (`copilot-instructions.md`, `prompts/`, `instructions/`) and `languages` are removed, along with the starter's own repository files (`.gitattributes`, `.github/CODEOWNERS`, the bug and feature issue forms and their `config.yml`, `.github/labels.yml`, `SECURITY.md`) and its release workflow, config and manifest (`.github/workflows/release-starter.yml`, `.github/release-starter/`), while the other workflows and the PR template stay untouched. In a `composer create-project` copy, confirm those repository files were never there: `.gitattributes` export-ignores them, and its list must match `cleanup.targets` in `bin/scaffold.config.js`. Also confirm the init wrapper script is not removed by cleanup, and that `sync-ai` (see [initialization.md](../initialization.md#what-changes)) restores only generated framework instructions. Claude skills and documentation remain; Copilot prompts and theme-specific GitHub rules do not. Run POT generation separately to verify the language output can be recreated. Check references in retained documentation and AI instructions. Use upstream source links for optional examples or starter-only files that cleanup may remove. Do not silently change the cleanup contract as part of a documentation correction. diff --git a/webpack.blocks.config.js b/webpack.blocks.config.js index 984aea3b..00fec0a6 100644 --- a/webpack.blocks.config.js +++ b/webpack.blocks.config.js @@ -1,15 +1,11 @@ /** * Wrapper config for the `start:blocks` invocation. * - * Layered on top of wp-scripts' default config to fix the dev-server issue that - * bites during `wp-scripts start --hot` for blocks in this stack: - * - * webpack-dev-server v5 (resolved at the top level for the CVE-2025-30359 / - * CVE-2025-30360 fix) is what `webpack serve` loads, but `@wordpress/scripts` - * still defines `devServer.proxy` in the webpack-dev-server v4 object form, so - * v5's schema rejects it with "options.proxy should be an array". The bundled - * `/build` rewrite has no `target`, isn't needed for block HMR, and would fail - * at runtime even if converted to the v5 array form, so we remove it. + * Layered on top of wp-scripts' default config to adjust the webpack-dev-server + * 6 setup that `wp-scripts start --hot` runs for blocks. The stock config adds + * a `/build` proxy whose target is hardcoded to `localhost:8887`. Block HMR + * doesn't use it, and once the port comes from `BLOCKS_DEV_SERVER_PORT` it + * would point at whatever else listens on 8887, so we remove it. * * All dev-server knobs are read from `.env.local` so they can change without * editing this file. @@ -56,7 +52,7 @@ const devServerPort = toPort( * Apply the dev-server fixes to a single webpack config. * * @param {Object} singleConfig A webpack configuration object. - * @return {Object} The same config, dev-server v5 compatible. + * @return {Object} The same config, with the dev-server changes applied. */ const fixDevServer = (singleConfig) => { /* @@ -68,8 +64,8 @@ const fixDevServer = (singleConfig) => { } /* - * webpack-dev-server v5 requires `proxy` to be an array; wp-scripts ships a - * v4-style object. Not needed for block HMR, so drop it. + * wp-scripts adds a `/build` proxy hardcoded to localhost:8887. Block HMR + * doesn't need it, and with a custom port it would hit another server. */ delete singleConfig.devServer.proxy;