@funnelsgrove/cli 0.1.231 → 0.1.237

package/README.md

@@ -150,3 +150,14 @@ rows changed since the last pull. Pull again to resolve a concurrent edit.
 
 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`.
+
+### Add a content locale
+
+Run `fgrove locales add ru --dir ./my-funnel` to copy every default content
+object into `src/localization/ru/`, preserving its path relative to `src/`.
+Original content stays in place; translated files import its structural type.
+Repeat runs preserve translations, add missing exports and repair registrations.
+Translate the new content, run `npx tsc --noEmit`, review `?locale=ru` and the live builder Preview language
+selector, then sync and publish through the normal workflow. Run `fgrove docs`
+for the full localization guide. The funnel must use a runtime release supporting
+URL locale selection; this command does not upgrade dependencies.

package/dist/cli.js

@@ -7,6 +7,7 @@ import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
+import { addFunnelLocale } from './locales.js';
 import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, PREVIOUS_STEP_CONTRACT_VERSION, createFunnelContractDiagnostic, } from '@funnelsgrove/runtime';
 import { abortFunnelSourceCandidate, applyFunnelDraftPatch, beginFunnelSourceCandidate, callTrpcProcedure, createFunnelExperimentFromSpec, finalizeFunnelDirectAssetUpload, finalizeFunnelSourceCandidate, prepareFunnelDirectAssetUpload, stageFunnelSourceCandidate, } from './apiClient.js';
 import { cliReleaseIdentity } from './cliIdentity.js';
@@ -2980,6 +2981,15 @@ addExamples(githubCommand
     });
     printValueRows(formatGitHubJobRows(result));
 });
+program.command('locales')
+    .description('Manage local funnel content languages')
+    .command('add <locale>')
+    .description('Create or complete typed localization files without translating')
+    .option('--dir <path>', 'Local funnel directory', '.')
+    .action(async (locale, options) => {
+    const result = await addFunnelLocale(path.resolve(options.dir), locale);
+    console.log(`${result.locale}\t${result.added.length} added\t${result.existing.length} already present`);
+});
 addExamples(program
     .command('validate')
     .description('Validate a local funnel against the current authoring contract')

package/dist/localeContentSource.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+export declare const modulePath: (from: string, to: string) => string;
+export declare function property(object: ts.ObjectLiteralExpression, name: string): ts.PropertyAssignment | undefined;
+export type ContentDefinition = {
+    name: string;
+    type: string;
+    defaultLocale: string;
+    map: ts.ObjectLiteralExpression;
+};
+export declare function readContentDefinitions(parsed: ts.SourceFile): ContentDefinition[];
+/** Copies authored expressions, redirecting same-file inheritance to the translated export. */
+export declare function translatedExpression(value: ts.Expression, parsed: ts.SourceFile, definitions: ContentDefinition[], locale: string, existingBindings?: ReadonlyMap<string, string | null>): string;
+export declare function contentImports(parsed: ts.SourceFile, destination: string, payload: string): string[];

package/dist/localeContentSource.js

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import ts from 'typescript';
+import { selectImport } from './localeModuleEdits.js';
+export const modulePath = (from, to) => {
+    const relative = path.relative(path.dirname(from), to).split(path.sep).join('/').replace(/\.ts$/, '');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+};
+export function property(object, name) {
+    return object.properties.find((node) => ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) && node.name.text === name);
+}
+export function readContentDefinitions(parsed) {
+    const definitions = [];
+    for (const statement of parsed.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            let expression = declaration.initializer;
+            let type = declaration.type;
+            while (expression && (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isParenthesizedExpression(expression))) {
+                if (!ts.isParenthesizedExpression(expression) && ts.isTypeReferenceNode(expression.type) && expression.type.typeArguments?.length)
+                    type = expression.type;
+                expression = expression.expression;
+            }
+            if (!expression || !ts.isObjectLiteralExpression(expression))
+                continue;
+            const base = property(expression, 'defaultLocale');
+            const locales = property(expression, 'locales');
+            if (!base || !locales)
+                continue;
+            if (!ts.isStringLiteral(base.initializer) || !ts.isObjectLiteralExpression(locales.initializer))
+                throw new Error('defaultLocale and locales must be literals.');
+            if (locales.initializer.properties.some((item) => !ts.isPropertyAssignment(item) || !(ts.isIdentifier(item.name) || ts.isStringLiteral(item.name))))
+                throw new Error('locale entries must be explicit properties, without spreads or computed names.');
+            const contentType = type && ts.isTypeReferenceNode(type) && type.typeArguments?.[0];
+            if (!ts.isIdentifier(declaration.name) || !contentType || !ts.isTypeReferenceNode(contentType) || !ts.isIdentifier(contentType.typeName))
+                throw new Error('Declare a named content type and use satisfies LocalizedStepContent<YourContentType>.');
+            if (contentType.typeArguments?.length)
+                throw new Error('Use a named non-generic content type; generic content types are not supported by locale copying.');
+            const typeName = contentType.typeName.text;
+            const owner = parsed.statements.find((item) => (ts.isTypeAliasDeclaration(item) || ts.isInterfaceDeclaration(item)) && item.name.text === typeName);
+            if (!owner)
+                throw new Error(`Declare ${typeName} in this original content file so translations can import its structure.`);
+            definitions.push({ name: declaration.name.text, type: typeName, defaultLocale: base.initializer.text, map: locales.initializer });
+        }
+    }
+    if (!definitions.length)
+        throw new Error('No localized content definition found.');
+    return definitions;
+}
+/** Copies authored expressions, redirecting same-file inheritance to the translated export. */
+export function translatedExpression(value, parsed, definitions, locale, existingBindings = new Map()) {
+    const edits = [];
+    const options = { noLib: true, noResolve: true };
+    const host = ts.createCompilerHost(options);
+    host.getSourceFile = (name) => path.resolve(name) === path.resolve(parsed.fileName) ? parsed : undefined;
+    const checker = ts.createProgram([parsed.fileName], options, host).getTypeChecker();
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+            const map = node.expression;
+            const key = ts.isPropertyAccessExpression(node) ? node.name.text : ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text : null;
+            if (ts.isPropertyAccessExpression(map) && map.name.text === 'locales' && ts.isIdentifier(map.expression)) {
+                const definition = definitions.find((item) => item.name === map.expression.getText(parsed));
+                if (definition && key) {
+                    if (key !== definition.defaultLocale && key !== locale) {
+                        throw new Error(`Cannot copy ${node.getText(parsed)}: inheritance must use the default or requested locale. Make this copy explicit before retrying.`);
+                    }
+                    const binding = existingBindings.get(definition.name);
+                    if (binding === null)
+                        throw new Error(`Import the re-exported ${definition.name} into the translation before adding inherited content.`);
+                    edits.push({ start: node.getStart(parsed), end: node.end, text: binding ?? definition.name });
+                    return;
+                }
+            }
+        }
+        if (ts.isIdentifier(node)
+            && !(ts.isPropertyAssignment(node.parent) && node.parent.name === node)
+            && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node)) {
+            const symbol = ts.isShorthandPropertyAssignment(node.parent)
+                ? checker.getShorthandAssignmentValueSymbol(node.parent)
+                : checker.getSymbolAtLocation(node);
+            const uncopied = symbol?.declarations?.some((declaration) => {
+                if (declaration.getSourceFile() !== parsed || declaration.pos >= value.pos && declaration.end <= value.end)
+                    return false;
+                let parent = declaration;
+                while (parent && parent !== parsed) {
+                    if (ts.isImportDeclaration(parent))
+                        return false;
+                    parent = parent.parent;
+                }
+                return true;
+            });
+            if (uncopied)
+                throw new Error(`Content references local helper ${node.text}. Inline it in the content object or move it into an independent imported module before adding a locale.`);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(value);
+    let result = value.getText(parsed);
+    const offset = value.getStart(parsed);
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+        result = result.slice(0, edit.start - offset) + edit.text + result.slice(edit.end - offset);
+    return result;
+}
+export function contentImports(parsed, destination, payload) {
+    const identifiers = new Set();
+    const visit = (node) => { if (ts.isIdentifier(node))
+        identifiers.add(node.text); ts.forEachChild(node, visit); };
+    visit(ts.createSourceFile('content.ts', payload, ts.ScriptTarget.Latest, true));
+    return parsed.statements.flatMap((statement) => {
+        if (!ts.isImportDeclaration(statement) || !statement.importClause || !ts.isStringLiteral(statement.moduleSpecifier))
+            return [];
+        const specifier = statement.moduleSpecifier.text;
+        const target = specifier.startsWith('.') ? modulePath(destination, path.resolve(path.dirname(parsed.fileName), specifier)) : specifier;
+        const selected = selectImport(statement, parsed, (name) => identifiers.has(name), ts.factory.createStringLiteral(target));
+        return selected ? [selected] : [];
+    });
+}

package/dist/localeFilePlan.d.ts

@@ -0,0 +1,4 @@
+export declare function planLocaleFile(file: string, source: string, destination: string, translated: string | null, locale: string): {
+    source: string;
+    translated: string | null;
+};

package/dist/localeFilePlan.js

@@ -0,0 +1,63 @@
+import ts from 'typescript';
+import { contentImports, modulePath, property, readContentDefinitions, translatedExpression } from './localeContentSource.js';
+import { appendTranslation, applySourceEdits, exportedBindings, importedNames, insertImports } from './localeModuleEdits.js';
+export function planLocaleFile(file, source, destination, translated, locale) {
+    const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const definitions = readContentDefinitions(parsed);
+    const canonical = (tag) => Intl.getCanonicalLocales(tag)[0];
+    if (new Set(definitions.map((item) => canonical(item.defaultLocale))).size !== 1) {
+        throw new Error('Definitions in one content file must use the same defaultLocale.');
+    }
+    if (canonical(definitions[0].defaultLocale) === locale)
+        return { source, translated };
+    const translatedModule = ts.createSourceFile(destination, translated ?? '', ts.ScriptTarget.Latest, true);
+    const present = exportedBindings(translatedModule);
+    const sourceImports = importedNames(parsed);
+    const registrationPath = modulePath(file, destination);
+    const edits = [];
+    const exports = [];
+    const imports = [];
+    const newTypes = new Set();
+    const typeNames = new Set(definitions.map((item) => item.type));
+    for (const definition of definitions) {
+        const previous = definition.map.properties.find((item) => ts.isPropertyAssignment(item)
+            && canonical(item.name.text) === locale);
+        if (!present.has(definition.name)) {
+            const value = (previous ?? property(definition.map, definition.defaultLocale))?.initializer;
+            if (!value || !ts.isObjectLiteralExpression(value)) {
+                throw new Error(`Restore the missing translation for ${definition.name} or provide inline object content before retrying.`);
+            }
+            exports.push(`export const ${definition.name}: ${definition.type} = ${translatedExpression(value, parsed, definitions, locale, present)};`);
+            newTypes.add(definition.type);
+        }
+        const registered = [...sourceImports].find(([, value]) => value.module === registrationPath && value.name === definition.name && !value.typeOnly)?.[0];
+        if (registered && previous && ts.isIdentifier(previous.initializer) && previous.initializer.text === registered)
+            continue;
+        let alias = registered ?? `${definition.name}_${locale.replace(/-/g, '_')}`;
+        if (!registered) {
+            const initial = alias;
+            let suffix = 1;
+            while (source.includes(alias))
+                alias = `${initial}_${suffix++}`;
+            imports.push(`import { ${definition.name} as ${alias} } from ${JSON.stringify(registrationPath)};`);
+        }
+        if (previous)
+            edits.push({ start: previous.initializer.getStart(parsed), end: previous.initializer.end, text: alias });
+        else
+            edits.push({ start: definition.map.end - 1, end: definition.map.end - 1, text: `${definition.map.properties.hasTrailingComma ? '' : ','}\n    ${JSON.stringify(locale)}: ${alias},\n  ` });
+    }
+    for (const statement of parsed.statements) {
+        if ((ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) && typeNames.has(statement.name.text)
+            && !statement.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) {
+            edits.push({ start: statement.getStart(parsed), end: statement.getStart(parsed), text: 'export ' });
+        }
+    }
+    const payload = exports.join('\n\n');
+    const dependencies = exports.length ? contentImports(parsed, destination, payload) : [];
+    if (newTypes.size)
+        dependencies.unshift(`import type { ${[...newTypes].join(', ')} } from ${JSON.stringify(modulePath(destination, file))};`);
+    return {
+        source: insertImports(applySourceEdits(source, edits), imports),
+        translated: appendTranslation(translated ?? '', dependencies, exports),
+    };
+}

package/dist/localeModuleEdits.d.ts

@@ -0,0 +1,19 @@
+import ts from 'typescript';
+export type SourceEdit = {
+    start: number;
+    end: number;
+    text: string;
+};
+export declare function applySourceEdits(source: string, edits: SourceEdit[]): string;
+/** Keep module directives and leading comments before generated imports. */
+export declare function insertImports(source: string, imports: string[]): string;
+export declare function importedNames(parsed: ts.SourceFile): Map<string, {
+    module: string;
+    name: string;
+    typeOnly: boolean;
+}>;
+export declare function exportedBindings(parsed: ts.SourceFile): Map<string, string | null>;
+/** Print the selected bindings, preserving import kinds and attributes. */
+export declare function selectImport(statement: ts.ImportDeclaration, parsed: ts.SourceFile, keep: (name: string) => boolean, module?: ts.Expression): string | null;
+/** Reuse matching imports when adding definitions to an already translated module. */
+export declare function appendTranslation(source: string, imports: string[], definitions: string[]): string;

package/dist/localeModuleEdits.js

@@ -0,0 +1,97 @@
+import ts from 'typescript';
+export function applySourceEdits(source, edits) {
+    return [...edits].sort((a, b) => b.start - a.start).reduce((result, edit) => result.slice(0, edit.start) + edit.text + result.slice(edit.end), source);
+}
+/** Keep module directives and leading comments before generated imports. */
+export function insertImports(source, imports) {
+    if (!imports.length)
+        return source;
+    const parsed = ts.createSourceFile('content.ts', source, ts.ScriptTarget.Latest, true);
+    const first = parsed.statements.find((statement) => !ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression));
+    const offset = first?.getStart(parsed) ?? source.length;
+    return source.slice(0, offset) + imports.join('\n') + '\n' + source.slice(offset);
+}
+export function importedNames(parsed) {
+    const names = new Map();
+    for (const statement of parsed.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const clause = statement.importClause;
+        if (!clause)
+            continue;
+        const module = statement.moduleSpecifier.text;
+        if (clause.name)
+            names.set(clause.name.text, { module, name: 'default', typeOnly: clause.isTypeOnly });
+        const bindings = clause.namedBindings;
+        if (bindings && ts.isNamespaceImport(bindings))
+            names.set(bindings.name.text, { module, name: '*', typeOnly: clause.isTypeOnly });
+        if (bindings && ts.isNamedImports(bindings)) {
+            for (const item of bindings.elements)
+                names.set(item.name.text, { module, name: (item.propertyName ?? item.name).text, typeOnly: clause.isTypeOnly || item.isTypeOnly });
+        }
+    }
+    return names;
+}
+export function exportedBindings(parsed) {
+    const names = new Map();
+    for (const statement of parsed.statements) {
+        if (ts.isVariableStatement(statement)
+            && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    names.set(declaration.name.text, declaration.name.text);
+            }
+        }
+        if (ts.isExportDeclaration(statement) && !statement.isTypeOnly
+            && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+            for (const item of statement.exportClause.elements) {
+                if (!item.isTypeOnly)
+                    names.set(item.name.text, statement.moduleSpecifier ? null : (item.propertyName ?? item.name).text);
+            }
+        }
+    }
+    return names;
+}
+/** Print the selected bindings, preserving import kinds and attributes. */
+export function selectImport(statement, parsed, keep, module = statement.moduleSpecifier) {
+    const clause = statement.importClause;
+    if (!clause)
+        return null;
+    const name = clause.name && keep(clause.name.text) ? clause.name : undefined;
+    const bindings = clause.namedBindings;
+    const named = bindings && (ts.isNamespaceImport(bindings)
+        ? keep(bindings.name.text) ? bindings : undefined
+        : ts.factory.createNamedImports(bindings.elements.filter((item) => keep(item.name.text))));
+    if (!name && (!named || ts.isNamedImports(named) && !named.elements.length))
+        return null;
+    const updated = ts.factory.updateImportDeclaration(statement, statement.modifiers, ts.factory.updateImportClause(clause, clause.isTypeOnly, name, named), module, statement.attributes);
+    return ts.createPrinter().printNode(ts.EmitHint.Unspecified, updated, parsed);
+}
+/** Reuse matching imports when adding definitions to an already translated module. */
+export function appendTranslation(source, imports, definitions) {
+    const parsed = ts.createSourceFile('content.ts', source, ts.ScriptTarget.Latest, true);
+    const existing = importedNames(parsed);
+    const additions = [];
+    for (const text of imports) {
+        const imported = ts.createSourceFile('import.ts', text, ts.ScriptTarget.Latest, true);
+        const statement = imported.statements[0];
+        const names = importedNames(imported);
+        const needed = (name) => {
+            const previous = existing.get(name);
+            const next = names.get(name);
+            if (!previous) {
+                existing.set(name, next);
+                return true;
+            }
+            if (previous.module !== next.module || previous.name !== next.name || previous.typeOnly !== next.typeOnly) {
+                throw new Error(`Translation import ${name} conflicts with an existing import. Resolve the import before retrying.`);
+            }
+            return false;
+        };
+        const addition = selectImport(statement, imported, needed);
+        if (addition)
+            additions.push(addition);
+    }
+    const updated = insertImports(source, additions);
+    return definitions.length ? `${updated}${updated.endsWith('\n') || !updated ? '' : '\n'}\n${definitions.join('\n\n')}\n` : updated;
+}

package/dist/locales.d.ts

@@ -0,0 +1,6 @@
+/** Plan every source change before writing; original content keeps its existing location. */
+export declare function addFunnelLocale(directory: string, requestedLocale: string): Promise<{
+    locale: string;
+    added: string[];
+    existing: string[];
+}>;

package/dist/locales.js

@@ -0,0 +1,92 @@
+import { lstat, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { planLocaleFile } from './localeFilePlan.js';
+function canonicalLocale(value) {
+    try {
+        const [locale] = Intl.getCanonicalLocales(value);
+        if (locale)
+            return locale;
+    }
+    catch { /* Invalid tag. */ }
+    throw new Error(`Invalid locale: ${value}. Use a language tag such as ru or pt-BR.`);
+}
+async function contentFiles(directory, localizationRoot) {
+    const files = [];
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(directory, entry.name);
+        if (file === localizationRoot)
+            continue;
+        if (entry.isDirectory())
+            files.push(...await contentFiles(file, localizationRoot));
+        else if (entry.isFile() && entry.name.endsWith('.content.ts'))
+            files.push(file);
+    }
+    return files;
+}
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function assertDestinationPath(root, file) {
+    let current = root;
+    for (const part of path.relative(root, file).split(path.sep)) {
+        current = path.join(current, part);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error(`Localization destination contains a symbolic link: ${current}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+/** Plan every source change before writing; original content keeps its existing location. */
+export async function addFunnelLocale(directory, requestedLocale) {
+    directory = path.resolve(directory);
+    const locale = canonicalLocale(requestedLocale);
+    const sourceRoot = path.join(directory, 'src');
+    const localizationRoot = path.join(sourceRoot, 'localization');
+    const files = await contentFiles(sourceRoot, localizationRoot);
+    if (!files.length)
+        throw new Error('No src/**/*.content.ts files found. Move translatable copy into content definitions first.');
+    const edits = [];
+    const added = [];
+    const existing = [];
+    for (const file of files) {
+        const relative = path.relative(directory, file).split(path.sep).join('/');
+        try {
+            const source = await readFile(file, 'utf8');
+            const destination = path.join(localizationRoot, locale, path.relative(sourceRoot, file));
+            const localizedPath = path.relative(directory, destination).split(path.sep).join('/');
+            await assertDestinationPath(sourceRoot, destination);
+            const translated = await exists(destination) ? await readFile(destination, 'utf8') : null;
+            const plan = planLocaleFile(file, source, destination, translated, locale);
+            if (plan.source === source && plan.translated === translated) {
+                existing.push(translated === null ? relative : localizedPath);
+                continue;
+            }
+            if (plan.translated !== translated && plan.translated !== null) {
+                edits.push({ file: destination, source: plan.translated, create: translated === null });
+            }
+            if (plan.source !== source)
+                edits.push({ file, source: plan.source });
+            added.push(localizedPath);
+        }
+        catch (error) {
+            throw new Error(`${relative}: ${error.message}`);
+        }
+    }
+    for (const edit of edits) {
+        await mkdir(path.dirname(edit.file), { recursive: true });
+        await writeFile(edit.file, edit.source, edit.create ? { flag: 'wx' } : undefined);
+    }
+    return { locale, added, existing };
+}