@harpy-js/core 0.4.7

package/scripts/build-hydration.ts

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+/**
+ * Build script to:
+ * 1. Analyze components for 'use client' directive
+ * 2. Generate separate hydration entry files
+ * 3. Bundle them with esbuild to dist/chunks with cache-busted names
+ * 4. Create a manifest file for server-side lookup
+ * 5. Create shared vendor bundle for React/ReactDOM to eliminate duplication
+ */
+
+import { execSync } from "child_process";
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+const PROJECT_ROOT = process.cwd();
+const SRC_DIR = path.join(PROJECT_ROOT, "src");
+const DIST_DIR = path.join(PROJECT_ROOT, "dist");
+const HYDRATION_ENTRIES_DIR = path.join(SRC_DIR, ".hydration-entries");
+const CHUNKS_DIR = path.join(DIST_DIR, "chunks");
+// Write manifest directly to dist (no need for temp since this runs after nest build)
+const MANIFEST_FILE = path.join(DIST_DIR, "hydration-manifest.json");
+const VENDOR_BUNDLE = "vendor.js";
+
+// Check if running in production mode (add cache-busting hashes only in production)
+const IS_PRODUCTION = process.argv.includes("--prod");
+
+interface ComponentFile {
+  filePath: string;
+  componentName: string;
+  isNamedExport: boolean; // Track if it's a named export
+}
+
+interface HydrationManifest {
+  [componentName: string]: string; // componentName -> chunkFileName
+}
+
+/**
+ * Find all files with 'use client' directive
+ */
+function findClientComponents(): ComponentFile[] {
+  const components: ComponentFile[] = [];
+  const extensions = [".ts", ".tsx"];
+
+  function walkDir(dir: string) {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith(".") && entry.name !== "node_modules") {
+          walkDir(fullPath);
+        }
+      } else if (extensions.includes(path.extname(entry.name))) {
+        try {
+          const content = fs.readFileSync(fullPath, "utf-8");
+
+          // Check for 'use client' directive at the start of the file
+          if (/^['"]use client['"]/.test(content.trim())) {
+            const fileName = path.basename(fullPath, path.extname(fullPath));
+            // Convert kebab-case to PascalCase
+            const componentName = fileName
+              .split("-")
+              .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+              .join("");
+
+            // Detect if it's a named export by checking for patterns like:
+            // export function ComponentName or export const ComponentName
+            const hasNamedExport = new RegExp(
+              `export\\s+(function|const|class)\\s+${componentName}\\b`,
+            ).test(content);
+
+            components.push({
+              filePath: fullPath,
+              componentName,
+              isNamedExport: hasNamedExport,
+            });
+          }
+        } catch (error) {
+          console.error(`Error reading file ${fullPath}:`, error);
+        }
+      }
+    }
+  }
+
+  walkDir(SRC_DIR);
+  return components;
+}
+
+/**
+ * Generate hydration entry file for a client component
+ * Uses window.React from vendor bundle
+ */
+function generateHydrationEntry(component: ComponentFile): string {
+  const relativePath = path.relative(HYDRATION_ENTRIES_DIR, component.filePath);
+  const importPath = `./${relativePath.replace(/\\\\/g, "/")}`;
+
+  // Generate appropriate import statement based on export type
+  const importStatement = component.isNamedExport
+    ? `import { ${component.componentName} } from '${importPath}';`
+    : `import ${component.componentName} from '${importPath}';`;
+
+  const content = `
+// Use React from vendor bundle
+const React = window.React;
+const { hydrateRoot } = window.ReactDOM;
+
+${importStatement}
+
+/**
+ * Auto-generated hydration entry for ${component.componentName}
+ */
+
+// Find all hydration containers for this component
+const containers = document.querySelectorAll('[id^="hydrate-${component.componentName}"]');
+
+containers.forEach((container) => {
+  const containerElement = container as HTMLElement;
+  const propsElement = document.getElementById(\`\${container.id}-props\`);
+  
+  let props = {};
+  if (propsElement) {
+    try {
+      props = JSON.parse(propsElement.textContent || '{}');
+    } catch (error) {
+      console.error('Error parsing props:', error);
+    }
+  }
+
+  try {
+    hydrateRoot(containerElement, React.createElement(${component.componentName}, props));
+    console.log('[Hydration] Hydrated ${component.componentName}');
+  } catch (error) {
+    console.error('[Hydration] Failed to hydrate ${component.componentName}:', error);
+  }
+});
+`.trim();
+
+  return content;
+}
+
+/**
+ * Generate cache-busted filename (production only)
+ * In dev mode, uses consistent filenames so the browser doesn't re-download
+ */
+function generateChunkFilename(componentName: string): string {
+  if (IS_PRODUCTION) {
+    // Production: use cache-busting hash
+    const hash = crypto.randomBytes(8).toString("hex");
+    return `${componentName}.${hash}.js`;
+  } else {
+    // Development: use consistent filename
+    return `${componentName}.js`;
+  }
+}
+
+/**
+ * Main build process
+ */
+function main(): void {
+  // Ensure hydration entries directory exists
+  if (!fs.existsSync(HYDRATION_ENTRIES_DIR)) {
+    fs.mkdirSync(HYDRATION_ENTRIES_DIR, { recursive: true });
+  }
+
+  console.log("🔍 Detecting client components...");
+  const clientComponents = findClientComponents();
+
+  if (clientComponents.length === 0) {
+    console.log("⚠️  No client components found");
+    // Still ensure chunks directory exists and clear manifest
+    if (!fs.existsSync(CHUNKS_DIR)) {
+      fs.mkdirSync(CHUNKS_DIR, { recursive: true });
+    }
+    fs.writeFileSync(MANIFEST_FILE, JSON.stringify({}, null, 2), "utf-8");
+    return;
+  }
+
+  console.log(`✅ Found ${clientComponents.length} client component(s):`);
+  clientComponents.forEach((c) => console.log(`   - ${c.componentName}`));
+
+  // Create hydration entries directory
+  if (!fs.existsSync(HYDRATION_ENTRIES_DIR)) {
+    fs.mkdirSync(HYDRATION_ENTRIES_DIR, { recursive: true });
+  }
+
+  // Ensure chunks directory exists
+  if (!fs.existsSync(CHUNKS_DIR)) {
+    fs.mkdirSync(CHUNKS_DIR, { recursive: true });
+  }
+
+  console.log("\n📝 Generating hydration entries...");
+
+  // Generate hydration entry files
+  const entryFiles: { path: string; componentName: string }[] = [];
+  for (const component of clientComponents) {
+    const entryContent = generateHydrationEntry(component);
+    const entryPath = path.join(
+      HYDRATION_ENTRIES_DIR,
+      `${component.componentName}.tsx`,
+    );
+
+    fs.writeFileSync(entryPath, entryContent, "utf-8");
+    entryFiles.push({
+      path: entryPath,
+      componentName: component.componentName,
+    });
+    console.log(`   ✓ ${component.componentName}.tsx`);
+  }
+
+  // Build shared vendor bundle first
+  console.log("\n📦 Building shared vendor bundle...");
+  const vendorEntryPath = path.join(HYDRATION_ENTRIES_DIR, "_vendor.js");
+  const vendorContent = `
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+
+// Expose React and ReactDOM globally for component chunks
+window.React = React;
+window.ReactDOM = ReactDOM;
+`.trim();
+
+  fs.writeFileSync(vendorEntryPath, vendorContent, "utf-8");
+
+  const vendorOutputPath = path.join(CHUNKS_DIR, VENDOR_BUNDLE);
+  try {
+    const vendorCommand = `npx esbuild "${vendorEntryPath}" --bundle --minify --target=es2020 --format=iife --outfile="${vendorOutputPath}" --platform=browser --tree-shaking=true --define:process.env.NODE_ENV=\\"production\\"`;
+    execSync(vendorCommand, { stdio: "inherit" });
+    console.log(`   ✓ vendor.js (React + ReactDOM)`);
+  } catch (error) {
+    console.error(`   ✗ Failed to bundle vendor:`, error);
+    process.exit(1);
+  }
+
+  // Bundle each entry file separately with cache-busted names
+  console.log("\n📦 Bundling hydration scripts...");
+
+  // Create React shim files for aliasing
+  const SHIMS_DIR = path.join(DIST_DIR, ".shims");
+  if (!fs.existsSync(SHIMS_DIR)) {
+    fs.mkdirSync(SHIMS_DIR, { recursive: true });
+  }
+
+  // Create shim for react
+  const reactShimPath = path.join(SHIMS_DIR, "react.js");
+  fs.writeFileSync(reactShimPath, "module.exports = window.React;", "utf-8");
+
+  // Create shim for react-dom
+  const reactDomShimPath = path.join(SHIMS_DIR, "react-dom.js");
+  fs.writeFileSync(
+    reactDomShimPath,
+    "module.exports = window.ReactDOM;",
+    "utf-8",
+  );
+
+  // Create shim for react-dom/client
+  const reactDomClientShimPath = path.join(SHIMS_DIR, "react-dom-client.js");
+  fs.writeFileSync(
+    reactDomClientShimPath,
+    "module.exports = window.ReactDOM;",
+    "utf-8",
+  );
+
+  // Create shim for react/jsx-runtime
+  const jsxRuntimeShimPath = path.join(SHIMS_DIR, "jsx-runtime.js");
+  fs.writeFileSync(
+    jsxRuntimeShimPath,
+    `
+const React = window.React;
+module.exports = {
+  jsx: React.createElement,
+  jsxs: React.createElement,
+  Fragment: React.Fragment
+};`,
+    "utf-8",
+  );
+
+  const manifest: HydrationManifest = {};
+
+  for (const entry of entryFiles) {
+    const chunkFilename = generateChunkFilename(entry.componentName);
+    const outputPath = path.join(CHUNKS_DIR, chunkFilename);
+
+    try {
+      // Use aliases to redirect React imports to window.React from vendor bundle
+      const command = `npx esbuild "${entry.path}" --bundle --minify --target=es2020 --format=iife --keep-names --outfile="${outputPath}" --platform=browser --tree-shaking=true --define:process.env.NODE_ENV=\\"production\\" --alias:react=${reactShimPath} --alias:react-dom=${reactDomShimPath} --alias:react-dom/client=${reactDomClientShimPath} --alias:react/jsx-runtime=${jsxRuntimeShimPath}`;
+      execSync(command, { stdio: "inherit" });
+      manifest[entry.componentName] = chunkFilename;
+      console.log(`   ✓ ${entry.componentName} -> ${chunkFilename}`);
+    } catch (error) {
+      console.error(`   ✗ Failed to bundle ${entry.componentName}:`, error);
+      process.exit(1);
+    }
+  }
+
+  // Write manifest file for server-side lookup
+  console.log("\n📋 Writing hydration manifest...");
+  fs.writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2), "utf-8");
+  console.log(`   ✓ Manifest written to ${MANIFEST_FILE}`);
+
+  // Clean up temporary entries directory
+  if (fs.existsSync(HYDRATION_ENTRIES_DIR)) {
+    fs.rmSync(HYDRATION_ENTRIES_DIR, { recursive: true });
+  }
+
+  console.log("\n✨ Hydration build complete!");
+}
+
+main();

