@chaim-tools/chaim 0.1.5 → 0.1.7

package/README.md

@@ -1,110 +1,185 @@
 # chaim-cli
 
-A **schema-driven code generation tool** that transforms `.bprint` schema snapshots into complete SDKs with DynamoDB Mapper clients, DTOs, and configuration management. Currently supports **Java** (default), with more languages coming soon.
+The command-line tool that generates type-safe Java SDKs from your DynamoDB schema snapshots. It reads the local snapshots produced by `chaim-cdk`, groups entities by table, validates key consistency, and invokes the Java code generator to produce ready-to-use entity classes, repositories, validators, and configuration.
 
-## Prerequisite
+**npm**: [`@chaim-tools/chaim`](https://www.npmjs.com/package/@chaim-tools/chaim)
 
-> **IMPORTANT**: You must run `cdk synth` or `cdk deploy` in your CDK project before using this CLI.
+## Where This Fits
+
+```
+ .bprint file  ──>  chaim-cdk  ──>  chaim-cli  ──>  chaim-client-java
+                                        ^                    │
+                                        │                    v
+                                   YOU RUN THIS      Generated Java SDK
+```
+
+The CLI sits between the CDK construct and the code generator. It discovers cached snapshots from your file system, resolves table metadata (including GSIs and LSIs), and delegates to `chaim-client-java` for Java source file generation. The generated code supports all `.bprint` field types including recursive nesting (maps within maps, lists of maps within maps) with no depth limit.
+
+## Installation
 
 ```bash
-# In your CDK project directory
-cdk synth   # Creates LOCAL snapshot in OS cache
-# OR
-cdk deploy  # Creates LOCAL snapshot + publishes to Chaim SaaS
+npm install -g @chaim-tools/chaim
 ```
 
-The CLI reads snapshot files from the **OS cache** (`~/.chaim/cache/snapshots/`) produced by [chaim-cdk](https://github.com/chaim-tools/chaim-cdk). You can run the CLI from **any directory**.
+**Requirements**: Node.js 18+, Java 11+ (runtime for code generation)
 
 ## Quick Start
 
 ```bash
-# 1. In your CDK project, create a snapshot
+# 1. Synthesize your CDK project to create a local snapshot
 cd my-cdk-project
 cdk synth
 
-# 2. Generate SDK (run from your Java application directory)
-cd my-java-app
+# 2. Generate the Java SDK (run from your Java application directory)
+cd ../my-java-app
 chaim generate --package com.mycompany.myapp.model
 
-# That's it! Your Java SDK is ready in ./src/main/java/
+# Your Java SDK is now in ./src/main/java/
 ```
 
-## Installation
+The CLI reads snapshots from the OS cache (`~/.chaim/cache/snapshots/`). You can run it from any directory.
+
+## CDK Prerequisites
+
+Before running `chaim generate`, your CDK project must produce valid snapshots via `cdk synth`. The CDK construct enforces two important safeguards:
+
+- **Field reference validation** — All DynamoDB key attributes (table PK/SK, GSI/LSI keys, TTL attribute) must exist as fields in the `.bprint` schema. Mismatches fail the CDK synth immediately with a descriptive error.
+- **Strict failure mode** — Deployment defaults to `STRICT`, meaning ingestion failures cause CloudFormation rollback. Use `FailureMode.BEST_EFFORT` explicitly if you want deployment to continue on ingestion errors.
+
+## Commands
+
+### `chaim generate`
+
+Generates Java SDK code from local snapshots.
 
 ```bash
-npm install -g @chaim-tools/chaim
+chaim generate --package com.mycompany.myapp.model
 ```
 
-## System Requirements
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--package <name>` | Yes | — | Java package name (e.g., `com.mycompany.myapp.model`) |
+| `-l, --language <lang>` | No | `java` | Target language |
+| `--output <dir>` | No | `./src/main/java` | Output directory |
+| `--stack <name>` | No | — | Filter snapshots by CDK stack name |
+| `--snapshot-dir <path>` | No | OS cache | Override snapshot directory |
+| `--skip-checks` | No | `false` | Skip environment validation |
+
+**What it does**:
+
+1. Scans the OS cache for snapshot files produced by `chaim-cdk`
+2. Filters by stack name (if provided) and discards DELETE-action snapshots
+3. Groups entities by physical DynamoDB table (using table ARN or composite key)
+4. Validates that all entities sharing a table have matching partition/sort key field names
+5. Detects field name collisions from `nameOverride` or auto-conversion
+6. Passes schemas and table metadata (including GSI/LSI definitions) to the Java generator. LSI metadata does not include `partitionKey` — the generator uses the table's own partition key since LSIs always share it
+7. Writes generated `.java` files to the output directory
 
-Run `chaim doctor` to verify your environment:
+### `chaim validate`
+
+Validates a `.bprint` schema file and displays the field mapping table.
+
+```bash
+chaim validate ./schemas/user.bprint
+```
+
+### `chaim doctor`
+
+Checks your system environment for required dependencies.
 
 ```bash
 chaim doctor
 ```
 
-**Required:**
-- Node.js v18+
-- Java 11+ (for code generation)
-- AWS CLI (configured)
+Verifies: Node.js version, Java installation, AWS CLI availability.
 
-## CLI Commands
+### `chaim init`
 
-### Generate SDK
+Verifies and optionally installs prerequisites.
 
 ```bash
-# Generate all entities from snapshots (defaults to Java)
-chaim generate --package com.mycompany.myapp.model
-
-# Explicitly specify language
-chaim generate --package com.mycompany.myapp.model --language java
+chaim init              # Verify only
+chaim init --install    # Install missing dependencies
+```
 
-# Filter by CDK stack name
-chaim generate --package com.mycompany.myapp.model --stack MyStack
+### `chaim bump`
 
-# Custom output directory
-chaim generate --package com.mycompany.myapp.model --output ./generated
+Increments the `schemaVersion` in a `.bprint` file.
 
-# Skip environment checks
-chaim generate --package com.mycompany.myapp.model --skip-checks
+```bash
+chaim bump ./schemas/user.bprint            # minor bump: 1.3 -> 1.4
+chaim bump ./schemas/user.bprint --major    # major bump: 1.3 -> 2.0
 ```
 
-**Options:**
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `<schemaFile>` | Yes | — | Path to the `.bprint` file |
+| `--major` | No | `false` | Major version bump instead of minor |
 
-| Option | Required | Description | Default |
-|--------|----------|-------------|---------|
-| `--package` | **Yes** | Package name (e.g., `com.mycompany.myapp.model` for Java) | - |
-| `-l, --language` | No | Target language for code generation | java |
-| `--output` | No | Output directory | ./src/main/java |
-| `--stack` | No | Filter by CDK stack name | - |
-| `--snapshot-dir` | No | Override snapshot directory | OS cache |
-| `--skip-checks` | No | Skip environment checks | false |
+The `schemaVersion` is a customer-controlled field. The Chaim system validates during `cdk deploy` that the version was bumped when schema content changes. Use this command to increment the version before deploying.
 
-**Supported Languages:**
-- `java` (default) — generates Java DTOs, ChaimConfig, and ChaimMapperClient
+### `chaim clean`
 
-### Other Commands
+Prunes old or stack-specific snapshots from the local cache.
 
 ```bash
-# Verify prerequisites
-chaim init
+chaim clean --all                   # Remove all snapshots
+chaim clean --stack MyStack         # Remove snapshots for a specific stack
+chaim clean --older-than 30         # Remove snapshots older than 30 days
+chaim clean --dry-run               # Show what would be deleted
+```
 
-# Validate a schema file
-chaim validate ./schemas/user.bprint
+### `chaim context`
 
-# Check environment health
-chaim doctor
+Downloads an AI agent context file that teaches coding agents how to use the Chaim toolchain in your project.
+
+```bash
+chaim context                         # Write .chaim/CHAIM_AGENT_CONTEXT.md; auto-detect agents
+chaim context --agent cursor          # Also write .cursor/rules/chaim.md
+chaim context --agent all             # Write to all supported agent locations
+chaim context --no-auto               # Only write canonical file, skip auto-detection
+chaim context --remove                # Remove Chaim context from all locations
+chaim context --list-agents           # Show supported agents and detection status
 ```
 
+| Option | Description |
+|--------|-------------|
+| `--agent <name>` | Target a specific AI tool: `cursor`, `copilot`, `claude`, `windsurf`, `aider`, `generic`, `all` |
+| `--no-auto` | Skip auto-detection; only write the canonical `.chaim/CHAIM_AGENT_CONTEXT.md` |
+| `--remove` | Remove managed Chaim context blocks from all agent locations |
+| `--list-agents` | Show supported agents, their detection status, and file paths |
+
+**What it does**:
+
+1. Writes a comprehensive guide to `.chaim/CHAIM_AGENT_CONTEXT.md` (always)
+2. Auto-detects which AI tools are present (`.cursor/`, `CLAUDE.md`, `.windsurfrules`, etc.)
+3. Places the context into each detected tool's config location
+
+**Supported agents and placement strategy**:
+
+| Agent | File | Strategy |
+|-------|------|----------|
+| `cursor` | `.cursor/rules/chaim.md` | Dedicated file (overwrite) |
+| `copilot` | `.github/copilot-instructions.md` | Append managed block |
+| `claude` | `CLAUDE.md` | Append managed block |
+| `windsurf` | `.windsurfrules` | Append managed block |
+| `aider` | `.aider.conf.yml` | Add read-only reference |
+| `generic` | `AGENTS.md` | Append managed block |
+
+For append targets, the content is wrapped in HTML comment fences (`<!-- CHAIM_AGENT_CONTEXT_START -->` / `<!-- CHAIM_AGENT_CONTEXT_END -->`). Running the command again replaces the existing block in-place (idempotent). Existing content in those files is preserved.
+
 ## Snapshot Locations
 
-Snapshots are stored in a **global OS cache**, allowing the CLI to work from any directory.
+The CLI reads from the global OS cache, so it works regardless of your current directory.
 
-**Default locations:**
-- macOS/Linux: `~/.chaim/cache/snapshots/`
-- Windows: `%LOCALAPPDATA%/chaim/cache/snapshots/`
+| OS | Default Path |
+|----|--------------|
+| macOS / Linux | `~/.chaim/cache/snapshots/` |
+| Windows | `%LOCALAPPDATA%/chaim/cache/snapshots/` |
 
-**Directory structure:**
+Override with `CHAIM_SNAPSHOT_DIR` or `--snapshot-dir`.
+
+Directory structure:
 ```
 ~/.chaim/cache/snapshots/
 └── aws/
@@ -115,97 +190,311 @@ Snapshots are stored in a **global OS cache**, allowing the CLI to work from any
                     └── {resourceId}.json
 ```
 
-## Error: No Snapshot Found
+## Generated Output
+
+For a package `com.example.model` with `User` and `Order` entities on the same table:
+
+```
+src/main/java/com/example/model/
+├── User.java                          # Entity DTO (@DynamoDbBean + Lombok)
+├── Order.java                         # Entity DTO
+├── keys/
+│   ├── UserKeys.java                  # Key constants, INDEX_ constants, key() helper
+│   └── OrderKeys.java
+├── repository/
+│   ├── UserRepository.java            # save(), findByKey(), deleteByKey(), queryBy{Index}()
+│   └── OrderRepository.java
+├── validation/
+│   ├── UserValidator.java             # Required, constraint, and enum checks
+│   ├── OrderValidator.java
+│   └── ChaimValidationException.java  # Structured validation errors
+├── client/
+│   └── ChaimDynamoDbClient.java       # DI-friendly DynamoDB client wrapper
+└── config/
+    └── ChaimConfig.java               # Table constants, lazy client, repository factories
+```
+
+## Field Type Mappings
+
+| .bprint Type | Java Type | Notes |
+|--------------|-----------|-------|
+| `string` | `String` | |
+| `number` | `Double` | |
+| `boolean` | `Boolean` | |
+| `timestamp` | `Instant` | `java.time.Instant` |
+| `list` (scalar) | `List<String>`, `List<Double>`, etc. | Parameterized by `items.type` |
+| `list` (map) | `List<{FieldName}Item>` | Inner `@DynamoDbBean` class |
+| `map` | `{FieldName}` (inner class) | Inner `@DynamoDbBean` class; supports recursive nesting |
+| `stringSet` | `Set<String>` | |
+| `numberSet` | `Set<Double>` | |
 
-If you see "No snapshot found", **you need to create a snapshot first**. Snapshots are created by `chaim-cdk`:
+Recursive nesting is fully supported. A `map` field can contain nested `map` or `list` fields, which generate further inner static classes. There is no hardcoded depth limit — the database itself is the guardrail.
+
+## Using the Generated Code
+
+### Add Dependencies to Your Java Project
+
+The generated code requires these dependencies (Gradle example):
+
+```kotlin
+dependencies {
+    implementation("software.amazon.awssdk:dynamodb-enhanced:2.21.+")
+    compileOnly("org.projectlombok:lombok:1.18.+")
+    annotationProcessor("org.projectlombok:lombok:1.18.+")
+}
+```
+
+### Basic Usage
+
+```java
+// Use the generated config for a singleton client
+UserRepository users = ChaimConfig.userRepository();
+
+// Save an entity (validates constraints automatically)
+User user = User.builder()
+    .userId("user-123")
+    .email("alice@example.com")
+    .isActive(true)
+    .build();
+users.save(user);
+
+// Find by key
+Optional<User> found = users.findByKey("user-123");
+
+// Delete
+users.deleteByKey("user-123");
+```
+
+### GSI/LSI Queries
+
+The generator produces typed query methods for every GSI and LSI on the table. Each index generates a PK-only method and a PK+SK overloaded method (when the index has a sort key).
+
+```java
+OrderRepository orders = ChaimConfig.orderRepository();
+
+// GSI query — uses the GSI's own partition key
+List<Order> customerOrders = orders.queryByCustomerIndex("customer-123");
+
+// GSI query with sort key — PK + SK overload
+List<Order> filtered = orders.queryByCustomerDateIndex("customer-123", "2024-01-15");
+
+// LSI query — uses the table's partition key (LSIs always share it)
+List<Order> sorted = orders.queryByAmountIndex("order-456");
+List<Order> ranged = orders.queryByAmountIndex("order-456", "100.00");
+```
+
+### Custom Client (Local DynamoDB, Testing)
+
+```java
+ChaimDynamoDbClient client = ChaimConfig.clientBuilder()
+    .endpoint("http://localhost:8000")
+    .build();
+UserRepository users = ChaimConfig.userRepository(client);
+```
+
+## Troubleshooting
+
+### "No snapshot found"
+
+You need to create a snapshot first by running `cdk synth` or `cdk deploy` in your CDK project:
 
 ```bash
-# Navigate to your CDK project
 cd my-cdk-project
+cdk synth
+```
 
-# Create a snapshot
-cdk synth    # For development
-# OR
-cdk deploy   # For production
+Then run `chaim generate` from any directory.
 
-# Then generate (from any directory)
-chaim generate --package com.mycompany.myapp.model
+### Stack filter does not match
+
+The CLI shows existing snapshots that did not match your `--stack` filter, helping you adjust the value.
+
+## Using in Your Application Codebase
+
+A typical project layout:
+
+```
+my-cdk-project/                       # CDK infrastructure
+├── schemas/
+│   ├── user.bprint
+│   └── order.bprint
+├── lib/my-stack.ts
+└── package.json
+
+my-java-app/                          # Java application
+├── src/main/java/com/example/model/  # ← generated by `chaim generate`
+│   ├── User.java
+│   ├── Order.java
+│   └── ...
+├── src/main/java/com/example/        # Your application code
+│   └── service/UserService.java
+├── build.gradle.kts
+└── ...
 ```
 
-**Common causes:**
-- Haven't run `cdk synth` or `cdk deploy` yet
-- Filters (`--stack`) don't match existing snapshots
-- Snapshots in non-default location (use `--snapshot-dir`)
+Run `cdk synth` once, then `chaim generate --package com.example.model` in your Java project. Re-run whenever you change a `.bprint` file or add a new entity.
 
-**Tip:** The CLI shows existing snapshots that didn't match your filters, helping you adjust.
+## Development
 
-## Generated Output
+### Prerequisites
+
+- **Node.js 18+** — required for building and running the CLI
+- **npm** — comes with Node.js
 
+### Setup
+
+Clone the repository and install dependencies:
+
+```bash
+npm install
 ```
-src/main/java/com/mycompany/myapp/model/
-├── Users.java              # Entity DTO
-├── config/
-│   └── ChaimConfig.java    # Table configuration
-└── mapper/
-    └── ChaimMapperClient.java  # DynamoDB mapper
+
+Or use the included setup script, which validates your Node.js version, installs dependencies, and builds in one step:
+
+```bash
+npm run setup
 ```
 
-### Using the Generated SDK
+### Building
 
-```java
-// Create mapper client
-ChaimMapperClient mapper = ChaimConfig.createMapper();
+The CLI is written in TypeScript and compiles to `dist/` via the TypeScript compiler.
 
-// Save entity
-User user = new User();
-user.setUserId("user-123");
-user.setEmail("john@example.com");
-mapper.save(user);
+```bash
+npm run build          # Compile TypeScript → dist/
+```
 
-// Find by ID
-Optional<User> found = mapper.findById(User.class, "user-123");
+To start from a clean state:
+
+```bash
+npm run clean          # Delete dist/
+npm run build          # Rebuild
 ```
 
-## Optional Configuration
+The build emits CommonJS modules targeting ES2020 with declarations, declaration maps, and source maps (configured in `tsconfig.json`).
 
-Create `chaim.json` to set defaults:
+### Running Locally (Development)
 
-```json
-{
-  "defaults": {
-    "package": "com.mycompany.myapp.model",
-    "output": "./src/main/java"
-  }
-}
+You can run the CLI directly from source without compiling first:
+
+```bash
+npm run dev -- generate --package com.example.model
 ```
 
-Then run without arguments:
+Or after building, run the compiled output:
+
 ```bash
-chaim generate
+npm start -- generate --package com.example.model
+# equivalent to: node dist/index.js generate --package com.example.model
 ```
 
-## Field Type Mappings
+### Testing
+
+Tests use [Vitest](https://vitest.dev/) and live alongside the source files (`*.test.ts`).
 
-| .bprint Type | Java Type |
-|--------------|-----------|
-| `string` | `String` |
-| `number` | `Double` |
-| `boolean` | `Boolean` |
-| `timestamp` | `Instant` |
+```bash
+npm test               # Run all tests in watch mode
+```
 
-## Related Packages
+To run tests once (CI-friendly):
 
-| Package | Purpose |
-|---------|---------|
-| [chaim-cdk](https://github.com/chaim-tools/chaim-cdk) | AWS CDK constructs (creates snapshots) |
-| [chaim-bprint-spec](https://github.com/chaim-tools/chaim-bprint-spec) | Schema specification |
-| [chaim-client-java](https://github.com/chaim-tools/chaim-client-java) | Java code generation |
+```bash
+npx vitest run
+```
 
-## Getting Help
+To run a specific test file:
+
+```bash
+npx vitest run src/commands/generate.test.ts
+```
+
+Test files:
+
+| File | Covers |
+|------|--------|
+| `src/index.test.ts` | CLI entry point and command registration |
+| `src/commands/generate.test.ts` | `chaim generate` command |
+| `src/commands/validate.test.ts` | `chaim validate` command |
+| `src/commands/init.test.ts` | `chaim init` command |
+| `src/commands/doctor.test.ts` | `chaim doctor` command |
+| `src/commands/context.test.ts` | `chaim context` command |
+| `src/services/snapshot-discovery.test.ts` | Snapshot file discovery logic |
+| `src/services/name-resolver.test.ts` | Field name resolution and collision detection |
+
+### Linting
+
+The project uses ESLint with TypeScript support.
+
+```bash
+npm run lint           # Check for lint errors
+npm run lint:fix       # Auto-fix lint errors
+```
+
+### Project Structure
+
+```
+chaim-cli/
+├── src/                      # TypeScript source
+│   ├── index.ts              # CLI entry point (Commander.js)
+│   ├── commands/             # Command implementations
+│   │   ├── generate.ts
+│   │   ├── validate.ts
+│   │   ├── init.ts
+│   │   ├── doctor.ts
+│   │   ├── bump.ts
+│   │   ├── clean.ts
+│   │   └── context.ts
+│   └── services/             # Shared logic
+│       ├── snapshot-discovery.ts
+│       └── name-resolver.ts
+├── dist/                     # Compiled output (git-ignored)
+├── shared/
+│   ├── scripts/setup.sh      # One-time setup helper
+│   └── templates/
+│       └── CHAIM_AGENT_CONTEXT.md  # Bundled AI agent context template
+├── tsconfig.json             # TypeScript configuration
+├── .eslintrc.js              # ESLint configuration
+└── package.json
+```
+
+## Publishing to npm
+
+Publishing is automated via GitHub Actions. The workflow triggers when you create a GitHub release.
+
+### Steps
+
+1. **Update the version** in `package.json`:
+
+```bash
+npm version patch   # 0.1.5 → 0.1.6
+npm version minor   # 0.1.5 → 0.2.0
+npm version major   # 0.1.5 → 1.0.0
+```
+
+2. **Push the commit and tag**:
+
+```bash
+git push && git push --tags
+```
+
+3. **Create a GitHub release** from the tag. Go to the repository's **Releases** page, click **Draft a new release**, select the tag, and publish.
+
+4. The `publish.yml` workflow runs automatically: checks out the code, runs `npm ci`, builds, and publishes to npm with `--access public`.
+
+### Prerequisites
+
+- The repository must have an `NPM_TOKEN` secret configured in **Settings > Secrets and variables > Actions**. This token must have publish permissions for the `@chaim-tools` scope.
+
+### Manual Publishing (Emergency)
+
+If the workflow fails or you need to publish from your local machine:
+
+```bash
+npm run build
+npm publish --access public
+```
 
-- **Issues**: [GitHub Issues](https://github.com/chaim-tools/chaim-cli/issues)
-- **Examples**: [chaim-examples](https://github.com/chaim-tools/chaim-examples)
+You must be logged in to npm (`npm login`) with publish access to the `@chaim-tools` scope.
 
----
+## License
 
-**Chaim** means life, representing our mission: supporting the life (data) of software applications as they grow and evolve alongside businesses.
+Apache-2.0

package/dist/commands/bump.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Increment the schemaVersion in a .bprint file.
+ *
+ * Default is a minor bump (e.g., 1.3 -> 1.4).
+ * With --major, performs a major bump (e.g., 1.3 -> 2.0).
+ */
+export declare function bumpCommand(schemaFile: string, options: {
+    major?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=bump.d.ts.map

package/dist/commands/bump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bump.d.ts","sourceRoot":"","sources":["../../src/commands/bump.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Df"}