modscape 2.0.1 → 2.0.3

package/src/table.js

@@ -0,0 +1,118 @@
+import { Command } from 'commander';
+import { readYaml, writeYaml, findTableById, outputError, outputWarn, outputOk } from './model-utils.js';
+
+export function tableCommand() {
+  const cmd = new Command('table').description('Manage tables in a YAML model');
+
+  // list
+  cmd
+    .command('list <file>')
+    .description('List all tables in the model')
+    .option('--json', 'output as JSON')
+    .action((file, opts) => {
+      const data = readYaml(file);
+      const tables = (data.tables || []).map(t => ({ id: t.id, name: t.name }));
+      if (opts.json) {
+        console.log(JSON.stringify(tables));
+      } else {
+        if (tables.length === 0) {
+          console.log('  (no tables)');
+        } else {
+          tables.forEach(t => console.log(`  ${t.id}  ${t.name || ''}`));
+        }
+      }
+    });
+
+  // get
+  cmd
+    .command('get <file>')
+    .description('Get a table definition by ID')
+    .requiredOption('--id <id>', 'table ID')
+    .option('--json', 'output as JSON')
+    .action((file, opts) => {
+      const data = readYaml(file);
+      const table = findTableById(data, opts.id);
+      if (!table) return outputError(opts.json, `Table "${opts.id}" not found`);
+      if (opts.json) {
+        console.log(JSON.stringify(table));
+      } else {
+        console.log(JSON.stringify(table, null, 2));
+      }
+    });
+
+  // add
+  cmd
+    .command('add <file>')
+    .description('Add a new table to the model')
+    .requiredOption('--id <id>', 'table ID (snake_case)')
+    .requiredOption('--name <name>', 'conceptual name')
+    .option('--type <type>', 'appearance type (fact|dimension|mart|hub|link|satellite|table)')
+    .option('--logical-name <name>', 'logical (business) name')
+    .option('--physical-name <name>', 'physical (database) table name')
+    .option('--description <text>', 'conceptual description')
+    .option('--json', 'output as JSON')
+    .action((file, opts) => {
+      const data = readYaml(file);
+      if (findTableById(data, opts.id)) {
+        return outputError(opts.json, `Table "${opts.id}" already exists`, 'Use `table update` instead');
+      }
+      const table = { id: opts.id, name: opts.name };
+      if (opts.logicalName) table.logical_name = opts.logicalName;
+      if (opts.physicalName) table.physical_name = opts.physicalName;
+      if (opts.type) table.appearance = { type: opts.type };
+      if (opts.description) table.conceptual = { description: opts.description };
+      if (!data.tables) data.tables = [];
+      data.tables.push(table);
+      writeYaml(file, data);
+      outputOk(opts.json, 'add', 'table', opts.id);
+    });
+
+  // update
+  cmd
+    .command('update <file>')
+    .description('Update fields of an existing table')
+    .requiredOption('--id <id>', 'table ID to update')
+    .option('--name <name>', 'conceptual name')
+    .option('--type <type>', 'appearance type')
+    .option('--logical-name <name>', 'logical (business) name')
+    .option('--physical-name <name>', 'physical (database) table name')
+    .option('--description <text>', 'conceptual description')
+    .option('--json', 'output as JSON')
+    .action((file, opts) => {
+      const data = readYaml(file);
+      const table = findTableById(data, opts.id);
+      if (!table) return outputError(opts.json, `Table "${opts.id}" not found`, 'Use `table add` instead');
+      if (opts.name) table.name = opts.name;
+      if (opts.logicalName) table.logical_name = opts.logicalName;
+      if (opts.physicalName) table.physical_name = opts.physicalName;
+      if (opts.type) {
+        table.appearance = table.appearance || {};
+        table.appearance.type = opts.type;
+      }
+      if (opts.description) {
+        table.conceptual = table.conceptual || {};
+        table.conceptual.description = opts.description;
+      }
+      writeYaml(file, data);
+      outputOk(opts.json, 'update', 'table', opts.id);
+    });
+
+  // remove
+  cmd
+    .command('remove <file>')
+    .description('Remove a table from the model')
+    .requiredOption('--id <id>', 'table ID to remove')
+    .option('--json', 'output as JSON')
+    .action((file, opts) => {
+      const data = readYaml(file);
+      const before = (data.tables || []).length;
+      data.tables = (data.tables || []).filter(t => t.id !== opts.id);
+      if (data.tables.length === before) {
+        return outputWarn(opts.json, `Table "${opts.id}" not found, nothing removed`);
+      }
+      writeYaml(file, data);
+      outputOk(opts.json, 'remove', 'table', opts.id);
+    });
+
+  return cmd;
+}

