@funnelsgrove/cli 0.1.75 → 0.1.76

package/dist/cli.js

@@ -15,6 +15,7 @@ import { buildCommittedSyncManifest, buildDownloadedSyncManifest, buildSourceCan
 import { mergeTextSourceWithGit } from './sourceRebase.js';
 import { executeExperimentCreate, formatExperimentCreateSuccess, recoverExperimentCreateTransaction, } from './experimentCreate.js';
 import { pullEnvFile } from './envSync.js';
+import { executeEmailPull, executeEmailPush, executeEmailSequencePublish, executeEmailTemplatePublish, executeEmailValidate, } from './emailCommands.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { GitHubSyncTimeoutError, syncGitHubDraftIfConnected, } from './githubSyncFlow.js';
 import { reskinFunnel } from './reskin.js';
@@ -1440,6 +1441,22 @@ const resolveAnalyticsProject = async (input) => {
     }
     return resolveProject(input.token, input.workspaceId, project);
 };
+const resolveEmailCommandScope = async (options) => {
+    const token = await readAuthToken();
+    const workspaceId = await resolveWorkspaceId(token, options.workspace);
+    const project = await resolveAnalyticsProject({
+        token,
+        workspaceId,
+        project: options.project,
+    });
+    return {
+        callApi,
+        token,
+        workspaceId,
+        projectId: project.id,
+        sourceDir: path.resolve(process.cwd(), options.dir),
+    };
+};
 const resolveAnalyticsFunnel = async (input) => {
     const active = await loadActiveContext(getConfigPath());
     const funnel = input.funnel || (active?.workspaceId === input.workspaceId ? active.funnelId : undefined);
@@ -1682,6 +1699,69 @@ addExamples(program
         console.log(`${legacyDiagnostic.code}\t${legacyDiagnostic.message}`);
     }
 });
