@productbrain/cli 0.1.0-beta.49 → 0.1.0-beta.4902

package/dist/lib/configResult.d.ts

@@ -0,0 +1,80 @@
+/** Structured, non-throwing view of the CLI configuration cascade. */
+import { CLIError, type ErrorCategory, type ErrorCodeValue } from './errors.js';
+export type ConfigSource = 'env' | 'project' | 'profile' | 'cwd' | 'default';
+/**
+ * Where the resolved `siteUrl` came from — tracked SEPARATELY from `ConfigSource`.
+ *
+ * The credential and the gateway are picked by two different fallback chains: almost every
+ * credential branch prefers `.productbrain/config.json`'s siteUrl over its own. So a result
+ * labelled `profile`/`cwd` can be carrying a URL that came from config.json, and naming the
+ * credential's source in a URL repair would send the operator to edit a file that does not
+ * control the failing URL.
+ */
+export type SiteUrlSource = 'env' | 'local-binding' | 'profile-pin' | 'project-config' | 'profile' | 'legacy' | 'cwd' | 'default';
+export interface ResolvedConfig {
+    apiKey?: string;
+    siteUrl: string;
+    source: ConfigSource;
+    /**
+     * Which candidate supplied `siteUrl`. Optional because a caller may construct a
+     * ResolvedConfig without observing the cascade; diagnostics must then name NO source
+     * rather than guess one.
+     */
+    siteUrlSource?: SiteUrlSource;
+    /**
+     * The concrete file a source resolved to, where the source alone is ambiguous — `cwd` covers
+     * three different candidate paths, so naming the generic one would point the operator at a
+     * file that is not the one being read.
+     */
+    siteUrlDetail?: string;
+    /**
+     * Which named profile supplied a `profile`-sourced credential or URL. Absent when the profile
+     * cascade landed on the nameless legacy `~/.config/productbrain/.env`, so diagnostics can name
+     * the profile that actually won instead of an "active profile" that may not be the one read.
+     */
+    profileName?: string;
+}
+/**
+ * Pick the first present siteUrl candidate and record which one won, so the URL and its
+ * reported origin are produced by one expression and cannot disagree. Candidates are given
+ * in the caller's existing precedence order; `DEFAULT_SITE_URL` closes every chain.
+ */
+export declare function pickSiteUrl(candidates: ReadonlyArray<readonly [SiteUrlSource, string | undefined, string?]>): {
+    siteUrl: string;
+    siteUrlSource: SiteUrlSource;
+    siteUrlDetail?: string;
+};
+export type ConfigFailureKind = 'missing-key' | 'invalid-key' | 'profile-pin' | 'preview-binding' | 'invalid-url' | 'unknown';
+export type ConfigResult = {
+    ok: true;
+    apiKey: string;
+    siteUrl: string;
+    source: ConfigSource;
+} | {
+    ok: false;
+    kind: ConfigFailureKind;
+    reason: string;
+    guidance: string;
+    nextCommand: string;
+};
+/**
+ * The transport-security bar every cascade enforces: HTTPS, or http://localhost while in dev mode.
+ * Both the structured result below and `getConfigOrGuide()`'s throwing path read it from here so
+ * the two can never diverge on what counts as a safe gateway to send an API key to.
+ */
+export declare function isInsecureSiteUrl(siteUrl: string): boolean;
+/** A resolution refusal that diagnostic surfaces must preserve instead of relabelling. */
+export declare class ConfigResolutionError extends CLIError {
+    readonly kind: ConfigFailureKind;
+    readonly nextCommand: string;
+    constructor(message: string, options: {
+        kind: ConfigFailureKind;
+        nextCommand: string;
+        code?: ErrorCodeValue;
+        category?: ErrorCategory;
+        guidance: string;
+    });
+}
+/** Convert a throwing resolution cascade into the single diagnostic contract. */
+export declare function resolveConfigResult(resolveConfig: () => ResolvedConfig): ConfigResult;
+//# sourceMappingURL=configResult.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configResult.d.ts","sourceRoot":"","sources":["../../src/lib/configResult.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAE,QAAQ,EAAa,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG3F,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7E;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB,KAAK,GACL,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,SAAS,GACT,QAAQ,GACR,KAAK,GACL,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,GAC/E;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAK3E;AAED,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,aAAa,GACb,SAAS,CAAC;AAEd,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;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AA2EN;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,0FAA0F;AAC1F,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,IAAI,EAAE,iBAAiB,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,aAAa,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;KAClB;CAOJ;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,cAAc,GAAG,YAAY,CAqErF"}

