@rasensio/aidlc 1.20.0 → 1.21.0

package/dist/roadmap/sync/execute.js

@@ -0,0 +1,164 @@
+/**
+ * Apply a plan. The only module in this feature that writes anything to GitHub.
+ *
+ * It imports no `node:fs` — deliberately, and pinned by a test. `sync` writes nothing to
+ * disk, and the cheapest way to keep that true is for the writing module to have no
+ * ability to. Snapshotting a directory around a run would be the weaker check: cost
+ * capture writes into `.aidlc/` during a session, so a whole-tree snapshot is either
+ * flaky or has to exclude so much that it stops proving anything.
+ *
+ * A `create` is **one** invocation carrying the discovery label, the status label, and the
+ * body marker. If the label were applied by a second call, a process death between the two
+ * would strand an issue invisible to discovery — which the next run would duplicate. One
+ * invocation makes the issue discoverable the instant it exists, and that atomicity is
+ * what the whole no-local-state design rests on.
+ *
+ * Execution **aborts on the first failure**. A rate limit or an authorization failure will
+ * fail everything after it too, so continuing would turn one legible error into forty.
+ *
+ * Requirements: roadmap-issue-projection/AC-23, roadmap-issue-projection/AC-41,
+ * roadmap-issue-projection/AC-42, roadmap-issue-projection/AC-43,
+ * roadmap-issue-projection/AC-46
+ *
+ * @module
+ */
+import { renderIssueBody } from './body.js';
+import { firstLine, repoArgs } from './gh.js';
+import { colorFor, descriptionFor } from './labels.js';
+import { isWrite } from './types.js';
+export function applyPlan(gh, plan, discoveryLabel) {
+    const writes = plan.lines.filter((l) => isWrite(l.outcome));
+    const applied = [];
+    const ensured = new Set();
+    for (let i = 0; i < writes.length; i++) {
+        const line = writes[i];
+        const labelFailure = ensureLabels(gh, plan, line, discoveryLabel, ensured);
+        if (labelFailure !== null) {
+            return { applied, failure: { line, error: labelFailure }, notAttempted: writes.slice(i) };
+        }
+        const result = gh.run(invocationFor(plan, line, discoveryLabel));
+        if (!result.ok) {
+            return {
+                applied,
+                failure: { line, error: firstLine(result.error) },
+                notAttempted: writes.slice(i + 1),
+            };
+        }
+        applied.push(line);
+    }
+    return { applied, failure: null, notAttempted: [] };
+}
+/** The `gh` argv for one write outcome. */
+export function invocationFor(plan, line, discoveryLabel) {
+    const repo = [...repoArgs(plan.repo)];
+    switch (line.outcome) {
+        case 'create': {
+            if (line.item === null)
+                throw new Error('create without an item');
+            return [
+                'issue',
+                'create',
+                ...repo,
+                '--title',
+                line.item.title,
+                '--body',
+                renderIssueBody(line.item),
+                '--label',
+                discoveryLabel,
+                ...line.addLabels.flatMap((l) => ['--label', l]),
+            ];
+        }
+        case 'update-title': {
+            if (line.item === null || line.issueNumber === null) {
+                throw new Error('update-title without an item and issue');
+            }
+            return ['issue', 'edit', String(line.issueNumber), ...repo, '--title', line.item.title];
+        }
+        case 'update-labels': {
+            if (line.issueNumber === null)
+                throw new Error('update-labels without an issue');
+            // --add-label / --remove-label, never a wholesale --label: a human's labels on a
+            // projected issue are theirs, and replacing the set would silently delete them.
+            return [
+                'issue',
+                'edit',
+                String(line.issueNumber),
+                ...repo,
+                ...line.addLabels.flatMap((l) => ['--add-label', l]),
+                ...line.removeLabels.flatMap((l) => ['--remove-label', l]),
+            ];
+        }
+        case 'close': {
+            if (line.issueNumber === null)
+                throw new Error('close without an issue');
+            return ['issue', 'close', String(line.issueNumber), ...repo];
+        }
+        default:
+            throw new Error(`not a write outcome: ${line.outcome}`);
+    }
+}
+/**
+ * Create every label this line needs, once per run.
+ *
+ * `gh label create` **exits 1 when the label already exists**, so bare creation plus
+ * abort-on-first-failure would kill every run after the first. `--force` fixes that — but
+ * `gh` chooses a *random* colour when none is given, so `--force` alone would repaint the
+ * label on every run. The colour and description are therefore always passed, from a fixed
+ * table, which makes the ensure genuinely idempotent rather than merely non-failing.
+ */
+function ensureLabels(gh, plan, line, discoveryLabel, ensured) {
+    const needed = line.outcome === 'create' ? [discoveryLabel, ...line.addLabels] : [...line.addLabels];
+    for (const name of needed) {
+        if (ensured.has(name))
+            continue;
+        const result = gh.run([
+            'label',
+            'create',
+            name,
+            ...repoArgs(plan.repo),
+            '--color',
+            colorFor(name),
+            '--description',
+            descriptionFor(name),
+            '--force',
+        ]);
+        if (!result.ok) {
+            return `could not create the label ${JSON.stringify(name)}: ${firstLine(result.error)}`;
+        }
+        ensured.add(name);
+    }
+    return null;
+}
+/** Render an execution report for stdout. */
+export function renderExecReport(report) {
+    const out = [];
+    if (report.applied.length > 0) {
+        out.push(`Applied ${report.applied.length} write${report.applied.length === 1 ? '' : 's'}:`);
+        for (const l of report.applied)
+            out.push(`  ${l.outcome} ${subjectOf(l)}`);
+    }
+    else {
+        out.push('No writes were applied.');
+    }
+    if (report.failure !== null) {
+        out.push('');
+        out.push(`Stopped at ${report.failure.line.outcome} ${subjectOf(report.failure.line)}`);
+        out.push(`  gh said: ${report.failure.error}`);
+        if (report.notAttempted.length > 0) {
+            out.push(`  ${report.notAttempted.length} further write(s) were not attempted:`);
+            for (const l of report.notAttempted)
+                out.push(`    ${l.outcome} ${subjectOf(l)}`);
+        }
+        out.push('');
+        out.push('Re-run once the cause is fixed — the projection is idempotent, so completed writes are not repeated.');
+    }
+    return out.join('\n');
+}
+function subjectOf(line) {
+    if (line.item !== null) {
+        return `${line.item.status}/${line.item.filename}` +
+            (line.issueNumber === null ? '' : ` (#${line.issueNumber})`);
+    }
+    return `#${line.issueNumber}`;
+}
+//# sourceMappingURL=execute.js.map

