@forgewp/compiler 0.4.3 → 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 (133) hide show
  1. package/README.md +59 -0
  2. package/bin/add.js +20 -14
  3. package/bin/cli.js +145 -70
  4. package/bin/doctor.js +21 -12
  5. package/bin/export.js +69 -20
  6. package/bin/fresh.js +5 -0
  7. package/bin/i18n-extract.js +3 -10
  8. package/bin/i18n-translate.js +15 -24
  9. package/bin/make-block.js +13 -0
  10. package/bin/make-editable.js +166 -0
  11. package/bin/make-form.js +131 -0
  12. package/bin/make-loop.js +40 -43
  13. package/bin/make-mail.js +27 -0
  14. package/bin/make-post-type.js +57 -29
  15. package/bin/make-sandbox.js +62 -11
  16. package/bin/make-section.js +221 -0
  17. package/bin/make-shell.js +375 -0
  18. package/bin/repair.js +14 -26
  19. package/bin/seed.js +119 -0
  20. package/bin/sync-routes.js +107 -85
  21. package/lib/adapters/html-adapter.js +5 -0
  22. package/lib/adapters/stub-adapter.js +4 -0
  23. package/lib/add-component.js +153 -92
  24. package/lib/asset-loader.js +313 -3
  25. package/lib/assets/asset-graph.js +432 -0
  26. package/lib/assets/asset-pipeline.js +125 -0
  27. package/lib/assets/diagnostics-report.js +345 -0
  28. package/lib/assets/external-fetcher.js +173 -0
  29. package/lib/assets/font-orchestrator.js +348 -0
  30. package/lib/assets/font-usage-scanner.js +242 -0
  31. package/lib/assets/image-optimizer.js +229 -0
  32. package/lib/assets/index.js +51 -0
  33. package/lib/assets/preload-generator.js +70 -0
  34. package/lib/assets/public-url.js +153 -0
  35. package/lib/block-authoring-help.js +11 -0
  36. package/lib/blocks/ast-parser.js +67 -0
  37. package/lib/blocks/discover-blocks.js +146 -0
  38. package/lib/blocks/editor-scope.js +733 -0
  39. package/lib/blocks/editor-transpiler.js +1229 -0
  40. package/lib/blocks/index.js +2838 -0
  41. package/lib/blocks/php-transpiler.js +4928 -0
  42. package/lib/blocks/scanner.js +1487 -0
  43. package/lib/blocks/shared-utils.js +290 -0
  44. package/lib/blocks/source-sanitize.js +1449 -0
  45. package/lib/blueprints.js +31 -91
  46. package/lib/build-assets.js +38 -33
  47. package/lib/collect-page-template-routes.js +102 -0
  48. package/lib/collect-static-routes.js +175 -0
  49. package/lib/diagnostics.js +58 -33
  50. package/lib/export-theme.js +84 -5
  51. package/lib/extract-template-content.js +90 -0
  52. package/lib/forms-preview.js +42 -0
  53. package/lib/functions/cpt-routing.js +69 -0
  54. package/lib/functions/forms.js +2461 -0
  55. package/lib/functions/hydration-enqueuer.js +400 -0
  56. package/lib/functions/index.js +1623 -0
  57. package/lib/functions/load-menus.js +112 -0
  58. package/lib/functions/load-translations.js +148 -0
  59. package/lib/functions/rest-endpoints.js +2923 -0
  60. package/lib/functions/routing.js +765 -0
  61. package/lib/functions/seed-mock-data.js +392 -0
  62. package/lib/functions/seed-products.js +481 -0
  63. package/lib/functions/settings-page.js +273 -0
  64. package/lib/functions/theme-setup.js +494 -0
  65. package/lib/generate-theme.js +1916 -339
  66. package/lib/hydration/editable-schemas.js +332 -0
  67. package/lib/hydration/enter-hidden-initial.js +65 -0
  68. package/lib/hydration/form-schemas.js +227 -0
  69. package/lib/hydration/index.js +12 -0
  70. package/lib/hydration/is-interactive.js +951 -0
  71. package/lib/hydration/island-split.js +1231 -0
  72. package/lib/hydration/islands-scanner.js +599 -0
  73. package/lib/hydration/resolve-island-chunk.js +103 -0
  74. package/lib/hydration/resolve-island-component.js +52 -0
  75. package/lib/hydration/rollup-inputs.js +81 -0
  76. package/lib/hydration/root-class-extractor.js +220 -0
  77. package/lib/hydration/scan-app-providers.js +154 -0
  78. package/lib/hydration/static-lint.js +382 -0
  79. package/lib/hydration/transform.js +257 -0
  80. package/lib/hydration/uses-block-area.js +49 -0
  81. package/lib/hydration/utils.js +119 -0
  82. package/lib/i18n/translation-cache.js +141 -0
  83. package/lib/icon-registry.js +72 -0
  84. package/lib/index.d.ts +287 -8
  85. package/lib/index.js +2 -1
  86. package/lib/load-config.js +338 -242
  87. package/lib/mail-templates.js +37 -0
  88. package/lib/markup-processor.js +388 -102
  89. package/lib/node-runtime.js +7 -0
  90. package/lib/page-config-plugin.js +64 -20
  91. package/lib/php-builders.js +383 -44
  92. package/lib/react-adapter.js +983 -235
  93. package/lib/registration-metadata.js +11 -0
  94. package/lib/render-theme.mts +1410 -616
  95. package/lib/route-layout.js +76 -0
  96. package/lib/template-discovery.js +58 -0
  97. package/lib/theme-compatibility.js +32 -0
  98. package/lib/validate-export.js +2 -2
  99. package/lib/validate.js +27 -5
  100. package/lib/virtual-plugin.js +319 -0
  101. package/lib/walkthrough.md +26 -0
  102. package/package.json +16 -5
  103. package/templates/auth/cms/email-logs.json +9 -0
  104. package/templates/auth/cms/menus.json +11 -0
  105. package/templates/auth/cms/mock-data.json +123 -0
  106. package/templates/auth/cms/roles.json +7 -0
  107. package/templates/auth/cms/sessions.json +1 -0
  108. package/templates/auth/cms/site-settings.json +28 -0
  109. package/templates/auth/cms/translations.json +4 -0
  110. package/templates/auth/cms/users.json +46 -0
  111. package/templates/auth/components/forgot-password-form-wrapper.tsx +10 -2
  112. package/templates/auth/components/login-form-wrapper.tsx +118 -21
  113. package/templates/auth/components/reset-password-form-wrapper.tsx +10 -2
  114. package/templates/auth/components/signup-form-wrapper.tsx +2 -2
  115. package/templates/auth/components/verify-email-view-wrapper.tsx +5 -5
  116. package/templates/auth/pages/DashboardPage.tsx +1 -4
  117. package/templates/auth/pages/ForgotPasswordPage.tsx +1 -4
  118. package/templates/auth/pages/LoginPage.tsx +1 -4
  119. package/templates/auth/pages/ResetPasswordPage.tsx +1 -4
  120. package/templates/auth/pages/SignUpPage.tsx +1 -4
  121. package/templates/auth/pages/VerifyEmailPage.tsx +1 -4
  122. package/templates/auth/ui/button.tsx +57 -0
  123. package/templates/auth/ui/card.tsx +76 -0
  124. package/templates/auth/ui/field.tsx +242 -0
  125. package/templates/auth/ui/input.tsx +22 -0
  126. package/templates/auth/ui/label.tsx +24 -0
  127. package/templates/auth/ui/separator.tsx +31 -0
  128. package/templates/menus.json +12 -10
  129. package/templates/users.json +8 -4
  130. package/templates/wordpress.tsx +690 -245
  131. package/lib/block-compiler.js +0 -552
  132. package/lib/functions-builder.js +0 -2970
  133. package/lib/hydration-scanner.js +0 -833
