@funnelsgrove/cli 0.1.15 → 0.1.19

package/dist/projectValidator.js

@@ -0,0 +1,208 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { CURRENT_STEP_CONTRACT_VERSION } from '@funnelsgrove/runtime';
+import { createValidationDiagnostic, isValidationDiagnostic, } from './diagnosticOutput.js';
+export const PROJECT_VALIDATOR_TIMEOUT_MS = 120_000;
+export const PROJECT_VALIDATOR_CONTRACT_VERSION = CURRENT_STEP_CONTRACT_VERSION;
+const PROJECT_VALIDATOR_TERMINATION_GRACE_MS = 250;
+const PROJECT_VALIDATOR_PIPE_GRACE_MS = 250;
+const ENVIRONMENT_ALLOWLIST = [
+    'CI',
+    'COLORTERM',
+    'COMSPEC',
+    'HOME',
+    'LANG',
+    'LC_ALL',
+    'PATH',
+    'PATHEXT',
+    'Path',
+    'SystemRoot',
+    'TEMP',
+    'TERM',
+    'TMP',
+    'TMPDIR',
+    'USERPROFILE',
+];
+export const buildProjectValidatorEnvironment = (parentEnv) => ({
+    ...Object.fromEntries(ENVIRONMENT_ALLOWLIST.flatMap((key) => {
+        const value = parentEnv[key];
+        return value === undefined ? [] : [[key, value]];
+    })),
+    npm_config_ignore_scripts: 'true',
+    npm_config_loglevel: 'silent',
+});
+const runProcessWithSpawn = async (request) => new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+    let terminationTimeout;
+    let pipeTimeout;
+    const windows = process.platform === 'win32';
+    const child = spawn(request.command, request.args, {
+        cwd: request.cwd,
+        env: request.env,
+        detached: !windows,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+    });
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timeout);
+        clearTimeout(terminationTimeout);
+        clearTimeout(pipeTimeout);
+        resolve(result);
+    };
+    const killProcessTree = (signal) => {
+        if (!windows && child.pid) {
+            try {
+                process.kill(-child.pid, signal);
+                return;
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    return;
+            }
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // The close/error handlers own completion when the process is already gone.
+        }
+    };
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        killProcessTree('SIGTERM');
+        terminationTimeout = setTimeout(() => {
+            if (windows && child.pid) {
+                try {
+                    const taskkill = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+                        shell: false,
+                        stdio: 'ignore',
+                        windowsHide: true,
+                    });
+                    taskkill.unref();
+                }
+                catch {
+                    killProcessTree('SIGKILL');
+                }
+            }
+            else {
+                killProcessTree('SIGKILL');
+            }
+            pipeTimeout = setTimeout(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+                child.unref();
+                finish({
+                    stdout,
+                    stderr,
+                    exitCode: null,
+                    signal: 'SIGKILL',
+                    timedOut: true,
+                });
+            }, PROJECT_VALIDATOR_PIPE_GRACE_MS);
+        }, PROJECT_VALIDATOR_TERMINATION_GRACE_MS);
+    }, request.timeoutMs);
+    child.once('error', (error) => {
+        finish({ stdout, stderr, exitCode: null, signal: null, timedOut, error });
+    });
+    child.once('close', (exitCode, signal) => {
+        finish({ stdout, stderr, exitCode, signal, timedOut });
+    });
+});
+const protocolDiagnostic = (received) => createValidationDiagnostic({
+    code: 'FG-CLIENT-001',
+    file: 'src/contract/validate-funnel.cli.ts',
+    expected: 'one schemaVersion 1 validator protocol object',
+    received,
+    reason: 'The checked-in project validator did not complete its required protocol.',
+    guide: 'docs/funnelsgrove/qa/local.md',
+    repair: 'Restore the managed validator runner and rerun fgrove validate.',
+});
+const failedResult = (received) => ({
+    schemaVersion: 1,
+    contractVersion: PROJECT_VALIDATOR_CONTRACT_VERSION,
+    valid: false,
+    diagnostics: [protocolDiagnostic(received)],
+    exitCode: 2,
+});
+const PROTOCOL_KEYS = [
+    'schemaVersion',
+    'contractVersion',
+    'valid',
+    'diagnostics',
+];
+const parseProtocol = (stdout) => {
+    let value;
+    try {
+        value = JSON.parse(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const protocol = value;
+    if (Object.keys(protocol).length !== PROTOCOL_KEYS.length
+        || PROTOCOL_KEYS.some((key) => !(key in protocol))
+        || protocol.schemaVersion !== 1
+        || protocol.contractVersion !== PROJECT_VALIDATOR_CONTRACT_VERSION
+        || typeof protocol.valid !== 'boolean'
+        || !Array.isArray(protocol.diagnostics)
+        || !protocol.diagnostics.every(isValidationDiagnostic))
+        return null;
+    return protocol;
+};
+const protocolMatchesExit = (exitCode, protocol) => {
+    if (exitCode === 0)
+        return protocol.valid && protocol.diagnostics.length === 0;
+    if (exitCode === 1 || exitCode === 2) {
+        return !protocol.valid && protocol.diagnostics.length > 0;
+    }
+    return false;
+};
+export const runProjectValidator = async (options) => {
+    const request = {
+        command: 'npm',
+        args: ['run', 'validate:funnel', '--', '--json'],
+        cwd: path.resolve(options.projectDir),
+        env: buildProjectValidatorEnvironment(options.parentEnv ?? process.env),
+        timeoutMs: PROJECT_VALIDATOR_TIMEOUT_MS,
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    };
+    let processResult;
+    try {
+        processResult = await (options.runProcess ?? runProcessWithSpawn)(request);
+    }
+    catch {
+        return failedResult('project validator failed to start');
+    }
+    if (processResult.timedOut)
+        return failedResult('project validator timed out');
+    if (processResult.error)
+        return failedResult('project validator failed to start');
+    const protocol = parseProtocol(processResult.stdout);
+    if (!protocol || !protocolMatchesExit(processResult.exitCode, protocol)) {
+        return failedResult('invalid project validator protocol');
+    }
+    return {
+        schemaVersion: 1,
+        contractVersion: protocol.contractVersion,
+        valid: protocol.valid,
+        diagnostics: protocol.diagnostics,
+        exitCode: processResult.exitCode,
+    };
+};

package/dist/reskin.js

@@ -26,6 +26,23 @@ const replaceInFile = async (filePath, replacements) => {
     }
     return changed;
 };
+const updateJsonFile = async (filePath, update) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(filePath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const next = update(parsed);
+    const currentContent = `${JSON.stringify(parsed, null, 2)}\n`;
+    const nextContent = `${JSON.stringify(next, null, 2)}\n`;
+    if (nextContent === currentContent) {
+        return false;
+    }
+    await writeFile(filePath, nextContent, 'utf8');
+    return true;
+};
 export const reskinFunnel = async (dir, appName) => {
     const kebabName = toKebabCase(appName);
     const updated = [];
@@ -52,7 +69,16 @@ export const reskinFunnel = async (dir, appName) => {
     ])) {
         updated.push('src/config/funnel.config.ts');
     }
