tshex-cli 1.0.22 → 1.0.24

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/docs/context-ports.md

@@ -1,12 +1,17 @@
 ### Context Ports
 
 Context ports define the communication available at a context boundary.
-They describe what data enters the context, what data leaves it, and which
-operation another system can invoke.
+They describe which concrete capability a context exposes, what data enters
+that capability, and what data it returns.
 
-Ports are used to keep communication contracts explicit. An adapter imports a
-port, implements that contract, and translates the external interaction into an
-application process.
+In practice a port is usually not just an abstraction or a contract. It is a
+specific boundary element of the system with identity: a command handler, a
+query entry point, an event consumer, a published endpoint, or another concrete
+interaction mechanism that exists because the running system exposes it.
+
+Types and interfaces still matter, but they are secondary. Their role is to
+make the port explicit. The main concern is the port as a real executable
+surface that another actor can call or observe.
 
 > **Hint**
 > The generated `example-ports.ts` file is only a placeholder. Replace it when
@@ -22,12 +27,12 @@ export function example(): void {
 }
 ```
 
-This placeholder does not define a real contract yet. Its purpose is to mark
-the context root as the place where boundary-facing types and interfaces live.
+This placeholder does not define a real port yet. Its purpose is to mark the
+context root as the place where boundary-facing capabilities are declared.
 
-#### First Contract
+#### First Port
 
-In the following example we replace the placeholder with a minimal contract for
+In the following example we replace the placeholder with a concrete port for
 creating a user.
 
 ```ts title="users/example-ports.ts"
