cyclecad 0.2.2 → 0.2.3

package/docs/CAM-QUICK-REFERENCE.md

@@ -0,0 +1,199 @@
+# CAM Pipeline — Quick Reference
+
+## Quick Start (30 seconds)
+
+```javascript
+// 1. Get a mesh
+const mesh = window.allParts[0];
+
+// 2. Slice for 3D printing
+const slice = window.cycleCAD.cam.slice(mesh, {
+  printer: 'ender3',
+  material: 'pla'
+});
+
+// 3. Download G-code
+window.cycleCAD.cam.exportGcode(slice.gcode, 'part.gcode');
+
+// 4. Compare costs
+const costs = window.cycleCAD.cam.compareCosts(mesh);
+console.table(costs.processes);
+```
+
+## One-Liner Examples
+
+```javascript
+// FDM slicing
+window.cycleCAD.cam.slice(mesh).estimatedTimeReadable
+// Output: "6h 0m"
+
+// CNC estimate
+window.cycleCAD.cam.estimate(mesh, {process: 'CNC'}).totalCost
+// Output: 47.50
+
+// List all machines
+window.cycleCAD.cam.getMachines().map(m => m.name)
+// Output: ["Creality Ender 3", "Prusa MK4", ...]
+
+// Nesting score
+window.cycleCAD.cam.nest(parts, {width: 1000, height: 500}).nestingScore
+// Output: "A"
+```
+
+## API Cheat Sheet
+
+| Command | Input | Output | Example |
+|---------|-------|--------|---------|
+| `slice()` | mesh, {printer, material, layerHeight} | {gcode, time, weight} | `slice(m, {printer:'ender3'})` |
+| `toolpath()` | mesh, {tool, machine, strategy} | {gcode, time, passes} | `toolpath(m, {strategy:'contour'})` |
+| `nest()` | parts[], sheetSize | {placements, utilization} | `nest([{w:100,h:50}], {w:1000})` |
+| `compareCosts()` | mesh, {material} | {processes[]} | `compareCosts(m)` |
+| `estimate()` | mesh, {process, quantity} | {cost, time, breakdown} | `estimate(m, {process:'FDM'})` |
+| `exportGcode()` | gcode, filename | download | `exportGcode(gcode, 'p.gcode')` |
+| `getMachines()` | none | {id, name, type, specs}[] | `getMachines()` |
+| `getTools()` | none | {id, name, diameter}[] | `getTools()` |
+| `getMaterials()` | none | {materials[]} | `getMaterials()` |
+
+## Machine Quick Codes
+
+| Code | Machine | Type | Build Volume |
+|------|---------|------|---------------|
+| `ender3` | Creality Ender 3 | FDM | 220×220×250 |
+| `prusa_mk4` | Prusa MK4 | FDM | 250×210×210 |
+| `bambu_x1` | Bambu Lab X1 | FDM | 256×256×256 |
+| `elegoo_mars` | Elegoo Mars | SLA | 129×80×150 |
+| `formlabs_form3` | Formlabs Form 3 | SLA | 145×145×185 |
+| `shapeoko` | Shapeoko 5 | CNC | 400×400×75 |
+| `nomad3` | Nomad 3 | CNC | 203×203×76 |
+| `tormach_pcnc` | Tormach PCNC | CNC | 432×279×305 |
+| `k40` | K40 Laser | Laser | 300×200 |
+| `xtool_d1` | xTool M1 | Laser | 432×406 |
+
+## Material Quick Codes
+
+| Material | Density | Cost/kg | Best For |
+|----------|---------|---------|----------|
+| `pla` | 1.24 | €8.00 | FDM (default) |
+| `petg` | 1.27 | €12.00 | FDM (tough) |
+| `abs` | 1.05 | €10.00 | FDM (flexible) |
+| `nylon` | 1.14 | €2.50 | FDM (strong) |
+| `resin` | 1.15 | €35.00 | SLA (detail) |
+| `steel` | 7.85 | €0.50 | CNC |
+| `aluminum` | 2.70 | €1.20 | CNC |
+
+## Keyboard Shortcuts (if integrated into UI)
+
+| Key | Action |
+|-----|--------|
+| `Alt+C` | Toggle CAM panel |
+| `S` | Slice current part |
+| `E` | Export G-code |
+| `Shift+C` | Compare costs |
+
+## Common Workflows
+
+### Print a Part
+```javascript
+const mesh = window.allParts[0];
+const result = window.cycleCAD.cam.slice(mesh);
+window.cycleCAD.cam.exportGcode(result.gcode, 'part.gcode');
+// → Download G-code, open in Cura, print
+```
+
+### Find Cheapest Option
+```javascript
+const comparison = window.cycleCAD.cam.compareCosts(mesh);
+const cheapest = comparison.processes[0];
+console.log(`${cheapest.process}: €${cheapest.totalCost}`);
+```
+
+### Batch Production Cost
+```javascript
+for (let qty of [1, 10, 100]) {
+  const est = window.cycleCAD.cam.estimate(mesh, {quantity: qty});
+  console.log(`${qty}x: €${est.totalBatch} (€${(est.totalBatch/qty).toFixed(2)}/unit)`);
+}
+```
+
+### Check Build Volume Fit
+```javascript
+const result = window.cycleCAD.cam.slice(mesh, {printer: 'ender3'});
+if (!result.fits) {
+  console.warn('Too large for Ender 3');
+  const result2 = window.cycleCAD.cam.slice(mesh, {printer: 'bambu_x1'});
+  console.log(`Bambu X1: ${result2.fits ? 'fits' : 'too large'}`);
+}
+```
+
+### CNC Milling Setup
+```javascript
+const result = window.cycleCAD.cam.toolpath(mesh, {
+  machine: 'shapeoko',
+  tool: 't_6mm_flat',
+  strategy: 'contour',
+  feedRate: 600
+});
+console.log(`Time: ${result.estimatedTimeReadable}`);
+window.cycleCAD.cam.exportGcode(result.gcode, 'mill.nc');
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "mesh is undefined" | Get mesh from `window.allParts[0]` |
+| "printer not found" | Use `getMachines()` to list valid IDs |
+| "Volume too large" | Try larger printer or rotate mesh |
+| "G-code looks wrong" | Use output in dedicated slicer (Cura) |
+| "Cost seems off" | Material costs vary; adjust in CAM-INTEGRATION.md |
+
+## Response Format
+
+All functions return an object with:
+```javascript
+{
+  // Main result
+  result: {},          // Function-specific output
+
+  // Common fields
+  time: number,        // Estimated time in minutes
+  cost: number,        // Total cost in EUR
+  fits: boolean,       // Fits in build volume
+  gcode: string,       // G-code output (if applicable)
+
+  // Error (if thrown)
+  error: string        // Error message
+}
+```
+
+## Performance
+
+| Operation | Time |
+|-----------|------|
+| Slice simple mesh | <100ms |
+| Slice complex mesh | <300ms |
+| Toolpath generation | <200ms |
+| Cost comparison | <50ms |
+| Nesting 20 parts | <50ms |
+| Export G-code | instant |
+
+All operations are synchronous.
+
+## Integration Points
+
+1. **Console API** — Already available as `window.cycleCAD.cam`
+2. **Agent API** — Add to `agent-api.js` commands
+3. **UI Panel** — Copy HTML from CAM-INTEGRATION.md
+4. **Toolbar** — Add button to toggle CAM panel
+
+## Learning Path
+
+1. **Try it now** → `const m = window.allParts[0]; console.log(window.cycleCAD.cam.slice(m))`
+2. **Read examples** → See CAM-EXAMPLES.md
+3. **Explore API** → Try each of the 11 functions
+4. **Integrate UI** → Copy panel code to app/index.html
+5. **Wire agent** → Add cam.* commands to agent-api.js
+
+---
+
+**Version 1.0** — Last updated 2026-03-26

package/docs/CLI-INTEGRATION.md

@@ -0,0 +1,510 @@
+# cycleCAD CLI Integration Guide
+
+This guide explains how to integrate the cycleCAD CLI with your actual CAD application.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Terminal / Script                                       │
+│  $ cyclecad shape.cylinder --radius 25 --height 80     │
+└──────────────────┬──────────────────────────────────────┘
+                   │
+                   │ HTTP POST /api/execute
+                   │ { method: "shape.cylinder", params: {...} }
+                   │
+┌──────────────────▼──────────────────────────────────────┐
+│  cycleCAD API Server (Node.js / Express / FastAPI)      │
+│  - Receives command via /api/execute                     │
+│  - Dispatches to cycleCAD modules                       │
+│  - Returns JSON result                                  │
+└──────────────────┬──────────────────────────────────────┘
+                   │
+                   │ HTTP Response
+                   │ { ok: true, result: {...} }
+                   │
+┌──────────────────▼──────────────────────────────────────┐
+│  CLI Client                                              │
+│  - Parses response JSON                                 │
+│  - Formats output for terminal                          │
+│  - Displays results                                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Step 1: Implement the API Endpoint
+
+Create a `/api/execute` endpoint in your server that receives commands and returns results.
+
+### Express.js Example
+
+```javascript
+// server.js
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+// Import cycleCAD modules
+const { viewport, sketch, operations } = require('./cycleCAD');
+
+// Main API endpoint
+app.post('/api/execute', (req, res) => {
+  const { method, params } = req.body;
+
+  try {
+    // Dispatch command to appropriate handler
+    const result = executeCommand(method, params);
+
+    res.json({
+      ok: true,
+      result: result
+    });
+  } catch (error) {
+    res.status(400).json({
+      ok: false,
+      error: error.message
+    });
+  }
+});
+
+// Command dispatcher
+function executeCommand(method, params) {
+  const [namespace, command] = method.split('.');
+
+  // Route to appropriate namespace handler
+  switch (namespace) {
+    case 'shape':
+      return handleShapeCommand(command, params);
+    case 'sketch':
+      return handleSketchCommand(command, params);
+    case 'feature':
+      return handleFeatureCommand(command, params);
+    // ... more namespaces
+    default:
+      throw new Error(`Unknown namespace: ${namespace}`);
+  }
+}
+
+// Shape handlers
+function handleShapeCommand(command, params) {
+  switch (command) {
+    case 'cylinder':
+      return viewport.createCylinder(params.radius, params.height);
+    case 'box':
+      return viewport.createBox(params.width, params.height, params.depth);
+    // ... more shape commands
+    default:
+      throw new Error(`Unknown command: shape.${command}`);
+  }
+}
+
+// Similar handlers for other namespaces...
+
+app.listen(3000, () => {
+  console.log('cycleCAD API server running on http://localhost:3000');
+});
+```
+
+### Python / FastAPI Example
+
+```python
+# server.py
+from fastapi import FastAPI
+from pydantic import BaseModel
+import cyclecad
+
+app = FastAPI()
+
+class ExecuteRequest(BaseModel):
+    method: str
+    params: dict = {}
+
+@app.post("/api/execute")
+async def execute_command(request: ExecuteRequest):
+    try:
+        method, params = request.method, request.params
+        result = dispatch_command(method, params)
+        return {"ok": True, "result": result}
+    except Exception as e:
+        return {"ok": False, "error": str(e)}
+
+def dispatch_command(method: str, params: dict):
+    namespace, command = method.split('.')
+
+    if namespace == 'shape':
+        if command == 'cylinder':
+            return cyclecad.create_cylinder(
+                radius=params.get('radius'),
+                height=params.get('height')
+            )
+        # ... more commands
+    elif namespace == 'sketch':
+        # ... sketch commands
+        pass
+    # ... more namespaces
+
+    raise ValueError(f"Unknown command: {method}")
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=3000)
+```
+
+## Step 2: Return Proper Response Format
+
+Each command handler should return a result object. The response format is:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "entityId": "unique_id",
+    "type": "shape/feature/assembly",
+    "property1": "value",
+    "property2": 123,
+    "message": "Human-readable message"
+  }
+}
+```
+
+### Examples
+
+**Create a cylinder:**
+```json
+{
+  "ok": true,
+  "result": {
+    "entityId": "cylinder_1",
+    "type": "shape",
+    "radius": 25,
+    "height": 80,
+    "volume": 157079.63,
+    "message": "Created cylinder with radius 25mm and height 80mm"
+  }
+}
+```
+
+**Validate dimensions:**
+```json
+{
+  "ok": true,
+  "result": {
+    "target": "extrude_1",
+    "dimensions": {
+      "width": 80,
+      "height": 40,
+      "depth": 30
+    },
+    "message": "Dimensions calculated"
+  }
+}
+```
+
+**Estimate cost:**
+```json
+{
+  "ok": true,
+  "result": {
+    "target": "bracket",
+    "process": "CNC",
+    "material": "aluminum",
+    "cost": 45.50,
+    "costPerUnit": 0.4550,
+    "quantity": 100,
+    "message": "Cost estimation complete"
+  }
+}
+```
+
+**Design review:**
+```json
+{
+  "ok": true,
+  "result": {
+    "target": "bracket",
+    "score": "B",
+    "warnings": [
+      "Wall thickness approaching minimum (0.9mm < 1.0mm)",
+      "Sharp corner at junction — consider adding fillet"
+    ],
+    "suggestions": [
+      "Increase wall thickness by 0.5mm",
+      "Add 2mm fillet to corners",
+      "Check for draft angle on undercuts"
+    ],
+    "message": "Design review complete with score: B"
+  }
+}
+```
+
+## Step 3: Handle Each Namespace
+
+### shape.* — Geometry Creation
+
+```javascript
+// Should create 3D geometry and return entityId
+shape.cylinder({ radius: 25, height: 80 })
+// Returns: { entityId: "cylinder_1", radius: 25, height: 80, volume: 157079.63 }
+
+shape.box({ width: 50, height: 40, depth: 30 })
+// Returns: { entityId: "box_1", width: 50, height: 40, depth: 30, volume: 60000 }
+
+shape.sphere({ radius: 30 })
+// Returns: { entityId: "sphere_1", radius: 30, volume: 113097.34 }
+```
+
+### sketch.* — 2D Sketch Operations
+
+```javascript
+// Sketch operations work within a sketch context
+sketch.start({ plane: 'XY' })
+// Returns: { sketchId: "sketch_1", plane: "XY", ready: true }
+
+sketch.circle({ cx: 0, cy: 0, radius: 15 })
+// Returns: { entityId: "circle_1", cx: 0, cy: 0, radius: 15 }
+
+sketch.rect({ x: 0, y: 0, width: 100, height: 50 })
+// Returns: { entityId: "rect_1", x: 0, y: 0, width: 100, height: 50 }
+
+sketch.end()
+// Returns: { sketchId: "sketch_1", entities: 3, ready: false }
+```
+
+### feature.* — 3D Feature Operations
+
+```javascript
+feature.extrude({ height: 10 })
+// Returns: { entityId: "extrude_1", height: 10, volume: /* calculated */ }
+
+feature.fillet({ radius: 5, edges: 'all' })
+// Returns: { entityId: "fillet_1", radius: 5, edges: "all", applied: true }
+
+feature.pattern({ type: 'rectangular', count: 3, spacing: 25 })
+// Returns: { entityId: "pattern_1", type: "rectangular", count: 3, instances: 3 }
+```
+
+### validate.* — Analysis & Validation
+
+```javascript
+validate.dimensions({ target: 'extrude_1' })
+// Returns: { target: "extrude_1", dimensions: { width: 80, height: 40, depth: 30 } }
+
+validate.cost({ target: 'bracket', process: 'CNC', material: 'aluminum' })
+// Returns: { target: "bracket", cost: 45.50, process: "CNC", material: "aluminum" }
+
+validate.designReview({ target: 'bracket' })
+// Returns: { target: "bracket", score: "B", warnings: [...], suggestions: [...] }
+```
+
+### render.* — Viewport Operations
+
+```javascript
+render.snapshot({ width: 1200, height: 800 })
+// Returns: { imageUrl: "data:image/png;base64,..." }
+
+render.multiview({ width: 400, height: 400 })
+// Returns: { views: { front: "data:...", back: "data:...", ... } }
+
+render.highlight({ target: 'cylinder_1', color: 0xffff00 })
+// Returns: { target: "cylinder_1", highlighted: true }
+```
+
+### export.* — File Export
+
+```javascript
+export.stl({ filename: 'bracket.stl', binary: true })
+// Returns: { filename: "bracket.stl", format: "STL", size: 2048000 }
+
+export.json({ filename: 'bracket.json' })
+// Returns: { filename: "bracket.json", format: "JSON", size: 45000 }
+```
+
+### assembly.* — Assembly Management
+
+```javascript
+assembly.addComponent({ name: 'bolt', meshOrFile: 'cylinder_1', position: [0, 0, 10] })
+// Returns: { componentId: "bolt_1", name: "bolt", position: [0, 0, 10] }
+
+assembly.bom({ target: 'assembly_1' })
+// Returns: { target: "assembly_1", components: 23, subassemblies: 4 }
+```
+
+### meta.* — API Metadata
+
+```javascript
+meta.version()
+// Returns: { version: "0.1.0", apiVersion: "1.0.0" }
+
+meta.getSchema()
+// Returns: { namespaces: 10, commands: 30, ... }
+```
+
+## Step 4: Testing
+
+Once implemented, test with the CLI:
+
+```bash
+# Start your server
+npm start
+# or
+python server.py
+
+# In another terminal, test with CLI
+node bin/cyclecad-cli.js shape.cylinder --radius 25 --height 80
+# Should output: ✓ Command executed: shape.cylinder
+
+node bin/cyclecad-cli.js --list
+# Should list all available commands
+
+node bin/cyclecad-cli.js --batch examples/batch-simple.txt
+# Should execute batch and report results
+```
+
+## Step 5: Configuration
+
+Allow the CLI to connect to different servers:
+
+```bash
+# Default server
+cyclecad shape.cylinder --radius 25 --height 80
+
+# Custom server
+cyclecad --server http://production.cyclecad.com shape.cylinder --radius 25
+
+# Environment variable
+export CYCLECAD_SERVER=http://production.cyclecad.com
+cyclecad shape.cylinder --radius 25
+```
+
+## Step 6: Error Handling
+
+Return proper error responses:
+
+```json
+{
+  "ok": false,
+  "error": "Unknown command: invalid.method"
+}
+```
+
+The CLI will display:
+```
+[10:37:35] ✗ Command failed: Unknown command: invalid.method
+```
+
+## Integration Checklist
+
+- [ ] Create `/api/execute` endpoint
+- [ ] Implement command dispatcher
+- [ ] Implement all namespace handlers (shape, sketch, feature, etc.)
+- [ ] Return proper JSON response format
+- [ ] Test with CLI: `--help`, `--list`, single commands
+- [ ] Test batch mode: `--batch examples/batch-simple.txt`
+- [ ] Test JSON output: `--json`
+- [ ] Test error cases
+- [ ] Add CORS headers if needed
+- [ ] Deploy to production server
+- [ ] Update CLI server URL in configuration
+- [ ] Document server API for other clients
+
+## Example Integration in cycleCAD
+
+Here's how to integrate in the existing `app/index.html`:
+
+```javascript
+// In your server initialization
+import { initAgentAPI } from './app/js/agent-api.js';
+
+// After initializing all modules
+const { sessionId } = initAgentAPI({
+  viewport: window._viewport,
+  sketch: window._sketch,
+  operations: window._ops,
+  advancedOps: window._advancedOps,
+  exportModule: window._exportMod,
+  appState: window._appState,
+  tree: window._tree,
+  assembly: window._assemblyModule
+});
+
+// Expose HTTP API
+const express = require('express');
+const app = express();
+
+app.post('/api/execute', (req, res) => {
+  const { method, params } = req.body;
+  try {
+    const result = window.cycleCAD.execute({ method, params });
+    res.json({ ok: true, result });
+  } catch (error) {
+    res.status(400).json({ ok: false, error: error.message });
+  }
+});
+
+app.listen(3000);
+```
+
+## Deployment Options
+
+### 1. Single Node.js Server
+```bash
+node server.js
+cyclecad shape.cylinder --radius 25
+```
+
+### 2. Containerized (Docker)
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+### 3. Cloud Deployment (Vercel, Netlify)
+```bash
+npm install -g vercel
+vercel --prod
+```
+
+## Performance Optimization
+
+- Cache frequently accessed data
+- Use database for history/state
+- Implement request queuing for batch operations
+- Add rate limiting for production
+- Monitor API response times
+
+## Security Considerations
+
+- Add authentication (API keys, JWT)
+- Validate input parameters
+- Sanitize output for display
+- Rate limit API endpoints
+- Log all commands for audit trail
+- Implement HTTPS for production
+
+## Monitoring & Logging
+
+```javascript
+app.use((req, res, next) => {
+  const start = Date.now();
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    console.log(`${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
+  });
+  next();
+});
+```
+
+## Further Reading
+
+- CLI Documentation: `docs/CLI.md`
+- Quick Start: `QUICKSTART-CLI.md`
+- Build Summary: `CLI-BUILD-SUMMARY.md`
+- Agent API: `app/js/agent-api.js`
+- Mock Server: `bin/server.js`
+
+---
+
+For questions or issues, refer to the main documentation or create an issue on GitHub.