hbs-magic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Kobtsev
+
+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

@@ -0,0 +1,386 @@
+#  hbs-magic
+
+A CLI tool designed to simplify source-code generation with [Handlebars](https://handlebarsjs.com/) templates as much as humanly possible.
+
+Point it at a folder with a `.hbs` template, give it some data — and it generates a fully formatted source file. That's it.
+
+## Installation
+
+```bash
+yarn add -D hbs-magic
+```
+Or
+```bash
+npm install -D hbs-magic
+```
+
+
+## Quick Start
+
+### 1. Create an input folder with a template and some data
+
+```
+my-gen/
+  template.hbs
+  input-data.json
+```
+
+**`input-data.json`**
+```json
+{
+  "greeting": "Hello",
+  "items": ["Apple", "Banana", "Cherry"]
+}
+```
+
+**`template.hbs`**
+```handlebars
+// {{greeting}}, World!
+
+{{#each items}}
+export const {{this}} = "{{this}}";
+{{/each}}
+```
+
+### 2. Run hbs-magic
+
+```bash
+hbs-magic --hbs=my-gen --output=result.gen.ts
+```
+
+### 3. Get a formatted output file ✅
+
+**`result.gen.ts`**
+```typescript
+// Hello, World!
+
+export const Apple = "Apple";
+export const Banana = "Banana";
+export const Cherry = "Cherry";
+```
+
+That's all it takes. No config files, no boilerplate — just a template and data.
+
+---
+
+## How It Works
+
+Everything lives inside a single **input folder** (the `--hbs` folder). Depending on your needs, it can contain:
+
+| File                         | Purpose                                                      |
+|------------------------------|--------------------------------------------------------------|
+| `template.hbs`               | The Handlebars template to render                            |
+| `input-data.json`            | Static JSON data for the template                            |
+| `preparation-script.ts`      | A script that programmatically builds the data object        |
+| `hbs-helpers.ts`             | Custom Handlebars helpers                                    |
+| `template_partial_*.hbs`     | Handlebars partials (named by the part after the second `_`) |
+
+> If multiple data sources are provided, priority is: `--input` flag → `preparation-script` → `input-data.json`.
+
+---
+
+## CLI Usage
+
+```
+hbs-magic --hbs=<folder> --output=<file> [--input=<json>] [--disable-formatting]
+```
+
+| Flag | Description |
+|---|---|
+| `--hbs` | **(required)** Path to the folder containing your template, data, helpers, etc. |
+| `--output` | **(required)** Path for the generated output file |
+| `--input` | Optional external JSON data source — a local file path **or a URL** |
+| `--disable-formatting` | Skip auto-formatting the output (Prettier for JS/TS, CSharpier for C#) |
+
+---
+
+## Data Input — Three Ways
+
+### Option A: Static JSON — `input-data.json`
+
+The simplest approach. Just drop a JSON file into the input folder:
+
+```
+my-gen/
+  template.hbs
+  input-data.json      ← hbs-magic picks this up automatically
+```
+
+### Option B: Preparation Script — `preparation-script.ts`
+
+Need to compute data dynamically? Export a default function that returns the data object:
+
+```
+my-gen/
+  template.hbs
+  preparation-script.ts
+```
+
+```typescript
+// preparation-script.ts
+export default async function () {
+  // Read files, call APIs, parse ASTs — whatever you need
+  return {
+    items: ["generated", "at", "build-time"],
+  };
+}
+```
+
+The function can be `async`. hbs-magic will bundle and execute it for you (TypeScript supported out of the box).
+
+### Option C: External JSON via `--input` flag
+
+Pass a local file or a remote URL:
+
+```bash
+# From a local file
+hbs-magic --hbs=my-gen --output=result.ts --input=./data.json
+
+# From an API endpoint
+hbs-magic --hbs=my-gen --output=result.ts --input=https://api.example.com/data.json
+```
+
+---
+
+## Custom Handlebars Helpers — `hbs-helpers.ts`
+
+Export a default object whose keys are helper names and values are helper functions:
+
+```
+my-gen/
+  template.hbs
+  input-data.json
+  hbs-helpers.ts       ← automatically registered
+```
+
+```typescript
+// hbs-helpers.ts
+function shout(text: string) {
+  return text.toUpperCase() + "!!!";
+}
+
+function isEven(index: number) {
+  return index % 2 === 0;
+}
+
+export default { shout, isEven };
+```
+
+Then use them in your template:
+
+```handlebars
+{{#each items}}
+  {{shout this}}
+{{/each}}
+```
+
+---
+
+## Handlebars Partials
+
+Any `.hbs` file in the input folder (other than `template.hbs`) is registered as a partial. The partial name is taken from the **third segment** of the filename, split by `_`:
+
+```
+template_partial_node.hbs  →  partial name: "node"
+template_partial_row.hbs   →  partial name: "row"
+```
+
+Use them in your template with `{{> node}}` or `{{> row}}`.
+
+Partials are great for recursive structures — like rendering a nested tree of routes (see the [Advanced Example](#3-advanced--c-url-helpers-with-partials-preparation-script-and-helpers) below).
+
+---
+
+## Auto-Formatting
+
+hbs-magic automatically formats the generated output file based on its extension:
+
+| Extension | Formatter |
+|---|---|
+| `.ts`, `.tsx`, `.js`, `.jsx` | [Prettier](https://prettier.io/) |
+| `.cs` | [CSharpier](https://csharpier.com/) |
+
+You can disable it with `--disable-formatting`.
+
+---
+
+## Examples
+
+### 1. Simple — Assets Helper (Preparation Script)
+
+> Scans a folder of audio files and generates a typed TypeScript module with imports, an enum, and a record.
+
+**Folder structure:**
+```
+examples/simple_assets-helper/
+  external-input/
+    dummy_audio_1.mp3
+    dummy_audio_2.mp3
+    dummy_audio_3.mp3
+  input/
+    preparation-script.ts
+    template.hbs
+```
+
+**Run:**
+```bash
+hbs-magic --hbs=examples/simple_assets-helper/input --output=examples/simple_assets-helper/Result.gen.ts
+```
+
+**Generated `Result.gen.ts`:**
+```typescript
+import dummy_audio_1SFX from "examples/simple_assets-helper/external-input/dummy_audio_1.mp3";
+import dummy_audio_2SFX from "examples/simple_assets-helper/external-input/dummy_audio_2.mp3";
+import dummy_audio_3SFX from "examples/simple_assets-helper/external-input/dummy_audio_3.mp3";
+
+export enum SoundEffect {
+  dummy_audio_1 = "dummy_audio_1",
+  dummy_audio_2 = "dummy_audio_2",
+  dummy_audio_3 = "dummy_audio_3",
+}
+
+export const SoundEffects: Record<SoundEffect, SoundSource> = {
+    [SoundEffect.dummy_audio_1]: {
+        src: dummy_audio_1SFX,
+        name: SoundEffect.dummy_audio_1,
+    },
+    [SoundEffect.dummy_audio_2]: {
+        src: dummy_audio_2SFX,
+        name: SoundEffect.dummy_audio_2,
+    },
+    [SoundEffect.dummy_audio_3]: {
+        src: dummy_audio_3SFX,
+        name: SoundEffect.dummy_audio_3,
+    },
+};
+```
+
+---
+
+### 2. From API — TypeScript API Client (Helpers + External JSON)
+
+> Fetches an OpenAPI spec from a URL and generates TypeScript functions for every endpoint.
+
+**Folder structure:**
+```
+examples/from-api_ts-api-client/
+  input/
+    template.hbs
+    hbs-helpers.ts
+```
+
+**Run** (note the `--input` pointing to a live API):
+```bash
+hbs-magic \
+  --input=https://petstore3.swagger.io/api/v3/openapi.json \
+  --hbs=examples/from-api_ts-api-client/input \
+  --output=examples/from-api_ts-api-client/Result.gen.ts
+```
+
+**Generated `Result.gen.ts`** (excerpt):
+```typescript
+export async function findPetsByStatus(status: string) {
+  console.log("Calling get /pet/findByStatus");
+}
+
+export async function getPetById(petId: number) {
+  console.log("Calling get /pet/{petId}");
+}
+
+export async function loginUser(username: string, password: string) {
+  console.log("Calling get /user/login");
+}
+// ... and every other endpoint from the Swagger Petstore
+```
+
+---
+
+### 3. Advanced — C# URL Helpers with Partials, Preparation Script, and Helpers
+
+> Parses a TypeScript route definition file (using `ts-morph`), extracts route/param info, and generates a full C# helper class with nested static classes, query parameter models, and link-builder methods — using **partials** for recursive rendering.
+
+**Folder structure:**
+```
+examples/advanced_csharp-url-helpers/
+  external-input/
+    links.ts                          ← source routes file (react-router-url-params)
+  input/
+    preparation-script.ts             ← parses links.ts via ts-morph AST
+    hbs-helpers.ts                    ← TS→C# type converters
+    template.hbs                      ← main template
+    template_partial_node.hbs         ← recursive partial for nested route groups
+    input-data.json                   ← generated intermediate JSON (by prep script)
+```
+
+**Run:**
+```bash
+hbs-magic \
+  --hbs=examples/advanced_csharp-url-helpers/input \
+  --output=examples/advanced_csharp-url-helpers/Result.gen.cs
+```
+
+**Generated `Result.gen.cs`** (excerpt):
+```csharp
+public static class Routes
+{
+    public static class Unauthorized
+    {
+        public static class Login
+        {
+            public static string Link(string siteUrl, LoginQueryParams queryParams) =>
+                siteUrl + "/login" + "?" + queryParams.GetQueryString();
+        }
+
+        public static class ConfirmEmail
+        {
+            public static string Link(string siteUrl, string userId, string token) =>
+                siteUrl + "/confirm-email/:userId/:token"
+                    .Replace(":userId", userId.ToString())
+                    .Replace(":token", token.ToString());
+        }
+    }
+
+    public static class Authorized
+    {
+        // ... deeply nested route groups with full C# link builders
+    }
+}
+
+public class LoginQueryParams : IRouteQueryParams
+{
+    public string? Redirect { get; init; }
+
+    public string GetQueryString()
+    {
+        var queryParams = new List<string>();
+        if (!string.IsNullOrEmpty(Redirect))
+            queryParams.Add($"redirect={Redirect}");
+        return string.Join("&", queryParams);
+    }
+}
+```
+
+---
+
+## Adding to `package.json` scripts
+
+A convenient pattern is to add generation commands as npm scripts:
+
+```json
+{
+  "scripts": {
+    "gen:assets": "hbs-magic --hbs=src/gen/assets/input --output=src/generated/assets.gen.ts",
+    "gen:api":    "hbs-magic --input=https://api.example.com/openapi.json --hbs=src/gen/api/input --output=src/generated/api-client.gen.ts",
+    "gen:all":    "npm run gen:assets && npm run gen:api"
+  }
+}
+```
+
+Then simply run `npm run gen:all` to regenerate everything.
+
+---
+
+## License
+
+[MIT](LICENSE) © Ivan Kobtsev
+

package/bin/cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import {
+  getHbsHelpersAndTemplatePaths,
+  getInputDataPath,
+  runPreparationScript,
+} from "../src/file-helpers.js";
+import { formatSourceFile } from "../src/formatting-helpers.js";
+import {
+  compileHbsTemplateAndWriteToFile,
+  registerHbsHelpersFromFile,
+  registerHbsPartials,
+} from "../src/hbs-process-helpers.js";
+import {
+  extractArgument,
+  extractArguments,
+  extractFlag,
+  getInputObject,
+} from "../src/process-helpers.js";
+
+const args = extractArguments(process, ["hbs", "output"]);
+const hbsFolder = args.hbs as string;
+const outputFile = args.output as string;
+const formatOutput = !extractFlag(process, "disable-formatting");
+const externalJson = extractArgument(process, "input");
+
+async function main() {
+  const { preparationScriptPath, hbsHelpersPath, hbsPartials, templatePath } =
+    getHbsHelpersAndTemplatePaths(hbsFolder);
+
+  const inputObject = await getInputObject(
+    externalJson,
+    await runPreparationScript(preparationScriptPath),
+    getInputDataPath(hbsFolder),
+  );
+
+  if (hbsHelpersPath) await registerHbsHelpersFromFile(hbsHelpersPath);
+
+  if (hbsPartials.length > 0) await registerHbsPartials(hbsPartials);
+
+  await compileHbsTemplateAndWriteToFile(templatePath, inputObject, outputFile);
+
+  if (formatOutput) await formatSourceFile(outputFile);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/bin/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { getHbsHelpersAndTemplatePaths, getInputDataPath, runPreparationScript, } from "../src/file-helpers.js";
+import { formatSourceFile } from "../src/formatting-helpers.js";
+import { compileHbsTemplateAndWriteToFile, registerHbsHelpersFromFile, registerHbsPartials, } from "../src/hbs-process-helpers.js";
+import { extractArgument, extractArguments, extractFlag, getInputObject, } from "../src/process-helpers.js";
+const args = extractArguments(process, ["hbs", "output"]);
+const hbsFolder = args.hbs;
+const outputFile = args.output;
+const formatOutput = !extractFlag(process, "disable-formatting");
+const externalJson = extractArgument(process, "input");
+async function main() {
+    const { preparationScriptPath, hbsHelpersPath, hbsPartials, templatePath } = getHbsHelpersAndTemplatePaths(hbsFolder);
+    const inputObject = await getInputObject(externalJson, await runPreparationScript(preparationScriptPath), getInputDataPath(hbsFolder));
+    if (hbsHelpersPath)
+        await registerHbsHelpersFromFile(hbsHelpersPath);
+    if (hbsPartials.length > 0)
+        await registerHbsPartials(hbsPartials);
+    await compileHbsTemplateAndWriteToFile(templatePath, inputObject, outputFile);
+    if (formatOutput)
+        await formatSourceFile(outputFile);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/src/cli-messages.js

@@ -0,0 +1,84 @@
+export const inputDataNotFound = `No input data found.
+
+Please provide data using one of the following options:
+
+1. Use the "--input" flag with a path or URL to a JSON file
+   Example: hbs-magic --input=./data.json
+
+2. Add a preparation script:
+   - File name: preparation-script.ts or preparation-script.js
+   - Must export a default function that returns the data object
+   - Place it inside your .hbs template folder
+
+3. Add a default JSON file:
+   - File name: input-data.json
+   - Place it inside your .hbs template folder
+
+Need help? Run: hbs-magic --help`;
+export const multipleSourcesDetected = `Warning: Multiple input sources detected.
+
+hbs-magic will use only one source based on the following priority:
+
+1. --input flag
+2. preparation-script.ts/js
+3. input-data.json
+
+The highest-priority source will be used. All others will be ignored.
+
+Tip: Remove unused inputs to make your setup clearer.`;
+export const positionalArgumentsNotAllowed = `No positional arguments allowed. Use '--key=value' format.`;
+export const hbsMagicCliUsage = `Usage: [--input=<json>] --hbs=<folder> --output=<file> [--disable-formatting]
+    --input: Optional JSON input file path. If not provided, the script will look for "input-data.json" in the specified hbs folder.
+    --hbs: Required folder containing the Handlebars template, optional helpers, partials, and preparation script.
+    --output: Required output file path where the generated source code will be written.
+    --disable-formatting: Optional flag to disable auto-formatting of the output file after generation.`;
+export const hbsMagicHelp = `hbs-magic — source-code generation with Handlebars templates
+
+Usage:
+  hbs-magic --hbs=<folder> --output=<file> [--input=<json>] [--disable-formatting]
+
+Required flags:
+  --hbs=<folder>        Folder containing your Handlebars template and optional
+                        helpers, partials, and preparation script.
+  --output=<file>       Path where the generated file will be written.
+
+Optional flags:
+  --input=<json>        External JSON data source — a local file path or a URL.
+  --disable-formatting  Skip auto-formatting of the generated output.
+  --help                Show this help message.
+
+Input folder structure:
+  The --hbs folder can contain any combination of these files:
+
+  template.hbs              (required)  The Handlebars template to render.
+  input-data.json           (optional)  Static JSON data for the template.
+  preparation-script.ts     (optional)  Script exporting a default function
+                                        that returns the data object.
+  hbs-helpers.ts            (optional)  Custom Handlebars helpers. Must export
+                                        a default object: { helperName: fn }.
+  template_partial_*.hbs    (optional)  Partials, named by the part after the
+                                        second "_" (e.g. template_partial_row.hbs
+                                        registers a partial called "row").
+
+Data source priority:
+  If multiple sources are provided, only one is used:
+    1. --input flag          (highest)
+    2. preparation-script
+    3. input-data.json       (lowest)
+
+Auto-formatting:
+  Output files are automatically formatted based on extension:
+    .ts .tsx .js .jsx  →  Prettier
+    .cs                →  CSharpier
+
+Examples:
+  # Simple: static JSON + template
+  hbs-magic --hbs=gen/input --output=src/result.gen.ts
+
+  # From a remote API
+  hbs-magic --input=https://api.example.com/openapi.json --hbs=gen/input --output=src/client.gen.ts
+
+  # With formatting disabled
+  hbs-magic --hbs=gen/input --output=src/result.gen.ts --disable-formatting
+
+Documentation: https://github.com/IvanKobtsev/hbs-magic#readme`;

package/dist/src/file-helpers.js

@@ -0,0 +1,94 @@
+import fs from "fs";
+import fetch from "node-fetch";
+import https from "https";
+import path from "path";
+import { pathToFileURL } from "url";
+import { build } from "esbuild";
+const agent = new https.Agent({ rejectUnauthorized: false });
+export async function getJson(source) {
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        let response;
+        try {
+            response = await fetch(source, { agent });
+        }
+        catch (err) {
+            throw new Error(`Failed to fetch JSON from URL: ${err}`);
+        }
+        if (!response.ok)
+            throw new Error(`HTTP error: ${response.status}`);
+        return await response.json();
+    }
+    else {
+        return JSON.parse(fs.readFileSync(source, "utf8"));
+    }
+}
+export async function getDefaultExport(source) {
+    if (source.endsWith(".ts")) {
+        const tempFile = source.replace(/\.ts$/, ".temp.js");
+        await build({
+            entryPoints: [source],
+            outfile: tempFile,
+            bundle: true,
+            platform: "node",
+            format: "esm",
+            packages: "external",
+            banner: {
+                js: 'import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);',
+            },
+        });
+        const defaultExport = (await import(pathToFileURL(tempFile).href)).default;
+        fs.unlinkSync(tempFile);
+        return defaultExport;
+    }
+    else {
+        return (await import(pathToFileURL(source).href)).default;
+    }
+}
+export async function runPreparationScript(fullPath) {
+    if (!fullPath)
+        return undefined;
+    const preparationScript = await getDefaultExport(fullPath);
+    if (typeof preparationScript === "function")
+        return await preparationScript();
+    else
+        throw new Error(`Failed to run preparation script: ${fullPath}. Default export is not a function.`);
+}
+export function getAllHbsPartialsInFolder(folder) {
+    const partials = [];
+    const files = fs.readdirSync(folder);
+    for (const file of files) {
+        if (file.endsWith(".hbs")) {
+            const partialFullName = path.basename(file, ".hbs");
+            if (partialFullName === "template")
+                continue; // skip main template file
+            const partialName = partialFullName.split("_")[2];
+            const partialPath = path.join(folder, file);
+            partials.push({
+                name: partialName,
+                content: fs.readFileSync(partialPath, "utf8"),
+            });
+        }
+    }
+    return partials;
+}
+export function getInputDataPath(hbsFolder) {
+    const inputPath = path.join(hbsFolder, "input-data.json");
+    return fs.existsSync(inputPath) ? inputPath : undefined;
+}
+export function getHbsHelpersAndTemplatePaths(hbsFolder) {
+    const preparationScriptPath = path.join(hbsFolder, "preparation-script.ts");
+    const helpersPath = path.join(hbsFolder, "hbs-helpers.ts");
+    const templatePath = path.join(hbsFolder, "template.hbs");
+    const partials = getAllHbsPartialsInFolder(hbsFolder);
+    if (!fs.existsSync(templatePath)) {
+        throw new Error(`Template file not found: ${templatePath}`);
+    }
+    return {
+        preparationScriptPath: fs.existsSync(preparationScriptPath)
+            ? preparationScriptPath
+            : undefined,
+        hbsHelpersPath: fs.existsSync(helpersPath) ? helpersPath : undefined,
+        templatePath: templatePath,
+        hbsPartials: partials,
+    };
+}