tshex-cli 1.0.22 → 1.0.23

package/build/main.js

@@ -2,18 +2,20 @@
 import { program } from 'commander';
 import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
 function readPackageJson() {
     const filePath = path.join(import.meta.dirname, '..', 'package.json');
     const fileContents = fs.readFileSync(filePath, 'utf-8');
     return JSON.parse(fileContents);
 }
-function executeCreateLib(templatesDir, libraryDir) {
+function executeCreateProject(templatesDir, projectDir) {
     try {
-        fs.cpSync(path.join(templatesDir, 'lib'), libraryDir, {
+        fs.cpSync(path.join(templatesDir, 'lib'), projectDir, {
             recursive: true,
             filter: (src) => src.endsWith('.gitkeep') === false
         });
-        console.log('Library created successfully');
+        console.log('Project created successfully');
     }
     catch (err) {
         console.error(err);
@@ -43,7 +45,53 @@ function executeCreateReactContext(templatesDir, contextDir) {
         console.error(err);
     }
 }
-function main(program) {
+function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSourceDir) {
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+    if (fs.existsSync(destinationDir) === false) {
+        fs.mkdirSync(destinationDir, { recursive: true });
+    }
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationPath = path.join(destinationDir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'shared') {
+                continue;
+            }
+            if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
+                continue;
+            }
+            if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
+                continue;
+            }
+            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir);
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {
+            fs.writeFileSync(destinationPath, fileContents);
+        }
+    }
+}
+async function ensureTestsDirectory(testsRootDir) {
+    if (fs.existsSync(testsRootDir)) {
+        if (fs.statSync(testsRootDir).isDirectory() === false) {
+            throw new Error(`Tests path exists but is not a directory: ${testsRootDir}`);
+        }
+        return;
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `);
+        if (answer.trim().toLowerCase() !== 'y') {
+            return false;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    fs.mkdirSync(testsRootDir, { recursive: true });
+    return true;
+}
+async function main(program) {
     const templatesDir = path.join(import.meta.dirname, '..', 'templates');
     const options = program.opts();
     let targetDir = path.resolve(options.dir ?? process.cwd());
@@ -53,15 +101,15 @@ function main(program) {
     if (fs.existsSync(targetDir) === false) {
         fs.mkdirSync(targetDir, { recursive: true });
     }
-    if (options.lib !== undefined) {
-        targetDir = path.join(targetDir, options.lib);
-        executeCreateLib(templatesDir, targetDir);
+    if (options.project !== undefined) {
+        targetDir = path.join(targetDir, options.project);
+        executeCreateProject(templatesDir, targetDir);
     }
-    if (options.react === true && options.ctx === undefined) {
-        program.error('Option --react requires --ctx <name>');
+    if (options.react === true && options.context === undefined) {
+        program.error('Option --react requires --context <name>');
     }
-    if (options.ctx !== undefined) {
-        targetDir = path.join(targetDir, options.ctx);
+    if (options.context !== undefined) {
+        targetDir = path.join(targetDir, options.context);
         if (options.react === true) {
             executeCreateReactContext(templatesDir, targetDir);
         }
@@ -69,14 +117,43 @@ function main(program) {
             executeCreateContext(templatesDir, targetDir);
         }
     }
+    if (options.tests !== undefined) {
+        const sourceDir = path.resolve(options.tests);
+        const testsTemplateFile = path.join(templatesDir, 'tests', 'content.ts');
+        if (fs.existsSync(sourceDir) === false) {
+            program.error(`Tests source directory does not exist: ${sourceDir}`);
+        }
+        if (fs.statSync(sourceDir).isDirectory() === false) {
+            program.error(`Tests source path is not a directory: ${sourceDir}`);
+        }
+        if (fs.existsSync(testsTemplateFile) === false) {
+            program.error(`Tests template file does not exist: ${testsTemplateFile}`);
+        }
+        const testsTemplateContents = fs.readFileSync(testsTemplateFile, 'utf-8');
+        const testsRootDir = path.join(targetDir, 'tests');
+        const testsDirectoryCreated = await ensureTestsDirectory(testsRootDir);
+        if (testsDirectoryCreated === false) {
+            program.error('Tests directory creation cancelled');
+        }
+        const testsDir = path.join(testsRootDir, path.basename(sourceDir));
+        if (testsDir === sourceDir) {
+            program.error('Tests destination directory cannot be the same as the source directory');
+        }
+        executeCreateTests(sourceDir, testsDir, testsTemplateContents, testsRootDir);
+        console.log('Tests structure created successfully');
+    }
 }
 const packageJson = readPackageJson();
 program
     .name('tshex')
     .version(packageJson.version)
-    .option('--lib <name>', "creates a new library with it's shared directory")
-    .option('--ctx <name>', 'creates a new context')
-    .option('-R, --react', 'creates a React context with --ctx')
+    .option('-P, --project <name>', "creates a new project with it's shared directory")
+    .option('-C, --context <name>', 'creates a new context')
+    .option('-R, --react', 'creates a React context with --context')
+    .option('-T, --tests <path>', 'creates a .ts tests structure from an existing directory')
     .option('--dir <path>', 'sets the directory to create the new item')
     .parse(process.argv);
-main(program);
+void main(program).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    program.error(message);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",

package/{README.md → readme.md}

@@ -1,8 +1,8 @@
 # Hexagonal Architecture CLI `tshex-cli`
 
-`tshex-cli` creates the base structure of a library organized by contexts. The structure groups shared contracts, domain concepts, use cases, and adapters into directories with defined responsibilities.
+`tshex-cli` creates the base structure of a project organized by contexts. The structure groups shared contracts, domain concepts, use cases, and adapters into directories with defined responsibilities.
 
-In this guide, we will build a library named `core` with a context named `users`. The walkthrough starts with the CLI and then explains the purpose of the generated components.
+In this guide, we will build a project named `core` with a context named `users`. The walkthrough starts with the CLI and then explains the purpose of the generated components.
 
 The examples in this guide are intentionally simple. They are designed to show the responsibility of each component, not to cover real infrastructure or production scenarios.
 
@@ -38,32 +38,44 @@ View the available commands and options with:
 npx tshex --help
 ```
 
-### Create a library
+### Create a project
 
-The `--lib` option receives the name of the library's root directory:
+The `--project` option receives the name of the project's root directory:
 
 ```bash
-npx tshex --lib core
+npx tshex --project core
 ```
 
-In this example, `core` will contain the shared code, the contexts, and the library's main implementation.
+You can also use the short form:
+
+```bash
+npx tshex -P core
+```
+
+In this example, `core` will contain the shared code, the contexts, and the project's main implementation.
 
 ### Create a context
 
-The `--ctx` option receives the context name:
+The `--context` option receives the context name:
+
+```bash
+npx tshex --context users
+```
+
+You can also use the short form:
 
 ```bash
-npx tshex --ctx users
+npx tshex -C users
 ```
 
 A context groups the rules and operations of an application capability. `users`, `sales`, `billing`, and `inventory` are examples of contexts.
 
-### Create the library and the first context
+### Create the project and the first context
 
 You can generate both components in a single execution:
 
 ```bash
-npx tshex --lib core --ctx users
+npx tshex --project core --context users
 ```
 
 The command creates this structure:
@@ -100,15 +112,15 @@ core/
 The `--dir` option specifies the directory from which the structure is created:
 
 ```bash
-npx tshex --dir ./src --lib core --ctx users
+npx tshex --dir ./src --project core --context users
 ```
 
-The example library is created at `src/core`.
+The example project is created at `src/core`.
 
-To add a context to an existing library, use the library as the destination directory:
+To add a context to an existing project, use the project as the destination directory:
 
 ```bash
-npx tshex --dir ./core --ctx billing
+npx tshex --dir ./core --context billing
 ```
 
 The context is created at `core/billing`.
@@ -122,13 +134,13 @@ A React context is a consumer by nature. It does not provide a hexagonal capabil
 Use this mode when the generated context will call APIs, validate interface data, expose hooks, compose components, and localize messages.
 
 ```bash
-npx tshex --ctx users --react
+npx tshex --context users --react
 ```
 
 You can also use its short form:
 
 ```bash
-npx tshex --ctx users -R
+npx tshex -C users -R
 ```
 
 The command creates this structure:
@@ -158,14 +170,61 @@ Each directory represents a consumption adapter or a resource used by those adap
 
 This layout is intentionally different from the default context template. The standard context separates `domain`, `application`, and `adapters` because it models and provides a capability. The React context generated with `--react` assumes the opposite role: it always consumes capabilities and groups the code around the adapters required by that consumption.
 
+### Create a tests structure
+
+The `--tests` option receives a source directory and creates a matching tests structure.
+
+```bash
+npx tshex --tests ./core
+```
+
+You can also use the short form:
+
+```bash
+npx tshex -T ./core
+```
+
+The command creates the output inside a `tests/` directory. If `tests/` does not exist, the CLI asks whether it should be created.
+
+By default, the `tests/` directory is resolved from the current execution directory:
+
+```bash
+npx tshex -T ./core
+```
+
+This generates a structure like this:
+
+```text
+tests/
+`-- core/
+    |-- users/
+    |   |-- adapters/
+    |   |-- application/
+    |   |   `-- create-user.ts
+    |   `-- domain/
+    `-- billing/
+        |-- application/
+        `-- domain/
+```
+
+To choose another base directory for `tests/`, combine `--tests` with `--dir`:
+
+```bash
+npx tshex -T ./core --dir ./output
+```
+
+That command creates or reuses `./output/tests/`.
+
+This command helps you prepare a tests workspace that follows the shape of your source directory while fitting naturally into the place where you are working. You can use it in the current directory for a quick setup, or combine it with `--dir` when you want the tests structure to be created somewhere else. If `tests/` already contains content, the command continues working with what is already there instead of interrupting your flow.
+
 ## Documentation index
 
 From this point on, the guide is split into dedicated documents under `docs/`.
 
 ### General
 
-- [Library structure](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-structure.md)
-- [Library types](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-types.md)
+- [Project structure](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-structure.md)
+- [Project types](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-types.md)
 - [Context ports](https://github.com/virtualitems/tshex-cli/blob/main/docs/context-ports.md)
 - [Generated file reference](https://github.com/virtualitems/tshex-cli/blob/main/docs/generated-file-reference.md)
 

package/source/main.ts

@@ -8,6 +8,8 @@ import { program } from 'commander'
 
 import fs from 'node:fs'
 import path from 'node:path'
+import readline from 'node:readline/promises'
+import { stdin as input, stdout as output } from 'node:process'
 
 // FUNCTIONS
 
@@ -17,13 +19,13 @@ function readPackageJson() {
     return JSON.parse(fileContents)
 }
 
-function executeCreateLib(templatesDir: string, libraryDir: string) {
+function executeCreateProject(templatesDir: string, projectDir: string) {
     try {
-        fs.cpSync(path.join(templatesDir, 'lib'), libraryDir, {
+        fs.cpSync(path.join(templatesDir, 'lib'), projectDir, {
             recursive: true,
             filter: (src) => src.endsWith('.gitkeep') === false
         })
-        console.log('Library created successfully')
+        console.log('Project created successfully')
     } catch (err) {
         console.error(err)
     }
@@ -53,7 +55,66 @@ function executeCreateReactContext(templatesDir: string, contextDir: string) {
     }
 }
 
-function main(program: typeof import('commander').program) {
+function executeCreateTests(sourceDir: string, destinationDir: string, fileContents: string, ignoredSourceDir?: string) {
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true })
+
+    if (fs.existsSync(destinationDir) === false) {
+        fs.mkdirSync(destinationDir, { recursive: true })
+    }
+
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name)
+        const destinationPath = path.join(destinationDir, entry.name)
+
+        if (entry.isDirectory()) {
+            if (entry.name === 'shared') {
+                continue
+            }
+
+            if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
+                continue
+            }
+
+            if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
+                continue
+            }
+
+            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir)
+            continue
+        }
+
+        if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {
+            fs.writeFileSync(destinationPath, fileContents)
+        }
+    }
+}
+
+async function ensureTestsDirectory(testsRootDir: string) {
+    if (fs.existsSync(testsRootDir)) {
+        if (fs.statSync(testsRootDir).isDirectory() === false) {
+            throw new Error(`Tests path exists but is not a directory: ${testsRootDir}`)
+        }
+
+        return
+    }
+
+    const rl = readline.createInterface({ input, output })
+
+    try {
+        const answer = await rl.question(`Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `)
+
+        if (answer.trim().toLowerCase() !== 'y') {
+            return false
+        }
+    } finally {
+        rl.close()
+    }
+
+    fs.mkdirSync(testsRootDir, { recursive: true })
+    return true
+}
+
+async function main(program: typeof import('commander').program) {
     const templatesDir = path.join(import.meta.dirname, '..', 'templates')
 
     const options = program.opts()
@@ -68,17 +129,17 @@ function main(program: typeof import('commander').program) {
         fs.mkdirSync(targetDir, { recursive: true })
     }
 
-    if (options.lib !== undefined) {
-        targetDir = path.join(targetDir, options.lib)
-        executeCreateLib(templatesDir, targetDir)
+    if (options.project !== undefined) {
+        targetDir = path.join(targetDir, options.project)
+        executeCreateProject(templatesDir, targetDir)
     }
 
-    if (options.react === true && options.ctx === undefined) {
-        program.error('Option --react requires --ctx <name>')
+    if (options.react === true && options.context === undefined) {
+        program.error('Option --react requires --context <name>')
     }
 
-    if (options.ctx !== undefined) {
-        targetDir = path.join(targetDir, options.ctx)
+    if (options.context !== undefined) {
+        targetDir = path.join(targetDir, options.context)
 
         if (options.react === true) {
             executeCreateReactContext(templatesDir, targetDir)
@@ -86,6 +147,41 @@ function main(program: typeof import('commander').program) {
             executeCreateContext(templatesDir, targetDir)
         }
     }
+
+    if (options.tests !== undefined) {
+        const sourceDir = path.resolve(options.tests)
+        const testsTemplateFile = path.join(templatesDir, 'tests', 'content.ts')
+
+        if (fs.existsSync(sourceDir) === false) {
+            program.error(`Tests source directory does not exist: ${sourceDir}`)
+        }
+
+        if (fs.statSync(sourceDir).isDirectory() === false) {
+            program.error(`Tests source path is not a directory: ${sourceDir}`)
+        }
+
+        if (fs.existsSync(testsTemplateFile) === false) {
+            program.error(`Tests template file does not exist: ${testsTemplateFile}`)
+        }
+
+        const testsTemplateContents = fs.readFileSync(testsTemplateFile, 'utf-8')
+
+        const testsRootDir = path.join(targetDir, 'tests')
+        const testsDirectoryCreated = await ensureTestsDirectory(testsRootDir)
+
+        if (testsDirectoryCreated === false) {
+            program.error('Tests directory creation cancelled')
+        }
+
+        const testsDir = path.join(testsRootDir, path.basename(sourceDir))
+
+        if (testsDir === sourceDir) {
+            program.error('Tests destination directory cannot be the same as the source directory')
+        }
+
+        executeCreateTests(sourceDir, testsDir, testsTemplateContents, testsRootDir)
+        console.log('Tests structure created successfully')
+    }
 }
 
 const packageJson = readPackageJson()
@@ -93,10 +189,14 @@ const packageJson = readPackageJson()
 program
     .name('tshex')
     .version(packageJson.version)
-    .option('--lib <name>', "creates a new library with it's shared directory")
-    .option('--ctx <name>', 'creates a new context')
-    .option('-R, --react', 'creates a React context with --ctx')
+    .option('-P, --project <name>', "creates a new project with it's shared directory")
+    .option('-C, --context <name>', 'creates a new context')
+    .option('-R, --react', 'creates a React context with --context')
+    .option('-T, --tests <path>', 'creates a .ts tests structure from an existing directory')
     .option('--dir <path>', 'sets the directory to create the new item')
     .parse(process.argv)
 
-main(program)
+void main(program).catch((err: unknown) => {
+    const message = err instanceof Error ? err.message : String(err)
+    program.error(message)
+})

package/templates/tests/content.ts

@@ -0,0 +1,16 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+describe('math', () => {
+    test('sum', () => {
+        // Arrange
+        const a = 2
+        const b = 3
+
+        // Act
+        const result = a * b
+
+        // Assert
+        assert.strictEqual(result, 6)
+    })
+})