@claudexor/cli 3.0.4 → 3.1.1

package/dist/cli-error.js

@@ -0,0 +1,308 @@
+/**
+ * The ONE CLI result/error projector (D-7, GH #28). Every failure class —
+ * argument/usage validation, pre-daemon bootstrap, typed preflight/daemon
+ * problems, transport errors, and unexpected exceptions — is normalized into a
+ * single typed problem and rendered as EXACTLY ONE JSON envelope on stdout
+ * (`--json` mode) or one human line on stderr (text mode), both derived from
+ * the SAME typed object. A central category -> exit-code table owns the codes:
+ * usage/validation = 2, operational failure = 1.
+ *
+ * This projector is intentionally dependency-light: it imports only the CLI IO
+ * owner and the typed `ControlProblem`/Zod shapes. It never needs the daemon,
+ * writable state, or a schema-generation step that could itself fail — so it is
+ * a valid last-resort serializer even when bootstrap failed.
+ *
+ * The run-verb SUCCESS envelope (`{runId, runDir, status, ...}`) does NOT flow
+ * through here: the projector owns FAILURE paths and the non-run commands whose
+ * error handling was previously ad-hoc. The failure envelope keeps a legacy
+ * `error` alias of `message` so existing consumers/tests that read `error`
+ * keep working.
+ */
+import { ControlProblem } from "@claudexor/schema";
+import { redactSecrets } from "@claudexor/util";
+import { printJson, printJsonLine } from "./cli-io.js";
+/** The central category -> process exit-code table (the one owner). */
+const CATEGORY_EXIT = {
+    usage: 2,
+    operational: 1,
+};
+/** A typed CLI failure: category picks the exit code, the rest survive projection. */
+export class CliError extends Error {
+    category;
+    code;
+    retryable;
+    fieldErrors;
+    requiredActions;
+    details;
+    context;
+    constructor(category, message, fields = {}) {
+        super(message);
+        this.name = "CliError";
+        this.category = category;
+        this.code = fields.code;
+        this.retryable = fields.retryable;
+        this.fieldErrors = fields.fieldErrors;
+        this.requiredActions = fields.requiredActions;
+        this.details = fields.details;
+        this.context = fields.context;
+    }
+}
+/** A usage/validation failure (exit 2). An operational failure (exit 1) is
+ * `new CliError("operational", ...)` — most operational failures reach the
+ * projector as native throwables (Node errors, ControlProblem-derived errors)
+ * rather than a hand-built one. */
+export function usageError(message, fields = {}) {
+    return new CliError("usage", message, fields);
+}
+/**
+ * A structured minimum-value validation error matching the #28 contract shape:
+ * `{code:invalid_argument, message, details:{field, minimum}, fieldErrors}`.
+ */
+export function minIntError(field, minimum) {
+    const message = `--${field} must be at least ${minimum}`;
+    return new CliError("usage", message, {
+        code: "invalid_argument",
+        fieldErrors: { [field]: [message] },
+        details: { field, minimum },
+    });
+}
+/** Structural ZodError detection (no `zod` import — the projector stays
+ * dependency-light so it is a valid last-resort serializer). */
+function asZodIssues(err) {
+    if (err &&
+        typeof err === "object" &&
+        err.name === "ZodError" &&
+        Array.isArray(err.issues)) {
+        return err.issues;
+    }
+    return null;
+}
+/** Convert Zod issues into path->messages field errors (no serialized Zod dump). */
+export function zodFieldErrors(issues) {
+    const out = {};
+    for (const issue of issues) {
+        const key = issue.path.length > 0 ? issue.path.map((p) => String(p)).join(".") : "_";
+        (out[key] ??= []).push(issue.message);
+    }
+    return out;
+}
+/** A human one-liner from Zod issues — the first issue, never the whole object. */
+function zodMessage(issues) {
+    const first = issues[0];
+    if (!first)
+        return "invalid input";
+    const at = first.path.length > 0 ? ` at ${first.path.map((p) => String(p)).join(".")}` : "";
+    return `${first.message}${at}`;
+}
+const ERRNO_RE = /^E[A-Z0-9]+$/;
+const MAX_CONTEXT_STRING = 2000;
+/** Bound long string values in a typed context so a localized git/tool stderr
+ * is demoted to bounded evidence instead of flooding the envelope (QA-051). */
+export function boundContext(context) {
+    if (!context)
+        return undefined;
+    const keys = Object.keys(context);
+    if (keys.length === 0)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (typeof value === "string" && value.length > MAX_CONTEXT_STRING) {
+            out[key] =
+                `${value.slice(0, MAX_CONTEXT_STRING)}… (truncated ${value.length - MAX_CONTEXT_STRING} chars)`;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function nonEmptyRecord(value) {
+    return value && Object.keys(value).length > 0 ? value : undefined;
+}
+function nonEmptyArray(value) {
+    return value && value.length > 0 ? value : undefined;
+}
+/** A typed context record or undefined when empty. Unlike `boundContext` this
+ *  does NOT truncate — bounding is deferred to `redactProblem` so redaction of a
+ *  boundary-straddling token always runs on the FULL string first (finding 6). */
+function nonEmptyContext(context) {
+    return context && Object.keys(context).length > 0 ? context : undefined;
+}
+/**
+ * Normalize ANY thrown value into a typed problem. `defaultCategory` decides the
+ * exit code only when the throwable carries no category signal of its own — a
+ * flag-parsing context passes "usage", the top-level catch passes "operational".
+ */
+export function normalizeThrowable(err, defaultCategory) {
+    if (err instanceof CliError) {
+        return {
+            category: err.category,
+            message: err.message,
+            code: err.code,
+            retryable: err.retryable,
+            fieldErrors: nonEmptyRecord(err.fieldErrors),
+            requiredActions: nonEmptyArray(err.requiredActions),
+            details: err.details,
+            // RAW context here; redaction runs BEFORE truncation in redactProblem so a
+            // secret token straddling the truncation boundary cannot survive (finding 6).
+            context: nonEmptyContext(err.context),
+        };
+    }
+    const zodIssues = asZodIssues(err);
+    if (zodIssues) {
+        return {
+            category: "usage",
+            code: "invalid_argument",
+            message: zodMessage(zodIssues),
+            fieldErrors: zodFieldErrors(zodIssues),
+        };
+    }
+    if (err instanceof Error) {
+        const anyErr = err;
+        const code = typeof anyErr["code"] === "string" ? anyErr["code"] : undefined;
+        const status = typeof anyErr["status"] === "number" ? anyErr["status"] : undefined;
+        const category = status === 400 ||
+            status === 422 ||
+            code === "inline_secret_rejected" ||
+            code === "invalid_argument"
+            ? "usage"
+            : code && ERRNO_RE.test(code)
+                ? "operational"
+                : defaultCategory;
+        const retryable = typeof anyErr["retryable"] === "boolean" ? anyErr["retryable"] : undefined;
+        const fieldErrors = nonEmptyRecord(anyErr["fieldErrors"]);
+        const requiredActions = nonEmptyArray(anyErr["requiredActions"]);
+        // A Node system error's syscall/errno are stable machine detail.
+        const details = typeof anyErr["syscall"] === "string" || typeof anyErr["errno"] === "number"
+            ? {
+                ...(typeof anyErr["syscall"] === "string" ? { syscall: anyErr["syscall"] } : {}),
+                ...(typeof anyErr["errno"] === "number" ? { errno: anyErr["errno"] } : {}),
+            }
+            : undefined;
+        return {
+            category,
+            message: err.message,
+            code,
+            retryable,
+            fieldErrors,
+            requiredActions,
+            details,
+        };
+    }
+    return { category: defaultCategory, message: String(err) };
+}
+/** Recursively redact secret-like tokens from any projected value: strings are
+ *  redacted directly; arrays and plain objects are mapped so a token nested in
+ *  `details`/`context` (a runtime-assembled git/tool stderr, an errored URL)
+ *  never leaks. Non-string leaves pass through untouched. */
+function redactUnknown(value) {
+    if (typeof value === "string")
+        return redactSecrets(value);
+    if (Array.isArray(value))
+        return value.map(redactUnknown);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = redactUnknown(v);
+        return out;
+    }
+    return value;
+}
+/**
+ * The SINGLE redaction owner for the projector (QA — runtime-assembled tokens):
+ * every human/machine string a failure envelope renders — message, field-error
+ * lines, required actions, and details/context leaves — is passed through
+ * `redactSecrets` here, so a token that reached a thrown message or a bounded
+ * git/tool context is masked once, at the one place that serializes failures.
+ */
+function redactProblem(p) {
+    return {
+        ...p,
+        message: redactSecrets(p.message),
+        fieldErrors: p.fieldErrors
+            ? Object.fromEntries(Object.entries(p.fieldErrors).map(([k, v]) => [k, v.map((s) => redactSecrets(s))]))
+            : undefined,
+        requiredActions: p.requiredActions?.map((s) => redactSecrets(s)),
+        details: p.details ? redactUnknown(p.details) : undefined,
+        // Redact THEN bound: a secret token that straddles the MAX_CONTEXT_STRING
+        // boundary is masked on the full string before truncation, so a split token
+        // can never evade the detector (finding 6).
+        context: p.context
+            ? boundContext(redactUnknown(p.context))
+            : undefined,
+    };
+}
+/**
+ * THE projector: render any thrown value as one failure envelope (json) or one
+ * stderr line (text), and return the process exit code. Human stderr and the
+ * JSON envelope are generated from the SAME normalized problem, and every string
+ * they carry is secret-redacted once here (the single owner).
+ */
+export function renderCliFailure(json, err, opts = {}) {
+    const p = redactProblem(normalizeThrowable(err, opts.defaultCategory ?? "operational"));
+    const exitCode = CATEGORY_EXIT[p.category];
+    const prefix = opts.messagePrefix;
+    const message = prefix && !p.message.startsWith(prefix) ? `${prefix} ${p.message}` : p.message;
+    if (json) {
+        const envelope = {
+            // Per-command extras first; every canonical field below overrides a
+            // same-named extra so the failure shape can't be forged. Redacted once
+            // here (the single owner) like everything else in the envelope.
+            ...(opts.extras ? redactUnknown(opts.extras) : {}),
+            ok: false,
+            exitCode,
+            ...(p.code ? { code: p.code } : {}),
+            message,
+            // Legacy alias: earlier CLI envelopes and their consumers read `error`.
+            error: message,
+            ...(p.retryable !== undefined ? { retryable: p.retryable } : {}),
+            ...(p.fieldErrors ? { fieldErrors: p.fieldErrors } : {}),
+            ...(p.requiredActions ? { requiredActions: p.requiredActions } : {}),
+            ...(p.details ? { details: p.details } : {}),
+            ...(p.context ? { context: p.context } : {}),
+        };
+        if (opts.stream)
+            printJsonLine(envelope);
+        else
+            printJson(envelope);
+    }
+    else {
+        process.stderr.write(`${message}\n`);
+    }
+    return exitCode;
+}
+/**
+ * Build a typed CliError from a failed control-API response body. A typed
+ * `ControlProblem` (code/message/retryable/fieldErrors/requiredActions/context)
+ * is preserved intact — never flattened to a bare string. The exit category is
+ * derived from the HTTP status: 400/422 are validation (exit 2), everything
+ * else is an operational failure (exit 1). Context strings are bounded so a
+ * localized git/tool stderr rides as bounded evidence.
+ */
+export function controlProblemError(status, body, fallbackMessage) {
+    const category = status === 400 || status === 422 ? "usage" : "operational";
+    const parsed = ControlProblem.safeParse(body);
+    if (parsed.success) {
+        const pb = parsed.data;
+        return new CliError(category, pb.message || fallbackMessage, {
+            code: pb.code,
+            retryable: pb.retryable,
+            fieldErrors: nonEmptyRecord(pb.fieldErrors),
+            requiredActions: nonEmptyArray(pb.requiredActions),
+            // RAW: redactProblem redacts before it bounds (finding 6).
+            context: nonEmptyContext(pb.context),
+            ...(pb.evidenceRefs.length > 0 ? { details: { evidenceRefs: pb.evidenceRefs } } : {}),
+        });
+    }
+    // Not a typed ControlProblem: salvage message/error/code without inventing fields.
+    const record = body && typeof body === "object" ? body : {};
+    const message = typeof record["message"] === "string"
+        ? record["message"]
+        : typeof record["error"] === "string"
+            ? record["error"]
+            : fallbackMessage;
+    const code = typeof record["code"] === "string" ? record["code"] : undefined;
+    const retryable = typeof record["retryable"] === "boolean" ? record["retryable"] : undefined;
+    return new CliError(category, message, { code, retryable });
+}
+//# sourceMappingURL=cli-error.js.map

package/dist/cli-error.js.map

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

package/dist/cli-io.d.ts

@@ -8,6 +8,15 @@ export declare function printJson(value: unknown): void;
 /** One COMPACT JSON object per line — the NDJSON contract (--json-stream). A
  *  pretty multi-line object would break `for line in stream: json.loads(line)`. */
 export declare function printJsonLine(value: unknown): void;
+/**
+ * A usage/validation failure (exit 2). The JSON envelope aligns with the D-7
+ * projector shape ({ok, exitCode, code, message}) while keeping the legacy
+ * `error` alias for existing consumers. The `code` uses the SAME vocabulary the
+ * projector stamps for this class (`invalid_argument`, matching `minIntError`
+ * and the Zod path) so a machine consumer never sees two names for one failure.
+ * Typed failures (field errors, domain codes) go through `renderCliFailure` in
+ * cli-error.ts instead.
+ */
 export declare function printUsageError(json: boolean, error: string): number;
 export declare function statusGlyph(status: string): string;
 export declare function authSourceAvailability(status: {

package/dist/cli-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-io.d.ts","sourceRoot":"","sources":["../src/cli-io.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAErC;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED;mFACmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;QACtD,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;KAC/C,EAAE,CAAC;CACL,GAAG,MAAM,CAST;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5D,GAAG,MAAM,CAIT"}
+{"version":3,"file":"cli-io.d.ts","sourceRoot":"","sources":["../src/cli-io.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAErC;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED;mFACmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;QACtD,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;KAC/C,EAAE,CAAC;CACL,GAAG,MAAM,CAST;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5D,GAAG,MAAM,CAIT"}

package/dist/cli-io.js

@@ -14,9 +14,18 @@ export function printJson(value) {
 export function printJsonLine(value) {
     process.stdout.write(JSON.stringify(value) + "\n");
 }
+/**
+ * A usage/validation failure (exit 2). The JSON envelope aligns with the D-7
+ * projector shape ({ok, exitCode, code, message}) while keeping the legacy
+ * `error` alias for existing consumers. The `code` uses the SAME vocabulary the
+ * projector stamps for this class (`invalid_argument`, matching `minIntError`
+ * and the Zod path) so a machine consumer never sees two names for one failure.
+ * Typed failures (field errors, domain codes) go through `renderCliFailure` in
+ * cli-error.ts instead.
+ */
 export function printUsageError(json, error) {
     if (json)
-        printJson({ ok: false, exitCode: 2, error });
+        printJson({ ok: false, exitCode: 2, code: "invalid_argument", message: error, error });
     else
         process.stderr.write(`${error}\n`);
     return 2;

package/dist/cli-io.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-io.js","sourceRoot":"","sources":["../src/cli-io.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED;mFACmF;AACnF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,KAAa;IAC1D,IAAI,IAAI;QAAE,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;;QAClD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAMtC;IACC,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,wBAAwB,CAAC;IAC1D,OAAO,OAAO;SACX,GAAG,CACF,CAAC,MAAM,EAAE,EAAE,CACT,GAAG,MAAM,CAAC,MAAM,iBAAiB,MAAM,CAAC,YAAY,iBAAiB,MAAM,CAAC,YAAY,GAAG,CAC9F;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAE7B;IACC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACvC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"cli-io.js","sourceRoot":"","sources":["../src/cli-io.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED;mFACmF;AACnF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,KAAa;IAC1D,IAAI,IAAI;QAAE,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;;QAC5F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAMtC;IACC,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,wBAAwB,CAAC;IAC1D,OAAO,OAAO;SACX,GAAG,CACF,CAAC,MAAM,EAAE,EAAE,CACT,GAAG,MAAM,CAAC,MAAM,iBAAiB,MAAM,CAAC,YAAY,iBAAiB,MAAM,CAAC,YAAY,GAAG,CAC9F;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAE7B;IACC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACvC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC"}