chore(release): 2.2.2 [skip ci]

## [2.2.2](https://github.com/chenasraf/simple-scaffold/compare/v2.2.1...v2.2.2) (2024-08-27)

### Bug Fixes

* homepage url ([daaefaf](daaefaf54e))

.github/workflows/docs.yml

@@ -1,5 +1,8 @@
 name: Documentation
 
+permissions:
+  contents: write
+
 on:
   push:
     branches: [master, pre, develop]

.github/workflows/release.yml

@@ -31,8 +31,6 @@ jobs:
         run: pnpm test
       - name: Build Package
         run: pnpm build
-      - name: Pack
-        run: cd ./dist && pnpm pack --pack-destination=../
       - name: Semantic Release
         run: npx semantic-release
         env:

CHANGELOG.md

@@ -1,57 +1,59 @@
 # Change Log
 
-# [2.0.0](https://github.com/chenasraf/simple-scaffold/compare/v1.10.0...v2.0.0) (2024-01-31)
+## [2.2.2](https://github.com/chenasraf/simple-scaffold/compare/v2.2.1...v2.2.2) (2024-08-27)
 
 
+### Bug Fixes
+
+* homepage url ([daaefaf](https://github.com/chenasraf/simple-scaffold/commit/daaefaf54e8c8887e6f210d02fd5f96c6ff4aa21))
+
+## [2.2.1](https://github.com/chenasraf/simple-scaffold/compare/v2.2.0...v2.2.1) (2024-04-21)
+
+
+### Bug Fixes
+
+* beforeWrite from config files ([98b326c](https://github.com/chenasraf/simple-scaffold/commit/98b326c84346162f379af46bc5aefb69df8be515))
+* use console.info for handlebars parse warning ([19e7b0f](https://github.com/chenasraf/simple-scaffold/commit/19e7b0f0c35c1b79a98781bdec9f54354123d8e0))
+
+# [2.2.0](https://github.com/chenasraf/simple-scaffold/compare/v2.1.0...v2.2.0) (2024-02-23)
+
+
+### Features
+
+* `list` command ([d579c09](https://github.com/chenasraf/simple-scaffold/commit/d579c09c11f2149fe7bb4515297c1287fa67083e))
+* add `--before-write` cli option ([#89](https://github.com/chenasraf/simple-scaffold/issues/89)) ([5f810e2](https://github.com/chenasraf/simple-scaffold/commit/5f810e21160816bc683cc0f375de318ff874871c))
+
+# [2.1.0](https://github.com/chenasraf/simple-scaffold/compare/v2.0.2...v2.1.0) (2024-02-12)
+
+
+### Features
+
+* support directory in --config flag ([e48b832](https://github.com/chenasraf/simple-scaffold/commit/e48b832e0b72a084d33fa2cbcca332e8209a734f))
+* support providing name in config ([4e7ac34](https://github.com/chenasraf/simple-scaffold/commit/4e7ac34db9bf67d012bbd1c06c1a26bc5ac93559))
+
+## [2.0.2](https://github.com/chenasraf/simple-scaffold/compare/v2.0.1...v2.0.2) (2024-02-04)
+
+
+### Bug Fixes
+
+* try to await scaffold before finally ([1b70897](https://github.com/chenasraf/simple-scaffold/commit/1b70897f9840e6365ff800490fbb813b9840177d))
+
+## [2.0.1](https://github.com/chenasraf/simple-scaffold/compare/v2.0.0...v2.0.1) (2024-02-02)
+
+
+### Bug Fixes
+
+* log level flag ([5d7f449](https://github.com/chenasraf/simple-scaffold/commit/5d7f449050e50a6e4b2d00b7a2215cdb5fc9b611))
+* rm tmp dir too early ([4aa52c8](https://github.com/chenasraf/simple-scaffold/commit/4aa52c84bd8cf302031e9f7f6407466aa736beb7))
+
+# [2.0.0](https://github.com/chenasraf/simple-scaffold/compare/v1.9.0...v2.0.0) (2024-01-31)
+
 * fix!: version number ([bc0a18d](https://github.com/chenasraf/simple-scaffold/commit/bc0a18dce01fefec6187192cb20c9303f7f7dbfa))
-
-
-### BREAKING CHANGES
-
-* see changelog
-
-# [1.10.0](https://github.com/chenasraf/simple-scaffold/compare/v1.9.0...v1.10.0) (2024-01-31)
-
-
-### Bug Fixes
-
 * remove gh flag ([939200c](https://github.com/chenasraf/simple-scaffold/commit/939200c9f21be240485ea602a73b983ba2f47aaf))
 * tests ([ff92fd7](https://github.com/chenasraf/simple-scaffold/commit/ff92fd7607f1b86f36fc6b62652fdfc81cb391a3))
-
-
-### Features
-
 * try multiple default config files ([89aacb5](https://github.com/chenasraf/simple-scaffold/commit/89aacb58fd90a892f4994c758c61c43b2a6b1fba))
-
-# [1.10.0](https://github.com/chenasraf/simple-scaffold/compare/v1.9.0...v1.10.0) (2024-01-31)
-
-
-### Bug Fixes
-
-* remove gh flag ([939200c](https://github.com/chenasraf/simple-scaffold/commit/939200c9f21be240485ea602a73b983ba2f47aaf))
-* tests ([ff92fd7](https://github.com/chenasraf/simple-scaffold/commit/ff92fd7607f1b86f36fc6b62652fdfc81cb391a3))
-
-
-### Features
-
-* try multiple default config files ([89aacb5](https://github.com/chenasraf/simple-scaffold/commit/89aacb58fd90a892f4994c758c61c43b2a6b1fba))
-
-# [2.0.0-pre.3](https://github.com/chenasraf/simple-scaffold/compare/v2.0.0-pre.2...v2.0.0-pre.3) (2024-01-30)
-
-
-### Bug Fixes
-
-* tests ([c219d38](https://github.com/chenasraf/simple-scaffold/commit/c219d382e6df8b2ca1157544a7785f6645d04be2))
-
-## 2.0.0-pre.2 (2024-01-29)
-
 * Update README.md ([e012d51](https://github.com/chenasraf/simple-scaffold/commit/e012d51))
 * docs: fix readme doc links ([55e561b](https://github.com/chenasraf/simple-scaffold/commit/55e561b))
-
-
-
-## 2.0.0-pre.1 (2024-01-29)
-
 * chore: fix docs & formatting ([b4f0731](https://github.com/chenasraf/simple-scaffold/commit/b4f0731))
 * chore: update deps ([22ad5d4](https://github.com/chenasraf/simple-scaffold/commit/22ad5d4))
 * chore: update deps ([b2373aa](https://github.com/chenasraf/simple-scaffold/commit/b2373aa))

README.md

@@ -1,4 +1,6 @@
-<h1 align="center">Simple Scaffold</h1>
+<p align="center">
+  <img src="https://chenasraf.github.io//simple-scaffold/img/logo-lg.png" alt="Logo" />
+</p>
 
 <h2 align="center">
 
@@ -31,54 +33,76 @@ lifting for you and start building your projects faster and more efficiently tod
 
 ---
 
-## Quick Start
+## Documentation
 
-### Local Templates
+See full documentation [here](https://chenasraf.github.io/simple-scaffold).
 
-The fastest way to get started is to use `npx` to immediately start a scaffold process.
+- [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)
 
-Prepare any templates you want to use - for example, in the directory `templates/component`; and use
-that in the CLI args. Here is a simple example file:
+## Getting Started
 
-Simple Scaffold will maintain any file and directory structure you try to generate.
+### Cheat Sheet
 
-`templates/component/{{ pascalName name }}.tsx`
+A quick rundown of common usage scenarios:
 
-```tsx
-// Created: {{ now 'yyyy-MM-dd' }}
-import React from 'react'
+- Remote template config file on GitHub:
 
-export default {{pascalCase name}}: React.FC = (props) => {
-  return (
-    <div className="{{camelCase name}}">{{pascalCase name}} Component</div>
-  )
-}
-```
+  ```sh
+  npx simple-scaffold -g username/repository -c scaffold.js -k component NewComponentName
+  ```
 
-To generate the template output, run:
+- Local template config file:
+
+  ```sh
+  npx simple-scaffold -c scaffold.js -k component NewComponentName
+  ```
+
+- Local one-time usage:
+
+  ```sh
+  npx simple-scaffold -t templates/component -o src/components NewComponentName
+  ```
+
+### Remote Configurations
+
+The fastest way to get started is to is to re-use someone else's (or your own) work using a template
+repository.
+
+A remote config can be loaded in one of these ways:
+
+- 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`
+
+These remote configurations support multiple scaffold groups, which can be specified using the
+`--key` or `-k` argument:
 
 ```sh
-# generate single component
-$ npx simple-scaffold@latest \
-  -t templates/component -o src/components PageWrapper
+$ 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
 ```
 
-This will immediately create the following file: `src/components/PageWrapper.tsx`
+By default, the template name is set to `default` when the `--key` option is not provided.
 
-```tsx
-// Created: 2077-01-01
-import React from 'react'
-
-export default PageWrapper: React.FC = (props) => {
-  return (
-    <div className="pageWrapper">PageWrapper Component</div>
-  )
-}
-```
+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).
 
 ### Configuration Files
 
-You can also use a config file to more easily maintain all your scaffold definitions.
+You can use a config file to more easily maintain all your scaffold definitions.
 
 `scaffold.config.js`
 
@@ -99,66 +123,61 @@ module.exports = {
 Then call your scaffold like this:
 
 ```sh
-$ npx simple-scaffold@latest -c scaffold.config.js PageWrapper
+$ npx simple-scaffold -c scaffold.config.js PageWrapper
 ```
 
 This will allow you to avoid needing to remember which configs are needed or to store them in a
-1-liner in `packqge.json` which can get pretty long and messy, which is harder to maintain.
+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)
 
-See more at the [CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli) and
-[Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files).
+More information can be found at the
+[Configuration Files documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files).
 
-### Remote Configurations
+### Templates Structure
 
-Another quick way to start is to re-use someone else's (or your own) work using a template
-repository.
+Templates are **any file** in the a directory given to `--templates`.
 
-A remote config can be loaded in one of these ways:
+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/).
 
-- If it's on GitHub, you can use `-g user/repository_name`
-- If it's on another git server (such as GitLab), you can use
-  `-g https://example.com/user/repository_name.git`
+`templates/component/{{ pascalName name }}.tsx`
 
-Configurations can hold multiple scaffold groups. Each group can be accessed using its key by
-supplying the `--key` or `-k` argument, like so:
+```tsx
+// Created: {{ now 'yyyy-MM-dd' }}
+import React from 'react'
 
-```sh
--g user/repository_name -c scaffold.js -k key_name`.
+export default {{pascalCase name}}: React.FC = (props) => {
+  return (
+    <div className="{{camelCase name}}">{{pascalCase name}} Component</div>
+  )
+}
 ```
 
-Here is an example for loading the example component templates in this very repository:
+To generate the template output once without saving a configuration file, run:
 
 ```sh
-$ npx simple-scaffold@latest \
-  -g chenasraf/simple-scaffold \
-  -k component \
-  PageWrapper
-
-# equivalent to:
-$ npx simple-scaffold@latest \
-  -g https://github.com/chenasraf/simple-scaffold.git \
-  -c scaffold.config.js \
-  -k component \
+# generate single component
+$ npx simple-scaffold \
+  -t templates/component \
+  -o src/components \
   PageWrapper
 ```
 
-When template name (`-k component`) is omitted, `default` is used.
+This will immediately create the following file: `src/components/PageWrapper.tsx`
 
-See more at the [CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli) and
-[Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files).
+```tsx
+// Created: 2077-01-01
+import React from 'react'
 
-## 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)
+export default PageWrapper: React.FC = (props) => {
+  return (
+    <div className="pageWrapper">PageWrapper Component</div>
+  )
+}
+```
 
 ## Contributing
 
@@ -189,22 +208,9 @@ If you are a developer and want to contribute code, here are some starting tips:
 
 Some tips on getting around the code:
 
-- Use `pnpm dev` for development - it runs TypeScript compile in watch mode, allowing you to make
-  changes and immediately be able to try them using `pnpm cmd`.
-- Use `pnpm build` to build the output once
-- Use `pnpm test` to run tests
 - Use `pnpm cmd` to use the CLI feature of Simple Scaffold from within the root directory, enabling
   you to test different behaviors. See `pnpm cmd -h` for more information.
-
-  > This requires an updated build, and does not trigger one itself. From here you have several
-  > options:
-  >
-  > - Run `pnpm dev` to watch for file changes and build automatically
-  > - Run `pnpm build` before running this to trigger a one-time build
-  > - Run `pnpm build-cmd` which triggers a build right before running `pnpm cmd` automatically with
-  >   the rest of the given arguments.
-
-- Use `pnpm build-docs` to build the documentation once
-- Use `pnpm watch-docs` to start docs in watch mode
-- To see the documentation, currently you have to serve the directory yourself with a static web
-  server (like node's built in serve, VS code's "Go Live" mode, etc)
+- Use `pnpm test` to run tests
+- Use `pnpm docs:build` to build the documentation once
+- Use `pnpm docs:watch` to start docs in watch mode
+- Use `pnpm build` to build the output

docs/docs/usage/01-templates.md

@@ -50,7 +50,6 @@ The contents of the file will be transformed in a similar fashion.
 
 Your `data` will be pre-populated with the following:
 
-- `{{Name}}`: PascalCase of the component name
 - `{{name}}`: raw name of the component as you entered it
 
 > Simple-Scaffold uses [Handlebars.js](https://handlebarsjs.com/) for outputting the file contents.
@@ -110,7 +109,15 @@ Further details:
   ```
 
 - **The now helper** (for current time) takes the same arguments, minus the first one (`date`) as it
-  is implicitly the current date.
+  is implicitly the current date:
+
+  ```typescript
+  (
+    format: string,
+    offsetAmount?: number,
+    offsetType?: "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds"
+  )
+  ```
 
 ### Custom Helpers
 

docs/docs/usage/02-configuration_files.md

@@ -23,48 +23,11 @@ module.exports = {
 }
 ```
 
-The configuration contents are identical to the
-[Node.js configuration structure](https://chenasraf.github.io/simple-scaffold/docs/usage/node):
-
-```ts
-interface ScaffoldConfig {
-  name: string
-  templates: string[]
-  output: FileResponse<string>
-  subdir?: boolean
-  git?: string
-  config?: string
-  key?: string
-  data?: Record<string, any>
-  overwrite?: FileResponse<boolean>
-  quiet?: boolean
-  verbose?: LogLevel
-  dryRun?: boolean
-  helpers?: Record<string, Helper>
-  subdirHelper?: DefaultHelpers | string
-  beforeWrite?(
-    content: Buffer,
-    rawContent: Buffer,
-    outputPath: string,
-  ): string | Buffer | undefined | Promise<string | Buffer | undefined>
-}
-```
+For the full configuration options, see [ScaffoldConfigFile](../api/modules#scaffoldconfigfile).
 
 If you want to supply functions inside the configurations, you must use a `.js`/`.cjs`/`.mjs` file
 as JSON does not support non-primitives.
 
-A `.js` file can be just like a `.json` file, make sure to export the final configuration:
-
-```js
-/** @type {import('simple-scaffold').ScaffoldConfigFile} */
-module.exports = {
-  component: {
-    templates: ["templates/component"],
-    output: "src/components",
-  },
-}
-```
-
 Another feature of using a JS file is you can export a function which will be loaded with the CMD
 config provided to Simple Scaffold. The `extra` key contains any values not consumed by built-in
 flags, so you can pre-process your args before outputting a config:
@@ -82,6 +45,12 @@ module.exports = (config) => {
 }
 ```
 
+If you want to provide templates that need no name (such as common config files which are easily
+portable between projects), you may provide the `name` property in the config object.
+
+You will always be able to override it using `--name NewName`, but it will be given a value by
+default and therefore it will no longer be required in the CLI arguments.
+
 ## Using a config file
 
 Once your config is created, you can use it by providing the file name to the `--config` (or `-c`
@@ -116,7 +85,7 @@ And then:
 simple-scaffold -c scaffold.json MyComponentName
 ```
 
-- When the filename is omitted, the following files will be tried in order:
+- When the a directory is given, the following files in the given directory will be tried in order:
 
   - `scaffold.config.*`
   - `scaffold.*`
@@ -162,6 +131,12 @@ simple-scaffold -g git://gitlab.com/<username>/<project_name> [-c <filename>] [-
 simple-scaffold -g https://gitlab.com/<username>/<project_name>.git [-c <filename>] [-k <template_key>]
 ```
 
+When a config file path is omitted, the files given in the list above will be tried on the root
+directory of the git repository.
+
+**Note:** The repository will be cloned to a temporary directory and removed after the scaffolding
+has been done.
+
 ## Use In Node.js
 
 You can also start a scaffold from Node.js with a remote file or URL config.

docs/docs/usage/03-cli.md

@@ -0,0 +1,130 @@
+---
+title: CLI Usage
+---
+
+## Available flags
+
+```text
+Usage: simple-scaffold [options]
+```
+
+To see this and more information anytime, add the `-h` or `--help` flag to your call, e.g.
+`npx simple-scaffold@latest -h`.
+
+Options:
+
+| Option/flag \| Alias                              | Description                                                                                                                                                                                              |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name` \| `-n`                                  | Name to be passed to the generated files. `{{name}}` and other data parameters inside contents and file names will be replaced accordingly. You may omit the `--name` or `-n` for this specific option.  |
+| `--config` \| `-c`                                | Filename or directory to load config from                                                                                                                                                                |
+| `--git` \| `-g`                                   | Git URL or GitHub path to load a template from.                                                                                                                                                          |
+| `--key` \| `-k`                                   | Key to load inside the config file. This overwrites the config key provided after the colon in `--config` (e.g. `--config scaffold.cmd.js:component)`                                                    |
+| `--output` \| `-o`                                | Path to output to. If `--subdir` is enabled, the subdir will be created inside this path. Default is current working directory.                                                                          |
+| `--templates` \| `-t`                             | Template files to use as input. You may provide multiple files, each of which can be a relative or absolute path, or a glob pattern for multiple file matching easily.                                   |
+| `--overwrite` \| `-w` \| `--no-overwrite` \| `-W` | Enable to override output files, even if they already exist. (default: false)                                                                                                                            |
+| `--data` \| `-d`                                  | Add custom data to the templates. By default, only your app name is included.                                                                                                                            |
+| `--append-data` \| `-D`                           | Append additional custom data to the templates, which will overwrite `--data`, using an alternate syntax, which is easier to use with CLI: `-D key1=string -D key2:=raw`                                 |
+| `--subdir` \| `-s` \| `--no-subdir` \| `-S`       | Create a parent directory with the input name (and possibly `--subdir-helper` (default: false)                                                                                                           |
+| `--subdir-helper` \| `-H`                         | Default helper to apply to subdir name when using `--subdir`.                                                                                                                                            |
+| `--quiet` \| `-q`                                 | Suppress output logs (Same as `--log-level none`)(default: false)                                                                                                                                        |
+| `--log-level` \| `-l`                             | Determine amount of logs to display. The values are: `none, debug, info, warn, error`. The provided level will display messages of the same level or higher. (default: info)                             |
+| `--before-write` \| `-B`                          | 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. |
+| `--dry-run` \| `-dr`                              | Don't emit files. This is good for testing your scaffolds and making sure they don't fail, without having to write actual file contents or create directories. (default: false)                          |
+| `--version` \| `-v`                               | Display version.                                                                                                                                                                                         |
+
+### Before Write option
+
+This option allows you to preprocess a file before it is being written, such as running a formatter,
+linter or other commands.
+
+To use this option, pass it the command you would like to run. The following tokens will be replaced
+in your string:
+
+- `{{path}}` - the temporary file path for you to read from
+- `{{rawpath}}` - a different file path containing the raw file contents **before** they were
+  handled by Handlebars.js.
+
+If none of these tokens are found, the regular (non-raw) path will be appended to the end of the
+command.
+
+```shell
+simple-scaffold -c . --before-write prettier
+# command: prettier /tmp/somefile
+
+simple-scaffold -c . --before-write 'cat {{path}} | my-linter'
+# command: cat /tmp/somefile | my-linter
+```
+
+The command should return the string to write to the file through standard output (stdout), and not
+re-write the tmp file as it is not used for writing. Returning an empty string (after trimming) will
+discard the result and write the original file contents.
+
+See
+[beforeWrite](https://chenasraf.github.io/simple-scaffold/docs/api/interfaces/ScaffoldConfig#beforewrite)
+Node.js API for more details. Instead of returning `undefined` to keep the default behavior, you can
+output `''` for the same effect.
+
+## Available Commands:
+
+| Command \| Alias | Description                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `list` \| `ls`   | List all available templates for a given config. See `list -h` for more information. |
+
+## Examples:
+
+> See
+> [Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files)
+> for organizing multiple scaffold types into easy-to-maintain files
+
+Usage with config file
+
+```shell
+$ simple-scaffold -c scaffold.cmd.js -k component MyComponent
+```
+
+Usage with GitHub config file
+
+```shell
+$ simple-scaffold -g chenasraf/simple-scaffold -k component MyComponent
+```
+
+Usage with https git URL (for non-GitHub)
+
+```shell
+$ simple-scaffold \
+      -g https://example.com/user/template.git \
+      -c scaffold.cmd.js \
+      -k component \
+      MyComponent
+```
+
+Full syntax with config path and template key (applicable to all above methods)
+
+```shell
+$ simple-scaffold -c scaffold.cmd.js -k component MyComponent
+```
+
+Excluded template key, assumes 'default' key
+
+```shell
+$ simple-scaffold -c scaffold.cmd.js MyComponent
+```
+
+Shortest syntax for GitHub, assumes file 'scaffold.cmd.js' and template key 'default'
+
+```shell
+$ simple-scaffold -g chenasraf/simple-scaffold MyComponent
+```
+
+You can also add this as a script in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "scaffold-cfg": "npx simple-scaffold -c scaffold.cmd.js -k component",
+    "scaffold-gh": "npx simple-scaffold -g chenasraf/simple-scaffold -k component",
+    "scaffold": "npx simple-scaffold@latest -t scaffolds/component/**/* -o src/components -d '{\"myProp\": \"propName\", \"myVal\": 123}'"
+    "scaffold-component":  "npx simple-scaffold -c scaffold.cmd.js -k"
+  }
+}
+```

docs/docs/usage/04-node.md

@@ -2,6 +2,8 @@
 title: Node.js Usage
 ---
 
+## Overview
+
 You can build the scaffold yourself, if you want to create more complex arguments, scaffold groups,
 etc - simply pass a config object to the Scaffold function when you are ready to start.
 
@@ -17,14 +19,14 @@ interface ScaffoldConfig {
   name: string
   templates: string[]
   output: FileResponse<string>
-  createSubFolder?: boolean
+  subdir?: boolean
   data?: Record<string, any>
   overwrite?: FileResponse<boolean>
   quiet?: boolean
   verbose?: LogLevel
   dryRun?: boolean
   helpers?: Record<string, Helper>
-  subFolderNameHelper?: DefaultHelpers | string
+  subdirHelper?: DefaultHelpers | string
   beforeWrite?(
     content: Buffer,
     rawContent: Buffer,
@@ -33,6 +35,19 @@ interface ScaffoldConfig {
 }
 ```
 
+### Before Write option
+
+This option allows you to preprocess a file before it is being written, such as running a formatter,
+linter or other commands.
+
+To use this option, you can run any async/blocking command, and return a string as the final output
+to be used as the file contents.
+
+Returning `undefined` will keep the file contents as-is, after normal Handlebars.js procesing by
+Simple Scaffold.
+
+## Example
+
 This is an example of loading a complete scaffold via Node.js:
 
 ```typescript
@@ -42,15 +57,17 @@ const config = {
   name: "component",
   templates: [path.join(__dirname, "scaffolds", "component")],
   output: path.join(__dirname, "src", "components"),
-  createSubFolder: true,
-  subFolderNameHelper: "upperCase"
+  subdir: true,
+  subdirHelper: "upperCase",
   data: {
     property: "value",
   },
   helpers: {
-    twice: (text) => [text, text].join(" ")
+    twice: (text) => [text, text].join(" "),
   },
-  beforeWrite: (content, rawContent, outputPath) => content.toString().toUpperCase()
+  // return a string to replace the final file contents after pre-processing, or `undefined`
+  // to keep it as-is
+  beforeWrite: (content, rawContent, outputPath) => content.toString().toUpperCase(),
 }
 
 const scaffold = Scaffold(config)

docs/docs/usage/06-migration.md

@@ -15,8 +15,7 @@ title: Migration
   - The `#template_file` syntax has been removed, you may use `--config` or `-c` to tell Simple
     Scaffold which file to look for inside the git project. There is a default file priority list
     which can find the file for you if it is in one of the supported filenames.
-- `verbose` can now take the names `debug`, `info`, `warn`, `error` or `none` (case insensitive) or
-  as usual by using the numbering from before.
+- `verbose` can now take the names `debug`, `info`, `warn`, `error` or `none` (case insensitive).
 - `--create-sub-folder` (`-s`) has been renamed to `--subdir` (`-s`) in the CLI. The Node.js names
   have been changed as well.
 - `--sub-folder-name-helper` (`-sh`) has been renamed to `--subdir-helper` (`-sh`). The Node.js

docs/docs/usage/cli.md

@@ -1,89 +0,0 @@
----
-title: CLI Usage
----
-
-## Available flags
-
-```text
-Usage: simple-scaffold [options]
-```
-
-To see this and more information anytime, add the `-h` or `--help` flag to your call, e.g.
-`npx simple-scaffold@latest -h`.
-
-| Command \| alias                    |                                                                                                                                                                                                                                                                            |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--name` \| `-n`                    | Name to be passed to the generated files. `{{name}}` and other data parameters inside contents and file names will be replaced accordingly. You may omit the `--name` or `-n` for this specific option.                                                                    |
-| `--config`\|`-c`                    | Filename to load config from instead of passing arguments to CLI or using a Node.js script. See examples for syntax. This can also work in conjunction with `--git` or `--github` to point to remote files, and with `--key` to denote which key to select from the file., |
-| `--git`\|`-g`                       | Git URL to load config from instead of passing arguments to CLI or using a Node.js script. See examples for syntax.                                                                                                                                                        |
-| `--key` \| `-k`                     | Key to load inside the config file. This overwrites the config key provided after the colon in `--config` (e.g. `--config scaffold.cmd.js:component`)                                                                                                                      |
-| `--output` \| `-o`                  | Path to output to. If `--create-sub-folder` is enabled, the subfolder will be created inside this path. Default is current working directory.                                                                                                                              |
-| `--templates` \| `-t`               | Template files to use as input. You may provide multiple files, each of which can be a relative or absolute path, or a glob pattern for multiple file matching easily.                                                                                                     |
-| `--overwrite` \| `-w`               | Enable to override output files, even if they already exist.                                                                                                                                                                                                               |
-| `--data` \| `-d`                    | Add custom data to the templates. By default, only your app name is included.                                                                                                                                                                                              |
-| `--append-data` \| `-D`             | Append additional custom data to the templates, which will overwrite `--data`, using an alternate syntax, which is easier to use with CLI: `-D key1=string -D key2:=raw`                                                                                                   |
-| `--create-sub-folder` \| `-s`       | Create subfolder with the input name                                                                                                                                                                                                                                       |
-| `--sub-folder-name-helper` \| `-sh` | Default helper to apply to subfolder name when using `--create-sub-folder true`.                                                                                                                                                                                           |
-| `--quiet` \| `-q`                   | Suppress output logs (Same as `--log-level none`)                                                                                                                                                                                                                          |
-| `--log-level` \| `-l`               | Determine amount of logs to display. The values are: `none \| debug \| info \| warn \| error`. The provided level will display messages of the same level or higher.                                                                                                       |
-| `--dry-run` \| `-dr`                | Don't emit files. This is good for testing your scaffolds and making sure they don't fail, without having to write actual file contents or create directories.                                                                                                             |
-| `--help` \| `-h`                    | Show this help message                                                                                                                                                                                                                                                     |
-
-## Examples:
-
-> See
-> [Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files)
-> for organizing multiple scaffold types into easy-to-maintain files
-
-Usage with config file
-
-```shell
-$ simple-scaffold -c scaffold.cmd.js -k component MyComponent
-```
-
-Usage with GitHub config file
-
-```shell
-$ simple-scaffold -g chenasraf/simple-scaffold -k component MyComponent
-```
-
-Usage with https git URL (for non-GitHub)
-
-```shell
-$ simple-scaffold \
-      -g https://example.com/user/template.git \
-      -c scaffold.cmd.js \
-      -k component \
-      MyComponent
-```
-
-Full syntax with config path and template key (applicable to all above methods)
-
-```shell
-$ simple-scaffold -c scaffold.cmd.js -k component MyComponent
-```
-
-Excluded template key, assumes 'default' key
-
-```shell
-$ simple-scaffold -c scaffold.cmd.js MyComponent
-```
-
-Shortest syntax for GitHub, assumes file 'scaffold.cmd.js' and template key 'default'
-
-```shell
-$ simple-scaffold -g chenasraf/simple-scaffold MyComponent
-```
-
-You can also add this as a script in your `package.json`:
-
-```json
-{
-  "scripts": {
-    "scaffold-cfg": "npx simple-scaffold -c scaffold.cmd.js -k component",
-    "scaffold-gh": "npx simple-scaffold -g chenasraf/simple-scaffold -k component",
-    "scaffold": "npx simple-scaffold@latest -t scaffolds/component/**/* -o src/components -d '{\"myProp\": \"propName\", \"myVal\": 123}'"
-    "scaffold-component":  "npx simple-scaffold -c scaffold.cmd.js -k"
-  }
-}
-```

docs/docusaurus.config.ts

@@ -5,7 +5,7 @@ import type * as Preset from "@docusaurus/preset-classic"
 const config: Config = {
   title: "Simple Scaffold",
   tagline: "Generate any file structure - from single components to entire app boilerplates, with a single command.",
-  favicon: "img/favicon.ico",
+  favicon: "img/favicon.svg",
 
   // Set the production url of your site here
   url: "https://chenasraf.github.io",
@@ -64,13 +64,7 @@ const config: Config = {
           sidebarPath: "./sidebars.ts",
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
-          editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
-        },
-        blog: {
-          showReadingTime: true,
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
+          editUrl: "https://github.com/chenasraf/simple-scaffold/blob/master/docs",
         },
         theme: {
           customCss: "./src/css/custom.css",
@@ -89,7 +83,7 @@ const config: Config = {
       title: "Simple Scaffold",
       logo: {
         alt: "Simple Scaffold",
-        src: "img/logo.svg",
+        src: "img/favicon.svg",
       },
       items: [
         {
@@ -127,7 +121,7 @@ const config: Config = {
           position: "right",
         },
         {
-          href: "https://github.com/facebook/docusaurus",
+          href: "https://github.com/chenasraf/simple-scaffold",
           label: "GitHub",
           position: "right",
         },

docs/src/pages/index.module.css

@@ -22,3 +22,13 @@
   justify-content: center;
   gap: 2rem;
 }
+
+.heroImage {
+  margin-bottom: 1.5rem;
+}
+
+.logo {
+  width: 100%;
+  max-width: 300px;
+  margin: 0 auto;
+}

docs/src/pages/index.tsx

@@ -12,10 +12,12 @@ function HomepageHeader() {
   return (
     <header className={clsx("hero hero--primary", styles.heroBanner)}>
       <div className="container">
+        <img className={styles.logo} src="img/logo-lg.svg" alt="Simple Scaffold" />
         <Heading as="h1" className="hero__title">
           {siteConfig.title}
         </Heading>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <img className={styles.heroImage} src="img/intro.gif" alt="Simple-Scaffold doing its thing" />
         <div className={styles.buttons}>
           <Link className="button button--secondary button--lg" to="/docs/api">
             API

examples/test-input/Component/{{pascalCase name}}.tsx

@@ -1,7 +1,7 @@
 import * as React from "react"
-import * as css from "./{{pascalCae name}}.css"
+import * as css from "./{{pascalCase name}}.css"
 
-class {{pascalCae name}} extends React.Component<any> {
+class {{pascalCase name}} extends React.Component<any> {
   private {{ property }}
 
   constructor(props: any) {
@@ -10,8 +10,8 @@ class {{pascalCae name}} extends React.Component<any> {
   }
 
   public render() {
-    return <div className={ css.{{pascalCae name}} } />
+    return <div className={ css.{{pascalCase name}} } />
   }
 }
 
-export default {pascalCae nName}}
+export default {{pascalCase name}}

package.json

@@ -1,14 +1,19 @@
 {
   "name": "simple-scaffold",
-  "version": "2.0.0",
+  "version": "2.2.2",
   "description": "Generate any file structure - from single components to entire app boilerplates, with a single command.",
-  "homepage": "https: //chenasraf.github.io/simple-scaffold",
-  "repository": "https://github.com/chenasraf/simple-scaffold.git",
-  "author": "Chen Asraf <contact@casraf.dev>",
+  "homepage": "https://chenasraf.github.io/simple-scaffold",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenasraf/simple-scaffold.git"
+  },
+  "author": "Chen Asraf <contact@casraf.dev> (https://casraf.dev)",
   "license": "MIT",
   "main": "index.js",
-  "bin": "cmd.js",
-  "packageManager": "pnpm@8.6.2",
+  "bin": {
+    "simple-scaffold": "cmd.js"
+  },
+  "packageManager": "pnpm@9.0.4",
   "keywords": [
     "javascript",
     "cli",
@@ -34,28 +39,28 @@
   },
   "dependencies": {
     "chalk": "^4.1.2",
-    "date-fns": "^3.3.1",
-    "glob": "^10.3.10",
+    "date-fns": "^3.6.0",
+    "glob": "^11.0.0",
     "handlebars": "^4.7.8",
-    "massarg": "2.0.0"
+    "massarg": "2.0.1"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/release-notes-generator": "^12.1.0",
-    "@types/jest": "^29.5.11",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "@types/jest": "^29.5.12",
     "@types/mock-fs": "^4.13.4",
-    "@types/node": "^20.11.14",
+    "@types/node": "^22.5.0",
     "@types/semantic-release": "^20.0.6",
-    "conventional-changelog": "^5.1.0",
-    "conventional-changelog-cli": "^4.1.0",
+    "conventional-changelog": "^6.0.0",
+    "conventional-changelog-cli": "^5.0.0",
     "jest": "^29.7.0",
     "mock-fs": "^5.2.0",
-    "semantic-release": "^23.0.0",
+    "semantic-release": "^24.1.0",
     "semantic-release-conventional-commits": "^3.0.0",
-    "ts-jest": "^29.1.2",
+    "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
-    "typescript": "^5.3.3"
+    "typescript": "^5.5.4"
   }
 }

release.config.js

@@ -13,31 +13,44 @@ module.exports = {
       "@semantic-release/npm",
       {
         // only update the pkg version on root, don't publish
+        // this is to keep package.json version in sync with the release
         npmPublish: false,
       },
     ],
-    // [
-    //   '@semantic-release/npm',
-    //   {
-    //     // only update the pkg version on doc, don't publish
-    //     npmPublish: false,
-    //     pkgRoot: 'doc',
-    //   },
-    // ]
+    [
+      "@semantic-release/exec",
+      {
+        // pack the dist folder, during publish step (after version was bumped)
+        publishCmd: 'echo "Packing..."; cd ./dist && pnpm pack --pack-destination=../; echo "Done"',
+      },
+    ],
     [
       "@semantic-release/npm",
       {
         // publish from dist dir instead of root
+        // this is the actual uild output
         pkgRoot: "dist",
       },
     ],
     [
+      // Release to GitHub
       "@semantic-release/github",
       {
         assets: ["*.tgz"],
       },
     ],
+    branch === "master"
+      ? [
+        // Update CHANGELOG.md only on master
+        "@semantic-release/changelog",
+        {
+          changelogFile: "CHANGELOG.md",
+          changelogTitle: "# Change Log",
+        },
+      ]
+      : undefined,
     [
+      // Commit the package.json and CHANGELOG.md files to git (if modified)
       "@semantic-release/git",
       {
         assets: ["package.json", "CHANGELOG.md"].filter(Boolean),
@@ -50,16 +63,5 @@ module.exports = {
     //     verifyReleaseCmd: 'echo ${nextRelease.version} > .VERSION',
     //   },
     // ],
-  ],
-}
-
-if (branch === "master") {
-  const gitIdx = module.exports.plugins.findIndex((plugin) => plugin[0] === "@semantic-release/git")
-  module.exports.plugins.splice(gitIdx, 0, [
-    "@semantic-release/changelog",
-    {
-      changelogFile: "CHANGELOG.md",
-      changelogTitle: "# Change Log",
-    },
-  ])
+  ].filter(Boolean),
 }

scaffold.config.js

@@ -1,4 +1,5 @@
-/** @type {import('simple-scaffold').ScaffoldConfigFile} */
+// @ts-check
+/** @type {import('./dist').ScaffoldConfigFile} */
 module.exports = (conf) => {
   console.log("Config:", conf)
   return {
@@ -12,5 +13,10 @@ module.exports = (conf) => {
       output: "examples/test-output/component",
       data: { property: "myProp", value: "10" },
     },
+    configs: {
+      templates: ["examples/test-input/**/.*"],
+      output: "examples/test-output/configs",
+      name: "---",
+    },
   }
 }

src/cmd.ts

@@ -1,50 +1,67 @@
 #!/usr/bin/env node
-import { massarg } from "massarg"
-import chalk from "chalk"
-import { LogLevel, ScaffoldCmdConfig } from "./types"
-import { Scaffold } from "./scaffold"
+
 import path from "node:path"
 import fs from "node:fs/promises"
-import { parseAppendData, parseConfigFile } from "./config"
+import { massarg } from "massarg"
+import chalk from "chalk"
+import { ListCommandCliOptions, LogLevel, ScaffoldCmdConfig } from "./types"
+import { Scaffold } from "./scaffold"
+import { getConfigFile, parseAppendData, parseConfigFile } from "./config"
+import { log } from "./logger"
+import { MassargCommand } from "massarg/command"
+import { getUniqueTmpPath as generateUniqueTmpPath } from "./file"
 
 export async function parseCliArgs(args = process.argv.slice(2)) {
   const isProjectRoot = Boolean(await fs.stat(path.join(__dirname, "package.json")).catch(() => false))
   const pkgFile = await fs.readFile(path.resolve(__dirname, isProjectRoot ? "." : "..", "package.json"))
   const pkg = JSON.parse(pkgFile.toString())
-  const isConfigProvided =
-    args.includes("--config") || args.includes("-c") || args.includes("--git") || args.includes("-g")
+  const isVersionFlag = args.includes("--version") || args.includes("-v")
+  const isConfigFileProvided = args.includes("--config") || args.includes("-c")
+  const isGitProvided = args.includes("--git") || args.includes("-g")
+  const isConfigProvided = isConfigFileProvided || isGitProvided || isVersionFlag
 
   return massarg<ScaffoldCmdConfig>({
     name: pkg.name,
     description: pkg.description,
   })
     .main(async (config) => {
-      const parsed = await parseConfigFile(config)
-      return Scaffold(parsed)
+      if (config.version) {
+        console.log(pkg.version)
+        return
+      }
+      log(config, LogLevel.info, `Simple Scaffold v${pkg.version}`)
+      const tmpPath = generateUniqueTmpPath()
+      try {
+        log(config, LogLevel.debug, "Parsing config file...", config)
+        const parsed = await parseConfigFile(config, tmpPath)
+        await Scaffold(parsed)
+      } catch (e) {
+        const message = "message" in (e as any) ? (e as any).message : e?.toString()
+        log(config, LogLevel.error, message)
+      } finally {
+        log(config, LogLevel.debug, "Cleaning up temporary files...", tmpPath)
+        await fs.rm(tmpPath, { recursive: true, force: true })
+      }
     })
     .option({
       name: "name",
       aliases: ["n"],
       description:
         "Name to be passed to the generated files. `{{name}}` and other data parameters inside " +
-        "contents and file names will be replaced accordingly. You may omit the `--name` or `-n` for this specific option.",
+        "contents and file names will be replaced accordingly. You may omit the `--name` or `-n` " +
+        "for this specific option.",
       isDefault: true,
-      required: true,
+      required: !isConfigProvided,
     })
     .option({
       name: "config",
       aliases: ["c"],
-      description:
-        "Filename to load config from instead of passing arguments to CLI or using a Node.js " +
-        "script. See examples for syntax. This can also work in conjunction with `--git` or `--github` to point " +
-        "to remote files, and with `--key` to denote which key to select from the file.",
+      description: "Filename or directory to load config from",
     })
     .option({
       name: "git",
       aliases: ["g"],
-      description:
-        "Git URL to load config from instead of passing arguments to CLI or using a Node.js script. See " +
-        "examples for syntax.",
+      description: "Git URL or GitHub path to load a template from.",
     })
     .option({
       name: "key",
@@ -57,7 +74,7 @@ export async function parseCliArgs(args = process.argv.slice(2)) {
       name: "output",
       aliases: ["o"],
       description:
-        "Path to output to. If `--subdir` is enabled, the subfolder will be created inside " +
+        "Path to output to. If `--subdir` is enabled, the subdir will be created inside " +
         "this path. Default is current working directory.",
       required: !isConfigProvided,
     })
@@ -103,7 +120,7 @@ export async function parseCliArgs(args = process.argv.slice(2)) {
     .option({
       name: "subdir-helper",
       aliases: ["H"],
-      description: "Default helper to apply to subfolder name when using `--subdir`.",
+      description: "Default helper to apply to subdir name when using `--subdir`.",
     })
     .flag({
       name: "quiet",
@@ -119,7 +136,21 @@ export async function parseCliArgs(args = process.argv.slice(2)) {
         "Determine amount of logs to display. The values are: " +
         `${chalk.bold`\`none | debug | info | warn | error\``}. ` +
         "The provided level will display messages of the same level or higher.",
-      parse: Number,
+      parse: (v) => {
+        const val = v.toLowerCase()
+        if (!(val in LogLevel)) {
+          throw new Error(`Invalid log level: ${val}, must be one of: ${Object.keys(LogLevel).join(", ")}`)
+        }
+        return val
+      },
+    })
+    .option({
+      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.",
     })
     .flag({
       name: "dry-run",
@@ -129,6 +160,72 @@ export async function parseCliArgs(args = process.argv.slice(2)) {
         "Don't emit files. This is good for testing your scaffolds and making sure they " +
         "don't fail, without having to write actual file contents or create directories.",
     })
+    .flag({
+      name: "version",
+      aliases: ["v"],
+      description: "Display version.",
+    })
+    .command(
+      new MassargCommand<ListCommandCliOptions>({
+        name: "list",
+        aliases: ["ls"],
+        description: "List all available templates for a given config. See `list -h` for more information.",
+        run: async (_config) => {
+          const tmpPath = generateUniqueTmpPath()
+          const config = {
+            templates: [],
+            name: "",
+            version: false,
+            output: "",
+            subdir: false,
+            overwrite: false,
+            dryRun: false,
+            ..._config,
+            config: _config.config ?? (!_config.git ? process.cwd() : undefined),
+          }
+          try {
+            const file = await getConfigFile(config, tmpPath)
+            console.log(chalk.underline`Available templates:\n`)
+            console.log(Object.keys(file).join("\n"))
+          } catch (e) {
+            const message = "message" in (e as any) ? (e as any).message : e?.toString()
+            log(config, LogLevel.error, message)
+          } finally {
+            log(config, LogLevel.debug, "Cleaning up temporary files...", tmpPath)
+            await fs.rm(tmpPath, { recursive: true, force: true })
+          }
+        },
+      })
+        .option({
+          name: "config",
+          aliases: ["c"],
+          description: "Filename or directory to load config from. Defaults to current working directory.",
+        })
+        .option({
+          name: "git",
+          aliases: ["g"],
+          description: "Git URL or GitHub path to load a template from.",
+        })
+        .option({
+          name: "log-level",
+          aliases: ["l"],
+          defaultValue: LogLevel.none,
+          description:
+            "Determine amount of logs to display. The values are: " +
+            `${chalk.bold`\`none | debug | info | warn | error\``}. ` +
+            "The provided level will display messages of the same level or higher.",
+          parse: (v) => {
+            const val = v.toLowerCase()
+            if (!(val in LogLevel)) {
+              throw new Error(`Invalid log level: ${val}, must be one of: ${Object.keys(LogLevel).join(", ")}`)
+            }
+            return val
+          },
+        })
+        .help({
+          bindOption: true,
+        }),
+    )
     .example({
       description: "Usage with config file",
       input: "simple-scaffold -c scaffold.cmd.js --key component",

src/config.ts

@@ -1,4 +1,5 @@
 import path from "node:path"
+import fs from "node:fs/promises"
 import {
   ConfigLoadConfig,
   FileResponse,
@@ -9,11 +10,14 @@ import {
   ScaffoldCmdConfig,
   ScaffoldConfig,
   ScaffoldConfigFile,
+  ScaffoldConfigMap,
 } from "./types"
 import { handlebarsParse } from "./parser"
 import { log } from "./logger"
 import { resolve, wrapNoopResolver } from "./utils"
 import { getGitConfig } from "./git"
+import { createDirIfNotExists, getUniqueTmpPath, isDir, pathExists } from "./file"
+import { exec, spawn } from "node:child_process"
 
 /** @internal */
 export function getOptionValueForFile<T>(
@@ -48,56 +52,73 @@ function isWrappedWithQuotes(string: string): boolean {
 }
 
 /** @internal */
-export async function parseConfigFile(config: ScaffoldCmdConfig): Promise<ScaffoldConfig> {
-  let output: ScaffoldConfig = config
-
-  if (config.quiet) {
-    config.logLevel = LogLevel.none
-  }
-
+export async function getConfigFile(config: ScaffoldCmdConfig, tmpPath: string): Promise<ScaffoldConfigMap> {
   if (config.git && !config.git.includes("://")) {
     log(config, LogLevel.info, `Loading config from GitHub ${config.git}`)
     config.git = githubPartToUrl(config.git)
   }
 
-  const shouldLoadConfig = config.config || config.git
+  const isGit = Boolean(config.git)
+  const configFilename = config.config
+  const configPath = isGit ? config.git : configFilename
+
+  log(config, LogLevel.info, `Loading config from file ${configFilename}`)
+
+  const configPromise = await (isGit
+    ? getRemoteConfig({ git: configPath, config: configFilename, logLevel: config.logLevel, tmpPath })
+    : getLocalConfig({ config: configFilename, logLevel: config.logLevel }))
+
+  // resolve the config
+  let configImport = await resolve(configPromise, config)
+
+  // If the config is a function or promise, return the output
+  if (typeof configImport.default === "function" || configImport.default instanceof Promise) {
+    log(config, LogLevel.debug, "Config is a function or promise, resolving...")
+    configImport = await resolve(configImport.default, config)
+  }
+  return configImport
+}
+
+/** @internal */
+export async function parseConfigFile(config: ScaffoldCmdConfig, tmpPath: string): Promise<ScaffoldConfig> {
+  let output: ScaffoldConfig = { ...config, beforeWrite: undefined }
+
+  if (config.quiet) {
+    config.logLevel = LogLevel.none
+  }
+
+  const shouldLoadConfig = Boolean(config.config || config.git)
 
   if (shouldLoadConfig) {
-    const isGit = Boolean(config.git)
     const key = config.key ?? "default"
-    const configFilename = config.config
-    const configPath = isGit ? config.git : configFilename
-
-    log(config, LogLevel.info, `Loading config from ${configFilename} with key ${key}`)
-    const configPromise = await (config.git
-      ? getRemoteConfig({ git: configPath, config: configFilename, logLevel: config.logLevel })
-      : getLocalConfig({ config: configFilename, logLevel: config.logLevel }))
-
-    // resolve the config
-    let configImport = await resolve(configPromise, config)
-
-    // If the config is a function or promise, return the output
-    if (typeof configImport.default === "function" || configImport.default instanceof Promise) {
-      configImport = await resolve(configImport.default, config)
-    }
+    const configImport = await getConfigFile(config, tmpPath)
 
     if (!configImport[key]) {
-      throw new Error(`Template "${key}" not found in ${configFilename}`)
+      throw new Error(`Template "${key}" not found in ${config.config}`)
     }
 
-    const importedKey = configImport[key]
+    const imported = configImport[key]
+    log(config, LogLevel.debug, "Imported result", imported)
     output = {
       ...config,
-      ...importedKey,
+      ...imported,
+      beforeWrite: undefined,
       data: {
-        ...(importedKey as any).data,
+        ...(imported as any).data,
         ...config.data,
       },
     }
   }
 
   output.data = { ...output.data, ...config.appendData }
-  delete config.appendData
+  const cmdBeforeWrite = config.beforeWrite ? wrapBeforeWrite(config, config.beforeWrite) : undefined
+  output.beforeWrite = cmdBeforeWrite ?? output.beforeWrite
+
+  if (!output.name) {
+    throw new Error("simple-scaffold: Missing required option: name")
+  }
+
+  log(output, LogLevel.debug, "Parsed config", output)
   return output
 }
 
@@ -114,8 +135,22 @@ export function githubPartToUrl(part: string): string {
 export async function getLocalConfig(config: ConfigLoadConfig & Partial<LogConfig>): Promise<ScaffoldConfigFile> {
   const { config: configFile, ...logConfig } = config as Required<typeof config>
 
-  log(logConfig, LogLevel.info, `Loading config from file ${configFile}`)
   const absolutePath = path.resolve(process.cwd(), configFile)
+
+  const _isDir = await isDir(absolutePath)
+
+  if (_isDir) {
+    log(logConfig, LogLevel.debug, `Resolving config file from directory ${absolutePath}`)
+    const file = await findConfigFile(absolutePath)
+    const exists = await pathExists(file)
+    if (!exists) {
+      throw new Error(`Could not find config file in directory ${absolutePath}`)
+    }
+    log(logConfig, LogLevel.info, `Loading config from: ${path.resolve(absolutePath, file)}`)
+    return wrapNoopResolver(import(path.resolve(absolutePath, file)))
+  }
+
+  log(logConfig, LogLevel.info, `Loading config from: ${absolutePath}`)
   return wrapNoopResolver(import(absolutePath))
 }
 
@@ -123,7 +158,7 @@ export async function getLocalConfig(config: ConfigLoadConfig & Partial<LogConfi
 export async function getRemoteConfig(
   config: RemoteConfigLoadConfig & Partial<LogConfig>,
 ): Promise<ScaffoldConfigFile> {
-  const { config: configFile, git, ...logConfig } = config as Required<typeof config>
+  const { config: configFile, git, tmpPath, ...logConfig } = config as Required<typeof config>
 
   log(logConfig, LogLevel.info, `Loading config from remote ${git}, file ${configFile}`)
 
@@ -135,5 +170,90 @@ export async function getRemoteConfig(
     throw new Error(`Unsupported protocol ${url.protocol}`)
   }
 
-  return getGitConfig(url, configFile, logConfig)
+  return getGitConfig(url, configFile, tmpPath, logConfig)
+}
+
+/** @internal */
+export async function findConfigFile(root: string): Promise<string> {
+  const allowed = ["mjs", "cjs", "js", "json"].reduce((acc, ext) => {
+    acc.push(`scaffold.config.${ext}`)
+    acc.push(`scaffold.${ext}`)
+    return acc
+  }, [] as string[])
+  for (const file of allowed) {
+    const exists = await pathExists(path.resolve(root, file))
+    if (exists) {
+      return file
+    }
+  }
+  throw new Error(`Could not find config file in git repo`)
+}
+
+function wrapBeforeWrite(
+  config: LogConfig & Pick<ScaffoldConfig, "dryRun">,
+  beforeWrite: string,
+): ScaffoldConfig["beforeWrite"] {
+  return async (content, rawContent, outputFile) => {
+    const tmpPath = path.join(getUniqueTmpPath(), path.basename(outputFile))
+    await createDirIfNotExists(path.dirname(tmpPath), config)
+    const ext = path.extname(outputFile)
+    const rawTmpPath = tmpPath.replace(ext, ".raw" + ext)
+    try {
+      log(config, LogLevel.debug, "Parsing beforeWrite command", beforeWrite)
+      let cmd = await prepareBeforeWriteCmd({ beforeWrite, tmpPath, content, rawTmpPath, rawContent })
+      const result = await new Promise<string | undefined>((resolve, reject) => {
+        log(config, LogLevel.debug, "Running parsed beforeWrite command:", cmd)
+        const proc = exec(cmd)
+        proc.stdout!.on("data", (data) => {
+          if (data.trim()) {
+            resolve(data.toString())
+          } else {
+            resolve(undefined)
+          }
+        })
+        proc.stderr!.on("data", (data) => {
+          reject(data.toString())
+        })
+      })
+      return result
+    } catch (e) {
+      log(config, LogLevel.debug, e)
+      log(config, LogLevel.warning, "Error running beforeWrite command, returning original content")
+      return undefined
+    } finally {
+      await fs.rm(tmpPath, { force: true })
+      await fs.rm(rawTmpPath, { force: true })
+    }
+  }
+}
+
+async function prepareBeforeWriteCmd({
+  beforeWrite,
+  tmpPath,
+  content,
+  rawTmpPath,
+  rawContent,
+}: {
+  beforeWrite: string
+  tmpPath: string
+  content: Buffer
+  rawTmpPath: string
+  rawContent: Buffer
+}): Promise<string> {
+  let cmd: string = ""
+  const pathReg = /\{\{\s*path\s*\}\}/gi
+  const rawPathReg = /\{\{\s*rawpath\s*\}\}/gi
+  if (pathReg.test(beforeWrite)) {
+    await fs.writeFile(tmpPath, content)
+    cmd = beforeWrite.replaceAll(pathReg, tmpPath)
+  }
+  if (rawPathReg.test(beforeWrite)) {
+    await fs.writeFile(rawTmpPath, rawContent)
+    cmd = beforeWrite.replaceAll(rawPathReg, rawTmpPath)
+  }
+  if (!cmd) {
+    await fs.writeFile(tmpPath, content)
+    cmd = [beforeWrite, tmpPath].join(" ")
+  }
+  return cmd
 }

src/file.ts

@@ -1,7 +1,8 @@
+import os from "node:os"
 import path from "node:path"
-import { F_OK } from "node:constants"
-import { LogLevel, ScaffoldConfig } from "./types"
 import fs from "node:fs/promises"
+import { F_OK } from "node:constants"
+import { LogConfig, LogLevel, ScaffoldConfig } from "./types"
 import { glob, hasMagic } from "glob"
 import { log } from "./logger"
 import { getOptionValueForFile } from "./config"
@@ -10,7 +11,10 @@ import { handleErr } from "./utils"
 
 const { stat, access, mkdir, readFile, writeFile } = fs
 
-export async function createDirIfNotExists(dir: string, config: ScaffoldConfig): Promise<void> {
+export async function createDirIfNotExists(
+  dir: string,
+  config: LogConfig & Pick<ScaffoldConfig, "dryRun">,
+): Promise<void> {
   if (config.dryRun) {
     log(config, LogLevel.info, `Dry Run. Not creating dir ${dir}`)
     return
@@ -142,6 +146,7 @@ export async function copyFileTransformed(
     if (exists && overwrite) {
       log(config, LogLevel.info, `File ${outputPath} exists, overwriting`)
     }
+    log(config, LogLevel.debug, `Processing file ${inputPath}`)
     const templateBuffer = await readFile(inputPath)
     const unprocessedOutputContents = handlebarsParse(config, templateBuffer)
     const finalOutputContents =
@@ -149,7 +154,6 @@ export async function copyFileTransformed(
 
     if (!config.dryRun) {
       await writeFile(outputPath, finalOutputContents)
-      log(config, LogLevel.info, "Done.")
     } else {
       log(config, LogLevel.info, "Dry Run. Output should be:")
       log(config, LogLevel.info, finalOutputContents.toString())
@@ -157,6 +161,7 @@ export async function copyFileTransformed(
   } else if (exists) {
     log(config, LogLevel.info, `File ${outputPath} already exists, skipping`)
   }
+  log(config, LogLevel.info, "Done.")
 }
 
 export function getOutputDir(config: ScaffoldConfig, outputPathOpt: string, basePath: string): string {
@@ -209,3 +214,8 @@ export async function handleTemplateFile(
     }
   })
 }
+
+/** @internal */
+export function getUniqueTmpPath(): string {
+  return path.resolve(os.tmpdir(), `scaffold-config-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+}

src/git.ts

@@ -1,23 +1,22 @@
 import path from "node:path"
-import os from "node:os"
-import fs from "node:fs/promises"
 import { log } from "./logger"
 import { AsyncResolver, LogConfig, LogLevel, ScaffoldCmdConfig, ScaffoldConfigMap } from "./types"
 import { spawn } from "node:child_process"
 import { resolve, wrapNoopResolver } from "./utils"
+import { findConfigFile } from "./config"
 
 export async function getGitConfig(
   url: URL,
   file: string,
+  tmpPath: string,
   logConfig: LogConfig,
 ): Promise<AsyncResolver<ScaffoldCmdConfig, ScaffoldConfigMap>> {
   const repoUrl = `${url.protocol}//${url.host}${url.pathname}`
 
   log(logConfig, LogLevel.info, `Cloning git repo ${repoUrl}`)
 
-  const tmpPath = path.resolve(os.tmpdir(), `scaffold-config-${Date.now()}`)
-
   return new Promise((res, reject) => {
+    log(logConfig, LogLevel.debug, `Cloning git repo to ${tmpPath}`)
     const clone = spawn("git", ["clone", "--recurse-submodules", "--depth", "1", repoUrl, tmpPath])
 
     clone.on("error", reject)
@@ -47,6 +46,7 @@ export async function loadGitConfig({
   log(logConfig, LogLevel.info, `Loading config from git repo: ${repoUrl}`)
   const filename = file || (await findConfigFile(tmpPath))
   const absolutePath = path.resolve(tmpPath, filename)
+  log(logConfig, LogLevel.debug, `Resolving config file: ${absolutePath}`)
   const loadedConfig = await resolve(async () => (await import(absolutePath)).default as ScaffoldConfigMap, logConfig)
 
   log(logConfig, LogLevel.info, `Loaded config from git`)
@@ -58,25 +58,5 @@ export async function loadGitConfig({
       templates: v.templates.map((t) => path.resolve(tmpPath, t)),
     }
   }
-  await fs.rm(tmpPath, { recursive: true })
   return wrapNoopResolver(fixedConfig)
 }
-
-/** @internal */
-export async function findConfigFile(root: string): Promise<string> {
-  const allowed = ["mjs", "cjs", "js", "json"].reduce((acc, ext) => {
-    acc.push(`scaffold.config.${ext}`)
-    acc.push(`scaffold.${ext}`)
-    return acc
-  }, [] as string[])
-  for (const file of allowed) {
-    const exists = await fs
-      .stat(path.resolve(root, file))
-      .then(() => true)
-      .catch(() => false)
-    if (exists) {
-      return file
-    }
-  }
-  throw new Error(`Could not find config file in git repo`)
-}

src/index.ts

@@ -1,4 +1,5 @@
 export * from "./scaffold"
 export * from "./types"
 import Scaffold from "./scaffold"
+
 export default Scaffold

src/logger.ts

@@ -1,3 +1,4 @@
+import util from "util"
 import { LogConfig, LogLevel, ScaffoldConfig } from "./types"
 import chalk from "chalk"
 
@@ -30,7 +31,7 @@ export function log(config: LogConfig, level: LogLevel, ...obj: any[]): void {
       i instanceof Error
         ? chalkFn(i, JSON.stringify(i, undefined, 1), i.stack)
         : typeof i === "object"
-          ? chalkFn(JSON.stringify(i, undefined, 1))
+          ? util.inspect(i, { depth: null, colors: true })
           : chalkFn(i),
     ),
   )

src/parser.ts

@@ -121,7 +121,7 @@ export function handlebarsParse(
     return Buffer.from(outputContents)
   } catch (e) {
     log(config, LogLevel.debug, e)
-    log(config, LogLevel.warning, "Couldn't parse file with handlebars, returning original content")
+    log(config, LogLevel.info, "Couldn't parse file with handlebars, returning original content")
     return Buffer.from(templateBuffer)
   }
 }

src/scaffold.ts

@@ -5,6 +5,8 @@
  * See [readme](README.md)
  */
 import path from "node:path"
+import os from "node:os"
+
 import { handleErr, resolve } from "./utils"
 import {
   isDir,
@@ -126,10 +128,12 @@ Scaffold.fromConfig = async function (
     subdir: false,
     quiet: false,
     config: pathOrUrl,
+    version: false,
     ...config,
   }
+  const tmpPath = path.resolve(os.tmpdir(), `scaffold-config-${Date.now()}`)
   const _overrides = resolve(overrides, _cmdConfig)
-  const _config = await parseConfigFile(_cmdConfig)
+  const _config = await parseConfigFile(_cmdConfig, tmpPath)
   return Scaffold({ ..._config, ..._overrides })
 }
 

src/types.ts

@@ -27,7 +27,7 @@ export interface ScaffoldConfig {
   templates: string[]
 
   /**
-   * Path to output to. If `subdir` is `true`, the subfolder will be created inside this path.
+   * Path to output to. If `subdir` is `true`, the subdir will be created inside this path.
    *
    * May also be a {@link FileResponseHandler} which returns a new output path to override the default one.
    *
@@ -37,7 +37,7 @@ export interface ScaffoldConfig {
   output: FileResponse<string>
 
   /**
-   * Whether to create subfolder with the input name.
+   * Whether to create subdir with the input name.
    *
    * When `true`, you may also use {@link subdirHelper} to determine a pre-process helper on
    * the directory name.
@@ -131,7 +131,7 @@ export interface ScaffoldConfig {
   helpers?: Record<string, Helper>
 
   /**
-   * Default transformer to apply to subfolder name when using `subdir: true`. Can be one of the default
+   * Default transformer to apply to subdir name when using `subdir: true`. Can be one of the default
    * capitalization helpers, or a custom one you provide to `helpers`. Defaults to `undefined`, which means no
    * transformation is done.
    *
@@ -165,7 +165,7 @@ export interface ScaffoldConfig {
 /**
  * The names of the available helper functions that relate to text capitalization.
  *
- * These are available for `subfolderNameHelper`.
+ * These are available for `subdirHelper`.
  *
  * | Helper name  | Example code            | Example output |
  * | ------------ | ----------------------- | -------------- |
@@ -257,6 +257,18 @@ export type DefaultHelpers = CaseHelpers | DateHelpers
  */
 export type Helper = HelperDelegate
 
+/**
+ * The amount of information to log when generating scaffold.
+ * When not `none`, the selected level will be the lowest level included.
+ *
+ * For example, level `info`  will include `info`, `warning` and `error`, but not `debug`; and `warning` will only
+ * show `warning` and `error`, but not `info` or `debug`.
+ *
+ * @default `info`
+ *
+ * @category Logging (const)
+ */
+
 export const LogLevel = {
   /** Silent output */
   none: "none",
@@ -276,17 +288,14 @@ export const LogLevel = {
 
 /**
  * The amount of information to log when generating scaffold.
- * When not `None`, the selected level will be the lowest level included.
+ * When not `none`, the selected level will be the lowest level included.
  *
- * For example, level `Info` (2) will include `Info`, `Warning` and `Error`, but not `Debug`; and `Warning` will only
- * show `Warning` and `Error`.
+ * For example, level `info`  will include `info`, `warning` and `error`, but not `debug`; and `warning` will only
+ * show `warning` and `error`, but not `info` or `debug`.
  *
- * You may use either the number or the name of the level.
- * For example, `2` or `info` are both valid.
+ * @default `info`
  *
- * @default `2 (info)`
- *
- * @category Logging
+ * @category Logging (type)
  */
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel]
 
@@ -324,16 +333,16 @@ export type FileResponse<T> = T | FileResponseHandler<T>
  * The Scaffold config for CLI
  * Contains less and more specific options than {@link ScaffoldConfig}
  */
-export interface ScaffoldCmdConfig {
+export type ScaffoldCmdConfig = {
   /** The name of the scaffold template to use. */
   name: string
   /** The templates to use for generation */
   templates: string[]
   /** The output path to write to */
   output: string
-  /** Whether to create subfolder with the input name */
+  /** Whether to create subdir with the input name */
   subdir: boolean
-  /** Default transformer to apply to subfolder name when using `subdir: true` */
+  /** Default transformer to apply to subdir name when using `subdir: true` */
   subdirHelper?: string
   /** Add custom data to the templates */
   data?: Record<string, string>
@@ -357,6 +366,10 @@ export interface ScaffoldCmdConfig {
   key?: string
   /** The git repository to use to fetch the config file */
   git?: string
+  /** Display version */
+  version: boolean
+  /** Run a script before writing the files. This can be a command or a path to a file. The file contents will be passed to the given command. */
+  beforeWrite?: string
 }
 
 /**
@@ -369,14 +382,19 @@ export interface ScaffoldCmdConfig {
  * When no template key is provided to the scaffold command, the "default" template is used.
  *
  * @see {@link ScaffoldConfig}
+ *
+ * @category Config
  */
 export type ScaffoldConfigMap = Record<string, ScaffoldConfig>
 
-/** The scaffold config file is either:
+/**
+ * The scaffold config file is either:
  * - A {@link ScaffoldConfigMap} object
  * - A function that returns a {@link ScaffoldConfigMap} object
  * - A promise that resolves to a {@link ScaffoldConfigMap} object
  * - A function that returns a promise that resolves to a {@link ScaffoldConfigMap} object
+ *
+ * @category Config
  */
 export type ScaffoldConfigFile = AsyncResolver<ScaffoldCmdConfig, ScaffoldConfigMap>
 
@@ -393,7 +411,9 @@ export type LogConfig = Pick<ScaffoldConfig, "logLevel">
 export type ConfigLoadConfig = LogConfig & Pick<ScaffoldCmdConfig, "config">
 
 /** @internal */
-export type RemoteConfigLoadConfig = LogConfig & Pick<ScaffoldCmdConfig, "config" | "git">
+export type RemoteConfigLoadConfig = LogConfig & Pick<ScaffoldCmdConfig, "config" | "git"> & { tmpPath: string }
 
 /** @internal */
 export type MinimalConfig = Pick<ScaffoldCmdConfig, "name" | "key">
+
+export type ListCommandCliOptions = Pick<ScaffoldCmdConfig, "config" | "git" | "logLevel" | "quiet">

tests/config.test.ts

@@ -6,7 +6,7 @@ import * as config from "../src/config"
 import { resolve } from "../src/utils"
 // @ts-ignore
 import * as configFile from "../scaffold.config"
-import { findConfigFile } from "../src/git"
+import { findConfigFile } from "../src/config"
 
 jest.mock("../src/git", () => {
   return {
@@ -30,6 +30,7 @@ const blankCliConf: ScaffoldCmdConfig = {
   subdir: false,
   dryRun: false,
   quiet: false,
+  version: false,
 }
 
 const blankConfig: ScaffoldCmdConfig = {
@@ -68,25 +69,37 @@ describe("config", () => {
   describe("parseConfigFile", () => {
     test("normal config does not change", async () => {
       expect(
-        await parseConfigFile({
-          ...blankCliConf,
-        }),
-      ).toEqual(blankCliConf)
+        await parseConfigFile(
+          {
+            ...blankCliConf,
+            name: "-",
+          },
+          `/tmp/scaffold-config-${Date.now()}`,
+        ),
+      ).toEqual({ ...blankCliConf, name: "-" })
     })
     describe("appendData", () => {
       test("appends", async () => {
-        const result = await parseConfigFile({
-          ...blankCliConf,
-          appendData: { key: "value" },
-        })
+        const result = await parseConfigFile(
+          {
+            ...blankCliConf,
+            name: "-",
+            appendData: { key: "value" },
+          },
+          `/tmp/scaffold-config-${Date.now()}`,
+        )
         expect(result?.data?.key).toEqual("value")
       })
       test("overwrites existing value", async () => {
-        const result = await parseConfigFile({
-          ...blankCliConf,
-          data: { num: "123" },
-          appendData: { num: "1234" },
-        })
+        const result = await parseConfigFile(
+          {
+            ...blankCliConf,
+            name: "-",
+            data: { num: "123" },
+            appendData: { num: "1234" },
+          },
+          `/tmp/scaffold-config-${Date.now()}`,
+        )
         expect(result?.data?.num).toEqual("1234")
       })
     })
@@ -97,6 +110,7 @@ describe("config", () => {
       const resultFn = await config.getRemoteConfig({
         git: "https://github.com/chenasraf/simple-scaffold.git",
         logLevel: LogLevel.none,
+        tmpPath: `/tmp/scaffold-config-${Date.now()}`,
       })
       const result = await resolve(resultFn, blankCliConf)
       expect(result).toEqual(blankCliConf)

tests/scaffold.test.ts

@@ -92,7 +92,7 @@ function withMock(fileStruct: FileSystem.DirectoryItems, testFn: jest.EmptyFunct
 
 describe("Scaffold", () => {
   describe(
-    "create subfolder",
+    "create subdir",
     withMock(fileStructNormal, () => {
       test("should not create by default", async () => {
         await Scaffold({
@@ -395,7 +395,7 @@ describe("Scaffold", () => {
     }),
   )
   describe(
-    "transform subfolder",
+    "transform subdir",
     withMock(fileStructSubdirTransformer, () => {
       test("should work with no helper", async () => {
         await Scaffold({