package/dist/roadmap/sync/execute.js.map

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

package/dist/roadmap/sync/gh.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The single subprocess boundary between this feature and the `gh` CLI.
+ *
+ * Every `gh` invocation in the projection goes through `GhRunner.run(args)`, and
+ * `args` is an array. That is structural rather than habitual on purpose: item titles
+ * and config values come from tracked files, so in a cloned repo they are the repo
+ * author's strings, not the user's. With one seam there is no call site for somebody
+ * in a hurry to add a template string or `shell: true` to, and the fake runner used in
+ * tests records every argv — which is what lets the token-secrecy property be checked
+ * by *value* (set `GH_TOKEN` to a sentinel, assert it appears in no recorded argv)
+ * rather than by grepping the source for a variable name. This project has broken
+ * prose-scoped greps six separate times.
+ *
+ * Nothing here reads `GH_TOKEN` or `GITHUB_TOKEN`. `gh` owns the credential; this
+ * module owns the argv.
+ *
+ * Requirements: roadmap-issue-projection/AC-30, roadmap-issue-projection/AC-50
+ *
+ * @module
+ */
+export type GhResult = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    error: string;
+    exitCode: number | null;
+};
+export interface GhRunner {
+    run(args: readonly string[]): GhResult;
+}
+/**
+ * 256 MiB.
+ *
+ * `execFileSync` defaults to 1 MiB, and discovery asks for every projected issue's
+ * body so the marker can be read. Measured: the default throws `ENOBUFS` at roughly
+ * 2 MiB of output, which a few hundred issues with ordinary bodies will exceed — two
+ * orders of magnitude below the 1000-issue map this feature otherwise supports. The
+ * failure is a thrown error rather than a truncated read, so it would be loud; it
+ * would also be entirely avoidable, which is why the limit is stated.
+ */
+export declare const GH_MAX_BUFFER: number;
+/** The real runner. Argument array, no shell, explicit buffer. */
+export declare function realGhRunner(): GhRunner;
+/**
+ * Check that `gh` is present and authenticated.
+ *
+ * **Authentication only.** `gh auth status` cannot tell whether the token may write
+ * issues on the target repository, so a token that is authenticated but not authorized
+ * passes here and fails on the first write — where `applyPlan` names the item and
+ * prints `gh`'s own message. Claiming otherwise would put the check in the wrong
+ * place and make the first-run failure less legible, not more.
+ */
+export declare function ghPreflight(gh: GhRunner): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** First non-empty line of a `gh` message, for one-line error reporting. */
+export declare function firstLine(text: string): string;
+/** `['--repo', repo]` when a coordinate was resolved, else `[]`. */
+export declare function repoArgs(repo: string | null): readonly string[];
+//# sourceMappingURL=gh.d.ts.map

