@forgewp/compiler 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/README.md +70 -3
  2. package/bin/add.js +30 -15
  3. package/bin/analyze.js +66 -1
  4. package/bin/cli.js +149 -70
  5. package/bin/doctor.js +21 -12
  6. package/bin/export.js +69 -20
  7. package/bin/fresh.js +6 -1
  8. package/bin/i18n-extract.js +3 -10
  9. package/bin/i18n-translate.js +15 -24
  10. package/bin/make-block.js +24 -0
  11. package/bin/make-editable.js +166 -0
  12. package/bin/make-form.js +131 -0
  13. package/bin/make-island.js +11 -0
  14. package/bin/make-loop.js +147 -0
  15. package/bin/make-mail.js +27 -0
  16. package/bin/make-page.js +83 -0
  17. package/bin/make-post-type.js +68 -29
  18. package/bin/make-sandbox.js +609 -0
  19. package/bin/make-section.js +221 -0
  20. package/bin/make-shell.js +375 -0
  21. package/bin/repair.js +14 -26
  22. package/bin/seed.js +119 -0
  23. package/bin/sync-routes.js +107 -85
  24. package/lib/adapters/html-adapter.js +13 -3
  25. package/lib/adapters/stub-adapter.js +10 -2
  26. package/lib/add-component.js +153 -92
  27. package/lib/asset-loader.js +333 -1
  28. package/lib/assets/asset-graph.js +432 -0
  29. package/lib/assets/asset-pipeline.js +125 -0
  30. package/lib/assets/diagnostics-report.js +345 -0
  31. package/lib/assets/external-fetcher.js +173 -0
  32. package/lib/assets/font-orchestrator.js +348 -0
  33. package/lib/assets/font-usage-scanner.js +242 -0
  34. package/lib/assets/image-optimizer.js +229 -0
  35. package/lib/assets/index.js +51 -0
  36. package/lib/assets/preload-generator.js +70 -0
  37. package/lib/assets/public-url.js +153 -0
  38. package/lib/block-authoring-help.js +11 -0
  39. package/lib/blocks/ast-parser.js +67 -0
  40. package/lib/blocks/discover-blocks.js +146 -0
  41. package/lib/blocks/editor-scope.js +733 -0
  42. package/lib/blocks/editor-transpiler.js +1229 -0
  43. package/lib/blocks/index.js +2838 -0
  44. package/lib/blocks/php-transpiler.js +4928 -0
  45. package/lib/blocks/scanner.js +1487 -0
  46. package/lib/blocks/shared-utils.js +290 -0
  47. package/lib/blocks/source-sanitize.js +1449 -0
  48. package/lib/blueprints.js +77 -5
  49. package/lib/build-assets.js +38 -33
  50. package/lib/collect-page-template-routes.js +102 -0
  51. package/lib/collect-static-routes.js +175 -0
  52. package/lib/diagnostics.js +58 -33
  53. package/lib/export-theme.js +84 -5
  54. package/lib/extract-template-content.js +90 -0
  55. package/lib/forms-preview.js +42 -0
  56. package/lib/functions/cpt-routing.js +69 -0
  57. package/lib/functions/forms.js +2461 -0
  58. package/lib/functions/hydration-enqueuer.js +400 -0
  59. package/lib/functions/index.js +1623 -0
  60. package/lib/functions/load-menus.js +112 -0
  61. package/lib/functions/load-translations.js +148 -0
  62. package/lib/functions/rest-endpoints.js +2923 -0
  63. package/lib/functions/routing.js +765 -0
  64. package/lib/functions/seed-mock-data.js +392 -0
  65. package/lib/functions/seed-products.js +481 -0
  66. package/lib/functions/settings-page.js +273 -0
  67. package/lib/functions/theme-setup.js +494 -0
  68. package/lib/generate-theme.js +2076 -303
  69. package/lib/hydration/editable-schemas.js +332 -0
  70. package/lib/hydration/enter-hidden-initial.js +65 -0
  71. package/lib/hydration/form-schemas.js +227 -0
  72. package/lib/hydration/index.js +12 -0
  73. package/lib/hydration/is-interactive.js +951 -0
  74. package/lib/hydration/island-split.js +1231 -0
  75. package/lib/hydration/islands-scanner.js +599 -0
  76. package/lib/hydration/resolve-island-chunk.js +103 -0
  77. package/lib/hydration/resolve-island-component.js +52 -0
  78. package/lib/hydration/rollup-inputs.js +81 -0
  79. package/lib/hydration/root-class-extractor.js +220 -0
  80. package/lib/hydration/scan-app-providers.js +154 -0
  81. package/lib/hydration/static-lint.js +382 -0
  82. package/lib/hydration/transform.js +257 -0
  83. package/lib/hydration/uses-block-area.js +49 -0
  84. package/lib/hydration/utils.js +119 -0
  85. package/lib/i18n/translation-cache.js +141 -0
  86. package/lib/icon-registry.js +72 -0
  87. package/lib/index.d.ts +324 -8
  88. package/lib/index.js +3 -2
  89. package/lib/load-config.js +338 -144
  90. package/lib/mail-templates.js +37 -0
  91. package/lib/markup-processor.js +483 -92
  92. package/lib/node-runtime.js +7 -0
  93. package/lib/page-config-plugin.js +84 -0
  94. package/lib/php-builders.js +383 -42
  95. package/lib/react-adapter.js +1053 -246
  96. package/lib/registration-metadata.js +11 -0
  97. package/lib/render-theme.mts +1410 -543
  98. package/lib/route-layout.js +76 -0
  99. package/lib/template-discovery.js +58 -0
  100. package/lib/theme-compatibility.js +32 -0
  101. package/lib/validate-export.js +51 -2
  102. package/lib/validate.js +27 -5
  103. package/lib/virtual-plugin.js +319 -0
  104. package/lib/walkthrough.md +26 -0
  105. package/package.json +17 -5
  106. package/templates/PresetsStyle.tsx +1 -1
  107. package/templates/auth/cms/email-logs.json +9 -0
  108. package/templates/auth/cms/menus.json +11 -0
  109. package/templates/auth/cms/mock-data.json +123 -0
  110. package/templates/auth/cms/roles.json +7 -0
  111. package/templates/auth/cms/sessions.json +1 -0
  112. package/templates/auth/cms/site-settings.json +28 -0
  113. package/templates/auth/cms/translations.json +4 -0
  114. package/templates/auth/cms/users.json +46 -0
  115. package/templates/auth/components/dashboard-view-wrapper.tsx +168 -0
  116. package/templates/auth/components/forgot-password-form-wrapper.tsx +141 -0
  117. package/templates/auth/components/login-form-wrapper.tsx +300 -0
  118. package/templates/auth/components/reset-password-form-wrapper.tsx +190 -0
  119. package/templates/auth/components/signup-form-wrapper.tsx +257 -0
  120. package/templates/auth/components/verify-email-view-wrapper.tsx +265 -0
  121. package/templates/auth/pages/DashboardPage.tsx +12 -0
  122. package/templates/auth/pages/ForgotPasswordPage.tsx +11 -0
  123. package/templates/auth/pages/LoginPage.tsx +11 -0
  124. package/templates/auth/pages/ResetPasswordPage.tsx +11 -0
  125. package/templates/auth/pages/SignUpPage.tsx +11 -0
  126. package/templates/auth/pages/VerifyEmailPage.tsx +11 -0
  127. package/templates/auth/ui/button.tsx +57 -0
  128. package/templates/auth/ui/card.tsx +76 -0
  129. package/templates/auth/ui/field.tsx +242 -0
  130. package/templates/auth/ui/input.tsx +22 -0
  131. package/templates/auth/ui/label.tsx +24 -0
  132. package/templates/auth/ui/separator.tsx +31 -0
  133. package/templates/forgewp-config.ts +70 -3
  134. package/templates/menus.json +12 -10
  135. package/templates/mock-data.json +122 -433
  136. package/templates/products.json +5 -0
  137. package/templates/roles.json +7 -0
  138. package/templates/sessions.json +1 -0
  139. package/templates/users.json +38 -0
  140. package/templates/wordpress.tsx +1835 -1297
  141. package/bin/make-template.js +0 -145
  142. package/lib/block-compiler.js +0 -552
  143. package/lib/functions-builder.js +0 -2044
  144. package/lib/hydration-scanner.js +0 -821
