@forgewp/compiler 0.1.1 → 0.1.7

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.
package/README.md ADDED
@@ -0,0 +1,38 @@
1
+ # @forgewp/compiler ⚙️
2
+
3
+ The core engine of the ForgeWP ecosystem. It transforms modern React applications into standards-compliant WordPress themes.
4
+
5
+ ## 📦 Features
6
+
7
+ ### 1. Theme Export
8
+ Compiles your React components into `header.php`, `footer.php`, and `index.php`. It automatically:
9
+ - Resolves asset paths.
10
+ - Injects standard WordPress PHP hooks (`wp_head()`, `wp_footer()`).
11
+ - Replaces relative links with dynamic WordPress routing (`home_url()`).
12
+
13
+ ```bash
14
+ pnpm export
15
+ ```
16
+
17
+ ### 2. Smart Component Adder
18
+ A powerful utility that pulls components from the ForgeWP Registry or shadcn/ui and applies the signature **Sharpness Transformer**.
19
+
20
+ ```bash
21
+ pnpm forgewp:add button
22
+ ```
23
+
24
+ ## 🔌 Configuration
25
+
26
+ ForgeWP is controlled via `wp.config.ts` in your project root:
27
+
28
+ ```typescript
29
+ export default {
30
+ themeName: "My Sharp Theme",
31
+ slug: "my-sharp-theme",
32
+ style: "forgewp" // or "shadcn"
33
+ };
34
+ ```
35
+
36
+ ---
37
+
38
+ Maintainable, Scalable, WordPress-native.
@@ -1,5 +1,5 @@
1
1
  import { execSync } from "node:child_process";
2
- import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
2
+ import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
3
3
  import path from "node:path";
4
4
  import pc from "picocolors";
5
5
 
