@funnelsgrove/cli 0.1.15 → 0.1.18

package/dist/funnelValidation.d.ts

@@ -0,0 +1,14 @@
+import { type FunnelValidationResult } from './diagnosticOutput.js';
+import { type LegacyDocsCatalogEntry } from './docsTransaction.js';
+import { type RunProjectValidatorOptions } from './projectValidator.js';
+type ProjectValidator = (options: Pick<RunProjectValidatorOptions, 'projectDir'>) => Promise<FunnelValidationResult>;
+export type ValidateFunnelOptions = {
+    projectDir: string;
+    bundledDocsDir: string;
+    bundledValidationDir: string;
+    bundledContractPath: string;
+    legacyCatalog?: readonly LegacyDocsCatalogEntry[];
+    runProjectValidator?: ProjectValidator;
+};
+export declare const validateFunnel: (options: ValidateFunnelOptions) => Promise<FunnelValidationResult>;
+export {};

package/dist/funnelValidation.js

@@ -0,0 +1,297 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import ts from 'typescript';
+import { createValidationDiagnostic, isValidationDiagnostic, } from './diagnosticOutput.js';
+import { inspectTemplateDocs, loadBundledDocs, planTemplateDocsUpdate, } from './docsTransaction.js';
+import { PROJECT_VALIDATOR_CONTRACT_VERSION, runProjectValidator as runCheckedInProjectValidator, } from './projectValidator.js';
+const MANIFEST_PATH = 'src/config/funnel.manifest.ts';
+const PROJECT_VALIDATOR_PATH = 'src/contract/funnel-project.validation.ts';
+const VALIDATOR_VITE_CONFIG_PATH = 'src/contract/funnel-validator.vite.config.ts';
+const RUNNER_PATH = 'src/contract/validate-funnel.cli.ts';
+const MANAGED_VALIDATOR_PATHS = [
+    PROJECT_VALIDATOR_PATH,
+    VALIDATOR_VITE_CONFIG_PATH,
+    RUNNER_PATH,
+];
+const RUNNER_SCRIPT = 'vite-node --config src/contract/funnel-validator.vite.config.ts src/contract/validate-funnel.cli.ts';
+const MIGRATION_COMMAND = 'fgrove migrate step-contract --to 3';
+const resultWith = (diagnostics, exitCode, contractVersion = PROJECT_VALIDATOR_CONTRACT_VERSION) => ({
+    schemaVersion: 1,
+    contractVersion,
+    valid: false,
+    diagnostics,
+    exitCode,
+});
+const versionDiagnostic = (code, received, file = MANIFEST_PATH) => createValidationDiagnostic({
+    code,
+    file,
+    expected: `step contract version ${PROJECT_VALIDATOR_CONTRACT_VERSION} with the managed validator runner`,
+    received,
+    reason: code === 'FG-VERSION-001'
+        ? 'The project uses a step contract newer than this CLI supports.'
+        : `The project is not a complete version-${PROJECT_VALIDATOR_CONTRACT_VERSION} authoring checkout.`,
+    guide: 'docs/funnelsgrove/migrations/step-contract-v3.md',
+    repair: `Run ${MIGRATION_COMMAND}, then rerun fgrove validate.`,
+});
+const docsDiagnostic = (code, received, file) => createValidationDiagnostic({
+    code,
+    file,
+    expected: 'the current packaged contract and managed documentation bundle',
+    received,
+    reason: code === 'FG-DOC-002'
+        ? 'Managed documentation conflicts with local content.'
+        : 'Managed contract documentation is missing, stale, or inconsistent.',
+    guide: 'docs/funnelsgrove/START-HERE.md',
+    repair: code === 'FG-DOC-002'
+        ? 'Resolve the managed documentation conflict explicitly before validation.'
+        : 'Run fgrove docs to refresh managed documentation before validation.',
+});
+const clientDiagnostic = (received) => createValidationDiagnostic({
+    code: 'FG-CLIENT-001',
+    file: RUNNER_PATH,
+    expected: 'a complete schemaVersion 1 project validator result',
+    received,
+    reason: 'The local project validator could not provide a trustworthy result.',
+    guide: 'docs/funnelsgrove/qa/local.md',
+    repair: 'Restore the managed validator runner and rerun fgrove validate.',
+});
+const unwrapExpression = (input) => {
+    let expression = input;
+    while (ts.isParenthesizedExpression(expression)
+        || ts.isAsExpression(expression)
+        || ts.isSatisfiesExpression(expression)) {
+        expression = expression.expression;
+    }
+    return expression;
+};
+const importedCurrentVersionBindings = (sourceFile) => {
+    const bindings = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement)
+            || !ts.isStringLiteral(statement.moduleSpecifier)
+            || statement.moduleSpecifier.text !== '@funnelsgrove/runtime'
+            || !statement.importClause?.namedBindings
+            || !ts.isNamedImports(statement.importClause.namedBindings))
+            continue;
+        for (const element of statement.importClause.namedBindings.elements) {
+            if ((element.propertyName?.text ?? element.name.text) === 'CURRENT_STEP_CONTRACT_VERSION') {
+                bindings.add(element.name.text);
+            }
+        }
+    }
+    return bindings;
+};
+const parseAuthoredVersion = (source) => {
+    const sourceFile = ts.createSourceFile(MANIFEST_PATH, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const parseDiagnostics = sourceFile.parseDiagnostics;
+    if (parseDiagnostics?.length)
+        return { version: null, received: 'malformed authored manifest' };
+    const declarations = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.name.text === 'rawFunnelManifest') {
+                declarations.push(declaration);
+            }
+        }
+    }
+    if (declarations.length !== 1 || !declarations[0].initializer) {
+        return { version: null, received: 'missing unique rawFunnelManifest object' };
+    }
+    const initializer = unwrapExpression(declarations[0].initializer);
+    if (!ts.isObjectLiteralExpression(initializer)) {
+        return { version: null, received: 'dynamic rawFunnelManifest value' };
+    }
+    if (initializer.properties.some((property) => {
+        if (ts.isSpreadAssignment(property))
+            return true;
+        const name = 'name' in property ? property.name : undefined;
+        return name !== undefined && ts.isComputedPropertyName(name);
+    })) {
+        return { version: null, received: 'dynamic root manifest property' };
+    }
+    const versionProperties = initializer.properties.filter((property) => {
+        const name = 'name' in property ? property.name : undefined;
+        return name !== undefined
+            && (ts.isIdentifier(name) || ts.isStringLiteral(name))
+            && name.text === 'stepContractVersion';
+    });
+    if (versionProperties.length !== 1 || !ts.isPropertyAssignment(versionProperties[0])) {
+        return { version: null, received: 'missing unique stepContractVersion property' };
+    }
+    const expression = unwrapExpression(versionProperties[0].initializer);
+    if (ts.isNumericLiteral(expression)) {
+        const version = Number(expression.text);
+        return Number.isSafeInteger(version)
+            ? { version, received: version }
+            : { version: null, received: 'invalid stepContractVersion literal' };
+    }
+    if (ts.isIdentifier(expression)
+        && importedCurrentVersionBindings(sourceFile).has(expression.text)) {
+        return {
+            version: PROJECT_VALIDATOR_CONTRACT_VERSION,
+            received: PROJECT_VALIDATOR_CONTRACT_VERSION,
+        };
+    }
+    return { version: null, received: 'dynamic stepContractVersion expression' };
+};
+const inspectAuthoredVersion = async (projectDir) => {
+    try {
+        return parseAuthoredVersion(await readFile(path.join(projectDir, MANIFEST_PATH), 'utf8'));
+    }
+    catch {
+        return { version: null, received: 'missing authored manifest' };
+    }
+};
+const missingValidatorReceived = (file) => file === RUNNER_PATH
+    ? 'missing checked-in validate:funnel runner'
+    : 'missing checked-in managed validator file';
+const inspectCheckedInValidator = async (projectDir, bundledValidationDir) => {
+    let packageValue;
+    try {
+        packageValue = JSON.parse(await readFile(path.join(projectDir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return { valid: false, file: RUNNER_PATH, received: 'missing checked-in validate:funnel runner' };
+    }
+    if (!packageValue || typeof packageValue !== 'object' || Array.isArray(packageValue)) {
+        return { valid: false, file: RUNNER_PATH, received: 'missing checked-in validate:funnel runner' };
+    }
+    const scripts = packageValue.scripts;
+    if (!scripts
+        || typeof scripts !== 'object'
+        || Array.isArray(scripts)
+        || scripts['validate:funnel'] !== RUNNER_SCRIPT) {
+        return { valid: false, file: RUNNER_PATH, received: 'missing checked-in validate:funnel runner' };
+    }
+    for (const file of MANAGED_VALIDATOR_PATHS) {
+        const localPath = path.join(projectDir, ...file.split('/'));
+        const bundledPath = path.join(bundledValidationDir, ...file.split('/'));
+        try {
+            const [localEntry, bundledEntry] = await Promise.all([
+                lstat(localPath),
+                lstat(bundledPath),
+            ]);
+            if (!localEntry.isFile()
+                || localEntry.isSymbolicLink()
+                || !bundledEntry.isFile()
+                || bundledEntry.isSymbolicLink()) {
+                return { valid: false, file, received: missingValidatorReceived(file) };
+            }
+            const [localBytes, bundledBytes] = await Promise.all([
+                readFile(localPath),
+                readFile(bundledPath),
+            ]);
+            if (!localBytes.equals(bundledBytes)) {
+                return { valid: false, file, received: 'modified managed validator file' };
+            }
+        }
+        catch {
+            return { valid: false, file, received: missingValidatorReceived(file) };
+        }
+    }
+    return { valid: true };
+};
+const loadContractSnapshot = async (contractPath) => {
+    let value;
+    try {
+        value = JSON.parse(await readFile(contractPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const contract = value;
+    if (contract.schemaVersion !== 1
+        || contract.stepContractVersion !== PROJECT_VALIDATOR_CONTRACT_VERSION
+        || !Array.isArray(contract.supportedStepContractVersions)
+        || !contract.supportedStepContractVersions.includes(PROJECT_VALIDATOR_CONTRACT_VERSION)
+        || typeof contract.contractHash !== 'string'
+        || !/^[a-f0-9]{64}$/.test(contract.contractHash))
+        return null;
+    return contract;
+};
+const docsFileDiagnostic = (file) => file.action === 'conflict'
+    ? docsDiagnostic('FG-DOC-002', file.state, file.path)
+    : docsDiagnostic('FG-DOC-001', file.state, file.path);
+const inspectStaticDocs = async (options) => {
+    try {
+        const [contract, bundle] = await Promise.all([
+            loadContractSnapshot(options.bundledContractPath),
+            loadBundledDocs(options.bundledDocsDir),
+        ]);
+        if (!contract
+            || contract.stepContractVersion !== bundle.manifest.stepContractVersion
+            || contract.contractHash !== bundle.manifest.contractHash) {
+            return resultWith([
+                docsDiagnostic('FG-DOC-001', 'inconsistent packaged contract bundle', null),
+            ], 2);
+        }
+        const inspection = await inspectTemplateDocs(bundle, options.projectDir, {
+            legacyCatalog: options.legacyCatalog,
+        });
+        const status = planTemplateDocsUpdate(inspection);
+        if (status.clean)
+            return null;
+        const diagnostics = status.files
+            .filter((file) => file.action !== 'none')
+            .map(docsFileDiagnostic);
+        return resultWith(diagnostics.length > 0 ? diagnostics : [
+            docsDiagnostic('FG-DOC-001', 'stale managed documentation manifest', null),
+        ], 1);
+    }
+    catch {
+        return resultWith([
+            docsDiagnostic('FG-DOC-001', 'unreadable packaged or project documentation', null),
+        ], 2);
+    }
+};
+const isCompleteChildResult = (result) => {
+    if (result.schemaVersion !== 1
+        || result.contractVersion !== PROJECT_VALIDATOR_CONTRACT_VERSION
+        || !Array.isArray(result.diagnostics)
+        || !result.diagnostics.every(isValidationDiagnostic))
+        return false;
+    if (result.exitCode === 0)
+        return result.valid && result.diagnostics.length === 0;
+    if (result.exitCode === 1 || result.exitCode === 2) {
+        return !result.valid && result.diagnostics.length > 0;
+    }
+    return false;
+};
+export const validateFunnel = async (options) => {
+    const projectDir = path.resolve(options.projectDir);
+    const authoredVersion = await inspectAuthoredVersion(projectDir);
+    if (authoredVersion.version !== PROJECT_VALIDATOR_CONTRACT_VERSION) {
+        const code = authoredVersion.version !== null
+            && authoredVersion.version > PROJECT_VALIDATOR_CONTRACT_VERSION
+            ? 'FG-VERSION-001'
+            : 'FG-VERSION-002';
+        return resultWith([
+            versionDiagnostic(code, authoredVersion.received),
+        ], 1, authoredVersion.version ?? PROJECT_VALIDATOR_CONTRACT_VERSION);
+    }
+    const validator = await inspectCheckedInValidator(projectDir, path.resolve(options.bundledValidationDir));
+    if (!validator.valid) {
+        return resultWith([
+            versionDiagnostic('FG-VERSION-002', validator.received, validator.file),
+        ], 1);
+    }
+    const staticFailure = await inspectStaticDocs({ ...options, projectDir });
+    if (staticFailure)
+        return staticFailure;
+    let childResult;
+    try {
+        childResult = await (options.runProjectValidator ?? runCheckedInProjectValidator)({
+            projectDir,
+        });
+    }
+    catch {
+        return resultWith([clientDiagnostic('project validator failed to start')], 2);
+    }
+    return isCompleteChildResult(childResult)
+        ? childResult
+        : resultWith([clientDiagnostic('invalid project validator result')], 2);
+};

package/dist/localSync.d.ts

@@ -26,17 +26,96 @@ export type SourceFilePatchBatch = {
     deletedPaths: string[];
     files: SourceFile[];
 };
+export type SourceCandidateOperation = {
+    type: 'create' | 'modify';
+    path: string;
+    content: string;
+    contentType?: string;
+    sha256: string;
+} | {
+    type: 'delete';
+    path: string;
+} | {
+    type: 'rename';
+    path: string;
+    oldPath: string;
+};
+export type SourceCandidateApi<TResult> = {
+    begin: (input: {
+        workspaceId: string;
+        funnelId: string;
+        baseDraftVersionId: string | null;
+        idempotencyKey: string;
+    }) => Promise<{
+        candidateId: string;
+        status: 'staging' | 'validating' | 'committed' | 'aborted' | 'expired' | 'failed';
+        baseDraftVersionId: string | null;
+    }>;
+    stage: (input: {
+        workspaceId: string;
+        candidateId: string;
+        idempotencyKey: string;
+        operations: SourceCandidateOperation[];
+    }) => Promise<unknown>;
+    finalize: (input: {
+        workspaceId: string;
+        candidateId: string;
+        message?: string;
+    }) => Promise<TResult>;
+    abort: (input: {
+        workspaceId: string;
+        candidateId: string;
+    }) => Promise<unknown>;
+};
 export declare const DEFAULT_PATCH_BATCH_CONTENT_CHARS = 12000000;
+export declare const DEFAULT_SOURCE_CANDIDATE_BATCH_CONTENT_BYTES = 12000000;
+export declare const MAX_SOURCE_CANDIDATE_OPERATIONS: number;
+export declare const MAX_SOURCE_CANDIDATE_FILE_BYTES: number;
+export declare const MAX_SOURCE_CANDIDATE_PATH_CHARACTERS = 1024;
+export declare const MAX_SOURCE_CANDIDATE_TOTAL_BYTES: number;
+export type SyncDownLocalLifecycle = {
+    recoverMigration: () => Promise<unknown>;
+    recoverDocs: () => Promise<unknown>;
+    refreshDocs: () => Promise<unknown>;
+    writeSyncState: () => Promise<unknown>;
+};
+export declare function runSyncDownLocalLifecycle(lifecycle: SyncDownLocalLifecycle): Promise<void>;
 export declare function normalizeSyncPath(filePath: string): string;
 export declare function shouldSyncFile(filePath: string): boolean;
 export declare function buildSyncManifest(rootDir: string, input: SyncManifestInput): Promise<SyncManifest>;
+export declare function buildCommittedSyncManifest(input: {
+    workspaceId: string;
+    funnelId: string;
+    draftVersionId: string;
+    files: readonly SyncManifestFile[];
+}): SyncManifest;
 export declare function writeSyncManifest(rootDir: string, manifest: SyncManifest): Promise<void>;
 export declare function ensureGitignore(rootDir: string): Promise<void>;
 export declare function writeLocalEnvFile(rootDir: string, envFile: string | null | undefined): Promise<boolean>;
 export declare function readSyncManifest(rootDir: string): Promise<SyncManifest | null>;
+export declare function collectSourceSnapshot(rootDir: string): Promise<{
+    manifestFiles: SyncManifestFile[];
+    sourceFiles: SourceFile[];
+}>;
 export declare function collectSourceFiles(rootDir: string): Promise<SourceFile[]>;
 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[];
+export declare function buildSourceCandidateOperations(input: {
+    previousFiles: readonly SyncManifestFile[];
+    files: readonly SourceFile[];
+    deletedPaths: readonly string[];
+}): SourceCandidateOperation[];
+export declare function runSourceCandidateSync<TResult>(input: {
+    workspaceId: string;
+    funnelId: string;
+    baseDraftVersionId: string | null;
+    message?: string;
+    operations: readonly SourceCandidateOperation[];
+    api: SourceCandidateApi<TResult>;
+    maxOperationsPerBatch?: number;
+    maxContentBytesPerBatch?: number;
+    signal?: AbortSignal;
+}): Promise<TResult>;
 export declare function formatSyncUploadSummary(changes: Pick<ChangedSourceFiles, 'deletedPaths' | 'files'>, largestFileLimit?: number): string[];
 export declare function writeSourceFiles(rootDir: string, files: SourceFile[]): Promise<void>;