@effijs/forge 0.0.0-stage → 1.0.0-alpha.0

package/src/cli/ForgeCLI.js

@@ -0,0 +1,189 @@
+import { Command } from "commander";
+import inquirer from "inquirer";
+import fs from "fs/promises";
+import path from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { Forge } from "../Forge.js";
+import { discoverGenerators } from "../config/resolveGenerator.js";
+import { scaffoldLocalGenerator } from "./scaffoldLocal.js";
+import { parseUnknownFlags } from "./parseArgv.js";
+
+export class ForgeCLI {
+  constructor() {
+    this.program = new Command();
+    this.forge = null;
+  }
+
+  async init(cwd = process.cwd()) {
+    this.forge = await Forge.create(cwd);
+
+    this.program
+      .name("forge")
+      .description("A modern scaffolding tool for generating code and projects")
+      .version("1.0.0");
+
+    const generateCmd = this.program
+      .command("generate <generator>")
+      .alias("g")
+      .description("Run a generator")
+      .option("--dry-run", "Preview without writing files")
+      .option("--force", "Overwrite existing files")
+      .option("--yes", "Skip prompts and use defaults")
+      .option("--name <name>", "Pass name directly")
+      .option("--path <path>", "Pass path directly")
+      .allowUnknownOption()
+      .action(async (generator, options) => {
+        const runOptions = {
+          dryRun: options.dryRun,
+          force: options.force,
+          yes: options.yes,
+        };
+        if (options.name) runOptions.name = options.name;
+        if (options.path) runOptions.path = options.path;
+
+        Object.assign(runOptions, parseUnknownFlags(this.argv ?? process.argv));
+
+        await this.forge.run(generator, runOptions);
+      });
+
+    this.program
+      .command("list")
+      .alias("ls")
+      .description("List available generators")
+      .action(async () => {
+        const spinner = ora("Loading generators...").start();
+
+        try {
+          const catalog = await discoverGenerators(this.forge.config);
+          spinner.stop();
+
+          const byNamespace = new Map();
+          for (const [id, meta] of catalog) {
+            const ns = meta.namespace ?? id.split(":")[0];
+            if (!byNamespace.has(ns)) byNamespace.set(ns, []);
+            byNamespace.get(ns).push({ id, meta });
+          }
+
+          console.log(chalk.bold.cyan("\n📦 Available generators:\n"));
+
+          for (const [ns, items] of byNamespace) {
+            const label =
+              ns === "local"
+                ? "Local"
+                : `Extended (${ns})`;
+            console.log(chalk.bold(label + ":"));
+            for (const { id, meta } of items) {
+              const shortName = id.split(":")[1] ?? id;
+              const desc = meta.description ? chalk.dim(` — ${meta.description}`) : "";
+              console.log(`  • ${chalk.green(shortName)}${desc}`);
+            }
+            console.log("");
+          }
+
+          const aliases = this.forge.config.aliases ?? {};
+          const aliasEntries = Object.entries(aliases);
+          if (aliasEntries.length) {
+            console.log(chalk.bold("Aliases:"));
+            for (const [alias, target] of aliasEntries) {
+              console.log(`  ${chalk.yellow(alias)} → ${target}`);
+            }
+            console.log("");
+          }
+        } catch (error) {
+          spinner.fail("Failed to list generators");
+          console.error(chalk.red(error.message));
+        }
+      });
+
+    this.program
+      .command("init")
+      .description("Initialize Forge configuration and local directories")
+      .action(async () => {
+        const answers = await inquirer.prompt([
+          {
+            type: "input",
+            name: "templatesDir",
+            message: "Local templates directory:",
+            default: "./forge/templates",
+          },
+          {
+            type: "input",
+            name: "generatorsDir",
+            message: "Local generators directory:",
+            default: "./forge/generators",
+          },
+          {
+            type: "input",
+            name: "outputDir",
+            message: "Default output directory:",
+            default: "./src",
+          },
+          {
+            type: "list",
+            name: "templateEngine",
+            message: "Template engine:",
+            choices: ["handlebars", "eta"],
+            default: "handlebars",
+          },
+          {
+            type: "confirm",
+            name: "usePreset",
+            message: "Use @effijs/templates preset (react-native-fsd)?",
+            default: true,
+          },
+        ]);
+
+        const config = {
+          outputDir: answers.outputDir,
+          templateEngine: answers.templateEngine,
+          local: {
+            templatesDir: answers.templatesDir,
+            generatorsDir: answers.generatorsDir,
+          },
+        };
+
+        if (answers.usePreset) {
+          config.preset = "react-native-fsd";
+          config.presetMap = {
+            "rn-fsd": "@effijs/templates/presets/react-native-fsd",
+          };
+          config.primaryPreset = "rn-fsd";
+          config.generators = ["rn-fsd:component"];
+          config.aliases = { comp: "rn-fsd:component" };
+        }
+
+        const configContent = `export default ${JSON.stringify(config, null, 2)};\n`;
+        await fs.writeFile("./forge.config.js", configContent);
+
+        await fs.mkdir(answers.templatesDir, { recursive: true });
+        await fs.mkdir(answers.generatorsDir, { recursive: true });
+
+        console.log(chalk.green("\n✅ Created forge.config.js and ./forge/ directories\n"));
+      });
+
+    const newCmd = this.program
+      .command("new")
+      .description("Scaffold new resources");
+
+    newCmd
+      .command("local <name>")
+      .description("Create a local generator with example templates")
+      .option("--type <type>", "Variant: service | api | component", "service")
+      .option("--force", "Overwrite existing generator")
+      .option("--no-register", "Skip auto-register in forge.config.js")
+      .action(async (name, options) => {
+        await scaffoldLocalGenerator({
+          name,
+          type: options.type,
+          force: options.force,
+          register: options.register !== false,
+        });
+      });
+  }
+
+  run(argv = process.argv) {
+    this.argv = argv;
+    this.program.parse(argv);
+  }
+}