@@ -0,0 +1,316 @@
1
+ /**
2
+ * System File Blueprints — ForgeWP Compiler
3
+ *
4
+ * These are fallback templates used by the compiler's self-healing preflight check.
5
+ * If a developer accidentally deletes a system-critical library file,
6
+ * the compiler will automatically recreate it to prevent compilation and runtime errors.
7
+ */
8
+
9
+ export const SYSTEM_BLUEPRINTS = {
10
+ "src/lib/wordpress.tsx": `/**
11
+ * ForgeWP WordPress Data Hooks
12
+ *
13
+ * These hooks provide mock data during local development (Vite dev server).
14
+ * When the theme is exported, the ForgeWP compiler replaces every token
15
+ * with the equivalent WordPress PHP function call.
16
+ *
17
+ * ── Available hooks ────────────────────────────────────────────────────────
18
+ * useWpTitle() → the_title() / get_the_title()
19
+ * useWpContent() → the_content()
20
+ * useWpExcerpt() → the_excerpt()
21
+ * useWpPermalink() → get_permalink()
22
+ * useWpDate() → get_the_date()
23
+ * useWpAuthor() → get_the_author()
24
+ * useWpFeaturedImage() → get_the_post_thumbnail_url()
25
+ * useWpCategories() → the_category()
26
+ * useWpArchiveTitle() → the_archive_title()
27
+ * WpLoop → while ( have_posts() ) : the_post();
28
+ * ──────────────────────────────────────────────────────────────────────────
29
+ */
30
+ import React from "react";
31
+
32
+ const IS_DEV =
33
+ typeof import.meta !== "undefined" &&
34
+ // @ts-ignore
35
+ import.meta.env?.DEV === true;
36
+
37
+ // ── Post content ─────────────────────────────────────────────────────────────
38
+
39
+ export function useWpTitle() {
40
+ if (IS_DEV) return "Sample WordPress Post Title";
41
+ return "__FORGEWP_THE_TITLE__";
42
+ }
43
+
44
+ export function useWpContent() {
45
+ if (IS_DEV) {
46
+ return "<p>This is sample post content rendered locally so you can design your theme. In WordPress, this is replaced by the actual content from the Gutenberg editor — including blocks, shortcodes, and embeds.</p><p>You can style this area using the <code>.prose</code> utility or any Tailwind class you like.</p>";
47
+ }
48
+ return "__FORGEWP_THE_CONTENT__";
49
+ }
50
+
51
+ export function useWpExcerpt() {
52
+ if (IS_DEV) {
53
+ return "A short excerpt that gives readers a quick preview of what to expect in the full post. ForgeWP replaces this with the_excerpt() on export.";
54
+ }
55
+ return "__FORGEWP_THE_EXCERPT__";
56
+ }
57
+
58
+ export function useWpPermalink() {
59
+ if (IS_DEV) return "/post";
60
+ return "__FORGEWP_THE_PERMALINK__";
61
+ }
62
+
63
+ // ── Post meta ─────────────────────────────────────────────────────────────────
64
+
65
+ /** Returns the formatted post date. Maps to get_the_date() in WordPress. */
66
+ export function useWpDate() {
67
+ if (IS_DEV) {
68
+ return new Date().toLocaleDateString("en-US", {
69
+ year: "numeric",
70
+ month: "long",
71
+ day: "numeric",
72
+ });
73
+ }
74
+ return "__FORGEWP_THE_DATE__";
75
+ }
76
+
77
+ /** Returns the post author's display name. Maps to get_the_author() in WordPress. */
78
+ export function useWpAuthor() {
79
+ if (IS_DEV) return "Jane Doe";
80
+ return "__FORGEWP_THE_AUTHOR__";
81
+ }
82
+
83
+ /**
84
+ * Returns the featured image URL (large size).
85
+ * Maps to get_the_post_thumbnail_url(null, 'large') in WordPress.
86
+ *
87
+ * In dev, returns a placeholder image from picsum.photos.
88
+ * In your JSX, use it as: <img src={featuredImage} alt={title} />
89
+ */
90
+ export function useWpFeaturedImage() {
91
+ if (IS_DEV) return "https://picsum.photos/seed/forgewp/1200/630";
92
+ return "__FORGEWP_THE_POST_THUMBNAIL_URL__";
93
+ }
94
+
95
+ /**
96
+ * Returns the post's categories as an HTML string (links separated by commas).
97
+ * Maps to the_category(', ') in WordPress.
98
+ *
99
+ * Use with dangerouslySetInnerHTML since it contains anchor tags.
100
+ * @example
101
+ * const categories = useWpCategories();
102
+ * <div dangerouslySetInnerHTML={{ __html: categories }} />
103
+ */
104
+ export function useWpCategories() {
105
+ if (IS_DEV) {
106
+ return '<a href="#">Technology</a>, <a href="#">Design</a>';
107
+ }
108
+ return "__FORGEWP_THE_CATEGORY_LIST__";
109
+ }
110
+
111
+ /**
112
+ * Returns the archive page title (e.g. "Category: Technology", "Tag: React").
113
+ * Maps to the_archive_title() in WordPress.
114
+ * Use this in archive.tsx — not needed for single posts.
115
+ */
116
+ export function useWpArchiveTitle() {
117
+ if (IS_DEV) return "Category: Technology";
118
+ return "__FORGEWP_THE_ARCHIVE_TITLE__";
119
+ }
120
+
121
+ // ── Loop ──────────────────────────────────────────────────────────────────────
122
+
123
+ /**
124
+ * \`<WpLoop>\` — Renders a WordPress post loop.
125
+ *
126
+ * In dev: renders your children 3 times with mock data so you can design your layout.
127
+ * On export: wraps your JSX in a real \`while (have_posts()) : the_post();\` PHP loop.
128
+ *
129
+ * @example
130
+ * <WpLoop>
131
+ * <PostCard />
132
+ * </WpLoop>
133
+ */
134
+ export function WpLoop({ children }: { children: React.ReactNode }) {
135
+ if (IS_DEV) {
136
+ // Render 3 dummy posts so the developer can design the grid/list layout
137
+ return (
138
+ <>
139
+ {children}
140
+ {children}
141
+ {children}
142
+ </>
143
+ );
144
+ }
145
+
146
+ // In production: custom elements become compiler tokens → PHP loop
147
+ return (
148
+ <>
149
+ {/* @ts-ignore — custom elements used as ForgeWP compiler tokens */}
150
+ <forgewp-loop-start />
151
+ {children}
152
+ {/* @ts-ignore */}
153
+ <forgewp-loop-end />
154
+ </>
155
+ );
156
+ }
157
+ `,
158
+
159
+ "src/lib/SEO.tsx": `import * as ReactHelmetAsync from "react-helmet-async";
160
+ import { useWpTitle } from "./wordpress";
161
+
162
+ // Support both ESM and CommonJS exports of react-helmet-async across Vite and TSX compiler
163
+ const Helmet = (ReactHelmetAsync.Helmet || (ReactHelmetAsync as any)["default"]?.Helmet || ReactHelmetAsync) as any;
164
+
165
+ /**
166
+ * ForgeWP SEO — Internal system file. Do not delete.
167
+ *
168
+ * Use this component in \`src/app/layout.tsx\` to set global SEO defaults,
169
+ * and in individual page files to override them per-page.
170
+ *
171
+ * The ForgeWP compiler reads the props you pass here and injects them
172
+ * directly into the WordPress theme's <head> as native meta tags.
173
+ *
174
+ * @see https://forgewp.dev/docs/seo
175
+ */
176
+
177
+ export interface SEOProps {
178
+ /** Page title — defaults to the WordPress post title via useWpTitle() */
179
+ title?: string;
180
+ /** Meta description for search engines and social cards */
181
+ description?: string;
182
+ /** Comma-separated keywords */
183
+ keywords?: string;
184
+ /** Open Graph title (falls back to title if omitted) */
185
+ ogTitle?: string;
186
+ /** Open Graph description (falls back to description if omitted) */
187
+ ogDescription?: string;
188
+ /** Absolute URL to the Open Graph image */
189
+ ogImage?: string;
190
+ /** Open Graph type — "website" for homepages, "article" for posts */
191
+ ogType?: string;
192
+ /** Twitter card type */
193
+ twitterCard?: string;
194
+ /** Twitter creator handle, e.g. "@username" */
195
+ twitterCreator?: string;
196
+ /** Canonical URL — tells search engines the preferred version of this page */
197
+ canonical?: string;
198
+ /** Set to true to prevent this page from being indexed by search engines */
199
+ noIndex?: boolean;
200
+ }
201
+
202
+ /**
203
+ * \`<SEO>\` — ForgeWP SEO manager.
204
+ *
205
+ * Drop this into your **layout.tsx** to set site-wide defaults.
206
+ * Then drop it into any **page file** to override for that specific template.
207
+ *
208
+ * @example
209
+ * // layout.tsx — global defaults (the compiler reads these for all pages)
210
+ * <SEO
211
+ * description="Your site tagline or description."
212
+ * keywords="WordPress, React, Tailwind"
213
+ * ogImage="https://yoursite.com/og-default.png"
214
+ * />
215
+ *
216
+ * @example
217
+ * // single.tsx — per-page override (article-specific metadata)
218
+ * <SEO
219
+ * ogType="article"
220
+ * ogImage="https://yoursite.com/og-post.png"
221
+ * twitterCreator="@yourhandle"
222
+ * />
223
+ */
224
+ export function SEO({
225
+ title,
226
+ description = "A WordPress theme built with ForgeWP — React & Tailwind CSS.",
227
+ keywords = "WordPress, React, Tailwind CSS, ForgeWP",
228
+ ogTitle,
229
+ ogDescription,
230
+ ogImage,
231
+ ogType = "website",
232
+ twitterCard = "summary_large_image",
233
+ twitterCreator,
234
+ canonical,
235
+ noIndex = false,
236
+ }: SEOProps) {
237
+ const wpTitle = useWpTitle();
238
+ const resolvedTitle = title ?? wpTitle;
239
+
240
+ return (
241
+ <Helmet>
242
+ {/* ── Primary ── */}
243
+ <title>{resolvedTitle}</title>
244
+ <meta name="description" content={description} />
245
+ {keywords && <meta name="keywords" content={keywords} />}
246
+ {noIndex && <meta name="robots" content="noindex, nofollow" />}
247
+ {canonical && <link rel="canonical" href={canonical} />}
248
+
249
+ {/* ── Open Graph ── */}
250
+ <meta property="og:type" content={ogType} />
251
+ <meta property="og:title" content={ogTitle ?? resolvedTitle} />
252
+ <meta property="og:description" content={ogDescription ?? description} />
253
+ {ogImage && <meta property="og:image" content={ogImage} />}
254
+
255
+ {/* ── Twitter ── */}
256
+ <meta name="twitter:card" content={twitterCard} />
257
+ <meta name="twitter:title" content={ogTitle ?? resolvedTitle} />
258
+ <meta name="twitter:description" content={ogDescription ?? description} />
259
+ {ogImage && <meta name="twitter:image" content={ogImage} />}
260
+ {twitterCreator && <meta name="twitter:creator" content={twitterCreator} />}
261
+ </Helmet>
262
+ );
263
+ }
264
+ `,
265
+
266
+ "src/lib/PresetsStyle.tsx": `import wpConfig from "../../wp.config";
267
+
268
+ const IS_DEV =
269
+ typeof import.meta !== "undefined" &&
270
+ // @ts-ignore
271
+ import.meta.env?.DEV === true;
272
+
273
+ /**
274
+ * PresetsStyle component — Internal system component.
275
+ *
276
+ * Dynamically injects WordPress-preset CSS Custom Properties and enqueues Google Fonts
277
+ * during local Vite development, keeping your styles perfectly in sync with WordPress.
278
+ * In production builds, this returns null and is completely skipped since WordPress
279
+ * native styles are enqueued automatically.
280
+ */
281
+ export function PresetsStyle() {
282
+ if (!IS_DEV) return null;
283
+
284
+ // Local development fallbacks for WordPress CSS presets
285
+ const colors = wpConfig.settings?.color?.palette || [];
286
+ const fontSizes = wpConfig.settings?.typography?.fontSizes || [];
287
+ const fontFamilies = wpConfig.settings?.typography?.fontFamilies || [];
288
+ const layout = wpConfig.settings?.layout || {};
289
+ const googleFonts = wpConfig.settings?.typography?.googleFonts || [];
290
+
291
+ // Parse and build Google Fonts href for dev injection
292
+ const fontsHtml = googleFonts.length > 0
293
+ ? \`<link rel="preconnect" href="https://fonts.googleapis.com">
294
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
295
+ <link href="https://fonts.googleapis.com/css2?family=\${googleFonts.map(f => encodeURIComponent(f)).join("&family=")}&display=swap" rel="stylesheet">\`
296
+ : "";
297
+
298
+ const css = \`
299
+ :root {
300
+ \${colors.map((c) => \`--wp--preset--color--\${c.slug}: \${c.color};\`).join("\\n ")}
301
+ \${fontSizes.map((f) => \`--wp--preset--font-size--\${f.slug}: \${f.size};\`).join("\\n ")}
302
+ \${fontFamilies.map((f) => \`--wp--preset--font-family--\${f.slug}: \${f.fontFamily};\`).join("\\n ")}
303
+ \${layout.contentSize ? \`--wp--style--global--content-size: \${layout.contentSize};\` : ""}
304
+ \${layout.wideSize ? \`--wp--style--global--wide-size: \${layout.wideSize};\` : ""}
305
+ }
306
+ \`;
307
+
308
+ return (
309
+ <>
310
+ {fontsHtml && <span dangerouslySetInnerHTML={{ __html: fontsHtml }} />}
311
+ <style dangerouslySetInnerHTML={{ __html: css }} />
312
+ </>
313
+ );
314
+ }
315
+ `
316
+ };
@@ -6,6 +6,8 @@ import { loadConfig } from "./load-config.js";
6
6
  import { renderStaticMarkup } from "./render-static.js";
