create-juisy 2.0.0-beta.9 → 2.1.0

package/index.js

@@ -17,6 +17,7 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
 const {
+  abort,
   run,
   prompts
 } = InterfaceUtils
@@ -39,7 +40,10 @@ const argv = mri(process.argv.slice(2), {
 const cwd = process.cwd()
 
 // Get juisy version from this package.json file
-const { version: JUISY_VERSION } = JSON.parse(
+const {
+  version: JUISY_VERSION,
+  homepage: JUISY_DOCS_HOMEPAGE
+} = JSON.parse(
   fs.readFileSync(path.resolve(__dirname, './package.json'), 'utf-8')
 )
 
@@ -64,7 +68,11 @@ async function main () {
         initial: defaultTargetDir,
         name: 'projectName'
       }
-    ])
+    ], {
+      onCancel: () => {
+        abort(1)
+      }
+    })
     targetDir = rmTrailingSlashes(promptsResult.projectName)
   }
 
@@ -81,7 +89,11 @@ async function main () {
       initial: 0,
       name: 'devConfigFormat'
     }
-  ])
+  ], {
+    onCancel: () => {
+      abort(1)
+    }
+  })
   devConfigFormat = promptsResult.devConfigFormat
 
   /**
@@ -98,13 +110,21 @@ async function main () {
       'dev.config.json'
     ].filter(identifier => !identifier.endsWith(devConfigFormat)), // don't ignore dev config file of chosen format
     logLevel: 'warn',
-    processor: (content, identifier) => {
-      if (identifier === 'package.json') {
-        return content.replace(/__JUISY_VERSION__/g, JUISY_VERSION)
-      } else {
-        return content
+    templateData: (identifier) => {
+      return {
+        __PROJECT_NAME__: targetDir,
+        __JUISY_VERSION__: JUISY_VERSION,
+        __JUISY_DOCS_HOMEPAGE__: JUISY_DOCS_HOMEPAGE
       }
     }
+    // processor: (content, identifier) => {
+    //   if (identifier === 'package.json') {
+    //     let newContent = content.replace(/__PROJECT_NAME__/g, targetDir)
+    //     return newContent
+    //   } else {
+    //     return content
+    //   }
+    // }
   })
 
   substep($style.green(`✔ Successfuly copied`), { last: true })
@@ -116,25 +136,30 @@ async function main () {
    * Update package.json file
    */
   const scripts = {
-    'docs:api': `${targetCliCommand} docs generate -c ./docs/docs.config.js`,
+    'docs:api': `${targetCliCommand} docs generate:api`,
     'docs:readme': `${targetCliCommand} docs generate:readme`,
-    'docs:lint': `${targetCliCommand} docs lint`,
-    'docs:lint:fix': 'npm run docs:lint -- --fix',
-    'docs': 'npm run docs:readme && npm run docs:api && npm run docs:lint',
+    'docs:cli': 'npm run docs:cli:private && npm run docs:cli:public',
+    'docs:cli:private': `${targetCliCommand} docs generate:cli -c ./docs/cli/private/config.js`,
+    'docs:cli:public': `${targetCliCommand} docs generate:cli -c ./docs/cli/public/config.js`,
+    'docs': 'npm run docs:readme && npm run docs:cli && npm run docs:api && npm run lint:markdown:fix',
     'lint': `${targetCliCommand} lint`,
     'lint:fix': 'npm run lint -- --fix',
-    'lint:markdown': 'npm run docs:lint',
-    'lint:markdown:fix': 'npm run docs:lint:fix',
+    'lint:markdown': 'node ./bin/cli lint:markdown',
+    'lint:markdown:fix': 'npm run lint:markdown -- --fix',
     'release': `${targetCliCommand} release`,
     'changelog': `${targetCliCommand} changelog`,
     'git-hooks:reset': `${targetCliCommand} git-hooks reset`,
     'git-hooks:sync': `${targetCliCommand} git-hooks sync`,
-    'test': `${targetCliCommand} test`
+    'test': `${targetCliCommand} test run`,
+    'test:watch': `${targetCliCommand} test`,
+    'test:ui': 'npm run test:watch -- --ui --coverage.enabled=true',
+    'test:coverage': 'npm run test -- --coverage.enabled=true'
   }
 
   step('Adding scripts to package.json')
+  const packageJsonPath = path.join(path.resolve(cwd, targetDir), 'package.json')
   const pkg = JSON.parse(
-    fs.readFileSync(path.join(path.resolve(cwd, targetDir), 'package.json'), 'utf-8')
+    fs.readFileSync(packageJsonPath, 'utf-8')
   )
   pkg.scripts = pkg.scripts || {}
 