package/README.md CHANGED
@@ -34,6 +34,52 @@ 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
+ #### 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
+
37
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):
@@ -62,6 +108,19 @@ pnpm forgewp repair # Force restore framework utility blueprints
62
108
  pnpm forgewp clean # Prune build artifacts and clear caches
63
109
  ```
64
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
+
65
124
  ## 🔌 Configuration
66
125
 
67
126
  ForgeWP is controlled via `wp.config.ts` in your project root:
package/bin/add.js CHANGED
@@ -1,32 +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 components = args.filter(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
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
- components.push(nameEqual.split("=")[1]);
14
+ components.push(nameEqual.split('=')[1]);
15
15
  }
16
16
  }
17
17
 
18
18
  // Clean and deduplicate the component list
19
- components = Array.from(new Set(components.map(c => c.trim()).filter(Boolean)));
19
+ components = Array.from(
20
+ new Set(components.map((c) => c.trim()).filter(Boolean)),
21
+ );
20
22
 
21
- import { readFileSync, existsSync } from "node:fs";
22
- import path from "node:path";
23
+ import { readFileSync, existsSync } from 'node:fs';
24
+ import path from 'node:path';
23
25
 
24
- let projectStyle = "forgewp";
26
+ let projectStyle = 'forgewp';
25
27
  try {
26
28
  // Read wp.config.ts natively by regexing the 'style' property since it's a TS file
27
- const wpConfigPath = path.join(process.cwd(), "wp.config.ts");
29
+ const wpConfigPath = path.join(process.cwd(), 'wp.config.ts');
28
30
  if (existsSync(wpConfigPath)) {
29
- const content = readFileSync(wpConfigPath, "utf8");
31
+ const content = readFileSync(wpConfigPath, 'utf8');
30
32
  const styleMatch = content.match(/style:\s*['"](forgewp|shadcn)['"]/);
31
33
  if (styleMatch && styleMatch[1]) {
32
34
  projectStyle = styleMatch[1];
@@ -36,16 +38,20 @@ try {
36
38
  // Silent fallback
37
39
  }
38
40
 
39
- 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');
40
44
 
41
45
  if (components.length === 0) {
42
- console.error("Usage: forgewp add <component1> [component2] ... [--style=forgewp|shadcn]");
46
+ console.error(
47
+ 'Usage: forgewp add <component1> [component2] ... [--style=forgewp|shadcn] [--overwrite]',
48
+ );
43
49
  process.exit(1);
44
50
  }
45
51
 
46
52
  async function run() {
47
53
  for (const component of components) {
48
- await addComponent(component, { style });
54
+ await addComponent(component, { style, overwrite });
49
55
  }
50
56
  }
51
57
 
package/bin/cli.js CHANGED
@@ -1,36 +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:loop": path.join(__dirname, "make-loop.js"),
15
- "make:page": path.join(__dirname, "make-page.js"),
16
- "make:island": path.join(__dirname, "make-island.js"),
17
- "make:sandbox": path.join(__dirname, "make-sandbox.js"),
18
- "sync:routes": path.join(__dirname, "sync-routes.js"),
19
- "sync:hooks": path.join(__dirname, "sync-hooks.js"),
20
- "i18n:extract": path.join(__dirname, "i18n-extract.js"),
21
- "i18n:translate": path.join(__dirname, "i18n-translate.js"),
22
- export: path.join(__dirname, "export.js"),
23
- doctor: path.join(__dirname, "doctor.js"),
24
- analyze: path.join(__dirname, "analyze.js"),
25
- repair: path.join(__dirname, "repair.js"),
26
- clean: path.join(__dirname, "clean.js"),
27
- 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'),
28
43
  };
29
44
 
30
45
  const args = process.argv.slice(2);
31
46
  const command = args[0];
32
47
 
33
- if (!command || command === "-h" || command === "--help") {
48
+ if (!command || command === '-h' || command === '--help') {
34
49
  printHelp();
35
50
  process.exit(0);
36
51
  }
@@ -39,30 +54,78 @@ let targetScript = subcommands[command];
39
54
 
40
55
  // Helper fallback routes
41
56
  if (!targetScript) {
42
- if (command === "make-block" || command === "make") {
43
- targetScript = subcommands["make:block"];
44
- } else if (command === "make-post-type" || command === "post-type" || command === "make:post-type") {
45
- targetScript = subcommands["make:post-type"];
46
- } else if (command === "make-loop" || command === "loop" || command === "make:loop") {
47
- targetScript = subcommands["make:loop"];
48
- } else if (command === "make-page" || command === "page" || command === "make:page") {
49
- targetScript = subcommands["make:page"];
50
- } else if (command === "make-island" || command === "island" || command === "make:island") {
51
- targetScript = subcommands["make:island"];
52
- } else if (command === "make-sandbox" || command === "sandbox" || command === "make:sandbox") {
53
- targetScript = subcommands["make:sandbox"];
54
- } else if (command === "sync-routes" || command === "sync" || command === "sync:routes") {
55
- targetScript = subcommands["sync:routes"];
56
- } else if (command === "sync-hooks" || command === "sync:hooks") {
57
- targetScript = subcommands["sync:hooks"];
58
- } else if (command === "i18n-extract" || command === "i18n:extract") {
59
- targetScript = subcommands["i18n:extract"];
60
- } else if (command === "i18n-translate" || command === "i18n:translate") {
61
- targetScript = subcommands["i18n:translate"];
62
- } else if (command === "reset") {
63
- targetScript = subcommands["fresh"];
64
- } else if (command === "inspect" || command === "analyze") {
65
- 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'];
66
129
  }
67
130
  }
68
131
 
@@ -77,48 +140,59 @@ const commandArgs = args.slice(1);
77
140
 
78
141
  // Run the subcommand using spawn, inheriting stdio for rich interactivity
79
142
  const child = spawn(process.execPath, [targetScript, ...commandArgs], {
80
- stdio: "inherit",
143
+ stdio: 'inherit',
81
144
  });
82
145
 
83
- child.on("close", (code) => {
146
+ child.on('close', (code) => {
84
147
  process.exit(code ?? 0);
85
148
  });
86
149
 
87
150
  function printHelp() {
88
151
  console.log(`
