cayenne-cgen

<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> # cayenne-cgen Run Cayenne's class generator on a DataMap via the `mcp__cayenne__cgen_run` MCP tool. The tool reads the embedded `<cgen>` block in the DataMap to determine destination, mode, templates, etc.; **if no block is present the tool generates anyway using a sensible default config** (all entities, `makePairs=true`, destination derived from the Maven layout). A missing `<cgen>` block is **not** an error and must never stop you from running the tool. ## Required reading - `${CLAUDE_PLUGIN_ROOT}/references/mcp-tools.md` — `cgen_run` tool reference (arguments, return shape, failure modes). - `${CLAUDE_PLUGIN_ROOT}/references/cgen-config.md` — every `<cgen>` field; needed when the user has to add or tweak the config block. - `${CLAUDE_PLUGIN_ROOT}/references/project-layout.md` — locate the project descriptor. ## Step 1 — Resolve project and DataMap The MCP tool needs two arguments: - `projectPath` — **absolute path** to the top-level project descriptor (`cayenne-*.xml`). **Not** a DataMap file. - `dataMap` — the **name** as it appears in `<map name="...">` in the descriptor. **Not** a file path. Locate the descriptor via `project-layout.md`. If multiple descriptors exist, ask which one. Open the descriptor to extract the DataMap names from `<map>` elements. If the user named the DataMap directly (e.g. "regenerate classes for the customers DataMap"), use that. If they said "regenerate everything" and there are multiple DataMaps, run `cgen_run` once per DataMap in sequence (the tool generates per-DataMap). ## Step 2 — Call `cgen_run` ``` mcp__cayenne__cgen_run({ "projectPath": "<absolute path to cayenne-*.xml>", "dataMap": "<map name from the descriptor>" }) ``` Call the tool directly for each DataMap — never inspect the DataMap for a `<cgen>` block first, and never treat its absence as a blocker. The tool generates with a default config when no block exists. If the tool is not available (MCP server not registered), surface `cayenne-mcp-server/README.md` and stop. **Do not** suggest `mvn cayenne:cgen` or the Gradle cgen task. ## Step 3 — Surface the result The tool returns structured JSON. Report: - `summary.filesConsidered` and `summary.filesWritten` verbatim — these are the headline. - The first few entries in `files` (relative paths). Full list is informational; offer to dump it if the user asks. - `error`, when non-null — this is blocking. Read the message and explain in user terms (a missing entity class name, a bad template path, an invalid `<destDir>`, etc.). - `resolved.destDir` — the absolute output directory. If the DataMap had no `<cgen>` block, the tool generated from a synthesized default; report this destination so the user can confirm it's right, and offer to persist a `<cgen>` block (via `cayenne-modeling`) if they want to customize destination, templates, or entity filtering. cgen always runs in full, but rewrites a file only when the generated contents differ from what is on disk. So `files` is exactly what changed, and a `status` of `up_to_date` means the Java was already in sync with the model — say so plainly rather than implying work was skipped. ## Step 4 — Next steps - If new `_<Entity>.java` superclass files were generated, gently remind the user not to edit those — they will be overwritten next run. User code goes in the matching `<Entity>.java` subclass. - If the user just ran reverse engineering, this skill is the natural follow-up. Cross-link back to `cayenne-modeling` if they need to tweak names/types before regenerating. ## Anti-patterns - **Do not** pre-check the DataMap for a `<cgen>` block before calling `cgen_run`, and **do not** add a block before running. A missing block is not an error — the tool generates with defaults. Only add a `<cgen>` block afterward if the user wants to persist or customize the config. - **Do not** suggest Maven (`mvn cayenne:cgen`) or Gradle (`cayenneCgen`) goals when MCP is unavailable. Those build plugins are out of scope. Point at MCP setup instead. - **Do not** edit `_<Entity>.java` files. Generated superclasses. Edit `<Entity>.java` subclasses. - **Do not** confuse `projectPath` and `dataMap` arguments. `projectPath` is a file system path to `cayenne-*.xml`. `dataMap` is a logical name (e.g. `mydb`), not a path to `mydb.map.xml`.