@creatorem/cli 0.0.1 → 1.0.4

package/src/utils/env-template.ts

@@ -0,0 +1,635 @@
+import { Project, SyntaxKind } from 'ts-morph';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+export interface EnvVarInfo {
+    name: string;
+    required: boolean;
+    description: string;
+    group: string;
+    defaultValue?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Package map: @kit/foo → absolute directory
+// ---------------------------------------------------------------------------
+
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.next', '.turbo', 'dist', 'build', '.cache', '.expo',
+]);
+
+export async function buildPackageMap(monoRoot: string): Promise<Map<string, string>> {
+    const map = new Map<string, string>();
+
+    const scan = async (dir: string, depth: number) => {
+        if (depth > 6) return;
+        let entries: fs.Dirent[];
+        try { entries = await fs.readdir(dir, { withFileTypes: true }); }
+        catch { return; }
+
+        for (const entry of entries) {
+            if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+            const subDir = path.join(dir, entry.name);
+            const pkgJsonPath = path.join(subDir, 'package.json');
+            if (await fs.pathExists(pkgJsonPath)) {
+                try {
+                    const pkg = await fs.readJson(pkgJsonPath);
+                    if (pkg.name) map.set(pkg.name, subDir);
+                } catch { /* ignore malformed package.json */ }
+            }
+            await scan(subDir, depth + 1);
+        }
+    };
+
+    await scan(monoRoot, 0);
+    return map;
+}
+
+// ---------------------------------------------------------------------------
+// Module specifier resolution
+// ---------------------------------------------------------------------------
+
+function resolveSpecifier(
+    specifier: string,
+    fromDir: string,
+    pkgMap: Map<string, string>,
+): string | null {
+    // Relative imports
+    if (specifier.startsWith('.')) {
+        for (const candidate of [
+            path.resolve(fromDir, specifier + '.ts'),
+            path.resolve(fromDir, specifier, 'index.ts'),
+        ]) {
+            if (fs.existsSync(candidate)) return candidate;
+        }
+        return null;
+    }
+
+    // Exact package name (e.g. '@kit/billing')
+    const exactDir = pkgMap.get(specifier);
+    if (exactDir) {
+        for (const candidate of [
+            path.join(exactDir, 'index.ts'),
+            path.join(exactDir, 'envs.ts'),
+        ]) {
+            if (fs.existsSync(candidate)) return candidate;
+        }
+        return null;
+    }
+
+    // Sub-path (e.g. '@kit/billing/envs' → '@kit/billing' dir + 'envs.ts')
+    for (const [pkgName, pkgDir] of pkgMap) {
+        if (specifier.startsWith(pkgName + '/')) {
+            const subPath = specifier.slice(pkgName.length + 1);
+            for (const candidate of [
+                path.join(pkgDir, subPath + '.ts'),
+                path.join(pkgDir, subPath, 'index.ts'),
+            ]) {
+                if (fs.existsSync(candidate)) return candidate;
+            }
+        }
+    }
+
+    return null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function groupNameFromSpecifier(specifier: string): string {
+    // '@kit/supabase-server/envs' → 'Supabase Server'
+    // '@kit/lemon-squeezy/envs'  → 'Lemon Squeezy'
+    const match = specifier.match(/^@(?:[^/]+)\/([^/]+)/);
+    if (match) {
+        return match[1]
+            .replace(/-/g, ' ')
+            .replace(/\b\w/g, c => c.toUpperCase());
+    }
+    return specifier;
+}
+
+function cleanComment(raw: string): string {
+    return raw
+        .replace(/^\/\*\*?/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, '').trim())
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+}
+
+function extractDefaultFromDescription(description: string): string | undefined {
+    const line = description
+        .split('\n')
+        .map(part => part.trim())
+        .find(part => /^@default(\s|$)/.test(part));
+
+    if (!line) return undefined;
+
+    const rawValue = line.replace(/^@default\s*/, '').trim();
+    if (!rawValue) return undefined;
+
+    // Support patterns like:
+    // @default "http://127.0.0.1:54321" for local dev purpose only
+    const quoted = rawValue.match(/(['"`])((?:\\.|(?!\1).)*)\1/);
+    if (quoted) return quoted[2];
+
+    // Fallback for unquoted defaults with trailing explanation.
+    const token = rawValue.split(/\s+/, 1)[0];
+    return token || undefined;
+}
+
+function extractDefaultFromInitializer(initializer: any): string | undefined {
+    if (!initializer) return undefined;
+
+    const calls = initializer.getDescendantsOfKind?.(SyntaxKind.CallExpression) ?? [];
+    for (const call of calls) {
+        const expr = call.getExpression?.();
+        if (!expr || expr.getKind() !== SyntaxKind.PropertyAccessExpression) continue;
+
+        const access = expr.asKind?.(SyntaxKind.PropertyAccessExpression);
+        if (!access || access.getName() !== 'default') continue;
+
+        const [arg] = call.getArguments?.() ?? [];
+        if (!arg) return undefined;
+
+        switch (arg.getKind()) {
+            case SyntaxKind.StringLiteral:
+            case SyntaxKind.NoSubstitutionTemplateLiteral:
+                return arg.getLiteralText?.() ?? arg.getText().replace(/^['"`]|['"`]$/g, '');
+            case SyntaxKind.NumericLiteral:
+            case SyntaxKind.BigIntLiteral:
+                return arg.getText();
+            case SyntaxKind.TrueKeyword:
+                return 'true';
+            case SyntaxKind.FalseKeyword:
+                return 'false';
+            case SyntaxKind.NullKeyword:
+                return 'null';
+            default:
+                return arg.getText?.();
+        }
+    }
+
+    return undefined;
+}
+
+function getRootIdentifier(node: any): string | null {
+    if (!node) return null;
+    switch (node.getKind()) {
+        case SyntaxKind.Identifier:
+            return node.getText();
+        case SyntaxKind.CallExpression:
+            return getRootIdentifier(node.getExpression());
+        case SyntaxKind.PropertyAccessExpression:
+            return getRootIdentifier(node.getExpression());
+        default:
+            return null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Extract env vars from a single createEnv(...) call
+// ---------------------------------------------------------------------------
+
+function extractVarsFromCreateEnvCall(callExpr: any, group: string): EnvVarInfo[] {
+    const args = callExpr.getArguments?.();
+    if (!args || args.length === 0) return [];
+
+    const configObj = args[0];
+    if (configObj.getKind() !== SyntaxKind.ObjectLiteralExpression) return [];
+
+    // runtimeEnv keys are the canonical env var names
+    const runtimeEnvProp = configObj
+        .getProperty?.('runtimeEnv')
+        ?.asKind?.(SyntaxKind.PropertyAssignment);
+    if (!runtimeEnvProp) return [];
+
+    const runtimeEnvObj = runtimeEnvProp
+        .getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+    if (!runtimeEnvObj) return [];
+
+    const varNames: string[] = [];
+    for (const prop of runtimeEnvObj.getProperties()) {
+        const kind = prop.getKind();
+        if (
+            kind === SyntaxKind.PropertyAssignment ||
+            kind === SyntaxKind.ShorthandPropertyAssignment
+        ) {
+            const name: string | undefined = (prop as any).getName?.();
+            if (name) varNames.push(name);
+        }
+    }
+
+    if (varNames.length === 0) return [];
+
+    // Cross-reference server + client for description and required flag
+    const metaMap = new Map<string, {
+        required: boolean;
+        description: string;
+        defaultValue?: string;
+    }>();
+
+    for (const sectionName of ['server', 'client'] as const) {
+        const sectionObj = configObj
+            .getProperty?.(sectionName)
+            ?.asKind?.(SyntaxKind.PropertyAssignment)
+            ?.getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+        if (!sectionObj) continue;
+
+        for (const prop of sectionObj.getProperties()) {
+            if (prop.getKind() !== SyntaxKind.PropertyAssignment) continue;
+            const pa = prop.asKind?.(SyntaxKind.PropertyAssignment);
+            if (!pa) continue;
+
+            const name: string | undefined = pa.getName?.();
+            if (!name) continue;
+
+            const commentRanges = pa.getLeadingCommentRanges?.() ?? [];
+            const description = commentRanges
+                .map((r: any) => cleanComment(r.getText()))
+                .filter(Boolean)
+                .join('\n');
+            const defaultValue = extractDefaultFromInitializer(pa.getInitializer?.())
+                ?? extractDefaultFromDescription(description);
+
+            const initText: string = pa.getInitializer()?.getText() ?? '';
+            const required = !initText.includes('.optional()');
+
+            metaMap.set(name, { required, description, defaultValue });
+        }
+    }
+
+    return varNames.map(name => ({
+        name,
+        required: metaMap.get(name)?.required ?? true,
+        description: metaMap.get(name)?.description ?? '',
+        group,
+        defaultValue: metaMap.get(name)?.defaultValue,
+    }));
+}
+
+// ---------------------------------------------------------------------------
+// Recursive file collector
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect env vars from a file and its transitive dependencies.
+ *
+ * @param requestedIdentifiers
+ *   - `null`       → collect everything (used when entering a leaf file via re-export)
+ *   - non-null Set → only process createEnv calls whose enclosing variable declaration
+ *                    name is in the set, and only follow re-exports that export one of them.
+ *                    This prevents aggregator files (e.g. @kit/billing/envs) from pulling
+ *                    in sibling exports that are not actually used (e.g. lemonSqueezyEnvs
+ *                    when only stripeEnvs is referenced).
+ */
+export async function collectEnvVarsFromFile(
+    filePath: string,
+    pkgMap: Map<string, string>,
+    visited: Set<string>,
+    group: string,
+    requestedIdentifiers: Set<string> | null = null,
+): Promise<EnvVarInfo[]> {
+    if (visited.has(filePath) || !fs.existsSync(filePath)) return [];
+    visited.add(filePath);
+
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    let sourceFile: any;
+    try {
+        sourceFile = project.addSourceFileAtPath(filePath);
+    } catch {
+        return [];
+    }
+
+    const fromDir = path.dirname(filePath);
+    const results: EnvVarInfo[] = [];
+
+    // ── Step 1: Follow re-exports ─────────────────────────────────────────
+    // e.g. `export { stripeEnvs } from '@kit/stripe/envs'`
+    // When requestedIdentifiers is set, only follow re-exports that export at
+    // least one of the requested identifiers. This is the key guard that stops
+    // lemonSqueezyEnvs / umamiEnvs from being collected when they aren't used.
+    for (const exportDec of sourceFile.getExportDeclarations()) {
+        if (!exportDec.hasModuleSpecifier?.()) continue;
+        const spec: string = exportDec.getModuleSpecifierValue?.() ?? '';
+        if (!spec) continue;
+
+        if (requestedIdentifiers && requestedIdentifiers.size > 0) {
+            const namedExports: string[] = (exportDec.getNamedExports?.() ?? [])
+                .map((e: any) => e.getName?.() ?? '');
+            if (!namedExports.some(n => requestedIdentifiers.has(n))) continue;
+        }
+
+        const resolved = resolveSpecifier(spec, fromDir, pkgMap);
+        if (!resolved) continue;
+
+        const subGroup = spec.startsWith('@') ? groupNameFromSpecifier(spec) : group;
+        // Entering the target of a re-export: the file is a leaf, collect everything.
+        results.push(...await collectEnvVarsFromFile(resolved, pkgMap, visited, subGroup, null));
+    }
+
+    // ── Step 2: Process createEnv(...) calls ──────────────────────────────
+    const calls: any[] = sourceFile
+        .getDescendantsOfKind(SyntaxKind.CallExpression)
+        .filter((c: any) => {
+            try { return c.getExpression().getText() === 'createEnv'; }
+            catch { return false; }
+        });
+
+    for (const call of calls) {
+        // When we have specific identifiers to look for, only process createEnv
+        // calls that belong to one of those identifiers. We detect ownership via
+        // the nearest enclosing VariableDeclaration (which holds the function or
+        // object that wraps this createEnv call).
+        if (requestedIdentifiers && requestedIdentifiers.size > 0) {
+            const enclosingVarName: string | undefined = call
+                .getFirstAncestorByKind?.(SyntaxKind.VariableDeclaration)
+                ?.getName?.();
+            // Skip if the enclosing var doesn't match, or if there is none.
+            if (!enclosingVarName || !requestedIdentifiers.has(enclosingVarName)) continue;
+        }
+
+        const args = call.getArguments?.();
+        if (!args || args.length === 0) continue;
+        const configObj = args[0];
+        if (configObj.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
+
+        // 2a. Follow `extends` entries first so the upstream packages appear in
+        //     the template before this file's own local vars.
+        //     Group entries by source module specifier so that multiple identifiers
+        //     from the same module (e.g. utilsEnvs + sharedRouteEnvs from @kit/utils/envs)
+        //     are collected in a single recursive call — otherwise the visited set would
+        //     block the second identifier.
+        const extendsProp = configObj
+            .getProperty?.('extends')
+            ?.asKind?.(SyntaxKind.PropertyAssignment);
+
+        if (extendsProp) {
+            const extendsArr = extendsProp
+                .getInitializerIfKind(SyntaxKind.ArrayLiteralExpression);
+
+            if (extendsArr) {
+                // Map: moduleSpecifier → { subGroup, rootIds }
+                const byModule = new Map<string, { subGroup: string; rootIds: Set<string> }>();
+
+                for (const element of extendsArr.getElements()) {
+                    const rootId = getRootIdentifier(element);
+                    if (!rootId) continue;
+
+                    let importDec: any;
+                    try {
+                        importDec = sourceFile.getImportDeclarations().find((imp: any) => {
+                            try {
+                                if (imp.getNamedImports().some(
+                                    (n: any) => n.getNameNode().getText() === rootId
+                                )) return true;
+                                if (imp.getDefaultImport()?.getText() === rootId) return true;
+                                if (imp.getNamespaceImport()?.getText() === rootId) return true;
+                            } catch { /* ignore */ }
+                            return false;
+                        });
+                    } catch { /* ignore */ }
+
+                    if (!importDec) continue;
+                    const moduleSpec: string = importDec.getModuleSpecifierValue?.() ?? '';
+                    if (!moduleSpec) continue;
+
+                    if (!byModule.has(moduleSpec)) {
+                        const subGroup = moduleSpec.startsWith('@')
+                            ? groupNameFromSpecifier(moduleSpec)
+                            : group;
+                        byModule.set(moduleSpec, { subGroup, rootIds: new Set() });
+                    }
+                    byModule.get(moduleSpec)!.rootIds.add(rootId);
+                }
+
+                // Recurse once per source module, passing the set of identifiers
+                // we need from that module. This propagates the filtering all the
+                // way through aggregator files.
+                for (const [moduleSpec, { subGroup, rootIds }] of byModule.entries()) {
+                    const resolvedModule = resolveSpecifier(moduleSpec, fromDir, pkgMap);
+                    if (!resolvedModule) continue;
+                    results.push(
+                        ...await collectEnvVarsFromFile(
+                            resolvedModule, pkgMap, visited, subGroup, rootIds,
+                        )
+                    );
+                }
+            }
+        }
+
+        // 2b. Extract this call's own runtimeEnv vars (after extends so that
+        //     duplicates — e.g. EMAIL_FROM — are attributed to the upstream package).
+        results.push(...extractVarsFromCreateEnvCall(call, group));
+    }
+
+    return results;
+}
+
+// ---------------------------------------------------------------------------
+// Template generator
+// ---------------------------------------------------------------------------
+
+export function generateEnvTemplate(vars: EnvVarInfo[]): string {
+    // Deduplicate by name – first occurrence wins (upstream package definition
+    // takes priority over the dashboard's re-declaration of the same var).
+    const seen = new Set<string>();
+    const unique: EnvVarInfo[] = [];
+    for (const v of vars) {
+        if (!seen.has(v.name)) {
+            seen.add(v.name);
+            unique.push(v);
+        }
+    }
+
+    // Group by source package, preserving insertion order
+    const groups = new Map<string, EnvVarInfo[]>();
+    for (const v of unique) {
+        if (!groups.has(v.group)) groups.set(v.group, []);
+        groups.get(v.group)!.push(v);
+    }
+
+    const lines: string[] = [
+        '# =============================================================================',
+        '# Dashboard Environment Variables',
+        '# Generated by Creatorem CLI',
+        '# =============================================================================',
+        '',
+    ];
+
+    for (const [group, groupVars] of groups) {
+        const bar = '─'.repeat(Math.max(2, 76 - group.length));
+        lines.push(`# ── ${group} ${bar}`);
+        lines.push('');
+
+        for (const v of groupVars) {
+            if (v.description) {
+                for (const line of v.description.split('\n')) {
+                    if (line.trim()) lines.push(`# ${line}`);
+                }
+            }
+            if (!v.required) lines.push('# optional');
+            lines.push(`${v.name}=${v.defaultValue ?? ''}`);
+            lines.push('');
+        }
+    }
+
+    return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse `apps/dashboard/envs.ts` (after feature removals have been applied),
+ * recursively follow only the env definitions that are actually referenced in
+ * the extends array, and write `.env.template` into the dashboard root.
+ */
+export interface GenerateEnvTemplateOptions {
+    createEnvFile?: boolean;
+    fallbackMonoRoot?: string;
+}
+
+function isWithinRoot(root: string, target: string): boolean {
+    const rel = path.relative(root, target);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function isCreatoreMonorepoRoot(root: string): boolean {
+    return (
+        fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) &&
+        fs.existsSync(path.join(root, 'turbo.json')) &&
+        fs.existsSync(path.join(root, 'apps')) &&
+        fs.existsSync(path.join(root, 'kit'))
+    );
+}
+
+function findNearestCreatoreMonorepoRoot(startDir: string): string | null {
+    let current = path.resolve(startDir);
+
+    while (true) {
+        if (isCreatoreMonorepoRoot(current)) return current;
+        const parent = path.dirname(current);
+        if (parent === current) return null;
+        current = parent;
+    }
+}
+
+function getImplicitFallbackRoots(): string[] {
+    const roots = new Set<string>();
+    const addNearestRoot = (startDir: string) => {
+        const root = findNearestCreatoreMonorepoRoot(startDir);
+        if (root) roots.add(root);
+    };
+
+    addNearestRoot(process.cwd());
+
+    try {
+        const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+        addNearestRoot(moduleDir);
+    } catch {
+        // Ignore when module path cannot be resolved in non-standard runtimes.
+    }
+
+    return Array.from(roots);
+}
+
+function mergeEnvVarMetadata(vars: EnvVarInfo[], fallbackVars: EnvVarInfo[]): EnvVarInfo[] {
+    const fallbackByName = new Map<string, { description: string; defaultValue?: string }>();
+
+    for (const v of fallbackVars) {
+        const existing = fallbackByName.get(v.name);
+        if (!existing) {
+            fallbackByName.set(v.name, {
+                description: v.description,
+                defaultValue: v.defaultValue,
+            });
+            continue;
+        }
+
+        fallbackByName.set(v.name, {
+            description: existing.description || v.description,
+            defaultValue: existing.defaultValue ?? v.defaultValue,
+        });
+    }
+
+    return vars.map(v => {
+        const fallback = fallbackByName.get(v.name);
+        if (!fallback) return v;
+
+        return {
+            ...v,
+            description: v.description || fallback.description,
+            defaultValue: v.defaultValue ?? fallback.defaultValue,
+        };
+    });
+}
+
+export async function generateDashboardEnvTemplate(
+    dashboardRoot: string,
+    monoRoot: string,
+    options: GenerateEnvTemplateOptions = {},
+): Promise<void> {
+    const envsPath = path.join(dashboardRoot, 'envs.ts');
+    if (!fs.existsSync(envsPath)) return;
+
+    const pkgMap = await buildPackageMap(monoRoot);
+    const visited = new Set<string>();
+    // Initial call: null requestedIdentifiers → collect the dashboard file in full
+    const vars = await collectEnvVarsFromFile(envsPath, pkgMap, visited, 'Dashboard', null);
+
+    let mergedVars = vars;
+    const resolvedMonoRoot = path.resolve(monoRoot);
+    const resolvedDashboardRoot = path.resolve(dashboardRoot);
+
+    if (isWithinRoot(resolvedMonoRoot, resolvedDashboardRoot)) {
+        const relativeAppPath = path.relative(resolvedMonoRoot, resolvedDashboardRoot);
+        const fallbackCandidates = [
+            options.fallbackMonoRoot,
+            ...getImplicitFallbackRoots(),
+        ]
+            .filter((candidate): candidate is string => Boolean(candidate))
+            .map(candidate => path.resolve(candidate))
+            .filter(candidate => candidate !== resolvedMonoRoot);
+
+        const seenFallbackRoots = new Set<string>();
+
+        for (const fallbackRoot of fallbackCandidates) {
+            if (seenFallbackRoots.has(fallbackRoot)) continue;
+            seenFallbackRoots.add(fallbackRoot);
+
+            const fallbackAppRoot = path.join(fallbackRoot, relativeAppPath);
+            const fallbackEnvsPath = path.join(fallbackAppRoot, 'envs.ts');
+            if (!await fs.pathExists(fallbackEnvsPath)) continue;
+
+            const fallbackPkgMap = await buildPackageMap(fallbackRoot);
+            const fallbackVisited = new Set<string>();
+            const fallbackVars = await collectEnvVarsFromFile(
+                fallbackEnvsPath,
+                fallbackPkgMap,
+                fallbackVisited,
+                'Dashboard',
+                null,
+            );
+
+            mergedVars = mergeEnvVarMetadata(mergedVars, fallbackVars);
+        }
+    }
+
+    const content = generateEnvTemplate(mergedVars);
+    const templatePath = path.join(dashboardRoot, '.env.template');
+    await fs.writeFile(templatePath, content, 'utf-8');
+
+    if (options.createEnvFile) {
+        const envPath = path.join(dashboardRoot, '.env');
+        const envExists = await fs.pathExists(envPath);
+        if (!envExists) {
+            await fs.copy(templatePath, envPath);
+        }
+    }
+}