@lumenflow/core 3.1.3 → 3.2.1

package/dist/package-manager-resolver.js

@@ -0,0 +1,193 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Package Manager and Test Runner Resolution
+ *
+ * WU-2037: Extracted from gates-config.ts
+ *
+ * Resolves package manager, test runner, build commands, gates commands,
+ * and ignore patterns from workspace.yaml software_delivery configuration.
+ *
+ * @module package-manager-resolver
+ */
+import { asRecord, isString } from './object-guards.js';
+import { GATES_RUNTIME_DEFAULTS, SOFTWARE_DELIVERY_FIELDS, GATES_FIELDS, GATES_COMMAND_FIELDS, loadSoftwareDeliveryConfig, getGatesSection, } from './gates-config-internal.js';
+// ---------------------------------------------------------------------------
+// Supported values
+// ---------------------------------------------------------------------------
+const SUPPORTED_PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
+const SUPPORTED_TEST_RUNNERS = ['vitest', 'jest', 'mocha'];
+// ---------------------------------------------------------------------------
+// Default command tables
+// ---------------------------------------------------------------------------
+/**
+ * WU-1356: Default gates commands by package manager
+ *
+ * Provides sensible defaults for different package manager and test runner combinations.
+ */
+const DEFAULT_GATES_COMMANDS = {
+    pnpm: {
+        test_full: 'pnpm turbo run test',
+        test_docs_only: '',
+        test_incremental: 'pnpm vitest run --changed origin/main',
+        lint: 'pnpm lint',
+        typecheck: 'pnpm typecheck',
+        format: 'pnpm format:check',
+    },
+    npm: {
+        test_full: 'npm test',
+        test_docs_only: '',
+        test_incremental: 'npm test -- --onlyChanged',
+        lint: 'npm run lint',
+        typecheck: 'npm run typecheck',
+        format: 'npm run format:check',
+    },
+    yarn: {
+        test_full: 'yarn test',
+        test_docs_only: '',
+        test_incremental: 'yarn test --onlyChanged',
+        lint: 'yarn lint',
+        typecheck: 'yarn typecheck',
+        format: 'yarn format:check',
+    },
+    bun: {
+        test_full: 'bun test',
+        test_docs_only: '',
+        test_incremental: 'bun test --changed',
+        lint: 'bun run lint',
+        typecheck: 'bun run typecheck',
+        format: 'bun run format:check',
+    },
+};
+/**
+ * WU-1356: Default build commands by package manager
+ */
+const DEFAULT_BUILD_COMMANDS = {
+    pnpm: 'pnpm --filter @lumenflow/cli build',
+    npm: 'npm run build --workspace @lumenflow/cli',
+    yarn: 'yarn workspace @lumenflow/cli build',
+    bun: 'bun run --filter @lumenflow/cli build',
+};
+/**
+ * WU-1356: Ignore patterns by test runner
+ *
+ * Different test runners use different cache directories that should be ignored.
+ */
+const IGNORE_PATTERNS_BY_RUNNER = {
+    vitest: ['.turbo'],
+    jest: ['coverage', '.jest-cache'],
+    mocha: ['coverage', '.nyc_output'],
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * WU-1356: Resolve package manager from configuration
+ *
+ * Reads the package_manager field from workspace.yaml software_delivery.
+ * Returns 'pnpm' as default if not configured.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved package manager ('pnpm', 'npm', 'yarn', or 'bun')
+ */
+export function resolvePackageManager(projectRoot) {
+    const softwareDelivery = loadSoftwareDeliveryConfig(projectRoot);
+    if (!softwareDelivery) {
+        return GATES_RUNTIME_DEFAULTS.DEFAULT_PACKAGE_MANAGER;
+    }
+    const pm = softwareDelivery[SOFTWARE_DELIVERY_FIELDS.PACKAGE_MANAGER] ??
+        softwareDelivery[SOFTWARE_DELIVERY_FIELDS.PACKAGE_MANAGER_CAMEL];
+    if (isString(pm) && SUPPORTED_PACKAGE_MANAGERS.includes(pm)) {
+        return pm;
+    }
+    return GATES_RUNTIME_DEFAULTS.DEFAULT_PACKAGE_MANAGER;
+}
+/**
+ * WU-1356: Resolve test runner from configuration
+ *
+ * Reads the test_runner field from workspace.yaml software_delivery.
+ * Returns 'vitest' as default if not configured.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved test runner ('vitest', 'jest', or 'mocha')
+ */
+export function resolveTestRunner(projectRoot) {
+    const softwareDelivery = loadSoftwareDeliveryConfig(projectRoot);
+    if (!softwareDelivery) {
+        return GATES_RUNTIME_DEFAULTS.DEFAULT_TEST_RUNNER;
+    }
+    const runner = softwareDelivery[SOFTWARE_DELIVERY_FIELDS.TEST_RUNNER] ??
+        softwareDelivery[SOFTWARE_DELIVERY_FIELDS.TEST_RUNNER_CAMEL];
+    if (isString(runner) && SUPPORTED_TEST_RUNNERS.includes(runner)) {
+        return runner;
+    }
+    return GATES_RUNTIME_DEFAULTS.DEFAULT_TEST_RUNNER;
+}
+/**
+ * WU-1356: Resolve build command from configuration
+ *
+ * Reads the build_command field from workspace.yaml software_delivery.
+ * If not configured, uses default based on package_manager.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved build command
+ */
+export function resolveBuildCommand(projectRoot) {
+    const defaultPm = resolvePackageManager(projectRoot);
+    const softwareDelivery = loadSoftwareDeliveryConfig(projectRoot);
+    if (!softwareDelivery) {
+        return DEFAULT_BUILD_COMMANDS[defaultPm];
+    }
+    const configuredBuildCommand = softwareDelivery[SOFTWARE_DELIVERY_FIELDS.BUILD_COMMAND] ??
+        softwareDelivery[SOFTWARE_DELIVERY_FIELDS.BUILD_COMMAND_CAMEL];
+    if (isString(configuredBuildCommand) && configuredBuildCommand.length > 0) {
+        return configuredBuildCommand;
+    }
+    return DEFAULT_BUILD_COMMANDS[defaultPm];
+}
+/**
+ * WU-1356: Resolve gates commands from configuration
+ *
+ * Reads gates.commands from workspace.yaml software_delivery.
+ * Merges with defaults based on package_manager if not fully specified.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved gates commands configuration
+ */
+export function resolveGatesCommands(projectRoot) {
+    const pm = resolvePackageManager(projectRoot);
+    const defaults = DEFAULT_GATES_COMMANDS[pm];
+    const gates = getGatesSection(projectRoot);
+    if (!gates) {
+        return defaults;
+    }
+    const commands = asRecord(gates[GATES_FIELDS.COMMANDS]);
+    if (!commands) {
+        return defaults;
+    }
+    // Merge user config with defaults (user config wins)
+    return {
+        test_full: commands[GATES_COMMAND_FIELDS.TEST_FULL] ?? defaults.test_full,
+        test_docs_only: commands[GATES_COMMAND_FIELDS.TEST_DOCS_ONLY] ??
+            defaults.test_docs_only,
+        test_incremental: commands[GATES_COMMAND_FIELDS.TEST_INCREMENTAL] ??
+            defaults.test_incremental,
+        lint: commands[GATES_COMMAND_FIELDS.LINT] ?? defaults.lint,
+        typecheck: commands[GATES_COMMAND_FIELDS.TYPECHECK] ?? defaults.typecheck,
+        format: commands[GATES_COMMAND_FIELDS.FORMAT] ?? defaults.format,
+    };
+}
+/**
+ * WU-1356: Get ignore patterns for test runner
+ *
+ * Returns patterns to ignore when detecting changed tests,
+ * based on the test runner configuration.
+ *
+ * @param testRunner - Test runner type (vitest, jest, mocha)
+ * @returns Array of ignore patterns
+ */
+export function getIgnorePatterns(testRunner) {
+    return (IGNORE_PATTERNS_BY_RUNNER[testRunner] ??
+        IGNORE_PATTERNS_BY_RUNNER[GATES_RUNTIME_DEFAULTS.DEFAULT_TEST_RUNNER]);
+}
+//# sourceMappingURL=package-manager-resolver.js.map

package/dist/package-manager-resolver.js.map

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

package/dist/path-classifiers.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Path Classification Utilities for WU Tooling
+ *
+ * WU-1255: Classifies file paths to determine test scoping.
+ * Uses string methods (no regex) for path prefix matching.
+ *
+ * Paths that skip web app tests:
+ * - Documentation: docs/, ai/, .claude/, README*, CLAUDE*.md
+ * - Tooling: tools/, scripts/
+ *
+ * @see {@link ./wu-done-paths.js} - Consumer for detectDocsOnlyByPaths
+ */
+/**
+ * Prefixes for paths that should skip web app tests.
+ * These are paths for docs, tooling, and configuration that don't affect app functionality.
+ *
+ * @constant {string[]}
+ */
+export declare const SKIP_TESTS_PREFIXES: readonly string[];
+/**
+ * Root file patterns that should skip web app tests.
+ * These are files in the root directory that are documentation.
+ *
+ * @constant {string[]}
+ */
+export declare const SKIP_TESTS_ROOT_FILES: readonly string[];
+/**
+ * Check if a single file path should skip web app tests.
+ *
+ * Uses string methods for matching:
+ * - `startsWith` for directory prefixes (docs/, tools/, etc.)
+ * - `toLowerCase` for case-insensitive root file matching
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if path should skip web app tests
+ *
+ * @example
+ * isSkipWebTestsPath('docs/README.md') // true
+ * isSkipWebTestsPath('tools/wu-done.js') // true
+ * isSkipWebTestsPath('apps/web/src/page.tsx') // false
+ */
+export declare function isSkipWebTestsPath(filePath: UnsafeAny): boolean;
+/**
+ * Check if ALL code paths should skip web app tests.
+ *
+ * Returns true only if EVERY path in the array is a skip-tests path.
+ * This is the aggregate check for WU YAML code_paths array.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if all paths should skip web app tests
+ *
+ * @example
+ * shouldSkipWebTests(['docs/README.md', 'tools/wu-done.js']) // true
+ * shouldSkipWebTests(['docs/README.md', 'apps/web/src/page.tsx']) // false
+ */
+export declare function shouldSkipWebTests(codePaths: UnsafeAny): boolean;
+//# sourceMappingURL=path-classifiers.d.ts.map

package/dist/path-classifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-classifiers.d.ts","sourceRoot":"","sources":["../src/path-classifiers.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mBAM9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,mBAGhC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,WA0BrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,WAMtD"}

package/dist/path-classifiers.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Path Classification Utilities for WU Tooling
+ *
+ * WU-1255: Classifies file paths to determine test scoping.
+ * Uses string methods (no regex) for path prefix matching.
+ *
+ * Paths that skip web app tests:
+ * - Documentation: docs/, ai/, .claude/, README*, CLAUDE*.md
+ * - Tooling: tools/, scripts/
+ *
+ * @see {@link ./wu-done-paths.js} - Consumer for detectDocsOnlyByPaths
+ */
+/**
+ * Prefixes for paths that should skip web app tests.
+ * These are paths for docs, tooling, and configuration that don't affect app functionality.
+ *
+ * @constant {string[]}
+ */
+export const SKIP_TESTS_PREFIXES = Object.freeze([
+    'docs/',
+    'ai/',
+    '.claude/',
+    'tools/', // WU-1255: Tooling WUs
+    'scripts/', // WU-1255: Scripts WUs
+]);
+/**
+ * Root file patterns that should skip web app tests.
+ * These are files in the root directory that are documentation.
+ *
+ * @constant {string[]}
+ */
+export const SKIP_TESTS_ROOT_FILES = Object.freeze([
+    'readme', // Case-insensitive match
+    'claude', // CLAUDE.md, CLAUDE-core.md, etc.
+]);
+/**
+ * Check if a single file path should skip web app tests.
+ *
+ * Uses string methods for matching:
+ * - `startsWith` for directory prefixes (docs/, tools/, etc.)
+ * - `toLowerCase` for case-insensitive root file matching
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if path should skip web app tests
+ *
+ * @example
+ * isSkipWebTestsPath('docs/README.md') // true
+ * isSkipWebTestsPath('tools/wu-done.js') // true
+ * isSkipWebTestsPath('apps/web/src/page.tsx') // false
+ */
+export function isSkipWebTestsPath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    const path = filePath.trim();
+    if (path.length === 0) {
+        return false;
+    }
+    // Check directory prefixes (docs/, ai/, .claude/, tools/, scripts/)
+    for (const prefix of SKIP_TESTS_PREFIXES) {
+        if (path.startsWith(prefix)) {
+            return true;
+        }
+    }
+    // Check root file patterns (README*, CLAUDE*.md)
+    const lowerPath = path.toLowerCase();
+    for (const pattern of SKIP_TESTS_ROOT_FILES) {
+        if (lowerPath.startsWith(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if ALL code paths should skip web app tests.
+ *
+ * Returns true only if EVERY path in the array is a skip-tests path.
+ * This is the aggregate check for WU YAML code_paths array.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if all paths should skip web app tests
+ *
+ * @example
+ * shouldSkipWebTests(['docs/README.md', 'tools/wu-done.js']) // true
+ * shouldSkipWebTests(['docs/README.md', 'apps/web/src/page.tsx']) // false
+ */
+export function shouldSkipWebTests(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return false;
+    }
+    return codePaths.every((path) => isSkipWebTestsPath(path));
+}
+//# sourceMappingURL=path-classifiers.js.map

package/dist/path-classifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-classifiers.js","sourceRoot":"","sources":["../src/path-classifiers.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AACzC;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,OAAO;IACP,KAAK;IACL,UAAU;IACV,QAAQ,EAAE,uBAAuB;IACjC,UAAU,EAAE,uBAAuB;CACpC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,QAAQ,EAAE,yBAAyB;IACnC,QAAQ,EAAE,kCAAkC;CAC7C,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAmB;IACpD,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,oEAAoE;IACpE,KAAK,MAAM,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACzC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,KAAK,MAAM,OAAO,IAAI,qBAAqB,EAAE,CAAC;QAC5C,IAAI,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAoB;IACrD,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/patrol-loop.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Patrol Loop Module (WU-1242)
+ *
+ * Continuous patrol loop for monitoring spawn health.
+ * The 'Witness patrol' pattern - keeps the spawn fleet healthy by
+ * checking status at configurable intervals with exponential backoff
+ * on repeated failures.
+ *
+ * Features:
+ * - Configurable patrol interval (default 5min)
+ * - Exponential backoff on failures (max 1hr)
+ * - Graceful shutdown support
+ * - Cycle callbacks for status reporting
+ * - Error handling with continuation
+ *
+ * @see {@link packages/@lumenflow/cli/src/orchestrate-monitor.ts} - CLI integration
+ * @see {@link packages/@lumenflow/core/src/__tests__/patrol-loop.test.ts} - Tests
+ */
+/**
+ * Default patrol interval (5 minutes in milliseconds)
+ */
+export declare const DEFAULT_PATROL_INTERVAL_MS: number;
+/**
+ * Maximum backoff interval (1 hour in milliseconds)
+ */
+export declare const MAX_BACKOFF_MS: number;
+/**
+ * Result of a patrol check
+ */
+export interface PatrolCheckResult {
+    /** Whether the spawn fleet is healthy (no stuck spawns or zombies) */
+    healthy: boolean;
+    /** Number of stuck spawns detected */
+    stuckCount: number;
+    /** Number of zombie locks detected */
+    zombieCount: number;
+    /** Optional suggestions for recovery */
+    suggestions?: string[];
+}
+/**
+ * Metadata passed to cycle callbacks
+ */
+export interface CycleMetadata {
+    /** The cycle number (1-indexed) */
+    cycleNumber: number;
+    /** Current interval in milliseconds */
+    intervalMs: number;
+    /** Number of consecutive failures */
+    consecutiveFailures: number;
+    /** Timestamp of the cycle */
+    timestamp: Date;
+}
+/**
+ * Callback invoked on each patrol cycle
+ */
+export type OnCycleCallback = (result: PatrolCheckResult, meta: CycleMetadata) => void;
+/**
+ * Callback invoked when an error occurs
+ */
+export type OnErrorCallback = (error: Error, cycleNumber: number) => void;
+/**
+ * Options for creating a PatrolLoop
+ */
+export interface PatrolLoopOptions {
+    /**
+     * Function to check spawn health
+     */
+    checkFn: () => Promise<PatrolCheckResult>;
+    /**
+     * Patrol interval in milliseconds (default: 5 minutes)
+     */
+    intervalMs?: number;
+    /**
+     * Callback invoked after each patrol cycle
+     */
+    onCycle?: OnCycleCallback;
+    /**
+     * Callback invoked when checkFn throws an error
+     */
+    onError?: OnErrorCallback;
+}
+/**
+ * Calculates the backoff interval based on consecutive failures.
+ * Uses exponential backoff with a maximum of 1 hour.
+ *
+ * Backoff formula: baseInterval * 2^(failures-1), capped at MAX_BACKOFF_MS
+ *
+ * @param consecutiveFailures - Number of consecutive failures (1-indexed)
+ * @param baseIntervalMs - Base interval in milliseconds
+ * @returns Backoff interval in milliseconds
+ *
+ * @example
+ * calculateBackoff(1, 5*60*1000) // 5 minutes (no backoff yet)
+ * calculateBackoff(2, 5*60*1000) // 10 minutes (2x)
+ * calculateBackoff(3, 5*60*1000) // 20 minutes (4x)
+ */
+export declare function calculateBackoff(consecutiveFailures: number, baseIntervalMs: number): number;
+/**
+ * Patrol loop for continuous spawn monitoring.
+ *
+ * @example
+ * const patrol = new PatrolLoop({
+ *   checkFn: async () => {
+ *     const result = await runMonitor();
+ *     return {
+ *       healthy: result.stuckSpawns.length === 0,
+ *       stuckCount: result.stuckSpawns.length,
+ *       zombieCount: result.zombieLocks.length,
+ *     };
+ *   },
+ *   intervalMs: 5 * 60 * 1000, // 5 minutes
+ *   onCycle: (result, meta) => {
+ *     console.log(`Cycle ${meta.cycleNumber}: ${result.healthy ? 'healthy' : 'issues detected'}`);
+ *   },
+ * });
+ *
+ * patrol.start();
+ * // Later...
+ * patrol.stop();
+ */
+export declare class PatrolLoop {
+    private readonly checkFn;
+    private readonly baseIntervalMs;
+    private readonly onCycle?;
+    private readonly onError?;
+    private timer;
+    private running;
+    private failures;
+    private cycles;
+    /**
+     * Creates a new PatrolLoop instance.
+     *
+     * @param options - Patrol loop configuration
+     */
+    constructor(options: PatrolLoopOptions);
+    /**
+     * The configured base interval in milliseconds.
+     */
+    get intervalMs(): number;
+    /**
+     * Whether the patrol loop is currently running.
+     */
+    get isRunning(): boolean;
+    /**
+     * Number of consecutive failures (resets on success).
+     */
+    get consecutiveFailures(): number;
+    /**
+     * Total number of completed patrol cycles.
+     */
+    get totalCycles(): number;
+    /**
+     * Starts the patrol loop.
+     * Does nothing if already running.
+     */
+    start(): void;
+    /**
+     * Stops the patrol loop.
+     * Safe to call even if not running.
+     */
+    stop(): void;
+    /**
+     * Schedules the next patrol cycle.
+     */
+    private scheduleNextCycle;
+    /**
+     * Runs a single patrol cycle.
+     */
+    private runCycle;
+}
+//# sourceMappingURL=patrol-loop.d.ts.map

package/dist/patrol-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patrol-loop.d.ts","sourceRoot":"","sources":["../src/patrol-loop.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B,QAAgB,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,cAAc,QAAiB,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE1C;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,mBAAmB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAW5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkB;IAE3C,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;OAIG;gBACS,OAAO,EAAE,iBAAiB;IAOtC;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IASb;;;OAGG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;YACW,QAAQ;CAkCvB"}