@pipeshub-ai/mcp 2.2.0 → 2.3.1

package/esm/cli/init-qm.js

@@ -0,0 +1,170 @@
+// `pipeshub init-qm <dir>` — scaffold the QM deployment-layer bundle into an
+// operator's deployment directory.
+//
+// Why this exists rather than "copy the folder from the repo": the bundle and
+// the CLI it describes are one contract. Copying by hand lets an operator end
+// up with a tool.json written for a different version of the binary that is
+// actually installed, and that mismatch is silent — an approval rule naming a
+// subcommand that no longer exists compiles to a pattern matching nothing.
+// Scaffolding from the installed package makes the two versions the same by
+// construction, and stamps the version into the Dockerfile's pin.
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError, EXIT } from "./config.js";
+/**
+ * Walk up from this module to the package root. The CLI runs from two possible
+ * layouts — `bin/pipeshub.js` (bundled) and `esm/cli/pipeshub.js` (tsc) — so a
+ * fixed number of `..` would be wrong for one of them.
+ */
+async function packageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            const raw = await readFile(join(dir, "package.json"), "utf8");
+            const pkg = JSON.parse(raw);
+            if (pkg.name === "@pipeshub-ai/mcp")
+                return dir;
+        }
+        catch {
+            // keep walking
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new CliError("could not locate the installed package root — reinstall @pipeshub-ai/mcp");
+}
+async function packageVersion(root) {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    return pkg.version ?? "latest";
+}
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Copy a directory tree, reporting what was written and what was left alone. */
+async function copyTree(from, to, force, written, skipped) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+        const src = join(from, entry.name);
+        const dst = join(to, entry.name);
+        if (entry.isDirectory()) {
+            await copyTree(src, dst, force, written, skipped);
+            continue;
+        }
+        if (!force && await exists(dst)) {
+            skipped.push(dst);
+            continue;
+        }
+        await copyFile(src, dst);
+        written.push(dst);
+    }
+}
+const DOCKERFILE_NOTE = (version) => `
+# --- PipesHub ---------------------------------------------------------------
+# Installs the \`pipeshub\` binary. Pin the version: the sandbox image and the
+# PipesHub instance's MCP tool surface need to stay compatible, and an unpinned
+# install turns a remote release into a silent change in agent behaviour.
+RUN npm install -g "@pipeshub-ai/mcp@${version}" \\
+ && pipeshub --help >/dev/null
+# ----------------------------------------------------------------------------
+`;
+export async function initQm(targetDir, force) {
+    const root = await packageRoot();
+    const bundle = join(root, "qm");
+    if (!await exists(join(bundle, "sandbox"))) {
+        throw new CliError(`the QM bundle is missing from the installed package (looked in ${bundle}). `
+            + "This build was packaged without it.");
+    }
+    const version = await packageVersion(root);
+    const dest = resolve(targetDir);
+    const written = [];
+    const skipped = [];
+    // Tools and skills copy cleanly — they are ours and live in their own
+    // subdirectories, so merging with an existing sandbox/ cannot collide with
+    // anything the operator wrote.
+    for (const sub of ["tools/pipeshub", "skills/pipeshub"]) {
+        await copyTree(join(bundle, "sandbox", sub), join(dest, "sandbox", sub), force, written, skipped);
+    }
+    // The Dockerfile is shared with whatever else the operator installs, so it is
+    // never overwritten. Create it if absent, append our block if it exists and
+    // has no PipesHub block yet, and otherwise leave it entirely alone.
+    const dockerfile = join(dest, "sandbox", "Dockerfile");
+    let dockerfileAction;
+    if (!await exists(dockerfile)) {
+        await copyFile(join(bundle, "sandbox", "Dockerfile"), dockerfile);
+        // Restamp the pin so it matches the version actually installed.
+        const body = await readFile(dockerfile, "utf8");
+        await writeFile(dockerfile, body.replace(/ARG PIPESHUB_CLI_VERSION=.*/, `ARG PIPESHUB_CLI_VERSION=${version}`), "utf8");
+        written.push(dockerfile);
+        dockerfileAction = "created";
+    }
+    else {
+        const body = await readFile(dockerfile, "utf8");
+        if (body.includes("@pipeshub-ai/mcp")) {
+            dockerfileAction = "manual";
+        }
+        else {
+            await writeFile(dockerfile, body.replace(/\n*$/, "\n") + DOCKERFILE_NOTE(version), "utf8");
+            dockerfileAction = "appended";
+        }
+    }
+    // Do not swallow this. The fragment carries the `sandbox.env` block the
+    // operator must merge in, so reporting a successful init without it leaves
+    // them with a scaffold that cannot reach PipesHub and no sign of why.
+    const fragmentPath = join(bundle, "qm.config.fragment.jsonc");
+    let configFragment;
+    try {
+        configFragment = await readFile(fragmentPath, "utf8");
+    }
+    catch (e) {
+        throw new CliError(`the QM bundle is incomplete — could not read ${fragmentPath} `
+            + `(${e.message}). Reinstall @pipeshub-ai/mcp.`);
+    }
+    return { written, skipped, dockerfileAction, version, configFragment };
+}
+export function renderInitReport(dest, r) {
+    const lines = [];
+    lines.push(`Scaffolded the PipesHub bundle into ${dest}`);
+    lines.push(`CLI version pinned: ${r.version}`);
+    lines.push("");
+    for (const f of r.written)
+        lines.push(`  wrote   ${f}`);
+    for (const f of r.skipped)
+        lines.push(`  kept    ${f}  (already existed — use --force to replace)`);
+    lines.push("");
+    if (r.dockerfileAction === "appended") {
+        lines.push("Appended the install block to your existing sandbox/Dockerfile.");
+    }
+    else if (r.dockerfileAction === "manual") {
+        lines.push("Your sandbox/Dockerfile already mentions @pipeshub-ai/mcp, so it was left"
+            + " untouched. Check the pinned version matches " + r.version + ".");
+    }
+    lines.push("");
+    lines.push("Two things left to do:");
+    lines.push("");
+    lines.push("1. Set your PipesHub origin in qm.config.jsonc. It must be a PUBLIC");
+    lines.push("   HTTPS address — QM sandboxes do not run on your machine, so");
+    lines.push("   localhost and LAN addresses are unreachable from them:");
+    lines.push("");
+    lines.push('     "sandbox": {');
+    lines.push('       "env": { "PIPESHUB_BASE_URL": "https://pipeshub.your-company.com" }');
+    lines.push("     }");
+    lines.push("");
+    lines.push("   Do NOT put anyone's token in sandbox.secretEnv — that is org-wide and");
+    lines.push("   would hand one person's credential to everybody. Each person adds");
+    lines.push("   their own to their own keychain (service: pipeshub, kind: env).");
+    lines.push("");
+    lines.push("2. Set `egress` in sandbox/tools/pipeshub/tool.json to your hostname,");
+    lines.push("   then run:  qm check && qm sandbox publish && qm up");
+    return lines.join("\n");
+}
+export const INIT_QM_EXIT = EXIT.OK;
+//# sourceMappingURL=init-qm.js.map

