tshex-cli 1.0.24 → 1.0.25

package/build/main.js

@@ -45,7 +45,7 @@ function executeCreateReactContext(templatesDir, contextDir) {
         console.error(err);
     }
 }
-function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSourceDir) {
+function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSourceDir, rootSourceDir = sourceDir) {
     const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
     if (fs.existsSync(destinationDir) === false) {
         fs.mkdirSync(destinationDir, { recursive: true });
@@ -54,7 +54,7 @@ function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSour
         const sourcePath = path.join(sourceDir, entry.name);
         const destinationPath = path.join(destinationDir, entry.name);
         if (entry.isDirectory()) {
-            if (entry.name === 'shared') {
+            if (entry.name === 'shared' && sourceDir === rootSourceDir) {
                 continue;
             }
             if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
@@ -63,7 +63,7 @@ function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSour
             if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
                 continue;
             }
-            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir);
+            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir, rootSourceDir);
             continue;
         }
         if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {

package/docs/context-ports.md

@@ -4,10 +4,10 @@ Context ports define the communication available at a context boundary.
 They describe which concrete capability a context exposes, what data enters
 that capability, and what data it returns.
 
-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.
+In practice a port 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
@@ -22,13 +22,19 @@ surface that another actor can call or observe.
 The generated context starts with a single root file for ports.
 
 ```ts title="users/example-ports.ts"
-export function example(): void {
-    // ...
+export class ExamplePort {
+    public doSomething(): void {
+        // ...
+    }
 }
 ```
 
-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.
+This placeholder marks the context root as the place where boundary-facing
+capabilities are declared. Replace it with the first module that defines a real
+port of the context when that capability becomes clear.
+
+Context root `.ts` files belong to this same boundary surface. Each one is
+expected to be a module that defines one or more context ports.
 
 #### First Port
 
@@ -36,113 +42,56 @@ In the following example we replace the placeholder with a concrete port for
 creating a user.
 
 ```ts title="users/example-ports.ts"
-export type CreateUserRequest = {
-    user: {
-        id: string
-        email: string
-        active: boolean | null
-    }
+export interface User {
+    id: string
+    email: string
+    active: boolean | null
 }
 
-export type CreateUserResponse = {
-    user: {
-        id: string
-        email: string
-        active: boolean | null
+export class UsersRegistry {
+    public async createUser(user: User): Promise<User> {
+        // ...
     }
 }
-
-export interface CreateUserPort {
-    create(request: CreateUserRequest): Promise<CreateUserResponse>
-}
 ```
 
-`CreateUserRequest` defines the incoming payload. `CreateUserResponse` defines
-the outgoing payload. `CreateUserPort` names the concrete capability exposed at
-the boundary: creating a user.
+`User` expresses the user data that crosses the boundary. `UsersRegistry` is a
+boundary object of the context and `createUser()` is one concrete capability
+that it exposes.
 
-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.
+This definition focuses on the interaction the context makes available. The
+port keeps its identity as one boundary capability while making its data and
+action explicit.
 
-#### Adapter Implementation
+The port is the executable object that this context exposes. Types help
+describe it and make its boundary explicit.
 
-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 {
-    CreateUserPort,
-    CreateUserRequest,
-    CreateUserResponse,
-} from '../example-ports.js'
-
-type CreateUserService = {
-    execute(data: {
-        id: string
-        email: string
-        active: boolean | null
-    }): Promise<CreateUserResponse>
-}
-
-export class CreateUserAdapter implements CreateUserPort {
-    public constructor(
-        private readonly service: CreateUserService,
-    ) {}
-
-    public async create(
-        request: CreateUserRequest,
-    ): Promise<CreateUserResponse> {
-        return this.service.execute({
-            id: request.user.id,
-            email: request.user.email,
-            active: request.user.active,
-        })
-    }
-}
-```
-
-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:
+This is the normal flow inside the context boundary:
 
 ```mermaid
 flowchart LR
-    external["External system"] --> adapter[Adapter]
-    adapter --> port[Port]
+    caller["Caller"] --> port[Concrete port]
     port --> application[Application]
     application --> domain[Domain]
 ```
 
-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.
+The port belongs to the boundary because it is part of what the context
+exposes. The application process executes the use case behind the exposed
+capability and uses domain capabilities.
 
 #### Multiple Port Files
 
-As the context grows, you can keep several ports at the context root.
-
-```ts title="users/list-users.ts"
-export type ListUsersRequest = {
-    active: boolean | null
-}
+As the context grows, you can keep several port modules at the context root.
 
-export type ListUsersResponse = {
-    users: Array<{
-        id: string
-        email: string
-        active: boolean | null
-    }>
-}
-
-export interface ListUsersPort {
-    list(request: ListUsersRequest): Promise<ListUsersResponse>
+```ts title="users/registry.ts"
+export class UsersRegistry {
+    public async listUsers(): Promise<User[]> {
+        // ...
+    }
 }
 ```
 
-An adapter can then import the port definition from the file that owns it.
+Another caller can then import the port from the file that owns it.
 
 This arrangement is useful when one context exposes several independent
 capabilities. A single file works well for a small context. Separate files
@@ -150,9 +99,9 @@ become easier to maintain when each port has its own identity and
 responsibility.
 
 > **Warning**
-> A port should define an exposed boundary capability, not domain internals.
-> Avoid moving entity rules, repository logic, or infrastructure details into
-> the port file.
+> A port should define an exposed boundary capability.
+> Keep business rules, repository logic, and infrastructure details in their
+> corresponding layers.
 
 #### Example Layout
 
@@ -161,16 +110,14 @@ in the generated folders.
 
 ```mermaid
 flowchart TD
-    users["users/"] --> examplePorts["example-ports.ts"]
-    users --> listUsers["list-users.ts"]
-    users --> adapters["adapters/"]
+    users["users/"] --> registry["registry.ts"]
     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 port
-definitions for the capabilities the context exposes.
+makes each exposed capability easy to locate because the port modules stay at
+the root of the context.
 
 #### Next Step
 

package/docs/generated-file-reference.md

@@ -61,14 +61,14 @@ application coordinates data access without forcing a specific driver.
 
 #### Context Files
 
-Each generated context starts with a root port file and three directories.
+Each generated context starts with an example port file and three directories.
 
 | Path | Responsibility |
 | --- | --- |
-| `users/example-ports.ts` | Placeholder root file for context ports. |
+| `users/example-ports.ts` | Example module for context ports. All context root `.ts` files are expected to define context ports. |
 | `users/domain/` | Domain capabilities and rules for the context. |
 | `users/application/` | Processes that use domain capabilities to fulfill system purposes. |
-| `users/adapters/` | Integrations that implement ports and connect the context to external systems. |
+| `users/adapters/` | Integrations that wraps third-party libraries or context ports. |
 
 The `users/` path is an example context name. Your project can generate one or
 more contexts with the same internal layout.
@@ -81,8 +81,8 @@ Use the following sequence when deciding where new code belongs.
 2. Put reusable application contracts in `shared/application`.
 3. Put context-specific rules in `<context>/domain`.
 4. Put use cases in `<context>/application`.
-5. Put boundary implementations in `<context>/adapters`.
-6. Put boundary contracts at the context root.
+5. Put transport and infrastructure integrations in `<context>/adapters`.
+6. Put concrete boundary ports in context root `.ts` files.
 
 This reference explains placement. The architectural rationale is described in
-`library-structure.md`.
+`library-structure.md`.

package/docs/library-structure.md

@@ -72,9 +72,14 @@ flowchart TD
     users --> domain["domain/"]
 ```
 
-`example-ports.ts` is the root communication surface of the context.
+`example-ports.ts` is an example module in the root communication surface of
+the context.
 `domain/` contains capabilities and rules. `application/` contains processes.
-`adapters/` contains boundary implementations.
+`adapters/` contains integrations that wrap third-party libraries or context
+ports.
+
+Context root `.ts` files belong to the boundary surface of the context. Each
+one is expected to be a module that defines one or more context ports.
 
 #### Domain
 
@@ -105,21 +110,23 @@ business rules themselves.
 The adapters layer contains the integrations that connect a context to other
 systems.
 
-An adapter can expose an HTTP handler, consume a message, call a remote API,
-implement a data driver, or connect to an event bus. Its role is to translate
-external input or output into the contracts expected by the application layer.
+An adapter wraps a third-party library or a context port so that the context
+can interact with a concrete transport or infrastructure path. An adapter can
+expose an HTTP handler, consume a message, call a remote API, implement a data
+driver, or connect to an event bus.
 
 #### Ports
 
 Ports define the communication available at the context boundary.
 
 They live at the context root because they describe how the context is used
-from the outside. An adapter imports a port, implements it, and delegates the
-work to an application process.
+from the outside. A port is the concrete object the context exposes. Adapters
+or other callers can use that port object and route work into an application
+process.
 
-The generated template starts with `example-ports.ts`, but a larger context may
-split ports across several files. The detailed guidance for that layout lives in
-`context-ports.md`.
+The generated template starts with `example-ports.ts`. As the context grows,
+additional context root `.ts` modules can define more ports. The detailed
+guidance for that layout lives in `context-ports.md`.
 
 #### Dependency Direction
 
@@ -130,15 +137,13 @@ 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. 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.
+connect the context boundary to application processes. 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

package/docs/shared/domain/aggregates.md

@@ -1,9 +1,8 @@
 ### Aggregates
 
-An aggregate is responsible for grouping multiple entities into one logical
-domain unit.
-It is used when the behavior of the concept depends on the collaboration of
-several entities instead of a single entity in isolation.
+An aggregate groups multiple entities into one logical domain unit.
+It is useful when the behavior of a concept depends on the collaboration of
+several entities working together.
 
 The generated template provides `Aggregate` as a semantic base class.
 
@@ -15,45 +14,145 @@ The generated template provides `Aggregate` as a semantic base class.
 export abstract class Aggregate {}
 ```
 
-This means the generated base class does not impose persistence rules, event
-publication, or identity behavior. Those concerns remain in the concrete domain
-model of the project.
+The class is intentionally empty. Its role is to provide the semantic base for
+an aggregate whose concrete implementation gathers the involved entities as a
+key-value structure through its own properties, such as `buyer`, `seller`,
+`order`, or `invoice`. Persistence rules, event publication, and identity
+behavior live in the concrete domain model of the project.
 
 #### First Aggregate
 
-In the following example we model a shopping cart as a group of line items.
+In the following example we model a sale as one domain unit composed of a
+buyer, a seller, an order, and an invoice generated by the aggregate itself.
 
-```ts title="users/domain/cart.ts"
+```ts title="sales/domain/sale.ts"
 import { Aggregate } from '../../shared/domain/aggregates.js'
 import { Entity } from '../../shared/domain/entities.js'
 
-class LineItem extends Entity {
+class Person extends Entity {
+	public readonly id: string
+	public readonly name: string
+
+	public constructor(id: string, name: string) {
+		super()
+		this.id = id
+		this.name = name
+	}
+
+	public equals(other: Entity): boolean {
+		return other instanceof Person && this.id === other.id
+	}
+}
+
+class Product extends Entity {
+	public readonly id: string
+	public readonly name: string
+	public readonly price: number
+
+	public constructor(id: string, name: string, price: number) {
+		super()
+		this.id = id
+		this.name = name
+		this.price = price
+	}
+
+	public equals(other: Entity): boolean {
+		return other instanceof Product && this.id === other.id
+	}
+}
+
+class Order extends Entity {
+	public readonly id: string
+	public readonly products: Product[]
+
+	public constructor(id: string, products: Product[]) {
+		super()
+		this.id = id
+		this.products = products
+	}
+
+	public equals(other: Entity): boolean {
+		return other instanceof Order && this.id === other.id
+	}
+}
+
+class Invoice extends Entity {
+	public readonly id: string
+	public readonly order: Order
+	public readonly buyer: Person
+	public readonly seller: Person
+	public readonly total: number
+
 	public constructor(
-		public readonly id: string,
-		public readonly quantity: number,
+		id: string,
+		order: Order,
+		buyer: Person,
+		seller: Person,
 	) {
 		super()
+		this.id = id
+		this.order = order
+		this.buyer = buyer
+		this.seller = seller
+		this.total = this.order.products.reduce(
+			(sum, product) => sum + product.price,
+			0,
+		)
 	}
 
 	public equals(other: Entity): boolean {
-		return other instanceof LineItem && this.id === other.id
+		return other instanceof Invoice && this.id === other.id
 	}
 }
 
-export class Cart extends Aggregate {
-	public constructor(public readonly items: Array<LineItem>) {
+export class Sale extends Aggregate {
+	public readonly buyer: Person
+	public readonly seller: Person
+	public readonly order: Order
+	protected invoice: Invoice | null
+
+	public constructor(
+		buyer: Person,
+		seller: Person,
+		order: Order,
+	) {
 		super()
+		this.buyer = buyer
+		this.seller = seller
+		this.order = order
+		this.invoice = null
+	}
+
+	public generateInvoice(): { invoice: Invoice } {
+		const id = Math.random().toString()
+		const invoice = new Invoice(
+			id,
+			this.order,
+			this.buyer,
+			this.seller,
+		)
+
+		this.invoice = invoice
+
+		return { invoice }
 	}
 
-	public totalItems(): number {
-		return this.items.reduce((sum, item) => sum + item.quantity, 0)
+	public getInvoice(): Invoice | null {
+		return this.invoice
 	}
 }
 ```
 
-`Cart` is an aggregate because its behavior depends on the collection of
-entities that compose it. `LineItem` remains an entity because its identity is
-independent inside the aggregate.
+`Sale` is an aggregate because the rule for generating the invoice depends on
+the collaboration between buyer, seller, and order. In this example, both
+buyer and seller are modeled with the same `Person` entity, while `Order`
+stores the list of purchased products and `Invoice` stores the computed
+`total`. `Invoice` is created inside the aggregate, and its constructor
+calculates the total from the order products when the invoice is generated. The
+`invoice` field stays inside the aggregate lifecycle and `getInvoice()` offers
+controlled access to the generated invoice. When a domain object already
+exists, the example uses that object directly and keeps the collaboration
+between domain parts explicit.
 
 #### Responsibility Boundary
 
@@ -66,14 +165,15 @@ Examples include:
 2. keeping related entities in a consistent state;
 3. exposing operations that depend on the collaboration of those entities.
 
-The generated `Aggregate` base class does not implement these rules for you. It
-only provides the semantic place where those rules belong.
+The generated `Aggregate` base class provides the semantic place where those
+rules belong. The concrete aggregate defines and coordinates the rules that
+keep the domain unit consistent.
 
 > **Warning**
-> Do not extend `Aggregate` only to create a container for unrelated values. Use
-> it when the concept represents one domain unit composed of several parts.
+> Extend `Aggregate` when the concept represents one domain unit composed of
+> several related parts and shared rules.
 
 #### Next Step
 
 Aggregates usually collaborate with entities and value objects. The base entity
-behavior is documented in `entities.md`.
+behavior is documented in `entities.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",
@@ -45,6 +45,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "^1.6.0",
     "@types/node": "^22.5.4",
     "typescript": "^5.4.5"
   },

package/source/main.ts

@@ -55,7 +55,13 @@ function executeCreateReactContext(templatesDir: string, contextDir: string) {
     }
 }
 
-function executeCreateTests(sourceDir: string, destinationDir: string, fileContents: string, ignoredSourceDir?: string) {
+function executeCreateTests(
+    sourceDir: string,
+    destinationDir: string,
+    fileContents: string,
+    ignoredSourceDir?: string,
+    rootSourceDir: string = sourceDir
+) {
     const entries = fs.readdirSync(sourceDir, { withFileTypes: true })
 
     if (fs.existsSync(destinationDir) === false) {
@@ -67,7 +73,7 @@ function executeCreateTests(sourceDir: string, destinationDir: string, fileConte
         const destinationPath = path.join(destinationDir, entry.name)
 
         if (entry.isDirectory()) {
-            if (entry.name === 'shared') {
+            if (entry.name === 'shared' && sourceDir === rootSourceDir) {
                 continue
             }
 
@@ -79,7 +85,7 @@ function executeCreateTests(sourceDir: string, destinationDir: string, fileConte
                 continue
             }
 
-            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir)
+            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir, rootSourceDir)
             continue
         }