monday-cli 0.3.0 → 0.5.0

package/dist/commands/completion.js

@@ -0,0 +1,418 @@
+import { z } from 'zod';
+import { parseArgv } from './parse-argv.js';
+import { emitSuccess } from './emit.js';
+import { parseGlobalFlags } from '../types/global-flags.js';
+import { UsageError } from '../utils/errors.js';
+/**
+ * Closed 3-value enum of shell flavours the CLI knows how to emit a
+ * completion script for. Adding a 4th value (e.g. `powershell`,
+ * `nushell`) is a SemVer-minor expansion at the M33 contract + a
+ * matching hand-rolled template below.
+ */
+export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'];
+/**
+ * zod enum binding for the closed 3-value shell flavour. Exported so
+ * downstream `monday schema completion` introspection consumers can
+ * pin against the same enum the argv parse boundary uses.
+ */
+export const shellSchema = z.enum(COMPLETION_SHELLS);
+const inputSchema = z
+    .object({
+    shell: shellSchema,
+})
+    .strict();
+/**
+ * `--json` envelope shape. The default mode emits raw script bytes
+ * with NO envelope (see module-level carve-out note); this schema
+ * applies only when `--json` / `--output json` / `MONDAY_OUTPUT=json`
+ * opts into the envelope path.
+ *
+ * `shell` echoes the input flavour; `script` is the per-shell
+ * completion script body as a single string (including trailing
+ * newlines). Agents extract via `jq -r '.data.script'`.
+ */
+export const completionOutputSchema = z
+    .object({
+    shell: shellSchema,
+    script: z.string().min(1),
+})
+    .strict();
+/**
+ * Strip placeholder syntax (`get <itemId>` → `get`, `set <iid>
+ * [setExpr]` → `set`) so the completion script enumerates bare
+ * verbs. Commander's `Command.name()` already strips this in v14
+ * but the defensive helper keeps the templates resilient to any
+ * future commander shape change.
+ */
+const stripPlaceholders = (raw) => 
+// `String.prototype.split` always returns at least one element so
+// the `?? raw` arm is unreachable from a non-empty input. The
+// commander `Command.name()` source is non-empty by construction;
+// the defensive guard stays so a future commander shape change
+// doesn't surface as an unhandled `undefined` first-token.
+/* c8 ignore next */
+raw.split(/\s+/u)[0] ?? raw;
+const collectLongOptions = (cmd) => {
+    const out = [];
+    for (const opt of cmd.options) {
+        // Commander v14 stores the long form on `opt.long`. Every option
+        // declared via `program.option('--foo …', …)` carries a non-empty
+        // long-form string; the `length > 0` guard is defensive against
+        // a hypothetical short-only option (not currently used anywhere
+        // in `src/cli/program.ts`'s global-flag set or any verb's
+        // per-command options).
+        /* c8 ignore next */
+        if (typeof opt.long === 'string' && opt.long.length > 0) {
+            out.push(opt.long);
+        }
+    }
+    return out;
+};
+const buildCompletionTree = (program) => {
+    const visit = (cmd) => ({
+        name: stripPlaceholders(cmd.name()),
+        children: cmd.commands.map(visit),
+        options: collectLongOptions(cmd),
+    });
+    return visit(program);
+};
+const flattenPaths = (root) => {
+    const globalOptions = root.options;
+    const acc = [];
+    const recur = (node, path) => {
+        const merged = new Set([...globalOptions, ...node.options]);
+        acc.push({
+            path,
+            children: node.children.map((c) => c.name).sort(),
+            options: [...merged].sort(),
+            localOptions: [...node.options].sort(),
+        });
+        for (const child of node.children) {
+            recur(child, [...path, child.name]);
+        }
+    };
+    recur(root, []);
+    acc.sort((a, b) => a.path.join(' ').localeCompare(b.path.join(' ')));
+    return acc;
+};
+/**
+ * Encode a value for safe interpolation inside POSIX-shell
+ * single-quoted strings. The only metachar to escape is the
+ * single quote itself — close, escape, reopen.
+ */
+const shSingleQuote = (raw) => `'${raw.replace(/'/gu, `'\\''`)}'`;
+const buildBashScript = (paths) => {
+    const cases = [];
+    for (const entry of paths) {
+        const key = entry.path.join(' ');
+        const completions = [...entry.children, ...entry.options].join(' ');
+        cases.push(`    ${shSingleQuote(key)})\n` +
+            `      COMPREPLY=( $(compgen -W ${shSingleQuote(completions)} -- "$cur") )\n` +
+            `      return 0\n` +
+            `      ;;`);
+    }
+    return [
+        '# monday-cli bash completion',
+        '# Generated by `monday completion bash` — do not edit by hand.',
+        '# Install: append the output to your bashrc, e.g.',
+        '#   monday completion bash >> ~/.bashrc',
+        '',
+        '_monday_completion() {',
+        '  local cur prev words cword',
+        '  COMPREPLY=()',
+        '  cur="${COMP_WORDS[COMP_CWORD]}"',
+        '  prev="${COMP_WORDS[COMP_CWORD-1]}"',
+        '  words=("${COMP_WORDS[@]}")',
+        '  cword=$COMP_CWORD',
+        '',
+        '  # Build the command path from the words BEFORE the current',
+        '  # cursor position. Flags (anything starting with `-`) and the',
+        '  # binary name itself are skipped — only positional verbs',
+        '  # contribute to the path lookup.',
+        '  local path=""',
+        '  local i=1',
+        '  while [ $i -lt $cword ]; do',
+        '    local w="${words[$i]}"',
+        '    case "$w" in',
+        '      -*) ;;',
+        '      *)',
+        '        if [ -z "$path" ]; then',
+        '          path="$w"',
+        '        else',
+        '          path="$path $w"',
+        '        fi',
+        '        ;;',
+        '    esac',
+        '    i=$((i+1))',
+        '  done',
+        '',
+        '  case "$path" in',
+        ...cases,
+        '    *)',
+        '      COMPREPLY=()',
+        '      return 0',
+        '      ;;',
+        '  esac',
+        '}',
+        '',
+        'complete -F _monday_completion monday',
+        '',
+    ].join('\n');
+};
+const buildZshScript = (paths) => {
+    // compadd takes one shell word per completion candidate after `--`,
+    // so we single-quote each item individually rather than pre-joining
+    // into a single space-delimited string. Quoting per-item keeps the
+    // emitted compadd line resilient to verb / flag names that ever
+    // contain whitespace or quoting metacharacters (none today, but
+    // future v0.5+ verbs added by other agents shouldn't have to know
+    // the script-emit invariant to stay correct).
+    const cases = paths.map((entry) => {
+        const key = entry.path.join(' ');
+        const items = [...entry.children, ...entry.options]
+            .map(shSingleQuote)
+            .join(' ');
+        return (`    ${shSingleQuote(key)})\n` +
+            `      compadd -- ${items}\n` +
+            `      return 0\n` +
+            `      ;;`);
+    });
+    return [
+        '#compdef monday',
+        '# monday-cli zsh completion',
+        '# Generated by `monday completion zsh` — do not edit by hand.',
+        '# Install: append the output to your zshrc, e.g.',
+        '#   monday completion zsh >> ~/.zshrc',
+        '',
+        '_monday() {',
+        '  local -a words_arr',
+        '  words_arr=("${words[@]}")',
+        '  local cword=$CURRENT',
+        '',
+        '  # Build the command path from the words BEFORE the current',
+        '  # cursor position. Flags and the binary name itself are',
+        '  # skipped — only positional verbs feed the lookup.',
+        '  local path=""',
+        '  local i=2',
+        '  while [ $i -lt $cword ]; do',
+        '    local w="${words_arr[$i]}"',
+        '    case "$w" in',
+        '      -*) ;;',
+        '      *)',
+        '        if [ -z "$path" ]; then',
+        '          path="$w"',
+        '        else',
+        '          path="$path $w"',
+        '        fi',
+        '        ;;',
+        '    esac',
+        '    i=$((i+1))',
+        '  done',
+        '',
+        '  case "$path" in',
+        ...cases,
+        '    *)',
+        '      return 0',
+        '      ;;',
+        '  esac',
+        '}',
+        '',
+        '_monday "$@"',
+        '',
+    ].join('\n');
+};
+const buildFishScript = (paths) => {
+    const lines = [
+        '# monday-cli fish completion',
+        '# Generated by `monday completion fish` — do not edit by hand.',
+        '# Install: write the output to your fish completions dir, e.g.',
+        '#   monday completion fish > ~/.config/fish/completions/monday.fish',
+        '',
+        '# Disable file completion globally for the monday command; per-',
+        '# scope rules below re-enable suggestions where appropriate.',
+        'complete -c monday -f',
+        '',
+    ];
+    for (const entry of paths) {
+        const depth = entry.path.length;
+        // The condition predicate enumerates how to detect "we are at',
+        // this command depth": at depth 0, no subcommand seen; at depth
+        // N, every prior path token has been seen AND the next token
+        // has not.
+        const seenChain = entry.path
+            .map((p) => `__fish_seen_subcommand_from ${p}`)
+            .join('; and ');
+        const cond = depth === 0
+            ? '__fish_use_subcommand'
+            : seenChain;
+        // Emit one `complete -c monday -n '<cond>' -a 'name' -d 'description'`
+        // per direct child (sub-noun / sub-verb).
+        for (const child of entry.children) {
+            const desc = `(${entry.path.length === 0 ? 'top-level' : entry.path.join(' ')} ${child})`;
+            lines.push(`complete -c monday -n ${shSingleQuote(cond)} -a ${shSingleQuote(child)} -d ${shSingleQuote(desc)}`);
+        }
+        // Emit one `complete -c monday -n '<cond>' -l <flag>` per option
+        // long-form. The fish completion model is per-condition: globals
+        // register at the root (no `-n` predicate so they apply
+        // everywhere); per-verb locals register at their specific depth
+        // with the matching `__fish_seen_subcommand_from ...` predicate
+        // so the suggestion only fires inside the right command scope.
+        // Without the per-depth local-flag emission, fish would lose
+        // every verb-specific flag (e.g. `doc list --workspace`,
+        // `dev sprint list --state`) — Codex IMPL round-1 P2-1 catch.
+        const flagsToEmit = depth === 0 ? entry.options : entry.localOptions;
+        for (const flag of flagsToEmit) {
+            // Strip the leading `--` from the long form for fish's -l.
+            // Commander's long-form always starts with `--`; the `: flag`
+            // arm is defensive against a hypothetical bare-name input.
+            /* c8 ignore next */
+            const long = flag.startsWith('--') ? flag.slice(2) : flag;
+            if (depth === 0) {
+                lines.push(`complete -c monday -l ${shSingleQuote(long)}`);
+            }
+            else {
+                lines.push(`complete -c monday -n ${shSingleQuote(cond)} -l ${shSingleQuote(long)}`);
+            }
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+};
+const buildCompletionScript = (shell, program) => {
+    const tree = buildCompletionTree(program);
+    const paths = flattenPaths(tree);
+    switch (shell) {
+        case 'bash':
+            return buildBashScript(paths);
+        case 'zsh':
+            return buildZshScript(paths);
+        case 'fish':
+            return buildFishScript(paths);
+    }
+};
+/**
+ * Exposed for unit-test access — lets the test suite build a tree
+ * against a synthetic commander program (without spinning the full
+ * runner) and assert structural properties.
+ */
+export const _internals = {
+    buildCompletionTree,
+    flattenPaths,
+    buildCompletionScript,
+    stripPlaceholders,
+};
+export const completionCommand = {
+    name: 'completion',
+    summary: 'Emit a shell-completion script (bash | zsh | fish)',
+    examples: [
+        'monday completion bash >> ~/.bashrc',
+        'monday completion zsh  >> ~/.zshrc',
+        'monday completion fish >  ~/.config/fish/completions/monday.fish',
+        'monday completion bash --json',
+    ],
+    idempotent: true,
+    inputSchema,
+    outputSchema: completionOutputSchema,
+    attach: (program, ctx) => {
+        program
+            .command('completion <shell>')
+            .description(completionCommand.summary)
+            .addHelpText('after', [
+            '',
+            'Examples:',
+            ...completionCommand.examples.map((e) => `  ${e}`),
+            '',
+            'Notes:',
+            '  - Default output is the raw shell script on stdout (no envelope).',
+            '    The standard install pipes to your rc file (see examples).',
+            '  - --json wraps the script in the §6 envelope (data: { shell, script }).',
+            '  - --table / --output table|text|ndjson are rejected (not applicable to a script).',
+            '',
+        ].join('\n'))
+            .action((shellArg) => {
+            // Argv parse boundary — validates the positional against
+            // the closed 3-value enum BEFORE the output-format dispatch
+            // runs, so a premature `monday completion floppy` invocation
+            // surfaces `usage_error` from the parse boundary (NOT a
+            // confusing "format not applicable" message).
+            const parsed = parseArgv(completionCommand.inputSchema, {
+                shell: shellArg,
+            });
+            const globalFlags = parseGlobalFlags(program.opts(), ctx.env);
+            // Detect whether the caller explicitly opted into an output
+            // format. The cli-design §3.1 #2 raw-bytes carve-out is
+            // explicit: default behaviour (no flag, no env) emits raw
+            // bytes regardless of TTY / pipe context. Going through
+            // `selectOutput` would silently collapse "no opt-in" to
+            // either `table` (TTY) or `json` (pipe) — neither matches
+            // the carve-out's "raw bytes by default" contract.
+            const envOutput = ctx.env.MONDAY_OUTPUT;
+            const envOptIn = envOutput !== undefined && envOutput !== '';
+            const optedIn = globalFlags.json ||
+                globalFlags.table ||
+                globalFlags.output !== undefined ||
+                envOptIn;
+            if (!optedIn) {
+                // Default raw-bytes mode. Writes the script directly to
+                // stdout with NO envelope wrap — the standard install flow
+                // `monday completion bash >> ~/.bashrc` relies on this. No
+                // secret-redaction pass is needed: the script bytes are
+                // built from `program.commands` + global option names,
+                // both compile-time constants with no env interpolation.
+                // The integration test suite pins a LEAK_CANARY assertion
+                // to catch future drift.
+                const script = buildCompletionScript(parsed.shell, program);
+                ctx.stdout.write(script);
+                return;
+            }
+            // Reject inapplicable formats BEFORE building the script.
+            // The cli-design §3.1 #2 carve-out documents three modes:
+            // default raw bytes, `--json` envelope, and rejection for
+            // every other format. `text` and `ndjson` are accessible
+            // only via `--output <fmt>` (NOT as standalone `--text` /
+            // `--ndjson` shorthand flags — only `--json` and `--table`
+            // are shorthands per §4.4).
+            if (globalFlags.table) {
+                throw new UsageError('output format not applicable to monday completion: ' +
+                    '--table is rejected (the verb emits a shell script — ' +
+                    'raw bytes by default, JSON envelope via --json).');
+            }
+            if (globalFlags.output === 'table' ||
+                globalFlags.output === 'text' ||
+                globalFlags.output === 'ndjson') {
+                throw new UsageError(`output format not applicable to monday completion: ` +
+                    `--output ${globalFlags.output} is rejected (the verb emits ` +
+                    `a shell script — raw bytes by default, JSON envelope via --json).`);
+            }
+            // Reject MONDAY_OUTPUT=<non-json> on the env path too. The
+            // env opt-in is symmetric with the flag opt-in: only
+            // MONDAY_OUTPUT=json maps onto the envelope mode; everything
+            // else routes through this rejection.
+            if (globalFlags.output === undefined &&
+                !globalFlags.json &&
+                envOptIn &&
+                envOutput !== 'json') {
+                throw new UsageError(`output format not applicable to monday completion: ` +
+                    `MONDAY_OUTPUT=${envOutput} is rejected (the verb emits ` +
+                    `a shell script — raw bytes by default, JSON envelope via --json).`);
+            }
+            // At this point the caller opted INTO the `--json` envelope
+            // path (either `--json`, `--output json`, or
+            // `MONDAY_OUTPUT=json`). Build the script + emit through
+            // the standard §6 envelope. `source: 'none'` mirrors
+            // `monday config show` / `monday config path` cadence for
+            // CLI-internal verbs — no Monday API call, no cache, so the
+            // data-source field carries the same "no upstream" value.
+            const script = buildCompletionScript(parsed.shell, program);
+            emitSuccess({
+                ctx,
+                data: { shell: parsed.shell, script },
+                schema: completionCommand.outputSchema,
+                programOpts: program.opts(),
+                source: 'none',
+                cacheAgeSeconds: null,
+            });
+        });
+    },
+};
+//# sourceMappingURL=completion.js.map

package/dist/commands/completion.js.map

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

package/dist/commands/doc/append-markdown.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `monday doc append-markdown <doc-id> (--markdown <file|-> |
+ * --markdown-string <s>) [--after <bid>] [--dry-run]` — append a
+ * parsed-markdown payload as new blocks at the tail of an existing
+ * workdoc (`cli-design.md` §4.3 DOC section + §13 v0.5 entry;
+ * `v0.5-plan.md` §3 M37 + §8 D12-D13).
+ *
+ * **Wire shape.** Single `add_content_to_doc_from_markdown(docId,
+ * markdown, afterBlockId?) → DocBlocksFromMarkdownResult` round-trip
+ * via {@link addContentToDocFromMarkdown} against `mutation
+ * AddContentToDocFromMarkdown` with `operationName:
+ * 'AddContentToDocFromMarkdown'` (R-NEW-37 W2 audit-point).
+ * Custom-OBJECT return shape: `{success!, block_ids?, error?}`.
+ *
+ * **camelCase wire-arg note.** `add_content_to_doc_from_markdown`
+ * uses camelCase `docId` / `afterBlockId` on the wire (Finding 7);
+ * CLI argv stays kebab-case (`<doc-id>` positional / `--after <bid>`);
+ * error envelope `details.*` keys stay snake_case (`details.doc_id` /
+ * `details.after_block_id`). 5th supporting site for R-NEW-41 at the
+ * canonical asymmetry note (see `src/api/documents.ts` module header).
+ *
+ * **Argv shape.**
+ *
+ *   - `<doc-id>` — required positional (Monday's
+ *     `add_content_to_doc_from_markdown.docId` is `ID!`). Brand-
+ *     validated via {@link DocIdSchema}.
+ *   - `--markdown <file|->` OR `--markdown-string <s>` — **mutually-
+ *     exclusive content source; exactly one required.** Mirrors the
+ *     `import-html` `--html` / `--html-string` shape verbatim. File
+ *     path form supports `-` for stdin per cli-design §3.1; inline
+ *     form caps at {@link MAX_DOC_IMPORT_PAYLOAD_BYTES} bytes UTF-8
+ *     at parse boundary per D13 closure (same empirical threshold
+ *     as the HTML side — the wire-side cap is transport-layer-wide,
+ *     not per-mutation).
+ *   - `--after <bid>` — optional opaque block ID (maps to wire
+ *     `afterBlockId: String`). Brand-validated via
+ *     {@link DocBlockIdSchema}. Absent → markdown blocks land at the
+ *     document tail (append-end semantics per Monday's probe
+ *     description: "Use this to append content to the end of a
+ *     document or insert content after a specific block").
+ *
+ * **Output envelope.** Custom-OBJECT projection per D12 — `data: {
+ * doc_id (echoed input), block_ids, success: true }`. Echoes the
+ * input `<doc-id>` so agents piping the envelope into a follow-up
+ * `monday doc get <doc-id>` keep the parent doc context inline.
+ * `block_ids` is the wire's full list of NEWLY-CREATED block ids
+ * preserved in markdown-source order. **Empty `block_ids: []` IS a
+ * valid success shape** (non-empty markdown that Monday parses to
+ * zero convertible blocks — e.g. comments-only or whitespace-only
+ * post-Monday-parse); the CLI does not rewrap empty-blocks as
+ * failure. (Note: empty / whitespace-only input is rejected at the
+ * parse / read boundary — `--markdown-string` rejects at parse via
+ * the schema's `.refine()`; file / stdin rejects at the runtime
+ * read boundary via {@link readSourceContent}'s empty-after-trim
+ * check — so the empty-`block_ids` success path is only reachable
+ * for non-empty input that Monday's parser collapses to zero
+ * structural blocks.)
+ *
+ * **Failure mapping** per D12 closure:
+ *
+ *   - `success: false + populated error` → `validation_failed` with
+ *     `details: { doc_id, error, hint }`.
+ *   - `success: false + empty/null error` → `internal_error` with
+ *     wire-regression hint.
+ *   - `success: true + null block_ids` → `internal_error` (Monday
+ *     promises a non-null `block_ids` list on success).
+ *   - Oversized inline `--markdown-string` at parse boundary →
+ *     `usage_error.details.issues[{path: 'markdownString', message:
+ *     '--markdown-string exceeds the 256000-byte wire-side limit
+ *     ...'}]` from `parseArgv`'s zod-issues envelope (D13 closure).
+ *     The `usage_error` rejection surfaces ahead of any wire
+ *     dispatch.
+ *   - Oversized file payload at runtime →
+ *     `readSourceContent` rejects with `usage_error` carrying
+ *     `details: { source: 'file' | 'stdin', size_bytes, limit_bytes,
+ *     file_path? }`.
+ *   - Non-existent / inaccessible `<doc-id>` → bubbles via Monday's
+ *     wire-side `errors[]` → typed `ApiError` (`not_found` or
+ *     `forbidden`).
+ *
+ * **Dry-run shape** per cli-design §6.4 mutation-dry-run variant.
+ * Minimal envelope listing the planned
+ * `add_content_to_doc_from_markdown` operation + resolved input
+ * slots (`doc_id`, optional `after_block_id`, `markdown_source`
+ * descriptor — file path / `'(stdin)'` / `'(inline)'`). Markdown
+ * payload itself omitted (can be hundreds of KB); agents see what
+ * would be sent, not the bytes. No preflight read; `meta.source:
+ * 'none'`.
+ *
+ * **Idempotent: false.** Re-running creates a SECOND set of blocks
+ * carrying the same markdown content (Monday's wire does not dedupe).
+ * Agents that need idempotency must pair with a `monday doc get
+ * <doc-id>` lookup first to confirm the content isn't already
+ * present, OR use `monday doc block-delete` + `block-create`
+ * (M36) for fine-grained per-block control.
+ *
+ * **Permission-sensitive.** Tokens lacking workdoc-write scope on
+ * the target doc surface `forbidden`.
+ *
+ * **Runtime body landed at v0.5-M37 IMPL.** Same shape as
+ * `import-html.ts` — `parseArgv` BEFORE `resolveClient`; lifted
+ * {@link readSourceContent} for file/stdin/inline with runtime size
+ * guard; dry-run emits minimal planned changes; live path dispatches
+ * {@link addContentToDocFromMarkdown} + projects via `emitMutation`.
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+import { type DocAppendMarkdownOutput } from '../../api/documents.js';
+declare const inputSchema: z.ZodObject<{
+    docId: z.core.$ZodBranded<z.ZodString, "DocId", "out">;
+    markdown: z.ZodOptional<z.ZodString>;
+    markdownString: z.ZodOptional<z.ZodString>;
+    after: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DocBlockId", "out">>;
+}, z.core.$strict>;
+export declare const docAppendMarkdownCommand: CommandModule<z.infer<typeof inputSchema>, DocAppendMarkdownOutput>;
+export {};
+//# sourceMappingURL=append-markdown.d.ts.map

package/dist/commands/doc/append-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-markdown.d.ts","sourceRoot":"","sources":["../../../src/commands/doc/append-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAKnE,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,wBAAwB,CAAC;AAGhC,QAAA,MAAM,WAAW;;;;;kBA2Cd,CAAC;AAeJ,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAClD,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAC3B,uBAAuB,CAuGxB,CAAC"}