+const addEmailScopeOptions = (command) => command
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--dir <path>', 'Directory containing the emails folder', '.');
+const emailCommand = addExamples(program.command('email').description('Manage project email drafts'), [
+    'fgrove email pull',
+    'fgrove email validate',
+    'fgrove email push',
+    'fgrove email template publish welcome',
+]);
+addEmailScopeOptions(emailCommand
+    .command('pull')
+    .description('Pull project email drafts into local files'))
+    .action(async (options) => {
+    const result = await executeEmailPull(await resolveEmailCommandScope(options));
+    console.log(`Pulled ${result.templates} templates and ${result.sequences} sequences.`);
+});
+emailCommand
+    .command('validate')
+    .description('Validate local email draft files')
+    .option('--dir <path>', 'Directory containing the emails folder', '.')
+    .action(async (options) => {
+    const result = await executeEmailValidate({
+        sourceDir: path.resolve(process.cwd(), options.dir),
+    });
+    if (result.valid) {
+        console.log('Email files are valid.');
+        return;
+    }
+    for (const item of result.diagnostics) {
+        console.error(`[${item.code}] ${item.file || 'emails'}: ${item.reason}`);
+    }
+    process.exitCode = 1;
+});
+addEmailScopeOptions(emailCommand
+    .command('push')
+    .description('Push local email drafts without publishing'))
+    .action(async (options) => {
+    const result = await executeEmailPush(await resolveEmailCommandScope(options));
+    console.log(`Pushed ${result.templates} templates and ${result.sequences} sequences.`);
+});
+const emailTemplateCommand = emailCommand.command('template').description('Manage email templates');
+addEmailScopeOptions(emailTemplateCommand
+    .command('publish <slug>')
+    .description('Publish one email template explicitly'))
+    .action(async (slug, options) => {
+    await executeEmailTemplatePublish({
+        ...await resolveEmailCommandScope(options),
+        slug,
+    });
+    console.log(`Published email template ${slug}.`);
+});
+const emailSequenceCommand = emailCommand.command('sequence').description('Manage email sequences');
+addEmailScopeOptions(emailSequenceCommand
+    .command('publish <slug>')
+    .description('Publish one email sequence explicitly'))
+    .action(async (slug, options) => {
+    await executeEmailSequencePublish({
+        ...await resolveEmailCommandScope(options),
+        slug,
+    });
+    console.log(`Published email sequence ${slug}.`);
+});
 const projectsCommand = addExamples(program.command('projects').description('Manage projects'), [
     'fgrove projects list',
     'fgrove projects list --workspace acme',

package/dist/emailCommands.d.ts

@@ -0,0 +1,32 @@
+import { type EmailFilesResult } from './emailFiles.js';
+export type EmailCallApi = <T>(input: {
+    path: string;
+    type: 'query' | 'mutation';
+    data?: unknown;
+    token?: string | null;
+}) => Promise<T>;
+type EmailCommandScope = {
+    callApi: EmailCallApi;
+    token: string;
+    workspaceId: string;
+    projectId: string;
+    sourceDir: string;
+};
+export declare function executeEmailPull(scope: EmailCommandScope): Promise<{
+    templates: number;
+    sequences: number;
+}>;
+export declare const executeEmailValidate: (input: {
+    sourceDir: string;
+}) => Promise<EmailFilesResult>;
+export declare function executeEmailPush(scope: EmailCommandScope): Promise<{
+    templates: number;
+    sequences: number;
+}>;
+export declare function executeEmailTemplatePublish(scope: EmailCommandScope & {
+    slug: string;
+}): Promise<unknown>;
+export declare function executeEmailSequencePublish(scope: EmailCommandScope & {
+    slug: string;
+}): Promise<unknown>;
+export {};

package/dist/emailCommands.js

@@ -0,0 +1,269 @@
+import { readEmailFiles, replaceEmailFiles, writeEmailFiles, writeEmailSequenceFile, writeEmailTemplateFile, } from './emailFiles.js';
+const isRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value));
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const hasDraft = (value) => (isRecord(value) && isRecord(value.draft));
+const assertRemoteResource = (value, resource) => {
+    if (!isRecord(value)
+        || typeof value.id !== 'string'
+        || !UUID.test(value.id)
+        || typeof value.slug !== 'string'
+        || typeof value.name !== 'string'
+        || !hasDraft(value)) {
+        throw new Error(`Invalid remote ${resource} resource`);
+    }
+    return value;
+};
+const assertCreatedId = (value, resource) => {
+    if (!isRecord(value) || typeof value.id !== 'string' || !UUID.test(value.id)) {
+        throw new Error(`Invalid created ${resource} ID`);
+    }
+    return value.id;
+};
+const assertRemoteIdentity = (value, resource) => {
+    if (!isRecord(value)
+        || typeof value.id !== 'string'
+        || !UUID.test(value.id)
+        || typeof value.slug !== 'string') {
+        throw new Error(`Invalid remote ${resource} identity`);
+    }
+    return value;
+};
+const assertValidFiles = (result) => {
+    if (result.valid)
+        return;
+    const summary = result.diagnostics
+        .map((item) => `[${item.code}] ${item.file || 'emails'}: ${item.reason}`)
+        .join('\n');
+    throw new Error(`Email files are invalid. Run \`fgrove email validate\`.\n${summary}`);
+};
+const projectData = (scope) => ({
+    workspaceId: scope.workspaceId,
+    projectId: scope.projectId,
+});
+const assertRemoteIdentities = async (scope, input) => {
+    const localWithIds = input.local.filter((item) => item.id !== null);
+    if (localWithIds.length === 0)
+        return new Map();
+    const remote = await scope.callApi({
+        path: `${input.resource}.list`,
+        type: 'query',
+        token: scope.token,
+        data: projectData(scope),
+    });
+    const parsed = remote.map((item) => assertRemoteIdentity(item, input.resource));
+    const remoteSlugs = new Map(parsed.map((item) => [item.id, item.slug]));
+    for (const local of localWithIds) {
+        const remoteSlug = remoteSlugs.get(local.id);
+        if (remoteSlug !== local.slug) {
+            throw new Error(`Email identity mismatch: ID ${local.id} has local slug "${local.slug}" but remote slug ${remoteSlug ? `"${remoteSlug}"` : 'is missing'}.`);
+        }
+    }
+    return new Map(parsed.map((item) => [item.id, item]));
+};
+const canonicalResource = (kind, value) => {
+    if (kind === 'template') {
+        const variables = isRecord(value.draft.variables) ? value.draft.variables : {};
+        return JSON.stringify({
+            name: value.name,
+            subject: value.draft.subject,
+            previewText: value.draft.previewText,
+            html: value.draft.html,
+            text: value.draft.text,
+            variables: Object.fromEntries(Object.entries(variables).sort(([left], [right]) => left.localeCompare(right))),
+        });
+    }
+    const steps = Array.isArray(value.draft.steps) ? value.draft.steps : [];
+    return JSON.stringify({
+        name: value.name,
+        triggerEventType: value.draft.triggerEventType,
+        funnelIds: Array.isArray(value.draft.funnelIds) ? [...new Set(value.draft.funnelIds)].sort() : [],
+        steps: steps.map((step) => isRecord(step) ? {
+            key: step.key,
+            delaySeconds: step.delaySeconds,
+            templateVersionId: step.templateVersionId,
+        } : step),
+        exitEventTypes: Array.isArray(value.draft.exitEventTypes)
+            ? [...new Set(value.draft.exitEventTypes)].sort()
+            : [],
+    });
+};
+const loadCompleteItems = async (scope, input) => {
+    const listed = await scope.callApi({
+        path: `${input.resource}.list`,
+        type: 'query',
+        token: scope.token,
+        data: projectData(scope),
+    });
+    return Promise.all(listed.map(async (item) => {
+        if (hasDraft(item))
+            return assertRemoteResource(item, input.resource);
+        if (!isRecord(item) || typeof item.id !== 'string') {
+            throw new Error(`Invalid ${input.resource}.list response`);
+        }
+        const detail = await scope.callApi({
+            path: `${input.resource}.get`,
+            type: 'query',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                [input.idKey]: item.id,
+            },
+        });
+        return assertRemoteResource(detail[input.detailKey], input.resource);
+    }));
+};
+export async function executeEmailPull(scope) {
+    const [templates, sequences] = await Promise.all([
+        loadCompleteItems(scope, {
+            resource: 'emailTemplates',
+            idKey: 'templateId',
+            detailKey: 'template',
+        }),
+        loadCompleteItems(scope, {
+            resource: 'emailSequences',
+            idKey: 'sequenceId',
+            detailKey: 'sequence',
+        }),
+    ]);
+    await replaceEmailFiles({
+        sourceDir: scope.sourceDir,
+        templates,
+        sequences,
+    });
+    return { templates: templates.length, sequences: sequences.length };
+}
+export const executeEmailValidate = (input) => readEmailFiles(input.sourceDir);
+export async function executeEmailPush(scope) {
+    const files = await readEmailFiles(scope.sourceDir);
+    assertValidFiles(files);
+    await Promise.all([
+        assertRemoteIdentities(scope, {
+            resource: 'emailTemplates',
+            local: files.templates,
+        }),
+        assertRemoteIdentities(scope, {
+            resource: 'emailSequences',
+            local: files.sequences,
+        }),
+    ]);
+    for (const template of files.templates) {
+        if (template.id) {
+            await scope.callApi({
+                path: 'emailTemplates.updateDraft',
+                type: 'mutation',
+                token: scope.token,
+                data: {
+                    ...projectData(scope),
+                    templateId: template.id,
+                    name: template.name,
+                    draft: template.draft,
+                },
+            });
+            continue;
+        }
+        const created = await scope.callApi({
+            path: 'emailTemplates.create',
+            type: 'mutation',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                slug: template.slug,
+                name: template.name,
+                draft: template.draft,
+            },
+        });
+        template.id = assertCreatedId(created, 'email template');
+        await writeEmailTemplateFile(scope.sourceDir, template);
+    }
+    for (const sequence of files.sequences) {
+        if (sequence.id) {
+            await scope.callApi({
+                path: 'emailSequences.updateDraft',
+                type: 'mutation',
+                token: scope.token,
+                data: {
+                    ...projectData(scope),
+                    sequenceId: sequence.id,
+                    name: sequence.name,
+                    draft: sequence.draft,
+                },
+            });
+            continue;
+        }
+        const created = await scope.callApi({
+            path: 'emailSequences.create',
+            type: 'mutation',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                slug: sequence.slug,
+                name: sequence.name,
+                draft: sequence.draft,
+            },
+        });
+        sequence.id = assertCreatedId(created, 'email sequence');
+        await writeEmailSequenceFile(scope.sourceDir, sequence);
+    }
+    await writeEmailFiles({
+        sourceDir: scope.sourceDir,
+        templates: files.templates,
+        sequences: files.sequences,
+    });
+    return { templates: files.templates.length, sequences: files.sequences.length };
+}
+export async function executeEmailTemplatePublish(scope) {
+    return executeEmailPublish(scope, {
+        kind: 'template',
+        resource: 'emailTemplates',
+        idKey: 'templateId',
+    });
+}
+export async function executeEmailSequencePublish(scope) {
+    return executeEmailPublish(scope, {
+        kind: 'sequence',
+        resource: 'emailSequences',
+        idKey: 'sequenceId',
+    });
+}
+const executeEmailPublish = async (scope, input) => {
+    const files = await readEmailFiles(scope.sourceDir);
+    assertValidFiles(files);
+    const resources = input.kind === 'template' ? files.templates : files.sequences;
+    const resource = resources.find((item) => item.slug === scope.slug);
+    if (!resource)
+        throw new Error(`Email ${input.kind} "${scope.slug}" was not found locally.`);
+    if (!resource.id)
+        throw new Error(`Push email ${input.kind} "${scope.slug}" before publishing it.`);
+    const remote = await assertRemoteIdentities(scope, {
+        resource: input.resource,
+        local: [resource],
+    });
+    let remoteResource = remote.get(resource.id);
+    if (remoteResource && !hasDraft(remoteResource)) {
+        const detailKey = input.kind;
+        const detail = await scope.callApi({
+            path: `${input.resource}.get`,
+            type: 'query',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                [input.idKey]: resource.id,
+            },
+        });
+        remoteResource = assertRemoteResource(detail[detailKey], input.resource);
+    }
+    if (!remoteResource
+        || canonicalResource(input.kind, resource)
+            !== canonicalResource(input.kind, remoteResource)) {
+        throw new Error(`Run \`fgrove email push\` before publishing ${input.kind} "${scope.slug}".`);
+    }
+    return scope.callApi({
+        path: `${input.resource}.publish`,
+        type: 'mutation',
+        token: scope.token,
+        data: {
+            ...projectData(scope),
+            [input.idKey]: resource.id,
+        },
+    });
+};