7
7
  import { assertZipCreated, zipTheme } from "./zip-theme.js";
8
8
 
9
+ import { validateCriticalFiles } from "./validate.js";
10
+
9
11
  /**
10
12
  * @param {Object} options
11
13
  * @param {string} options.themeRoot
@@ -15,6 +17,10 @@ import { assertZipCreated, zipTheme } from "./zip-theme.js";
15
17
  */
16
18
  export async function exportTheme(options) {
17
19
  const themeRoot = path.resolve(options.themeRoot);
20
+
21
+ // Run Preflight Safeguards and Self-Healing checks
22
+ validateCriticalFiles(themeRoot);
23
+
18
24
  const config = await loadConfig(themeRoot);
19
25
 
20
26
  console.log(pc.cyan(`\n ForgeWP export — ${config.name}\n`));
@@ -37,6 +43,11 @@ export async function exportTheme(options) {
37
43
  appHtml: markup.appHtml,
38
44
  headerHtml: markup.headerHtml,
39
45
  footerHtml: markup.footerHtml,
46
+ headHtml: markup.headHtml,
47
+ singleHeadHtml: markup.singleHeadHtml,
48
+ singleHtml: markup.singleHtml,
49
+ notFoundHtml: markup.notFoundHtml,
50
+ archiveHtml: markup.archiveHtml,
40
51
  assets,
41
52
  });
42
53
 
@@ -1,4 +1,4 @@
1
- import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
1
+ import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2
2
  import path from "node:path";
3
3
 
