laive-mcp 0.1.0

package/packages/state-engine/src/normalize.js

@@ -0,0 +1,357 @@
+import {
+  makeArrangementClipId,
+  makeDeviceId,
+  makeParameterId,
+  makeSceneId,
+  makeSessionClipId,
+  makeTrackId
+} from "./ids.js";
+
+function isoNow(value) {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+
+  return new Date().toISOString();
+}
+
+function toSourcePath(pathValue, fallback) {
+  if (typeof pathValue === "string" && pathValue.length > 0) {
+    return pathValue;
+  }
+
+  return fallback;
+}
+
+function bumpVersion(existingEntity) {
+  return existingEntity ? existingEntity.version + 1 : 1;
+}
+
+function createBaseEntity({
+  existingEntity,
+  id,
+  kind,
+  sourcePath,
+  observedAt,
+  source = "runtime"
+}) {
+  return {
+    id,
+    kind,
+    source,
+    sourcePath,
+    version: bumpVersion(existingEntity),
+    lastObservedAt: isoNow(observedAt)
+  };
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function pickFirst(...values) {
+  for (const value of values) {
+    if (value !== undefined) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export function normalizeApplication(snapshot, existingEntity, options = {}) {
+  const observedAt = isoNow(options.observedAt ?? snapshot.observed_at);
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: "application",
+      kind: "application",
+      sourcePath: "application",
+      observedAt
+    }),
+    name: snapshot.name ?? "Ableton Live",
+    versionLabel: pickFirst(snapshot.version, snapshot.versionLabel) ?? "unknown",
+    majorVersion: pickFirst(snapshot.major_version, snapshot.majorVersion) ?? null,
+    minorVersion: pickFirst(snapshot.minor_version, snapshot.minorVersion) ?? null,
+    bugfixVersion: pickFirst(snapshot.bugfix_version, snapshot.bugfixVersion) ?? null,
+    mode: snapshot.mode ?? null
+  };
+}
+
+export function normalizeSong(snapshot, existingEntity, options = {}) {
+  const observedAt = isoNow(options.observedAt ?? snapshot.observed_at);
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: "song",
+      kind: "song",
+      sourcePath: "song",
+      observedAt
+    }),
+    name: snapshot.name ?? "Untitled Set",
+    tempo: snapshot.tempo ?? null,
+    timeSignatureNumerator:
+      pickFirst(snapshot.time_signature_numerator, snapshot.timeSignatureNumerator) ?? null,
+    timeSignatureDenominator:
+      pickFirst(snapshot.time_signature_denominator, snapshot.timeSignatureDenominator) ?? null,
+    isPlaying: Boolean(pickFirst(snapshot.is_playing, snapshot.isPlaying)),
+    isRecording: Boolean(pickFirst(snapshot.is_recording, snapshot.isRecording)),
+    overdub: Boolean(snapshot.overdub),
+    metronome: Boolean(snapshot.metronome),
+    loopEnabled: Boolean(pickFirst(snapshot.loop_enabled, snapshot.loopEnabled)),
+    arrangementPositionBeats:
+      pickFirst(snapshot.arrangement_position_beats, snapshot.arrangementPositionBeats) ?? null,
+    clipTriggerQuantization:
+      pickFirst(snapshot.clip_trigger_quantization, snapshot.clipTriggerQuantization) ?? null,
+    midiRecordingQuantization:
+      pickFirst(snapshot.midi_recording_quantization, snapshot.midiRecordingQuantization) ?? null
+  };
+}
+
+export function normalizeSelection(snapshot, existingEntity, options = {}) {
+  const observedAt = isoNow(options.observedAt ?? snapshot.observed_at);
+  const selectedTrackId =
+    snapshot.selected_track_id ??
+    snapshot.selectedTrackId ??
+    (snapshot.selected_track
+      ? makeTrackId(
+          snapshot.selected_track.section ?? "visible",
+          snapshot.selected_track.index ?? 0
+        )
+      : null);
+
+  const selectedSceneId =
+    snapshot.selected_scene_id ??
+    snapshot.selectedSceneId ??
+    (Number.isInteger(snapshot.selected_scene_index)
+      ? makeSceneId(snapshot.selected_scene_index)
+      : null);
+
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: "selection",
+      kind: "selection",
+      sourcePath: "selection",
+      observedAt
+    }),
+    selectedTrackId,
+    selectedSceneId,
+    selectedClipId: pickFirst(snapshot.selected_clip_id, snapshot.selectedClipId) ?? null,
+    selectedDeviceId: pickFirst(snapshot.selected_device_id, snapshot.selectedDeviceId) ?? null,
+    detailView: pickFirst(snapshot.detail_view, snapshot.detailView) ?? null,
+    browserVisible: Boolean(pickFirst(snapshot.browser_visible, snapshot.browserVisible))
+  };
+}
+
+export function normalizeCapabilities(snapshot, existingEntity, options = {}) {
+  const observedAt = isoNow(options.observedAt ?? snapshot.observed_at);
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: "capabilities",
+      kind: "capabilities",
+      sourcePath: "capabilities",
+      observedAt
+    }),
+    runtimeVersion: pickFirst(snapshot.runtime_version, snapshot.runtimeVersion) ?? null,
+    supportedCommands: asArray(
+      pickFirst(snapshot.supported_commands, snapshot.supportedCommands)
+    ),
+    supportedEvents: asArray(pickFirst(snapshot.supported_events, snapshot.supportedEvents)),
+    features: snapshot.features ?? {}
+  };
+}
+
+export function normalizeTrack(track, existingEntity, options = {}) {
+  const section = pickFirst(track.section, track.kind, track.trackSection) ?? "visible";
+  const index = pickFirst(track.track_index, track.trackIndex, track.index) ?? 0;
+  const trackId = track.id ?? makeTrackId(section, index);
+  const observedAt = isoNow(options.observedAt ?? track.observed_at);
+
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: trackId,
+      kind: "track",
+      sourcePath: toSourcePath(track.path, `song.tracks.${section}.${index}`),
+      observedAt
+    }),
+    section,
+    index,
+    name: track.name ?? `Track ${index + 1}`,
+    color: track.color ?? null,
+    isGroup: Boolean(pickFirst(track.is_group, track.isGroup)),
+    groupTrackId: pickFirst(track.group_track_id, track.groupTrackId) ?? null,
+    armed: Boolean(track.armed),
+    muted: Boolean(track.muted),
+    soloed: Boolean(track.soloed),
+    frozen: Boolean(track.frozen),
+    monitoringState: pickFirst(track.monitoring_state, track.monitoringState) ?? null,
+    playingSlotIndex: pickFirst(track.playing_slot_index, track.playingSlotIndex) ?? null,
+    clipSlotCount:
+      pickFirst(track.clip_slot_count, track.clipSlotCount) ?? asArray(track.session_clips).length,
+    arrangementClipCount:
+      pickFirst(track.arrangement_clip_count, track.arrangementClipCount) ??
+      asArray(track.arrangement_clips).length,
+    sessionClipIds: [],
+    arrangementClipIds: [],
+    deviceIds: []
+  };
+}
+
+export function normalizeScene(scene, existingEntity, options = {}) {
+  const index = pickFirst(scene.scene_index, scene.sceneIndex, scene.index) ?? 0;
+  const sceneId = scene.id ?? makeSceneId(index);
+  const observedAt = isoNow(options.observedAt ?? scene.observed_at);
+
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: sceneId,
+      kind: "scene",
+      sourcePath: toSourcePath(scene.path, `song.scenes.${index}`),
+      observedAt
+    }),
+    index,
+    name: scene.name ?? `Scene ${index + 1}`,
+    color: scene.color ?? null,
+    isTriggered: Boolean(pickFirst(scene.is_triggered, scene.isTriggered))
+  };
+}
+
+export function normalizeClip(clip, trackId, existingEntity, options = {}) {
+  const slotIndex = pickFirst(clip.slot_index, clip.slotIndex, clip.scene_index);
+  const clipIndex = pickFirst(clip.arrangement_index, clip.arrangementIndex, clip.index) ?? 0;
+  const location = clip.location ?? (Number.isInteger(slotIndex) ? "session" : "arrangement");
+  const clipId =
+    clip.id ??
+    (location === "session"
+      ? makeSessionClipId(trackId, slotIndex ?? 0)
+      : makeArrangementClipId(trackId, clipIndex));
+  const observedAt = isoNow(options.observedAt ?? clip.observed_at);
+
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: clipId,
+      kind: "clip",
+      sourcePath:
+        location === "session"
+          ? toSourcePath(clip.path, `${trackId}.session_clips.${slotIndex ?? 0}`)
+          : toSourcePath(clip.path, `${trackId}.arrangement_clips.${clipIndex}`),
+      observedAt
+    }),
+    trackId,
+    location,
+    slotIndex: location === "session" ? slotIndex ?? 0 : null,
+    index: location === "arrangement" ? clipIndex : null,
+    name: clip.name ?? null,
+    color: clip.color ?? null,
+    isMidi: pickFirst(clip.is_midi, clip.isMidi) ?? null,
+    isAudio: pickFirst(clip.is_audio, clip.isAudio) ?? null,
+    isPlaying: Boolean(pickFirst(clip.is_playing, clip.isPlaying)),
+    isTriggered: Boolean(pickFirst(clip.is_triggered, clip.isTriggered)),
+    isRecording: Boolean(pickFirst(clip.is_recording, clip.isRecording)),
+    startBeats: pickFirst(clip.start_beats, clip.startBeats) ?? null,
+    endBeats: pickFirst(clip.end_beats, clip.endBeats) ?? null,
+    loopStartBeats: pickFirst(clip.loop_start_beats, clip.loopStartBeats) ?? null,
+    loopEndBeats: pickFirst(clip.loop_end_beats, clip.loopEndBeats) ?? null,
+    noteCount: pickFirst(clip.note_count, clip.noteCount) ?? null
+  };
+}
+
+export function normalizeDevice(device, trackId, existingEntity, options = {}) {
+  const index = pickFirst(device.device_index, device.deviceIndex, device.index) ?? 0;
+  const deviceId = device.id ?? makeDeviceId(trackId, index);
+  const observedAt = isoNow(options.observedAt ?? device.observed_at);
+
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: deviceId,
+      kind: "device",
+      sourcePath: toSourcePath(device.path, `${trackId}.devices.${index}`),
+      observedAt
+    }),
+    trackId,
+    index,
+    name: device.name ?? `Device ${index + 1}`,
+    className: pickFirst(device.class_name, device.className) ?? null,
+    type: device.type ?? null,
+    canHaveChains: Boolean(pickFirst(device.can_have_chains, device.canHaveChains)),
+    isSelected: Boolean(pickFirst(device.is_selected, device.isSelected)),
+    isEnabled: pickFirst(device.is_enabled, device.isEnabled) ?? null,
+    parameterIds: []
+  };
+}
+
+export function normalizeParameter(parameter, deviceId, existingEntity, options = {}) {
+  const index =
+    pickFirst(parameter.parameter_index, parameter.parameterIndex, parameter.index) ?? 0;
+  const parameterId = parameter.id ?? makeParameterId(deviceId, index);
+  const observedAt = isoNow(options.observedAt ?? parameter.observed_at);
+
+  return {
+    ...createBaseEntity({
+      existingEntity,
+      id: parameterId,
+      kind: "parameter",
+      sourcePath: toSourcePath(parameter.path, `${deviceId}.parameters.${index}`),
+      observedAt
+    }),
+    deviceId,
+    index,
+    name: parameter.name ?? `Parameter ${index + 1}`,
+    value: parameter.value ?? null,
+    min: parameter.min ?? null,
+    max: parameter.max ?? null,
+    isQuantized: Boolean(pickFirst(parameter.is_quantized, parameter.isQuantized)),
+    displayValue: pickFirst(parameter.display_value, parameter.displayValue) ?? null,
+    unit: parameter.unit ?? null
+  };
+}
+
+export function normalizeTrackBundle(track, existingState = {}, options = {}) {
+  const normalizedTrack = normalizeTrack(track, existingState.track, options);
+
+  const sessionClips = asArray(track.session_clips).map((clip) =>
+    normalizeClip(clip, normalizedTrack.id, existingState.clips?.[clip.id], options)
+  );
+  const arrangementClips = asArray(track.arrangement_clips).map((clip) =>
+    normalizeClip(clip, normalizedTrack.id, existingState.clips?.[clip.id], options)
+  );
+  const devices = asArray(track.devices).map((device) => {
+    const normalizedDevice = normalizeDevice(
+      device,
+      normalizedTrack.id,
+      existingState.devices?.[device.id],
+      options
+    );
+    const parameters = asArray(device.parameters).map((parameter) =>
+      normalizeParameter(
+        parameter,
+        normalizedDevice.id,
+        existingState.parameters?.[parameter.id],
+        options
+      )
+    );
+
+    normalizedDevice.parameterIds = parameters.map((parameter) => parameter.id);
+    return {
+      device: normalizedDevice,
+      parameters
+    };
+  });
+
+  normalizedTrack.sessionClipIds = sessionClips.map((clip) => clip.id);
+  normalizedTrack.arrangementClipIds = arrangementClips.map((clip) => clip.id);
+  normalizedTrack.deviceIds = devices.map(({ device }) => device.id);
+
+  return {
+    track: normalizedTrack,
+    sessionClips,
+    arrangementClips,
+    devices
+  };
+}

