simple-scaffold 3.0.0 → 3.1.1

package/README.md

@@ -28,181 +28,292 @@ of files you're generating.
 
 ---
 
-## Documentation
-
-See full documentation [here](https://chenasraf.github.io/simple-scaffold).
-
-- [Command Line Interface (CLI) usage](https://chenasraf.github.io/simple-scaffold/docs/usage/cli)
-- [Node.js usage](https://chenasraf.github.io/simple-scaffold/docs/usage/node)
-- [Templates](https://chenasraf.github.io/simple-scaffold/docs/usage/templates)
-- [Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files)
-- [Migration](https://chenasraf.github.io/simple-scaffold/docs/usage/migration)
+> **Full documentation is available at
+> [chenasraf.github.io/simple-scaffold](https://chenasraf.github.io/simple-scaffold)** — including
+> detailed guides on [CLI usage](https://chenasraf.github.io/simple-scaffold/docs/usage/cli),
+> [Node.js API](https://chenasraf.github.io/simple-scaffold/docs/usage/node),
+> [templates](https://chenasraf.github.io/simple-scaffold/docs/usage/templates),
+> [configuration files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files),
+> [examples](https://chenasraf.github.io/simple-scaffold/docs/usage/examples), and
+> [migration from v1/v2](https://chenasraf.github.io/simple-scaffold/docs/usage/migration).
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Configuration Files](#configuration-files)
+- [Templates](#templates)
+- [Interactive Mode & Inputs](#interactive-mode--inputs)
+- [Remote Templates](#remote-templates)
+- [CLI Reference](#cli-reference)
+- [Node.js API](#nodejs-api)
+- [Built-in Helpers](#built-in-helpers)
+- [Contributing](#contributing)
 
 ## Getting Started
 
-### Cheat Sheet
-
-A quick rundown of common usage scenarios:
-
-- Remote template config file on GitHub:
+### Install
 
-  ```sh
-  npx simple-scaffold -g username/repository -c scaffold.js -k component NewComponentName
-  ```
-
-- Local template config file:
-
-  ```sh
-  npx simple-scaffold -c scaffold.js -k component NewComponentName
-  ```
+```sh
+npm install -D simple-scaffold
+# or use directly with npx
+npx simple-scaffold
+```
 
-- Local one-time usage:
+### Initialize a Project
 
-  ```sh
-  npx simple-scaffold -t templates/component -o src/components NewComponentName
-  ```
+Run `init` to create a config file and an example template:
 
-### Remote Configurations
+```sh
+npx simple-scaffold init
+```
 
-The fastest way to get started is to is to re-use someone else's (or your own) work using a template
-repository.
+This creates `scaffold.config.js` and `templates/default/{{name}}.md`. Now generate files:
 
-A remote config can be loaded in one of these ways:
+```sh
+npx simple-scaffold MyProject
+```
 
-- For templates hosted on GitHub, the syntax is `-g user/repository_name`
-- For other Git platforms like GitLab, use `-g https://example.com/user/repository_name.git`
+### One-off Usage (No Config)
 
-These remote configurations support multiple scaffold groups, which can be specified using the
-`--key` or `-k` argument:
+Generate files from a template directory without a config file:
 
 ```sh
-$ npx simple-scaffold \
-  -g chenasraf/simple-scaffold \
-  -k component \
-  PageWrapper
-
-# equivalent to:
-$ npx simple-scaffold \
-  -g https://github.com/chenasraf/simple-scaffold.git \
-  -c scaffold.config.js \
-  -k component \
-  PageWrapper
+npx simple-scaffold -t templates/component -o src/components MyComponent
 ```
 
-By default, the template name is set to `default` when the `--key` option is not provided.
+## Configuration Files
 
-See information about each option and flag using the `--help` flag, or read the
-[CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli). For information
-about how configuration files work, [see below](#configuration-files).
+Config files let you define reusable scaffold definitions. Simple Scaffold **auto-detects** config
+files in the current directory — no `--config` flag needed.
 
-### Interactive Mode
+It searches for these files in order:
 
-When running in a terminal, Simple Scaffold will interactively prompt for any missing required
-values — name, output directory, template paths, and template key (if multiple are available).
+`scaffold.config.{mjs,cjs,js,json}`, `scaffold.{mjs,cjs,js,json}`, `.scaffold.{mjs,cjs,js,json}`
 
-Config files can also define **inputs** — custom fields that are prompted interactively and become
-template data:
+### Example
 
 ```js
+// scaffold.config.js
 module.exports = {
   component: {
     templates: ["templates/component"],
     output: "src/components",
-    inputs: {
-      author: { message: "Author name", required: true },
-      license: { message: "License", default: "MIT" },
-    },
+  },
+  page: {
+    templates: ["templates/page"],
+    output: "src/pages",
+    subdir: true,
   },
 }
 ```
 
-Inputs can be pre-provided via `--data` or `-D` to skip the prompt:
+Then run:
+
+```sh
+npx simple-scaffold -k component MyComponent
+npx simple-scaffold -k page Dashboard
+```
+
+Use the key `default` to skip the `-k` flag entirely.
+
+### Listing Available Templates
 
 ```sh
-npx simple-scaffold -c scaffold.config.js -k component -D author=John MyComponent
+npx simple-scaffold list
+npx simple-scaffold list -c path/to/config.js
+```
+
+## Templates
+
+Templates are regular files in a directory. Both **file names** and **file contents** support
+Handlebars syntax. Simple Scaffold preserves the directory structure of your template folder.
+
+### Example Template
+
+`templates/component/{{pascalCase name}}.tsx`
+
+```tsx
+// Created: {{ now 'yyyy-MM-dd' }}
+import React from "react"
+
+export default {{ pascalCase name }}: React.FC = (props) => {
+  return (
+    <div className="{{ camelCase name }}">{{ pascalCase name }} Component</div>
+  )
+}
 ```
 
-### Configuration Files
+Running `npx simple-scaffold -t templates/component -o src/components PageWrapper` produces
+`src/components/PageWrapper.tsx` with all tokens replaced.
 
-You can use a config file to more easily maintain all your scaffold definitions. Simple Scaffold
-**auto-detects** config files in the current directory — no `--config` flag needed.
+### Glob Patterns & Exclusions
 
-It searches for these files in order: `scaffold.config.{mjs,cjs,js,json}`,
-`scaffold.{mjs,cjs,js,json}`, `.scaffold.{mjs,cjs,js,json}`.
+Template paths support globs and negation:
 
-`scaffold.config.js`
+```js
+{
+  templates: ["templates/component/**", "!templates/component/README.md"]
+}
+```
+
+### .scaffoldignore
+
+Place a `.scaffoldignore` file in your template directory to exclude files. It works like
+`.gitignore` — one pattern per line, `#` for comments.
+
+## Interactive Mode & Inputs
+
+When running in a terminal, Simple Scaffold prompts for any missing required values (name, output,
+template key). Config files can also define **inputs** — custom fields that are prompted
+interactively:
 
 ```js
 module.exports = {
-  // use "default" to avoid needing to specify key
-  // in this case the key is "component"
   component: {
     templates: ["templates/component"],
     output: "src/components",
-    data: {
-      // ...
+    inputs: {
+      author: { type: "text", message: "Author name", required: true },
+      license: { type: "select", message: "License", options: ["MIT", "Apache-2.0", "GPL-3.0"] },
+      isPublic: { type: "confirm", message: "Public package?" },
+      priority: { type: "number", message: "Priority level", default: 1 },
     },
   },
 }
 ```
 
-Then just run from the same directory:
+**Input types:** `text` (default), `select`, `confirm`, `number`
+
+Pre-fill inputs from the command line to skip prompts:
 
 ```sh
-$ npx simple-scaffold PageWrapper
-# or explicitly: npx simple-scaffold -c scaffold.config.js PageWrapper
+npx simple-scaffold -k component -D author=John -D license=MIT MyComponent
 ```
 
-This will allow you to avoid needing to remember which configs are needed or to store them in a
-one-liner in `package.json` which can get pretty long and messy, and harder to maintain.
-
-Also, this allows you to define more complex scaffolds with logic without having to use the Node.js
-API directly. (Of course you always have the option to still do so if you wish)
-
-More information can be found at the
-[Configuration Files documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files).
-
-### Templates Structure
+## Remote Templates
 
-Templates are **any file** in the a directory given to `--templates`.
+Use templates from any Git repository:
 
-Simple Scaffold will maintain any file and directory structure you try to generate, while replacing
-any tokens such as `{{ name }}` or other custom-data using
-[Handlebars.js](https://handlebarsjs.com/).
+```sh
+# GitHub shorthand
+npx simple-scaffold -g username/repo -k component MyComponent
 
-`templates/component/{{ pascalName name }}.tsx`
+# Full Git URL (GitLab, Bitbucket, etc.)
+npx simple-scaffold -g https://gitlab.com/user/repo.git -k component MyComponent
+```
 
-```tsx
-// Created: {{ now 'yyyy-MM-dd' }}
-import React from 'react'
+The repository is cloned to a temporary directory, used, and cleaned up automatically.
+
+## CLI Reference
+
+### Commands
+
+| Command       | Description                              |
+| ------------- | ---------------------------------------- |
+| `[name]`      | Generate files from a template (default) |
+| `init`        | Create config file and example template  |
+| `list` / `ls` | List available template keys in a config |
+
+### Options
+
+| Flag                           | Short     | Description                                          | Default     |
+| ------------------------------ | --------- | ---------------------------------------------------- | ----------- |
+| `--config`                     | `-c`      | Path to config file or directory                     | auto-detect |
+| `--git`                        | `-g`      | Git URL or GitHub shorthand                          |             |
+| `--key`                        | `-k`      | Template key from config                             | `default`   |
+| `--output`                     | `-o`      | Output directory                                     |             |
+| `--templates`                  | `-t`      | Template file paths or globs                         |             |
+| `--data`                       | `-d`      | Custom JSON data                                     |             |
+| `--append-data`                | `-D`      | Key-value data (`key=string`, `key:=raw`)            |             |
+| `--subdir`/`--no-subdir`       | `-s`/`-S` | Create parent directory with input name              | `false`     |
+| `--subdir-helper`              | `-H`      | Helper to transform subdir name                      |             |
+| `--overwrite`/`--no-overwrite` | `-w`/`-W` | Overwrite existing files                             | `false`     |
+| `--dry-run`                    | `-dr`     | Preview output without writing files                 | `false`     |
+| `--before-write`               | `-B`      | Script to run before each file is written            |             |
+| `--after-scaffold`             | `-A`      | Shell command to run after scaffolding               |             |
+| `--quiet`                      | `-q`      | Suppress output                                      |             |
+| `--log-level`                  | `-l`      | Log level (`none`, `debug`, `info`, `warn`, `error`) | `info`      |
+| `--version`                    | `-v`      | Show version                                         |             |
+| `--help`                       | `-h`      | Show help                                            |             |
+
+## Node.js API
 
-export default {{pascalCase name}}: React.FC = (props) => {
-  return (
-    <div className="{{camelCase name}}">{{pascalCase name}} Component</div>
-  )
-}
+```js
+import Scaffold from "simple-scaffold"
+
+// Basic usage
+const scaffold = new Scaffold({
+  name: "MyComponent",
+  templates: ["templates/component"],
+  output: "src/components",
+})
+await scaffold.run()
+
+// Load from config file
+const scaffold = await Scaffold.fromConfig("scaffold.config.js", {
+  key: "component",
+  name: "MyComponent",
+})
+await scaffold.run()
 ```
 
-To generate the template output once without saving a configuration file, run:
-
-```sh
-# generate single component
-$ npx simple-scaffold \
-  -t templates/component \
-  -o src/components \
-  PageWrapper
+### Config Options
+
+| Option          | Type                       | Description                           |
+| --------------- | -------------------------- | ------------------------------------- |
+| `name`          | `string`                   | Name for generated files (required)   |
+| `templates`     | `string[]`                 | Template paths or globs (required)    |
+| `output`        | `string \| Function`       | Output directory or per-file function |
+| `data`          | `Record<string, unknown>`  | Custom template data                  |
+| `inputs`        | `Record<string, Input>`    | Interactive input definitions         |
+| `helpers`       | `Record<string, Function>` | Custom Handlebars helpers             |
+| `subdir`        | `boolean`                  | Create parent directory with name     |
+| `subdirHelper`  | `string`                   | Helper for subdir name transformation |
+| `overwrite`     | `boolean \| Function`      | Overwrite existing files              |
+| `dryRun`        | `boolean`                  | Preview without writing               |
+| `logLevel`      | `string`                   | Log verbosity                         |
+| `beforeWrite`   | `Function`                 | Async hook before each file write     |
+| `afterScaffold` | `Function \| string`       | Hook after all files are written      |
+
+## Built-in Helpers
+
+All helpers work in both file names and file contents.
+
+### Case Helpers
+
+| Helper       | Example Input | Output    |
+| ------------ | ------------- | --------- |
+| `camelCase`  | `my name`     | `myName`  |
+| `pascalCase` | `my name`     | `MyName`  |
+| `snakeCase`  | `my name`     | `my_name` |
+| `kebabCase`  | `my name`     | `my-name` |
+| `hyphenCase` | `my name`     | `my-name` |
+| `startCase`  | `my name`     | `My Name` |
+| `upperCase`  | `my name`     | `MY NAME` |
+| `lowerCase`  | `My Name`     | `my name` |
+
+### Date Helpers
+
+```handlebars
+{{now "yyyy-MM-dd"}}
+{{now "yyyy-MM-dd HH:mm" -1 "hours"}}
+{{date myDateVar "yyyy-MM-dd"}}
+{{date "2077-01-01T00:00:00Z" "yyyy-MM-dd" 7 "days"}}
 ```
 
-This will immediately create the following file: `src/components/PageWrapper.tsx`
+### Custom Helpers
 
-```tsx
-// Created: 2077-01-01
-import React from 'react'
+Add your own via config:
 
-export default PageWrapper: React.FC = (props) => {
-  return (
-    <div className="pageWrapper">PageWrapper Component</div>
-  )
+```js
+module.exports = {
+  component: {
+    templates: ["templates/component"],
+    output: "src/components",
+    helpers: {
+      shout: (str) => str.toUpperCase() + "!!!",
+    },
+  },
 }
 ```
 
@@ -216,7 +327,7 @@ just a small amount to help sustain this project, I would be very very thankful!
   <img
     height='36'
     src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3'
-    alt='Buy Me a Coffee at ko-fi.com' 
+    alt='Buy Me a Coffee at ko-fi.com'
   />
 </a>
 

package/cmd.js

@@ -1,20 +1,110 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_scaffold = require("./scaffold-Ce-rIwy9.js");
+const require_scaffold = require("./scaffold-DOzCgpZT.js");
 let node_path = require("node:path");
 node_path = require_scaffold.__toESM(node_path);
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_scaffold.__toESM(node_fs_promises);
+let _inquirer_select = require("@inquirer/select");
+_inquirer_select = require_scaffold.__toESM(_inquirer_select);
 let massarg = require("massarg");
 let massarg_command = require("massarg/command");
+//#region src/init.ts
+var CONFIG_EXTENSIONS = {
+	js: "scaffold.config.js",
+	mjs: "scaffold.config.mjs",
+	json: "scaffold.config.json"
+};
+var CONFIG_TEMPLATES = {
+	js: `/** @type {import('simple-scaffold').ScaffoldConfigMap} */
+module.exports = {
+  default: {
+    templates: ["templates/default"],
+    output: ".",
+    // inputs: {
+    //   author: { message: "Author name", required: true },
+    //   license: { message: "License", default: "MIT" },
+    // },
+  },
+}
+`,
+	mjs: `/** @type {import('simple-scaffold').ScaffoldConfigMap} */
+export default {
+  default: {
+    templates: ["templates/default"],
+    output: ".",
+    // inputs: {
+    //   author: { message: "Author name", required: true },
+    //   license: { message: "License", default: "MIT" },
+    // },
+  },
+}
+`,
+	json: `{
+  "default": {
+    "templates": ["templates/default"],
+    "output": "."
+  }
+}
+`
+};
+var EXAMPLE_TEMPLATE_CONTENT = `# {{ name }}
+
+Created by Simple Scaffold.
+
+{{#if description}}{{ description }}{{/if}}
+`;
+/**
+* Initializes a new Simple Scaffold project by creating a config file
+* and an optional example template directory.
+*/
+async function initScaffold(options = {}) {
+	const dir = options.dir ?? process.cwd();
+	const format = options.format ?? await (0, _inquirer_select.default)({
+		message: require_scaffold.colorize.cyan("Config file format:"),
+		choices: [
+			{
+				name: "JavaScript (CommonJS)",
+				value: "js"
+			},
+			{
+				name: "JavaScript (ESM)",
+				value: "mjs"
+			},
+			{
+				name: "JSON",
+				value: "json"
+			}
+		]
+	});
+	const filename = CONFIG_EXTENSIONS[format];
+	const configPath = node_path.default.resolve(dir, filename);
+	if (await require_scaffold.pathExists(configPath)) console.log(require_scaffold.colorize.yellow(`${filename} already exists, skipping config creation.`));
+	else {
+		await node_fs_promises.default.writeFile(configPath, CONFIG_TEMPLATES[format]);
+		console.log(require_scaffold.colorize.green(`Created ${filename}`));
+	}
+	if (options.createExample ?? true) {
+		const templateDir = node_path.default.resolve(dir, "templates", "default");
+		const templateFile = node_path.default.join(templateDir, "{{name}}.md");
+		if (await require_scaffold.pathExists(templateDir)) console.log(require_scaffold.colorize.yellow("templates/default/ already exists, skipping example template."));
+		else {
+			await node_fs_promises.default.mkdir(templateDir, { recursive: true });
+			await node_fs_promises.default.writeFile(templateFile, EXAMPLE_TEMPLATE_CONTENT);
+			console.log(require_scaffold.colorize.green("Created templates/default/{{name}}.md"));
+		}
+	}
+	console.log();
+	console.log(require_scaffold.colorize.dim("Get started:"));
+	console.log(require_scaffold.colorize.dim(`  npx simple-scaffold MyProject`));
+	console.log();
+}
+//#endregion
 //#region src/cmd.ts
 async function parseCliArgs(args = process.argv.slice(2)) {
 	const isProjectRoot = Boolean(await node_fs_promises.default.stat(node_path.default.join(__dirname, "package.json")).catch(() => false));
 	const pkgFile = await node_fs_promises.default.readFile(node_path.default.resolve(__dirname, isProjectRoot ? "." : "..", "package.json"));
 	const pkg = JSON.parse(pkgFile.toString());
-	args.includes("--version") || args.includes("-v");
-	args.includes("--config") || args.includes("-c");
-	args.includes("--git") || args.includes("-g");
 	return (0, massarg.massarg)({
 		name: pkg.name,
 		description: pkg.description
@@ -23,19 +113,20 @@ async function parseCliArgs(args = process.argv.slice(2)) {
 			console.log(pkg.version);
 			return;
 		}
-		require_scaffold.log(config, require_scaffold.LogLevel.info, `Simple Scaffold v${pkg.version}`);
+		require_scaffold.log(config, require_scaffold.LogLevel.debug, `Simple Scaffold v${pkg.version}`);
 		config.tmpDir = require_scaffold.getUniqueTmpPath();
 		try {
-			if (!config.config && !config.git) try {
+			const isOneTimeRun = config.templates?.length > 0 || config.output;
+			if (!config.config && !config.git && !isOneTimeRun) try {
 				config.config = await require_scaffold.findConfigFile(process.cwd());
 				require_scaffold.log(config, require_scaffold.LogLevel.debug, `Auto-detected config file: ${config.config}`);
 			} catch {}
 			const hasConfigSource = Boolean(config.config || config.git);
 			let configMap;
 			if (hasConfigSource) configMap = await require_scaffold.getConfigFile(config);
-			config = await require_scaffold.promptForMissingConfig(config, configMap);
+			config = await require_scaffold.promptBeforeConfig(config, configMap);
 			require_scaffold.log(config, require_scaffold.LogLevel.debug, "Parsing config file...", config);
-			await require_scaffold.Scaffold(await require_scaffold.resolveInputs(await require_scaffold.parseConfigFile(config)));
+			await require_scaffold.Scaffold(await require_scaffold.resolveInputs(await require_scaffold.promptAfterConfig(await require_scaffold.parseConfigFile(config))));
 		} catch (e) {
 			const message = "message" in e ? e.message : e?.toString();
 			require_scaffold.log(config, require_scaffold.LogLevel.error, message);
@@ -118,6 +209,10 @@ async function parseCliArgs(args = process.argv.slice(2)) {
 		name: "before-write",
 		aliases: ["B"],
 		description: "Run a script before writing the files. This can be a command or a path to a file. A temporary file path will be passed to the given command and the command should return a string for the final output."
+	}).option({
+		name: "after-scaffold",
+		aliases: ["A"],
+		description: "Run a shell command after all files have been written. The command is executed in the output directory. For example: `--after-scaffold 'npm install'`"
 	}).flag({
 		name: "dry-run",
 		aliases: ["dr"],
@@ -177,6 +272,29 @@ async function parseCliArgs(args = process.argv.slice(2)) {
 			if (!(val in require_scaffold.LogLevel)) throw new Error(`Invalid log level: ${val}, must be one of: ${Object.keys(require_scaffold.LogLevel).join(", ")}`);
 			return val;
 		}
+	}).help({ bindOption: true })).command(new massarg_command.MassargCommand({
+		name: "init",
+		aliases: [],
+		description: "Initialize a new scaffold config file and example template in the current directory.",
+		run: async (config) => {
+			try {
+				await initScaffold({
+					dir: config.dir,
+					format: config.format
+				});
+			} catch (e) {
+				const message = "message" in e ? e.message : e?.toString();
+				console.error(require_scaffold.colorize.red(message ?? "Unknown error"));
+			}
+		}
+	}).option({
+		name: "dir",
+		aliases: ["d"],
+		description: "Directory to create the config in. Defaults to current working directory."
+	}).option({
+		name: "format",
+		aliases: ["f"],
+		description: "Config file format: js, mjs, or json. If omitted, you will be prompted."
 	}).help({ bindOption: true })).example({
 		description: "Usage with config file",
 		input: "simple-scaffold -c scaffold.cmd.js --key component"