4
4
  /**
@@ -18,6 +18,11 @@ export function generateTheme({
18
18
  appHtml,
19
19
  headerHtml = "",
20
20
  footerHtml = "",
21
+ headHtml = "",
22
+ singleHeadHtml = "",
23
+ singleHtml = "",
24
+ notFoundHtml = "",
25
+ archiveHtml = "",
21
26
  assets,
22
27
  }) {
23
28
  if (existsSync(outDir)) {
@@ -55,11 +60,56 @@ export function generateTheme({
55
60
  contentHtml = contentHtml.replace(processedFooter, "");
56
61
  }
57
62
 
63
+ // Process single post template if exists
64
+ let processedSingle = "";
65
+ if (singleHtml) {
66
+ processedSingle = processMarkup(singleHtml);
67
+ if (processedHeader) {
68
+ processedSingle = processedSingle.replace(processedHeader, "");
69
+ }
70
+ if (processedFooter) {
71
+ processedSingle = processedSingle.replace(processedFooter, "");
72
+ }
73
+ }
74
+
75
+ // Process 404 template if exists
76
+ let processedNotFound = "";
77
+ if (notFoundHtml) {
78
+ processedNotFound = processMarkup(notFoundHtml);
79
+ if (processedHeader) {
80
+ processedNotFound = processedNotFound.replace(processedHeader, "");
81
+ }
82
+ if (processedFooter) {
83
+ processedNotFound = processedNotFound.replace(processedFooter, "");
84
+ }
85
+ }
86
+
58
87
  const staticDir = path.join(outDir, "forgewp-static");
59
88
  mkdirSync(staticDir, { recursive: true });
60
89
  writeFileSync(path.join(staticDir, "content.html"), contentHtml, "utf8");
61
90
  writeFileSync(path.join(staticDir, "header.html"), processedHeader, "utf8");
62
91
  writeFileSync(path.join(staticDir, "footer.html"), processedFooter, "utf8");
92
+ if (headHtml) {
93
+ writeFileSync(path.join(staticDir, "head.html"), headHtml, "utf8");
94
+ }
95
+ if (singleHeadHtml) {
96
+ writeFileSync(path.join(staticDir, "single-head.html"), singleHeadHtml, "utf8");
97
+ }
98
+ if (processedSingle) {
99
+ writeFileSync(path.join(staticDir, "single.html"), processedSingle, "utf8");
100
+ }
101
+ if (processedNotFound) {
102
+ writeFileSync(path.join(staticDir, "404.html"), processedNotFound, "utf8");
103
+ }
104
+
105
+ // Archive page (category / tag / date archives)
106
+ let processedArchive = "";
107
+ if (archiveHtml) {
108
+ processedArchive = processMarkup(archiveHtml);
109
+ if (processedHeader) processedArchive = processedArchive.replace(processedHeader, "");
110
+ if (processedFooter) processedArchive = processedArchive.replace(processedFooter, "");
111
+ writeFileSync(path.join(staticDir, "archive.html"), processedArchive, "utf8");
112
+ }
63
113
 
64
114
  writeFileSync(path.join(outDir, "style.css"), buildStyleCss(config), "utf8");
65
115
  writeFileSync(
@@ -71,13 +121,64 @@ export function generateTheme({
71
121
  writeFileSync(path.join(outDir, "footer.php"), buildFooterPhp(config), "utf8");
72
122
  writeFileSync(path.join(outDir, "index.php"), buildIndexPhp(), "utf8");
73
123
  writeFileSync(path.join(outDir, "single.php"), buildSinglePhp(), "utf8");
124
+ writeFileSync(path.join(outDir, "404.php"), build404Php(), "utf8");
74
125
  writeFileSync(path.join(outDir, "front-page.php"), buildIndexPhp(), "utf8");
126
+ writeFileSync(path.join(outDir, "archive.php"), buildArchivePhp(), "utf8");
127
+ writeFileSync(path.join(outDir, "page.php"), buildPagePhp(), "utf8");
75
128
 
129
+ // Dynamic theme.json compiler (Phase 5)
76
130
  const themeJsonSrc = path.join(themeRoot, "wordpress", "theme.json");
131
+ let themeJson = {
132
+ "$schema": "https://schemas.wp.org/trunk/theme.json",
133
+ "version": 3,
134
+ "settings": {
135
+ "appearanceTools": true,
136
+ },
137
+ };
138
+
77
139
  if (existsSync(themeJsonSrc)) {
78
- copyFileSync(themeJsonSrc, path.join(outDir, "theme.json"));
140
+ try {
141
+ themeJson = JSON.parse(readFileSync(themeJsonSrc, "utf8"));
142
+ } catch (e) {
143
+ console.warn("Failed to parse theme.json template:", e.message);
144
+ }
79
145
  }
80
146
 
147
+ // Merge tokens from wp.config.ts
148
+ if (config.settings) {
149
+ if (!themeJson.settings) themeJson.settings = {};
150
+
151
+ // Layout (contentSize, wideSize)
152
+ if (config.settings.layout) {
153
+ themeJson.settings.layout = {
154
+ ...themeJson.settings.layout,
155
+ ...config.settings.layout,
156
+ };
157
+ }
158
+
159
+ // Colors (custom, palette)
160
+ if (config.settings.color) {
161
+ themeJson.settings.color = {
162
+ ...themeJson.settings.color,
163
+ ...config.settings.color,
164
+ };
165
+ }
166
+
167
+ // Typography (fontSizes, fontFamilies)
168
+ if (config.settings.typography) {
169
+ themeJson.settings.typography = {
170
+ ...themeJson.settings.typography,
171
+ ...config.settings.typography,
172
+ };
173
+ }
174
+ }
175
+
176
+ writeFileSync(
177
+ path.join(outDir, "theme.json"),
178
+ JSON.stringify(themeJson, null, 2),
179
+ "utf8"
180
+ );
181
+
81
182
  const screenshot = path.join(themeRoot, "wordpress", "screenshot.png");
82
183
  if (existsSync(screenshot)) {
83
184
  copyFileSync(screenshot, path.join(outDir, "screenshot.png"));
@@ -92,12 +193,80 @@ function processMarkup(html) {
92
193
  // Fix nav links — # → <?php echo esc_url( home_url( '/' ) ); ?>
93
194
  // We use a placeholder and replace it in the PHP file generation if needed,
94
195
  // but for now we'll do it via string replacement in the template files.
95
- return html.replace(
196
+ let processed = html.replace(
96
197
  /href="#"/g,
97
198
  'href="<?php echo esc_url( home_url( \'/\' ) ); ?>"',
98
199
  );
200
+
201
+ processed = processed.replace(
202
+ /__FORGEWP_THE_TITLE__/g,
203
+ '<?php the_title(); ?>'
204
+ );
205
+
206
+ processed = processed.replace(
207
+ /__FORGEWP_THE_CONTENT__/g,
208
+ '<?php the_content(); ?>'
209
+ );
210
+
211
+ processed = processed.replace(
212
+ /__FORGEWP_THE_PERMALINK__/g,
213
+ '<?php the_permalink(); ?>'
214
+ );
215
+
216
+ processed = processed.replace(
217
+ /__FORGEWP_THE_EXCERPT__/g,
218
+ '<?php the_excerpt(); ?>'
219
+ );
220
+
221
+ processed = processed.replace(
222
+ /__FORGEWP_THE_DATE__/g,
223
+ "<?php echo esc_html( get_the_date() ); ?>"
224
+ );
225
+
226
+ processed = processed.replace(
227
+ /__FORGEWP_THE_AUTHOR__/g,
228
+ "<?php echo esc_html( get_the_author() ); ?>"
229
+ );
230
+
231
+ processed = processed.replace(
232
+ /__FORGEWP_THE_POST_THUMBNAIL_URL__/g,
233
+ "<?php echo esc_url( get_the_post_thumbnail_url( null, 'large' ) ); ?>"
234
+ );
235
+
236
+ processed = processed.replace(
237
+ /__FORGEWP_THE_CATEGORY_LIST__/g,
238
+ "<?php the_category( ', ' ); ?>"
239
+ );
240
+
241
+ processed = processed.replace(
242
+ /__FORGEWP_THE_ARCHIVE_TITLE__/g,
243
+ "<?php the_archive_title(); ?>"
244
+ );
245
+
246
+ processed = processed.replace(
247
+ /<forgewp-loop-start\s*\/?>/g,
248
+ '<?php if (have_posts()) : while (have_posts()) : the_post(); ?>'
249
+ );
250
+
251
+ processed = processed.replace(
252
+ /<\/forgewp-loop-start>/g,
253
+ ''
254
+ );
255
+
256
+ processed = processed.replace(
257
+ /<forgewp-loop-end\s*\/?>/g,
258
+ '<?php endwhile; else : echo "<p>No posts found.</p>"; endif; ?>'
259
+ );
260
+
261
+ processed = processed.replace(
262
+ /<\/forgewp-loop-end>/g,
263
+ ''
264
+ );
265
+
266
+ return processed;
99
267
  }
100
268
 
269
+
101
270
  /**
102
271
  * @param {import('./types.js').ForgeWPThemeConfig} config
103
272
  */
