@routerlab/cli 0.0.1

package/dist/commands/frontier.js

@@ -0,0 +1,212 @@
+// commands/frontier.ts — read `eval/results/frontier.json` and pretty-print
+// the Pareto frontier for a given task.
+//
+// The frontier file is the public artifact published by the eval harness
+// (`eval/frontier/runner.ts`, landing in this same wave). Schema:
+//
+//   {
+//     "schema_version": 1,
+//     "generated_at": "<iso8601>",
+//     "frontiers": {
+//       "<taskClass>": [
+//         {
+//           "model": "claude-haiku-4-5",
+//           "provider": "anthropic",
+//           "expectedCost": 0.00042,
+//           "expectedQuality": 0.87,
+//           "qualityLo95"?: 0.82,
+//           "qualityHi95"?: 0.91,
+//           "n"?: 12
+//         },
+//         ...
+//       ]
+//     }
+//   }
+//
+// We accept either the absolute path via `ROUTERLAB_FRONTIER_PATH` env var
+// or the default repo-relative location. Both are validated at read time.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { resolve as resolvePath, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError, EXIT_DOWNSTREAM, EXIT_INVALID_INPUT } from "../errors.js";
+import { writeLine } from "../io.js";
+import { parseFormat, parseTask } from "../parse.js";
+// Resolve repo-relative path from this module's location. File lives at
+// `packages/cli/src/commands/frontier.ts`; frontier.json is at
+// `eval/results/frontier.json` (4 levels up to repo root, then down).
+const DEFAULT_FRONTIER_PATH = resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "eval", "results", "frontier.json");
+const FRONTIER_PATH_ENV_VAR = "ROUTERLAB_FRONTIER_PATH";
+/**
+ * Parse and execute the `frontier` subcommand.
+ */
+export function runFrontier(ctx) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...ctx.argv],
+            options: {
+                task: { type: "string" },
+                format: { type: "string" },
+                path: { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (e) {
+        throw new CliError(EXIT_INVALID_INPUT, `frontier: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const task = parseTask(parsed.values["task"]);
+    const format = parseFormat(parsed.values["format"], "table");
+    const pathOverride = parsed.values["path"];
+    const path = resolveFrontierPath(ctx, typeof pathOverride === "string" ? pathOverride : undefined);
+    const file = loadFrontierFile(path);
+    const rows = file.frontiers[task];
+    if (rows === undefined || rows.length === 0) {
+        throw new CliError(EXIT_DOWNSTREAM, `frontier: no rows for task "${task}" in ${path}`);
+    }
+    if (format === "json") {
+        writeLine(ctx.stdout, JSON.stringify({
+            task,
+            generated_at: file.generated_at,
+            rows,
+        }, null, 2));
+        return 0;
+    }
+    renderTable(task, rows, file, ctx);
+    return 0;
+}
+/**
+ * Resolve which frontier.json path to read. Precedence:
+ *   1. `--path=<p>` flag.
+ *   2. `ROUTERLAB_FRONTIER_PATH` env var.
+ *   3. The repo-default absolute path.
+ */
+function resolveFrontierPath(ctx, pathFlag) {
+    if (pathFlag !== undefined && pathFlag.length > 0) {
+        return resolvePath(ctx.cwd, pathFlag);
+    }
+    const fromEnv = ctx.env[FRONTIER_PATH_ENV_VAR];
+    if (typeof fromEnv === "string" && fromEnv.length > 0) {
+        return fromEnv;
+    }
+    return DEFAULT_FRONTIER_PATH;
+}
+function loadFrontierFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        throw new CliError(EXIT_DOWNSTREAM, `frontier: cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} root is not an object`);
+    }
+    const obj = parsed;
+    const frontiers = obj["frontiers"];
+    if (frontiers === null || typeof frontiers !== "object") {
+        throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} missing required "frontiers" object`);
+    }
+    // Schema validation is intentionally shallow — we just verify the rows
+    // have the fields we render so a malformed row produces a clean message.
+    const normalized = {};
+    for (const [k, v] of Object.entries(frontiers)) {
+        if (!Array.isArray(v)) {
+            throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} key "frontiers.${k}" is not an array`);
+        }
+        normalized[k] = v.map((row, idx) => validateRow(row, k, idx, path));
+    }
+    return {
+        schema_version: typeof obj["schema_version"] === "number" ? obj["schema_version"] : undefined,
+        generated_at: typeof obj["generated_at"] === "string" ? obj["generated_at"] : undefined,
+        frontiers: normalized,
+    };
+}
+function validateRow(row, taskKey, idx, path) {
+    if (row === null || typeof row !== "object") {
+        throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} frontiers.${taskKey}[${idx}] is not an object`);
+    }
+    const r = row;
+    const requireString = (key) => {
+        const v = r[key];
+        if (typeof v !== "string" || v.length === 0) {
+            throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} frontiers.${taskKey}[${idx}].${key} must be a non-empty string`);
+        }
+        return v;
+    };
+    const requireNumber = (key) => {
+        const v = r[key];
+        if (typeof v !== "number" || !Number.isFinite(v)) {
+            throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} frontiers.${taskKey}[${idx}].${key} must be a finite number`);
+        }
+        return v;
+    };
+    const optionalNumber = (key) => {
+        const v = r[key];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== "number" || !Number.isFinite(v)) {
+            throw new CliError(EXIT_DOWNSTREAM, `frontier: ${path} frontiers.${taskKey}[${idx}].${key} must be a finite number`);
+        }
+        return v;
+    };
+    const out = {
+        model: requireString("model"),
+        provider: requireString("provider"),
+        expectedCost: requireNumber("expectedCost"),
+        expectedQuality: requireNumber("expectedQuality"),
+    };
+    const lo = optionalNumber("qualityLo95");
+    if (lo !== undefined)
+        out.qualityLo95 = lo;
+    const hi = optionalNumber("qualityHi95");
+    if (hi !== undefined)
+        out.qualityHi95 = hi;
+    const n = optionalNumber("n");
+    if (n !== undefined)
+        out.n = n;
+    return out;
+}
+function renderTable(task, rows, file, ctx) {
+    const header = `Pareto frontier — task: ${task}`;
+    writeLine(ctx.stdout, header);
+    writeLine(ctx.stdout, "=".repeat(header.length));
+    if (typeof file.generated_at === "string") {
+        writeLine(ctx.stdout, `generated_at: ${file.generated_at}`);
+    }
+    writeLine(ctx.stdout, "");
+    // Sort by cost ascending so the cheapest comes first; this is the natural
+    // reading order for "what should I pick at quality bar X?" workflows.
+    const sorted = [...rows].sort((a, b) => a.expectedCost - b.expectedCost);
+    const headers = ["model", "provider", "cost", "quality", "CI95", "n"];
+    const data = sorted.map((r) => [
+        r.model,
+        r.provider,
+        `$${r.expectedCost.toFixed(6)}`,
+        r.expectedQuality.toFixed(3),
+        r.qualityLo95 !== undefined && r.qualityHi95 !== undefined
+            ? `${r.qualityLo95.toFixed(3)}..${r.qualityHi95.toFixed(3)}`
+            : "—",
+        r.n !== undefined ? String(r.n) : "—",
+    ]);
+    const widths = headers.map((h, col) => {
+        const cells = data.map((row) => row[col] ?? "");
+        return Math.max(h.length, ...cells.map((s) => s.length));
+    });
+    const fmt = (cols) => cols.map((s, i) => s.padEnd(widths[i] ?? s.length)).join("  ");
+    writeLine(ctx.stdout, fmt(headers));
+    writeLine(ctx.stdout, fmt(widths.map((w) => "-".repeat(w))));
+    for (const row of data) {
+        writeLine(ctx.stdout, fmt(row));
+    }
+}
+//# sourceMappingURL=frontier.js.map

