@funnelsgrove/cli 0.1.24 → 0.1.27

package/dist/analyticsOutput.d.ts

@@ -101,6 +101,7 @@ export type MarketingCohortPerformanceRow = {
     funnelUrl: string;
     mediaSource: string;
     spend: number;
+    spendCurrency: string | null;
     subscribers: number;
     subscribersAlive: number;
     subscribersAlivePercent: number | null;
@@ -108,6 +109,16 @@ export type MarketingCohortPerformanceRow = {
     revenueDay3: number;
     revenueDay90: number;
     revenueDay180: number;
+    revenueCurrency: string | null;
+    revenueCurrencySafe: boolean;
+    predictedNetRevenueDay3Minor: number | null;
+    predictedNetRevenueDay3Currency: string | null;
+    predictedNetRevenueDay90Minor: number | null;
+    predictedNetRevenueDay90Currency: string | null;
+    predictedNetRevenueDay180Minor: number | null;
+    predictedNetRevenueDay180Currency: string | null;
+    predictedNetRevenueDay365Minor: number | null;
+    predictedNetRevenueDay365Currency: string | null;
     pLtvCurrency: string | null;
     pLtv: number | null;
     pLtvPredictedNetRevenueDay365Minor: number | null;

package/dist/analyticsOutput.js

@@ -226,9 +226,16 @@ export const formatConversionsTable = (input) => {
 };
 const flattenCohortRows = (rows) => rows.flatMap((row) => [row, ...(row.segments || []), ...(row.children || [])]);
 const normalizeCurrency = (value) => {
-    const currency = value?.trim().toUpperCase() || '';
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const currency = value.trim().toUpperCase();
     return /^[A-Z]{3}$/.test(currency) ? currency : null;
 };
+const sameCurrency = (left, right) => {
+    const normalizedLeft = normalizeCurrency(left);
+    return normalizedLeft !== null && normalizedLeft === normalizeCurrency(right);
+};
 const predictedAverageLtv = (row) => {
     if (!normalizeCurrency(row.pLtvCurrency)) {
         return null;
@@ -245,19 +252,49 @@ const predictedAverageLtv = (row) => {
         ? row.pLtv
         : null;
 };
-const ratioToSpend = (value, spend) => (Number.isFinite(value) && Number.isFinite(spend) && spend !== 0 ? value / spend : null);
+const ratioToSpend = (value, spend) => (Number.isFinite(value) && Number.isFinite(spend) && spend > 0 ? value / spend : null);
 const formatRoi = (profit, spend) => {
     const ratio = ratioToSpend(profit, spend);
     return ratio === null ? '' : `${(ratio * 100).toFixed(2)}%`;
 };
-const formatRoas = (revenue, spend) => {
-    const ratio = ratioToSpend(revenue, spend);
-    return ratio === null ? '' : `${ratio.toFixed(2)}x`;
+const forecastDefinitions = {
+    day3: {
+        minor: 'predictedNetRevenueDay3Minor',
+        currency: 'predictedNetRevenueDay3Currency',
+    },
+    day90: {
+        minor: 'predictedNetRevenueDay90Minor',
+        currency: 'predictedNetRevenueDay90Currency',
+    },
+    day180: {
+        minor: 'predictedNetRevenueDay180Minor',
+        currency: 'predictedNetRevenueDay180Currency',
+    },
+    day365: {
+        minor: 'predictedNetRevenueDay365Minor',
+        currency: 'predictedNetRevenueDay365Currency',
+    },
+};
+const formatForecastRoas = (row, forecast) => {
+    const minor = row[forecast.minor];
+    if (typeof minor !== 'number'
+        || !Number.isFinite(minor)
+        || !Number.isFinite(row.spend)
+        || row.spend <= 0) {
+        return '';
+    }
+    if (!normalizeCurrency(row.spendCurrency)) {
+        return '';
+    }
+    if (minor !== 0 && !sameCurrency(row[forecast.currency], row.spendCurrency)) {
+        return '';
+    }
+    return `${((minor / 100 / row.spend) * 100).toFixed(2)}%`;
 };
 export const formatCohortTable = (input) => {
     const lines = [
         `Cohort\t${input.date}`,
-        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tpLtvCurrency\tcpa\tpredictedProfit\tpROI\tROAS\tROAS d3\tROAS d90\tROAS d180',
+        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tpLtvCurrency\tcpa\tpRevenue\tpredictedProfit\tpROI\tROAS\tROAS d3\tROAS d90\tROAS d180',
     ];
     for (const row of flattenCohortRows(input.cohort.rows)) {
         const cpa = row.subscribers > 0 ? row.spend / row.subscribers : 0;
@@ -265,31 +302,41 @@ export const formatCohortTable = (input) => {
         const predictedRevenue = averageLtv === null
             ? null
             : averageLtv * row.subscribers;
-        const predictedProfit = predictedRevenue === null
-            ? null
-            : predictedRevenue - row.spend;
+        const predictedProfit = predictedRevenue !== null
+            && sameCurrency(row.pLtvCurrency, row.spendCurrency)
+            ? predictedRevenue - row.spend
+            : null;
+        const spendCurrency = normalizeCurrency(row.spendCurrency);
+        const revenueCurrency = row.revenueCurrencySafe === true
+            ? normalizeCurrency(row.revenueCurrency)
+            : null;
         const pLtvCurrency = normalizeCurrency(row.pLtvCurrency);
         lines.push([
             row.cohortDate,
             row.mediaSource,
             row.funnelUrl,
-            formatCurrency(row.spend),
+            spendCurrency === null ? '' : formatCurrency(row.spend, spendCurrency),
             formatNumber(row.subscribers),
             formatPercentPoints(row.subscribersAlivePercent),
-            formatCurrency(row.revenue),
+            revenueCurrency === null ? '' : formatCurrency(row.revenue, revenueCurrency),
             row.pLtv === null || pLtvCurrency === null
                 ? ''
                 : formatCurrency(row.pLtv, pLtvCurrency),
             pLtvCurrency || '',
-            row.subscribers > 0 ? formatCurrency(cpa) : '',
+            row.subscribers > 0 && spendCurrency !== null
+                ? formatCurrency(cpa, spendCurrency)
+                : '',
+            predictedRevenue === null || pLtvCurrency === null
+                ? ''
+                : formatCurrency(predictedRevenue, pLtvCurrency),
             predictedProfit === null
                 ? ''
                 : formatCurrency(predictedProfit, pLtvCurrency || 'USD'),
             predictedProfit === null ? '' : formatRoi(predictedProfit, row.spend),
-            formatRoas(row.revenue, row.spend),
-            formatRoas(row.revenueDay3, row.spend),
-            formatRoas(row.revenueDay90, row.spend),
-            formatRoas(row.revenueDay180, row.spend),
+            formatForecastRoas(row, forecastDefinitions.day365),
+            formatForecastRoas(row, forecastDefinitions.day3),
+            formatForecastRoas(row, forecastDefinitions.day90),
+            formatForecastRoas(row, forecastDefinitions.day180),
         ].join('\t'));
     }
     return `${lines.join('\n')}\n`;

package/dist/apiClient.js

@@ -1,4 +1,6 @@
 import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, } from '@funnelsgrove/runtime';
+import { checkContractCompatibility } from './contractCompatibility.js';
+import { cliReleaseIdentity } from './cliIdentity.js';
 export const FUNNEL_CONTRACT_API_INGRESSES = Object.freeze([
     'cli-sync',
     'github-sync',
@@ -235,6 +237,14 @@ const buildHeaders = (input) => {
 };
 export async function callTrpcProcedure(input) {
     const fetchFn = input.fetchFn || fetch;
+    await checkContractCompatibility({
+        apiUrl: input.apiUrl,
+        cliVersion: cliReleaseIdentity.cliVersion,
+        docsIdentity: cliReleaseIdentity.docsIdentity,
+        fetchImpl: fetchFn,
+        timeoutMs: 3_000,
+        warn: (message) => console.warn(message),
+    });
     const baseUrl = `${trimTrailingSlash(input.apiUrl)}/${input.path}`;
     const init = input.type === 'query'
         ? {

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createHash } from 'node:crypto';
-import { constants as fsConstants, readFileSync, realpathSync } from 'node:fs';
+import { constants as fsConstants, realpathSync } from 'node:fs';
 import { cp, link, lstat, mkdir, mkdtemp, open, readFile, readdir, rmdir, rm, unlink, writeFile, } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, PREVIOUS_STEP_CONTRACT_VERSION, createFunnelContractDiagnostic, } from '@funnelsgrove/runtime';
 import { abortFunnelSourceCandidate, beginFunnelSourceCandidate, callTrpcProcedure, createFunnelExperimentFromSpec, finalizeFunnelSourceCandidate, stageFunnelSourceCandidate, } from './apiClient.js';
+import { cliReleaseIdentity } from './cliIdentity.js';
 import { clearActiveContext, getDefaultAuthConfigPath, loadActiveContext, loadAuthToken, saveActiveContext, saveAuthToken, } from './authStore.js';
 import { buildSyncManifest, buildCommittedSyncManifest, buildSourceCandidateOperations, collectChangedSourceFiles, collectSourceSnapshot, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, readSyncManifest, runSyncDownLocalLifecycle, runSourceCandidateSync, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
 import { executeExperimentCreate, formatExperimentCreateSuccess, recoverExperimentCreateTransaction, } from './experimentCreate.js';
@@ -24,18 +25,6 @@ import { validateFunnel } from './funnelValidation.js';
 import { StepContractMigrationError, applyStepContractV2Migration, checkStepContractV2Migration, recoverStepContractV2Migration, resolveStepContractMigrationMode, stepContractMigrationReportPath, } from './stepContractMigration.js';
 import { assertHasCohortData, assertHasConversionData, assertHasFunnelPathData, assertHasTransitionData, buildCohortReportPayload, buildConversionReportPayload, buildFunnelPathReportPayload, buildTransitionReportPayload, formatAnalyticsJson, formatCohortTable, formatConversionsTable, formatFunnelPathTable, formatTransitionsTable, normalizeAnalyticsOutputFormat, parseAnalyticsDate, } from './analyticsOutput.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const readCliVersion = () => {
-    try {
-        const packageJson = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
-        if (typeof packageJson.version === 'string' && packageJson.version.trim()) {
-            return packageJson.version;
-        }
-    }
-    catch {
-        // Fall through to the packaged fallback below.
-    }
-    return '0.1.3';
-};
 const toKebabCase = (value) => value
     .trim()
     .replace(/([a-z])([A-Z])/g, '$1-$2')
@@ -1450,7 +1439,7 @@ program.hook('preAction', async (_command, actionCommand) => {
 program
     .name('fgrove')
     .description('FunnelsGrove CLI for editing, syncing, and publishing funnels')
-    .version(readCliVersion())
+    .version(cliReleaseIdentity.cliVersion)
     .option('--api-url <url>', 'FunnelsGrove tRPC API URL', process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL)
     .option('--config <path>', 'Auth config path', process.env.FUNNELSGROVE_CONFIG || getDefaultAuthConfigPath());
 addExamples(program, [

package/dist/cliIdentity.d.ts

@@ -0,0 +1,13 @@
+import { type DocsIdentity } from './contractCompatibility.js';
+export type CliReleaseIdentity = Readonly<{
+    cliVersion: string;
+    docsIdentity: DocsIdentity;
+}>;
+type ReadTextFile = (path: URL, encoding: 'utf8') => string;
+export declare const parseCliReleaseIdentity: (packageJson: unknown, docsManifest: unknown) => CliReleaseIdentity;
+export declare const loadCliReleaseIdentity: (readTextFile?: ReadTextFile) => CliReleaseIdentity;
+export declare const cliReleaseIdentity: Readonly<{
+    cliVersion: string;
+    docsIdentity: DocsIdentity;
+}>;
+export {};

package/dist/cliIdentity.js

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import { isStrictSemVer } from './contractCompatibility.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const isRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value));
+const startupError = (reason) => new Error(`FG-CLI-IDENTITY-001: invalid packaged CLI release identity: ${reason}`);
+export const parseCliReleaseIdentity = (packageJson, docsManifest) => {
+    if (!isRecord(packageJson) || !isStrictSemVer(packageJson.version)) {
+        throw startupError('package.json version must be an exact semantic version');
+    }
+    if (!isRecord(docsManifest) || !isStrictSemVer(docsManifest.bundleVersion)) {
+        throw startupError('docs bundleVersion must be an exact semantic version');
+    }
+    if (!Number.isSafeInteger(docsManifest.stepContractVersion)
+        || docsManifest.stepContractVersion <= 0) {
+        throw startupError('stepContractVersion must be a positive integer');
+    }
+    if (typeof docsManifest.contractHash !== 'string' || !SHA256.test(docsManifest.contractHash)) {
+        throw startupError('contractHash must be a lowercase SHA-256 digest');
+    }
+    return Object.freeze({
+        cliVersion: packageJson.version,
+        docsIdentity: Object.freeze({
+            docsBundleVersion: docsManifest.bundleVersion,
+            stepContractVersion: docsManifest.stepContractVersion,
+            contractHash: docsManifest.contractHash,
+        }),
+    });
+};
+export const loadCliReleaseIdentity = (readTextFile = readFileSync) => {
+    try {
+        const packageJson = JSON.parse(readTextFile(new URL('../package.json', import.meta.url), 'utf8'));
+        const docsManifest = JSON.parse(readTextFile(new URL('../template_docs/.funnelsgrove-docs.json', import.meta.url), 'utf8'));
+        return parseCliReleaseIdentity(packageJson, docsManifest);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('FG-CLI-IDENTITY-001:')) {
+            throw error;
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw startupError(`could not read packaged CLI release identity (${reason})`);
+    }
+};
+export const cliReleaseIdentity = loadCliReleaseIdentity();

package/dist/contractCompatibility.d.ts

@@ -0,0 +1,30 @@
+export type DocsIdentity = Readonly<{
+    docsBundleVersion: string;
+    stepContractVersion: number;
+    contractHash: string;
+}>;
+export type ContractCapabilities = Readonly<DocsIdentity & {
+    preferredCliVersion: string;
+    minimumCliVersion: string;
+    acceptedDocsBundles: readonly DocsIdentity[];
+}>;
+export type ContractCompatibilityInput = {
+    apiUrl: string;
+    cliVersion: string;
+    docsIdentity: DocsIdentity;
+    fetchImpl: typeof fetch;
+    timeoutMs: number;
+    warn: (message: string) => void;
+};
+export declare const CONTRACT_COMPATIBILITY_ERROR_CODES: readonly ["FG-CLI-COMPAT-001", "FG-CLI-COMPAT-002", "FG-CLI-COMPAT-003"];
+export type ContractCompatibilityErrorCode = (typeof CONTRACT_COMPATIBILITY_ERROR_CODES)[number];
+export declare class ContractCompatibilityError extends Error {
+    readonly code: ContractCompatibilityErrorCode;
+    constructor(code: ContractCompatibilityErrorCode, message: string);
+}
+export declare const isStrictSemVer: (value: unknown) => value is string;
+export declare const compareSemVer: (left: string, right: string) => -1 | 0 | 1 | null;
+export declare const parseContractCapabilities: (value: unknown) => ContractCapabilities | null;
+export declare const deriveContractHealthUrl: (apiUrl: string) => string | null;
+export declare const createContractCompatibilityChecker: () => (input: ContractCompatibilityInput) => Promise<void>;
+export declare const checkContractCompatibility: (input: ContractCompatibilityInput) => Promise<void>;

package/dist/contractCompatibility.js

@@ -0,0 +1,250 @@
+export const CONTRACT_COMPATIBILITY_ERROR_CODES = Object.freeze([
+    'FG-CLI-COMPAT-001',
+    'FG-CLI-COMPAT-002',
+    'FG-CLI-COMPAT-003',
+]);
+export class ContractCompatibilityError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = 'ContractCompatibilityError';
+        this.code = code;
+    }
+}
+const SHA256 = /^[a-f0-9]{64}$/;
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const UPDATE_COMMAND = 'npm install -g @funnelsgrove/cli@latest';
+const DEFAULT_TIMEOUT_MS = 3_000;
+const MAX_TIMEOUT_MS = 10_000;
+const MAX_HEALTH_RESPONSE_BYTES = 64 * 1_024;
+const MAX_ACCEPTED_DOCS_BUNDLES = 7;
+const isRecord = (value) => (typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+const parseSemVer = (value) => {
+    if (typeof value !== 'string')
+        return null;
+    const match = SEMVER.exec(value);
+    if (!match)
+        return null;
+    const prerelease = match[4]?.split('.') ?? null;
+    if (prerelease?.some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0'))) {
+        return null;
+    }
+    return {
+        source: value,
+        core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+        prerelease,
+    };
+};
+export const isStrictSemVer = (value) => parseSemVer(value) !== null;
+const compareBigInt = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const compareParsedSemVer = (left, right) => {
+    for (let index = 0; index < left.core.length; index += 1) {
+        const result = compareBigInt(left.core[index], right.core[index]);
+        if (result !== 0)
+            return result;
+    }
+    if (left.prerelease === null && right.prerelease === null)
+        return 0;
+    if (left.prerelease === null)
+        return 1;
+    if (right.prerelease === null)
+        return -1;
+    const count = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < count; index += 1) {
+        const leftIdentifier = left.prerelease[index];
+        const rightIdentifier = right.prerelease[index];
+        if (leftIdentifier === undefined)
+            return -1;
+        if (rightIdentifier === undefined)
+            return 1;
+        if (leftIdentifier === rightIdentifier)
+            continue;
+        const leftNumeric = /^\d+$/.test(leftIdentifier);
+        const rightNumeric = /^\d+$/.test(rightIdentifier);
+        if (leftNumeric && rightNumeric) {
+            return compareBigInt(BigInt(leftIdentifier), BigInt(rightIdentifier));
+        }
+        if (leftNumeric)
+            return -1;
+        if (rightNumeric)
+            return 1;
+        return leftIdentifier < rightIdentifier ? -1 : 1;
+    }
+    return 0;
+};
+export const compareSemVer = (left, right) => {
+    const parsedLeft = parseSemVer(left);
+    const parsedRight = parseSemVer(right);
+    return parsedLeft && parsedRight ? compareParsedSemVer(parsedLeft, parsedRight) : null;
+};
+const parseDocsIdentity = (value) => {
+    if (!isRecord(value))
+        return null;
+    const docsBundleVersion = value.docsBundleVersion;
+    const stepContractVersion = value.stepContractVersion;
+    const contractHash = value.contractHash;
+    if (!isStrictSemVer(docsBundleVersion)
+        || !Number.isSafeInteger(stepContractVersion)
+        || stepContractVersion <= 0
+        || typeof contractHash !== 'string'
+        || !SHA256.test(contractHash))
+        return null;
+    return Object.freeze({
+        docsBundleVersion,
+        stepContractVersion: stepContractVersion,
+        contractHash,
+    });
+};
+const sameDocsIdentity = (left, right) => (left.docsBundleVersion === right.docsBundleVersion
+    && left.stepContractVersion === right.stepContractVersion
+    && left.contractHash === right.contractHash);
+export const parseContractCapabilities = (value) => {
+    if (!isRecord(value) || !isRecord(value.funnelContract))
+        return null;
+    const funnelContract = value.funnelContract;
+    const preferredIdentity = parseDocsIdentity(funnelContract);
+    const preferredCliVersion = funnelContract.preferredCliVersion;
+    const minimumCliVersion = funnelContract.minimumCliVersion;
+    const acceptedValue = funnelContract.acceptedDocsBundles;
+    if (preferredIdentity === null
+        || !isStrictSemVer(preferredCliVersion)
+        || !isStrictSemVer(minimumCliVersion)
+        || !Array.isArray(acceptedValue)
+        || acceptedValue.length === 0
+        || acceptedValue.length > MAX_ACCEPTED_DOCS_BUNDLES
+        || compareSemVer(minimumCliVersion, preferredCliVersion) > 0)
+        return null;
+    const acceptedDocsBundles = acceptedValue.map(parseDocsIdentity);
+    if (acceptedDocsBundles.some((identity) => identity === null)
+        || !acceptedDocsBundles.some((identity) => (identity !== null && sameDocsIdentity(identity, preferredIdentity))))
+        return null;
+    return Object.freeze({
+        ...preferredIdentity,
+        preferredCliVersion,
+        minimumCliVersion,
+        acceptedDocsBundles: Object.freeze(acceptedDocsBundles),
+    });
+};
+export const deriveContractHealthUrl = (apiUrl) => {
+    try {
+        const parsed = new URL(apiUrl);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        const pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+        parsed.pathname = pathname === '/trpc' || pathname.endsWith('/trpc')
+            ? `${pathname.slice(0, -'/trpc'.length)}/health`
+            : '/health';
+        parsed.search = '';
+        parsed.hash = '';
+        return parsed.toString();
+    }
+    catch {
+        return null;
+    }
+};
+const boundedTimeout = (timeoutMs) => (Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? Math.min(Math.ceil(timeoutMs), MAX_TIMEOUT_MS)
+    : DEFAULT_TIMEOUT_MS);
+const readBoundedJson = async (response) => {
+    if (response.body === null)
+        throw new Error('health response body is missing');
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let byteCount = 0;
+    let text = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            byteCount += value.byteLength;
+            if (byteCount > MAX_HEALTH_RESPONSE_BYTES) {
+                void reader.cancel('health response exceeds the protocol byte limit').catch(() => undefined);
+                throw new Error('health response exceeds the protocol byte limit');
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        text += decoder.decode();
+        return JSON.parse(text);
+    }
+    finally {
+        reader.releaseLock();
+    }
+};
+const fetchCapabilities = async (healthUrl, fetchImpl, timeoutMs) => {
+    const controller = new AbortController();
+    let timeout;
+    const timeoutResult = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            controller.abort();
+            reject(new Error('contract capability lookup timed out'));
+        }, boundedTimeout(timeoutMs));
+    });
+    try {
+        const lookup = (async () => {
+            const response = await fetchImpl(healthUrl, {
+                headers: { accept: 'application/json' },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                return null;
+            return parseContractCapabilities(await readBoundedJson(response));
+        })();
+        return await Promise.race([lookup, timeoutResult]);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+};
+export const createContractCompatibilityChecker = () => {
+    const lookups = new Map();
+    const warned = new Set();
+    const warnOnce = (key, warn, message) => {
+        if (warned.has(key))
+            return;
+        warned.add(key);
+        warn(message);
+    };
+    return async (input) => {
+        const healthUrl = deriveContractHealthUrl(input.apiUrl);
+        const cacheKey = healthUrl ?? `invalid:${input.apiUrl}`;
+        if (healthUrl === null) {
+            warnOnce(cacheKey, input.warn, 'FunnelsGrove contract compatibility check could not derive the API health URL; continuing with server-side validation.');
+            return;
+        }
+        let lookup = lookups.get(healthUrl);
+        if (!lookup) {
+            lookup = fetchCapabilities(healthUrl, input.fetchImpl, input.timeoutMs);
+            lookups.set(healthUrl, lookup);
+        }
+        const capabilities = await lookup;
+        if (capabilities === null) {
+            warnOnce(cacheKey, input.warn, 'FunnelsGrove contract compatibility capabilities are unavailable; continuing with server-side validation.');
+            return;
+        }
+        if (!capabilities.acceptedDocsBundles.some((identity) => sameDocsIdentity(identity, input.docsIdentity))) {
+            throw new ContractCompatibilityError('FG-CLI-COMPAT-001', `docs bundle ${input.docsIdentity.docsBundleVersion} is not accepted by this API. Update the CLI with: ${UPDATE_COMMAND}`);
+        }
+        const minimumComparison = compareSemVer(input.cliVersion, capabilities.minimumCliVersion);
+        if (minimumComparison === null || minimumComparison < 0) {
+            throw new ContractCompatibilityError('FG-CLI-COMPAT-002', `CLI ${input.cliVersion} is below the API minimum ${capabilities.minimumCliVersion}. Update with: ${UPDATE_COMMAND}`);
+        }
+        const preferredComparison = compareSemVer(input.cliVersion, capabilities.preferredCliVersion);
+        if (preferredComparison === null || preferredComparison > 0) {
+            throw new ContractCompatibilityError('FG-CLI-COMPAT-003', `CLI ${input.cliVersion} is newer than the server preferred CLI ${capabilities.preferredCliVersion}; API update needed.`);
+        }
+        const isPreferredDocs = sameDocsIdentity(input.docsIdentity, capabilities);
+        const isExactPreferredCli = input.cliVersion === capabilities.preferredCliVersion;
+        if (!isPreferredDocs || !isExactPreferredCli) {
+            warnOnce(cacheKey, input.warn, `This CLI/docs release is accepted but not preferred by the API. Update when convenient with: ${UPDATE_COMMAND}`);
+        }
+    };
+};
+export const checkContractCompatibility = createContractCompatibilityChecker();