looply-cli 0.0.0-stage → 0.3.0

package/dist/repos-cmd.d.ts

@@ -0,0 +1,80 @@
+import { type CombinedVerdict, type CrossRepoNeed } from '@looply/core';
+import { type CompatibleRecord } from './compatible-sets';
+/**
+ * `looply repos` — THE CONSUMER D7 SAYS THIS MUST HAVE.
+ *
+ * 🔴 *"Do not reduce this to a manifest writer with no consumer."* A recorded
+ * compatible-revision set that nothing ever asks about is a log line pretending
+ * to be a safeguard. This is the asking: it reads what was accepted, reads where
+ * the repositories actually are now, and says whether the set still holds.
+ *
+ * Three verbs, and the middle one is the whole feature:
+ *
+ *   looply repos                     what is true now
+ *   looply repos --accept            write down the revisions as compatible
+ *   looply repos --published <id>    one repository published; the rest remain
+ *
+ * ⚠️ IT PUBLISHES NOTHING ITSELF, and that is deliberate. Publication across
+ * repositories is not atomic and this does not pretend otherwise: it records
+ * that a step happened and says what is left, so an interruption leaves a
+ * resumable state rather than a mystery.
+ */
+export declare const REPOS_USAGE: string;
+export interface ReposDeps {
+    /** Declared identities, from `repos:` in the config. */
+    declared(): readonly {
+        id: string;
+        path: string;
+    }[];
+    /**
+     * This project's own declared identity, worked out from the paths. Optional:
+     * a caller that omits it gets no circularity check rather than a wrong one.
+     */
+    self?(): string | null;
+    /**
+     * What this project waits for another repository to publish, from
+     * `cross_repo_needs:`. Absent and empty mean the same: nothing is waited for.
+     */
+    needs?(): readonly CrossRepoNeed[];
+    /**
+     * Where a repository is now.
+     *
+     * ⚠️ NULL, NEVER A GUESS. An unreadable repository must reach
+     * `combinedAcceptance` as absent so it answers `unmeasurable`; inventing a sha
+     * here would turn "I could not look" into "it has drifted".
+     */
+    revisionOf(repo: {
+        id: string;
+        path: string;
+    }): Promise<{
+        sha: string;
+        from: string;
+    } | null>;
+    records(): Promise<CompatibleRecord[]>;
+    append(record: CompatibleRecord): Promise<void>;
+    now(): string;
+    newId(): string;
+    out(line: string): void;
+    err(line: string): void;
+}
+export declare const EXIT_OK = 0;
+export declare const EXIT_REFUSED = 3;
+export declare const EXIT_USAGE = 2;
+/**
+ * 🔴 NOTHING WAS ESTABLISHED, AND A SCRIPT MUST NOT READ IT AS A REFUSAL.
+ *
+ * A repository that could not be read has not drifted — nobody knows — and the
+ * two call for opposite things: a refusal is answered by fixing the drift, and
+ * this is answered by looking again. `sessions-cmd.ts` keeps the same fourth
+ * code for the same reason, in its own words: "a script that retried a refusal
+ * would be wrong and a script that ignored an unmeasurable would be worse".
+ */
+export declare const EXIT_UNMEASURABLE = 4;
+export declare function reposCommand(argv: readonly string[], deps: ReposDeps): Promise<number>;
+/**
+ * ⚠️ `partial` IS NOT A FAILURE and must not exit non-zero. It is the expected
+ * middle of a publication that cannot be atomic, and a script that treats it as
+ * an error would stop exactly where it should carry on to the next repository.
+ */
+export declare function verdictExit(v: CombinedVerdict): number;
+//# sourceMappingURL=repos-cmd.d.ts.map

package/dist/repos-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repos-cmd.d.ts","sourceRoot":"","sources":["../src/repos-cmd.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAqC,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE7F;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,WAAW,QAIZ,CAAC;AAEb,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,QAAQ,IAAI,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpD;;;OAGG;IACH,IAAI,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,IAAI,SAAS,aAAa,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC9F,OAAO,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACvC,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,IAAI,MAAM,CAAC;IAChB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,wBAAsB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA0M5F;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAEtD"}

