@formigio/fazemos-cli 0.6.1 → 0.7.0

package/dist/api.d.ts

@@ -1,7 +1,9 @@
+import { type AuthMeResponse } from './config.js';
 /**
  * Error thrown when an API request returns a non-2xx response. Carries the
  * `code` field from the API's error envelope (when present) so command
- * handlers can branch on specific failure modes (e.g., EMAIL_SEND_FAILED).
+ * handlers can branch on specific failure modes (e.g., EMAIL_SEND_FAILED,
+ * F15's MISSING_PROJECT_CONTEXT / PROJECT_NOT_FOUND / PROJECT_MISMATCH).
  * Also exposes the parsed body so callers can read extra fields like
  * `inviteEmail`/`sessionEmail` on INVITE_EMAIL_MISMATCH.
  */
@@ -11,4 +13,63 @@ export declare class ApiError extends Error {
     body?: unknown;
     constructor(message: string, status: number, code?: string, body?: unknown);
 }
-export declare function api(method: string, path: string, body?: unknown): Promise<unknown>;
+/**
+ * F15 — options for `api()` that controls project context threading.
+ *
+ * - `projectSlug` — override active project for this call. The CLI resolves
+ *   slug → id from the cached /auth/me response, falling back to a single
+ *   refresh + retry on miss (per §8.3 slug-miss cache refresh behavior).
+ * - `allProjects` — send `?view=all` query param on GET list endpoints. Set
+ *   by `--all-projects` on any scoped list command (§8.2 of the tech spec).
+ * - `noProjectHeader` — for endpoints that are not project-scoped (e.g.,
+ *   /auth/me itself, /api/organizations/mine). Skip header emission so the
+ *   API doesn't misinterpret a stale projectId.
+ */
+export interface ApiOptions {
+    projectSlug?: string;
+    allProjects?: boolean;
+    noProjectHeader?: boolean;
+}
+/**
+ * Resolve the project id to send as X-Fazemos-Project-Id on a scoped call.
+ *
+ * Resolution order:
+ *   1. If a slug override is provided (--project <slug>), look it up in the
+ *      cached /auth/me response. On a cache miss, refresh once (covers the
+ *      "just created on another host" case) and retry.
+ *   2. Otherwise, return the active project id from config.
+ *
+ * On a slug that refuses to resolve after refresh → throws ApiError with
+ * code UNKNOWN_PROJECT. The outer command handler prints the standard
+ * "unknown project: <slug>" and exits 1.
+ */
+export declare function resolveProjectIdBySlug(slugOverride?: string): Promise<string | null>;
+/**
+ * Fetch /auth/me fresh from the API and cache the response. Used on slug
+ * miss and by any command that has just mutated orgs/projects (create,
+ * archive) and needs subsequent lookups to see the new data.
+ */
+export declare function refreshAuthMeCache(): Promise<AuthMeResponse | null>;
+/**
+ * Core API helper. Always authenticates, always sends X-Org-Id when one is
+ * active, and sends X-Fazemos-Project-Id when a project is active (or one
+ * has been resolved via `projectSlug` override).
+ *
+ * Error handling (F15): if the API returns `code: 'MISSING_PROJECT_CONTEXT'`
+ * we re-shape the thrown ApiError to the uniform KD9 shape — `message` is
+ * the literal string `requirement missing: project`, `code` is preserved.
+ * This keeps the CLI's "missing required input" surface uniform and lets
+ * outer handlers print the standard hint block without substring-matching
+ * API message text.
+ *
+ * Other codes (PROJECT_NOT_FOUND, PROJECT_MISMATCH, VALIDATION_ERROR) pass
+ * through verbatim so the caller sees the API's precise message. This is
+ * the "thin validator" of KD9: translate one specific code, pass the rest.
+ */
+export declare function api(method: string, path: string, body?: unknown, opts?: ApiOptions): Promise<unknown>;
+/**
+ * Invalidate the /auth/me cache after any mutation that changes the set of
+ * projects (create/archive/unarchive) or orgs. Called from command
+ * handlers to keep the next slug-resolution honest.
+ */
+export declare function invalidateAuthMeCache(): void;

