# Iris Library Generator

Generate a new TypeScript library for the Iris AI Assistant platform with a
standardized structure.

## Usage

### Basic Usage

```bash
# Using Nx generate
nx generate @oshun/tools:iris-library --name=my-lib --description="My awesome library"

# Short form
nx g @oshun/tools:iris-library my-lib
```

### With Options

```bash
nx generate @oshun/tools:iris-library \
  --name=memory-manager \
  --description="Advanced memory management for Iris" \
  --layer=core \
  --dependencies=types,core \
  --withTests=true
```

## Options

| Option         | Type      | Default        | Description                                            |
| -------------- | --------- | -------------- | ------------------------------------------------------ |
| `name`         | `string`  | (required)     | The name of the library (e.g., 'memory', 'agent')      |
| `description`  | `string`  | (required)     | A short description of the library's purpose           |
| `layer`        | `string`  | `'domain'`     | Architectural layer: core, domain, infra, api, testing |
| `directory`    | `string`  | `'libs/iris'`  | Parent directory for the library                       |
| `importPath`   | `string`  | `@iris/<name>` | Custom import path                                     |
| `dependencies` | `array`   | `[]`           | List of Iris library dependencies (e.g., ['types'])    |
| `withTests`    | `boolean` | `true`         | Generate test files and vitest configuration           |
| `withExports`  | `boolean` | `true`         | Generate sample exports in index.ts                    |

## Generated Structure

```
libs/iris/<name>/
├── src/
│   ├── index.ts           # Main exports
│   ├── <name>.ts          # Main module with types and classes
│   └── <name>.test.ts     # Unit tests
├── project.json           # Nx project configuration
├── package.json           # Package configuration (ESM)
├── tsconfig.json          # TypeScript base config
├── tsconfig.lib.json      # Library compilation config
├── tsconfig.spec.json     # Test compilation config
├── vitest.config.ts       # Vitest configuration
└── README.md              # Documentation
```

## Features

### Project Configuration

The generator creates a `project.json` with:

- **Tags**: `scope:iris`, `type:lib`, `layer:<layer>`
- **Targets**:
  - `build`: TypeScript compilation with `@nx/js:tsc`
  - `lint`: ESLint with `@nx/eslint:lint`
  - `test`: Vitest with `@nx/vite:test`
  - `typecheck`: Type checking with `tsc --noEmit`

### TypeScript Configuration

- Modern ESM configuration with `NodeNext` module resolution
- Strict type checking enabled
- Separate configs for library and test compilation
- Project references for optimal incremental builds

### Package Configuration

- ESM-first with dual exports
- Proper `exports` field for submodule imports
- Catalog dependencies from pnpm workspace
- Node.js 20+ engine requirement

### Testing

- Vitest configuration with globals
- V8 coverage provider
- HTML and JSON coverage reports
- Test file patterns: `*.test.ts`, `*.spec.ts`

## Architectural Layers

| Layer       | Description                          | Example Libraries                |
| ----------- | ------------------------------------ | -------------------------------- |
| `core`      | Core utilities and base abstractions | `@iris/core`, `@iris/config`     |
| `domain`    | Domain-specific business logic       | `@iris/memory`, `@iris/agent`    |
| `infra`     | Infrastructure and external adapters | `@iris/database`, `@iris/cache`  |
| `api`       | API contracts and route handlers     | `@iris/api`                      |
| `testing`   | Test utilities and mocks             | `@iris/testing`                  |
| `contracts` | Shared types and schemas             | `@iris/types`, `@iris/contracts` |

## Examples

### Create a Core Library

```bash
nx g @oshun/tools:iris-library \
  --name=logger \
  --description="Structured logging for Iris" \
  --layer=core
```

### Create a Domain Library with Dependencies

```bash
nx g @oshun/tools:iris-library \
  --name=conversation \
  --description="Conversation management and dialogue" \
  --layer=domain \
  --dependencies=types,core,memory
```

### Create a Testing Library

```bash
nx g @oshun/tools:iris-library \
  --name=test-utils \
  --description="Testing utilities and mocks" \
  --layer=testing \
  --withTests=false
```

## After Generation

1. **Install dependencies**:

   ```bash
   pnpm install
   ```

2. **Implement your library**: Edit `src/<name>.ts` with your actual
   implementation.

3. **Add tests**: Update `src/<name>.test.ts` with comprehensive tests.

4. **Build and verify**:

   ```bash
   nx build @iris/<name>
   nx test @iris/<name>
   nx lint @iris/<name>
   ```

5. **Use in other libraries**:
   ```typescript
   import { MyClass } from '@iris/<name>';
   ```

## Integration with Nx

The generator automatically:

- Adds path mappings to `tsconfig.base.json`
- Updates `pnpm-workspace.yaml` if needed
- Creates proper project configuration for Nx graph

You can verify the integration:

```bash
# View project graph
nx graph

# Run affected tests
nx affected:test

# Build all Iris libraries
nx run-many --target=build --projects=tag:scope:iris
```