package/dist/emailFiles.d.ts

@@ -0,0 +1,52 @@
+import { type FunnelValidationDiagnostic } from './diagnosticOutput.js';
+export type EmailTemplateVariableType = 'string' | 'number' | 'boolean';
+export type EmailEventType = 'email_captured' | 'purchase_completed' | 'registration_completed';
+export type EmailTemplateDraft = {
+    subject: string;
+    previewText: string | null;
+    html: string;
+    text: string;
+    variables: Record<string, EmailTemplateVariableType>;
+};
+export type EmailTemplateFile = {
+    id: string | null;
+    slug: string;
+    name: string;
+    draft: EmailTemplateDraft;
+};
+export type EmailSequenceStep = {
+    key: string;
+    delaySeconds: number;
+    templateVersionId: string;
+};
+export type EmailSequenceDraft = {
+    triggerEventType: EmailEventType;
+    funnelIds: string[];
+    steps: EmailSequenceStep[];
+    exitEventTypes: EmailEventType[];
+};
+export type EmailSequenceFile = {
+    id: string | null;
+    slug: string;
+    name: string;
+    draft: EmailSequenceDraft;
+};
+export type EmailFilesResult = {
+    valid: boolean;
+    diagnostics: FunnelValidationDiagnostic[];
+    templates: EmailTemplateFile[];
+    sequences: EmailSequenceFile[];
+};
+export declare function readEmailFiles(sourceDir: string): Promise<EmailFilesResult>;
+export declare function writeEmailTemplateFile(sourceDir: string, template: EmailTemplateFile): Promise<void>;
+export declare function writeEmailSequenceFile(sourceDir: string, sequence: EmailSequenceFile): Promise<void>;
+export declare function writeEmailFiles(input: {
+    sourceDir: string;
+    templates: EmailTemplateFile[];
+    sequences: EmailSequenceFile[];
+}): Promise<void>;
+export declare function replaceEmailFiles(input: {
+    sourceDir: string;
+    templates: EmailTemplateFile[];
+    sequences: EmailSequenceFile[];
+}): Promise<void>;