package/dist/repos-cmd.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_UNMEASURABLE = exports.EXIT_USAGE = exports.EXIT_REFUSED = exports.EXIT_OK = exports.REPOS_USAGE = void 0;
+exports.reposCommand = reposCommand;
+exports.verdictExit = verdictExit;
+const core_1 = require("@looply/core");
+const compatible_sets_1 = require("./compatible-sets");
+/**
+ * `looply repos` — THE CONSUMER D7 SAYS THIS MUST HAVE.
+ *
+ * 🔴 *"Do not reduce this to a manifest writer with no consumer."* A recorded
+ * compatible-revision set that nothing ever asks about is a log line pretending
+ * to be a safeguard. This is the asking: it reads what was accepted, reads where
+ * the repositories actually are now, and says whether the set still holds.
+ *
+ * Three verbs, and the middle one is the whole feature:
+ *
+ *   looply repos                     what is true now
+ *   looply repos --accept            write down the revisions as compatible
+ *   looply repos --published <id>    one repository published; the rest remain
+ *
+ * ⚠️ IT PUBLISHES NOTHING ITSELF, and that is deliberate. Publication across
+ * repositories is not atomic and this does not pretend otherwise: it records
+ * that a step happened and says what is left, so an interruption leaves a
+ * resumable state rather than a mystery.
+ */
+exports.REPOS_USAGE = [
+    'looply repos                      where each declared repository is, and whether the accepted set still holds',
+    'looply repos --accept             record the current revisions as a compatible set',
+    'looply repos --published <repo>   record that one repository published the newest set',
+].join('\n');
+exports.EXIT_OK = 0;
+exports.EXIT_REFUSED = 3;
+exports.EXIT_USAGE = 2;
+/**
+ * 🔴 NOTHING WAS ESTABLISHED, AND A SCRIPT MUST NOT READ IT AS A REFUSAL.
+ *
+ * A repository that could not be read has not drifted — nobody knows — and the
+ * two call for opposite things: a refusal is answered by fixing the drift, and
+ * this is answered by looking again. `sessions-cmd.ts` keeps the same fourth
+ * code for the same reason, in its own words: "a script that retried a refusal
+ * would be wrong and a script that ignored an unmeasurable would be worse".
+ */
+exports.EXIT_UNMEASURABLE = 4;
+async function reposCommand(argv, deps) {
+    /**
+     * 🔴 THE ARGUMENTS ARE CHECKED BEFORE ANYTHING IS READ OR WRITTEN. Asked for
+     * both verbs at once, the first shape of this took the `--accept` branch and
+     * WROTE A SET — so `looply repos --published --accept`, which is a person
+     * mistyping one command, silently accepted a new compatible set instead of
+     * refusing. Two verbs is not a preference to resolve; it is a sentence with
+     * two meanings, and the only safe reading is neither.
+     */
+    if (argv.includes('--accept') && argv.includes('--published')) {
+        deps.err(`looply repos: --accept and --published are two different things to do. Pick one.\n\n${exports.REPOS_USAGE}`);
+        return exports.EXIT_USAGE;
+    }
+    /**
+     * 🔴 AN ARGUMENT THIS DOES NOT KNOW IS A REFUSAL, NOT A SHRUG. Ignoring it
+     * meant `looply repos --acept` — one missing letter — printed a perfectly
+     * true status page and exited 0, so somebody who meant to accept a set walked
+     * away believing there was nothing to do. That is the same silent no-op twice
+     * more over, and the fix is to refuse the whole class rather than each case.
+     */
+    const unknown = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--accept')
+            continue;
+        // Whatever follows `--published` is its value; whether it names a real
+        // repository is a question for later, with the declarations in hand.
+        if (argv[i] === '--published') {
+            i += 1;
+            continue;
+        }
+        unknown.push(argv[i]);
+    }
+    if (unknown.length > 0) {
+        deps.err(`looply repos: ${unknown.join(', ')} — no idea what that means.\n\n${exports.REPOS_USAGE}`);
+        return exports.EXIT_USAGE;
+    }
+    const declared = deps.declared();
+    if (declared.length === 0) {
+        deps.err('looply repos: this project declares no other repositories. Add `repos:` to .looply/config.yaml ' +
+            '— each entry an id and a local path.');
+        return exports.EXIT_USAGE;
+    }
+    /** Read once and shared by every verb: three questions about one moment. */
+    const now = [];
+    const unreadable = [];
+    const shown = new Map();
+    for (const r of declared) {
+        const at = await deps.revisionOf(r);
+        if (at === null) {
+            unreadable.push(r.id);
+            continue;
+        }
+        now.push({ repo: r.id, sha: at.sha });
+        shown.set(r.id, at.from);
+    }
+    if (argv.includes('--accept')) {
+        if (unreadable.length > 0) {
+            deps.err(`looply repos --accept: refusing — ${unreadable.join(', ')} could not be read, and a set that omits a ` +
+                'declared repository is a set nobody can check');
+            return exports.EXIT_REFUSED;
+        }
+        const setId = deps.newId();
+        await deps.append({ id: setId, kind: 'accepted', setId, at: deps.now(), revisions: now });
+        deps.out(`repos: accepted ${setId} — ${now.map((r) => `${r.repo}@${r.sha.slice(0, 7)}`).join(', ')}`);
+        deps.out('  nothing is published yet. `looply repos --published <repo>` records each step.');
+        return exports.EXIT_OK;
+    }
+    const records = await deps.records();
+    const setId = (0, compatible_sets_1.newestSetId)(records);
+    const publishAt = argv.indexOf('--published');
+    if (setId === null) {
+        /**
+         * ⚠️ ASKED TO RECORD A PUBLICATION WITH NOTHING ACCEPTED, THIS SAYS SO.
+         * Falling through to the status report below would print a perfectly true
+         * page and exit 0 — and the person who asked to record a step would have no
+         * way to tell that nothing was recorded.
+         */
+        if (publishAt >= 0) {
+            deps.err('looply repos --published: refusing — nothing has been accepted as compatible yet, so there is no set to ' +
+                'publish against. `looply repos --accept` first.');
+            return exports.EXIT_REFUSED;
+        }
+        deps.out('repos: no compatible set has been accepted yet.');
+        for (const r of declared) {
+            deps.out(`  ${r.id.padEnd(16)} ${shown.get(r.id) ?? 'could not be read'}`);
+        }
+        deps.out('  `looply repos --accept` writes the current revisions down as compatible.');
+        return exports.EXIT_OK;
+    }
+    if (publishAt >= 0) {
+        const repo = argv[publishAt + 1];
+        if (repo === undefined || repo.startsWith('--')) {
+            deps.err(`looply repos --published: which repository?\n\n${exports.REPOS_USAGE}`);
+            return exports.EXIT_USAGE;
+        }
+        const before = (0, compatible_sets_1.setFrom)(records, setId);
+        if (before === null) {
+            deps.err(`looply repos --published: ${setId} has no acceptance on record`);
+            return exports.EXIT_REFUSED;
+        }
+        /**
+         * 🔴 THE DECISION IS `publicationRuling`, NOT THIS FUNCTION, AND §6.D IS
+         * WHY. The charter asks for a RUN to drive this same workflow, and a run
+         * that wrote its own lines would be a second implementation of these
+         * refusals — the one that forgets the drift check is the one that writes
+         * down a compatible pair that does not exist. A behaviour with two callers
+         * and one implementation cannot drift between them.
+         *
+         * Every refusal that used to live here still happens, in the same order,
+         * and is now shared: drift before anything is recorded, a repository this
+         * project does not declare, and one declared after the set was accepted.
+         */
+        const ruling = (0, core_1.publicationRuling)({
+            declared: declared.map((d) => d.id),
+            set: before,
+            current: new Map(now.map((r) => [r.repo, r.sha])),
+            repo,
+        });
+        if (ruling.kind === 'refused' || ruling.kind === 'unmeasurable') {
+            deps.err(`looply repos --published: ${(0, core_1.describePublicationRuling)(ruling)}`);
+            return ruling.kind === 'unmeasurable' ? exports.EXIT_UNMEASURABLE : exports.EXIT_REFUSED;
+        }
+        if (ruling.kind === 'already') {
+            deps.out(`repos: ${(0, core_1.describePublicationRuling)(ruling)}`);
+            return exports.EXIT_OK;
+        }
+        await deps.append({ id: (0, compatible_sets_1.publishedId)(setId, repo), kind: 'published', setId, at: deps.now(), repo });
+        deps.out(`repos: ${(0, core_1.describePublicationRuling)(ruling)}`);
+    }
+    const after = (0, compatible_sets_1.setFrom)(await deps.records(), setId);
+    if (after === null) {
+        deps.err(`looply repos: ${setId} has no acceptance on record`);
+        return exports.EXIT_REFUSED;
+    }
+    const verdict = (0, core_1.combinedAcceptance)({
+        declared: declared.map((d) => d.id),
+        set: after,
+        current: new Map(now.map((r) => [r.repo, r.sha])),
+    });
+    deps.out(`repos: ${setId} accepted ${after.at}`);
+    for (const r of declared) {
+        const named = after.revisions.find((x) => x.repo === r.id);
+        const isAt = now.find((x) => x.repo === r.id);
+        const mark = after.published.includes(r.id) ? 'published' : 'to publish';
+        deps.out(`  ${r.id.padEnd(16)} ${(named === undefined ? 'not in the set' : named.sha.slice(0, 7)).padEnd(16)} ` +
+            `now ${(isAt === undefined ? 'unreadable' : isAt.sha.slice(0, 7)).padEnd(12)} ${mark}`);
+    }
+    const said = (0, core_1.describeCombined)(verdict);
+    deps.out(said === null ? `  COMPLETE — every declared repository published this set and is still at it` : `  ${said}`);
+    /**
+     * 🔴 AND WHAT THIS PROJECT IS STILL WAITING FOR, which is a different question
+     * from whether the set holds.
+     *
+     * `combinedAcceptance` answers "is this convergence finished". A need answers
+     * "may I start" — and the two come apart in both directions: a PARTIAL set can
+     * already satisfy a need whose repository happens to be one of the published
+     * ones, and a COMPLETE set satisfies a need for a repository it never named at
+     * all only by accident. So the needs are asked separately and reported
+     * separately.
+     *
+     * ⚠️ IT DOES NOT CHANGE THE EXIT CODE. The verdict is about the set; a need is
+     * about this project's own readiness, and a script driving publication must
+     * not stop because some unrelated dependency is outstanding. The line is
+     * information, and `crossRepoReady` is what a caller asks when it wants the
+     * answer as a decision.
+     */
+    const needs = deps.needs?.() ?? [];
+    if (needs.length > 0) {
+        const blockers = (0, core_1.crossRepoBlockedBy)({
+            needs,
+            declared: declared.map((d) => d.id),
+            self: deps.self?.() ?? null,
+            set: after,
+            current: new Map(now.map((r) => [r.repo, r.sha])),
+        });
+        const waiting = (0, core_1.describeCrossRepoBlockers)(blockers);
+        if (waiting === null) {
+            deps.out(`  needs: all ${needs.length} met — every repository this project waits on has published`);
+        }
+        else {
+            deps.out(`  needs: ${waiting}`);
+            for (const b of blockers)
+                deps.out(`    ${b.repo.padEnd(16)} ${b.reason.padEnd(12)} ${b.what}`);
+        }
+    }
+    return verdictExit(verdict);
+}
+/**
+ * ⚠️ `partial` IS NOT A FAILURE and must not exit non-zero. It is the expected
+ * middle of a publication that cannot be atomic, and a script that treats it as
+ * an error would stop exactly where it should carry on to the next repository.
+ */
+function verdictExit(v) {
+    return v.kind === 'complete' || v.kind === 'partial' ? exports.EXIT_OK : exports.EXIT_REFUSED;
+}
+//# sourceMappingURL=repos-cmd.js.map

