tshex-cli 1.0.23 → 1.0.24

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.23",
+  "version": "1.0.24",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",