package/esm/cli/init-qm.js.map

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

package/esm/cli/pipeshub.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeshub.d.ts.map

package/esm/cli/pipeshub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeshub.d.ts","sourceRoot":"","sources":["../../src/cli/pipeshub.ts"],"names":[],"mappings":""}

package/esm/cli/pipeshub.js

@@ -0,0 +1,296 @@
+// `pipeshub` — a thin CLI over the PipesHub MCP endpoint, built for agent use.
+//
+// Design constraints worth stating at the top, because they are easy to erode:
+//
+//   - There is NO way to supply a credential on the command line. No
+//     `auth set`, no `auth import`, no `--token`, no `--print-token`. The
+//     keychain is the only credential path. A flag that accepts a token would
+//     end up in shell history, process listings, and eventually a transcript.
+//   - The token is never printed, in any command, in any mode.
+//   - Exit codes are contractual: agents branch on them.
+import { CliError, EXIT, resolveOrigin, resolveToken, } from "./config.js";
+import { newRequestId } from "./client.js";
+import { initQm, renderInitReport } from "./init-qm.js";
+import { ask, authStatus, connectHelp, directoryWhoami, get, search, sources, } from "./commands.js";
+const USAGE = `pipeshub — query your organization's PipesHub context layer
+
+USAGE
+  pipeshub <command> [options]
+
+COMMANDS
+  auth status                 show connection, user, org, scopes, expiry
+  auth connect-help           print the keychain setup steps
+  init-qm <dir>               scaffold the QM deployment-layer bundle (admin)
+  sources                     list searchable sources (ids for --app)
+  search <query>              locate records
+  ask <question>              ask a grounded question; returns citations
+  get <recordId>              fetch a record's content
+  directory whoami            the identity behind the current token
+
+OPTIONS
+  --json                      JSON output (default)
+  --text                      human-readable output where available
+  --limit <n>                 search: max results (default 10)
+  --app <id>                  search: restrict to a source id (repeatable)
+  --conversation <id>         ask: continue an existing conversation
+  --mode <internal|web>       ask: retrieval strategy (default internal)
+  --as <format>               get: server-side conversion, e.g. pdf
+  --out <path>                get: write to a file instead of stdout
+  --max-chars <n>             cap snippet/content length (default 2000)
+  --insecure-http             allow cleartext to a host outside the private allowlist
+  --force                     init-qm: overwrite files that already exist
+
+ENVIRONMENT
+  PIPESHUB_TOKEN     preferred; PIPESHUB_MCP_TOKEN also accepted
+  PIPESHUB_BASE_URL  origin, e.g. https://pipeshub.example.com
+                     PIPESHUB_MCP_URL also accepted (its /mcp path is stripped)
+
+EXIT CODES
+  0 ok · 2 usage · 3 not authenticated · 4 forbidden · 5 rate limited
+  6 no results (also: an 'ask' answer with no citations)
+
+Credentials come from your QM keychain. This CLI cannot accept one as an
+argument, by design. Run 'pipeshub auth connect-help' for setup steps.`;
+function parseFlags(argv) {
+    const flags = {
+        json: true,
+        limit: 10,
+        apps: [],
+        conversation: null,
+        mode: "internal",
+        as: null,
+        out: null,
+        maxChars: 2000,
+        insecureHttp: false,
+        force: false,
+    };
+    const positional = [];
+    const needValue = (name, value) => {
+        if (value === undefined) {
+            throw new CliError(`${name} requires a value`, EXIT.USAGE);
+        }
+        return value;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined)
+            continue;
+        switch (a) {
+            case "--json":
+                flags.json = true;
+                break;
+            case "--text":
+                flags.json = false;
+                break;
+            case "--insecure-http":
+                flags.insecureHttp = true;
+                break;
+            case "--force":
+                flags.force = true;
+                break;
+            case "--limit":
+                flags.limit = Number(needValue(a, argv[++i]));
+                break;
+            case "--app":
+                flags.apps.push(needValue(a, argv[++i]));
+                break;
+            case "--conversation":
+                flags.conversation = needValue(a, argv[++i]);
+                break;
+            case "--mode":
+                flags.mode = needValue(a, argv[++i]);
+                break;
+            case "--as":
+                flags.as = needValue(a, argv[++i]);
+                break;
+            case "--out":
+                flags.out = needValue(a, argv[++i]);
+                break;
+            case "--max-chars":
+                flags.maxChars = Number(needValue(a, argv[++i]));
+                break;
+            default:
+                if (a.startsWith("--")) {
+                    // Fail loudly rather than ignoring a flag the caller believed in.
+                    throw new CliError(`unknown option: ${a}`, EXIT.USAGE);
+                }
+                positional.push(a);
+        }
+    }
+    if (!Number.isFinite(flags.limit) || flags.limit <= 0) {
+        throw new CliError("--limit must be a positive number", EXIT.USAGE);
+    }
+    if (!Number.isFinite(flags.maxChars) || flags.maxChars <= 0) {
+        throw new CliError("--max-chars must be a positive number", EXIT.USAGE);
+    }
+    return { positional, flags };
+}
+/** `--mode internal|web` → the tool's `chatMode` vocabulary. */
+function resolveChatMode(mode) {
+    if (mode === "internal" || mode === "internal_search")
+        return "internal_search";
+    if (mode === "web" || mode === "web_search")
+        return "web_search";
+    throw new CliError(`--mode must be "internal" or "web" (got "${mode}"). The other chatMode `
+        + "values the API accepts (quick, verification, deep) are only valid for "
+        + "agent conversations, which v1 does not expose.", EXIT.USAGE);
+}
+/**
+ * Write and wait for the bytes to actually reach the pipe.
+ *
+ * `process.stdout` is asynchronous when it is a pipe — which is the normal
+ * case here, since the caller is an agent capturing output. `process.exit()`
+ * does not flush it, so a payload larger than the pipe buffer is silently cut
+ * off (measured: a 2,000,015-byte write delivered 1,048,576 bytes) while the
+ * exit code still reports success. The consumer then parses truncated JSON.
+ *
+ * The `write` callback fires once the chunk has been handed to the underlying
+ * resource, so exiting after it is safe — and unlike setting `process.exitCode`
+ * and returning, it does not wait on undici's keep-alive sockets.
+ */
+function writeFlushed(stream, text) {
+    return new Promise((resolve) => {
+        stream.write(text, () => resolve());
+    });
+}
+function emit(outcome, json) {
+    if (!json && outcome.text !== undefined) {
+        return writeFlushed(process.stdout, outcome.text + "\n");
+    }
+    return writeFlushed(process.stdout, JSON.stringify(outcome.payload, null, 2) + "\n");
+}
+async function run(argv) {
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+        await writeFlushed(process.stdout, USAGE + "\n");
+        return EXIT.OK;
+    }
+    const { positional, flags } = parseFlags(argv);
+    const command = positional[0] ?? "";
+    const sub = positional[1] ?? "";
+    // Refuse the credential-mutating shapes explicitly, so the failure explains
+    // itself instead of looking like a typo. These names must never work.
+    if (command === "auth" && ["set", "import", "login", "add"].includes(sub)) {
+        await writeFlushed(process.stderr, `pipeshub auth ${sub} does not exist, deliberately.\n`
+            + "Credentials come from your QM keychain — run "
+            + "'pipeshub auth connect-help' for the steps.\n");
+        return EXIT.USAGE;
+    }
+    const requestId = newRequestId();
+    const token = resolveToken();
+    const origin = resolveOrigin();
+    // connect-help must work with no credential at all — it is the thing you run
+    // precisely when you have none.
+    if (command === "auth" && sub === "connect-help") {
+        const outcome = connectHelp({
+            origin: origin ?? "",
+            token: "",
+            insecureHttp: flags.insecureHttp,
+            requestId,
+            json: flags.json,
+            maxChars: flags.maxChars,
+        });
+        await emit(outcome, flags.json);
+        return outcome.exit;
+    }
+    // Scaffolding is an admin task performed before any credential exists, so it
+    // runs before the token and base-URL checks.
+    if (command === "init-qm") {
+        const dir = positional[1] ?? "";
+        if (dir === "") {
+            throw new CliError("init-qm requires a target directory", EXIT.USAGE);
+        }
+        const result = await initQm(dir, flags.force);
+        const report = renderInitReport(dir, result);
+        if (flags.json) {
+            await writeFlushed(process.stdout, JSON.stringify({
+                requestId,
+                target: dir,
+                version: result.version,
+                written: result.written,
+                skipped: result.skipped,
+                dockerfile: result.dockerfileAction,
+            }, null, 2) + "\n");
+        }
+        else {
+            await writeFlushed(process.stdout, report + "\n");
+        }
+        return EXIT.OK;
+    }
+    if (origin === null) {
+        // Report the missing credential too when both are absent. Otherwise a
+        // person whose actual problem is "I never added my token" is told about an
+        // admin-level setting, and goes looking in the wrong place.
+        const alsoNoToken = token === null
+            ? " Your PipesHub credential is also missing ($PIPESHUB_TOKEN is unset)."
+            : "";
+        throw new CliError("PIPESHUB_BASE_URL is not set — an admin sets it once for the deployment."
+            + alsoNoToken
+            + " Run 'pipeshub auth connect-help' for the steps.", EXIT.USAGE);
+    }
+    if (token === null) {
+        throw new CliError("No PipesHub credential found ($PIPESHUB_TOKEN is unset). "
+            + "Run 'pipeshub auth connect-help' for setup steps.", EXIT.UNAUTHENTICATED);
+    }
+    const ctx = {
+        origin,
+        token,
+        insecureHttp: flags.insecureHttp,
+        requestId,
+        json: flags.json,
+        maxChars: flags.maxChars,
+    };
+    let outcome;
+    switch (command) {
+        case "auth":
+            if (sub !== "status") {
+                throw new CliError(`unknown subcommand: auth ${sub || "(none)"}`, EXIT.USAGE);
+            }
+            outcome = await authStatus(ctx);
+            break;
+        case "sources":
+            outcome = await sources(ctx);
+            break;
+        case "search": {
+            const query = positional.slice(1).join(" ").trim();
+            if (query === "")
+                throw new CliError("search requires a query", EXIT.USAGE);
+            outcome = await search(ctx, query, flags.limit, flags.apps);
+            break;
+        }
+        case "ask": {
+            const query = positional.slice(1).join(" ").trim();
+            if (query === "")
+                throw new CliError("ask requires a question", EXIT.USAGE);
+            outcome = await ask(ctx, query, flags.conversation, resolveChatMode(flags.mode));
+            break;
+        }
+        case "get": {
+            const recordId = positional[1] ?? "";
+            if (recordId === "")
+                throw new CliError("get requires a recordId", EXIT.USAGE);
+            outcome = await get(ctx, recordId, flags.as, flags.out);
+            break;
+        }
+        case "directory":
+            if (sub !== "whoami") {
+                throw new CliError("v1 supports 'directory whoami' only. 'groups' needs usergroup:read, "
+                    + "which is not in the stock MCP_SCOPES and cannot be minted on a "
+                    + "default instance; 'teams' needs team:read, which the agent "
+                    + "preset excludes.", EXIT.USAGE);
+            }
+            outcome = await directoryWhoami(ctx);
+            break;
+        default:
+            throw new CliError(`unknown command: ${command}`, EXIT.USAGE);
+    }
+    await emit(outcome, flags.json);
+    return outcome.exit;
+}
+const code = await run(process.argv.slice(2)).catch(async (e) => {
+    const err = e;
+    const exit = typeof err.code === "number" ? err.code : EXIT.ERROR;
+    await writeFlushed(process.stderr, `pipeshub: ${err.message}\n`);
+    return exit;
+});
+process.exit(code);
+//# sourceMappingURL=pipeshub.js.map

