@harpy-js/core 0.4.7

package/src/core/__tests__/hydration-manifest.test.ts

@@ -0,0 +1,223 @@
+import * as fs from "fs";
+import * as path from "path";
+
+jest.mock("fs");
+
+describe("Hydration Manifest", () => {
+  const mockFs = fs as jest.Mocked<typeof fs>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("manifest structure", () => {
+    it("should have components array", () => {
+      const manifest = { components: [] };
+      expect(manifest).toHaveProperty("components");
+      expect(Array.isArray(manifest.components)).toBe(true);
+    });
+
+    it("should store component metadata", () => {
+      const component = {
+        name: "TestComponent",
+        path: "/src/TestComponent.tsx",
+        isClient: true,
+        hasState: true,
+        hasEffects: false,
+        hasEventHandlers: true,
+      };
+
+      expect(component.name).toBe("TestComponent");
+      expect(component.isClient).toBe(true);
+      expect(component.hasState).toBe(true);
+    });
+
+    it("should handle multiple components", () => {
+      const manifest = {
+        components: [
+          { name: "Comp1", path: "/Comp1.tsx", isClient: true },
+          { name: "Comp2", path: "/Comp2.tsx", isClient: true },
+        ],
+      };
+
+      expect(manifest.components).toHaveLength(2);
+    });
+  });
+
+  describe("client component filtering", () => {
+    it("should identify client components", () => {
+      const components = [
+        { name: "ClientComp", isClient: true },
+        { name: "ServerComp", isClient: false },
+      ];
+
+      const clientOnly = components.filter((c) => c.isClient);
+      expect(clientOnly).toHaveLength(1);
+      expect(clientOnly[0].name).toBe("ClientComp");
+    });
+
+    it("should handle all server components", () => {
+      const components = [
+        { name: "ServerComp1", isClient: false },
+        { name: "ServerComp2", isClient: false },
+      ];
+
+      const clientOnly = components.filter((c) => c.isClient);
+      expect(clientOnly).toHaveLength(0);
+    });
+
+    it("should handle all client components", () => {
+      const components = [
+        { name: "ClientComp1", isClient: true },
+        { name: "ClientComp2", isClient: true },
+      ];
+
+      const clientOnly = components.filter((c) => c.isClient);
+      expect(clientOnly).toHaveLength(2);
+    });
+  });
+
+  describe("JSON serialization", () => {
+    it("should serialize to JSON", () => {
+      const manifest = {
+        components: [
+          {
+            name: "TestComponent",
+            path: "/TestComponent.tsx",
+            isClient: true,
+            hasState: true,
+            hasEffects: false,
+            hasEventHandlers: true,
+          },
+        ],
+      };
+
+      const json = JSON.stringify(manifest);
+      expect(json).toContain("TestComponent");
+      expect(json).toContain("isClient");
+    });
+
+    it("should deserialize from JSON", () => {
+      const json =
+        '{"components":[{"name":"Comp","path":"/Comp.tsx","isClient":true}]}';
+      const manifest = JSON.parse(json);
+
+      expect(manifest.components).toHaveLength(1);
+      expect(manifest.components[0].name).toBe("Comp");
+    });
+
+    it("should preserve component metadata", () => {
+      const original = {
+        name: "Component",
+        path: "/Component.tsx",
+        isClient: true,
+        hasState: true,
+        hasEffects: true,
+        hasEventHandlers: true,
+      };
+
+      const json = JSON.stringify(original);
+      const parsed = JSON.parse(json);
+
+      expect(parsed).toEqual(original);
+    });
+  });
+
+  describe("file operations", () => {
+    it("should serialize manifest for saving", () => {
+      const manifest = { components: [] };
+      const filePath = "/output/manifest.json";
+      const serialized = JSON.stringify(manifest, null, 2);
+
+      expect(serialized).toContain("components");
+      expect(serialized).toContain("[]");
+    });
+
+    it("should deserialize manifest from JSON string", () => {
+      const mockData = JSON.stringify({
+        components: [
+          { name: "LoadedComponent", path: "/Comp.tsx", isClient: true },
+        ],
+      });
+
+      const manifest = JSON.parse(mockData);
+
+      expect(manifest.components).toHaveLength(1);
+      expect(manifest.components[0].name).toBe("LoadedComponent");
+    });
+
+    it("should validate file paths", () => {
+      const validPath = "/manifest.json";
+      const invalidPath = "";
+
+      expect(validPath.length).toBeGreaterThan(0);
+      expect(invalidPath.length).toBe(0);
+    });
+
+    it("should handle directory paths", () => {
+      const dirPath = "/new/directory";
+      const parts = dirPath.split("/").filter(Boolean);
+
+      expect(parts).toEqual(["new", "directory"]);
+      expect(parts.length).toBe(2);
+    });
+  });
+
+  describe("component metadata", () => {
+    it("should track component state usage", () => {
+      const component = { name: "StatefulComp", hasState: true };
+      expect(component.hasState).toBe(true);
+    });
+
+    it("should track component effects", () => {
+      const component = { name: "EffectComp", hasEffects: true };
+      expect(component.hasEffects).toBe(true);
+    });
+
+    it("should track event handlers", () => {
+      const component = { name: "InteractiveComp", hasEventHandlers: true };
+      expect(component.hasEventHandlers).toBe(true);
+    });
+
+    it("should combine multiple flags", () => {
+      const component = {
+        name: "ComplexComp",
+        hasState: true,
+        hasEffects: true,
+        hasEventHandlers: true,
+      };
+
+      expect(component.hasState).toBe(true);
+      expect(component.hasEffects).toBe(true);
+      expect(component.hasEventHandlers).toBe(true);
+    });
+  });
+
+  describe("deduplication", () => {
+    it("should prevent duplicate component entries", () => {
+      const components = [
+        { name: "Comp", path: "/Comp.tsx" },
+        { name: "Comp", path: "/Comp.tsx" },
+      ];
+
+      const unique = Array.from(new Set(components.map((c) => c.name))).map(
+        (name) => components.find((c) => c.name === name),
+      );
+
+      expect(unique).toHaveLength(1);
+    });
+
+    it("should allow same name in different paths", () => {
+      const components = [
+        { name: "Button", path: "/ui/Button.tsx" },
+        { name: "Button", path: "/forms/Button.tsx" },
+      ];
+
+      const uniqueByPath = Array.from(
+        new Set(components.map((c) => c.path)),
+      ).map((path) => components.find((c) => c.path === path));
+
+      expect(uniqueByPath).toHaveLength(2);
+    });
+  });
+});

