sandcastle-drain 0.1.0

package/dist/orchestrator/reviewer.js

@@ -0,0 +1,260 @@
+/**
+ * Reviewer sub-agent invocation.
+ *
+ * After the implementer commits on `agent/issue-N`, the wrapper spawns a
+ * separate Sandcastle run with the rendered reviewer prompt. The reviewer is
+ * read-only against the worktree, eager-loads the project's principles, and
+ * emits a single fenced JSON block as its final message. This module owns:
+ *
+ * - `runReviewer` — spawn the reviewer run, capture stdout + log
+ * - `parseReviewerOutput` — extract the JSON verdict from stdout
+ * - `formatReviewerComment` — render the verdict as a GitHub issue comment
+ *
+ * The reviewer is advisory: a `FAIL` verdict produces a comment for the human
+ * to weigh; it does not gate the merge. See `src/prompts/reviewer.md.tpl`.
+ */
+import { run, claudeCode } from '@ai-hero/sandcastle';
+import { docker } from '@ai-hero/sandcastle/sandboxes/docker';
+import { copyFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { detectRubricFlags, STAGED_SANDBOX_PATH } from '../stage.js';
+import { REPO_ROOT } from './prereqs.js';
+import { renderPrompt } from '../render-prompt.js';
+const FENCED_JSON_REGEX = /```json\s*\n([\s\S]*?)\n```/g;
+const VALID_VERDICTS = new Set(['PASS', 'FAIL']);
+const VALID_SEVERITIES = new Set(['high', 'medium', 'low']);
+function isString(v) {
+    return typeof v === 'string';
+}
+function isNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+function parseFinding(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return 'finding is not an object';
+    const f = raw;
+    if (!isString(f.severity) || !VALID_SEVERITIES.has(f.severity)) {
+        return `severity must be one of ${[...VALID_SEVERITIES].join('|')}; got ${JSON.stringify(f.severity)}`;
+    }
+    if (!isString(f.principle))
+        return 'principle must be a string';
+    if (!isString(f.file))
+        return 'file must be a string';
+    if (!isNumber(f.line))
+        return 'line must be a number';
+    if (!isString(f.message))
+        return 'message must be a string';
+    if (!isString(f.suggestedFix))
+        return 'suggestedFix must be a string';
+    return {
+        severity: f.severity,
+        principle: f.principle,
+        file: f.file,
+        line: f.line,
+        message: f.message,
+        suggestedFix: f.suggestedFix,
+    };
+}
+/**
+ * Extracts the last fenced ```json``` block from the reviewer's stdout and
+ * validates it against the expected shape. We take the *last* block to be
+ * resilient against the reviewer including an example JSON block earlier in
+ * its thinking — the final answer is always the last one.
+ */
+export function parseReviewerOutput(stdout) {
+    const matches = [...stdout.matchAll(FENCED_JSON_REGEX)];
+    if (matches.length === 0) {
+        return { ok: false, reason: 'no fenced ```json``` block found in reviewer output' };
+    }
+    const lastMatch = matches[matches.length - 1];
+    const rawJson = lastMatch[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `JSON.parse failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        return { ok: false, reason: 'top-level JSON value is not an object' };
+    }
+    const obj = parsed;
+    if (!isString(obj.verdict) || !VALID_VERDICTS.has(obj.verdict)) {
+        return {
+            ok: false,
+            reason: `verdict must be "PASS" or "FAIL"; got ${JSON.stringify(obj.verdict)}`,
+        };
+    }
+    if (!Array.isArray(obj.findings)) {
+        return { ok: false, reason: 'findings must be an array' };
+    }
+    if (!isString(obj.summary)) {
+        return { ok: false, reason: 'summary must be a string' };
+    }
+    const findings = [];
+    for (let i = 0; i < obj.findings.length; i++) {
+        const result = parseFinding(obj.findings[i]);
+        if (typeof result === 'string') {
+            return { ok: false, reason: `findings[${i}]: ${result}` };
+        }
+        findings.push(result);
+    }
+    return {
+        ok: true,
+        value: {
+            verdict: obj.verdict,
+            findings,
+            summary: obj.summary,
+        },
+    };
+}
+function severityBadge(s) {
+    if (s === 'high')
+        return '🔴 high';
+    if (s === 'medium')
+        return '🟡 medium';
+    return '🔵 low';
+}
+function formatFinding(f) {
+    const location = f.line > 0 ? `${f.file}:${f.line}` : f.file;
+    return [
+        `**${severityBadge(f.severity)} — ${f.principle}**`,
+        `\`${location}\``,
+        '',
+        f.message,
+        '',
+        `_Suggested fix:_ ${f.suggestedFix}`,
+    ].join('\n');
+}
+/**
+ * Renders the reviewer's verdict as a GitHub issue comment body. The summary
+ * leads, then findings are listed by severity (high → medium → low) so the
+ * human sees the load-bearing items first.
+ */
+export function formatReviewerComment(output) {
+    const verdictEmoji = output.verdict === 'PASS' ? '✅' : '❌';
+    const lines = [];
+    lines.push(`**Reviewer verdict:** ${verdictEmoji} \`${output.verdict}\` _(advisory — not a merge gate)_`);
+    lines.push('');
+    lines.push(output.summary);
+    if (output.findings.length > 0) {
+        const ordered = [...output.findings].sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+        lines.push('');
+        lines.push(`### Findings (${output.findings.length})`);
+        lines.push('');
+        for (const f of ordered) {
+            lines.push(formatFinding(f));
+            lines.push('');
+        }
+    }
+    return lines.join('\n').trimEnd();
+}
+function severityRank(s) {
+    if (s === 'high')
+        return 0;
+    if (s === 'medium')
+        return 1;
+    return 2;
+}
+/**
+ * Formats a fallback comment when the reviewer either didn't run, or ran but
+ * didn't emit parseable JSON. We still want the human to know the reviewer
+ * was invoked and that its output is in the log file.
+ */
+export function formatReviewerErrorComment(args) {
+    const lines = [];
+    lines.push('**Reviewer verdict:** ⚠️ `error` _(advisory — not a merge gate)_');
+    lines.push('');
+    lines.push(`The reviewer sub-agent ran but produced no parseable verdict: ${args.reason}`);
+    if (args.logFilePath) {
+        lines.push('');
+        lines.push(`See \`${args.logFilePath}\` for the full reviewer transcript.`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Spawns the reviewer Sandcastle run. The branch already exists with the
+ * implementer's commits — the reviewer checks it out into a separate worktree,
+ * reads the diff, and emits its verdict. We do not pass a `branchStrategy` that
+ * would create a new branch; sandcastle reuses the existing one.
+ *
+ * On any failure (timeout, missing JSON, throw), we return a result with
+ * `output: undefined` and a non-empty `parseError`. The wrapper posts an error
+ * comment in that case rather than skipping the comment entirely — the absence
+ * of a reviewer verdict on an issue would itself be confusing.
+ */
+export async function runReviewer(args) {
+    let result;
+    let runError;
+    try {
+        const flags = detectRubricFlags(REPO_ROOT);
+        const prompt = await renderPrompt('reviewer', {
+            ISSUE_NUMBER: String(args.issueNumber),
+            BRANCH: args.branch,
+        }, {
+            HAS_CONTEXT_MD: flags.hasContextMd,
+            HAS_ADRS: flags.hasAdrs,
+            HAS_PROJECT_RULES: flags.hasContextMd || flags.hasAdrs,
+        });
+        result = await run({
+            agent: claudeCode('claude-opus-4-7'),
+            sandbox: docker({
+                imageName: args.imageName,
+                mounts: [
+                    { hostPath: args.hostCredsPath, sandboxPath: args.sandboxCredsPath },
+                    { hostPath: args.stagedHostPath, sandboxPath: STAGED_SANDBOX_PATH, readonly: true },
+                ],
+                env: { GH_TOKEN: args.ghToken },
+            }),
+            prompt,
+            branchStrategy: { type: 'branch', branch: args.branch },
+            idleTimeoutSeconds: args.idleTimeoutSeconds,
+            signal: AbortSignal.timeout(args.wallClockTimeoutMs),
+        });
+    }
+    catch (err) {
+        runError = err;
+    }
+    const stdout = result?.stdout ?? (runError instanceof Error ? runError.message : String(runError ?? ''));
+    const sourceLogPath = result?.logFilePath;
+    // Best-effort copy the sandcastle log to our well-known path. The branch's
+    // implementer log lives alongside the reviewer log so post-mortem is easy.
+    let copiedLogPath;
+    if (sourceLogPath !== undefined) {
+        try {
+            await mkdir(dirname(args.reviewerLogPath), { recursive: true });
+            await copyFile(sourceLogPath, args.reviewerLogPath);
+            copiedLogPath = args.reviewerLogPath;
+        }
+        catch (err) {
+            console.error(`[reviewer] failed to copy log ${sourceLogPath} → ${args.reviewerLogPath}:`, err.message);
+        }
+    }
+    if (runError !== undefined && result === undefined) {
+        return {
+            output: undefined,
+            parseError: `reviewer run threw: ${runError instanceof Error ? runError.message : String(runError)}`,
+            stdout,
+            logFilePath: copiedLogPath,
+        };
+    }
+    const parsed = parseReviewerOutput(stdout);
+    if (!parsed.ok) {
+        return {
+            output: undefined,
+            parseError: parsed.reason,
+            stdout,
+            logFilePath: copiedLogPath,
+        };
+    }
+    return {
+        output: parsed.value,
+        parseError: undefined,
+        stdout,
+        logFilePath: copiedLogPath,
+    };
+}
+//# sourceMappingURL=reviewer.js.map

package/dist/orchestrator/reviewer.js.map

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

package/dist/orchestrator/ship.d.ts

@@ -0,0 +1,19 @@
+export declare class ShipError extends Error {
+    constructor(message: string);
+}
+export interface ShipBranchArgs {
+    issue: number;
+}
+export interface ShipBranchResult {
+    branch: string;
+    prUrl: string | undefined;
+}
+/**
+ * Pushes `agent/issue-N`, opens (or reuses) a PR with an explicit `Closes #N`
+ * body, squash-merges it, and deletes the remote branch. Throws `ShipError`
+ * with a human-readable message on any step that can't be recovered. Idempotent
+ * to the extent that re-running after a partial failure picks up where it left
+ * off — push is a no-op when up-to-date, an already-open PR is reused.
+ */
+export declare function shipBranch(args: ShipBranchArgs): Promise<ShipBranchResult>;
+//# sourceMappingURL=ship.d.ts.map

package/dist/orchestrator/ship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.d.ts","sourceRoot":"","sources":["../../src/orchestrator/ship.ts"],"names":[],"mappings":"AA6BA,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+DhF"}

package/dist/orchestrator/ship.js

@@ -0,0 +1,73 @@
+/**
+ * Pushes an `agent/issue-N` branch, opens a PR, and merges it (squash + delete
+ * remote branch). The PR body is explicitly set to include `Closes #N` so the
+ * merge auto-closes the issue regardless of what the agent's commit messages
+ * looked like.
+ *
+ * Invoked by `src/cli.ts` as `sandcastle-drain ship <issue>`. After this completes
+ * successfully, the user runs `sandcastle-drain sweep <issue>` to clean up the
+ * local worktree, branch, and pull main. The drain orchestrator (`main.ts`)
+ * also calls `shipBranch` inline when the CI gate and reviewer both pass.
+ */
+import { execa } from 'execa';
+import { REPO_ROOT } from './prereqs.js';
+async function run(cmd, args, opts = {}) {
+    const r = await execa(cmd, args, { cwd: REPO_ROOT, reject: opts.reject ?? true });
+    return { exitCode: r.exitCode ?? 0, stdout: r.stdout, stderr: r.stderr };
+}
+export class ShipError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ShipError';
+    }
+}
+/**
+ * Pushes `agent/issue-N`, opens (or reuses) a PR with an explicit `Closes #N`
+ * body, squash-merges it, and deletes the remote branch. Throws `ShipError`
+ * with a human-readable message on any step that can't be recovered. Idempotent
+ * to the extent that re-running after a partial failure picks up where it left
+ * off — push is a no-op when up-to-date, an already-open PR is reused.
+ */
+export async function shipBranch(args) {
+    const branch = `agent/issue-${args.issue}`;
+    const branchCheck = await run('git', ['rev-parse', '--verify', branch], { reject: false });
+    if (branchCheck.exitCode !== 0) {
+        throw new ShipError(`Branch \`${branch}\` not found locally. Did you already ship this issue, or has \`sandcastle-drain drain\` run yet?`);
+    }
+    console.log(`[ship] Pushing ${branch} to origin...`);
+    await run('git', ['push', '-u', 'origin', branch]);
+    const titleResult = await run('git', ['log', '-1', '--pretty=%s', branch]);
+    const title = titleResult.stdout.trim();
+    // Explicit `Closes #N` so the squash-merge auto-closes the issue regardless of
+    // what's in commit messages — `gh pr create --fill` only reads the first
+    // commit's body, which is fragile when an agent makes multiple commits.
+    const body = `Closes #${args.issue}\n\n_Created via \`sandcastle-drain ship ${args.issue}\`._`;
+    console.log(`[ship] Creating PR for ${branch}...`);
+    const prCreate = await run('gh', ['pr', 'create', '--head', branch, '--base', 'main', '--title', title, '--body', body], { reject: false });
+    let prUrl;
+    if (prCreate.exitCode === 0) {
+        prUrl = prCreate.stdout.trim().split(/\s+/).pop();
+    }
+    else {
+        // A PR may already exist for this branch (e.g. ship was re-run after a
+        // merge failure). Surface the existing one and continue to the merge.
+        const list = await run('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url'], { reject: false });
+        const open = JSON.parse(list.stdout || '[]');
+        if (open.length === 0) {
+            throw new ShipError(`gh pr create failed and no open PR exists for ${branch}.\n${prCreate.stderr}`);
+        }
+        prUrl = open[0].url;
+        console.log(`[ship] PR already open: ${prUrl}`);
+    }
+    // Squash keeps main's history one-commit-per-slice. We do NOT use
+    // `gh pr merge --delete-branch` because that flag tries to delete the
+    // *local* branch too, which always fails at ship time — the branch is
+    // checked out in the worktree. Explicit remote-only delete follows.
+    console.log(`[ship] Merging (squash)...`);
+    await run('gh', ['pr', 'merge', branch, '--squash']);
+    console.log(`[ship] Deleting remote branch...`);
+    await run('git', ['push', 'origin', '--delete', branch]);
+    console.log(`[ship] Done. Run \`sandcastle-drain sweep ${args.issue}\` to clean up the local worktree and branch.`);
+    return { branch, prUrl };
+}
+//# sourceMappingURL=ship.js.map

package/dist/orchestrator/ship.js.map

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

package/dist/orchestrator/sibling-context.d.ts

@@ -0,0 +1,16 @@
+export interface SiblingSummary {
+    issue: number;
+    branch: string;
+    changedFiles: string[];
+    newExports: string[];
+}
+export declare function extractNewExports(diff: string): string[];
+export declare function summarizeBranch(args: {
+    issue: number;
+    branch: string;
+    baseBranch: string;
+    cwd: string;
+}): Promise<SiblingSummary>;
+export declare function estimateTokens(text: string): number;
+export declare function buildSiblingContextBlock(siblings: readonly SiblingSummary[]): string;
+//# sourceMappingURL=sibling-context.d.ts.map

package/dist/orchestrator/sibling-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-context.d.ts","sourceRoot":"","sources":["../../src/orchestrator/sibling-context.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAOD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMxD;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,OAAO,CAAC,cAAc,CAAC,CAiB1B;AAKD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CA6BpF"}

package/dist/orchestrator/sibling-context.js

@@ -0,0 +1,61 @@
+import { execa } from 'execa';
+// Match `+export ...` lines added in a unified diff. Intentionally narrow:
+// missing matches just don't appear in the prompt — the goal is informational
+// hints, not a complete export index.
+const EXPORT_REGEX = /^\+export (?:async )?(?:function|const|class|type|interface|enum) (\w+)/gm;
+export function extractNewExports(diff) {
+    const found = new Set();
+    for (const match of diff.matchAll(EXPORT_REGEX)) {
+        found.add(match[1]);
+    }
+    return [...found];
+}
+export async function summarizeBranch(args) {
+    const { issue, branch, baseBranch, cwd } = args;
+    const range = `${baseBranch}..${branch}`;
+    const namesResult = await execa('git', ['diff', '--name-only', range], {
+        cwd,
+        reject: false,
+    });
+    const changedFiles = namesResult.exitCode === 0
+        ? namesResult.stdout.split(/\r?\n/).filter((line) => line.length > 0)
+        : [];
+    const diffResult = await execa('git', ['diff', range], { cwd, reject: false });
+    const newExports = diffResult.exitCode === 0 ? extractNewExports(diffResult.stdout) : [];
+    return { issue, branch, changedFiles, newExports };
+}
+// Rough token estimate: Anthropic tokenizers average ~3.5–4 chars/token for
+// English prose. We use 4 because it's the standard heuristic and we only need
+// an order-of-magnitude signal to monitor for context bloat. Empty string → 0.
+export function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+export function buildSiblingContextBlock(siblings) {
+    if (siblings.length === 0)
+        return '';
+    const header = [
+        '## Sibling work in this drain session',
+        '',
+        'The following branches were just created by this same drain run and are awaiting review. They are NOT yet on `main`. If your work overlaps with any of them:',
+        '',
+        '- Prefer importing their exported symbols over re-implementing.',
+        '- If you import, your PR will be reviewed as a stack with the sibling.',
+        '- If you have a strong reason to differ, do so and explain in the commit.',
+        '',
+        'Siblings:',
+        '',
+    ].join('\n');
+    const siblingLines = siblings
+        .map((s) => [
+        `- \`${s.branch}\` (issue #${s.issue}):`,
+        s.changedFiles.length > 0 ? `  - Changed: ${s.changedFiles.join(', ')}` : null,
+        s.newExports.length > 0 ? `  - New exports: ${s.newExports.join(', ')}` : null,
+    ]
+        .filter((line) => line !== null)
+        .join('\n'))
+        .join('\n');
+    return `${header}\n${siblingLines}`;
+}
+//# sourceMappingURL=sibling-context.js.map

package/dist/orchestrator/sibling-context.js.map

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

package/dist/orchestrator/splits.d.ts

@@ -0,0 +1,60 @@
+export declare const SPLITS_FILE_RELATIVE_PATH = ".sandcastle-drain/splits.json";
+export declare const OVERSIZED_LABEL = "oversized";
+export declare const MAX_SPLITS = 10;
+export declare const MAX_TITLE_LENGTH = 256;
+export interface Split {
+    title: string;
+    body: string;
+}
+export interface CreatedSplit {
+    number: number;
+    url: string;
+    title: string;
+}
+export type SplitsParseResult = {
+    ok: true;
+    value: Split[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates the raw JSON read from `.sandcastle-drain/splits.json`. The shape is
+ * intentionally tiny: an array of `{ title, body }`. Body is markdown the
+ * implementer wrote — we never massage it on the way through.
+ */
+export declare function parseSplitsFile(rawJson: string): SplitsParseResult;
+export declare function splitsFilePath(worktreePath: string): string;
+/**
+ * Reads + parses the splits file from a worktree. Returns `undefined` when
+ * the file isn't present — the common case, since most implementers won't
+ * split. File-read failures other than ENOENT surface as parse errors so the
+ * wrapper can post the same error-comment path.
+ */
+export declare function readSplitsFile(worktreePath: string): Promise<SplitsParseResult | undefined>;
+/**
+ * Renders the comment left on the parent issue when splits land successfully.
+ * The reader gets a numbered checklist of the follow-ups so they can spot at a
+ * glance how the work was decomposed, plus a note explaining the label.
+ */
+export declare function buildOriginalIssueSplitComment(args: {
+    parentIssue: number;
+    splits: readonly CreatedSplit[];
+}): string;
+/**
+ * Renders the error comment when the splits file is malformed. We still want
+ * the human to know the implementer tried to split — silent dropping would
+ * make the next drain look like the implementer just bailed out.
+ */
+export declare function buildSplitErrorComment(args: {
+    reason: string;
+}): string;
+/**
+ * Renders the message the wrapper logs to its own stdout when the splits
+ * flow fires. Not posted to GitHub — this is just for the drain operator.
+ */
+export declare function formatSplitsLogLine(args: {
+    parentIssue: number;
+    splits: readonly CreatedSplit[];
+}): string;
+//# sourceMappingURL=splits.d.ts.map

package/dist/orchestrator/splits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splits.d.ts","sourceRoot":"","sources":["../../src/orchestrator/splits.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,yBAAyB,kCAAkC,CAAC;AACzE,eAAO,MAAM,eAAe,cAAc,CAAC;AAC3C,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,KAAK,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAmB7F;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CA6BlE;AAED,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAajG;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC,GAAG,MAAM,CAkBT;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAUvE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC,GAAG,MAAM,CAGT"}