package/packages/state-engine/src/queries.js

@@ -0,0 +1,154 @@
+function valuesInOrder(ids, collection) {
+  return ids.map((id) => collection[id]).filter(Boolean);
+}
+
+export function summarizeProject(state) {
+  const tracks = valuesInOrder(state.trackOrder, state.tracks);
+  const scenes = valuesInOrder(state.sceneOrder, state.scenes);
+  const clips = Object.values(state.clips);
+  const playingClips = clips.filter((clip) => clip.isPlaying);
+
+  return {
+    snapshotVersion: state.meta.snapshotVersion,
+    lastUpdatedAt: state.meta.lastUpdatedAt,
+    dirtyPaths: [...state.meta.dirtyPaths],
+    application: state.application
+      ? {
+          versionLabel: state.application.versionLabel,
+          mode: state.application.mode
+        }
+      : null,
+    song: state.song
+      ? {
+          name: state.song.name,
+          tempo: state.song.tempo,
+          isPlaying: state.song.isPlaying,
+          isRecording: state.song.isRecording
+        }
+      : null,
+    counts: {
+      tracks: tracks.length,
+      visibleTracks: state.visibleTrackIds.length,
+      returnTracks: state.returnTrackIds.length,
+      scenes: scenes.length,
+      clips: clips.length,
+      devices: Object.keys(state.devices).length,
+      parameters: Object.keys(state.parameters).length,
+      playingClips: playingClips.length
+    },
+    playingClips: playingClips.map((clip) => ({
+      id: clip.id,
+      name: clip.name,
+      trackId: clip.trackId,
+      location: clip.location,
+      slotIndex: clip.slotIndex,
+      index: clip.index
+    }))
+  };
+}
+
+export function getSelectedContext(state) {
+  const selection = state.selection;
+
+  if (!selection) {
+    return null;
+  }
+
+  const track = selection.selectedTrackId
+    ? state.tracks[selection.selectedTrackId] ?? null
+    : null;
+  const clip = selection.selectedClipId
+    ? state.clips[selection.selectedClipId] ?? null
+    : null;
+  const device = selection.selectedDeviceId
+    ? state.devices[selection.selectedDeviceId] ?? null
+    : null;
+  const scene = selection.selectedSceneId
+    ? state.scenes[selection.selectedSceneId] ?? null
+    : null;
+
+  return {
+    selection,
+    track,
+    clip,
+    device,
+    scene
+  };
+}
+
+export function findTrack(state, query) {
+  const searchValue = String(query ?? "").trim().toLowerCase();
+
+  if (!searchValue) {
+    return null;
+  }
+
+  if (state.tracks[searchValue]) {
+    return state.tracks[searchValue];
+  }
+
+  return Object.values(state.tracks).find((track) => {
+    if (String(track.index) === searchValue) {
+      return true;
+    }
+
+    return track.name.toLowerCase() === searchValue;
+  }) ?? null;
+}
+
+export function listPlayingClips(state) {
+  return Object.values(state.clips)
+    .filter((clip) => clip.isPlaying)
+    .map((clip) => ({
+      clip,
+      track: state.tracks[clip.trackId] ?? null
+    }));
+}
+
+export function getTrackDetails(state, trackId) {
+  const track = state.tracks[trackId] ?? null;
+
+  if (!track) {
+    return null;
+  }
+
+  const sessionClips = valuesInOrder(track.sessionClipIds, state.clips);
+  const arrangementClips = valuesInOrder(track.arrangementClipIds, state.clips);
+  const devices = valuesInOrder(track.deviceIds, state.devices).map((device) => ({
+    ...device,
+    parameters: valuesInOrder(device.parameterIds, state.parameters)
+  }));
+
+  return {
+    track,
+    sessionClips,
+    arrangementClips,
+    devices
+  };
+}
+
+export function searchEntities(state, query) {
+  const searchValue = String(query ?? "").trim().toLowerCase();
+
+  if (!searchValue) {
+    return [];
+  }
+
+  const collections = [
+    ...Object.values(state.tracks),
+    ...Object.values(state.scenes),
+    ...Object.values(state.clips),
+    ...Object.values(state.devices),
+    ...Object.values(state.parameters)
+  ];
+
+  return collections.filter((entity) => {
+    if (entity.id.toLowerCase().includes(searchValue)) {
+      return true;
+    }
+
+    return String(entity.name ?? "")
+      .toLowerCase()
+      .includes(searchValue);
+  });
+}