package/src/core/__tests__/jsx.engine.test.ts

@@ -0,0 +1,137 @@
+import { withJsxEngine } from "../jsx.engine";
+import { NestFastifyApplication } from "@nestjs/platform-fastify";
+import * as React from "react";
+
+describe("JSX Engine", () => {
+  let mockApp: NestFastifyApplication;
+  let mockAdapter: any;
+  let mockReply: any;
+
+  beforeEach(() => {
+    mockReply = {
+      raw: {
+        end: jest.fn(),
+        write: jest.fn(),
+        setHeader: jest.fn(),
+        headersSent: false,
+      },
+      statusCode: 200,
+      request: {},
+      status: jest.fn().mockReturnThis(),
+      send: jest.fn(),
+    };
+
+    mockAdapter = {
+      render: null,
+      get: jest.fn(),
+      post: jest.fn(),
+    };
+
+    mockApp = {
+      getHttpAdapter: jest.fn().mockReturnValue(mockAdapter),
+    } as unknown as NestFastifyApplication;
+  });
+
+  describe("withJsxEngine", () => {
+    it("should attach render method to the adapter", () => {
+      const mockLayout = (props: any) =>
+        React.createElement("html", null, props.children);
+
+      withJsxEngine(mockApp, mockLayout);
+
+      expect(mockAdapter.render).toBeDefined();
+      expect(typeof mockAdapter.render).toBe("function");
+    });
+
+    it("should handle redirect status codes without rendering", async () => {
+      const mockLayout = (props: any) =>
+        React.createElement("html", null, props.children);
+      withJsxEngine(mockApp, mockLayout);
+
+      mockReply.statusCode = 301;
+
+      await mockAdapter.render(
+        mockReply,
+        [() => React.createElement("div"), {}],
+        {},
+      );
+
+      expect(mockReply.raw.end).toHaveBeenCalled();
+    });
+
+    it("should handle error status codes without rendering", async () => {
+      const mockLayout = (props: any) =>
+        React.createElement("html", null, props.children);
+      withJsxEngine(mockApp, mockLayout);
+
+      mockReply.statusCode = 500;
+
+      await mockAdapter.render(
+        mockReply,
+        [() => React.createElement("div"), {}],
+        {},
+      );
+
+      expect(mockReply.raw.end).toHaveBeenCalled();
+    });
+
+    it("should accept custom layout in options", () => {
+      const defaultLayout = (props: any) =>
+        React.createElement(
+          "html",
+          null,
+          React.createElement("body", null, props.children),
+        );
+      const customLayout = (props: any) =>
+        React.createElement(
+          "html",
+          null,
+          React.createElement("main", null, props.children),
+        );
+
+      withJsxEngine(mockApp, defaultLayout);
+
+      expect(mockAdapter.render).toBeDefined();
+      expect(typeof customLayout).toBe("function");
+    });
+
+    it("should support component props", () => {
+      const mockLayout = (props: any) =>
+        React.createElement("html", null, props.children);
+      withJsxEngine(mockApp, mockLayout);
+
+      const component = (props: any) =>
+        React.createElement("div", null, `Hello ${props.name}`);
+      const rendered = component({ name: "Harpy" });
+
+      expect(rendered.props.children).toContain("Harpy");
+    });
+  });
+
+  describe("React rendering", () => {
+    it("should render simple React components", () => {
+      const element = React.createElement("div", null, "Hello World");
+      expect(element).toBeDefined();
+      expect(element.type).toBe("div");
+    });
+
+    it("should render nested components", () => {
+      const child = React.createElement("span", null, "Child");
+      const parent = React.createElement("div", null, child);
+
+      expect(parent).toBeDefined();
+      expect(parent.type).toBe("div");
+    });
+
+    it("should handle component props", () => {
+      const element = React.createElement(
+        "div",
+        { className: "test", id: "main" },
+        "Content",
+      );
+
+      expect(element.props.className).toBe("test");
+      expect(element.props.id).toBe("main");
+    });
+  });
+});