package/README.md CHANGED
@@ -34,17 +34,71 @@ Dynamically scaffolds dynamic WordPress blocks authored in React with options fo
34
34
  pnpm forgewp make:block HeroBlock --attributes=heading,text,image,buttonText
35
35
  ```
36
36
 
37
- ### 4. Post-Type Loop Component Scaffolder
37
+ #### Gutenberg editor previews
38
+
39
+ ForgeWP uses a block's `edit` component as the Gutenberg canvas by default.
40
+ Static same-file helpers and imported components are expanded into that canvas,
41
+ so `WpEditable` fields remain inline-editable instead of showing a separate,
42
+ uneditable server-rendered result. Links in the canvas do not navigate; when
43
+ their URL is bound to a block attribute, the editor also offers URL editing.
44
+
45
+ If the edit component is interactive or cannot be evaluated safely, ForgeWP
46
+ falls back to WordPress's server-rendered block preview. This renders the
47
+ compiled `render.php` output and keeps visitor-only event handlers, React
48
+ state, and live-data hooks from running inside the editor.
49
+ The custom preview runtime also provides `resolveWpAsset()` for converting
50
+ theme-relative asset URLs, such as a PDF link, to their exported theme URL.
51
+
52
+ For a block whose visitor output depends on live data or browser interaction,
53
+ define an editor-safe visual approximation with `editorPreview`. It receives
54
+ the block's `attributes` and `setAttributes`, and should not submit forms or
55
+ depend on visitor-only data:
56
+
57
+ ```tsx
58
+ export default defineBlock({
59
+ name: 'inquiry-form',
60
+ title: 'Inquiry Form',
61
+ attributes: { heading: { type: 'string', default: 'Contact us' } },
62
+ editorPreview: ({ attributes }) => (
63
+ <section>
64
+ <h2>{attributes.heading}</h2>
65
+ <label>
66
+ Name <input disabled />
67
+ </label>
68
+ <button disabled>Send request</button>
69
+ </section>
70
+ ),
71
+ save: () => <InquiryForm />,
72
+ });
73
+ ```
74
+
75
+ The preview is editor-only; the visitor page continues to use `save` and the
76
+ compiled PHP/hydration output. An explicit `editorPreviewMode: 'override'`
77
+ selects `editorPreview` even when an `edit` component exists. Without a safe
78
+ custom editor view, WordPress previews the PHP output, which can show a loading
79
+ or empty state when the component depends on live query data. Validate these
80
+ blocks in Gutenberg and on the visitor page:
81
+ `pnpm --filter @forgewp/compiler exec vitest run test/blocks/editor-preview.test.js`.
82
+
83
+ ### 4. Post-Type Loop Scaffolder
38
84
 
39
85
  Instantly scaffolds beautifully designed React loop grid components bound to custom WordPress post types (ACF-like integration):
40
86
 
41
87
  ```bash
