@zintrust/core 0.1.28 → 0.1.30

package/src/cli/scaffolding/ProjectScaffolder.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Project Scaffolder - New project generation
+ * Handles directory structure and boilerplate file creation
+ */
+export interface ProjectScaffoldOptions {
+    name: string;
+    force?: boolean;
+    overwrite?: boolean;
+    template?: string;
+    port?: number;
+    author?: string;
+    description?: string;
+    git?: boolean;
+    install?: boolean;
+    database?: string;
+    driver?: string;
+}
+export type ProjectOptions = ProjectScaffoldOptions;
+export interface ProjectTemplate {
+    name: string;
+    description: string;
+    directories: string[];
+    files: Record<string, string>;
+}
+export interface ProjectScaffoldResult {
+    success: boolean;
+    projectPath: string;
+    filesCreated: number;
+    directoriesCreated: number;
+    message: string;
+    error?: Error;
+}
+export interface IProjectScaffolder {
+    prepareContext(options: ProjectScaffoldOptions): void;
+    getVariables(): Record<string, unknown>;
+    getTemplateInfo(templateName?: string): ProjectTemplate | undefined;
+    getProjectPath(): string;
+    projectDirectoryExists(): boolean;
+    createDirectories(): number;
+    createFiles(options?: ProjectScaffoldOptions): number;
+    createConfigFile(): boolean;
+    createEnvFile(): boolean;
+    scaffold(options: ProjectScaffoldOptions): Promise<ProjectScaffoldResult>;
+}
+export declare function getAvailableTemplates(): string[];
+export declare function getTemplate(name: string): ProjectTemplate | undefined;
+export declare function validateOptions(options: ProjectScaffoldOptions): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Plain-function scaffolder creator (replaces the function-object factory).
+ */
+export declare function createProjectScaffolder(projectPath?: string): IProjectScaffolder;
+export declare function scaffoldProject(projectPath: string, options: ProjectScaffoldOptions): Promise<ProjectScaffoldResult>;
+/**
+ * Sealed namespace for ProjectScaffolder
+ */
+export declare const ProjectScaffolder: Readonly<{
+    create: typeof createProjectScaffolder;
+    getAvailableTemplates: typeof getAvailableTemplates;
+    getTemplate: typeof getTemplate;
+    validateOptions: typeof validateOptions;
+    scaffold: typeof scaffoldProject;
+}>;
+//# sourceMappingURL=ProjectScaffolder.d.ts.map

package/src/cli/scaffolding/ProjectScaffolder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AA6eD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA4ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}

package/src/cli/scaffolding/ProjectScaffolder.js

