modscape 2.0.2 → 2.0.4

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

@@ -5,6 +5,19 @@ Start an interactive data modeling session.
 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

@@ -13,6 +13,19 @@ When the user issues this command:
 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.

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

@@ -11,6 +11,19 @@ BEFORE making any suggestions or changes, you MUST read and strictly follow the
 
 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.

package/src/templates/rules.md

@@ -16,7 +16,7 @@ COORDINATES    ONLY in `layout`. NEVER inside tables or domains.
 LINEAGE        Use top-level `lineage` section (not relationships, not table.lineage.upstream).
 parentId       Declare a table's domain membership inside layout, not inside domains.
 IDs            Every object (table, domain, annotation) needs a unique `id`.
-sampleData     First row = column IDs. At least 3 realistic data rows.
+sampleData     At least 3 realistic data rows. No header row.
 Grid           All x/y values must be multiples of 40.
 ```
 
@@ -45,13 +45,12 @@ layout:        # (object) ALL coordinates — REQUIRED if any objects exist
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `id` | **REQUIRED** | Unique identifier used as a key in `layout`, `domains.tables`, `lineage.upstream`, etc. Use snake_case. |
+| `id` | **REQUIRED** | Unique identifier used as a key in `layout`, `domains.tables`, `lineage`, etc. Use snake_case. |
 | `name` | **REQUIRED** | Conceptual (business) name shown large on the canvas. |
 | `logical_name` | optional | Formal business name shown medium. Omit if same as `name`. |
 | `physical_name` | optional | Actual database table name shown small. |
 | `appearance` | optional | Visual type, icon, color. |
 | `conceptual` | optional | AI-friendly business context metadata. |
-| `lineage` | optional | Upstream table IDs. Only for `mart` / aggregated tables. |
 | `columns` | optional | Column definitions. |
 | `sampleData` | optional | 2D array of sample rows. Strongly recommended. |
 
@@ -72,7 +71,7 @@ appearance:
 |------|-------------|
 | `fact` | Events, transactions, measurements. Has measures (numbers) and FK columns. |
 | `dimension` | Entities, master data, reference lists. Descriptive attributes. |
-| `mart` | Aggregated or consumer-facing output. **Always add `lineage.upstream`.** |
+| `mart` | Aggregated or consumer-facing output. **Always add a top-level `lineage` entry.** |
 | `hub` | Data Vault: stores a single unique business key. |
 | `link` | Data Vault: joins two or more hubs (transaction or relationship). |
 | `satellite` | Data Vault: descriptive attributes of a hub, tracked over time. |
@@ -96,7 +95,7 @@ Each column has an `id` plus optional `logical` and `physical` blocks.
 
 ```yaml
 columns:
-  - id: order_id           # REQUIRED. Unique within the table. Used in sampleData header.
+  - id: order_id           # REQUIRED. Unique within the table.
     logical:
       name: "Order ID"     # Display name
       type: Int            # Int | String | Decimal | Date | Timestamp | Boolean | ...
@@ -138,7 +137,7 @@ relationships:
 | `many-to-one` | Fact → Dimension *(inverse notation of above)* |
 | `many-to-many` | Via a bridge / link table |
 
-**MUST NOT** use `relationships` to express data lineage (use `lineage.upstream` instead).
+**MUST NOT** use `relationships` to express data lineage (use the top-level `lineage` section instead).
 
 ---
 
@@ -497,7 +496,7 @@ The command reads `target/manifest.json` and produces YAML with:
 | `physical_name` | `node.alias` | Falls back to `node.name` |
 | `conceptual.description` | `node.description` | From dbt docs |
 | `columns[].logical.name/type/description` | `node.columns` | From dbt schema.yml |
-| `lineage.upstream` | `node.depends_on.nodes` | Auto-populated |
+| `lineage` (top-level) | `node.depends_on.nodes` | Auto-populated as `{from, to}` entries |
 | `appearance.type` | — | **Always `table`. Must be reclassified.** |
 | `sampleData` | — | **Not generated. Must be added.** |
 | `layout` | — | **Not generated. Must be added.** |
@@ -517,7 +516,7 @@ After running `modscape dbt import`, the generated YAML needs enrichment. AI age
 
 3. **Add `sampleData`** — The import does not generate sample data. Add at least 3 realistic rows per table.
 
-4. **Do NOT re-generate `lineage.upstream`** — It is already correctly populated from `depends_on.nodes`.
+4. **Do NOT re-generate `lineage` entries** — Top-level `lineage` is already correctly populated from `depends_on.nodes`.
 
 ### 11-4. `dbt sync` — Incremental updates
 
@@ -527,7 +526,7 @@ Use `modscape dbt sync` when the dbt project has changed (new models, updated co
 - `name`, `logical_name`, `physical_name`
 - `conceptual.description`
 - `columns` (all)
-- `lineage.upstream`
+- `lineage` (top-level)
 
 **What `sync` preserves (safe to edit manually):**
 - `appearance` (type, icon, color, scd)
@@ -549,14 +548,15 @@ id: "model.my_project.fct_orders"
 id: "source.my_project.raw.orders"
 id: "seed.my_project.product_categories"
 
-# lineage.upstream also uses unique_id format
+# top-level lineage also uses unique_id format
 lineage:
-  upstream:
-    - "model.my_project.stg_orders"
-    - "source.my_project.raw.customers"
+  - from: "model.my_project.stg_orders"
+    to: "model.my_project.fct_orders"
+  - from: "source.my_project.raw.customers"
+    to: "model.my_project.fct_orders"
 ```
 
-**MUST NOT** shorten these IDs. They are the join keys between `tables`, `domains.tables`, `lineage.upstream`, and `layout`.
+**MUST NOT** shorten these IDs. They are the join keys between `tables`, `domains.tables`, `lineage`, and `layout`.
 
 ---
 
@@ -592,7 +592,116 @@ modscape merge ./sales ./marketing -o combined.yaml
 
 ---
 
-## 13. Project-Specific Rule Extensions
+## 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
+
+When inspecting a model's current state, **prefer using the list/get commands** over reading the YAML file directly.
+They return validated, structured JSON output that is easier to process.
+
+```bash
+# Inspect current state before making changes
+modscape table list model.yaml --json
+modscape domain list model.yaml --json
+modscape relationship list model.yaml --json
+modscape lineage list model.yaml --json
+```
+
+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.
 
@@ -626,7 +735,7 @@ A project MAY place a `.modscape/rules.custom.md` file to define rules that exte
 
 ---
 
-## 14. Complete Example
+## 16. Complete Example
 
 ```yaml
 domains:

package/visualizer/package.json

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