@williamzujkowski/live-coding-music-mcp 2.0.0 → 4.0.0

package/dist/server/tools/types.js

@@ -6,4 +6,69 @@
  * dispatcher. The server keeps the MCP protocol layer thin and delegates
  * to these modules.
  */
-export {};
+/** Type guard for tools and dispatchers. */
+export function isEnvelope(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'ok' in v &&
+        typeof v.ok === 'boolean');
+}
+/** Construct a success envelope. */
+export function ok(data) {
+    return { ok: true, data };
+}
+/**
+ * Construct a success envelope that represents a valid-empty result —
+ * the call worked but produced nothing (no patterns found, empty
+ * history, etc.). Distinct from `err` so agents can choose between
+ * "report nothing" and "retry/setup".
+ */
+export function empty(data) {
+    return { ok: true, data, empty: true };
+}
+/** Construct an error envelope. */
+export function err(category, message, opts) {
+    return {
+        ok: false,
+        errorCategory: category,
+        // Default retryability follows category: transient retries, others don't.
+        isRetryable: opts?.isRetryable ?? category === 'transient',
+        message,
+        ...(opts?.partialResult !== undefined ? { partialResult: opts.partialResult } : {}),
+    };
+}
+/**
+ * Best-effort error categorization for raw thrown errors. Used by the
+ * dispatcher when a tool throws without wrapping. Tools that know better
+ * should construct `err(category, message)` directly.
+ */
+export function categorizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes('not initialized') ||
+        lower.includes("run 'init' first") ||
+        lower.includes('run init first') ||
+        lower.includes('not found') ||
+        lower.includes('already exists')) {
+        return 'business';
+    }
+    if (lower.includes('invalid') ||
+        lower.includes('must be') ||
+        lower.includes('required') ||
+        lower.includes('out of range')) {
+        return 'validation';
+    }
+    if (lower.includes('gemini') ||
+        lower.includes('api key') ||
+        lower.includes('unauthorized') ||
+        lower.includes('forbidden')) {
+        return 'permission';
+    }
+    if (lower.includes('timeout') ||
+        lower.includes('econnrefused') ||
+        lower.includes('network') ||
+        lower.includes('fetch failed')) {
+        return 'transient';
+    }
+    return 'internal';
+}

package/dist/services/AudioCaptureService.js

@@ -89,7 +89,7 @@ export class AudioCaptureService {
                                 capture.chunks.push(event.data);
                             }
                         };
