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

package/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2020-2026 Yevhenii Kyrychok
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,234 @@
-# Temporary Holding Version
+# @effijs/forge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Forge is a Node.js **ESM scaffolding engine** for EffiJS projects — a modern alternative to [Plop.js](https://plopjs.com/). It runs generators and templates; it does **not** ship them. Templates and extended presets live in [`@effijs/templates`](../templates); project-specific generators live in `./forge/`.
+
+## Documentation
+
+Full documentation lives in [`docs/`](./docs) and is built with VitePress:
+
+```bash
+npm run docs:dev
+```
+
+| Section | Contents |
+| ------- | -------- |
+| [Guide](./docs/guide/index.md) | [Getting Started](./docs/guide/getting-started.md), [Core Concepts](./docs/guide/core-concepts.md), [Coming from Plop.js](./docs/guide/vs-plop.md) |
+| [CLI](./docs/cli/index.md) | [`init`](./docs/cli/init.md), [`list`](./docs/cli/list.md), [`generate`](./docs/cli/generate.md), [`new local`](./docs/cli/new-local.md) |
+| [Core API](./docs/core/index.md) | [`Forge`](./docs/core/forge.md), [`ForgeCLI`](./docs/core/forge-cli.md), [Configuration](./docs/core/configuration.md), [Generators](./docs/core/generators.md), [Actions](./docs/core/actions.md), [Presets](./docs/core/presets.md), [Template Engines](./docs/core/template-engines.md) |
+| [Examples](./docs/examples/index.md) | [React Native FSD](./docs/examples/react-native-fsd.md), [Local Generator](./docs/examples/local-generator.md), [Custom Actions](./docs/examples/custom-actions.md), [Multi-Preset Monorepo](./docs/examples/monorepo-multi-preset.md) |
+
+The rest of this file is a condensed quick reference.
+
+## Install
+
+```bash
+npm install @effijs/forge @effijs/templates
+```
+
+Requires Node.js **≥ 18**.
+
+## Quick start
+
+```bash
+forge init
+forge list
+forge g rn-fsd:component
+forge g comp                    # via alias
+```
+
+## Forge vs Plop.js
+
+Both tools follow the same mental model: **prompts → actions → files**. Forge keeps Plop-compatible action shapes (`add`, `addMany`, `modify`, `append`, `custom`, `skip`) but changes how configuration, templates, and CLI resolution work.
+
+| Topic | Plop.js | Forge |
+| ----- | ------- | ----- |
+| **Role** | All-in-one: CLI + generators in one `plopfile` | Engine only; templates in packages or `./forge/` |
+| **Module system** | Historically CJS (`plopfile.js`); ESM in newer versions | Native ESM (`type: "module"`) |
+| **Config** | Single `plopfile.js` | Layered merge: defaults → presets → `forge.config.js` |
+| **Generator IDs** | Flat names (`component`) | Namespaced (`rn-fsd:component`, `local:billing-service`) |
+| **Multiple stacks** | One plopfile per project or manual wiring | Multiple presets in one config (`presets`, `presetMap`) |
+| **Templates location** | Next to plopfile, often `plop-templates/` | Preset package (`@effijs/templates`) + `./forge/templates/` |
+| **Template engines** | Handlebars (default) | Handlebars (default) or **Eta** (`templateEngine: "eta"`) |
+| **Case helpers** | Add via `setHelper` / `helper-case` | Built-in (`camelCase`, `pascalCase`, `kebabCase`, …) |
+| **CLI** | `plop <generator>` | `forge init`, `forge list`, `forge g <id>`, `forge new local` |
+| **Local generator scaffold** | Manual | `forge new local <name> --type=service\|api\|component` |
+| **Dry run / force** | Via API / custom | `--dry-run`, `--force`, `--yes` on CLI and `Forge.run()` |
+| **Per-generator output** | Usually in generator actions | `overrides` in config (e.g. custom `outputDir`) |
+| **Ambiguity** | Duplicate names = runtime confusion | Explicit error with suggestions when bare name matches several presets |
+
+**When to use Forge:** monorepos or products that share generators across apps (React Native FSD + NestJS in one repo), versioned template packages, and EffiJS preset conventions.
+
+**When Plop is enough:** a single app with a handful of local generators and no shared preset layer.
+
+### Generator shape (Plop-compatible)
+
+```js
+export default {
+  description: "Optional description for forge list",
+  prompts: [/* inquirer questions */],
+  actions: [
+    { type: "add", path: "...", templateFile: "..." },
+    { type: "addMany", templateFiles: "feature", destination: "{{name}}" },
+    { type: "modify", path: "...", pattern: "...", template: "..." },
+    { type: "append", path: "...", pattern: "...", template: "..." },
+    { type: "custom", action: async (data, forge) => { /* ... */ } },
+    { type: "add", path: "...", template: "...", skip: (data) => !data.flag },
+  ],
+};
+```
+
+Generators are discovered as `**/generator.js` under each template root, or registered in a preset’s `generators` map.
+
+## Configuration (layered)
+
+Config merges in order: **base defaults → extended presets → local project config**.
+
+Supported config files (first match wins): `forge.config.js`, `forge.config.mjs`, `.forgerc.js`, `.forgerc.json`.
+
+```js
+// forge.config.js
+export default {
+  presets: ["rn-fsd", "nest"],
+  presetMap: {
+    "rn-fsd": "@effijs/templates/presets/react-native-fsd",
+    nest: "@effijs/templates/presets/nestjs-fsd",
+  },
+  primaryPreset: "rn-fsd",
+  outputDir: "./src",
+  templateEngine: "handlebars", // or "eta"
+  local: {
+    templatesDir: "./forge/templates",
+    generatorsDir: "./forge/generators",
+  },
+  generators: ["rn-fsd:component", "nest:controller", "local:billing-service"],
+  aliases: {
+    comp: "rn-fsd:component",
+    ctrl: "nest:controller",
+  },
+  overrides: {
+    "local:billing-service": { outputDir: "./src/billing" },
+  },
+  helpers: {
+    // custom Handlebars helpers when templateEngine is "handlebars"
+  },
+};
+```
+
+### Generator resolution
+
+For `forge g <input>`:
+
+1. Resolve `aliases[input]` (recursive)
+2. If input contains `:`, match catalog (`preset:action`)
+3. Bare `action` when exactly one preset defines it (e.g. `component` → `rn-fsd:component` if unambiguous)
+4. Fall back to `primaryPreset:action`
+5. Fall back to `local:action`
+6. On ambiguity, fail with a list of matching IDs
+
+Examples:
+
+```bash
+forge g comp              # alias → rn-fsd:component
+forge g rn-fsd:component  # explicit namespace
+forge g component         # bare name if only one match (or primaryPreset)
+forge g local:my-service  # project-local generator
+```
+
+## CLI
+
+| Command | Description |
+| ------- | ----------- |
+| `forge init` | Create `forge.config.js` and `./forge/` directories |
+| `forge list` (`ls`) | List generators grouped by namespace + aliases |
+| `forge g <id>` (`generate`) | Run a generator |
+| `forge new local <name>` | Scaffold a local generator and templates |
+
+### Flags (`forge g`)
+
+| Flag | Description |
+| ---- | ----------- |
+| `--dry-run` | Preview paths without writing files |
+| `--force` | Overwrite existing files |
+| `--yes` | Skip prompts and apply each prompt's `default`. Flags override defaults |
+| `--name <name>` | Pass prompt value directly |
+| `--path <path>` | Pass path prompt directly |
+| `--<promptName> <value>` | Any other flag maps to prompt data (unknown options allowed) |
+
+```bash
+forge g rn-fsd:component --yes --name Button
+forge g feature --yes --name Note --screens list,detail --tab
+forge g rn-fsd:component --dry-run --name Button --includeStyles=false
+```
+
+## Action types
+
+| Type | Fields | Behavior |
+| ---- | ------ | -------- |
+| `add` | `path`, `templateFile` or `template` | Create a single file |
+| `addMany` | `templateFiles`, `destination?`, `options?` | Render `.hbs` or `.eta` files; copy every other file as bytes |
+| `modify` | `path`, `transform` or `pattern` + `template` | Transform existing file content |
+| `append` | `path`, `template`, `pattern?`, `unique?`, `options?` | Insert at a marker. A missing marker fails. `unique` skips a fragment already in the file |
+| `custom` | `action(data, forge)` | Arbitrary async logic |
+
+All actions support `skip` or `when`: `(data) => boolean`.
+
+Paths and templates are resolved relative to the generator’s preset root or `./forge/templates`. Template file names in `addMany` can contain Handlebars/Eta expressions when `processFileNames` is enabled.
+
+## Local generators
+
+```bash
+forge new local billing-service --type=service
+forge g local:billing-service
+```
+
+Creates:
+
+```
+forge/
+  generators/billing-service/generator.js
+  templates/billing-service/*.hbs
+```
+
+Variants: `--type=service` | `api` | `component`. Use `--no-register` to skip auto-entry in `forge.config.js`, `--force` to overwrite.
+
+> **Known limitation:** `forge list` discovers local generators, but `forge g local:<name>` currently fails to resolve them — `resolveGeneratorId` reads only the preset catalog, and the local template root contributes no catalog entries. Expose project generators through a small in-repo preset until this is fixed; see [Presets → local preset workaround](./docs/core/presets.md#local-preset-workaround).
+
+## Programmatic API
+
+```js
+import { Forge } from "@effijs/forge";
+
+const forge = await Forge.create(process.cwd());
+
+const result = await forge.run("rn-fsd:component", {
+  yes: true,
+  name: "Button",
+  dryRun: false,
+  force: false,
+});
+
+if (result.success) {
+  console.log(result.generatorId, result.results);
+}
+```
+
+`Forge` also exposes `renderTemplate`, `addFile`, `modifyFile`, `processTemplate`, and `processDirectory` for custom actions.
+
+## Architecture
+
+```
+src/
+  Forge.js           # orchestration, prompts, run()
+  cli/ForgeCLI.js    # commander CLI
+  cli/scaffoldLocal.js
+  config/            # load, merge, resolve generators & presets
+  engines/           # handlebars + eta
+  actions/           # action registry
+  fs/                # add, modify, process templates
+  utils/             # paths, skip, deepMerge
+```
+
+## Related packages
+
+- [`@effijs/templates`](../templates) — extended presets (`react-native-fsd`, …) and shared generators
+- Example generator: `generators/shared/component` (component with optional styles, tests, barrel append)

package/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "url";
+import { ForgeCLI } from "./src/index.js";
+
+const cli = new ForgeCLI();
+await cli.init();
+cli.run(process.argv);

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@effijs/forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-alpha.1",
+  "type": "module",
+  "description": "Modern scaffolding engine for EffiJS",
+  "author": "Yevhenii Kyrychok",
+  "license": "MIT",
+  "main": "src/index.js",
+  "bin": {
+    "forge": "./index.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "forge",
+    "scaffolding",
+    "generator",
+    "effijs",
+    "cli"
+  ],
+  "files": [
+    "index.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "forge": "node index.js",
+    "test": "node --test test/*.test.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "change-case": "^5.4.4",
+    "commander": "^11.1.0",
+    "eta": "^3.5.0",
+    "handlebars": "^4.7.10",
+    "inquirer": "^9.3.8",
+    "ora": "^8.2.0",
+    "tinyglobby": "^0.2.17"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/Forge.js

@@ -0,0 +1,187 @@
+import path from "path";
+import inquirer from "inquirer";
+import chalk from "chalk";
+import { compileHandlebars, registerHandlebarsHelpers } from "./engines/handlebars.js";
+import { createEtaEngine, renderEtaString } from "./engines/eta.js";
+import { mergeConfig } from "./config/mergeConfig.js";
+import {
+  resolveGeneratorId,
+  loadGenerator,
+} from "./config/resolveGenerator.js";
+import { runActions } from "./actions/index.js";
+import { addFile } from "./fs/addFile.js";
+import { modifyFile, appendToFile } from "./fs/modifyFile.js";
+import { processTemplate, processDirectory } from "./fs/processTemplate.js";
+
+async function applyPromptDefaults(questions, options) {
+  const answers = {};
+  const list = Array.isArray(questions) ? questions : [];
+
+  for (const question of list) {
+    if (!question?.name) continue;
+    if (options[question.name] !== undefined) continue;
+
+    const context = { ...answers, ...options };
+    let active = question.when;
+    if (typeof active === "function") active = await active(context);
+    if (active === false) continue;
+    if (question.default === undefined) continue;
+
+    answers[question.name] =
+      typeof question.default === "function"
+        ? await question.default(context)
+        : question.default;
+  }
+
+  return answers;
+}
+
+export class Forge {
+  constructor(config = {}) {
+    this.config = config;
+    this.paths = config.paths ?? {};
+    this.generators = new Map();
+
+    if (this.config.templateEngine === "eta") {
+      this.eta = createEtaEngine(this.paths.templatesDir);
+    } else {
+      registerHandlebarsHelpers(this.config.helpers ?? {});
+    }
+  }
+
+  static async create(cwd = process.cwd()) {
+    const config = await mergeConfig(cwd);
+    return new Forge(config);
+  }
+
+  async prompt(questions) {
+    return inquirer.prompt(questions);
+  }
+
+  async renderTemplate(templateContent, data) {
+    if (this.config.templateEngine === "eta") {
+      return renderEtaString(this.eta, templateContent, data);
+    }
+    return compileHandlebars(templateContent, data);
+  }
+
+  async addFile(filePath, content, options = {}) {
+    return addFile(filePath, content, {
+      dryRun: options.dryRun ?? this.runOptions?.dryRun,
+      force: options.force ?? this.runOptions?.force,
+    });
+  }
+
+  async modifyFile(filePath, modifier, options = {}) {
+    return modifyFile(filePath, modifier, {
+      dryRun: options.dryRun ?? this.runOptions?.dryRun,
+      force: options.force ?? this.runOptions?.force,
+    });
+  }
+
+  async appendToFile(filePath, content, appendOptions = {}, runOptions = {}) {
+    return appendToFile(filePath, content, appendOptions, {
+      dryRun: runOptions.dryRun ?? this.runOptions?.dryRun,
+      force: runOptions.force ?? this.runOptions?.force,
+    });
+  }
+
+  async processTemplate(templatePath, outputPath, data) {
+    return processTemplate(
+      templatePath,
+      outputPath,
+      (content, d) => this.renderTemplate(content, d),
+      {
+        data,
+        dryRun: this.runOptions?.dryRun,
+        force: this.runOptions?.force,
+      },
+    );
+  }
+
+  async processDirectory(templateDir, outputDir, data, options = {}) {
+    return processDirectory(
+      templateDir,
+      outputDir,
+      (content, d) => this.renderTemplate(content, d),
+      data,
+      {
+        ...options,
+        templateSuffix:
+          options.templateSuffix ??
+          (this.config.templateEngine === "eta" ? ".eta" : ".hbs"),
+        dryRun: this.runOptions?.dryRun,
+        force: this.runOptions?.force,
+      },
+    );
+  }
+
+  resolveOutputDir(generatorId) {
+    const override = this.config.overrides?.[generatorId];
+    if (override?.outputDir) {
+      const root = this.paths.root;
+      return path.isAbsolute(override.outputDir)
+        ? override.outputDir
+        : path.resolve(root, override.outputDir);
+    }
+    return this.paths.outputDir;
+  }
+
+  async run(generatorInput, options = {}) {
+    this.runOptions = options;
+    const { dryRun = false, force = false, yes = false } = options;
+
+    const generatorId = resolveGeneratorId(generatorInput, this.config);
+    console.log(
+      chalk.bold.cyan(`\n🔨 Running ${generatorId} generator\n`),
+    );
+
+    try {
+      const generator = await loadGenerator(generatorId, this.config);
+
+      let answers = {};
+      if (generator.prompts) {
+        const questions =
+          typeof generator.prompts === "function"
+            ? await generator.prompts(this)
+            : generator.prompts;
+        answers = yes
+          ? await applyPromptDefaults(questions, options)
+          : await this.prompt(questions);
+      }
+
+      const data = { ...answers, ...options };
+      const outputDir = this.resolveOutputDir(generatorId);
+
+      const ctx = {
+        forge: this,
+        generator,
+        data,
+        outputDir,
+        dryRun,
+        force,
+        abortOnError: options.abortOnError ?? true,
+      };
+
+      const { results, hasFailure } = await runActions(generator, ctx);
+
+      if (hasFailure) {
+        console.error(
+          chalk.red("\n❌ Generation failed — one or more actions failed\n"),
+        );
+        return { success: false, results };
+      }
+
+      if (dryRun) {
+        console.log(chalk.bold.yellow("\n✨ Dry run complete (no files written)\n"));
+      } else {
+        console.log(chalk.bold.green("\n✨ Generation complete!\n"));
+      }
+
+      return { success: true, results, generatorId };
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Generation failed: ${error.message}\n`));
+      return { success: false, error: error.message };
+    }
+  }
+}

package/src/actions/index.js

@@ -0,0 +1,175 @@
+import path from "path";
+import { shouldSkip } from "../utils/shouldSkip.js";
+import { processTemplate, processDirectory } from "../fs/processTemplate.js";
+import { addFile } from "../fs/addFile.js";
+import { modifyFile, appendToFile } from "../fs/modifyFile.js";
+
+async function resolveTemplatePath(ctx, templateFile) {
+  const root = ctx.generator._root;
+  const templatesDir = root?.templatesDir ?? ctx.forge.paths.templatesDir;
+
+  if (path.isAbsolute(templateFile)) return templateFile;
+
+  const candidates = [
+    path.join(templatesDir, templateFile),
+    path.join(path.dirname(ctx.generator._generatorPath), templateFile),
+    path.join(templatesDir, path.basename(templateFile)),
+  ];
+
+  const fs = await import("fs/promises");
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // try next
+    }
+  }
+
+  return candidates[0];
+}
+
+async function runAddAction(action, ctx) {
+  const outputPath = path.join(
+    ctx.outputDir,
+    await ctx.forge.renderTemplate(action.path, ctx.data),
+  );
+
+  if (action.templateFile) {
+    const templatePath = await resolveTemplatePath(ctx, action.templateFile);
+    return processTemplate(
+      templatePath,
+      outputPath,
+      (content, data) => ctx.forge.renderTemplate(content, data),
+      { data: ctx.data, dryRun: ctx.dryRun, force: ctx.force },
+    );
+  }
+
+  if (action.template) {
+    const content = await ctx.forge.renderTemplate(action.template, ctx.data);
+    return addFile(outputPath, content, {
+      dryRun: ctx.dryRun,
+      force: ctx.force,
+    });
+  }
+}
+
+async function runAddManyAction(action, ctx) {
+  const root = ctx.generator._root;
+  const templatesDir = root?.templatesDir ?? ctx.forge.paths.templatesDir;
+  const templateDir = path.join(templatesDir, action.templateFiles);
+  const outputDir = path.join(
+    ctx.outputDir,
+    action.destination
+      ? await ctx.forge.renderTemplate(action.destination, ctx.data)
+      : "",
+  );
+
+  const templateSuffix =
+    ctx.forge.config.templateEngine === "eta" ? ".eta" : ".hbs";
+
+  const results = await processDirectory(
+    templateDir,
+    outputDir,
+    (content, data) => ctx.forge.renderTemplate(content, data),
+    ctx.data,
+    {
+      ...action.options,
+      dryRun: ctx.dryRun,
+      force: ctx.force,
+      templateSuffix,
+    },
+  );
+
+  const failed = results.filter((r) => r && !r.success);
+  if (failed.length) {
+    return { success: false, results, error: `${failed.length} file(s) failed` };
+  }
+
+  return { success: true, results };
+}
+
+async function runModifyAction(action, ctx) {
+  const targetPath = path.join(
+    ctx.outputDir,
+    await ctx.forge.renderTemplate(action.path, ctx.data),
+  );
+
+  return modifyFile(
+    targetPath,
+    async (content) => {
+      if (action.transform) {
+        return action.transform(content, ctx.data);
+      }
+      if (action.pattern && action.template) {
+        const rendered = await ctx.forge.renderTemplate(
+          action.template,
+          ctx.data,
+        );
+        return content.replace(
+          new RegExp(action.pattern, action.flags || "g"),
+          rendered,
+        );
+      }
+      return content;
+    },
+    { dryRun: ctx.dryRun, force: ctx.force },
+  );
+}
+
+async function runAppendAction(action, ctx) {
+  const appendPath = path.join(
+    ctx.outputDir,
+    await ctx.forge.renderTemplate(action.path, ctx.data),
+  );
+  const appendContent = await ctx.forge.renderTemplate(
+    action.template || "",
+    ctx.data,
+  );
+
+  return appendToFile(appendPath, appendContent, action, {
+    dryRun: ctx.dryRun,
+    force: ctx.force,
+  });
+}
+
+async function runCustomAction(action, ctx) {
+  if (action.action) {
+    return action.action(ctx.data, ctx.forge);
+  }
+}
+
+export const actionHandlers = new Map([
+  ["add", runAddAction],
+  ["addMany", runAddManyAction],
+  ["modify", runModifyAction],
+  ["append", runAppendAction],
+  ["custom", runCustomAction],
+]);
+
+export async function runActions(generator, ctx) {
+  const results = [];
+  let hasFailure = false;
+
+  for (const action of generator.actions ?? []) {
+    if (await shouldSkip(action, ctx.data)) {
+      continue;
+    }
+
+    const handler = actionHandlers.get(action.type);
+    if (!handler) {
+      throw new Error(`Unknown action type: ${action.type}`);
+    }
+
+    const result = await handler(action, ctx);
+    if (result) {
+      results.push(result);
+      if (result.success === false) {
+        hasFailure = true;
+        if (ctx.abortOnError !== false) break;
+      }
+    }
+  }
+
+  return { results, hasFailure };
+}