@productbrain/cli 0.1.0-beta.5 → 0.1.0-beta.5060

package/dist/lib/adminConfig.js

@@ -0,0 +1,130 @@
+/**
+ * WP-681 (WP-679) — resolveAdminConfig(), split out of config.ts (STD-2/DEC-1504: config.ts is
+ * grandfathered over the 500-LOC budget, so a growing responsibility moves to a leaf module
+ * rather than widening the baseline). NOT re-exported from config.ts: this module imports FROM
+ * config.ts (readLocalProjectConfig, HOME_ENV_PATH), so a re-export back would be a circular
+ * import (dependency-cruiser's no-circular rule). Every caller imports `resolveAdminConfig`
+ * directly from here.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { DEFAULT_SITE_URL, isDevMode } from './constants.js';
+import { API_KEY_PREFIX } from './tokenConstants.js';
+import { resolveProfileConfig } from './profiles.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { HOME_ENV_PATH, readLocalProjectConfig } from './config.js';
+import { refuseWhenProjectHasNoTenant, resolvePinnedProfile } from './localBinding.js';
+/** Parse env file content and return key-value pairs (without mutating process.env). Mirrors
+ *  config.ts's private helper of the same shape — kept local rather than shared to avoid
+ *  widening config.ts's export surface for an 8-line pure function. */
+function parseEnvVars(content) {
+    const vars = {};
+    for (const line of content.split('\n')) {
+        const m = line.match(/^([^#=]+)=(.*)$/);
+        if (m) {
+            vars[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+        }
+    }
+    return vars;
+}
+/**
+ * Resolve config for admin operations — profile-only resolution.
+ *
+ * Admin commands (pb admin ...) must NOT read .productbrain/config.json's `siteUrl` (the
+ * COMMITTED, repo-wide gateway override) or CWD env files — a shared repo file silently
+ * redirecting every admin call, for every operator who checks it out, is exactly the
+ * wrong-gateway risk TEN-1334 named. That risk does NOT apply to `config.local.json`'s
+ * `profile` field: it is gitignored, machine-local, and only ever set by an explicit
+ * `pb profile use --local` (or a hand-edit) — a deliberate per-repo pin, not something that
+ * ships with the repo. WP-681 (live-reproduced): without honoring that pin, `pb admin run`
+ * silently fell back to the operator's GLOBAL active profile — which defaults to production —
+ * even from inside a repo explicitly pinned to a dev-scoped profile, so a dev-only workspace id
+ * got sent to prod and produced an opaque `ArgumentValidationError` (the id happened to decode
+ * to an unrelated table there) instead of an actionable "wrong deployment" signal.
+ *
+ * Resolution order:
+ * 1. Shell env vars (PRODUCTBRAIN_API_KEY / CONVEX_SITE_URL) — always win
+ * 2. Repo-local profile pin (.productbrain/config.local.json `profile` field only — never
+ *    that file's preview-binding keys, which are for `resolveConfig()`'s non-admin path)
+ * 2b. Declared project that names no tenant at all — refuses, so step 3 cannot substitute a
+ *    workspace the repo never asked for. A preview binding still counts as a named tenant here
+ *    even though step 2 does not CONSUME it, otherwise a preview-bound worktree reads as unpinned.
+ * 3. Global active named profile (~/.config/productbrain/profiles/{name}.env)
+ * 4. Legacy home config (~/.config/productbrain/.env)
+ * 5. DEFAULT_SITE_URL as fallback for siteUrl
+ *
+ * Throws CLIError with AUTH_MISSING if no API key is found. A dangling repo-local
+ * pin throws ConfigResolutionError (kind: profile-pin) from the shared helper.
+ * A declared project with no pin throws kind missing-pin from the same module.
+ */
+export function resolveAdminConfig() {
+    let apiKey;
+    let rawSiteUrl;
+    let source = 'env';
+    let profileName = null;
+    // 1. Shell env vars — always highest priority
+    const envKey = process.env.PRODUCTBRAIN_API_KEY;
+    if (envKey?.startsWith(API_KEY_PREFIX)) {
+        apiKey = envKey;
+        rawSiteUrl = process.env.CONVEX_SITE_URL;
+        source = 'env';
+    }
+    // 2. Repo-local profile pin — deliberate, gitignored, machine-local; never config.json's
+    // siteUrl and never CWD .env files (those stay excluded per the module docstring above).
+    // The pin step is the shared helper so admin cannot drift on the validity bar again (TEN-3239).
+    if (!apiKey) {
+        const localProfile = readLocalProjectConfig()?.profile;
+        if (localProfile) {
+            const pinned = resolvePinnedProfile(localProfile);
+            apiKey = pinned.apiKey;
+            rawSiteUrl = pinned.siteUrl;
+            source = 'local-profile';
+            profileName = localProfile;
+        }
+    }
+    // 2b. Declared project with no tenant — refuse before the global profile can be substituted.
+    // Detects config.json's existence only; never consumes its siteUrl (TEN-1334).
+    if (!apiKey) {
+        refuseWhenProjectHasNoTenant();
+    }
+    // 3. Global active profile (no project config, no CWD files). Reports the profile NAME that
+    // resolveProfileConfig() itself resolved (review fix, P2) — NEVER a separate
+    // getGlobalActiveProfile() lookup, which only reflects the active-profile FILE and can
+    // disagree with what actually supplied the credential (a PB_PROFILE override at its step 1,
+    // or a fallback past a missing/invalid active profile to its step 3 "default").
+    if (!apiKey) {
+        const profileConfig = resolveProfileConfig();
+        if (profileConfig?.apiKey?.startsWith(API_KEY_PREFIX)) {
+            apiKey = profileConfig.apiKey;
+            rawSiteUrl = profileConfig.siteUrl;
+            source = 'global-profile';
+            profileName = profileConfig.profileName;
+        }
+    }
+    // 4. Legacy ~/.config/productbrain/.env
+    if (!apiKey && existsSync(HOME_ENV_PATH)) {
+        const vars = parseEnvVars(readFileSync(HOME_ENV_PATH, 'utf8'));
+        if (vars['PRODUCTBRAIN_API_KEY']?.startsWith(API_KEY_PREFIX)) {
+            apiKey = vars['PRODUCTBRAIN_API_KEY'];
+            rawSiteUrl = vars['CONVEX_SITE_URL'];
+            source = 'legacy';
+        }
+    }
+    if (!apiKey) {
+        throw new CLIError('No API key found. Run pb login or set PRODUCTBRAIN_API_KEY.', {
+            code: ErrorCode.AUTH_MISSING,
+            category: 'auth',
+            guidance: 'Run `pb login` to set your API key.',
+        });
+    }
+    const siteUrl = (rawSiteUrl || DEFAULT_SITE_URL).replace(/\/$/, '');
+    const allowHttp = isDevMode() && siteUrl.startsWith('http://localhost');
+    if (!siteUrl.startsWith('https://') && !allowHttp) {
+        throw new CLIError(`CONVEX_SITE_URL must use HTTPS for admin operations (got "${siteUrl.slice(0, 30)}…").`, {
+            code: ErrorCode.CONFIG_INVALID,
+            category: 'config',
+            guidance: 'Set CONVEX_SITE_URL to an https:// URL.',
+        });
+    }
+    return { apiKey, siteUrl, source, profileName };
+}
+//# sourceMappingURL=adminConfig.js.map

package/dist/lib/adminConfig.js.map

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

package/dist/lib/canonicalRefs.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Synced from convex/lib/canonicalRefs.ts (WP-345: canonical refs, NG4: CLI import boundary).
+ * GENERATED by scripts/generate-canonical-refs-copies.mjs — DO NOT EDIT BY HAND.
+ * Run `npm run refs:sync` to regenerate after editing the source.
+ */
+/**
+ * Canonical Refs — pure parser for semantic ref syntax.
+ *
+ * WP-640 S2 (TASK-63): THIS FILE IS THE SINGLE SOURCE. `packages/cli/src/lib/canonicalRefs.ts`
+ * and `packages/mcp-server/src/lib/canonicalRefs.ts` are GENERATED mirrors (scripts/generate-
+ * canonical-refs-copies.mjs) — never hand-edit them. Edit here, then `npm run refs:sync` (writes
+ * both copies) and `npm run refs:sync:check` to verify (no drift). Folding all three into a real
+ * shared package (e.g. `kernel`, which already declares "ZERO Convex imports" and is already a
+ * `cli` devDependency) was considered and DECLINED: `scripts/check-mcp-boundaries.mjs` (BR-25,
+ * TEN-174) unconditionally fails any `packages/mcp-server/src` file importing from outside the
+ * package — a live `kernel` import there is structurally blocked, not just risky — and a new
+ * kernel/ folder also needs a WP-537 kind-manifest row. This generate+check pair reuses the SAME
+ * "copy-free at the source-editing level, physically-copied at the build level" pattern
+ * `scripts/generate-mcp-embedded-copies.mjs` already established for flags_core.ts/logo-markup.ts
+ * for exactly this MCP-boundary reason — not a new mechanism, the established one. It collapses
+ * the "3 independently hand-copy-pasted files" problem the doneWhen names (a human previously had
+ * to remember to edit three files identically) down to ONE edited source with caught drift. NG4
+ * (WP-345) is UNCHANGED: CLI/MCP still must not import the resolver (convex/canonicalRefs.ts, no
+ * `lib/`) — only this pure parser.
+ *
+ * Zero Convex imports. This file is drift-synced to:
+ *   - packages/cli/src/lib/canonicalRefs.ts (CLI copy — identical logic)
+ *   - packages/mcp-server/src/lib/canonicalRefs.ts (MCP copy — identical logic)
+ *
+ * NG4 (WP-345): CLI/MCP MUST NOT import the resolver (convex/canonicalRefs.ts).
+ * They import only this pure parser module.
+ *
+ * DEC-A/WP-354: semantic refs syntax is {{ref:canonicalKey}},
+ * {{ref:canonicalKey:display}}, {{ref:domain:data/analytics}}, or
+ * {{ref:entry:DEC-123}}.
+ * Chain: WP-345 E4, DEC-K (projection hash trailer)
+ *
+ * WP-436 S1 — Axis 2 vocabulary resolver (DEC-1021, STD-253):
+ * {{vocab:<canonicalKey>.<form>}} tokens + getCollectionLabel resolver.
+ * PAT-230: resolver is pure — no Convex import, workspace context passed as arg.
+ */
+/**
+ * WP-354 Build-Order #6: Setup-ref resolver return shape.
+ *
+ * All consumers (CLI, MCP, handshake, editor health) must read
+ * the discriminated kind+status fields instead of an optional resolved object.
+ *
+ * Spec: docs/system/design/authority-domains-design-spec.md §632
+ * Chain: WP-354 Slice H, STD-101 (single source of truth)
+ *
+ * drift-synced to:
+ *   - packages/cli/src/lib/canonicalRefs.ts
+ *   - packages/mcp-server/src/lib/canonicalRefs.ts
+ */
+export type SetupRefResolution = {
+    ref: string;
+    kind: 'entry' | 'domain' | 'seed' | 'unknown';
+    status: 'resolved' | 'unresolved' | 'unsupported-future' | 'invalid';
+    /** Human-readable entryId (e.g. 'BR-5'). Only when status='resolved' for kind='entry' or 'domain'. */
+    localEntryId?: string;
+    /** Domain slug (e.g. 'engineering/backend'). Only when kind='domain' and status='resolved'. */
+    canonicalSlug?: string;
+    /** true when kind is 'entry' or 'domain'; false for seed/unknown */
+    required: boolean;
+    message?: string;
+    action?: string;
+};
+/**
+ * Extracts canonical keys from a body string.
+ * Handles {{ref:key}} and {{ref:key:display}}.
+ *
+ * Returns deduplicated array of canonical keys in order of first appearance.
+ */
+export declare function parseSemanticRefs(body: string): string[];
+/**
+ * Renders a resolved ref for display in projected output.
+ * Falls back to the raw key wrapped in brackets if no resolved name is available.
+ *
+ * Examples:
+ *   renderSemanticRef(bet, 'Active Bets')  → 'Active Bets'
+ *   renderSemanticRef(bet)                 → '[bet]'
+ *   renderSemanticRef(bet, undefined)      → '[bet]'
+ */
+export declare function renderSemanticRef(key: string, resolvedName?: string): string;
+/**
+ * Replaces all semantic refs in a body string with their resolved display names.
+ *
+ * resolvedMap: Map<canonicalKey, resolvedName> — keys not in the map are rendered
+ * as [unresolved: key] to make missing refs visible.
+ */
+export declare function replaceSemanticRefs(body: string, resolvedMap: Map<string, string>): string;
+/**
+ * Label set for a single canonical type (Axis 2, DEC-1021).
+ * All fields optional — undefined means "derive from next layer".
+ */
+export type LabelSet = {
+    singular?: string;
+    plural?: string;
+    verb_start?: string;
+    verb_commit?: string;
+    verb_review?: string;
+    verb_complete?: string;
+    verb_archive?: string;
+};
+/** Valid form names for a LabelSet. */
+export type LabelForm = keyof LabelSet;
+/**
+ * Minimal workspace context for Axis 2 resolution.
+ * Passed by the caller — keeps the resolver pure (PAT-230).
+ */
+export type WorkspaceVocabCtx = {
+    /** Per-workspace overrides: canonicalKey → LabelSet (partial). */
+    collectionLabels?: Record<string, LabelSet | undefined>;
+    /**
+     * Layer 2 defaults from system_collection_definitions.labels, keyed by canonicalKey.
+     * Fetched via chain.getVocabulary collectionDefaults and threaded through by the caller.
+     * Used as fallback when no workspace override exists and collectionCtx is not passed.
+     * WP-436 completion — wires dead Layer 2 to consumers.
+     */
+    collectionDefaults?: Record<string, LabelSet | undefined>;
+};
+/**
+ * Minimal collection context for Axis 2 resolution.
+ * Passed by the caller — keeps the resolver pure (PAT-230).
+ */
+export type CollectionVocabCtx = {
+    /** Collection-level default labels (from system_collection_definitions.labels). */
+    labels?: LabelSet;
+};
+/**
+ * Regex for matching vocab tokens: {{vocab:<canonicalKey>.<form>}}
+ * STD-253: canonicalKey + form are both lowercase snake_case.
+ * Captures: [1] canonicalKey, [2] form.
+ */
+export declare const VOCAB_TOKEN_REGEX: RegExp;
+/**
+ * Resolve the display label for a canonical type + form.
+ *
+ * Resolution chain (DEC-1021):
+ *   1. workspaceCtx.collectionLabels[canonicalKey][form]  — workspace override
+ *   2. collectionCtx.labels[form]                         — collection default
+ *   3. canonicalKey literal                               — fallback (no throw)
+ *
+ * Pure function. No Convex imports. No side effects. (PAT-230)
+ *
+ * @param canonicalKey - e.g. 'work_package', 'decision'
+ * @param form - e.g. 'singular', 'plural', 'verb_start'
+ * @param workspaceCtx - optional workspace-level override context
+ * @param collectionCtx - optional collection-level default context
+ * @returns resolved label string
+ */
+export declare function getCollectionLabel(canonicalKey: string, form: string, workspaceCtx?: WorkspaceVocabCtx, collectionCtx?: CollectionVocabCtx): string;
+/**
+ * Replace all {{vocab:<canonicalKey>.<form>}} tokens in a string.
+ *
+ * For each token, calls getCollectionLabel with the provided contexts.
+ * STD-253.
+ */
+export declare function replaceVocabTokens(body: string, workspaceCtx?: WorkspaceVocabCtx, collectionCtxMap?: Map<string, CollectionVocabCtx>): string;
+//# sourceMappingURL=canonicalRefs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalRefs.d.ts","sourceRoot":"","sources":["../../src/lib/canonicalRefs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,MAAM,EACH,UAAU,GACV,YAAY,GACZ,oBAAoB,GACpB,SAAS,CACV;IACF,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAOF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAmBxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAgB1F;AAOD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,uCAAuC;AACvC,MAAM,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC/B,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IACxD;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;CAC1D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,mFAAmF;IACnF,MAAM,CAAC,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAwC,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CACjC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,iBAAiB,EAChC,aAAa,CAAC,EAAE,kBAAkB,GAChC,MAAM,CAyBR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,iBAAiB,EAChC,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAChD,MAAM,CASR"}

package/dist/lib/canonicalRefs.js

@@ -0,0 +1,169 @@
+/**
+ * Synced from convex/lib/canonicalRefs.ts (WP-345: canonical refs, NG4: CLI import boundary).
+ * GENERATED by scripts/generate-canonical-refs-copies.mjs — DO NOT EDIT BY HAND.
+ * Run `npm run refs:sync` to regenerate after editing the source.
+ */
+/**
+ * Canonical Refs — pure parser for semantic ref syntax.
+ *
+ * WP-640 S2 (TASK-63): THIS FILE IS THE SINGLE SOURCE. `packages/cli/src/lib/canonicalRefs.ts`
+ * and `packages/mcp-server/src/lib/canonicalRefs.ts` are GENERATED mirrors (scripts/generate-
+ * canonical-refs-copies.mjs) — never hand-edit them. Edit here, then `npm run refs:sync` (writes
+ * both copies) and `npm run refs:sync:check` to verify (no drift). Folding all three into a real
+ * shared package (e.g. `kernel`, which already declares "ZERO Convex imports" and is already a
+ * `cli` devDependency) was considered and DECLINED: `scripts/check-mcp-boundaries.mjs` (BR-25,
+ * TEN-174) unconditionally fails any `packages/mcp-server/src` file importing from outside the
+ * package — a live `kernel` import there is structurally blocked, not just risky — and a new
+ * kernel/ folder also needs a WP-537 kind-manifest row. This generate+check pair reuses the SAME
+ * "copy-free at the source-editing level, physically-copied at the build level" pattern
+ * `scripts/generate-mcp-embedded-copies.mjs` already established for flags_core.ts/logo-markup.ts
+ * for exactly this MCP-boundary reason — not a new mechanism, the established one. It collapses
+ * the "3 independently hand-copy-pasted files" problem the doneWhen names (a human previously had
+ * to remember to edit three files identically) down to ONE edited source with caught drift. NG4
+ * (WP-345) is UNCHANGED: CLI/MCP still must not import the resolver (convex/canonicalRefs.ts, no
+ * `lib/`) — only this pure parser.
+ *
+ * Zero Convex imports. This file is drift-synced to:
+ *   - packages/cli/src/lib/canonicalRefs.ts (CLI copy — identical logic)
+ *   - packages/mcp-server/src/lib/canonicalRefs.ts (MCP copy — identical logic)
+ *
+ * NG4 (WP-345): CLI/MCP MUST NOT import the resolver (convex/canonicalRefs.ts).
+ * They import only this pure parser module.
+ *
+ * DEC-A/WP-354: semantic refs syntax is {{ref:canonicalKey}},
+ * {{ref:canonicalKey:display}}, {{ref:domain:data/analytics}}, or
+ * {{ref:entry:DEC-123}}.
+ * Chain: WP-345 E4, DEC-K (projection hash trailer)
+ *
+ * WP-436 S1 — Axis 2 vocabulary resolver (DEC-1021, STD-253):
+ * {{vocab:<canonicalKey>.<form>}} tokens + getCollectionLabel resolver.
+ * PAT-230: resolver is pure — no Convex import, workspace context passed as arg.
+ */
+/**
+ * Regex for matching semantic refs. Captures: [1] ref key/path, [2] optional display label.
+ */
+const SEMANTIC_REF_REGEX = /\{\{ref:([a-zA-Z0-9_./-]+(?::[a-zA-Z0-9_./-]+)?)(?::([^}]+))?\}\}/g;
+/**
+ * Extracts canonical keys from a body string.
+ * Handles {{ref:key}} and {{ref:key:display}}.
+ *
+ * Returns deduplicated array of canonical keys in order of first appearance.
+ */
+export function parseSemanticRefs(body) {
+    if (!body || body.length === 0)
+        return [];
+    const keys = [];
+    const seen = new Set();
+    // Reset lastIndex for global regex before each use
+    const regex = new RegExp(SEMANTIC_REF_REGEX.source, 'g');
+    let match;
+    while ((match = regex.exec(body)) !== null) {
+        const key = match[1];
+        if (key && !seen.has(key)) {
+            seen.add(key);
+            keys.push(key);
+        }
+    }
+    return keys;
+}
+/**
+ * Renders a resolved ref for display in projected output.
+ * Falls back to the raw key wrapped in brackets if no resolved name is available.
+ *
+ * Examples:
+ *   renderSemanticRef(bet, 'Active Bets')  → 'Active Bets'
+ *   renderSemanticRef(bet)                 → '[bet]'
+ *   renderSemanticRef(bet, undefined)      → '[bet]'
+ */
+export function renderSemanticRef(key, resolvedName) {
+    if (resolvedName && resolvedName.trim().length > 0) {
+        return resolvedName.trim();
+    }
+    return `[${key}]`;
+}
+/**
+ * Replaces all semantic refs in a body string with their resolved display names.
+ *
+ * resolvedMap: Map<canonicalKey, resolvedName> — keys not in the map are rendered
+ * as [unresolved: key] to make missing refs visible.
+ */
+export function replaceSemanticRefs(body, resolvedMap) {
+    if (!body || body.length === 0)
+        return body;
+    const regex = new RegExp(SEMANTIC_REF_REGEX.source, 'g');
+    return body.replace(regex, (_match, key, displayLabel) => {
+        // If an inline display label is provided, it takes precedence over the resolved name
+        if (displayLabel && displayLabel.trim().length > 0) {
+            return displayLabel.trim();
+        }
+        const resolved = resolvedMap.get(key);
+        if (resolved) {
+            return resolved;
+        }
+        return `[unresolved: ${key}]`;
+    });
+}
+/**
+ * Regex for matching vocab tokens: {{vocab:<canonicalKey>.<form>}}
+ * STD-253: canonicalKey + form are both lowercase snake_case.
+ * Captures: [1] canonicalKey, [2] form.
+ */
+export const VOCAB_TOKEN_REGEX = /\{\{vocab:([a-z_]+)\.([a-z_]+)\}\}/g;
+/**
+ * Resolve the display label for a canonical type + form.
+ *
+ * Resolution chain (DEC-1021):
+ *   1. workspaceCtx.collectionLabels[canonicalKey][form]  — workspace override
+ *   2. collectionCtx.labels[form]                         — collection default
+ *   3. canonicalKey literal                               — fallback (no throw)
+ *
+ * Pure function. No Convex imports. No side effects. (PAT-230)
+ *
+ * @param canonicalKey - e.g. 'work_package', 'decision'
+ * @param form - e.g. 'singular', 'plural', 'verb_start'
+ * @param workspaceCtx - optional workspace-level override context
+ * @param collectionCtx - optional collection-level default context
+ * @returns resolved label string
+ */
+export function getCollectionLabel(canonicalKey, form, workspaceCtx, collectionCtx) {
+    // Layer 1: workspace override
+    const wsLabels = workspaceCtx?.collectionLabels?.[canonicalKey];
+    if (wsLabels) {
+        const wsVal = wsLabels[form];
+        if (wsVal !== undefined && wsVal.length > 0)
+            return wsVal;
+    }
+    // Layer 2: explicit collection ctx (granular call sites — handshake projector)
+    const colLabels = collectionCtx?.labels;
+    if (colLabels) {
+        const colVal = colLabels[form];
+        if (colVal !== undefined && colVal.length > 0)
+            return colVal;
+    }
+    // Layer 2.5: collection defaults from WorkspaceVocabCtx (threaded via chain.getVocabulary)
+    // New: wires the dead Layer 2 path for consumers that don't pass explicit collectionCtx.
+    const defaultLabels = workspaceCtx?.collectionDefaults?.[canonicalKey];
+    if (defaultLabels) {
+        const defVal = defaultLabels[form];
+        if (defVal !== undefined && defVal.length > 0)
+            return defVal;
+    }
+    // Layer 3: canonicalKey literal fallback
+    return canonicalKey;
+}
+/**
+ * Replace all {{vocab:<canonicalKey>.<form>}} tokens in a string.
+ *
+ * For each token, calls getCollectionLabel with the provided contexts.
+ * STD-253.
+ */
+export function replaceVocabTokens(body, workspaceCtx, collectionCtxMap) {
+    if (!body || body.length === 0)
+        return body;
+    const regex = new RegExp(VOCAB_TOKEN_REGEX.source, 'g');
+    return body.replace(regex, (_match, canonicalKey, form) => {
+        const collectionCtx = collectionCtxMap?.get(canonicalKey);
+        return getCollectionLabel(canonicalKey, form, workspaceCtx, collectionCtx);
+    });
+}
+//# sourceMappingURL=canonicalRefs.js.map

package/dist/lib/canonicalRefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalRefs.js","sourceRoot":"","sources":["../../src/lib/canonicalRefs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAkCH;;GAEG;AACH,MAAM,kBAAkB,GAAG,oEAAoE,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC7C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,mDAAmD;IACnD,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACzD,IAAI,KAA6B,CAAC;IAElC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,YAAqB;IACnE,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,IAAI,GAAG,GAAG,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,WAAgC;IACjF,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEzD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,YAAgC,EAAE,EAAE;QACpF,qFAAqF;QACrF,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;QACD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ,EAAE,CAAC;YACd,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,OAAO,gBAAgB,GAAG,GAAG,CAAC;IAC/B,CAAC,CAAC,CAAC;AACJ,CAAC;AAiDD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qCAAqC,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CACjC,YAAoB,EACpB,IAAY,EACZ,YAAgC,EAChC,aAAkC;IAElC,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,YAAY,EAAE,gBAAgB,EAAE,CAAC,YAAY,CAAC,CAAC;IAChE,IAAI,QAAQ,EAAE,CAAC;QACd,MAAM,KAAK,GAAI,QAA+C,CAAC,IAAI,CAAC,CAAC;QACrE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC3D,CAAC;IAED,+EAA+E;IAC/E,MAAM,SAAS,GAAG,aAAa,EAAE,MAAM,CAAC;IACxC,IAAI,SAAS,EAAE,CAAC;QACf,MAAM,MAAM,GAAI,SAAgD,CAAC,IAAI,CAAC,CAAC;QACvE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC;IAC9D,CAAC;IAED,2FAA2F;IAC3F,yFAAyF;IACzF,MAAM,aAAa,GAAG,YAAY,EAAE,kBAAkB,EAAE,CAAC,YAAY,CAAC,CAAC;IACvE,IAAI,aAAa,EAAE,CAAC;QACnB,MAAM,MAAM,GAAI,aAAoD,CAAC,IAAI,CAAC,CAAC;QAC3E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC;IAC9D,CAAC;IAED,yCAAyC;IACzC,OAAO,YAAY,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CACjC,IAAY,EACZ,YAAgC,EAChC,gBAAkD;IAElD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAExD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAoB,EAAE,IAAY,EAAE,EAAE;QACzE,MAAM,aAAa,GAAG,gBAAgB,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;QAC1D,OAAO,kBAAkB,CAAC,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/captureGrounding.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `pb capture` grounding presentation helpers — extracted from capture.ts (WP-688 S4, TASK-105)
+ * purely to fund that file's shrink-only LOC budget (STD-2/DEC-1504); no behavior change.
+ * `promptYN` moves here as dead-on-arrival for the `--link-type` refusal path — it stays used
+ * only by `--strict`'s existing possible-duplicate confirmation, unchanged.
+ */
+/** WP-319 S3: Pre-write grounding result from chain.suggestLinksForCapture */
+export type GroundingRelated = {
+    entryId: string;
+    name: string;
+    collectionSlug: string;
+    overlapRatio: number;
+    recommendedRelationType: string;
+    reasoning: string;
+};
+export type GroundingDuplicate = {
+    entryId: string;
+    name: string;
+    collectionSlug: string;
+    matchType: 'related' | 'possible_duplicate';
+    overlapRatio: number;
+};
+export type GroundingGovernance = {
+    entryId: string;
+    name: string;
+    collectionSlug: string;
+    severity: 'block' | 'warn' | 'inform';
+};
+export type GroundingResult = {
+    index: number;
+    related: GroundingRelated[];
+    duplicates: GroundingDuplicate[];
+    /** WP-319 S1: Present only after Convex S1 deploys to production. */
+    governance?: GroundingGovernance[];
+    v?: number;
+};
+/**
+ * Extract a known ID prefix hint from capture text.
+ * Pattern: "FLO: description" or "TEN: something broken" — prefix must be uppercase,
+ * followed by colon and optional whitespace, then the actual text.
+ * Returns the resolved collection slug and the cleaned text (prefix stripped).
+ */
+export declare function extractPrefixHint(text: string, prefixMap: Record<string, string>): {
+    resolvedCollection: string | null;
+    cleanText: string;
+};
+/** Print advisory grounding banner to stderr. Suppressed when grounding has no matches. */
+export declare function printGroundingBanner(grounding: GroundingResult): void;
+/** Print dry-run grounding preview to stdout (--suggest-only). */
+export declare function printGroundingPreview(grounding: GroundingResult | null, entryName: string, collectionSlug: string): void;
+/** Prompt the user with a y/N question. Resolves true for "y", false otherwise. */
+export declare function promptYN(message: string): Promise<boolean>;
+//# sourceMappingURL=captureGrounding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"captureGrounding.d.ts","sourceRoot":"","sources":["../../src/lib/captureGrounding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,SAAS,GAAG,oBAAoB,CAAC;IAC5C,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,qEAAqE;IACrE,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;IAAE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAO3I;AAID,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAoCrE;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,eAAe,GAAG,IAAI,EACjC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,IAAI,CA+CN;AAED,mFAAmF;AACnF,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQhE"}

package/dist/lib/captureGrounding.js

@@ -0,0 +1,108 @@
+/**
+ * `pb capture` grounding presentation helpers — extracted from capture.ts (WP-688 S4, TASK-105)
+ * purely to fund that file's shrink-only LOC budget (STD-2/DEC-1504); no behavior change.
+ * `promptYN` moves here as dead-on-arrival for the `--link-type` refusal path — it stays used
+ * only by `--strict`'s existing possible-duplicate confirmation, unchanged.
+ */
+/**
+ * Extract a known ID prefix hint from capture text.
+ * Pattern: "FLO: description" or "TEN: something broken" — prefix must be uppercase,
+ * followed by colon and optional whitespace, then the actual text.
+ * Returns the resolved collection slug and the cleaned text (prefix stripped).
+ */
+export function extractPrefixHint(text, prefixMap) {
+    const match = text.match(/^([A-Z]{2,4}):\s*(.+)$/s);
+    if (!match)
+        return { resolvedCollection: null, cleanText: text };
+    const [, prefix, rest] = match;
+    const slug = prefixMap[prefix];
+    if (!slug)
+        return { resolvedCollection: null, cleanText: text };
+    return { resolvedCollection: slug, cleanText: rest.trim() };
+}
+// WP-319 S3: Grounding helpers — advisory output, stderr only.
+/** Print advisory grounding banner to stderr. Suppressed when grounding has no matches. */
+export function printGroundingBanner(grounding) {
+    const possibleDuplicates = grounding.duplicates.filter((d) => d.matchType === 'possible_duplicate');
+    const related = [
+        ...grounding.related,
+        ...grounding.duplicates.filter((d) => d.matchType === 'related'),
+    ];
+    const governance = grounding.governance ?? [];
+    const hasGovernance = governance.length > 0;
+    if (possibleDuplicates.length === 0 && related.length === 0 && !hasGovernance) {
+        return; // Zero-noise floor: nothing to show
+    }
+    const lines = ['\n  Grounding:'];
+    if (possibleDuplicates.length > 0) {
+        const label = possibleDuplicates.length === 1 ? 'Possible duplicate' : 'Possible duplicates';
+        const items = possibleDuplicates.map((d) => `${d.entryId} "${d.name}"`).join(', ');
+        lines.push(`  ⚠ ${label}: ${items}`);
+    }
+    if (related.length > 0) {
+        const items = related
+            .slice(0, 3)
+            .map((r) => `${r.entryId} "${r.name}"`)
+            .join(', ');
+        lines.push(`  ~ Related: ${items}`);
+    }
+    for (const gov of governance) {
+        const icon = gov.severity === 'block' ? '✗' : gov.severity === 'warn' ? '⚠' : 'ℹ';
+        lines.push(`  ${icon} Governance [${gov.severity}]: ${gov.entryId} "${gov.name}"`);
+    }
+    lines.push('');
+    process.stderr.write(lines.join('\n') + '\n');
+}
+/** Print dry-run grounding preview to stdout (--suggest-only). */
+export function printGroundingPreview(grounding, entryName, collectionSlug) {
+    process.stdout.write(`\n  Grounding preview for: ${entryName.slice(0, 80)}\n`);
+    process.stdout.write(`  Collection: ${collectionSlug}\n\n`);
+    if (!grounding) {
+        process.stdout.write('  No grounding data available (timeout or unavailable).\n\n');
+        return;
+    }
+    const possibleDuplicates = grounding.duplicates.filter((d) => d.matchType === 'possible_duplicate');
+    const related = [
+        ...grounding.related,
+        ...grounding.duplicates.filter((d) => d.matchType === 'related'),
+    ];
+    const govCandidates = grounding.governance ?? [];
+    if (possibleDuplicates.length === 0 && related.length === 0 && govCandidates.length === 0) {
+        process.stdout.write('  No matches found — capture looks unique.\n\n');
+        return;
+    }
+    if (possibleDuplicates.length > 0) {
+        process.stdout.write('  Possible duplicates:\n');
+        for (const d of possibleDuplicates) {
+            process.stdout.write(`    · ${d.entryId} "${d.name}" (overlap: ${Math.round(d.overlapRatio * 100)}%)\n`);
+        }
+        process.stdout.write('\n');
+    }
+    if (related.length > 0) {
+        process.stdout.write('  Related entries:\n');
+        for (const r of related.slice(0, 5)) {
+            const relType = 'recommendedRelationType' in r ? r.recommendedRelationType : 'related';
+            process.stdout.write(`    · ${r.entryId} "${r.name}" → ${relType}\n`);
+        }
+        process.stdout.write('\n');
+    }
+    if (govCandidates.length > 0) {
+        process.stdout.write('  Governance:\n');
+        for (const g of govCandidates) {
+            process.stdout.write(`    · [${g.severity}] ${g.entryId} "${g.name}"\n`);
+        }
+        process.stdout.write('\n');
+    }
+    process.stdout.write('  Run without --suggest-only to create the entry.\n\n');
+}
+/** Prompt the user with a y/N question. Resolves true for "y", false otherwise. */
+export async function promptYN(message) {
+    return new Promise((resolve) => {
+        process.stderr.write(message);
+        process.stdin.once('data', (data) => {
+            const answer = data.toString().trim().toLowerCase();
+            resolve(answer === 'y');
+        });
+    });
+}
+//# sourceMappingURL=captureGrounding.js.map

package/dist/lib/captureGrounding.js.map

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