@@ -127,6 +296,42 @@ Text Domain: ${config.textDomain}
127
296
  function buildFunctionsPhp(config, assets) {
128
297
  const css = assets.cssFile.replace(/^assets\//, "");
129
298
  const version = config.version.replace(/'/g, "\\'");
299
+ const googleFonts = config.settings?.typography?.googleFonts || [];
300
+
301
+ let fontsEnqueue = "";
302
+ let preconnectFilter = "";
303
+
304
+ if (googleFonts.length > 0) {
305
+ const fontsParam = googleFonts.map(f => encodeURIComponent(f)).join("&family=");
306
+ fontsEnqueue = `
307
+ // Enqueue Google Fonts (dynamic preset via wp.config.ts)
308
+ wp_enqueue_style(
309
+ '${config.textDomain}-google-fonts',
310
+ 'https://fonts.googleapis.com/css2?family=${fontsParam}&display=swap',
311
+ array(),
312
+ null
313
+ );`;
314
+
315
+ preconnectFilter = `
316
+ /**
317
+ * Add preconnect resource hints for Google Fonts performance.
318
+ */
319
+ function forgewp_google_fonts_resource_hints(array $urls, string $relation_type): array {
320
+ if (wp_style_is('${config.textDomain}-google-fonts', 'queue') && 'preconnect' === $relation_type) {
321
+ $urls[] = array(
322
+ 'href' => 'https://fonts.googleapis.com',
323
+ 'crossorigin' => 'anonymous',
324
+ );
325
+ $urls[] = array(
326
+ 'href' => 'https://fonts.gstatic.com',
327
+ 'crossorigin' => 'anonymous',
328
+ );
329
+ }
330
+ return $urls;
331
+ }
332
+ add_filter('wp_resource_hints', 'forgewp_google_fonts_resource_hints', 10, 2);
333
+ `;
334
+ }
130
335
 
131
336
  return `<?php
132
337
  /**
@@ -142,11 +347,12 @@ if (! defined('ABSPATH')) {
142
347
  define('FORGEWP_THEME_VERSION', '${version}');
143
348
 
144
349
  /**
145
- * Enqueue compiled theme assets (CSS only in v1 — static HTML, no hydration).
350
+ * Enqueue compiled theme assets.
146
351
  */
147
352
  function forgewp_enqueue_assets(): void {
148
353
  $theme_uri = get_template_directory_uri();
149
354
  $css_path = get_template_directory() . '/assets/${css}';
355
+ ${fontsEnqueue}
150
356
 
151
357
  if (file_exists($css_path)) {
152
358
  wp_enqueue_style(
@@ -170,7 +376,7 @@ function forgewp_theme_setup(): void {
170
376
  add_theme_support('editor-styles');
171
377
  }
172
378
  add_action('after_setup_theme', 'forgewp_theme_setup');
173
- `;
379
+ ${preconnectFilter}`;
174
380
  }
175
381
 
176
382
  function buildHeaderPhp(config) {
@@ -185,6 +391,15 @@ function buildHeaderPhp(config) {
185
391
  <head>
186
392
  <meta charset="<?php bloginfo('charset'); ?>">
187
393
  <meta name="viewport" content="width=device-width, initial-scale=1">
394
+ <?php
395
+ $single_head = get_template_directory() . '/forgewp-static/single-head.html';
396
+ $head_file = get_template_directory() . '/forgewp-static/head.html';
397
+ if (is_single() && file_exists($single_head)) {
398
+ include $single_head;
399
+ } elseif (file_exists($head_file)) {
400
+ include $head_file;
401
+ }
402
+ ?>
188
403
  <?php wp_head(); ?>
189
404
  <style>
190
405
  /* Reset WP link underlines to match React/Tailwind expected styling */
@@ -263,17 +478,133 @@ function buildSinglePhp() {
263
478
 
264
479
  get_header();
265
480
 
266
- if (have_posts()) {
267
- while (have_posts()) {
268
- the_post();
269
- echo '<main class="mx-auto max-w-3xl px-6 py-12">';
270
- echo '<article>';
271
- echo '<h1 class="text-4xl font-bold mb-6">' . get_the_title() . '</h1>';
272
- echo '<div class="prose prose-zinc max-w-none">';
273
- the_content();
481
+ $single_file = get_template_directory() . '/forgewp-static/single.html';
482
+ if (file_exists($single_file)) {
483
+ if (have_posts()) {
484
+ while (have_posts()) {
485
+ the_post();
486
+ include $single_file;
487
+ }
488
+ }
489
+ } else {
490
+ if (have_posts()) {
491
+ while (have_posts()) {
492
+ the_post();
493
+ echo '<main class="mx-auto max-w-3xl px-6 py-12">';
494
+ echo '<article>';
495
+ echo '<h1 class="text-4xl font-bold mb-6">' . get_the_title() . '</h1>';
496
+ echo '<div class="prose prose-zinc max-w-none">';
497
+ the_content();
498
+ echo '</div>';
499
+ echo '</article>';
500
+ echo '</main>';
501
+ }
502
+ }
503
+ }
504
+
505
+ get_footer();
506
+ `;
507
+ }
508
+
509
+ function build404Php() {
510
+ return `<?php
511
+ /**
512
+ * 404 template
513
+ *
514
+ * @package forgewp
515
+ */
516
+
517
+ get_header();
518
+
519
+ $notFound_file = get_template_directory() . '/forgewp-static/404.html';
520
+ if (file_exists($notFound_file)) {
521
+ include $notFound_file;
522
+ } else {
523
+ echo '<main class="flex min-h-[60vh] flex-col items-center justify-center text-center px-6 py-24">';
524
+ echo '<p class="text-base font-semibold text-zinc-900">404</p>';
525
+ echo '<h1 class="mt-4 text-3xl font-bold tracking-tight text-zinc-900 sm:text-5xl">Page not found</h1>';
526
+ echo '<p class="mt-6 text-base leading-7 text-zinc-600">Sorry, we couldn’t find the page you’re looking for.</p>';
527
+ echo '</main>';
528
+ }
529
+
530
+ get_footer();
531
+ `;
532
+ }
533
+
534
+ function buildArchivePhp() {
535
+ return `<?php
536
+ /**
537
+ * Archive template — category, tag, date, and author archives.
538
+ * Loads the ForgeWP compiled archive.html which contains the WpLoop.
539
+ *
540
+ * @package forgewp
541
+ */
542
+
543
+ get_header();
544
+
545
+ $archive_file = get_template_directory() . '/forgewp-static/archive.html';
546
+
547
+ if (file_exists($archive_file)) {
548
+ include $archive_file;
549
+ } else {
550
+ echo '<main class="mx-auto max-w-3xl px-6 py-12">';
551
+ the_archive_title('<h1 class="text-3xl font-bold mb-8">', '</h1>');
552
+ if (have_posts()) {
553
+ echo '<div class="space-y-8">';
554
+ while (have_posts()) {
555
+ the_post();
556
+ echo '<article>';
557
+ echo '<h2 class="text-xl font-bold"><a href="' . get_permalink() . '">' . get_the_title() . '</a></h2>';
558
+ echo '<div class="text-sm text-zinc-500 mt-1">' . get_the_date() . ' by ' . get_the_author() . '</div>';
559
+ echo '<div class="mt-3 text-zinc-600">';
560
+ the_excerpt();
561
+ echo '</div>';
562
+ echo '</article>';
563
+ }
274
564
  echo '</div>';
275
- echo '</article>';
276
- echo '</main>';
565
+ } else {
566
+ echo '<p>No posts found.</p>';
567
+ }
568
+ echo '</main>';
569
+ }
570
+
571
+ get_footer();
572
+ `;
573
+ }
574
+
575
+ function buildPagePhp() {
576
+ return `<?php
577
+ /**
578
+ * Static page template — WordPress pages (e.g. About, Contact).
579
+ * Reuses single.html since static pages share the same title+content structure.
580
+ *
581
+ * @package forgewp
582
+ */
583
+
584
+ get_header();
585
+
586
+ $page_file = get_template_directory() . '/forgewp-static/single.html';
587
+
588
+ if (file_exists($page_file)) {
589
+ if (have_posts()) {
590
+ while (have_posts()) {
591
+ the_post();
592
+ include $page_file;
593
+ }
594
+ }
595
+ } else {
596
+ if (have_posts()) {
597
+ while (have_posts()) {
598
+ the_post();
599
+ echo '<main class="mx-auto max-w-3xl px-6 py-12">';
600
+ echo '<article>';
601
+ echo '<h1 class="text-4xl font-bold mb-6">' . get_the_title() . '</h1>';
602
+ echo '<div class="prose prose-zinc max-w-none">';
603
+ the_content();
604
+ echo '</div>';
605
+ echo '</article>';
606
+ echo '</main>';
607
+ }
277
608
  }
278
609
  }
279
610
 
package/lib/index.d.ts ADDED
@@ -0,0 +1,60 @@
1
+ export interface ColorPreset {
2
+ name: string;
3
+ slug: string;
4
+ color: string;
5
+ }
6
+
7
+ export interface FontSizePreset {
8
+ name: string;
9
+ slug: string;
10
+ size: string;
11
+ }
12
+
13
+ export interface FontFamilyPreset {
14
+ name: string;
15
+ slug: string;
16
+ fontFamily: string;
17
+ }
18
+
19
+ export interface ForgeWPThemeConfig {
20
+ name: string;
21
+ slug: string;
22
+ version: string;
23
+ description: string;
24
+ textDomain: string;
25
+ settings?: {
26
+ layout?: {
27
+ contentSize?: string;
28
+ wideSize?: string;
29
+ };
30
+ color?: {
31
+ palette?: ColorPreset[];
32
+ custom?: boolean;
33
+ };
34
+ typography?: {
35
+ fontSizes?: FontSizePreset[];
36
+ fontFamilies?: FontFamilyPreset[];
37
+ googleFonts?: string[];
38
+ };
39
+ };
40
+ }
41
+
42
+ export interface ForgeWPBuildAssets {
43
+ cssFile: string;
44
+ }
45
+
46
+ export function exportTheme(options: {
47
+ themeRoot: string;
48
+ skipBuild?: boolean;
49
+ zip?: boolean;
50
+ packageManager?: string;
51
+ }): Promise<{
52
+ config: ForgeWPThemeConfig;
53
+ outDir: string;
54
+ zipPath: string | null;
55
+ assets: ForgeWPBuildAssets;
56
+ }>;
57
+
58
+ export function loadConfig(themeRoot: string): Promise<ForgeWPThemeConfig>;
59
+
60
+ export function validateCriticalFiles(themeRoot: string): void;
package/lib/index.js CHANGED
@@ -1,2 +1,3 @@
1
1
  export { exportTheme } from "./export-theme.js";
2
2
  export { loadConfig } from "./load-config.js";
3
+ export { validateCriticalFiles } from "./validate.js";
@@ -53,6 +53,11 @@ export async function renderStaticMarkup(themeRoot) {
53
53
 
54
54
  const headerHtmlPath = path.join(outDir, "header.html");
55
55
  const footerHtmlPath = path.join(outDir, "footer.html");
56
+ const headHtmlPath = path.join(outDir, "head.html");
57
+ const singleHtmlPath = path.join(outDir, "single.html");
58
+ const singleHeadHtmlPath = path.join(outDir, "single-head.html");
59
+ const notFoundHtmlPath = path.join(outDir, "404.html");
60
+ const archiveHtmlPath = path.join(outDir, "archive.html");
56
61
 
57
62
  return {
58
63
  appHtml: readFileSync(appHtmlPath, "utf8"),
@@ -62,5 +67,20 @@ export async function renderStaticMarkup(themeRoot) {
62
67
  footerHtml: existsSync(footerHtmlPath)
63
68
  ? readFileSync(footerHtmlPath, "utf8")
64
69
  : "",
70
+ headHtml: existsSync(headHtmlPath)
71
+ ? readFileSync(headHtmlPath, "utf8")
72
+ : "",
73
+ singleHtml: existsSync(singleHtmlPath)
74
+ ? readFileSync(singleHtmlPath, "utf8")
75
+ : "",
76
+ singleHeadHtml: existsSync(singleHeadHtmlPath)
77
+ ? readFileSync(singleHeadHtmlPath, "utf8")
78
+ : "",
79
+ notFoundHtml: existsSync(notFoundHtmlPath)
80
+ ? readFileSync(notFoundHtmlPath, "utf8")
81
+ : "",
82
+ archiveHtml: existsSync(archiveHtmlPath)
83
+ ? readFileSync(archiveHtmlPath, "utf8")
84
+ : "",
65
85
  };
66
86
  }
@@ -1,48 +1,200 @@
1
- import { mkdirSync, writeFileSync } from "node:fs";
2
- import path from "node:path";
3
- import { pathToFileURL } from "node:url";
4
- import { createRequire } from "node:module";
5
-
6
- const themeRoot = process.argv[2];
7
-
8
- if (!themeRoot) {
9
- console.error("Usage: render-theme.mts <theme-root>");
10
- process.exit(1);
11
- }
12
-
13
- const require = createRequire(path.join(themeRoot, "package.json"));
14
- const React = require("react");
15
- const { renderToStaticMarkup } = require("react-dom/server");
16
-
17
- const appUrl = pathToFileURL(path.join(themeRoot, "src", "App.tsx")).href;
18
- const headerUrl = pathToFileURL(path.join(themeRoot, "src", "components", "SiteHeader.tsx")).href;
19
- const footerUrl = pathToFileURL(path.join(themeRoot, "src", "components", "SiteFooter.tsx")).href;
20
-
21
- const { default: App } = await import(appUrl);
22
-
23
- let headerHtml = "";
24
- try {
25
- const { SiteHeader } = await import(headerUrl);
26
- headerHtml = renderToStaticMarkup(React.createElement(SiteHeader));
27
- } catch (e) {
28
- console.warn("SiteHeader not found, skipping separate render");
29
- }
30
-
31
- let footerHtml = "";
32
- try {
33
- const { SiteFooter } = await import(footerUrl);
34
- footerHtml = renderToStaticMarkup(React.createElement(SiteFooter));
35
- } catch (e) {
36
- console.warn("SiteFooter not found, skipping separate render");
37
- }
38
-
39
- const appHtml = renderToStaticMarkup(React.createElement(App));
40
-
41
- const outDir = path.join(themeRoot, ".forgewp");
42
- mkdirSync(outDir, { recursive: true });
43
-
44
- writeFileSync(path.join(outDir, "header.html"), headerHtml, "utf8");
45
- writeFileSync(path.join(outDir, "footer.html"), footerHtml, "utf8");
46
- writeFileSync(path.join(outDir, "app.html"), appHtml, "utf8");
47
-
48
- process.stdout.write(outDir);
1
+ import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { pathToFileURL } from "node:url";
4
+ import { createRequire } from "node:module";
5
+
6
+ const themeRoot = process.argv[2];
7
+
8
+ if (!themeRoot) {
9
+ console.error("Usage: render-theme.mts <theme-root>");
10
+ process.exit(1);
11
+ }
12
+
13
+ // Use the theme's own node_modules for ALL packages (React 19)
14
+ const require = createRequire(path.join(themeRoot, "package.json"));
15
+ const React = require("react");
16
+ const { renderToStaticMarkup } = require("react-dom/server");
17
+
18
+ const appUrl = pathToFileURL(path.join(themeRoot, "src", "app", "page.tsx")).href;
19
+ const headerUrl = pathToFileURL(path.join(themeRoot, "src", "components", "SiteHeader.tsx")).href;
20
+ const footerUrl = pathToFileURL(path.join(themeRoot, "src", "components", "SiteFooter.tsx")).href;
21
+ const layoutUrl = pathToFileURL(path.join(themeRoot, "src", "app", "layout.tsx")).href;
22
+ const layoutPath = path.join(themeRoot, "src", "app", "layout.tsx");
23
+
24
+ // ── Load pages ────────────────────────────────────────────────────────────────
25
+ const { default: App } = await import(appUrl);
26
+
27
+ let RootLayout: (props: any) => any = ({ children }: any) =>
28
+ React.createElement(React.Fragment, null, children);
29
+ try {
30
+ const { default: LoadedLayout } = await import(layoutUrl);
31
+ RootLayout = LoadedLayout;
32
+ } catch {
33
+ console.warn("RootLayout not found, using Fragment fallback");
34
+ }
35
+
36
+ // ── Render a page inside RootLayout ──────────────────────────────────────────
37
+ function renderPage(PageComponent: any): string {
38
+ return renderToStaticMarkup(
39
+ React.createElement(RootLayout, null, React.createElement(PageComponent))
40
+ );
41
+ }
42
+
43
+ // ── SEO extraction from source files (React 19 SSR-safe) ─────────────────────
44
+ // react-helmet-async v3 disabled server-side context for React 19 —
45
+ // HelmetProvider is a Fragment at SSR time so helmetContext.helmet is never set.
46
+ // Instead we parse <SEO .../> props directly from the source TSX file.
47
+
48
+ function extractSeoPropsFromSource(filePath: string): Record<string, string> {
49
+ if (!existsSync(filePath)) return {};
50
+
51
+ let src = readFileSync(filePath, "utf8");
52
+
53
+ // Strip JSX block comments so we don't match <SEO /> mentions inside them
54
+ src = src.replace(/\{\/\*[\s\S]*?\*\/\}/g, "");
55
+
56
+ // Find the first <SEO ... /> (multiline, s flag)
57
+ const seoMatch = src.match(/<SEO\b([\s\S]*?)\/>/s);
58
+ if (!seoMatch) return {};
59
+
60
+ const attribsStr = seoMatch[1];
61
+ const props: Record<string, string> = {};
62
+
63
+ // Double-quoted values: prop="value with & and spaces"
64
+ let m: RegExpExecArray | null;
65
+ const dqPattern = /(\w+)\s*=\s*"([^"]*)"/g;
66
+ while ((m = dqPattern.exec(attribsStr)) !== null) props[m[1]] = m[2];
67
+
68
+ // Single-quoted values: prop='value'
69
+ const sqPattern = /(\w+)\s*=\s*'([^']*)'/g;
70
+ while ((m = sqPattern.exec(attribsStr)) !== null) if (!props[m[1]]) props[m[1]] = m[2];
71
+
72
+ // JSX string expressions: prop={"value"} or prop={'value'}
73
+ const jsxPattern = /(\w+)\s*=\s*\{["']([^"']*)["']\}/g;
74
+ while ((m = jsxPattern.exec(attribsStr)) !== null) if (!props[m[1]]) props[m[1]] = m[2];
75
+
76
+ return props;
77
+ }
78
+
79
+ function buildHeadHtml(
80
+ base: Record<string, string>,
81
+ override: Record<string, string> = {}
82
+ ): string {
83
+ // Merge: per-page overrides win over layout defaults
84
+ const p = { ...base, ...override };
85
+
86
+ const {
87
+ title,
88
+ description,
89
+ keywords,
90
+ ogTitle,
91
+ ogDescription,
92
+ ogImage,
93
+ ogType = "website",
94
+ twitterCard = "summary_large_image",
95
+ twitterCreator,
96
+ canonical,
97
+ } = p;
98
+
99
+ const tags: string[] = [];
100
+
101
+ if (title && !title.includes("FORGEWP")) tags.push(`<title>${title}</title>`);
102
+ if (description) tags.push(`<meta name="description" content="${description}">`);
103
+ if (keywords) tags.push(`<meta name="keywords" content="${keywords}">`);
104
+ if (canonical) tags.push(`<link rel="canonical" href="${canonical}">`);
105
+
106
+ // Open Graph
107
+ tags.push(`<meta property="og:type" content="${ogType}">`);
108
+ const ogTitleVal = ogTitle || title;
109
+ if (ogTitleVal && !ogTitleVal.includes("FORGEWP")) {
110
+ tags.push(`<meta property="og:title" content="${ogTitleVal}">`);
111
+ }
112
+ const ogDescVal = ogDescription || description;
113
+ if (ogDescVal) tags.push(`<meta property="og:description" content="${ogDescVal}">`);
114
+ if (ogImage) tags.push(`<meta property="og:image" content="${ogImage}">`);
115
+
116
+ // Twitter
117
+ tags.push(`<meta name="twitter:card" content="${twitterCard}">`);
118
+ if (ogTitleVal && !ogTitleVal.includes("FORGEWP")) {
119
+ tags.push(`<meta name="twitter:title" content="${ogTitleVal}">`);
120
+ }
121
+ if (ogDescVal) tags.push(`<meta name="twitter:description" content="${ogDescVal}">`);
122
+ if (ogImage) tags.push(`<meta name="twitter:image" content="${ogImage}">`);
123
+ if (twitterCreator) tags.push(`<meta name="twitter:creator" content="${twitterCreator}">`);
124
+
125
+ return tags.join("\n");
126
+ }
127
+
128
+ // ── Render header / footer fragments ─────────────────────────────────────────
129
+ let headerHtml = "";
130
+ try {
131
+ const { SiteHeader } = await import(headerUrl);
132
+ headerHtml = renderToStaticMarkup(React.createElement(SiteHeader));
133
+ } catch {
134
+ console.warn("SiteHeader not found, skipping separate render");
135
+ }
136
+
137
+ let footerHtml = "";
138
+ try {
139
+ const { SiteFooter } = await import(footerUrl);
140
+ footerHtml = renderToStaticMarkup(React.createElement(SiteFooter));
141
+ } catch {
142
+ console.warn("SiteFooter not found, skipping separate render");
143
+ }
144
+
145
+ // ── Render pages ──────────────────────────────────────────────────────────────
146
+ const appHtml = renderPage(App);
147
+
148
+ // single.tsx
149
+ const singlePath = path.join(themeRoot, "src", "app", "single.tsx");
150
+ let singleHtml = "";
151
+ if (existsSync(singlePath)) {
152
+ const { default: SinglePage } = await import(pathToFileURL(singlePath).href);
153
+ singleHtml = renderPage(SinglePage);
154
+ }
155
+
156
+ // 404.tsx — rendered bare, no RootLayout (WP 404.php calls get_header/get_footer)
157
+ const notFoundPath = path.join(themeRoot, "src", "app", "404.tsx");
158
+ let notFoundHtml = "";
159
+ if (existsSync(notFoundPath)) {
160
+ const { default: NotFoundPage } = await import(pathToFileURL(notFoundPath).href);
161
+ notFoundHtml = renderToStaticMarkup(React.createElement(NotFoundPage));
162
+ }
163
+
164
+ // archive.tsx
165
+ const archivePath = path.join(themeRoot, "src", "app", "archive.tsx");
166
+ let archiveHtml = "";
167
+ if (existsSync(archivePath)) {
168
+ const { default: ArchivePage } = await import(pathToFileURL(archivePath).href);
169
+ archiveHtml = renderPage(ArchivePage);
170
+ }
171
+
172
+ // ── Extract SEO from source files ─────────────────────────────────────────────
173
+ // Global defaults come from layout.tsx <SEO> props.
174
+ // Per-page overrides come from the individual page file's <SEO> props.
175
+ const layoutSeo = extractSeoPropsFromSource(layoutPath);
176
+ const singleSeo = existsSync(singlePath)
177
+ ? extractSeoPropsFromSource(singlePath)
178
+ : {};
179
+
180
+ // Global head.html (used on all pages that don't have a per-page override)
181
+ const headHtml = buildHeadHtml(layoutSeo);
182
+
183
+ // Per-page head HTML for single.html (merged: layout defaults + single overrides)
184
+ const singleHeadHtml = buildHeadHtml(layoutSeo, singleSeo);
185
+
186
+ // ── Write outputs ─────────────────────────────────────────────────────────────
187
+ const outDir = path.join(themeRoot, ".forgewp");
188
+ mkdirSync(outDir, { recursive: true });
189
+
190
+ writeFileSync(path.join(outDir, "header.html"), headerHtml, "utf8");
191
+ writeFileSync(path.join(outDir, "footer.html"), footerHtml, "utf8");
192
+ writeFileSync(path.join(outDir, "app.html"), appHtml, "utf8");
193
+ writeFileSync(path.join(outDir, "head.html"), headHtml, "utf8");
194
+ writeFileSync(path.join(outDir, "single-head.html"), singleHeadHtml, "utf8");
195
+
196
+ if (singleHtml) writeFileSync(path.join(outDir, "single.html"), singleHtml, "utf8");
197
+ if (notFoundHtml) writeFileSync(path.join(outDir, "404.html"), notFoundHtml, "utf8");
198
+ if (archiveHtml) writeFileSync(path.join(outDir, "archive.html"), archiveHtml, "utf8");
199
+
200
+ process.stdout.write(outDir);
@@ -0,0 +1,54 @@
1
+ import { existsSync, writeFileSync, mkdirSync } from "node:fs";
2
+ import path from "node:path";
3
+ import pc from "picocolors";
4
+ import { SYSTEM_BLUEPRINTS } from "./blueprints.js";
5
+
6
+ /**
7
+ * Preflight Check & Self-Healing Validator
8
+ *
9
+ * Runs before compiling the theme.
10
+ * - Automatically restores any deleted system-critical utility files using pre-compiled blueprints.
11
+ * - Throws descriptive, highly actionable errors if a user-editable core file is deleted.
12
+ *
13
+ * @param {string} themeRoot Absolute path to the theme root folder.
14
+ */
15
+ export function validateCriticalFiles(themeRoot) {
16
+ const USER_EDITABLE_FILES = [
17
+ { relativePath: "wp.config.ts", name: "Theme configuration file" },
18
+ { relativePath: "index.html", name: "Main HTML entry wrapper" },
19
+ { relativePath: "package.json", name: "NPM Package configuration" },
20
+ { relativePath: "src/main.tsx", name: "React development entry point" },
21
+ { relativePath: "src/app/layout.tsx", name: "Root HTML structural layout" },
22
+ { relativePath: "src/app/routes.tsx", name: "Local Vite preview routing switcher" },
23
+ ];
24
+
25
+ // 1. Validate User-Editable Files (throw clear, actionable errors)
26
+ for (const file of USER_EDITABLE_FILES) {
27
+ const fullPath = path.join(themeRoot, file.relativePath);
28
+ if (!existsSync(fullPath)) {
29
+ throw new Error(
30
+ `Critical project file is missing: ${pc.bold(file.relativePath)}\n` +
31
+ ` Description: ${file.name}\n\n` +
32
+ ` 👉 To fix this, please restore the file from your version control (Git) or re-create it from the original ForgeWP theme template.`
33
+ );
34
+ }
35
+ }
36
+
37
+ // 2. Validate & Self-Heal System-Critical Files
38
+ for (const [relativePath, blueprintContent] of Object.entries(SYSTEM_BLUEPRINTS)) {
39
+ const fullPath = path.join(themeRoot, relativePath);
40
+
41
+ if (!existsSync(fullPath)) {
42
+ console.log(pc.yellow(` ⚠️ System file ${pc.bold(relativePath)} was missing! Restoring default system blueprint...`));
43
+
44
+ // Ensure target directory exists (e.g. src/lib/)
45
+ const dirPath = path.dirname(fullPath);
46
+ if (!existsSync(dirPath)) {
47
+ mkdirSync(dirPath, { recursive: true });
48
+ }
49
+
50
+ writeFileSync(fullPath, blueprintContent, "utf8");
51
+ console.log(pc.green(` ✅ Successfully restored system file: ${relativePath}`));
52
+ }
53
+ }
54
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forgewp/compiler",
3
- "version": "0.1.1",
3
+ "version": "0.1.7",
4
4
  "description": "Compile ForgeWP React themes into installable WordPress themes",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -9,7 +9,10 @@
9
9
  "forgewp-add": "./bin/add.js"
10
10
  },
11
11
  "exports": {
12
- ".": "./lib/index.js"
12
+ ".": {
13
+ "types": "./lib/index.d.ts",
14
+ "default": "./lib/index.js"
15
+ }
13
16
  },
14
17
  "files": [
15
18
  "bin",
@@ -22,6 +25,10 @@
22
25
  "archiver": "^7.0.1",
23
26
  "jiti": "^2.6.1",
24
27
  "picocolors": "^1.1.1",
25
- "@forgewp/registry": "0.1.1"
28
+ "react-helmet-async": "^3.0.0",
29
+ "@forgewp/registry": "0.1.7"
30
+ },
31
+ "devDependencies": {
32
+ "@types/node": "^22.19.19"
26
33
  }
27
34
  }