package/src/cli/parseArgv.js

@@ -0,0 +1,50 @@
+const RESERVED_FLAGS = new Set(["dry-run", "force", "yes", "name", "path"]);
+
+function camelCaseFlag(key) {
+  return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function coerceFlagValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return value;
+}
+
+/**
+ * Collect generator data from unknown long flags.
+ * Reserved run flags stay with the commander options that already parsed them.
+ */
+export function parseUnknownFlags(argv) {
+  const data = {};
+  const args = Array.isArray(argv) ? argv : [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") break;
+    if (!arg.startsWith("--")) continue;
+
+    const body = arg.slice(2);
+    let key;
+    let value;
+    const eq = body.indexOf("=");
+
+    if (eq !== -1) {
+      key = body.slice(0, eq);
+      value = body.slice(eq + 1);
+    } else {
+      key = body;
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        value = next;
+        i++;
+      } else {
+        value = true;
+      }
+    }
+
+    if (!key || RESERVED_FLAGS.has(key)) continue;
+    data[camelCaseFlag(key)] = coerceFlagValue(value);
+  }
+
+  return data;
+}

package/src/cli/scaffoldLocal.js

@@ -0,0 +1,228 @@
+import fs from "fs/promises";
+import path from "path";
+import chalk from "chalk";
+import * as changeCase from "change-case";
+
+const TYPE_VARIANTS = {
+  service: {
+    files: [
+      {
+        name: "{{kebabCase name}}.service.ts.hbs",
+        content: `export class {{pascalCase name}}Service {
+  async execute(): Promise<void> {
+    // TODO: implement {{camelCase name}} service
+  }
+}
+`,
+      },
+      {
+        name: "{{kebabCase name}}.types.ts.hbs",
+        content: `export interface {{pascalCase name}}Config {
+  // TODO: define config
+}
+`,
+      },
+      {
+        name: "index.ts.hbs",
+        content: `export * from './{{kebabCase name}}.service';\nexport * from './{{kebabCase name}}.types';\n`,
+      },
+    ],
+    actions: `[
+    {
+      type: "add",
+      path: "{{kebabCase name}}/{{kebabCase name}}.service.ts",
+      templateFile: "{{kebabCase name}}/{{kebabCase name}}.service.ts.hbs",
+    },
+    {
+      type: "add",
+      path: "{{kebabCase name}}/{{kebabCase name}}.types.ts",
+      templateFile: "{{kebabCase name}}/{{kebabCase name}}.types.ts.hbs",
+    },
+    {
+      type: "add",
+      path: "{{kebabCase name}}/index.ts",
+      templateFile: "{{kebabCase name}}/index.ts.hbs",
+    },
+  ]`,
+  },
+  api: {
+    files: [
+      {
+        name: "{{kebabCase name}}.api.ts.hbs",
+        content: `export async function fetch{{pascalCase name}}(): Promise<unknown> {
+  // TODO: implement API client
+  return null;
+}
+`,
+      },
+      {
+        name: "{{kebabCase name}}.types.ts.hbs",
+        content: `export type {{pascalCase name}}Response = Record<string, unknown>;\n`,
+      },
+      {
+        name: "index.ts.hbs",
+        content: `export * from './{{kebabCase name}}.api';\n`,
+      },
+    ],
+    actions: `[
+    {
+      type: "add",
+      path: "api/{{kebabCase name}}.api.ts",
+      templateFile: "{{kebabCase name}}/{{kebabCase name}}.api.ts.hbs",
+    },
+    {
+      type: "add",
+      path: "api/{{kebabCase name}}.types.ts",
+      templateFile: "{{kebabCase name}}/{{kebabCase name}}.types.ts.hbs",
+    },
+  ]`,
+  },
+  component: {
+    files: [
+      {
+        name: "{{pascalCase name}}.tsx.hbs",
+        content: `import React from 'react';
+
+export function {{pascalCase name}}() {
+  return <div>{{pascalCase name}}</div>;
+}
+`,
+      },
+      {
+        name: "index.ts.hbs",
+        content: `export { {{pascalCase name}} } from './{{pascalCase name}}';\n`,
+      },
+    ],
+    actions: `[
+    {
+      type: "add",
+      path: "components/{{pascalCase name}}/{{pascalCase name}}.tsx",
+      templateFile: "{{kebabCase name}}/{{pascalCase name}}.tsx.hbs",
+    },
+    {
+      type: "add",
+      path: "components/{{pascalCase name}}/index.ts",
+      templateFile: "{{kebabCase name}}/index.ts.hbs",
+    },
+  ]`,
+  },
+};
+
+export async function scaffoldLocalGenerator(options = {}) {
+  const {
+    name,
+    type = "service",
+    description = "",
+    force = false,
+    register = true,
+    cwd = process.cwd(),
+  } = options;
+
+  const kebabName = changeCase.kebabCase(name);
+  const variant = TYPE_VARIANTS[type] ?? TYPE_VARIANTS.service;
+
+  const generatorsDir = path.join(cwd, "forge", "generators", kebabName);
+  const templatesDir = path.join(cwd, "forge", "templates", kebabName);
+
+  try {
+    await fs.access(generatorsDir);
+    if (!force) {
+      throw new Error(
+        `Generator "${kebabName}" already exists. Use --force to overwrite.`,
+      );
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+
+  await fs.mkdir(generatorsDir, { recursive: true });
+  await fs.mkdir(templatesDir, { recursive: true });
+
+  for (const file of variant.files) {
+    const fileName = file.name
+      .replace(/\{\{kebabCase name\}\}/g, kebabName)
+      .replace(/\{\{pascalCase name\}\}/g, changeCase.pascalCase(name));
+    const filePath = path.join(templatesDir, fileName);
+    const content = file.content
+      .replace(/\{\{pascalCase name\}\}/g, changeCase.pascalCase(name))
+      .replace(/\{\{camelCase name\}\}/g, changeCase.camelCase(name))
+      .replace(/\{\{kebabCase name\}\}/g, kebabName);
+    await fs.writeFile(filePath, content);
+  }
+
+  const generatorJs = `export default {
+  description: "${description || `Local ${type} generator: ${kebabName}`}",
+  prompts: [
+    {
+      type: "input",
+      name: "name",
+      message: "Name:",
+      default: "${changeCase.pascalCase(name)}",
+    },
+  ],
+  actions: ${variant.actions},
+};
+`;
+
+  await fs.writeFile(path.join(generatorsDir, "generator.js"), generatorJs);
+
+  const readme = `# ${kebabName}
+
+Local Forge generator (${type}).
+
+## Run
+
+\`\`\`bash
+forge g local:${kebabName}
+\`\`\`
+
+## Customize
+
+- Edit \`forge/generators/${kebabName}/generator.js\`
+- Edit templates in \`forge/templates/${kebabName}/\`
+`;
+
+  await fs.writeFile(path.join(generatorsDir, "README.md"), readme);
+
+  if (register) {
+    await registerInConfig(cwd, kebabName);
+  }
+
+  console.log(chalk.green(`\n✅ Created local generator "${kebabName}"`));
+  console.log(chalk.dim(`   forge/generators/${kebabName}/`));
+  console.log(chalk.dim(`   forge/templates/${kebabName}/\n`));
+
+  return { name: kebabName, generatorsDir, templatesDir };
+}
+
+async function registerInConfig(cwd, kebabName) {
+  const configPath = path.join(cwd, "forge.config.js");
+  const entry = `local:${kebabName}`;
+
+  try {
+    let content = await fs.readFile(configPath, "utf-8");
+
+    if (content.includes(entry)) return;
+
+    if (content.includes("generators:")) {
+      content = content.replace(
+        /generators:\s*\[/,
+        `generators: [\n    "${entry}",`,
+      );
+    } else {
+      content = content.replace(
+        /export default \{/,
+        `export default {\n  generators: ["${entry}"],`,
+      );
+    }
+
+    await fs.writeFile(configPath, content);
+    console.log(chalk.dim(`   Registered "${entry}" in forge.config.js`));
+  } catch {
+    console.log(
+      chalk.yellow(
+        `   Add "${entry}" to generators in forge.config.js manually`,
+      ),
+    );
+  }
+}

package/src/config/loadConfig.js

@@ -0,0 +1,52 @@
+import fs from "fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+
+const CONFIG_FILES = [
+  "forge.config.js",
+  "forge.config.mjs",
+  ".forgerc.js",
+  ".forgerc.json",
+];
+
+export const BASE_DEFAULTS = {
+  templatesDir: "./templates",
+  outputDir: "./src",
+  templateEngine: "handlebars",
+  helpers: {},
+};
+
+/**
+ * Load project forge config from cwd.
+ * @returns {Promise<{ config: object, configFileDir: string | null }>}
+ */
+export async function loadLocalConfig(cwd = process.cwd()) {
+  for (const configFile of CONFIG_FILES) {
+    const fullPath = path.resolve(cwd, configFile);
+
+    try {
+      await fs.access(fullPath);
+
+      if (configFile.endsWith(".json")) {
+        const content = await fs.readFile(fullPath, "utf-8");
+        return {
+          config: JSON.parse(content),
+          configFileDir: path.dirname(fullPath),
+        };
+      }
+
+      const module = await import(pathToFileURL(fullPath).href);
+      return {
+        config: module.default ?? module,
+        configFileDir: path.dirname(fullPath),
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw new Error(
+        `Failed to load config "${configFile}": ${error.message}`,
+      );
+    }
+  }
+
+  return { config: {}, configFileDir: null };
+}

package/src/config/loadPreset.js

@@ -0,0 +1,85 @@
+import path from "path";
+import { pathToFileURL, fileURLToPath } from "url";
+import fs from "fs/promises";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function defaultResolve(specifier) {
+  return import.meta.resolve(specifier);
+}
+
+async function finalizeModulePath(absPath) {
+  let stat = null;
+  try {
+    stat = await fs.stat(absPath);
+  } catch {
+    stat = null;
+  }
+
+  if (stat?.isFile()) return absPath;
+  if (stat?.isDirectory()) return path.join(absPath, "index.js");
+  if (path.extname(absPath)) return absPath;
+  return path.join(absPath, "index.js");
+}
+
+/**
+ * Resolve a preset reference to the module file that should be imported.
+ * Absolute paths and `./` / `../` are files or directories on disk.
+ * Any other specifier goes through Node resolution, then a monorepo fallback.
+ */
+export async function resolvePresetPath(
+  presetRef,
+  presetMap = {},
+  resolveImport = defaultResolve,
+) {
+  if (presetMap[presetRef]) {
+    return resolvePresetPath(presetMap[presetRef], {}, resolveImport);
+  }
+
+  if (path.isAbsolute(presetRef)) {
+    return finalizeModulePath(presetRef);
+  }
+
+  if (presetRef.startsWith("./") || presetRef.startsWith("../")) {
+    return finalizeModulePath(path.resolve(process.cwd(), presetRef));
+  }
+
+  try {
+    const resolved = resolveImport(presetRef);
+    const filePath = String(resolved).startsWith("file:")
+      ? fileURLToPath(resolved)
+      : resolved;
+    return finalizeModulePath(filePath);
+  } catch {
+    // Package resolution failed; try the checkout next to Forge, then cwd.
+  }
+
+  const templatesPkg = path.resolve(__dirname, "../../../templates");
+  const fromTemplates = path.join(templatesPkg, "presets", presetRef);
+  try {
+    await fs.access(fromTemplates);
+    return finalizeModulePath(fromTemplates);
+  } catch {
+    return finalizeModulePath(path.resolve(process.cwd(), presetRef));
+  }
+}
+
+/**
+ * Load a preset config module.
+ */
+export async function loadPreset(presetRef, presetMap = {}) {
+  const modulePath = await resolvePresetPath(presetRef, presetMap);
+
+  try {
+    const module = await import(pathToFileURL(modulePath).href);
+    const config = module.default ?? module;
+    const presetDir = path.dirname(modulePath);
+    return {
+      ...config,
+      id: config.id ?? path.basename(presetDir),
+      _presetDir: presetDir,
+    };
+  } catch (error) {
+    throw new Error(`Failed to load preset "${presetRef}": ${error.message}`);
+  }
+}

package/src/config/mergeConfig.js

@@ -0,0 +1,104 @@
+import path from "path";
+import { BASE_DEFAULTS, loadLocalConfig } from "./loadConfig.js";
+import { loadPreset } from "./loadPreset.js";
+import { deepMerge } from "../utils/deepMerge.js";
+import { resolveForgePaths } from "../utils/resolvePaths.js";
+
+function resolvePresetIds(config) {
+  if (config.presets?.length) return config.presets;
+  if (config.preset) {
+    const id =
+      typeof config.preset === "string" && !config.preset.includes("/")
+        ? config.preset
+        : path.basename(config.preset);
+    return [id];
+  }
+  return [];
+}
+
+function buildTemplateRoots(presets, paths, localConfig) {
+  const roots = [];
+
+  for (const preset of presets) {
+    const templatesDir = preset.templatesDir
+      ? path.isAbsolute(preset.templatesDir)
+        ? preset.templatesDir
+        : path.resolve(preset._presetDir, preset.templatesDir)
+      : path.resolve(preset._presetDir, "../../generators");
+
+    roots.push({
+      id: preset.id,
+      namespace: preset.id,
+      templatesDir,
+      generatorsDir: templatesDir,
+      generators: preset.generators ?? {},
+    });
+  }
+
+  roots.push({
+    id: "local",
+    namespace: "local",
+    templatesDir: paths.localTemplatesDir,
+    generatorsDir: paths.localGeneratorsDir,
+    generators: {},
+  });
+
+  return roots;
+}
+
+function collectGeneratorCatalog(templateRoots) {
+  const catalog = new Map();
+
+  for (const root of templateRoots) {
+    if (root.generators && typeof root.generators === "object") {
+      for (const [name, meta] of Object.entries(root.generators)) {
+        const namespacedId = `${root.namespace}:${name}`;
+        catalog.set(namespacedId, {
+          id: namespacedId,
+          name,
+          namespace: root.namespace,
+          root,
+          ...meta,
+        });
+      }
+    }
+  }
+
+  return catalog;
+}
+
+/**
+ * Merge base → extended presets → local project config.
+ */
+export async function mergeConfig(cwd = process.cwd()) {
+  const { config: localConfig, configFileDir } = await loadLocalConfig(cwd);
+
+  let merged = deepMerge({}, BASE_DEFAULTS);
+  const presetIds = resolvePresetIds(localConfig);
+  const presetMap = localConfig.presetMap ?? {};
+  const loadedPresets = [];
+
+  for (const presetId of presetIds) {
+    const presetRef = presetMap[presetId] ?? presetId;
+    const preset = await loadPreset(presetRef, presetMap);
+    preset.id = preset.id ?? presetId;
+    loadedPresets.push(preset);
+    merged = deepMerge(merged, preset);
+  }
+
+  merged = deepMerge(merged, localConfig);
+  merged.configFileDir = configFileDir;
+  merged.primaryPreset =
+    merged.primaryPreset ?? loadedPresets[0]?.id ?? null;
+
+  const paths = resolveForgePaths(merged, configFileDir);
+  merged.paths = paths;
+  merged.templateRoots = buildTemplateRoots(
+    loadedPresets,
+    paths,
+    localConfig.local,
+  );
+  merged.generatorCatalog = collectGeneratorCatalog(merged.templateRoots);
+
+  return merged;
+}