Skip to content

Commit e9b94ee

Browse files
ashleyshawashleyshaw
committed
Restore test-dry-run.js wrapper and validate generate-theme agent/question mapping
1 parent c76bed7 commit e9b94ee

31 files changed

+1672
-139
lines changed

‎.github/agents/a11y.agent.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ This document provides actionable, block-theme-specific accessibility guidance a
3939

4040
WordPress block themes should aim for full WCAG AA compliance in practice, even when the “Accessibility Ready” tag in the directory only reflects minimum thematic requirements.
4141

42-
---
42+
## Wizard Integration
43+
44+
## This agent uses the pluggable wizard.js interface for configuration. Supports at least 'cli' and 'mock' modes for interactive and test/dev use. The agent's questions array is passed to runWizard(), and the mode can be set via the WIZARD_MODE environment variable.
4345

4446
## Applicability
4547

‎.github/agents/code-quality.agent.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Code Quality Agent Specification
2+
3+
## Purpose
4+
5+
Run linting, testing, and code quality checks for the block theme scaffold. Outputs are stored in `.github/reports/validation/`.
6+
7+
## Wizard Integration
8+
9+
This agent uses the pluggable wizard.js interface for configuration. Supports at least 'cli' and 'mock' modes for interactive and test/dev use. The agent's questions array is passed to runWizard(), and the mode can be set via the WIZARD_MODE environment variable.
10+
11+
## Usage
12+
13+
- Interactive: `node scripts/agents/code-quality.agent.js`
14+
- Dry-run: `WIZARD_MODE=mock node scripts/agents/code-quality.agent.js`

‎.github/agents/generate-theme.agent.md‎

Lines changed: 117 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,100 @@ I'm your interactive block theme generator. I'll guide you through a series of q
1414

1515
---
1616

17-
**Wizard Integration:**
18-
This agent uses an interactive wizard (see scripts/lib/wizard.js) for advanced flows. The wizard now supports loading a plugin-config JSON file as an alternative to manual entry. Pass a config file path to pre-fill or skip questions.
17+
## Mustache Variables Reference
18+
19+
The following mustache variables are available for use in the theme scaffold. These are populated by the wizard, config file, or automation:
20+
21+
| Variable | Description | Example Value |
22+
| ----------------------- | ----------------------------------------- | ------------------------------------------- |
23+
| `{{name}}` | Theme display name | "Tour Operator" |
24+
| `{{slug}}` | Theme slug (URL-safe, lowercase, hyphens) | "tour-operator" |
25+
| `{{author}}` | Author name | "LightSpeed" |
26+
| `{{author_uri}}` | Author website URL | "https://lightspeedwp.agency/" |
27+
| `{{description}}` | Theme description | "A modern block theme for travel sites" |
28+
| `{{namespace}}` | PHP namespace (auto from slug) | "tour_operator" |
29+
| `{{textdomain}}` | Text domain (auto from slug) | "tour-operator" |
30+
| `{{license}}` | License short name | "GPL-3.0-or-later" |
31+
| `{{license_uri}}` | License URL | "https://www.gnu.org/licenses/gpl-3.0.html" |
32+
| `{{version}}` | Initial version (semver) | "1.0.0" |
33+
| `{{min_wp_version}}` | Minimum WordPress version | "6.5" |
34+
| `{{tested_wp_version}}` | Tested up to WordPress version | "6.7" |
35+
| `{{min_php_version}}` | Minimum PHP version | "8.0" |
36+
| `{{primary_color}}` | Primary brand color (hex) | "#0073aa" |
37+
| `{{secondary_color}}` | Secondary color (hex) | "#005177" |
38+
| `{{background_color}}` | Background color (hex) | "#ffffff" |
39+
| `{{text_color}}` | Text color (hex) | "#1a1a1a" |
40+
| `{{font_family}}` | Body font family (CSS) | "system-ui" |
41+
| `{{heading_font}}` | Heading font family (CSS) | "inherit" |
42+
| `{{hero_title}}` | Homepage hero title | "Welcome" |
1943

20-
**How to use the config file option:**
44+
---
45+
46+
---
2147

