@productbrain/cli 0.1.0-beta.1 → 0.1.0-beta.1000

package/dist/lib/config.d.ts

@@ -1,9 +1,195 @@
 /**
- * CLI config — reads PRODUCTBRAIN_API_KEY + CONVEX_SITE_URL from env / .env.mcp.
- * Mirrors scripts/test-orient.mjs pattern.
+ * CLI config — reads PRODUCTBRAIN_API_KEY + CONVEX_SITE_URL from:
+ * 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;
+/** 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;
 };
+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>;
+/**
+ * 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;;;GAGG;AA2BH,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiB/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}