-    // 4. Update HTML title if index.html exists
+    // 4. Update canonical funnel config metadata
+    const jsonConfigPath = path.join(dir, 'funnel.config.json');
+    if (await updateJsonFile(jsonConfigPath, (config) => ({
+        ...config,
+        name: appName,
+        description: `${appName} web funnel`,
+    }))) {
+        updated.push('funnel.config.json');
+    }
+    // 5. Update HTML title if index.html exists
     const indexHtmlPath = path.join(dir, 'index.html');
     if (await replaceInFile(indexHtmlPath, [
         { pattern: /<title>[^<]*<\/title>/, replacement: `<title>${appName}</title>` },

package/dist/stepContractMigration.d.ts

@@ -0,0 +1,71 @@
+import { type FunnelContractDiagnostic, type StepContractV2MigrationRule as SemanticMigrationRule } from '@funnelsgrove/runtime';
+export declare const STEP_CONTRACT_V2_REPORT_PATH = ".funnelsgrove/migrations/step-contract-v2-report.json";
+export type StepContractMigrationTargetVersion = 2 | 3;
+export declare const stepContractMigrationReportPath: (targetVersion: StepContractMigrationTargetVersion) => string;
+export type StepContractMigrationMode = 'check' | 'apply';
+export type StepContractMigrationFlags = {
+    check?: boolean;
+    apply?: boolean;
+};
+export type StepContractMigrationRule = SemanticMigrationRule | 'add-name-from-id+restore-reserved-step' | 'upgrade-purchase-terminal' | 'set-step-contract-version';
+export type StepContractMigrationOperation = {
+    path: string;
+    start: number;
+    end: number;
+    beforeHash: string;
+    afterHash: string;
+    rule: StepContractMigrationRule;
+};
+export type StepContractMigrationReport = {
+    schemaVersion: 1;
+    fromVersion: 1 | 2 | null;
+    toVersion: StepContractMigrationTargetVersion;
+    checkedAt: string;
+    operations: readonly StepContractMigrationOperation[];
+    protectedChanges: readonly StepContractMigrationOperation[];
+    diagnostics: readonly FunnelContractDiagnostic[];
+    valid: boolean;
+};
+export type StepContractMigrationCheckOptions = {
+    projectDir: string;
+    checkedAt?: string;
+    managedBundleAvailable: boolean;
+    targetVersion?: StepContractMigrationTargetVersion;
+};
+export type StepContractMigrationCheckResult = {
+    reportPath: string;
+    report: StepContractMigrationReport;
+};
+export type StepContractMigrationValidationResult = {
+    valid: boolean;
+    diagnostics: readonly FunnelContractDiagnostic[];
+};
+export type InstallManagedCandidateContext = {
+    candidateDir: string;
+    report: StepContractMigrationReport;
+};
+export type ValidateMigrationCandidateContext = {
+    candidateDir: string;
+    phase: 'shadow' | 'committed';
+    authoringContractVersion: StepContractMigrationTargetVersion;
+};
+export type StepContractMigrationFaultPoint = 'after-report' | 'after-shadow-created' | 'after-source-edits' | 'after-managed-install' | 'after-shadow-validation' | 'before-stage-file' | 'after-stage-file' | 'after-journal-staged' | 'before-commit-file' | 'after-commit-file' | 'after-manifest-commit' | 'before-committed-validation' | 'after-committed-validation';
+export type StepContractMigrationFaultContext = {
+    path?: string;
+};
+export type StepContractMigrationApplyOptions = StepContractMigrationCheckOptions & {
+    installManagedCandidate: (context: InstallManagedCandidateContext) => Promise<void>;
+    validateCandidate: (context: ValidateMigrationCandidateContext) => Promise<StepContractMigrationValidationResult>;
+    faultInjector?: (point: StepContractMigrationFaultPoint, context: StepContractMigrationFaultContext) => void | Promise<void>;
+};
+export type StepContractMigrationApplyResult = StepContractMigrationCheckResult & {
+    applied: true;
+};
+export declare class StepContractMigrationError extends Error {
+    readonly report?: StepContractMigrationReport;
+    constructor(message: string, report?: StepContractMigrationReport);
+}
+export declare const resolveStepContractMigrationMode: (flags: StepContractMigrationFlags) => StepContractMigrationMode;
+export declare const checkStepContractV2Migration: (options: StepContractMigrationCheckOptions) => Promise<StepContractMigrationCheckResult>;
+export declare const applyStepContractV2Migration: (options: StepContractMigrationApplyOptions) => Promise<StepContractMigrationApplyResult>;
+export declare const recoverStepContractV2Migration: (projectDirectory: string, targetVersion?: StepContractMigrationTargetVersion) => Promise<"none" | "restored">;