@modyo/mcp 0.1.0

package/docs/channels/versioning-system.md

@@ -0,0 +1,554 @@
+# Modyo Versioning System
+
+## Overview
+
+Modyo implements a comprehensive versioning system for all publishable resources (widgets, snippets, templates, pages, menus). Understanding this system is **critical** for building reliable tools and workflows.
+
+---
+
+## Core Principle: IDs Change, UUIDs Don't
+
+**The Golden Rule**: When a resource is published in Modyo:
+1. ❌ The `id` field **WILL CHANGE** (new version created)
+2. ✅ The `uuid` field **REMAINS STABLE** (identifies resource across versions)
+3. 📦 The old version is **ARCHIVED** (available for rollback)
+4. ↩️ You can **ROLLBACK** to any previous version via Modyo UI
+
+---
+
+## Why IDs Change
+
+### Versioning Architecture
+
+Modyo uses a **copy-on-publish** architecture:
+
+```
+Draft State:
+  Resource (id: 100, uuid: "abc123", status: "draft")
+
+Publish Action:
+  1. Create new version with new ID
+  2. Archive old version
+  3. Update published resource pointer
+
+Published State:
+  Old Version (id: 100, uuid: "abc123", version: 1, archived: true)
+  New Version (id: 101, uuid: "abc123", version: 2, status: "published")
+```
+
+**Why?**
+- **Version History**: Every publish creates a snapshot
+- **Rollback Capability**: Can restore any previous version
+- **Audit Trail**: Track what was published when
+- **Draft/Published Separation**: Draft edits don't affect live version
+
+---
+
+## Affected Resources
+
+All publishable Modyo resources follow this pattern:
+
+| Resource Type | Stable ID | Changes on Publish |
+|--------------|-----------|-------------------|
+| **Widgets** | `definition_uuid` (OID) | `id` field |
+| **Snippets** | `uuid` | `id` field |
+| **Templates** | `uuid` | `id` field |
+| **Pages** | `uuid` | `id` field |
+| **Menus** | `uuid` | `id` field |
+| **Layouts** | `uuid` | `id` field |
+
+**Key**: Always use the **Stable ID** column for references and storage.
+
+---
+
+## Complete Versioning Lifecycle
+
+### Widgets Example
+
+```typescript
+// 1. CREATE
+widget-definitions-create({ name: "Product Card" })
+// Returns: { id: 100, definition_uuid: "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260" }
+
+// 2. EDIT (Draft)
+widget-definition-update({ widgetId: 100, html: "<div>v1</div>" })
+// Still: { id: 100, definition_uuid: "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260", status: "draft" }
+
+// 3. PUBLISH (Version 1)
+release-create({ data: { widgetDefinition: [{ id: 100, selected: true }] } })
+// Result:
+//   Archived: { id: 100, version: 1, definition_uuid: "ac2fe2d..." }
+//   Published: { id: 101, version: 2, definition_uuid: "ac2fe2d...", status: "published" }
+
+// 4. EDIT AGAIN (Draft)
+widget-definition-update({ widgetId: 101, html: "<div>v2</div>" })
+// Now: { id: 101, definition_uuid: "ac2fe2d...", status: "draft" }
+
+// 5. PUBLISH AGAIN (Version 2)
+release-create({ data: { widgetDefinition: [{ id: 101, selected: true }] } })
+// Result:
+//   Archived: { id: 100, version: 1, definition_uuid: "ac2fe2d..." }
+//   Archived: { id: 101, version: 2, definition_uuid: "ac2fe2d..." }
+//   Published: { id: 102, version: 3, definition_uuid: "ac2fe2d...", status: "published" }
+
+// 6. ROLLBACK to Version 1 (via UI)
+// Modyo restores id: 100 content but creates NEW version
+// Result:
+//   All previous versions still archived
+//   Published: { id: 103, version: 4, definition_uuid: "ac2fe2d...", content: "<div>v1</div>" }
+```
+
+**Key Observation**: After 3 publishes and 1 rollback:
+- `id` went from 100 → 101 → 102 → 103
+- `definition_uuid` remained "ac2fe2d..." throughout
+- 4 versions exist in history (v1, v2, v3, v4)
+
+---
+
+## Snippets Example
+
+```typescript
+// CREATE
+template-create({ name: "product_card", type: "custom_snippet", body: "v1" })
+// Returns: { id: 200, uuid: "def456", status: "draft" }
+
+// PUBLISH
+release-create({ data: { template: [{ id: 200, selected: true }] } })
+// Result: { id: 201, uuid: "def456", version: 2, status: "published" }
+
+// EDIT & PUBLISH AGAIN
+template-update({ templateId: 201, template: { body: "v2" } })
+release-create({ data: { template: [{ id: 201, selected: true }] } })
+// Result: { id: 202, uuid: "def456", version: 3, status: "published" }
+```
+
+**Same Pattern**: ID changes (200 → 201 → 202), UUID stable ("def456")
+
+---
+
+## Pages Example
+
+```typescript
+// CREATE
+page-create({ name: "Homepage", path: "/" })
+// Returns: { id: 300, uuid: "ghi789", status: "draft" }
+
+// PUBLISH
+release-create({ data: { page: [{ id: 300, selected: true }] } })
+// Result: { id: 301, uuid: "ghi789", version: 2, status: "published" }
+```
+
+**Same Pattern**: ID changes, UUID stable
+
+---
+
+## Implications for Tool Development
+
+### ❌ Anti-Patterns (Don't Do This)
+
+**1. Hardcoding IDs**
+```typescript
+// ❌ WRONG
+const widgetId = 100;
+function updateWidget() {
+  widget-definition-update({ widgetId, html: "..." });  // Breaks after publish!
+}
+```
+
+**2. Storing IDs in External Systems**
+```typescript
+// ❌ WRONG
+database.save({
+  page: "homepage",
+  widgetId: 100  // This ID becomes invalid after publish
+});
+```
+
+**3. ID-Based Lookups**
+```typescript
+// ❌ WRONG
+function getWidget(id: number) {
+  return widget-definition-get({ widgetId: id });  // May return archived version
+}
+```
+
+**4. Assuming ID Stability**
+```typescript
+// ❌ WRONG
+const widgetBefore = widget-definition-get({ widgetId: 100 });
+publishWidget(100);
+const widgetAfter = widget-definition-get({ widgetId: 100 });  // May fail or return archived version
+```
+
+### ✅ Correct Patterns
+
+**1. Use UUIDs for References**
+```typescript
+// ✅ CORRECT
+const widgetUuid = "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260";
+
+function updateWidget() {
+  // Get current ID from UUID
+  const widget = findWidgetByUuid(widgetUuid);
+  widget-definition-update({ widgetId: widget.id, html: "..." });
+}
+```
+
+**2. Store UUIDs in External Systems**
+```typescript
+// ✅ CORRECT
+database.save({
+  page: "homepage",
+  widgetUuid: "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260"  // Stable across versions
+});
+```
+
+**3. UUID-Based Lookups**
+```typescript
+// ✅ CORRECT
+function getWidgetByUuid(uuid: string) {
+  const widgets = widget-definitions-list({ siteId });
+  return widgets.find(w => w.definition_uuid === uuid);
+}
+```
+
+**4. Always Fetch Current State**
+```typescript
+// ✅ CORRECT
+function updateAndPublish(uuid: string) {
+  // Get current version
+  const widget = getWidgetByUuid(uuid);
+
+  // Update draft
+  widget-definition-update({ widgetId: widget.id, html: "..." });
+
+  // Publish (ID will change)
+  release-create({ data: { widgetDefinition: [{ id: widget.id, selected: true }] } });
+
+  // Get NEW version for next operation
+  const updatedWidget = getWidgetByUuid(uuid);
+  console.log(`New ID: ${updatedWidget.id}`);  // Different from widget.id
+}
+```
+
+---
+
+## UUID Formats
+
+Different resources use different UUID formats:
+
+### Widgets: OID (Object Identifier)
+
+**Format**: 40-character SHA-1 hash
+**Example**: `ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260`
+
+**Characteristics**:
+- Not RFC 4122 standard UUID
+- No hyphens
+- Content-addressable (based on widget content/definition)
+- Modyo calls these "definition_uuid" or "widget_definition_uuid"
+
+**Validation**:
+```typescript
+// ❌ WRONG - Don't use UUID validation
+z.string().uuid()  // Fails for OIDs
+
+// ✅ CORRECT - Validate as string or hex
+z.string().length(40).regex(/^[a-f0-9]{40}$/)
+```
+
+### Snippets/Templates/Pages: Standard UUID
+
+**Format**: RFC 4122 UUID
+**Example**: `550e8400-e29b-41d4-a716-446655440000`
+
+**Characteristics**:
+- Standard UUID format
+- Includes hyphens
+- Randomly generated
+
+**Validation**:
+```typescript
+// ✅ CORRECT
+z.string().uuid()  // Standard UUID validation
+```
+
+---
+
+## Rollback Behavior
+
+### How Rollback Works
+
+1. **Via Modyo UI**: Administrator selects "Revert to Version X"
+2. **Content Restoration**: Modyo copies content from version X
+3. **New Version Created**: Creates NEW version with NEW ID
+4. **UUID Preserved**: Same UUID throughout
+
+### Example
+
+```typescript
+// Version History:
+// v1: id: 100, content: "old", uuid: "abc"
+// v2: id: 101, content: "new", uuid: "abc" (current published)
+
+// Admin rolls back to v1 via UI
+
+// Result:
+// v1: id: 100, content: "old", uuid: "abc" (archived)
+// v2: id: 101, content: "new", uuid: "abc" (archived)
+// v3: id: 102, content: "old", uuid: "abc" (published) ← NEW version with v1 content
+```
+
+**Key**: Rollback creates a **new forward version**, not a true revert.
+
+### Implications
+
+- ✅ Version history is append-only (never deleted)
+- ✅ Can rollback to any version at any time
+- ✅ Each rollback creates new version with new ID
+- ✅ UUID always remains stable
+
+---
+
+## Version History Storage
+
+### Where Versions Are Stored
+
+**Database**:
+- All versions stored in same table
+- `version` column tracks version number
+- `archived` flag indicates current vs archived
+
+**Example Schema**:
+```sql
+widget_definitions:
+  id: 100, uuid: "abc", version: 1, archived: true
+  id: 101, uuid: "abc", version: 2, archived: true
+  id: 102, uuid: "abc", version: 3, archived: false  ← Current
+```
+
+### Accessing Version History
+
+**Via Modyo UI**:
+- Template/Widget/Page editor → "Version History"
+- Shows all versions with timestamps and authors
+- Can preview any version
+- Can rollback to any version
+
+**Via API**: ❌ No direct API access to version history
+- Can only access current published/draft versions
+- Cannot list or retrieve archived versions via API
+- Version history is UI-only feature
+
+---
+
+## Best Practices
+
+### 1. UUID-First Architecture
+
+**Always design around UUIDs**:
+```typescript
+interface WidgetReference {
+  uuid: string;           // ✅ Store this
+  name: string;           // ✅ For human reference
+  lastKnownId?: number;   // ⚠️ Optional, for cache only
+}
+```
+
+### 2. Refresh After Publish
+
+**Always fetch fresh data after publishing**:
+```typescript
+// Before publish
+const widgetId = 100;
+
+// Publish
+await publishWidget(widgetId);
+
+// ❌ WRONG - Don't reuse old ID
+await widget-definition-update({ widgetId: 100, ... });  // May fail
+
+// ✅ CORRECT - Fetch new version
+const widget = await getWidgetByUuid(uuid);
+await widget-definition-update({ widgetId: widget.id, ... });
+```
+
+### 3. UUID Lookup Helper
+
+**Create reusable UUID lookup function**:
+```typescript
+async function getResourceByUuid(
+  resourceType: "widget" | "template" | "page",
+  uuid: string
+): Promise<Resource> {
+  const resources = await listResources(resourceType);
+  const resource = resources.find(r => r.uuid === uuid);
+
+  if (!resource) {
+    throw new Error(`${resourceType} with UUID ${uuid} not found`);
+  }
+
+  return resource;
+}
+```
+
+### 4. Document ID Volatility
+
+**In tool documentation, always note**:
+```markdown
+**⚠️ Important**: The `id` parameter may change after publishing.
+Always use `uuid` for stable references across versions.
+```
+
+### 5. Automated Workflows
+
+**For CI/CD pipelines**:
+```typescript
+async function deployWidget(uuid: string, updates: Updates) {
+  // 1. Get current version
+  const widget = await getWidgetByUuid(uuid);
+
+  // 2. Update draft
+  await widget-definition-update({ widgetId: widget.id, ...updates });
+
+  // 3. Publish
+  await release-create({ data: { widgetDefinition: [{ id: widget.id, selected: true }] } });
+
+  // 4. Get new version for verification
+  const published = await getWidgetByUuid(uuid);
+
+  console.log(`Deployed widget ${uuid}`);
+  console.log(`Old ID: ${widget.id}, New ID: ${published.id}`);
+
+  return published;
+}
+```
+
+---
+
+## Testing Versioning Behavior
+
+### Test Case 1: ID Changes After Publish
+
+```typescript
+test("widget ID changes after publish", async () => {
+  // Create widget
+  const created = await widget-definitions-create({ name: "Test Widget" });
+  const originalId = created.id;
+  const uuid = created.definition_uuid;
+
+  // Publish
+  await release-create({ data: { widgetDefinition: [{ id: originalId, selected: true }] } });
+
+  // Get published version
+  const published = await getWidgetByUuid(uuid);
+
+  // Assert ID changed
+  expect(published.id).not.toBe(originalId);
+  expect(published.definition_uuid).toBe(uuid);  // UUID stable
+});
+```
+
+### Test Case 2: UUID Lookup After Multiple Publishes
+
+```typescript
+test("UUID lookup works after multiple publishes", async () => {
+  const widget = await widget-definitions-create({ name: "Test" });
+  const uuid = widget.definition_uuid;
+
+  // Publish 3 times
+  for (let i = 0; i < 3; i++) {
+    const current = await getWidgetByUuid(uuid);
+    await widget-definition-update({ widgetId: current.id, html: `<div>v${i}</div>` });
+    await release-create({ data: { widgetDefinition: [{ id: current.id, selected: true }] } });
+  }
+
+  // UUID still finds current version
+  const final = await getWidgetByUuid(uuid);
+  expect(final.definition_uuid).toBe(uuid);
+  expect(final.html).toContain("v2");  // Last update
+});
+```
+
+---
+
+## Common Errors and Solutions
+
+### Error 1: "Resource not found"
+
+**Symptom**: Tool fails after publishing
+**Cause**: Using old ID after publish changed it
+**Solution**: Refresh resource using UUID
+
+```typescript
+// ❌ Causes error
+const id = 100;
+await publishResource(id);
+await updateResource(id);  // Error: Resource 100 not found
+
+// ✅ Correct
+const uuid = "abc123...";
+let resource = await getByUuid(uuid);
+await publishResource(resource.id);
+resource = await getByUuid(uuid);  // Refresh
+await updateResource(resource.id);  // Works
+```
+
+### Error 2: "Cannot update archived resource"
+
+**Symptom**: Update operation fails with archived error
+**Cause**: Trying to update old version after publish
+**Solution**: Get current version by UUID
+
+```typescript
+// ❌ Causes error
+const old = await getResource(100);
+await publishResource(100);
+await updateResource(old.id);  // Error: Cannot update archived
+
+// ✅ Correct
+const uuid = old.uuid;
+await publishResource(old.id);
+const current = await getByUuid(uuid);
+await updateResource(current.id);  // Works
+```
+
+### Error 3: "Unexpected version mismatch"
+
+**Symptom**: Resource has unexpected content or properties
+**Cause**: Cached old version after publish
+**Solution**: Always fetch fresh after publish
+
+---
+
+## Summary Checklist
+
+When working with Modyo resources:
+
+- [ ] Store UUIDs, not IDs, in external systems
+- [ ] Refresh resource data after every publish operation
+- [ ] Use UUID-based lookups for resource retrieval
+- [ ] Document that IDs are volatile in tool docs
+- [ ] Validate widget UUIDs as 40-char hex, not standard UUIDs
+- [ ] Never hardcode resource IDs in code
+- [ ] Create UUID lookup helpers for common operations
+- [ ] Test workflows with multiple publish cycles
+- [ ] Handle ID changes gracefully in error messages
+- [ ] Use UUIDs in API integration contracts
+
+---
+
+## Related Documentation
+
+- [MODYO_SNIPPETS_ARCHITECTURE.md](./MODYO_SNIPPETS_ARCHITECTURE.md) - Snippet versioning section
+- [tools/WIDGET_TOOLS.md](./tools/WIDGET_TOOLS.md) - Widget versioning section
+- [tools/RELEASE_TOOLS.md](./tools/RELEASE_TOOLS.md) - Publishing workflow
+- [CONTEXT_FOR_NEW_TOOLS.md](./CONTEXT_FOR_NEW_TOOLS.md) - Tool development guide
+
+---
+
+**Document Version**: 1.0.0
+**Last Updated**: 2025-01-09
+**Maintained By**: Modyo MCP Development Team
+
+**Key Takeaway**: Modyo's versioning system changes resource IDs on every publish to maintain version history and enable rollback. Always use UUIDs for stable references and refresh resource data after publishing operations.