-                        capture.recorder.onerror = (event) => {
+                        capture.recorder.onerror = (_event) => {
                             capture.error = 'MediaRecorder error occurred';
                             capture.isCapturing = false;
                         };
@@ -157,10 +157,11 @@ export class AudioCaptureService {
      * Starts audio capture on the page.
      *
      * @param page - Playwright page instance
-     * @param config - Optional capture configuration
+     * @param _config - Optional capture configuration (currently unused;
+     *   recorder config is fixed at injectRecorder time)
      * @throws {Error} When capture fails to start
      */
-    async startCapture(page, config) {
+    async startCapture(page, _config) {
         const result = await page.evaluate(/* istanbul ignore next */ () => {
             const capture = window.strudelAudioCapture;
             if (!capture) {

package/dist/services/GeminiService.js

@@ -549,7 +549,7 @@ Focus on:
         return prompt;
     }
     buildVariationPrompt(pattern, style) {
-        let prompt = `You are an expert in Strudel.cc live coding music.
+        const prompt = `You are an expert in Strudel.cc live coding music.
 
 Given this pattern:
 \`\`\`javascript

package/dist/services/MIDIExportService.js

@@ -206,7 +206,7 @@ export class MIDIExportService {
             }
             // Handle sub-patterns in brackets [c4 e4]
             if (part.startsWith('[')) {
-                const subContent = part.replace(/[\[\]]/g, '');
+                const subContent = part.replace(/[[\]]/g, '');
                 const subParts = subContent.split(/[\s,]+/);
                 subParts.forEach(subPart => {
                     const midi = asMidiNumbers
@@ -271,7 +271,7 @@ export class MIDIExportService {
     parseInlineNotes(pattern) {
         const notes = [];
         // Find quoted strings that look like note sequences
-        const quotedRegex = /["'`]([a-g][#b]?\d[\s,a-g#b0-9~\-\[\]]+)["'`]/gi;
+        const quotedRegex = /["'`]([a-g][#b]?\d[\s,a-g#b0-9~\-[\]]+)["'`]/gi;
         let match;
         while ((match = quotedRegex.exec(pattern)) !== null) {
             const noteSequence = match[1];
@@ -300,8 +300,6 @@ export class MIDIExportService {
         // Create track
         const track = midi.addTrack();
         track.name = trackName;
-        // Calculate PPQ (pulses per quarter note) from the header
-        const ppq = midi.header.ppq;
         // Add notes to track
         notes.forEach(noteEvent => {
             // Only add notes within the specified bar range

package/dist/services/SessionManager.js

@@ -47,11 +47,13 @@ export class SessionManager {
     /**
      * Creates a new isolated Strudel session
      * @param id - Unique session identifier
-     * @param headless - Override headless mode for this session (unused, uses shared browser)
+     * @param _headless - Override headless mode for this session (currently a
+     *   no-op; sessions share the constructor's browser instance). Kept in the
+     *   signature for API stability until multi-session work in #108 lands.
      * @returns Initialized StrudelController for the session
      * @throws {Error} When max sessions limit reached or session ID already exists
      */
-    async createSession(id, headless) {
+    async createSession(id, _headless) {
         // Validate session ID
         if (!id || typeof id !== 'string') {
             throw new Error('Session ID must be a non-empty string');

package/dist/services/StrudelEngine.js

@@ -15,6 +15,7 @@
 import * as strudelCore from '@strudel/core';
 import { mini } from '@strudel/mini';
 import { transpiler } from '@strudel/transpiler';
+import { calculateComplexity, checkCommonIssues, extractBpm, extractFunctionsUsed, getSuggestionsForError, parseErrorLocation, } from './StrudelEngineHelpers.js';
 /**
  * Local Strudel pattern engine - executes patterns without browser.
  * Replaces fragile browser automation for pattern validation and analysis.
@@ -76,8 +77,7 @@ export class StrudelEngine {
             };
         }
         catch (error) {
-            // Parse error location from Strudel/acorn errors
-            const location = this.parseErrorLocation(error);
+            const location = parseErrorLocation(error);
             return {
                 success: false,
                 error: error.message || 'Transpilation failed',
@@ -112,24 +112,21 @@ export class StrudelEngine {
                 suggestions: ['Add a pattern like: s("bd hh sd hh")'],
             };
         }
-        // Try transpilation first - catches syntax errors
         const transpileResult = this.transpile(code);
         if (!transpileResult.success) {
             return {
                 valid: false,
                 errors: [transpileResult.error || 'Syntax error'],
                 warnings,
-                suggestions: this.getSuggestionsForError(transpileResult.error || ''),
+                suggestions: getSuggestionsForError(transpileResult.error || ''),
                 errorLocation: transpileResult.errorLocation
                     ? { line: transpileResult.errorLocation.line, column: transpileResult.errorLocation.column }
                     : undefined,
             };
         }
-        // Try to evaluate the pattern to catch runtime errors
         try {
             const fn = new Function(...Object.keys(this.context), transpileResult.transpiledCode);
             const pattern = fn(...Object.values(this.context));
-            // Verify it's a valid pattern
             if (!pattern || typeof pattern.queryArc !== 'function') {
                 errors.push('Code did not produce a valid pattern');
                 suggestions.push('Ensure your code returns a pattern (e.g., s("bd"), note("c3"), stack(...))');
@@ -137,10 +134,9 @@ export class StrudelEngine {
         }
         catch (error) {
             errors.push(`Runtime error: ${error.message}`);
-            suggestions.push(...this.getSuggestionsForError(error.message));
+            suggestions.push(...getSuggestionsForError(error.message));
         }
-        // Check for common issues
-        this.checkCommonIssues(code, warnings, suggestions);
+        checkCommonIssues(code, warnings, suggestions);
         return {
             valid: errors.length === 0,
             errors,
@@ -221,36 +217,22 @@ export class StrudelEngine {
      * ```
      */
     analyzePattern(code) {
-        // Default metadata
         const metadata = {
             eventsPerCycle: 0,
             uniqueValues: [],
-            usesSound: false,
-            usesNote: false,
-            isStack: false,
-            functionsUsed: [],
+            usesSound: /\bs\s*\(/.test(code) || /\bsound\s*\(/.test(code),
+            usesNote: /\bnote\s*\(/.test(code),
+            isStack: /\bstack\s*\(/.test(code),
+            functionsUsed: extractFunctionsUsed(code),
             complexity: 0,
         };
-        // Extract BPM from setcpm
-        const bpmMatch = code.match(/setcpm\s*\(\s*(\d+(?:\.\d+)?)\s*\)/);
-        if (bpmMatch) {
-            metadata.bpm = parseFloat(bpmMatch[1]);
+        const bpm = extractBpm(code);
+        if (bpm !== undefined) {
+            metadata.bpm = bpm;
         }
-        // Analyze code structure
-        metadata.usesSound = /\bs\s*\(/.test(code) || /\bsound\s*\(/.test(code);
-        metadata.usesNote = /\bnote\s*\(/.test(code);
-        metadata.isStack = /\bstack\s*\(/.test(code);
-        // Extract function names used
-        const funcMatches = code.match(/\b([a-z][a-zA-Z0-9_]*)\s*\(/g);
-        if (funcMatches) {
-            const funcNames = funcMatches.map(m => m.replace(/\s*\($/, ''));
-            metadata.functionsUsed = [...new Set(funcNames)];
-        }
-        // Try to query events for detailed analysis
         try {
             const events = this.queryEvents(code, 0, 1);
             metadata.eventsPerCycle = events.length;
-            // Extract unique values
             const values = events.map(e => {
                 if (typeof e.value === 'object' && e.value !== null) {
                     return e.value.s || e.value.note || e.value.n || JSON.stringify(e.value);
@@ -258,21 +240,20 @@ export class StrudelEngine {
                 return String(e.value);
             });
             metadata.uniqueValues = [...new Set(values)];
-            // Calculate complexity based on various factors
-            const complexityFactors = [
-                Math.min(events.length / 16, 1) * 0.3, // Event density
-                Math.min(metadata.uniqueValues.length / 8, 1) * 0.2, // Variety
-                Math.min(metadata.functionsUsed.length / 10, 1) * 0.3, // Function complexity
-                metadata.isStack ? 0.1 : 0, // Layering
-                (code.length / 500) * 0.1, // Code length
-            ];
-            metadata.complexity = Math.min(complexityFactors.reduce((a, b) => a + b, 0), 1);
+            metadata.complexity = calculateComplexity({
+                uniqueValues: metadata.uniqueValues,
+                functionsUsed: metadata.functionsUsed,
+                isStack: metadata.isStack,
+                codeLength: code.length,
+            }, events.length);
         }
         catch {
-            // If we can't query events, estimate from code
-            metadata.complexity = Math.min((metadata.functionsUsed.length / 10) * 0.5 +
-                (code.length / 500) * 0.3 +
-                (metadata.isStack ? 0.2 : 0), 1);
+            metadata.complexity = calculateComplexity({
+                uniqueValues: metadata.uniqueValues,
+                functionsUsed: metadata.functionsUsed,
+                isStack: metadata.isStack,
+                codeLength: code.length,
+            });
         }
         return metadata;
     }
@@ -288,87 +269,4 @@ export class StrudelEngine {
             context: hap.context,
         };
     }
-    /**
-     * Parse error location from various error formats
-     */
-    parseErrorLocation(error) {
-        // Acorn-style location
-        if (error.loc) {
-            return {
-                line: error.loc.line,
-                column: error.loc.column,
-                offset: error.pos || 0,
-            };
-        }
-        // Strudel mini SyntaxError
-        if (error.location) {
-            return {
-                line: error.location.start.line,
-                column: error.location.start.column,
-                offset: error.location.start.offset,
-            };
-        }
-        // Try to parse from message
-        const lineColMatch = error.message?.match(/line\s*(\d+).*column\s*(\d+)/i);
-        if (lineColMatch) {
-            return {
-                line: parseInt(lineColMatch[1]),
-                column: parseInt(lineColMatch[2]),
-                offset: 0,
-            };
-        }
-        return undefined;
-    }
-    /**
-     * Get suggestions based on error message
-     */
-    getSuggestionsForError(error) {
-        const suggestions = [];
-        const lowerError = error.toLowerCase();
-        if (lowerError.includes('unexpected token')) {
-            suggestions.push('Check for missing quotes, parentheses, or brackets');
-            suggestions.push('Ensure all function calls have matching ()');
-        }
-        if (lowerError.includes('is not defined')) {
-            const match = error.match(/(\w+) is not defined/);
-            if (match) {
-                suggestions.push(`"${match[1]}" is not a known Strudel function`);
-                suggestions.push('Check spelling or use a valid function like s(), note(), stack()');
-            }
-        }
-        if (lowerError.includes('not a function')) {
-            suggestions.push('Check that you are calling methods on a pattern object');
-        }
-        if (lowerError.includes('unexpected end')) {
-            suggestions.push('Pattern appears incomplete - check for missing closing brackets');
-        }
-        return suggestions;
-    }
-    /**
-     * Check for common issues in pattern code
-     */
-    checkCommonIssues(code, warnings, suggestions) {
-        // Check for high gain values
-        const gainMatches = code.match(/\.gain\s*\(\s*(\d+(?:\.\d+)?)\s*\)/g);
-        if (gainMatches) {
-            for (const match of gainMatches) {
-                const value = parseFloat(match.match(/(\d+(?:\.\d+)?)/)?.[1] || '0');
-                if (value > 2) {
-                    warnings.push(`High gain value (${value}) may cause distortion`);
-                }
-                if (value > 5) {
-                    warnings.push(`Dangerous gain value (${value}) - consider reducing to 2 or less`);
-                }
-            }
-        }
-        // Check for missing sound-producing functions
-        if (!/\b(s|sound|note|n)\s*\(/.test(code) && !/\bstack\s*\(/.test(code)) {
-            warnings.push('Pattern may not produce sound - no s(), note(), or stack() found');
-            suggestions.push('Add a sound source like s("bd") or note("c3")');
-        }
-        // Suggest tempo if not set
-        if (!/setcpm|setbpm|cpm|bpm/.test(code)) {
-            suggestions.push('Consider setting tempo with setcpm(120)');
-        }
-    }
 }

package/dist/services/StrudelEngineHelpers.js

@@ -0,0 +1,151 @@
+/**
+ * Pure helpers extracted from StrudelEngine for direct unit testing.
+ *
+ * StrudelEngine.ts imports @strudel/* packages, which ship as ESM and
+ * fight Jest's CJS loader (see #107). Helpers that don't touch @strudel
+ * — string parsing, regex extraction, scoring — live here so they can
+ * be tested without the ESM workaround dance.
+ *
+ * @module services/StrudelEngineHelpers
+ */
+/**
+ * Parse an error location from the assortment of shapes the Strudel
+ * stack produces:
+ *   - acorn:  { loc: { line, column }, pos }
+ *   - mini:   { location: { start: { line, column, offset } } }
+ *   - other:  message string containing "line N ... column N"
+ * Returns undefined if no shape matches — callers should treat that
+ * as "location unknown" rather than an error.
+ */
+export function parseErrorLocation(error) {
+    if (error?.loc) {
+        return {
+            line: error.loc.line,
+            column: error.loc.column,
+            offset: error.pos ?? 0,
+        };
+    }
+    if (error?.location?.start) {
+        return {
+            line: error.location.start.line,
+            column: error.location.start.column,
+            offset: error.location.start.offset,
+        };
+    }
+    const lineColMatch = error?.message?.match(/line\s*(\d+).*column\s*(\d+)/i);
+    if (lineColMatch) {
+        return {
+            line: parseInt(lineColMatch[1], 10),
+            column: parseInt(lineColMatch[2], 10),
+            offset: 0,
+        };
+    }
+    return undefined;
+}
+/**
+ * Produce actionable suggestions for an error message. Recognises four
+ * common error families: unexpected token, undefined name, not-a-fn,
+ * unexpected end of input. Returns an empty array for anything else
+ * (callers should still surface the raw error).
+ */
+export function getSuggestionsForError(error) {
+    const suggestions = [];
+    const lowerError = error.toLowerCase();
+    if (lowerError.includes('unexpected token')) {
+        suggestions.push('Check for missing quotes, parentheses, or brackets');
+        suggestions.push('Ensure all function calls have matching ()');
+    }
+    if (lowerError.includes('is not defined')) {
+        const match = error.match(/(\w+) is not defined/);
+        if (match) {
+            suggestions.push(`"${match[1]}" is not a known Strudel function`);
+            suggestions.push('Check spelling or use a valid function like s(), note(), stack()');
+        }
+    }
+    if (lowerError.includes('not a function')) {
+        suggestions.push('Check that you are calling methods on a pattern object');
+    }
+    if (lowerError.includes('unexpected end')) {
+        suggestions.push('Pattern appears incomplete - check for missing closing brackets');
+    }
+    return suggestions;
+}
+/**
+ * Append warnings/suggestions for common pattern-code issues:
+ *   - gain values above safe thresholds (2.0 warn, 5.0 strong warn)
+ *   - patterns with no sound-producing call (s/sound/note/n/stack)
+ *   - patterns with no tempo set (setcpm/setbpm/cpm/bpm)
+ *
+ * Mutates the passed arrays in-place to match the calling convention
+ * in StrudelEngine.validate(). Returns nothing.
+ */
+export function checkCommonIssues(code, warnings, suggestions) {
+    const gainMatches = code.match(/\.gain\s*\(\s*(\d+(?:\.\d+)?)\s*\)/g);
+    if (gainMatches) {
+        for (const match of gainMatches) {
+            const value = parseFloat(match.match(/(\d+(?:\.\d+)?)/)?.[1] || '0');
+            if (value > 2) {
+                warnings.push(`High gain value (${value}) may cause distortion`);
+            }
+            if (value > 5) {
+                warnings.push(`Dangerous gain value (${value}) - consider reducing to 2 or less`);
+            }
+        }
+    }
+    if (!/\b(s|sound|note|n)\s*\(/.test(code) && !/\bstack\s*\(/.test(code)) {
+        warnings.push('Pattern may not produce sound - no s(), note(), or stack() found');
+        suggestions.push('Add a sound source like s("bd") or note("c3")');
+    }
+    if (!/setcpm|setbpm|cpm|bpm/.test(code)) {
+        suggestions.push('Consider setting tempo with setcpm(120)');
+    }
+}
+/**
+ * Extract BPM from a `setcpm(<number>)` call. Returns undefined when
+ * absent — Strudel's default tempo is documented elsewhere; this helper
+ * stays narrow (no fallback) so callers can distinguish "not set" from
+ * "set to default".
+ */
+export function extractBpm(code) {
+    const match = code.match(/setcpm\s*\(\s*(\d+(?:\.\d+)?)\s*\)/);
+    return match ? parseFloat(match[1]) : undefined;
+}
+/**
+ * Extract unique function-call names from pattern code. Matches the
+ * lowercase-starting identifier immediately before `(` — same heuristic
+ * Strudel patterns follow (s, note, stack, fast, ...). Returns names in
+ * first-seen order, deduplicated.
+ */
+export function extractFunctionsUsed(code) {
+    const matches = code.match(/\b([a-z][a-zA-Z0-9_]*)\s*\(/g);
+    if (!matches)
+        return [];
+    const names = matches.map(m => m.replace(/\s*\($/, ''));
+    return [...new Set(names)];
+}
+/**
+ * Score pattern complexity on a 0..1 scale. Two paths:
+ *   - with events: weighted sum across event density, value variety,
+ *     function count, stack bonus, code length
+ *   - without events (e.g. unqueryable pattern): fall back to a simpler
+ *     code-only estimate so we still return something useful
+ *
+ * Weights and caps are calibrated to keep typical patterns around 0.3–0.7
+ * with truly dense patterns reaching 1.0. Changing them shifts every
+ * downstream "complexity" report — bump cautiously.
+ */
+export function calculateComplexity(input, eventCount) {
+    if (eventCount === undefined) {
+        return Math.min((input.functionsUsed.length / 10) * 0.5 +
+            (input.codeLength / 500) * 0.3 +
+            (input.isStack ? 0.2 : 0), 1);
+    }
+    const factors = [
+        Math.min(eventCount / 16, 1) * 0.3,
+        Math.min(input.uniqueValues.length / 8, 1) * 0.2,
+        Math.min(input.functionsUsed.length / 10, 1) * 0.3,
+        input.isStack ? 0.1 : 0,
+        (input.codeLength / 500) * 0.1,
+    ];
+    return Math.min(factors.reduce((a, b) => a + b, 0), 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamzujkowski/live-coding-music-mcp",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "MCP server (unofficial, fan project) for AI-assisted live-coding music via strudel.cc. Lets Claude drive pattern generation, audio analysis, and MIDI export through the Strudel browser REPL.",
   "type": "module",
   "main": "dist/index.js",