@funnelsgrove/cli 0.1.66 → 0.1.67

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;

package/dist/cli.js

@@ -481,7 +481,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 +502,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 +512,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 +523,15 @@ 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 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');
@@ -2163,7 +2172,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,
@@ -2528,13 +2537,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/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.66",
+      "repositoryCliVersion": "0.1.67",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.55",
+        "bundleVersion": "2.0.56",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
+            "sha256": "3f89ff9d4d5501c6d3562f4d60d5d2fbc46d0069866353d0fe9a899e4690ac24"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
+            "sha256": "44a40a7630f8ffd287390886d48461cbfb982160daaa9c77a816fbdf446df683"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.65",
+      "repositoryCliVersion": "0.1.66",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.54",
+        "bundleVersion": "2.0.55",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "1efb49d4c6adf05d1d64524110d4a651ad63b32c1862899d10cf4a9a56d50a41"
+            "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "f52545efb1bc7fdf11ae4a792feb3b0eb50c45a01a08036136242bbd483162f2"
+            "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.64",
+      "repositoryCliVersion": "0.1.65",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.53",
+        "bundleVersion": "2.0.54",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "7488bcd0e73a7070aea003f5f5cbb2be59e63fad1e48c32e136c5a2e9f7f5360"
+            "sha256": "1efb49d4c6adf05d1d64524110d4a651ad63b32c1862899d10cf4a9a56d50a41"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,7 +439,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "cf2e7c92984818a28baa7ee330f5979225dc0b5a66aed8a25ffec89a11137e4b"
+            "sha256": "f52545efb1bc7fdf11ae4a792feb3b0eb50c45a01a08036136242bbd483162f2"
           }
         ]
       }
@@ -448,7 +448,7 @@
       "repositoryCliVersion": "0.1.64",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.52",
+        "bundleVersion": "2.0.53",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "63df77a196cbbf761f46bd5256dcca81fa933d49f3faf9f00619b33ec3cbf96a"
+            "sha256": "cf2e7c92984818a28baa7ee330f5979225dc0b5a66aed8a25ffec89a11137e4b"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.62",
+      "repositoryCliVersion": "0.1.64",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.51",
+        "bundleVersion": "2.0.52",
         "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": "63df77a196cbbf761f46bd5256dcca81fa933d49f3faf9f00619b33ec3cbf96a"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.61",
+      "repositoryCliVersion": "0.1.62",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.50",
+        "bundleVersion": "2.0.51",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "88942be6d27cf6f8526d01dfbf143948dd7f82f4b9a17469e18243900a736139"
+            "sha256": "10cd5853ffbe09a300fe222b18d1f7d7c1dd0f61a02693dd8e6d586b283f2121"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "a39599a33bdbed2eaa5660371d25912dae392a5cefda40798014bd8b933db50e"
+            "sha256": "06c7a3e1b2885129c83e8dd405a9d37ef6f87a14702d92c420772e5bf733f9cc"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.60",
+      "repositoryCliVersion": "0.1.61",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.49",
+        "bundleVersion": "2.0.50",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "f0294b0f21fc24ab69d2f41917869a885a5901d6138d25df11140174e4fb4e72"
+            "sha256": "88942be6d27cf6f8526d01dfbf143948dd7f82f4b9a17469e18243900a736139"
           },
           {
             "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": "a39599a33bdbed2eaa5660371d25912dae392a5cefda40798014bd8b933db50e"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "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.56",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
+      "sha256": "3f89ff9d4d5501c6d3562f4d60d5d2fbc46d0069866353d0fe9a899e4690ac24"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
+      "sha256": "44a40a7630f8ffd287390886d48461cbfb982160daaa9c77a816fbdf446df683"
     }
   ]
 }

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.67`. 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.56",
   "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.56",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f"
+      "sha256": "3f89ff9d4d5501c6d3562f4d60d5d2fbc46d0069866353d0fe9a899e4690ac24"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959"
+      "sha256": "44a40a7630f8ffd287390886d48461cbfb982160daaa9c77a816fbdf446df683"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "2f00440db8705e5bf141bc11b7855a4f699cbf18b4b9fda9a6bdf5b5a454bd41",
+  "sourceTreeHash": "da47d4b45148058b3485786ebf529164773f845391a1ca1ce896b38606651bb5",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.55",
+  "docsBundleVersion": "2.0.56",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "56200ed2898a5fca164d6932cc62a440195b3251a85940248b1c7bad9211556c",
+      "sha256": "8a7f62f1471af7a5a37e5e1e8123c4f9c64b09a2570ec12f5b8812eeddc145f3",
       "mode": "100644"
     },
     {
@@ -101,7 +101,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c27e6c1a0fcf279e9fb36e53249021f46bb99117e7ae1f5cee3d0861b705395f",
+      "sha256": "3f89ff9d4d5501c6d3562f4d60d5d2fbc46d0069866353d0fe9a899e4690ac24",
       "mode": "100644"
     },
     {
@@ -236,7 +236,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "c4c7bf1252585ecc3eaa0d8f93fdb056a50e0d3ded134c2e32a051dabd247959",
+      "sha256": "44a40a7630f8ffd287390886d48461cbfb982160daaa9c77a816fbdf446df683",
       "mode": "100644"
     },
     {
@@ -916,7 +916,7 @@
     },
     {
       "path": "tests/funnel-agent-docs.test.ts",
-      "sha256": "606c5737c5a298507adbda00ab88333152404ee102c73d0f23b85bc87e2675be",
+      "sha256": "4245b5e7c07fdc15a099e1c2c758b4960e7d43e90abdfb1ac52b5d423b816317",
       "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.67`. 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.56",
   "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.56',
       stepContractVersion: contract.stepContractVersion,
       contractHash: contract.contractHash,
     });