package/docs/development/e2e-test-guide.md

@@ -0,0 +1,128 @@
+# E2E AI Test Guide
+
+Natural language test instructions for AI-driven tool validation.
+
+## Purpose
+
+E2E AI tests are markdown files containing natural language instructions that an AI can follow to validate tool behavior against a real Modyo platform.
+
+## File Location
+
+```
+tests/e2e-ai/
+├── CLAUDE.md           # Points here
+├── {tool-name}.md      # Test scenarios
+└── ...
+```
+
+## Test File Format
+
+```markdown
+# {tool-name} E2E AI Tests
+
+## Tool Overview
+Brief description of what the tool does.
+
+## Test Platform
+- Platform: `fed-team` (or other configured platform)
+
+---
+
+## {Category} Operations
+
+### Scenario N: {Description}
+**Instruction:**
+> Natural language instruction for the AI to execute
+
+**Expected Parameters:**
+\`\`\`json
+{ "action": "...", "param": "..." }
+\`\`\`
+
+**Validation:**
+- [ ] Validation point 1
+- [ ] Validation point 2
+
+---
+
+## Error Scenarios
+
+### Scenario EN: {Error Description}
+**Instruction:**
+> Instruction that should produce an error
+
+**Expected:** Error message description
+
+---
+
+## Test Cleanup
+Instructions for cleaning up test data if needed.
+
+---
+
+**Total Scenarios:** X main + Y error = Z scenarios
+```
+
+## Writing Instructions
+
+### Good Instructions
+- Clear, unambiguous language
+- Specific values when needed
+- Reference existing resources by name/ID
+
+### Bad Instructions
+- Vague or ambiguous
+- Missing required context
+- Assuming prior state
+
+## Example Scenarios
+
+### CRUD Operations
+```markdown
+### Scenario 1: List Resources
+**Instruction:**
+> List all spaces in the fed-team platform
+
+**Expected Parameters:**
+\`\`\`json
+{ "action": "list", "platformSlug": "fed-team" }
+\`\`\`
+```
+
+### Smart Resolution
+```markdown
+### Scenario 5: Get by Name
+**Instruction:**
+> Get the space named "Marketing" from fed-team
+
+**Expected Parameters:**
+\`\`\`json
+{ "action": "manage", "platformSlug": "fed-team", "identifier": "Marketing" }
+\`\`\`
+```
+
+### Error Cases
+```markdown
+### Scenario E1: Missing Required Field
+**Instruction:**
+> Create a new space without providing a name
+
+**Expected:** Validation error for missing name
+```
+
+## Running Tests
+
+1. Configure platform in manager service
+2. Read test file for tool
+3. Execute each scenario
+4. Validate results match expectations
+5. Run cleanup if needed
+
+## Coverage Goals
+
+Each tool should have scenarios for:
+- All supported actions
+- Smart identifier resolution (when applicable)
+- Pagination (for list actions)
+- Error cases (validation, not found)
+- Verification mode (when supported)