package/dist/lib/configResult.js

@@ -0,0 +1,176 @@
+/** Structured, non-throwing view of the CLI configuration cascade. */
+import { DEFAULT_SITE_URL, isDevMode } from './constants.js';
+import { CLIError } from './errors.js';
+import { API_KEY_PREFIX } from './tokenConstants.js';
+/**
+ * Pick the first present siteUrl candidate and record which one won, so the URL and its
+ * reported origin are produced by one expression and cannot disagree. Candidates are given
+ * in the caller's existing precedence order; `DEFAULT_SITE_URL` closes every chain.
+ */
+export function pickSiteUrl(candidates) {
+    for (const [siteUrlSource, value, siteUrlDetail] of candidates) {
+        if (value)
+            return { siteUrl: value.replace(/\/$/, ''), siteUrlSource, siteUrlDetail };
+    }
+    return { siteUrl: DEFAULT_SITE_URL.replace(/\/$/, ''), siteUrlSource: 'default' };
+}
+/**
+ * What to call a `profile` source that has no name.
+ *
+ * `resolveProfileConfig()` reaches a credential four ways — `PB_PROFILE`, the active-profile
+ * marker, a `default` fallback, and the legacy `~/.config/productbrain/.env` — and `resolveConfig()`
+ * reports the legacy home file as `profile` too. Only the first three have a name, so a fixed
+ * "the active profile" label would claim the operator's active profile supplied a credential that
+ * came from `PB_PROFILE`, from `default`, or from a file that is not a profile at all.
+ */
+const UNNAMED_PROFILE_ORIGIN = 'the stored profile configuration';
+/** Name the profile that won, or fall back to the nameless label above. */
+function describeProfileOrigin(profileName) {
+    return profileName ? `the profile "${profileName}"` : UNNAMED_PROFILE_ORIGIN;
+}
+/** The repo pin knows which profile it names, so say so rather than "the profile it pins". */
+function describePinnedOrigin(profileName) {
+    return profileName
+        ? `the profile "${profileName}" pinned by .productbrain/config.local.json`
+        : 'the profile pinned by .productbrain/config.local.json';
+}
+/**
+ * The operator-facing name of each siteUrl origin.
+ *
+ * Only an environment API key outranks a file in the cascade, so every file-sourced URL keeps
+ * winning over `CONVEX_SITE_URL`. Telling every caller to set that variable would send the
+ * operator around the same failure again — the repair has to name the origin that actually won.
+ */
+const SITE_URL_ORIGIN = {
+    env: 'the CONVEX_SITE_URL environment variable',
+    'local-binding': '.productbrain/config.local.json',
+    'profile-pin': 'the profile pinned by .productbrain/config.local.json',
+    'project-config': '.productbrain/config.json',
+    profile: UNNAMED_PROFILE_ORIGIN,
+    legacy: 'the legacy config at ~/.config/productbrain/.env',
+    cwd: 'the .env file in this directory',
+    default: 'the built-in default',
+};
+/**
+ * Name the origin, preferring the concrete file or profile when the source covers several.
+ * `cwd` spans three candidate paths (`.env.mcp`, `packages/mcp-server/.env.mcp`, `.env`), so the
+ * generic label would send the operator to edit a file the cascade never read.
+ */
+function describeSiteUrlOrigin(source, detail, profileName) {
+    if (detail)
+        return `${detail} in this directory`;
+    if (source === 'profile')
+        return describeProfileOrigin(profileName);
+    if (source === 'profile-pin')
+        return describePinnedOrigin(profileName);
+    return SITE_URL_ORIGIN[source];
+}
+/** The operator-facing name of each credential origin, for `invalid-key` messages. */
+const API_KEY_ORIGIN = {
+    env: 'the PRODUCTBRAIN_API_KEY environment variable',
+    project: '.productbrain/config.local.json (or the profile it pins)',
+    profile: UNNAMED_PROFILE_ORIGIN,
+    cwd: 'the .env file in this directory',
+    default: 'the built-in default',
+};
+/**
+ * Name the credential's origin, preferring the profile that actually supplied it.
+ * `project` covers both the direct local binding (no profile) and the repo pin (which names one),
+ * so the pin is only claimed when a profile name is actually present.
+ */
+function describeApiKeyOrigin(source, profileName) {
+    if (source === 'profile')
+        return describeProfileOrigin(profileName);
+    if (source === 'project' && profileName)
+        return describePinnedOrigin(profileName);
+    return API_KEY_ORIGIN[source];
+}
+/**
+ * The transport-security bar every cascade enforces: HTTPS, or http://localhost while in dev mode.
+ * Both the structured result below and `getConfigOrGuide()`'s throwing path read it from here so
+ * the two can never diverge on what counts as a safe gateway to send an API key to.
+ */
+export function isInsecureSiteUrl(siteUrl) {
+    return !siteUrl.startsWith('https://') && !(isDevMode() && siteUrl.startsWith('http://localhost'));
+}
+/** A resolution refusal that diagnostic surfaces must preserve instead of relabelling. */
+export class ConfigResolutionError extends CLIError {
+    kind;
+    nextCommand;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ConfigResolutionError';
+        this.kind = options.kind;
+        this.nextCommand = options.nextCommand;
+    }
+}
+/** Convert a throwing resolution cascade into the single diagnostic contract. */
+export function resolveConfigResult(resolveConfig) {
+    let resolved;
+    try {
+        resolved = resolveConfig();
+    }
+    catch (error) {
+        if (error instanceof ConfigResolutionError) {
+            return {
+                ok: false,
+                kind: error.kind,
+                reason: error.message,
+                guidance: error.guidance ?? `Run \`${error.nextCommand}\`.`,
+                nextCommand: error.nextCommand,
+            };
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            kind: 'unknown',
+            reason,
+            guidance: 'Run `pb doctor` to diagnose the configuration.',
+            nextCommand: 'pb doctor',
+        };
+    }
+    if (!resolved.apiKey) {
+        return {
+            ok: false,
+            kind: 'missing-key',
+            reason: 'No API key configured.',
+            guidance: 'Run `pb login` to configure your API key, or set PRODUCTBRAIN_API_KEY.',
+            nextCommand: 'pb login',
+        };
+    }
+    if (!resolved.apiKey.startsWith(API_KEY_PREFIX)) {
+        // `source` IS the credential's origin by definition, so it can be named without hedging.
+        // An exported key wins step 1 of the cascade, which `pb login` cannot outrank: login
+        // persists into a profile or the legacy home file, both of which lose to the env var —
+        // so telling the operator to log in would replay the identical failure forever.
+        const fromEnv = resolved.source === 'env';
+        return {
+            ok: false,
+            kind: 'invalid-key',
+            reason: `Invalid API key format (expected ${API_KEY_PREFIX}..., from ${describeApiKeyOrigin(resolved.source, resolved.profileName)}).`,
+            guidance: fromEnv
+                ? `Unset PRODUCTBRAIN_API_KEY, or replace it with a valid ${API_KEY_PREFIX} key — it outranks every stored profile, so \`pb login\` cannot repair this.`
+                : 'Run `pb login` to configure a valid API key.',
+            nextCommand: fromEnv ? 'pb doctor' : 'pb login',
+        };
+    }
+    if (isInsecureSiteUrl(resolved.siteUrl)) {
+        const got = `got "${resolved.siteUrl.slice(0, 30)}…"`;
+        // No recorded provenance means the URL's origin was never observed. Naming a specific file
+        // here would be a guess, and a wrong repair target is worse than an unnamed one.
+        const origin = resolved.siteUrlSource
+            ? describeSiteUrlOrigin(resolved.siteUrlSource, resolved.siteUrlDetail, resolved.profileName)
+            : null;
+        return {
+            ok: false,
+            kind: 'invalid-url',
+            reason: `Site URL must use HTTPS (${got}${origin ? `, from ${origin}` : ''}). API keys must not be sent over unencrypted connections.`,
+            guidance: origin
+                ? `Set an https:// URL in ${origin}.`
+                : 'Run `pb doctor` to see which source supplied the URL, then set an https:// URL there.',
+            nextCommand: 'pb doctor',
+        };
+    }
+    return { ok: true, ...resolved, apiKey: resolved.apiKey };
+}
+//# sourceMappingURL=configResult.js.map

