codeloop-mcp-server 0.1.88 → 0.1.95

package/dist/runners/active_target.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Persists which device a journey/recording is driving so follow-up
+ * `codeloop_interact` / screenshot / video calls hit the SAME device
+ * instead of adb's "whatever single device happens to be attached"
+ * (a hard error with 2+ devices) or simctl's "booted" (ambiguous with
+ * 2+ booted simulators).
+ *
+ * Stored at `.codeloop/active_target.json` in the project root —
+ * deliberately a file (not process memory) because the MCP server can
+ * be restarted between the journey and the agent's follow-up calls.
+ */
+export interface ActiveTarget {
+    target_type: string;
+    /** adb serial (emulator-5554) or simulator UDID. */
+    device_id?: string;
+    /** Human-readable device name when known (e.g. "iPhone 16 Pro"). */
+    device_name?: string;
+    /** App/bundle id when known. */
+    app_id?: string;
+    updated_at: string;
+}
+export declare function saveActiveTarget(projectDir: string, target: Omit<ActiveTarget, "updated_at">): void;
+export declare function loadActiveTarget(projectDir: string): ActiveTarget | null;
+export declare function clearActiveTarget(projectDir: string): void;
+/**
+ * Resolve the device id an interact/screenshot call should use:
+ * explicit param wins, then the persisted active target (only when its
+ * target_type matches the call's resolved target type).
+ */
+export declare function resolveDeviceId(explicit: string | undefined, projectDir: string, targetType: string): string | undefined;
+//# sourceMappingURL=active_target.d.ts.map

package/dist/runners/active_target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active_target.d.ts","sourceRoot":"","sources":["../../src/runners/active_target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,IAAI,CASnG;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAUxE;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAOpB"}

package/dist/runners/active_target.js

@@ -0,0 +1,65 @@
+/**
+ * Persists which device a journey/recording is driving so follow-up
+ * `codeloop_interact` / screenshot / video calls hit the SAME device
+ * instead of adb's "whatever single device happens to be attached"
+ * (a hard error with 2+ devices) or simctl's "booted" (ambiguous with
+ * 2+ booted simulators).
+ *
+ * Stored at `.codeloop/active_target.json` in the project root —
+ * deliberately a file (not process memory) because the MCP server can
+ * be restarted between the journey and the agent's follow-up calls.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "fs";
+import { join } from "path";
+function activeTargetPath(projectDir) {
+    return join(projectDir, ".codeloop", "active_target.json");
+}
+export function saveActiveTarget(projectDir, target) {
+    try {
+        const dir = join(projectDir, ".codeloop");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const payload = { ...target, updated_at: new Date().toISOString() };
+        writeFileSync(activeTargetPath(projectDir), JSON.stringify(payload, null, 2));
+    }
+    catch {
+        // Best-effort — pinning still works for the in-process journey.
+    }
+}
+export function loadActiveTarget(projectDir) {
+    try {
+        const p = activeTargetPath(projectDir);
+        if (!existsSync(p))
+            return null;
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || !parsed.target_type)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearActiveTarget(projectDir) {
+    try {
+        const p = activeTargetPath(projectDir);
+        if (existsSync(p))
+            unlinkSync(p);
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Resolve the device id an interact/screenshot call should use:
+ * explicit param wins, then the persisted active target (only when its
+ * target_type matches the call's resolved target type).
+ */
+export function resolveDeviceId(explicit, projectDir, targetType) {
+    if (explicit && explicit.trim().length > 0)
+        return explicit.trim();
+    const persisted = loadActiveTarget(projectDir);
+    if (persisted?.device_id && persisted.target_type === targetType) {
+        return persisted.device_id;
+    }
+    return undefined;
+}
+//# sourceMappingURL=active_target.js.map

