@funnelsgrove/cli 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# FunnelsGrove CLI
+
+Install:
+
+```bash
+npm install -g @funnelsgrove/cli
+fg login
+```
+
+Set the active project and funnel:
+
+```bash
+fg use --project claimbee --funnel claimbee-ios
+fg status
+```
+
+Common workflow:
+
+```bash
+fg sync down --dir ./claimbee-ios
+cd ./claimbee-ios
+fg docs
+fg sync up --message 'Update funnel copy'
+fg publish --env preview
+```
+
+The package also keeps the longer `funnelsgrove` command as a compatibility alias.
+Use `--api-url` or `FUNNELSGROVE_API_URL` for non-production APIs.
+Use `--config` or `FUNNELSGROVE_CONFIG` to keep test credentials separate from the default `~/.funnelsgrove/config.json`.

package/dist/apiClient.d.ts

@@ -0,0 +1,13 @@
+type FetchFn = typeof fetch;
+type TrpcProcedureType = 'query' | 'mutation';
+export type TrpcCallInput = {
+    apiUrl: string;
+    path: string;
+    type: TrpcProcedureType;
+    input?: unknown;
+    token?: string | null;
+    fetchFn?: FetchFn;
+};
+export declare function parseTrpcJsonResponse<T = unknown>(response: unknown): T;
+export declare function callTrpcProcedure<T = unknown>(input: TrpcCallInput): Promise<T>;
+export {};

package/dist/apiClient.js

@@ -0,0 +1,51 @@
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseTrpcJsonResponse(response) {
+    if (!isObject(response)) {
+        throw new Error('Invalid tRPC response');
+    }
+    if (isObject(response.error)) {
+        const message = typeof response.error.message === 'string' ? response.error.message : 'Unknown error';
+        throw new Error(`tRPC request failed: ${message}`);
+    }
+    const result = response.result;
+    if (!isObject(result) || !('data' in result)) {
+        throw new Error('Invalid tRPC response');
+    }
+    if (isObject(result.data) && 'json' in result.data) {
+        return result.data.json;
+    }
+    return result.data;
+}
+const trimTrailingSlash = (value) => value.trim().replace(/\/+$/, '');
+const buildHeaders = (input) => {
+    const headers = {};
+    if (input.token) {
+        headers.authorization = `Bearer ${input.token}`;
+    }
+    if (input.contentType) {
+        headers['content-type'] = input.contentType;
+    }
+    return headers;
+};
+export async function callTrpcProcedure(input) {
+    const fetchFn = input.fetchFn || fetch;
+    const baseUrl = `${trimTrailingSlash(input.apiUrl)}/${input.path}`;
+    const init = input.type === 'query'
+        ? {
+            method: 'GET',
+            headers: buildHeaders({ token: input.token }),
+        }
+        : {
+            method: 'POST',
+            headers: buildHeaders({ token: input.token, contentType: 'application/json' }),
+            body: JSON.stringify(input.input ?? {}),
+        };
+    const url = input.type === 'query' && input.input !== undefined
+        ? `${baseUrl}?input=${encodeURIComponent(JSON.stringify(input.input))}`
+        : baseUrl;
+    const response = await fetchFn(url, init);
+    const json = await response.json();
+    return parseTrpcJsonResponse(json);
+}

package/dist/authStore.d.ts

@@ -0,0 +1,18 @@
+export type ActiveContext = {
+    workspaceId?: string;
+    workspaceName?: string;
+    workspaceSlug?: string;
+    projectId?: string;
+    projectName?: string;
+    projectSlug?: string;
+    funnelId?: string;
+    funnelName?: string;
+    funnelSlug?: string;
+};
+export declare function saveAuthToken(token: string, configPath: string): Promise<void>;
+export declare function loadAuthToken(configPath: string): Promise<string | null>;
+export declare function clearAuthToken(configPath: string): Promise<void>;
+export declare function saveActiveContext(configPath: string, active: ActiveContext): Promise<void>;
+export declare function loadActiveContext(configPath: string): Promise<ActiveContext | null>;
+export declare function clearActiveContext(configPath: string): Promise<void>;
+export declare function getDefaultAuthConfigPath(): string;

package/dist/authStore.js