package/dist/emailFiles.js

@@ -0,0 +1,517 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createValidationDiagnostic, } from './diagnosticOutput.js';
+const EMAIL_EVENTS = new Set([
+    'email_captured',
+    'purchase_completed',
+    'registration_completed',
+]);
+const VARIABLE_TYPES = new Set(['string', 'number', 'boolean']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED_VARIABLE_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+const STEP_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TEMPLATE_METADATA_KEYS = new Set([
+    'id',
+    'slug',
+    'name',
+    'subject',
+    'previewText',
+    'variables',
+]);
+const SEQUENCE_KEYS = new Set([
+    'id',
+    'slug',
+    'name',
+    'triggerEventType',
+    'funnelIds',
+    'steps',
+    'exitEventTypes',
+]);
+const SEQUENCE_STEP_KEYS = new Set(['key', 'delaySeconds', 'templateVersionId']);
+const isRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value));
+const assertNoSymlinkPath = async (root, relativePath = '') => {
+    const parts = relativePath ? relativePath.split('/') : [];
+    let current = path.resolve(root);
+    for (const part of ['', ...parts]) {
+        if (part)
+            current = path.join(current, part);
+        try {
+            const metadata = await lstat(current);
+            if (metadata.isSymbolicLink()) {
+                throw new Error(`Managed email path cannot be a symlink: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+};
+const assertWriterSlug = (slug) => {
+    if (slug.length > 80 || !SLUG.test(slug)) {
+        throw new Error(`Invalid email file slug: ${slug}`);
+    }
+};
+const writeAtomic = async (filePath, content) => {
+    const temporaryPath = `${filePath}.tmp-${randomUUID()}`;
+    try {
+        await writeFile(temporaryPath, content, { flag: 'wx' });
+        await rename(temporaryPath, filePath);
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+};
+const diagnostic = (input) => createValidationDiagnostic({
+    ...input,
+    stepId: null,
+    guide: 'Run `fgrove email validate` after repairing the file.',
+});
+const schemaDiagnostic = (file, field, expected, received) => diagnostic({
+    code: 'FG-EMAIL-002',
+    file,
+    reason: `Invalid email field: ${field}`,
+    expected,
+    received,
+    repair: `Set ${field} to the documented email file value.`,
+});
+const missingFileDiagnostic = (file) => diagnostic({
+    code: 'FG-EMAIL-001',
+    file,
+    reason: `Missing required email file: ${file}`,
+    expected: 'file',
+    received: null,
+    repair: `Create ${file}.`,
+});
+const readUtf8 = async (absolutePath, relativePath, diagnostics) => {
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            diagnostics.push(missingFileDiagnostic(relativePath));
+            return null;
+        }
+        throw error;
+    }
+};
+const readJson = async (absolutePath, relativePath, diagnostics) => {
+    const source = await readUtf8(absolutePath, relativePath, diagnostics);
+    if (source === null)
+        return null;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-001',
+            file: relativePath,
+            reason: 'Invalid JSON in email file',
+            expected: 'valid JSON',
+            received: source,
+            repair: `Repair the JSON syntax in ${relativePath}.`,
+        }));
+        return null;
+    }
+};
+const validateExactKeys = (value, allowed, file, diagnostics) => {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            diagnostics.push(schemaDiagnostic(file, key, 'no unknown fields', value[key]));
+        }
+    }
+};
+const validateIdentity = (value, pathSlug, file, diagnostics) => {
+    let valid = true;
+    if (value.id !== null && (typeof value.id !== 'string' || !UUID.test(value.id))) {
+        diagnostics.push(schemaDiagnostic(file, 'id', 'UUID or null', value.id));
+        valid = false;
+    }
+    if (typeof value.slug !== 'string' || value.slug.length > 80 || !SLUG.test(value.slug)) {
+        diagnostics.push(schemaDiagnostic(file, 'slug', 'lowercase kebab-case slug', value.slug));
+        valid = false;
+    }
+    else if (value.slug !== pathSlug) {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-003',
+            file,
+            reason: `Email slug ${value.slug} does not match path slug ${pathSlug}`,
+            expected: pathSlug,
+            received: value.slug,
+            repair: `Restore the path to ${value.slug} or restore slug to ${pathSlug}.`,
+        }));
+        valid = false;
+    }
+    if (typeof value.name !== 'string' || !value.name.trim() || value.name.length > 120) {
+        diagnostics.push(schemaDiagnostic(file, 'name', 'non-empty string up to 120 characters', value.name));
+        valid = false;
+    }
+    else if (value.name !== value.name.trim()) {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-002',
+            file,
+            reason: 'Email name contains surrounding whitespace',
+            expected: value.name.trim(),
+            received: value.name,
+            repair: 'Remove surrounding whitespace from name.',
+        }));
+        valid = false;
+    }
+    return valid;
+};
+const validateTemplateMetadata = (value, pathSlug, file, diagnostics) => {
+    if (!isRecord(value)) {
+        diagnostics.push(schemaDiagnostic(file, 'root', 'object', value));
+        return null;
+    }
+    const initialCount = diagnostics.length;
+    validateExactKeys(value, TEMPLATE_METADATA_KEYS, file, diagnostics);
+    validateIdentity(value, pathSlug, file, diagnostics);
+    if (typeof value.subject !== 'string' || Buffer.byteLength(value.subject, 'utf8') > 998) {
+        diagnostics.push(schemaDiagnostic(file, 'subject', 'string up to 998 UTF-8 bytes', value.subject));
+    }
+    else if ([...value.subject].some((character) => {
+        const code = character.codePointAt(0);
+        return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+    })) {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-002',
+            file,
+            reason: 'Email subject contains invalid control characters',
+            expected: 'subject without control characters',
+            received: value.subject,
+            repair: 'Remove control characters from subject.',
+        }));
+    }
+    if (value.previewText !== null
+        && (typeof value.previewText !== 'string' || Buffer.byteLength(value.previewText, 'utf8') > 500)) {
+        diagnostics.push(schemaDiagnostic(file, 'previewText', 'string up to 500 UTF-8 bytes or null', value.previewText));
+    }
+    if (!isRecord(value.variables)) {
+        diagnostics.push(schemaDiagnostic(file, 'variables', 'object', value.variables));
+    }
+    else {
+        const names = Object.keys(value.variables);
+        if (names.length > 50) {
+            diagnostics.push(schemaDiagnostic(file, 'variables', 'at most 50 variables', names.length));
+        }
+        for (const name of names) {
+            if (!VARIABLE_NAME.test(name) || Buffer.byteLength(name, 'utf8') > 64) {
+                diagnostics.push(schemaDiagnostic(file, `variables.${name}`, 'safe variable name', name));
+            }
+            if (RESERVED_VARIABLE_NAMES.has(name)) {
+                diagnostics.push(schemaDiagnostic(file, `variables.${name}`, 'non-reserved variable name', name));
+            }
+            if (!VARIABLE_TYPES.has(value.variables[name])) {
+                diagnostics.push(schemaDiagnostic(file, `variables.${name}`, 'string, number, or boolean', value.variables[name]));
+            }
+        }
+    }
+    if (diagnostics.length !== initialCount)
+        return null;
+    return value;
+};
+const validateSequence = (value, pathSlug, file, diagnostics) => {
+    if (!isRecord(value)) {
+        diagnostics.push(schemaDiagnostic(file, 'root', 'object', value));
+        return null;
+    }
+    const initialCount = diagnostics.length;
+    validateExactKeys(value, SEQUENCE_KEYS, file, diagnostics);
+    validateIdentity(value, pathSlug, file, diagnostics);
+    if (!EMAIL_EVENTS.has(value.triggerEventType)) {
+        diagnostics.push(schemaDiagnostic(file, 'triggerEventType', [...EMAIL_EVENTS], value.triggerEventType));
+    }
+    if (!Array.isArray(value.funnelIds) || value.funnelIds.length < 1 || value.funnelIds.length > 50) {
+        diagnostics.push(schemaDiagnostic(file, 'funnelIds', '1 to 50 UUIDs', value.funnelIds));
+    }
+    else {
+        value.funnelIds.forEach((id, index) => {
+            if (typeof id !== 'string' || !UUID.test(id)) {
+                diagnostics.push(schemaDiagnostic(file, `funnelIds[${index}]`, 'UUID', id));
+            }
+        });
+    }
+    if (!Array.isArray(value.steps) || value.steps.length < 1 || value.steps.length > 50) {
+        diagnostics.push(schemaDiagnostic(file, 'steps', '1 to 50 steps', value.steps));
+    }
+    else {
+        const seenKeys = new Set();
+        value.steps.forEach((step, index) => {
+            if (!isRecord(step)) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}]`, 'object', step));
+                return;
+            }
+            validateExactKeys(step, SEQUENCE_STEP_KEYS, file, diagnostics);
+            if (typeof step.key !== 'string' || !STEP_KEY.test(step.key) || step.key.length > 64) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].key`, 'lowercase kebab-case key', step.key));
+            }
+            else if (seenKeys.has(step.key)) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].key`, 'unique step key', step.key));
+            }
+            else {
+                seenKeys.add(step.key);
+            }
+            if (!Number.isInteger(step.delaySeconds) || Number(step.delaySeconds) < 0 || Number(step.delaySeconds) > 7_776_000) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].delaySeconds`, 'integer from 0 to 7776000', step.delaySeconds));
+            }
+            if (typeof step.templateVersionId !== 'string' || !UUID.test(step.templateVersionId)) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].templateVersionId`, 'UUID', step.templateVersionId));
+            }
+        });
+    }
+    if (!Array.isArray(value.exitEventTypes) || value.exitEventTypes.length > EMAIL_EVENTS.size) {
+        diagnostics.push(schemaDiagnostic(file, 'exitEventTypes', 'up to 3 event types', value.exitEventTypes));
+    }
+    else {
+        value.exitEventTypes.forEach((event, index) => {
+            if (!EMAIL_EVENTS.has(event)) {
+                diagnostics.push(schemaDiagnostic(file, `exitEventTypes[${index}]`, [...EMAIL_EVENTS], event));
+            }
+        });
+        if (value.exitEventTypes.includes(value.triggerEventType)) {
+            diagnostics.push(schemaDiagnostic(file, 'exitEventTypes', 'events excluding triggerEventType', value.exitEventTypes));
+        }
+    }
+    if (diagnostics.length !== initialCount)
+        return null;
+    return {
+        id: value.id,
+        slug: value.slug,
+        name: value.name,
+        draft: {
+            triggerEventType: value.triggerEventType,
+            funnelIds: value.funnelIds,
+            steps: value.steps,
+            exitEventTypes: value.exitEventTypes,
+        },
+    };
+};
+const listDirectories = async (directory) => {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const symlink = entries.find((entry) => entry.isSymbolicLink());
+        if (symlink)
+            throw new Error(`Managed email path cannot be a symlink: ${path.join(directory, symlink.name)}`);
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+const listJsonFiles = async (directory) => {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const symlink = entries.find((entry) => entry.isSymbolicLink());
+        if (symlink)
+            throw new Error(`Managed email path cannot be a symlink: ${path.join(directory, symlink.name)}`);
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+export async function readEmailFiles(sourceDir) {
+    const diagnostics = [];
+    const templates = [];
+    const sequences = [];
+    const templateRoot = path.join(sourceDir, 'emails', 'templates');
+    const sequenceRoot = path.join(sourceDir, 'emails', 'sequences');
+    await Promise.all([
+        assertNoSymlinkPath(sourceDir),
+        assertNoSymlinkPath(sourceDir, 'emails'),
+        assertNoSymlinkPath(sourceDir, 'emails/templates'),
+        assertNoSymlinkPath(sourceDir, 'emails/sequences'),
+    ]);
+    for (const slug of await listDirectories(templateRoot)) {
+        const relativeRoot = path.posix.join('emails', 'templates', slug);
+        const metadataFile = path.posix.join(relativeRoot, 'template.json');
+        const htmlFile = path.posix.join(relativeRoot, 'body.html');
+        const textFile = path.posix.join(relativeRoot, 'body.txt');
+        await Promise.all([
+            assertNoSymlinkPath(sourceDir, relativeRoot),
+            assertNoSymlinkPath(sourceDir, metadataFile),
+            assertNoSymlinkPath(sourceDir, htmlFile),
+            assertNoSymlinkPath(sourceDir, textFile),
+        ]);
+        const metadataValue = await readJson(path.join(templateRoot, slug, 'template.json'), metadataFile, diagnostics);
+        const html = await readUtf8(path.join(templateRoot, slug, 'body.html'), htmlFile, diagnostics);
+        const text = await readUtf8(path.join(templateRoot, slug, 'body.txt'), textFile, diagnostics);
+        const metadata = metadataValue === null
+            ? null
+            : validateTemplateMetadata(metadataValue, slug, metadataFile, diagnostics);
+        if (metadata && html !== null && text !== null) {
+            if (Buffer.byteLength(html, 'utf8') > 256_000) {
+                diagnostics.push(schemaDiagnostic(htmlFile, 'body', 'up to 256000 UTF-8 bytes', html.length));
+            }
+            else if (Buffer.byteLength(text, 'utf8') > 100_000) {
+                diagnostics.push(schemaDiagnostic(textFile, 'body', 'up to 100000 UTF-8 bytes', text.length));
+            }
+            else {
+                templates.push({
+                    id: metadata.id,
+                    slug: metadata.slug,
+                    name: metadata.name,
+                    draft: {
+                        subject: metadata.subject,
+                        previewText: metadata.previewText,
+                        html,
+                        text,
+                        variables: metadata.variables,
+                    },
+                });
+            }
+        }
+    }
+    for (const filename of await listJsonFiles(sequenceRoot)) {
+        const slug = filename.slice(0, -'.json'.length);
+        const relativeFile = path.posix.join('emails', 'sequences', filename);
+        const value = await readJson(path.join(sequenceRoot, filename), relativeFile, diagnostics);
+        const sequence = value === null ? null : validateSequence(value, slug, relativeFile, diagnostics);
+        if (sequence)
+            sequences.push(sequence);
+    }
+    return {
+        valid: diagnostics.length === 0,
+        diagnostics,
+        templates,
+        sequences,
+    };
+}
+const sortedVariables = (variables) => Object.fromEntries(Object.entries(variables).sort(([left], [right]) => (Buffer.compare(Buffer.from(left), Buffer.from(right)))));
+const compareUtf8 = (left, right) => (Buffer.compare(Buffer.from(left), Buffer.from(right)));
+const sortedUnique = (values) => [...new Set(values)].sort(compareUtf8);
+export async function writeEmailTemplateFile(sourceDir, template) {
+    assertWriterSlug(template.slug);
+    const relativeDirectory = path.posix.join('emails', 'templates', template.slug);
+    const directory = path.join(sourceDir, relativeDirectory);
+    await Promise.all([
+        assertNoSymlinkPath(sourceDir),
+        assertNoSymlinkPath(sourceDir, 'emails'),
+        assertNoSymlinkPath(sourceDir, 'emails/templates'),
+        assertNoSymlinkPath(sourceDir, relativeDirectory),
+        assertNoSymlinkPath(sourceDir, path.posix.join(relativeDirectory, 'template.json')),
+        assertNoSymlinkPath(sourceDir, path.posix.join(relativeDirectory, 'body.html')),
+        assertNoSymlinkPath(sourceDir, path.posix.join(relativeDirectory, 'body.txt')),
+    ]);
+    await mkdir(directory, { recursive: true });
+    const metadata = {
+        id: template.id,
+        slug: template.slug,
+        name: template.name,
+        subject: template.draft.subject,
+        previewText: template.draft.previewText,
+        variables: sortedVariables(template.draft.variables),
+    };
+    await writeAtomic(path.join(directory, 'template.json'), `${JSON.stringify(metadata, null, 2)}\n`);
+    await Promise.all([
+        writeAtomic(path.join(directory, 'body.html'), template.draft.html),
+        writeAtomic(path.join(directory, 'body.txt'), template.draft.text),
+    ]);
+}
+export async function writeEmailSequenceFile(sourceDir, sequence) {
+    assertWriterSlug(sequence.slug);
+    const relativeRoot = path.posix.join('emails', 'sequences');
+    const relativeFile = path.posix.join(relativeRoot, `${sequence.slug}.json`);
+    await Promise.all([
+        assertNoSymlinkPath(sourceDir),
+        assertNoSymlinkPath(sourceDir, 'emails'),
+        assertNoSymlinkPath(sourceDir, relativeRoot),
+        assertNoSymlinkPath(sourceDir, relativeFile),
+    ]);
+    const sequenceRoot = path.join(sourceDir, relativeRoot);
+    await mkdir(sequenceRoot, { recursive: true });
+    const serialized = {
+        id: sequence.id,
+        slug: sequence.slug,
+        name: sequence.name,
+        triggerEventType: sequence.draft.triggerEventType,
+        funnelIds: sortedUnique(sequence.draft.funnelIds),
+        steps: sequence.draft.steps.map((step) => ({
+            key: step.key,
+            delaySeconds: step.delaySeconds,
+            templateVersionId: step.templateVersionId,
+        })),
+        exitEventTypes: sortedUnique(sequence.draft.exitEventTypes),
+    };
+    await writeAtomic(path.join(sequenceRoot, `${sequence.slug}.json`), `${JSON.stringify(serialized, null, 2)}\n`);
+}
+export async function writeEmailFiles(input) {
+    await Promise.all([
+        assertNoSymlinkPath(input.sourceDir),
+        assertNoSymlinkPath(input.sourceDir, 'emails'),
+        assertNoSymlinkPath(input.sourceDir, 'emails/templates'),
+        assertNoSymlinkPath(input.sourceDir, 'emails/sequences'),
+    ]);
+    await Promise.all([
+        mkdir(path.join(input.sourceDir, 'emails', 'templates'), { recursive: true }),
+        mkdir(path.join(input.sourceDir, 'emails', 'sequences'), { recursive: true }),
+    ]);
+    for (const template of [...input.templates].sort((left, right) => compareUtf8(left.slug, right.slug))) {
+        await writeEmailTemplateFile(input.sourceDir, template);
+    }
+    for (const sequence of [...input.sequences].sort((left, right) => compareUtf8(left.slug, right.slug))) {
+        await writeEmailSequenceFile(input.sourceDir, sequence);
+    }
+}
+const pathExists = async (value) => {
+    try {
+        await lstat(value);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+export async function replaceEmailFiles(input) {
+    await mkdir(input.sourceDir, { recursive: true });
+    await Promise.all([
+        assertNoSymlinkPath(input.sourceDir),
+        assertNoSymlinkPath(input.sourceDir, 'emails'),
+    ]);
+    const stagingRoot = await mkdtemp(path.join(input.sourceDir, '.fgrove-email-pull-'));
+    const target = path.join(input.sourceDir, 'emails');
+    const staged = path.join(stagingRoot, 'emails');
+    const backup = path.join(input.sourceDir, `.fgrove-email-backup-${randomUUID()}`);
+    let backedUp = false;
+    try {
+        await writeEmailFiles({ ...input, sourceDir: stagingRoot });
+        const validation = await readEmailFiles(stagingRoot);
+        if (!validation.valid)
+            throw new Error('Invalid remote email resources');
+        if (await pathExists(target)) {
+            await rename(target, backup);
+            backedUp = true;
+        }
+        try {
+            await rename(staged, target);
+        }
+        catch (error) {
+            if (backedUp)
+                await rename(backup, target);
+            backedUp = false;
+            throw error;
+        }
+        if (backedUp)
+            await rm(backup, { recursive: true, force: true });
+    }
+    finally {
+        await rm(stagingRoot, { recursive: true, force: true });
+    }
+}

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.75",
+      "repositoryCliVersion": "0.1.76",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.64",
+        "bundleVersion": "2.0.65",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "e73eba7d01d41d4d87be8a6170835c84b7c4f64792bbafb59201130a380250ec"
+            "sha256": "753d4bd01a3f05d3165cbe19510564b44a80d0f8392b72582222b771bc7045e0"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "fd64ef085f6037e92d596ef958d4118e671285dd3561e22881eed0d7da1bba82"
+            "sha256": "d085f9a552809b085d6b6cd1a5237ad5fcc0d88a8d4384d185638bc3bc99c90f"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.74",
+      "repositoryCliVersion": "0.1.75",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.63",
+        "bundleVersion": "2.0.64",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "f025610f7c1d91188a67f50e7511a47642b3606170700e11cef0e7a49c8cd997"
+            "sha256": "e73eba7d01d41d4d87be8a6170835c84b7c4f64792bbafb59201130a380250ec"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "7852876ec227cb893db0315a00627cd609afe14ac5ffac5fdba0fe585a56fbbf"
+            "sha256": "fd64ef085f6037e92d596ef958d4118e671285dd3561e22881eed0d7da1bba82"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.73",
+      "repositoryCliVersion": "0.1.74",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.62",
+        "bundleVersion": "2.0.63",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "54e982ca3f199113646be0d6de1f8e2b8dde87744df82d6d7452d8e33b2b5258"
+            "sha256": "f025610f7c1d91188a67f50e7511a47642b3606170700e11cef0e7a49c8cd997"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "7f343fd806a932abcb3cac6463ae84a7532b7c9f583540e6fa06fd7ff7721ddf"
+            "sha256": "7852876ec227cb893db0315a00627cd609afe14ac5ffac5fdba0fe585a56fbbf"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.72",
+      "repositoryCliVersion": "0.1.73",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.61",
+        "bundleVersion": "2.0.62",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "217b719ef163d485c7a740906b3a1d551f5af37faf9fb721fc61d1fecf5fa9e6"
+            "sha256": "54e982ca3f199113646be0d6de1f8e2b8dde87744df82d6d7452d8e33b2b5258"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "f9be1a58ba8548ecbf51b2676479964dca89a04a63c9de53f6f805a6ed090fd0"
+            "sha256": "7f343fd806a932abcb3cac6463ae84a7532b7c9f583540e6fa06fd7ff7721ddf"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.71",
+      "repositoryCliVersion": "0.1.72",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.60",
+        "bundleVersion": "2.0.61",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "cf02bed62505b7b00ce5f6175eaa2fde99159556b37aad0f304ceba407041173"
+            "sha256": "217b719ef163d485c7a740906b3a1d551f5af37faf9fb721fc61d1fecf5fa9e6"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "2cd26fc471e315234da4daca6d5f54bf33107d9c7671e1db1a4ba229bc5c2ba0"
+            "sha256": "f9be1a58ba8548ecbf51b2676479964dca89a04a63c9de53f6f805a6ed090fd0"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.70",
+      "repositoryCliVersion": "0.1.71",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.59",
+        "bundleVersion": "2.0.60",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "f3a61a8d62eb9644f8cf20f86f856b5664cbf1c94e172694c4becc9a6bd11821"
+            "sha256": "cf02bed62505b7b00ce5f6175eaa2fde99159556b37aad0f304ceba407041173"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ffae3632d0eb3d1c8f58542d89a95f9068e8fcb7540ea46d1a0a3502419fc599"
+            "sha256": "2cd26fc471e315234da4daca6d5f54bf33107d9c7671e1db1a4ba229bc5c2ba0"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.69",
+      "repositoryCliVersion": "0.1.70",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.58",
+        "bundleVersion": "2.0.59",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "6a6f526910ce80032feae59d33fc079f10168554430a582f03b39b73d0109367"
+            "sha256": "f3a61a8d62eb9644f8cf20f86f856b5664cbf1c94e172694c4becc9a6bd11821"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ec76219d1d3a50f95fc9f5c5b690eb6747c0d468b81c11a926ed9ec484ffc654"
+            "sha256": "ffae3632d0eb3d1c8f58542d89a95f9068e8fcb7540ea46d1a0a3502419fc599"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "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.64",
+  "bundleVersion": "2.0.65",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "e73eba7d01d41d4d87be8a6170835c84b7c4f64792bbafb59201130a380250ec"
+      "sha256": "753d4bd01a3f05d3165cbe19510564b44a80d0f8392b72582222b771bc7045e0"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "fd64ef085f6037e92d596ef958d4118e671285dd3561e22881eed0d7da1bba82"
+      "sha256": "d085f9a552809b085d6b6cd1a5237ad5fcc0d88a8d4384d185638bc3bc99c90f"
     }
   ]
 }

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.5` first, then `@funnelsgrove/analytics` `0.1.54`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.75`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.7.5` first, then `@funnelsgrove/analytics` `0.1.54`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.76`. 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.64",
+  "bundleVersion": "2.0.65",
   "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.64",
+  "bundleVersion": "2.0.65",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "e73eba7d01d41d4d87be8a6170835c84b7c4f64792bbafb59201130a380250ec"
+      "sha256": "753d4bd01a3f05d3165cbe19510564b44a80d0f8392b72582222b771bc7045e0"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "fd64ef085f6037e92d596ef958d4118e671285dd3561e22881eed0d7da1bba82"
+      "sha256": "d085f9a552809b085d6b6cd1a5237ad5fcc0d88a8d4384d185638bc3bc99c90f"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "1d3aed0b290e8bf180195361309a48286c8be8d5ca476c42e148541e7f6fc9ff",
+  "sourceTreeHash": "77d2b1cb039b837f9670b9ae962687c4b61b0bbbbb97ad9b370a39265f9b73b4",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.64",
+  "docsBundleVersion": "2.0.65",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "1e188eb21c6d7adee2426c5cfc693e34899246b1dd00f7899d10ad44b71d0109",
+      "sha256": "4f86b42926b30547392406f7b7040acd029e348b7d556339298814eefaac119d",
       "mode": "100644"
     },
     {
@@ -101,7 +101,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "e73eba7d01d41d4d87be8a6170835c84b7c4f64792bbafb59201130a380250ec",
+      "sha256": "753d4bd01a3f05d3165cbe19510564b44a80d0f8392b72582222b771bc7045e0",
       "mode": "100644"
     },
     {
@@ -236,7 +236,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "fd64ef085f6037e92d596ef958d4118e671285dd3561e22881eed0d7da1bba82",
+      "sha256": "d085f9a552809b085d6b6cd1a5237ad5fcc0d88a8d4384d185638bc3bc99c90f",
       "mode": "100644"
     },
     {
@@ -916,7 +916,7 @@
     },
     {
       "path": "tests/funnel-agent-docs.test.ts",
-      "sha256": "0337e69fe6319c8d34aa9278b17997cf97ddbe63cac23c389a9069b9762619d0",
+      "sha256": "f5e68980974e69795f2dd8d4d180c2e8b860a63b0496cbcc8ca0aed82db09c57",
       "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.5` first, then `@funnelsgrove/analytics` `0.1.54`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.75`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.7.5` first, then `@funnelsgrove/analytics` `0.1.54`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.76`. 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.64",
+  "bundleVersion": "2.0.65",
   "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.64',
+      bundleVersion: '2.0.65',
       stepContractVersion: contract.stepContractVersion,
       contractHash: contract.contractHash,
     });