Development and Releases

Development and releases

Dashless is one repository containing the local Codex plugin, the WordPress companion, the generated Astro template, operating skills, tests, and documentation.

Repository map

Path	Responsibility
.codex-plugin/plugin.json	Installable plugin metadata and packaged capabilities
.mcp.json	Local Dashless MCP server declaration
server/dashless-mcp.mjs	Tool definitions and guarded editorial orchestration
server/lib/wordpress.mjs	WordPress REST client and content normalization
server/lib/storage.mjs	Connections, secrets, idempotency, staged changes, and preview locks
server/lib/setup.mjs	Loopback credential setup and disconnect lifecycle
server/lib/frontend.mjs	Astro creation, build, manifests, deployment, WP Cloud preflight, and verification
wordpress/	Conventional plugin and WP Cloud must-use companion
templates/astro/	Source copied into each generated Astro publication
skills/dashless/	Editorial behavior and production-content boundaries
skills/design-dashless-astro-sites/	Frontend art direction, QA workflow, and static audit
tests/	Node, PHP harness, template, release, deployment, and protocol tests
docs/	Version-controlled documentation sources and acceptance records
scripts/package.mjs	Deterministic release packaging and extraction smoke tests

Runtime requirements

The local MCP server uses only Node.js built-ins and requires Node 22.12 or newer. The Astro template has its own locked dependencies and installs them on the first build.

PHP is not used by the local server; it is required for WordPress and for PHP syntax checks during development.

Commands

npm test
npm run check
npm run test:coverage
npm run test:template
npm run test:wordpress:playground
npm run package
npm run release

npm test

Runs every tests/*.test.mjs suite with Node's built-in test runner.

npm run check

Runs JavaScript syntax checks, PHP syntax checks, and the complete Node suite. This is the normal local gate before a commit.

npm run test:coverage

Runs the Node suite with Node's experimental coverage report.

npm run test:template

Builds and exercises the real generated Astro template in isolation.

npm run test:wordpress:playground

Mounts the companion into the committed WordPress Playground compatibility fixtures. This is an additional integration check and uses @wp-playground/cli through npx.

npm run package

Creates deterministic Codex and WordPress ZIP archives, clean-extraction smoke-tests them, and writes dist/SHA256SUMS.

npm run release

Runs npm run check followed by npm run package. This is the complete local release gate.

Release artifacts

Version 1.0.0 produces:

• dist/dashless-1.0.0.zip
• dist/dashless-wordpress-1.0.0.zip
• dist/SHA256SUMS

Version metadata must agree in:

• .codex-plugin/plugin.json;
• package.json;
• server/dashless-mcp.mjs;
• the WordPress plugin header and bridge constant;
• wordpress/readme.txt;
• README release references; and
• CHANGELOG.md.

The release-metadata test fails when these disagree.

Continuous integration

The GitHub Actions release gate:

• runs npm run release on Ubuntu and macOS;
• verifies the published SHA-256 checksums;
• uploads the Linux release candidate;
• starts isolated oldest- and newest-supported WordPress versions with matching PHP versions;
• verifies activation, hooks, content generation, and the authenticated site contract; and
• runs WordPress Plugin Check against the packaged companion.

Static frontend audit

The site-director skill includes a dependency-free production audit:

node skills/design-dashless-astro-sites/scripts/audit-dist.mjs --project /path/to/generated/site

It checks generated markup, metadata, accessibility-critical structure, internal links, unsafe patterns, and bundle budgets. It complements Astro's compiler checks and visual inspection; it does not replace them.

Manual frontend gate

Before releasing a template change, inspect at least:

• wide desktop;
• ordinary mobile;
• narrow mobile;
• the homepage;
• a long story with media and structured content;
• nested Pages;
• archive and search routes;
• 404 behavior;
• day and night palettes;
• keyboard focus;
• reduced motion;
• missing-media fallbacks; and
• an empty WordPress state.

Real WP Cloud acceptance

A release that changes deployment or the companion should also prove on a fresh WP Cloud site:

1. Application Password setup
2. Key-based SFTP preflight
3. Companion install or safe upgrade
4. Astro project creation from real WordPress content
5. Exact draft preview and publication
6. Stable generation build
7. Immutable release upload and manifest verification
8. Public release ID and digest verification
9. Rollback to the previous release
10. Re-deployment of current canonical WordPress state

Record the host shape, WordPress and PHP versions, bridge version, release IDs, commands, and pass/fail result without recording credentials.

See the repository changelog and release checklist.