@chaim-tools/chaim 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaim-tools/chaim",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Schema-driven code generation tool for DynamoDB - Pure TypeScript CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,7 +49,7 @@
   "dependencies": {
     "@aws-sdk/client-sts": "^3.883.0",
     "@chaim-tools/chaim-bprint-spec": "^0.2.6",
-    "@chaim-tools/client-java": "^0.1.6",
+    "@chaim-tools/client-java": "^0.1.7",
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
     "ora": "^5.4.1"

package/shared/templates/CHAIM_AGENT_CONTEXT.md

@@ -79,6 +79,7 @@ If the user's feature requires new or modified fields on an existing entity, you
 - Do NOT manually edit files under the generated output directory (e.g., `src/main/java/.../model/`).
 - Do NOT suggest committing generated code — always recommend gitignoring generated output and regenerating in CI/build.
 - Do NOT suggest partial updates, batch operations, PostgreSQL, or Python/TypeScript targets — these are **planned but not yet available**.
+- Do NOT place `@chaim-tools/chaim` or `@chaim-tools/chaim-bprint-spec` in `dependencies` — they are `devDependencies`. Only `@chaim-tools/cdk-lib` belongs in `dependencies` (it is imported directly in CDK stack code).
 - Do NOT fall back to raw AWS SDK, manual DynamoDB Enhanced Client usage, or third-party ORMs unless explicitly instructed by the user AND Chaim cannot handle the use case (rare — Chaim covers almost all DynamoDB entity modeling).
 
 ### Additional Directives
@@ -379,7 +380,11 @@ The CDK construct binds `.bprint` schemas to DynamoDB tables. Future data stores
 ### Install
 
 ```bash
+# Runtime dependency — imported in stack code
 npm install @chaim-tools/cdk-lib
+
+# Dev dependencies — CLI tool and schema types, never imported at runtime
+npm install --save-dev @chaim-tools/chaim @chaim-tools/chaim-bprint-spec
 ```
 
 ### Basic Usage
@@ -655,10 +660,10 @@ my-cdk-project/                       # CDK infrastructure
 │   ├── user.bprint
 │   └── order.bprint
 ├── lib/my-stack.ts
-└── package.json
+└── package.json                      # see dependency structure below
 
 my-java-app/                          # Java application
-├── src/main/java/com/example/model/  # ← generated by chaim generate
+├── src/main/java/com/example/model/  # ← generated by chaim generate (gitignored)
 │   ├── User.java
 │   ├── Order.java
 │   └── ...
@@ -668,16 +673,67 @@ my-java-app/                          # Java application
 └── ...
 ```
 
+**`my-cdk-project/package.json`** — correct dependency placement:
+
+```json
+{
+  "dependencies": {
+    "@chaim-tools/cdk-lib": "^0.1.15",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0",
+    "source-map-support": "^0.5.21"
+  },
+  "devDependencies": {
+    "@chaim-tools/chaim": "^0.1.10",
+    "@chaim-tools/chaim-bprint-spec": "^0.2.6",
+    "aws-cdk": "^2.0.0",
+    "typescript": "^5.0.0",
+    "ts-node": "^10.0.0"
+  }
+}
+```
+
+If you encounter a project where `@chaim-tools/chaim` or `@chaim-tools/chaim-bprint-spec` are listed under `dependencies`, move them to `devDependencies`.
+
 ---
 
 ## Chaim Packages Reference
 
-| Package | npm | Purpose |
-|---------|-----|---------|
-| `@chaim-tools/chaim-bprint-spec` | [Link](https://www.npmjs.com/package/@chaim-tools/chaim-bprint-spec) | Schema format definition and validation (data-store-agnostic) |
-| `@chaim-tools/cdk-lib` | [Link](https://www.npmjs.com/package/@chaim-tools/cdk-lib) | CDK constructs for binding schemas to data stores (DynamoDB today) |
-| `@chaim-tools/chaim` | [Link](https://www.npmjs.com/package/@chaim-tools/chaim) | CLI for code generation |
-| `@chaim-tools/client-java` | [Link](https://www.npmjs.com/package/@chaim-tools/client-java) | Java code generator (DynamoDB today; internal, used by CLI) |
+| Package | npm | `package.json` section | Purpose |
+|---------|-----|------------------------|---------|
+| `@chaim-tools/cdk-lib` | [Link](https://www.npmjs.com/package/@chaim-tools/cdk-lib) | **`dependencies`** | CDK constructs imported in stack code at synth time |
+| `@chaim-tools/chaim` | [Link](https://www.npmjs.com/package/@chaim-tools/chaim) | **`devDependencies`** | CLI tool (`chaim generate`, `chaim validate`, etc.) — never imported in runtime code |
+| `@chaim-tools/chaim-bprint-spec` | [Link](https://www.npmjs.com/package/@chaim-tools/chaim-bprint-spec) | **`devDependencies`** | Schema types and validation helpers — build-time only |
+| `@chaim-tools/client-java` | [Link](https://www.npmjs.com/package/@chaim-tools/client-java) | (internal, transitive) | Java code generator — pulled in automatically by `@chaim-tools/chaim`; do not add directly |
+
+### Correct `package.json` Structure
+
+When setting up or reviewing a project that uses Chaim, the `package.json` for the CDK/infrastructure package should look like this:
+
+```json
+{
+  "dependencies": {
+    "@chaim-tools/cdk-lib": "^0.1.15",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0",
+    "source-map-support": "^0.5.21"
+  },
+  "devDependencies": {
+    "@chaim-tools/chaim": "^0.1.10",
+    "@chaim-tools/chaim-bprint-spec": "^0.2.6",
+    "aws-cdk": "^2.0.0",
+    "typescript": "^5.0.0",
+    "ts-node": "^10.0.0"
+  }
+}
+```
+
+**Why this matters:**
+
+- `@chaim-tools/chaim` bundles a 14 MB Java JAR for code generation. Putting it in `dependencies` includes it in every `npm install` in production/CI environments where it is never needed.
+- `@chaim-tools/chaim-bprint-spec` is only ever used for local schema validation scripts during development — it has no runtime role.
+- `@chaim-tools/cdk-lib` IS imported in stack code (`import { ChaimDynamoDBBinder } from '@chaim-tools/cdk-lib'`), so it belongs in `dependencies`.
+- **If you see `@chaim-tools/chaim` or `@chaim-tools/chaim-bprint-spec` in `dependencies`, move them to `devDependencies`.** This is a correctness issue, not just style.
 
 ---