package/packages/state-engine/src/replay.js

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import { applyEvent, applySnapshot, createInitialState } from "./engine.js";
+
+function parseTraceText(text) {
+  const trimmed = text.trim();
+
+  if (!trimmed) {
+    return [];
+  }
+
+  if (trimmed.startsWith("[")) {
+    return JSON.parse(trimmed);
+  }
+
+  return trimmed
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+export async function loadTraceFile(filePath) {
+  const content = await readFile(filePath, "utf8");
+  return parseTraceText(content);
+}
+
+export function replayTrace(entries, initialState = createInitialState()) {
+  let currentState = structuredClone(initialState);
+  const history = [];
+
+  for (const entry of entries) {
+    if (entry.type === "snapshot") {
+      currentState = applySnapshot(currentState, entry.payload, {
+        observedAt: entry.observed_at
+      });
+    } else if (entry.type === "event") {
+      currentState = applyEvent(
+        currentState,
+        {
+          event: entry.event,
+          name: entry.name,
+          payload: entry.payload,
+          observed_at: entry.observed_at
+        },
+        {
+          observedAt: entry.observed_at
+        }
+      );
+    }
+
+    history.push(structuredClone(currentState));
+  }
+
+  return {
+    state: currentState,
+    history
+  };
+}
+
+export { parseTraceText };

package/packages/ui-automation/src/executor.js

@@ -0,0 +1,87 @@
+import {
+  activateApplication,
+  clickMenuPath,
+  getFrontmostApplication,
+  sendKeystroke,
+  typeText
+} from "./macos.js";
+import { assertSupportedLiveWindow, assertWorkflowAllowed } from "./guards.js";
+import { getWorkflow } from "./workflows.js";
+
+function resolveParameter(step, parameters) {
+  if (!step.parameter) {
+    return step.value;
+  }
+
+  if (!(step.parameter in parameters)) {
+    throw new Error(`Missing workflow parameter: ${step.parameter}`);
+  }
+
+  return parameters[step.parameter];
+}
+
+export function materializeWorkflow(name, parameters = {}) {
+  const workflow = getWorkflow(name);
+  const materializedSteps = workflow.steps.map((step) => ({
+    ...step,
+    resolvedValue: resolveParameter(step, parameters)
+  }));
+
+  return {
+    ...workflow,
+    steps: materializedSteps
+  };
+}
+
+export async function captureContext() {
+  return getFrontmostApplication();
+}
+
+export async function executeWorkflow(name, parameters = {}, options = {}) {
+  const workflow = materializeWorkflow(name, parameters);
+  assertWorkflowAllowed(workflow);
+
+  const context = options.context ?? (await captureContext());
+  if (workflow.guards.includes("app:ableton-live-frontmost")) {
+    assertSupportedLiveWindow(context);
+  }
+
+  const executedSteps = [];
+
+  for (const step of workflow.steps) {
+    switch (step.type) {
+      case "activate_app":
+        await activateApplication(step.appName);
+        break;
+      case "menu_click":
+        await clickMenuPath("Ableton Live", step.menuPath);
+        break;
+      case "keystroke":
+        await sendKeystroke(step.value, step.modifiers);
+        break;
+      case "type_text":
+        await typeText(step.resolvedValue);
+        break;
+      case "capture_context":
+        break;
+      case "focus_section":
+      case "set_text_field":
+      case "press_button":
+      case "wait_for_window":
+        break;
+      default:
+        throw new Error(`Unsupported workflow step: ${step.type}`);
+    }
+
+    executedSteps.push({
+      type: step.type,
+      resolvedValue: step.resolvedValue ?? null
+    });
+  }
+
+  return {
+    workflow: workflow.name,
+    context,
+    executedSteps
+  };
+}

package/packages/ui-automation/src/guards.js

@@ -0,0 +1,21 @@
+export function assertMacOS() {
+  if (process.platform !== "darwin") {
+    throw new Error("UI automation is currently supported on macOS only.");
+  }
+}
+
+export function assertSupportedLiveWindow(windowContext) {
+  if (!windowContext?.isFrontmost) {
+    throw new Error("Ableton Live must be the frontmost application for UI fallback.");
+  }
+
+  if (!windowContext?.appName?.includes("Live")) {
+    throw new Error("Focused application is not Ableton Live.");
+  }
+}
+
+export function assertWorkflowAllowed(workflow) {
+  if (!workflow?.allowFallback) {
+    throw new Error(`Workflow ${workflow?.name ?? "unknown"} is not allowed in fallback mode.`);
+  }
+}