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

package/dist/server/tools/editor.js

@@ -1,14 +1,13 @@
 /**
  * editor domain — pattern editing in the CodeMirror editor.
  *
- * Owns one consolidated mutation tool (`edit_pattern(mode)`) plus
- * `get_pattern` (kept separate, hot read path) and five deprecated
- * aliases (write/append/insert/replace/clear) per #120 / #148.
- *
- * Aliases forward to `edit_pattern` and will be removed in a future
- * release per the deprecation policy.
+ * Owns one consolidated mutation tool (`edit_pattern(mode)`) with
+ * write/append/insert/replace/clear modes, plus `get_pattern` (kept
+ * separate — hot read path).
  */
+import { empty, ok, withStashField } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { ValidationError } from '../../utils/CategorisedError.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -22,7 +21,8 @@ export const tools = [
             'mode=write replaces the editor contents (default; mirrors the old write tool exactly, including optional pattern validation and auto_play). ' +
             'mode=append concatenates `code` after the current pattern with a newline. ' +
             'mode=insert places `code` at the given line `position`. ' +
-            'mode=replace runs a single string-replace from `search` to `replace`. ' +
+            'mode=replace substitutes `search` with `replace` — the first occurrence only, unless replace_all is true. ' +
+            'The response reports how many occurrences matched, were replaced, and remain. ' +
             'mode=clear empties the editor. ' +
             'Example: edit_pattern({ mode: "write", pattern: "s(\\"bd\\")", auto_play: true }). ' +
             'For reading the editor without mutating it use get_pattern; for the on-disk pattern catalog use pattern_store.',
@@ -36,9 +36,14 @@ export const tools = [
                 },
                 pattern: { type: 'string', description: 'Pattern code (mode=write)' },
                 code: { type: 'string', description: 'Code to append/insert (mode=append/insert)' },
-                position: { type: 'number', description: 'Line number (mode=insert)' },
+                position: {
+                    type: 'number',
+                    description: 'mode=insert: 0-indexed line to insert BEFORE. 0 puts the code at the top; '
+                        + 'a value equal to the line count appends. Out of range is an error, not an append.',
+                },
                 search: { type: 'string', description: 'Text to replace (mode=replace)' },
                 replace: { type: 'string', description: 'Replacement text (mode=replace)' },
+                replace_all: { type: 'boolean', description: 'mode=replace: replace every occurrence instead of just the first (default false)' },
                 auto_play: { type: 'boolean', description: 'Start playback after write (mode=write only, default: false)' },
                 validate: { type: 'boolean', description: 'Validate pattern before write (mode=write only, default: true)' },
                 ...SESSION_ID_PROP,
@@ -50,60 +55,6 @@ export const tools = [
         description: 'Get current pattern code',
         inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
     },