package/dist/commands/frontier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier.js","sourceRoot":"","sources":["../../src/commands/frontier.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wCAAwC;AACxC,EAAE;AACF,yEAAyE;AACzE,kEAAkE;AAClE,EAAE;AACF,MAAM;AACN,2BAA2B;AAC3B,mCAAmC;AACnC,qBAAqB;AACrB,yBAAyB;AACzB,YAAY;AACZ,yCAAyC;AACzC,qCAAqC;AACrC,qCAAqC;AACrC,qCAAqC;AACrC,kCAAkC;AAClC,kCAAkC;AAClC,qBAAqB;AACrB,aAAa;AACb,cAAc;AACd,UAAU;AACV,QAAQ;AACR,MAAM;AACN,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAmB,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAErD,wEAAwE;AACxE,+DAA+D;AAC/D,sEAAsE;AACtE,MAAM,qBAAqB,GAAG,WAAW,CACvC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,SAAS,EACT,eAAe,CAChB,CAAC;AAEF,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AA2BxD;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAe;IACzC,IAAI,MAAoC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC;YACjB,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC;YACnB,OAAO,EAAE;gBACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;aACzB;YACD,MAAM,EAAE,IAAI;YACZ,gBAAgB,EAAE,KAAK;SACxB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAChB,kBAAkB,EAClB,aAAa,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAC1D,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;IAE7D,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,EAAE,OAAO,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEnG,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,+BAA+B,IAAI,QAAQ,IAAI,EAAE,CAClD,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,SAAS,CACP,GAAG,CAAC,MAAM,EACV,IAAI,CAAC,SAAS,CACZ;YACE,IAAI;YACJ,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,IAAI;SACL,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,GAAe,EAAE,QAA4B;IACxE,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC/C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,yBAAyB,IAAI,KAC3B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAC3C,EAAE,CACH,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,uBACf,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAC3C,EAAE,CACH,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,wBAAwB,CAC1C,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;IACnC,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,sCAAsC,CACxD,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,UAAU,GAA2C,EAAE,CAAC;IAC9D,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,mBAAmB,CAAC,mBAAmB,CACzD,CAAC;QACJ,CAAC;QACD,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,OAAO;QACL,cAAc,EAAE,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS;QAC7F,YAAY,EAAE,OAAO,GAAG,CAAC,cAAc,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS;QACvF,SAAS,EAAE,UAAU;KACtB,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAY,EAAE,OAAe,EAAE,GAAW,EAAE,IAAY;IAC3E,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,cAAc,OAAO,IAAI,GAAG,oBAAoB,CAClE,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,aAAa,GAAG,CAAC,GAAW,EAAU,EAAE;QAC5C,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,cAAc,OAAO,IAAI,GAAG,KAAK,GAAG,6BAA6B,CACnF,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IACF,MAAM,aAAa,GAAG,CAAC,GAAW,EAAU,EAAE;QAC5C,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,cAAc,OAAO,IAAI,GAAG,KAAK,GAAG,0BAA0B,CAChF,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IACF,MAAM,cAAc,GAAG,CAAC,GAAW,EAAsB,EAAE;QACzD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACtC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,QAAQ,CAChB,eAAe,EACf,aAAa,IAAI,cAAc,OAAO,IAAI,GAAG,KAAK,GAAG,0BAA0B,CAChF,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IAEF,MAAM,GAAG,GAAgB;QACvB,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC;QAC7B,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC;QACnC,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC;QAC3C,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC;KAClD,CAAC;IACF,MAAM,EAAE,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,EAAE,KAAK,SAAS;QAAE,GAAG,CAAC,WAAW,GAAG,EAAE,CAAC;IAC3C,MAAM,EAAE,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,EAAE,KAAK,SAAS;QAAE,GAAG,CAAC,WAAW,GAAG,EAAE,CAAC;IAC3C,MAAM,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,SAAS;QAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,WAAW,CAClB,IAAY,EACZ,IAA4B,EAC5B,IAAkB,EAClB,GAAe;IAEf,MAAM,MAAM,GAAG,2BAA2B,IAAI,EAAE,CAAC;IACjD,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC1C,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE1B,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IAEzE,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC7B,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,QAAQ;QACV,IAAI,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QAC/B,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5B,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS;YACxD,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YAC5D,CAAC,CAAC,GAAG;QACP,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;KACtC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,CAAC,IAAuB,EAAU,EAAE,CAC9C,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjE,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/commands/help.d.ts