42
- pnpm forgewp make:component PortfolioGrid --postType=portfolio
88
+ pnpm forgewp make:loop PortfolioGrid --postType=portfolio
43
89
  ```
44
90
 
45
91
  _Note: If the requested post type does not exist in `cms/mock-data.json`, the compiler will automatically register and seed it for you!_
46
92
 
47
- ### 5. Resilient Framework Immunity & Diagnostics
93
+ ### 5. Custom Page Template Scaffolder
94
+
95
+ Scaffold custom standalone WordPress Page Templates written in React:
96
+
97
+ ```bash
98
+ pnpm forgewp make:page AboutUs
99
+ ```
100
+
101
+ ### 6. Resilient Framework Immunity & Diagnostics
48
102
 
49
103
  Keep your monorepo perfectly healthy, clean, and self-healing:
50
104
 
@@ -54,6 +108,19 @@ pnpm forgewp repair # Force restore framework utility blueprints
54
108
  pnpm forgewp clean # Prune build artifacts and clear caches
55
109
  ```
56
110
 
111
+ ### 7. Typed CMS & Seed Database (`cms/*.ts`)
112
+
113
+ ForgeWP provides first-class TypeScript autocomplete, type validation, and JSDoc tooltips for all local development CMS mock data via helper definitions:
114
+
115
+ - **`cms/products.ts`**: Authored using `defineProducts([...])` from `@forgewp/woocommerce` covering dimensions (`length`, `width`, `height`, `unit`), physical weights, regular and sale pricing, attributes, variations, stock management, reviews, and cross-sell/upsell associations.
116
+ - **`cms/mock-data.ts`**: Authored using `defineWpPosts({...})` from `@forgewp/react` supporting core WordPress post types (`post`, `page`) alongside arbitrary Custom Post Types (`portfolio`, `project`, `review`, etc.) with typed custom meta fields.
117
+ - **`cms/menus.ts`**: Authored using `defineWpMenus({...})` from `@forgewp/react` declaring hierarchical navigation structures.
118
+ - **`cms/roles.ts`**: Authored using `defineWpRoles({...})` from `@forgewp/react` defining role capabilities.
119
+ - **`cms/users.ts`**: Authored using `defineWpUsers([...])` from `@forgewp/react` defining seed user accounts.
120
+ - **`cms/translations.ts`**: Authored using `defineTranslations({...})` from `@forgewp/react` declaring multilingual dictionaries.
121
+
122
+ _The compiler automatically supports dual-resolution: modern typed `.ts` files are preferred by default, while legacy `.json` files remain 100% backward-compatible._
123
+
57
124
  ## 🔌 Configuration
58
125
 
59
126
  ForgeWP is controlled via `wp.config.ts` in your project root:
package/bin/add.js CHANGED
@@ -1,29 +1,34 @@
1
1
  #!/usr/bin/env node
2
- import { addComponent } from "../lib/add-component.js";
2
+ import { addComponent } from '../lib/add-component.js';
3
3
 
4
4
  const args = process.argv.slice(2);
5
- let component = args.find(a => !a.startsWith("-"));
5
+ let components = args.filter((a) => !a.startsWith('-'));
6
6
 
7
7
  // Support --name navbar or --name=navbar
8
- const nameIndex = args.indexOf("--name");
8
+ const nameIndex = args.indexOf('--name');
9
9
  if (nameIndex !== -1 && args[nameIndex + 1]) {
10
- component = args[nameIndex + 1];
10
+ components.push(args[nameIndex + 1]);
11
11
  } else {
12
- const nameEqual = args.find(a => a.startsWith("--name="));
12
+ const nameEqual = args.find((a) => a.startsWith('--name='));
13
13
  if (nameEqual) {
14
- component = nameEqual.split("=")[1];
14
+ components.push(nameEqual.split('=')[1]);
15
15
  }
16
16
  }
17
17
 
18
- import { readFileSync, existsSync } from "node:fs";
19
- import path from "node:path";
18
+ // Clean and deduplicate the component list
19
+ components = Array.from(
20
+ new Set(components.map((c) => c.trim()).filter(Boolean)),
21
+ );
20
22
 