package/src/core/app-setup.ts

@@ -0,0 +1,114 @@
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import * as path from "path";
+// Use runtime `require` for optional fastify plugins so consumers don't need
+// to install them as direct dependencies of the core package at compile time.
+// We'll type them as `any` to avoid TypeScript module resolution errors here.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+// Load optional fastify plugins with graceful fallback so consumers that
+// don't install these packages don't crash at runtime.
+let fastifyStatic: any;
+let fastifyCookie: any;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  fastifyStatic = require("@fastify/static");
+} catch (e) {
+  // Module not installed — we'll skip registering static handler below.
+  fastifyStatic = undefined;
+}
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  fastifyCookie = require("@fastify/cookie");
+} catch (e) {
+  fastifyCookie = undefined;
+}
+import { withJsxEngine } from "./jsx.engine";
+
+export interface HarpyAppOptions {
+  /** JSX Default layout used by the app (optional) */
+  layout?: any;
+  /** Folder containing built server assets (chunks) — defaults to `dist` */
+  distDir?: string;
+}
+
+/**
+ * Configure a Nest + Fastify application with the standard Harpy defaults.
+ *
+ * This registers the JSX engine (if `layout` is provided), cookie support,
+ * the `dist` static handler (required for hydration chunks), and an optional
+ * public static handler. The function is intentionally conservative — it
+ * registers only what Harpy needs to function, while allowing the caller to
+ * pass a `publicDir` for project-specific assets.
+ */
+export async function configureHarpyApp(
+  app: NestFastifyApplication,
+  opts: HarpyAppOptions = {},
+) {
+  const { layout, distDir = "dist" } = opts;
+
+  if (layout) {
+    withJsxEngine(app, layout);
+  }
+
+  const fastify = app.getHttpAdapter().getInstance();
+
+  // Cookie support is used by i18n and other helpers if available.
+  if (fastifyCookie) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    await fastify.register(fastifyCookie);
+  } else {
+    // If cookie plugin is not installed, warn but continue. Consumers who
+    // rely on cookie-based features should install `@fastify/cookie`.
+    // We intentionally do not throw here to avoid breaking projects that
+    // don't need cookie support.
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[harpy-core] optional dependency `@fastify/cookie` is not installed; skipping cookie registration.",
+    );
+  }
+
+  // Ensure hydration chunks and other built assets are served from `dist`
+  // This is important: hydration chunks are expected at the root ("/").
+  // Use absolute path to be robust when invoked from different CWDs.
+  if (fastifyStatic) {
+    // Ensure hydration chunks and other built assets are served from `dist`
+    // This is important: hydration chunks are expected at the root ("/").
+    // Use absolute path to be robust when invoked from different CWDs.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    await fastify.register(fastifyStatic, {
+      root: path.join(process.cwd(), distDir),
+      prefix: "/",
+      decorateReply: false,
+    });
+  } else {
+    // If the static plugin is not available, emit a warning and continue.
+    // Consumers who need hydration chunk serving in production should add
+    // `@fastify/static` as a dependency in their application.
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[harpy-core] optional dependency `@fastify/static` is not installed; static `dist` handler not registered.",
+    );
+  }
+
+  // Note: we intentionally do not register a `public` static handler by
+  // default. Some applications prefer to control their public asset handling
+  // themselves (or not use a `public/` folder). If an app needs a public
+  // directory served under `/public/`, it can call `fastify.register` in
+  // its own `main.ts` after `configureHarpyApp`.
+
+  // Analytics injection is intentionally omitted — keep analytics opt-in for
+  // application authors so they can wire up their provider of choice.
+}
+
+/**
+ * A small, strongly-typed wrapper exported for consumers who may face
+ * editor/module-resolution issues when importing the original function.
+ *
+ * Use this in application `main.ts` to ensure the callsite is typed from
+ * the core package itself (avoids local casting or lint workarounds).
+ */
+export async function setupHarpyApp(
+  app: NestFastifyApplication,
+  opts: HarpyAppOptions = {},
+) {
+  return configureHarpyApp(app, opts);
+}