-    {
-        name: 'write',
-        description: '[DEPRECATED — use edit_pattern({ mode: "write" }) instead] Write pattern to editor with optional auto-play and validation',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                pattern: { type: 'string', description: 'Pattern code' },
-                auto_play: { type: 'boolean', description: 'Start playback immediately after writing (default: false)' },
-                validate: { type: 'boolean', description: 'Validate pattern before writing (default: true)' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['pattern'],
-        },
-    },
-    {
-        name: 'append',
-        description: '[DEPRECATED — use edit_pattern({ mode: "append" }) instead] Append code to current pattern',
-        inputSchema: {
-            type: 'object',
-            properties: { code: { type: 'string', description: 'Code to append' }, ...SESSION_ID_PROP },
-            required: ['code'],
-        },
-    },
-    {
-        name: 'insert',
-        description: '[DEPRECATED — use edit_pattern({ mode: "insert" }) instead] Insert code at specific line',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                position: { type: 'number', description: 'Line number' },
-                code: { type: 'string', description: 'Code to insert' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['position', 'code'],
-        },
-    },
-    {
-        name: 'replace',
-        description: '[DEPRECATED — use edit_pattern({ mode: "replace" }) instead] Replace pattern section',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                search: { type: 'string', description: 'Text to replace' },
-                replace: { type: 'string', description: 'Replacement text' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['search', 'replace'],
-        },
-    },
-    {
-        name: 'clear',
-        description: '[DEPRECATED — use edit_pattern({ mode: "clear" }) instead] Clear the editor',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
 async function doWrite(args, ctx, sid) {
@@ -141,20 +92,66 @@ async function doAppend(args, ctx, sid) {
     return await ctx.writePatternSafe(current + '\n' + args.code, sid);
 }
 async function doInsert(args, ctx, sid) {
-    InputValidator.validatePositiveInteger(args.position, 'position');
     InputValidator.validateStringLength(args.code, 'code', 10000, true);
     const lines = (await ctx.getCurrentPatternSafe(sid)).split('\n');
-    lines.splice(args.position, 0, args.code);
+    // 0-indexed, and 0 is a legal position.
+    //
+    // `validatePositiveInteger` rejected 0 while the `splice` below is
+    // 0-indexed, so inserting at the TOP of a pattern was impossible
+    // through this tool — and `StrudelController.insertAtLine`, which does
+    // the same job, documents the parameter as 0-indexed and permits 0.
+    //
+    // The other end was unguarded: `position: 9999` on a three-line
+    // pattern passed validation and `splice` silently appended, where
+    // `insertAtLine` throws. Now it matches that contract exactly
+    // (#442), so the two ways of doing this cannot disagree.
+    const position = args.position;
+    if (!Number.isInteger(position) || position < 0 || position > lines.length) {
+        throw new ValidationError(`Invalid position: ${String(position)}. Must be an integer between 0 and ${String(lines.length)} ` +
+            `(0 inserts before the first line, ${String(lines.length)} appends).`);
+    }
+    lines.splice(position, 0, args.code);
     return await ctx.writePatternSafe(lines.join('\n'), sid);
 }
 async function doReplace(args, ctx, sid) {
     InputValidator.validateStringLength(args.search, 'search', 1000, true);
     InputValidator.validateStringLength(args.replace, 'replace', 10000, true);
+    const search = args.search ?? '';
+    if (search.length === 0) {
+        throw new Error('Invalid search: must be a non-empty string.');
+    }
     const pattern = await ctx.getCurrentPatternSafe(sid);
+    // Literal string operations throughout — never a RegExp built from
+    // `search`. Interpolating caller text into a pattern is how #236
+    // happened: `(a+)+Z` against a crafted subject blocked the event loop
+    // for 25 seconds.
+    const matches = pattern.split(search).length - 1;
     // Escape $ in replacement to prevent special sequence injection ($&, $1, $', etc.)
     const safeReplacement = args.replace.replace(/\$/g, '$$$$');
-    const replaced = pattern.replace(args.search, safeReplacement);
-    return await ctx.writePatternSafe(replaced, sid);
+    const replaceAll = args.replace_all === true;
+    const updated = replaceAll
+        ? pattern.replaceAll(search, safeReplacement)
+        : pattern.replace(search, safeReplacement);
+    const replaced = replaceAll ? matches : Math.min(matches, 1);
+    const remaining = matches - replaced;
+    const written = await ctx.writePatternSafe(updated, sid);
+    // Counts are reported under BOTH settings. Previously a caller had no
+    // way to learn that other occurrences survived — and these callers are
+    // LLM agents, which do not reliably re-read the pattern to check (#243).
+    // Zero matches is a valid-empty: the search ran and found nothing.
+    // Wrapped in a plain ok() it was indistinguishable from a replace
+    // that actually changed the pattern (#288).
+    const wrap = matches === 0 ? empty : ok;
+    return wrap(withStashField({
+        success: true,
+        message: matches === 0
+            ? `No occurrences of ${JSON.stringify(search)} found`
+            : `Replaced ${String(replaced)} of ${String(matches)} occurrence(s)` +
+                (remaining > 0 ? `; ${String(remaining)} remain. Pass replace_all: true to replace them all.` : ''),
+        replaced,
+        remaining,
+        matches,
+    }, written));
 }
 async function doClear(ctx, sid) {
     return await ctx.writePatternSafe('', sid);
@@ -177,12 +174,6 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid mode: ${mode}. Must be one of: write, append, insert, replace, clear`);
             }
         }
-        // Deprecated aliases — forward to consolidated handler.
-        case 'write': return await doWrite(args, ctx, sid);
-        case 'append': return await doAppend(args, ctx, sid);
-        case 'insert': return await doInsert(args, ctx, sid);
-        case 'replace': return await doReplace(args, ctx, sid);
-        case 'clear': return await doClear(ctx, sid);
         case 'get_pattern':
             return await ctx.getCurrentPatternSafe(sid);
         default:

package/dist/server/tools/generate.js

@@ -1,18 +1,17 @@
 /**
  * generate domain — pattern and music-theory generation (no browser needed).
  *
- * Owns (9 tools):
- *   generate_pattern, generate_drums, generate_bassline, generate_melody,
- *   generate_fill, generate_scale, generate_chord_progression,
- *   generate_euclidean, generate_polyrhythm
+ * Owns (3 tools):
+ *   generate_part(role)   — drums/bass/melody/fill layers
+ *   music_theory(query)   — scale notes, chord progressions
+ *   generate_rhythm(type) — euclidean / polyrhythm patterns
  *
- * `compose` stays in server.ts for now — it orchestrates init + generate
- * + play + optional AI feedback and pairs with ai.ts when that extraction
- * happens. Per the #110 audit, compose eventually absorbs generate_pattern
- * and the four generate_* drums/bass/melody/fill tools collapse into
- * `generate_part(role)`, while scale+chord_prog become `music_theory`.
+ * Full-composition generation lives in `compose` (compose.ts), which
+ * orchestrates init + generate + play + optional AI feedback.
  */
+import { withStashNotice } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { BASS_STYLES, DRUM_STYLES, resolveBassStyle, resolveDrumStyle } from '../../services/StyleRegistry.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -20,21 +19,6 @@ const SESSION_ID_PROP = {
     },
 };
 export const tools = [
-    {
-        name: 'generate_pattern',
-        description: '[DEPRECATED — use compose instead, which auto-inits and returns richer metadata] Generate complete pattern from style with optional auto-play.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                style: { type: 'string', description: 'Music style (techno/house/dnb/ambient/etc)' },
-                key: { type: 'string', description: 'Musical key' },
-                bpm: { type: 'number', description: 'Tempo in BPM' },
-                auto_play: { type: 'boolean', description: 'Start playback immediately (default: false)' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['style'],
-        },
-    },
     {
         name: 'generate_part',
         description: 'Generate a single instrumental layer and append it to the current session pattern. ' +
@@ -60,51 +44,11 @@ export const tools = [
             required: ['role'],
         },
     },
-    {
-        name: 'generate_drums',
-        description: '[DEPRECATED — use generate_part({ role: "drums" }) instead] Generate drum pattern',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                style: { type: 'string', description: 'Drum style' },
-                complexity: { type: 'number', description: 'Complexity (0-1)' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['style'],
-        },
-    },
-    {
-        name: 'generate_bassline',
-        description: '[DEPRECATED — use generate_part({ role: "bass" }) instead] Generate bassline',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Musical key' },
-                style: { type: 'string', description: 'Bass style' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['key', 'style'],
-        },
-    },
-    {
-        name: 'generate_melody',
-        description: '[DEPRECATED — use generate_part({ role: "melody" }) instead] Generate melody from scale',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                scale: { type: 'string', description: 'Scale name' },
-                root: { type: 'string', description: 'Root note' },
-                length: { type: 'number', description: 'Number of notes' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['scale', 'root'],
-        },
-    },
     {
         name: 'music_theory',
         description: 'Music-theory queries. ' +
             'query=scale returns the notes of a scale (e.g. "C major scale: C, D, E, F, G, A, B"). ' +
-            'query=chord_progression returns a chord progression for the key/style AND writes the resulting chord pattern into the current session (matches the pre-consolidation behaviour of generate_chord_progression). ' +
+            'query=chord_progression returns a chord progression for the key/style AND writes the resulting chord pattern into the current session. ' +
             'Example: music_theory({ query: "scale", root: "C", scale: "major" }). ' +
             'For pattern generation (drums/bass/melody) use generate_part; for rhythmic patterns use generate_rhythm.',
         inputSchema: {
@@ -120,31 +64,6 @@ export const tools = [
             required: ['query'],
         },
     },
-    {
-        name: 'generate_scale',
-        description: '[DEPRECATED — use music_theory({ query: "scale" }) instead] Generate scale notes',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                root: { type: 'string', description: 'Root note' },
-                scale: { type: 'string', description: 'Scale type' },
-            },
-            required: ['root', 'scale'],
-        },
-    },
-    {
-        name: 'generate_chord_progression',
-        description: '[DEPRECATED — use music_theory({ query: "chord_progression" }) instead] Generate chord progression',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Key' },
-                style: { type: 'string', description: 'Style (pop/jazz/blues/etc)' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['key', 'style'],
-        },
-    },
     {
         name: 'generate_rhythm',
         description: 'Generate a rhythmic pattern and append it to the current session. ' +
@@ -166,52 +85,19 @@ export const tools = [
             required: ['type'],
         },
     },
-    {
-        name: 'generate_euclidean',
-        description: '[DEPRECATED — use generate_rhythm({ type: "euclidean" }) instead] Generate Euclidean rhythm',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hits: { type: 'number', description: 'Number of hits' },
-                steps: { type: 'number', description: 'Total steps' },
-                sound: { type: 'string', description: 'Sound to use' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['hits', 'steps'],
-        },
-    },
-    {
-        name: 'generate_polyrhythm',
-        description: '[DEPRECATED — use generate_rhythm({ type: "polyrhythm" }) instead] Generate polyrhythm',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                sounds: { type: 'array', items: { type: 'string' }, description: 'Sounds to use' },
-                patterns: { type: 'array', items: { type: 'number' }, description: 'Pattern numbers' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['sounds', 'patterns'],
-        },
-    },
-    {
-        name: 'generate_fill',
-        description: '[DEPRECATED — use generate_part({ role: "fill" }) instead] Generate drum fill',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                style: { type: 'string', description: 'Fill style' },
-                bars: { type: 'number', description: 'Number of bars' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['style'],
-        },
-    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
+/**
+ * Appends generated material to the current pattern and writes it back.
+ *
+ * @returns Whatever `writePatternSafe` returned — callers must pass it
+ *   to `withStashNotice` rather than discard it, because a write with
+ *   no browser up is a stash, not a write (#285).
+ */
 async function appendOrSet(generated, ctx, sessionId) {
     const current = await ctx.getCurrentPatternSafe(sessionId);
     const combined = current ? current + '\n' + generated : generated;
-    await ctx.writePatternSafe(combined, sessionId);
+    return await ctx.writePatternSafe(combined, sessionId);
 }
 function doScale(args, ctx) {
     InputValidator.validateRootNote(args.root);
@@ -224,38 +110,52 @@ async function doChordProgression(args, ctx, sid) {
     InputValidator.validateChordStyle(args.style);
     const progression = ctx.theory.generateChordProgression(args.key, args.style);
     const chordPattern = ctx.generator.generateChords(progression);
-    await appendOrSet(chordPattern, ctx, sid);
-    return `Generated ${args.style} progression in ${args.key}: ${progression}`;
+    const written = await appendOrSet(chordPattern, ctx, sid);
+    return withStashNotice(`Generated ${args.style} progression in ${args.key}: ${progression}`, written);
 }
 async function doEuclidean(args, ctx, sid) {
     InputValidator.validateEuclidean(args.hits, args.steps);
     if (args.sound)
         InputValidator.validateStringLength(args.sound, 'sound', 100, false);
     const euclidean = ctx.generator.generateEuclideanPattern(args.hits, args.steps, args.sound || 'bd');
-    await appendOrSet(euclidean, ctx, sid);
-    return `Generated Euclidean rhythm (${args.hits}/${args.steps})`;
+    const written = await appendOrSet(euclidean, ctx, sid);
+    return withStashNotice(`Generated Euclidean rhythm (${args.hits}/${args.steps})`, written);
 }
 async function doPolyrhythm(args, ctx, sid) {
     args.sounds.forEach((s) => InputValidator.validateStringLength(s, 'sound', 100, false));
     args.patterns.forEach((p) => InputValidator.validatePositiveInteger(p, 'pattern'));
     const poly = ctx.generator.generatePolyrhythm(args.sounds, args.patterns);
-    await appendOrSet(poly, ctx, sid);
-    return 'Generated polyrhythm';
+    const written = await appendOrSet(poly, ctx, sid);
+    return withStashNotice('Generated polyrhythm', written);
 }
 async function doDrums(args, ctx, sid) {
     InputValidator.validateStringLength(args.style, 'style', 100, false);
     if (args.complexity !== undefined)
         InputValidator.validateNormalizedValue(args.complexity, 'complexity');
+    // Say which style actually produced the notes. An unknown genre falls
+    // back to techno, and echoing the request back made that invisible (#279).
+    const resolution = resolveDrumStyle(args.style);
     const drums = ctx.generator.generateDrumPattern(args.style, args.complexity || 0.5);
-    await appendOrSet(drums, ctx, sid);
-    return `Generated ${args.style} drums`;
+    const written = await appendOrSet(drums, ctx, sid);
+    return withStashNotice(resolution.supported
+        ? `Generated ${resolution.resolved} drums`
+        : `No drum pattern for style "${args.style}" — generated ${resolution.resolved} drums instead. ` +
+            `Styles with their own drums: ${DRUM_STYLES.join(', ')}.`, written);
 }
 async function doBassline(args, ctx, sid) {
     InputValidator.validateRootNote(args.key);
     InputValidator.validateStringLength(args.style, 'style', 100, false);
+    // role=bass echoed args.style back while the generator had silently
+    // fallen back to techno — #279 in the same file, eight lines below
+    // the sibling it fixed (#294).
+    const resolution = resolveBassStyle(args.style);
     const bass = ctx.generator.generateBassline(args.key, args.style);
-    await appendOrSet(bass, ctx, sid);
-    return `Generated ${args.style} bassline in ${args.key}`;
+    const written = await appendOrSet(bass, ctx, sid);
+    return withStashNotice(resolution.supported
+        ? `Generated ${resolution.resolved} bassline in ${args.key}`
+        : `No bassline for style "${args.style}" — generated ${resolution.resolved} ` +
+            `bassline in ${args.key} instead. ` +
+            `Styles with their own bassline: ${BASS_STYLES.join(', ')}.`, written);
 }
 async function doMelody(args, ctx, sid) {
     InputValidator.validateRootNote(args.root);
@@ -264,34 +164,20 @@ async function doMelody(args, ctx, sid) {
         InputValidator.validatePositiveInteger(args.length, 'length');
     const scale = ctx.theory.generateScale(args.root, args.scale);
     const melody = ctx.generator.generateMelody(scale, args.length || 8);
-    await appendOrSet(melody, ctx, sid);
-    return `Generated melody in ${args.root} ${args.scale}`;
+    const written = await appendOrSet(melody, ctx, sid);
+    return withStashNotice(`Generated melody in ${args.root} ${args.scale}`, written);
 }
 async function doFill(args, ctx, sid) {
     InputValidator.validateStringLength(args.style, 'style', 100, false);
     if (args.bars !== undefined)
         InputValidator.validatePositiveInteger(args.bars, 'bars');
     const fill = ctx.generator.generateFill(args.style, args.bars || 1);
-    await appendOrSet(fill, ctx, sid);
-    return `Generated ${args.bars || 1} bar fill`;
+    const written = await appendOrSet(fill, ctx, sid);
+    return withStashNotice(`Generated ${args.bars || 1} bar fill`, written);
 }
 export async function execute(name, args, ctx) {
     const sid = args?.session_id;
     switch (name) {
-        case 'generate_pattern': {
-            InputValidator.validateStringLength(args.style, 'style', 100, false);
-            if (args.key)
-                InputValidator.validateRootNote(args.key);
-            if (args.bpm !== undefined)
-                InputValidator.validateBPM(args.bpm);
-            const generated = ctx.generator.generateCompletePattern(args.style, args.key || 'C', args.bpm || 120);
-            await ctx.writePatternSafe(generated, sid);
-            if (args.auto_play && (sid || ctx.isInitialized())) {
-                await ctx.getController(sid).play();
-                return `Generated ${args.style} pattern. Playing.`;
-            }
-            return `Generated ${args.style} pattern`;
-        }
         case 'generate_part': {
             const role = args?.role;
             switch (role) {
@@ -303,9 +189,6 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid role: ${role}. Must be one of: drums, bass, melody, fill`);
             }
         }
