@productbrain/cli 0.1.0-beta.15 → 0.1.0-beta.1502

package/dist/lib/collectionRegistry.js

@@ -0,0 +1,112 @@
+/**
+ * Runtime collection registry — fetches from chain.listCollections via kernelCall
+ * and memoizes per process invocation (module-scope singleton).
+ *
+ * Fails open to a build-time SEED snapshot (mirrors PREFIX_TO_COLLECTION in
+ * capture.ts) so CLI commands continue to work even when the backend is
+ * unreachable or chain.listCollections is unavailable.
+ *
+ * FEAT-885 / TEN-1406: Replaces hardcoded PREFIX_TO_COLLECTION + datedCollections
+ * constants with runtime-derived data.  BR-108: CLI cannot import from convex/,
+ * so registry uses kernelCall (HTTP gateway).
+ */
+import { kernelCall } from './client.js';
+/**
+ * SEED fallback — mirrors PREFIX_TO_COLLECTION in capture.ts.
+ * Keeps the registry functional when backend is offline.
+ * Update when new collections are added to the system.
+ */
+const SEED = [
+    { slug: 'principles', idPrefix: 'PRI' },
+    { slug: 'standards', idPrefix: 'STD' },
+    { slug: 'business-rules', idPrefix: 'BR' },
+    { slug: 'policies', idPrefix: 'POL' },
+    { slug: 'patterns', idPrefix: 'PAT' },
+    { slug: 'glossary', idPrefix: 'GLO' },
+    { slug: 'features', idPrefix: 'FEAT' },
+    { slug: 'architecture', idPrefix: 'ARCH' },
+    { slug: 'decisions', idPrefix: 'DEC' },
+    { slug: 'strategy', idPrefix: 'STR' },
+    { slug: 'semantic-types', idPrefix: 'ST' },
+    { slug: 'maps', idPrefix: 'MAP' },
+    { slug: 'tensions', idPrefix: 'TEN' },
+    { slug: 'teams', idPrefix: 'TEAM' },
+    { slug: 'roles', idPrefix: 'ROL' },
+    { slug: 'assumptions', idPrefix: 'ASM' },
+    { slug: 'landscape', idPrefix: 'LAND' },
+    { slug: 'insights', idPrefix: 'INS' },
+    { slug: 'tasks', idPrefix: 'TASK' },
+    { slug: 'milestones', idPrefix: 'MIL' },
+    { slug: 'workstreams', idPrefix: 'WS' },
+    { slug: 'initiatives', idPrefix: 'INI' },
+    { slug: 'work-packages', idPrefix: 'WP' },
+    { slug: 'work-packages', idPrefix: 'BET' }, // legacy alias — BET-230 rename backward compat
+    { slug: 'audiences', idPrefix: 'AUD' },
+    { slug: 'key-results', idPrefix: 'KEY' },
+    { slug: 'questions', idPrefix: 'QUE' },
+    { slug: 'products', idPrefix: 'PROD' },
+    { slug: 'opportunities', idPrefix: 'OPP' },
+    { slug: 'experiments', idPrefix: 'EXP' },
+    { slug: 'flows', idPrefix: 'FLO' },
+];
+/**
+ * Collections that have a date field and accept a sourceDate during capture.
+ * Used as SEED fallback when the backend doesn't return field metadata.
+ */
+const DATED_COLLECTIONS_SEED = new Set([
+    'tensions',
+    'decisions',
+    'insights',
+    'standards',
+    'business-rules',
+]);
+let _cache = null;
+/**
+ * Fetch all collections for the current workspace.
+ * Module-scope memoized — calls kernelCall once per process, then returns
+ * the cached result.  Fails open to SEED on any error.
+ */
+export async function getCollections() {
+    if (_cache !== null)
+        return _cache;
+    try {
+        const result = await kernelCall('chain.listCollections');
+        _cache = Array.isArray(result) && result.length > 0 ? result : SEED;
+    }
+    catch {
+        _cache = SEED;
+    }
+    return _cache;
+}
+/**
+ * Build a prefix → collection slug map from the runtime registry.
+ * Falls back to SEED-derived map on failure.
+ */
+export async function getPrefixToCollection() {
+    const cols = await getCollections();
+    const map = {};
+    for (const col of cols) {
+        if (col.idPrefix)
+            map[col.idPrefix] = col.slug;
+    }
+    return map;
+}
+/**
+ * Returns slugs of collections that accept a date field during capture.
+ * Derived from classificationCheck presence when available (a non-empty
+ * classificationCheck indicates the collection is content-dated).
+ * Falls back to a hardcoded seed set when field metadata is absent.
+ */
+export async function getDatedCollections() {
+    const cols = await getCollections();
+    // If any collection in the result has classificationCheck populated, use that
+    // to derive dated collections (classificationCheck is present on collections
+    // that have date-sensitive content requiring classification).
+    const hasFieldMeta = cols.some((c) => c.classificationCheck !== undefined);
+    if (hasFieldMeta) {
+        return new Set(cols.filter((c) => !!c.classificationCheck).map((c) => c.slug));
+    }
+    // No field metadata available — fall back to seed list
+    return DATED_COLLECTIONS_SEED;
+}
+//# sourceMappingURL=collectionRegistry.js.map