package/src/core/auto-register.module.ts

@@ -0,0 +1,30 @@
+import { OnModuleInit } from "@nestjs/common";
+import { NavigationService } from "./navigation.service";
+import type { NavigationRegistry } from "./types/nav.types";
+
+/**
+ * Base module that automatically registers navigation on module init.
+ *
+ * Feature modules can extend this class and implement `registerNavigation`
+ * to avoid implementing `OnModuleInit` themselves.
+ */
+export abstract class AutoRegisterModule implements OnModuleInit {
+  constructor(protected readonly navigationService: NavigationService) {}
+
+  /**
+   * Implement this in the concrete module to register navigation items/sections.
+   */
+  protected abstract registerNavigation(navigation: NavigationRegistry): void;
+
+  onModuleInit(): void {
+    // Call the concrete module's registration method with the core NavigationService
+    try {
+      this.registerNavigation(this.navigationService);
+    } catch (err) {
+      // Don't let registration errors break app startup; surface via console for now.
+      // Consumers can still throw if they want startup to fail.
+      // eslint-disable-next-line no-console
+      console.warn("[AutoRegisterModule] registerNavigation failed:", err);
+    }
+  }
+}

package/src/core/auto-wrap-middleware.ts

@@ -0,0 +1,165 @@
+/**
+ * Automatic client component wrapping middleware.
+ *
+ * This module provides a createElement wrapper that intercepts React component creation
+ * and automatically wraps components with 'use client' directive for hydration.
+ *
+ * It works by analyzing component modules at render time and applying hydration
+ * wrapping transparently without requiring explicit wrapper calls in user code.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import React from "react";
+import { autoWrapClientComponent } from "./client-component-wrapper";
+import { getComponentNameFromPath } from "./component-analyzer";
+
+/**
+ * Cache of analyzed components
+ */
+const componentAnalysisCache = new Map<
+  React.ComponentType<any>,
+  { isClientComponent: boolean; componentName: string }
+>();
+
+/**
+ * Try to find the source file for a component
+ * This is a best-effort approach that works for most cases
+ */
+function findComponentSourceFile(
+  component: React.ComponentType<any>,
+): string | null {
+  try {
+    // Check if component has a source location (some bundlers preserve this)
+    if ((component as any).__filename) {
+      return (component as any).__filename;
+    }
+
+    // For default exports from modules, try to find based on name
+    // This is a heuristic and may not work in all cases
+    const componentName = component.displayName || component.name;
+    if (!componentName) return null;
+
+    // Look in src/features/*/views/ directories
+    const srcRoot = path.join(process.cwd(), "src");
+    const viewsDirs = fs.readdirSync(srcRoot).flatMap((feature) => {
+      const viewsPath = path.join(srcRoot, "features", feature, "views");
+      if (fs.existsSync(viewsPath)) {
+        return fs
+          .readdirSync(viewsPath)
+          .map((file) => path.join(viewsPath, file));
+      }
+      return [];
+    });
+
+    // Find matching file
+    const kebabName = componentName
+      .replace(/([A-Z])/g, "-$1")
+      .toLowerCase()
+      .substring(1);
+
+    return (
+      viewsDirs.find(
+        (f) =>
+          path.basename(f, path.extname(f)) === kebabName ||
+          path.basename(f, path.extname(f)) === componentName.toLowerCase(),
+      ) || null
+    );
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check if a component source has 'use client' directive
+ */
+function hasUseClientDirective(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return /^['"]use client['"];?\s*/.test(content);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Automatically wraps a component if it has 'use client' directive.
+ * Uses caching to avoid repeated file analysis.
+ */
+export function autoWrapIfUsesClient(
+  component: React.ComponentType<any>,
+): React.ComponentType<any> {
+  // Check cache
+  if (componentAnalysisCache.has(component)) {
+    const cached = componentAnalysisCache.get(component)!;
+    if (cached.isClientComponent) {
+      return autoWrapClientComponent(component, cached.componentName);
+    }
+    return component;
+  }
+
+  // Try to find source file
+  const sourceFile = findComponentSourceFile(component);
+  if (!sourceFile) {
+    // Can't find source, cache as non-client component
+    componentAnalysisCache.set(component, {
+      isClientComponent: false,
+      componentName: component.displayName || component.name || "Unknown",
+    });
+    return component;
+  }
+
+  // Check for 'use client' directive
+  if (!hasUseClientDirective(sourceFile)) {
+    const componentName = getComponentNameFromPath(sourceFile);
+    componentAnalysisCache.set(component, {
+      isClientComponent: false,
+      componentName,
+    });
+    return component;
+  }
+
+  // It's a client component - wrap it
+  const componentName = getComponentNameFromPath(sourceFile);
+  componentAnalysisCache.set(component, {
+    isClientComponent: true,
+    componentName,
+  });
+
+  return autoWrapClientComponent(component, componentName);
+}
+
+/**
+ * Override React.createElement to auto-wrap client components.
+ * This is called for every JSX element during rendering.
+ */
+export const createAutoWrapCreateElement = (
+  originalCreateElement: typeof React.createElement,
+) => {
+  return (
+    type: React.ElementType,
+    props?: Record<string, any> | null,
+    ...children: React.ReactNode[]
+  ) => {
+    // Only process function components
+    if (typeof type === "function" && !type.prototype?.isReactComponent) {
+      try {
+        // Auto-wrap if it has 'use client'
+        const wrappedType = autoWrapIfUsesClient(type);
+        return originalCreateElement(wrappedType, props, ...children);
+      } catch (error) {
+        // Fallback to original if wrapping fails
+        return originalCreateElement(type, props, ...children);
+      }
+    }
+
+    return originalCreateElement(type, props, ...children);
+  };
+};
+
+/**
+ * Clear the analysis cache (useful for testing or hot reload)
+ */
+export function clearComponentAnalysisCache(): void {
+  componentAnalysisCache.clear();
+}