@mrpatronz/nexusflow 0.2.19 → 1.3.0

package/dist/core/analysis-cache.js

@@ -0,0 +1,116 @@
+/**
+ * @module core/analysis-cache
+ * Persists per-repo analysis results in `.nexusflow-analysis-cache.json` at
+ * the workspace root, keyed by a git content fingerprint (HEAD SHA plus a
+ * signature of dirty files). Lets refresh/sync re-analyze only repos whose
+ * content actually changed, keeping unchanged maps byte-identical — which
+ * avoids file churn and preserves AI assistants' prompt caches (token saving).
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execa } from 'execa';
+/** Name of the analysis cache file, written at the workspace root. */
+const CACHE_FILE = '.nexusflow-analysis-cache.json';
+/**
+ * Returns the path to the analysis cache file for a workspace.
+ */
+export function getAnalysisCachePath(workspacePath) {
+    return path.join(workspacePath, CACHE_FILE);
+}
+/**
+ * Loads the analysis cache, returning an empty skeleton when the file does
+ * not exist or cannot be parsed.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ */
+export async function loadAnalysisCache(workspacePath) {
+    try {
+        const raw = await fs.readFile(getAnalysisCachePath(workspacePath), 'utf-8');
+        const cache = JSON.parse(raw);
+        if (!cache.repos || typeof cache.repos !== 'object') {
+            cache.repos = {};
+        }
+        return cache;
+    }
+    catch {
+        return { version: 1, repos: {} };
+    }
+}
+/**
+ * Saves the analysis cache, pruning entries for repos that are no longer in
+ * the given list of current repo names.
+ *
+ * @param workspacePath    - Absolute path to the workspace root.
+ * @param cache            - The cache to persist.
+ * @param currentRepoNames - Names of repos currently in the workspace; when
+ *                           provided, entries for other repos are dropped.
+ */
+export async function saveAnalysisCache(workspacePath, cache, currentRepoNames) {
+    if (currentRepoNames) {
+        for (const name of Object.keys(cache.repos)) {
+            if (!currentRepoNames.includes(name)) {
+                delete cache.repos[name];
+            }
+        }
+    }
+    const data = JSON.stringify(cache, null, 2) + '\n';
+    await fs.writeFile(getAnalysisCachePath(workspacePath), data, 'utf-8');
+}
+/**
+ * Strips the surrounding quotes git adds to porcelain paths containing
+ * special characters.
+ */
+function unquotePorcelainPath(p) {
+    if (p.startsWith('"') && p.endsWith('"')) {
+        return p.slice(1, -1);
+    }
+    return p;
+}
+/**
+ * Computes a content fingerprint for a repo: the HEAD commit SHA, extended
+ * with a hash of the dirty working-tree files (status line + size + mtime per
+ * file) when the tree is not clean. Editing, adding, or deleting an
+ * uncommitted file therefore changes the fingerprint too.
+ *
+ * @param repoPath - Absolute path to the repo root.
+ * @returns The fingerprint, or null when git fails (caller should re-analyze).
+ */
+export async function getRepoFingerprint(repoPath) {
+    try {
+        const { stdout: shaOut } = await execa('git', ['rev-parse', 'HEAD'], {
+            cwd: repoPath,
+        });
+        const sha = shaOut.trim();
+        const { stdout: statusOut } = await execa('git', ['status', '--porcelain'], {
+            cwd: repoPath,
+        });
+        const lines = statusOut.split('\n').filter(Boolean);
+        if (lines.length === 0) {
+            return sha;
+        }
+        let dirtySignature = '';
+        for (const line of lines) {
+            const rel = line.slice(3).trim();
+            // Rename lines look like "R  old -> new"; stat the new path.
+            const target = rel.includes(' -> ') ? rel.split(' -> ').pop() : rel;
+            const filePath = path.join(repoPath, unquotePorcelainPath(target));
+            try {
+                const st = await fs.stat(filePath);
+                dirtySignature += `${line}|${st.size}|${Math.floor(st.mtimeMs)}\n`;
+            }
+            catch {
+                dirtySignature += `${line}|missing\n`;
+            }
+        }
+        const dirtyHash = createHash('sha1')
+            .update(dirtySignature)
+            .digest('hex')
+            .slice(0, 12);
+        return `${sha}+${dirtyHash}`;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=analysis-cache.js.map

package/dist/core/analysis-cache.js.map

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

package/dist/core/analysis-cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analysis-cache.test.d.ts.map

package/dist/core/analysis-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-cache.test.d.ts","sourceRoot":"","sources":["../../src/core/analysis-cache.test.ts"],"names":[],"mappings":""}

package/dist/core/analysis-cache.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import { execa } from 'execa';
+import { loadAnalysisCache, saveAnalysisCache, getRepoFingerprint, } from './analysis-cache.js';
+vi.mock('node:fs/promises');
+vi.mock('execa');
+const mockAnalysis = {
+    name: 'repo-1',
+    path: '/ws/repo-1',
+    techStack: { languages: ['typescript'], frameworks: [], buildTools: [], projectType: 'backend' },
+    endpoints: [],
+    dependencies: [],
+    ports: [],
+    readmeSummary: null,
+    existingAIConfigs: [],
+};
+/** Parses the JSON written by the most recent writeFile call. */
+function lastWritten() {
+    const calls = vi.mocked(fs.writeFile).mock.calls;
+    const data = calls[calls.length - 1][1];
+    return JSON.parse(data);
+}
+describe('analysis-cache', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+    });
+    describe('loadAnalysisCache', () => {
+        it('returns an empty skeleton when the file is absent', async () => {
+            vi.mocked(fs.readFile).mockRejectedValue(new Error('ENOENT'));
+            const cache = await loadAnalysisCache('/ws');
+            expect(cache.version).toBe(1);
+            expect(cache.repos).toEqual({});
+        });
+        it('round-trips an existing cache file', async () => {
+            const existing = {
+                version: 1,
+                repos: {
+                    'repo-1': {
+                        repoName: 'repo-1',
+                        fingerprint: 'abc123',
+                        analyzedAt: '2026-01-01T00:00:00.000Z',
+                        analysis: mockAnalysis,
+                    },
+                },
+            };
+            vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(existing));
+            const cache = await loadAnalysisCache('/ws');
+            expect(cache.repos['repo-1'].fingerprint).toBe('abc123');
+            expect(cache.repos['repo-1'].analysis.name).toBe('repo-1');
+        });
+    });
+    describe('saveAnalysisCache', () => {
+        it('prunes entries for repos no longer in the workspace', async () => {
+            const cache = {
+                version: 1,
+                repos: {
+                    'repo-1': { repoName: 'repo-1', fingerprint: 'a', analyzedAt: '', analysis: mockAnalysis },
+                    'removed-repo': { repoName: 'removed-repo', fingerprint: 'b', analyzedAt: '', analysis: mockAnalysis },
+                },
+            };
+            await saveAnalysisCache('/ws', cache, ['repo-1']);
+            const written = lastWritten();
+            expect(written.repos['repo-1']).toBeDefined();
+            expect(written.repos['removed-repo']).toBeUndefined();
+        });
+    });
+    describe('getRepoFingerprint', () => {
+        it('returns the bare HEAD SHA for a clean tree', async () => {
+            vi.mocked(execa).mockImplementation((async (_cmd, args) => {
+                if (args[0] === 'rev-parse')
+                    return { stdout: 'abc123\n' };
+                return { stdout: '' }; // clean status
+            }));
+            const fp = await getRepoFingerprint('/ws/repo-1');
+            expect(fp).toBe('abc123');
+        });
+        it('extends the SHA with a dirty-files hash when the tree is dirty', async () => {
+            vi.mocked(execa).mockImplementation((async (_cmd, args) => {
+                if (args[0] === 'rev-parse')
+                    return { stdout: 'abc123\n' };
+                return { stdout: ' M src/file1.ts\n' };
+            }));
+            vi.mocked(fs.stat).mockResolvedValue({ size: 100, mtimeMs: 1000 });
+            const fp = await getRepoFingerprint('/ws/repo-1');
+            expect(fp).toMatch(/^abc123\+[0-9a-f]{12}$/);
+        });
+        it('changes the fingerprint when a dirty file is edited', async () => {
+            vi.mocked(execa).mockImplementation((async (_cmd, args) => {
+                if (args[0] === 'rev-parse')
+                    return { stdout: 'abc123\n' };
+                return { stdout: ' M src/file1.ts\n' };
+            }));
+            vi.mocked(fs.stat).mockResolvedValue({ size: 100, mtimeMs: 1000 });
+            const before = await getRepoFingerprint('/ws/repo-1');
+            vi.mocked(fs.stat).mockResolvedValue({ size: 150, mtimeMs: 2000 });
+            const after = await getRepoFingerprint('/ws/repo-1');
+            expect(before).not.toBe(after);
+            expect(before).not.toBe('abc123');
+        });
+        it('returns null when git fails', async () => {
+            vi.mocked(execa).mockRejectedValue(new Error('not a git repository'));
+            const fp = await getRepoFingerprint('/not-a-repo');
+            expect(fp).toBeNull();
+        });
+    });
+});
+//# sourceMappingURL=analysis-cache.test.js.map

