@spfn/core 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -6,12 +6,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 
+> ⚠️ **Alpha Release**: SPFN is currently in alpha. APIs may change. Use `@alpha` tag for installation.
+
 ## Installation
 
-**Recommended: Use CLI**
+**Recommended: Create New Project**
+```bash
+npx spfn@alpha create my-app
+```
+
+**Add to Existing Next.js Project**
 ```bash
-npm install -g @spfn/cli
-spfn init
+cd your-nextjs-project
+npx spfn@alpha init
 ```
 
 **Manual Installation**
@@ -478,6 +485,18 @@ Server configuration and lifecycle management.
 
 **[→ Read Server Documentation](./src/server/README.md)**
 
+### ⚙️ Code Generation
+Automatic code generation with pluggable generators and centralized file watching.
+
+**[→ Read Codegen Documentation](./src/codegen/README.md)**
+
+**Key Features:**
+- Orchestrator pattern for managing multiple generators
+- Built-in contract generator for type-safe API clients
+- Configuration-based setup (`.spfnrc.json` or `package.json`)
+- Watch mode integrated into `spfn dev`
+- Extensible with custom generators
+
 ## Module Exports
 
 ### Main Export
@@ -567,6 +586,7 @@ npm test -- --coverage      # With coverage
 - [Error Handling](./src/errors/README.md)
 - [Middleware](./src/middleware/README.md)
 - [Server Configuration](./src/server/README.md)
+- [Code Generation](./src/codegen/README.md)
 
 ### API Reference
 - See module-specific README files linked above

package/dist/{auto-loader-C44TcLmM.d.ts → auto-loader-Pq1wY1qz.d.ts}