-        case 'generate_drums': return await doDrums(args, ctx, sid);
-        case 'generate_bassline': return await doBassline(args, ctx, sid);
-        case 'generate_melody': return await doMelody(args, ctx, sid);
         case 'music_theory': {
             const q = args?.query;
             if (q !== 'scale' && q !== 'chord_progression') {
@@ -313,8 +196,6 @@ export async function execute(name, args, ctx) {
             }
             return q === 'scale' ? doScale(args, ctx) : await doChordProgression(args, ctx, sid);
         }
-        case 'generate_scale': return doScale(args, ctx);
-        case 'generate_chord_progression': return await doChordProgression(args, ctx, sid);
         case 'generate_rhythm': {
             const t = args?.type;
             if (t !== 'euclidean' && t !== 'polyrhythm') {
@@ -324,9 +205,6 @@ export async function execute(name, args, ctx) {
                 ? await doEuclidean(args, ctx, sid)
                 : await doPolyrhythm(args, ctx, sid);
         }
-        case 'generate_euclidean': return await doEuclidean(args, ctx, sid);
-        case 'generate_polyrhythm': return await doPolyrhythm(args, ctx, sid);
-        case 'generate_fill': return await doFill(args, ctx, sid);
         default:
             throw new Error(`generate module does not handle tool: ${name}`);
     }