package/dist/core/analysis-cache.test.js.map

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

package/dist/core/refresh.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module core/refresh
+ * Headless workspace refresh — regenerates context files, maps, and plans for
+ * a workspace using the analysis cache, so only repos whose content changed
+ * are re-analyzed and only their maps are rewritten. Backs the CLI command,
+ * the HTTP API, and the scheduler alike.
+ */
+/** Options for a headless refresh run. */
+export interface RefreshOptions {
+    /** Restrict regeneration to a single repo (by directory name). */
+    onlyRepo?: string;
+    /** Only refresh base-layer maps and codebase knowledge. */
+    baseOnly?: boolean;
+    /** Ignore the analysis cache and re-analyze every repo. */
+    force?: boolean;
+}
+/** Outcome of a headless refresh run. */
+export interface RefreshReport {
+    /** Absolute path to the workspace. */
+    workspacePath: string;
+    /** Names of repos that were re-analyzed because their content changed. */
+    analyzedRepos: string[];
+    /** Names of repos whose cached analysis was reused. */
+    reusedRepos: string[];
+    /** Whether the handoff bundle was refreshed too. */
+    refreshedHandoff: boolean;
+}
+/**
+ * Refreshes a workspace's context files, maps, and plans. Throws if the
+ * workspace configuration cannot be loaded.
+ *
+ * Token-saving behavior: repos with an unchanged git fingerprint reuse their
+ * cached analysis and keep their existing map files byte-identical, so AI
+ * assistants' prompt caches stay valid across refreshes.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ * @param options       - Refresh options.
+ * @returns A report of what was analyzed vs reused.
+ */
+export declare function refreshWorkspace(workspacePath: string, options?: RefreshOptions): Promise<RefreshReport>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/core/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/core/refresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uDAAuD;IACvD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oDAAoD;IACpD,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAoDxB"}