package/dist/lib/configResult.js.map

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

package/dist/lib/connectKeyLabel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Labels for API keys from `pb connect` — keep in sync with convex/lib/connectRedeemDisplayName.ts.
+ * (Monorepo boundary: Convex cannot import from packages/cli and vice versa.)
+ */
+export declare const CONNECT_REDEEM_DEFAULT_API_KEY_NAME = "Product Brain CLI";
+export declare const CONNECT_REDEEM_NAME_MAX_LENGTH = 200;
+/** Align client-side trimming with server `normalizeConnectRedeemDisplayName` (control strip + cap). */
+export declare function trimClientKeyLabelInput(raw: string): string;
+//# sourceMappingURL=connectKeyLabel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connectKeyLabel.d.ts","sourceRoot":"","sources":["../../src/lib/connectKeyLabel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,mCAAmC,sBAAsB,CAAC;AAEvE,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAIlD,wGAAwG;AACxG,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/lib/connectKeyLabel.js

@@ -0,0 +1,12 @@
+/**
+ * Labels for API keys from `pb connect` — keep in sync with convex/lib/connectRedeemDisplayName.ts.
+ * (Monorepo boundary: Convex cannot import from packages/cli and vice versa.)
+ */
+export const CONNECT_REDEEM_DEFAULT_API_KEY_NAME = 'Product Brain CLI';
+export const CONNECT_REDEEM_NAME_MAX_LENGTH = 200;
+const CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/g;
+/** Align client-side trimming with server `normalizeConnectRedeemDisplayName` (control strip + cap). */
+export function trimClientKeyLabelInput(raw) {
+    return raw.replace(CONTROL_CHARS, '').trim().slice(0, CONNECT_REDEEM_NAME_MAX_LENGTH).trimEnd();
+}
+//# sourceMappingURL=connectKeyLabel.js.map

