@maxal_studio/kratosjs-cli 1.0.0

package/dist/commands/init.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const picocolors_1 = __importDefault(require("picocolors"));
+const render_1 = require("../render");
+/**
+ * Scaffold the standard KratosJs admin client entry (index.html, vite config,
+ * src/admin/main.tsx) into an existing app. Idempotent: never overwrites.
+ */
+async function runInit() {
+    const cwd = process.cwd();
+    const result = (0, render_1.renderTemplateTree)((0, render_1.templatePath)('admin-client'), cwd, {});
+    if (result.created.length > 0) {
+        console.log(picocolors_1.default.green('Created admin client files:'));
+        for (const file of result.created) {
+            console.log(`  ${picocolors_1.default.green('+')} ${file}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log(picocolors_1.default.dim('Already present (skipped):'));
+        for (const file of result.skipped) {
+            console.log(`  ${picocolors_1.default.dim('-')} ${file}`);
+        }
+    }
+    if (result.created.length === 0 && result.skipped.length === 0) {
+        console.log(picocolors_1.default.dim('No files to scaffold.'));
+    }
+    console.log('');
+    console.log('Ensure these dev dependencies are installed in your app:');
+    console.log(picocolors_1.default.dim('  @maxal_studio/kratosjs-react react react-dom react-hook-form vite'));
+    console.log('');
+    console.log('Recommended package.json scripts:');
+    console.log(picocolors_1.default.dim('  "dev": "tsx watch src/index.ts"'));
+    console.log(picocolors_1.default.dim('  "build": "npm run build:server && npm run build:admin"'));
+    console.log(picocolors_1.default.dim('  "build:server": "tsc"'));
+    console.log(picocolors_1.default.dim('  "build:admin": "vite build"'));
+    console.log(picocolors_1.default.dim('  "start": "NODE_ENV=production node dist/index.js"'));
+}

package/dist/commands/new.js

@@ -0,0 +1,148 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runNew = runNew;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const prompts_1 = require("@inquirer/prompts");
+const picocolors_1 = __importDefault(require("picocolors"));
+const drivers_1 = require("../drivers");
+const render_1 = require("../render");
+const versions_1 = require("../versions");
+const MIKRO_ORM_CORE = '^7.1.4';
+/** Resolve the monorepo root (only meaningful with --local). */
+function monorepoRoot() {
+    // dist/commands/new.js -> dist -> kratosjs-cli -> packages -> repo root
+    return path_1.default.resolve(__dirname, '..', '..', '..', '..');
+}
+function buildDependencies(driver, local) {
+    return {
+        '@maxal_studio/kratosjs': (0, versions_1.kratosCoreDep)(local),
+        '@mikro-orm/core': MIKRO_ORM_CORE,
+        ...driver.dependencies,
+        dotenv: '^17.4.2',
+        express: '^5.2.1',
+    };
+}
+function buildDevDependencies(local) {
+    return {
+        '@maxal_studio/kratosjs-react': (0, versions_1.kratosReactDep)(local),
+        '@types/node': '^25.9.3',
+        react: '^19.2.7',
+        'react-dom': '^19.2.7',
+        'react-hook-form': '^7.79.0',
+        tsx: '^4.22.4',
+        typescript: '^5.9.3',
+        vite: '^7.3.5',
+    };
+}
+/** JSON.stringify an object and re-indent so it nests under a one-tab key. */
+function jsonBlock(obj) {
+    return JSON.stringify(obj, null, '\t')
+        .split('\n')
+        .map((line, i) => (i === 0 ? line : '\t' + line))
+        .join('\n');
+}
+function resolveDriver(value) {
+    if (!value) {
+        return null;
+    }
+    const key = value.toLowerCase();
+    return drivers_1.DRIVERS[key] ?? null;
+}
+async function runNew(nameArg, options) {
+    const projectName = nameArg ??
+        (await (0, prompts_1.input)({
+            message: 'Project name:',
+            default: 'my-kratosjs-app',
+            validate: value => (value.trim().length > 0 ? true : 'Please enter a project name'),
+        }));
+    const appName = (0, render_1.toKebabCase)(projectName);
+    const targetDir = path_1.default.resolve(process.cwd(), appName);
+    if (fs_1.default.existsSync(targetDir) && fs_1.default.readdirSync(targetDir).length > 0) {
+        console.error(picocolors_1.default.red(`✖ Directory "${appName}" already exists and is not empty.`));
+        process.exit(1);
+    }
+    let driver = resolveDriver(options.driver);
+    if (options.driver && !driver) {
+        console.error(picocolors_1.default.red(`✖ Unknown driver "${options.driver}". Valid drivers: ${drivers_1.DRIVER_KEYS.join('|')}`));
+        process.exit(1);
+    }
+    if (!driver) {
+        const driverKey = await (0, prompts_1.select)({
+            message: 'Which database do you want to use?',
+            choices: drivers_1.DRIVER_KEYS.map(key => ({ name: drivers_1.DRIVERS[key].label, value: key })),
+        });
+        driver = drivers_1.DRIVERS[driverKey];
+    }
+    const local = options.local ?? false;
+    const tokens = {
+        appName,
+        appTitle: `${appName} admin`,
+        driverLabel: driver.label,
+        driverImport: driver.driverImport,
+        migratorImport: driver.migratorImport,
+        ormConfig: driver.ormConfig,
+        idProps: driver.idProps,
+        idInterfaceFields: driver.idInterfaceFields,
+        envVars: driver.envVars,
+        dependencies: jsonBlock(buildDependencies(driver, local)),
+        devDependencies: jsonBlock(buildDevDependencies(local)),
+    };
+    console.log('');
+    console.log(picocolors_1.default.cyan(`Creating a new KratosJs app in ${picocolors_1.default.bold(targetDir)}`));
+    console.log(picocolors_1.default.dim(`  driver: ${driver.label}${local ? '  (local file: links)' : ''}`));
+    console.log('');
+    fs_1.default.mkdirSync(targetDir, { recursive: true });
+    const result = (0, render_1.renderTemplateTree)((0, render_1.templatePath)('app'), targetDir, tokens);
+    for (const file of result.created) {
+        console.log(`  ${picocolors_1.default.green('+')} ${file}`);
+    }
+    const install = options.install ?? true;
+    let built = false;
+    if (install) {
+        console.log('');
+        console.log(picocolors_1.default.cyan('Installing dependencies...'));
+        let installOk = false;
+        try {
+            (0, child_process_1.execSync)('npm install', { cwd: local ? monorepoRoot() : targetDir, stdio: 'inherit' });
+            installOk = true;
+        }
+        catch {
+            console.error(picocolors_1.default.yellow('⚠ npm install failed — you can run it manually later.'));
+        }
+        if (installOk) {
+            console.log('');
+            console.log(picocolors_1.default.cyan('Building app...'));
+            try {
+                (0, child_process_1.execSync)('npm run build', { cwd: targetDir, stdio: 'inherit' });
+                built = true;
+            }
+            catch {
+                console.error(picocolors_1.default.yellow('⚠ npm run build failed — you can run it manually later.'));
+            }
+        }
+    }
+    printNextSteps(appName, install, built);
+}
+function printNextSteps(appName, installed, built) {
+    const steps = [
+        `cd ${appName}`,
+        'cp .env.example .env   ' + picocolors_1.default.dim('# then edit DB settings'),
+        ...(installed ? [] : ['npm install']),
+        ...(built ? [] : ['npm run build']),
+        'npm run dev',
+    ];
+    console.log('');
+    console.log(picocolors_1.default.green('✔ Done! Next steps:'));
+    console.log('');
+    for (const step of steps) {
+        console.log(`  ${picocolors_1.default.bold(step)}`);
+    }
+    console.log('');
+    console.log(picocolors_1.default.dim('Login with admin@example.com / password once the server is running.'));
+    console.log('');
+}

package/dist/commands/plugin.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPlugin = runPlugin;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const prompts_1 = require("@inquirer/prompts");
+const picocolors_1 = __importDefault(require("picocolors"));
+const render_1 = require("../render");
+const versions_1 = require("../versions");
+function buildPackageJson(pluginName, withClient, local) {
+    const pkg = {
+        name: `kratosjs-plugin-${pluginName}`,
+        version: '1.0.0',
+        description: `${pluginName} plugin for KratosJs panels`,
+        main: './dist/server/index.js',
+        types: './dist/server/index.d.ts',
+        sideEffects: false,
+        exports: {
+            '.': {
+                types: './dist/server/index.d.ts',
+                default: './dist/server/index.js',
+            },
+            ...(withClient
+                ? {
+                    './client': {
+                        types: './dist/client/index.d.ts',
+                        default: './dist/client/index.js',
+                    },
+                }
+                : {}),
+            './package.json': './package.json',
+        },
+        files: ['dist'],
+        scripts: {
+            build: withClient
+                ? 'npm run clean && tsc -p tsconfig.server.json && tsc -p tsconfig.client.json'
+                : 'npm run clean && tsc -p tsconfig.server.json',
+            clean: 'rm -rf dist',
+        },
+        keywords: ['kratosjs', 'kratosjs-plugin'],
+        license: 'ISC',
+        peerDependencies: withClient
+            ? {
+                '@maxal_studio/kratosjs': (0, versions_1.kratosCoreDep)(local),
+                '@maxal_studio/kratosjs-react': (0, versions_1.kratosReactDep)(local),
+                react: '^19.0.0',
+                'react-hook-form': '^7.0.0',
+            }
+            : {
+                '@maxal_studio/kratosjs': (0, versions_1.kratosCoreDep)(local),
+            },
+        devDependencies: withClient
+            ? {
+                '@types/react': '^19.2.5',
+                typescript: '^5.9.3',
+            }
+            : {
+                typescript: '^5.9.3',
+            },
+    };
+    return JSON.stringify(pkg, null, '\t') + '\n';
+}
+async function runPlugin(nameArg, options) {
+    const rawName = nameArg ??
+        (await (0, prompts_1.input)({
+            message: 'Plugin name:',
+            default: 'my-plugin',
+            validate: value => (value.trim().length > 0 ? true : 'Please enter a plugin name'),
+        }));
+    const pluginName = (0, render_1.toKebabCase)(rawName);
+    const PluginName = (0, render_1.toPascalCase)(rawName);
+    const pluginCamel = (0, render_1.toCamelCase)(rawName);
+    const withClient = options.client ?? false;
+    const targetDir = path_1.default.resolve(process.cwd(), `kratosjs-plugin-${pluginName}`);
+    if (fs_1.default.existsSync(targetDir) && fs_1.default.readdirSync(targetDir).length > 0) {
+        console.error(picocolors_1.default.red(`✖ Directory "${path_1.default.basename(targetDir)}" already exists and is not empty.`));
+        process.exit(1);
+    }
+    const tokens = {
+        pluginName,
+        PluginName,
+        pluginCamel,
+        registerBody: withClient
+            ? `panel.registerCustomField('${pluginName}');`
+            : `// e.g. panel.registerCustomField('${pluginName}');`,
+    };
+    console.log('');
+    console.log(picocolors_1.default.cyan(`Creating a new KratosJs plugin in ${picocolors_1.default.bold(targetDir)}`));
+    console.log(picocolors_1.default.dim(`  ${withClient ? 'server + client' : 'server-only'}`));
+    console.log('');
+    fs_1.default.mkdirSync(targetDir, { recursive: true });
+    const result = (0, render_1.renderTemplateTree)((0, render_1.templatePath)('plugin'), targetDir, tokens);
+    if (withClient) {
+        (0, render_1.renderTemplateTree)((0, render_1.templatePath)('plugin-client'), targetDir, tokens, result);
+    }
+    fs_1.default.writeFileSync(path_1.default.join(targetDir, 'package.json'), buildPackageJson(pluginName, withClient, false), 'utf-8');
+    result.created.unshift('package.json');
+    for (const file of result.created) {
+        console.log(`  ${picocolors_1.default.green('+')} ${file}`);
+    }
+    console.log('');
+    console.log(picocolors_1.default.green('✔ Plugin scaffolded. Next steps:'));
+    console.log('');
+    console.log(`  ${picocolors_1.default.bold(`cd ${path_1.default.basename(targetDir)}`)}`);
+    console.log(`  ${picocolors_1.default.bold('npm install')}`);
+    console.log(`  ${picocolors_1.default.bold('npm run build')}`);
+    console.log('');
+}

package/dist/drivers.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRIVER_KEYS = exports.DRIVERS = void 0;
+const MIKRO_ORM_VERSION = '^7.1.4';
+exports.DRIVERS = {
+    mysql: {
+        key: 'mysql',
+        label: 'MySQL',
+        kind: 'sql',
+        dependencies: {
+            '@mikro-orm/mysql': MIKRO_ORM_VERSION,
+            '@mikro-orm/migrations': MIKRO_ORM_VERSION,
+        },
+        driverImport: "import { MySqlDriver } from '@mikro-orm/mysql';",
+        migratorImport: "import { Migrator } from '@mikro-orm/migrations';",
+        ormConfig: `{
+			driver: MySqlDriver,
+			host: process.env.DATABASE_HOST || 'localhost',
+			port: parseInt(process.env.DATABASE_PORT || '3306'),
+			user: process.env.DATABASE_USER || 'root',
+			password: process.env.DATABASE_PASSWORD || '',
+			dbName: process.env.DATABASE_NAME || 'kratosjs',
+			extensions: [Migrator],
+		}`,
+        idProps: `id: { type: 'number', primary: true, autoincrement: true },`,
+        idInterfaceFields: `id: number;`,
+        envVars: `DATABASE_HOST="localhost"
+DATABASE_PORT="3306"
+DATABASE_USER="root"
+DATABASE_PASSWORD=""
+DATABASE_NAME="kratosjs"`,
+    },
+    postgresql: {
+        key: 'postgresql',
+        label: 'PostgreSQL',
+        kind: 'sql',
+        dependencies: {
+            '@mikro-orm/postgresql': MIKRO_ORM_VERSION,
+            '@mikro-orm/migrations': MIKRO_ORM_VERSION,
+        },
+        driverImport: "import { PostgreSqlDriver } from '@mikro-orm/postgresql';",
+        migratorImport: "import { Migrator } from '@mikro-orm/migrations';",
+        ormConfig: `{
+			driver: PostgreSqlDriver,
+			host: process.env.DATABASE_HOST || 'localhost',
+			port: parseInt(process.env.DATABASE_PORT || '5432'),
+			user: process.env.DATABASE_USER || 'postgres',
+			password: process.env.DATABASE_PASSWORD || '',
+			dbName: process.env.DATABASE_NAME || 'kratosjs',
+			extensions: [Migrator],
+		}`,
+        idProps: `id: { type: 'number', primary: true, autoincrement: true },`,
+        idInterfaceFields: `id: number;`,
+        envVars: `DATABASE_HOST="localhost"
+DATABASE_PORT="5432"
+DATABASE_USER="postgres"
+DATABASE_PASSWORD=""
+DATABASE_NAME="kratosjs"`,
+    },
+    mariadb: {
+        key: 'mariadb',
+        label: 'MariaDB',
+        kind: 'sql',
+        dependencies: {
+            '@mikro-orm/mariadb': MIKRO_ORM_VERSION,
+            '@mikro-orm/migrations': MIKRO_ORM_VERSION,
+        },
+        driverImport: "import { MariaDbDriver } from '@mikro-orm/mariadb';",
+        migratorImport: "import { Migrator } from '@mikro-orm/migrations';",
+        ormConfig: `{
+			driver: MariaDbDriver,
+			host: process.env.DATABASE_HOST || 'localhost',
+			port: parseInt(process.env.DATABASE_PORT || '3306'),
+			user: process.env.DATABASE_USER || 'root',
+			password: process.env.DATABASE_PASSWORD || '',
+			dbName: process.env.DATABASE_NAME || 'kratosjs',
+			extensions: [Migrator],
+		}`,
+        idProps: `id: { type: 'number', primary: true, autoincrement: true },`,
+        idInterfaceFields: `id: number;`,
+        envVars: `DATABASE_HOST="localhost"
+DATABASE_PORT="3306"
+DATABASE_USER="root"
+DATABASE_PASSWORD=""
+DATABASE_NAME="kratosjs"`,
+    },
+    sqlite: {
+        key: 'sqlite',
+        label: 'SQLite',
+        kind: 'sql',
+        dependencies: {
+            '@mikro-orm/sqlite': MIKRO_ORM_VERSION,
+            '@mikro-orm/migrations': MIKRO_ORM_VERSION,
+        },
+        driverImport: "import { SqliteDriver } from '@mikro-orm/sqlite';",
+        migratorImport: "import { Migrator } from '@mikro-orm/migrations';",
+        ormConfig: `{
+			driver: SqliteDriver,
+			dbName: process.env.DATABASE_NAME || 'kratosjs.sqlite',
+			extensions: [Migrator],
+		}`,
+        idProps: `id: { type: 'number', primary: true, autoincrement: true },`,
+        idInterfaceFields: `id: number;`,
+        envVars: `DATABASE_NAME="kratosjs.sqlite"`,
+    },
+    mongo: {
+        key: 'mongo',
+        label: 'MongoDB',
+        kind: 'mongo',
+        dependencies: {
+            '@mikro-orm/mongodb': MIKRO_ORM_VERSION,
+            '@mikro-orm/migrations-mongodb': MIKRO_ORM_VERSION,
+        },
+        driverImport: "import { MongoDriver } from '@mikro-orm/mongodb';",
+        migratorImport: "import { Migrator } from '@mikro-orm/migrations-mongodb';",
+        ormConfig: `{
+			driver: MongoDriver,
+			clientUrl: process.env.DATABASE_URL || 'mongodb://localhost:27017',
+			dbName: process.env.DATABASE_NAME || 'kratosjs',
+			extensions: [Migrator],
+		}`,
+        idProps: `_id: { type: 'ObjectId', primary: true },
+		id: { type: 'string', serializedPrimaryKey: true },`,
+        idInterfaceFields: `_id: any;
+	id: string;`,
+        envVars: `DATABASE_URL="mongodb://localhost:27017"
+DATABASE_NAME="kratosjs"`,
+    },
+};
+exports.DRIVER_KEYS = Object.keys(exports.DRIVERS);

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const picocolors_1 = __importDefault(require("picocolors"));
+const new_1 = require("./commands/new");
+const plugin_1 = require("./commands/plugin");
+const init_1 = require("./commands/init");
+const drivers_1 = require("./drivers");
+const program = new commander_1.Command();
+program.name('kratosjs').description('Scaffold KratosJs apps and plugins').version(require('../package.json').version);
+program
+    .command('new')
+    .argument('[name]', 'project name')
+    .description('Create a new KratosJs app')
+    .option('--driver <driver>', `database driver (${drivers_1.DRIVER_KEYS.join('|')})`)
+    .option('--no-install', 'skip installing dependencies')
+    .option('--local', 'use file: links to the monorepo packages (for local testing)')
+    .action(async (name, options) => {
+    await (0, new_1.runNew)(name, options);
+});
+program
+    .command('plugin')
+    .argument('[name]', 'plugin name')
+    .description('Scaffold a standalone KratosJs plugin package')
+    .option('--client', 'include a React client entry (custom UI components)')
+    .action(async (name, options) => {
+    await (0, plugin_1.runPlugin)(name, options);
+});
+program
+    .command('init')
+    .description('Scaffold the admin client entry into an existing app')
+    .action(async () => {
+    await (0, init_1.runInit)();
+});
+program.parseAsync(process.argv).catch((error) => {
+    if (error instanceof Error && error.name === 'ExitPromptError') {
+        console.log(picocolors_1.default.dim('\nAborted.'));
+        process.exit(130);
+    }
+    console.error(picocolors_1.default.red(error instanceof Error ? error.message : String(error)));
+    process.exit(1);
+});

package/dist/render.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPascalCase = toPascalCase;
+exports.toKebabCase = toKebabCase;
+exports.toCamelCase = toCamelCase;
+exports.replaceTokens = replaceTokens;
+exports.renderTemplateTree = renderTemplateTree;
+exports.templatePath = templatePath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** Convert an arbitrary string into PascalCase, e.g. "star rating" -> "StarRating". */
+function toPascalCase(input) {
+    return input
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+/** Convert an arbitrary string into kebab-case, e.g. "StarRating" -> "star-rating". */
+function toKebabCase(input) {
+    return input
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
+/** Convert an arbitrary string into camelCase, e.g. "Star Rating" -> "starRating". */
+function toCamelCase(input) {
+    const pascal = toPascalCase(input);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/** Replace every {{token}} occurrence in a string using the provided map. */
+function replaceTokens(content, tokens) {
+    return content.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (match, key) => {
+        return key in tokens ? tokens[key] : match;
+    });
+}
+/**
+ * Recursively render a template directory into the target directory.
+ *
+ * - `.tmpl` files have their tokens replaced and the `.tmpl` suffix stripped.
+ * - Other files are copied verbatim.
+ * - Existing files are skipped (idempotent, never overwrites).
+ * - File/directory names also get token replacement (so `{{name}}.ts` works).
+ */
+function renderTemplateTree(templateDir, targetDir, tokens, result = { created: [], skipped: [] }) {
+    const entries = fs_1.default.readdirSync(templateDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path_1.default.join(templateDir, entry.name);
+        const renderedName = replaceTokens(entry.name.replace(/\.tmpl$/, ''), tokens);
+        const targetPath = path_1.default.join(targetDir, renderedName);
+        if (entry.isDirectory()) {
+            fs_1.default.mkdirSync(targetPath, { recursive: true });
+            renderTemplateTree(sourcePath, targetPath, tokens, result);
+            continue;
+        }
+        const relative = path_1.default.relative(targetDir, targetPath);
+        if (fs_1.default.existsSync(targetPath)) {
+            result.skipped.push(relative);
+            continue;
+        }
+        const isTemplate = entry.name.endsWith('.tmpl');
+        fs_1.default.mkdirSync(path_1.default.dirname(targetPath), { recursive: true });
+        if (isTemplate) {
+            const raw = fs_1.default.readFileSync(sourcePath, 'utf-8');
+            fs_1.default.writeFileSync(targetPath, replaceTokens(raw, tokens), 'utf-8');
+        }
+        else {
+            fs_1.default.copyFileSync(sourcePath, targetPath);
+        }
+        result.created.push(relative);
+    }
+    return result;
+}
+/** Resolve a path inside the shipped templates directory. */
+function templatePath(...segments) {
+    return path_1.default.join(__dirname, '..', 'templates', ...segments);
+}

package/dist/versions.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kratosCoreDep = kratosCoreDep;
+exports.kratosReactDep = kratosReactDep;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function readVersionFromPackageJson(pkgJsonPath) {
+    if (!fs_1.default.existsSync(pkgJsonPath)) {
+        return null;
+    }
+    try {
+        const pkg = JSON.parse(fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function monorepoRoot() {
+    // dist/versions.js -> dist -> kratosjs-cli -> packages -> repo root
+    return path_1.default.resolve(__dirname, '..', '..', '..', '..');
+}
+function readMonorepoVersion(relativePath) {
+    const pkgPath = relativePath === '.'
+        ? path_1.default.join(monorepoRoot(), 'package.json')
+        : path_1.default.join(monorepoRoot(), relativePath, 'package.json');
+    return readVersionFromPackageJson(pkgPath);
+}
+function readInstalledVersion(packageName) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const pkgPath = require.resolve(`${packageName}/package.json`);
+        return readVersionFromPackageJson(pkgPath);
+    }
+    catch {
+        return null;
+    }
+}
+function readPublishedVersion(packageName) {
+    try {
+        return (0, child_process_1.execSync)(`npm view ${packageName} version`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function toVersionRange(version) {
+    return version ? `^${version}` : 'latest';
+}
+/** Resolve a semver range for @maxal_studio/kratosjs. */
+function kratosCoreDep(local) {
+    if (local) {
+        return 'file:..';
+    }
+    return toVersionRange(readInstalledVersion('@maxal_studio/kratosjs') ??
+        readMonorepoVersion('.') ??
+        readPublishedVersion('@maxal_studio/kratosjs'));
+}
+/** Resolve a semver range for @maxal_studio/kratosjs-react. */
+function kratosReactDep(local) {
+    if (local) {
+        return 'file:../packages/kratosjs-react';
+    }
+    return toVersionRange(readInstalledVersion('@maxal_studio/kratosjs-react') ??
+        readMonorepoVersion('packages/kratosjs-react') ??
+        readPublishedVersion('@maxal_studio/kratosjs-react'));
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@maxal_studio/kratosjs-cli",
+	"version": "1.0.0",
+	"description": "Command-line interface for scaffolding KratosJs apps and plugins",
+	"bin": {
+		"kratosjs": "dist/index.js"
+	},
+	"files": [
+		"dist",
+		"templates"
+	],
+	"scripts": {
+		"build": "npm run clean && tsc -p tsconfig.json && chmod +x dist/index.js",
+		"clean": "rm -rf dist",
+		"lint": "eslint ./src"
+	},
+	"keywords": [
+		"kratosjs",
+		"cli",
+		"scaffold",
+		"generator"
+	],
+	"author": "MaxAl",
+	"license": "ISC",
+	"repository": {
+		"type": "git",
+		"url": "git+ssh://git@github.com/maxal-studio/kratosjs.git"
+	},
+	"dependencies": {
+		"@inquirer/prompts": "^8.5.2",
+		"commander": "^15.0.0",
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"@types/node": "^25.9.3",
+		"typescript": "^5.9.3"
+	}
+}

package/templates/admin-client/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<!-- VALAJS_PANEL_FAVICON -->
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<!-- VALAJS_PANEL_TITLE -->
+		<!-- VALAJS_PANEL_SETTINGS -->
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/admin/main.tsx"></script>
+	</body>
+</html>

package/templates/admin-client/src/admin/main.tsx

@@ -0,0 +1,9 @@
+import { mountAdminPanel } from '@maxal_studio/kratosjs-react';
+import '@maxal_studio/kratosjs-react/styles.css';
+
+// Import plugin client manifests here, e.g.:
+// import starRating from '@maxal_studio/kratosjs-plugin-star-rating/client';
+
+mountAdminPanel({
+	plugins: [],
+});

package/templates/admin-client/vite.config.mts

@@ -0,0 +1,4 @@
+import { defineConfig } from 'vite';
+import { kratosAdminVite } from '@maxal_studio/kratosjs/vite';
+
+export default defineConfig(kratosAdminVite());

package/templates/app/.env.example.tmpl

@@ -0,0 +1,11 @@
+PORT="3000"
+
+# ------------------------------------------------------------
+# Database configuration ({{driverLabel}})
+# ------------------------------------------------------------
+{{envVars}}
+
+# ------------------------------------------------------------
+# Auth
+# ------------------------------------------------------------
+JWT_SECRET="your-secret-key-change-in-production"

package/templates/app/README.md.tmpl

@@ -0,0 +1,61 @@
+# {{appName}}
+
+A [KratosJs](https://github.com/maxal-studio/kratosjs) admin panel using **{{driverLabel}}**.
+
+## Getting started
+
+1. Copy the environment file and adjust the database settings:
+
+```bash
+cp .env.example .env
+```
+
+2. Install dependencies (if you skipped `--install`):
+
+```bash
+npm install
+```
+
+3. Start the dev server (API + admin client with HMR):
+
+```bash
+npm run dev
+```
+
+The admin panel will be available at `http://localhost:3000`.
+
+Default login (seeded automatically on first boot):
+
+- **Email:** `admin@example.com`
+- **Password:** `password`
+
+## Project structure
+
+```
+src/
+  index.ts              # Panel definition, ORM config, auth, server bootstrap
+  entities/User.ts       # MikroORM entity (driver-agnostic schema)
+  resources/UserResource.ts  # Admin resource (form + table) for users
+  seedAdminUser.ts       # Seeds the demo admin user on first boot
+  admin/main.tsx         # Admin client entry — register plugin client manifests here
+  migrations/            # Generated migrations (mikro-orm migration:create)
+index.html              # Admin client HTML shell
+vite.config.mts         # Admin client Vite config (kratosAdminVite)
+```
+
+The database schema is created automatically on first boot via `updateSchema: true`.
+When you are ready for versioned migrations, generate them with
+`npx mikro-orm migration:create` and register them on the panel.
+
+## Building for production
+
+```bash
+npm run build   # compiles the server (tsc) and the admin client (vite build)
+npm start       # runs the compiled server with NODE_ENV=production
+```
+
+## Adding a plugin
+
+Install a KratosJs plugin package, register its server class in `src/index.ts`
+via `.plugins([...])`, and (if it ships UI) import its client manifest in
+`src/admin/main.tsx`. See the docs for details.

package/templates/app/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<!-- VALAJS_PANEL_FAVICON -->
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<!-- VALAJS_PANEL_TITLE -->
+		<!-- VALAJS_PANEL_SETTINGS -->
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/admin/main.tsx"></script>
+	</body>
+</html>

package/templates/app/package.json.tmpl

@@ -0,0 +1,15 @@
+{
+	"name": "{{appName}}",
+	"version": "1.0.0",
+	"private": true,
+	"description": "A KratosJs admin panel ({{driverLabel}})",
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "npm run build:server && npm run build:admin",
+		"build:server": "tsc",
+		"build:admin": "vite build",
+		"start": "NODE_ENV=production node dist/index.js"
+	},
+	"dependencies": {{dependencies}},
+	"devDependencies": {{devDependencies}}
+}

package/templates/app/src/admin/main.tsx

@@ -0,0 +1,11 @@
+import { mountAdminPanel } from '@maxal_studio/kratosjs-react';
+import '@maxal_studio/kratosjs-react/styles.css';
+
+// Import plugin client manifests here, e.g.:
+// import starRating from '@maxal_studio/kratosjs-plugin-star-rating/client';
+
+// Languages are configured once on the backend (src/index.ts) and injected into
+// the page, so no i18n config is needed here.
+mountAdminPanel({
+	plugins: [],
+});

package/templates/app/src/entities/User.ts.tmpl

@@ -0,0 +1,31 @@
+import { EntitySchema } from '@mikro-orm/core';
+
+export interface IUser {
+	{{idInterfaceFields}}
+	firstname: string;
+	lastname?: string;
+	email: string;
+	password?: string;
+	phone?: string;
+	profileMediaImage?: { key: string; bucket: string; url?: string } | null;
+	active: boolean;
+	createdAt: Date;
+}
+
+/**
+ * User entity ({{driverLabel}})
+ */
+export const User = new EntitySchema<IUser>({
+	name: 'User',
+	properties: {
+		{{idProps}}
+		firstname: { type: 'string' },
+		lastname: { type: 'string', nullable: true },
+		email: { type: 'string', unique: true },
+		password: { type: 'string', hidden: true },
+		phone: { type: 'string', nullable: true },
+		profileMediaImage: { type: 'json', nullable: true },
+		active: { type: 'boolean', default: true },
+		createdAt: { type: 'Date', onCreate: () => new Date() },
+	} as any,
+});

package/templates/app/src/hooks/userHooks.ts

@@ -0,0 +1,51 @@
+import { hashPassword, type ResourceHooks, type HookContext } from '@maxal_studio/kratosjs';
+
+const capitalize = (str: string | undefined): string => {
+	if (!str || typeof str !== 'string') return str || '';
+	return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+};
+
+export const userHooks: ResourceHooks = {
+	beforeCreate: [
+		async (ctx: HookContext) => {
+			const data = ctx.input.data?.[0];
+			if (!data) return;
+
+			if (data.firstname) {
+				data.firstname = capitalize(data.firstname);
+			}
+			if (data.lastname) {
+				data.lastname = capitalize(data.lastname);
+			}
+		},
+	],
+	beforeUpdate: [
+		async (ctx: HookContext) => {
+			const data = ctx.input.data?.[0];
+			if (!data) return;
+
+			if (data.firstname) {
+				data.firstname = capitalize(data.firstname);
+			}
+			if (data.lastname) {
+				data.lastname = capitalize(data.lastname);
+			}
+		},
+	],
+	// Hash the password AFTER validation, so length rules (e.g. min/max) check the
+	// raw password the user typed — not the 60-char bcrypt hash. This handler runs
+	// for both create and update. On update, an empty password is dropped so it
+	// doesn't overwrite the stored hash.
+	afterValidate: [
+		async (ctx: HookContext) => {
+			const data = ctx.input.data?.[0];
+			if (!data) return;
+
+			if (data.password) {
+				data.password = await hashPassword(data.password);
+			} else {
+				delete data.password;
+			}
+		},
+	],
+};

package/templates/app/src/index.ts.tmpl

@@ -0,0 +1,71 @@
+import 'dotenv/config';
+import path from 'path';
+import { Panel, LocalMediaAdapter, EmailAuthProvider } from '@maxal_studio/kratosjs';
+{{driverImport}}
+{{migratorImport}}
+import { UserResource } from './resources/UserResource';
+import { User } from './entities/User';
+import { seedAdminUser } from './seedAdminUser';
+
+const PORT = parseInt(process.env.PORT || '3000');
+const uploadsPath = path.join(process.cwd(), 'uploads');
+const assetsPath = path.join(process.cwd(), 'assets');
+
+const adminPanel = Panel.make('admin')
+	.title('{{appTitle}}')
+	.favicon('/assets/icon.png')
+	.icon('/assets/icon.png')
+	.orm(
+		{{ormConfig}},
+		{ migrate: true, updateSchema: true },
+	)
+	.mediaAdapters([
+		new LocalMediaAdapter({
+			name: 'local-uploads',
+			uploadPath: uploadsPath,
+			publicUrl: `http://localhost:${PORT}/uploads`,
+			createDirectories: true,
+			isDefault: true,
+		}),
+	])
+	.resources([UserResource])
+	.plugins([]);
+
+// Multilingual support (optional). This is the single source of truth for
+// languages — the admin client auto-configures itself from what you register here.
+//
+// adminPanel
+// 	.i18n({ locales: ['en', 'sq'], defaultLocale: 'en', fallbackLocale: 'en' })
+// 	.registerTranslations('app', {
+// 		en: { 'users.label': 'Users' },
+// 		sq: { 'users.label': 'Përdoruesit' },
+// 	});
+
+// Email/password login. With `userEntity` set, `validateCredentials` and `getUserById`
+// are provided by default (look up the user, verify the password, resolve the avatar).
+// To customize, pass your own `validateCredentials` to EmailAuthProvider, add more
+// providers, or pass a `getUserById` here. Map non-standard field names with `userFields`.
+adminPanel.auth({
+	jwt: {
+		secret: process.env.JWT_SECRET || 'your-secret-key-change-in-production',
+		accessTokenExpiry: '15m',
+		refreshTokenExpiry: '7d',
+	},
+	userEntity: User,
+	providers: [new EmailAuthProvider()],
+});
+
+// Serve static assets (including panel icon)
+adminPanel.useStatic('/assets', assetsPath);
+
+adminPanel
+	.start(PORT, async () => {
+		await seedAdminUser(adminPanel);
+		console.log(`🚀 {{appTitle}} running on http://localhost:${PORT}`);
+		console.log(`📊 Admin Panel API: ${adminPanel.getBasePath()}`);
+		console.log('🔐 Login: admin@example.com / password');
+	})
+	.catch((error: unknown) => {
+		console.error('Failed to start panel:', error);
+		process.exit(1);
+	});

package/templates/app/src/resources/UserResource.ts

@@ -0,0 +1,79 @@
+import {
+	BaseResource,
+	FormBuilder,
+	TextInput,
+	Toggle,
+	FileUpload,
+	TableBuilder,
+	TextColumn,
+	ToggleColumn,
+	ImageColumn,
+	StatsWidget,
+	Widget,
+	type FormContext,
+} from '@maxal_studio/kratosjs';
+import { User } from '../entities/User';
+import { userHooks } from '../hooks/userHooks';
+
+export class UserResource extends BaseResource {
+	static slug = 'users';
+
+	static entity = User;
+
+	static label = 'User';
+	static pluralLabel = 'Users';
+	static icon = 'Users';
+	static navigationGroup = 'App';
+	static navigationSort = 1;
+
+	static recordTitleAttribute = (record: any) =>
+		record.lastname ? `${record.firstname} ${record.lastname}` : record.firstname;
+	static recordFeaturedImageAttribute = 'profileMediaImage';
+	static globallySearchableAttributes = ['firstname', 'lastname', 'email'];
+
+	static form() {
+		return FormBuilder.make().schema([
+			FileUpload.make('profileMediaImage').label('Profile Image').image(),
+			TextInput.make('password')
+				.label('Password')
+				.password()
+				.required((context: FormContext) => context?.operation === 'create')
+				.min(8)
+				.max(50)
+				.hidden((context: FormContext) => context?.operation === 'view'),
+			TextInput.make('firstname').label('First name').required().min(2).max(50),
+			TextInput.make('lastname').label('Last name').max(50),
+			TextInput.make('email').label('Email').email().required(),
+			TextInput.make('phone').label('Phone Number').placeholder('Enter phone number...'),
+			Toggle.make('active').label('Active').default(true),
+		]);
+	}
+
+	static table() {
+		return TableBuilder.make()
+			.columns([
+				ImageColumn.make('profileMediaImage').label('Profile').circular(),
+				TextColumn.make('firstname').label('First name').sortable().searchable(),
+				TextColumn.make('lastname').label('Last name').sortable().searchable(),
+				TextColumn.make('email').label('Email').sortable().searchable(),
+				ToggleColumn.make('active').label('Active').sortable(),
+				TextColumn.make('createdAt').label('Created').sortable().dateTime(),
+			])
+			.searchable()
+			.paginate(10)
+			.defaultSort('createdAt', 'desc');
+	}
+
+	static hooks() {
+		return userHooks;
+	}
+
+	static widgets(): Widget[] {
+		return [
+			StatsWidget.make('totalUsers')
+				.label('Total Users')
+				.icon('Users')
+				.render(async (em, entity) => em.count(entity, {})),
+		];
+	}
+}

package/templates/app/src/seedAdminUser.ts

@@ -0,0 +1,30 @@
+import { hashPassword, type Panel } from '@maxal_studio/kratosjs';
+import { User } from './entities/User';
+
+const DEFAULT_ADMIN_EMAIL = 'admin@example.com';
+const DEFAULT_ADMIN_PASSWORD = 'password';
+
+/**
+ * Ensure a default admin user exists for local development login.
+ */
+export async function seedAdminUser(panel: Panel): Promise<void> {
+	const em = panel.getOrm().em.fork();
+	const existing = await em.findOne(User, { email: DEFAULT_ADMIN_EMAIL });
+
+	if (existing) {
+		return;
+	}
+
+	const hashedPassword = await hashPassword(DEFAULT_ADMIN_PASSWORD);
+	const user = em.create(User, {
+		firstname: 'Admin',
+		email: DEFAULT_ADMIN_EMAIL,
+		password: hashedPassword,
+		active: true,
+		createdAt: new Date(),
+	});
+
+	em.persist(user);
+	await em.flush();
+	console.log(`👤 Seeded admin user (${DEFAULT_ADMIN_EMAIL} / ${DEFAULT_ADMIN_PASSWORD})`);
+}

package/templates/app/tsconfig.json

@@ -0,0 +1,21 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "commonjs",
+		"lib": ["ES2020"],
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"declaration": false,
+		"sourceMap": true,
+		"removeComments": true,
+		"moduleResolution": "node",
+		"allowSyntheticDefaultImports": true
+	},
+	"include": ["src"],
+	"exclude": ["node_modules", "dist", "**/*.tsx"]
+}

package/templates/app/vite.config.mts

@@ -0,0 +1,4 @@
+import { defineConfig } from 'vite';
+import { kratosAdminVite } from '@maxal_studio/kratosjs/vite';
+
+export default defineConfig(kratosAdminVite());

package/templates/plugin/src/index.ts.tmpl

@@ -0,0 +1,2 @@
+// Server entry: plugin class (+ any builder classes used in resources)
+export { {{PluginName}}Plugin } from './{{PluginName}}Plugin';

package/templates/plugin/src/{{PluginName}}Plugin.ts.tmpl

@@ -0,0 +1,25 @@
+import { Plugin, Panel } from '@maxal_studio/kratosjs';
+
+/**
+ * {{PluginName}} Plugin
+ *
+ * Implement `register` to extend a panel: register custom component names,
+ * add routes, register migrations, or wire up resources.
+ */
+export class {{PluginName}}Plugin extends Plugin {
+	getName(): string {
+		return '{{pluginName}}';
+	}
+
+	register(panel: Panel): void {
+		{{registerBody}}
+
+		// Register the plugin's translations (labels + any frontend UI strings) once,
+		// here on the backend, under the plugin namespace. They are injected into the
+		// admin page, so the client uses `t('{{pluginName}}:...')` with no extra setup.
+		// panel.registerTranslations('{{pluginName}}', {
+		// 	en: { 'hint': 'Tap to rate' },
+		// 	sq: { 'hint': 'Prekni për të vlerësuar' },
+		// });
+	}
+}

package/templates/plugin/tsconfig.server.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "CommonJS",
+		"moduleResolution": "node",
+		"declaration": true,
+		"outDir": "./dist/server",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"isolatedModules": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "src/client/**/*"]
+}

package/templates/plugin-client/src/client/index.ts.tmpl

@@ -0,0 +1,17 @@
+import { definePluginClient } from '@maxal_studio/kratosjs-react';
+import {{PluginName}}Field from './{{PluginName}}Field';
+
+/**
+ * Client manifest. Import this from your app's `src/admin/main.tsx`:
+ *
+ * import {{pluginCamel}} from 'kratosjs-plugin-{{pluginName}}/client';
+ * mountAdminPanel({ plugins: [{{pluginCamel}}] });
+ *
+ * Translations are NOT declared here — register them on the backend in the
+ * plugin's `register()` via `panel.registerTranslations('{{pluginName}}', {...})`.
+ * The server injects them into the page and the client picks them up automatically.
+ */
+export default definePluginClient({
+	name: '{{pluginName}}',
+	fields: { '{{pluginName}}': {{PluginName}}Field },
+});

package/templates/plugin-client/src/client/{{PluginName}}Field.tsx.tmpl

@@ -0,0 +1,28 @@
+// @ts-nocheck
+import { FieldProps, ViewFieldWrapper } from '@maxal_studio/kratosjs-react';
+import { useFormContext } from 'react-hook-form';
+
+/**
+ * Sample custom field component for the {{PluginName}} plugin.
+ * Replace the body with your own UI.
+ */
+export default function {{PluginName}}Field(props: FieldProps) {
+	if (props.mode === 'view') {
+		return (
+			<ViewFieldWrapper label={props.label}>
+				<span>{props.value ?? '—'}</span>
+			</ViewFieldWrapper>
+		);
+	}
+
+	const { register } = useFormContext();
+
+	return (
+		<div className="mb-4">
+			{props.label && (
+				<label className="block text-sm font-medium kratosjstext-primary mb-2">{props.label}</label>
+			)}
+			<input type="text" className="w-full rounded border px-3 py-2" {...register(props.name)} />
+		</div>
+	);
+}

package/templates/plugin-client/tsconfig.client.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ES2020", "DOM", "DOM.Iterable"],
+		"jsx": "react-jsx",
+		"declaration": true,
+		"outDir": "./dist/client",
+		"rootDir": "./src/client",
+		"strict": false,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"isolatedModules": true
+	},
+	"include": ["src/client/**/*"],
+	"exclude": ["node_modules", "dist"]
+}