package/src/templates/claude/modeling.md

@@ -1,10 +1,23 @@
 Start an interactive data modeling session.
 
 ## Instructions
-1. FIRST, read `.modscape/rules.md` to understand the project strategy, naming conventions, and YAML schema.
+1. FIRST, read `.modscape/rules.md` to understand the project strategy, naming conventions, and YAML schema. If `.modscape/rules.custom.md` exists, read it too — custom rules take priority over the base rules.
 2. SECOND, analyze the existing `model.yaml` if it exists.
 3. Listen to the user's requirements and propose/apply changes to `model.yaml` strictly following the rules.
 
+## Mutation CLI — Use Before Editing YAML Directly
+
+For targeted changes to tables, columns, relationships, lineage, or domains, **PREFER the mutation CLI commands** over editing YAML directly. CLI commands validate input and write atomically.
+
+Recommended flow:
+1. Check existence: `modscape table get model.yaml --id <id> --json`
+2. Add or update: `modscape table add` / `modscape table update`
+3. After adding tables: `modscape layout model.yaml` to assign coordinates
+
+See Section 13 of `.modscape/rules.md` for the full command reference.
+
+Only edit YAML directly for complex nested fields not covered by CLI flags (e.g., `implementation`, `sampleData`, full `columns` definition).
+
 ## Appearance & Layout
 - **Appearance**: For new tables, include the `appearance: { type: "..." }` block.
 - **Layout**: When creating new entities, always assign initial `x` and `y` coordinates in the `layout` section. Position them logically near their related entities to avoid stacking.

package/src/templates/codex/modscape-modeling/SKILL.md