package/dist/lib/connectKeyLabel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectKeyLabel.js","sourceRoot":"","sources":["../../src/lib/connectKeyLabel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,mCAAmC,GAAG,mBAAmB,CAAC;AAEvE,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAElD,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAEtD,wGAAwG;AACxG,MAAM,UAAU,uBAAuB,CAAC,GAAW;IAClD,OAAO,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,8BAA8B,CAAC,CAAC,OAAO,EAAE,CAAC;AACjG,CAAC"}

package/dist/lib/constants.d.ts

@@ -4,6 +4,8 @@
  */
 /** Production Convex HTTP Actions endpoint. */
 export declare const DEFAULT_SITE_URL = "https://gateway.productbrain.io";
+/** Canonical self-upgrade command. WP-425 fixes the stale @latest dist-tag trap. */
+export declare const UPGRADE_COMMAND = "npm install -g @productbrain/cli@beta";
 /**
  * Resolve the Convex site URL based on PB_ENV.
  * - PB_ENV=dev → DEV_SITE_URL (localhost — see caveat on DEV_SITE_URL)
@@ -32,7 +34,9 @@ export declare function resolveSiteUrl(): string;
  */
 export declare function resolveConnectRedeemUrl(cliGateway?: string): string;
 /**
- * Resolve the web app URL based on PB_ENV.
+ * Resolve the web app URL.
+ * - PB_APP_URL (explicit override) → wins, for any binding whose app host isn't
+ *   inferrable from PB_ENV (e.g. a preview deployment walked via a custom host).
  * - PB_ENV=dev → localhost:5173
  * - PB_ENV=production or unset → work.productbrain.io
  */

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAiBlE;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQnE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAItC;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,IAAI,OAAO,CAEnC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAElE,oFAAoF;AACpF,eAAO,MAAM,eAAe,0CAA0C,CAAC;AAiBvE;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQnE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAMtC;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,IAAI,OAAO,CAEnC"}

package/dist/lib/constants.js

@@ -4,6 +4,8 @@
  */
 /** Production Convex HTTP Actions endpoint. */
 export const DEFAULT_SITE_URL = 'https://gateway.productbrain.io';
+/** Canonical self-upgrade command. WP-425 fixes the stale @latest dist-tag trap. */
+export const UPGRADE_COMMAND = 'npm install -g @productbrain/cli@beta';
 /** Hostname lists for banners + admin seed gates live in `deployment.ts` (PRODUCTION_HOSTS, DEV_CLOUD_HOSTS). */
 /** Production web app URL. */
 const PROD_APP_URL = 'https://work.productbrain.io';
