laive-mcp 0.1.0

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

@@ -0,0 +1,186 @@
+import { readFileSync } from "node:fs";
+import { chmod, cp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = path.resolve(packageRoot, "..", "..");
+const rootPackageJsonPath = path.join(repoRoot, "package.json");
+
+function getPackageVersion() {
+  return JSON.parse(readFileSync(rootPackageJsonPath, "utf8")).version;
+}
+
+export function getUiHelperBundlePaths({
+  destinationRoot = path.join(repoRoot, "artifacts", "ui-helper")
+} = {}) {
+  const appBundleRoot = path.join(destinationRoot, "laive-ui-helper.app");
+  const contentsRoot = path.join(appBundleRoot, "Contents");
+  const macOsRoot = path.join(contentsRoot, "MacOS");
+  const resourcesRoot = path.join(contentsRoot, "Resources");
+  const executablePath = path.join(macOsRoot, "laive-ui-helper");
+  const infoPlistPath = path.join(contentsRoot, "Info.plist");
+
+  return {
+    repoRoot,
+    destinationRoot,
+    appBundleRoot,
+    contentsRoot,
+    macOsRoot,
+    resourcesRoot,
+    executablePath,
+    infoPlistPath
+  };
+}
+
+export function getDefaultHelperExecutablePath() {
+  return getUiHelperBundlePaths().executablePath;
+}
+
+export function getStableUiHelperInstallPaths({
+  destinationRoot = path.join(os.homedir(), "Applications")
+} = {}) {
+  return getUiHelperBundlePaths({ destinationRoot });
+}
+
+export function buildHelperInfoPlist() {
+  const packageVersion = getPackageVersion();
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>laive-ui-helper</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.laive.ui-helper</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>laive-ui-helper</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>${packageVersion}</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>LSUIElement</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+
+function shellEscapeSingleQuotes(value) {
+  return String(value).replaceAll("'", `'\\''`);
+}
+
+export function buildHelperExecutableScript() {
+  const frontmostScript = [
+    'tell application "System Events"',
+    "set frontApp to name of first application process whose frontmost is true",
+    "end tell",
+    "return frontApp"
+  ].join("\n");
+
+  return `#!/bin/zsh
+set -euo pipefail
+
+command="\${1:-}"
+shift || true
+
+decode_base64() {
+  /usr/bin/python3 - "$1" <<'PY'
+import base64
+import sys
+print(base64.b64decode(sys.argv[1]).decode("utf-8"), end="")
+PY
+}
+
+run_script() {
+  local script_content="$1"
+  /usr/bin/osascript -e "$script_content"
+}
+
+case "$command" in
+  run_applescript_base64)
+    if [[ "$#" -lt 1 ]]; then
+      echo "Missing base64 payload" >&2
+      exit 64
+    fi
+    script_content="$(decode_base64 "$1")"
+    run_script "$script_content"
+    ;;
+  frontmost_app)
+    run_script '${shellEscapeSingleQuotes(frontmostScript)}'
+    ;;
+  activate_app)
+    if [[ "$#" -lt 1 ]]; then
+      echo "Missing app name" >&2
+      exit 64
+    fi
+    run_script "tell application \\"$1\\" to activate"
+    ;;
+  *)
+    echo "Unsupported command: $command" >&2
+    exit 64
+    ;;
+esac
+`;
+}
+
+export async function stageUiHelper(options = {}) {
+  const paths = getUiHelperBundlePaths(options);
+
+  await mkdir(paths.macOsRoot, { recursive: true });
+  await mkdir(paths.resourcesRoot, { recursive: true });
+  await writeFile(paths.infoPlistPath, buildHelperInfoPlist(), "utf8");
+  await writeFile(paths.executablePath, buildHelperExecutableScript(), "utf8");
+  await chmod(paths.executablePath, 0o755);
+
+  return {
+    appBundleRoot: paths.appBundleRoot,
+    executablePath: paths.executablePath,
+    infoPlistPath: paths.infoPlistPath
+  };
+}
+
+export async function installUiHelper({
+  destinationRoot = path.join(os.homedir(), "Applications"),
+  dryRun = true,
+  overwrite = true
+} = {}) {
+  const staged = await stageUiHelper();
+  const installPaths = getStableUiHelperInstallPaths({ destinationRoot });
+
+  const payload = {
+    stagedAppBundleRoot: staged.appBundleRoot,
+    stagedExecutablePath: staged.executablePath,
+    installDestinationRoot: installPaths.destinationRoot,
+    appBundleRoot: installPaths.appBundleRoot,
+    executablePath: installPaths.executablePath,
+    infoPlistPath: installPaths.infoPlistPath,
+    dryRun,
+    overwrite
+  };
+
+  if (dryRun) {
+    return {
+      ...payload,
+      status: "dry_run"
+    };
+  }
+
+  await mkdir(installPaths.destinationRoot, { recursive: true });
+  if (overwrite) {
+    await rm(installPaths.appBundleRoot, { recursive: true, force: true });
+  }
+  await cp(staged.appBundleRoot, installPaths.appBundleRoot, { recursive: true });
+
+  return {
+    ...payload,
+    status: "installed"
+  };
+}

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

@@ -0,0 +1,20 @@
+export { captureContext, executeWorkflow, materializeWorkflow } from "./executor.js";
+export { assertMacOS, assertSupportedLiveWindow, assertWorkflowAllowed } from "./guards.js";
+export {
+  buildHelperExecutableScript,
+  buildHelperInfoPlist,
+  getDefaultHelperExecutablePath,
+  getUiHelperBundlePaths,
+  getStableUiHelperInstallPaths,
+  installUiHelper,
+  stageUiHelper
+} from "./helper.js";
+export {
+  activateApplication,
+  clickMenuPath,
+  getFrontmostApplication,
+  runAppleScript,
+  sendKeystroke,
+  typeText
+} from "./macos.js";
+export { getWorkflow, workflows } from "./workflows.js";

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

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+
+import { assertMacOS } from "./guards.js";
+import { getDefaultHelperExecutablePath } from "./helper.js";
+
+const execFileAsync = promisify(execFile);
+
+function quoteAppleScriptString(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+
+export async function runAppleScript(lines) {
+  assertMacOS();
+
+  const script = Array.isArray(lines) ? lines.join("\n") : lines;
+  const helperExecutablePath = process.env.LAIVE_UI_HELPER_EXECUTABLE ?? getDefaultHelperExecutablePath();
+  const encodedScript = Buffer.from(script, "utf8").toString("base64");
+  const command =
+    helperExecutablePath && existsSync(helperExecutablePath)
+      ? { executable: helperExecutablePath, args: ["run_applescript_base64", encodedScript] }
+      : { executable: "/usr/bin/osascript", args: ["-e", script] };
+  const { stdout } = await execFileAsync(command.executable, command.args);
+  return stdout.trim();
+}
+
+export async function getFrontmostApplication() {
+  const output = await runAppleScript([
+    'tell application "System Events"',
+    "set frontApp to name of first application process whose frontmost is true",
+    "end tell",
+    "return frontApp"
+  ]);
+
+  return {
+    appName: output,
+    isFrontmost: Boolean(output)
+  };
+}
+
+export async function activateApplication(appName) {
+  const safeAppName = quoteAppleScriptString(appName);
+  await runAppleScript(`tell application "${safeAppName}" to activate`);
+}
+
+export async function clickMenuPath(appName, menuPath) {
+  const [menuBarItem, menuItem] = menuPath;
+  const safeAppName = quoteAppleScriptString(appName);
+  const safeMenuBarItem = quoteAppleScriptString(menuBarItem);
+  const safeMenuItem = quoteAppleScriptString(menuItem);
+
+  await runAppleScript([
+    `tell application "${safeAppName}" to activate`,
+    'tell application "System Events"',
+    `tell process "${safeAppName}"`,
+    `click menu item "${safeMenuItem}" of menu "${safeMenuBarItem}" of menu bar item "${safeMenuBarItem}" of menu bar 1`,
+    "end tell",
+    "end tell"
+  ]);
+}
+
+export async function sendKeystroke(value, modifiers = []) {
+  const safeValue = quoteAppleScriptString(value);
+  const modifierExpression =
+    modifiers.length > 0 ? ` using {${modifiers.map((item) => `${item} down`).join(", ")}}` : "";
+
+  await runAppleScript([
+    'tell application "System Events"',
+    `keystroke "${safeValue}"${modifierExpression}`,
+    "end tell"
+  ]);
+}
+
+export async function typeText(value) {
+  const safeValue = quoteAppleScriptString(value);
+  await runAppleScript([
+    'tell application "System Events"',
+    `keystroke "${safeValue}"`,
+    "end tell"
+  ]);
+}

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

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { stageUiHelper } from "./helper.js";
+
+const result = await stageUiHelper();
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

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

@@ -0,0 +1,72 @@
+const commonGuards = ["platform:darwin", "app:ableton-live-frontmost"];
+
+export const workflows = {
+  exportAudioVideo: {
+    name: "exportAudioVideo",
+    description: "Open the Export Audio/Video dialog and stage the UI for a deterministic export flow.",
+    allowFallback: true,
+    guards: commonGuards,
+    steps: [
+      { type: "activate_app", appName: "Ableton Live" },
+      { type: "menu_click", menuPath: ["File", "Export Audio/Video..."] },
+      { type: "wait_for_window", title: "Export Audio/Video", timeoutMs: 5000 }
+    ]
+  },
+  exportWithPreset: {
+    name: "exportWithPreset",
+    description: "Apply a known export preset, then confirm the export dialog.",
+    allowFallback: true,
+    guards: commonGuards,
+    parameters: ["presetName", "outputPath"],
+    steps: [
+      { type: "activate_app", appName: "Ableton Live" },
+      { type: "menu_click", menuPath: ["File", "Export Audio/Video..."] },
+      { type: "wait_for_window", title: "Export Audio/Video", timeoutMs: 5000 },
+      { type: "set_text_field", label: "Preset", parameter: "presetName" },
+      { type: "set_text_field", label: "Output Folder", parameter: "outputPath" },
+      { type: "press_button", label: "Export" }
+    ]
+  },
+  browserSearchAndLoad: {
+    name: "browserSearchAndLoad",
+    description: "Focus the browser, search for an item, and perform a deterministic load action.",
+    allowFallback: true,
+    guards: commonGuards,
+    parameters: ["query"],
+    steps: [
+      { type: "activate_app", appName: "Ableton Live" },
+      { type: "menu_click", menuPath: ["View", "Browser"] },
+      { type: "keystroke", value: "f", modifiers: ["command"] },
+      { type: "type_text", parameter: "query" },
+      { type: "keystroke", value: "return" }
+    ]
+  },
+  focusSection: {
+    name: "focusSection",
+    description: "Navigate Live to a named section using deterministic menu or shortcut actions.",
+    allowFallback: true,
+    guards: commonGuards,
+    parameters: ["sectionName"],
+    steps: [
+      { type: "activate_app", appName: "Ableton Live" },
+      { type: "focus_section", parameter: "sectionName" }
+    ]
+  },
+  captureContext: {
+    name: "captureContext",
+    description: "Capture focused app metadata for diagnostics before running a fallback action.",
+    allowFallback: true,
+    guards: ["platform:darwin"],
+    steps: [{ type: "capture_context" }]
+  }
+};
+
+export function getWorkflow(name) {
+  const workflow = workflows[name];
+
+  if (!workflow) {
+    throw new Error(`Unknown workflow: ${name}`);
+  }
+
+  return workflow;
+}

package/scripts/install-remote-script.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+
+from remote_script_tooling import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/install-ui-helper.mjs

@@ -0,0 +1,14 @@
+import process from "node:process";
+
+import { installUiHelper } from "../packages/ui-automation/src/index.js";
+
+const args = process.argv.slice(2);
+const dryRun = !args.includes("--apply");
+const overwrite = args.includes("--overwrite");
+
+const result = await installUiHelper({
+  dryRun,
+  overwrite
+});
+
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/package-remote-script.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+
+from remote_script_tooling import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(["package"]))

package/scripts/package-ui-helper.mjs

@@ -0,0 +1,4 @@
+import { stageUiHelper } from "../packages/ui-automation/src/index.js";
+
+const payload = await stageUiHelper();
+process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);

package/scripts/remote_script_tooling.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+REMOTE_SCRIPT_SOURCE = (
+    REPO_ROOT / "packages" / "live-bridge-remote-script" / "python" / "laive"
+)
+DEFAULT_ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "remote-script"
+
+
+@dataclass(frozen=True)
+class LiveInstall:
+    app_path: Path
+    remote_scripts_dir: Path
+
+    def to_dict(self) -> dict:
+        return {
+            "app_path": str(self.app_path),
+            "remote_scripts_dir": str(self.remote_scripts_dir),
+        }
+
+
+def candidate_live_search_roots() -> List[Path]:
+    return [Path("/Applications"), Path.home() / "Applications"]
+
+
+def remote_scripts_dir_for_app(app_path: Path) -> Path:
+    return app_path / "Contents" / "App-Resources" / "MIDI Remote Scripts"
+
+
+def detect_live_installs(search_roots: Iterable[Path] | None = None) -> List[LiveInstall]:
+    installs = []
+    for root in search_roots or candidate_live_search_roots():
+        if not root.exists():
+            continue
+        for app_path in sorted(root.glob("Ableton Live*.app")):
+            remote_scripts_dir = remote_scripts_dir_for_app(app_path)
+            installs.append(
+                LiveInstall(app_path=app_path, remote_scripts_dir=remote_scripts_dir)
+            )
+    return installs
+
+
+def ensure_source_exists(source_root: Path = REMOTE_SCRIPT_SOURCE) -> Path:
+    if not source_root.exists():
+        raise FileNotFoundError("Remote Script source not found: {0}".format(source_root))
+    return source_root
+
+
+def stage_remote_script(
+    source_root: Path = REMOTE_SCRIPT_SOURCE,
+    artifacts_dir: Path = DEFAULT_ARTIFACTS_DIR,
+    archive_name: str = "laive-remote-script",
+) -> dict:
+    source_root = ensure_source_exists(source_root)
+    artifacts_dir.mkdir(parents=True, exist_ok=True)
+    staging_root = artifacts_dir / "staging"
+    target_dir = staging_root / source_root.name
+
+    if target_dir.exists():
+        shutil.rmtree(target_dir)
+
+    shutil.copytree(source_root, target_dir)
+    archive_path = shutil.make_archive(
+        str(artifacts_dir / archive_name), "zip", root_dir=staging_root, base_dir=source_root.name
+    )
+
+    return {
+        "source_root": str(source_root),
+        "staging_dir": str(target_dir),
+        "archive_path": archive_path,
+    }
+
+
+def choose_live_install(
+    live_app_path: Path | None = None, search_roots: Iterable[Path] | None = None
+) -> LiveInstall:
+    if live_app_path is not None:
+        return LiveInstall(
+            app_path=live_app_path,
+            remote_scripts_dir=remote_scripts_dir_for_app(live_app_path),
+        )
+
+    installs = detect_live_installs(search_roots)
+    if not installs:
+        raise FileNotFoundError(
+            "No Ableton Live installs were detected. Pass --live-app to choose a bundle explicitly."
+        )
+    if len(installs) > 1:
+        raise RuntimeError(
+            "Multiple Live installs were detected. Pass --live-app to choose one explicitly."
+        )
+    return installs[0]
+
+
+def doctor_report(search_roots: Iterable[Path] | None = None) -> dict:
+    installs = detect_live_installs(search_roots)
+    remote_script_source_exists = REMOTE_SCRIPT_SOURCE.exists()
+    archive_path = DEFAULT_ARTIFACTS_DIR / "laive-remote-script.zip"
+    package_json = REPO_ROOT / "package.json"
+    bin_script = REPO_ROOT / "bin" / "laive.mjs"
+
+    return {
+        "repo_root": str(REPO_ROOT),
+        "python_executable": sys.executable,
+        "python_version": sys.version.split()[0],
+        "remote_script_source": str(REMOTE_SCRIPT_SOURCE),
+        "remote_script_source_exists": remote_script_source_exists,
+        "cli_entrypoint": str(bin_script),
+        "cli_entrypoint_exists": bin_script.exists(),
+        "package_json_exists": package_json.exists(),
+        "packaged_archive": str(archive_path),
+        "packaged_archive_exists": archive_path.exists(),
+        "detected_live_installs": [install.to_dict() for install in installs],
+        "ready_for_install": remote_script_source_exists and len(installs) >= 1,
+    }
+
+
+def install_remote_script(
+    live_app_path: Path | None = None,
+    source_root: Path = REMOTE_SCRIPT_SOURCE,
+    dry_run: bool = True,
+    overwrite: bool = False,
+    auto_package: bool = True,
+) -> dict:
+    source_root = ensure_source_exists(source_root)
+    chosen_install = choose_live_install(live_app_path)
+    live_app_path = chosen_install.app_path
+    remote_scripts_dir = chosen_install.remote_scripts_dir
+    target_dir = remote_scripts_dir / source_root.name
+    package_payload = stage_remote_script(source_root=source_root) if auto_package else None
+
+    payload = {
+        "live_app_path": str(live_app_path),
+        "remote_scripts_dir": str(remote_scripts_dir),
+        "source_root": str(source_root),
+        "target_dir": str(target_dir),
+        "dry_run": dry_run,
+        "overwrite": overwrite,
+        "auto_packaged": auto_package,
+        "package_payload": package_payload,
+    }
+
+    if dry_run:
+        payload["status"] = "dry_run"
+        payload["would_install"] = source_root.exists()
+        payload["remote_scripts_dir_exists"] = remote_scripts_dir.exists()
+        payload["target_exists"] = target_dir.exists()
+        return payload
+
+    remote_scripts_dir.mkdir(parents=True, exist_ok=True)
+    if target_dir.exists():
+        if not overwrite:
+            raise FileExistsError(
+                "Target Remote Script already exists: {0}. Use --overwrite to replace it.".format(
+                    target_dir
+                )
+            )
+        shutil.rmtree(target_dir)
+
+    shutil.copytree(source_root, target_dir)
+    payload["status"] = "installed"
+    payload["target_exists"] = target_dir.exists()
+    return payload
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Package and install the laive Remote Script.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    detect_parser = subparsers.add_parser("detect", help="Detect likely Ableton Live.app installs.")
+    detect_parser.add_argument("--json", action="store_true", help="Emit JSON instead of plain text.")
+
+    doctor_parser = subparsers.add_parser("doctor", help="Report whether the repo is ready to install.")
+    doctor_parser.add_argument("--json", action="store_true", help="Emit JSON instead of plain text.")
+
+    package_parser = subparsers.add_parser("package", help="Stage and zip the Remote Script.")
+    package_parser.add_argument(
+        "--artifacts-dir",
+        default=str(DEFAULT_ARTIFACTS_DIR),
+        help="Directory where staged files and zip archives are written.",
+    )
+    package_parser.add_argument("--json", action="store_true", help="Emit JSON instead of plain text.")
+
+    install_parser = subparsers.add_parser("install", help="Install the Remote Script into a Live.app bundle.")
+    install_parser.add_argument("--live-app", help="Path to Ableton Live.app")
+    install_parser.add_argument("--apply", action="store_true", help="Perform the install instead of a dry run.")
+    install_parser.add_argument("--overwrite", action="store_true", help="Overwrite an existing laive script.")
+    install_parser.add_argument("--json", action="store_true", help="Emit JSON instead of plain text.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "detect":
+        installs = [install.to_dict() for install in detect_live_installs()]
+        if args.json:
+            print(json.dumps({"installs": installs}, indent=2))
+        else:
+            for install in installs:
+                print("{app_path} -> {remote_scripts_dir}".format(**install))
+        return 0
+
+    if args.command == "doctor":
+        payload = doctor_report()
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            for key, value in payload.items():
+                print("{0}: {1}".format(key, value))
+        return 0
+
+    if args.command == "package":
+        payload = stage_remote_script(artifacts_dir=Path(args.artifacts_dir))
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            for key, value in payload.items():
+                print("{0}: {1}".format(key, value))
+        return 0
+
+    if args.command == "install":
+        payload = install_remote_script(
+            live_app_path=Path(args.live_app) if args.live_app else None,
+            dry_run=not args.apply,
+            overwrite=args.overwrite,
+        )
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            for key, value in payload.items():
+                print("{0}: {1}".format(key, value))
+        return 0
+
+    parser.error("Unknown command")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())