package/esm/cli/pipeshub.js.map

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

package/esm/funcs/connectorLookupRecordByIdentifier.d.ts

@@ -0,0 +1,68 @@
+import { PipeshubCore } from "../core.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { APIError } from "../models/errors/apierror.js";
+import { ConnectionError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, UnexpectedClientError } from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { LookupRecordByIdentifierRequest } from "../models/lookuprecordbyidentifierop.js";
+import { APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+/**
+ * Resolve a URL, issue key or external ID to a Record ID
+ *
+ * @remarks
+ * Turn an external reference into the matching PipesHub record. Accepts a
+ * pasted link, a Jira-style issue key, or a bare external system ID from
+ * any connected source. Repeat `identifiers` to batch-resolve up to ten
+ * in one call.
+ *
+ * The response carries a rendered `text` view — each match's metadata
+ * block followed by a `Next:` line naming a follow-up call. The structured
+ * fields carry the same information for programmatic use.
+ *
+ * **Accepted identifiers**
+ * - Jira issue URL — `https://acme.atlassian.net/browse/PA-1787`
+ * - Jira issue key — `PA-1787`
+ * - Confluence page URL —
+ *   `https://acme.atlassian.net/wiki/spaces/SD/pages/450625553/Agent+Loop`
+ * - Google Drive / Docs URL — `https://docs.google.com/document/d/1AbC.../edit`
+ * - Slack message link — `https://acme.slack.com/archives/C0123/p1720000000000100`
+ * - Bare external system ID — `450625553`
+ *
+ * **When to use this vs. the other record endpoints:**
+ * - **This endpoint** converts an *external* reference into an internal
+ *   Record ID. Reach for it whenever you meet a link or ticket key and
+ *   need the record behind it.
+ * - `GET /connectors/record/{recordId}/content` reads a record you have
+ *   already identified. It needs an internal Record ID, which is exactly
+ *   what this endpoint returns.
+ * - `GET /connectors/navigate` browses the hierarchy when you have a
+ *   position in the tree rather than a specific identifier.
+ *
+ * **Typical flow:** call this with the reference, take a match's `id`
+ * from the response, then call
+ * `GET /connectors/record/{recordId}/content` to read the record.
+ *
+ * **Multiple matches:** one identifier can legitimately match more than
+ * one record — the same external ID may exist in several connected
+ * instances. In that case the response sets `ambiguous: true` and
+ * `matches` holds every candidate. Present the choice rather than taking
+ * the first; `connectorName` narrows a retry.
+ *
+ * **Misses are not errors.**
+ *
+ * Only records the caller can see are returned, and a miss is a `200`
+ * with an empty `matches` array and the input echoed in
+ * `not_found_identifiers` — not a `404`. The identifier resolved to
+ * nothing *or* to something the caller may not access; the two are
+ * deliberately indistinguishable, because an identifier is
+ * caller-supplied and guessable, and confirming existence would leak
+ * records across organizations. `searched_connectors` names what was
+ * covered, so a retry with `connectorName` is often the right next move.
+ *
+ * **Scope:** resolution searches every connector the caller can access,
+ * regardless of any source filter used elsewhere.
+ *
+ * If set, this operation will use either {@link Security.bearerAuth} or {@link Security.oauth2} from the global security.
+ */
+export declare function connectorLookupRecordByIdentifier(client$: PipeshubCore, request: LookupRecordByIdentifierRequest, options?: RequestOptions): APIPromise<Result<Response, APIError | SDKValidationError | UnexpectedClientError | InvalidRequestError | RequestAbortedError | RequestTimeoutError | ConnectionError>>;
+//# sourceMappingURL=connectorLookupRecordByIdentifier.d.ts.map

package/esm/funcs/connectorLookupRecordByIdentifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectorLookupRecordByIdentifier.d.ts","sourceRoot":"","sources":["../../src/funcs/connectorLookupRecordByIdentifier.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EACL,+BAA+B,EAEhC,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAW,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,+BAA+B,EACxC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CACX,MAAM,CACJ,QAAQ,EACN,QAAQ,GACR,kBAAkB,GAClB,qBAAqB,GACrB,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,GACnB,eAAe,CAClB,CACF,CAMA"}