orchestrated-discussions/artifact-editor---ai-enhanced-diagram-and-3d-model-creator.discussion.md

<!-- DISCUSSION -->
<!-- Title: Artifact Editor - AI-Enhanced Diagram and 3D Model Creator -->
<!-- Phase: initial_feedback -->
<!-- Status: OPEN -->
<!-- Created: 2025-12-19T02:07:49Z -->
<!-- Template: brainstorm -->
<!-- Participants: architect, security, pragmatist -->

# Artifact Editor - AI-Enhanced Diagram and 3D Model Creator

## Context
## Overview

We want to build a standalone **Artifact Editor** that can be launched from any application to create visual artifacts like diagrams, sketches, and 3D models.

## Key Requirements

1. **Standalone executable** - Can be launched via command line with arguments
2. **Multiple artifact types** - Mermaid, PlantUML, OpenSCAD/SolidPython, SVG, ASCII art
3. **AI assistance** - Voice input, conversational editing, auto-generation
4. **Integration contract** - Simple stdin/stdout/exit-code interface for parent apps
5. **Live preview** - See rendered output as you edit code

## Integration Target

Primary integration with **orchestrated-discussions** project:
- User clicks 'Add Artifact' in comment dialog
- Launches artifact-editor with output path argument
- User creates/edits artifact
- On save, outputs 'ARTIFACT_SAVED:/path/to/file'
- Parent app embeds artifact reference in comment

## Questions to Explore

- What's the right UI framework? (urwid TUI, Dear PyGui, web-based?)
- How should AI assistance work? (SmartTools integration?)
- What's the MVP feature set?
- How do we handle 3D model preview?
- Should we support collaborative editing?

## Project Scaffold

Initial scaffold already created at ~/PycharmProjects/artifact-editor with:
- pyproject.toml
- Basic CLI structure
- Renderer base class
- Mermaid and OpenSCAD renderer stubs

## Requirements
- [ ] [Requirement 1]
- [ ] [Requirement 2]

## Open Questions
- [Question 1]

---

*Discussion begins below.*
---

Name: AI-Pragmatist
## Practical Shipping Analysis

This is a classic case of solving tomorrow's problems today. Let me break down what we actually need vs what's being proposed.

### CONCERN: COMPLEXITY - Overscoped for Integration Need

The stated goal is "User clicks 'Add Artifact' in orchestrated-discussions." But the proposed scope includes:
- Multiple diagram types (Mermaid, PlantUML, OpenSCAD, SVG, ASCII)
- Voice input
- Conversational editing
- Live preview
- 3D model rendering
- Collaborative editing (in questions)

This is 6+ months of work for a feature that needs to ship in weeks.

### MVP: Single Artifact Type + Text Editor

**What ships in 2 weeks:**
1. Launch editor with `--output-path` argument
2. Simple text editor for PlantUML/Mermaid (pick ONE)
3. Save button that outputs `ARTIFACT_SAVED:/path`
4. Exit code 0 on save, 1 on cancel

That's it. No AI, no preview, no 3D. Just a working integration.

**Defer to v2:**
- AI assistance (SmartTools)
- Live preview (nice-to-have, not blocking)
- Additional formats (add after first one works)
- Voice input (future)
- 3D models (separate project)

### UI Framework Decision

**Simplest that works:** urwid TUI
- Already in dependency tree (orchestrated-discussions uses it)
- Zero preview complexity (just show code)
- Fast to build
- Terminal-native, no GUI frameworks

**Defer:** Dear PyGui, web-based - these add complexity without solving the core integration need.

### Architecture: Just Enough

```
artifact-editor --type mermaid --output diagrams/foo.mmd
→ Opens text editor
→ User types Mermaid code
→ Saves to file
→ Prints ARTIFACT_SAVED:diagrams/foo.mmd
→ Exit 0
```

No renderers, no preview pipeline, no AI - just a glorified text editor with contract compliance.

### What Success Looks Like (v1)

User can add a diagram to a discussion comment. That's it. Ship that, get feedback, iterate.

### Recommendation

Q: What's the right UI framework?
A: urwid - simplest, already a dependency

