@productbrain/cli 0.1.0-beta.1125 → 0.1.0-beta.11259

package/dist/lib/config.d.ts

@@ -2,7 +2,8 @@
  * 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)
+ * 3. Project config: .productbrain/config.json (walked up from CWD, committed) — its presence
+ *    declares a project; its siteUrl never routes a key (TEN-4500)
  * 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
@@ -12,60 +13,14 @@
  *
  * 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.
+ * The repo's own config files (.productbrain/config.json, config.local.json) are located and
+ * read by projectConfig.ts — this module turns what they declare into a credential.
  */
+import { type ConfigResult, type ResolvedConfig } from './configResult.js';
 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;
+export { findProjectRoot, readLocalProjectConfig, type LocalProjectConfig } from './projectConfig.js';
+export type { ConfigFailureKind, ConfigResult, ConfigSource, ResolvedConfig, SiteUrlSource } from './configResult.js';
 /**
  * Returns the preview binding metadata when pb is currently bound to a throwaway preview,
  * or null when bound to the real Chain (the default).
@@ -93,7 +48,7 @@ export declare function getPreviewBinding(): {
  *
  * 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
+ * `npm run pb:preview` / `npm run pb:real`, plus previewKey*. Both writers keep 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;
@@ -102,11 +57,11 @@ export declare function setLocalProfilePin(projectRoot: string, profile: string)
  * 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
+ *  - 'unchanged'   — the bound key file'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
+ *  - 'unavailable' — preview-bound but the bound key file is unrecorded, missing, malformed, names
+ *                    another person, workspace or seat, or 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.
@@ -115,55 +70,56 @@ export type PreviewKeyRefresh = 'refreshed' | 'unchanged' | 'unavailable' | 'not
 /**
  * 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
+ * After a worktree preview is reseeded, seed-preview.mjs Step 6 mints a NEW apiKey into the bound key
+ * file the binding recorded (`previewKey`), 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
+ * with an opaque INTERNAL. This re-reads the fresh key from that file so the caller can retry
+ * ONCE (session.ts). It is deliberately disk-to-disk: it compares that file'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.
+ * in config.local.json (profile, preview, workspaceName, previewKey*) 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';
+export type EffectiveProfileSource = 'local' | 'env' | '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.
+ * Resolve the effective profile NAME + where it came from. PRECEDENCE — local pin > env >
+ * global > default: the pin outranks `PB_PROFILE` because resolveConfig() 2b / loadEnv() 1b
+ * bind the pinned key before the profile system (the only step reading `PB_PROFILE`), so
+ * under both the env name never supplies the credential and must not be reported. Unlike
+ * resolveConfig() this names the *configured* pin even when unresolvable (deleted / missing
+ * key): a dangling pin must be surfaced by `pb whoami`, never masked by the global profile
+ * — the TEN-2163 silent-drift bug. Used by `pb whoami`, session labels, "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)
+ * 2c. Declared project naming no tenant — refuses (config.json names neither a tenant nor a gateway)
  * 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).
+ * A key travels only with the site URL stored or exported beside it (TEN-4500): every branch
+ * reads its URL from the same source as its key, and a key with no URL of its own goes to
+ * DEFAULT_SITE_URL. `.productbrain/config.json` is committed, so a cloned repo controls its
+ * siteUrl; it never routes a key. Same rule as resolveAdminConfig() (TEN-1334). loadEnv()
+ * exports this function's answer, so `pb doctor` and the command path cannot name different
+ * hosts. `siteUrlSource` records which source supplied the URL.
+ *
+ * THROWS at step 2 rather than substituting a different workspace: CONFIG_INVALID at 2a
+ * (incomplete binding), AUTH_MISSING at 2b (dangling pin), missing-pin at 2c. getConfigSafe()
+ * reports each as `ok: false` with the kind preserved, for callers that must not crash.
  */
-export declare function resolveConfig(): ResolvedConfig;
+export declare function resolveConfig(ignoreEnvKey?: boolean): ResolvedConfig;
 /** Reset env loaded state — used for profile switching. */
 export declare function resetConfigCache(): void;
 export declare function getConfig(): {
@@ -174,16 +130,6 @@ 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().
  *
@@ -194,6 +140,12 @@ export type ConfigResult = {
  * coexist by design — see WP-303 review (DW#5).
  *
  * Uses resolveConfig() directly (no loadEnv) to avoid env var pollution affecting source attribution.
+ *
+ * A refusal from resolveConfig() (dangling repo pin) is reported as `ok: false` with the
+ * refusal as the reason — NOT rethrown. This surface is what `pb doctor` and the bare-`pb`
+ * dashboard use to *diagnose*, and a diagnostic that dies on the condition it exists to
+ * explain is useless. The refusal keeps its teeth either way: `ok: false` hands out no
+ * credential, so nothing can proceed against the wrong workspace.
  */
 export declare function getConfigSafe(): ConfigResult;
 /**
@@ -202,25 +154,5 @@ export declare function getConfigSafe(): ConfigResult;
  * @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 };
+export { HOME_CONFIG_DIR, HOME_ENV_PATH };
 //# 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;;;;;;;;;;;;;;;;;GAiBG;AAWH,QAAA,MAAM,eAAe,QAAgD,CAAC;AACtE,QAAA,MAAM,aAAa,QAAmC,CAAC;AAUvD,iFAAiF;AACjF,UAAU,aAAa;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+FAA+F;AAC/F,UAAU,kBAAkB;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB/D;AAED;;;;;GAKG;AACH,iBAAS,iBAAiB,IAAI,aAAa,GAAG,IAAI,CAuBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,kBAAkB,GAAG,IAAI,CAmClE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAW3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAY7E;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,WAAW,CAAC;AAExF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,IAAI,iBAAiB,CAyDhE;AAED,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAErF;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAapG;AAED,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7E,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,IAAI,cAAc,CA+F9C;AAwFD,2DAA2D;AAC3D,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AA6DD,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA0B/D;AAED,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,iEAAiE;AACjE,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACnE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAiB5C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBzF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAmDxE;AAED,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAYH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAE3B,QAAA,MAAM,eAAe,QAAgD,CAAC;AACtE,QAAA,MAAM,aAAa,QAAmC,CAAC;AAYvD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACtG,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEtH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAO3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAY7E;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,WAAW,CAAC;AAExF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,IAAI,iBAAiB,CAiDhE;AAED,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAErF;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAapG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,YAAY,UAAQ,GAAG,cAAc,CAsFlE;AAyDD,2DAA2D;AAC3D,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AA6DD,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA0B/D;AAED,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAE5C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmBzF;AAMD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC"}