tshex-cli 1.0.24 → 1.0.26

package/docs/shared/application/http.md

@@ -1,94 +1,64 @@
 ### HTTP
 
-The HTTP contracts define a transport-facing boundary without coupling the
-generated structure to a specific framework.
+The HTTP contracts define a framework-agnostic, transport-facing boundary.
 They are used when an adapter needs to describe requests, responses, handlers,
 or middleware in a consistent way.
 
-The generated template keeps `HttpRequest` and `HttpResponse` empty on purpose.
-Each project can extend them with the fields required by its own transport.
+The generated template relies on the standard `Request` and `Response` types
+from the Fetch API, so adapters work directly with the platform's own APIs.
 
-#### Response Body
+The concern is split across four files under `shared/application/http/`:
 
-`HttpResponseBody` is responsible for standardizing the shape of the response
-payload.
+1. `http.ts` for the request/response boundary contracts and `HttpError`;
+2. `json-api.ts` for a type-only JSON:API v1.1 specification;
+3. `json-web-token.ts` for a type-only JOSE/JWT specification;
+4. `opengraph.ts` for a type-only Open Graph and social metadata specification.
 
-```ts title="shared/application/http.ts"
-export interface HttpResponseBody {
-    readonly data: Record<string, unknown> | null
-    readonly errors: string[] | null
-    readonly links: Record<string, URL> | null
-}
-```
-
-This structure makes successful data, error messages, and related links
-explicit without forcing a specific router or server implementation.
+Only `http.ts` contains runtime code. The other three files describe
+compile-time structure for widely used formats so adapters do not have to
+redefine them; they do not implement parsing, validation, or serialization.
 
 #### Request Handler
 
 `HttpRequestHandler` is responsible for processing a request and returning a
 response.
 
-```ts title="shared/application/http.ts"
+```ts title="shared/application/http/http.ts"
 export interface HttpRequestHandler {
-    handle(request: HttpRequest): HttpResponse | Promise<HttpResponse>
+    handle(request: Request): Response | Promise<Response>
 }
 ```
 
-In the following example we define adapter-specific request and response types,
-then implement a handler.
+In the following example we implement a handler using the standard `Request`
+and `Response` objects.
 
 ```ts title="users/adapters/get-user-handler.ts"