package/scripts/build-page-styles.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Build script for common CSS file
+ * Generates a single styles.css with all Tailwind styles for the entire app
+ */
+
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+const projectRoot = process.cwd();
+const distDir = path.join(projectRoot, "dist");
+const stylesDir = path.join(distDir, "styles");
+const srcAssetsDir = path.join(projectRoot, "src/assets");
+const outputCssPath = path.join(stylesDir, "styles.css");
+
+async function main(): Promise<void> {
+  console.log("🎨 Building styles...");
+
+  try {
+    // Ensure styles directory exists
+    if (!fs.existsSync(stylesDir)) {
+      fs.mkdirSync(stylesDir, { recursive: true });
+    }
+
+    // Compile Tailwind CSS
+    console.log("   Compiling Tailwind CSS...");
+    execSync(
+      `NODE_ENV=production postcss ${path.join(srcAssetsDir, "styles.css")} -o ${outputCssPath}`,
+      {
+        stdio: "inherit",
+      },
+    );
+
+    console.log(`   ✓ Generated styles.css`);
+    console.log("✨ Styles build complete!");
+  } catch (error: any) {
+    console.error("❌ CSS generation failed:", error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/copy-assets.ts

@@ -0,0 +1,34 @@
+import * as fs from "fs";
+import * as path from "path";
+
+const src = "public";
+const dest = path.join("dist", "public");
+
+if (!fs.existsSync(src)) {
+  console.log("No public folder to copy");
+  process.exit(0);
+}
+
+if (fs.existsSync(dest)) {
+  fs.rmSync(dest, { recursive: true });
+}
+
+const copy = (source: string, target: string): void => {
+  fs.mkdirSync(target, { recursive: true });
+
+  for (const entry of fs.readdirSync(source)) {
+    const srcPath = path.join(source, entry);
+    const destPath = path.join(target, entry);
+    const stat = fs.statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      copy(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+};
+
+copy(src, dest);
+
+console.log("Assets copied successfully");

package/scripts/dev.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Development script that rebuilds hydration on file changes
+pnpm ts-node scripts/dev.ts

package/scripts/dev.ts

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as http from "http";
+
+let nestProcess: any = null;
+let isRebuilding = false;
+
+/**
+ * Trigger browser reload by sending notification to LiveReloadController
+ */
+function triggerBrowserReload(): void {
+  const options = {
+    hostname: "127.0.0.1",
+    port: 3000,
+    path: "/__harpy/live-reload/trigger",
+    method: "POST",
+  };
+
+  const req = http.request(options, () => {
+    // Silently succeed
+  });
+
+  req.on("error", () => {
+    // Silently fail - server might not be ready yet
+  });
+
+  req.end();
+}
+
+async function runCommand(cmd: string, args: string[] = []): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: "inherit", shell: true });
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+async function buildHydration(): Promise<void> {
+  console.log("🔧 Building hydration...");
+  try {
+    await runCommand("pnpm", ["build:hydration"]);
+    console.log("✅ Hydration built");
+  } catch (error) {
+    console.error("❌ Hydration build failed:", error);
+    throw error;
+  }
+}
+
+async function autoWrap(): Promise<void> {
+  console.log("🔄 Auto-wrapping client components...");
+  try {
+    await runCommand("pnpm", ["auto-wrap"]);
+    console.log("✅ Auto-wrap complete");
+  } catch (error) {
+    console.error("❌ Auto-wrap failed:", error);
+    throw error;
+  }
+}
+
+async function buildStyles(): Promise<void> {
+  console.log("🎨 Building styles...");
+  try {
+    await runCommand("pnpm", ["build:styles"]);
+    console.log("✅ Styles built");
+  } catch (error) {
+    console.error("❌ Styles build failed:", error);
+    throw error;
+  }
+}
+
+async function startNestServer(): Promise<void> {
+  return new Promise((resolve) => {
+    console.log("🚀 Starting NestJS server from compiled dist...");
+    // Run compiled dist/main.js instead of using ts-node
+    // This ensures auto-wrapped components are used
+    nestProcess = spawn("node", ["--watch", "dist/main.js"], {
+      stdio: "pipe",
+      shell: false,
+      cwd: process.cwd(),
+    });
+
+    let resolved = false;
+    let isFirstStart = true;
+
+    // Capture output to detect when server is ready
+    nestProcess.stdout?.on("data", (data: Buffer) => {
+      const output = data.toString();
+      process.stdout.write(output);
+
+      // Detect when NestJS application successfully started
+      if (output.includes("Nest application successfully started")) {
+        if (!resolved && isFirstStart) {
+          // First start - resolve the promise
+          resolved = true;
+          isFirstStart = false;
+          resolve();
+        } else if (!isFirstStart && !isRebuilding) {
+          // Subsequent restarts - rebuild assets
+          setTimeout(async () => {
+            if (isRebuilding) return;
+            isRebuilding = true;
+            console.log("\n🔄 NestJS rebuild detected, rebuilding assets...");
+            try {
+              await buildHydration();
+              await autoWrap();
+              await buildStyles();
+              console.log("✅ Assets rebuilt\n");
+              triggerBrowserReload();
+            } catch (error) {
+              console.error("❌ Asset rebuild failed:", error);
+            } finally {
+              isRebuilding = false;
+            }
+          }, 100);
+        }
+      }
+    });
+
+    nestProcess.stderr?.on("data", (data: Buffer) => {
+      process.stderr.write(data);
+    });
+
+    // Fallback timeout in case the detection fails
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        isFirstStart = false;
+        resolve();
+      }
+    }, 8000);
+  });
+}
+
+function watchSourceChanges(): void {
+  console.log("👀 Watching source files for changes...");
+
+  let debounceTimer: NodeJS.Timeout | null = null;
+  const watchedFiles = new Set<string>();
+
+  // Watch src for CSS changes only (TS/TSX changes are handled by NestJS watch + stdout detection)
+  fs.watch("src", { recursive: true }, async (eventType, filename) => {
+    if (!filename || isRebuilding) return;
+
+    // Ignore .hydration-entries changes
+    if (filename.includes(".hydration-entries")) {
+      return;
+    }
+
+    // Only watch CSS files (TS/TSX changes trigger nest rebuild which we catch above)
+    if (!filename.endsWith(".css")) return;
+
+    // Skip if we just rebuilt for this file (avoid duplicate rebuilds)
+    if (watchedFiles.has(filename)) {
+      return;
+    }
+
+    watchedFiles.add(filename);
+
+    // Debounce: wait 1000ms after last change before rebuilding
+    if (debounceTimer) clearTimeout(debounceTimer);
+
+    debounceTimer = setTimeout(async () => {
+      isRebuilding = true;
+      console.log(`\n📝 CSS file changed: ${filename}`);
+
+      try {
+        await buildStyles();
+        console.log("✅ Styles rebuilt\n");
+        triggerBrowserReload();
+      } catch (error) {
+        console.error("Build error:", error);
+      } finally {
+        watchedFiles.delete(filename);
+        isRebuilding = false;
+      }
+    }, 1000);
+  });
+}
+
+let tscProcess: any = null;
+
+async function startTypeScriptWatch(): Promise<void> {
+  return new Promise((resolve) => {
+    console.log("⚙️  Starting TypeScript compiler in watch mode...");
+    tscProcess = spawn("pnpm", ["nest", "build", "--watch"], {
+      stdio: "pipe",
+      shell: true,
+    });
+
+    let resolved = false;
+
+    tscProcess.stdout?.on("data", (data: Buffer) => {
+      const output = data.toString();
+      process.stdout.write(output);
+
+      // Resolve once first compilation is done
+      if (output.includes("Found 0 errors. Watching") && !resolved) {
+        resolved = true;
+        resolve();
+      }
+    });
+
+    tscProcess.stderr?.on("data", (data: Buffer) => {
+      process.stderr.write(data);
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  try {
+    console.log("📦 Initializing development environment...\n");
+
+    // First: Start TypeScript compiler in watch mode
+    await startTypeScriptWatch();
+
+    // Build initial assets after first compilation
+    console.log("\n🔧 Building hydration assets...");
+    await buildHydration();
+    await autoWrap();
+    await buildStyles();
+
+    // Now start the node server with compiled dist files
+    await startNestServer();
+
+    console.log("\n✅ Development server ready!\n");
+
+    // Watch for source changes
+    watchSourceChanges();
+
+    // Handle graceful shutdown
+    process.on("SIGINT", async () => {
+      console.log("\n\n🛑 Stopping development server...");
+      if (tscProcess) tscProcess.kill();
+      if (nestProcess) nestProcess.kill();
+      process.exit(0);
+    });
+
+    process.on("SIGTERM", async () => {
+      console.log("\n\n🛑 Stopping development server...");
+      if (tscProcess) tscProcess.kill();
+      if (nestProcess) nestProcess.kill();
+      process.exit(0);
+    });
+  } catch (error) {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  }
+}
+
+main();