@@ -0,0 +1,629 @@
+/**
+ * Project Scaffolder - New project generation
+ * Handles directory structure and boilerplate file creation
+ */
+import { EnvFileBackfill } from '../env/EnvFileBackfill.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { randomBytes } from '../../node-singletons/crypto.js';
+import fs from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+import { fileURLToPath } from '../../node-singletons/url.js';
+const loadCoreVersion = () => {
+    try {
+        const packageUrl = new URL('../../../package.json', import.meta.url);
+        const packageJson = JSON.parse(fs.readFileSync(packageUrl, 'utf-8'));
+        return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+const createDirectories = (projectPath, directories) => {
+    let count = 0;
+    if (!fs.existsSync(projectPath)) {
+        fs.mkdirSync(projectPath, { recursive: true });
+        count++;
+    }
+    for (const dir of directories) {
+        const fullPath = path.join(projectPath, dir);
+        if (!fs.existsSync(fullPath)) {
+            fs.mkdirSync(fullPath, { recursive: true });
+            count++;
+        }
+    }
+    return count;
+};
+const createFiles = (projectPath, files, variables) => {
+    const renderPathVar = (value) => {
+        if (value === undefined || value === null)
+            return '';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'boolean')
+            return value ? 'true' : 'false';
+        return '';
+    };
+    const renderContentVar = (value) => {
+        if (value === undefined || value === null)
+            return '';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'boolean')
+            return value ? 'true' : 'false';
+        if (typeof value === 'symbol')
+            return value.toString();
+        if (typeof value === 'function')
+            return '[Function]';
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return '';
+        }
+    };
+    let count = 0;
+    for (const [file, content] of Object.entries(files)) {
+        const renderedPath = file.replaceAll(/\{\{\s*(\w+)\s*\}\}/g, (_m, key) => renderPathVar(variables[key]));
+        const fullPath = path.join(projectPath, renderedPath);
+        const rendered = content.replaceAll(/\{\{\s*(\w+)\s*\}\}/g, (_m, key) => renderContentVar(variables[key]));
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, rendered);
+        count++;
+    }
+    return count;
+};
+const createProjectConfigFile = (projectPath, variables) => {
+    try {
+        if (!fs.existsSync(projectPath)) {
+            fs.mkdirSync(projectPath, { recursive: true });
+        }
+        const fullPath = path.join(projectPath, '.zintrust.json');
+        const config = {
+            name: variables['projectName'] ?? variables['name'],
+            database: {
+                connection: variables['database'] ?? 'sqlite',
+            },
+            server: {
+                port: variables['port'] ?? 7777,
+            },
+        };
+        fs.writeFileSync(fullPath, JSON.stringify(config, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const toSafeDbBasename = (raw) => {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return 'zintrust';
+    const lower = trimmed.toLowerCase();
+    let out = '';
+    let prevWasDash = false;
+    for (const char of lower) {
+        const isAlphaNum = (char >= 'a' && char <= 'z') || (char >= '0' && char <= '9');
+        const isContent = isAlphaNum || char === '_';
+        if (isContent) {
+            out += char;
+            prevWasDash = false;
+            continue;
+        }
+        // Treat as separator: collapse dashes and avoid leading dash
+        if (out.length > 0 && !prevWasDash) {
+            out += '-';
+            prevWasDash = true;
+        }
+    }
+    if (out.endsWith('-')) {
+        out = out.slice(0, -1);
+    }
+    return out === '' ? 'zintrust' : out;
+};
+const buildDatabaseEnvLinesWithName = (database, name) => {
+    if (database === 'postgresql' || database === 'postgres') {
+        return [
+            'DB_HOST=localhost',
+            'DB_PORT=5432',
+            'DB_DATABASE=zintrust',
+            'DB_USERNAME=postgres',
+            'DB_PASSWORD=',
+        ];
+    }
+    if (database === 'mysql') {
+        return [
+            'DB_HOST=localhost',
+            'DB_PORT=3306',
+            'DB_DATABASE=zintrust',
+            'DB_USERNAME=root',
+            'DB_PASSWORD=',
+        ];
+    }
+    if (database === 'sqlite') {
+        // Provide both DB_DATABASE (used by the framework) and DB_PATH (common alias)
+        const base = toSafeDbBasename(name);
+        return [`DB_DATABASE=.zintrust/dbs/${base}.sqlite`, `DB_PATH=.zintrust/dbs/${base}.sqlite`];
+    }
+    if (database === 'd1-remote' || database === 'd1-proxy') {
+        return [
+            '# Cloudflare D1 Remote Proxy (HTTPS)',
+            'D1_REMOTE_URL=',
+            'D1_REMOTE_KEY_ID=',
+            'D1_REMOTE_SECRET=',
+            'D1_REMOTE_MODE=registry',
+            'ZT_PROXY_TIMEOUT_MS=15000',
+        ];
+    }
+    return [];
+};
+const createEnvFile = (projectPath, variables) => {
+    try {
+        if (!fs.existsSync(projectPath)) {
+            fs.mkdirSync(projectPath, { recursive: true });
+        }
+        const fullPath = path.join(projectPath, '.env');
+        // If an .env already exists (e.g., from a template), do not overwrite user values.
+        // But we *do* backfill safe defaults for common bootstrap keys when missing/blank.
+        if (fs.existsSync(fullPath)) {
+            EnvFileBackfill.backfillEnvDefaults(fullPath, {
+                HOST: 'localhost',
+                PORT: String(Number(variables['port'] ?? 7777)),
+                LOG_LEVEL: 'debug',
+            });
+            return true;
+        }
+        const name = typeof variables['projectName'] === 'string' ? variables['projectName'] : 'zintrust-app';
+        const port = Number(variables['port'] ?? 7777);
+        const database = typeof variables['database'] === 'string' ? variables['database'] : 'sqlite';
+        // Generate a secure APP_KEY (32 bytes = 256-bit, base64 encoded)
+        const appKeyBytes = randomBytes(32);
+        const appKey = appKeyBytes.toString('base64');
+        const baseLines = [
+            'NODE_ENV=development',
+            'STARTUP_REQUIRE_ENV=true',
+            `APP_NAME=${name}`,
+            'HOST=localhost',
+            `PORT=${port}`,
+            'APP_DEBUG=true',
+            // Auto-generated secure key for storage signing and encryption
+            `APP_KEY=${appKey}`,
+            `DB_CONNECTION=${database}`,
+        ];
+        const dbLines = buildDatabaseEnvLinesWithName(database, name);
+        const placeholderLines = [
+            '',
+            '# Logging',
+            'LOG_LEVEL=debug',
+            'LOG_CHANNEL=file',
+            'LOG_FORMAT=text',
+            '',
+            '# Auth / Security',
+            'JWT_SECRET=',
+            'JWT_EXPIRES_IN=1h',
+            'CSRF_SECRET=',
+            'ENCRYPTION_CIPHER=aes-256-cbc',
+            'APP_PREVIOUS_KEYS=',
+            '',
+            '# Cache / Queue',
+            'CACHE_DRIVER=memory',
+            'CACHE_TTL=300',
+            'QUEUE_DRIVER=sync',
+            '',
+            '# Microservices',
+            'SERVICE_DISCOVERY_ENABLED=false',
+            'SERVICE_DISCOVERY_TYPE=filesystem',
+            'SERVICE_NAME=',
+            'SERVICE_VERSION=1.0.0',
+        ];
+        const lines = [...baseLines, ...dbLines, ...placeholderLines];
+        fs.writeFileSync(fullPath, lines.join('\n') + '\n');
+        return true;
+    }
+    catch {
+        Logger.error('Failed to create .env file');
+        return false;
+    }
+};
+const getProjectTemplatesRoot = () => {
+    // src/cli/scaffolding/ -> src/templates/project/
+    const templatesUrl = new URL('../../templates/project', import.meta.url);
+    return fileURLToPath(templatesUrl);
+};
+const listTemplateFilesRecursive = (dirPath) => {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listTemplateFilesRecursive(full));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(full);
+        }
+    }
+    return files;
+};
+const coerceStringArray = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item === 'string')
+            out.push(item);
+    }
+    return out;
+};
+const readTemplateJson = (templateJsonPath) => {
+    try {
+        return JSON.parse(fs.readFileSync(templateJsonPath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+const resolveTemplateMetadata = (templateName, meta, fallback) => {
+    const name = typeof meta.name === 'string' ? meta.name : (fallback?.name ?? templateName);
+    const description = typeof meta.description === 'string' ? meta.description : (fallback?.description ?? '');
+    const directories = Array.isArray(meta.directories)
+        ? coerceStringArray(meta.directories)
+        : (fallback?.directories ?? []);
+    return { name, description, directories };
+};
+const loadTemplateFiles = (templateDir) => {
+    const files = {};
+    const allFiles = listTemplateFilesRecursive(templateDir);
+    const allowedConfigFiles = new Set([
+        'config/broadcast.ts',
+        'config/cache.ts',
+        'config/database.ts',
+        'config/middleware.ts',
+        'config/logging/HttpLogger.ts',
+        'config/mail.ts',
+        'config/notification.ts',
+        'config/queue.ts',
+        'config/storage.ts',
+    ]);
+    const isENOENT = (error) => error !== null &&
+        typeof error === 'object' &&
+        'code' in error &&
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        error.code === 'ENOENT';
+    const normalizeRelPath = (relPath) => relPath.replaceAll('\\', '/');
+    const getOutputRelPath = (relPath) => relPath.endsWith('.tpl') ? relPath.slice(0, -'.tpl'.length) : relPath;
+    const shouldIncludeTemplateFile = (relPath) => {
+        if (relPath === 'template.json')
+            return false;
+        const normalized = normalizeRelPath(relPath);
+        // Project `.env` is generated by createEnvFile() so it can set defaults and create a secure APP_KEY.
+        // Some templates ship `.env.tpl` (which would become `.env`), but that file is intentionally ignored.
+        const outputRel = normalizeRelPath(getOutputRelPath(relPath));
+        if (outputRel === '.env')
+            return false;
+        if (!normalized.startsWith('config/'))
+            return true;
+        // Starter apps should only ship app-level config modules.
+        // Core/framework config internals (e.g. config/logging/*) remain core-owned.
+        return allowedConfigFiles.has(outputRel);
+    };
+    const readUtf8FileOrUndefined = (absPath) => {
+        try {
+            return fs.readFileSync(absPath, 'utf8');
+        }
+        catch (error) {
+            // Some tests temporarily create/delete template files in parallel; if a file
+            // disappears between directory listing and read, skip it.
+            if (isENOENT(error))
+                return undefined;
+            throw error;
+        }
+    };
+    for (const absPath of allFiles) {
+        const rel = path.relative(templateDir, absPath);
+        if (!shouldIncludeTemplateFile(rel))
+            continue;
+        const content = readUtf8FileOrUndefined(absPath);
+        if (content === undefined)
+            continue;
+        const outputRel = getOutputRelPath(rel);
+        files[outputRel] = content;
+    }
+    return files;
+};
+const loadTemplateFromDisk = (templateName, fallback) => {
+    const root = getProjectTemplatesRoot();
+    const templateDir = path.join(root, templateName);
+    const templateJsonPath = path.join(templateDir, 'template.json');
+    if (!fs.existsSync(templateDir) || !fs.existsSync(templateJsonPath)) {
+        return undefined;
+    }
+    const meta = readTemplateJson(templateJsonPath);
+    const resolved = resolveTemplateMetadata(templateName, meta, fallback);
+    const files = loadTemplateFiles(templateDir);
+    return { ...resolved, files };
+};
+/**
+ * Project Scaffolder Factory
+ */
+const BASIC_TEMPLATE = {
+    name: 'basic',
+    description: 'Basic ZinTrust project structure',
+    directories: [
+        'config',
+        'app/Controllers',
+        'app/Middleware',
+        'app/Models',
+        'database/migrations',
+        'database/seeders',
+        'logs',
+        'storage',
+        'tmp',
+        'public',
+        'routes',
+        'src',
+        'tests/unit',
+        'tests/integration',
+    ],
+    files: {},
+};
+const API_TEMPLATE = {
+    name: 'api',
+    description: 'API-focused ZinTrust project structure',
+    directories: [
+        'app/Controllers',
+        'app/Middleware',
+        'app/Models',
+        'logs',
+        'storage',
+        'tmp',
+        'src',
+        'routes',
+        'tests',
+    ],
+    files: {},
+};
+const MICROSERVICE_TEMPLATE = {
+    name: 'microservice',
+    description: 'Microservice-focused ZinTrust project structure',
+    directories: [
+        'app/Controllers',
+        'app/Middleware',
+        'app/Models',
+        'logs',
+        'storage',
+        'tmp',
+        'routes',
+        'tests',
+        'src/services',
+        'src/microservices',
+    ],
+    files: {},
+};
+const FULLSTACK_TEMPLATE = {
+    name: 'fullstack',
+    description: 'Fullstack ZinTrust project structure',
+    directories: [
+        'app/Controllers',
+        'app/Middleware',
+        'app/Models',
+        // Starter projects should not include framework config internals.
+        'database/migrations',
+        'database/seeders',
+        'logs',
+        'storage',
+        'tmp',
+        'public',
+        'routes',
+        'src',
+        'tests/unit',
+        'tests/integration',
+    ],
+    files: {},
+};
+const TEMPLATE_MAP = new Map([
+    ['basic', BASIC_TEMPLATE],
+    ['api', API_TEMPLATE],
+    ['microservice', MICROSERVICE_TEMPLATE],
+    ['fullstack', FULLSTACK_TEMPLATE],
+]);
+export function getAvailableTemplates() {
+    return [...TEMPLATE_MAP.keys()];
+}
+export function getTemplate(name) {
+    const fallback = TEMPLATE_MAP.get(name);
+    if (!fallback)
+        return undefined;
+    const disk = loadTemplateFromDisk(name, fallback);
+    if (disk)
+        return disk;
+    // If we don't have a dedicated disk template yet (e.g. fullstack/api/microservice),
+    // fall back to the starter project's file set so generated projects are runnable.
+    if (name !== 'basic') {
+        const basicFallback = TEMPLATE_MAP.get('basic');
+        const basicDisk = basicFallback ? loadTemplateFromDisk('basic', basicFallback) : undefined;
+        if (basicDisk) {
+            return {
+                ...fallback,
+                files: basicDisk.files,
+            };
+        }
+    }
+    return fallback;
+}
+export function validateOptions(options) {
+    const errors = [];
+    if (!options.name) {
+        errors.push('Project name is required');
+    }
+    if (options.name && !/^[a-z0-9_-]+$/.test(options.name)) {
+        errors.push('Project name must contain only lowercase letters, numbers, hyphens, and underscores');
+    }
+    if (options.template !== undefined && !getTemplate(options.template)) {
+        errors.push(`Template "${options.template}" not found`);
+    }
+    if (options.port !== undefined && (options.port < 1 || options.port > 65535)) {
+        errors.push('Port must be a number between 1 and 65535');
+    }
+    return { valid: errors.length === 0, errors };
+}
+const resolveTemplate = (templateName) => getTemplate(templateName) ?? getTemplate('basic');
+const prepareContext = (state, options) => {
+    state.templateName = options.template ?? 'basic';
+    state.projectPath = path.join(state.basePath, options.name);
+    const migrationTimestamp = new Date()
+        .toISOString()
+        .replaceAll(/[-:T.Z]/g, '')
+        .slice(0, 14);
+    state.variables = {
+        projectName: options.name,
+        projectSlug: options.name,
+        author: options.author ?? 'Your Name',
+        description: options.description ?? '',
+        port: options.port ?? 7777,
+        database: options.database ?? 'sqlite',
+        template: state.templateName,
+        migrationTimestamp,
+        coreVersion: loadCoreVersion(),
+    };
+};
+const createDirectoriesForState = (state) => {
+    const template = resolveTemplate(state.templateName);
+    return createDirectories(state.projectPath, template?.directories ?? []);
+};
+const createFilesForState = (state) => {
+    const template = resolveTemplate(state.templateName);
+    const variables = state.variables;
+    const templateFiles = template?.files;
+    const files = templateFiles !== undefined && Object.keys(templateFiles).length > 0
+        ? { ...templateFiles }
+        : {};
+    // Backward-compatible defaults for templates that don't ship these files yet.
+    if (!Object.hasOwn(files, '.gitignore')) {
+        files['.gitignore'] = `node_modules/
+dist/
+.env
+.env.*
+.env.local
+.DS_Store
+coverage/
+logs/
+storage/
+tmp/
+.zintrust/
+*.log
+`;
+    }
+    if (!Object.hasOwn(files, 'README.md')) {
+        files['README.md'] = `# {{projectName}}
+
+Starter Task API built with ZinTrust.
+
+## Run
+
+\`\`\`bash
+npm install
+zin s
+\`\`\`
+
+- Health: http://localhost:{{port}}/health
+- Tasks:  http://localhost:{{port}}/api/tasks
+- Doc:  http://localhost:{{port}}/doc
+`;
+    }
+    return createFiles(state.projectPath, files, variables);
+};
+const scaffoldWithState = async (state, options
+// eslint-disable-next-line @typescript-eslint/require-await
+) => {
+    try {
+        const validation = validateOptions(options);
+        if (!validation.valid) {
+            return {
+                success: false,
+                projectPath: path.join(state.basePath, options.name),
+                filesCreated: 0,
+                directoriesCreated: 0,
+                message: validation.errors.join('\n'),
+            };
+        }
+        prepareContext(state, options);
+        if (fs.existsSync(state.projectPath)) {
+            if (options.overwrite === true) {
+                fs.rmSync(state.projectPath, { recursive: true, force: true });
+            }
+            else {
+                return {
+                    success: false,
+                    projectPath: state.projectPath,
+                    filesCreated: 0,
+                    directoriesCreated: 0,
+                    message: `Project directory "${state.projectPath}" already exists`,
+                };
+            }
+        }
+        const directoriesCreated = createDirectoriesForState(state);
+        const filesCreated = createFilesForState(state);
+        createProjectConfigFile(state.projectPath, state.variables);
+        createEnvFile(state.projectPath, state.variables);
+        return {
+            success: true,
+            projectPath: state.projectPath,
+            filesCreated,
+            directoriesCreated,
+            message: `Project "${options.name}" scaffolded successfully.`,
+        };
+    }
+    catch (error) {
+        Logger.error('Project scaffolding failed', error);
+        const err = error instanceof Error ? error : ErrorFactory.createGeneralError(String(error));
+        return {
+            success: false,
+            projectPath: state.projectPath,
+            filesCreated: 0,
+            directoriesCreated: 0,
+            message: err.message,
+            error: err,
+        };
+    }
+};
+/**
+ * Plain-function scaffolder creator (replaces the function-object factory).
+ */
+export function createProjectScaffolder(projectPath = process.cwd()) {
+    const state = {
+        variables: {},
+        basePath: projectPath,
+        projectPath,
+        templateName: 'basic',
+    };
+    return {
+        prepareContext: (options) => prepareContext(state, options),
+        getVariables: () => state.variables,
+        getTemplateInfo: (templateName) => getTemplate(templateName ?? state.templateName),
+        getProjectPath: () => state.projectPath,
+        projectDirectoryExists: () => fs.existsSync(state.projectPath),
+        createDirectories: () => createDirectoriesForState(state),
+        createFiles: (_options) => createFilesForState(state),
+        createConfigFile: () => createProjectConfigFile(state.projectPath, state.variables),
+        createEnvFile: () => createEnvFile(state.projectPath, state.variables),
+        scaffold: async (options) => scaffoldWithState(state, options),
+    };
+}
+export async function scaffoldProject(projectPath, options) {
+    return createProjectScaffolder(projectPath).scaffold(options);
+}
+/**
+ * Sealed namespace for ProjectScaffolder
+ */
+export const ProjectScaffolder = Object.freeze({
+    create: createProjectScaffolder,
+    getAvailableTemplates,
+    getTemplate,
+    validateOptions,
+    scaffold: scaffoldProject,
+});