Q: How should AI assistance work?
A: Don't build it yet - defer to v2

Q: What's the MVP feature set?
A: Text editing + save contract for ONE format

Q: How do we handle 3D preview?
A: Don't - that's a v3+ feature

Q: Collaborative editing?
A: Hard no for MVP

DIAGRAM: diagrams/artifact-editor-ai-enhanced-diagram-and-3d-model-creator_mvp_5.puml

VOTE: CHANGES - Scope needs 80% reduction to ship something useful

VOTE: CHANGES

---

Name: AI-Security
## Security Analysis

I've reviewed the Artifact Editor proposal and identified several security concerns that need to be addressed:

### High Priority Threats

**1. Command Injection via Renderer Execution**

CONCERN: PlantUML, OpenSCAD, and Mermaid renderers execute external processes. User-controlled content could escape sandboxing.

- PlantUML Java execution with user diagrams
- OpenSCAD code compilation and execution
- SVG rendering with embedded scripts
- ASCII art could contain terminal escape sequences

Mitigation: Strict input validation, sandboxed execution (containers/firejail), disable network access for renderers, CSP for web-based previews.

**2. Path Traversal in File Operations**

CONCERN: The `--output` argument could be exploited to write files outside intended directories.

```
artifact-editor --output ../../../etc/cron.d/backdoor
```

Mitigation: Validate and canonicalize all file paths, restrict writes to specific directories, check for `..` sequences.

**3. Voice Input Attack Surface**

CONCERN: Voice-to-AI pipeline introduces new vectors:
- Audio injection attacks
- Prompt injection via transcribed speech
- Privacy concerns (recording storage)

Mitigation: Sanitize transcriptions before AI processing, ephemeral audio storage, user consent for recording.

**4. AI-Generated Code Execution**

CONCERN: AI might generate malicious code in OpenSCAD/PlantUML that gets auto-executed.

- OpenSCAD can read/write files
- PlantUML can include external files
- SVG can contain JavaScript

Mitigation: Review-before-execute workflow, static analysis of generated code, disable dangerous language features.

### Medium Priority

**5. Stdout/Stdin Protocol Security**

The parent app integration uses stdout for communication. Malicious artifact content could inject fake protocol messages:

```
ARTIFACT_SAVED:/fake/path\nARTIFACT_SAVED:/actual/malicious/path
```

Mitigation: Structured format (JSON over stdout), message signing/verification.

**6. Dependency Chain Attacks**

External renderers (PlantUML JAR, OpenSCAD binary) could be compromised.

Mitigation: Checksum verification, pinned versions, consider alternative pure-Python implementations where possible.

**7. Resource Exhaustion**

CONCERN: Complex diagrams could cause DoS:
- Infinite loops in OpenSCAD
- Massive PlantUML graphs consuming memory
- SVG bomb attacks

Mitigation: Execution timeouts, memory limits, input size restrictions.

### Recommendations

**For MVP:**
1. Start with read-only ASCII art and Mermaid (client-side rendering)
2. Defer executable formats (OpenSCAD, PlantUML) until sandboxing is implemented
3. Use JSON protocol for parent communication
4. Implement strict path validation immediately
5. Add `--safe-mode` flag that disables AI features for security-critical contexts

**Architecture:**
- Separate renderer processes with minimal privileges
- Filesystem access only to designated artifact directory
- Network isolation for all renderers
- Audit logging of all file operations

**Voice/AI:**
- Disable by default, require explicit `--enable-ai` flag
- Clear user warning about data being sent to AI providers
- Local speech-to-text option for privacy

DIAGRAM: diagrams/artifact-editor-ai-enhanced-diagram-and-3d-model-creator_security_5.puml

VOTE: CHANGES

---

Name: AI-Architect
## Architectural Analysis

### Strong Foundation

The Unix philosophy alignment with orchestrated-discussions is excellent. The stdin/stdout/exit-code contract keeps integration clean and testable.

### Critical Architectural Decisions Needed

#### 1. **UI Framework Choice Has Long-Term Implications**

- **urwid TUI**: Aligns with project ecosystem, SSH-friendly, but 3D preview severely limited
- **Dear PyGui**: Native performance, better for 3D/live preview, but desktop-only
- **Web-based (local server)**: Most flexible for preview/3D, cross-platform, but adds complexity

