adminforth 1.5.9-next.12 → 1.5.9-next.14

package/commands/cli.js

@@ -3,10 +3,14 @@
 const args = process.argv.slice(2);
 const command = args[0];
 
-import generateModels from "./generateModels.js";
 import bundle from "./bundle.js";
+import createApp from "./createApp/main.js";
+import generateModels from "./generateModels.js";
 
 switch (command) {
+  case "create-app":
+    createApp(args);
+    break;
   case "generate-models":
     generateModels();
     break;
@@ -14,5 +18,5 @@ switch (command) {
     bundle();
     break;
   default:
-    console.log("Unknown command. Available commands: generate-models, bundle");
-}
+    console.log("Unknown command. Available commands: create-app, generate-models, bundle");
+}

package/commands/createApp/assets/logo.svg

@@ -0,0 +1,19 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_1_8)">
+<path d="M8.034 6.006V13H6.097V12.194C5.59433 12.8007 4.86633 13.104 3.913 13.104C3.25433 13.104 2.65633 12.9567 2.119 12.662C1.59033 12.3673 1.17433 11.947 0.871 11.401C0.567667 10.855 0.416 10.2223 0.416 9.503C0.416 8.78367 0.567667 8.151 0.871 7.605C1.17433 7.059 1.59033 6.63867 2.119 6.344C2.65633 6.04933 3.25433 5.902 3.913 5.902C4.80567 5.902 5.50333 6.18367 6.006 6.747V6.006H8.034ZM4.264 11.44C4.77533 11.44 5.2 11.2667 5.538 10.92C5.876 10.5647 6.045 10.0923 6.045 9.503C6.045 8.91367 5.876 8.44567 5.538 8.099C5.2 7.74367 4.77533 7.566 4.264 7.566C3.744 7.566 3.315 7.74367 2.977 8.099C2.639 8.44567 2.47 8.91367 2.47 9.503C2.47 10.0923 2.639 10.5647 2.977 10.92C3.315 11.2667 3.744 11.44 4.264 11.44Z" fill="url(#paint0_linear_1_8)"/>
+<path d="M13.317 5.538C12.589 5.538 12.0387 5.69833 11.666 6.019C11.2933 6.331 11.107 6.80333 11.107 7.436V7.995H14.851V9.685H11.107V13H9.001V7.449C9.001 6.279 9.365 5.369 10.093 4.719C10.8297 4.069 11.8567 3.744 13.174 3.744C13.694 3.744 14.1837 3.80033 14.643 3.913C15.1023 4.017 15.501 4.173 15.839 4.381L15.189 6.045C14.669 5.707 14.045 5.538 13.317 5.538Z" fill="url(#paint1_linear_1_8)"/>
+</g>
+<defs>
+<linearGradient id="paint0_linear_1_8" x1="1.5" y1="6.93333" x2="7.31883" y2="11.8926" gradientUnits="userSpaceOnUse">
+<stop stop-color="#656E7A"/>
+<stop offset="1" stop-color="#99A6B8"/>
+</linearGradient>
+<linearGradient id="paint1_linear_1_8" x1="12.5" y1="3.73333" x2="9.68642" y2="12.7016" gradientUnits="userSpaceOnUse">
+<stop stop-color="#48C5FF"/>
+<stop offset="1" stop-color="#A1E1FF"/>
+</linearGradient>
+<clipPath id="clip0_1_8">
+<rect width="16" height="16" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/commands/createApp/main.js

@@ -0,0 +1,27 @@
+import chalk from 'chalk';
+
+import {
+  parseArgumentsIntoOptions,
+  prepareWorkflow,
+  promptForMissingOptions,
+} from './utils.js';
+
+
+export default async function createApp(args) {
+  // Step 1: Parse CLI arguments with `arg`
+  let options = parseArgumentsIntoOptions(args);
+
+  // Step 2: Ask for missing arguments via `inquirer`
+  options = await promptForMissingOptions(options);
+
+  // Step 3: Prepare a Listr-based workflow
+  const tasks = prepareWorkflow(options)
+
+  // Step 4: Run tasks
+  try {
+    await tasks.run();
+  } catch (err) {
+    console.error(chalk.red(`\n❌  ${err.message}\n`));
+    process.exit(1);
+  }
+}

package/commands/createApp/templates.js