@@ -0,0 +1,85 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import os from 'node:os';
+import path from 'node:path';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function normalizeActiveContext(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const active = {
+        workspaceId: normalizeString(value.workspaceId),
+        workspaceName: normalizeString(value.workspaceName),
+        workspaceSlug: normalizeString(value.workspaceSlug),
+        projectId: normalizeString(value.projectId),
+        projectName: normalizeString(value.projectName),
+        projectSlug: normalizeString(value.projectSlug),
+        funnelId: normalizeString(value.funnelId),
+        funnelName: normalizeString(value.funnelName),
+        funnelSlug: normalizeString(value.funnelSlug),
+    };
+    return Object.values(active).some(Boolean) ? active : undefined;
+}
+function pruneActiveContext(active) {
+    return Object.fromEntries(Object.entries(active).filter(([, value]) => typeof value === 'string' && value.trim()));
+}
+async function loadConfig(configPath) {
+    try {
+        const config = JSON.parse(await readFile(configPath, 'utf8'));
+        return {
+            token: typeof config.token === 'string' ? config.token : undefined,
+            active: normalizeActiveContext(config.active),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+}
+async function saveConfig(configPath, config) {
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+export async function saveAuthToken(token, configPath) {
+    const config = await loadConfig(configPath);
+    await saveConfig(configPath, {
+        ...config,
+        token,
+    });
+}
+export async function loadAuthToken(configPath) {
+    return (await loadConfig(configPath)).token || null;
+}
+export async function clearAuthToken(configPath) {
+    await rm(configPath, { force: true });
+}
+export async function saveActiveContext(configPath, active) {
+    const config = await loadConfig(configPath);
+    await saveConfig(configPath, {
+        ...config,
+        active: pruneActiveContext(active),
+    });
+}
+export async function loadActiveContext(configPath) {
+    return (await loadConfig(configPath)).active || null;
+}
+export async function clearActiveContext(configPath) {
+    const config = await loadConfig(configPath);
+    if (!config.token) {
+        await rm(configPath, { force: true });
+        return;
+    }
+    await saveConfig(configPath, {
+        token: config.token,
+    });
+}
+export function getDefaultAuthConfigPath() {
+    return path.join(os.homedir(), '.funnelsgrove', 'config.json');
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,550 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { callTrpcProcedure } from './apiClient.js';
+import { clearActiveContext, getDefaultAuthConfigPath, loadActiveContext, loadAuthToken, saveActiveContext, saveAuthToken, } from './authStore.js';
+import { buildSyncManifest, collectSourceFiles, readSyncManifest, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { isKnownTemplate, KNOWN_TEMPLATE_SLUGS, reskinFunnel } from './reskin.js';
+import { syncTemplateDocs, TEMPLATE_DOCS_DIR } from './templateDocs.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const toKebabCase = (value) => value
+    .trim()
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+const resolveTemplatePath = (slug) => path.resolve(__dirname, '..', '..', '..', 'funnels', 'rag-catalog', slug);
+const resolveTemplateDocsPath = () => path.resolve(__dirname, '..', TEMPLATE_DOCS_DIR);
+const DEFAULT_API_URL = 'https://api.funnelsgrove.com/trpc';
+const UUID_PATTERN = /^[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 getApiUrl = () => {
+    const options = program.opts();
+    return options.apiUrl || process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL;
+};
+const getConfigPath = () => {
+    const options = program.opts();
+    return options.config || process.env.FUNNELSGROVE_CONFIG || getDefaultAuthConfigPath();
+};
+const readAuthToken = async () => {
+    const token = await loadAuthToken(getConfigPath());
+    if (!token) {
+        throw new Error('Not logged in. Run `fg login` first.');
+    }
+    return token;
+};
+const callApi = async (input) => {
+    return callTrpcProcedure({
+        apiUrl: getApiUrl(),
+        path: input.path,
+        type: input.type,
+        input: input.data,
+        token: input.token,
+    });
+};
+const readCodeFromStdin = async () => {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        return (await rl.question('Enter 8 digit code: ')).trim();
+    }
+    finally {
+        rl.close();
+    }
+};
+const getCurrentUser = async (token) => {
+    return callApi({
+        path: 'auth.me',
+        type: 'query',
+        token,
+    });
+};
+const matchesResource = (resource, value) => {
+    const normalized = value.trim().toLowerCase();
+    return (resource.id === value ||
+        resource.slug?.toLowerCase() === normalized ||
+        resource.name?.toLowerCase() === normalized);
+};
+const resolveWorkspace = async (token, workspace) => {
+    const me = await getCurrentUser(token);
+    if (workspace) {
+        const matched = me.workspaces.find((item) => matchesResource(item, workspace));
+        if (!matched) {
+            throw new Error(`Unable to resolve workspace "${workspace}"`);
+        }
+        return matched;
+    }
+    const active = await loadActiveContext(getConfigPath());
+    if (active?.workspaceId) {
+        const matched = me.workspaces.find((item) => item.id === active.workspaceId);
+        if (matched) {
+            return matched;
+        }
+    }
+    const defaultWorkspaceId = me.workspace?.id || me.workspaces[0]?.id;
+    if (!defaultWorkspaceId) {
+        throw new Error('No workspace found for this account.');
+    }
+    const defaultWorkspace = me.workspaces.find((item) => item.id === defaultWorkspaceId);
+    if (!defaultWorkspace) {
+        throw new Error('Default workspace is unavailable.');
+    }
+    return defaultWorkspace;
+};
+const resolveWorkspaceId = async (token, workspace) => {
+    return (await resolveWorkspace(token, workspace)).id;
+};
+const listProjects = async (token, workspaceId) => {
+    const result = await callApi({
+        path: 'projects.list',
+        type: 'query',
+        token,
+        data: {
+            workspaceId,
+        },
+    });
+    return result.projects;
+};
+const resolveProject = async (token, workspaceId, project) => {
+    const projects = await listProjects(token, workspaceId);
+    const matched = projects.find((item) => matchesResource(item, project));
+    if (!matched) {
+        throw new Error(`Unable to resolve project "${project}" in workspace ${workspaceId}`);
+    }
+    return matched;
+};
+const listFunnels = async (token, workspaceId) => {
+    const result = await callApi({
+        path: 'funnels.list',
+        type: 'query',
+        token,
+        data: {
+            workspaceId,
+        },
+    });
+    return result.funnels;
+};
+const resolveFunnel = async (token, workspaceId, funnel) => {
+    if (UUID_PATTERN.test(funnel)) {
+        return {
+            id: funnel,
+            name: funnel,
+            slug: funnel,
+        };
+    }
+    const funnels = await listFunnels(token, workspaceId);
+    const matched = funnels.find((item) => matchesResource(item, funnel));
+    if (!matched) {
+        throw new Error(`Unable to resolve funnel "${funnel}" in workspace ${workspaceId}`);
+    }
+    return matched;
+};
+const resolveFunnelId = async (token, workspaceId, funnel) => {
+    return (await resolveFunnel(token, workspaceId, funnel)).id;
+};
+const contextFromResources = (input) => {
+    const sameWorkspace = input.current?.workspaceId === input.workspace.id;
+    return {
+        workspaceId: input.workspace.id,
+        workspaceName: input.workspace.name,
+        workspaceSlug: input.workspace.slug,
+        projectId: input.project?.id || (sameWorkspace ? input.current?.projectId : undefined),
+        projectName: input.project?.name || (sameWorkspace ? input.current?.projectName : undefined),
+        projectSlug: input.project?.slug || (sameWorkspace ? input.current?.projectSlug : undefined),
+        funnelId: input.funnel?.id || (sameWorkspace ? input.current?.funnelId : undefined),
+        funnelName: input.funnel?.name || (sameWorkspace ? input.current?.funnelName : undefined),
+        funnelSlug: input.funnel?.slug || (sameWorkspace ? input.current?.funnelSlug : undefined),
+    };
+};
+const loadManifestForDir = async (dir) => {
+    return readSyncManifest(path.resolve(process.cwd(), dir));
+};
+const resolveSyncTarget = async (input) => {
+    const sourceDir = path.resolve(process.cwd(), input.dir || '.');
+    const manifest = await readSyncManifest(sourceDir);
+    const active = await loadActiveContext(getConfigPath());
+    const workspaceId = input.workspace
+        ? await resolveWorkspaceId(input.token, input.workspace)
+        : manifest?.workspaceId || active?.workspaceId || await resolveWorkspaceId(input.token);
+    const funnelId = input.funnel
+        ? await resolveFunnelId(input.token, workspaceId, input.funnel)
+        : manifest?.funnelId || active?.funnelId;
+    if (!funnelId) {
+        throw new Error('No active funnel. Run `fg use --funnel <id-or-slug>` or pass `--funnel`.');
+    }
+    return {
+        workspaceId,
+        funnelId,
+        sourceDir,
+        manifest,
+    };
+};
+const ensureGitignore = async (dir) => {
+    const gitignorePath = path.join(dir, '.gitignore');
+    const existing = await readFile(gitignorePath, 'utf8').catch(() => '');
+    const lines = existing.split(/\r?\n/g).filter(Boolean);
+    const required = ['.env', '.env.local', '.env.*', '!.env.example', '.funnelsgrove-sync.json', 'node_modules', '.next', 'out'];
+    const seen = new Set(lines);
+    for (const line of required) {
+        if (!seen.has(line)) {
+            lines.push(line);
+        }
+    }
+    await writeFile(gitignorePath, `${lines.join('\n')}\n`, 'utf8');
+};
+const printRows = (rows, columns) => {
+    for (const row of rows) {
+        console.log(columns.map((column) => row[column] || '').join('\t'));
+    }
+};
+const addExamples = (command, examples) => command.addHelpText('after', `\nExamples:\n${examples.map((example) => `  $ ${example}`).join('\n')}`);
+const program = new Command();
+program
+    .name('fg')
+    .description('FunnelsGrove CLI for editing, syncing, and publishing funnels')
+    .version('0.1.0')
+    .option('--api-url <url>', 'FunnelsGrove tRPC API URL', process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL)
+    .option('--config <path>', 'Auth config path', process.env.FUNNELSGROVE_CONFIG || getDefaultAuthConfigPath());
+addExamples(program, [
+    'fg login',
+    'fg use --project claimbee --funnel claimbee-ios',
+    'fg sync down --dir ./claimbee-ios',
+    'fg publish --env preview',
+]);
+addExamples(program
+    .command('login')
+    .description('Authorize this CLI with your FunnelsGrove account')
+    .option('--code <code>', '8 digit code from the authorization page'), [
+    'fg login',
+    'fg login --api-url http://localhost:3001/trpc',
+])
+    .action(async (options) => {
+    const request = await callApi({
+        path: 'cliAuth.createDeviceLogin',
+        type: 'mutation',
+    });
+    console.log('Open this URL to authorize the CLI:');
+    console.log(request.authorizeUrl);
+    console.log(`This request expires at ${request.expiresAt}.`);
+    const userCode = options.code?.trim() || await readCodeFromStdin();
+    const result = await callApi({
+        path: 'cliAuth.exchangeDeviceCode',
+        type: 'mutation',
+        data: {
+            deviceId: request.deviceId,
+            userCode,
+        },
+    });
+    await saveAuthToken(result.token, getConfigPath());
+    console.log(`Logged in. Token expires at ${result.expiresAt}.`);
+});
+addExamples(program
+    .command('whoami')
+    .description('Show the current authenticated user'), [
+    'fg whoami',
+])
+    .action(async () => {
+    const token = await readAuthToken();
+    const me = await getCurrentUser(token);
+    console.log(`${me.user.email || me.user.id}\t${me.workspace?.name || 'No workspace'}`);
+});
+addExamples(program
+    .command('use')
+    .description('Set the active workspace, project, and funnel for future commands')
+    .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('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .option('--clear', 'Clear the active CLI context'), [
+    'fg use --project claimbee --funnel claimbee-ios',
+    'fg use --workspace acme --project claimbee',
+    'fg use --clear',
+])
+    .action(async (options) => {
+    if (options.clear) {
+        await clearActiveContext(getConfigPath());
+        console.log('Cleared active context.');
+        return;
+    }
+    const token = await readAuthToken();
+    const current = await loadActiveContext(getConfigPath());
+    const workspace = await resolveWorkspace(token, options.workspace || current?.workspaceId);
+    const project = options.project ? await resolveProject(token, workspace.id, options.project) : null;
+    const funnel = options.funnel ? await resolveFunnel(token, workspace.id, options.funnel) : null;
+    const nextContext = contextFromResources({
+        workspace,
+        project,
+        funnel,
+        current,
+    });
+    await saveActiveContext(getConfigPath(), nextContext);
+    console.log(`workspace\t${nextContext.workspaceName || nextContext.workspaceId}`);
+    if (nextContext.projectId) {
+        console.log(`project\t${nextContext.projectName || nextContext.projectSlug || nextContext.projectId}`);
+    }
+    if (nextContext.funnelId) {
+        console.log(`funnel\t${nextContext.funnelName || nextContext.funnelSlug || nextContext.funnelId}`);
+    }
+});
+addExamples(program
+    .command('status')
+    .description('Show the authenticated user and active CLI context')
+    .option('--dir <path>', 'Local source directory for reading sync manifest', '.'), [
+    'fg status',
+    'fg status --dir ./claimbee-ios',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const [me, active, manifest] = await Promise.all([
+        getCurrentUser(token),
+        loadActiveContext(getConfigPath()),
+        loadManifestForDir(options.dir),
+    ]);
+    console.log(`user\t${me.user.email || me.user.id}`);
+    console.log(`api\t${getApiUrl()}`);
+    console.log(`config\t${getConfigPath()}`);
+    console.log(`workspace\t${active?.workspaceName || active?.workspaceSlug || active?.workspaceId || me.workspace?.name || 'Not set'}`);
+    console.log(`project\t${active?.projectName || active?.projectSlug || active?.projectId || 'Not set'}`);
+    console.log(`funnel\t${active?.funnelName || active?.funnelSlug || active?.funnelId || 'Not set'}`);
+    if (manifest) {
+        console.log(`localWorkspace\t${manifest.workspaceId}`);
+        console.log(`localFunnel\t${manifest.funnelId}`);
+        console.log(`localDraft\t${manifest.draftVersionId}`);
+    }
+});
+const projectsCommand = addExamples(program.command('projects').description('Manage projects'), [
+    'fg projects list',
+    'fg projects list --workspace acme',
+]);
+addExamples(projectsCommand
+    .command('list')
+    .description('List projects in the active or provided workspace')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name'), [
+    'fg projects list',
+    'fg projects list --workspace acme',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const workspaceId = await resolveWorkspaceId(token, options.workspace);
+    const projects = await listProjects(token, workspaceId);
+    printRows(projects, ['id', 'name', 'slug']);
+});
+const funnelsCommand = addExamples(program.command('funnels').description('Manage funnels'), [
+    'fg funnels list',
+    'fg funnels clone --funnel claimbee --name claimbee-ios',
+]);
+addExamples(funnelsCommand
+    .command('list')
+    .description('List funnels in a workspace')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name'), [
+    'fg funnels list',
+    'fg funnels list --workspace acme',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const workspaceId = await resolveWorkspaceId(token, options.workspace);
+    const funnels = await listFunnels(token, workspaceId);
+    printRows(funnels, ['id', 'name', 'slug']);
+});
+addExamples(funnelsCommand
+    .command('clone')
+    .description('Copy an existing funnel')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .requiredOption('--funnel <id-or-slug>', 'Source funnel id or slug')
+    .requiredOption('--name <name>', 'New funnel name'), [
+    'fg funnels clone --funnel claimbee --name claimbee-ios',
+    'fg funnels clone --workspace acme --funnel claimbee --name claimbee-ios',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const workspaceId = await resolveWorkspaceId(token, options.workspace);
+    const funnelId = await resolveFunnelId(token, workspaceId, options.funnel);
+    const result = await callApi({
+        path: 'funnels.clone',
+        type: 'mutation',
+        token,
+        data: {
+            workspaceId,
+            funnelId,
+            name: options.name,
+        },
+    });
+    console.log(`${result.funnel.id}\t${result.funnel.name}\t${result.funnel.slug}`);
+});
+const syncCommand = addExamples(program.command('sync').description('Sync funnel source'), [
+    'fg sync down --dir ./claimbee-ios',
+    'fg sync up --message "Update copy"',
+]);
+addExamples(syncCommand
+    .command('down')
+    .description('Download funnel draft source to a local directory')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--funnel <id-or-slug>', 'Funnel id or slug')
+    .requiredOption('--dir <path>', 'Local target directory'), [
+    'fg sync down --dir ./claimbee-ios',
+    'fg sync down --funnel claimbee-ios --dir ./claimbee-ios',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    const result = await callApi({
+        path: 'funnels.exportSource',
+        type: 'query',
+        token,
+        data: {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+        },
+    });
+    await mkdir(target.sourceDir, { recursive: true });
+    await writeSourceFiles(target.sourceDir, result.files);
+    if (result.envFile) {
+        await writeFile(path.join(target.sourceDir, '.env'), result.envFile, 'utf8');
+    }
+    await ensureGitignore(target.sourceDir);
+    await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
+        workspaceId: target.workspaceId,
+        funnelId: target.funnelId,
+        draftVersionId: result.draftVersionId,
+    }));
+    console.log(`Synced ${result.files.length} files to ${target.sourceDir}`);
+});
+addExamples(syncCommand
+    .command('up')
+    .description('Upload local source into a new funnel draft version')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--funnel <id-or-slug>', 'Funnel id or slug')
+    .option('--dir <path>', 'Local source directory', '.')
+    .option('--message <message>', 'Draft version message'), [
+    'fg sync up --message "Update hero copy"',
+    'fg sync up --dir ./claimbee-ios --message "Update paywall"',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    const files = await collectSourceFiles(target.sourceDir);
+    const result = await callApi({
+        path: 'funnels.importSource',
+        type: 'mutation',
+        token,
+        data: {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+            message: options.message,
+            files,
+        },
+    });
+    await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
+        workspaceId: target.workspaceId,
+        funnelId: target.funnelId,
+        draftVersionId: result.versionId,
+    }));
+    console.log(`Synced ${result.syncedFiles.length} files to draft v${result.versionSeq} (${result.versionId})`);
+});
+addExamples(program
+    .command('publish')
+    .description('Publish a funnel preview or production deployment')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--funnel <id-or-slug>', 'Funnel id or slug')
+    .option('--dir <path>', 'Local source directory for reading sync manifest', '.')
+    .option('--env <preview-or-production>', 'Publish environment', 'preview')
+    .option('--domain <domain>', 'Production custom domain')
+    .option('--message <message>', 'Publish version message'), [
+    'fg publish --env preview --message "Preview copy updates"',
+    'fg publish --env production --domain claimbee.example.com --message "Launch"',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    const publishEnv = options.env.trim().toLowerCase();
+    if (publishEnv !== 'preview' && publishEnv !== 'production') {
+        throw new Error('--env must be preview or production');
+    }
+    if (publishEnv === 'production' && !options.domain?.trim()) {
+        throw new Error('--domain is required when publishing production');
+    }
+    const result = await callApi({
+        path: 'funnels.publish',
+        type: 'mutation',
+        token,
+        data: {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+            message: options.message,
+            domains: publishEnv === 'production' && options.domain ? [options.domain] : undefined,
+        },
+    });
+    console.log(`${result.deploymentUrl}\tv${result.publishedVersionSeq}\t${result.publishedVersionId}`);
+});
+addExamples(program
+    .command('docs')
+    .description('Install or refresh local funnel editing docs in a funnel directory')
+    .option('--dir <path>', 'Local funnel directory', '.'), [
+    'fg docs',
+    'fg docs --dir ./claimbee-ios',
+])
+    .action(async (options) => {
+    const targetDir = path.resolve(process.cwd(), options.dir);
+    const copiedFiles = await syncTemplateDocs(resolveTemplateDocsPath(), targetDir);
+    console.log(`Synced ${copiedFiles.length} docs files to ${targetDir}`);
+});
+addExamples(program
+    .command('create')
+    .description('Create a new funnel from a template')
+    .requiredOption('--from <template>', 'Template slug from rag-catalog')
+    .requiredOption('--app <name>', 'Your app name')
+    .option('--output <dir>', 'Output directory'), [
+    'fg create --from headway-funnel --app ClaimBee',
+    'fg create --from promova --app ClaimBee --output ./claimbee-funnel',
+])
+    .action(async (options) => {
+    const { from: templateSlug, app: appName, output } = options;
+    if (!isKnownTemplate(templateSlug)) {
+        console.error(`Unknown template "${templateSlug}". Available templates:\n${KNOWN_TEMPLATE_SLUGS.map((s) => `  - ${s}`).join('\n')}`);
+        process.exit(1);
+    }
+    const templatePath = resolveTemplatePath(templateSlug);
+    const outputDir = output ?? `./${toKebabCase(appName)}-funnel`;
+    const outputPath = path.resolve(process.cwd(), outputDir);
+    console.log(`Creating funnel from "${templateSlug}" for "${appName}"...`);
+    try {
+        await cp(templatePath, outputPath, { recursive: true });
+    }
+    catch (err) {
+        console.error(`Failed to copy template: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const updated = await reskinFunnel(outputPath, appName);
+    console.log(`\nCreated funnel at ${outputDir}`);
+    if (updated.length > 0) {
+        console.log(`Updated ${updated.length} files with "${appName}" branding:`);
+        for (const file of updated) {
+            console.log(`  - ${file}`);
+        }
+    }
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${outputDir}`);
+    console.log('  npm install');
+    console.log('  npm run dev');
+});
+program.parseAsync().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/localSync.d.ts

@@ -0,0 +1,25 @@
+export declare const SYNC_MANIFEST_FILE = ".funnelsgrove-sync.json";
+export type SyncManifestFile = {
+    path: string;
+    hash: string;
+};
+export type SyncManifest = {
+    version: 1;
+    workspaceId: string;
+    funnelId: string;
+    draftVersionId: string;
+    files: SyncManifestFile[];
+};
+export type SyncManifestInput = Omit<SyncManifest, 'version' | 'files'>;
+export type SourceFile = {
+    path: string;
+    content: string;
+    contentType?: string;
+};
+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 writeSyncManifest(rootDir: string, manifest: SyncManifest): Promise<void>;
+export declare function readSyncManifest(rootDir: string): Promise<SyncManifest | null>;
+export declare function collectSourceFiles(rootDir: string): Promise<SourceFile[]>;
+export declare function writeSourceFiles(rootDir: string, files: SourceFile[]): Promise<void>;

package/dist/localSync.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const SYNC_MANIFEST_FILE = '.funnelsgrove-sync.json';
+const EXCLUDED_PATH_PARTS = new Set(['node_modules', '.next', 'out']);
+export function normalizeSyncPath(filePath) {
+    const normalized = path.posix.normalize(filePath.replaceAll('\\', '/'));
+    return normalized.replace(/^(\.\/|\/)+/, '');
+}
+function assertSafeSyncPath(filePath) {
+    const normalized = normalizeSyncPath(filePath);
+    if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized.includes('/../')) {
+        throw new Error(`Unsafe sync path "${filePath}"`);
+    }
+    return normalized;
+}
+export function shouldSyncFile(filePath) {
+    const normalized = normalizeSyncPath(filePath);
+    const parts = normalized.split('/');
+    const fileName = parts.at(-1) ?? '';
+    if (parts.some((part) => EXCLUDED_PATH_PARTS.has(part))) {
+        return false;
+    }
+    if (fileName === SYNC_MANIFEST_FILE) {
+        return false;
+    }
+    if (fileName === '.env' || (fileName.startsWith('.env.') && fileName !== '.env.example')) {
+        return false;
+    }
+    return true;
+}
+export async function buildSyncManifest(rootDir, input) {
+    const files = await collectSyncFiles(rootDir, rootDir);
+    return {
+        version: 1,
+        workspaceId: input.workspaceId,
+        funnelId: input.funnelId,
+        draftVersionId: input.draftVersionId,
+        files: files.sort((left, right) => left.path.localeCompare(right.path)),
+    };
+}
+export async function writeSyncManifest(rootDir, manifest) {
+    await writeFile(path.join(rootDir, SYNC_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+export async function readSyncManifest(rootDir) {
+    try {
+        const raw = JSON.parse(await readFile(path.join(rootDir, SYNC_MANIFEST_FILE), 'utf8'));
+        if (raw.version !== 1 ||
+            typeof raw.workspaceId !== 'string' ||
+            typeof raw.funnelId !== 'string' ||
+            typeof raw.draftVersionId !== 'string' ||
+            !Array.isArray(raw.files)) {
+            throw new Error(`${SYNC_MANIFEST_FILE} is invalid`);
+        }
+        return {
+            version: 1,
+            workspaceId: raw.workspaceId,
+            funnelId: raw.funnelId,
+            draftVersionId: raw.draftVersionId,
+            files: raw.files.map((file) => ({
+                path: String(file.path || ''),
+                hash: String(file.hash || ''),
+            })),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function collectSourceFiles(rootDir) {
+    const manifest = await buildSyncManifest(rootDir, {
+        workspaceId: '',
+        funnelId: '',
+        draftVersionId: '',
+    });
+    const files = await Promise.all(manifest.files.map(async (file) => {
+        const absolutePath = path.join(rootDir, assertSafeSyncPath(file.path));
+        const imageContentType = inferImageContentType(file.path);
+        const buffer = await readFile(absolutePath);
+        return {
+            path: file.path,
+            content: imageContentType ? `data:${imageContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
+            contentType: imageContentType || 'text/plain',
+        };
+    }));
+    return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+export async function writeSourceFiles(rootDir, files) {
+    for (const file of files) {
+        const relativePath = assertSafeSyncPath(file.path);
+        const absolutePath = path.join(rootDir, relativePath);
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, decodeDataUrl(file.content) || file.content, decodeDataUrl(file.content) ? undefined : 'utf8');
+    }
+}
+async function collectSyncFiles(rootDir, dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = path.join(dir, entry.name);
+        const relativePath = normalizeSyncPath(path.relative(rootDir, absolutePath));
+        if (!shouldSyncFile(relativePath)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            files.push(...(await collectSyncFiles(rootDir, absolutePath)));
+            continue;
+        }
+        if (entry.isFile() || (entry.isSymbolicLink() && (await stat(absolutePath)).isFile())) {
+            files.push({
+                path: relativePath,
+                hash: await hashFile(absolutePath),
+            });
+        }
+    }
+    return files;
+}
+async function hashFile(filePath) {
+    return createHash('sha256').update(await readFile(filePath)).digest('hex');
+}
+function inferImageContentType(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension === '.png') {
+        return 'image/png';
+    }
+    if (extension === '.jpg' || extension === '.jpeg') {
+        return 'image/jpeg';
+    }
+    if (extension === '.webp') {
+        return 'image/webp';
+    }
+    if (extension === '.gif') {
+        return 'image/gif';
+    }
+    if (extension === '.svg') {
+        return 'image/svg+xml';
+    }
+    if (extension === '.avif') {
+        return 'image/avif';
+    }
+    return null;
+}
+function decodeDataUrl(content) {
+    const match = content.trim().match(/^data:([^;,]+);base64,([A-Za-z0-9+/=\s_-]+)$/);
+    if (!match) {
+        return null;
+    }
+    return Buffer.from(match[2].replace(/\s+/g, '').replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}

package/dist/reskin.d.ts

@@ -0,0 +1,4 @@
+export declare const reskinFunnel: (dir: string, appName: string) => Promise<string[]>;
+export declare const KNOWN_TEMPLATE_SLUGS: readonly ["12min", "addmile", "astroline", "betterme-chair-yoga", "blesse", "claimbee-funnel", "headway-funnel", "keiki", "monivate", "promova"];
+export type TemplateSlugs = typeof KNOWN_TEMPLATE_SLUGS;
+export declare const isKnownTemplate: (slug: string) => boolean;

package/dist/reskin.js

@@ -0,0 +1,76 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const toKebabCase = (value) => value
+    .trim()
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+const replaceInFile = async (filePath, replacements) => {
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let changed = false;
+    for (const { pattern, replacement } of replacements) {
+        const next = content.replace(pattern, replacement);
+        if (next !== content) {
+            content = next;
+            changed = true;
+        }
+    }
+    if (changed) {
+        await writeFile(filePath, content, 'utf8');
+    }
+    return changed;
+};
+export const reskinFunnel = async (dir, appName) => {
+    const kebabName = toKebabCase(appName);
+    const updated = [];
+    // 1. Update package.json name
+    const pkgPath = path.join(dir, 'package.json');
+    if (await replaceInFile(pkgPath, [
+        { pattern: /"name":\s*"[^"]*"/, replacement: `"name": "${kebabName}-funnel"` },
+    ])) {
+        updated.push('package.json');
+    }
+    // 2. Update funnel.manifest.ts inline meta (12min pattern)
+    const manifestPath = path.join(dir, 'src', 'config', 'funnel.manifest.ts');
+    if (await replaceInFile(manifestPath, [
+        { pattern: /(title:\s*')[^']*(')/g, replacement: `$1${appName}$2` },
+        { pattern: /(description:\s*')[^']*(')/g, replacement: `$1${appName} web funnel$2` },
+    ])) {
+        updated.push('src/config/funnel.manifest.ts');
+    }
+    // 3. Update funnel.config.ts meta (most other funnels)
+    const configPath = path.join(dir, 'src', 'config', 'funnel.config.ts');
+    if (await replaceInFile(configPath, [
+        { pattern: /(title:\s*')[^']*(')/g, replacement: `$1${appName}$2` },
+        { pattern: /(description:\s*')[^']*(')/g, replacement: `$1${appName} web funnel$2` },
+    ])) {
+        updated.push('src/config/funnel.config.ts');
+    }
+    // 4. 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>` },
+    ])) {
+        updated.push('index.html');
+    }
+    return updated;
+};
+export const KNOWN_TEMPLATE_SLUGS = [
+    '12min',
+    'addmile',
+    'astroline',
+    'betterme-chair-yoga',
+    'blesse',
+    'claimbee-funnel',
+    'headway-funnel',
+    'keiki',
+    'monivate',
+    'promova',
+];
+export const isKnownTemplate = (slug) => KNOWN_TEMPLATE_SLUGS.includes(slug);

package/dist/templateDocs.d.ts

@@ -0,0 +1,2 @@
+export declare const TEMPLATE_DOCS_DIR = "template_docs";
+export declare function syncTemplateDocs(sourceDir: string, targetDir: string): Promise<string[]>;

package/dist/templateDocs.js

@@ -0,0 +1,28 @@
+import { cp, mkdir, readdir } from 'node:fs/promises';
+import path from 'node:path';
+export const TEMPLATE_DOCS_DIR = 'template_docs';
+export async function syncTemplateDocs(sourceDir, targetDir) {
+    const targetRoot = path.resolve(targetDir);
+    const copiedFiles = await listTemplateFiles(sourceDir, sourceDir);
+    await mkdir(targetRoot, { recursive: true });
+    await cp(sourceDir, targetRoot, {
+        recursive: true,
+        force: true,
+    });
+    return copiedFiles.sort((left, right) => left.localeCompare(right));
+}
+async function listTemplateFiles(rootDir, dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listTemplateFiles(rootDir, absolutePath)));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(path.relative(rootDir, absolutePath).replaceAll(path.sep, '/'));
+        }
+    }
+    return files;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@funnelsgrove/cli",
+  "version": "0.1.0",
+  "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
+  "type": "module",
+  "bin": {
+    "fg": "dist/cli.js",
+    "funnelsgrove": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "template_docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}

package/template_docs/agent.md

@@ -0,0 +1,24 @@
+# Funnel Editing Guide
+
+Use this folder as the local source-of-truth guide when editing a synced FunnelsGrove funnel.
+
+## Workflow
+
+1. Run `fg status` and confirm the active project and funnel.
+2. Keep edits inside the synced funnel tree.
+3. Run the funnel's local checks before syncing.
+4. Run `fg sync up --message '<summary>'`.
+5. Run `fg publish --env preview --message '<summary>'` and verify the preview.
+6. Publish production only when explicitly requested.
+
+## Topics
+
+- [Editing a Step](docs/editing-step.md)
+- [Editing Flow](docs/editing-flow.md)
+- [Editor and Content](docs/editor-and-content.md)
+- [Payment Plans and Discounts](docs/payment-plans-and-discounts.md)
+- [SDK API Endpoints](docs/sdk-api-endpoints.md)
+- [Analytics](docs/analytics.md)
+- [A/B Experiments](docs/ab-experiments.md)
+- [Theme](docs/theme.md)
+- [Publishing and Versioning](docs/publishing-and-versioning.md)

package/template_docs/docs/ab-experiments.md

@@ -0,0 +1,10 @@
+# A/B Experiments
+
+Experiments should isolate one decision and make results trustworthy.
+
+Principles:
+- Define the hypothesis before changing variants.
+- Keep assignment stable for a user during the experiment.
+- Change one major variable per experiment when possible.
+- Make variant names clear and durable.
+- Do not remove the control until results are reviewed and the rollout is approved.

package/template_docs/docs/analytics.md

@@ -0,0 +1,10 @@
+# Analytics
+
+Analytics should describe meaningful user behavior, not implementation details.
+
+Principles:
+- Keep event names stable unless a migration is planned.
+- Track step views, key choices, checkout starts, purchases, and major errors.
+- Include only dimensions needed for analysis.
+- Do not send personal data or secrets.
+- When changing flow or offers, verify analytics still fires on the new path.

package/template_docs/docs/editing-flow.md

@@ -0,0 +1,10 @@
+# Editing Flow
+
+The flow controls how users move between steps. Treat flow edits as product logic changes, not only UI changes.
+
+Principles:
+- Keep the happy path short and obvious.
+- Make every conditional branch easy to explain.
+- Preserve back/forward behavior when the funnel supports it.
+- Confirm that skipped steps do not leave required state missing.
+- Update analytics events when a branch, gate, or conversion path changes.

package/template_docs/docs/editing-step.md

@@ -0,0 +1,10 @@
+# Editing a Step
+
+A step is one screen or decision point in the funnel. Keep step changes focused: copy, layout, input behavior, validation, and navigation for that screen.
+
+Principles:
+- Preserve existing step ids and route keys unless the change is explicitly a migration.
+- Reuse existing UI components, tokens, and helper functions.
+- Keep step state local unless another step needs it.
+- Make button labels, validation messages, and analytics events match the changed user action.
+- Test the edited step directly and also test the step before and after it.

package/template_docs/docs/editor-and-content.md

@@ -0,0 +1,10 @@
+# Editor and Content
+
+Content should be editable without making the runtime fragile. Prefer existing content structures over hardcoded one-off strings.
+
+Principles:
+- Keep user-facing copy in the same content pattern the funnel already uses.
+- Use plain, direct copy for actions and error states.
+- Keep legal, pricing, and disclaimer text exact.
+- Do not add unused content fields.
+- If content is repeated across steps, centralize it only when that matches the current funnel pattern.

package/template_docs/docs/payment-plans-and-discounts.md

@@ -0,0 +1,10 @@
+# Payment Plans and Discounts
+
+Payment changes affect conversion, billing, and support. Keep them explicit and easy to review.
+
+Principles:
+- Treat plan ids, price ids, trial lengths, and discount codes as stable contracts.
+- Do not rename or remove a live plan unless the rollout calls for it.
+- Keep displayed price, billing period, trial text, and checkout payload in sync.
+- Test free trials, discounted offers, and default paid plans separately.
+- Update paywall copy and analytics when an offer changes.

package/template_docs/docs/publishing-and-versioning.md

@@ -0,0 +1,10 @@
+# Publishing and Versioning
+
+Syncing creates drafts. Publishing makes a draft available to users.
+
+Principles:
+- Use clear sync and publish messages so versions are reviewable.
+- Publish preview first and verify the returned URL.
+- Production publish requires an explicit production request and target domain.
+- Keep `.funnelsgrove-sync.json` in the local tree; it records the synced draft.
+- If preview verification fails, fix locally, sync up again, and publish a new preview.

package/template_docs/docs/sdk-api-endpoints.md

@@ -0,0 +1,10 @@
+# SDK API Endpoints
+
+SDK calls should be thin, typed boundaries between the funnel and FunnelsGrove services.
+
+Principles:
+- Reuse existing SDK helpers instead of calling raw endpoints directly.
+- Keep request payloads minimal and typed.
+- Handle loading, retryable errors, and final failure states in the UI.
+- Avoid logging personal data, payment data, or secrets.
+- When an endpoint contract changes, update the caller, tests, and docs together.

package/template_docs/docs/theme.md

@@ -0,0 +1,10 @@
+# Theme
+
+Theme changes should make the funnel feel consistent, not create one-off styling.
+
+Principles:
+- Use existing tokens for colors, spacing, typography, and radius.
+- Keep contrast readable across all important states.
+- Check mobile and desktop layouts after theme edits.
+- Avoid changing component internals for a theme-only request.
+- Update shared theme values when the same style appears in multiple places.