@@ -9,15 +9,28 @@ You are a professional Data Modeler. Your primary directive is to manage `model.
 
 ## COMMAND: /modscape:modeling
 When the user issues this command:
-1. READ `.modscape/rules.md` to understand project strategy and conventions.
+1. READ `.modscape/rules.md` to understand project strategy and conventions. If `.modscape/rules.custom.md` exists, read it too — custom rules take priority over the base rules.
 2. ANALYZE `model.yaml` (if present).
 3. INTERACT with the user to gather requirements and update the model strictly following the rules.
 
+## Mutation CLI — Use Before Editing YAML Directly
+
+For targeted changes to tables, columns, relationships, lineage, or domains, **PREFER the mutation CLI commands** over editing YAML directly. CLI commands validate input and write atomically.
+
+Recommended flow:
+1. Check existence: `modscape table get model.yaml --id <id> --json`
+2. Add or update: `modscape table add` / `modscape table update`
+3. After adding tables: `modscape layout model.yaml` to assign coordinates
+
+See Section 13 of `.modscape/rules.md` for the full command reference.
+
+Only edit YAML directly for complex nested fields not covered by CLI flags (e.g., `implementation`, `sampleData`, full `columns` definition).
+
 ## Appearance & Layout
 - **Appearance**: When creating new tables, include the `appearance` block with an appropriate `type`.
 - **Layout**: For any new entity, assign logical `x` and `y` coordinates in the `layout` section to prevent overlapping and ensure a clean initial visualization.
 
-ALWAYS follow the rules defined in `.modscape/rules.md` for any modeling tasks.
+ALWAYS follow the rules defined in `.modscape/rules.md` (and `.modscape/rules.custom.md` if present) for any modeling tasks.
 
 ## COMMAND: /modscape:codegen
 When the user issues this command:

package/src/templates/gemini/modscape-modeling/SKILL.md

@@ -7,10 +7,23 @@ description: Create the data model defined in `model.yaml` according to project
 
 You are a professional Data Modeler. Your primary directive is to manage `model.yaml`.
 
-BEFORE making any suggestions or changes, you MUST read and strictly follow the rules defined in `.modscape/rules.md`.
+BEFORE making any suggestions or changes, you MUST read and strictly follow the rules defined in `.modscape/rules.md`. If `.modscape/rules.custom.md` exists, read it too — custom rules take priority over the base rules.
 
 If a requested change violates these rules, warn the user.
 
+## Mutation CLI — Use Before Editing YAML Directly
+
+For targeted changes to tables, columns, relationships, lineage, or domains, **PREFER the mutation CLI commands** over editing YAML directly. CLI commands validate input and write atomically.
+
+Recommended flow:
+1. Check existence: `modscape table get model.yaml --id <id> --json`
+2. Add or update: `modscape table add` / `modscape table update`
+3. After adding tables: `modscape layout model.yaml` to assign coordinates
+
+See Section 13 of `.modscape/rules.md` for the full command reference.
+
+Only edit YAML directly for complex nested fields not covered by CLI flags (e.g., `implementation`, `sampleData`, full `columns` definition).
+
 ## 📁 Multi-file Awareness
 `modscape dev` supports pointing to a directory (e.g., `modscape dev samples/`).
 -   **Switching Models**: Identify which YAML file you are editing from the directory.
@@ -24,4 +37,4 @@ If a requested change violates these rules, warn the user.
 ## Interactive Modeling
 When the user wants to perform modeling tasks, ensure you are utilizing the strategy and conventions defined in the project rules.
 
-ALWAYS follow the rules defined in `.modscape/rules.md` for any modeling tasks.
+ALWAYS follow the rules defined in `.modscape/rules.md` (and `.modscape/rules.custom.md` if present) for any modeling tasks.

package/src/templates/rules.md

@@ -3,6 +3,9 @@
 > **Purpose**: This file teaches AI agents how to write valid `model.yaml` files for Modscape.
 > Read this file completely before generating or editing any YAML.
 
+> **Extension**: If `.modscape/rules.custom.md` exists in this project, read it **in addition** to this file.
+> Rules in `rules.custom.md` take **priority** over this file when they conflict.
+
 ---
 
 ## QUICK REFERENCE (read this first)
@@ -589,7 +592,139 @@ modscape merge ./sales ./marketing -o combined.yaml
 
 ---
 
-## 13. Complete Example
+## 13. Model Mutation CLI
+
+Use the built-in mutation commands to **add, update, or remove individual entities** in a YAML model. These commands validate input and write atomically — safer than editing YAML directly.
+
+**MUST** use these commands when making targeted changes. Only edit YAML directly for complex nested fields not covered by CLI flags (e.g., `implementation`, `sampleData`, `columns` full definition).
+
+### 13-1. Available Operations
+
+| Resource | Operations |
+|----------|-----------|
+| `table` | `list` `get` `add` `update` `remove` |
+| `column` | `add` `update` `remove` |
+| `relationship` | `list` `add` `remove` |
+| `lineage` | `list` `add` `remove` |
+| `domain` | `list` `get` `add` `update` `remove` |
+| `domain member` | `add` `remove` |
+
+### 13-2. Recommended AI Agent Flow
+
+Before `add` or `update`, check existence with `get` or `list`:
+
+```bash
+# 1. Check if table exists
+modscape table get model.yaml --id fct_orders --json
+# → found: use update / not found: use add
+
+# 2a. Add new table
+modscape table add model.yaml --id fct_orders --name "Orders" --type fact
+
+# 2b. Update existing table
+modscape table update model.yaml --id fct_orders --physical-name fct_sales_orders
+```
+
+### 13-3. CLI Flag Reference
+
+**table add / update**
+```bash
+modscape table add model.yaml \
+  --id <id> --name <name> \
+  [--type fact|dimension|mart|hub|link|satellite|table] \
+  [--logical-name <name>] [--physical-name <name>] \
+  [--description <text>] [--json]
+```
+
+**column add / update**
+```bash
+modscape column add model.yaml \
+  --table <tableId> --id <id> --name <name> \
+  [--type Int|String|Decimal|Date|Timestamp|Boolean] \
+  [--primary-key] [--foreign-key] \
+  [--physical-name <name>] [--physical-type <type>] [--json]
+```
+
+**relationship add**
+```bash
+modscape relationship add model.yaml \
+  --from <table.column> --to <table.column> \
+  --type one-to-one|one-to-many|many-to-one|many-to-many [--json]
+```
+
+**lineage add**
+```bash
+modscape lineage add model.yaml --from <tableId> --to <tableId> [--json]
+```
+
+**domain add / update**
+```bash
+modscape domain add model.yaml \
+  --id <id> --name <name> [--description <text>] [--color <color>] [--json]
+```
+
+**domain member add / remove**
+```bash
+modscape domain member add model.yaml --domain <domainId> --table <tableId> [--json]
+modscape domain member remove model.yaml --domain <domainId> --table <tableId> [--json]
+```
+
+### 13-4. After Adding Tables
+
+`table add` does **not** create layout coordinates. After adding tables, run:
+
+```bash
+modscape layout model.yaml
+```
+
+This assigns coordinates to all layout-less entries automatically.
+
+### 13-5. JSON Output for AI Pipelines
+
+All commands support `--json` for machine-readable output:
+
+```json
+{ "ok": true,  "action": "add", "resource": "table", "id": "fct_orders" }
+{ "ok": false, "error": "Table \"fct_orders\" already exists", "hint": "Use `table update` instead" }
+```
+
+---
+
+## 15. Project-Specific Rule Extensions
+
+A project MAY place a `.modscape/rules.custom.md` file to define rules that extend or override this base file.
+
+**How to use it:**
+
+- Create `.modscape/rules.custom.md` in the project root (alongside `rules.md`)
+- Write any project-specific rules, naming conventions, or overrides in Markdown
+- AI agents reading this file will also check for `rules.custom.md` and apply it
+
+**Priority:** Rules in `rules.custom.md` take priority over this file when they conflict.
+
+**What to put in `rules.custom.md`** (examples):
+
+```markdown
+## Naming Conventions
+- All fact table IDs must use the prefix `fct_` followed by the domain: e.g., `fct_sales_orders`
+- All dimension table IDs must end in `_dim`: e.g., `customers_dim`
+
+## Allowed Table Types
+- This project only uses `fact`, `dimension`, and `mart`. Do NOT use `hub`, `link`, or `satellite`.
+
+## Domain Topology
+- This project has three domains: `sales`, `marketing`, `finance`
+- Every new table MUST be assigned to one of these domains
+
+## SCD Policy
+- Dimension tables use SCD Type 1 only. Do NOT apply `scd: type2` or higher.
+```
+
+`rules.custom.md` is NOT generated by `modscape init`. Create it manually when your project needs it.
+
+---
+
+## 16. Complete Example
 
 ```yaml
 domains:

package/visualizer/package.json

@@ -1,7 +1,7 @@
 {
   "name": "visualizer",
   "private": true,
-  "version": "2.0.1",
+  "version": "2.0.3",
   "type": "module",
   "scripts": {
     "dev": "vite",