brepjs-claude-plugin 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "brepjs",
+  "version": "1.0.0",
+  "description": "Generate production-ready CAD models using expert methodology",
+  "author": {
+    "name": "brepjs team",
+    "url": "https://github.com/andymai/brepjs"
+  },
+  "homepage": "https://github.com/andymai/brepjs/tree/main/brepjs-plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andymai/brepjs",
+    "directory": "brepjs-plugin"
+  },
+  "license": "Apache-2.0",
+  "commands": [
+    "brepjs",
+    "brepjs:analyze",
+    "brepjs:validate",
+    "brepjs:export"
+  ],
+  "agents": [
+    "brepjs-modeler",
+    "brepjs-validator"
+  ],
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "command": "sh ${CLAUDE_PLUGIN_ROOT}/scripts/validate-brepjs-file.sh"
+      }
+    ]
+  },
+  "requirements": {
+    "brepjs": ">=7.0.0",
+    "node": ">=18",
+    "typescript": ">=5.0.0"
+  },
+  "keywords": ["cad", "3d-modeling", "mechanical-design", "brepjs", "opencascade", "parametric"]
+}

package/README.md

@@ -0,0 +1,99 @@
+# brepjs Plugin
+
+Generate CAD models using expert methodology.
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+claude-code plugins add brepjs-claude-plugin
+```
+
+### From GitHub
+
+```bash
+claude-code plugins add https://github.com/andymai/brepjs/tree/main/brepjs-plugin
+```
+
+### Local development
+
+```bash
+claude-code plugins add ./brepjs-plugin
+```
+
+Verify installation:
+
+```bash
+claude-code plugins list | grep brepjs
+```
+
+## Commands
+
+### `/brepjs <description>`
+
+5-phase workflow: Clarify → Explore → Design → Implement → Validate
+
+- Asks functional questions (INTO/ONTO/THROUGH?)
+- Presents 2-3 approaches with trade-offs
+- Generates parametric TypeScript
+- Auto-validates geometry
+
+### `/brepjs:analyze <file.stl>`
+
+Quick STL analysis (dimensions, mesh quality, ASCII preview)
+
+### `/brepjs:validate <file.ts>`
+
+Run model and validate output
+
+### `/brepjs:export <format>`
+
+Export to STEP/GLTF/OBJ/SVG
+
+## Agents
+
+**brepjs-modeler** (sonnet) - Decomposes designs into B-REP operations
+
+- Workflow selection: extrude/loft/revolve/sweep
+- Profile management: < 80 points
+- Auto-recovery on errors
+
+**brepjs-validator** (haiku) - Validates geometry
+
+- Checks: execution, volume, mesh quality, dimensions
+- ASCII preview generation
+
+## Key Patterns
+
+**Profile Complexity:**
+
+- Safe: < 60 points
+- Risky: 60-80 points
+- Fatal: > 100 points (auto-simplifies)
+
+**Helical Geometry:**
+
+```typescript
+// ✓ Use loft (smooth)
+loft([bottomWire, topWire], { ruled: false });
+
+// ✗ Never stacked slices (stair-stepping)
+```
+
+**Functional Requirements:**
+
+- INTO → HOLLOW
+- ONTO → SOLID with mounting
+- THROUGH → HOLLOW channel
+
+## Examples
+
+Progressive: `examples/progressive/01-04` (simple → complex)
+Functional: `examples/functional/` (real-world parts)
+
+## Requirements
+
+- brepjs >= 1.0.0
+- Node.js >= 18
+- TypeScript >= 5.0.0

package/agents/brepjs-modeler.md

@@ -0,0 +1,146 @@
+---
+name: brepjs-modeler
+description: 'Expert CAD modeler - decomposes designs into B-REP operations. Workflow selection: extrude/loft/revolve/sweep. Manages profile complexity < 80 points.'
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+model: sonnet
+color: blue
+---
+
+# brepjs-modeler
+
+## Core Task
+
+Decompose user requirements into B-REP operations. Present 2-3 approaches with trade-offs.
+
+## Decision Tree
+
+### 1. Base Form Selection
+
+- **2D profile** → extrude/revolve/loft/sweep
+- **Primitive** → box/cylinder/sphere + booleans
+- **Combination** → multiple primitives fused
+
+### 2. 3D Transform Selection
+
+- **Constant cross-section** → Extrude
+- **Axially symmetric** → Revolve
+- **Twisted/helical** → **Loft** (NEVER stacked slices)
+- **Path-following** → Sweep
+
+### 3. Profile Complexity
+
+- **< 60 points**: Safe
+- **60-80 points**: Risky but acceptable
+- **> 80 points**: Fatal - auto-simplify
+
+Auto-simplification: Reduce points per feature (8→6→4) until < 80
+
+### 4. Functional Requirements (CRITICAL)
+
+Ask first: "What goes INTO/ONTO/THROUGH this part?"
+
+- **INTO** (tool/wire) → HOLLOW structure
+- **ONTO** (mount) → SOLID with features
+- **THROUGH** (cable) → HOLLOW channel
+
+## Workflow for /brepjs Command
+
+### Phase 2: Exploration
+
+Search `examples/` for similar patterns. Report:
+
+- Relevant files
+- Profile complexity found
+- Recommended workflow
+
+```bash
+rg "extrude|loft|revolve" examples/
+rg "gear|tooth" examples/
+```
+
+### Phase 3: Design (Present 2-3 approaches)
+
+Template:
+
+```
+## Approach A: [Name]
+Operations: 1. [step], 2. [step], 3. [step]
+Profile: [N] points ([safe/risky/fatal])
+Stability: ⭐⭐⭐⭐⭐ (5=rock solid)
+Flexibility: ⭐⭐⭐⭐⭐ (5=parametric)
+Trade-off: [key limitation]
+```
+
+Wait for user approval before Phase 4.
+
+### Phase 4: Implementation
+
+Generate TypeScript with:
+
+- Parametric interface (JSDoc)
+- Expert thinking comments: "// This is prismatic → extrude"
+- Profile complexity note: "// 60 points (safe)"
+- Validation function
+- Export logic
+
+## Critical Patterns
+
+### Helical Geometry
+
+```typescript
+// ✓ CORRECT - Loft
+const bottom = createProfile(0, 0);
+const top = createProfile(height, rotated);
+const gear = loft([bottomWire, topWire], { ruled: false });
+
+// ✗ WRONG - Stacked slices (stair-stepping)
+for (let i = 0; i < 8; i++) gear = gear.fuse(slice);
+```
+
+### Gears
+
+- Spur: 2D profile (6 pts/tooth) → extrude
+- Helical: Bottom + top profiles → loft
+- Profile at pitch circle (not random)
+- Tooth flanks must engage
+
+## Error Recovery
+
+| Error            | Action                     |
+| ---------------- | -------------------------- |
+| Profile > 80 pts | Auto-reduce points/feature |
+| Boolean fails    | Try `heal()` first         |
+| Loft crashes     | Fallback to extrude, warn  |
+| WASM error       | Add `initFromOC(oc)`       |
+
+Report recoveries: "⚠️ Profile simplified: 95 → 72 points"
+
+## Code Structure
+
+```typescript
+import initOpenCascade from 'opencascade.js';
+import { initFromOC, box, shape, exportSTL } from 'brepjs';
+
+interface PartParams {
+  /** Dimension in mm */
+  width: number;
+}
+
+function createPart(params: PartParams) {
+  // Expert thinking: [workflow choice]
+  // Profile: [N] points (safe/risky)
+
+  // Implementation
+  return solid;
+}
+
+async function main() {
+  const oc = await initOpenCascade();
+  initFromOC(oc);
+
+  const model = createPart({ width: 40 });
+  await exportSTL(model, 'output.stl', { tolerance: 0.1 });
+}
+
+main().catch(console.error);
+```

package/agents/brepjs-validator.md

@@ -0,0 +1,72 @@
+---
+name: brepjs-validator
+description: 'Validates brepjs geometry. Runs TS models, analyzes STL output, checks mesh quality, verifies dimensions, detects issues.'
+tools: [Bash, Read, Grep]
+model: haiku
+color: green
+---
+
+# brepjs-validator
+
+## Validation Checklist
+
+### 1. Execution
+
+```bash
+npx tsx file.ts
+# Check exit code, find STL output
+```
+
+### 2. Geometry
+
+- Volume > 1e-9 (not empty)
+- All dimensions > 0.1mm (no collapse)
+- Bounding box valid
+
+### 3. Mesh Quality
+
+- Triangles > 0
+- No NaN vertices
+- Edge lengths reasonable (0.01-50mm)
+- Degenerate triangles < 5 (edges > 50mm)
+
+### 4. Dimensions
+
+Compare actual vs expected (tolerance ±0.5mm)
+
+### 5. ASCII Preview
+
+Generate side view (60×20 chars)
+
+## Report Format
+
+```
+=== VALIDATION REPORT ===
+
+Execution: ✓/❌ [status]
+Geometry: ✓/❌ [dimensions, volume]
+Mesh Quality: ✓/⚠️/❌ [triangles, edges]
+ASCII Preview: [visualization]
+Overall: ✓/⚠️/❌ [result]
+```
+
+## Issue Detection
+
+| Issue                | Cause                        | Fix               |
+| -------------------- | ---------------------------- | ----------------- |
+| Zero volume          | Boolean removed entire solid | Check positioning |
+| Dimension < 0.1mm    | Extrusion height = 0         | Check parameters  |
+| Degenerate triangles | Tolerance too high           | Reduce to 0.1mm   |
+| NaN vertices         | WASM corruption              | Restart           |
+
+## Analysis Script (Three.js)
+
+```javascript
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+
+const geometry = loader.parse(stlBuffer);
+geometry.computeBoundingBox();
+
+// Check volume, edges, degenerate triangles
+// Generate ASCII preview from XZ projection
+```

package/commands/analyze.md

@@ -0,0 +1,22 @@
+---
+description: Analyze STL mesh quality and dimensions
+argument-hint: <file.stl>
+allowed-tools: [Read, Bash]
+model: haiku
+---
+
+# /brepjs:analyze
+
+Quick STL analysis.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/analyze-stl.js" "$1"
+```
+
+Reports:
+
+- File size, triangles
+- Dimensions, volume
+- Edge lengths
+- Degenerate triangles
+- ASCII preview

