@funnelsgrove/cli 0.1.66 → 0.1.68

package/README.md

@@ -30,9 +30,12 @@ fgrove publish --env preview
 Inside a synced folder, `fgrove` reads `.funnelsgrove-sync.json` first, so you do not need to run `fgrove use` when switching between local funnel directories. Use `fgrove use` only when you want a global fallback context for commands outside a synced folder.
 
 `fgrove sync down` refuses to overwrite local changes in an existing synced
-folder unless `--force` is passed. If `fgrove sync up` says the remote draft
-changed since your local sync, download the latest draft into a clean temporary
-directory, merge your local changes, rerun checks, and sync again.
+folder. If `fgrove sync up` says the remote draft changed since your local sync,
+run `fgrove sync rebase`: it performs a three-way merge from the recorded base,
+preserves CLI-managed files, and leaves the working tree untouched when it finds
+conflicts. Review the merged diff, rerun `fgrove validate`, then sync up again.
+`sync down --force` is the explicit discard path and writes an automatic source
+backup under `.funnelsgrove/rebase-backups/` before replacing hosted paths.
 
 `fgrove sync up` is for funnels without GitHub source sync. When GitHub is
 connected, commit and push source changes with normal git, then run `fgrove

package/dist/cli.d.ts

@@ -94,7 +94,13 @@ export type StepContractMigrationCommandResult = {
     exitCode: 0 | 1 | 2;
     output: string;
 };
-export declare const copyManagedValidationFiles: (targetDir: string, sourceDir?: string) => Promise<void>;
+export declare const copyManagedValidationFiles: (targetDir: string, sourceDir?: string, options?: {
+    replaceConflicts?: boolean;
+}) => Promise<void>;
+export declare const repairDownloadedManagedFiles: (targetDir: string, options?: {
+    docsSourceDir?: string;
+    validationSourceDir?: string;
+}) => Promise<void>;
 export type BoundedNpmCommandOptions = {
     timeoutMs?: number;
     terminationGraceMs?: number;
@@ -145,7 +151,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 const EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS: readonly ["sync down", "sync rebase", "sync up", "experiments sync", "offer-sets sync"];
 export declare function resolveSyncTargetIds(input: SyncTargetIdInput): {
     workspaceId: string;
     funnelId?: string;

package/dist/cli.js

@@ -11,7 +11,8 @@ import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, PREVIO
 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 { buildCommittedSyncManifest, buildDownloadedSyncManifest, buildSourceCandidateOperations, collectChangedSourceFiles, collectSourceSnapshot, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, readSyncManifest, runSyncDownLocalLifecycle, runSourceCandidateSync, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { buildCommittedSyncManifest, buildDownloadedSyncManifest, buildSourceCandidateOperations, collectChangedSourceFiles, collectSourceFiles, collectSourceSnapshot, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, rebaseSourceFiles, readSyncManifest, replaceSourceFiles, runSyncDownLocalLifecycle, runSourceCandidateSync, writeLocalEnvFile, writeSourceFiles, writeSourceRebaseBackup, writeSyncManifest, } from './localSync.js';
+import { mergeTextSourceWithGit } from './sourceRebase.js';
 import { executeExperimentCreate, formatExperimentCreateSuccess, recoverExperimentCreateTransaction, } from './experimentCreate.js';
 import { pullEnvFile } from './envSync.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
@@ -481,7 +482,7 @@ const readTargetRegularFile = async (rootDir, relativePath) => {
     }
     return readFile(path.join(rootDir, relativePath));
 };
-export const copyManagedValidationFiles = async (targetDir, sourceDir = resolveTemplateValidationPath()) => {
+export const copyManagedValidationFiles = async (targetDir, sourceDir = resolveTemplateValidationPath(), options = {}) => {
     const sourcePaths = await listManagedValidatorSourceFiles(sourceDir);
     const sourceManifestBytes = await readFile(path.join(sourceDir, CONTRACT_TOOLS_MANIFEST_PATH));
     const sourceManifest = parseContractToolsManifest(sourceManifestBytes, 'FG-DOC-001');
@@ -502,7 +503,7 @@ export const copyManagedValidationFiles = async (targetDir, sourceDir = resolveT
         sourceFiles.set(entry.path, bytes);
     }
     const priorManifestBytes = await readTargetRegularFile(targetDir, CONTRACT_TOOLS_MANIFEST_PATH);
-    const priorManifest = priorManifestBytes === null
+    const priorManifest = priorManifestBytes === null || options.replaceConflicts === true
         ? null
         : parseContractToolsManifest(priorManifestBytes, 'FG-DOC-002');
     const priorHashes = new Map(priorManifest?.managedFiles.map((entry) => [entry.path, entry.sha256]) ?? []);
@@ -512,7 +513,7 @@ export const copyManagedValidationFiles = async (targetDir, sourceDir = resolveT
             continue;
         }
         const currentHash = createHash('sha256').update(currentBytes).digest('hex');
-        if (priorHashes.get(relativePath) !== currentHash) {
+        if (options.replaceConflicts !== true && priorHashes.get(relativePath) !== currentHash) {
             throw new CliContractError('FG-DOC-002', `Managed validator conflicts with local changes: ${relativePath}`);
         }
     }
@@ -523,6 +524,25 @@ export const copyManagedValidationFiles = async (targetDir, sourceDir = resolveT
     }
     await writeFile(path.join(targetDir, CONTRACT_TOOLS_MANIFEST_PATH), sourceManifestBytes);
 };
+export const repairDownloadedManagedFiles = async (targetDir, options = {}) => {
+    await copyManagedValidationFiles(targetDir, options.validationSourceDir ?? resolveTemplateValidationPath(), { replaceConflicts: true });
+    await recoverTemplateDocs(targetDir);
+    const bundle = await loadBundledDocs(options.docsSourceDir ?? resolveTemplateDocsPath());
+    const status = planTemplateDocsUpdate(await inspectTemplateDocs(bundle, targetDir));
+    for (const conflict of status.files.filter((file) => (file.action === 'conflict' && bundle.files.has(file.path)))) {
+        await resolveTemplateDocsConflict(bundle, targetDir, conflict.path);
+    }
+};
+const loadManagedSyncPaths = async () => {
+    const docsBundle = await loadBundledDocs(resolveTemplateDocsPath());
+    const validationManifest = parseContractToolsManifest(await readFile(path.join(resolveTemplateValidationPath(), CONTRACT_TOOLS_MANIFEST_PATH)), 'FG-DOC-001');
+    return new Set([
+        '.funnelsgrove-docs.json',
+        CONTRACT_TOOLS_MANIFEST_PATH,
+        ...docsBundle.files.keys(),
+        ...validationManifest.managedFiles.map((file) => file.path),
+    ]);
+};
 const MANAGED_VALIDATOR_SCRIPT = 'vite-node --config src/contract/funnel-validator.vite.config.ts src/contract/validate-funnel.cli.ts';
 const ensureManagedValidatorPackage = async (targetDir) => {
     const packagePath = path.join(targetDir, 'package.json');
@@ -1051,6 +1071,7 @@ const GENERATED_CONFIG_PATH_BY_KIND = {
 export const SYNC_DOWN_GENERATED_CONFIG_KINDS = ['offerSets'];
 export const EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS = [
     'sync down',
+    'sync rebase',
     'sync up',
     'experiments sync',
     'offer-sets sync',
@@ -2115,15 +2136,27 @@ addExamples(analyticsCommand
 });
 const syncCommand = addExamples(program.command('sync').description('Sync funnel source'), [
     'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
+    'fgrove sync rebase --dir ./claimbee-ios',
     'fgrove sync up --message "Update copy"',
 ]);
+const assertHistoricalSyncBaseline = (input) => {
+    const historical = buildDownloadedSyncManifest({
+        workspaceId: input.manifest.workspaceId,
+        funnelId: input.manifest.funnelId,
+        draftVersionId: input.manifest.draftVersionId,
+        files: input.files,
+    });
+    if (JSON.stringify(historical.files) !== JSON.stringify(input.manifest.files)) {
+        throw Object.assign(new Error('The historical hosted draft no longer matches this local sync baseline. The rebase was not applied; preserve the local directory and contact FunnelsGrove support.'), { code: 'FG-SYNC-REBASE-BASE' });
+    }
+};
 addExamples(syncCommand
     .command('down')
     .description('Download funnel draft source to a local directory')
     .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
     .option('--funnel <id-or-slug>', 'Funnel id or slug')
     .requiredOption('--dir <path>', 'Local target directory')
-    .option('--force', 'Overwrite local changes in an existing synced directory'), [
+    .option('--force', 'Replace hosted source paths after saving an automatic local source backup'), [
     'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
 ])
     .action(async (options) => {
@@ -2134,8 +2167,11 @@ addExamples(syncCommand
         funnel: options.funnel,
         dir: options.dir,
     });
-    if (!options.force && target.manifest && await hasLocalSourceChanges(target.sourceDir, target.manifest)) {
-        throw new Error('Local sync directory has unuploaded changes. Commit, stash, sync up, or merge them before `fgrove sync down`; pass `--force` only if overwriting local changes is intentional.');
+    const hasLocalChanges = target.manifest
+        ? await hasLocalSourceChanges(target.sourceDir, target.manifest)
+        : false;
+    if (!options.force && hasLocalChanges) {
+        throw new Error('Local sync directory has unuploaded changes. Run `fgrove sync rebase --dir <path>` to preserve them, or pass `--force` only if replacing hosted source paths is intentional; force creates an automatic backup.');
     }
     const result = await callApi({
         path: 'funnels.exportSource',
@@ -2152,6 +2188,16 @@ addExamples(syncCommand
         draftVersionId: result.draftVersionId,
         files: result.files,
     });
+    if (options.force && target.manifest && hasLocalChanges) {
+        const localFiles = await collectSourceFiles(target.sourceDir);
+        const backupPath = await writeSourceRebaseBackup({
+            rootDir: target.sourceDir,
+            files: localFiles,
+            manifest: target.manifest,
+            remoteDraftVersionId: result.draftVersionId,
+        });
+        console.log(`Saved the pre-force source backup to ${path.join(target.sourceDir, backupPath)}`);
+    }
     await mkdir(target.sourceDir, { recursive: true });
     await writeSourceFiles(target.sourceDir, result.files);
     const generatedFiles = await syncGeneratedConfigFilesForCli({
@@ -2163,7 +2209,7 @@ addExamples(syncCommand
     await ensureGitignore(target.sourceDir);
     await runSyncDownLocalLifecycle({
         recoverMigration: async () => recoverStepContractV2Migration(target.sourceDir),
-        recoverDocs: async () => recoverTemplateDocs(target.sourceDir),
+        recoverDocs: async () => repairDownloadedManagedFiles(target.sourceDir),
         refreshDocs: async () => {
             const docs = await executeDocsCommand({
                 targetDir: target.sourceDir,
@@ -2180,6 +2226,115 @@ addExamples(syncCommand
     console.log(`Synced ${result.files.length} files to ${target.sourceDir}`);
     console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
 });
+addExamples(syncCommand
+    .command('rebase')
+    .description('Merge local source changes onto the latest hosted draft without discarding them')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--funnel <id-or-slug>', 'Funnel id or slug')
+    .option('--dir <path>', 'Local funnel directory', '.'), [
+    'fgrove sync rebase',
+    'fgrove sync rebase --dir ./claimbee-ios',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    if (!target.manifest) {
+        throw Object.assign(new Error('No local sync baseline found. Run `fgrove sync down` into a new directory before rebasing.'), { code: 'FG-SYNC-REBASE-BASE' });
+    }
+    const remote = await callApi({
+        path: 'funnels.exportSource',
+        type: 'query',
+        token,
+        data: {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+        },
+    });
+    if (remote.draftVersionId === target.manifest.draftVersionId) {
+        console.log(`Local source is already based on hosted draft ${remote.draftVersionId}; no rebase is needed.`);
+        return;
+    }
+    const base = await callApi({
+        path: 'funnels.exportSource',
+        type: 'query',
+        token,
+        data: {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+            versionId: target.manifest.draftVersionId,
+        },
+    });
+    if (base.draftVersionId !== target.manifest.draftVersionId) {
+        throw Object.assign(new Error('The hosted historical export returned the wrong sync baseline. The rebase was not applied.'), { code: 'FG-SYNC-REBASE-BASE' });
+    }
+    assertHistoricalSyncBaseline({ manifest: target.manifest, files: base.files });
+    const localFiles = await collectSourceFiles(target.sourceDir);
+    const merged = await rebaseSourceFiles({
+        baseFiles: base.files,
+        localFiles,
+        remoteFiles: remote.files,
+        remoteOwnedPaths: await loadManagedSyncPaths(),
+        mergeText: mergeTextSourceWithGit,
+    });
+    if (merged.conflicts.length > 0) {
+        const conflictLines = merged.conflicts.map((conflict) => `  ${conflict.kind.padEnd(15)} ${conflict.path}`);
+        throw Object.assign(new Error([
+            `Rebase found ${merged.conflicts.length} conflicting ${merged.conflicts.length === 1 ? 'path' : 'paths'}; no local files were changed.`,
+            ...conflictLines,
+            'Resolve these paths against a fresh sync directory, or commit the local work and retry after reconciling the overlapping edits.',
+        ].join('\n')), { code: 'FG-SYNC-REBASE-CONFLICT' });
+    }
+    const backupPath = await writeSourceRebaseBackup({
+        rootDir: target.sourceDir,
+        files: localFiles,
+        manifest: target.manifest,
+        remoteDraftVersionId: remote.draftVersionId,
+    });
+    console.log(`Saved the pre-rebase source backup to ${path.join(target.sourceDir, backupPath)}`);
+    const downloadedSyncManifest = buildDownloadedSyncManifest({
+        workspaceId: target.workspaceId,
+        funnelId: target.funnelId,
+        draftVersionId: remote.draftVersionId,
+        files: remote.files,
+    });
+    await replaceSourceFiles({
+        rootDir: target.sourceDir,
+        currentFiles: localFiles,
+        nextFiles: merged.files,
+    });
+    const generatedFiles = await syncGeneratedConfigFilesForCli({
+        token,
+        target,
+        kinds: SYNC_DOWN_GENERATED_CONFIG_KINDS,
+    });
+    await writeLocalEnvFile(target.sourceDir, remote.envFile);
+    await ensureGitignore(target.sourceDir);
+    await runSyncDownLocalLifecycle({
+        recoverMigration: async () => recoverStepContractV2Migration(target.sourceDir),
+        recoverDocs: async () => repairDownloadedManagedFiles(target.sourceDir),
+        refreshDocs: async () => {
+            const docs = await executeDocsCommand({
+                targetDir: target.sourceDir,
+                options: { json: true },
+            });
+            if (docs.exitCode !== 0) {
+                const output = JSON.parse(docs.output);
+                const diagnostic = output.diagnostics?.[0];
+                throw new CliContractError(diagnostic?.code ?? 'FG-DOC-001', diagnostic?.message ?? 'Managed documentation refresh failed after sync rebase.');
+            }
+        },
+        writeSyncState: async () => writeSyncManifest(target.sourceDir, downloadedSyncManifest),
+    });
+    const localChanges = await collectChangedSourceFiles(target.sourceDir, downloadedSyncManifest);
+    console.log(`Rebased ${localChanges.files.length + localChanges.deletedPaths.length} local changes onto hosted draft ${remote.draftVersionId}.`);
+    console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
+    console.log('Run `fgrove validate`, review the diff, then run `fgrove sync up`.');
+});
 const envCommand = addExamples(program.command('env').description('Manage local funnel environment files'), [
     'fgrove env pull --dir ./claimbee-ios',
 ]);
@@ -2528,13 +2683,25 @@ addExamples(program
     .command('validate')
     .description('Validate a local funnel against the current authoring contract')
     .option('--dir <path>', 'Local funnel directory', '.')
+    .option('--repair-managed', 'Restore CLI-owned docs and validator files before validation')
     .option('--json', 'Emit one machine-readable validation object'), [
     'fgrove validate',
+    'fgrove validate --repair-managed',
     'fgrove validate --dir ./claimbee-ios --json',
 ])
     .action(async (options) => {
+    const targetDir = path.resolve(process.cwd(), options.dir);
+    if (options.repairManaged === true) {
+        await repairDownloadedManagedFiles(targetDir);
+        const docs = await executeDocsCommand({ targetDir, options: { json: true } });
+        if (docs.exitCode !== 0) {
+            const output = JSON.parse(docs.output);
+            const diagnostic = output.diagnostics?.[0];
+            throw new CliContractError(diagnostic?.code ?? 'FG-DOC-001', diagnostic?.message ?? 'Managed files could not be repaired.');
+        }
+    }
     const result = await executeValidateCommand({
-        targetDir: path.resolve(process.cwd(), options.dir),
+        targetDir,
         json: options.json,
     });
     process.stdout.write(result.output);

package/dist/localSync.d.ts

@@ -30,6 +30,24 @@ export type SourceFilePatchBatch = {
     deletedPaths: string[];
     files: SourceFile[];
 };
+export type SourceRebaseConflictKind = 'add-add' | 'delete-modify' | 'modify-delete' | 'modify-modify';
+export type SourceRebaseConflict = {
+    path: string;
+    kind: SourceRebaseConflictKind;
+};
+export type SourceTextMerge = (input: {
+    path: string;
+    base: string;
+    local: string;
+    remote: string;
+}) => Promise<{
+    content: string;
+    clean: boolean;
+}>;
+export type SourceRebaseResult = {
+    files: SourceFile[];
+    conflicts: SourceRebaseConflict[];
+};
 export type SourceCandidateOperation = {
     type: 'create' | 'modify';
     path: string;
@@ -86,6 +104,7 @@ export type SyncDownLocalLifecycle = {
 export declare function runSyncDownLocalLifecycle(lifecycle: SyncDownLocalLifecycle): Promise<void>;
 export declare const assertSafeRootFileWriteTarget: (rootDir: string, relativePath: string) => Promise<void>;
 export declare const readSafeRootFile: (rootDir: string, relativePath: string) => Promise<Buffer>;
+export declare const removeSafeRootFile: (rootDir: string, relativePath: string) => Promise<void>;
 export declare const writeSafeRootFile: (rootDir: string, relativePath: string, content: string | Buffer, hooks?: SafeRootWriteHooks) => Promise<void>;
 export declare function normalizeSyncPath(filePath: string): string;
 export declare function assertSafeSyncPath(filePath: string): string;
@@ -109,6 +128,24 @@ export declare function collectSourceSnapshot(rootDir: string): Promise<{
     sourceFiles: SourceFile[];
 }>;
 export declare function collectSourceFiles(rootDir: string): Promise<SourceFile[]>;
+export declare function rebaseSourceFiles(input: {
+    baseFiles: readonly SourceFile[];
+    localFiles: readonly SourceFile[];
+    remoteFiles: readonly SourceFile[];
+    remoteOwnedPaths?: ReadonlySet<string>;
+    mergeText?: SourceTextMerge;
+}): Promise<SourceRebaseResult>;
+export declare function replaceSourceFiles(input: {
+    rootDir: string;
+    currentFiles: readonly SourceFile[];
+    nextFiles: readonly SourceFile[];
+}): Promise<void>;
+export declare function writeSourceRebaseBackup(input: {
+    rootDir: string;
+    files: readonly SourceFile[];
+    manifest: SyncManifest;
+    remoteDraftVersionId: string;
+}): Promise<string>;
 export declare function collectChangedSourceFiles(rootDir: string, previousManifest: SyncManifest): Promise<ChangedSourceFiles>;
 export declare function hasLocalSourceChanges(rootDir: string, previousManifest: SyncManifest): Promise<boolean>;
 export declare function chunkChangedSourceFiles(changes: Pick<ChangedSourceFiles, 'deletedPaths' | 'files'>, maxContentChars?: number): SourceFilePatchBatch[];

package/dist/localSync.js

@@ -186,6 +186,23 @@ export const readSafeRootFile = async (rootDir, relativePath) => {
         await handle.close();
     }
 };
+export const removeSafeRootFile = async (rootDir, relativePath) => {
+    const resolvedRoot = await resolveSafeRoot(rootDir, false);
+    const absolutePath = await assertSafeExistingPath(resolvedRoot, relativePath, false, true);
+    try {
+        const metadata = await lstat(absolutePath);
+        if (metadata.isSymbolicLink() || !metadata.isFile()) {
+            throw sourceCandidateInvariantError(`Local sync path is not a regular file: ${relativePath}`);
+        }
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    await rm(absolutePath);
+    await syncDirectory(path.dirname(absolutePath));
+};
 export const writeSafeRootFile = async (rootDir, relativePath, content, hooks = {}) => {
     const resolvedRoot = await resolveSafeRoot(rootDir, true);
     const absolutePath = await assertSafeExistingPath(resolvedRoot, relativePath, true, false, hooks);
@@ -365,6 +382,119 @@ export async function collectSourceSnapshot(rootDir) {
 export async function collectSourceFiles(rootDir) {
     return (await collectSourceSnapshot(rootDir)).sourceFiles;
 }
+const sourceFileBytes = (file) => (decodeBinarySourceContent(file) ?? Buffer.from(file.content, 'utf8'));
+const sourceFilesEqual = (left, right) => {
+    if (!left || !right)
+        return left === right;
+    return sourceFileBytes(left).equals(sourceFileBytes(right));
+};
+const mapSourceFiles = (files, label) => {
+    const output = new Map();
+    const pathByFolded = new Map();
+    for (const file of files) {
+        const filePath = assertSafeSyncTargetPath(file.path);
+        const folded = filePath.toLocaleLowerCase('en-US');
+        const previousPath = pathByFolded.get(folded);
+        if (previousPath) {
+            throw sourceCandidateInvariantError(`${label} source repeats or case-collides at: ${previousPath}, ${filePath}`);
+        }
+        pathByFolded.set(folded, filePath);
+        output.set(filePath, file);
+    }
+    return output;
+};
+const isTextSourceFile = (file) => (decodeBinarySourceContent(file) === null && !Buffer.from(file.content, 'utf8').includes(0));
+export async function rebaseSourceFiles(input) {
+    const base = mapSourceFiles(input.baseFiles, 'Base');
+    const local = mapSourceFiles(input.localFiles, 'Local');
+    const remote = mapSourceFiles(input.remoteFiles, 'Remote');
+    const paths = Array.from(new Set([...base.keys(), ...local.keys(), ...remote.keys()]))
+        .sort((left, right) => left.localeCompare(right));
+    const files = [];
+    const conflicts = [];
+    for (const filePath of paths) {
+        const baseFile = base.get(filePath);
+        const localFile = local.get(filePath);
+        const remoteFile = remote.get(filePath);
+        if (input.remoteOwnedPaths?.has(filePath)) {
+            if (remoteFile)
+                files.push(remoteFile);
+            continue;
+        }
+        if (sourceFilesEqual(localFile, remoteFile)) {
+            if (localFile)
+                files.push(localFile);
+            continue;
+        }
+        if (sourceFilesEqual(localFile, baseFile)) {
+            if (remoteFile)
+                files.push(remoteFile);
+            continue;
+        }
+        if (sourceFilesEqual(remoteFile, baseFile)) {
+            if (localFile)
+                files.push(localFile);
+            continue;
+        }
+        if (!baseFile) {
+            conflicts.push({ path: filePath, kind: 'add-add' });
+            continue;
+        }
+        if (!localFile) {
+            conflicts.push({ path: filePath, kind: 'delete-modify' });
+            continue;
+        }
+        if (!remoteFile) {
+            conflicts.push({ path: filePath, kind: 'modify-delete' });
+            continue;
+        }
+        if (input.mergeText
+            && isTextSourceFile(baseFile)
+            && isTextSourceFile(localFile)
+            && isTextSourceFile(remoteFile)) {
+            const merged = await input.mergeText({
+                path: filePath,
+                base: sourceFileBytes(baseFile).toString('utf8'),
+                local: sourceFileBytes(localFile).toString('utf8'),
+                remote: sourceFileBytes(remoteFile).toString('utf8'),
+            });
+            if (merged.clean) {
+                files.push({ path: filePath, content: merged.content, contentType: 'text/plain' });
+                continue;
+            }
+        }
+        conflicts.push({ path: filePath, kind: 'modify-modify' });
+    }
+    return { files, conflicts };
+}
+export async function replaceSourceFiles(input) {
+    const current = mapSourceFiles(input.currentFiles, 'Current');
+    const next = mapSourceFiles(input.nextFiles, 'Next');
+    const deletedPaths = Array.from(current.keys())
+        .filter((filePath) => !next.has(filePath))
+        .sort((left, right) => left.localeCompare(right));
+    for (const filePath of deletedPaths) {
+        await removeSafeRootFile(input.rootDir, filePath);
+    }
+    await writeSourceFiles(input.rootDir, Array.from(next.values()));
+}
+export async function writeSourceRebaseBackup(input) {
+    mapSourceFiles(input.files, 'Backup');
+    const backupId = `${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID()}`;
+    const backupRoot = `.funnelsgrove/rebase-backups/${backupId}`;
+    for (const file of input.files) {
+        await writeSafeRootFile(input.rootDir, `${backupRoot}/source/${file.path}`, sourceFileBytes(file));
+    }
+    await writeSafeRootFile(input.rootDir, `${backupRoot}/metadata.json`, `${JSON.stringify({
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        baseDraftVersionId: input.manifest.draftVersionId,
+        remoteDraftVersionId: input.remoteDraftVersionId,
+        sourcePaths: input.files.map((file) => file.path).sort((left, right) => left.localeCompare(right)),
+        syncManifest: input.manifest,
+    }, null, 2)}\n`);
+    return backupRoot;
+}
 export async function collectChangedSourceFiles(rootDir, previousManifest) {
     const currentManifest = await buildSyncManifest(rootDir, {
         workspaceId: previousManifest.workspaceId,

package/dist/sourceRebase.d.ts

@@ -0,0 +1,2 @@
+import type { SourceTextMerge } from './localSync.js';
+export declare const mergeTextSourceWithGit: SourceTextMerge;

package/dist/sourceRebase.js

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+const MAX_MERGE_OUTPUT_BYTES = 15 * 1024 * 1024;
+const runGitMergeFile = async (input) => new Promise((resolve, reject) => {
+    const child = spawn('git', [
+        'merge-file',
+        '--stdout',
+        '--diff3',
+        '-L', 'LOCAL',
+        '-L', 'BASE',
+        '-L', 'REMOTE',
+        input.localPath,
+        input.basePath,
+        input.remotePath,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    let outputBytes = 0;
+    child.stdout.on('data', (chunk) => {
+        outputBytes += chunk.length;
+        if (outputBytes > MAX_MERGE_OUTPUT_BYTES) {
+            child.kill('SIGKILL');
+            return;
+        }
+        stdout.push(chunk);
+    });
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', (error) => {
+        reject(new Error(error.code === 'ENOENT'
+            ? 'fgrove sync rebase requires Git for overlapping text-file changes.'
+            : `Unable to run git merge-file: ${error.message}`));
+    });
+    child.once('close', (code) => {
+        if (outputBytes > MAX_MERGE_OUTPUT_BYTES) {
+            reject(new Error('Merged file exceeds the 15 MiB safety limit.'));
+            return;
+        }
+        if (code !== 0 && code !== 1) {
+            reject(new Error(`git merge-file failed${stderr.length > 0 ? `: ${Buffer.concat(stderr).toString('utf8').trim()}` : '.'}`));
+            return;
+        }
+        resolve({
+            content: Buffer.concat(stdout).toString('utf8'),
+            clean: code === 0,
+        });
+    });
+});
+export const mergeTextSourceWithGit = async (input) => {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), 'fgrove-rebase-'));
+    const localPath = path.join(tempDir, 'local');
+    const basePath = path.join(tempDir, 'base');
+    const remotePath = path.join(tempDir, 'remote');
+    try {
+        await Promise.all([
+            writeFile(localPath, input.local),
+            writeFile(basePath, input.base),
+            writeFile(remotePath, input.remote),
+        ]);
+        return await runGitMergeFile({ localPath, basePath, remotePath });
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+};

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.66",
+      "repositoryCliVersion": "0.1.68",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.55",
+        "bundleVersion": "2.0.57",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
+            "sha256": "d1defd086fb3d785e49ec5dd2114d493261a3bba14f6f9c4c8cd38285c563056"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
+            "sha256": "6e29f38b19aaf964d22ad205ca766a7a54c6b5c998892700e16103451adfec43"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.65",
+      "repositoryCliVersion": "0.1.67",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.54",
+        "bundleVersion": "2.0.56",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "1efb49d4c6adf05d1d64524110d4a651ad63b32c1862899d10cf4a9a56d50a41"
+            "sha256": "3f89ff9d4d5501c6d3562f4d60d5d2fbc46d0069866353d0fe9a899e4690ac24"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "f52545efb1bc7fdf11ae4a792feb3b0eb50c45a01a08036136242bbd483162f2"
+            "sha256": "44a40a7630f8ffd287390886d48461cbfb982160daaa9c77a816fbdf446df683"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.64",
+      "repositoryCliVersion": "0.1.66",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.53",
+        "bundleVersion": "2.0.55",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "7488bcd0e73a7070aea003f5f5cbb2be59e63fad1e48c32e136c5a2e9f7f5360"
+            "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "cf2e7c92984818a28baa7ee330f5979225dc0b5a66aed8a25ffec89a11137e4b"
+            "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.64",
+      "repositoryCliVersion": "0.1.65",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.52",
+        "bundleVersion": "2.0.54",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "7488bcd0e73a7070aea003f5f5cbb2be59e63fad1e48c32e136c5a2e9f7f5360"
+            "sha256": "1efb49d4c6adf05d1d64524110d4a651ad63b32c1862899d10cf4a9a56d50a41"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "63df77a196cbbf761f46bd5256dcca81fa933d49f3faf9f00619b33ec3cbf96a"
+            "sha256": "f52545efb1bc7fdf11ae4a792feb3b0eb50c45a01a08036136242bbd483162f2"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.62",
+      "repositoryCliVersion": "0.1.64",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.51",
+        "bundleVersion": "2.0.53",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "10cd5853ffbe09a300fe222b18d1f7d7c1dd0f61a02693dd8e6d586b283f2121"
+            "sha256": "7488bcd0e73a7070aea003f5f5cbb2be59e63fad1e48c32e136c5a2e9f7f5360"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "06c7a3e1b2885129c83e8dd405a9d37ef6f87a14702d92c420772e5bf733f9cc"
+            "sha256": "cf2e7c92984818a28baa7ee330f5979225dc0b5a66aed8a25ffec89a11137e4b"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.61",
+      "repositoryCliVersion": "0.1.64",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.50",
+        "bundleVersion": "2.0.52",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "88942be6d27cf6f8526d01dfbf143948dd7f82f4b9a17469e18243900a736139"
+            "sha256": "7488bcd0e73a7070aea003f5f5cbb2be59e63fad1e48c32e136c5a2e9f7f5360"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "a39599a33bdbed2eaa5660371d25912dae392a5cefda40798014bd8b933db50e"
+            "sha256": "63df77a196cbbf761f46bd5256dcca81fa933d49f3faf9f00619b33ec3cbf96a"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.60",
+      "repositoryCliVersion": "0.1.62",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.49",
+        "bundleVersion": "2.0.51",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "f0294b0f21fc24ab69d2f41917869a885a5901d6138d25df11140174e4fb4e72"
+            "sha256": "10cd5853ffbe09a300fe222b18d1f7d7c1dd0f61a02693dd8e6d586b283f2121"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -947,7 +947,7 @@
           },
           {
             "path": "docs/funnelsgrove/recipes/add-experiment.md",
-            "sha256": "dda3f6d812a18ec6be690f76ba82a520ba9e07b4a23f2278e14a0eecb801c729"
+            "sha256": "c63a0f15884b2bf5d65f28d127345bd97641a7b38d047907d6d66f091e15a44a"
           },
           {
             "path": "docs/funnelsgrove/recipes/add-step.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "70200599749b518b879b32539ea67ada93bd138237c1a5fab57d64203c06cda1"
+            "sha256": "06c7a3e1b2885129c83e8dd405a9d37ef6f87a14702d92c420772e5bf733f9cc"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",

package/template_docs/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.55",
+  "bundleVersion": "2.0.57",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
+      "sha256": "d1defd086fb3d785e49ec5dd2114d493261a3bba14f6f9c4c8cd38285c563056"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
+      "sha256": "6e29f38b19aaf964d22ad205ca766a7a54c6b5c998892700e16103451adfec43"
     }
   ]
 }

package/template_docs/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/runtime` `0.7.2` first, then `@funnelsgrove/analytics` `0.1.51`, then `@funnelsgrove/payments` `0.7.1`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.66`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.7.2` first, then `@funnelsgrove/analytics` `0.1.51`, then `@funnelsgrove/payments` `0.7.1`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.68`. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_docs/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.55",
+  "bundleVersion": "2.0.57",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.55",
+  "bundleVersion": "2.0.57",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
+      "sha256": "d1defd086fb3d785e49ec5dd2114d493261a3bba14f6f9c4c8cd38285c563056"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
+      "sha256": "6e29f38b19aaf964d22ad205ca766a7a54c6b5c998892700e16103451adfec43"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "2f00440db8705e5bf141bc11b7855a4f699cbf18b4b9fda9a6bdf5b5a454bd41",
+  "sourceTreeHash": "673367bb11c9f955f1b3b428596f478b2dad9344d474106a525bfbad43c76c0f",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.55",
+  "docsBundleVersion": "2.0.57",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "56200ed2898a5fca164d6932cc62a440195b3251a85940248b1c7bad9211556c",
+      "sha256": "8670d5374613fb4055e850bb7a85da7817aa8613d41ec2859d44ae792bb1440d",
       "mode": "100644"
     },
     {
@@ -101,7 +101,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f",
+      "sha256": "d1defd086fb3d785e49ec5dd2114d493261a3bba14f6f9c4c8cd38285c563056",
       "mode": "100644"
     },
     {
@@ -236,7 +236,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959",
+      "sha256": "6e29f38b19aaf964d22ad205ca766a7a54c6b5c998892700e16103451adfec43",
       "mode": "100644"
     },
     {
@@ -916,7 +916,7 @@
     },
     {
       "path": "tests/funnel-agent-docs.test.ts",
-      "sha256": "606c5737c5a298507adbda00ab88333152404ee102c73d0f23b85bc87e2675be",
+      "sha256": "27c7d7f3fca1dfea5b3884c6f6fcff549f226bc8d69215880edc329757dc5210",
       "mode": "100644"
     },
     {

package/template_scaffold/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/runtime` `0.7.2` first, then `@funnelsgrove/analytics` `0.1.51`, then `@funnelsgrove/payments` `0.7.1`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.66`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.7.2` first, then `@funnelsgrove/analytics` `0.1.51`, then `@funnelsgrove/payments` `0.7.1`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.68`. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_scaffold/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.55",
+  "bundleVersion": "2.0.57",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/tests/funnel-agent-docs.test.ts

@@ -363,7 +363,7 @@ describe('funnel agent documentation supply', () => {
 
     expect(manifest).toMatchObject({
       schemaVersion: 1,
-      bundleVersion: '2.0.55',
+      bundleVersion: '2.0.57',
       stepContractVersion: contract.stepContractVersion,
       contractHash: contract.contractHash,
     });