@@ -59,11 +61,16 @@ export function resolveConnectRedeemUrl(cliGateway) {
     return DEFAULT_SITE_URL;
 }
 /**
- * Resolve the web app URL based on PB_ENV.
+ * Resolve the web app URL.
+ * - PB_APP_URL (explicit override) → wins, for any binding whose app host isn't
+ *   inferrable from PB_ENV (e.g. a preview deployment walked via a custom host).
  * - PB_ENV=dev → localhost:5173
  * - PB_ENV=production or unset → work.productbrain.io
  */
 export function resolveAppUrl() {
+    const override = process.env.PB_APP_URL?.trim();
+    if (override)
+        return override.replace(/\/$/, '');
     const env = process.env.PB_ENV?.toLowerCase();
     if (env === 'dev')
         return DEV_APP_URL;

package/dist/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,iCAAiC,CAAC;AAElE,iHAAiH;AAEjH,8BAA8B;AAC9B,MAAM,YAAY,GAAG,8BAA8B,CAAC;AAEpD;;;;GAIG;AACH,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAE7C,yBAAyB;AACzB,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC9C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,YAAY,CAAC;IACvC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAmB;IACzD,MAAM,OAAO,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,CAAC;IAC3D,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC9C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,WAAW,CAAC;IACtC,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,KAAK,CAAC;AACrD,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,iCAAiC,CAAC;AAElE,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,uCAAuC,CAAC;AAEvE,iHAAiH;AAEjH,8BAA8B;AAC9B,MAAM,YAAY,GAAG,8BAA8B,CAAC;AAEpD;;;;GAIG;AACH,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAE7C,yBAAyB;AACzB,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC9C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,YAAY,CAAC;IACvC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAmB;IACzD,MAAM,OAAO,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,CAAC;IAC3D,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IAChD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC9C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,WAAW,CAAC;IACtC,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,KAAK,CAAC;AACrD,CAAC"}

package/dist/lib/conversation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Conversation identity resolution — WP-479 E2 (client half).
+ *
+ * Feature-detects a stable per-conversation identifier so multiple concurrent harness
+ * conversations (Claude Code, Cursor, Codex, …) sharing one worktree don't collide on the single
+ * legacy `.productbrain/session.json` marker. All channels are optional and degrade gracefully —
+ * absent any signal, resolution returns `null` and every caller falls back to the pre-WP-479
+ * single-marker behavior (zero-config invariant).
+ *
+ * Priority order (harness findings: INS-2122, founder-run tests 2026-07-10):
+ *   1. explicit override (CLI `--conversation` flag on `pb session start`) — the manual seam.
+ *   2. `PB_CONVERSATION_ID` — the universal seam any harness adapter can set.
+ *   3. `CLAUDE_CODE_SESSION_ID` — present in Claude Code 2.1.206+ Bash shells (version-dependent,
+ *      treat as detected, never asserted).
+ *   4. `CURSOR_CONVERSATION_ID` — confirmed live in cursor-agent 2026.07.01 shell env.
+ *   5. `CODEX_TUI_SESSION_LOG_PATH` — Codex has no native conversation id; this Superset-injected
+ *      log path is unique per session run and stands in as the discriminator. It always contains
+ *      `/`, so normalization (below) always hashes it — no special-casing needed here.
+ *   6. none of the above → `null` (legacy shared-marker path).
+ */
+/**
+ * Normalize a raw candidate conversation id into a value that is always safe to use as (a) a
+ * Convex join key and (b) a filesystem path segment. Never truncates (a `slice()` would collide
+ * two distinct long ids into one lineage) — oversized or unsafe-charset ids are replaced whole
+ * with their sha256 hex digest (fixed-width, charset-safe by construction).
+ */
+export declare function normalizeConversationId(raw: string): string;
+/**
+ * Resolve the effective conversation id for the current process. `explicitOverride` — normally
+ * only threaded through from the CLI's `--conversation` flag on `pb session start` — takes
+ * priority over every env channel. Every other call site (the vast majority) calls this with no
+ * argument, which is pure env-based feature detection: with none of the channel env vars set,
+ * this returns `null` and callers must fall back to legacy behavior.
+ */
+export declare function resolveConversationId(explicitOverride?: string | null): string | null;
+//# sourceMappingURL=conversation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/lib/conversation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3D;AAiBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAIrF"}

package/dist/lib/conversation.js

@@ -0,0 +1,66 @@
+/**
+ * Conversation identity resolution — WP-479 E2 (client half).
+ *
+ * Feature-detects a stable per-conversation identifier so multiple concurrent harness
+ * conversations (Claude Code, Cursor, Codex, …) sharing one worktree don't collide on the single
+ * legacy `.productbrain/session.json` marker. All channels are optional and degrade gracefully —
+ * absent any signal, resolution returns `null` and every caller falls back to the pre-WP-479
+ * single-marker behavior (zero-config invariant).
+ *
+ * Priority order (harness findings: INS-2122, founder-run tests 2026-07-10):
+ *   1. explicit override (CLI `--conversation` flag on `pb session start`) — the manual seam.
+ *   2. `PB_CONVERSATION_ID` — the universal seam any harness adapter can set.
+ *   3. `CLAUDE_CODE_SESSION_ID` — present in Claude Code 2.1.206+ Bash shells (version-dependent,
+ *      treat as detected, never asserted).
+ *   4. `CURSOR_CONVERSATION_ID` — confirmed live in cursor-agent 2026.07.01 shell env.
+ *   5. `CODEX_TUI_SESSION_LOG_PATH` — Codex has no native conversation id; this Superset-injected
+ *      log path is unique per session run and stands in as the discriminator. It always contains
+ *      `/`, so normalization (below) always hashes it — no special-casing needed here.
+ *   6. none of the above → `null` (legacy shared-marker path).
+ */
+import { createHash } from 'crypto';
+/** Above this raw length, or containing any char outside the join-key-safe set, hash instead. */
+const MAX_RAW_LEN = 128;
+/** Join-key-safe charset — also what's safe to use as a marker filename with no traversal risk. */
+const SAFE_CHARS_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * Normalize a raw candidate conversation id into a value that is always safe to use as (a) a
+ * Convex join key and (b) a filesystem path segment. Never truncates (a `slice()` would collide
+ * two distinct long ids into one lineage) — oversized or unsafe-charset ids are replaced whole
+ * with their sha256 hex digest (fixed-width, charset-safe by construction).
+ */
+export function normalizeConversationId(raw) {
+    if (raw.length > MAX_RAW_LEN || !SAFE_CHARS_RE.test(raw)) {
+        return createHash('sha256').update(raw).digest('hex');
+    }
+    return raw;
+}
+/** Picks the first non-empty candidate in priority order. No normalization here. */
+function pickRawConversationId(explicitOverride) {
+    const candidates = [
+        explicitOverride,
+        process.env.PB_CONVERSATION_ID,
+        process.env.CLAUDE_CODE_SESSION_ID,
+        process.env.CURSOR_CONVERSATION_ID,
+        process.env.CODEX_TUI_SESSION_LOG_PATH,
+    ];
+    for (const candidate of candidates) {
+        if (candidate && candidate.trim().length > 0)
+            return candidate.trim();
+    }
+    return null;
+}
+/**
+ * Resolve the effective conversation id for the current process. `explicitOverride` — normally
+ * only threaded through from the CLI's `--conversation` flag on `pb session start` — takes
+ * priority over every env channel. Every other call site (the vast majority) calls this with no
+ * argument, which is pure env-based feature detection: with none of the channel env vars set,
+ * this returns `null` and callers must fall back to legacy behavior.
+ */
+export function resolveConversationId(explicitOverride) {
+    const raw = pickRawConversationId(explicitOverride);
+    if (!raw)
+        return null;
+    return normalizeConversationId(raw);
+}
+//# sourceMappingURL=conversation.js.map

package/dist/lib/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/lib/conversation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,iGAAiG;AACjG,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,mGAAmG;AACnG,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,IAAI,GAAG,CAAC,MAAM,GAAG,WAAW,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oFAAoF;AACpF,SAAS,qBAAqB,CAAC,gBAAgC;IAC7D,MAAM,UAAU,GAAG;QACjB,gBAAgB;QAChB,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAC9B,OAAO,CAAC,GAAG,CAAC,sBAAsB;QAClC,OAAO,CAAC,GAAG,CAAC,sBAAsB;QAClC,OAAO,CAAC,GAAG,CAAC,0BAA0B;KACvC,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,gBAAgC;IACpE,MAAM,GAAG,GAAG,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;IACpD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC"}

package/dist/lib/createEntryResult.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Narrowing helpers for the `chain.createEntry` gateway route's return type.
+ *
+ * WP-577 / TEN-2918: the route's declared return type is now an honest union that
+ * includes the preview branch (convex/agentKnowledge/entries.ts +
+ * createEntryPreview.ts). Callers that read real-create fields must narrow first.
+ *
+ * Why a local predicate rather than the server's own `isCreateEntryPreview`
+ * (convex/agentKnowledge/createEntryPreview.ts): `packages/cli` is a published npm
+ * package (bin `pb`) built with `rootDir: "src"` — a `convex/` import lives outside
+ * that root and would fail TypeScript's rootDir check (TS6059), and `convex/` is not
+ * part of the published tarball anyway. Keeping the CLI's own copy avoids that
+ * build-graph coupling. It is deliberately tiny and behaviour-free so the duplication
+ * cannot drift meaningfully — the discriminant is the presence of the `preview` key,
+ * which is part of the route's public response contract.
+ *
+ * Verified against the deployed preview: a real-create response carries no `preview`
+ * key at all, so this predicate is false on the normal capture path.
+ */
+import type { GatewayRouteReturnByName } from '@productbrain/kernel-client';
+export type CreateEntryRouteResult = GatewayRouteReturnByName<'chain.createEntry'>;
+export type CreateEntryPreviewRouteResult = Extract<CreateEntryRouteResult, {
+    preview: true;
+}>;
+/**
+ * True when the route returned its preview branch.
+ *
+ * A plain inline `'preview' in result` check does not reliably narrow the ELSE branch
+ * for this generated union shape — an explicit predicate function does. The same
+ * limitation is documented in convex/agentKnowledge/createEntryPreview.ts and was
+ * re-derived independently in packages/mcp-server/src/tools/smart-capture.ts.
+ */
+export declare function isPreviewCreateEntryResult(result: CreateEntryRouteResult): result is CreateEntryPreviewRouteResult;
+//# sourceMappingURL=createEntryResult.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createEntryResult.d.ts","sourceRoot":"","sources":["../../src/lib/createEntryResult.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAE5E,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;AAEnF,MAAM,MAAM,6BAA6B,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAE/F;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,sBAAsB,GAC7B,MAAM,IAAI,6BAA6B,CAEzC"}

package/dist/lib/createEntryResult.js

@@ -0,0 +1,12 @@
+/**
+ * True when the route returned its preview branch.
+ *
+ * A plain inline `'preview' in result` check does not reliably narrow the ELSE branch
+ * for this generated union shape — an explicit predicate function does. The same
+ * limitation is documented in convex/agentKnowledge/createEntryPreview.ts and was
+ * re-derived independently in packages/mcp-server/src/tools/smart-capture.ts.
+ */
+export function isPreviewCreateEntryResult(result) {
+    return 'preview' in result;
+}
+//# sourceMappingURL=createEntryResult.js.map

package/dist/lib/createEntryResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createEntryResult.js","sourceRoot":"","sources":["../../src/lib/createEntryResult.ts"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAA8B;IAE9B,OAAO,SAAS,IAAI,MAAM,CAAC;AAC7B,CAAC"}

