umpordez 0.0.2 → 1.0.0

package/create.mjs

@@ -0,0 +1,334 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { buildReplacements } from './template-variables.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.join(__dirname, 'template');
+
+// umpordez.com design tokens
+const green = chalk.hex('#02e027');
+const cyan = chalk.hex('#00fff9');
+const red = chalk.hex('#ff3c00');
+const dim = chalk.hex('#a0a0a0');
+
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg',
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.zip', '.tar', '.gz', '.br',
+    '.pdf', '.mp3', '.mp4', '.webm', '.ogg',
+]);
+
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+
+function toDbName(slug) {
+    return slug.replace(/-/g, '_');
+}
+
+async function promptProjectDetails() {
+    console.log(green.bold('  Project Setup'));
+    console.log(chalk.hex('#2c2c2c')('  ' + '\u2500'.repeat(40)));
+    console.log('');
+
+    const { name } = await inquirer.prompt([{
+        type: 'input',
+        name: 'name',
+        message: 'Project name (e.g. "Minha Empresa"):',
+        validate: (v) => v.trim() ? true : 'Project name is required',
+    }]);
+
+    const suggestedSlug = slugify(name);
+    const suggestedDb = toDbName(suggestedSlug);
+
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'slug',
+            message: 'Project slug:',
+            default: suggestedSlug,
+            validate: (v) => /^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(v) || v.length === 1 && /^[a-z0-9]$/.test(v)
+                ? true
+                : 'Slug must be lowercase alphanumeric with hyphens (no leading/trailing hyphens)',
+        },
+        {
+            type: 'input',
+            name: 'description',
+            message: 'Short description:',
+            default: '',
+        },
+        {
+            type: 'input',
+            name: 'domain',
+            message: 'Domain (e.g. "minhaempresa.com.br"):',
+            validate: (v) => v.trim() ? true : 'Domain is required',
+        },
+        {
+            type: 'input',
+            name: 'dbName',
+            message: 'Database name:',
+            default: suggestedDb,
+            validate: (v) => /^[a-z_][a-z0-9_]*$/.test(v)
+                ? true
+                : 'Database name must be lowercase with underscores',
+        },
+        {
+            type: 'input',
+            name: 'outputDir',
+            message: 'Output directory:',
+            default: `./${suggestedSlug}`,
+        },
+        {
+            type: 'input',
+            name: 'adminEmail',
+            message: 'Admin email:',
+            default: 'admin@localhost.com',
+            validate: (v) => v.includes('@') ? true : 'Must be a valid email',
+        },
+        {
+            type: 'password',
+            name: 'adminPassword',
+            message: 'Admin password:',
+            validate: (v) => v.length >= 6 ? true : 'Password must be at least 6 characters',
+        },
+        {
+            type: 'input',
+            name: 'apiPort',
+            message: 'Admin API port:',
+            default: '4000',
+            validate: (v) => /^\d+$/.test(v) && +v > 0 && +v < 65536
+                ? true
+                : 'Must be a valid port number',
+        },
+        {
+            type: 'input',
+            name: 'siteApiPort',
+            message: 'Site API port:',
+            default: '4001',
+            validate: (v) => /^\d+$/.test(v) && +v > 0 && +v < 65536
+                ? true
+                : 'Must be a valid port number',
+        },
+        {
+            type: 'input',
+            name: 'adminUiPort',
+            message: 'Admin panel port:',
+            default: '5173',
+            validate: (v) => /^\d+$/.test(v) && +v > 0 && +v < 65536
+                ? true
+                : 'Must be a valid port number',
+        },
+        {
+            type: 'input',
+            name: 'sitePort',
+            message: 'Public site port:',
+            default: '3000',
+            validate: (v) => /^\d+$/.test(v) && +v > 0 && +v < 65536
+                ? true
+                : 'Must be a valid port number',
+        },
+        {
+            type: 'input',
+            name: 'primaryColor',
+            message: 'Primary color (hex):',
+            default: '#2563eb',
+            validate: (v) => /^#?([0-9a-fA-F]{6})$/.test(v.trim())
+                ? true
+                : 'Must be a valid hex color (e.g. #2563eb)',
+            filter: (v) => v.trim().startsWith('#') ? v.trim() : `#${v.trim()}`,
+        },
+        {
+            type: 'list',
+            name: 'defaultTheme',
+            message: 'Default theme:',
+            choices: [
+                { name: 'Light', value: 'light' },
+                { name: 'Dark', value: 'dark' },
+                { name: 'System (follows OS preference)', value: 'system' },
+            ],
+            default: 'light',
+        },
+    ]);
+
+    return { name: name.trim(), ...answers };
+}
+
+function showSummary(details) {
+    console.log('');
+    console.log(green.bold('  Project Summary'));
+    console.log(chalk.hex('#2c2c2c')('  ' + '\u2500'.repeat(40)));
+    console.log('');
+    console.log(`  ${chalk.bold('Name:')}         ${cyan(details.name)}`);
+    console.log(`  ${chalk.bold('Slug:')}         ${details.slug}`);
+    console.log(`  ${chalk.bold('Description:')}  ${details.description || dim('(none)')}`);
+    console.log(`  ${chalk.bold('Domain:')}       ${cyan(details.domain)}`);
+    console.log(`  ${chalk.bold('Database:')}     ${details.dbName}`);
+    console.log(`  ${chalk.bold('Output:')}       ${details.outputDir}`);
+    console.log(`  ${chalk.bold('Admin:')}        ${details.adminEmail}`);
+    console.log(`  ${chalk.bold('Ports:')}        API ${cyan(details.apiPort)} | Site API ${cyan(details.siteApiPort)} | Admin ${cyan(details.adminUiPort)} | Site ${cyan(details.sitePort)}`);
+    console.log(`  ${chalk.bold('Color:')}        ${chalk.hex(details.primaryColor)('\u2588\u2588')} ${details.primaryColor}`);
+    console.log(`  ${chalk.bold('Theme:')}        ${details.defaultTheme}`);
+    console.log('');
+    console.log(dim('  What gets generated:'));
+    console.log(dim(`  ${green('>')} Admin API (Express + TypeScript)`));
+    console.log(dim(`  ${green('>')} Site API (Express + TypeScript)`));
+    console.log(dim(`  ${green('>')} React admin panel (Vite + shadcn/ui)`));
+    console.log(dim(`  ${green('>')} Public site (EJS + Tailwind)`));
+    console.log(dim(`  ${green('>')} PostgreSQL migrations + seed`));
+    console.log(dim(`  ${green('>')} S3 file uploads`));
+    console.log(dim(`  ${green('>')} Console task runner`));
+    console.log(dim(`  ${green('>')} Production build system`));
+    console.log('');
+}
+
+async function getAllFiles(dir) {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await getAllFiles(fullPath));
+        } else {
+            files.push(fullPath);
+        }
+    }
+
+    return files;
+}
+
+function isBinaryFile(filePath) {
+    return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+function replacePlaceholders(content, replacements) {
+    let result = content;
+    for (const [placeholder, value] of Object.entries(replacements)) {
+        result = result.replaceAll(placeholder, value);
+    }
+    return result;
+}
+
+export async function createProject() {
+    const details = await promptProjectDetails();
+
+    showSummary(details);
+
+    const { confirm } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Look good? Let\'s go!',
+        default: true,
+    }]);
+
+    if (!confirm) {
+        console.log(chalk.yellow('Aborted. No files were created.'));
+        return;
+    }
+
+    const outputDir = path.resolve(details.outputDir);
+
+    if (fs.existsSync(outputDir)) {
+        const { overwrite } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'overwrite',
+            message: `Directory ${outputDir} already exists. Continue anyway?`,
+            default: false,
+        }]);
+
+        if (!overwrite) {
+            console.log(chalk.yellow('Aborted.'));
+            return;
+        }
+    }
+
+    const replacements = buildReplacements(details);
+
+    console.log('');
+
+    // [1/5] Copy template
+    console.log(green('[1/5]') + ' Copying template files...');
+    await fs.promises.cp(TEMPLATE_DIR, outputDir, { recursive: true });
+
+    // [2/5] Replace placeholders
+    const files = await getAllFiles(outputDir);
+    let replacedCount = 0;
+
+    for (const filePath of files) {
+        if (isBinaryFile(filePath)) {
+            continue;
+        }
+
+        const content = await fs.promises.readFile(filePath, 'utf-8');
+        const replaced = replacePlaceholders(content, replacements);
+
+        if (replaced !== content) {
+            await fs.promises.writeFile(filePath, replaced, 'utf-8');
+            replacedCount++;
+        }
+    }
+
+    console.log(green('[2/5]') + ` Replacing placeholders... ${dim(`(${replacedCount} files updated)`)}`);
+
+    // [3/5] Rename files
+    const allEntries = await getAllFiles(outputDir);
+    for (const filePath of allEntries) {
+        const dir = path.dirname(filePath);
+        const basename = path.basename(filePath);
+
+        if (basename.includes('{{PROJECT_SLUG}}')) {
+            const newName = basename.replaceAll('{{PROJECT_SLUG}}', details.slug);
+            const newPath = path.join(dir, newName);
+            await fs.promises.rename(filePath, newPath);
+        }
+    }
+
+    console.log(green('[3/5]') + ' Renaming template files...');
+
+    // [4/5] Make scripts executable
+    const scripts = [
+        'dev.sh',
+        'install.sh',
+        'seed.sh',
+        'server/knex.sh',
+    ];
+
+    for (const script of scripts) {
+        const scriptPath = path.join(outputDir, script);
+        if (fs.existsSync(scriptPath)) {
+            await fs.promises.chmod(scriptPath, 0o755);
+        }
+    }
+
+    console.log(green('[4/5]') + ' Making scripts executable...');
+
+    // [5/5] Git init
+    execSync('git init', { cwd: outputDir, stdio: 'ignore' });
+    console.log(green('[5/5]') + ' Initializing git repository...');
+
+    // Done!
+    console.log('');
+    console.log(green.bold(`  \u2713 "${details.name}" created successfully!`));
+    console.log('');
+    console.log(chalk.bold('  Next steps:'));
+    console.log(`  ${green('1.')} cd ${details.outputDir}`);
+    console.log(`  ${green('2.')} ./install.sh`);
+    console.log(`  ${green('3.')} ./seed.sh`);
+    console.log(`  ${green('4.')} ./dev.sh`);
+    console.log('');
+    console.log(dim(`  Admin panel:  ${cyan(`http://localhost:${details.adminUiPort}`)}`));
+    console.log(dim(`  Admin API:    ${cyan(`http://localhost:${details.apiPort}`)}`));
+    console.log(dim(`  Site:         ${cyan(`http://localhost:${details.sitePort}`)}`));
+    console.log('');
+    console.log(dim('  Happy hacking! - ') + cyan('youtube.com/ligeiro'));
+    console.log('');
+}

package/package.json

@@ -1,14 +1,9 @@
 {
     "name": "umpordez",
     "type": "module",
-    "version": "0.0.2",
-    "description": "umpordez cli, interact, create, build your own meme",
+    "version": "1.0.0",
+    "description": "SaaS starter kit generator - multi-tenant TypeScript + React + PostgreSQL",
     "main": "cli.mjs",
-    "imports": {
-        "#root/*": "./*",
-        "#tests/*": "./tests/*",
-        "#core/*": "./core/*"
-    },
     "scripts": {
         "test": "test"
     },

package/template/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+    "permissions": {
+        "allow": [
+            "Bash(ls:*)",
+            "Bash(npm install:*)",
+            "Bash(npm run:*)",
+            "Bash(npm ls:*)",
+            "Bash(npx tsc:*)",
+            "Bash(npx knex:*)",
+            "Bash(npx tsx:*)",
+            "Bash(node -e:*)",
+            "Bash(psql:*)",
+            "Bash(chmod:*)",
+            "Bash(tree:*)",
+            "Bash(curl:*)",
+            "Bash(git add:*)",
+            "Bash(git commit:*)"
+        ]
+    }
+}

package/template/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,tsx,js,css,scss}]
+indent_style = space
+indent_size = 4

package/template/.github/copilot-instructions.md

@@ -0,0 +1,186 @@
+# Copilot Instructions
+
+## Project: {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+Multi-tenant SaaS application built with the **umpordez** architecture pattern for the Brazilian market.
+
+## Tech Stack
+
+- **Backend:** TypeScript, Express.js, PostgreSQL, Knex.js, Zod
+- **Admin UI:** React 18, Vite, TailwindCSS, shadcn/ui (Radix), React Router DOM 6, TanStack Query v5, React Hook Form + Zod
+- **Site UI:** Express + EJS + TailwindCSS
+- **Auth:** httpOnly JWT cookies (30-day expiry)
+- **Uploads:** AWS S3 via multer-s3 with signed URLs
+
+## Architecture
+
+- Multi-API: `server/apps/api/` (admin, port 4000) + `server/apps/site-api/` (site, port 4001)
+- Shared core: `server/core/` (db, models, context, s3, email, errors, logger)
+- Shared middleware: `server/apps/shared/` (auth guards, error handler, buildHandler)
+- Context-based DI: fresh `Context` per request with all models instantiated
+- Models extend `BaseModel`, access DB via `this.knex`, other models via `this.context`
+- Routes use `buildHandler()` wrapper for async error handling + Zod validation
+- Multi-tenant: users -> user_in_accounts -> accounts -> domain entities
+- Roles: admin (platform-wide), owner, manager, user (per-account)
+
+## Code Style
+
+- 4-space indentation, semicolons required, LF line endings
+- TypeScript strict mode everywhere
+- Code in English, UI text in Portuguese (Brazilian market)
+- Path aliases: `#core/*`, `#shared/*`, `#api/*` (server), `@/*` (admin UI)
+
+## Key Patterns — Follow These When Generating Code
+
+### Backend: Models (data access)
+
+All database queries go in models, never in route handlers directly. Models extend `BaseModel` and live in `server/core/models/`.
+
+```typescript
+import BaseModel from './base.js';
+import { NotFoundError, ValidationError } from '#core/errors.js';
+
+class MyEntityModel extends BaseModel {
+    async list(options = {}) {
+        const page = Math.max(1, options.page || 1);
+        const limit = Math.min(100, Math.max(1, options.limit || 20));
+        const offset = (page - 1) * limit;
+        const baseQuery = this.knex('my_entities').where('account_id', accountId);
+        if (options.search?.trim()) {
+            baseQuery.whereILike('name', `%${options.search.trim()}%`);
+        }
+        const [{ count }] = await baseQuery.clone().count('id as count');
+        const total = parseInt(String(count), 10);
+        const rows = await baseQuery.clone().select('*')
+            .orderBy('utc_created_on', 'desc').limit(limit).offset(offset);
+        return { rows, total, page, limit, totalPages: Math.ceil(total / limit) };
+    }
+
+    async findById(id: string) {
+        const row = await this.knex('my_entities').where({ id }).first();
+        if (!row) throw new NotFoundError('Entidade não encontrada');
+        return row;
+    }
+}
+```
+
+Register in `server/core/context.ts`: add field + `this.myEntity = new MyEntityModel(this);`
+
+### Backend: Routes
+
+```typescript
+import { buildHandler } from '#shared/utils.js';
+import { z } from 'zod';
+
+const createSchema = z.object({ name: z.string().min(1, 'Nome é obrigatório') });
+
+async function handleCreate(req: Request, res: Response): Promise<void> {
+    const data = createSchema.parse(req.body);
+    const result = await req.context.myEntity.create(req.accountId!, data);
+    res.json({ ok: true, result });
+}
+
+router.post('/my-entities', buildHandler(handleCreate));
+
+export default function makeEndpoint(app: Express): void {
+    app.use('/api/account/:accountId',
+        trySetUserByTokenMiddleware, demandUserMiddleware,
+        demandAccountAccessMiddleware, router);
+}
+```
+
+### Backend: Errors
+
+```typescript
+throw new ValidationError('Campo obrigatório');     // 400
+throw new NotFoundError('Não encontrado');           // 404
+throw new ConflictError('Já existe');                // 409
+throw new ForbiddenError('Sem permissão');           // 403
+throw new UnauthorizedError('Não autorizado');       // 401
+```
+
+### Backend: Transactions
+
+```typescript
+await req.context.knexTransaction(async () => {
+    // All model ops share the same transaction; rollback on throw
+});
+```
+
+### Backend: Migrations (raw SQL)
+
+```typescript
+export async function up(knex: Knex): Promise<void> {
+    await knex.schema.raw(`
+        CREATE TABLE my_entities (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            account_id UUID NOT NULL REFERENCES accounts(id),
+            name VARCHAR(255) NOT NULL,
+            utc_created_on TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+            utc_updated_on TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+        );
+        CREATE INDEX idx_my_entities_account ON my_entities(account_id);
+    `);
+}
+```
+
+### Frontend: fetchApi
+
+```typescript
+import fetchApi from '@/lib/fetch-api';
+const data = await fetchApi('user/accounts');                           // GET
+const data = await fetchApi('admin/users', { page: 1 });               // GET with params
+const data = await fetchApi('login', { email, password }, 'POST');     // POST
+```
+
+Uses `credentials: 'include'` for cookie auth.
+
+### Frontend: React Query hooks
+
+```typescript
+export function useMyEntities(accountId: string, filters: PaginationFilters) {
+    return useQuery({
+        queryKey: queryKeys.myEntities.list(accountId, filters),
+        placeholderData: keepPreviousData,
+        queryFn: async () => {
+            const res = await fetchApi(`account/${accountId}/my-entities`, filters);
+            if (!res.ok) throw new Error(res.message);
+            return res;
+        },
+    });
+}
+```
+
+Use `keepPreviousData` on paginated/searchable queries. Add keys to `lib/query-keys.ts`. Invalidate related queries in mutation `onSuccess`.
+
+### Frontend: Confirm modal
+
+```typescript
+const confirm = useConfirm();
+const ok = await confirm({
+    title: 'Excluir', description: 'Tem certeza?',
+    confirmLabel: 'Excluir', variant: 'destructive',
+});
+```
+
+### Frontend: Layouts
+
+| Layout | Auth | Route prefix |
+|---|---|---|
+| `PublicLayout` | None | `/` |
+| `UserLayout` | `useUser()` | `/user` |
+| `AdminLayout` | admin role | `/admin` |
+| `AccountLayout` | account access | `/account/:accountId` |
+
+## File Naming
+
+- Components: PascalCase (`AppSidebar.tsx`)
+- Hooks: kebab-case with `use-` prefix (`use-user.tsx`)
+- Routes/Models/Utils: kebab-case (`demand-user.ts`, `fetch-api.ts`)
+- Migrations: timestamp prefix (`20260208000000_description.ts`)
+
+## Multi-Tenancy
+
+Always filter by `account_id` in tenant-scoped queries. The `demand-account-access` middleware verifies access and sets `req.accountId` + `req.accountRole`. Admin users bypass the check.

package/template/.nvimrc

@@ -0,0 +1,7 @@
+set tabstop=4
+set shiftwidth=4
+set expandtab
+set smartindent
+set fileformat=unix
+set encoding=utf-8
+set colorcolumn=80

package/template/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "esbenp.prettier-vscode",
+        "dbaeumer.vscode-eslint",
+        "bradlc.vscode-tailwindcss",
+        "editorconfig.editorconfig",
+        "ms-vscode.vscode-typescript-next"
+    ]
+}

package/template/.vscode/settings.json

@@ -0,0 +1,28 @@
+{
+    "editor.tabSize": 4,
+    "editor.insertSpaces": true,
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.codeActionsOnSave": {
+        "source.fixAll.eslint": "explicit"
+    },
+    "files.eol": "\n",
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true,
+    "typescript.preferences.importModuleSpecifier": "non-relative",
+    "typescript.tsdk": "node_modules/typescript/lib",
+    "search.exclude": {
+        "**/node_modules": true,
+        "**/build": true,
+        "**/dist": true
+    },
+    "[typescript]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "[typescriptreact]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "[json]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    }
+}