@chaim-tools/chaim 0.1.4 → 0.1.6

package/README.md

@@ -1,110 +1,146 @@
 # 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**:
 
-Run `chaim doctor` to verify your environment:
+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
+
+### `chaim validate`
+
+Validates a `.bprint` schema file and displays the field mapping table.
 
 ```bash
-chaim doctor
+chaim validate ./schemas/user.bprint
 ```
 
-**Required:**
-- Node.js v18+
-- Java 11+ (for code generation)
-- AWS CLI (configured)
+### `chaim doctor`
 
-## CLI Commands
-
-### Generate SDK
+Checks your system environment for required dependencies.
 
 ```bash
-# Generate all entities from snapshots (defaults to Java)
-chaim generate --package com.mycompany.myapp.model
+chaim doctor
+```
 
-# Explicitly specify language
-chaim generate --package com.mycompany.myapp.model --language java
+Verifies: Node.js version, Java installation, AWS CLI availability.
 
-# Filter by CDK stack name
-chaim generate --package com.mycompany.myapp.model --stack MyStack
+### `chaim init`
 
-# Custom output directory
-chaim generate --package com.mycompany.myapp.model --output ./generated
+Verifies and optionally installs prerequisites.
 
-# Skip environment checks
-chaim generate --package com.mycompany.myapp.model --skip-checks
+```bash
+chaim init              # Verify only
+chaim init --install    # Install missing dependencies
 ```
 
-**Options:**
+### `chaim bump`
 
-| 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 |
+Increments the `schemaVersion` in a `.bprint` file.
 
-**Supported Languages:**
-- `java` (default) — generates Java DTOs, ChaimConfig, and ChaimMapperClient
+```bash
+chaim bump ./schemas/user.bprint            # minor bump: 1.3 -> 1.4
+chaim bump ./schemas/user.bprint --major    # major bump: 1.3 -> 2.0
+```
 
-### Other Commands
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `<schemaFile>` | Yes | — | Path to the `.bprint` file |
+| `--major` | No | `false` | Major version bump instead of minor |
 
-```bash
-# Verify prerequisites
-chaim init
+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.
 
-# Validate a schema file
-chaim validate ./schemas/user.bprint
+### `chaim clean`
 
-# Check environment health
-chaim doctor
+Prunes old or stack-specific snapshots from the local cache.
+
+```bash
+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
 ```
 
 ## 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 +151,306 @@ 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>` | |
+
+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
 
-If you see "No snapshot found", **you need to create a snapshot first**. Snapshots are created by `chaim-cdk`:
+### "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.
+
+```bash
+npm run build          # Compile TypeScript → dist/
+```
 
-// Save entity
-User user = new User();
-user.setUserId("user-123");
-user.setEmail("john@example.com");
-mapper.save(user);
+To start from a clean state:
 
