strikethroo 3.0.1 → 3.1.0

package/dist/serve/derivation.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Per-plan derivation layer for the serve data layer.
+ *
+ * Scans a plan directory's `tasks/*.md` into structured task records, computes
+ * the derived plan lifecycle state (`drafted` -> `ready` -> `doing` -> `done`)
+ * with done/total counts, and resolves execution phases (from a blueprint
+ * document when present, otherwise inferred from task `group` + `dependencies`).
+ *
+ * Everything is synchronous and read-only: file reads only, no watches, no
+ * network, no writes.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePhases = exports.inferPhases = exports.parseBlueprintPhases = exports.deriveState = exports.scanTasks = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const markdown_1 = require("./markdown");
+const STATUS_DONE = 'completed';
+const STATUS_NOT_STARTED = 'pending';
+/** Reads a plan directory's `tasks/*.md` into structured records. Missing dir -> []. */
+const scanTasks = (planDir) => {
+    const tasksDir = path.join(planDir, 'tasks');
+    let entries;
+    try {
+        entries = fs.readdirSync(tasksDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter(e => e.isFile() && e.name.endsWith('.md'))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .flatMap(e => {
+        const filePath = path.join(tasksDir, e.name);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const fm = (0, markdown_1.parseFrontmatter)(content);
+        const body = (0, markdown_1.extractBody)(content);
+        const dependencies = fm.dependencies
+            .map(d => (typeof d === 'number' ? d : parseInt(d, 10)))
+            .filter((d) => !Number.isNaN(d));
+        return [
+            {
+                id: fm.id,
+                name: (0, markdown_1.extractTitle)(body) ?? e.name.replace(/\.md$/, ''),
+                group: fm.group,
+                dependencies,
+                status: fm.status,
+                skills: fm.skills,
+                file: e.name,
+                body,
+                sections: (0, markdown_1.sectionBody)(body).sections,
+            },
+        ];
+    });
+};
+exports.scanTasks = scanTasks;
+/** Classifies a task status. Unknown/in-progress values count as "started". */
+const classify = (status) => {
+    if (status === STATUS_DONE)
+        return 'done';
+    if (status === STATUS_NOT_STARTED)
+        return 'notStarted';
+    return 'started';
+};
+/**
+ * Computes the derived plan state and counts. Never throws on unknown statuses.
+ *
+ * - empty list -> `drafted`
+ * - tasks present, none started or done -> `ready`
+ * - all done -> `done`
+ * - otherwise -> `doing`
+ */
+const deriveState = (tasks) => {
+    const total = tasks.length;
+    if (total === 0) {
+        return { state: 'drafted', done: 0, total: 0 };
+    }
+    let done = 0;
+    let started = 0;
+    for (const task of tasks) {
+        const klass = classify(task.status);
+        if (klass === 'done') {
+            done += 1;
+            started += 1;
+        }
+        else if (klass === 'started') {
+            started += 1;
+        }
+    }
+    let state;
+    if (done === total) {
+        state = 'done';
+    }
+    else if (started === 0) {
+        state = 'ready';
+    }
+    else {
+        state = 'doing';
+    }
+    return { state, done, total };
+};
+exports.deriveState = deriveState;
+const BLUEPRINT_SECTION_RE = /^##[ \t]+Execution Blueprint[ \t]*$/m;
+const PHASE_HEADING_RE = /^###[ \t]+(?:✅[ \t]*)?Phase[ \t]+(\d+)[ \t]*:?[ \t]*(.*?)[ \t]*$/gm;
+const TASK_REF_RE = /Task[ \t]+0*(\d+)/i;
+/**
+ * Parses phases from an "## Execution Blueprint" section if the plan body
+ * contains one. Returns undefined when no blueprint section is present.
+ */
+const parseBlueprintPhases = (planBody) => {
+    const sectionMatch = planBody.match(BLUEPRINT_SECTION_RE);
+    if (!sectionMatch || sectionMatch.index === undefined)
+        return undefined;
+    const blueprint = planBody.slice(sectionMatch.index);
+    const headings = [];
+    PHASE_HEADING_RE.lastIndex = 0;
+    let m;
+    while ((m = PHASE_HEADING_RE.exec(blueprint)) !== null) {
+        headings.push({
+            index: m.index,
+            afterHeading: m.index + m[0].length,
+            name: (m[2] ?? '').trim(),
+        });
+    }
+    if (headings.length === 0)
+        return undefined;
+    const phases = [];
+    for (let i = 0; i < headings.length; i++) {
+        const current = headings[i];
+        const next = headings[i + 1];
+        const end = next ? next.index : blueprint.length;
+        const segment = blueprint.slice(current.afterHeading, end);
+        const taskIds = [];
+        for (const line of segment.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            // Only consider bulleted task references to avoid matching prose.
+            if (!trimmed.startsWith('-') && !trimmed.startsWith('*'))
+                continue;
+            const ref = trimmed.match(TASK_REF_RE);
+            if (ref && ref[1] !== undefined) {
+                const id = parseInt(ref[1], 10);
+                if (!Number.isNaN(id) && !taskIds.includes(id))
+                    taskIds.push(id);
+            }
+        }
+        phases.push({
+            index: i + 1,
+            name: current.name.length > 0 ? current.name : undefined,
+            taskIds,
+            parallel: taskIds.length > 1,
+        });
+    }
+    return phases;
+};
+exports.parseBlueprintPhases = parseBlueprintPhases;
+/**
+ * Infers phases from tasks by grouping on satisfied dependencies. Tasks whose
+ * dependencies are all already emitted (or absent from the task set) form a
+ * phase; dependents fall into later phases. Best-effort and cycle-safe: if no
+ * progress is made, the remaining tasks are emitted as a final phase rather
+ * than looping forever. Never throws.
+ */
+const inferPhases = (tasks) => {
+    const withIds = tasks.filter((t) => typeof t.id === 'number');
+    if (withIds.length === 0)
+        return [];
+    const idSet = new Set(withIds.map(t => t.id));
+    const emitted = new Set();
+    const phases = [];
+    let remaining = [...withIds];
+    while (remaining.length > 0) {
+        const ready = remaining.filter(t => t.dependencies.every(dep => !idSet.has(dep) || emitted.has(dep)));
+        const batch = ready.length > 0 ? ready : remaining; // no progress -> emit the rest
+        const taskIds = batch.map(t => t.id);
+        phases.push({
+            index: phases.length + 1,
+            taskIds,
+            parallel: taskIds.length > 1,
+        });
+        for (const id of taskIds)
+            emitted.add(id);
+        remaining = remaining.filter(t => !emitted.has(t.id));
+    }
+    return phases;
+};
+exports.inferPhases = inferPhases;
+/**
+ * Resolves a plan's phases: parses a blueprint document's phase list when the
+ * plan body contains one, otherwise infers phases from task dependencies.
+ */
+const resolvePhases = (planBody, tasks) => {
+    const fromBlueprint = (0, exports.parseBlueprintPhases)(planBody);
+    if (fromBlueprint && fromBlueprint.length > 0)
+        return fromBlueprint;
+    return (0, exports.inferPhases)(tasks);
+};
+exports.resolvePhases = resolvePhases;
+//# sourceMappingURL=derivation.js.map

package/dist/serve/derivation.js.map

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

package/dist/serve/events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Server-Sent Events change stream for `npx strikethroo serve`.
+ *
+ * Provides `GET /api/events`: a `text/event-stream` that broadcasts a single
+ * coalesced `changed` ping whenever the workspace mutates on disk. The event
+ * carries no diff payload — clients refetch the affected API data (the browser
+ * consumer is a later plan).
+ *
+ * Exposes an {@link EventsHub} that owns the connected-client set and the
+ * workspace watcher, plus an `ApiHandler` the server registers so this module
+ * stays decoupled from routing. Connections are cleaned up on disconnect so no
+ * listeners or sockets leak. Node built-ins only.
+ */
+import * as http from 'http';
+/**
+ * Owns the SSE client set and the workspace watcher. One hub per server. Start
+ * the watcher with {@link start} after the server is listening; release it with
+ * {@link close} when the server closes.
+ */
+export declare class EventsHub {
+    private readonly workspaceDir;
+    private readonly debounceMs?;
+    private readonly clients;
+    private watcher;
+    constructor(workspaceDir: string, debounceMs?: number | undefined);
+    /** Begins watching the workspace; coalesced changes broadcast to all clients. */
+    start(): void;
+    /** Stops the watcher and ends every open client connection. */
+    close(): void;
+    /** Number of currently connected SSE clients (used by tests). */
+    get clientCount(): number;
+    /** Sends a single coalesced `changed` event to every connected client. */
+    private broadcast;
+    /** Attaches an SSE response: writes headers, registers cleanup on close. */
+    handleConnection(req: http.IncomingMessage, res: http.ServerResponse): void;
+    /** An {@link ApiHandler} for `GET /api/events`; returns false otherwise. */
+    apiHandler: (req: http.IncomingMessage, res: http.ServerResponse, ctx: {
+        pathname: string;
+    }) => boolean;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/serve/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/serve/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAM7B;;;;GAIG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAL9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,OAAO,CAAiC;gBAG7B,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,YAAA;IAGtC,iFAAiF;IACjF,KAAK,IAAI,IAAI;IASb,+DAA+D;IAC/D,KAAK,IAAI,IAAI;IAWb,iEAAiE;IACjE,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,0EAA0E;IAC1E,OAAO,CAAC,SAAS;IAMjB,4EAA4E;IAC5E,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,GAAG,IAAI;IAyB3E,4EAA4E;IAC5E,UAAU,GACR,KAAK,IAAI,CAAC,eAAe,EACzB,KAAK,IAAI,CAAC,cAAc,EACxB,KAAK;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KACxB,OAAO,CAMR;CACH"}

package/dist/serve/events.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Server-Sent Events change stream for `npx strikethroo serve`.
+ *
+ * Provides `GET /api/events`: a `text/event-stream` that broadcasts a single
+ * coalesced `changed` ping whenever the workspace mutates on disk. The event
+ * carries no diff payload — clients refetch the affected API data (the browser
+ * consumer is a later plan).
+ *
+ * Exposes an {@link EventsHub} that owns the connected-client set and the
+ * workspace watcher, plus an `ApiHandler` the server registers so this module
+ * stays decoupled from routing. Connections are cleaned up on disconnect so no
+ * listeners or sockets leak. Node built-ins only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsHub = void 0;
+const watcher_1 = require("./watcher");
+/** Keep-alive comment interval (ms) to hold idle proxies/streams open. */
+const KEEP_ALIVE_MS = 15000;
+/**
+ * Owns the SSE client set and the workspace watcher. One hub per server. Start
+ * the watcher with {@link start} after the server is listening; release it with
+ * {@link close} when the server closes.
+ */
+class EventsHub {
+    constructor(workspaceDir, debounceMs) {
+        this.workspaceDir = workspaceDir;
+        this.debounceMs = debounceMs;
+        this.clients = new Set();
+        this.watcher = null;
+        /** An {@link ApiHandler} for `GET /api/events`; returns false otherwise. */
+        this.apiHandler = (req, res, ctx) => {
+            if (ctx.pathname === '/api/events' || ctx.pathname === '/api/events/') {
+                this.handleConnection(req, res);
+                return true;
+            }
+            return false;
+        };
+    }
+    /** Begins watching the workspace; coalesced changes broadcast to all clients. */
+    start() {
+        if (this.watcher)
+            return;
+        this.watcher = (0, watcher_1.createWorkspaceWatcher)(this.workspaceDir, () => this.broadcast(), this.debounceMs);
+    }
+    /** Stops the watcher and ends every open client connection. */
+    close() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        for (const res of this.clients) {
+            res.end();
+        }
+        this.clients.clear();
+    }
+    /** Number of currently connected SSE clients (used by tests). */
+    get clientCount() {
+        return this.clients.size;
+    }
+    /** Sends a single coalesced `changed` event to every connected client. */
+    broadcast() {
+        for (const res of this.clients) {
+            res.write('event: changed\ndata: {}\n\n');
+        }
+    }
+    /** Attaches an SSE response: writes headers, registers cleanup on close. */
+    handleConnection(req, res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        // Initial comment opens the stream and flushes headers to the client.
+        res.write(': connected\n\n');
+        this.clients.add(res);
+        const keepAlive = setInterval(() => {
+            res.write(': keep-alive\n\n');
+        }, KEEP_ALIVE_MS);
+        // Don't let the keep-alive timer hold the event loop / process open.
+        keepAlive.unref?.();
+        const cleanup = () => {
+            clearInterval(keepAlive);
+            this.clients.delete(res);
+        };
+        req.on('close', cleanup);
+        res.on('close', cleanup);
+    }
+}
+exports.EventsHub = EventsHub;
+//# sourceMappingURL=events.js.map

package/dist/serve/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/serve/events.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAGH,uCAAqE;AAErE,0EAA0E;AAC1E,MAAM,aAAa,GAAG,KAAK,CAAC;AAE5B;;;;GAIG;AACH,MAAa,SAAS;IAIpB,YACmB,YAAoB,EACpB,UAAmB;QADnB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,eAAU,GAAV,UAAU,CAAS;QALrB,YAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;QAClD,YAAO,GAA4B,IAAI,CAAC;QAmEhD,4EAA4E;QAC5E,eAAU,GAAG,CACX,GAAyB,EACzB,GAAwB,EACxB,GAAyB,EAChB,EAAE;YACX,IAAI,GAAG,CAAC,QAAQ,KAAK,aAAa,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;gBACtE,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;IAzEC,CAAC;IAEJ,iFAAiF;IACjF,KAAK;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAA,gCAAsB,EACnC,IAAI,CAAC,YAAY,EACjB,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EACtB,IAAI,CAAC,UAAU,CAChB,CAAC;IACJ,CAAC;IAED,+DAA+D;IAC/D,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/B,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,iEAAiE;IACjE,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,0EAA0E;IAClE,SAAS;QACf,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/B,GAAG,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,gBAAgB,CAAC,GAAyB,EAAE,GAAwB;QAClE,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;YACjB,cAAc,EAAE,mBAAmB;YACnC,eAAe,EAAE,UAAU;YAC3B,UAAU,EAAE,YAAY;SACzB,CAAC,CAAC;QACH,sEAAsE;QACtE,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAE7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEtB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAChC,CAAC,EAAE,aAAa,CAAC,CAAC;QAClB,qEAAqE;QACrE,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;QAEpB,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,aAAa,CAAC,SAAS,CAAC,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC;QACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC;CAcF;AAjFD,8BAiFC"}

package/dist/serve/markdown.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure, dependency-light markdown parsing primitives for the serve data layer.
+ *
+ * These functions operate on already-read string content. File reading itself
+ * belongs to the task scanner and the model assembler. Everything here is
+ * synchronous, read-only, and side-effect-free: no `fs`, no network, no writes.
+ *
+ * The existing `src/skill-scripts/shared/frontmatter.ts` only recovers the
+ * numeric `id`; it is intentionally not forked. This module provides a richer
+ * frontmatter reader the UI needs (summary, created, status, group,
+ * dependencies[], skills[]).
+ */
+/**
+ * Parsed frontmatter. All fields are optional because real-world files vary and
+ * malformed/missing frontmatter must degrade gracefully rather than throw.
+ * `extra` retains any scalar keys not covered by the typed fields.
+ */
+export interface ParsedFrontmatter {
+    id?: number;
+    summary?: string;
+    created?: string;
+    status?: string;
+    group?: string;
+    dependencies: Array<number | string>;
+    skills: string[];
+    extra: Record<string, string>;
+}
+/** A named `## ` section of a markdown body. */
+export interface MarkdownSection {
+    /** Heading text (the remainder of the `## ` line, trimmed). */
+    heading: string;
+    /** Section content from just after the heading line up to the next `## ` or EOF. */
+    content: string;
+    /** Character offset of the heading start within the body. */
+    start: number;
+    /** Character offset of the section end (exclusive) within the body. */
+    end: number;
+}
+/** Result of sectioning a markdown body. */
+export interface SectionedBody {
+    /** Everything after the closing frontmatter `---`, verbatim. */
+    rawBody: string;
+    /** Ordered list of `## ` sections. */
+    sections: MarkdownSection[];
+}
+/** A single extracted mermaid fenced block. */
+export interface MermaidBlock {
+    /** Raw mermaid source (inner content of the fenced block). */
+    source: string;
+    /** True when the block falls within an "Architectural Approach" section. */
+    isArchitecturalApproach: boolean;
+}
+/**
+ * Reads the leading frontmatter block into typed fields. Never throws: malformed
+ * lines are skipped and absent keys fall back to defaults (undefined scalars,
+ * empty arrays).
+ */
+export declare const parseFrontmatter: (content: string) => ParsedFrontmatter;
+/** Returns the body: everything after the closing frontmatter `---`, or the whole content. */
+export declare const extractBody: (content: string) => string;
+/**
+ * Splits a markdown body into the verbatim `rawBody` plus an ordered list of
+ * `## ` sections addressable by heading text. Section access is additive:
+ * callers may always fall back to `rawBody`.
+ */
+export declare const sectionBody: (body: string) => SectionedBody;
+/**
+ * Extracts every fenced ```mermaid block's raw source from a body. Blocks whose
+ * position falls within an "Architectural Approach" section are flagged. Plans
+ * with no mermaid block yield an empty list (never an error).
+ */
+export declare const extractMermaidBlocks: (body: string) => MermaidBlock[];
+/** Returns the text of the first `# ` (level-1) heading in a body, or undefined. */
+export declare const extractTitle: (body: string) => string | undefined;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/serve/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/serve/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,uBAAuB,EAAE,OAAO,CAAC;CAClC;AAwCD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,iBAqFlD,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,MAI7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,aA6B1C,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,YAAY,EAmB/D,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAGpD,CAAC"}