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

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;
+}

package/src/config/resolveGenerator.js

@@ -0,0 +1,149 @@
+import path from "path";
+import { pathToFileURL } from "url";
+import fs from "fs/promises";
+import { glob } from "tinyglobby";
+
+/**
+ * Resolve user input to a namespaced generator id.
+ */
+export function resolveGeneratorId(input, config) {
+  const aliases = config.aliases ?? {};
+  const catalog = config.generatorCatalog ?? new Map();
+  const whitelist = config.generators;
+
+  if (aliases[input]) {
+    return resolveGeneratorId(aliases[input], config);
+  }
+
+  if (input.includes(":")) {
+    if (aliases[input]) return aliases[input];
+
+    if (catalog.has(input)) return input;
+
+    const [namespace, action] = input.split(":");
+    const namespaced = `${namespace}:${action}`;
+    if (catalog.has(namespaced)) return namespaced;
+  }
+
+  const bareMatches = [...catalog.keys()].filter(
+    (id) => id.endsWith(`:${input}`) || id === `local:${input}`,
+  );
+
+  if (bareMatches.length === 1) {
+    const resolved = bareMatches[0];
+    if (!whitelist?.length || whitelist.includes(resolved)) {
+      return resolved;
+    }
+  }
+
+  if (bareMatches.length > 1) {
+    const suggestions = bareMatches.map((id) => `  ${id}`).join("\n");
+    throw new Error(
+      `Ambiguous generator "${input}". Did you mean:\n${suggestions}`,
+    );
+  }
+
+  const primary = config.primaryPreset;
+  if (primary) {
+    const primaryId = `${primary}:${input}`;
+    if (catalog.has(primaryId)) return primaryId;
+  }
+
+  if (catalog.has(`local:${input}`)) return `local:${input}`;
+
+  throw new Error(`Generator "${input}" not found`);
+}
+
+/**
+ * Find generator.js path for a resolved generator id.
+ */
+export async function findGeneratorPath(generatorId, config) {
+  const [namespace, action] = generatorId.split(":");
+  const root = config.templateRoots?.find((r) => r.namespace === namespace);
+
+  if (!root) {
+    throw new Error(`No template root for namespace "${namespace}"`);
+  }
+
+  const meta = config.generatorCatalog?.get(generatorId);
+  const subPath = meta?.path ?? action;
+
+  const candidates = [
+    path.join(root.generatorsDir, subPath, "generator.js"),
+    path.join(root.generatorsDir, action, "generator.js"),
+    path.join(root.templatesDir, subPath, "generator.js"),
+    path.join(root.templatesDir, action, "generator.js"),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return { generatorPath: candidate, root, meta };
+    } catch {
+      // continue
+    }
+  }
+
+  throw new Error(
+    `Generator file not found for "${generatorId}" in ${root.generatorsDir}`,
+  );
+}
+
+/**
+ * Load generator module by id.
+ */
+export async function loadGenerator(generatorId, config) {
+  const { generatorPath, root, meta } = await findGeneratorPath(
+    generatorId,
+    config,
+  );
+
+  try {
+    const module = await import(
+      pathToFileURL(generatorPath).href + `?t=${Date.now()}`
+    );
+    const generator = module.default ?? module;
+    return {
+      ...generator,
+      id: generatorId,
+      _root: root,
+      _meta: meta,
+      _generatorPath: generatorPath,
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to load generator "${generatorId}": ${error.message}`,
+    );
+  }
+}
+
+/**
+ * List all generators from template roots (filesystem scan fallback).
+ */
+export async function discoverGenerators(config) {
+  const discovered = new Map(config.generatorCatalog ?? []);
+
+  for (const root of config.templateRoots ?? []) {
+    const files = await glob("**/generator.js", {
+      cwd: root.generatorsDir,
+      onlyFiles: true,
+    }).catch(() => []);
+
+    for (const file of files) {
+      const dir = path.dirname(file);
+      const name = path.basename(dir);
+      const id = `${root.namespace}:${name}`;
+      if (!discovered.has(id)) {
+        discovered.set(id, {
+          id,
+          name,
+          namespace: root.namespace,
+          path: dir,
+          root,
+        });
+      }
+    }
+  }
+
+  return discovered;
+}

package/src/engines/eta.js

@@ -0,0 +1,28 @@
+import { Eta } from "eta";
+import * as changeCase from "change-case";
+
+const CASE_FUNCTIONS = {
+  camelCase: changeCase.camelCase,
+  capitalCase: changeCase.capitalCase,
+  constantCase: changeCase.constantCase,
+  dotCase: changeCase.dotCase,
+  kebabCase: changeCase.kebabCase,
+  noCase: changeCase.noCase,
+  pascalCase: changeCase.pascalCase,
+  pathCase: changeCase.pathCase,
+  sentenceCase: changeCase.sentenceCase,
+  snakeCase: changeCase.snakeCase,
+  trainCase: changeCase.trainCase,
+};
+
+export function createEtaEngine(templatesDir) {
+  return new Eta({
+    views: templatesDir,
+    autoEscape: false,
+  });
+}
+
+export function renderEtaString(eta, templateContent, data) {
+  const context = { ...data, ...CASE_FUNCTIONS };
+  return eta.renderString(templateContent, context);
+}

package/src/engines/handlebars.js

@@ -0,0 +1,61 @@
+import Handlebars from "handlebars";
+import * as changeCase from "change-case";
+
+const CASE_FUNCTIONS = {
+  camelCase: changeCase.camelCase,
+  capitalCase: changeCase.capitalCase,
+  constantCase: changeCase.constantCase,
+  dotCase: changeCase.dotCase,
+  kebabCase: changeCase.kebabCase,
+  noCase: changeCase.noCase,
+  pascalCase: changeCase.pascalCase,
+  pathCase: changeCase.pathCase,
+  sentenceCase: changeCase.sentenceCase,
+  snakeCase: changeCase.snakeCase,
+  trainCase: changeCase.trainCase,
+};
+
+let helpersRegistered = false;
+
+export function registerHandlebarsHelpers(customHelpers = {}) {
+  if (helpersRegistered) return;
+
+  Object.entries(CASE_FUNCTIONS).forEach(([name, fn]) => {
+    Handlebars.registerHelper(name, fn);
+  });
+
+  Handlebars.registerHelper("eq", (a, b) => a === b);
+  Handlebars.registerHelper("ne", (a, b) => a !== b);
+  Handlebars.registerHelper("lt", (a, b) => a < b);
+  Handlebars.registerHelper("gt", (a, b) => a > b);
+  Handlebars.registerHelper("lte", (a, b) => a <= b);
+  Handlebars.registerHelper("gte", (a, b) => a >= b);
+  Handlebars.registerHelper("and", (...args) =>
+    args.slice(0, -1).every(Boolean),
+  );
+  Handlebars.registerHelper("or", (...args) =>
+    args.slice(0, -1).some(Boolean),
+  );
+  Handlebars.registerHelper("not", (value) => !value);
+  Handlebars.registerHelper("includes", (arr, value) => {
+    if (!arr) return false;
+    if (Array.isArray(arr)) return arr.includes(value);
+    return String(arr).includes(String(value));
+  });
+  Handlebars.registerHelper("concat", (...args) =>
+    args.slice(0, -1).join(""),
+  );
+  Handlebars.registerHelper("json", (value) => JSON.stringify(value));
+
+  Object.entries(customHelpers).forEach(([name, fn]) => {
+    Handlebars.registerHelper(name, fn);
+  });
+
+  helpersRegistered = true;
+}
+
+export function compileHandlebars(templateContent, data) {
+  registerHandlebarsHelpers();
+  const template = Handlebars.compile(templateContent);
+  return template(data);
+}

package/src/fs/addFile.js

@@ -0,0 +1,34 @@
+import fs from "fs/promises";
+import path from "path";
+import chalk from "chalk";
+import ora from "ora";
+
+export async function addFile(filePath, content, options = {}) {
+  const { dryRun = false, force = false } = options;
+  const spinner = ora(`Creating ${chalk.blue(filePath)}`).start();
+
+  try {
+    const exists = await fs
+      .access(filePath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (exists && !force) {
+      spinner.warn(`Skipped (exists) ${chalk.yellow(filePath)}`);
+      return { success: true, skipped: true, path: filePath };
+    }
+
+    if (dryRun) {
+      spinner.info(`[dry-run] Would create ${chalk.cyan(filePath)}`);
+      return { success: true, dryRun: true, path: filePath };
+    }
+
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content);
+    spinner.succeed(`Created ${chalk.green(filePath)}`);
+    return { success: true, path: filePath };
+  } catch (error) {
+    spinner.fail(`Failed to create ${filePath}: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}

package/src/fs/modifyFile.js

@@ -0,0 +1,110 @@
+import fs from "fs/promises";
+import chalk from "chalk";
+import ora from "ora";
+
+const FILE_CONTROL = Symbol("forgeFileControl");
+
+function skipControl() {
+  return { [FILE_CONTROL]: "skip" };
+}
+
+function failControl(error) {
+  return { [FILE_CONTROL]: "fail", error };
+}
+
+function resolveAppendOptions(input = {}) {
+  const nested =
+    input.options && typeof input.options === "object" ? input.options : {};
+  const pick = (key) => (input[key] !== undefined ? input[key] : nested[key]);
+  return {
+    pattern: pick("pattern"),
+    flags: pick("flags"),
+    before: pick("before") ?? false,
+    unique: Boolean(pick("unique")),
+  };
+}
+
+function compileAppendPattern(pattern, flags) {
+  if (pattern instanceof RegExp) {
+    return new RegExp(pattern.source, pattern.flags);
+  }
+  return new RegExp(pattern, flags ?? "g");
+}
+
+function patternLabel(pattern) {
+  return pattern instanceof RegExp ? pattern.toString() : String(pattern);
+}
+
+export async function modifyFile(filePath, modifier, options = {}) {
+  const { dryRun = false, force = false } = options;
+  const spinner = ora(`Modifying ${chalk.blue(filePath)}`).start();
+
+  try {
+    const exists = await fs
+      .access(filePath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (!exists) {
+      if (!force) {
+        spinner.fail(`File not found: ${filePath}`);
+        return { success: false, error: "File not found" };
+      }
+    }
+
+    const content = exists ? await fs.readFile(filePath, "utf-8") : "";
+    const modified = await modifier(content);
+
+    if (modified && typeof modified === "object" && modified[FILE_CONTROL]) {
+      if (modified[FILE_CONTROL] === "skip") {
+        spinner.warn(`Skipped (already present) ${chalk.yellow(filePath)}`);
+        return { success: true, skipped: true, path: filePath };
+      }
+      const error = modified.error || "Failed to modify file";
+      spinner.fail(error);
+      return { success: false, error, path: filePath };
+    }
+
+    if (dryRun) {
+      spinner.info(`[dry-run] Would modify ${chalk.cyan(filePath)}`);
+      return { success: true, dryRun: true, path: filePath };
+    }
+
+    await fs.writeFile(filePath, modified);
+    spinner.succeed(`Modified ${chalk.green(filePath)}`);
+    return { success: true, path: filePath };
+  } catch (error) {
+    spinner.fail(`Failed to modify ${filePath}: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}
+
+export async function appendToFile(filePath, content, appendOptions = {}, runOptions = {}) {
+  const { pattern, flags, before, unique } = resolveAppendOptions(appendOptions);
+
+  return modifyFile(
+    filePath,
+    (fileContent) => {
+      const fragment = String(content).trim();
+      if (unique && fragment && fileContent.includes(fragment)) {
+        return skipControl();
+      }
+
+      if (pattern === undefined || pattern === null || pattern === "") {
+        return fileContent + content;
+      }
+
+      const regex = compileAppendPattern(pattern, flags);
+      const matched = regex.test(fileContent);
+      regex.lastIndex = 0;
+      if (!matched) {
+        return failControl(`Marker not found: ${patternLabel(pattern)}`);
+      }
+
+      return fileContent.replace(regex, (match) =>
+        before ? content + match : match + content,
+      );
+    },
+    runOptions,
+  );
+}

package/src/fs/processTemplate.js

@@ -0,0 +1,133 @@
+import fs from "fs/promises";
+import path from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { glob } from "tinyglobby";
+
+export async function processTemplate(
+  templatePath,
+  outputPath,
+  renderTemplate,
+  options = {},
+) {
+  const { dryRun = false, force = false } = options;
+  const spinner = ora(
+    `Processing ${chalk.blue(path.basename(templatePath))}`,
+  ).start();
+
+  try {
+    const templateContent = await fs.readFile(templatePath, "utf-8");
+    const rendered = await renderTemplate(templateContent, options.data);
+
+    const exists = await fs
+      .access(outputPath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (exists && !force) {
+      spinner.warn(`Skipped (exists) ${chalk.yellow(outputPath)}`);
+      return { success: true, skipped: true, path: outputPath };
+    }
+
+    if (dryRun) {
+      spinner.info(`[dry-run] Would create ${chalk.cyan(outputPath)}`);
+      return { success: true, dryRun: true, path: outputPath };
+    }
+
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, rendered);
+    spinner.succeed(`Created ${chalk.green(outputPath)}`);
+    return { success: true, path: outputPath };
+  } catch (error) {
+    spinner.fail(`Failed to process ${templatePath}: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}
+
+export async function copyStaticFile(sourcePath, outputPath, options = {}) {
+  const { dryRun = false, force = false } = options;
+  const spinner = ora(`Copying ${chalk.blue(path.basename(sourcePath))}`).start();
+
+  try {
+    const exists = await fs
+      .access(outputPath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (exists && !force) {
+      spinner.warn(`Skipped (exists) ${chalk.yellow(outputPath)}`);
+      return { success: true, skipped: true, path: outputPath };
+    }
+
+    if (dryRun) {
+      spinner.info(`[dry-run] Would create ${chalk.cyan(outputPath)}`);
+      return { success: true, dryRun: true, path: outputPath };
+    }
+
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.copyFile(sourcePath, outputPath);
+    spinner.succeed(`Created ${chalk.green(outputPath)}`);
+    return { success: true, path: outputPath };
+  } catch (error) {
+    spinner.fail(`Failed to copy ${sourcePath}: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}
+
+export async function processDirectory(
+  templateDir,
+  outputDir,
+  renderTemplate,
+  data,
+  options = {},
+) {
+  const {
+    dryRun = false,
+    force = false,
+    ignore,
+    processFileNames = true,
+    templateSuffix = ".hbs",
+  } = options;
+
+  const spinner = ora("Scanning templates...").start();
+
+  try {
+    const templateFiles = await glob("**/*", {
+      cwd: templateDir,
+      onlyFiles: true,
+      ignore: ignore || ["**/node_modules/**", "**/.git/**", "**/generator.js"],
+    });
+
+    spinner.succeed(`Found ${templateFiles.length} template files`);
+
+    const results = [];
+    for (const file of templateFiles) {
+      const templatePath = path.join(templateDir, file);
+
+      let outputFileName = file;
+      if (processFileNames !== false) {
+        outputFileName = await renderTemplate(file, data);
+      }
+
+      const isTemplate = file.endsWith(templateSuffix);
+      if (outputFileName.endsWith(templateSuffix)) {
+        outputFileName = outputFileName.slice(0, -templateSuffix.length);
+      }
+
+      const outputPath = path.join(outputDir, outputFileName);
+      const result = isTemplate
+        ? await processTemplate(templatePath, outputPath, renderTemplate, {
+            data,
+            dryRun,
+            force,
+          })
+        : await copyStaticFile(templatePath, outputPath, { dryRun, force });
+      results.push(result);
+    }
+
+    return results;
+  } catch (error) {
+    spinner.fail(`Failed to process directory: ${error.message}`);
+    throw error;
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { Forge } from "./Forge.js";
+export { ForgeCLI } from "./cli/ForgeCLI.js";
+export { copyStaticFile } from "./fs/processTemplate.js";

package/src/utils/deepMerge.js

@@ -0,0 +1,23 @@
+/**
+ * Deep-merge plain objects (arrays replaced, not concatenated).
+ */
+export function deepMerge(target, source) {
+  const result = { ...target };
+
+  for (const [key, value] of Object.entries(source ?? {})) {
+    if (
+      value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof result[key] === "object" &&
+      result[key] &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(result[key], value);
+    } else if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

package/src/utils/resolvePaths.js

@@ -0,0 +1,27 @@
+import path from "path";
+
+/**
+ * Resolve forge paths from config relative to project root.
+ * @param {object} config
+ * @param {string} [configFileDir]
+ */
+export function resolveForgePaths(config, configFileDir) {
+  const root = config.root ?? configFileDir ?? process.cwd();
+
+  const resolve = (dir) => {
+    if (!dir) return root;
+    return path.isAbsolute(dir) ? dir : path.resolve(root, dir);
+  };
+
+  return {
+    root,
+    templatesDir: resolve(config.templatesDir ?? "./templates"),
+    outputDir: resolve(config.outputDir ?? "./src"),
+    localTemplatesDir: config.local?.templatesDir
+      ? resolve(config.local.templatesDir)
+      : resolve("./forge/templates"),
+    localGeneratorsDir: config.local?.generatorsDir
+      ? resolve(config.local.generatorsDir)
+      : resolve("./forge/generators"),
+  };
+}

package/src/utils/shouldSkip.js

@@ -0,0 +1,13 @@
+/**
+ * Evaluate action.skip / action.when predicate.
+ * @param {object} action
+ * @param {object} data
+ */
+export async function shouldSkip(action, data) {
+  const predicate = action.skip ?? action.when;
+  if (!predicate) return false;
+  if (typeof predicate === "function") {
+    return Boolean(await predicate(data));
+  }
+  return Boolean(predicate);
+}