package/dist/lib/collectionRegistry.js.map

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

package/dist/lib/compose-wrapup-view.d.ts

@@ -0,0 +1,48 @@
+/**
+ * composeWrapupView — the single place TEN-2402 is fixed on the CLI surface.
+ *
+ * Twin of the MCP package's helper (packages/mcp-server/src/lib/compose-wrapup-view.ts).
+ * CLI and MCP publish separately and cannot share a module, so each package keeps its own
+ * copy and a repo-level parity test (gateway-parity precedent) feeds ONE synthetic raw
+ * result to both and asserts set-equal committed/draft IDs + equal canClose.
+ *
+ * The MERGE (capped ∪ overflow) MUST live here, not at the call site — that is the only
+ * place the parity test can pin TEN-2402:
+ *   committed = committed ∪ overflowCommitted
+ *   drafts    = drafts ∪ overflowDrafts
+ *
+ * `canClose` is the REVIEW predicate (the loop is empty). Every overflow read coalesces
+ * `?? []` / `?? 0` so a result lacking the fields can never throw.
+ */
+export interface ComposedEntry {
+    entryId: string;
+    name: string;
+}
+interface OverflowEntry {
+    entryId: string;
+    name: string;
+}
+/** Raw kernel wrapup result this helper consumes (only the fields it reads are required). */
+export interface RawWrapupView {
+    committed?: Array<{
+        entryId: string;
+        name: string;
+    }>;
+    drafts?: Array<{
+        entryId: string;
+        name: string;
+    }>;
+    overflowCommitted?: OverflowEntry[];
+    overflowDrafts?: OverflowEntry[];
+    overflowUnscanned?: number;
+}
+export interface ComposedWrapupView {
+    committed: ComposedEntry[];
+    drafts: ComposedEntry[];
+    overflowUnscanned: number;
+    /** REVIEW predicate: the loop is empty (no remaining draft, nothing unread). */
+    canClose: boolean;
+}
+export declare function composeWrapupView(raw: RawWrapupView): ComposedWrapupView;
+export {};
+//# sourceMappingURL=compose-wrapup-view.d.ts.map

package/dist/lib/compose-wrapup-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-wrapup-view.d.ts","sourceRoot":"","sources":["../../src/lib/compose-wrapup-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,iBAAiB,CAAC,EAAE,aAAa,EAAE,CAAC;IACpC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAMD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,kBAAkB,CAgBxE"}

package/dist/lib/compose-wrapup-view.js

@@ -0,0 +1,37 @@
+/**
+ * composeWrapupView — the single place TEN-2402 is fixed on the CLI surface.
+ *
+ * Twin of the MCP package's helper (packages/mcp-server/src/lib/compose-wrapup-view.ts).
+ * CLI and MCP publish separately and cannot share a module, so each package keeps its own
+ * copy and a repo-level parity test (gateway-parity precedent) feeds ONE synthetic raw
+ * result to both and asserts set-equal committed/draft IDs + equal canClose.
+ *
+ * The MERGE (capped ∪ overflow) MUST live here, not at the call site — that is the only
+ * place the parity test can pin TEN-2402:
+ *   committed = committed ∪ overflowCommitted
+ *   drafts    = drafts ∪ overflowDrafts
+ *
+ * `canClose` is the REVIEW predicate (the loop is empty). Every overflow read coalesces
+ * `?? []` / `?? 0` so a result lacking the fields can never throw.
+ */
+function toComposed(e) {
+    return { entryId: e.entryId, name: e.name };
+}
+export function composeWrapupView(raw) {
+    const committed = [
+        ...(raw.committed ?? []).map(toComposed),
+        ...(raw.overflowCommitted ?? []).map(toComposed),
+    ];
+    const drafts = [
+        ...(raw.drafts ?? []).map(toComposed),
+        ...(raw.overflowDrafts ?? []).map(toComposed),
+    ];
+    const overflowUnscanned = raw.overflowUnscanned ?? 0;
+    return {
+        committed,
+        drafts,
+        overflowUnscanned,
+        canClose: drafts.length === 0 && overflowUnscanned === 0,
+    };
+}
+//# sourceMappingURL=compose-wrapup-view.js.map

