@spec0/cli 0.1.0

package/dist/lib/ci-detect.js

@@ -0,0 +1,136 @@
+/**
+ * CI environment auto-detection + local git metadata
+ * Priority: CLI flags > PLATFORM_* env vars > .spec0.yaml > CI env > local git
+ */
+import { execSync } from "child_process";
+import { existsSync } from "fs";
+import { resolve, dirname } from "path";
+export function detectCI() {
+    if (process.env.GITHUB_ACTIONS === "true") {
+        const repo = process.env.GITHUB_REPOSITORY ?? "";
+        const owner = process.env.GITHUB_REPOSITORY_OWNER ?? process.env.PLATFORM_OWNER ?? "";
+        const name = repo.split("/").pop() ?? process.env.PLATFORM_NAME ?? "unknown";
+        return {
+            name,
+            namespace: repo || "unknown",
+            owner,
+            gitSha: process.env.GITHUB_SHA ?? "",
+            branch: process.env.GITHUB_REF_NAME ?? "",
+            githubRepo: repo ? `https://github.com/${repo}` : undefined,
+        };
+    }
+    if (process.env.GITLAB_CI === "true") {
+        const path = process.env.CI_PROJECT_PATH ?? "";
+        const ns = process.env.CI_PROJECT_NAMESPACE ?? process.env.PLATFORM_OWNER ?? "";
+        const name = process.env.CI_PROJECT_NAME ?? path.split("/").pop() ?? "unknown";
+        return {
+            name,
+            namespace: path || "unknown",
+            owner: ns,
+            gitSha: process.env.CI_COMMIT_SHA ?? "",
+            branch: process.env.CI_COMMIT_REF_NAME ?? "",
+            githubRepo: process.env.CI_PROJECT_URL,
+        };
+    }
+    if (process.env.BITBUCKET_BUILD_NUMBER) {
+        const workspace = process.env.BITBUCKET_WORKSPACE ?? "";
+        const slug = process.env.BITBUCKET_REPO_SLUG ?? "";
+        const ns = process.env.BITBUCKET_REPO_OWNER ?? process.env.PLATFORM_OWNER ?? "";
+        const name = slug || "unknown";
+        const namespace = workspace && slug ? `${workspace}/${slug}` : "unknown";
+        return {
+            name,
+            namespace,
+            owner: ns,
+            gitSha: process.env.BITBUCKET_COMMIT ?? "",
+            branch: process.env.BITBUCKET_BRANCH ?? "",
+            githubRepo: process.env.BITBUCKET_GIT_HTTP_ORIGIN,
+        };
+    }
+    return null;
+}
+/**
+ * Returns true if the given directory (or any parent) contains a .git directory.
+ */
+function hasGitRepo(startDir) {
+    let dir = resolve(startDir);
+    // Walk up max 10 levels to avoid infinite loop
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(resolve(dir, ".git")))
+            return true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return false;
+}
+/**
+ * Get the git commit SHA of the last commit that touched a specific file.
+ * Uses `git log -1 --format=%H -- <file>` so the SHA reflects when the spec
+ * actually changed, not just the HEAD commit.
+ *
+ * Returns null if not in a git repo or git is not available.
+ */
+export function getGitShaForFile(specFilePath) {
+    const dir = dirname(resolve(specFilePath));
+    if (!hasGitRepo(dir))
+        return null;
+    try {
+        const sha = execSync(`git log -1 --format=%H -- "${specFilePath}"`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 5000,
+        }).trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the current HEAD commit SHA (repo-level, not file-specific).
+ * Falls back to getGitShaForFile when a spec path is available.
+ */
+export function getGitHeadSha() {
+    if (!hasGitRepo(process.cwd()))
+        return null;
+    try {
+        const sha = execSync("git rev-parse HEAD", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 5000,
+        }).trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the current branch name.
+ */
+export function getGitBranch() {
+    if (!hasGitRepo(process.cwd()))
+        return null;
+    try {
+        const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 5000,
+        }).trim();
+        return branch && branch !== "HEAD" ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getGitMetadata() {
+    return {};
+}
+export function hasPlatformEnv() {
+    const token = process.env.SPEC0_TOKEN ?? process.env.PLATFORM_API_TOKEN;
+    const orgId = process.env.SPEC0_ORG_ID ?? process.env.PLATFORM_ORG_ID;
+    return !!(token && orgId);
+}
+//# sourceMappingURL=ci-detect.js.map

package/dist/lib/ci-detect.js.map

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

package/dist/lib/cli-spec-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve OpenAPI spec path from: subcommand --spec-file > global spec0 --spec-file > positional.
+ */
+import type { Command } from "commander";
+export declare function resolveCliSpecPathFromFlags(command: Command, cwd: string, subcommandSpecFile: string | undefined, positional: string | undefined): string | null;
+//# sourceMappingURL=cli-spec-path.d.ts.map

package/dist/lib/cli-spec-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-spec-path.d.ts","sourceRoot":"","sources":["../../src/lib/cli-spec-path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAiCf"}

package/dist/lib/cli-spec-path.js

@@ -0,0 +1,34 @@
+/**
+ * Resolve OpenAPI spec path from: subcommand --spec-file > global spec0 --spec-file > positional.
+ */
+import chalk from "chalk";
+import { resolve } from "path";
+export function resolveCliSpecPathFromFlags(command, cwd, subcommandSpecFile, positional) {
+    const fromSub = subcommandSpecFile?.trim();
+    const root = command.parent?.opts();
+    const fromRoot = root?.specFile?.trim();
+    const fromPos = positional?.trim();
+    const ordered = [];
+    if (fromSub) {
+        ordered.push(fromSub);
+    }
+    if (fromRoot) {
+        ordered.push(fromRoot);
+    }
+    if (fromPos) {
+        ordered.push(fromPos);
+    }
+    if (ordered.length === 0) {
+        return null;
+    }
+    const resolvedAbs = ordered.map((p) => resolve(cwd, p));
+    const firstAbs = resolvedAbs[0];
+    for (let i = 1; i < resolvedAbs.length; i++) {
+        if (resolvedAbs[i] !== firstAbs) {
+            console.error(chalk.red("Conflicting spec paths: use only one of --spec-file, spec0 --spec-file, or the positional [spec-file], and ensure they refer to the same file."));
+            process.exit(1);
+        }
+    }
+    return ordered[0];
+}
+//# sourceMappingURL=cli-spec-path.js.map

package/dist/lib/cli-spec-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-spec-path.js","sourceRoot":"","sources":["../../src/lib/cli-spec-path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAG/B,MAAM,UAAU,2BAA2B,CACzC,OAAgB,EAChB,GAAW,EACX,kBAAsC,EACtC,UAA8B;IAE9B,MAAM,OAAO,GAAG,kBAAkB,EAAE,IAAI,EAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,EAAuC,CAAC;IACzE,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IAEnC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAE,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CACP,gJAAgJ,CACjJ,CACF,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;AACrB,CAAC"}

package/dist/lib/codeowners.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Parse .github/CODEOWNERS for team ownership
+ */
+/**
+ * Extract team from CODEOWNERS line like:
+ * /path/to/spec.yaml @myorg/backend-team
+ * Returns "backend-team" or null
+ */
+export declare function parseCodeownersLine(line: string, specPath: string): string | null;
+export declare function getTeamFromCodeowners(cwd: string, specPath: string): string | null;
+//# sourceMappingURL=codeowners.d.ts.map

package/dist/lib/codeowners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeowners.d.ts","sourceRoot":"","sources":["../../src/lib/codeowners.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcjF;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWlF"}

package/dist/lib/codeowners.js

@@ -0,0 +1,43 @@
+/**
+ * Parse .github/CODEOWNERS for team ownership
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+/**
+ * Extract team from CODEOWNERS line like:
+ * /path/to/spec.yaml @myorg/backend-team
+ * Returns "backend-team" or null
+ */
+export function parseCodeownersLine(line, specPath) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const parts = trimmed.split(/\s+/);
+    if (parts.length < 2)
+        return null;
+    const pattern = parts[0];
+    const owner = parts[1];
+    // Simple match: if pattern matches spec path
+    if (!specPath.includes(pattern.replace(/^\//, "")))
+        return null;
+    // @org/team-name -> team-name
+    if (owner.startsWith("@") && owner.includes("/")) {
+        return owner.split("/").pop() ?? null;
+    }
+    return owner.startsWith("@") ? owner.slice(1) : owner;
+}
+export function getTeamFromCodeowners(cwd, specPath) {
+    const codeownersPath = join(cwd, ".github", "CODEOWNERS");
+    if (!existsSync(codeownersPath))
+        return null;
+    const content = readFileSync(codeownersPath, "utf-8");
+    const lines = content.split("\n");
+    let lastMatch = null;
+    for (const line of lines) {
+        const team = parseCodeownersLine(line, specPath);
+        if (team)
+            lastMatch = team;
+    }
+    return lastMatch;
+}
+//# sourceMappingURL=codeowners.js.map

package/dist/lib/codeowners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeowners.js","sourceRoot":"","sources":["../../src/lib/codeowners.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,QAAgB;IAChE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,6CAA6C;IAC7C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,8BAA8B;IAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,QAAgB;IACjE,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,OAAO,GAAG,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjD,IAAI,IAAI;YAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/lib/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ~/.spec0/config.json management
+ * XDG-compliant config via conf package
+ */
+export interface OrgConfig {
+    apiKey: string;
+    name: string;
+    apiUrl: string;
+    keyName?: string;
+}
+export interface Spec0Config {
+    version: number;
+    defaultOrg?: string;
+    telemetry?: boolean;
+    orgs: Record<string, OrgConfig>;
+}
+export declare function getConfig(): Spec0Config;
+export declare function getDefaultOrgId(): string | null;
+export declare function getOrgConfig(orgId: string): OrgConfig | undefined;
+export declare function setOrgConfig(orgId: string, config: OrgConfig): void;
+export declare function setDefaultOrg(orgId: string): void;
+export declare function clearConfig(): void;
+export declare function getConfigPath(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACjC;AAqBD,wBAAgB,SAAS,IAAI,WAAW,CAOvC;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEjE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAEnE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/lib/config.js

@@ -0,0 +1,49 @@
+/**
+ * ~/.spec0/config.json management
+ * XDG-compliant config via conf package
+ */
+import Conf from "conf";
+// Schema kept for documentation; not currently passed to Conf (defaults below
+// are sufficient). Renamed `_schema` to satisfy lint while retaining intent.
+const _schema = {
+    version: { type: "number", default: 1 },
+    defaultOrg: { type: ["string", "null"], default: null },
+    telemetry: { type: "boolean", default: true },
+    orgs: { type: "object", default: {} },
+};
+const store = new Conf({
+    projectName: "spec0",
+    defaults: {
+        version: 1,
+        defaultOrg: undefined,
+        telemetry: true,
+        orgs: {},
+    },
+});
+export function getConfig() {
+    return {
+        version: store.get("version", 1),
+        defaultOrg: store.get("defaultOrg"),
+        telemetry: store.get("telemetry", true),
+        orgs: store.get("orgs", {}),
+    };
+}
+export function getDefaultOrgId() {
+    return store.get("defaultOrg") ?? null;
+}
+export function getOrgConfig(orgId) {
+    return store.get(`orgs.${orgId}`);
+}
+export function setOrgConfig(orgId, config) {
+    store.set(`orgs.${orgId}`, config);
+}
+export function setDefaultOrg(orgId) {
+    store.set("defaultOrg", orgId);
+}
+export function clearConfig() {
+    store.clear();
+}
+export function getConfigPath() {
+    return store.path;
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAgBxB,8EAA8E;AAC9E,6EAA6E;AAC7E,MAAM,OAAO,GAAG;IACd,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE;IACvC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE;IACvD,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;IAC7C,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE;CAC7B,CAAC;AAEX,MAAM,KAAK,GAAG,IAAI,IAAI,CAAc;IAClC,WAAW,EAAE,OAAO;IACpB,QAAQ,EAAE;QACR,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,SAAS;QACrB,SAAS,EAAE,IAAI;QACf,IAAI,EAAE,EAAE;KACT;CACF,CAAC,CAAC;AAEH,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;QAChC,UAAU,EAAE,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC;QACnC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC;QACvC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAAiB;IAC3D,KAAK,CAAC,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/lib/deprecation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deprecation warnings. Always print to stderr with a clear removal-version
+ * header so users have time to migrate.
+ *
+ * Set SPEC0_SUPPRESS_DEPRECATION=1 to silence in CI logs once the migration
+ * is queued.
+ */
+export interface DeprecationNotice {
+    /** What the user did, e.g. "the --json flag" or "the SPEC0_LEGACY env var". */
+    what: string;
+    /** Version when this stops working. e.g. "v1.0.0". */
+    removeIn: string;
+    /** What the user should do instead. e.g. "use --output=json". */
+    alternative: string;
+}
+export declare function warnDeprecated(notice: DeprecationNotice): void;
+//# sourceMappingURL=deprecation.d.ts.map

package/dist/lib/deprecation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.d.ts","sourceRoot":"","sources":["../../src/lib/deprecation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAW9D"}

package/dist/lib/deprecation.js

@@ -0,0 +1,22 @@
+/**
+ * Deprecation warnings. Always print to stderr with a clear removal-version
+ * header so users have time to migrate.
+ *
+ * Set SPEC0_SUPPRESS_DEPRECATION=1 to silence in CI logs once the migration
+ * is queued.
+ */
+import chalk from "chalk";
+const seen = new Set();
+export function warnDeprecated(notice) {
+    if (process.env.SPEC0_SUPPRESS_DEPRECATION)
+        return;
+    const key = `${notice.what}|${notice.removeIn}`;
+    if (seen.has(key))
+        return; // print once per process
+    seen.add(key);
+    const useColour = Boolean(process.stderr.isTTY);
+    const tag = useColour ? chalk.yellow("⚠ deprecated:") : "DEPRECATED:";
+    const msg = `${tag} ${notice.what} will be removed in ${notice.removeIn}. Use ${notice.alternative}.`;
+    process.stderr.write(msg + "\n");
+}
+//# sourceMappingURL=deprecation.js.map

package/dist/lib/deprecation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.js","sourceRoot":"","sources":["../../src/lib/deprecation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAW1B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;AAE/B,MAAM,UAAU,cAAc,CAAC,MAAyB;IACtD,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B;QAAE,OAAO;IAEnD,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;IAChD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,yBAAyB;IACpD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEd,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IACtE,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,uBAAuB,MAAM,CAAC,QAAQ,SAAS,MAAM,CAAC,WAAW,GAAG,CAAC;IACtG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/lib/doctor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Diagnostic helpers — used by `spec0 doctor` and (one day) by error
+ * messages that want to attach a "here's what's set right now" pointer.
+ *
+ * The goal: make every "auth missing" or "wrong URL" failure into something
+ * the user can act on in 30 seconds, by surfacing where each setting came
+ * from (env var name, config file path, or default).
+ */
+export type SettingSource = {
+    kind: "env";
+    var: string;
+} | {
+    kind: "config";
+    path: string;
+} | {
+    kind: "default";
+} | {
+    kind: "missing";
+};
+export interface SettingReport {
+    name: string;
+    /** Display value; secrets are redacted. */
+    value: string;
+    source: SettingSource;
+}
+export interface DoctorReport {
+    settings: SettingReport[];
+    /** Aggregate status — "ok" only when every required setting is non-missing. */
+    ok: boolean;
+    /** Path to the local config file (whether or not it exists). */
+    configPath: string;
+}
+/**
+ * Build a structured diagnostic of the runtime config the CLI sees right now.
+ * Pure — no network calls. Good for inclusion in `--verbose` output too.
+ */
+export declare function buildDoctorReport(): DoctorReport;
+/** Stringify a setting source for human display. */
+export declare function describeSource(source: SettingSource): string;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/lib/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/lib/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,+EAA+E;IAC/E,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CA8EhD;AAQD,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAW5D"}

package/dist/lib/doctor.js

@@ -0,0 +1,107 @@
+/**
+ * Diagnostic helpers — used by `spec0 doctor` and (one day) by error
+ * messages that want to attach a "here's what's set right now" pointer.
+ *
+ * The goal: make every "auth missing" or "wrong URL" failure into something
+ * the user can act on in 30 seconds, by surfacing where each setting came
+ * from (env var name, config file path, or default).
+ */
+import { getConfigPath, getDefaultOrgId, getOrgConfig } from "./config.js";
+import { DEFAULT_PLATFORM_API_URL, DEFAULT_PLATFORM_APP_URL, resolvedPlatformApiUrl, resolvedPlatformAppUrl, } from "./platform-defaults.js";
+/**
+ * Build a structured diagnostic of the runtime config the CLI sees right now.
+ * Pure — no network calls. Good for inclusion in `--verbose` output too.
+ */
+export function buildDoctorReport() {
+    const settings = [];
+    // Token: env wins; otherwise from default org's config; otherwise missing.
+    const envToken = process.env.SPEC0_TOKEN ?? process.env.PLATFORM_API_TOKEN;
+    const defaultOrgId = process.env.SPEC0_ORG_ID ?? process.env.PLATFORM_ORG_ID ?? getDefaultOrgId();
+    const cfg = defaultOrgId ? getOrgConfig(defaultOrgId) : undefined;
+    settings.push({
+        name: "token",
+        value: redactToken(envToken ?? cfg?.apiKey),
+        source: envToken
+            ? { kind: "env", var: process.env.SPEC0_TOKEN ? "SPEC0_TOKEN" : "PLATFORM_API_TOKEN" }
+            : cfg?.apiKey
+                ? { kind: "config", path: getConfigPath() }
+                : { kind: "missing" },
+    });
+    settings.push({
+        name: "orgId",
+        value: defaultOrgId ?? "(missing)",
+        source: process.env.SPEC0_ORG_ID
+            ? { kind: "env", var: "SPEC0_ORG_ID" }
+            : process.env.PLATFORM_ORG_ID
+                ? { kind: "env", var: "PLATFORM_ORG_ID" }
+                : defaultOrgId
+                    ? { kind: "config", path: getConfigPath() }
+                    : { kind: "missing" },
+    });
+    // API URL: env override wins; otherwise config; otherwise default.
+    const envApiUrl = process.env.SPEC0_API_URL ?? process.env.PLATFORM_API_URL;
+    const apiUrl = resolvedPlatformApiUrl();
+    settings.push({
+        name: "apiUrl",
+        value: apiUrl,
+        source: envApiUrl
+            ? { kind: "env", var: process.env.SPEC0_API_URL ? "SPEC0_API_URL" : "PLATFORM_API_URL" }
+            : cfg?.apiUrl
+                ? { kind: "config", path: getConfigPath() }
+                : apiUrl === DEFAULT_PLATFORM_API_URL
+                    ? { kind: "default" }
+                    : { kind: "config", path: getConfigPath() },
+    });
+    // App URL — used for browser auth + dashboard links only.
+    const envAppUrl = process.env.SPEC0_APP_URL ?? process.env.PLATFORM_APP_URL;
+    const appUrl = resolvedPlatformAppUrl();
+    settings.push({
+        name: "appUrl",
+        value: appUrl,
+        source: envAppUrl
+            ? { kind: "env", var: process.env.SPEC0_APP_URL ? "SPEC0_APP_URL" : "PLATFORM_APP_URL" }
+            : appUrl === DEFAULT_PLATFORM_APP_URL
+                ? { kind: "default" }
+                : { kind: "config", path: getConfigPath() },
+    });
+    // Mode: "agent" when SPEC0_MODE=agent, "human" otherwise. Surfaced so agents
+    // can confirm the mode they think they're in is actually active.
+    const mode = (process.env.SPEC0_MODE ?? "").toLowerCase() === "agent" ? "agent" : "human";
+    settings.push({
+        name: "mode",
+        value: mode,
+        source: process.env.SPEC0_MODE ? { kind: "env", var: "SPEC0_MODE" } : { kind: "default" },
+    });
+    // OK when token + orgId are present — those are the only two strictly required.
+    const ok = settings.every((s) => {
+        if (s.name === "token" || s.name === "orgId")
+            return s.source.kind !== "missing";
+        return true;
+    });
+    return {
+        settings,
+        ok,
+        configPath: getConfigPath(),
+    };
+}
+function redactToken(value) {
+    if (!value)
+        return "(missing)";
+    if (value.length <= 8)
+        return "***";
+    return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+/** Stringify a setting source for human display. */
+export function describeSource(source) {
+    switch (source.kind) {
+        case "env":
+            return `env: ${source.var}`;
+        case "config":
+            return `config: ${source.path}`;
+        case "default":
+            return "default";
+        case "missing":
+            return "(not set)";
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/lib/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/lib/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAuBhC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,QAAQ,GAAoB,EAAE,CAAC;IAErC,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC3E,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,eAAe,EAAE,CAAC;IAClG,MAAM,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAElE,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,WAAW,CAAC,QAAQ,IAAI,GAAG,EAAE,MAAM,CAAC;QAC3C,MAAM,EAAE,QAAQ;YACd,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,oBAAoB,EAAE;YACtF,CAAC,CAAC,GAAG,EAAE,MAAM;gBACX,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE;gBAC3C,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;KAC1B,CAAC,CAAC;IAEH,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,YAAY,IAAI,WAAW;QAClC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY;YAC9B,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,cAAc,EAAE;YACtC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe;gBAC3B,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,iBAAiB,EAAE;gBACzC,CAAC,CAAC,YAAY;oBACZ,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE;oBAC3C,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;KAC5B,CAAC,CAAC;IAEH,mEAAmE;IACnE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC5E,MAAM,MAAM,GAAG,sBAAsB,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,SAAS;YACf,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,kBAAkB,EAAE;YACxF,CAAC,CAAC,GAAG,EAAE,MAAM;gBACX,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE;gBAC3C,CAAC,CAAC,MAAM,KAAK,wBAAwB;oBACnC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;oBACrB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE;KAClD,CAAC,CAAC;IAEH,0DAA0D;IAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC5E,MAAM,MAAM,GAAG,sBAAsB,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,SAAS;YACf,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,kBAAkB,EAAE;YACxF,CAAC,CAAC,MAAM,KAAK,wBAAwB;gBACnC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;gBACrB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE;KAChD,CAAC,CAAC;IAEH,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1F,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;KAC1F,CAAC,CAAC;IAEH,gFAAgF;IAChF,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;QAC9B,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,QAAQ;QACR,EAAE;QACF,UAAU,EAAE,aAAa,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,KAAyB;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,WAAW,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,OAAO,QAAQ,MAAM,CAAC,GAAG,EAAE,CAAC;QAC9B,KAAK,QAAQ;YACX,OAAO,WAAW,MAAM,CAAC,IAAI,EAAE,CAAC;QAClC,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/lib/exit-codes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Stable exit-code contract. These values are part of the CLI's public API —
+ * once shipped, they MUST NOT be reused or repurposed. CI pipelines depend on
+ * them.
+ *
+ * See README "Exit codes" section for the user-facing reference.
+ */
+export declare const ExitCode: {
+    /** Operation succeeded. */
+    readonly SUCCESS: 0;
+    /** Generic / unclassified failure. Avoid; pick a specific code instead. */
+    readonly GENERIC: 1;
+    /** Bad invocation: missing required arg, conflicting flags, etc. */
+    readonly USAGE: 2;
+    /** No credentials available, or token expired. Hint at SPEC0_TOKEN. */
+    readonly AUTH_MISSING: 3;
+    /** Authenticated but lacking required permission (HTTP 403). */
+    readonly PERMISSION_DENIED: 4;
+    /** Resource (API, mock, environment, …) does not exist (HTTP 404). */
+    readonly NOT_FOUND: 5;
+    /** Conflict on create/update — e.g. name already taken (HTTP 409). */
+    readonly CONFLICT: 6;
+    /** Validation failure — e.g. spec lint score below threshold (HTTP 422 or local). */
+    readonly VALIDATION: 7;
+    /** Rate limit hit (HTTP 429). */
+    readonly RATE_LIMITED: 8;
+    /** Server-side failure the user can't act on directly (HTTP 5xx). */
+    readonly SERVER_ERROR: 9;
+    /** Network unreachable, timeout, DNS failure. */
+    readonly NETWORK_ERROR: 10;
+};
+export type ExitCodeName = keyof typeof ExitCode;
+export type ExitCodeValue = (typeof ExitCode)[ExitCodeName];
+/**
+ * Classifies an HTTP-style error into the corresponding exit code. Anything
+ * unrecognised falls back to `GENERIC` so callers can chain this safely.
+ */
+export declare function exitCodeForHttpStatus(status: number | undefined): ExitCodeValue;
+/**
+ * Single exit point. Logs `message` to stderr (if provided) before exiting.
+ * Commands MUST go through this rather than calling `process.exit` directly so
+ * that future logging / telemetry can hook one place.
+ */
+export declare function exit(code: ExitCodeValue, message?: string): never;
+/**
+ * Reverse-lookup: turn a numeric exit code into its stable string name
+ * ("AUTH_MISSING", "NOT_FOUND", …). Used when emitting structured errors
+ * so agents can branch on the symbolic code rather than the number.
+ */
+export declare function exitCodeName(code: ExitCodeValue): ExitCodeName;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/lib/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../../src/lib/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,QAAQ;IACnB,2BAA2B;;IAE3B,2EAA2E;;IAE3E,oEAAoE;;IAEpE,uEAAuE;;IAEvE,gEAAgE;;IAEhE,sEAAsE;;IAEtE,sEAAsE;;IAEtE,qFAAqF;;IAErF,iCAAiC;;IAEjC,qEAAqE;;IAErE,iDAAiD;;CAEzC,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,QAAQ,CAAC;AACjD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAKjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAK9D"}