package/commands/brepjs.md

@@ -0,0 +1,70 @@
+---
+description: Generate CAD models using expert methodology
+argument-hint: <model description>
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion]
+model: sonnet
+---
+
+# /brepjs
+
+5-phase workflow: Clarify → Explore → Design → Implement → Validate
+
+## Phase 1: Requirements
+
+Ask:
+
+- What goes INTO/ONTO/THROUGH this part?
+- Dimensions, tolerances?
+- Manufacturing method?
+- Complexity level?
+
+Output: Functional requirements
+
+## Phase 2: Exploration
+
+Launch brepjs-modeler agent:
+
+```
+Explore examples/ for patterns relevant to: [description]
+Report: files found, complexity, recommended workflow
+```
+
+## Phase 3: Design (Approval Required)
+
+Agent presents 2-3 approaches:
+
+- B-REP operations
+- Profile complexity
+- Stability/flexibility ratings
+- Trade-offs
+
+Use AskUserQuestion for approval.
+
+## Phase 4: Implementation
+
+Generate TypeScript file:
+
+- Parametric interface
+- Expert thinking comments
+- Validation code
+- STL export
+
+## Phase 5: Validation (Approval Required)
+
+Auto-hook validates:
+
+- Runs file
+- Analyzes STL
+- Shows report + ASCII preview
+
+Use AskUserQuestion for confirmation.
+
+## Error Recovery
+
+| Error            | Recovery            |
+| ---------------- | ------------------- |
+| Profile > 80 pts | Auto-simplify       |
+| Boolean fails    | Try heal()          |
+| Loft crashes     | Fallback to extrude |
+
+Report recoveries to user.