package/dist/runners/active_target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active_target.js","sourceRoot":"","sources":["../../src/runners/active_target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AACpF,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAa5B,SAAS,gBAAgB,CAAC,UAAkB;IAC1C,OAAO,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,oBAAoB,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,MAAwC;IAC3F,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QAC1C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAiB,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;QAClF,aAAa,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAiB,CAAC;QACpE,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAC9E,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,QAA4B,EAC5B,UAAkB,EAClB,UAAkB;IAElB,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,SAAS,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,SAAS,EAAE,SAAS,IAAI,SAAS,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACjE,OAAO,SAAS,CAAC,SAAS,CAAC;IAC7B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/runners/android_sdk.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Android SDK tool resolution (P2.1).
+ *
+ * Android Studio installs the SDK but does NOT put platform-tools on the
+ * shell PATH — `adb` works inside Studio's terminal and fails everywhere
+ * else (a top Windows support issue, but the same applies on macOS/Linux).
+ *
+ * Instead of threading an absolute adb path through the ~40 call sites
+ * (window_manager, screenshot, app_logger, device_probe, app_launcher,
+ * video_recorder, …) we resolve the SDK once at server startup and append
+ * its tool directories to process.env.PATH. Every child process — our own
+ * runCommand/spawn calls AND third-party tools like Maestro that shell out
+ * to adb themselves — inherits the fixed PATH.
+ */
+export interface AndroidSdkResolution {
+    /** Resolved SDK root, or null when no SDK was found. */
+    sdk_root: string | null;
+    /** Where the root came from. */
+    source: "ANDROID_HOME" | "ANDROID_SDK_ROOT" | "default_location" | null;
+    /** Tool directories appended to PATH by this call (empty when adb was already reachable or no SDK found). */
+    dirs_added: string[];
+    /** True when adb was already reachable through PATH before this call. */
+    adb_already_on_path: boolean;
+}
+/** Default per-OS SDK install locations used by Android Studio. */
+export declare function defaultSdkLocations(os?: string, home?: string, env?: NodeJS.ProcessEnv): string[];
+/**
+ * Finds the Android SDK root: ANDROID_HOME, then ANDROID_SDK_ROOT, then
+ * the default Android Studio install location. A candidate only counts
+ * when it actually contains platform-tools/adb.
+ */
+export declare function findAndroidSdkRoot(env?: NodeJS.ProcessEnv, os?: string, home?: string): {
+    root: string;
+    source: AndroidSdkResolution["source"];
+} | null;
+/** SDK subdirectories that hold CLI tools we (or Maestro) invoke. */
+export declare function androidToolDirs(sdkRoot: string): string[];
+/** True when some PATH entry contains the adb binary. */
+export declare function adbOnPath(env?: NodeJS.ProcessEnv, os?: string): boolean;
+/**
+ * Ensures adb/emulator are reachable via PATH, appending the resolved
+ * SDK tool dirs to `env.PATH` when they are not. Idempotent. Returns
+ * what happened so doctor / launch errors can explain the resolution.
+ */
+export declare function ensureAndroidToolsOnPath(env?: NodeJS.ProcessEnv, os?: string, home?: string): AndroidSdkResolution;
+/**
+ * One-line human summary for doctor output / launch failure hints.
+ */
+export declare function describeAndroidSdkResolution(r: AndroidSdkResolution, os?: string): string;
+//# sourceMappingURL=android_sdk.d.ts.map

package/dist/runners/android_sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"android_sdk.d.ts","sourceRoot":"","sources":["../../src/runners/android_sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gCAAgC;IAChC,MAAM,EAAE,cAAc,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACxE,6GAA6G;IAC7G,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yEAAyE;IACzE,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAMD,mEAAmE;AACnE,wBAAgB,mBAAmB,CACjC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CASV;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAAG,IAAI,CAiBjE;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAIzD;AAED,yDAAyD;AACzD,wBAAgB,SAAS,CACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,GACtB,OAAO,CAOT;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,oBAAoB,CA4BtB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,oBAAoB,EAAE,EAAE,GAAE,MAAmB,GAAG,MAAM,CAgBrG"}

package/dist/runners/android_sdk.js

