tshex-cli 1.0.24 → 1.0.26

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

@@ -9,12 +9,26 @@ The root contains the main entry points of the generated library.
 
 | File | Responsibility |
 | --- | --- |
-| `index.d.ts` | Declares root-level shared types such as `Generic<T>`. |
 | `main.ts` | Starts as a placeholder for the main implementation and root exports. |
 
-`index.d.ts` is the place for root-level type declarations. `main.ts` is the
-place for the main runtime entry point when the library starts exposing shared
-runtime components.
+`main.ts` is the place for the main runtime entry point when the library
+starts exposing shared runtime components.
+
+#### Types Files
+
+The `types/` directory contains root-level ambient type declarations.
+
+| File | Responsibility |
+| --- | --- |
+| `types/objects.d.ts` | Declares root-level shared types such as `Generic<T>`. |
+| `types/json.d.ts` | Declares `JsonValue` and the other plain, serializable JSON shapes. |
+| `types/cldr.d.ts` | Declares the `Locale` union from Unicode CLDR. |
+| `types/iana.d.ts` | Declares the `TimeZone` union from the IANA time zone database. |
+
+`types/objects.d.ts` and `types/json.d.ts` are the place for general-purpose
+root-level type declarations. `types/cldr.d.ts` and `types/iana.d.ts` are
+generated reference types consumed by other shared contracts, such as
+`shared/application/loggers.ts`.
 
 #### Shared Domain Files
 
@@ -39,13 +53,29 @@ cases and integrations.
 | --- | --- |
 | `shared/application/validations.ts` | Declares the `Validatable` contract. |
 | `shared/application/services.ts` | Declares the `Service` base class for use cases. |
-| `shared/application/http.ts` | Declares framework-agnostic HTTP contracts. |
 | `shared/application/loggers.ts` | Declares shared log levels and the `Logger` contract. |
 | `shared/application/events.ts` | Declares `Event`, `EventHandler`, and `EventDispatcher`. |
 
 These files do not implement frameworks or transports. They define the stable
 contracts that adapters and services can share.
 
+#### Shared HTTP Files
+
+The `shared/application/http` directory groups the framework-agnostic HTTP
+boundary and the type-only specifications for common web content formats.
+
+| File | Responsibility |
+| --- | --- |
+| `shared/application/http/http.ts` | Declares `HttpRequestHandler`, `HttpMiddleware`, and `HttpError`. |
+| `shared/application/http/json-api.ts` | Type-only JSON:API v1.1 document, resource, and Atomic Operations declarations. |
+| `shared/application/http/json-web-token.ts` | Type-only JOSE/JWT declarations (JWK, JWS, JWE, JWT claims). |
+| `shared/application/http/opengraph.ts` | Type-only Open Graph, Twitter Card, and social metadata declarations. |
+
+`http.ts` is the only file in this directory with runtime code. `json-api.ts`,
+`json-web-token.ts`, and `opengraph.ts` contain compile-time structure only;
+they describe the shape of external formats without implementing parsing,
+validation, or serialization.
+
 #### Shared Data Files
 
 The generated template also includes a small set of data-access abstractions.
@@ -61,14 +91,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 +111,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

@@ -15,15 +15,34 @@ The root contains the entry points of the generated library.
 
 ```mermaid
 flowchart TD
-    root["Library root"] --> index["index.d.ts"]
+    root["Library root"] --> types["types/"]
     root --> main["main.ts"]
     root --> shared["shared/"]
     root --> users["users/"]
 ```
 
-`index.d.ts` defines root-level types. `main.ts` starts as a placeholder for
-main runtime exports. The rest of the structure lives under `shared/` and one
-or more context directories.
+`types/` groups the root-level type declarations. `main.ts` starts as a
+placeholder for main runtime exports. The rest of the structure lives under
+`shared/` and one or more context directories.
+
+#### Types
+
+The `types/` directory contains ambient type declarations shared by the whole
+library.
+
+```mermaid
+flowchart TD
+    types["types/"] --> typesObjects["objects.d.ts"]
+    types --> json["json.d.ts"]
+    types --> cldr["cldr.d.ts"]
+    types --> iana["iana.d.ts"]
+```
+
+`types/objects.d.ts` defines root-level types such as `Generic<T>`.
+`types/json.d.ts` defines `JsonValue` and the other plain, serializable JSON
+shapes. `types/cldr.d.ts` declares the `Locale` union from Unicode CLDR.
+`types/iana.d.ts` declares the `TimeZone` union from the IANA time zone
+database.
 
 #### Shared
 
@@ -72,9 +91,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 +129,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 +156,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/library-types.md

@@ -7,10 +7,10 @@ data but does not need a more specific shape yet.
 
 #### Root Declaration
 
-The root declaration lives in `index.d.ts`.
+The root declaration lives in `types/objects.d.ts`.
 
-```ts title="index.d.ts"
-type Generic<T = unknown> = Record<string, T>
+```ts title="types/objects.d.ts"
+export type Generic<T = unknown> = Record<string, T>
 ```
 
 This alias expands to `Record<string, T>`. When no type argument is provided,
@@ -21,6 +21,8 @@ the values use `unknown`.
 In the following example we use `Generic<string>` for a set of plain filters.
 
 ```ts
+import { type Generic } from './types/objects.js'
+
 const filters: Generic<string> = {
     status: 'active',
     sort: 'email',
@@ -35,6 +37,8 @@ value shape for the whole object.
 Now consider the same pattern without providing a type argument.
 
 ```ts
+import { type Generic } from './types/objects.js'
+
 const metadata: Generic = {
     retries: 2,
     cached: true,
@@ -64,6 +68,44 @@ generic record.
 > `Generic<T>` is intentionally small. It should support loose object contracts,
 > not replace explicit domain or application types.
 
+#### JSON Values
+
+The generated root also declares a small family of types that describe plain,
+serializable JSON data. They live in `types/json.d.ts`.
+
+```ts title="types/json.d.ts"
+export type JsonPrimitive = string | number | boolean | null
+
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray
+
+export type JsonArray = readonly JsonValue[]
+
+export type JsonObject = {
+    readonly [key: string]: JsonValue
+}
+```
+
+`JsonPrimitive` covers the scalar values allowed in JSON. `JsonValue` extends
+that with nested objects and arrays, so it recursively describes any value that
+survives a round trip through `JSON.stringify()`/`JSON.parse()`. `JsonObject`
+and `JsonArray` name the two composite shapes so other declarations can refer
+to them directly instead of repeating the union.
+
+```ts
+import { type JsonValue } from './types/json.js'
+
+function toLogPayload(value: JsonValue): string {
+    return JSON.stringify(value)
+}
+```
+
+Use `JsonValue` and `JsonObject` when a contract must guarantee its data is
+plain and serializable, such as request payloads, stored metadata, or wire
+formats. Prefer `Generic<T>` instead when the value type is not required to be
+JSON-safe. `shared/application/http/json-api.ts` and
+`shared/application/http/json-web-token.ts` build on these types to describe
+JSON:API documents and JOSE/JWT structures.
+
 #### Next Step
 
 For the rest of the generated shared abstractions, continue with the pages in