package/dist/repos-cmd.js.map

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

package/dist/request-body-shape.d.ts

@@ -0,0 +1,93 @@
+/**
+ * WHAT A CLIENT SENDS, AND WHETHER THE ROUTE READS IT.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE OTHER HALF OF THE BOUNDARY, AND IT HAS ALREADY COST US ONCE.
+ *
+ * `@looply/sdk`'s `decideApproval` sent `version` where the route reads
+ * `expectedVersion`. It would have 400'd on every call — on the path that spends
+ * a person's authorisation — and nothing could see it: the body is `unknown` on
+ * the wire, so no type on either side disagrees.
+ *
+ * Path parity checks the PATH. The declared-shape check reads the RESPONSE. A
+ * field a client sends that no route reads is the third case, and it is the one
+ * with the worst failure mode of the three, because the two outcomes are a 400
+ * (loud) and being silently ignored (a setting that never applies, a note that
+ * never saves, a version guard that never guards).
+ *
+ * ⚠️ THIS READS SOURCE, NOT TYPES. It is a small honest parser: it reports what
+ * it cannot read rather than passing over it, because a checker that silently
+ * skips is how a fifth of a corpus disappears under a confident summary line.
+ */
+export interface RouteBody {
+    /** `POST`, `PATCH`, … */
+    method: string;
+    /** Path with `:params` left in, e.g. `/v1/projects/:id/approvals/:approvalId`. */
+    path: string;
+    /** Keys the handler reads off the body — `body?.expectedVersion` → `expectedVersion`. */
+    reads: string[];
+    /**
+     * Does the handler hand the WHOLE body somewhere instead of picking fields?
+     *
+     * 🔴 THE DIFFERENCE BETWEEN "READS NOTHING" AND "UNREADABLE". A handler that
+     * forwards `body` wholesale reads no named key, and treating that as "reads
+     * nothing" would flag every field a client sends to it. Reported, not guessed.
+     */
+    wholesale: boolean;
+    handler: string;
+}
+/** `@Controller('v1')` → `v1`. */
+export declare function controllerPrefix(source: string): string;
+export declare function routeBodies(source: string): RouteBody[];
+export interface SentBody {
+    /** The client method the call sits in. */
+    caller: string;
+    method: string;
+    /** Path with `${...}` interpolations replaced by `:param`, to match a route. */
+    path: string;
+    /**
+     * The path literal exactly as written, before normalisation.
+     *
+     * Kept because a caller may need to assert something about the SOURCE rather
+     * than the route — e.g. that no query string was ever written into a path
+     * literal. Asserting that on the normalised value would only prove a
+     * `replace` had run, which it always has.
+     */
+    rawPath: string;
+    /** Keys the client puts in the body. */
+    sends: string[];
+    /**
+     * Could the body be read at all?
+     *
+     * 🔴 FALSE IS NOT "SENDS NOTHING". A body built from a spread, a helper call
+     * or a variable this cannot resolve is UNREAD, and reporting it as empty would
+     * turn an unchecked call into a passing one.
+     */
+    readable: boolean;
+    raw: string;
+}
+/**
+ * Blanks comments, preserving LENGTH and NEWLINES.
+ *
+ * 🔴 ONE PARSER, USED BY BOTH HALVES OF THIS FILE. The client half stripped
+ * comments and the ROUTE half did not, so prose became evidence: a doc comment
+ * mentioning a field produced a phantom `body?.x` read, and a commented-out
+ * `@Post(...)` produced a phantom ROUTE. It failed in both directions at once --
+ * excusing a field the handler never reads, and inventing one it does.
+ *
+ * ⚠️ IT IS STRING-AWARE, WHICH A REGEX CANNOT BE. `'https://x'` contains `//`
+ * and a naive line-comment regex deletes the rest of that line -- taking
+ * any real `body?.x` on it with it. Quotes, double quotes, template literals and
+ * backslash escapes are copied through untouched.
+ *
+ * Length and newlines are preserved because callers index into the result:
+ * decorator offsets, `lastIndexOf`, and the line-based handler-name scan all
+ * stay valid, so stripping is invisible to everything except the text it removes.
+ *
+ * Known limit, stated rather than hidden: a STRING whose contents look like a
+ * read (`'body?.kind'`) is preserved, because it is data and this cannot tell
+ * data from code. No such string exists in the controllers today.
+ */
+export declare function stripComments(text: string): string;
+export declare function sentBodies(source: string): SentBody[];
+//# sourceMappingURL=request-body-shape.d.ts.map

package/dist/request-body-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-body-shape.d.ts","sourceRoot":"","sources":["../src/request-body-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,kCAAkC;AAClC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMvD;AAQD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CAsCvD;AAID,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AA+ID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoDlD;AAuCD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAuDrD"}