@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/lib/configResult.js

@@ -0,0 +1,189 @@
+/** Structured, non-throwing view of the CLI configuration cascade. */
+import { CONNECT_FIRST_STEP, DEFAULT_SITE_URL, connectPointer, isDevMode } from './constants.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { API_KEY_FORMAT_LINE, isApiKeyShaped } 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',
+    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 missingKeyResult();
+    if (!isApiKeyShaped(resolved.apiKey)) {
+        // `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',
+            profileName: resolved.profileName,
+            source: resolved.source,
+            reason: `Invalid API key format, from ${describeApiKeyOrigin(resolved.source, resolved.profileName)}. ${API_KEY_FORMAT_LINE}`,
+            guidance: fromEnv
+                ? `Unset PRODUCTBRAIN_API_KEY, or replace it with a valid 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',
+            profileName: resolved.profileName,
+            source: resolved.source,
+            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 };
+}
+/**
+ * TASK-562 (RULE-657): the one no-key next step. getConfigSafe reports it and getConfig /
+ * getConfigOrGuide throw it, so every surface says connect in the project folder, never paste a key.
+ */
+export function missingKeyResult() {
+    return {
+        ok: false,
+        kind: 'missing-key',
+        reason: 'No API key configured.',
+        guidance: `Run ${CONNECT_FIRST_STEP} in your project folder. ${connectPointer()}`,
+        nextCommand: CONNECT_FIRST_STEP,
+    };
+}
+export function missingKeyError() {
+    const { reason, guidance } = missingKeyResult();
+    return new CLIError(reason, { code: ErrorCode.AUTH_MISSING, category: 'auth', guidance });
+}
+//# 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/conflictResolution.d.ts

@@ -0,0 +1,37 @@
+/** The three ways an owner resolves a contradiction and the words the CLI and MCP print (TASK-1361, KR-7; RULE-664; signed DEC-2442,
+ *  DEC-2443). Generated copies go to both connectors; the door-only lines are DOOR_WORDS in conflictFlags.ts. */
+export declare const CONFLICT_RESOLUTIONS: readonly ["replaces", "refines", "unrelated"];
+export type ConflictResolution = (typeof CONFLICT_RESOLUTIONS)[number];
+export declare const isConflictResolution: (value: unknown) => value is ConflictResolution;
+/** The longest unrelated reason, one line. */
+export declare const CONFLICT_RESOLUTION_REASON_MAX = 200;
+/** A line Voice signed (DEC-2442, DEC-2443). The conflict doors refuse only with one of these, so a hand-written line does not compile. */
+export type SignedLine = string & {
+    readonly __signed: true;
+};
+export declare const signed: (line: string) => SignedLine;
+export declare const RESOLUTION_WORDS: {
+    readonly choose: SignedLine;
+    readonly both: SignedLine;
+    readonly reasonTooLong: SignedLine;
+    readonly target: "replaces or refines: the entry it replaces or refines, one of the two";
+    readonly reason: "For unrelated: one line on why (200 characters at most); for an amendment: why the answer changes";
+    readonly recorded: (choice: ConflictResolution) => string;
+    /** The list's header, one for the CLI and the MCP (DEC-2443): the open contradictions, then the closed ones beside them when `closed` is given.
+     *  A plus after a count means more exist than were read (RULE-17). */
+    readonly openHeader: (open: {
+        n: number;
+        more: boolean;
+    }, closed?: {
+        n: number;
+        more: boolean;
+    }) => string;
+    /** The list when nothing is open (all) or nothing is unanswered (the default list); the surface adds how to see the rest. */
+    readonly noneOpen: "No open contradictions.";
+    readonly noneUnanswered: "No unanswered contradictions.";
+    /** A stored answer as a person reads it: never the stored code. */
+    readonly answer: (answer: "real" | "false_alarm") => "real" | "false alarm";
+    /** The receipt for an answer given in the older form (real or noise), on the CLI and MCP alike. */
+    readonly answeredAs: (answer: "real" | "false_alarm") => "Answered as real: the contradiction stays open until an entry changes." | "Answered as a false alarm: the contradiction is closed.";
+};
+//# sourceMappingURL=conflictResolution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conflictResolution.d.ts","sourceRoot":"","sources":["../../src/lib/conflictResolution.ts"],"names":[],"mappings":"AAIA;iHACiH;AACjH,eAAO,MAAM,oBAAoB,+CAAgD,CAAC;AAClF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,kBAC0B,CAAC;AAE1F,8CAA8C;AAC9C,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,2IAA2I;AAC3I,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC;AAC9D,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,UAAgC,CAAC;AAEvE,eAAO,MAAM,gBAAgB;;;;;;gCAMT,kBAAkB;IACrC;0EACsE;gCACnD;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,WAAW;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE;IAEtF,6HAA6H;;;IAG7H,mEAAmE;8BAClD,MAAM,GAAG,aAAa;IACvC,mGAAmG;kCAC9E,MAAM,GAAG,aAAa;CAElC,CAAC"}

package/dist/lib/conflictResolution.js

@@ -0,0 +1,29 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/coherency/conflictResolution.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/** The three ways an owner resolves a contradiction and the words the CLI and MCP print (TASK-1361, KR-7; RULE-664; signed DEC-2442,
+ *  DEC-2443). Generated copies go to both connectors; the door-only lines are DOOR_WORDS in conflictFlags.ts. */
+export const CONFLICT_RESOLUTIONS = ['replaces', 'refines', 'unrelated'];
+export const isConflictResolution = (value) => typeof value === 'string' && CONFLICT_RESOLUTIONS.includes(value);
+/** The longest unrelated reason, one line. */
+export const CONFLICT_RESOLUTION_REASON_MAX = 200;
+export const signed = (line) => line;
+export const RESOLUTION_WORDS = {
+    choose: signed(`Choose ${CONFLICT_RESOLUTIONS.slice(0, -1).join(', ')} or ${CONFLICT_RESOLUTIONS[CONFLICT_RESOLUTIONS.length - 1]}.`),
+    both: signed('Give either the answer (real or false alarm) or the choice, not both.'),
+    reasonTooLong: signed(`Keep the reason to one line of ${CONFLICT_RESOLUTION_REASON_MAX} characters or fewer.`),
+    target: 'replaces or refines: the entry it replaces or refines, one of the two',
+    reason: `For unrelated: one line on why (${CONFLICT_RESOLUTION_REASON_MAX} characters at most); for an amendment: why the answer changes`,
+    recorded: (choice) => `Recorded: ${choice}.`,
+    /** The list's header, one for the CLI and the MCP (DEC-2443): the open contradictions, then the closed ones beside them when `closed` is given.
+     *  A plus after a count means more exist than were read (RULE-17). */
+    openHeader: (open, closed) => `Open contradictions (${open.n}${open.more ? '+' : ''})${closed ? `, ${closed.n}${closed.more ? '+' : ''} closed` : ''}`,
+    /** The list when nothing is open (all) or nothing is unanswered (the default list); the surface adds how to see the rest. */
+    noneOpen: 'No open contradictions.',
+    noneUnanswered: 'No unanswered contradictions.',
+    /** A stored answer as a person reads it: never the stored code. */
+    answer: (answer) => (answer === 'real' ? 'real' : 'false alarm'),
+    /** The receipt for an answer given in the older form (real or noise), on the CLI and MCP alike. */
+    answeredAs: (answer) => answer === 'real' ? 'Answered as real: the contradiction stays open until an entry changes.' : 'Answered as a false alarm: the contradiction is closed.',
+};
+//# sourceMappingURL=conflictResolution.js.map

package/dist/lib/conflictResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflictResolution.js","sourceRoot":"","sources":["../../src/lib/conflictResolution.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,gEAAgE;AAChE,uDAAuD;AAEvD;iHACiH;AACjH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,WAAW,CAAU,CAAC;AAGlF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAA+B,EAAE,CACnF,OAAO,KAAK,KAAK,QAAQ,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAE1F,8CAA8C;AAC9C,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAIlD,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAc,EAAE,CAAC,IAAkB,CAAC;AAEvE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC,UAAU,oBAAoB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,oBAAoB,CAAC,oBAAoB,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC;IACrI,IAAI,EAAE,MAAM,CAAC,uEAAuE,CAAC;IACrF,aAAa,EAAE,MAAM,CAAC,kCAAkC,8BAA8B,uBAAuB,CAAC;IAC9G,MAAM,EAAE,uEAAuE;IAC/E,MAAM,EAAE,mCAAmC,8BAA8B,gEAAgE;IACzI,QAAQ,EAAE,CAAC,MAA0B,EAAE,EAAE,CAAC,aAAa,MAAM,GAAG;IAChE;0EACsE;IACtE,UAAU,EAAE,CAAC,IAAkC,EAAE,MAAqC,EAAE,EAAE,CACzF,wBAAwB,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;IACzH,6HAA6H;IAC7H,QAAQ,EAAE,yBAAyB;IACnC,cAAc,EAAE,+BAA+B;IAC/C,mEAAmE;IACnE,MAAM,EAAE,CAAC,MAA8B,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC;IACxF,mGAAmG;IACnG,UAAU,EAAE,CAAC,MAA8B,EAAE,EAAE,CAC9C,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,wEAAwE,CAAC,CAAC,CAAC,yDAAyD;CAChJ,CAAC"}

package/dist/lib/connectKeyLabel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hand-kept, source convex/lib/connectRedeemDisplayName.ts: labels for API keys from `pb connect` (part of that file, so no
+ * generated copy; nothing checks it, TASK-1158). (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 @@
+/**
+ * Hand-kept, source convex/lib/connectRedeemDisplayName.ts: labels for API keys from `pb connect` (part of that file, so no
+ * generated copy; nothing checks it, TASK-1158). (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/connectProfileName.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The profile name `pb connect` gives a connection (TASK-638, DEC-1961): `<workspace>-<folder>`,
+ * so several folders on one machine can each hold their own key for one workspace:
+ * - the folder is the main clone's directory, read from the git common dir, so a Superset
+ *   worktree names the same profile as its main clone (DEC-1606 copies the pin across);
+ *   outside git it is the current directory;
+ * - a folder whose slug already is, or starts with, the workspace slug is the name on its own
+ *   (`product-brain` + `product-brain-positioning` → `product-brain-positioning`);
+ * - the name fits PROFILE_NAME_RE (32 chars): the folder part is cut first, then the workspace
+ *   part, and a `-N` clash suffix always fits.
+ */
+/** Lowercase, every run of other characters becomes one hyphen, no leading or trailing hyphen. */
+export declare function slugify(name: string): string;
+/**
+ * The folder a connect is named after: the directory holding the git common dir (the main
+ * clone, also from inside a worktree), or `cwd` itself outside git.
+ */
+export declare function connectFolderName(cwd: string): string;
+/** The name for clash attempt `n` (1 = no suffix, 2 → `-2`, …), always within 32 chars. */
+export declare function composeProfileName(workspaceName: string, folderName: string, n?: number): string;
+export interface ConnectProfileChoice {
+    profileName: string;
+    /** True when the name is this folder's own pin: the new key replaces it (a key rotation). */
+    replace: boolean;
+}
+/**
+ * Pick the profile a connect writes. This folder's own pin, if it is any of this folder's names,
+ * is replaced in place first; otherwise the first free `-N`. Never another folder's profile.
+ */
+export declare function pickConnectProfileName(args: {
+    workspaceName: string;
+    folderName: string;
+    ownPin: string | null;
+    isTaken: (profileName: string) => boolean;
+}): ConnectProfileChoice | null;
+//# sourceMappingURL=connectProfileName.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connectProfileName.d.ts","sourceRoot":"","sources":["../../src/lib/connectProfileName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,kGAAkG;AAClG,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYrD;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,MAAM,CAc3F;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C,GAAG,oBAAoB,GAAG,IAAI,CAK9B"}

package/dist/lib/connectProfileName.js

@@ -0,0 +1,72 @@
+/**
+ * The profile name `pb connect` gives a connection (TASK-638, DEC-1961): `<workspace>-<folder>`,
+ * so several folders on one machine can each hold their own key for one workspace:
+ * - the folder is the main clone's directory, read from the git common dir, so a Superset
+ *   worktree names the same profile as its main clone (DEC-1606 copies the pin across);
+ *   outside git it is the current directory;
+ * - a folder whose slug already is, or starts with, the workspace slug is the name on its own
+ *   (`product-brain` + `product-brain-positioning` → `product-brain-positioning`);
+ * - the name fits PROFILE_NAME_RE (32 chars): the folder part is cut first, then the workspace
+ *   part, and a `-N` clash suffix always fits.
+ */
+import { execFileSync } from 'node:child_process';
+import { basename, dirname } from 'node:path';
+const PROFILE_NAME_MAX = 32;
+/** The folder part keeps at least this many characters before the workspace part is cut. */
+const MIN_FOLDER_CHARS = 12;
+/** Bounded search for a free `-N`; a machine with 99 same-named folders is refused, not looped. */
+const MAX_CLASH_SUFFIX = 99;
+/** Lowercase, every run of other characters becomes one hyphen, no leading or trailing hyphen. */
+export function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function cut(slug, max) {
+    return slug.slice(0, max).replace(/-+$/, '');
+}
+/**
+ * The folder a connect is named after: the directory holding the git common dir (the main
+ * clone, also from inside a worktree), or `cwd` itself outside git.
+ */
+export function connectFolderName(cwd) {
+    try {
+        const commonDir = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return basename(dirname(commonDir));
+    }
+    catch {
+        // Not inside a git repository: the folder itself names the connection.
+        return basename(cwd);
+    }
+}
+/** The name for clash attempt `n` (1 = no suffix, 2 → `-2`, …), always within 32 chars. */
+export function composeProfileName(workspaceName, folderName, n = 1) {
+    const suffix = n === 1 ? '' : `-${n}`;
+    const budget = PROFILE_NAME_MAX - suffix.length;
+    const ws = slugify(workspaceName) || 'workspace';
+    const folder = slugify(folderName);
+    if (!folder)
+        return cut(ws, budget) + suffix;
+    if (folder === ws || folder.startsWith(`${ws}-`))
+        return cut(folder, budget) + suffix;
+    const over = ws.length + 1 + folder.length - budget;
+    if (over <= 0)
+        return `${ws}-${folder}${suffix}`;
+    const folderPart = cut(folder, Math.max(folder.length - over, Math.min(folder.length, MIN_FOLDER_CHARS)));
+    const wsPart = cut(ws, budget - 1 - folderPart.length);
+    return `${wsPart}-${folderPart}${suffix}`;
+}
+/**
+ * Pick the profile a connect writes. This folder's own pin, if it is any of this folder's names,
+ * is replaced in place first; otherwise the first free `-N`. Never another folder's profile.
+ */
+export function pickConnectProfileName(args) {
+    const names = Array.from({ length: MAX_CLASH_SUFFIX }, (_, i) => composeProfileName(args.workspaceName, args.folderName, i + 1));
+    if (args.ownPin && names.includes(args.ownPin))
+        return { profileName: args.ownPin, replace: true };
+    const free = names.find((name) => !args.isTaken(name));
+    return free ? { profileName: free, replace: false } : null;
+}
+//# sourceMappingURL=connectProfileName.js.map

package/dist/lib/connectProfileName.js.map

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

package/dist/lib/connectProfileName.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connectProfileName.test.d.ts.map

package/dist/lib/connectProfileName.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectProfileName.test.d.ts","sourceRoot":"","sources":["../../src/lib/connectProfileName.test.ts"],"names":[],"mappings":""}

package/dist/lib/connectProfileName.test.js

@@ -0,0 +1,100 @@
+/**
+ * The pb connect profile-name rule (TASK-638 doneWhen 1, DEC-1961).
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { composeProfileName, connectFolderName, pickConnectProfileName } from './connectProfileName.js';
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+// TEN-3088: a git hook's GIT_* env would point git at the real repo — stripped for the fixture
+// spawns here and, in beforeAll, for connectFolderName's own git call.
+const GIT_FIXTURE_ENV = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+describe('composeProfileName', () => {
+    it('joins workspace and folder: product-brain + Product-OS -> product-brain-product-os', () => {
+        expect(composeProfileName('Product Brain', 'Product-OS')).toBe('product-brain-product-os');
+    });
+    it('a folder already named after the workspace stands alone: product-brain-positioning', () => {
+        expect(composeProfileName('Product Brain', 'product-brain-positioning')).toBe('product-brain-positioning');
+        expect(composeProfileName('Product Brain', 'Product Brain')).toBe('product-brain');
+    });
+    it('a mere prefix is not a match: product-brainy -> product-brain-product-brainy', () => {
+        expect(composeProfileName('Product Brain', 'product-brainy')).toBe('product-brain-product-brainy');
+    });
+    it('a 40-char workspace and a 40-char folder give a valid 32-char name', () => {
+        const name = composeProfileName('w'.repeat(40), 'f'.repeat(40));
+        expect(name).toHaveLength(32);
+        expect(name).toMatch(PROFILE_NAME_RE);
+        expect(name).toBe(`${'w'.repeat(19)}-${'f'.repeat(12)}`);
+    });
+    it('a clash suffix always fits the 32-char cap', () => {
+        const name = composeProfileName('w'.repeat(40), 'f'.repeat(40), 17);
+        expect(name).toMatch(PROFILE_NAME_RE);
+        expect(name.endsWith('-17')).toBe(true);
+    });
+    it('never ends a cut part on a hyphen', () => {
+        const name = composeProfileName('a'.repeat(18) + ' b', 'c'.repeat(11) + ' ' + 'd'.repeat(30));
+        expect(name).not.toMatch(/--|-$/);
+    });
+});
+describe('pickConnectProfileName', () => {
+    const base = { workspaceName: 'Product Brain', folderName: 'Product-OS' };
+    it('a free name is created', () => {
+        expect(pickConnectProfileName({ ...base, ownPin: null, isTaken: () => false }))
+            .toEqual({ profileName: 'product-brain-product-os', replace: false });
+    });
+    it("another folder's profile holds the name -> the next free -2", () => {
+        const taken = new Set(['product-brain-product-os']);
+        expect(pickConnectProfileName({ ...base, ownPin: null, isTaken: (n) => taken.has(n) }))
+            .toEqual({ profileName: 'product-brain-product-os-2', replace: false });
+    });
+    it("this clone's own pin names the profile -> replaced in place", () => {
+        expect(pickConnectProfileName({ ...base, ownPin: 'product-brain-product-os', isTaken: () => true }))
+            .toEqual({ profileName: 'product-brain-product-os', replace: true });
+    });
+    it("this clone's own pin on a -2 is replaced even when the base name is free again", () => {
+        const taken = new Set(['product-brain-product-os-2']);
+        expect(pickConnectProfileName({ ...base, ownPin: 'product-brain-product-os-2', isTaken: (n) => taken.has(n) }))
+            .toEqual({ profileName: 'product-brain-product-os-2', replace: true });
+    });
+    it('a pin naming some other profile is never renamed or reused: the folder still gets its own name', () => {
+        expect(pickConnectProfileName({ ...base, ownPin: 'product-brain', isTaken: (n) => n === 'product-brain' }))
+            .toEqual({ profileName: 'product-brain-product-os', replace: false });
+    });
+    it('the clash search is bounded', () => {
+        expect(pickConnectProfileName({ ...base, ownPin: null, isTaken: () => true })).toBeNull();
+    });
+});
+describe('connectFolderName', () => {
+    let root = '';
+    beforeAll(() => {
+        for (const key of Object.keys(process.env))
+            if (key.startsWith('GIT_'))
+                delete process.env[key];
+        root = realpathSync(mkdtempSync(join(tmpdir(), 'pb-connect-name-')));
+    });
+    afterAll(() => rmSync(root, { recursive: true, force: true }));
+    function git(cwd, ...args) {
+        execFileSync('git', ['-c', 'user.email=t@example.com', '-c', 'user.name=t', ...args], { cwd, stdio: 'ignore', env: GIT_FIXTURE_ENV });
+    }
+    it('from a worktree -> the main clone folder name', () => {
+        const main = join(root, 'Main-Clone');
+        mkdirSync(main);
+        git(main, 'init', '-q');
+        writeFileSync(join(main, 'README'), 'x');
+        git(main, 'add', 'README');
+        git(main, 'commit', '-q', '-m', 'init');
+        git(main, 'worktree', 'add', '-q', '-b', 'side', join(root, 'some-worktree'));
+        expect(connectFolderName(main)).toBe('Main-Clone');
+        expect(connectFolderName(join(root, 'some-worktree'))).toBe('Main-Clone');
+        mkdirSync(join(main, 'sub'));
+        expect(connectFolderName(join(main, 'sub'))).toBe('Main-Clone');
+    });
+    it('outside git -> the current folder name', () => {
+        const plain = join(root, 'plain-folder');
+        mkdirSync(plain);
+        expect(connectFolderName(plain)).toBe('plain-folder');
+    });
+});
+//# sourceMappingURL=connectProfileName.test.js.map

package/dist/lib/connectProfileName.test.js.map

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

package/dist/lib/constants.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CLI constants — single source of truth for URLs and environment switching.
+ * WP-301 Slice 0: Extract hardcoded URLs, add PB_ENV awareness.
+ */
+/** Production Convex HTTP Actions endpoint. */
+export declare const DEFAULT_SITE_URL = "https://gateway.productbrain.io";
+/** Where every published pb release is listed, printed once after an upgrade (TEN-4860). No
+ *  changelog exists yet and the repository is private, so this is the public npm versions page. */
+export declare const CLI_RELEASES_URL = "https://www.npmjs.com/package/@productbrain/cli?activeTab=versions";
+/**
+ * Resolve the Convex site URL based on PB_ENV.
+ * - PB_ENV=dev → DEV_SITE_URL (localhost — see caveat on DEV_SITE_URL)
+ * - PB_ENV=production or unset → production URL
+ *
+ * NOTE: No production CLI command currently imports this function.
+ * For HTTP Actions (connect, etc.), use CONVEX_SITE_URL or DEFAULT_SITE_URL.
+ */
+export declare function resolveSiteUrl(): string;
+/**
+ * Gateway URL for `pb connect` token redemption (`POST …/auth/redeem-connect-token`).
+ *
+ * Resolution order:
+ * 1. `cliGateway` argument (from `pb connect --gateway <url>`)
+ * 2. `PB_CONNECT_GATEWAY_URL` env var
+ * 3. `CONVEX_SITE_URL` env var — the actual Convex HTTP Actions deployment
+ * 4. `DEFAULT_SITE_URL` (production gateway)
+ *
+ * Convex HTTP Actions are cloud-hosted even during local development
+ * (`npx convex dev` syncs to cloud, not localhost). Tokens minted by
+ * any web app (production or localhost) live in the cloud Convex DB,
+ * so redeem must target the cloud deployment — never localhost.
+ *
+ * For dev deployments: set CONVEX_SITE_URL to your *.convex.site URL
+ * or use --gateway.
+ */
+export declare function resolveConnectRedeemUrl(cliGateway?: string): string;
+/**
+ * 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 declare function resolveAppUrl(): string;
+/** TASK-562 (TEN-1923): every no-key first step names connect in the project folder, never a key paste. */
+export declare const CONNECT_FIRST_STEP = "pb connect <token>";
+/** Where a person without a key gets a connect command: the app page that mints one (RULE-662). */
+export declare function connectPointer(): string;
+/** Whether the CLI is running in dev mode. */
+export declare function isDevMode(): boolean;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +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;AAElE;mGACmG;AACnG,eAAO,MAAM,gBAAgB,uEAAuE,CAAC;AAiBrG;;;;;;;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,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,mGAAmG;AACnG,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,IAAI,OAAO,CAEnC"}