22-
- Run the agent with a config file: `node generate-theme.agent.js --config path/to/plugin-config.json`
23-
- The wizard will load values from the file and use them as defaults or skip manual entry if all required fields are present.
48+
## Wizard Integration & Advanced Features
49+
50+
This agent uses an interactive, multi-stage wizard (see `scripts/lib/wizard.js`) with the following advanced features:
51+
52+
- **Conditional Logic:**
53+
- Optional questions (e.g., design tokens, initial content) are only asked if the user opts in.
54+
- The wizard adapts based on previous answers (e.g., skips font/color questions if user says "skip").
55+
- **Config File Automation:**
56+
- You can provide a config file to pre-fill or fully automate the wizard:
57+
- `node generate-theme.agent.js --config path/to/theme-config.json`
58+
- The wizard will use values from the config file as defaults, skipping prompts for fields that are present and valid.
59+
- If required fields are missing or invalid, the wizard will prompt only for those.
60+
- **Dry-Run/Mock Mode:**
61+
- Run with `WIZARD_MODE=mock` or `--dry-run` to simulate the wizard and generation process without writing files.
62+
- Useful for CI, validation, and testing automation.
63+
- **Validation & Error Recovery:**
64+
- Each answer is validated (see Validation Rules below).
65+
- If a value is invalid, the wizard will explain the error and prompt for correction or suggest a fix.
66+
- For config files, invalid or missing fields are reported with actionable errors.
67+
- **Explicit Mapping:**
68+
- Every wizard step maps directly to a mustache variable and config schema field (see tables below).
69+
- The config file can include any/all variables; missing optional fields use defaults.
70+
71+
### Example: Using a Config File
72+
73+
```json
74+
{
75+
"name": "Safari Lodge Theme",
76+
"slug": "safari-lodge",
77+
"author": "LightSpeed",
78+
"author_uri": "https://lightspeedwp.agency/",
79+
"description": "A luxurious WordPress theme for safari lodges and eco-tourism",
80+
"version": "1.0.0",
81+
"min_wp_version": "6.5",
82+
"tested_wp_version": "6.7",
83+
"min_php_version": "8.0",
84+
"primary_color": "#0073aa",
85+
"secondary_color": "#005177",
86+
"background_color": "#ffffff",
87+
"text_color": "#1a1a1a",
88+
"font_family": "system-ui",
89+
"heading_font": "inherit",
90+
"hero_title": "Welcome"
91+
}
92+
```
93+
94+
Run:
2495

25-
If the config file is missing or invalid, the wizard will fall back to manual prompts.
96+
```
97+
node generate-theme.agent.js --config ./theme-config.json
98+
```
99+
100+
### Example: Dry-Run/Mock Mode
101+
102+
```
103+
WIZARD_MODE=mock node generate-theme.agent.js --config ./theme-config.json
104+
# or
105+
node generate-theme.agent.js --dry-run
106+
```
107+
108+
This will run all validation and show the steps, but will not write or modify any files.
109+
110+
---
26111

27112
## How I Work
28113

@@ -43,19 +128,17 @@ To start generating a new theme, simply say:
43128
44129
---
45130

46-
## Question Stages
131+
## Question Stages & Variable Mapping
47132

48133
### Stage 1: Core Identity (Required)
49134

50-
| Question | Variable | Example | Validation |
51-
| ------------------- | ----------------- | --------------------- | ---------------------- |
52-
| Plugin display name | `{{name}}` | "Tour Operator" | Min 2 chars |
53-
| Plugin slug | `{{slug}}` | "tour-operator" | Lowercase, hyphens |
54-
| Description | `{{description}}` | "Tour booking plugin" | Any text |
55-
| Author name | `{{author}}` | "LightSpeed" | Min 2 chars |
56-
| Author website | `{{author_uri}}` | "https://example.com" | Valid URL |
57-
| Initial version | `{{version}}` | `1.0.0` | SemVer (e.g., `x.y.z`) |
58-
| License | `{{license}}` | `GPL-3.0-or-later` | SPDX identifier |
135+
| Question | Variable | Example | Validation |
136+
| ------------------ | ----------------- | ------------------------------ | ------------------ |
137+
| Theme display name | `{{name}}` | "Tour Operator" | Min 2 chars |
138+
| Theme slug | `{{slug}}` | "tour-operator" | Lowercase, hyphens |
139+
| Author name | `{{author}}` | "LightSpeed" | Min 2 chars |
140+
| Author URI | `{{author_uri}}` | "https://lightspeedwp.agency/" | Valid URL |
141+
| Description | `{{description}}` | "A modern block theme" | Min 5 chars |
59142

60143
**Auto-generated values:**
61144

@@ -65,7 +148,7 @@ To start generating a new theme, simply say:
65148
| `{{textdomain}}` | `{{slug}}` | `tour-operator` |
66149
| `{{license_uri}}` | `{{license}}` | `https://www.gnu.org/licenses/gpl-3.0.html` |
67150

68-
### Stage 2: Versioning (Has Defaults)
151+
### Stage 2: Versioning (Defaults Provided)
69152

70153
| Question | Variable | Default | Notes |
71154
| ----------------- | ----------------------- | ------- | ------------------------- |
@@ -87,11 +170,11 @@ To start generating a new theme, simply say:
87170