@@ -0,0 +1,3 @@
+import { type CliContext } from "../io.ts";
+export declare function runHelp(ctx: CliContext): number;
+//# sourceMappingURL=help.d.ts.map

package/dist/commands/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/commands/help.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,UAAU,EAAa,MAAM,UAAU,CAAC;AA+CtD,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAG/C"}

package/dist/commands/help.js

@@ -0,0 +1,55 @@
+// commands/help.ts — top-level usage banner.
+//
+// Renders the multi-subcommand help text. The text is intentionally
+// long-form rather than a terse listing because the CLI is the user-facing
+// surface for the project and the primary entry point for adoption.
+import { writeLine } from "../io.js";
+const HELP_TEXT = `routerlab CLI — cost-quality routing for LLM APIs.
+
+USAGE
+  route <subcommand> [flags]
+
+SUBCOMMANDS
+  route       Route a single prompt to the cheapest model meeting a quality bar.
+  frontier    Pretty-print the published Pareto frontier for a task.
+  models      List candidate models (optionally filtered by provider).
+  eval        Run eval pipelines. Currently: \`eval frontier --task=<t>\`.
+  version     Print CLI + core versions.
+  help        Show this message.
+
+EXAMPLES
+  # Route a prompt for QA at quality bar 0.85, with a $0.005 budget cap:
+  echo "What's the capital of France?" \\
+    | route route --task=qa --quality-bar=0.85 --max-cost-usd=0.005
+
+  # Same, but raw JSON for piping into jq:
+  route route --task=qa --quality-bar=0.85 --input=prompt.txt --json
+
+  # Look up the frontier for codegen at quality bar 0.85:
+  route frontier --task=codegen
+
+  # List candidate models on Anthropic only:
+  route models --provider=anthropic
+
+  # Print versions:
+  route version
+
+FLAGS (route subcommand)
+  --task=<qa|codegen|summarization|classification|reasoning>  (required)
+  --quality-bar=<float in [0, 1]>                              (required)
+  --input=<path>                                               read prompt from file
+  --max-cost-usd=<number>                                      hard budget cap
+  --max-latency-ms=<number>                                    hard latency cap
+  --json                                                       emit raw RouteDecision JSON
+
+EXIT CODES
+  0   success
+  1   no candidates pass the filters
+  2   invalid input
+  3   downstream error (calibration / runner / missing artifact)
+`;
+export function runHelp(ctx) {
+    writeLine(ctx.stdout, HELP_TEXT.trimEnd());
+    return 0;
+}
+//# sourceMappingURL=help.js.map