package/dist/roadmap/sync/gh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gh.d.ts","sourceRoot":"","sources":["../../../src/roadmap/sync/gh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,MAAM,QAAQ,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,QAAoB,CAAC;AAE/C,kEAAkE;AAClE,wBAAgB,YAAY,IAAI,QAAQ,CAkBvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CASrF;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,MAAM,EAAE,CAE/D"}

package/dist/roadmap/sync/gh.js

@@ -0,0 +1,86 @@
+/**
+ * The single subprocess boundary between this feature and the `gh` CLI.
+ *
+ * Every `gh` invocation in the projection goes through `GhRunner.run(args)`, and
+ * `args` is an array. That is structural rather than habitual on purpose: item titles
+ * and config values come from tracked files, so in a cloned repo they are the repo
+ * author's strings, not the user's. With one seam there is no call site for somebody
+ * in a hurry to add a template string or `shell: true` to, and the fake runner used in
+ * tests records every argv — which is what lets the token-secrecy property be checked
+ * by *value* (set `GH_TOKEN` to a sentinel, assert it appears in no recorded argv)
+ * rather than by grepping the source for a variable name. This project has broken
+ * prose-scoped greps six separate times.
+ *
+ * Nothing here reads `GH_TOKEN` or `GITHUB_TOKEN`. `gh` owns the credential; this
+ * module owns the argv.
+ *
+ * Requirements: roadmap-issue-projection/AC-30, roadmap-issue-projection/AC-50
+ *
+ * @module
+ */
+import { execFileSync } from 'node:child_process';
+/**
+ * 256 MiB.
+ *
+ * `execFileSync` defaults to 1 MiB, and discovery asks for every projected issue's
+ * body so the marker can be read. Measured: the default throws `ENOBUFS` at roughly
+ * 2 MiB of output, which a few hundred issues with ordinary bodies will exceed — two
+ * orders of magnitude below the 1000-issue map this feature otherwise supports. The
+ * failure is a thrown error rather than a truncated read, so it would be loud; it
+ * would also be entirely avoidable, which is why the limit is stated.
+ */
+export const GH_MAX_BUFFER = 256 * 1024 * 1024;
+/** The real runner. Argument array, no shell, explicit buffer. */
+export function realGhRunner() {
+    return {
+        run(args) {
+            try {
+                const stdout = execFileSync('gh', [...args], {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    maxBuffer: GH_MAX_BUFFER,
+                });
+                return { ok: true, stdout };
+            }
+            catch (err) {
+                const e = err;
+                const stderr = typeof e.stderr === 'string' ? e.stderr : e.stderr?.toString('utf8');
+                const message = (stderr ?? e.message ?? 'gh invocation failed').trim();
+                return { ok: false, error: message, exitCode: e.status ?? null };
+            }
+        },
+    };
+}
+/**
+ * Check that `gh` is present and authenticated.
+ *
+ * **Authentication only.** `gh auth status` cannot tell whether the token may write
+ * issues on the target repository, so a token that is authenticated but not authorized
+ * passes here and fails on the first write — where `applyPlan` names the item and
+ * prints `gh`'s own message. Claiming otherwise would put the check in the wrong
+ * place and make the first-run failure less legible, not more.
+ */
+export function ghPreflight(gh) {
+    const result = gh.run(['auth', 'status']);
+    if (result.ok)
+        return { ok: true };
+    return {
+        ok: false,
+        error: 'gh is not available or not authenticated — install the GitHub CLI and run ' +
+            `\`gh auth login\`, then try again.\n  gh said: ${firstLine(result.error)}`,
+    };
+}
+/** First non-empty line of a `gh` message, for one-line error reporting. */
+export function firstLine(text) {
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return text.trim();
+}
+/** `['--repo', repo]` when a coordinate was resolved, else `[]`. */
+export function repoArgs(repo) {
+    return repo === null ? [] : ['--repo', repo];
+}
+//# sourceMappingURL=gh.js.map