package/dist/core/refresh.js

@@ -0,0 +1,60 @@
+/**
+ * @module core/refresh
+ * Headless workspace refresh — regenerates context files, maps, and plans for
+ * a workspace using the analysis cache, so only repos whose content changed
+ * are re-analyzed and only their maps are rewritten. Backs the CLI command,
+ * the HTTP API, and the scheduler alike.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { loadFeatureConfig } from './workspace.js';
+import { analyzeAllReposCached } from '../analyzers/index.js';
+import { generateContextFiles } from '../generators/index.js';
+/**
+ * Refreshes a workspace's context files, maps, and plans. Throws if the
+ * workspace configuration cannot be loaded.
+ *
+ * Token-saving behavior: repos with an unchanged git fingerprint reuse their
+ * cached analysis and keep their existing map files byte-identical, so AI
+ * assistants' prompt caches stay valid across refreshes.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ * @param options       - Refresh options.
+ * @returns A report of what was analyzed vs reused.
+ */
+export async function refreshWorkspace(workspacePath, options = {}) {
+    const feature = await loadFeatureConfig(workspacePath);
+    if (!feature) {
+        throw new Error(`Failed to load workspace configuration. Ensure nexusflow.json exists at ${workspacePath}.`);
+    }
+    const allRepos = feature.repos.map((r) => ({
+        name: path.basename(r),
+        path: r,
+        defaultBranch: 'main',
+    }));
+    const { analysis, analyzed, reused } = await analyzeAllReposCached(allRepos, workspacePath, { force: options.force });
+    const ctx = { feature, repos: allRepos, analysis };
+    await generateContextFiles(ctx, feature.assistants, workspacePath, options.onlyRepo, options.baseOnly, options.force ? undefined : analyzed);
+    // If a handoff bundle exists, refresh it too — it reuses the cached
+    // analysis, so this no longer triggers a second full analysis pass.
+    let refreshedHandoff = false;
+    const handoffPath = path.join(workspacePath, 'nexusflow-handoff.md');
+    if (!options.baseOnly) {
+        try {
+            await fs.access(handoffPath);
+            const { handoffCommand } = await import('../commands/handoff.js');
+            await handoffCommand(workspacePath);
+            refreshedHandoff = true;
+        }
+        catch {
+            // No handoff file, or refresh failed — non-fatal either way.
+        }
+    }
+    return {
+        workspacePath,
+        analyzedRepos: analyzed,
+        reusedRepos: reused,
+        refreshedHandoff,
+    };
+}
+//# sourceMappingURL=refresh.js.map

