archstone 1.0.4 → 1.1.1

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<br />
+
 # Archstone
 
 ### The TypeScript foundation for serious backend services.
@@ -15,11 +17,15 @@ Build on Domain-Driven Design and Clean Architecture — without writing the sam
 
 <br />
 
+[Quick Start](#install) · [Why Archstone](#why-archstone) · [Usage](#usage) · [Agent Skills](#agent-skills-new-in-v110) · [Architecture](#architecture) · [Contributing](./CONTRIBUTING.md)
+
+<br />
+
 </div>
 
 ---
 
-## Why archstone?
+## Why Archstone?
 
 Every backend project in DDD needs the same structural pieces — and most teams rewrite them from scratch each time. Archstone gives you a **battle-tested, zero-dependency set of base classes and contracts** so you can skip the boilerplate and go straight to modeling your domain.
 
@@ -37,13 +43,16 @@ async function createUser(): Promise<Either<NotFoundError, User>> { ... }
 
 ## Features
 
-- **`Either`** — functional error handling; use cases never throw
-- **`Entity` / `AggregateRoot`** — identity-based domain objects with built-in event support
-- **`ValueObject`** — equality by value, not reference
-- **`UniqueEntityId`** — UUID v7 identity, consistent across your entire domain
-- **`WatchedList`** — track additions and removals in collections without overwriting persistence
-- **`UseCase`** — typed contract for application logic
-- **Repository contracts** — define your interface in the domain; implement in infrastructure
+| | |
+|---|---|
+| **`Either`** | Functional error handling — use cases never throw |
+| **`Entity` / `AggregateRoot`** | Identity-based domain objects with built-in event support |
+| **`ValueObject`** | Equality by value, not reference |
+| **`UniqueEntityId`** | UUID v7 identity, consistent across your entire domain |
+| **`WatchedList`** | Track additions and removals in collections without overwriting persistence |
+| **`UseCase`** | Typed contract for application logic that always returns `Either` |
+| **Repository contracts** | Define your interface in the domain — implement anywhere in infrastructure |
+| **Agent Skills** | Built-in AI skill so your coding agent knows every DDD convention |
 
 ---
 
@@ -245,6 +254,32 @@ src/
 
 ---
 
+## Agent Skills — new in v1.1.0
+
+Archstone ships with a built-in skill for AI coding agents. Once installed, your agent understands every DDD convention, layer boundary, and usage pattern — without you ever having to explain them.
+
+**The skill covers:**
+- Entities, aggregates, and value objects
+- Use cases with `Either` error handling
+- Repository contracts and in-memory implementations
+- Domain events — raising, dispatching, and handling
+- Testing patterns with `bun:test` and in-memory repos
+- Common mistakes and how to avoid them
+
+**Install with Claude Code:**
+
+```bash
+bun x skills add joao-coimbra/archstone
+```
+
+**Or copy from the installed package:**
+
+```bash
+cp -r node_modules/archstone/skills/archstone .claude/skills/
+```
+
+---
+
 <div align="center">
 
 **Built with care for the TypeScript community.**

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "archstone",
   "description": "TypeScript architecture foundation for backend services based on Domain-Driven Design and Clean Architecture",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "type": "module",
   "private": false,
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -73,11 +74,10 @@
     "build": "bunup",
     "dev": "bunup --watch",
     "test": "bun test",
-    "lint": "biome check src/",
-    "prepublishOnly": "bun run build",
     "check": "ultracite check",
     "fix": "ultracite fix",
-    "prepare": "husky || true"
+    "prepublishOnly": "bun run build",
+    "prepare": "bunx husky"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.5",

package/skills/archstone/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: archstone
+description: 'Apply Archstone DDD and Clean Architecture conventions. Use when developers: (1) Create domain entities, aggregates, or value objects, (2) Write application use cases, (3) Define repository contracts, (4) Work with domain events or event handlers, (5) Ask about Either, UniqueEntityId, WatchedList, or UseCaseError. Triggers on: "entity", "aggregate", "value object", "use case", "repository", "domain event", "Either", "UniqueEntityId", "archstone".'
+---
+
+## Critical: Follow Archstone Conventions
+
+Everything you know about DDD patterns may differ from how Archstone implements them. Always follow the rules below — do not apply generic DDD patterns that contradict them.
+
+When working with Archstone:
+
+1. Check `node_modules/archstone/` for the installed version
+2. All entities must extend `Entity<Props>` or `AggregateRoot<Props>` — never use plain classes
+3. All value objects must extend `ValueObject<Props>`
+4. Use cases must implement `UseCase<Input, Output>` and **never throw** — always return `Either`
+5. Repository contracts are interfaces only — implementations belong in infrastructure
+6. Domain events are raised inside aggregates and dispatched after persistence — never before
+7. Use `UniqueEntityId` for all entity identifiers — never a plain `string`
+8. The left side of `Either` must `implement UseCaseError` — not `extend Error`
+
+If you are unsure about a pattern, check [Conventions Reference](references/conventions.md) before writing code.
+
+## Layer Boundaries
+
+Always respect the layer rules. Never place infrastructure code in `domain/`, and never import concrete implementations into use cases.
+
+See [Layer Rules](references/layers.md) for details.
+
+## Entities & Aggregates
+
+Use a static `create()` factory. Pass `id` as the second constructor argument. Use `Optional<T, K>` for auto-generated fields. See [Entity Patterns](references/entity.md).
+
+## Value Objects
+
+Use a static `create()` factory with validation. Value object `create()` may throw — wrap calls inside use cases with `try/catch` and return `left()`. See [Value Object Patterns](references/value-object.md).
+
+## Use Cases
+
+Implement `UseCase<Input, Output>`. Return `left()` for errors, `right()` for success. Error classes must `implement UseCaseError`. See [Use Case Patterns](references/use-case.md).
+
+## Repository Contracts
+
+Define as interfaces only. Use `Repository<T>` or compose `Findable`, `Creatable`, `Saveable`, `Deletable`. Note: `findById` takes `string` — pass `entity.id.toValue()`. See [Repository Patterns](references/repository.md).
+
+## Domain Events
+
+Raise inside the aggregate via `addDomainEvent()`. Dispatch after persistence via `DomainEvents.dispatchEventsForAggregate(aggregate.id)`. Define handlers as classes implementing `EventHandler`. See [Domain Event Patterns](references/domain-events.md).
+
+## Testing
+
+Use `bun:test`. Co-locate test files as `*.spec.ts`. Use in-memory repository implementations. See [Testing Patterns](references/testing.md).
+
+## References
+
+- [Conventions](references/conventions.md) — quick rules summary
+- [Imports](references/imports.md) — import paths for all exports
+- [Layers](references/layers.md) — layer boundary rules
+- [Entity Patterns](references/entity.md) — Entity and AggregateRoot examples
+- [Value Object Patterns](references/value-object.md) — ValueObject examples
+- [Use Case Patterns](references/use-case.md) — UseCase and Either examples
+- [Repository Patterns](references/repository.md) — repository interface and in-memory examples
+- [Domain Event Patterns](references/domain-events.md) — EventHandler and dispatch examples
+- [Testing Patterns](references/testing.md) — bun:test and in-memory repo examples

package/skills/archstone/references/conventions.md

@@ -0,0 +1,23 @@
+# Archstone Conventions — Quick Reference
+
+## Always
+
+- Extend `Entity<Props>` or `AggregateRoot<Props>` for domain entities
+- Extend `ValueObject<Props>` for value objects
+- Use `UniqueEntityId` for all entity identities — never `string`
+- Use static `create()` factory — never instantiate directly
+- Return `Either<UseCaseError, Value>` from use cases — never throw
+- Define repositories as interfaces only
+- Raise domain events inside aggregates via `addDomainEvent()`
+- Dispatch domain events **after** persistence
+
+## Never
+
+- Never throw inside a use case — use `left()`
+- Never use `extends Error` for use case errors — use `implements UseCaseError`
+- Never place repository implementations in `domain/`
+- Never import concrete classes into use cases
+- Never dispatch domain events before persistence
+- Never call `clearEvents()` manually — `dispatchEventsForAggregate` handles it
+- Never pass `UniqueEntityId` to `findById()` — it takes `string`; use `.toValue()`
+- Never use `===` to compare value objects — use `.equals()`

package/skills/archstone/references/domain-events.md

@@ -0,0 +1,78 @@
+# Domain Event Patterns
+
+## Rules
+
+- Raise events inside the aggregate via `this.addDomainEvent()`
+- Dispatch **after** successful persistence — never before
+- Define handlers as classes implementing `EventHandler` with `setupSubscriptions(): void`
+- Register handlers in the infrastructure composition root before the first request
+- Dispatch via `DomainEvents.dispatchEventsForAggregate(aggregate.id)` — argument is `UniqueEntityId`
+- `clearEvents()` is called internally by `dispatchEventsForAggregate` — do not call manually
+- Test isolation: call `DomainEvents.clearHandlers()` and `DomainEvents.clearMarkedAggregates()` in `beforeEach`
+
+## Raising Events (inside aggregate)
+
+```ts
+class User extends AggregateRoot<UserProps> {
+  static create(props: Optional<UserProps, 'createdAt'>, id?: UniqueEntityId): User {
+    const user = new User(
+      { ...props, createdAt: props.createdAt ?? new Date() },
+      id ?? new UniqueEntityId(),
+    )
+    user.addDomainEvent(new UserCreatedEvent(user))
+    return user
+  }
+}
+```
+
+## Defining a Handler
+
+```ts
+import type { EventHandler } from 'archstone/domain/enterprise'
+import { DomainEvents } from 'archstone/domain/enterprise'
+
+class OnUserCreated implements EventHandler {
+  constructor(private readonly mailer: Mailer) {}
+
+  setupSubscriptions(): void {
+    DomainEvents.register(
+      (event) => this.handle(event as UserCreatedEvent),
+      UserCreatedEvent.name,
+    )
+  }
+
+  private async handle(event: UserCreatedEvent): Promise<void> {
+    await this.mailer.send(event.user.email.value)
+  }
+}
+```
+
+## Dispatching (in repository, after persistence)
+
+```ts
+async create(user: User): Promise<void> {
+  await this.db.insert(user)
+  DomainEvents.dispatchEventsForAggregate(user.id) // UniqueEntityId, not string
+}
+```
+
+## Composition Root Registration
+
+```ts
+// Called once at app startup — in infrastructure, never in domain
+new OnUserCreated(mailer).setupSubscriptions()
+```
+
+## Common Mistakes
+
+```ts
+// ❌ dispatching before persisting
+DomainEvents.dispatchEventsForAggregate(user.id)
+await this.db.insert(user) // wrong order
+
+// ❌ passing string
+DomainEvents.dispatchEventsForAggregate(user.id.toValue()) // use UniqueEntityId
+
+// ❌ calling clearEvents() manually
+user.clearEvents() // dispatchEventsForAggregate handles this
+```

package/skills/archstone/references/entity.md

@@ -0,0 +1,75 @@
+# Entity & AggregateRoot Patterns
+
+## Rules
+
+- Extend `Entity<Props>` for identity-only entities
+- Extend `AggregateRoot<Props>` for entities that raise domain events
+- Always use a static `create()` factory — constructor stays `protected`
+- Include `id` as an optional field in `Props` and pass it as the second constructor argument
+- Use `Optional<T, K>` for auto-generated fields (e.g. `'id' | 'createdAt'`)
+- Use `UniqueEntityId` — never a plain `string`
+
+## Entity Example
+
+```ts
+import { Entity } from 'archstone/domain/enterprise'
+import { UniqueEntityId, type Optional } from 'archstone/core'
+
+interface ProductProps {
+  name: string
+  price: number
+  createdAt: Date
+}
+
+class Product extends Entity<ProductProps> {
+  get name()  { return this.props.name }
+  get price() { return this.props.price }
+
+  static create(props: Optional<ProductProps, 'createdAt'>, id?: UniqueEntityId): Product {
+    return new Product(
+      { ...props, createdAt: props.createdAt ?? new Date() },
+      id ?? new UniqueEntityId(),
+    )
+  }
+}
+```
+
+## AggregateRoot Example
+
+```ts
+import { AggregateRoot } from 'archstone/domain/enterprise'
+import { UniqueEntityId, type Optional } from 'archstone/core'
+
+interface OrderProps {
+  customerId: UniqueEntityId
+  total: number
+  createdAt: Date
+}
+
+class Order extends AggregateRoot<OrderProps> {
+  get customerId() { return this.props.customerId }
+  get total()      { return this.props.total }
+
+  static create(props: Optional<OrderProps, 'createdAt'>, id?: UniqueEntityId): Order {
+    const order = new Order(
+      { ...props, createdAt: props.createdAt ?? new Date() },
+      id ?? new UniqueEntityId(),
+    )
+    order.addDomainEvent(new OrderCreatedEvent(order))
+    return order
+  }
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ plain class
+class Order { id: string }
+
+// ❌ id not passed as second constructor arg
+return new Order(props) // id goes as second arg: new Order(props, id)
+
+// ❌ string id
+interface OrderProps { id: string } // use UniqueEntityId
+```

package/skills/archstone/references/imports.md

@@ -0,0 +1,13 @@
+# Archstone Import Reference
+
+| What | Import path |
+|---|---|
+| `Either`, `left`, `right` | `archstone/core` |
+| `ValueObject` | `archstone/core` |
+| `UniqueEntityId` | `archstone/core` |
+| `WatchedList` | `archstone/core` |
+| `Optional` | `archstone/core` |
+| `Entity`, `AggregateRoot` | `archstone/domain/enterprise` |
+| `DomainEvents`, `EventHandler` | `archstone/domain/enterprise` |
+| `UseCase`, `UseCaseError` | `archstone/domain/application` |
+| `Repository`, `Findable`, `Creatable`, `Saveable`, `Deletable` | `archstone/domain/application` |

package/skills/archstone/references/layers.md

@@ -0,0 +1,34 @@
+# Layer Rules
+
+## core/
+
+Zero domain knowledge. Contains only pure language utilities.
+
+Exports: `Either`, `left`, `right`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional`
+
+## domain/enterprise/
+
+Pure domain model. No framework or infrastructure dependencies.
+
+Contains: entities, aggregates, value objects, domain events, event handlers.
+
+## domain/application/
+
+Orchestration layer. Use cases and repository contracts only.
+
+Contains: use case interfaces, use case error contracts, repository interfaces.
+
+## Infrastructure (outside domain/)
+
+Database adapters, HTTP handlers, ORMs, email services — all live here.
+
+Repository implementations belong here, not in `domain/`.
+
+## Rule
+
+```
+core/ ← no deps
+domain/enterprise/ ← imports from core/ only
+domain/application/ ← imports from core/ and domain/enterprise/
+infrastructure/ ← imports from all layers, implements domain/application/ contracts
+```

package/skills/archstone/references/repository.md

@@ -0,0 +1,65 @@
+# Repository Patterns
+
+## Rules
+
+- Contracts are **interfaces only** — never place implementations in `domain/`
+- Extend `Repository<T>` for full CRUD, or compose granular interfaces:
+  - `Findable<T>` — `findById(id: string)` — takes `string`, not `UniqueEntityId`
+  - `Creatable<T>` — `create(entity: T)`
+  - `Saveable<T>` — `save(entity: T)`
+  - `Deletable<T>` — `delete(entity: T)` — takes full entity, not an id
+- Import via barrel: `archstone/domain/application`
+- Implementations belong in infrastructure
+- Inject as the **interface type** in use cases
+
+## Contract Example
+
+```ts
+import type { Repository, Creatable } from 'archstone/domain/application'
+
+// Full CRUD + custom method
+export interface UserRepository extends Repository<User> {
+  findByEmail(email: string): Promise<User | null>
+}
+
+// Compose only what you need
+export interface AuditRepository extends Creatable<AuditLog> {}
+```
+
+## In-Memory Implementation (for tests)
+
+```ts
+export class InMemoryUserRepository implements UserRepository {
+  public items: User[] = []
+
+  async findById(id: string) {
+    return this.items.find(u => u.id.toValue() === id) ?? null
+  }
+
+  async findByEmail(email: string) {
+    return this.items.find(u => u.email.value === email) ?? null
+  }
+
+  async create(user: User)  { this.items.push(user) }
+
+  async save(user: User) {
+    const i = this.items.findIndex(u => u.id.equals(user.id))
+    if (i >= 0) this.items[i] = user
+  }
+
+  async delete(user: User) {
+    this.items = this.items.filter(u => !u.id.equals(user.id))
+  }
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ concrete class in use case
+constructor(private repo: PrismaUserRepository) {}
+
+// ❌ UniqueEntityId to findById
+await repo.findById(user.id)           // wrong
+await repo.findById(user.id.toValue()) // correct
+```

package/skills/archstone/references/testing.md

@@ -0,0 +1,50 @@
+# Testing Patterns
+
+## Rules
+
+- Use `bun:test` — import `test`, `expect`, `beforeEach` from `bun:test`
+- Test files: `*.spec.ts` co-located with the source file they test
+- Use in-memory repository implementations for use case tests — never mock databases
+
+## Use Case Test Example
+
+```ts
+import { test, expect, beforeEach } from 'bun:test'
+import { GetUserUseCase } from './get-user'
+import { InMemoryUserRepository } from '@/test/repositories/in-memory-user-repository'
+
+let repo: InMemoryUserRepository
+let useCase: GetUserUseCase
+
+beforeEach(() => {
+  repo = new InMemoryUserRepository()
+  useCase = new GetUserUseCase(repo)
+})
+
+test('returns user when found', async () => {
+  const user = User.create({ name: 'João' })
+  await repo.create(user)
+
+  const result = await useCase.execute({ userId: user.id.toValue() })
+
+  expect(result.isRight()).toBe(true)
+  expect(result.value).toEqual(user)
+})
+
+test('returns error when user not found', async () => {
+  const result = await useCase.execute({ userId: 'non-existent' })
+
+  expect(result.isLeft()).toBe(true)
+})
+```
+
+## Domain Event Isolation
+
+```ts
+import { DomainEvents } from 'archstone/domain/enterprise'
+
+beforeEach(() => {
+  DomainEvents.clearHandlers()
+  DomainEvents.clearMarkedAggregates()
+})
+```

package/skills/archstone/references/use-case.md

@@ -0,0 +1,59 @@
+# UseCase + Either Patterns
+
+## Rules
+
+- Implement `UseCase<Input, Output>`
+- Output is always `Either<UseCaseError, Value>` — **never throw**
+- Error classes must `implement UseCaseError` (requires `message: string`) — not `extends Error`
+- Wrap value object construction in `try/catch` and return `left()`
+- Inject repositories via constructor typed as the **interface**
+
+## Example
+
+```ts
+import type { UseCase, UseCaseError } from 'archstone/domain/application'
+import { Either, left, right } from 'archstone/core'
+
+class UserNotFoundError implements UseCaseError {
+  message = 'User not found.'
+}
+
+class InvalidEmailError implements UseCaseError {
+  message = 'Invalid email address.'
+}
+
+type Input  = { userId: string; newEmail: string }
+type Output = Either<UserNotFoundError | InvalidEmailError, User>
+
+class UpdateUserEmailUseCase implements UseCase<Input, Output> {
+  constructor(private readonly repo: UserRepository) {} // interface, not concrete
+
+  async execute({ userId, newEmail }: Input): Promise<Output> {
+    const user = await this.repo.findById(userId)
+    if (!user) return left(new UserNotFoundError())
+
+    try {
+      const email = Email.create(newEmail)
+      user.updateEmail(email)
+    } catch {
+      return left(new InvalidEmailError())
+    }
+
+    await this.repo.save(user)
+    return right(user)
+  }
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ extends Error
+class UserNotFoundError extends Error {} // implement UseCaseError instead
+
+// ❌ throwing
+if (!user) throw new Error('not found') // return left(new UserNotFoundError())
+
+// ❌ concrete repo
+constructor(private repo: PrismaUserRepository) {} // use the interface
+```

package/skills/archstone/references/value-object.md

@@ -0,0 +1,57 @@
+# ValueObject Patterns
+
+## Rules
+
+- Extend `ValueObject<Props>`
+- Static `create()` factory with validation — may throw on invalid input (intentional)
+- Never mutate `this.props` — return a new instance instead
+- Compare with `.equals()` — never `===`
+
+## Example
+
+```ts
+import { ValueObject } from 'archstone/core'
+
+interface EmailProps { value: string }
+
+class Email extends ValueObject<EmailProps> {
+  get value() { return this.props.value }
+
+  static create(raw: string): Email {
+    if (!raw.includes('@')) throw new Error('Invalid email address')
+    return new Email({ value: raw.toLowerCase().trim() })
+  }
+
+  withDomain(domain: string): Email {
+    const [local] = this.props.value.split('@')
+    return new Email({ value: `${local}@${domain}` })
+  }
+}
+
+const a = Email.create('user@example.com')
+const b = Email.create('user@example.com')
+a.equals(b) // true
+```
+
+## Handling throws in use cases
+
+Since `create()` may throw, wrap it inside use cases:
+
+```ts
+try {
+  const email = Email.create(rawEmail)
+  user.updateEmail(email)
+} catch {
+  return left(new InvalidEmailError())
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ comparing with ===
+if (user.email === other.email) {} // use .equals()
+
+// ❌ mutating props
+this.props.value = newValue // return new Email({ value: newValue })
+```