-import {
-    HttpRequest,
-    HttpRequestHandler,
-    HttpResponse,
-    HttpResponseBody,
-} from '../../shared/application/http.js'
-
-interface UserHttpRequest extends HttpRequest {
-    readonly params: {
-        id: string
-    }
-}
-
-interface UserHttpResponse extends HttpResponse {
-    readonly status: number
-    readonly body: HttpResponseBody
-}
+import { HttpRequestHandler } from '../../shared/application/http/http.js'
 
 export class GetUserHandler implements HttpRequestHandler {
-    public handle(request: HttpRequest): HttpResponse {
-        const typedRequest = request as UserHttpRequest
-
-        return {
-            status: 200,
-            body: {
-                data: {
-                    id: typedRequest.params.id,
-                },
-                errors: null,
-                links: null,
-            },
-        } as UserHttpResponse
+    public handle(request: Request): Response {
+        const id = new URL(request.url).pathname.split('/').at(-1)
+
+        return Response.json({ data: { id } }, { status: 200 })
     }
 }
 ```
 
-The generated `HttpRequest` and `HttpResponse` interfaces stay empty, so the
-adapter declares the transport-specific fields locally. This keeps the shared
-contract small and portable.
+Using the standard `Request` and `Response` types means the adapter relies
+on the platform's own APIs, such as `request.url`, `request.headers`, and
+`Response.json`. The shape of the JSON body itself, when the adapter follows
+JSON:API, is described by the document types in `json-api.ts`.
 
 #### Middleware
 
 `HttpMiddleware` is responsible for running logic before or around the handler.
 
-```ts title="shared/application/http.ts"
+```ts title="shared/application/http/http.ts"
 export interface HttpMiddleware {
     process(
-        request: HttpRequest,
+        request: Request,
         handler: HttpRequestHandler,
-    ): HttpResponse | Promise<HttpResponse>
+    ): Response | Promise<Response>
 }
 ```
 
@@ -97,29 +67,69 @@ Now that the handler exists, middleware can wrap it.
 ```ts title="users/adapters/request-logger.ts"
 import {
     HttpMiddleware,
-    HttpRequest,
     HttpRequestHandler,
-    HttpResponse,
-} from '../../shared/application/http.js'
+} from '../../shared/application/http/http.js'
 
 export class RequestLoggerMiddleware implements HttpMiddleware {
     public async process(
-        request: HttpRequest,
+        request: Request,
         handler: HttpRequestHandler,
-    ): Promise<HttpResponse> {
+    ): Promise<Response> {
         void request
         return handler.handle(request)
     }
 }
 ```
 
-This middleware does not mutate the request or response. It only shows where
+This middleware passes the request through unchanged, showing where
 cross-cutting behavior belongs in the generated HTTP abstraction.
 
-> **Warning**
-> Do not treat the shared HTTP contracts as a full framework abstraction. They
-> only define the minimum boundary for adapters. Routing, serialization, and
-> status code policies remain the responsibility of the concrete transport.
+#### HTTP Errors
+
+`HttpError` is responsible for carrying an HTTP status code alongside a
+matching message.
+
+```ts title="shared/application/http/http.ts"
+export class HttpError extends Error {
+    public static readonly messages: { [code: number]: string } = Object.freeze({
+        400: 'Bad Request',
+        404: 'Not Found',
+        409: 'Conflict',
+        // ...remaining standard 4xx/5xx status codes
+        500: 'Internal Server Error',
+    })
+
+    public readonly code: number
+
+    constructor(code: number, message?: string) {
+        super(message ?? HttpError.messages[code] ?? 'Unknown Error')
+        this.code = code
+        this.name = 'HttpError'
+    }
+}
+```
+
+`HttpError.messages` maps every standard 4xx/5xx status code to its reason
+phrase. A caller can throw `new HttpError(404)` to get the standard message for
+free, or pass an explicit `message` to override it. Codes outside the map fall
+back to `'Unknown Error'`.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpError } from '../../shared/application/http/http.js'
+
+function assertFound<T>(value: T | null): T {
+    if (value === null) {
+        throw new HttpError(404)
+    }
+
+    return value
+}
+```
+
+> **Note**
+> The shared HTTP contracts define the minimum boundary for adapters. Routing,
+> serialization, and status code policies beyond `HttpError` are the
+> responsibility of the concrete transport.
 
 #### Example Flow
 
@@ -132,3 +142,142 @@ flowchart LR
 
 This flow keeps the transport boundary explicit while leaving framework choices
 to the adapter layer.
+
+#### JSON:API
+
+`json-api.ts` declares a type-only implementation of the
+[JSON:API v1.1](https://jsonapi.org/format/) specification, including the
+[Atomic Operations extension](https://jsonapi.org/ext/atomic/). It gives an
+adapter a shared vocabulary for request and response bodies without forcing a
+particular server framework.
+
+The main building blocks are:
+
+- `JsonApiResourceObject` / `JsonApiResourceIdentifier` for resources and
+  resource linkage, generic over the resource `type`, `attributes`, and
+  `relationships`;
+- `JsonApiRelationship`, `JsonApiToOneRelationship`, and
+  `JsonApiToManyRelationship` for relationship objects;
+- `JsonApiError` for the top-level error object;
+- `JsonApiDocument` (and its narrower aliases such as
+  `JsonApiSingleResourceDocument` and `JsonApiResourceCollectionDocument`) for
+  the top-level document, discriminated between a data document, an error
+  document, and a meta-only document;
+- `JsonApiAtomicOperationsDocument` / `JsonApiAtomicResultsDocument` for the
+  Atomic Operations extension request and response bodies.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpRequestHandler } from '../../shared/application/http/http.js'
+import {
+    JsonApiSingleResourceDocument,
+    JsonApiResourceObject,
+} from '../../shared/application/http/json-api.js'
+
+type UserAttributes = { email: string }
+type UserResource = JsonApiResourceObject<'users', UserAttributes>
+
+export class GetUserHandler implements HttpRequestHandler {
+    public handle(request: Request): Response {
+        const id = new URL(request.url).pathname.split('/').at(-1) ?? ''
+
+        const body: JsonApiSingleResourceDocument<UserResource> = {
+            data: {
+                type: 'users',
+                id,
+                attributes: { email: 'ada@example.com' },
+            },
+        }
+
+        return Response.json(body, { status: 200 })
+    }
+}
+```
+
+> **Hint**
+> These declarations only provide compile-time structure. Rules that depend on
+> runtime values, URI validity, document-wide uniqueness, or member-name
+> character validation still require explicit checks in the adapter.
+
+#### JSON Web Tokens
+
+`json-web-token.ts` declares a type-only implementation of the JOSE and JWT
+family of RFCs (JWS, JWE, JWK, JWT, and related extensions such as DPoP and
+selective disclosure). It lets an adapter describe tokens and keys precisely
+without depending on a specific JOSE library's own types.
+
+The main building blocks are:
+
+- branded wire-format primitives such as `Base64Url`, `NumericDate`, and
+  `CompactJwt`;
+- `JsonWebKey` / `JsonWebKeySet` for keys, covering EC, RSA, `oct`, OKP, and
+  ML-DSA (`AKP`) key types;
+- `JwsHeader` / `JweHeader` for protected header parameters, and
+  `JwsJsonSerialization` / `JweJsonSerialization` for the JSON serializations;
+- `JwtClaims` (built on `IanaRegisteredJwtClaims`) for decoded payloads, plus
+  ready-made profiles such as `OpenIdConnectIdTokenClaims`,
+  `OAuth2JwtAccessTokenClaims`, `DpopProofClaims`, and `SdJwtClaims`;
+- service contracts an adapter can implement against a concrete JOSE
+  library: `JwtDecoder`, `JwsSigner`, `JwsVerifier`, `JweEncrypter`,
+  `JweDecrypter`, `JwkThumbprinter`, and `JwksResolver`, plus
+  `JwtValidationResult` for the outcome of validating a token against a
+  `JwtValidationPolicy`.
+
+```ts title="users/adapters/verify-access-token.ts"
+import {
+    JwsVerifier,
+    OAuth2JwtAccessTokenClaims,
+    CompactJws,
+    JsonWebKey,
+} from '../../shared/application/http/json-web-token.js'
+
+export function verifyAccessToken(
+    verifier: JwsVerifier,
+    token: CompactJws,
+    key: JsonWebKey,
+) {
+    return verifier.verify<OAuth2JwtAccessTokenClaims>(token, key)
+}
+```
+
+> **Hint**
+> This module has no runtime implementation. Pair it with a concrete JOSE
+> library (for signing, encryption, or verification) and use these types to
+> annotate its inputs and outputs.
+
+#### Open Graph
+
+`opengraph.ts` declares a type-only implementation of the
+[Open Graph protocol](https://ogp.me/), the Twitter Card meta tags, and
+Facebook's compatibility extensions. It is used when an adapter needs to build
+or read the social-sharing metadata of a page.
+
+The main building blocks are:
+
+- `OpenGraphMetadata`, a union of every standard Open Graph object type
+  (`OpenGraphWebsite`, `OpenGraphArticle`, `OpenGraphBook`, `OpenGraphProfile`,
+  the `music.*` and `video.*` types, `OpenGraphPaymentLink`, and
+  `OpenGraphCustomObject` for CURIE-style custom types);
+- `OpenGraphMetaTag` and `TwitterMetaTag`, the flat `property`/`content` and
+  `name`/`content` tag representations closer to the actual `<meta>` markup;
+- `SocialMetadataDocument`, an aggregate of Open Graph, Twitter, Facebook, and
+  standard head metadata for a single page, and `RawSocialMetadataDocument`
+  for its rendered, tag-list form.
+
+```ts title="users/adapters/user-profile-metadata.ts"
+import { OpenGraphProfile } from '../../shared/application/http/opengraph.js'
+
+export function buildProfileMetadata(username: string): OpenGraphProfile {
+    return {
+        type: 'profile',
+        title: username,
+        url: `https://example.com/users/${username}`,
+        images: [{ url: `https://example.com/users/${username}/avatar.png` }],
+        username,
+    }
+}
+```
+
+> **Hint**
+> This module has no runtime implementation, including no HTML rendering. Use
+> `OpenGraphMetadata` to build the data and a separate template or renderer to
+> emit the `<meta>` tags described by `OpenGraphMetaTag`/`TwitterMetaTag`.

package/docs/shared/application/loggers.md

@@ -28,22 +28,57 @@ any adapter to use a particular logger implementation.
 `Logger` is responsible for receiving log data from the application layer.
 
 ```ts title="shared/application/loggers.ts"