package/dist/commands/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/commands/help.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,oEAAoE;AACpE,2EAA2E;AAC3E,oEAAoE;AAEpE,OAAO,EAAmB,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtD,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CjB,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,GAAe;IACrC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/commands/models.d.ts

@@ -0,0 +1,7 @@
+import { type CliContext } from "../io.ts";
+/**
+ * Parse and execute the `models` subcommand. Prints one model per line in
+ * a compact column layout, or JSON when `--json` is set.
+ */
+export declare function runModels(ctx: CliContext): number;
+//# sourceMappingURL=models.d.ts.map

package/dist/commands/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/commands/models.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,UAAU,EAAa,MAAM,UAAU,CAAC;AAGtD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAgCjD"}

package/dist/commands/models.js

@@ -0,0 +1,71 @@
+// commands/models.ts — list candidate models from the engine's pool.
+//
+// Useful for answering "what can routerlab even route to?" without
+// digging into `packages/core/src/candidates.json`. Supports an optional
+// `--provider=<p>` filter for narrowing the listing.
+import { parseArgs } from "node:util";
+import { getDefaultCandidates } from "@routerlab/core";
+import { CliError, EXIT_INVALID_INPUT } from "../errors.js";
+import { writeLine } from "../io.js";
+import { parseProviderOptional } from "../parse.js";
+/**
+ * Parse and execute the `models` subcommand. Prints one model per line in
+ * a compact column layout, or JSON when `--json` is set.
+ */
+export function runModels(ctx) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...ctx.argv],
+            options: {
+                provider: { type: "string" },
+                json: { type: "boolean", default: false },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (e) {
+        throw new CliError(EXIT_INVALID_INPUT, `models: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const provider = parseProviderOptional(parsed.values["provider"]);
+    const json = parsed.values["json"] === true;
+    const all = getDefaultCandidates();
+    const filtered = provider === undefined ? all : all.filter((c) => c.provider === provider);
+    if (json) {
+        writeLine(ctx.stdout, JSON.stringify({ candidates: filtered }, null, 2));
+        return 0;
+    }
+    renderTable(filtered, ctx);
+    return 0;
+}
+/**
+ * Render the candidate list as a fixed-width table on stdout. Columns are
+ * width-padded so values line up; this is a deliberate choice over a CSV /
+ * TSV form because the primary audience is humans reading at a terminal.
+ */
+function renderTable(rows, ctx) {
+    if (rows.length === 0) {
+        writeLine(ctx.stdout, "(no candidates match filter)");
+        return;
+    }
+    const headers = ["provider", "model", "input $/MTok", "output $/MTok", "context"];
+    const data = rows.map((c) => [
+        c.provider,
+        c.model,
+        c.pricing.inputUsdPerMtok.toFixed(2),
+        c.pricing.outputUsdPerMtok.toFixed(2),
+        c.contextWindow.toLocaleString(),
+    ]);
+    const widths = headers.map((h, col) => {
+        const cells = data.map((row) => row[col] ?? "");
+        return Math.max(h.length, ...cells.map((s) => s.length));
+    });
+    const fmt = (cols) => cols.map((s, i) => s.padEnd(widths[i] ?? s.length)).join("  ");
+    writeLine(ctx.stdout, fmt(headers));
+    writeLine(ctx.stdout, fmt(widths.map((w) => "-".repeat(w))));
+    for (const row of data) {
+        writeLine(ctx.stdout, fmt(row));
+    }
+}
+//# sourceMappingURL=models.js.map

package/dist/commands/models.js.map

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

package/dist/commands/route.d.ts

@@ -0,0 +1,7 @@
+import { type CliContext } from "../io.ts";
+/**
+ * Parse and execute the `route` subcommand against the provided context.
+ * Returns the exit code; never throws (all errors are converted).
+ */
+export declare function runRoute(ctx: CliContext): Promise<number>;
+//# sourceMappingURL=route.d.ts.map

package/dist/commands/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/commands/route.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,KAAK,UAAU,EAAgC,MAAM,UAAU,CAAC;AAQzE;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2E/D"}

package/dist/commands/route.js

@@ -0,0 +1,173 @@
+// commands/route.ts — the `route` subcommand.
+//
+// Reads a prompt (from `--input <file>` or stdin), calls the routing engine,
+// and prints either a human-friendly table or raw JSON (`--json`).
+//
+// Exit codes (see ../errors.ts):
+//   0 success, 1 no candidates, 2 invalid input, 3 downstream error.
+//
+// This subcommand is the user-facing surface for routerlab — most users
+// will only ever touch this and `frontier`. Output is engineered to be
+// scannable: chosen pick first, then ordered fallbacks, then a collapsed
+// skipped list with reasons.
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { resolve as resolvePath } from "node:path";
+import { route, } from "@routerlab/core";
+import { CliError, EXIT_INVALID_INPUT, EXIT_NO_CANDIDATES } from "../errors.js";
+import { readStdinToString, writeLine } from "../io.js";
+import { parseNonNegativeFloatOptional, parseQualityBar, parseTask, } from "../parse.js";
+/**
+ * Parse and execute the `route` subcommand against the provided context.
+ * Returns the exit code; never throws (all errors are converted).
+ */
+export async function runRoute(ctx) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...ctx.argv],
+            options: {
+                task: { type: "string" },
+                "quality-bar": { type: "string" },
+                input: { type: "string" },
+                "max-cost-usd": { type: "string" },
+                "max-latency-ms": { type: "string" },
+                json: { type: "boolean", default: false },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (e) {
+        throw new CliError(EXIT_INVALID_INPUT, `route: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const task = parseTask(parsed.values["task"]);
+    const qualityBar = parseQualityBar(parsed.values["quality-bar"]);
+    const maxCostUsd = parseNonNegativeFloatOptional("max-cost-usd", parsed.values["max-cost-usd"]);
+    const maxLatencyMs = parseNonNegativeFloatOptional("max-latency-ms", parsed.values["max-latency-ms"]);
+    const inputPathRaw = parsed.values["input"];
+    const json = parsed.values["json"] === true;
+    const prompt = await readPrompt(ctx, inputPathRaw);
+    if (prompt.trim().length === 0) {
+        throw new CliError(EXIT_INVALID_INPUT, "route: prompt is empty. Pass --input=<file> or pipe text via stdin.");
+    }
+    const request = {
+        task,
+        prompt,
+        qualityBar,
+        ...(maxCostUsd !== undefined ? { maxCostUsd } : {}),
+        ...(maxLatencyMs !== undefined ? { maxLatencyMs } : {}),
+    };
+    let decision;
+    try {
+        decision = route(request);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        // The engine throws a Plain `Error` whose message starts with this
+        // sentinel when no candidates passed filtering. Map that to exit 1.
+        if (msg.includes("no candidates passed filtering")) {
+            throw new CliError(EXIT_NO_CANDIDATES, msg);
+        }
+        // Engine-level validation errors are user input issues.
+        if (msg.startsWith("route(): ")) {
+            throw new CliError(EXIT_INVALID_INPUT, msg);
+        }
+        throw e;
+    }
+    if (json) {
+        writeLine(ctx.stdout, JSON.stringify(decision, null, 2));
+    }
+    else {
+        renderDecision(decision, ctx);
+    }
+    return 0;
+}
+/**
+ * Resolve the prompt source: `--input <file>` wins over stdin.
+ *
+ * - If `--input` is given, the file is read from `ctx.cwd`-relative path.
+ * - Else stdin is drained to a string (unless the caller is on a TTY, in
+ *   which case an empty string is returned and the caller raises a usage
+ *   error — see `runRoute` above).
+ */
+async function readPrompt(ctx, inputPathRaw) {
+    if (typeof inputPathRaw === "string" && inputPathRaw.length > 0) {
+        const absPath = resolvePath(ctx.cwd, inputPathRaw);
+        try {
+            return await readFile(absPath, "utf8");
+        }
+        catch (e) {
+            throw new CliError(EXIT_INVALID_INPUT, `route: cannot read --input "${inputPathRaw}": ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return await readStdinToString(ctx.stdin);
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/**
+ * Render a routing decision as a human-friendly multi-line block to stdout.
+ *
+ * Layout:
+ *
+ *   Decision: <model> (<provider>)
+ *     expected cost:    $0.001234
+ *     expected quality: 0.870
+ *     reasoning:        <engine reasoning>
+ *
+ *   Fallbacks (n):
+ *     1. <model> (<provider>)   $cost   q=quality
+ *
+ *   Skipped (n):
+ *     - <model>: <reason>
+ */
+function renderDecision(decision, ctx) {
+    const out = ctx.stdout;
+    renderChosen(decision.chosen, out);
+    if (decision.fallbacks.length > 0) {
+        writeLine(out, "");
+        writeLine(out, "Fallbacks (ordered by next-cheapest):");
+        decision.fallbacks.forEach((fb, i) => {
+            writeLine(out, formatFallbackLine(fb, i + 1));
+        });
+    }
+    if (decision.skipped.length > 0) {
+        writeLine(out, "");
+        writeLine(out, `Skipped (${decision.skipped.length}):`);
+        for (const s of decision.skipped) {
+            writeLine(out, formatSkippedLine(s));
+        }
+    }
+}
+function renderChosen(chosen, out) {
+    writeLine(out, `Decision: ${chosen.model.model} (${chosen.model.provider})`);
+    writeLine(out, `  expected cost:    ${formatUsd(chosen.expectedCost)}`);
+    writeLine(out, `  expected quality: ${formatQuality(chosen.expectedQuality)}`);
+    writeLine(out, `  reasoning:        ${chosen.reasoning}`);
+}
+function formatFallbackLine(fb, rank) {
+    // The engine encodes cost + quality in the reason string. We display the
+    // canonical model/provider line and append the reason for traceability.
+    const head = `  ${rank}. ${fb.model.model} (${fb.model.provider})`;
+    return `${head}   ${fb.reason}`;
+}
+function formatSkippedLine(s) {
+    return `  - ${s.model.model}: ${s.reason}`;
+}
+/**
+ * Format a USD amount with six fractional digits — that's enough to
+ * distinguish models at the low end of the pricing pool (Groq llama-3.1-8b
+ * at $0.05/MTok input).
+ */
+function formatUsd(usd) {
+    return `$${usd.toFixed(6)}`;
+}
+/**
+ * Format a quality score to 3 decimal places — matches the engine's own
+ * reasoning string format so the two are visually aligned.
+ */
+function formatQuality(q) {
+    return q.toFixed(3);
+}
+//# sourceMappingURL=route.js.map

package/dist/commands/route.js.map

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

package/dist/commands/version.d.ts

@@ -0,0 +1,8 @@
+import { type CliContext } from "../io.ts";
+export declare const CLI_VERSION = "0.0.1";
+/**
+ * `version` subcommand: prints two lines, `@routerlab/cli` first then
+ * `@routerlab/core`. Returns 0 unconditionally.
+ */
+export declare function runVersion(ctx: CliContext): number;
+//# sourceMappingURL=version.d.ts.map

package/dist/commands/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/commands/version.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,UAAU,EAAa,MAAM,UAAU,CAAC;AAItD,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAIlD"}

package/dist/commands/version.js

@@ -0,0 +1,21 @@
+// commands/version.ts — print CLI + core versions.
+//
+// We import the core version from `@routerlab/core` directly so the two
+// numbers can drift independently and the CLI honestly reports both.
+// CLI version is read from its own package.json at build time via the
+// constant below — keep this in lockstep with packages/cli/package.json.
+import { version as coreVersion } from "@routerlab/core";
+import { writeLine } from "../io.js";
+// Pinned to packages/cli/package.json. If you bump `package.json`, bump
+// this too — the repo's CI catches drift between the two via test.
+export const CLI_VERSION = "0.0.1";
+/**
+ * `version` subcommand: prints two lines, `@routerlab/cli` first then
+ * `@routerlab/core`. Returns 0 unconditionally.
+ */
+export function runVersion(ctx) {
+    writeLine(ctx.stdout, `@routerlab/cli ${CLI_VERSION}`);
+    writeLine(ctx.stdout, `@routerlab/core ${coreVersion}`);
+    return 0;
+}
+//# sourceMappingURL=version.js.map

package/dist/commands/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/commands/version.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,wEAAwE;AACxE,qEAAqE;AACrE,sEAAsE;AACtE,yEAAyE;AAEzE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAmB,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtD,wEAAwE;AACxE,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,WAAW,EAAE,CAAC,CAAC;IACvD,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,WAAW,EAAE,CAAC,CAAC;IACxD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_NO_CANDIDATES = 1;
+export declare const EXIT_INVALID_INPUT = 2;
+export declare const EXIT_DOWNSTREAM = 3;
+export type CliExitCode = typeof EXIT_SUCCESS | typeof EXIT_NO_CANDIDATES | typeof EXIT_INVALID_INPUT | typeof EXIT_DOWNSTREAM;
+/**
+ * The one error type the CLI throws for expected, user-facing failures.
+ * Unknown exceptions still bubble up to `main()` and are mapped to
+ * `EXIT_DOWNSTREAM` with the underlying message preserved.
+ */
+export declare class CliError extends Error {
+    readonly code: CliExitCode;
+    constructor(code: CliExitCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,MAAM,MAAM,WAAW,GACnB,OAAO,YAAY,GACnB,OAAO,kBAAkB,GACzB,OAAO,kBAAkB,GACzB,OAAO,eAAe,CAAC;AAE3B;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;gBAEf,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM;CAK/C"}