-// Find by ID
-Optional<User> found = mapper.findById(User.class, "user-123");
+```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`).
+
+```bash
+npm test               # Run all tests in watch mode
+```
+
+To run tests once (CI-friendly):
+
+```bash
+npx vitest run
+```
+
+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/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
+│   └── services/             # Shared logic
+│       ├── snapshot-discovery.ts
+│       └── name-resolver.ts
+├── dist/                     # Compiled output (git-ignored)
+├── shared/scripts/setup.sh   # One-time setup helper
+├── tsconfig.json             # TypeScript configuration
+├── .eslintrc.js              # ESLint configuration
+└── package.json
+```
 
-| .bprint Type | Java Type |
-|--------------|-----------|
-| `string` | `String` |
-| `number` | `Double` |
-| `boolean` | `Boolean` |
-| `timestamp` | `Instant` |
+## Publishing to npm
 
-## Related Packages
+Publishing is automated via GitHub Actions. The workflow triggers when you create a GitHub release.
 
-| 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 |
+### Steps
 
-## Getting Help
+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"}

package/dist/commands/bump.js

@@ -0,0 +1,90 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bumpCommand = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 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).
+ */
+async function bumpCommand(schemaFile, options) {
+    try {
+        const resolvedPath = path.resolve(schemaFile);
+        if (!fs.existsSync(resolvedPath)) {
+            console.error(chalk_1.default.red(`Error: File not found: ${schemaFile}`));
+            process.exit(1);
+        }
+        if (!schemaFile.endsWith('.bprint')) {
+            console.error(chalk_1.default.red('Error: File must have a .bprint extension'));
+            process.exit(1);
+        }
+        const content = fs.readFileSync(resolvedPath, 'utf-8');
+        let schema;
+        try {
+            schema = JSON.parse(content);
+        }
+        catch {
+            console.error(chalk_1.default.red('Error: File is not valid JSON'));
+            process.exit(1);
+        }
+        const currentVersion = schema.schemaVersion;
+        if (!currentVersion || typeof currentVersion !== 'string') {
+            console.error(chalk_1.default.red('Error: File does not contain a valid schemaVersion field'));
+            process.exit(1);
+        }
+        const versionPattern = /^\d+\.\d+$/;
+        if (!versionPattern.test(currentVersion)) {
+            console.error(chalk_1.default.red(`Error: Current schemaVersion "${currentVersion}" is not in "major.minor" format`));
+            process.exit(1);
+        }
+        const [major, minor] = currentVersion.split('.').map(Number);
+        let newVersion;
+        if (options.major) {
+            newVersion = `${major + 1}.0`;
+        }
+        else {
+            newVersion = `${major}.${minor + 1}`;
+        }
+        schema.schemaVersion = newVersion;
+        fs.writeFileSync(resolvedPath, JSON.stringify(schema, null, 2) + '\n', 'utf-8');
+        const fileName = path.basename(schemaFile);
+        const bumpType = options.major ? 'major' : 'minor';
+        console.log(chalk_1.default.green(`Bumped ${fileName}: ${currentVersion} -> ${newVersion}`) +
+            chalk_1.default.gray(` (${bumpType})`));
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('Error:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+exports.bumpCommand = bumpCommand;
+//# sourceMappingURL=bump.js.map

package/dist/commands/bump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bump.js","sourceRoot":"","sources":["../../src/commands/bump.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -5,12 +5,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
+const fs_1 = require("fs");
+const path_1 = require("path");
 const generate_1 = require("./commands/generate");
 const validate_1 = require("./commands/validate");
 const doctor_1 = require("./commands/doctor");
 const init_1 = require("./commands/init");
 const clean_1 = require("./commands/clean");
+const bump_1 = require("./commands/bump");
 const chalk_1 = __importDefault(require("chalk"));
+const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf-8'));
 /**
  * ==========================
  * Planned Commands (Roadmap)
@@ -39,7 +43,7 @@ const program = new commander_1.Command();
 program
     .name('chaim')
     .description('Schema-driven code generation tool for DynamoDB')
-    .version('0.1.0');
+    .version(pkg.version);
 program
     .command('generate')
     .description('Generate SDK code from LOCAL snapshot (reads from OS cache)')
@@ -75,6 +79,12 @@ program
     .option('--dry-run', 'Show what would be deleted without deleting')
     .option('--verbose', 'Show detailed output')
     .action(clean_1.cleanCommand);
+program
+    .command('bump')
+    .description('Increment the schemaVersion in a .bprint file')
+    .argument('<schemaFile>', '.bprint file to version bump')
+    .option('--major', 'Major version bump (X.Y -> X+1.0) instead of minor (X.Y -> X.Y+1)')
+    .action(bump_1.bumpCommand);
 /**
  * ==========================
  * Planned Command Registration
@@ -104,6 +114,7 @@ if (process.argv.length <= 2) {
     console.log('  init      - Verify and install all prerequisites');
     console.log('  generate  - Generate SDK code from CDK snapshot (default: java)');
     console.log('  validate  - Validate a .bprint schema file');
+    console.log('  bump      - Increment the schemaVersion in a .bprint file');
     console.log('  doctor    - Check system environment and dependencies');
     console.log('  clean     - Clean snapshot cache (remove old or stale snapshots)');
     console.log('');

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types/snapshot-payload.d.ts

@@ -55,7 +55,7 @@ export interface Annotations {
  * Schema v1.1 - flattened structure (no nested entity object).
  */
 export interface SchemaData {
-    schemaVersion: number;
+    schemaVersion: string;
     entityName: string;
     description: string;
     primaryKey: PrimaryKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaim-tools/chaim",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Schema-driven code generation tool for DynamoDB - Pure TypeScript CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,13 +18,13 @@
   },
   "scripts": {
     "build": "npm run build:cli",
-    "build:cli": "tsc",
+    "build:cli": "npx tsc",
     "setup": "./shared/scripts/setup.sh",
     "clean": "rm -rf dist",
-    "test": "vitest",
-    "lint": "eslint . --ext .ts",
-    "lint:fix": "eslint . --ext .ts --fix",
-    "dev": "ts-node src/index.ts",
+    "test": "npx vitest",
+    "lint": "npx eslint . --ext .ts",
+    "lint:fix": "npx eslint . --ext .ts --fix",
+    "dev": "npx ts-node src/index.ts",
     "start": "node dist/index.js"
   },
   "keywords": [
@@ -47,8 +47,8 @@
   "homepage": "https://github.com/chaim-tools/chaim-cli#readme",
   "dependencies": {
     "@aws-sdk/client-sts": "^3.883.0",
-    "@chaim-tools/chaim-bprint-spec": "^0.2.4",
-    "@chaim-tools/client-java": "^0.1.3",
+    "@chaim-tools/chaim-bprint-spec": "^0.2.5",
+    "@chaim-tools/client-java": "^0.1.5",
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
     "ora": "^5.4.1"

package/shared/scripts/setup.sh

@@ -1,47 +1,41 @@
 #!/bin/bash
 
-echo "🚀 Setting up Chaim CLI (TypeScript)"
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+echo "Setting up Chaim CLI (TypeScript)"
+echo ""
 
 # Check if Node.js is installed
 if ! command -v node &> /dev/null; then
-    echo "❌ Node.js is not installed. Please install Node.js v18 or higher."
+    echo "ERROR: Node.js is not installed. Please install Node.js v18 or higher."
     exit 1
 fi
 
 # Check Node.js version
 NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
 if [ "$NODE_VERSION" -lt 18 ]; then
-    echo "❌ Node.js version 18 or higher is required. Current version: $(node -v)"
+    echo "ERROR: Node.js version 18 or higher is required. Current version: $(node -v)"
     exit 1
 fi
 
-echo "✅ Node.js version: $(node -v)"
+echo "Node.js version: $(node -v) OK"
 
 # Install dependencies
-echo "📦 Installing CLI dependencies..."
-cd cli && npm install
+echo "Installing dependencies..."
+cd "$PROJECT_ROOT"
+npm install
 
 # Build the TypeScript CLI
-echo "🔨 Building TypeScript CLI..."
-npm run build
-
-# Build Java modules (for code generation)
-echo "☕ Building Java modules..."
-cd ../java
-if [ -f "gradlew" ]; then
-    ./gradlew :schema-core:build
-    ./gradlew :codegen-java:build
-    ./gradlew :cdk-integration:build
-else
-    echo "⚠️  Gradle wrapper not found. Please install Gradle and run:"
-    echo "   gradle :schema-core:build"
-    echo "   gradle :codegen-java:build"
-    echo "   gradle :cdk-integration:build"
-fi
+echo "Building TypeScript CLI..."
+npx tsc
 
-echo "✅ Setup complete!"
+echo ""
+echo "Setup complete!"
 echo ""
 echo "Usage:"
-echo "  ./cli/dist/index.js generate --stack MyStack --package com.example"
-echo "  ./cli/dist/index.js validate ./shared/examples/user.bprint"
-echo "  ./cli/dist/index.js doctor"
+echo "  npx chaim generate --stack MyStack --package com.example"
+echo "  npx chaim validate ./schemas/user.bprint"
+echo "  npx chaim doctor"