@williamzujkowski/live-coding-music-mcp 3.0.0 → 4.1.0

package/dist/server/tools/transform.js

@@ -1,19 +1,17 @@
 /**
  * transform domain — mutate the current pattern.
  *
- * Owns (14 tools): transpose, reverse, stretch, quantize, humanize,
- * add_swing, apply_scale, generate_variation, add_effect, remove_effect,
- * set_tempo, shift_mood, set_energy, refine.
- *
- * Per the #110 audit this eventually collapses into:
- * - `transform` (op enum) — 8 tools
- * - `effect` (add/remove enum) — 2 tools
- * - `shape` (mood/energy/refine enum) — 3 tools
- * - `set_tempo` stays — high-traffic verb
- *
- * For now we keep the individual verbs and just move them out of server.ts.
+ * Owns (4 tools):
+ * - `transform` (op enum: transpose/reverse/stretch/quantize/humanize/
+ *    swing/scale/vary)
+ * - `effect` (action enum: add/remove)
+ * - `shape` (dimension enum: mood/energy/refine)
+ * - `set_tempo` — high-traffic standalone verb
  */
+import { empty, err, withStashField, withStashNotice } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { BEATS_PER_CYCLE } from '../../utils/Tempo.js';
+import { lookup } from '../../utils/TableLookup.js';
 const ENERGY_LEVELS = {
     0: { tempoAdjust: -20, roomAmount: 0.5, densityAdjust: '.slow(4)', description: 'minimal/ambient' },
     1: { tempoAdjust: -15, roomAmount: 0.4, densityAdjust: '.slow(3)', description: 'very sparse' },
@@ -43,7 +41,7 @@ function transposePattern(pattern, semitones) {
             'f#': 6, 'g': 7, 'g#': 8, 'a': 9, 'a#': 10, 'b': 11,
         };
         const currentNote = note.toLowerCase();
-        const noteValue = noteMap[currentNote] || 0;
+        const noteValue = lookup(noteMap, currentNote, 0);
         const newNoteValue = (noteValue + semitones + 12) % 12;
         const noteNames = ['c', 'c#', 'd', 'd#', 'e', 'f', 'f#', 'g', 'g#', 'a', 'a#', 'b'];
         const newOctave = parseInt(octave) + Math.floor((noteValue + semitones) / 12);
@@ -65,9 +63,9 @@ export const tools = [
             'op=stretch slows by `factor` (>1 slower, <1 faster). ' +
             'op=quantize snaps to the `grid` (e.g. "1/16"). ' +
             'op=humanize adds rand-nudge timing of `amount` (0-1). ' +
-            'op=swing applies `.swing(amount)` (alias for add_swing). ' +
-            'op=scale applies a `root`/`scale` filter to notes (alias for apply_scale). ' +
-            'op=vary returns a variation of `type` (subtle/moderate/extreme/glitch/evolving — note: this is what generate_variation does today; the name is misleading because it transforms rather than generates). ' +
+            'op=swing applies `.swing(amount)`. ' +
+            'op=scale applies a `root`/`scale` filter to notes. ' +
+            'op=vary returns a variation of `type` (subtle/moderate/extreme/glitch/evolving). ' +
             'Example: transform({ op: "transpose", semitones: 7 }). ' +
             'For effects (add/remove) use effect; for mood/energy/refine use shape; for tempo use set_tempo.',
         inputSchema: {
@@ -90,59 +88,11 @@ export const tools = [
             required: ['op'],
         },
     },
-    {
-        name: 'transpose',
-        description: '[DEPRECATED — use transform({ op: "transpose" }) instead] Transpose notes by semitones',
-        inputSchema: {
-            type: 'object',
-            properties: { semitones: { type: 'number', description: 'Semitones to transpose' }, ...SESSION_ID_PROP },
-            required: ['semitones'],
-        },
-    },
-    {
-        name: 'reverse',
-        description: '[DEPRECATED — use transform({ op: "reverse" }) instead] Reverse pattern',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'stretch',
-        description: '[DEPRECATED — use transform({ op: "stretch" }) instead] Time stretch pattern',
-        inputSchema: {
-            type: 'object',
-            properties: { factor: { type: 'number', description: 'Stretch factor' }, ...SESSION_ID_PROP },
-            required: ['factor'],
-        },
-    },
-    {
-        name: 'quantize',
-        description: '[DEPRECATED — use transform({ op: "quantize" }) instead] Quantize to grid',
-        inputSchema: {
-            type: 'object',
-            properties: { grid: { type: 'string', description: 'Grid size (e.g., "1/16")' }, ...SESSION_ID_PROP },
-            required: ['grid'],
-        },
-    },
-    {
-        name: 'humanize',
-        description: '[DEPRECATED — use transform({ op: "humanize" }) instead] Add human timing variation',
-        inputSchema: {
-            type: 'object',
-            properties: { amount: { type: 'number', description: 'Humanization amount (0-1)' }, ...SESSION_ID_PROP },
-        },
-    },
-    {
-        name: 'generate_variation',
-        description: '[DEPRECATED — use transform({ op: "vary" }) instead] Create pattern variations (mis-named today; it transforms, not generates)',
-        inputSchema: {
-            type: 'object',
-            properties: { type: { type: 'string', description: 'Variation type (subtle/moderate/extreme/glitch/evolving)' }, ...SESSION_ID_PROP },
-        },
-    },
     {
         name: 'effect',
         description: 'Add or remove a Strudel effect on the current session pattern. ' +
             'action=add appends `.<effect>(<params>)`. ' +
-            'action=remove strips the last `.<effect>(...)` call from the pattern. ' +
+            'action=remove strips EVERY `.<effect>(...)` call from the pattern, not just the last. ' +
             'Example: effect({ action: "add", effect: "lpf", params: "1000" }). ' +
             'For higher-level effect bundles (mood/energy/refine) use shape; for raw transforms use transform.',
         inputSchema: {
@@ -156,59 +106,15 @@ export const tools = [
             required: ['action', 'effect'],
         },
     },
-    {
-        name: 'add_effect',
-        description: '[DEPRECATED — use effect({ action: "add" }) instead] Add effect to pattern',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                effect: { type: 'string', description: 'Effect name' },
-                params: { type: 'string', description: 'Effect parameters' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['effect'],
-        },
-    },
-    {
-        name: 'remove_effect',
-        description: '[DEPRECATED — use effect({ action: "remove" }) instead] Remove effect',
-        inputSchema: {
-            type: 'object',
-            properties: { effect: { type: 'string', description: 'Effect to remove' }, ...SESSION_ID_PROP },
-            required: ['effect'],
-        },
-    },
     {
         name: 'set_tempo',
-        description: 'Set BPM',
+        description: 'Set BPM. Writes setcpm(bpm/4), assuming one bar of 4/4 per cycle.',
         inputSchema: {
             type: 'object',
             properties: { bpm: { type: 'number', description: 'Tempo in BPM' }, ...SESSION_ID_PROP },
             required: ['bpm'],
         },
     },
-    {
-        name: 'add_swing',
-        description: '[DEPRECATED — use transform({ op: "swing" }) instead] Add swing to pattern',
-        inputSchema: {
-            type: 'object',
-            properties: { amount: { type: 'number', description: 'Swing amount (0-1)' }, ...SESSION_ID_PROP },
-            required: ['amount'],
-        },
-    },
-    {
-        name: 'apply_scale',
-        description: '[DEPRECATED — use transform({ op: "scale" }) instead] Apply scale to notes',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                scale: { type: 'string', description: 'Scale name' },
-                root: { type: 'string', description: 'Root note' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['scale', 'root'],
-        },
-    },
     {
         name: 'shape',
         description: 'Shape the current pattern along one of three high-level dimensions. ' +
@@ -236,42 +142,6 @@ export const tools = [
             required: ['dimension'],
         },
     },
-    {
-        name: 'shift_mood',
-        description: '[DEPRECATED — use shape({ dimension: "mood" }) instead] Transform current pattern to match a different emotional mood. Moods: dark, euphoric, melancholic, aggressive, dreamy, peaceful, energetic.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                target_mood: {
-                    type: 'string',
-                    enum: ['dark', 'euphoric', 'melancholic', 'aggressive', 'dreamy', 'peaceful', 'energetic'],
-                    description: 'Target mood',
-                },
-                intensity: { type: 'number', minimum: 0, maximum: 1, description: 'How strongly to apply the mood transformation (0-1, default: 0.5)' },
-                auto_play: { type: 'boolean', description: 'Start playback after transformation (default: true)' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['target_mood'],
-        },
-    },
-    {
-        name: 'set_energy',
-        description: '[DEPRECATED — use shape({ dimension: "energy" }) instead] Adjust energy level 0-10. Auto-plays after applying.',
-        inputSchema: {
-            type: 'object',
-            properties: { level: { type: 'number', description: 'Energy level from 0 (minimal) to 10 (maximum)' }, ...SESSION_ID_PROP },
-            required: ['level'],
-        },
-    },
-    {
-        name: 'refine',
-        description: '[DEPRECATED — use shape({ dimension: "refine" }) instead] Incrementally refine current pattern: faster/slower/louder/quieter/brighter/darker/"more reverb"/drier.',
-        inputSchema: {
-            type: 'object',
-            properties: { direction: { type: 'string', description: 'Refinement direction: faster, slower, louder, quieter, brighter, darker, "more reverb", or drier' }, ...SESSION_ID_PROP },
-            required: ['direction'],
-        },
-    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
 // ---- per-op helpers (shared by transform({op}) and the deprecated aliases)
@@ -280,73 +150,139 @@ async function opTranspose(args, ctx, sid) {
         throw new Error('Semitones must be an integer');
     }
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(transposePattern(p, args.semitones), sid);
-    return `Transposed ${args.semitones} semitones`;
+    const written = await ctx.writePatternSafe(transposePattern(p, args.semitones), sid);
+    return withStashNotice(`Transposed ${args.semitones} semitones`, written);
 }
 async function opReverse(ctx, sid) {
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + '.rev', sid);
-    return 'Pattern reversed';
+    const written = await ctx.writePatternSafe(p + '.rev', sid);
+    return withStashNotice('Pattern reversed', written);
 }
 async function opStretch(args, ctx, sid) {
     InputValidator.validateGain(args.factor);
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.slow(${args.factor})`, sid);
-    return `Stretched by factor of ${args.factor}`;
+    const written = await ctx.writePatternSafe(p + `.slow(${args.factor})`, sid);
+    return withStashNotice(`Stretched by factor of ${args.factor}`, written);
 }
 async function opQuantize(args, ctx, sid) {
     InputValidator.validateStringLength(args.grid, 'grid', 50, false);
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.struct("${args.grid}")`, sid);
-    return `Quantized to ${args.grid} grid`;
+    const written = await ctx.writePatternSafe(p + `.struct("${args.grid}")`, sid);
+    return withStashNotice(`Quantized to ${args.grid} grid`, written);
 }
 async function opHumanize(args, ctx, sid) {
     if (args.amount !== undefined)
         InputValidator.validateNormalizedValue(args.amount, 'amount');
     const p = await ctx.getCurrentPatternSafe(sid);
     const amt = args.amount || 0.01;
-    await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`, sid);
-    return 'Added human timing';
+    const written = await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`, sid);
+    return withStashNotice('Added human timing', written);
 }
 async function opVary(args, ctx, sid) {
     const p = await ctx.getCurrentPatternSafe(sid);
     const varied = ctx.generator.generateVariation(p, args.type || 'subtle');
-    await ctx.writePatternSafe(varied, sid);
-    return `Added ${args.type || 'subtle'} variation`;
+    const written = await ctx.writePatternSafe(varied, sid);
+    return withStashNotice(`Added ${args.type || 'subtle'} variation`, written);
 }
 async function opSwing(args, ctx, sid) {
     InputValidator.validateNormalizedValue(args.amount, 'amount');
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.swing(${args.amount})`, sid);
-    return `Added swing: ${args.amount}`;
+    const written = await ctx.writePatternSafe(p + `.swing(${args.amount})`, sid);
+    return withStashNotice(`Added swing: ${args.amount}`, written);
 }
 async function opScale(args, ctx, sid) {
     InputValidator.validateStringLength(args.scale, 'scale', 50, false);
+    // Concatenated straight into the pattern source below, so it must be a
+    // scale name and not arbitrary code — the same reason `opEffectAdd`
+    // validates its effect name (#236). A length check is not a content
+    // check: `scale: 'minor") .gain(9) //'` closed the string literal and
+    // appended a call, which is how it got past `PatternValidator`'s
+    // dangerous-gain rule — that runs on the pattern before this is
+    // appended to it (#440).
+    //
+    // `validateScaleName` already existed and `generate.ts` already used
+    // it; this path never did.
+    InputValidator.validateScaleName(args.scale);
     InputValidator.validateRootNote(args.root);
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`, sid);
-    return `Applied ${args.root} ${args.scale} scale`;
+    const written = await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`, sid);
+    return withStashNotice(`Applied ${args.root} ${args.scale} scale`, written);
 }
 async function opEffectAdd(args, ctx, sid) {
     InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+    // Concatenated straight into the pattern source, so it must be a plain
+    // method name and not arbitrary code (#236).
+    InputValidator.validateIdentifier(args.effect, 'effect');
     if (args.params)
         InputValidator.validateStringLength(args.params, 'params', 1000, true);
     const p = await ctx.getCurrentPatternSafe(sid);
     const withEffect = args.params
         ? p + `.${args.effect}(${args.params})`
         : p + `.${args.effect}()`;
-    await ctx.writePatternSafe(withEffect, sid);
-    return `Added ${args.effect} effect`;
+    const written = await ctx.writePatternSafe(withEffect, sid);
+    return withStashNotice(`Added ${args.effect} effect`, written);
+}
+/**
+ * Removes every `.effect(...)` call from a pattern.
+ *
+ * Deliberately not a RegExp. The old implementation interpolated the
+ * caller's effect name into `new RegExp(...)`, which handed the caller
+ * regex *syntax* — `(a+)+Z` against a crafted pattern blocked the event
+ * loop for 25 seconds, and a synchronous String.replace has no timeout to
+ * break out of (#236).
+ *
+ * Scanning also fixes a correctness bug the regex had: `[^)]*` stops at
+ * the FIRST `)`, so `.lpf(add(1,2))` was left as a stray `)`. This walks
+ * balanced parentheses instead.
+ *
+ * @param pattern - Pattern source to strip
+ * @param effect - Effect name (validated as an identifier by the caller)
+ * @returns The pattern with every matching call removed
+ */
+function stripEffectCalls(pattern, effect) {
+    const needle = `.${effect}(`;
+    let out = '';
+    let cursor = 0;
+    for (;;) {
+        const start = pattern.indexOf(needle, cursor);
+        if (start === -1)
+            break;
+        // Walk to the matching close paren, respecting nesting.
+        let depth = 0;
+        let end = -1;
+        for (let i = start + needle.length - 1; i < pattern.length; i++) {
+            const ch = pattern[i];
+            if (ch === '(')
+                depth++;
+            else if (ch === ')') {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        // Unbalanced: leave the rest untouched rather than mangling it.
+        if (end === -1)
+            break;
+        out += pattern.slice(cursor, start);
+        cursor = end + 1;
+    }
+    return out + pattern.slice(cursor);
 }
 async function opEffectRemove(args, ctx, sid) {
     InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+    // Must be a plain identifier: it is matched literally below, and was
+    // previously interpolated into a RegExp (#236).
+    InputValidator.validateIdentifier(args.effect, 'effect');
     const p = await ctx.getCurrentPatternSafe(sid);
-    const regex = new RegExp(`\\.${args.effect}\\([^)]*\\)`, 'g');
-    const stripped = p.replace(regex, '');
+    const stripped = stripEffectCalls(p, args.effect);
+    // The strip ran and matched nothing. That is a valid-empty result,
+    // not a failure and not a plain success (#288).
     if (stripped === p)
-        return `No ${args.effect} effect found to remove`;
-    await ctx.writePatternSafe(stripped, sid);
-    return `Removed ${args.effect} effect`;
+        return empty(`No ${args.effect} effect found to remove`);
+    const written = await ctx.writePatternSafe(stripped, sid);
+    return withStashNotice(`Removed ${args.effect} effect`, written);
 }
 export async function execute(name, args, ctx) {
     const sid = args?.session_id;
@@ -369,15 +305,6 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid op: ${op}. Must be one of: transpose, reverse, stretch, quantize, humanize, swing, scale, vary`);
             }
         }