@@ -86,6 +86,8 @@ declare class AutoRouteLoader {
      * - users/index.ts → /users
      * - users/[id].ts → /users/:id
      * - posts/[...slug].ts → /posts/*
+     * - users/index.js → /users (production)
+     * - users/[id].js → /users/:id (production)
      */
     private fileToPath;
     /**

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import '../auto-loader-C44TcLmM.js';
+import '../auto-loader-Pq1wY1qz.js';
 import { R as RouteContract, I as InferContract } from '../types-SlzTr8ZO.js';
 import 'hono';
 import 'hono/utils/http-status';

package/dist/codegen/index.d.ts

@@ -123,4 +123,108 @@ interface WatchGenerateOptions {
  */
 declare function watchAndGenerate(options?: WatchGenerateOptions): Promise<void>;
 
-export { type ClientGenerationOptions, type GenerationStats, HttpMethod, type ResourceRoutes, type RouteContractMapping, generateClient, groupByResource, scanContracts, watchAndGenerate };
+/**
+ * Generator Interface
+ *
+ * Defines the contract for code generators that can be orchestrated by the codegen system.
+ */
+interface GeneratorOptions {
+    /** Project root directory */
+    cwd: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom configuration options */
+    [key: string]: any;
+}
+interface Generator {
+    /** Unique generator name */
+    name: string;
+    /** File patterns to watch (glob patterns) */
+    watchPatterns: string[];
+    /**
+     * Generate code once
+     *
+     * @param options - Generator options
+     */
+    generate(options: GeneratorOptions): Promise<void>;
+    /**
+     * Handle individual file changes (optional)
+     *
+     * If not provided, the orchestrator will call generate() on any file change.
+     *
+     * @param filePath - Changed file path (relative to cwd)
+     * @param event - Type of file event
+     */
+    onFileChange?(filePath: string, event: 'add' | 'change' | 'unlink'): Promise<void>;
+}
+
+/**
+ * Codegen Orchestrator
+ *
+ * Manages multiple code generators and coordinates their execution
+ */
+
+interface OrchestratorOptions {
+    /** List of generators to orchestrate */
+    generators: Generator[];
+    /** Project root directory */
+    cwd?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+declare class CodegenOrchestrator {
+    private readonly generators;
+    private readonly cwd;
+    private readonly debug;
+    private isGenerating;
+    private pendingRegenerations;
+    constructor(options: OrchestratorOptions);
+    /**
+     * Run all generators once
+     */
+    generateAll(): Promise<void>;
+    /**
+     * Start watch mode
+     */
+    watch(): Promise<void>;
+}
+
+/**
+ * Contract Generator
+ *
+ * Generates type-safe API client from contract definitions
+ */
+
+interface ContractGeneratorConfig {
+    /** Routes directory (default: src/server/routes) */
+    routesDir?: string;
+    /** Output path (default: src/lib/api.ts) */
+    outputPath?: string;
+    /** Base URL for API client */
+    baseUrl?: string;
+}
+declare function createContractGenerator(config?: ContractGeneratorConfig): Generator;
+
+/**
+ * Codegen Configuration Loader
+ *
+ * Loads codegen configuration from .spfnrc.json or package.json
+ */
+
+interface CodegenConfig {
+    generators?: {
+        contract?: ContractGeneratorConfig & {
+            enabled?: boolean;
+        };
+    };
+}
+/**
+ * Load codegen configuration from .spfnrc.json or package.json
+ */
+declare function loadCodegenConfig(cwd: string): CodegenConfig;
+/**
+ * Create generator instances from configuration
+ */
+declare function createGeneratorsFromConfig(config: CodegenConfig): Generator[];
+
+export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, type ContractGeneratorConfig, type GenerationStats, type Generator, type GeneratorOptions, HttpMethod, type OrchestratorOptions, type ResourceRoutes, type RouteContractMapping, createContractGenerator, createGeneratorsFromConfig, generateClient, groupByResource, loadCodegenConfig, scanContracts, watchAndGenerate };

package/dist/codegen/index.js

@@ -1,9 +1,10 @@
 import { mkdir, writeFile, readdir, stat } from 'fs/promises';
-import { join, dirname } from 'path';
+import { join, dirname, relative } from 'path';
 import * as ts from 'typescript';
 import { existsSync, mkdirSync, createWriteStream, readFileSync } from 'fs';
 import { watch } from 'chokidar';
 import pino from 'pino';
+import mm from 'micromatch';
 
 // src/codegen/contract-scanner.ts
 async function scanContracts(routesDir) {
@@ -1009,7 +1010,214 @@ async function watchAndGenerate(options = {}) {
 if (import.meta.url === `file://${process.argv[1]}`) {
   watchAndGenerate({ debug: true });
 }
+var orchestratorLogger = logger.child("orchestrator");
+var CodegenOrchestrator = class {
+  generators;
+  cwd;
+  debug;
+  isGenerating = false;
+  pendingRegenerations = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.generators = options.generators;
+    this.cwd = options.cwd ?? process.cwd();
+    this.debug = options.debug ?? false;
+  }
+  /**
+   * Run all generators once
+   */
+  async generateAll() {
+    if (this.debug) {
+      orchestratorLogger.info("Running all generators", {
+        count: this.generators.length,
+        names: this.generators.map((g) => g.name)
+      });
+    }
+    for (const generator of this.generators) {
+      try {
+        const genOptions = {
+          cwd: this.cwd,
+          debug: this.debug
+        };
+        await generator.generate(genOptions);
+        if (this.debug) {
+          orchestratorLogger.info(`[${generator.name}] Generated successfully`);
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        orchestratorLogger.error(`[${generator.name}] Generation failed`, err);
+      }
+    }
+  }
+  /**
+   * Start watch mode
+   */
+  async watch() {
+    await this.generateAll();
+    const allPatterns = this.generators.flatMap((g) => g.watchPatterns);
+    if (allPatterns.length === 0) {
+      orchestratorLogger.warn("No watch patterns defined, exiting watch mode");
+      return;
+    }
+    const dirsToWatch = /* @__PURE__ */ new Set();
+    for (const pattern of allPatterns) {
+      const baseDir = pattern.split("**")[0].replace(/\/$/, "") || ".";
+      dirsToWatch.add(join(this.cwd, baseDir));
+    }
+    const watchDirs = Array.from(dirsToWatch);
+    if (this.debug) {
+      orchestratorLogger.info("Starting watch mode", {
+        patterns: allPatterns,
+        watchDirs,
+        cwd: this.cwd
+      });
+    }
+    const watcher = watch(watchDirs, {
+      ignored: /(^|[\/\\])\../,
+      // ignore dotfiles
+      persistent: true,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 100,
+        pollInterval: 50
+      }
+    });
+    const handleChange = async (absolutePath, event) => {
+      const filePath = relative(this.cwd, absolutePath);
+      if (this.isGenerating) {
+        this.pendingRegenerations.add(absolutePath);
+        return;
+      }
+      this.isGenerating = true;
+      this.pendingRegenerations.clear();
+      if (this.debug) {
+        orchestratorLogger.info(`File ${event}`, { file: filePath });
+      }
+      for (const generator of this.generators) {
+        const matches = generator.watchPatterns.some(
+          (pattern) => mm.isMatch(filePath, pattern)
+        );
+        if (matches) {
+          try {
+            if (generator.onFileChange) {
+              await generator.onFileChange(filePath, event);
+            } else {
+              const genOptions = {
+                cwd: this.cwd,
+                debug: this.debug
+              };
+              await generator.generate(genOptions);
+            }
+            if (this.debug) {
+              orchestratorLogger.info(`[${generator.name}] Regenerated`);
+            }
+          } catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            orchestratorLogger.error(`[${generator.name}] Regeneration failed`, err);
+          }
+        }
+      }
+      this.isGenerating = false;
+      if (this.pendingRegenerations.size > 0) {
+        const next = Array.from(this.pendingRegenerations)[0];
+        await handleChange(next, "change");
+      }
+    };
+    watcher.on("add", (path) => handleChange(path, "add")).on("change", (path) => handleChange(path, "change")).on("unlink", (path) => handleChange(path, "unlink"));
+    process.on("SIGINT", () => {
+      if (this.debug) {
+        orchestratorLogger.info("Shutting down watch mode");
+      }
+      watcher.close();
+      process.exit(0);
+    });
+    await new Promise(() => {
+    });
+  }
+};
+var contractLogger = logger.child("contract-gen");
+function createContractGenerator(config = {}) {
+  return {
+    name: "contract",
+    watchPatterns: [config.routesDir ?? "src/server/routes/**/*.ts"],
+    async generate(options) {
+      const cwd = options.cwd;
+      const routesDir = config.routesDir ?? join(cwd, "src", "server", "routes");
+      const outputPath = config.outputPath ?? join(cwd, "src", "lib", "api.ts");
+      try {
+        const contracts = await scanContracts(routesDir);
+        if (contracts.length === 0) {
+          if (options.debug) {
+            contractLogger.warn("No contracts found");
+          }
+          return;
+        }
+        const stats = await generateClient(contracts, {
+          outputPath,
+          includeTypes: true,
+          includeJsDoc: true
+        });
+        if (options.debug) {
+          contractLogger.info("Client generated", {
+            endpoints: stats.methodsGenerated,
+            resources: stats.resourcesGenerated,
+            duration: stats.duration
+          });
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        contractLogger.error("Generation failed", err);
+        throw err;
+      }
+    }
+  };
+}
+var configLogger = logger.child("config");
+function loadCodegenConfig(cwd) {
+  const rcPath = join(cwd, ".spfnrc.json");
+  if (existsSync(rcPath)) {
+    try {
+      const content = readFileSync(rcPath, "utf-8");
+      const config = JSON.parse(content);
+      if (config.codegen) {
+        configLogger.info("Loaded config from .spfnrc.json");
+        return config.codegen;
+      }
+    } catch (error) {
+      configLogger.warn("Failed to parse .spfnrc.json", error);
+    }
+  }
+  const pkgPath = join(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const content = readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(content);
+      if (pkg.spfn?.codegen) {
+        configLogger.info("Loaded config from package.json");
+        return pkg.spfn.codegen;
+      }
+    } catch (error) {
+      configLogger.warn("Failed to parse package.json", error);
+    }
+  }
+  configLogger.info("Using default config");
+  return {
+    generators: {
+      contract: { enabled: true }
+    }
+  };
+}
+function createGeneratorsFromConfig(config) {
+  const generators = [];
+  if (config.generators?.contract?.enabled !== false) {
+    const contractConfig = {
+      routesDir: config.generators?.contract?.routesDir,
+      outputPath: config.generators?.contract?.outputPath};
+    generators.push(createContractGenerator(contractConfig));
+    configLogger.info("Contract generator enabled");
+  }
+  return generators;
+}
 
-export { generateClient, groupByResource, scanContracts, watchAndGenerate };
+export { CodegenOrchestrator, createContractGenerator, createGeneratorsFromConfig, generateClient, groupByResource, loadCodegenConfig, scanContracts, watchAndGenerate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map