package/dist/lib/compose-wrapup-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-wrapup-view.js","sourceRoot":"","sources":["../../src/lib/compose-wrapup-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA6BH,SAAS,UAAU,CAAC,CAAoC;IACtD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAkB;IAClD,MAAM,SAAS,GAAG;QAChB,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;QACxC,GAAG,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;KACjD,CAAC;IACF,MAAM,MAAM,GAAG;QACb,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;QACrC,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;KAC9C,CAAC;IACF,MAAM,iBAAiB,GAAG,GAAG,CAAC,iBAAiB,IAAI,CAAC,CAAC;IACrD,OAAO;QACL,SAAS;QACT,MAAM;QACN,iBAAiB;QACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,iBAAiB,KAAK,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/lib/config.d.ts

@@ -1,13 +1,171 @@
 /**
  * CLI config — reads PRODUCTBRAIN_API_KEY + CONVEX_SITE_URL from:
- * 1. Environment variables
- * 2. ~/.config/productbrain/.env (works from any directory)
- * 3. CWD .env.mcp / packages/mcp-server/.env.mcp / .env
+ * 1. Environment variables (always highest priority)
+ * 2. Project local config: .productbrain/config.local.json (walked up from CWD, machine-local)
+ * 3. Project config: .productbrain/config.json (walked up from CWD, siteUrl only — committed)
+ * 4. Profile system (~/.config/productbrain/profiles/{name}.env)
+ * 5. Legacy ~/.config/productbrain/.env (auto-migrated to profiles on first use)
+ * 6. CWD .env.mcp / packages/mcp-server/.env.mcp / .env
+ *
+ * Config loading is lazy — loadEnv() runs on first getConfig()/getConfigOrGuide() call.
+ * This enables profile switching without import-time side effects (TEN-1276).
  *
  * When key is missing and retry is provided (TTY), runs guided flow per docs/cli-unauthenticated-user-journey.md.
+ *
+ * Split config design:
+ * - config.json (committed): siteUrl only — workspace gateway, safe to share with teammates.
+ * - config.local.json (gitignored): profile pin — machine-local, never committed.
  */
 declare const HOME_CONFIG_DIR: string;
 declare const HOME_ENV_PATH: string;