-        // Deprecated aliases — forward to per-op helpers.
-        case 'transpose': return await opTranspose(args, ctx, sid);
-        case 'reverse': return await opReverse(ctx, sid);
-        case 'stretch': return await opStretch(args, ctx, sid);
-        case 'quantize': return await opQuantize(args, ctx, sid);
-        case 'humanize': return await opHumanize(args, ctx, sid);
-        case 'generate_variation': return await opVary(args, ctx, sid);
-        case 'add_swing': return await opSwing(args, ctx, sid);
-        case 'apply_scale': return await opScale(args, ctx, sid);
         case 'effect': {
             const a = args?.action;
             if (a !== 'add' && a !== 'remove') {
@@ -387,13 +314,15 @@ export async function execute(name, args, ctx) {
                 ? await opEffectAdd(args, ctx, sid)
                 : await opEffectRemove(args, ctx, sid);
         }
-        case 'add_effect': return await opEffectAdd(args, ctx, sid);
-        case 'remove_effect': return await opEffectRemove(args, ctx, sid);
         case 'set_tempo': {
             InputValidator.validateBPM(args.bpm);
             const p = await ctx.getCurrentPatternSafe(sid);
-            await ctx.writePatternSafe(`setcpm(${args.bpm})\n${p}`, sid);
-            return `Set tempo to ${args.bpm} BPM`;
+            // `setcpm` is CYCLES per minute, and the Strudel convention this
+            // project follows is one bar of four beats per cycle — so the
+            // divisor is what makes `set_tempo({ bpm: 130 })` produce 130 BPM
+            // rather than 520 (#395).
+            const written = await ctx.writePatternSafe(`setcpm(${String(args.bpm)}/${String(BEATS_PER_CYCLE)})\n${p}`, sid);
+            return withStashNotice(`Set tempo to ${args.bpm} BPM`, written);
         }
         case 'shape': {
             const dim = args?.dimension;
@@ -405,21 +334,30 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid dimension: ${dim}. Must be one of: mood, energy, refine`);
             }
         }
-        case 'shift_mood': return await shiftMood(args, ctx, sid);
-        case 'set_energy': return await setEnergyLevel(args.level, ctx, sid);
-        case 'refine': return await refinePattern(args.direction, ctx, sid);
         default:
             throw new Error(`transform module does not handle tool: ${name}`);
     }
 }
 async function shiftMood(args, ctx, sid) {
     const mood = args.target_mood?.toLowerCase()?.trim();
-    const profile = MOOD_PROFILES[mood];
+    // hasOwn, not a bare index: MOOD_PROFILES is a plain object literal,
+    // so MOOD_PROFILES['constructor'] returned Object — truthy, so the
+    // `if (!profile)` guard below never fired. The result was
+    // s("bd*4").slow(NaN).lpf(NaN).room(NaN).gain(NaN) written into the
+    // editor and reported as success:true (#308).
+    const profile = typeof mood === 'string' && Object.hasOwn(MOOD_PROFILES, mood)
+        ? MOOD_PROFILES[mood]
+        : undefined;
     if (!profile) {
-        return {
-            success: false,
-            error: `Unknown mood: ${args.target_mood}. Valid moods: ${Object.keys(MOOD_PROFILES).join(', ')}.`,
-        };
+        // `err('validation', ...)`, not a failure-shaped object.
+        //
+        // The dispatcher categorises those by running the MESSAGE through
+        // the string matcher, and "Valid moods: ..." contains none of the
+        // phrases it looks for — so a caller's typo landed in `internal`,
+        // which is the non-retryable fall-through for a fault that is not
+        // the caller's (#453). This is the audit #382 describes, at four
+        // sites it did not reach.
+        return err('validation', `Unknown mood: ${args.target_mood}. Valid moods: ${Object.keys(MOOD_PROFILES).join(', ')}.`);
     }
     const pattern = await ctx.getCurrentPatternSafe(sid);
     if (!pattern || pattern.trim().length === 0) {
@@ -463,11 +401,11 @@ async function shiftMood(args, ctx, sid) {
         result += `.gain(${g.toFixed(2)})`;
         applied.push(`gain ${profile.gainMod > 0 ? '+' : ''}${Math.round(profile.gainMod * 100 * intensity)}%`);
     }
-    await ctx.writePatternSafe(result, sid);
+    const written = await ctx.writePatternSafe(result, sid);
     if (args.auto_play !== false && (sid || ctx.isInitialized())) {
         await ctx.getController(sid).play();
     }
-    return { success: true, target_mood: mood, intensity, applied_effects: applied };
+    return withStashField({ success: true, target_mood: mood, intensity, applied_effects: applied }, written);
 }
 async function setEnergyLevel(level, ctx, sid) {
     if (level < 0 || level > 10 || !Number.isInteger(level)) {
@@ -482,10 +420,10 @@ async function setEnergyLevel(level, ctx, sid) {
     if (config.densityAdjust)
         result += config.densityAdjust;
     result += `.room(${config.roomAmount})`;
-    await ctx.writePatternSafe(result, sid);
+    const written = await ctx.writePatternSafe(result, sid);
     if (sid || ctx.isInitialized())
         await ctx.getController(sid).play();
-    return { success: true, level, description: config.description };
+    return withStashField({ success: true, level, description: config.description }, written);
 }
 async function refinePattern(direction, ctx, sid) {
     const pattern = await ctx.getCurrentPatternSafe(sid);
@@ -520,14 +458,13 @@ async function refinePattern(direction, ctx, sid) {
             modification = '.room(0.1)';
             break;
         default:
-            return {
-                success: false,
-                error: `Unknown refinement direction: ${direction}. Supported: faster, slower, louder, quieter, brighter, darker, "more reverb", drier.`,
-            };
+            // See the mood branch above: the caller's argument, categorised
+            // `validation` rather than `internal` (#453).
+            return err('validation', `Unknown refinement direction: ${direction}. Supported: faster, slower, louder, quieter, brighter, darker, "more reverb", drier.`);
     }
-    await ctx.writePatternSafe(pattern + modification, sid);
+    const written = await ctx.writePatternSafe(pattern + modification, sid);
     if (sid || ctx.isInitialized())
         await ctx.getController(sid).play();
-    return { success: true, direction: dir, applied: modification };
+    return withStashField({ success: true, direction: dir, applied: modification }, written);
 }
 export const transformModule = { tools, toolNames, execute };