89
- ${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')}
90
153
 
91
- ${pc.bold("Usage:")}
154
+ ${pc.bold('Usage:')}
92
155
  pnpm forgewp <command> [options]
93
156
 
94
- ${pc.bold("Commands:")}
95
- ${pc.cyan("add <component>")} Add registry components (e.g. navbar)
96
- ${pc.cyan("make:block <Name>")} Scaffold a type-safe Gutenberg Block via defineBlock()
97
- ${pc.cyan("make:post-type <slug>")} Register a custom mock post-type (e.g. portfolio)
98
- ${pc.cyan("make:loop <Name>")} Scaffold a custom post-type loop feed component
99
- ${pc.cyan("make:page <Name>")} Scaffold a custom WordPress Page Template
100
- ${pc.cyan("make:island <Name>")} Scaffold an interactive selective hydration island
101
- ${pc.cyan("make:sandbox <type>")} Scaffold sandbox mock databases (e.g. ecommerce, auth)
102
- ${pc.cyan("sync:routes")} Synchronize sitemap menus with routes and scaffold pages
103
- ${pc.cyan("sync:hooks")} Propagate wordpress.tsx hooks to all workspace projects
104
- ${pc.cyan("i18n:extract")} Extract translation strings to translations.json
105
- ${pc.cyan("i18n:translate")} Translate missing strings via the configured engine
106
- ${pc.cyan("export")} Package your theme into an installable WP zip
107
- ${pc.cyan("doctor")} Perform diagnostic check on project health
108
- ${pc.cyan("analyze")} Generate visual hydration island & size report
109
- ${pc.cyan("repair")} Force-repair/auto-heal system internals
110
- ${pc.cyan("clean")} Clear all build caches and temporary artifacts
111
- ${pc.cyan("fresh")} Reset workspace completely to factory-clean canvas
112
-
113
- ${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:')}
114
183
  pnpm forgewp add navbar
184
+ pnpm forgewp add navbar --overwrite
115
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
116
188
  pnpm forgewp make:post-type portfolio --customFields=client_name
117
189
  pnpm forgewp make:sandbox ecommerce
118
190
  pnpm forgewp make:sandbox auth
119
191
  pnpm forgewp make:loop PortfolioGrid --postType=portfolio
120
192
  pnpm forgewp make:page AboutUs
121
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
122
196
  pnpm forgewp sync:routes
123
197
  pnpm forgewp doctor
124
198
  pnpm forgewp analyze
@@ -126,5 +200,6 @@ function printHelp() {
126
200
  pnpm forgewp clean
127
201
  pnpm forgewp fresh
128
202
  pnpm forgewp export
203
+ ${blockAuthoringHelp}
129
204
  `);
130
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
  }
package/bin/export.js CHANGED
@@ -1,9 +1,9 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import path from "node:path";
4
- import { cwd } from "node:process";
5
- import pc from "picocolors";
6
- import { exportTheme } from "../lib/export-theme.js";
3
+ import path from 'node:path';
4
+ import { cwd } from 'node:process';
5
+ import pc from 'picocolors';
6
+ import { exportTheme } from '../lib/export-theme.js';
7
7
 
8
8
  function printHelp() {
9
9
  console.log(`
@@ -13,13 +13,15 @@ Options:
13
13
  --skip-build Use existing dist/ (skip Vite build)
14
14
  --no-zip Output folder only, no ZIP file
15
15
  --validate Run export validation checks after generation
16
- --strict Treat validation warnings as failures
16
+ --strict Fail on editable from/pick issues and (with --validate) validation warnings
17
17
  -h, --help Show help
18
18
 
19
19
  Examples:
20
20
  forgewp-export
21
21
  forgewp-export ./my-theme
22
22
  forgewp-export --skip-build
23
+ forgewp-export --strict
24
+ forgewp-export --validate --strict
23
25
  `);
24
26
  }
25
27
 
@@ -36,32 +38,32 @@ function parseArgs(argv) {
36
38
  for (let i = 0; i < argv.length; i += 1) {
37
39
  const arg = argv[i];
38
40
 
39
- if (arg === "-h" || arg === "--help") {
41
+ if (arg === '-h' || arg === '--help') {
40
42
  options.help = true;
41
43
  continue;
42
44
  }
43
45
 
44
- if (arg === "--skip-build") {
46
+ if (arg === '--skip-build') {
45
47
  options.skipBuild = true;
46
48
  continue;
47
49
  }
48
50
 
49
- if (arg === "--no-zip") {
51
+ if (arg === '--no-zip') {
50
52
  options.zip = false;
51
53
  continue;
52
54
  }
53
55
 
54
- if (arg === "--validate") {
56
+ if (arg === '--validate') {
55
57
  options.validate = true;
56
58
  continue;
57
59
  }
58
60
 
59
- if (arg === "--strict") {
61
+ if (arg === '--strict') {
60
62
  options.strict = true;
61
63
  continue;
62
64
  }
63
65
 
64
- if (arg.startsWith("-")) {
66
+ if (arg.startsWith('-')) {
65
67
  console.error(pc.red(`Unknown option: ${arg}`));
66
68
  process.exit(1);
67
69
  }
@@ -80,6 +82,42 @@ async function main() {
80
82
  return;
81
83
  }
82
84
 
85
+ const interactive = Boolean(process.stdout.isTTY);
86
+ const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
87
+ let spinnerIndex = 0;
88
+ let spinnerTimer;
89
+ let activeStep = null;
90
+
91
+ const drawActiveStep = () => {
92
+ if (!activeStep || !interactive) return;
93
+ process.stdout.write(
94
+ `\r\x1b[2K ${pc.cyan(spinnerFrames[spinnerIndex])} ${activeStep.message}`,
95
+ );
96
+ spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
97
+ };
98
+
99
+ const startStep = (evt) => {
100
+ if (activeStep) finishStep();
101
+ activeStep = evt;
102
+ spinnerIndex = 0;
103
+ if (interactive) {
104
+ drawActiveStep();
105
+ spinnerTimer = setInterval(drawActiveStep, 90);
106
+ } else {
107
+ console.log(` ${pc.cyan('⠋')} ${evt.message}`);
108
+ }
109
+ };
110
+
111
+ function finishStep(message = activeStep?.message) {
112
+ if (!activeStep) return;
113
+ if (spinnerTimer) clearInterval(spinnerTimer);
114
+ spinnerTimer = undefined;
115
+ if (interactive)
116
+ process.stdout.write(`\r\x1b[2K ${pc.green('✓')} ${message}\n`);
117
+ else console.log(` ${pc.green('✓')} ${message}`);
118
+ activeStep = null;
119
+ }
120
+
83
121
  try {
84
122
  const result = await exportTheme({
85
123
  themeRoot: options.themeRoot,
@@ -88,21 +126,32 @@ async function main() {
88
126
  validate: options.validate,
89
127
  strict: options.strict,
90
128
  onProgress: (evt) => {
91
- // Minimal CLI progress line (stage label)
92
- console.log(pc.dim(` [${evt.stage}] ${evt.message}`));
129
+ if (evt.stage === 'fonts-done') return;
130
+ if (evt.stage.endsWith('-done')) finishStep(evt.message);
131
+ else startStep(evt);
93
132
  },
94
133
  });
95
134
 
96
- console.log(pc.green("\n Export complete\n"));
97
- console.log(` ${pc.dim("Theme folder")} ${result.outDir}`);
98
- if (result.zipPath) {
99
- console.log(` ${pc.dim("ZIP")} ${result.zipPath}`);
100
- }
135
+ finishStep();
101
136
  console.log(
102
- `\n ${pc.dim("Install:")} Upload the ZIP to Appearance → Themes → Add New\n`,
137
+ pc.green(
138
+ ` ✓ Exported ${result.config.name} → ${result.zipPath || result.outDir}`,
139
+ ),
103
140
  );
104
141
  } catch (error) {
105
- console.error(pc.red(`\n Export failed: ${error instanceof Error ? error.message : error}\n`));
142
+ if (activeStep) {
143
+ if (spinnerTimer) clearInterval(spinnerTimer);
144
+ if (interactive)
145
+ process.stdout.write(
146
+ `\r\x1b[2K ${pc.red('✖')} ${activeStep.message}\n`,
147
+ );
148
+ activeStep = null;
149
+ }
150
+ console.error(
151
+ pc.red(
152
+ `\n Export failed: ${error instanceof Error ? error.message : error}\n`,
153
+ ),
154
+ );
106
155
  process.exit(1);
107
156
  }
108
157
  }
package/bin/fresh.js CHANGED
@@ -60,6 +60,11 @@ for (const targetPrune of directoriesToPrune) {
60
60
  // 3. Restore Standard Database & Sitemap Menus from Core Blueprints
61
61
  const coreFilesToReset = ["cms/menus.json", "cms/mock-data.json", "cms/products.json"];
62
62
  for (const relPath of coreFilesToReset) {
63
+ const tsVariant = relPath.replace(/\.json$/, ".ts");
64
+ if (existsSync(path.join(projectRoot, tsVariant))) {
65
+ console.log(` ${pc.gray("ℹ️ Skipping JSON reset")} ${pc.cyan(relPath)} ${pc.gray(`(${tsVariant} is the active source)`)}`);
66
+ continue;
67
+ }
63
68
  const fullPath = path.join(projectRoot, relPath);
64
69
  const blueprintContent = SYSTEM_BLUEPRINTS[relPath];
65
70
  if (blueprintContent) {