@@ -0,0 +1,326 @@
+export function gitignore() {
+  return `# Dependency directories
+node_modules/
+
+# dotenv environment variable files
+.env
+`;
+}
+
+export function env(dbUrl, prismaDbUrl) {
+  const base = `
+ADMINFORTH_SECRET=123
+NODE_ENV=development
+DATABASE_URL=${dbUrl}
+`
+  if (prismaDbUrl)
+    return base + `PRISMA_DATABASE_URL=${prismaDbUrl}`;
+  return base;
+}
+
+export function envSample(dbUrl, prismaDbUrl) {
+  return env(dbUrl, prismaDbUrl);
+}
+
+export function indexTs(appName) {
+  return `import express from 'express';
+import AdminForth, { Filters } from 'adminforth';
+import usersResource from "./resources/users";
+
+const ADMIN_BASE_URL = '';
+
+export const admin = new AdminForth({
+  baseUrl : ADMIN_BASE_URL,
+  auth: {
+    usersResourceId: 'users',  // resource to get user during login
+    usernameField: 'email',  // field where username is stored, should exist in resource
+    passwordHashField: 'password_hash',
+    rememberMeDays: 30, // users who will check "remember me" will stay logged in for 30 days
+    loginBackgroundImage: 'https://images.unsplash.com/photo-1534239697798-120952b76f2b?q=80&w=3389&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
+    loginBackgroundPosition: '1/2', // over, 3/4, 2/5, 3/5 (tailwind grid)
+    demoCredentials: "adminforth:adminforth",  // never use it for production
+    loginPromptHTML: "Use email <b>adminforth</b> and password <b>adminforth</b> to login",
+  },
+  customization: {
+    brandName: '${appName}',
+    title: '${appName}',
+    favicon: '@@/assets/favicon.png',
+    brandLogo: '@@/assets/logo.svg',
+    datesFormat: 'DD MMM',
+    timeFormat: 'HH:mm a',
+    showBrandNameInSidebar: true,
+    styles: {
+      colors: {
+        light: {
+          // color for links, icons etc.
+          primary: '#B400B8',
+          // color for sidebar and text
+          sidebar: {main:'#571E58', text:'white'},
+        },
+        dark: {
+          primary: '#82ACFF',
+          sidebar: {main:'#1f2937', text:'#9ca3af'},
+        }
+      }
+    },
+  },
+  dataSources: [
+    {
+      id: 'maindb',
+      url: \`\${process.env.DATABASE_URL}\`
+    },
+  ],
+  resources: [
+    usersResource,
+  ],
+  menu: [
+    {
+      type: 'heading',
+      label: 'SYSTEM',
+    },
+    {
+      label: 'Users',
+      icon: 'flowbite:user-solid', // any icon from iconify supported in format <setname>:<icon>, e.g. from here https://icon-sets.iconify.design/flowbite/
+      resourceId: 'users',
+    }
+  ],
+});
+
+if (import.meta.url === \`file://\${process.argv[1]}\`) {
+  // if script is executed directly e.g. node index.ts or npm start
+
+  const app = express()
+  app.use(express.json());
+  const port = 3500;
+
+  // needed to compile SPA. Call it here or from a build script e.g. in Docker build time to reduce downtime
+  await admin.bundleNow({ hotReload: process.env.NODE_ENV === 'development'});
+  console.log('Bundling AdminForth done. For faster serving consider calling bundleNow() from a build script.');
+
+  // serve after you added all api
+  admin.express.serve(app)
+
+  admin.discoverDatabases().then(async () => {
+    if (!await admin.resource('users').get([Filters.EQ('email', 'adminforth')])) {
+      await admin.resource('users').create({
+        email: 'adminforth',
+        password_hash: await AdminForth.Utils.generatePasswordHash('adminforth'),
+        role: 'superadmin',
+      });
+    }
+  });
+
+  admin.express.listen(port, () => {
+    console.log(\`Example app listening at http://localhost:\${port}\`)
+    console.log(\`\\n⚡ AdminForth is available at http://localhost:\${port}\${ADMIN_BASE_URL}\n\`)
+  });
+}
+`;
+}
+
+export function schemaPrisma(provider, dbUrl) {
+  return `generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "${provider}"
+  url      = env("PRISMA_DATABASE_URL")
+}
+
+model adminuser {
+  id            String     @id
+  email         String     @unique
+  password_hash String
+  role          String
+  created_at    DateTime
+}
+`;
+}
+
+export function usersResource() {
+  return `import AdminForth, { AdminForthDataTypes, AdminForthResourceInput } from 'adminforth';
+import type { AdminUser } from  'adminforth';
+
+async function canModifyUsers({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
+  return adminUser.dbUser.role === 'superadmin';
+}
+
+export default {
+  dataSource: 'maindb',
+  table: 'adminuser',
+  resourceId: 'users',
+  label: 'Users',
+  recordLabel: (r) => \`👤 \${r.email}\`,
+  options: {
+    allowedActions: {
+      edit: canModifyUsers,
+      delete: canModifyUsers,
+    },
+  },
+  columns: [
+    {
+      name: 'id',
+      primaryKey: true,
+      type: AdminForthDataTypes.STRING,
+      fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),
+      showIn: ['list', 'filter', 'show'],
+    },
+    {
+      name: 'email',
+      required: true,
+      isUnique: true,
+      type: AdminForthDataTypes.STRING,
+      validation: [
+        // you can also use AdminForth.Utils.EMAIL_VALIDATOR which is alias to this object
+        {
+          regExp: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+          message: 'Email is not valid, must be in format example@test.com'
+        },
+      ]
+    },
+    {
+      name: 'created_at',
+      type: AdminForthDataTypes.DATETIME,
+      showIn: ['list', 'filter', 'show'],
+      fillOnCreate: ({ initialRecord, adminUser }) => (new Date()).toISOString(),
+    },
+    {
+      name: 'role',
+      type: AdminForthDataTypes.STRING,
+      enum: [
+        { value: 'superadmin', label: 'Super Admin' },
+        { value: 'user', label: 'User' },
+      ]
+    },
+    {
+      name: 'password',
+      virtual: true,  // field will not be persisted into db
+      required: { create: true }, // make required only on create page
+      editingNote: { edit: 'Leave empty to keep password unchanged' },
+      type: AdminForthDataTypes.STRING,
+      showIn: ['create', 'edit'], // to show field only on create and edit pages
+      masked: true, // to show stars in input field
+
+      minLength: 8,
+      validation: [
+        // request to have at least 1 digit, 1 upper case, 1 lower case
+        AdminForth.Utils.PASSWORD_VALIDATORS.UP_LOW_NUM,
+      ],
+    },
+    {
+      name: 'password_hash',
+      type: AdminForthDataTypes.STRING,
+      backendOnly: true,
+      showIn: []
+    }
+  ],
+  hooks: {
+    create: {
+      beforeSave: async ({ record, adminUser, resource }) => {
+        record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+        return { ok: true };
+      }
+    },
+    edit: {
+      beforeSave: async ({ record, adminUser, resource }) => {
+        if (record.password) {
+          record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+        }
+        return { ok: true }
+      },
+    },
+  }
+} as AdminForthResourceInput;
+`;
+}
+
+/**
+ * Root package.json template
+ */
+export function rootPackageJson(appName) {
+  // Note: you might want to keep versions in sync or fetch from a config
+  return `{
+  "name": "${appName}",
+  "version": "1.0.0",
+  "main": "index.ts",
+  "type": "module",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "scripts": {
+    "start": "tsx watch --env-file=.env index.ts",
+    "migrate": "npx prisma migrate deploy",
+    "makemigration": "npx --yes prisma migrate deploy; npx --yes prisma migrate dev",
+    "test": "echo \\"Error: no test specified\\" && exit 1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "adminforth": "latest",
+    "express": "latest"
+  },
+  "devDependencies": {
+    "typescript": "5.4.5",
+    "tsx": "4.11.2",
+    "@types/express": "latest",
+    "@types/node": "latest"
+  }
+}
+`;
+}
+
+/**
+ * Root tsconfig.json template
+ */
+export function rootTsConfig() {
+  return `{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true
+  },
+  "exclude": ["node_modules", "dist"]
+}
+`;
+}
+
+/**
+ * custom/package.json
+ */
+export function customPackageJson(appName) {
+  return `{
+  "name": "custom",
+  "version": "1.0.0",
+  "main": "index.ts",
+  "scripts": {
+    "test": "echo \\"Error: no test specified\\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": ""
+}
+`;
+}
+
+/**
+ * custom/tsconfig.json
+ */
+export function customTsconfig() {
+  return `{
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "@/": "../node_modules/adminforth/dist/spa/src/",
+            "": "../node_modules/adminforth/dist/spa/node_modules/",
+            "@@/*": "."
+        }
+    }
+}
+`;
+}