@@ -0,0 +1,123 @@
+/**
+ * Android SDK tool resolution (P2.1).
+ *
+ * Android Studio installs the SDK but does NOT put platform-tools on the
+ * shell PATH — `adb` works inside Studio's terminal and fails everywhere
+ * else (a top Windows support issue, but the same applies on macOS/Linux).
+ *
+ * Instead of threading an absolute adb path through the ~40 call sites
+ * (window_manager, screenshot, app_logger, device_probe, app_launcher,
+ * video_recorder, …) we resolve the SDK once at server startup and append
+ * its tool directories to process.env.PATH. Every child process — our own
+ * runCommand/spawn calls AND third-party tools like Maestro that shell out
+ * to adb themselves — inherits the fixed PATH.
+ */
+import { existsSync } from "fs";
+import { homedir, platform } from "os";
+import { delimiter, join } from "path";
+function adbBinaryName(os) {
+    return os === "win32" ? "adb.exe" : "adb";
+}
+/** Default per-OS SDK install locations used by Android Studio. */
+export function defaultSdkLocations(os = platform(), home = homedir(), env = process.env) {
+    if (os === "win32") {
+        const local = env.LOCALAPPDATA || join(home, "AppData", "Local");
+        return [join(local, "Android", "Sdk")];
+    }
+    if (os === "darwin") {
+        return [join(home, "Library", "Android", "sdk")];
+    }
+    return [join(home, "Android", "Sdk"), join(home, "Android", "sdk")];
+}
+/**
+ * Finds the Android SDK root: ANDROID_HOME, then ANDROID_SDK_ROOT, then
+ * the default Android Studio install location. A candidate only counts
+ * when it actually contains platform-tools/adb.
+ */
+export function findAndroidSdkRoot(env = process.env, os = platform(), home = homedir()) {
+    const adb = adbBinaryName(os);
+    const candidates = [
+        { root: env.ANDROID_HOME, source: "ANDROID_HOME" },
+        { root: env.ANDROID_SDK_ROOT, source: "ANDROID_SDK_ROOT" },
+        ...defaultSdkLocations(os, home, env).map((root) => ({
+            root,
+            source: "default_location",
+        })),
+    ];
+    for (const c of candidates) {
+        if (!c.root)
+            continue;
+        if (existsSync(join(c.root, "platform-tools", adb))) {
+            return { root: c.root, source: c.source };
+        }
+    }
+    return null;
+}
+/** SDK subdirectories that hold CLI tools we (or Maestro) invoke. */
+export function androidToolDirs(sdkRoot) {
+    return [join(sdkRoot, "platform-tools"), join(sdkRoot, "emulator")].filter((d) => existsSync(d));
+}
+/** True when some PATH entry contains the adb binary. */
+export function adbOnPath(env = process.env, os = platform()) {
+    const adb = adbBinaryName(os);
+    const pathVar = env.PATH || env.Path || "";
+    for (const dir of pathVar.split(delimiter)) {
+        if (dir && existsSync(join(dir, adb)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Ensures adb/emulator are reachable via PATH, appending the resolved
+ * SDK tool dirs to `env.PATH` when they are not. Idempotent. Returns
+ * what happened so doctor / launch errors can explain the resolution.
+ */
+export function ensureAndroidToolsOnPath(env = process.env, os = platform(), home = homedir()) {
+    const found = findAndroidSdkRoot(env, os, home);
+    if (adbOnPath(env, os)) {
+        return {
+            sdk_root: found?.root ?? null,
+            source: found?.source ?? null,
+            dirs_added: [],
+            adb_already_on_path: true,
+        };
+    }
+    if (!found) {
+        return { sdk_root: null, source: null, dirs_added: [], adb_already_on_path: false };
+    }
+    const current = (env.PATH || "").split(delimiter).filter(Boolean);
+    const added = [];
+    for (const dir of androidToolDirs(found.root)) {
+        if (!current.includes(dir)) {
+            current.push(dir);
+            added.push(dir);
+        }
+    }
+    env.PATH = current.join(delimiter);
+    return {
+        sdk_root: found.root,
+        source: found.source,
+        dirs_added: added,
+        adb_already_on_path: false,
+    };
+}
+/**
+ * One-line human summary for doctor output / launch failure hints.
+ */
+export function describeAndroidSdkResolution(r, os = platform()) {
+    if (r.adb_already_on_path) {
+        return r.sdk_root
+            ? `adb found on PATH (SDK root: ${r.sdk_root}, via ${r.source})`
+            : "adb found on PATH";
+    }
+    if (r.dirs_added.length > 0) {
+        return `adb was not on PATH — appended ${r.dirs_added.join(", ")} from the ${r.source === "default_location" ? "default Android Studio SDK location" : String(r.source)} (${r.sdk_root})`;
+    }
+    const fix = os === "win32"
+        ? 'set ANDROID_HOME to your SDK (usually %LOCALAPPDATA%\\Android\\Sdk) and add %ANDROID_HOME%\\platform-tools to PATH'
+        : os === "darwin"
+            ? 'set ANDROID_HOME to your SDK (usually ~/Library/Android/sdk) and add $ANDROID_HOME/platform-tools to PATH'
+            : 'set ANDROID_HOME to your SDK (usually ~/Android/Sdk) and add $ANDROID_HOME/platform-tools to PATH';
+    return `adb not found: no Android SDK at ANDROID_HOME, ANDROID_SDK_ROOT, or the default install location. Install Android Studio (or sdkmanager platform-tools), then ${fix}.`;
+}
+//# sourceMappingURL=android_sdk.js.map

package/dist/runners/android_sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"android_sdk.js","sourceRoot":"","sources":["../../src/runners/android_sdk.ts"],"names":[],"mappings":"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"}

package/dist/runners/app_launcher.d.ts

@@ -27,11 +27,69 @@ export interface LaunchAppOptions {
     bootedDevice?: string;
     /** Where to tee launcher stdout/stderr (best-effort). */
     logPath?: string;
-    /** Max time to wait for the app to come up (build can be slow). */
+    /**
+     * HARD CAP on the launch wait (`e2e.launch_timeout_seconds`). The wait is
+     * stall-aware — a build that keeps producing output keeps the wait alive —
+     * so this is the absolute bound, not the expected duration.
+     */
     readyTimeoutMs?: number;
+    /** Fail after this much launcher SILENCE (`e2e.launch_stall_seconds`). */
+    stallTimeoutMs?: number;
     /** Optional extra args (flavor/target/dart-define). */
     extraArgs?: string[];
+    /**
+     * P5.5 (0.1.92) — progress heartbeat while the launcher builds/installs.
+     * Called at most every ~10s with the elapsed wait and the launcher's latest
+     * output line, so a 12-minute cold build reads as visible progress instead
+     * of a hang. Best-effort: callback errors never affect the launch.
+     */
+    onProgress?: (u: {
+        elapsedMs: number;
+        lastLine: string;
+    }) => void;
+    /** P3.1 (0.1.93) — pin the Xcode scheme for native-iOS builds (`e2e.ios_scheme`); skips scheme auto-detection. */
+    iosScheme?: string;
+    /** P3.1 (0.1.93) — Xcode build configuration for native-iOS builds, default "Debug" (`e2e.ios_configuration`). */
+    iosConfiguration?: string;
+    /** P3.2 (0.1.93) — Gradle install task for native-Android builds, e.g. ":app:installDevDebug" (`e2e.gradle_install_task`). */
+    gradleInstallTask?: string;
+    /** P3.2 (0.1.93) — explicit applicationId to launch after install, for flavor/suffix builds (`e2e.android_app_id`). */
+    androidAppId?: string;
 }
+/** Last non-empty output line of a launcher buffer (pure, for heartbeats). */
+export declare function lastOutputLine(buffer: string): string;
+/** Heartbeat throttle: emit when at least intervalMs passed (pure). */
+export declare function shouldEmitHeartbeat(now: number, lastEmitAt: number, intervalMs?: number): boolean;
+/** Why the launch wait stopped (pure helper, unit-testable). */
+export type WaitVerdict = {
+    keep_waiting: true;
+} | {
+    keep_waiting: false;
+    why: "stalled" | "hard_cap";
+};
+/**
+ * Decide whether the ready-wait loop should keep waiting. Pure so the
+ * stall-vs-cap policy is testable without spawning real builds.
+ */
+export declare function shouldKeepWaiting(s: {
+    now: number;
+    startedAt: number;
+    lastOutputAt: number;
+    stallMs: number;
+    hardCapMs: number;
+}): WaitVerdict;
+/**
+ * 0.1.90 (P0.2) — reuse the verify-phase build. A full verify on a mobile
+ * Flutter project already built the app (`flutter build ios --simulator` /
+ * gradle); relaunching via plain `flutter run` then rebuilds from scratch —
+ * the second 12-minute build WedCheese hit. When a FRESH prebuilt binary
+ * exists (newer than the newest source edit, minus a 60s jitter buffer),
+ * launch with `flutter run --use-application-binary <path>` instead.
+ *
+ * iOS accepts a .app bundle directory; Android the debug APK (both verified
+ * against flutter_tools' IOSApp.fromPrebuiltApp / ApplicationPackageFactory).
+ */
+export declare function findFreshPrebuilt(cwd: string, target: JourneyTarget): string | null;
 /**
  * Launch the app for an interactive journey. Returns a handle whose `stop()`
  * quits the app. Only the Flutter path actually builds+launches today; native

package/dist/runners/app_launcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app_launcher.d.ts","sourceRoot":"","sources":["../../src/runners/app_launcher.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAUD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY3F;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,CAAC;IACtB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAID;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAehF;AAKD,2EAA2E;AAC3E,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAW5D;AA0JD,+EAA+E;AAC/E,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYlE;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE"}
+{"version":3,"file":"app_launcher.d.ts","sourceRoot":"","sources":["../../src/runners/app_launcher.ts"],"names":[],"mappings":"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"}