RECOMMENDATION: **Hybrid approach** - TUI for text-based formats (PlantUML, Mermaid, ASCII), launch external viewer for 3D. Matches orchestrated-discussions pattern (text-first, viewer on demand).

#### 2. **Renderer Architecture**

ARTIFACT: diagrams/artifact-editor-architecture.puml

Key principle: **Renderers are stateless SmartTools**

```
artifact-editor (orchestration)
  ↓ subprocess
artifact-render-{format} (SmartTools)
  ↓
External tools (plantuml.jar, mermaid-cli, openscad)
```

DON'T: Build rendering logic into the editor
DO: Each renderer is a SmartTool that can be tested independently:
```bash
echo '@startuml\nA -> B\n@enduml' | artifact-render-plantuml > out.svg
```

#### 3. **AI Assistance Integration**

Two architectural patterns emerge:

**Pattern A: AI as orchestrator** (RECOMMENDED)
- User voice → `artifact-assistant` SmartTool → generates code → editor displays
- Conversational loop: user refines → tool regenerates
- Editor remains thin, AI in separate SmartTool

**Pattern B: AI embedded in editor**
- Tighter coupling, harder to test, breaks Unix philosophy

#### 4. **State Management Concern**

Current scaffold suggests single-process architecture. Consider:
- Long-running edit sessions
- Undo/redo state
- Unsaved changes handling

RECOMMENDATION: **File-based state**
- Auto-save to temp file (e.g., `/tmp/artifact-edit-{pid}.state`)
- On crash/kill, can recover
- Aligns with "discussion file is source of truth" principle

### Architecture Risks

1. **3D Preview Complexity**: OpenSCAD rendering is SLOW. Need async architecture to prevent UI blocking.
   - Solution: Render process pool, preview throttling

2. **Voice Input Dependencies**: Adds heavyweight deps (speech recognition). Could bloat the tool.
   - Solution: Separate `artifact-voice` SmartTool, optional integration

3. **Format Proliferation**: Supporting 7+ formats means 7+ external tool dependencies.
   - Solution: Plugin architecture, core ships with Mermaid+PlantUML only

### Proposed System Architecture

```
artifact-editor                    # Thin orchestrator (urwid TUI)
├── Core loop: edit → render → display
├── Calls SmartTools via subprocess
└── File-based state persistence

SmartTools ecosystem:
├── artifact-render-{format}       # Stateless renderers
├── artifact-assistant             # AI code generation
├── artifact-voice                 # Speech → text (optional)
└── artifact-validate-{format}     # Syntax checking

External tools (user-installed):
├── plantuml.jar
├── mermaid-cli  
├── openscad
└── dot (graphviz)
```

### MVP Scope Recommendation

**Phase 1 (MVP)**:
- TUI editor (urwid)
- Mermaid + PlantUML support (most common in orchestrated-discussions)
- Basic `artifact-assistant` SmartTool (text prompt → diagram code)
- File output contract

**Phase 2**:
- OpenSCAD/3D support with external viewer
- Voice input via `artifact-voice` tool
- Live preview split-pane

**Phase 3**:
- Plugin system for custom formats
- Collaborative editing (shared state file)

### Open Architectural Questions

**Q1**: Should artifact-editor support editing existing artifacts or only creation?
- Editing adds complexity (need to parse existing files, detect format)
- Creation-only is cleaner but less useful

**Q2**: How to handle format-specific validation?
- Pre-render validation prevents invalid saves
- But adds per-format complexity

**Q3**: Should the editor be modal (vim-style) or modeless?
- Modal fits TUI better, smaller learning curve
- Modeless more familiar to non-terminal users

VOTE: CHANGES

## Required Decisions Before Implementation

1. ✅ Confirm hybrid TUI + external viewer approach
2. ✅ Confirm SmartTools-based renderer architecture  
3. ❓ Define MVP format support (recommend: Mermaid + PlantUML only)
4. ❓ Decide on edit-existing vs. create-only
5. ❓ Choose modal vs. modeless editing

VOTE: CHANGES