@@ -53,16 +58,17 @@ export interface CreateUserPort {
 ```
 
 `CreateUserRequest` defines the incoming payload. `CreateUserResponse` defines
-the outgoing payload. `CreateUserPort` exposes the operation available at the
-boundary.
+the outgoing payload. `CreateUserPort` names the concrete capability exposed at
+the boundary: creating a user.
 
-This contract says nothing about HTTP, queues, or databases. It only declares
-the shape of the communication.
+This definition does not commit to HTTP, queues, or databases. It focuses on
+the interaction the context makes available. The transport can vary, but the
+port remains the same identifiable boundary capability.
 
 #### Adapter Implementation
 
-Now that the port exists, an adapter can implement it and delegate the work to
-an application service.
+Now that the port exists, the system can materialize it through an adapter and
+delegate the work to an application service.
 
 ```ts title="users/adapters/create-user.ts"
 import type {
@@ -96,22 +102,27 @@ export class CreateUserAdapter implements CreateUserPort {
 }
 ```
 
-The adapter implements `CreateUserPort`, so it must provide `create()`. Inside
-that method it translates the root-level request into the input expected by the
-application service.
+The adapter implements `CreateUserPort`, so it materializes the boundary
+capability and provides `create()`. Inside that method it translates the
+root-level request into the input expected by the application service.
 
 This is the normal flow of the generated structure:
 
-```text
-external system -> adapter -> application -> domain
+```mermaid
+flowchart LR
+    external["External system"] --> adapter[Adapter]
+    adapter --> port[Port]
+    port --> application[Application]
+    application --> domain[Domain]
 ```
 
-The port belongs to the boundary. The adapter materializes the boundary. The
-application process executes the use case.
+The port belongs to the boundary because it is part of what the context really
+exposes. The adapter is one implementation path for that port. The application
+process executes the use case and uses domain capabilities.
 
 #### Multiple Port Files
 
-As the context grows, you can keep several contracts at the context root.
+As the context grows, you can keep several ports at the context root.
 
 ```ts title="users/list-users.ts"
 export type ListUsersRequest = {
@@ -131,35 +142,38 @@ export interface ListUsersPort {
 }
 ```
 
-An adapter can then import the contract from the file that owns it.
+An adapter can then import the port definition from the file that owns it.
 
-This arrangement is useful when one context exposes several independent forms
-of communication. A single file works well for a small context. Separate files
-become easier to maintain when responsibilities start to diverge.
+This arrangement is useful when one context exposes several independent
+capabilities. A single file works well for a small context. Separate files
+become easier to maintain when each port has its own identity and
+responsibility.
 
 > **Warning**
-> A port should define communication, not domain behavior. Avoid moving entity
-> rules, repository logic, or infrastructure details into the port file.
+> A port should define an exposed boundary capability, not domain internals.
+> Avoid moving entity rules, repository logic, or infrastructure details into
+> the port file.
 
 #### Example Layout
 
 The following structure keeps ports at the root while the implementation lives
 in the generated folders.
 
-```text
-users/
-├── example-ports.ts
-├── list-users.ts
-├── adapters/
-├── application/
-└── domain/
+```mermaid
+flowchart TD
+    users["users/"] --> examplePorts["example-ports.ts"]
+    users --> listUsers["list-users.ts"]
+    users --> adapters["adapters/"]
+    users --> application["application/"]
+    users --> domain["domain/"]
 ```
 
 This layout keeps the context boundary visible from the top level. It also
-reduces coupling between adapters because they all import the same contracts.
+reduces coupling between adapters because they all import the same port
+definitions for the capabilities the context exposes.
 
 #### Next Step
 
-After defining a port, implement the corresponding adapter and connect it to an
-application service. The surrounding structure is described in
-`library-structure.md`.
+After defining a port, implement the corresponding executable path and connect
+it to an application service. The surrounding structure is described in
+`library-structure.md`.

package/docs/library-structure.md

@@ -13,11 +13,12 @@ language, rules, and operations.
 
 The root contains the entry points of the generated library.
 
-```text
-index.d.ts
-main.ts
-shared/
-users/
+```mermaid
+flowchart TD
+    root["Library root"] --> index["index.d.ts"]
+    root --> main["main.ts"]
+    root --> shared["shared/"]
+    root --> users["users/"]
 ```
 
 `index.d.ts` defines root-level types. `main.ts` starts as a placeholder for
@@ -29,10 +30,10 @@ or more context directories.
 The `shared` directory contains concepts that can be reused by multiple
 contexts.
 
-```text
-shared/
-├── application/
-└── domain/
+```mermaid
+flowchart TD
+    shared["shared/"] --> application["application/"]
+    shared --> domain["domain/"]
 ```
 
 `shared/domain` contains modeling foundations such as value objects, entities,
@@ -47,11 +48,12 @@ Until then, keep it close to the context that owns the rule.
 A context groups the vocabulary, rules, and operations of one application
 capability.
 
-```text
-users/
-billing/
-inventory/
-sales/
+```mermaid
+flowchart TD
+    contexts["Contexts"] --> users["users/"]
+    contexts --> billing["billing/"]
+    contexts --> inventory["inventory/"]
+    contexts --> sales["sales/"]
 ```
 
 Each context can evolve independently while still reusing the abstractions from
@@ -62,12 +64,12 @@ the system.
 
 Every generated context starts with the same internal structure.
 
-```text
-users/
-├── example-ports.ts
-├── adapters/
-├── application/
-└── domain/
+```mermaid
+flowchart TD
+    users["users/"] --> ports["example-ports.ts"]
+    users --> adapters["adapters/"]
+    users --> application["application/"]
+    users --> domain["domain/"]
 ```
 
 `example-ports.ts` is the root communication surface of the context.
@@ -123,14 +125,20 @@ split ports across several files. The detailed guidance for that layout lives in
 
 The normal dependency direction is the following:
 
-```text
-adapter -> port
-adapter -> application
-application -> domain
+```mermaid
+flowchart LR
+    adapter[Adapter] --> thirdParty["Third-party library"]
+    adapter --> port[Port]
+    port --> application[Application]
+    port --> domain[Domain]
+    application --> domain
 ```
 
 This direction keeps the core model isolated from transport and infrastructure
-details. The deeper a layer is, the less it should know about the outside.
+details. Adapters integrate with external libraries and context ports. Ports
+connect the context boundary to application processes or directly to domain
+capabilities when no application orchestration is needed. The deeper a layer
+is, the less it should know about the outside.
 
 > **Warning**
 > Avoid importing adapter-specific concerns into the domain layer. Once a domain
@@ -141,23 +149,23 @@ details. The deeper a layer is, the less it should know about the outside.
 
 The following diagram shows the runtime flow of a typical operation.
 
-```text
-External system
-      |
-      v
-Port + adapter
-      |
-      v
-Application service
-      |
-      v
-Domain capability
+```mermaid
+flowchart TD
+    main["main.ts"] --> system["Own system"]
+    system --> application["Application services"]
+    application --> domain["Domain capabilities"]
+    system --> adapter[Adapters]
+    adapter --> port[Port]
+    adapter --> thirdParty["Third-party libraries"]
+    thirdParty --> external["External systems"]
 ```
 
-The adapter receives the input, the application service coordinates the use
-case, and the domain provides the rules and behavior required by that use case.
+`main.ts` is the runtime entry point into the own system. Inside that system,
+application services use domain capabilities, while adapters can depend on
+ports and third-party libraries. The port branch stops at the boundary because
+what exists beyond that port depends on the system that implements it.
 
 #### Next Step
 
 Use this structure as the default layout for new code. When you need to inspect
-the purpose of a generated file, consult `generated-file-reference.md`.
+the purpose of a generated file, consult `generated-file-reference.md`.

package/docs/shared/application/data.md

@@ -176,10 +176,15 @@ and the representation used by the context.
 
 The normal flow of the data abstractions is the following:
 
-```text
-service -> repository -> driver -> data manager -> raw records
-service <- repository <- transformed records
+```mermaid
+flowchart LR
+    service[Service] --> repository[Repository]
+    repository --> driver[Driver]
+    driver --> manager["Data manager"]
+    manager --> raw["Raw records"]
+    repository --> transformed["Transformed records"]
+    transformed --> service
 ```
 
 This separation keeps the application service focused on orchestration while
-the repository focuses on transformation.
+the repository focuses on transformation.

package/docs/shared/application/events.md

@@ -135,10 +135,12 @@ registered or executed.
 
 The normal flow is the following:
 
-```text
-service -> dispatch(event)
-dispatcher -> matching handlers
-handlers -> side effects
+```mermaid
+flowchart LR
+    service[Service] --> dispatch["dispatch(event)"]
+    dispatch --> dispatcher[Dispatcher]
+    dispatcher --> handlers["Matching handlers"]
+    handlers --> effects["Side effects"]
 ```
 
-This keeps the main process separate from secondary reactions.
+This keeps the main process separate from secondary reactions.

package/docs/shared/application/http.md

@@ -123,9 +123,12 @@ cross-cutting behavior belongs in the generated HTTP abstraction.
 
 #### Example Flow
 
-```text
-request -> middleware -> handler -> response body
+```mermaid
+flowchart LR
+    request[Request] --> middleware[Middleware]
+    middleware --> handler[Handler]
+    handler --> response["Response body"]
 ```
 
 This flow keeps the transport boundary explicit while leaving framework choices
-to the adapter layer.
+to the adapter layer.

package/docs/shared/application/loggers.md

@@ -120,8 +120,11 @@ an external platform. It only depends on the application-level contract.
 
 #### Example Flow
 
-```text
-service -> Logger contract -> adapter -> logging backend
+```mermaid
+flowchart LR
+    service[Service] --> contract["Logger contract"]
+    contract --> adapter[Adapter]
+    adapter --> backend["Logging backend"]
 ```
 
-This flow keeps observability concerns outside the core process.
+This flow keeps observability concerns outside the core process.

package/docs/shared/application/services.md

@@ -112,9 +112,13 @@ result, depending on the requirements of the use case.
 
 #### Example Flow
 
-```text
-input -> service -> domain capabilities -> collaborators -> result
+```mermaid
+flowchart LR
+    input[Input] --> service[Service]
+    service --> domain["Domain capabilities"]
+    domain --> collaborators[Collaborators]
+    collaborators --> result[Result]
 ```
 
 This flow keeps orchestration in the application layer and domain meaning in
-the domain layer.
+the domain layer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "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)
+    })
+})