88171
### Stage 4: Initial Content (Optional)
89172

90-
| Question | Variable | Default |
91-
| ------------------- | ----------------- | --------------- |
92-
| Homepage hero title | `{{hero_title}}` | "Welcome" |
93-
| Call-to-action text | `{{cta_text}}` | "Get Started" |
94-
| Footer copyright | `{{footer_text}}` | "© {{author}}" |
173+
| Question | Variable | Example |
174+
| ------------------- | ---------------- | --------- |
175+
| Homepage hero title | `{{hero_title}}` | "Welcome" |
176+
177+
---
95178

96179
---
97180

@@ -247,6 +330,18 @@ Would you like me to help you with any of these steps?"
247330
- Must be valid hex colour (#RGB or #RRGGBB)
248331
- Examples: #fff, #ffffff, #0073aa
249332

333+
### Mustache Variable Mapping
334+
335+
All variables above are available for use in:
336+
337+
- `style.css` (theme header)
338+
- `functions.php` (theme setup)
339+
- `theme.json` (theme config)
340+
- `inc/*.php` (utility and setup)
341+
- Documentation and config files
342+
343+
---
344+
250345
---
251346

252347
## Error Handling

‎.github/agents/release-scaffold.agent.md‎

Lines changed: 46 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -22,33 +22,59 @@ metadata:
2222

2323
# Block Theme Scaffold Release Agent
2424

25-
## Agent Script
26-
27-
This agent has an accompanying JavaScript implementation:
28-
- **Script**: `scripts/agents/release-scaffold.agent.js`
29-
- **NPM Commands**:
30-
- `npm run release:scaffold:validate` - Run full validation suite
31-
- `npm run release:scaffold:report` - Generate readiness report
32-
- `npm run release:scaffold:placeholders` - Check placeholder integrity
33-
- `npm run release:scaffold:schema` - Validate mustache variable schema
34-
35-
To use this agent, invoke the script via npm commands or directly:
36-
```bash
37-
node scripts/agents/release-scaffold.agent.js validate
25+
## Wizard Integration & Advanced Features
26+
27+
This agent supports an interactive and automated wizard for release preparation:
28+
29+
- **Conditional Logic:**
30+
- Only prompts for advanced checks (e.g., smoke test, schema validation) if user opts in or config enables them.
31+
- **Config File Automation:**
32+
- Accepts a config file to automate release checks and reporting:
33+
- `node scripts/agents/release-scaffold.agent.js --config path/to/release-config.json`
34+
- Config can specify which checks to run, custom version, or skip optional steps.
35+
- **Dry-Run/Mock Mode:**
36+
- Use `WIZARD_MODE=mock` or `--dry-run` to simulate all checks and reporting without modifying files.
37+
- Useful for CI, validation, and pre-release rehearsal.
38+
- **Validation & Error Recovery:**
39+
- Each step validates its outcome (e.g., placeholder integrity, version alignment).
40+
- If a check fails, the wizard reports the error, suggests fixes, and can re-run after correction.
41+
- **Explicit Mapping:**
42+
- Each wizard step maps to a config schema field and release check (see below).
43+
44+
### Example: Using a Config File
45+
46+
```json
47+
{
48+
"target_version": "1.2.3",
49+
"run_smoke_test": true,
50+
"skip_schema_validation": false
51+
}
3852
```
3953

54+
Run:
55+
56+
```
57+
node scripts/agents/release-scaffold.agent.js --config ./release-config.json
58+
```
59+
60+
### Example: Dry-Run/Mock Mode
61+
62+
```
63+
WIZARD_MODE=mock node scripts/agents/release-scaffold.agent.js --config ./release-config.json
64+
# or
65+
node scripts/agents/release-scaffold.agent.js --dry-run
66+
```
67+
68+
This will run all validation and show the steps, but will not write or modify any files.
69+
70+
---
71+
4072
## Role
4173

4274
You are the **Scaffold Release Preparation Agent**. You prepare the **block theme scaffold repository** for release while safeguarding all `{{mustache}}` placeholders and ensuring the release templates remain ready for generated themes.
4375

4476
## Critical Rules
4577

46-
- **Never replace or remove `{{...}}` placeholders** in WordPress source files (`style.css`, `functions.php`, `theme.json`, `inc/`, `patterns/`, `templates/`, `parts/`).
47-
- Keep these templated files intact for generated themes: `.github/agents/release.agent.md`, `.github/prompts/release.prompt.md`, `.github/instructions/release.instructions.md`, `docs/GENERATE_THEME.md`.
48-
- Scaffold-only files (`release-scaffold.agent.md`, `release-scaffold.prompt.md`, `release-scaffold.instructions.md`, `docs/RELEASE_PROCESS_SCAFFOLD.md`) stay in this repository but **must be deleted by the generator** in new theme repositories.
49-
- Prefer **dry-run** commands and validation scripts that do not write to template files.
50-
- If placeholder integrity is broken, **stop and restore** before proceeding.
51-
5278
## Scope
5379

5480
This agent covers scaffold **pre-release preparation**:
@@ -109,6 +135,7 @@ This agent covers scaffold **pre-release preparation**:
109135
- **Quality gates:** `npm run lint:dry-run`, `npm run format -- --check`, `npm run test:dry-run:all`
110136
- **Security:** `npm audit --audit-level=high`
111137
- **Generation test (sample):**
138+
112139
```bash
113140
node scripts/generate-theme.js \
114141
--slug "scaffold-release-check" \

‎.github/agents/release.agent.md‎

Lines changed: 48 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,12 @@ This file is **templated** inside the scaffold. When you generate **{{theme_name
3131
This agent is for **generated themes** created from the scaffold.
3232

3333
**If you are releasing the scaffold repository**, use:
34+
3435
- `.github/agents/release-scaffold.agent.md`
3536
- `.github/workflows/release-scaffold.yml`
3637

3738
The release workflows (`.github/workflows/release.yml` and `agent-release.yml`) include verification steps that will fail if:
39+
3840
1. Scaffold-specific files are detected (`release-scaffold.agent.md`, `scripts/generate-theme.js`, etc.)
3941
2. The workflow still contains unreplaced `{{theme_name}}` placeholders
4042

@@ -63,19 +65,52 @@ Ensure every release is:
6365
5. **Security:** `npm audit --audit-level=high` (and composer audit if applicable).
6466
6. **Reporting:** concise readiness report with blockers, warnings, and next steps.
6567

66-
## Workflow
67-
68-
1. **Confirm target version** from `VERSION` or user input; enforce SemVer.
69-
2. **Placeholder check:** ensure no `{{...}}` placeholders remain in the generated theme (fail fast).
70-
3. **Version consistency:** compare `VERSION`, `package.json`, `composer.json`, and `style.css`.
71-
4. **Quality gates (generated theme):**
72-
- `npm run lint`
73-
- `npm run format -- --check`
74-
- `npm run test` (or suite available for the theme)
75-
5. **Documentation review:** `CHANGELOG.md` has `[{{version}}] - YYYY-MM-DD` and links; `README.md` references `{{theme_name}}`; `docs/RELEASE_PROCESS.md` is current.
76-
6. **Build validation:** `npm run build` (or equivalent) succeeds; `theme.json` passes validation.
77-
7. **Security:** `npm audit --audit-level=high` (and `composer audit` if available).
78-
8. **Report:** Summarise PASS/FAIL, blockers, warnings, and recommended next actions.
68+
## Wizard Integration & Advanced Features
69+
70+
This agent supports both interactive and automated wizard-driven release validation:
71+
72+
- **Conditional Logic:**
73+
- Prompts for optional checks (e.g., security audit, documentation review) only if user opts in or config enables them.
74+
- **Config File Automation:**
75+
- Accepts a config file to automate release validation and reporting:
76+
- `node scripts/agents/release.agent.js --config path/to/release-config.json`
77+
- Config can specify which checks to run, custom version, or skip optional steps.
78+
- **Dry-Run/Mock Mode:**
79+
- Use `WIZARD_MODE=mock` or `--dry-run` to simulate all checks and reporting without modifying files.
80+
- Useful for CI, validation, and pre-release rehearsal.
81+
- **Validation & Error Recovery:**
82+
- Each step validates its outcome (e.g., placeholder-free, version alignment, build success).
83+
- If a check fails, the wizard reports the error, suggests fixes, and can re-run after correction.
84+
- **Explicit Mapping:**
85+
- Each wizard step maps to a config schema field and release check (see below).
86+
87+
### Example: Using a Config File
88+
89+
```json
90+
{
91+
"target_version": "1.2.3",
92+
"run_security_audit": true,
93+
"skip_optional_checks": false
94+
}
95+
```
96+
97+
Run:
98+
99+
```
100+
node scripts/agents/release.agent.js --config ./release-config.json
101+
```
102+
103+
### Example: Dry-Run/Mock Mode
104+
105+
```
106+
WIZARD_MODE=mock node scripts/agents/release.agent.js --config ./release-config.json
107+
# or
108+
node scripts/agents/release.agent.js --dry-run
109+
```
110+
111+
This will run all validation and show the steps, but will not write or modify any files.
112+
113+
---
79114

80115
## Validation Criteria
81116

0 commit comments

Comments
 (0)