package/commands/createApp/utils.js

@@ -0,0 +1,219 @@
+import arg from 'arg';
+import chalk from 'chalk';
+import fs from 'fs';
+import fse from 'fs-extra';
+import inquirer from 'inquirer';
+import path from 'path';
+import { Listr } from 'listr2'
+import { fileURLToPath } from 'url';
+import {ConnectionString} from 'connection-string';
+import {execa} from 'execa';
+
+import * as templates from './templates.js';
+
+export function parseArgumentsIntoOptions(rawArgs) {
+  const args = arg(
+    {
+      '--app-name': String,
+      '--db': String,
+      // you can add more flags here if needed
+    },
+    {
+      argv: rawArgs.slice(1),  // skip "create-app"
+    }
+  );
+
+  return {
+    appName: args['--app-name'],
+    db: args['--db'],
+  };
+}
+
+export async function promptForMissingOptions(options) {
+  const questions = [];
+
+  if (!options.appName) {
+      questions.push({
+      type: 'input',
+      name: 'appName',
+      message: 'Please specify the name of the app >',
+      default: 'adminforth-app',
+      });
+  };
+
+  if (!options.db) {
+      questions.push({
+      type: 'input',
+      name: 'db',
+      message: 'Please specify the database URL to use >',
+      default: 'sqlite://.db.sqlite',
+      });
+  };
+
+  const answers = await inquirer.prompt(questions);
+  return {
+      ...options,
+      appName: options.appName || answers.appName,
+      db: options.db || answers.db,
+  };
+}
+
+function checkNodeVersion(minRequiredVersion = 20) {
+  const current = process.versions.node.split('.');
+  const major = parseInt(current[0], 10);
+
+  if (isNaN(major) || major < minRequiredVersion) {
+    throw new Error(
+      `Node.js v${minRequiredVersion}+ is required. You have ${process.versions.node}. ` +
+      `Please upgrade Node.js.`
+    );
+  }
+}
+
+function parseConnectionString(dbUrl) {
+  return new ConnectionString(dbUrl);
+}
+
+function detectDbProvider(protocol) {
+  if (protocol.startsWith('sqlite')) {
+    return 'sqlite';
+  } else if (protocol.startsWith('postgres')) {
+    return 'postgresql';
+  } else if (protocol.startsWith('mongodb')) {
+    return 'mongodb';
+  }
+
+  const message = `Unknown database provider for ${protocol}. Only SQLite, PostgreSQL, and MongoDB are supported now.`;
+  throw new Error(message);
+}
+
+function generateDbUrlForPrisma(connectionString) {
+  if (connectionString.protocol.startsWith('sqlite'))
+    return `file:${connectionString.host}`;
+  if (connectionString.protocol.startsWith('mongodb'))
+    return null;
+  return connectionString.toString();
+}
+
+function initialChecks() {
+  return [
+    {
+      title: '👀 Checking Node.js version...',
+      task: () => checkNodeVersion(20)
+    },
+    {
+      title: '👀 Validating current working directory...',
+      task: () => checkForExistingPackageJson()
+    }
+  ]
+}
+
+function checkForExistingPackageJson() {
+  if (fs.existsSync(path.join(process.cwd(), 'package.json'))) {
+    throw new Error(
+      `A package.json already exists in this directory.\n` +
+      `Please remove it or use an empty directory.`
+    );
+  }
+}
+
+async function scaffoldProject(ctx, options, cwd) {
+  const connectionString = parseConnectionString(options.db);
+  const provider = detectDbProvider(connectionString.protocol);
+  const prismaDbUrl = generateDbUrlForPrisma(connectionString);
+  ctx.skipPrismaSetup = !prismaDbUrl;
+  const appName = options.appName;
+
+  const dirname = path.dirname(fileURLToPath(import.meta.url));
+  const sourceAssetsDir = path.join(dirname, 'assets');
+  const targetAssetsDir = path.join(cwd, 'custom', 'assets');
+
+  await fse.ensureDir(targetAssetsDir);
+  await fse.copy(sourceAssetsDir, targetAssetsDir);
+
+  writeTemplateFiles(cwd, connectionString.toString(), prismaDbUrl, appName, provider);
+
+  const resourcesDir = path.join(cwd, 'resources');
+  await fse.ensureDir(resourcesDir);
+  fs.writeFileSync(path.join(resourcesDir, 'users.ts'), templates.usersResource());
+
+  const customDir = path.join(cwd, 'custom');
+  await fse.ensureDir(customDir);
+  ctx.customDir = customDir;
+  fs.writeFileSync(path.join(customDir, 'package.json'), templates.customPackageJson(appName));
+  fs.writeFileSync(path.join(customDir, 'tsconfig.json'), templates.customTsconfig());
+}
+
+function writeTemplateFiles(cwd, dbUrl, prismaDbUrl, appName, provider) {
+  fs.writeFileSync(path.join(cwd, '.gitignore'), templates.gitignore());
+  fs.writeFileSync(path.join(cwd, '.env'), templates.env(dbUrl, prismaDbUrl));
+  fs.writeFileSync(path.join(cwd, '.env.sample'), templates.envSample(dbUrl, prismaDbUrl));
+  fs.writeFileSync(path.join(cwd, 'index.ts'), templates.indexTs(appName));
+  if (prismaDbUrl)
+    fs.writeFileSync(path.join(cwd, 'schema.prisma'), templates.schemaPrisma(provider, prismaDbUrl));
+  fs.writeFileSync(path.join(cwd, 'package.json'), templates.rootPackageJson(appName));
+  fs.writeFileSync(path.join(cwd, 'tsconfig.json'), templates.rootTsConfig());
+}
+
+async function installDependencies(ctx, cwd) {
+  const customDir = ctx.customDir;
+
+  await Promise.all([
+    await execa('npm', ['install', '--no-package-lock'], { cwd }),
+    await execa('npm', ['install'], { cwd: customDir }),
+  ]);
+}
+
+function generateFinalInstructions(skipPrismaSetup) {
+  let instruction = '⏭️  Run the following commands to get started:\n';
+  if (!skipPrismaSetup)
+    instruction += `
+  ${chalk.dim('// runs "npx prisma migrate dev --name init" to generate and apply initial migration')}`;
+  ${chalk.cyan('$ npm run makemigration -- --name init')}
+  instruction += `
+  ${chalk.dim('\n// starts dev server with tsx watch for hot-reloading')}\n
+  ${chalk.cyan('$ npm start')}
+`;
+
+  instruction += '😉 Happy coding!';
+
+  return instruction;
+}
+
+export function prepareWorkflow(options) {
+  const cwd = process.cwd();
+  const tasks = new Listr([
+    {
+      title: '🔍 Initial checks...',
+      task: (_, task) =>
+        task.newListr(
+          initialChecks(),
+          { concurrent: true },
+        )
+    },
+    {
+      title: '🚀 Scaffolding your project...',
+      task: async (ctx) => scaffoldProject(ctx, options, cwd)
+    },
+    {
+      title: '📦 Installing dependencies...',
+      task: async (ctx) => installDependencies(ctx, cwd)
+    },
+    {
+      title: '📝 Preparing final instructions...',
+      task: (ctx) => {
+        console.log(chalk.green(`✅ Successfully created your new Adminforth project!\n`));
+        console.log(generateFinalInstructions(ctx.skipPrismaSetup));
+        console.log('\n\n');
+    }
+  }],
+  {
+    rendererOptions: {collapseSubtasks: false},
+    concurrent: false,
+    exitOnError: true,
+    collectErrors: true,
+  }
+);
+
+  return tasks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adminforth",
-  "version": "1.5.9-next.12",
+  "version": "1.5.9-next.14",
   "description": "OpenSource Vue3 powered forth-generation admin panel",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -40,14 +40,21 @@
     "@clickhouse/client": "^1.4.0",
     "@faker-js/faker": "^9.0.3",
     "@types/express": "^5.0.0",
+    "arg": "^5.0.2",
     "better-sqlite3": "^11.5.0",
+    "chalk": "^5.4.1",
+    "connection-string": "^4.4.0",
     "dayjs": "^1.11.11",
     "dotenv": "^16.4.5",
+    "esm": "^3.2.25",
+    "execa": "^9.5.2",
     "express": "^4.21.0",
     "filewatcher": "^3.0.1",
     "fs-extra": "^11.2.0",
     "fuse.js": "^7.0.0",
+    "inquirer": "^12.3.0",
     "jsonwebtoken": "^9.0.2",
+    "listr2": "^8.2.5",
     "mongodb": "6.6",
     "node-fetch": "^3.3.2",
     "pg": "^8.11.5",