package/commands/export.md

@@ -0,0 +1,34 @@
+---
+description: Export CAD model to STEP, GLTF, OBJ, or SVG
+argument-hint: <format>
+allowed-tools: [Read, Edit, Bash]
+model: haiku
+---
+
+# /brepjs:export
+
+Export to different formats.
+
+**Formats:**
+
+- STEP: Exact geometry (CAD)
+- GLTF: Web 3D
+- OBJ: Rendering
+- SVG: 2D projections
+
+**Action:**
+
+1. Find recent brepjs .ts file
+2. Add export code
+3. Run file
+
+```typescript
+// STEP
+await exportSTEP(model, 'output.step');
+
+// GLTF
+await exportGLTF(model, 'output.gltf', { tolerance: 0.1 });
+
+// SVG (projections)
+await exportSVG(model, 'output-top.svg', { direction: [0, 0, -1] });
+```

package/commands/validate.md

@@ -0,0 +1,23 @@
+---
+description: Execute brepjs model and validate output geometry
+argument-hint: <file.ts>
+allowed-tools: [Bash, Read]
+model: haiku
+---
+
+# /brepjs:validate
+
+Run TS file and validate STL output.
+
+```bash
+cd "$(dirname "$FILE")"
+npx tsx "$(basename "$FILE")"
+
+# Find generated STL
+STL=$(find . -name "*.stl" -newer "$FILE" | head -1)
+
+# Analyze
+node "${CLAUDE_PLUGIN_ROOT}/scripts/analyze-stl.js" "$STL"
+```
+
+Reports: Execution status, geometry validity, mesh quality, dimensions.

package/examples/functional/cable-organizer.ts