@@ -145,13 +170,16 @@ async function main () {
       : true
     const isLastStep = scriptName === Object.keys(scripts)[Object.keys(scripts).length - 1]
     if (setScript) {
-      await run('npm', [ 'set-script', scriptName, scripts[scriptName] ], { stdio: 'pipe', cwd: path.resolve(cwd, targetDir) })
+      pkg.scripts[scriptName] = scripts[scriptName]
       substep($style.green(`✔ Script "${scriptName}" successfuly added`), { last: isLastStep })
     } else {
       substep($style.yellow(`Script "${scriptName}" already set. Use --force option to overwrite`), { last: isLastStep })
     }
   }
 
+  // Replace package.json content
+  fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n')
+
   log() // Blank line
   log('You should now move into the created folder and run the following command:\n  - npm install')
   log() // Blank line

package/package.json

@@ -1,63 +1,61 @@
 {
-    "name": "create-juisy",
-    "version": "2.0.0-beta.9",
-    "description": "Juisy boilerplate for npm init",
-    "type": "module",
-    "bin": {
-        "create-juisy": "index.js"
-    },
-    "files": [
-        "template",
-        "index.js"
-    ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "scripts": {
-        "release": "release-it",
-        "test": "echo No test found..."
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://gitlab.com/hperchec/juisy.git"
-    },
-    "keywords": [
-        "js",
-        "build",
-        "release",
-        "changelog",
-        "bin",
-        "cmd",
-        "easy"
-    ],
-    "author": {
-        "name": "Hervé Perchec",
-        "email": "contact@herve-perchec.com",
-        "url": "https://gitlab.com/herveperchec"
-    },
-    "license": "GPL-3.0-only",
-    "bugs": {
-        "url": "https://gitlab.com/hperchec/juisy/issues"
-    },
-    "homepage": "https://gitlab.com/hperchec/juisy#readme",
-    "devDependencies": {
-        "juisy": "2.0.0-beta.9"
-    },
-    "dependencies": {
-        "execa": "^8",
-        "mri": "^1.2.0"
-    },
-    "release-it": {
-        "git": false,
-        "plugins": {
-            "@release-it/bumper": {
-                "out": {
-                    "file": "package.json",
-                    "path": [
-                        "devDependencies.juisy"
-                    ]
-                }
-            }
+  "name": "create-juisy",
+  "version": "2.1.0",
+  "description": "Juisy boilerplate for npm init",
+  "type": "module",
+  "bin": {
+    "create-juisy": "index.js"
+  },
+  "files": [
+    "template",
+    "index.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "release": "release-it --no-increment",
+    "test": "echo No test found..."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/hperchec/juisy.git"
+  },
+  "keywords": [
+    "js",
+    "build",
+    "release",
+    "changelog",
+    "bin",
+    "cmd",
+    "easy"
+  ],
+  "author": {
+    "name": "Hervé Perchec",
+    "email": "contact@herve-perchec.com",
+    "url": "https://gitlab.com/herveperchec"
+  },
+  "license": "GPL-3.0-only",
+  "bugs": {
+    "url": "https://gitlab.com/hperchec/juisy/issues"
+  },
+  "homepage": "https://hperchec.gitlab.io/juisy",
+  "dependencies": {
+    "execa": "^9.5.2",
+    "juisy": "2.1.0",
+    "mri": "^1.2.0"
+  },
+  "release-it": {
+    "git": false,
+    "plugins": {
+      "@release-it/bumper": {
+        "out": {
+          "file": "package.json",
+          "path": [
+            "dependencies.juisy"
+          ]
         }
+      }
     }
+  }
 }

package/template/.env.example

@@ -1,4 +1,4 @@
 NODE_ENV=development
 
 # CLI specific environement variables
-__JUISY_CLI_ENV__=private
+CLI_ENV=private

package/template/COMMIT_CONVENTION.md

@@ -0,0 +1,116 @@
+# Commit Message Format
+
+> ❗ IMPORTANT
+>
+> This documentation is based on Angular [commit message guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md)
+
+We have very precise rules over how our Git commit messages must be formatted.
+This format leads to **easier to read commit history** and makes it analyzable for changelog generation.
+
+Each commit message consists of a **header**, a **body**, and a **footer**.
+
+```
+<header>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The `header` is mandatory and must conform to the [Commit Message Header](#commit-header) format.
+
+The `body` is mandatory for all commits except for those of type "docs".
+When the body is present it must be at least 20 characters long and must conform to the [Commit Message Body](#commit-body) format.
+
+The `footer` is optional. The [Commit Message Footer](#commit-footer) format describes what the footer is used for and the structure it must have.
+
+## Commit Message Header
+
+```
+<type>(<scope>): <short summary>
+  │       │             │
+  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
+  │       │
+  │       └─⫸ Commit Scope: see below
+  │
+  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test
+```
+
+The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is optional.
+
+### Type
+
+Must be one of the following:
+
+| Type         | Description                                                                                         |
+|--------------|-----------------------------------------------------------------------------------------------------|
+| **build**    | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
+| **ci**       | Changes to our CI configuration files and scripts (examples: Github Actions, SauceLabs)             |
+| **docs**     | Documentation only changes                                                                          |
+| **feat**     | A new feature                                                                                       |
+| **fix**      | A bug fix                                                                                           |
+| **perf**     | A code change that improves performance                                                             |
+| **refactor** | A code change that neither fixes a bug nor adds a feature                                           |
+| **test**     | Adding missing tests or correcting existing tests                                                   |
+
+### Scope
+The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages).
+
+The following is the list of supported scopes:
+
+* `scope-a`
+* `scope-b`
+* `scope-c`
+
+### Summary
+
+Use the summary field to provide a succinct description of the change:
+
+* use the imperative, present tense: "change" not "changed" nor "changes"
+* don't capitalize the first letter
+* no dot (.) at the end
+
+## Commit Message Body
+
+Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
+
+Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are making the change.
+You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
+
+## Commit Message Footer
+
+The footer can contain information about breaking changes and deprecations and is also the place to reference GitHub issues and other PRs that this commit closes or is related to.
+For example:
+
+```
+BREAKING CHANGE: <breaking change summary>
+<BLANK LINE>
+<breaking change description + migration instructions>
+<BLANK LINE>
+<BLANK LINE>
+Fixes #<issue number>
+```
+
+or
+
+```
+DEPRECATED: <what is deprecated>
+<BLANK LINE>
+<deprecation description + recommended update path>
+<BLANK LINE>
+<BLANK LINE>
+Closes #<pr number>
+```
+
+Breaking Change section should start with the phrase `BREAKING CHANGE: ` followed by a *brief* summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.
+
+Similarly, a Deprecation section should start with `DEPRECATED: ` followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path.
+
+## Revert commits
+
+If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
+
+The content of the commit message body should contain:
+
+- information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`,
+- a clear description of the reason for reverting the commit message.

package/template/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contribution guide
+
+## Commits
+
+Commit messages are linted with `commitlint` in the `commit-msg` git hook, following the **angular** convention. Please check the [commit convention](./COMMIT_CONVENTION.md).
+
+## Build
+
+Write here the instructions to build your code, if needed.
+
+To build, run the following command:
+
+```sh
+npm run build
+```
+
+## Tests
+
+### Units
+
+To run unit tests, run the following command:
+
+```sh
+npm run test
+# With coverage enabled
+npm run test:coverage
+# Watch mode
+npm run test:watch
+# With @vitest/ui
+npm run test:ui
+```
+
+## Releases
+
+Run the following command to make a release:
+
+```sh
+# Show help
+npm run release -- --help
+# Release a patch
+npm run release -- --increment patch
+# Release a specific version
+npm run release -- -i 2.0.0
+# To increment the current prerelease. For example:
+# from   1.0.0-beta.1
+# to     1.0.0-beta.2
+npm run release -- -i pre
+```
+
+> 💡 See also:
+>
+> - the **juisy** [release tool documentation](<%= __JUISY_DOCS_HOMEPAGE__ %>)
+> - the **release-it** [package documentation](https://github.com/release-it/release-it)
+
+## Documentation
+
+Run the following command to generate project documentation:
+
+```sh
+npm run docs
+```

package/template/bin/cli/cli.js

@@ -1,27 +1,24 @@
-const { createCli, utils } = require('@hperchec/juisy')
-const path = require('path')
-const {
-  rootDir,
-  $style
-} = utils
-// Get package.json content
-const packageJson = require(path.resolve(rootDir, './package.json'))
+import { CLIFactory } from 'juisy/cli'
+
+import { commands } from './cmds/index.js'
+
+const { $style } = CLI.OutputUtils
 
 function getBanner () {
   let str = ''
-  const title = $style.bold('CLI: ') + packageJson.name
-  const length = title.length - 9 // removes characters generated by $style.bold from length
+  const title = 'Built with Juisy'
+  const length = title.length
   str += $style.cyan('-'.repeat(length) + '\n')
   str += $style.cyan(title + '\n')
   str += $style.cyan('-'.repeat(length) + '\n')
-  str += $style.italic('Made with') + ' ' + $style.red('❤') + '  ' + $style.italic('by ') + $style.bold('Hervé Perchec <contact@herve-perchec.com') + '\n'
+  str += $style.italic('Made with') + ' ' + $style.red('❤') + '  ' + $style.italic('by ') + $style.bold('Hervé Perchec') + '\n'
   return str
 }
 
-// CLI
-module.exports = createCli(cli => cli
+export default await CLIFactory(cli => cli
   .scriptName('./bin/cli')
   .usage(`${getBanner()}\nUsage: $0 <command> [<options>]`)
-  .commandDir('cmds')
+  .disableDefaultCommand('docs generate:api')
+  .command(commands)
   .demandCommand(1, ('Command is missing. See help to learn more.').red)
 )

package/template/bin/cli/cmds/index.js

@@ -1,13 +1,11 @@
 // Private commands
-import docs from './private/docs/index.js'
-import release from './private/release.js'
-import test from './private/test.js'
+import Docs from './private/docs/index.js'
+import Test from './private/test.js'
 
 export const commands = [
   // Private commands
-  docs,
-  release,
-  test
+  Docs,
+  Test
   // Public commands
   // ...
 ]

package/template/bin/cli/cmds/private/docs/{generate-api.js → GenerateAPI.js}

@@ -1,10 +1,31 @@
-/** @type {import('juisy/cli').Command} */
-export default new CLI.Command({
-  command: 'generate:api',
-  describe: 'Generate API docs from source code',
+export default class GenerateAPI extends CLI.Command {
+  /**
+   * The command signature
+   */
+  command = 'generate:api'
+
+  /**
+   * The command description
+   */
+  describe = 'Generate API docs from source code'
+
+  /**
+   * The command meta
+   */
+  meta = {
+    private: true
+  }
+
+  /**
+   * Command builder
+   */
   builder (cli) {
-    cli
-  },
+    return cli
+  }
+
+  /**
+   * Command handler
+   */
   async handler (argv) {
     // Utils
     const { $style, step, substep } = CLI.OutputUtils
@@ -19,4 +40,4 @@ export default new CLI.Command({
     this.log($style.yellow('You can use JSDoc or TypeDoc for example. See documentation'))
     this.log() // blank line
   }
-})
+}

package/template/bin/cli/cmds/private/docs/index.js

@@ -1,20 +1,39 @@
-import generateAPI from './generate-api.js'
+import GenerateAPI from './GenerateAPI.js'
 
-/** @type {import('juisy/cli').Command} */
-export default new CLI.Command({
-  command: 'docs <command>',
-  describe: 'Manage project documentation',
-  meta: {
+export default class Docs extends CLI.Command {
+  /**
+   * The command signature
+   */
+  command = 'docs <command>'
+
+  /**
+   * The command description
+   */
+  describe = 'Manage project documentation'
+
+  /**
+   * The command meta
+   */
+  meta = {
     private: true
-  },
+  }
+
+  /**
+   * Command builder
+   */
   builder (cli) {
     return cli
       .command([
         /**
          * Default command are automatically injected here...
          */
-        generateAPI
+        GenerateAPI
       ])
-  },
-  handler (argv) {}
-})
+      .demandCommand(1, 'Command is missing. See help to learn more.')
+  }
+
+  /**
+   * Command handler
+   */
+  async handler (argv) {}
+}

package/template/bin/cli/cmds/private/test.js

@@ -1,33 +1,48 @@
-/** @type {import('juisy/cli').Command} */
-export default new CLI.Command({
-  command: 'test',
-  describe: 'Run project tests',
-  meta: {
+export default class Test extends CLI.Command {
+  /**
+   * The command signature
+   */
+  command = 'test'
+
+  /**
+   * The command description
+   */
+  describe = 'Run project tests with vitest. Accepts all arguments of vitest command.'
+
+  /**
+   * The command meta
+   */
+  meta = {
     private: true
-  },
+  }
+
+  /**
+   * Command builder
+   */
   builder (cli) {
-    cli.option('watch', {
-      alias: 'w',
-      type: 'boolean',
-      default: false,
-      describe: 'Run vitest in watch mode'
-    })
-    cli.option('ui', {
-      type: 'boolean',
-      default: false,
-      describe: 'Launch vitest UI'
-    })
+    cli.strict(false) // to forward all arguments
     return cli
-  },
-  async handler (args) {
-    const watchMode = args.watch || args.ui
+  }
+
+  /**
+   * Command handler
+   */
+  async handler (argv) {
     const { run } = CLI.InterfaceUtils
+
+    // Forward arguments to vitest command
+    const testCommandArgs = this.getProcessArgv().slice(1)
+
     /**
      * Run tests
      */
-    await run('vitest', [
-      ...(watchMode ? [] : [ 'run' ]),
-      ...(args.ui ? [ '--ui' ] : [])
-    ], { stdio: 'inherit' })
+    await run('npx', [
+      'vitest',
+      ...testCommandArgs
+    ])
+      // Prevent an error be thrown when Ctrl+C is pressed in watch mode
+      .catch((err) => {
+        if (err.exitCode !== 130) throw err
+      })
   }
-})
+}

package/template/bin/cli/index.js

@@ -2,6 +2,8 @@
 
 'use strict'
 
-const cli = require('./cli')
+import cli from './cli.js'
 
-cli().parse(process.argv.slice(2))
+const argv = CLI.helpers.hideBin(process.argv)
+
+cli().parse(argv)