21
- let projectStyle = "forgewp";
23
+ import { readFileSync, existsSync } from 'node:fs';
24
+ import path from 'node:path';
25
+
26
+ let projectStyle = 'forgewp';
22
27
  try {
23
28
  // Read wp.config.ts natively by regexing the 'style' property since it's a TS file
24
- const wpConfigPath = path.join(process.cwd(), "wp.config.ts");
29
+ const wpConfigPath = path.join(process.cwd(), 'wp.config.ts');
25
30
  if (existsSync(wpConfigPath)) {
26
- const content = readFileSync(wpConfigPath, "utf8");
31
+ const content = readFileSync(wpConfigPath, 'utf8');
27
32
  const styleMatch = content.match(/style:\s*['"](forgewp|shadcn)['"]/);
28
33
  if (styleMatch && styleMatch[1]) {
29
34
  projectStyle = styleMatch[1];
@@ -33,14 +38,24 @@ try {
33
38
  // Silent fallback
34
39
  }
35
40
 
36
- const style = args.find(a => a.startsWith("--style="))?.split("=")[1] || projectStyle;
41
+ const style =
42
+ args.find((a) => a.startsWith('--style='))?.split('=')[1] || projectStyle;
43
+ const overwrite = args.includes('--overwrite');
37
44
 
38
- if (!component) {
39
- console.error("Usage: forgewp add <component> [--style=forgewp|shadcn] or forgewp add --name <component>");
45
+ if (components.length === 0) {
46
+ console.error(
47
+ 'Usage: forgewp add <component1> [component2] ... [--style=forgewp|shadcn] [--overwrite]',
48
+ );
40
49
  process.exit(1);
41
50
  }
42
51
 
43
- addComponent(component, { style }).catch((err) => {
52
+ async function run() {
53
+ for (const component of components) {
54
+ await addComponent(component, { style, overwrite });
55
+ }
56
+ }
57
+
58
+ run().catch((err) => {
44
59
  console.error(err.message);
45
60
  process.exit(1);
46
61
  });
package/bin/analyze.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import { existsSync, readFileSync } from "node:fs";
3
+ import { existsSync, readFileSync, readdirSync } from "node:fs";
4
4
  import path from "node:path";
5
5
  import pc from "picocolors";
6
6
  import { exec } from "node:child_process";
@@ -98,6 +98,56 @@ async function main() {
98
98
  const violations = runStaticLintChecks(projectRoot);
99
99
  analysis.violations = violations;
100
100
 
101
+ // 6.5. Run Auth Security checks & parse manifest
102
+ const authManifestPath = path.join(projectRoot, ".forgewp", "out", config.slug, "auth-manifest.json");
103
+ let authManifest = { protectedPages: [], authGates: [] };
104
+ if (existsSync(authManifestPath)) {
105
+ try {
106
+ authManifest = JSON.parse(readFileSync(authManifestPath, "utf8"));
107
+ } catch {}
108
+ }
109
+
110
+ const authWarnings = [];
111
+ const pagesDir = path.join(projectRoot, "src", "app", "pages");
112
+ if (existsSync(pagesDir)) {
113
+ const collectPagesRecursive = (dir, list = []) => {
114
+ const items = readdirSync(dir, { withFileTypes: true });
115
+ for (const item of items) {
116
+ const fullPath = path.join(dir, item.name);
117
+ if (item.isDirectory()) {
118
+ collectPagesRecursive(fullPath, list);
119
+ } else if (item.isFile() && (item.name.endsWith(".tsx") || item.name.endsWith(".ts"))) {
120
+ list.push(fullPath);
121
+ }
122
+ }
123
+ return list;
124
+ };
125
+ try {
126
+ const pageFiles = collectPagesRecursive(pagesDir);
127
+ for (const file of pageFiles) {
128
+ const content = readFileSync(file, "utf8");
129
+ const hasAuthHooks = content.includes("useWpAuth") || content.includes("useWpUser");
130
+ if (hasAuthHooks) {
131
+ const fileBasename = path.basename(file, path.extname(file));
132
+ const slug = fileBasename
133
+ .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
134
+ .toLowerCase();
135
+
136
+ const isPageProtected = authManifest.protectedPages.some(
137
+ p => p.page === slug || p.page === slug.replace(/-page$/, "")
138
+ );
139
+
140
+ if (!isPageProtected) {
141
+ authWarnings.push({
142
+ file: path.relative(projectRoot, file),
143
+ message: `Page utilizes authentication hooks (useWpAuth/useWpUser) but is not protected by server-side page guards.`
144
+ });
145
+ }
146
+ }
147
+ }
148
+ } catch {}
149
+ }
150
+
101
151
  // 7. Generate HTML report
102
152
  let reportPath;
103
153
  try {
@@ -115,6 +165,21 @@ async function main() {
115
165
  const totalJsKb = analysis.results.reduce((acc, curr) => acc + curr.sizeKb, 0);
116
166
  console.log(` Total Client JS Weight: ${totalJsKb > 200 ? pc.red(totalJsKb.toFixed(1) + " kB") : pc.green(totalJsKb.toFixed(1) + " kB")}`);
117
167
 
168
+ console.log(`\n🔍 ${pc.bold("ForgeWP Auth Analysis")}`);
169
+ console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
170
+ console.log(` Protected Pages: ${pc.cyan(authManifest.protectedPages.length)}`);
171
+ console.log(` Auth Gates: ${pc.cyan(authManifest.authGates.filter(g => g.type === 'logged_in').length)}`);
172
+ console.log(` Capability Gates: ${pc.cyan(authManifest.authGates.filter(g => g.type === 'capability').length)}`);
173
+
174
+ if (authWarnings.length > 0) {
175
+ console.log(`\n⚠️ ${pc.bold(pc.yellow("SECURITY WARNINGS"))}`);
176
+ for (const w of authWarnings) {
177
+ console.log(` ${pc.yellow("⚠️ WARN")} ${pc.bold(w.file)}: ${w.message}`);
178
+ }
179
+ } else {
180
+ console.log(`\n✅ ${pc.green(pc.bold("Security Audit Passed:"))} No unprotected page auth hook usages detected.`);
181
+ }
182
+
118
183
  if (violations.length > 0) {
119
184
  console.log(`\n⚠️ ${pc.bold(pc.yellow("THEME LINT WARNINGS & SEO RECOMMENDATIONS"))}`);
120
185
  for (const v of violations) {
package/bin/cli.js CHANGED
@@ -1,35 +1,51 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import { spawn } from "node:child_process";
4
- import path from "node:path";
5
- import { fileURLToPath } from "node:url";
6
- import pc from "picocolors";
3
+ import { spawn } from 'node:child_process';
4
+ import path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import pc from 'picocolors';
7
+ import { blockAuthoringHelp } from '../lib/block-authoring-help.js';
8
+ import { isSupportedNode, SUPPORTED_NODE_RANGE } from '../lib/node-runtime.js';
9
+
10
+ if (!isSupportedNode()) {
11
+ console.error(`ForgeWP requires Node.js ${SUPPORTED_NODE_RANGE}; found ${process.version}. Install a compatible Node.js version and try again.`);
12
+ process.exit(1);
13
+ }
7
14
 
8
15
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
9
16
 
10
17
  const subcommands = {
11
- add: path.join(__dirname, "add.js"),
12
- "make:block": path.join(__dirname, "make-block.js"),
13
- "make:post-type": path.join(__dirname, "make-post-type.js"),
14
- "make:template": path.join(__dirname, "make-template.js"),
15
- "make:component": path.join(__dirname, "make-template.js"), // Backward compatible alias mapping
16
- "make:island": path.join(__dirname, "make-island.js"),
17
- "sync:routes": path.join(__dirname, "sync-routes.js"),
18
- "sync:hooks": path.join(__dirname, "sync-hooks.js"),
19
- "i18n:extract": path.join(__dirname, "i18n-extract.js"),
20
- "i18n:translate": path.join(__dirname, "i18n-translate.js"),
21
- export: path.join(__dirname, "export.js"),
22
- doctor: path.join(__dirname, "doctor.js"),
23
- analyze: path.join(__dirname, "analyze.js"),
24
- repair: path.join(__dirname, "repair.js"),
25
- clean: path.join(__dirname, "clean.js"),
26
- fresh: path.join(__dirname, "fresh.js"),
18
+ add: path.join(__dirname, 'add.js'),
19
+ 'make:block': path.join(__dirname, 'make-block.js'),
20
+ 'make:section': path.join(__dirname, 'make-section.js'),
21
+ 'make:shell': path.join(__dirname, 'make-shell.js'),
22
+ 'make:post-type': path.join(__dirname, 'make-post-type.js'),
23
+ 'make:loop': path.join(__dirname, 'make-loop.js'),
24
+ 'make:page': path.join(__dirname, 'make-page.js'),
25
+ 'make:island': path.join(__dirname, 'make-island.js'),
26
+ 'make:editable': path.join(__dirname, 'make-editable.js'),
27
+ 'make:mail': path.join(__dirname, 'make-mail.js'),
28
+ 'make:form': path.join(__dirname, 'make-form.js'),
29
+ 'make:sandbox': path.join(__dirname, 'make-sandbox.js'),
30
+ 'sync:routes': path.join(__dirname, 'sync-routes.js'),
31
+ 'sync:hooks': path.join(__dirname, 'sync-hooks.js'),
32
+ seed: path.join(__dirname, 'seed.js'),
33
+ 'seed:products': path.join(__dirname, 'seed.js'),
34
+ 'seed:mock-data': path.join(__dirname, 'seed.js'),
35
+ 'i18n:extract': path.join(__dirname, 'i18n-extract.js'),
36
+ 'i18n:translate': path.join(__dirname, 'i18n-translate.js'),
37
+ export: path.join(__dirname, 'export.js'),
38
+ doctor: path.join(__dirname, 'doctor.js'),
39
+ analyze: path.join(__dirname, 'analyze.js'),
40
+ repair: path.join(__dirname, 'repair.js'),
41
+ clean: path.join(__dirname, 'clean.js'),
42
+ fresh: path.join(__dirname, 'fresh.js'),
27
43
  };
28
44
 
29
45
  const args = process.argv.slice(2);
30
46
  const command = args[0];
31
47
 
32
- if (!command || command === "-h" || command === "--help") {
48
+ if (!command || command === '-h' || command === '--help') {
33
49
  printHelp();
34
50
  process.exit(0);
35
51
  }
@@ -38,28 +54,78 @@ let targetScript = subcommands[command];
38
54
 
39
55
  // Helper fallback routes
40
56
  if (!targetScript) {
41
- if (command === "make-block" || command === "make") {
42
- targetScript = subcommands["make:block"];
43
- } else if (command === "make-post-type" || command === "post-type" || command === "make:post-type") {
44
- targetScript = subcommands["make:post-type"];
45
- } else if (command === "make-template" || command === "template" || command === "make:template") {
46
- targetScript = subcommands["make:template"];
47
- } else if (command === "make-component" || command === "component" || command === "make:component") {
48
- targetScript = subcommands["make:component"];
49
- } else if (command === "make-island" || command === "island" || command === "make:island") {
50
- targetScript = subcommands["make:island"];
51
- } else if (command === "sync-routes" || command === "sync" || command === "sync:routes") {
52
- targetScript = subcommands["sync:routes"];
53
- } else if (command === "sync-hooks" || command === "sync:hooks") {
54
- targetScript = subcommands["sync:hooks"];
55
- } else if (command === "i18n-extract" || command === "i18n:extract") {
56
- targetScript = subcommands["i18n:extract"];
57
- } else if (command === "i18n-translate" || command === "i18n:translate") {
58
- targetScript = subcommands["i18n:translate"];
59
- } else if (command === "reset") {
60
- targetScript = subcommands["fresh"];
61
- } else if (command === "inspect" || command === "analyze") {
62
- targetScript = subcommands["analyze"];
57
+ if (command === 'make-block' || command === 'make') {
58
+ targetScript = subcommands['make:block'];
59
+ } else if (
60
+ command === 'make-section' ||
61
+ command === 'section' ||
62
+ command === 'make:section'
63
+ ) {
64
+ targetScript = subcommands['make:section'];
65
+ } else if (
66
+ command === 'make-shell' ||
67
+ command === 'make:shell' ||
68
+ command === 'shell'
69
+ ) {
70
+ targetScript = subcommands['make:shell'];
71
+ } else if (
72
+ command === 'make-post-type' ||
73
+ command === 'post-type' ||
74
+ command === 'make:post-type'
75
+ ) {
76
+ targetScript = subcommands['make:post-type'];
77
+ } else if (
78
+ command === 'make-loop' ||
79
+ command === 'loop' ||
80
+ command === 'make:loop'
81
+ ) {
82
+ targetScript = subcommands['make:loop'];
83
+ } else if (
84
+ command === 'make-page' ||
85
+ command === 'page' ||
86
+ command === 'make:page'
87
+ ) {
88
+ targetScript = subcommands['make:page'];
89
+ } else if (
90
+ command === 'make-island' ||
91
+ command === 'island' ||
92
+ command === 'make:island'
93
+ ) {
94
+ targetScript = subcommands['make:island'];
95
+ } else if (
96
+ command === 'make-editable' ||
97
+ command === 'editable' ||
98
+ command === 'make:editable'
99
+ ) {
100
+ targetScript = subcommands['make:editable'];
101
+ } else if (
102
+ command === 'make-form' ||
103
+ command === 'form' ||
104
+ command === 'make:form'
105
+ ) {
106
+ targetScript = subcommands['make:form'];
107
+ } else if (
108
+ command === 'make-sandbox' ||
109
+ command === 'sandbox' ||
110
+ command === 'make:sandbox'
111
+ ) {
112
+ targetScript = subcommands['make:sandbox'];
113
+ } else if (
114
+ command === 'sync-routes' ||
115
+ command === 'sync' ||
116
+ command === 'sync:routes'
117
+ ) {
118
+ targetScript = subcommands['sync:routes'];
119
+ } else if (command === 'sync-hooks' || command === 'sync:hooks') {
120
+ targetScript = subcommands['sync:hooks'];
121
+ } else if (command === 'i18n-extract' || command === 'i18n:extract') {
122
+ targetScript = subcommands['i18n:extract'];
123
+ } else if (command === 'i18n-translate' || command === 'i18n:translate') {
124
+ targetScript = subcommands['i18n:translate'];
125
+ } else if (command === 'reset') {
126
+ targetScript = subcommands['fresh'];
127
+ } else if (command === 'inspect' || command === 'analyze') {
128
+ targetScript = subcommands['analyze'];
63
129
  }
64
130
  }
65
131
 
@@ -74,47 +140,59 @@ const commandArgs = args.slice(1);
74
140
 
75
141
  // Run the subcommand using spawn, inheriting stdio for rich interactivity
76
142
  const child = spawn(process.execPath, [targetScript, ...commandArgs], {
77
- stdio: "inherit",
78
- env: {
79
- ...process.env,
80
- FORGEWP_LEGACY_ALIAS: (command === "make:component" || command === "make-component" || command === "component") ? "1" : "0",
81
- },
143
+ stdio: 'inherit',
82
144
  });
83
145
 
84
- child.on("close", (code) => {
146
+ child.on('close', (code) => {
85
147
  process.exit(code ?? 0);
86
148
  });
87
149
 
88
150
  function printHelp() {
89
151
  console.log(`
90
- ${pc.bold(pc.bgCyan(pc.black(" ⚡ FORGEWP CLI ")))} ${pc.cyan("— Fast visual frameworks for WordPress")}
152
+ ${pc.bold(pc.bgCyan(pc.black(' ⚡ FORGEWP CLI ')))} ${pc.cyan('— Fast visual frameworks for WordPress')}
91
153
 
92
- ${pc.bold("Usage:")}
154
+ ${pc.bold('Usage:')}
93
155
  pnpm forgewp <command> [options]
94
156
 
95
- ${pc.bold("Commands:")}
96
- ${pc.cyan("add <component>")} Add registry components (e.g. navbar)
97
- ${pc.cyan("make:block <Name>")} Scaffold a type-safe Gutenberg Block via defineBlock()
98
- ${pc.cyan("make:post-type <slug>")} Register a custom mock post-type (e.g. portfolio)
99
- ${pc.cyan("make:template <Name>")} Scaffold a custom post-type loop template
100
- ${pc.cyan("make:island <Name>")} Scaffold an interactive selective hydration island
101
- ${pc.cyan("sync:routes")} Synchronize sitemap menus with routes and scaffold pages
102
- ${pc.cyan("sync:hooks")} Propagate wordpress.tsx hooks to all workspace projects
103
- ${pc.cyan("i18n:extract")} Extract translation strings to translations.json
104
- ${pc.cyan("i18n:translate")} Translate missing strings via the configured engine
105
- ${pc.cyan("export")} Package your theme into an installable WP zip
106
- ${pc.cyan("doctor")} Perform diagnostic check on project health
107
- ${pc.cyan("analyze")} Generate visual hydration island & size report
108
- ${pc.cyan("repair")} Force-repair/auto-heal system internals
109
- ${pc.cyan("clean")} Clear all build caches and temporary artifacts
110
- ${pc.cyan("fresh")} Reset workspace completely to factory-clean canvas
111
-
112
- ${pc.bold("Examples:")}
157
+ ${pc.bold('Commands:')}
158
+ ${pc.cyan('add <component>')} Add a component; --overwrite replaces local ForgeWP source
159
+ ${pc.cyan('make:block <Name>')} Scaffold a type-safe Gutenberg Block via defineBlock()
160
+ ${pc.cyan('make:section <Name>')} Scaffold a shared editable page/block section
161
+ ${pc.cyan('make:shell <Name>')} Scaffold a parent shell (InnerBlocks layout + children)
162
+ ${pc.cyan('make:post-type <slug>')} Register a custom mock post-type (e.g. portfolio)
163
+ ${pc.cyan('make:loop <Name>')} Scaffold a custom post-type loop feed component
164
+ ${pc.cyan('make:page <Name>')} Scaffold a custom WordPress Page Template
165
+ ${pc.cyan('make:island <Name>')} Scaffold an interactive selective hydration island
166
+ ${pc.cyan('make:editable <Name>')} Scaffold a colocated editable content schema (cms/editables/)
167
+ ${pc.cyan('make:mail <name>')} Scaffold a plain-text email template (cms/mail/)
168
+ ${pc.cyan('make:form <Name>')} Scaffold a form (cms/forms/) + starter component (src/components/forms/)
169
+ ${pc.cyan('make:sandbox <type>')} Scaffold sandbox mock databases (e.g. ecommerce, auth)
170
+ ${pc.cyan('sync:routes')} Synchronize sitemap menus with routes and scaffold pages
171
+ ${pc.cyan('sync:hooks')} Propagate wordpress.tsx hooks to all workspace projects
172
+ ${pc.cyan('seed')} Inspect local fixtures and configure WordPress seed routines
173
+ ${pc.cyan('i18n:extract')} Extract translation strings to cms/translations.ts (or .json)
174
+ ${pc.cyan('i18n:translate')} Translate missing strings via the configured engine
175
+ ${pc.cyan('export')} Package your theme into an installable WP zip
176
+ ${pc.cyan('doctor')} Perform diagnostic check on project health
177
+ ${pc.cyan('analyze')} Generate visual hydration island & size report
178
+ ${pc.cyan('repair')} Force-repair/auto-heal system internals
179
+ ${pc.cyan('clean')} Clear all build caches and temporary artifacts
180
+ ${pc.cyan('fresh')} Reset workspace completely to factory-clean canvas
181
+
182
+ ${pc.bold('Examples:')}
113
183
  pnpm forgewp add navbar
184
+ pnpm forgewp add navbar --overwrite
114
185
  pnpm forgewp make:block HeroBlock --attributes=title,subtitle
186
+ pnpm forgewp make:section HeroSection --page=front-page --block
187
+ pnpm forgewp make:shell AboutSplitSection --children=about-mission,about-values --layout=2-col
115
188
  pnpm forgewp make:post-type portfolio --customFields=client_name
116
- pnpm forgewp make:template PortfolioGrid --postType=portfolio
189
+ pnpm forgewp make:sandbox ecommerce
190
+ pnpm forgewp make:sandbox auth
191
+ pnpm forgewp make:loop PortfolioGrid --postType=portfolio
192
+ pnpm forgewp make:page AboutUs
117
193
  pnpm forgewp make:island CounterIsland
194
+ pnpm forgewp make:editable AboutPage --fields=hero_badge:text,hero_title:text,hero_subtitle:richText
195
+ pnpm forgewp make:form Contact --fields=name:text,email:email,message:textarea
118
196
  pnpm forgewp sync:routes
119
197
  pnpm forgewp doctor
120
198
  pnpm forgewp analyze
@@ -122,5 +200,6 @@ function printHelp() {
122
200
  pnpm forgewp clean
123
201
  pnpm forgewp fresh
124
202
  pnpm forgewp export
203
+ ${blockAuthoringHelp}
125
204
  `);
126
205
  }
package/bin/doctor.js CHANGED
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import { isSupportedNode, SUPPORTED_NODE_RANGE } from '../lib/node-runtime.js';
2
3
 
3
4
  import { existsSync, readFileSync } from "node:fs";
4
5
  import path from "node:path";
@@ -6,7 +7,7 @@ import pc from "picocolors";
6
7
  import { SYSTEM_BLUEPRINTS } from "../lib/blueprints.js";
7
8
  import { loadConfig } from "../lib/load-config.js";
8
9
  import { loadFrameworkAdapter } from "../lib/framework-adapter.js";
9
- import { scanForHydrationIslands, runStaticLintChecks } from "../lib/hydration-scanner.js";
10
+ import { scanForHydrationIslands, runStaticLintChecks } from "../lib/hydration/index.js";
10
11
  import { analyzeHydrationIslands, printDiagnosticsReport } from "../lib/diagnostics.js";
11
12
 
12
13
  console.log(`\n🩺 ${pc.bold(pc.bgCyan(pc.black(" FORGEWP SYSTEM DOCTOR ")))}\n`);
@@ -48,9 +49,8 @@ function runCheck(name, fn) {
48
49
 
49
50
  // 1. Node Version Check
50
51
  runCheck("Node.js Runtime Environment", () => {
51
- const major = parseInt(process.versions.node.split(".")[0], 10);
52
- if (major < 18) {
53
- return `Your Node version is v${process.version}. ForgeWP recommends Node v18+ for compiling React themes.`;
52
+ if (!isSupportedNode()) {
53
+ return `Your Node version is ${process.version}. ForgeWP requires Node.js ${SUPPORTED_NODE_RANGE}.`;
54
54
  }
55
55
  return null;
56
56
  });
@@ -77,14 +77,17 @@ runCheck("User Configuration & HTML Layout", () => {
77
77
 
78
78
  // 3. Database Check
79
79
  runCheck("Mock Database Schema Integration", () => {
80
- const dbPath = path.join(projectRoot, "cms", "mock-data.json");
81
- if (!existsSync(dbPath)) {
82
- throw new Error(`Database "cms/mock-data.json" was not found!`);
83
- }
84
- try {
85
- JSON.parse(readFileSync(dbPath, "utf8"));
86
- } catch (err) {
87
- throw new Error(`Database "cms/mock-data.json" contains invalid JSON syntax!\n Message: ${err.message}`);
80
+ const dbTsPath = path.join(projectRoot, "cms", "mock-data.ts");
81
+ const dbJsonPath = path.join(projectRoot, "cms", "mock-data.json");
82
+ if (!existsSync(dbTsPath) && !existsSync(dbJsonPath)) {
83
+ throw new Error(`Database "cms/mock-data.ts" or "cms/mock-data.json" was not found!`);
84
+ }
85
+ if (existsSync(dbJsonPath)) {
86
+ try {
87
+ JSON.parse(readFileSync(dbJsonPath, "utf8"));
88
+ } catch (err) {
89
+ throw new Error(`Database "cms/mock-data.json" contains invalid JSON syntax!\n Message: ${err.message}`);
90
+ }
88
91
  }
89
92
  return null;
90
93
  });
@@ -94,6 +97,12 @@ runCheck("System Internal Framework Libraries", () => {
94
97
  const systemFiles = Object.keys(SYSTEM_BLUEPRINTS);
95
98
  const missing = [];
96
99
  for (const sf of systemFiles) {
100
+ if (sf.startsWith("cms/") && sf.endsWith(".json")) {
101
+ const tsVariant = sf.replace(/\.json$/, ".ts");
102
+ if (existsSync(path.join(projectRoot, tsVariant))) {
103
+ continue;
104
+ }
105
+ }
97
106
  if (!existsSync(path.join(projectRoot, sf))) {
98
107
  missing.push(sf);
99
108
  }