@@ -0,0 +1,40 @@
+/**
+ * Cable Organizer with Snap-Fit
+ *
+ * Functional requirements:
+ * - THROUGH: Multiple cable channels
+ * - ONTO: Mounts to desk edge with clip
+ *
+ * Manufacturing: 3D printing
+ */
+
+import initOpenCascade from 'opencascade.js';
+import { initFromOC, box, cylinder, shape, exportSTL } from 'brepjs';
+
+function createCableOrganizer() {
+  // Simplified implementation
+  const body = box(100, 30, 20);
+  
+  // Cable channels
+  let organizer = shape(body).val;
+  
+  for (let i = 0; i < 5; i++) {
+    const channel = cylinder(5, 22, {
+      at: [20 + i * 15, 15, -1],
+    });
+    organizer = shape(organizer).cut(channel).val;
+  }
+
+  return organizer;
+}
+
+async function main() {
+  const oc = await initOpenCascade();
+  initFromOC(oc);
+
+  const model = createCableOrganizer();
+  await exportSTL(model, 'examples/output/cable-organizer.stl');
+  console.log('✓ Cable organizer generated');
+}
+
+main().catch(console.error);

package/examples/functional/pcb-mount.ts

@@ -0,0 +1,50 @@
+/**
+ * PCB Mount with Standoffs
+ *
+ * Functional requirements:
+ * - ONTO: PCB sits on raised standoffs
+ * - Precise M3 mounting holes
+ * - Standard PCB dimensions (100×80mm)
+ *
+ * Manufacturing: CNC or 3D printing
+ */
+
+import initOpenCascade from 'opencascade.js';
+import { initFromOC, box, cylinder, shape, exportSTL } from 'brepjs';
+
+function createPCBMount() {
+  // Base plate
+  const base = box(120, 100, 3);
+  
+  let mount = shape(base).val;
+  
+  // Add 4 standoffs at PCB corners
+  const standoffPositions = [
+    [10, 10],
+    [110, 10],
+    [10, 90],
+    [110, 90],
+  ];
+  
+  for (const [x, y] of standoffPositions) {
+    const standoff = cylinder(4, 5, { at: [x, y, 3] });
+    mount = shape(mount).fuse(standoff).val;
+    
+    // M3 mounting hole through standoff
+    const hole = cylinder(1.6, 10, { at: [x, y, 0] });
+    mount = shape(mount).cut(hole).val;
+  }
+
+  return mount;
+}
+
+async function main() {
+  const oc = await initOpenCascade();
+  initFromOC(oc);
+
+  const model = createPCBMount();
+  await exportSTL(model, 'examples/output/pcb-mount.stl');
+  console.log('✓ PCB mount generated');
+}
+
+main().catch(console.error);

package/examples/functional/phone-stand.ts

@@ -0,0 +1,68 @@
+/**
+ * Phone Stand with Cable Routing
+ *
+ * Functional requirements:
+ * - ONTO: Phone rests on angled surface
+ * - THROUGH: Cable routing channel for charging
+ * - Stable base, angled back support
+ *
+ * Manufacturing: 3D printing (FDM)
+ * Material: PLA/PETG
+ */
+
+import initOpenCascade from 'opencascade.js';
+import { initFromOC, box, shape, exportSTL } from 'brepjs';
+
+interface PhoneStandParams {
+  baseWidth: number;
+  baseDepth: number;
+  baseHeight: number;
+  backHeight: number;
+  angle: number; // Degrees from vertical
+  cableChannelWidth: number;
+}
+
+function createPhoneStand(params: PhoneStandParams) {
+  // Base plate
+  const base = box(params.baseWidth, params.baseDepth, params.baseHeight);
+
+  // Angled back support
+  // (Simplified - in real implementation would use rotation)
+  const back = box(params.baseWidth, 5, params.backHeight, {
+    at: [0, params.baseDepth - 5, params.baseHeight],
+  });
+
+  let stand = shape(base).fuse(back).val;
+
+  // Cable routing channel (hollow through base)
+  const channel = box(
+    params.cableChannelWidth,
+    params.baseDepth + 2,
+    params.baseHeight + 2,
+    { at: [params.baseWidth / 2 - params.cableChannelWidth / 2, -1, -1] }
+  );
+
+  stand = shape(stand).cut(channel).val;
+
+  return stand;
+}
+
+async function main() {
+  const oc = await initOpenCascade();
+  initFromOC(oc);
+
+  const params: PhoneStandParams = {
+    baseWidth: 80,
+    baseDepth: 60,
+    baseHeight: 10,
+    backHeight: 100,
+    angle: 70, // 70° from vertical
+    cableChannelWidth: 10,
+  };
+
+  const model = createPhoneStand(params);
+  await exportSTL(model, 'examples/output/phone-stand.stl');
+  console.log('✓ Phone stand generated');
+}
+
+main().catch(console.error);