package/dist/core/refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.js","sourceRoot":"","sources":["../../src/core/refresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAyB9D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,aAAqB,EACrB,UAA0B,EAAE;IAE5B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACvD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,2EAA2E,aAAa,GAAG,CAC5F,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtB,IAAI,EAAE,CAAC;QACP,aAAa,EAAE,MAAM;KACtB,CAAC,CAAC,CAAC;IAEJ,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,qBAAqB,CAChE,QAAQ,EACR,aAAa,EACb,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CACzB,CAAC;IAEF,MAAM,GAAG,GAAqB,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAErE,MAAM,oBAAoB,CACxB,GAAG,EACH,OAAO,CAAC,UAAU,EAClB,aAAa,EACb,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CACrC,CAAC;IAEF,oEAAoE;IACpE,oEAAoE;IACpE,IAAI,gBAAgB,GAAG,KAAK,CAAC;IAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAC7B,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;YAClE,MAAM,cAAc,CAAC,aAAa,CAAC,CAAC;YACpC,gBAAgB,GAAG,IAAI,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;QAC/D,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa;QACb,aAAa,EAAE,QAAQ;QACvB,WAAW,EAAE,MAAM;QACnB,gBAAgB;KACjB,CAAC;AACJ,CAAC"}

package/dist/core/scheduler.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @module core/scheduler
+ * Recurring workspace jobs — periodic `sync` and `refresh` runs per workspace.
+ *
+ * Job definitions are persisted at `~/.nexusflow/schedules.json` and executed
+ * by any long-running NexusFlow process (the dashboard server started with
+ * `nexusflow ui` runs the scheduler automatically). Jobs use the headless
+ * cores (`syncWorkspace`, `refreshWorkspace`), which are cache-aware: a
+ * scheduled run only re-analyzes repos whose content changed, so unattended
+ * schedules stay token-efficient and never churn unchanged context files.
+ */
+/** Kinds of work a schedule can run. */
+export type ScheduleTask = 'sync' | 'refresh';
+/** A persisted recurring job definition. */
+export interface ScheduledJob {
+    /** Unique job id, e.g. 'sync-my-feature-k3x9q2'. */
+    id: string;
+    /** Absolute path to the workspace the job operates on. */
+    workspacePath: string;
+    /** What the job runs. */
+    task: ScheduleTask;
+    /** How often the job runs, in minutes. */
+    intervalMinutes: number;
+    /** Disabled jobs are kept but never run. */
+    enabled: boolean;
+    /** ISO timestamp of when the job was created. */
+    createdAt: string;
+    /** ISO timestamp of the last run, if any. */
+    lastRunAt?: string;
+    /** Outcome of the last run. */
+    lastStatus?: 'success' | 'error';
+    /** Human-readable summary of the last run. */
+    lastMessage?: string;
+}
+/** On-disk shape of the schedules file. */
+export interface ScheduleStore {
+    version: 1;
+    jobs: ScheduledJob[];
+}
+/** Result of running a single job. */
+export interface JobRunResult {
+    status: 'success' | 'error';
+    message: string;
+}
+/**
+ * Returns the path to the schedules file (~/.nexusflow/schedules.json).
+ */
+export declare function getSchedulesPath(): string;
+/**
+ * Loads all schedules, returning an empty store when the file does not exist
+ * or cannot be parsed.
+ */
+export declare function loadSchedules(): Promise<ScheduleStore>;
+/**
+ * Persists the schedule store to ~/.nexusflow/schedules.json.
+ */
+export declare function saveSchedules(store: ScheduleStore): Promise<void>;
+/**
+ * Parses a human interval like '30m', '2h', '1d', or a bare minute count
+ * ('45') into minutes. Returns null for unparseable or non-positive input.
+ */
+export declare function parseInterval(text: string): number | null;
+/**
+ * Formats an interval in minutes back to a compact human string.
+ */
+export declare function formatInterval(minutes: number): string;
+/**
+ * Whether a job is due to run: it is enabled and either never ran or its
+ * interval has elapsed since the last run. A job whose interval elapsed while
+ * no scheduler was running simply runs on the next tick.
+ */
+export declare function isDue(job: ScheduledJob, now?: Date): boolean;
+/**
+ * Computes when a job will next be due, for display purposes.
+ */
+export declare function nextDueAt(job: ScheduledJob): Date | null;
+/**
+ * Adds a new schedule and persists it.
+ *
+ * @param input - Workspace, task, and interval for the new job.
+ * @returns The created job.
+ */
+export declare function addSchedule(input: {
+    workspacePath: string;
+    task: ScheduleTask;
+    intervalMinutes: number;
+}): Promise<ScheduledJob>;
+/**
+ * Removes a schedule by id. Returns false when no job matched.
+ */
+export declare function removeSchedule(id: string): Promise<boolean>;
+/**
+ * Enables or disables a schedule by id. Returns the updated job, or null
+ * when no job matched.
+ */
+export declare function setScheduleEnabled(id: string, enabled: boolean): Promise<ScheduledJob | null>;
+/**
+ * Runs a single job immediately and records the outcome in the store.
+ * Never throws — failures are captured in the returned result.
+ *
+ * @param job - The job to run.
+ * @returns The classified outcome with a summary message.
+ */
+export declare function runJob(job: ScheduledJob): Promise<JobRunResult>;
+/**
+ * Starts the scheduler loop inside the current process. Every tick it
+ * re-loads the schedules file (so jobs added/removed via CLI are picked up
+ * without a restart) and runs all due jobs sequentially. Ticks never overlap.
+ *
+ * @param options - Tick interval (default 60s) and an optional log sink.
+ * @returns A stop function that clears the interval.
+ */
+export declare function startScheduler(options?: {
+    tickMs?: number;
+    log?: (message: string) => void;
+}): () => void;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/core/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/core/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9C,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IACjC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAW5D;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAezD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAItD;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAQxE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAMxD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,YAAY,CAAC,CAgBxB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOjE;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAO9B;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA2CrE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,GAAG,MAAM,IAAI,CA8BlB"}