package/dist/api.js

@@ -1,9 +1,10 @@
-import { getEnv, getToken, getActiveOrgId } from './config.js';
+import { getEnv, getToken, getActiveOrgId, getActiveProjectId, findProjectBySlug, setAuthMeCache, clearAuthMeCache, } from './config.js';
 import { refreshSession } from './auth.js';
 /**
  * Error thrown when an API request returns a non-2xx response. Carries the
  * `code` field from the API's error envelope (when present) so command
- * handlers can branch on specific failure modes (e.g., EMAIL_SEND_FAILED).
+ * handlers can branch on specific failure modes (e.g., EMAIL_SEND_FAILED,
+ * F15's MISSING_PROJECT_CONTEXT / PROJECT_NOT_FOUND / PROJECT_MISMATCH).
  * Also exposes the parsed body so callers can read extra fields like
  * `inviteEmail`/`sessionEmail` on INVITE_EMAIL_MISMATCH.
  */
@@ -19,7 +20,76 @@ export class ApiError extends Error {
         this.body = body;
     }
 }
-export async function api(method, path, body) {
+/**
+ * Resolve the project id to send as X-Fazemos-Project-Id on a scoped call.
+ *
+ * Resolution order:
+ *   1. If a slug override is provided (--project <slug>), look it up in the
+ *      cached /auth/me response. On a cache miss, refresh once (covers the
+ *      "just created on another host" case) and retry.
+ *   2. Otherwise, return the active project id from config.
+ *
+ * On a slug that refuses to resolve after refresh → throws ApiError with
+ * code UNKNOWN_PROJECT. The outer command handler prints the standard
+ * "unknown project: <slug>" and exits 1.
+ */
+export async function resolveProjectIdBySlug(slugOverride) {
+    const orgId = getActiveOrgId();
+    if (!orgId)
+        return null;
+    if (slugOverride) {
+        let project = findProjectBySlug(orgId, slugOverride);
+        if (!project) {
+            // Force-refresh the /auth/me cache. A slug miss is cheap to verify
+            // and catches the common "created via another host or via the web
+            // UI and not yet cached here" path.
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slugOverride);
+        }
+        if (!project) {
+            throw new ApiError(`unknown project: ${slugOverride}`, 400, 'UNKNOWN_PROJECT');
+        }
+        return project.id;
+    }
+    return getActiveProjectId();
+}
+/**
+ * Fetch /auth/me fresh from the API and cache the response. Used on slug
+ * miss and by any command that has just mutated orgs/projects (create,
+ * archive) and needs subsequent lookups to see the new data.
+ */
+export async function refreshAuthMeCache() {
+    try {
+        const me = (await api('GET', '/auth/me', undefined, { noProjectHeader: true }));
+        if (me && typeof me === 'object' && 'orgs' in me) {
+            setAuthMeCache(me);
+            return me;
+        }
+    }
+    catch {
+        // Swallow — caller will surface any follow-up error naturally. We
+        // don't want a /auth/me refresh failure to mask the user's real
+        // command error.
+    }
+    return null;
+}
+/**
+ * Core API helper. Always authenticates, always sends X-Org-Id when one is
+ * active, and sends X-Fazemos-Project-Id when a project is active (or one
+ * has been resolved via `projectSlug` override).
+ *
+ * Error handling (F15): if the API returns `code: 'MISSING_PROJECT_CONTEXT'`
+ * we re-shape the thrown ApiError to the uniform KD9 shape — `message` is
+ * the literal string `requirement missing: project`, `code` is preserved.
+ * This keeps the CLI's "missing required input" surface uniform and lets
+ * outer handlers print the standard hint block without substring-matching
+ * API message text.
+ *
+ * Other codes (PROJECT_NOT_FOUND, PROJECT_MISMATCH, VALIDATION_ERROR) pass
+ * through verbatim so the caller sees the API's precise message. This is
+ * the "thin validator" of KD9: translate one specific code, pass the rest.
+ */
+export async function api(method, path, body, opts = {}) {
     const env = getEnv();
     let token = getToken();
     const orgId = getActiveOrgId();
@@ -39,7 +109,25 @@ export async function api(method, path, body) {
     if (orgId) {
         headers['X-Org-Id'] = orgId;
     }
-    const url = `${env.apiUrl}${path}`;
+    // F15 — project context header. Skipped for non-project-scoped endpoints
+    // (auth/me, /api/organizations/mine, org CRUD). The API ignores the header
+    // on endpoints that don't require it, but omitting it keeps intent clear
+    // in request logs.
+    if (!opts.noProjectHeader) {
+        const projectId = await resolveProjectIdBySlug(opts.projectSlug);
+        if (projectId) {
+            headers['X-Fazemos-Project-Id'] = projectId;
+        }
+    }
+    // Build URL with optional ?view=all append. We don't try to be clever
+    // about merging with existing query strings here — callers that use
+    // --all-projects know they're on GET list endpoints with no other query.
+    // If a future endpoint wants both --all-projects and a manual query,
+    // extend this helper rather than working around it.
+    let url = `${env.apiUrl}${path}`;
+    if (opts.allProjects) {
+        url += (url.includes('?') ? '&' : '?') + 'view=all';
+    }
     const options = {
         method,
         headers,
@@ -60,9 +148,23 @@ export async function api(method, path, body) {
         const obj = typeof data === 'object' && data !== null
             ? data
             : null;
+        const code = obj?.code;
         const msg = obj?.error ?? `HTTP ${response.status}`;
-        throw new ApiError(msg, response.status, obj?.code, data);
+        // KD9 — translate MISSING_PROJECT_CONTEXT into the uniform CLI
+        // missing-input shape. Other F15 codes pass through verbatim.
+        if (code === 'MISSING_PROJECT_CONTEXT') {
+            throw new ApiError('requirement missing: project', response.status, code, data);
+        }
+        throw new ApiError(msg, response.status, code, data);
     }
     return data;
 }
+/**
+ * Invalidate the /auth/me cache after any mutation that changes the set of
+ * projects (create/archive/unarchive) or orgs. Called from command
+ * handlers to keep the next slug-resolution honest.
+ */
+export function invalidateAuthMeCache() {
+    clearAuthMeCache();
+}
 //# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,MAAM,CAAS;IACf,IAAI,CAAU;IACd,IAAI,CAAW;IACf,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa,EAAE,IAAc;QACxE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,MAAc,EAAE,IAAY,EAAE,IAAc;IACpE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAE/B,mCAAmC;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,kBAAkB;KACnC,CAAC;IACF,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,KAAK,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;IACnC,MAAM,OAAO,GAAgB;QAC3B,MAAM;QACN,OAAO;KACR,CAAC;IAEF,IAAI,IAAI,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEnC,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,GAAG,GACP,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YACvC,CAAC,CAAE,IAA0C;YAC7C,CAAC,CAAC,IAAI,CAAC;QACX,MAAM,GAAG,GAAG,GAAG,EAAE,KAAK,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpD,MAAM,IAAI,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -1,4 +1,47 @@
 import Conf from 'conf';
+/**
+ * Shape of a project as cached in /auth/me response.
+ */
+export interface CachedProject {
+    id: string;
+    slug: string;
+    name: string;
+    colorIndex: number;
+    status: 'active' | 'archived';
+}
+/**
+ * Shape of an org membership as cached in /auth/me response.
+ */
+export interface CachedOrg {
+    id: string;
+    slug: string;
+    name: string;
+    role: 'owner' | 'admin' | 'member';
+    memberId: string;
+    projects: CachedProject[];
+}
+/**
+ * Cached /auth/me response. Used to resolve project slug → id without a
+ * network round-trip on every scoped command (§8.4 of the F15 tech spec).
+ */
+export interface AuthMeResponse {
+    user: {
+        id: string;
+        email: string;
+    };
+    member: {
+        id: string;
+        orgId: string;
+        displayName: string;
+        email: string | null;
+        role: string;
+        memberType: string;
+        status: string;
+    };
+    orgs: CachedOrg[];
+    activeOrgId: string;
+    activeProjectId: string | null;
+}
 interface FazemosConfig {
     environments: Record<string, {
         apiUrl: string;
@@ -8,13 +51,31 @@ interface FazemosConfig {
     }>;
     activeEnv: string;
     activeOrgId: string;
+    /**
+     * F15 — Active project per org. When the user switches orgs, their last
+     * active project for the destination org is restored from this map (per
+     * UX §1.8). Keyed by orgId so a single machine can track multiple orgs'
+     * project selections independently.
+     */
+    activeProjectByOrg: Record<string, string>;
     auth: Record<string, {
         email: string;
         idToken: string;
         refreshToken: string;
         expiresAt: number;
     }>;
+    /**
+     * F15 — Cached /auth/me response. 5-minute TTL. Invalidated explicitly
+     * on any mutating projects/orgs command (create, archive) and refreshed
+     * lazily on first use by resolveProjectId() when a slug miss happens.
+     */
+    authMeCache?: {
+        activeEnv: string;
+        fetchedAt: number;
+        data: AuthMeResponse;
+    };
 }
+export declare const AUTH_ME_CACHE_TTL_MS: number;
 export declare const config: Conf<FazemosConfig>;
 export declare function addEnvironment(name: string, env: {
     apiUrl: string;
@@ -34,4 +95,33 @@ export declare function getToken(): string | null;
 export declare function getActiveOrgId(): string | null;
 export declare function setActiveOrgId(orgId: string): void;
 export declare function setAuth(env: string, email: string, idToken: string, refreshToken: string, expiresInSeconds: number): void;
+/**
+ * Returns the active project id for the currently-active org, or null if
+ * none is set. Follows KD9 — no auto-pick, no interactive prompt. The
+ * scoped-command handlers translate a null return into the uniform
+ * "requirement missing: project" error when the API says so.
+ */
+export declare function getActiveProjectId(): string | null;
+/**
+ * Sets the active project for the given org. Stored as a per-org map so
+ * switching orgs restores the last project you used in each.
+ */
+export declare function setActiveProjectId(orgId: string, projectId: string): void;
+/**
+ * Clears the active project for the given org (e.g., when the project
+ * is archived and was the active one).
+ */
+export declare function clearActiveProjectId(orgId: string): void;
+export declare function getAuthMeCache(): AuthMeResponse | null;
+export declare function setAuthMeCache(data: AuthMeResponse): void;
+export declare function clearAuthMeCache(): void;
+/**
+ * Look up a project by slug in the currently cached /auth/me response.
+ * Returns null if the cache is empty, stale, or the slug is not present.
+ * Callers should refresh the cache once and retry on miss — see
+ * resolveProjectIdBySlug in api.ts.
+ */
+export declare function findProjectBySlug(orgId: string, slug: string): CachedProject | null;
+export declare function findProjectById(orgId: string, projectId: string): CachedProject | null;
+export declare function findOrgById(orgId: string): CachedOrg | null;
 export {};

package/dist/config.js

@@ -1,10 +1,12 @@
 import Conf from 'conf';
+export const AUTH_ME_CACHE_TTL_MS = 5 * 60 * 1000;
 export const config = new Conf({
     projectName: 'fazemos-cli',
     defaults: {
         environments: {},
         activeEnv: '',
         activeOrgId: '',
+        activeProjectByOrg: {},
         auth: {},
     },
 });
@@ -53,4 +55,92 @@ export function setAuth(env, email, idToken, refreshToken, expiresInSeconds) {
     };
     config.set('auth', auth);
 }
+// ── F15 — Project context helpers ───────────────────────────
+/**
+ * Returns the active project id for the currently-active org, or null if
+ * none is set. Follows KD9 — no auto-pick, no interactive prompt. The
+ * scoped-command handlers translate a null return into the uniform
+ * "requirement missing: project" error when the API says so.
+ */
+export function getActiveProjectId() {
+    const orgId = getActiveOrgId();
+    if (!orgId)
+        return null;
+    const map = config.get('activeProjectByOrg') ?? {};
+    return map[orgId] ?? null;
+}
+/**
+ * Sets the active project for the given org. Stored as a per-org map so
+ * switching orgs restores the last project you used in each.
+ */
+export function setActiveProjectId(orgId, projectId) {
+    const map = config.get('activeProjectByOrg') ?? {};
+    map[orgId] = projectId;
+    config.set('activeProjectByOrg', map);
+}
+/**
+ * Clears the active project for the given org (e.g., when the project
+ * is archived and was the active one).
+ */
+export function clearActiveProjectId(orgId) {
+    const map = config.get('activeProjectByOrg') ?? {};
+    delete map[orgId];
+    config.set('activeProjectByOrg', map);
+}
+// ── F15 — /auth/me cache helpers ────────────────────────────
+export function getAuthMeCache() {
+    const cache = config.get('authMeCache');
+    if (!cache)
+        return null;
+    const activeEnv = config.get('activeEnv');
+    if (cache.activeEnv !== activeEnv)
+        return null;
+    if (Date.now() - cache.fetchedAt > AUTH_ME_CACHE_TTL_MS)
+        return null;
+    return cache.data;
+}
+export function setAuthMeCache(data) {
+    const activeEnv = config.get('activeEnv');
+    config.set('authMeCache', {
+        activeEnv,
+        fetchedAt: Date.now(),
+        data,
+    });
+}
+export function clearAuthMeCache() {
+    // conf's .delete strips the key entirely; using set(undefined) keeps the
+    // field present but null which confuses narrowing callers. Delete is the
+    // cleaner surface here.
+    config.delete('authMeCache');
+}
+/**
+ * Look up a project by slug in the currently cached /auth/me response.
+ * Returns null if the cache is empty, stale, or the slug is not present.
+ * Callers should refresh the cache once and retry on miss — see
+ * resolveProjectIdBySlug in api.ts.
+ */
+export function findProjectBySlug(orgId, slug) {
+    const me = getAuthMeCache();
+    if (!me)
+        return null;
+    const org = me.orgs.find(o => o.id === orgId);
+    if (!org)
+        return null;
+    return org.projects.find(p => p.slug === slug) ?? null;
+}
+export function findProjectById(orgId, projectId) {
+    const me = getAuthMeCache();
+    if (!me)
+        return null;
+    const org = me.orgs.find(o => o.id === orgId);
+    if (!org)
+        return null;
+    return org.projects.find(p => p.id === projectId) ?? null;
+}
+export function findOrgById(orgId) {
+    const me = getAuthMeCache();
+    if (!me)
+        return null;
+    return me.orgs.find(o => o.id === orgId) ?? null;
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAmBxB,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,IAAI,CAAgB;IAC5C,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE;QACR,YAAY,EAAE,EAAE;QAChB,SAAS,EAAE,EAAE;QACb,WAAW,EAAE,EAAE;QACf,IAAI,EAAE,EAAE;KACT;CACF,CAAC,CAAC;AAEH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAA8F;IACzI,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;IACjB,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACjC,iCAAiC;IACjC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,MAAM;IACpB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,kBAAkB,CAAC,CAAC;IAClE,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,IAAI,CAAC,OAAO,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACxC,OAAO,KAAK,IAAI,IAAI,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,KAAa,EAAE,OAAe,EAAE,YAAoB,EAAE,gBAAwB;IACjH,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,CAAC,GAAG;QACV,KAAK;QACL,OAAO;QACP,YAAY;QACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,gBAAgB,GAAG,IAAI;KAChD,CAAC;IACF,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}