+import { type TimeZone } from '../../types/iana.js'
+import { type Locale } from '../../types/cldr.js'
+
 export abstract class Logger {
-	public abstract debug(data: unknown): void
+    [property: string]: unknown
 
-	public abstract info(data: unknown): void
+    public name: string = 'main'
 
-	public abstract warning(data: unknown): void
+    public level: number = 0
 
-	public abstract error(data: unknown): void
+    public datetimeLocales: Locale[] = ['en-GB']
 
-	public abstract critical(data: unknown): void
-}
+    public datetimeFormatOptions: Intl.DateTimeFormatOptions & { timeZone: TimeZone } = {
+        timeZone: 'UTC',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        fractionalSecondDigits: 3,
+        hourCycle: 'h23'
+    }
+
+    public abstract debug(data: unknown): void
+
+    public abstract info(data: unknown): void
+
+    public abstract warning(data: unknown): void
+
+    public abstract error(data: unknown): void
+
+    public abstract critical(data: unknown): void
+
+    protected getCurrentDatetime(): string {
+        return new Date().toLocaleString(this.datetimeLocales, this.datetimeFormatOptions)
+    }
+} //:: class
 ```
 
 The contract is intentionally small. It defines the actions the application can
 request, while the adapter decides how those actions are persisted or displayed.
 
+`name` and `level` identify the logger instance and its minimum severity, so an
+adapter can decide which logs to emit or route. `datetimeLocales` and
+`datetimeFormatOptions` control how `getCurrentDatetime()` formats the current
+moment, using the `Locale` type from `types/cldr.d.ts` and the `TimeZone` type
+from `types/iana.d.ts`. Adapters can use `getCurrentDatetime()` to timestamp
+log entries consistently, regardless of the runtime environment's own locale
+or timezone.
+
 #### First Adapter
 
 In the following example we implement a console-based logger.
@@ -51,43 +86,32 @@ In the following example we implement a console-based logger.
 ```ts title="users/adapters/console-logger.ts"
 import { Logger } from '../../shared/application/loggers.js'
 
-type ExternalService = {
-    debug(data: unknown): void
-    info(data: unknown): void
-    warning(data: unknown): void
-    error(data: unknown): void
-    critical(data: unknown): void
-}
-
 export class ConsoleLogger extends Logger {
-    constructor(protected readonly externalService: ExternalService) {
-        super()
-    }
-
 	public debug(data: unknown): void {
-		this.externalService.debug(data)
+		console.debug(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public info(data: unknown): void {
-		this.externalService.info(data)
+		console.info(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public warning(data: unknown): void {
-		this.externalService.warning(data)
+		console.warn(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public error(data: unknown): void {
-		this.externalService.error(data)
+		console.error(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public critical(data: unknown): void {
-		this.externalService.critical(data)
+		console.error(this.getCurrentDatetime(), this.name, data)
 	}
 }
 ```
 
 This adapter satisfies the generated contract without changing the application
-layer.
+layer. It reuses `getCurrentDatetime()` to prefix every entry with a
+consistently formatted timestamp.
 
 #### Service Integration
 

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.26",
   "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"
   },