+/** Project config shape — .productbrain/config.json (committed, siteUrl only) */
+interface ProjectConfig {
+    siteUrl?: string;
+}
+/** Local project config shape — .productbrain/config.local.json (gitignored, machine-local) */
+interface LocalProjectConfig {
+    profile?: string;
+    /** Direct preview API key — set by `npm run pb:preview`, cleared by `npm run pb:real`. */
+    apiKey?: string;
+    /** Preview site URL — set alongside apiKey by `npm run pb:preview`. */
+    siteUrl?: string;
+    /** Marks this config as preview-bound; the CLI shows a loud banner on every command. */
+    preview?: boolean;
+    /** Human-readable preview workspace name for the banner (e.g. "Preview Workspace"). */
+    workspaceName?: string;
+}
+/**
+ * Walk up the directory tree (git-style) to find the nearest CLI project root.
+ *
+ * A `.productbrain/` directory only counts as a CLI project root when it carries
+ * CLI configuration — `config.json` (committed siteUrl gateway) or
+ * `config.local.json` (machine-local profile pin or preview binding). A
+ * projection-only `.productbrain/` written by `pb handshake` (briefing.md,
+ * context.md, rules/, etc.) does NOT count — otherwise a subrepo like
+ * `packages/cli/.productbrain/` would shadow the real configuring root and
+ * `npm run pb:preview` writes (which always land at the repo-root
+ * `.productbrain/`) would be invisible to commands run from the subrepo.
+ *
+ * Stops at home directory or filesystem root. Returns the directory containing
+ * a config-bearing `.productbrain/`, or null if not found.
+ */
+export declare function findProjectRoot(startDir: string): string | null;
+/**
+ * Read .productbrain/config.json from the walked-up project root.
+ * Only reads siteUrl — profile and apiKey fields are ignored (legacy or misplaced).
+ * Returns null if file missing or project root not found.
+ * Warns to stderr on invalid JSON but does not throw.
+ */
+declare function readProjectConfig(): ProjectConfig | null;
+/**
+ * Read .productbrain/config.local.json from the walked-up project root.
+ * Returns the machine-local pin (`profile`) and any preview-binding fields
+ * (`apiKey`, `siteUrl`, `preview`, `workspaceName`) written by
+ * `npm run pb:preview` — all gitignored, never committed.
+ * Returns null if file missing or project root not found.
+ * Warns to stderr on invalid JSON but does not throw.
+ */
+export declare function readLocalProjectConfig(): LocalProjectConfig | null;
+/**
+ * Returns the preview binding metadata when pb is currently bound to a throwaway preview,
+ * or null when bound to the real Chain (the default).
+ *
+ * Effective-binding mirror: this only reports a preview binding when
+ * `resolveConfig()`/`loadEnv()` would actually honor it — `preview === true` AND
+ * an atomic apiKey+siteUrl pair (SF-3) AND no `PRODUCTBRAIN_API_KEY` env override
+ * (env always wins in resolveConfig step 1). Without these guards the PREVIEW
+ * banner could fire while writes still hit the real Chain, defeating the safety
+ * warning. Used by the PREVIEW banner (index.ts preAction hook) and the
+ * capture/update advisory.
+ *
+ * Security classification: reads only the gitignored machine-local config.local.json.
+ * The preview key in that file is a throwaway preview-scoped key, set by explicit
+ * `npm run pb:preview` opt-in and reversed by `npm run pb:real`. Never throws — returns
+ * null on any error so the banner/advisory path is never the source of a CLI crash.
+ */
+export declare function getPreviewBinding(): {
+    workspaceName: string | null;
+} | null;
+/**
+ * Write/merge the profile pin into <projectRoot>/.productbrain/config.local.json,
+ * preserving any sibling keys. Single source of truth for the local pin write —
+ * used by `pb profile use --local`, the default reconcile path, and `pb connect`.
+ *
+ * Co-writer note (SF-2): scripts/pb-binding.mjs is the OTHER writer of config.local.json — it
+ * merges/strips the preview-binding keys (apiKey, siteUrl, preview, workspaceName) for
+ * `npm run pb:preview` / `npm run pb:real`. Both writers preserve the `profile` pin. If you add
+ * a preview-scoped key here or in readLocalProjectConfig(), update pb-binding.mjs's PREVIEW_KEYS.
+ */
+export declare function setLocalProfilePin(projectRoot: string, profile: string): void;
+/**
+ * Outcome of a preview apiKey refresh attempt (WP-458 E2). The discriminated result lets the
+ * caller (session.ts) react precisely instead of conflating "couldn't recover" with "the failure
+ * wasn't a stale key at all":
+ *  - 'refreshed'   — a DIFFERENT valid key was loaded; a retry is worthwhile.
+ *  - 'unchanged'   — preview.json's key already matches the bound key, so the auth/INTERNAL failure
+ *                    is NOT a stale-key problem. The caller must surface the ORIGINAL error rather
+ *                    than relabel it (the reviewer's no-masking concern; R2 honesty).
+ *  - 'unavailable' — preview-bound but preview.json is missing/malformed/lacks a valid key, so the
+ *                    stale binding cannot be recovered. The caller surfaces a clean, actionable
+ *                    error (doneWhen #1: no opaque INTERNAL).
+ *  - 'not-bound'   — not a preview binding, or a genuine env override is in play; leave the error
+ *                    untouched.
+ */
+export type PreviewKeyRefresh = 'refreshed' | 'unchanged' | 'unavailable' | 'not-bound';
+/**
+ * WP-458 E2 — one-shot preview apiKey refresh from disk.
+ *
+ * After a worktree preview is reseeded, seed-preview.mjs Step 6 mints a NEW apiKey into
+ * `.productbrain/preview.json`, but `config.local.json` (and the live `process.env` binding it
+ * seeded via loadEnv) still carry the PRE-reseed key — so the next `pb session start` fails auth
+ * with an opaque INTERNAL. This re-reads the fresh key from preview.json so the caller can retry
+ * ONCE (session.ts). It is deliberately disk-to-disk: it compares preview.json's key against
+ * config.local.json's bound key, NOT against process.env (which loadEnv already populated from the
+ * stale binding), so it can't be confused by its own prior population. Never throws — any error
+ * degrades to 'unavailable'/'not-bound' so it can sit on the session-start path.
+ *
+ * Co-writer note (SF-2): mirrors pb-binding.mjs / setLocalProfilePin — preserves every sibling key
+ * in config.local.json (profile, preview, workspaceName) and only rewrites apiKey + siteUrl.
+ */
+export declare function refreshPreviewApiKeyFromDisk(): PreviewKeyRefresh;
+/** Source of the effective profile, in resolution-precedence order. */
+export type EffectiveProfileSource = 'env' | 'local' | 'global' | 'default' | 'none';
+/**
+ * Resolve the effective profile NAME + where it came from. The SOURCE-PRECEDENCE
+ * ORDER matches resolveConfig() (env > local pin > global > default), but unlike
+ * resolveConfig() this reports the *configured* pin name even when that profile is
+ * unresolvable (deleted / missing key). That divergence is intentional: a dangling
+ * repo pin must be surfaced by `pb whoami`, not silently masked by the global
+ * profile — masking it is the TEN-2163 silent-drift bug. Used by `pb whoami` and
+ * the inline "now using" prints.
+ */
+export declare function resolveEffectiveProfile(): {
+    profile: string | null;
+    source: EffectiveProfileSource;
+};
+/** Config source in resolution priority order. */
+export type ConfigSource = 'env' | 'project' | 'profile' | 'cwd' | 'default';
+/** Result of the full config resolution cascade. */
+export interface ResolvedConfig {
+    apiKey?: string;
+    siteUrl: string;
+    source: ConfigSource;
+}
+/**
+ * Run the full config resolution cascade and return a typed result.
+ * Resolution order:
+ * 1. Environment variables (highest priority)
+ * 2. config.local.json profile → resolveNamedProfileConfig(profile) for apiKey + siteUrl
+ * 2b. config.json siteUrl (gateway override only — no apiKey, no profile)
+ * 3. Profile system (~/.config/productbrain/profiles/{name}.env)
+ * 4. Legacy home config (~/.config/productbrain/.env)
+ * 5. CWD .env files (.env.mcp, packages/mcp-server/.env.mcp, .env)
+ *
+ * siteUrl always has a value (falls back to DEFAULT_SITE_URL).
+ */
+export declare function resolveConfig(): ResolvedConfig;
+/** Reset env loaded state — used for profile switching. */
+export declare function resetConfigCache(): void;
 export declare function getConfig(): {
     apiKey: string;
     siteUrl: string;
@@ -16,11 +174,53 @@ export type Config = {
     apiKey: string;
     siteUrl: string;
 };
+/** Discriminated union result for non-throwing config access. */
+export type ConfigResult = {
+    ok: true;
+    apiKey: string;
+    siteUrl: string;
+    source: ConfigSource;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Non-throwing alternative to getConfig().
+ *
+ * Architecture: getConfig() is the primary path for commands that require auth — it
+ * throws CLIError when the key is missing, which is correct for API call paths.
+ * getConfigSafe() is for status/probe surfaces (no-args dashboard, init) that need
+ * to check config availability without crashing. Both paths are intentional and
+ * coexist by design — see WP-303 review (DW#5).
+ *
+ * Uses resolveConfig() directly (no loadEnv) to avoid env var pollution affecting source attribution.
+ */
+export declare function getConfigSafe(): ConfigResult;
 /**
  * Get config; if key is missing and stdin is a TTY, run guided flow (y/n → paste key → save → retry).
  * @param retry Called after saving key so the original command runs in-process.
  * @returns Config, or null if we ran retry (caller should return without running again).
  */
 export declare function getConfigOrGuide(retry: () => Promise<void>): Promise<Config | null>;
-export { HOME_CONFIG_DIR, HOME_ENV_PATH };
+/**
+ * Resolve config for admin operations — profile-only resolution.
+ *
+ * Admin commands (pb admin ...) must NOT read .productbrain/config.json or CWD env files.
+ * The project config intentionally pins the repo to a dev Convex site; admin operations
+ * target PROD workspaces via the operator's active profile. Reading project config here
+ * would silently route admin calls to the wrong gateway (TEN-1334).
+ *
+ * Resolution order:
+ * 1. Shell env vars (PRODUCTBRAIN_API_KEY / CONVEX_SITE_URL) — always win
+ * 2. Active named profile (~/.config/productbrain/profiles/{name}.env)
+ * 3. Legacy home config (~/.config/productbrain/.env)
+ * 4. DEFAULT_SITE_URL as fallback for siteUrl
+ *
+ * Throws CLIError with AUTH_MISSING if no API key is found.
+ */
+export declare function resolveAdminConfig(): {
+    apiKey: string;
+    siteUrl: string;
+};
+export { HOME_CONFIG_DIR, HOME_ENV_PATH, readProjectConfig };
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,QAAA,MAAM,eAAe,QAAgD,CAAC;AACtE,QAAA,MAAM,aAAa,QAAmC,CAAC;AA2FvD,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe/D;AAED,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAczF;AAED,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}