@funnelsgrove/cli 0.1.20 → 0.1.26

package/README.md

@@ -41,6 +41,22 @@ for the same local diff.
 
 Use `fgrove env pull` from a synced folder to refresh only the ignored local `.env` file after project settings change, without replacing source files.
 
+Create an experiment draft from a strict JSON spec:
+
+```bash
+fgrove experiments create --spec experiment.json --dir .
+fgrove experiments create --spec experiment.json --dir . --json
+fgrove validate
+```
+
+The spec uses a stable `id` and `type: "step"`, `"paywall"`, or `"pricing"` with two to five variants, exactly one control, unique metrics and variant keys, and integer traffic totaling 100. Pricing variants also require `offerSetKey` and must route to the top-level `stepId`. See `docs/funnelsgrove/recipes/add-experiment.md` in a synced funnel for complete valid JSON examples and remediation guidance.
+
+Creation is draft-only: it creates no PostHog flag and activates no traffic. The experiment becomes visible in the UI after the API commits its hosted generated snapshot, and the CLI installs those exact generated bytes locally through recoverable staging. `.funnelsgrove-sync.json` stays local and ignored.
+
+With `--json`, success output contains only `experimentId`, `experimentKey`, `draftVersionId`, and `writtenPaths`, with generated paths in canonical order.
+
+For a non-GitHub funnel, deliver the local source with `fgrove sync up`. For a GitHub-connected funnel, commit and push the generated source with the rest of the change, then run `fgrove github pull`; do not commit `.funnelsgrove-sync.json` or use `fgrove sync up` for that diff.
+
 GitHub sync workflow:
 
 ```bash

package/dist/analyticsOutput.d.ts

@@ -108,8 +108,9 @@ export type MarketingCohortPerformanceRow = {
     revenueDay3: number;
     revenueDay90: number;
     revenueDay180: number;
+    pLtvCurrency: string | null;
     pLtv: number | null;
-    pLtvPredictedNetRevenueDay365Minor: number;
+    pLtvPredictedNetRevenueDay365Minor: number | null;
     pLtvPredictedCustomerCount: number;
     campaign: string;
     channel: string;

package/dist/analyticsOutput.js

@@ -78,8 +78,8 @@ const formatPercent = (value) => (typeof value === 'number' && Number.isFinite(v
 const formatPercentPoints = (value) => (typeof value === 'number' && Number.isFinite(value)
     ? `${value.toFixed(2)}%`
     : '');
-const formatCurrency = (value) => new Intl.NumberFormat('en-US', {
-    currency: 'USD',
+const formatCurrency = (value, currency = 'USD') => new Intl.NumberFormat('en-US', {
+    currency,
     maximumFractionDigits: 2,
     style: 'currency',
 }).format(value);
@@ -225,11 +225,25 @@ export const formatConversionsTable = (input) => {
     return `${lines.join('\n')}\n`;
 };
 const flattenCohortRows = (rows) => rows.flatMap((row) => [row, ...(row.segments || []), ...(row.children || [])]);
+const normalizeCurrency = (value) => {
+    const currency = value?.trim().toUpperCase() || '';
+    return /^[A-Z]{3}$/.test(currency) ? currency : null;
+};
 const predictedAverageLtv = (row) => {
+    if (!normalizeCurrency(row.pLtvCurrency)) {
+        return null;
+    }
     if (row.pLtvPredictedCustomerCount > 0) {
-        return row.pLtvPredictedNetRevenueDay365Minor / row.pLtvPredictedCustomerCount / 100;
+        return typeof row.pLtvPredictedNetRevenueDay365Minor === 'number'
+            && Number.isFinite(row.pLtvPredictedNetRevenueDay365Minor)
+            ? row.pLtvPredictedNetRevenueDay365Minor
+                / row.pLtvPredictedCustomerCount
+                / 100
+            : null;
     }
-    return Number(row.pLtv) || 0;
+    return typeof row.pLtv === 'number' && Number.isFinite(row.pLtv)
+        ? row.pLtv
+        : null;
 };
 const ratioToSpend = (value, spend) => (Number.isFinite(value) && Number.isFinite(spend) && spend !== 0 ? value / spend : null);
 const formatRoi = (profit, spend) => {
@@ -243,12 +257,18 @@ const formatRoas = (revenue, spend) => {
 export const formatCohortTable = (input) => {
     const lines = [
         `Cohort\t${input.date}`,
-        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tcpa\tpredictedProfit\tpROI\tROAS\tROAS d3\tROAS d90\tROAS d180',
+        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tpLtvCurrency\tcpa\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;
-        const predictedRevenue = predictedAverageLtv(row) * row.subscribers;
-        const predictedProfit = predictedRevenue - row.spend;
+        const averageLtv = predictedAverageLtv(row);
+        const predictedRevenue = averageLtv === null
+            ? null
+            : averageLtv * row.subscribers;
+        const predictedProfit = predictedRevenue === null
+            ? null
+            : predictedRevenue - row.spend;
+        const pLtvCurrency = normalizeCurrency(row.pLtvCurrency);
         lines.push([
             row.cohortDate,
             row.mediaSource,
@@ -257,10 +277,15 @@ export const formatCohortTable = (input) => {
             formatNumber(row.subscribers),
             formatPercentPoints(row.subscribersAlivePercent),
             formatCurrency(row.revenue),
-            row.pLtv === null ? '' : formatCurrency(row.pLtv),
+            row.pLtv === null || pLtvCurrency === null
+                ? ''
+                : formatCurrency(row.pLtv, pLtvCurrency),
+            pLtvCurrency || '',
             row.subscribers > 0 ? formatCurrency(cpa) : '',
-            formatCurrency(predictedProfit),
-            formatRoi(predictedProfit, row.spend),
+            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),

package/dist/apiClient.d.ts

@@ -1,5 +1,6 @@
 import { type FunnelContractDiagnosticCode } from '@funnelsgrove/runtime';
 import type { SourceCandidateOperation } from './localSync.js';
+import type { AgentExperimentSpec, ExperimentCreateResponse } from './experimentCreate.js';
 type FetchFn = typeof fetch;
 type TrpcProcedureType = 'query' | 'mutation';
 export type TrpcCallInput = {
@@ -17,6 +18,12 @@ export type FunnelSourceCandidateApiContext = {
     fetchFn?: FetchFn;
     signal?: AbortSignal;
 };
+export type CreateFunnelExperimentFromSpecInput = {
+    workspaceId: string;
+    funnelId: string;
+    expectedDraftVersionId: string;
+    spec: AgentExperimentSpec;
+};
 export type FunnelSourceCandidateStatus = 'staging' | 'validating' | 'committed' | 'aborted' | 'expired' | 'failed';
 export type BeginFunnelSourceCandidateInput = {
     workspaceId: string;
@@ -64,7 +71,7 @@ export type FinalizeFunnelSourceCandidateResult = {
     idempotent: boolean;
     diagnostics: readonly FunnelContractApiDiagnostic[];
 };
-export declare const FUNNEL_CONTRACT_API_INGRESSES: readonly ["agent-transaction", "cli-sync", "github-sync", "builder-authoring", "preview-publish", "production-publish", "published-artifact-serving"];
+export declare const FUNNEL_CONTRACT_API_INGRESSES: readonly ["cli-sync", "github-sync", "builder-authoring", "preview-publish", "production-publish", "published-artifact-serving"];
 export type FunnelContractApiIngress = (typeof FUNNEL_CONTRACT_API_INGRESSES)[number];
 export type FunnelContractApiDiagnostic = {
     code: FunnelContractDiagnosticCode;
@@ -95,4 +102,5 @@ export declare const beginFunnelSourceCandidate: (context: FunnelSourceCandidate
 export declare const stageFunnelSourceCandidate: (context: FunnelSourceCandidateApiContext, input: StageFunnelSourceCandidateInput) => Promise<StageFunnelSourceCandidateResult>;
 export declare const finalizeFunnelSourceCandidate: (context: FunnelSourceCandidateApiContext, input: FinalizeFunnelSourceCandidateInput) => Promise<FinalizeFunnelSourceCandidateResult>;
 export declare const abortFunnelSourceCandidate: (context: FunnelSourceCandidateApiContext, input: FinishFunnelSourceCandidateInput) => Promise<FunnelSourceCandidateSummary>;
+export declare const createFunnelExperimentFromSpec: (context: FunnelSourceCandidateApiContext, input: CreateFunnelExperimentFromSpecInput) => Promise<ExperimentCreateResponse>;
 export {};

package/dist/apiClient.js

@@ -1,6 +1,7 @@
 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([
-    'agent-transaction',
     'cli-sync',
     'github-sync',
     'builder-authoring',
@@ -236,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'
         ? {
@@ -276,3 +285,9 @@ export const beginFunnelSourceCandidate = (context, input) => callFunnelSourceCa
 export const stageFunnelSourceCandidate = (context, input) => callFunnelSourceCandidateMutation(context, 'funnels.stageSourceCandidate', input);
 export const finalizeFunnelSourceCandidate = (context, input) => callFunnelSourceCandidateMutation(context, 'funnels.finalizeSourceCandidate', input);
 export const abortFunnelSourceCandidate = (context, input) => callFunnelSourceCandidateMutation(context, 'funnels.abortSourceCandidate', input);
+export const createFunnelExperimentFromSpec = (context, input) => callTrpcProcedure({
+    ...context,
+    path: 'funnelExperiments.createFromSpec',
+    type: 'mutation',
+    input,
+});

package/dist/cli.d.ts

@@ -144,6 +144,7 @@ type SyncTargetIdInput = {
 };
 type GeneratedConfigKind = 'offerSets' | 'experiments';
 export declare const SYNC_DOWN_GENERATED_CONFIG_KINDS: GeneratedConfigKind[];
+export declare const EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS: readonly ["sync down", "sync up", "experiments sync", "offer-sets sync"];
 export declare function resolveSyncTargetIds(input: SyncTargetIdInput): {
     workspaceId: string;
     funnelId?: string;

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';
@@ -8,9 +8,11 @@ import path from 'node:path';
 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, finalizeFunnelSourceCandidate, stageFunnelSourceCandidate, } from './apiClient.js';
+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';
 import { pullEnvFile } from './envSync.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { syncGitHubDraftIfConnected } from './githubSyncFlow.js';
@@ -23,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')
@@ -1059,6 +1049,13 @@ const GENERATED_CONFIG_PATH_BY_KIND = {
     experiments: 'src/config/experiments.generated.ts',
 };
 export const SYNC_DOWN_GENERATED_CONFIG_KINDS = ['offerSets', 'experiments'];
+export const EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS = [
+    'sync down',
+    'sync up',
+    'experiments sync',
+    'offer-sets sync',
+];
+const experimentTransactionRecoveryCommands = new Set(EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS);
 export function resolveSyncTargetIds(input) {
     const workspaceId = input.explicitWorkspaceId ||
         input.manifest?.workspaceId ||
@@ -1432,10 +1429,17 @@ const syncGeneratedConfigFilesForCli = async (input) => {
 };
 const addExamples = (command, examples) => command.addHelpText('after', `\nExamples:\n${examples.map((example) => `  $ ${example}`).join('\n')}`);
 export const program = new Command();
+program.hook('preAction', async (_command, actionCommand) => {
+    const commandPath = `${actionCommand.parent?.name() || ''} ${actionCommand.name()}`.trim();
+    if (!experimentTransactionRecoveryCommands.has(commandPath))
+        return;
+    const options = actionCommand.opts();
+    await recoverExperimentCreateTransaction(path.resolve(process.cwd(), options.dir || '.'));
+});
 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, [
@@ -1654,9 +1658,30 @@ addExamples(offerSetsCommand
     console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
 });
 const experimentsCommand = addExamples(program.command('experiments').description('Manage funnel experiments'), [
+    'fgrove experiments create --spec experiment.json --dir .',
     'fgrove experiments sync',
     'fgrove experiments sync --funnel claimbee-ios',
 ]);
+addExamples(experimentsCommand
+    .command('create')
+    .description('Create a draft experiment from a JSON spec')
+    .requiredOption('--spec <path>', 'Experiment JSON spec')
+    .option('--dir <path>', 'Synced local funnel directory', '.')
+    .option('--json', 'Emit one machine-readable success object'), [
+    'fgrove experiments create --spec experiment.json --dir .',
+    'fgrove experiments create --spec experiment.json --dir ./claimbee-ios --json',
+])
+    .action(async (options) => {
+    const result = await executeExperimentCreate({
+        sourceDir: path.resolve(process.cwd(), options.dir),
+        specPath: path.resolve(process.cwd(), options.spec),
+        createFromSpec: async (input) => createFunnelExperimentFromSpec({
+            apiUrl: getApiUrl(),
+            token: await readAuthToken(),
+        }, input),
+    });
+    process.stdout.write(formatExperimentCreateSuccess(result, options.json === true));
+});
 addExamples(experimentsCommand
     .command('sync')
     .description('Write generated experiment config for a funnel')

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();