package/dist/roadmap/sync/gh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gh.js","sourceRoot":"","sources":["../../../src/roadmap/sync/gh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUlD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C,kEAAkE;AAClE,MAAM,UAAU,YAAY;IAC1B,OAAO;QACL,GAAG,CAAC,IAAuB;YACzB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;oBAC3C,QAAQ,EAAE,MAAM;oBAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;oBACjC,SAAS,EAAE,aAAa;iBACzB,CAAC,CAAC;gBACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;YAC9B,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,GAA6E,CAAC;gBACxF,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACpF,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,sBAAsB,CAAC,CAAC,IAAI,EAAE,CAAC;gBACvE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YACnE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,EAAY;IACtC,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACnC,OAAO;QACL,EAAE,EAAE,KAAK;QACT,KAAK,EACH,4EAA4E;YAC5E,kDAAkD,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;KAC9E,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;AACrB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,QAAQ,CAAC,IAAmB;IAC1C,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/dist/roadmap/sync/import.d.ts

@@ -0,0 +1,73 @@
+/**
+ * One-shot import: a GitHub issue seeds a roadmap item.
+ *
+ * Import, not sync. Nothing reconciles afterwards, nothing is written back to the issue,
+ * and running it twice over the same issue is reported rather than duplicated.
+ *
+ * The `title` is **always** double-quoted, with no judgement call about whether this one
+ * needs it. An unquoted YAML plain scalar may not begin with a reserved indicator
+ * character, so the single most natural way to name a code defect — an identifier in
+ * backticks — does not parse; and nothing reports it, because an item that will not parse
+ * and an item that was never written look identical. Five of this project's first 49 items
+ * were lost that way for up to ten days, and GitHub issue titles are precisely the corpus
+ * that produces them.
+ *
+ * Requirements: roadmap-issue-projection/AC-51 … roadmap-issue-projection/AC-60
+ *
+ * @module
+ */
+import { type GhRunner } from './gh.js';
+/** A GitHub issue, reduced to what identifies it. */
+export interface IssueCoord {
+    host: string;
+    owner: string;
+    repo: string;
+    number: number;
+}
+export type ImportResult = {
+    kind: 'written';
+    path: string;
+} | {
+    kind: 'duplicate';
+    existing: string;
+    coord: IssueCoord;
+} | {
+    kind: 'refused';
+    error: string;
+};
+/** Slug used when a title yields nothing usable. */
+export declare const FALLBACK_SLUG_PREFIX = "imported-issue";
+/**
+ * Parse an issue reference into a comparable tuple.
+ *
+ * Normalising is the point: `https://github.com/o/r/issues/12`, the same with a trailing
+ * slash, with a `#issuecomment-…` fragment, with `www.`, and the
+ * `api.github.com/repos/o/r/issues/12` form all denote one issue. Comparing raw strings
+ * would report false duplicates in one direction and miss real ones in the other — and a
+ * naive substring compare makes `issues/1` match `issues/12`.
+ */
+export declare function parseIssueUrl(raw: string): IssueCoord | null;
+/** Canonical string form of a coordinate, for map keys. */
+export declare function coordKey(coord: IssueCoord): string;
+/**
+ * Every issue already linked by a roadmap item, keyed by coordinate.
+ *
+ * This reads item **bodies**, which the roadmap skill's frontmatter-only rule otherwise
+ * discourages. That rule governs *browse*, which is a list and must stay cheap enough to
+ * run over the whole roadmap. Import is neither a list nor cheap-by-contract, and there is
+ * nowhere else the local half of a duplicate check could come from — DD-1 means no
+ * `remote:` field exists to consult.
+ */
+export declare function linkedCoords(cwd: string): Map<string, string>;
+/**
+ * A filename-safe slug from an issue title.
+ *
+ * Must satisfy `ITEM_FILENAME_RE`'s `[a-z0-9][a-z0-9-]*`, which a title of punctuation or
+ * of a non-Latin script will not survive — hence the fallback rather than a refusal. An
+ * issue that cannot be imported because of its title would be a strange thing to tell
+ * somebody.
+ */
+export declare function slugFromTitle(title: string, number: number): string;
+/** Import one issue into `inbox/`. */
+export declare function importIssue(gh: GhRunner, cwd: string, url: string): ImportResult;
+//# sourceMappingURL=import.d.ts.map

package/dist/roadmap/sync/import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../../src/roadmap/sync/import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAYH,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnD,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAKrD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA2B5D;AAQD,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA8B7D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYnE;AAuBD,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CA+ChF"}