package/dist/lib/errors.d.ts

@@ -18,13 +18,80 @@ export declare const ErrorCode: {
     readonly CONFIG_MISSING: "CONFIG_MISSING";
     readonly CONFIG_INVALID: "CONFIG_INVALID";
     readonly SESSION_REQUIRED: "SESSION_REQUIRED";
+    /** Session close blocked: uncommitted drafts remain (TEN-2370). Non-zero exit unless --force. */
+    readonly LOOP_UNFINISHED: "LOOP_UNFINISHED";
     readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** Kernel / MCP quality gate (e.g. verify-before-commit). */
+    readonly QUALITY_GATE_BLOCKED: "QUALITY_GATE_BLOCKED";
+    /**
+     * Grounding gate refused a draft→active promotion (WP-455 E3 / WP-475 E2):
+     * verify grounding or accept via the audited acceptEntry override.
+     */
+    readonly GROUNDING_GATE_BLOCKED: "GROUNDING_GATE_BLOCKED";
+    /**
+     * Semantic quality gate refused a draft→active promotion on a gated
+     * collection (WP-475 E4 / DEC-1345): fix the draft per the returned coaching
+     * (weakest criterion + question) — or, when the verdict was missing/stale,
+     * retry once the scheduled fresh judgment lands. No override route.
+     */
+    readonly SEMANTIC_QUALITY_GATE_BLOCKED: "SEMANTIC_QUALITY_GATE_BLOCKED";
+    /**
+     * `paginationOpts.cursor` handed to `chain.listAutoLinkSuggestions` was not issued by that
+     * exact (workspaceId, status) query — undecodable, or minted for a different status
+     * (WP-477 / FEAT-1350). Pass the previous page's `continueCursor` back verbatim, or `null`
+     * to restart. Never silently reset: a reset re-walks rows the drain already handled.
+     */
+    readonly CURSOR_QUERY_MISMATCH: "CURSOR_QUERY_MISMATCH";
+    /**
+     * Convex could not return a complete page of `autoLinkSuggestions` even after the server's
+     * bounded halve-and-retry (WP-477 / FEAT-1350). Retry with a smaller
+     * `paginationOpts.numItems`. Never downgraded to a silent short page — resuming from an
+     * incomplete page's cursor would SKIP rows.
+     */
+    readonly PAGE_SPLIT_REQUIRED: "PAGE_SPLIT_REQUIRED";
+    /**
+     * Convex's OWN argument validator rejected the call shape — a required arg missing,
+     * an unknown extra arg, or a wrong-typed arg (TEN-2647). Fix the offending argument
+     * named in the message; never retry an unchanged call. A 400, not an internal fault.
+     * Mirror of convex/lib/errors.ts ErrorCodes.ARGUMENT_VALIDATION_FAILED.
+     */
+    readonly ARGUMENT_VALIDATION_FAILED: "ARGUMENT_VALIDATION_FAILED";
+    /**
+     * commitEntry's server-side contradiction gate (WP-485 Slice 2a, entries.ts) blocked the
+     * commit. DEAD-BUT-TYPED while DEC-1321 keeps `graduated: false` — disposition can only be
+     * allow/advisory, never block (evaluate.ts:533) — so this never fires today. Typed now so a
+     * future policy graduation needs no CLI retrofit. Mirror of the server's thrown
+     * `ConvexError({ code: 'CONTRADICTION_BLOCKED' })` (entries.ts, batchCommitConstellation too).
+     */
+    readonly CONTRADICTION_BLOCKED: "CONTRADICTION_BLOCKED";
+    /**
+     * Agent-submitted product feedback is switched off for this workspace
+     * (WP-494 / TEN-2742): `pb feedback submit` hits this when
+     * `productFeedbackPolicy.agentSubmissions` is off. Not a bug — an admin or
+     * owner disabled it; the message names the setting and the re-enable path.
+     * Mirror of convex/lib/errors.ts ErrorCodes.AGENT_FEEDBACK_DISABLED.
+     */
+    readonly AGENT_FEEDBACK_DISABLED: "AGENT_FEEDBACK_DISABLED";
+    /**
+     * Per-key API quota exceeded (TEN-656). Mirror of convex/lib/errors.ts
+     * ErrorCodes.RATE_LIMITED. Retryable — the caller waits `retryAfterSeconds`
+     * (on McpError) then retries the same call unchanged.
+     */
+    readonly RATE_LIMITED: "rate-limited";
     readonly PROFILE_NOT_FOUND: "PROFILE_NOT_FOUND";
     readonly PROFILE_ALREADY_EXISTS: "PROFILE_ALREADY_EXISTS";
     readonly PROFILE_IS_ACTIVE: "PROFILE_IS_ACTIVE";
     readonly PROFILE_IS_LAST: "PROFILE_IS_LAST";
     readonly PROFILE_NAME_INVALID: "PROFILE_NAME_INVALID";
+    /**
+     * `pb connect` would overwrite an existing profile that holds DIFFERENT credentials
+     * (TEN-2851). Never a silent side-effect of a workspace-name slug collision — the caller
+     * must confirm interactively, or fails closed non-interactively with a named escape hatch
+     * (`PB_PROFILE=<other-name>`).
+     */
+    readonly PROFILE_CREDENTIALS_CONFLICT: "PROFILE_CREDENTIALS_CONFLICT";
     readonly NON_INTERACTIVE: "NON_INTERACTIVE";
+    readonly UPGRADE_FAILED: "UPGRADE_FAILED";
     readonly INTERNAL: "INTERNAL";
 };
 export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9G,sEAAsE;AACtE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;CAyBZ,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,aAAa,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IASH,uCAAuC;IACvC,MAAM,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAQ/E"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9G,sEAAsE;AACtE,eAAO,MAAM,SAAS;;;;;;;;;IAapB,iGAAiG;;;IAIjG,6DAA6D;;IAE7D;;;OAGG;;IAEH;;;;;OAKG;;IAEH;;;;;OAKG;;IAEH;;;;;OAKG;;IAEH;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;OAMG;;IAEH;;;;OAIG;;;;;;;IAQH;;;;;OAKG;;;;;CAOK,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,aAAa,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IASH,uCAAuC;IACvC,MAAM,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAQ/E"}