tshex-cli 1.0.14 → 1.0.16

package/build/main.js

@@ -3,13 +3,15 @@ import { program } from 'commander';
 import fs from 'node:fs';
 import path from 'node:path';
 function readPackageJson() {
-    return JSON.parse(fs.readFileSync(path.join(import.meta.dirname, '..', 'package.json'), 'utf-8'));
+    const filePath = path.join(import.meta.dirname, '..', 'package.json');
+    const fileContents = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(fileContents);
 }
 function executeCreateLib(templatesDir, libraryDir) {
     try {
         fs.cpSync(path.join(templatesDir, 'lib'), libraryDir, {
             recursive: true,
-            filter: (src) => !src.endsWith('.gitkeep')
+            filter: (src) => src.endsWith('.gitkeep') === false
         });
         console.log('Library created successfully');
     }
@@ -21,7 +23,7 @@ function executeCreateContext(templatesDir, contextDir) {
     try {
         fs.cpSync(path.join(templatesDir, 'ctx'), contextDir, {
             recursive: true,
-            filter: (src) => !src.endsWith('.gitkeep')
+            filter: (src) => src.endsWith('.gitkeep') === false
         });
         console.log('Context created successfully');
     }
@@ -29,15 +31,52 @@ function executeCreateContext(templatesDir, contextDir) {
         console.error(err);
     }
 }
+function copyDirectoryContents(sourceDir, destinationDir) {
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationPath = path.join(destinationDir, entry.name);
+        if (fs.existsSync(destinationPath) === false) {
+            fs.cpSync(sourcePath, destinationPath, {
+                recursive: true,
+                filter: (src) => src.endsWith('.gitkeep') === false
+            });
+        }
+    }
+}
+function executeCreateReactProject(templatesDir, projectDir) {
+    try {
+        fs.cpSync(path.join(templatesDir, 'react-project'), projectDir, {
+            recursive: true,
+            filter: (src) => src.endsWith('.gitkeep') === false
+        });
+        copyDirectoryContents(path.join(templatesDir, 'lib', 'shared'), path.join(projectDir, 'core', 'shared'));
+        console.log('React project created successfully');
+    }
+    catch (err) {
+        console.error(err);
+    }
+}
+function executeCreateReactContext(templatesDir, contextDir) {
+    try {
+        fs.cpSync(path.join(templatesDir, 'react-context'), contextDir, {
+            recursive: true,
+            filter: (src) => src.endsWith('.gitkeep') === false
+        });
+        console.log('React context created successfully');
+    }
+    catch (err) {
+        console.error(err);
+    }
+}
 function main(program) {
     const templatesDir = path.join(import.meta.dirname, '..', 'templates');
     const options = program.opts();
     let targetDir = path.resolve(options.dir ?? process.cwd());
     if (Object.keys(options).length === 0) {
         program.help();
-        return;
     }
-    if (!fs.existsSync(targetDir)) {
+    if (fs.existsSync(targetDir) === false) {
         fs.mkdirSync(targetDir, { recursive: true });
     }
     if (options.lib !== undefined) {
@@ -48,6 +87,14 @@ function main(program) {
         targetDir = path.join(targetDir, options.ctx);
         executeCreateContext(templatesDir, targetDir);
     }
+    if (options.reactProject !== undefined) {
+        targetDir = path.join(targetDir, options.reactProject);
+        executeCreateReactProject(templatesDir, targetDir);
+    }
+    if (options.reactContext !== undefined) {
+        targetDir = path.join(targetDir, options.reactContext);
+        executeCreateReactContext(templatesDir, targetDir);
+    }
 }
 const packageJson = readPackageJson();
 program
@@ -56,5 +103,7 @@ program
     .option('--lib <name>', "creates a new library with it's shared directory")
     .option('--ctx <name>', 'creates a new context')
     .option('--dir <path>', 'sets the directory to create the new item')
+    .option('--react-project <name>', 'creates a new React project')
+    .option('--react-context <name>', 'creates a new React context')
     .parse(process.argv);
 main(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "author": "https://github.com/virtualitems/",
   "description": "Typescript Hexagonal Architecture CLI",
   "type": "module",

package/readme.md

@@ -4,15 +4,11 @@ This CLI will help you to generate a hexagonal architecture structure.
 
 # Why?
 
-Hexagonal architecture is a software design pattern that separates the internal domain of the application from the external dependencies.. This separation is achieved by dividing the application into layers. Each layer has a specific responsibility and interacts with the other layers in a specific way.
+Hexagonal architecture is a software design pattern that separates the internal domain of the application from the external dependencies. This separation is achieved by dividing the application into layers. Each layer has a specific responsibility and interacts with the other layers in a specific way.
 
-Because what we are trying to achieve is a separation between the domain code and the installed dependencies, a Hexagonal Architecture Framework is a step in the opposite direction, as it couples the domain code with the framework. This is why we need a tool to help us to create the structure with our own codebase.
+The goal is to separate the domain code from installed dependencies. A Hexagonal Architecture _framework_ would work against that goal, since it couples the domain code to the framework itself. That is why this CLI exists: it scaffolds the structure for you, using your own codebase instead of a framework.
 
-# Usage example
-
-https://github.com/virtualitems/tshex-cli
-
-# Note!!!
+# Note
 
 This tool and its templates are in constant development, so be aware that some changes may occur and be careful when updating the tool.
 
@@ -20,57 +16,214 @@ If you have any suggestions or improvements, please let me know.
 
 https://github.com/virtualitems/tshex-cli/issues
 
-# Installation
+# Getting started
+
+`tshex` scaffolds folders and files for a hexagonal architecture project. It does not write business logic for you; it only generates the structure, so you can fill it in with your own code.
+
+There are four things you can generate:
+
+- A **library** (`--lib`): the shared foundation of a project. It contains the domain and application contracts (entities, value objects, services, etc.) that the rest of the code depends on.
+- A **context** (`--ctx`): a specific business area (e.g. `users`, `billing`, `orders`). It contains the `domain/`, `application/`, and `adapters/` folders where you implement that area's logic.
+- A **React project** (`--react-project`): a full React-oriented hexagonal structure with `core/`, `dom-client/`, `dom-server/`, and `native/` folders.
+- A **React context** (`--react-context`): a React-ready context scaffold.
+
+A typical project has one library and one or more contexts inside it.
+
+## Install
+
+Install the CLI globally:
 
 ```bash
 npm install -g tshex-cli
 ```
 
-# Usage
+Check the installation:
+
+```bash
+tshex --version
+```
+
+Show the command options:
 
-> Remember to replace placeholders `<...>` with the actual data.
->
+```bash
+tshex --help
+```
 
-## Getting started
+## Usage
 
 ```bash
-tshex --lib <library-name> --ctx <context-name>
+tshex [--lib <name>] [--ctx <name>] [--react-project <name>] [--react-context <name>] [--dir <path>]
 ```
 
-## Help
+| Option         | Purpose                                                            |
+| -------------- | ------------------------------------------------------------------- |
+| `--lib <name>` | Generate a library called `<name>`, based on `templates/lib`.       |
+| `--ctx <name>` | Generate a context called `<name>`, based on `templates/ctx`.       |
+| `--react-project <name>` | Generate a React project called `<name>`, based on `templates/react-project` and `templates/lib/shared`. |
+| `--react-context <name>` | Generate a React context called `<name>`, based on `templates/react-context`. |
+| `--dir <path>` | Parent directory where the library/context will be created. Defaults to the current directory. |
+| `--help`       | Show the command options.                                           |
+| `--version`    | Show the installed version.                                         |
+
+`--lib`, `--ctx`, `--react-project`, and `--react-context` can be used together in a single command. Running `tshex` without any options just prints the help text — it does not generate anything.
+
+## Create a library
+
+Use this when you are starting a new project and need the shared contracts that the rest of your code will build on:
 
 ```bash
-tshex -h
+tshex --lib core
+```
 
-tshex --help
+This generates a `core/` folder in the current directory:
+
+```text
+core/
+├── index.d.ts
+├── main.ts
+└── shared/
+    ├── application/
+    │   ├── databases.ts
+    │   ├── events.ts
+    │   ├── http.ts
+    │   ├── loggers.ts
+    │   └── services.ts
+    └── domain/
+        ├── aggregates.ts
+        ├── entities.ts
+        ├── errors.ts
+        └── value-objects.ts
+```
+
+What each file is for:
+
+| File               | Purpose                                       |
+| ------------------ | --------------------------------------------- |
+| `index.d.ts`       | Declare library types.                        |
+| `main.ts`          | Export the library API.                       |
+| `entities.ts`      | Define entity contracts.                      |
+| `value-objects.ts` | Define value objects and validation.          |
+| `aggregates.ts`    | Define aggregate contracts.                   |
+| `errors.ts`        | Define domain errors.                         |
+| `services.ts`      | Define application service contracts.         |
+| `databases.ts`     | Define data manager and repository contracts. |
+| `events.ts`        | Define event contracts.                       |
+| `http.ts`          | Define HTTP response contracts.               |
+| `loggers.ts`       | Define logger contracts.                      |
+
+`main.ts` is generated with a placeholder `throw new Error('Not implemented yet')`, so the library fails loudly if you try to use it before filling it in. To start using it, open `main.ts`, remove that line, and export your own code, built on top of the shared contracts. For example:
+
+```ts
+export { Entity } from './shared/domain/entities.js'
+export { ValueObject, Email } from './shared/domain/value-objects.js'
+
+class User extends Entity {
+    constructor(public readonly email: Email) {
+        super()
+    }
+}
 ```
 
-## Create a new library
+## Create a context
+
+Use this to scaffold a specific business area, such as `users`, inside an existing library (or on its own):
 
 ```bash
-tshex --lib <name>
+tshex --ctx users
+```
+
+This generates a `users/` folder in the current directory:
+
+```text
+users/
+├── adapters/
+├── application/
+├── domain/
+└── index.ts
 ```
 
-## Create a new context
+What each part is for:
+
+| Path           | Purpose                                                         |
+| -------------- | ---------------------------------------------------------------- |
+| `domain/`      | Entities, value objects, aggregates, and domain errors.          |
+| `application/` | Use cases, services, DTOs, and contracts.                        |
+| `adapters/`    | Database, HTTP, event, file, and service implementations.        |
+| `index.ts`     | Export or compose the context's public API.                      |
+
+## Choose the destination folder
+
+By default, `tshex` creates files in your current directory. Use `--dir` to choose a different parent directory instead.
+
+Create a library inside `./src`:
 
 ```bash
-tshex --ctx <name>
+tshex --lib core --dir ./src
 ```
 
-## Create a new class
+This generates the library at:
+
+```text
+./src/core
+```
+
+Create a context inside that library:
 
 ```bash
-tshex --cls <name>
+tshex --ctx users --dir ./src/core
+```
+
+This generates the context at:
+
+```text
+./src/core/users
 ```
 
-## Create a new react functional component
+You can also use an absolute path:
 
 ```bash
-tshex --rfc <name>
+tshex --ctx users --dir /workspace/project/src
 ```
 
-## Set the directory to create the new items
+## Create a library and a context together
+
+You can generate both in a single command. `tshex` creates the library first, then creates the context inside it:
 
 ```bash
-tshex --lib <lib-name> --ctx <ctx-name> --dir <path>
-```
+tshex --dir ./src --lib core --ctx users
+```
+
+Result:
+
+```text
+src/
+└── core/
+    ├── index.d.ts
+    ├── main.ts
+    ├── shared/
+    └── users/
+        ├── adapters/
+        ├── application/
+        ├── domain/
+        └── index.ts
+```
+
+    ## Create a React project
+
+    Use this when you want the React-specific project scaffold with the shared `core/shared` contracts copied from the library template:
+
+    ```bash
+    tshex --react-project app
+    ```
+
+    This generates a `app/` folder in the current directory.
+
+    ## Create a React context
+
+    Use this when you want only the React context scaffold:
+
+    ```bash
+    tshex --react-context users
+    ```
+
+    This generates a `users/` folder in the current directory.

package/source/main.ts

@@ -12,19 +12,16 @@ import path from 'node:path'
 // FUNCTIONS
 
 function readPackageJson() {
-    return JSON.parse(
-        fs.readFileSync(
-            path.join(import.meta.dirname, '..', 'package.json'),
-            'utf-8'
-        )
-    )
+    const filePath = path.join(import.meta.dirname, '..', 'package.json')
+    const fileContents = fs.readFileSync(filePath, 'utf-8')
+    return JSON.parse(fileContents)
 }
 
 function executeCreateLib(templatesDir: string, libraryDir: string) {
     try {
         fs.cpSync(path.join(templatesDir, 'lib'), libraryDir, {
             recursive: true,
-            filter: (src) => !src.endsWith('.gitkeep')
+            filter: (src) => src.endsWith('.gitkeep') === false
         })
         console.log('Library created successfully')
     } catch (err) {
@@ -36,7 +33,7 @@ function executeCreateContext(templatesDir: string, contextDir: string) {
     try {
         fs.cpSync(path.join(templatesDir, 'ctx'), contextDir, {
             recursive: true,
-            filter: (src) => !src.endsWith('.gitkeep')
+            filter: (src) => src.endsWith('.gitkeep') === false
         })
         console.log('Context created successfully')
     } catch (err) {
@@ -44,6 +41,49 @@ function executeCreateContext(templatesDir: string, contextDir: string) {
     }
 }
 
+function copyDirectoryContents(sourceDir: string, destinationDir: string) {
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name)
+        const destinationPath = path.join(destinationDir, entry.name)
+
+        if (fs.existsSync(destinationPath) === false) {
+            fs.cpSync(sourcePath, destinationPath, {
+                recursive: true,
+                filter: (src) => src.endsWith('.gitkeep') === false
+            })
+        }
+    }
+}
+
+function executeCreateReactProject(templatesDir: string, projectDir: string) {
+    try {
+        fs.cpSync(path.join(templatesDir, 'react-project'), projectDir, {
+            recursive: true,
+            filter: (src) => src.endsWith('.gitkeep') === false
+        })
+
+        copyDirectoryContents(path.join(templatesDir, 'lib', 'shared'), path.join(projectDir, 'core', 'shared'))
+
+        console.log('React project created successfully')
+    } catch (err) {
+        console.error(err)
+    }
+}
+
+function executeCreateReactContext(templatesDir: string, contextDir: string) {
+    try {
+        fs.cpSync(path.join(templatesDir, 'react-context'), contextDir, {
+            recursive: true,
+            filter: (src) => src.endsWith('.gitkeep') === false
+        })
+        console.log('React context created successfully')
+    } catch (err) {
+        console.error(err)
+    }
+}
+
 function main(program: typeof import('commander').program) {
     const templatesDir = path.join(import.meta.dirname, '..', 'templates')
 
@@ -53,10 +93,9 @@ function main(program: typeof import('commander').program) {
 
     if (Object.keys(options).length === 0) {
         program.help()
-        return
     }
 
-    if (!fs.existsSync(targetDir)) {
+    if (fs.existsSync(targetDir) === false) {
         fs.mkdirSync(targetDir, { recursive: true })
     }
 
@@ -69,6 +108,16 @@ function main(program: typeof import('commander').program) {
         targetDir = path.join(targetDir, options.ctx)
         executeCreateContext(templatesDir, targetDir)
     }
+
+    if (options.reactProject !== undefined) {
+        targetDir = path.join(targetDir, options.reactProject)
+        executeCreateReactProject(templatesDir, targetDir)
+    }
+
+    if (options.reactContext !== undefined) {
+        targetDir = path.join(targetDir, options.reactContext)
+        executeCreateReactContext(templatesDir, targetDir)
+    }
 }
 
 const packageJson = readPackageJson()
@@ -79,6 +128,8 @@ program
     .option('--lib <name>', "creates a new library with it's shared directory")
     .option('--ctx <name>', 'creates a new context')
     .option('--dir <path>', 'sets the directory to create the new item')
+    .option('--react-project <name>', 'creates a new React project')
+    .option('--react-context <name>', 'creates a new React context')
     .parse(process.argv)
 
 main(program)

package/templates/ctx/index.ts

@@ -1,9 +0,0 @@
-// Ports layer
-
-// Adapters layer
-
-// Application layer
-
-// Domain layer
-
-// Constants

package/templates/react-project/dom-client/context/Example.tsx

@@ -0,0 +1,11 @@
+type Props = {
+  children?: React.ReactNode
+}
+
+/**
+ * @description Example component that renders its children.
+ */
+export default function Example(props: Props) {
+  const { children } = props
+  return children
+}

package/templates/react-project/dom-server/context/Example.tsx

@@ -0,0 +1,11 @@
+type Props = {
+  children?: React.ReactNode
+}
+
+/**
+ * @description Example component that renders its children.
+ */
+export default function Example(props: Props) {
+  const { children } = props
+  return children
+}

package/templates/react-project/index.d.ts

@@ -0,0 +1 @@
+type Generic<T=unknown> = Record<string, T>;

package/templates/react-project/native/context/Example.tsx

@@ -0,0 +1,11 @@
+type Props = {
+  children?: React.ReactNode
+}
+
+/**
+ * @description Example component that renders its children.
+ */
+export default function Example(props: Props) {
+  const { children } = props
+  return children
+}