@appweaver/create-weaver-app 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+UNLICENSED

package/README.md

@@ -0,0 +1,7 @@
+# Appweaver - Create Weaver App
+
+> Simple, fast, and reliable web application builder tool.
+
+## License
+
+UNLICENSED

package/create-weaver-app.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/create-weaver-app.js

@@ -0,0 +1,266 @@
+#!/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 node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const commander_1 = require("commander");
+const glob_1 = require("glob");
+const pkg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, './package.json'), 'utf8'));
+const prismaVersion = '7.8.0';
+const dbTypes = ['sqlite', 'postgresql', 'mysql', 'sqlserver'];
+const agentTypes = [
+    'claude',
+    'codex',
+    'junie',
+    'cursor',
+    'copilot',
+    'opencode',
+    'kiro',
+    'pi',
+    'none'
+];
+const program = new commander_1.Command();
+program
+    .name('create-weaver-app')
+    .description('Create Weaver App - Bootstrap new Appweaver project')
+    .version(pkg.version, '-v, --version', 'Output the current version.')
+    .helpOption('-h, --help', 'Output usage information.')
+    .usage('<name> [description] [options]')
+    .argument('<name>', 'Name of the new project')
+    .argument('[description]', 'Description of the new project', 'Appweaver project')
+    .option('-o, --outputDir [outputDir]', 'Directory where to generate new project. (default: name of project)')
+    .option('--database [database]', `Type of SQL database (${dbTypes.join(', ')}).`, parseDatabaseType, 'sqlite')
+    .option('--port [port]', 'Port number where the application server will listen.', parsePortNumber, 5000)
+    .option('--host [host]', 'Hostname or IP address where the application server will bind.', parseHostname, '0.0.0.0')
+    .option('--agent [agent]', `The AI agent for which to configure guidelines and skill files (${agentTypes.join(', ')}).`, parseAgentType, 'claude')
+    .option('--bun', 'Use Bun as application runtime.')
+    .option('--skipInstall', 'Skip all dependencies installation.')
+    .option('--noRedis', 'Skip IoRedis package installation.')
+    .option('--noQueue', 'Skip BullQueue package installation.')
+    .option('--noMailer', 'Skip Nodemailer package installation.')
+    .option('--noCron', 'Skip Cron package installation.')
+    .action(async (name, description, _, command) => {
+    const directory = command.getOptionValue('outputDir');
+    const runtime = command.getOptionValue('bun') ? 'bun' : 'node';
+    const packageManager = runtime === 'bun' ? 'bun' : 'npm';
+    // Check if bun runtime is installed on this machine
+    if (runtime === 'bun') {
+        const status = await runProcess('bun', ['--version'], { quiet: true });
+        if (status !== 0) {
+            console.error('Bun runtime is not installed on this machine.');
+            process.exit(1);
+        }
+    }
+    // Sanitize and create a new directory
+    const sanitizedName = name
+        .replace(/\s+/g, '-')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase();
+    const projectDir = directory ?? sanitizedName;
+    const destDir = node_path_1.default.join(process.cwd(), projectDir);
+    // Initialize new project directory
+    try {
+        await promises_1.default.access(destDir, node_fs_1.default.constants.F_OK);
+        console.log(`Using existing directory: ${node_path_1.default.dirname(destDir)}\n`);
+    }
+    catch (e) {
+        await promises_1.default.mkdir(destDir, { recursive: true });
+        console.log(`Created new directory: ${projectDir}\n`);
+    }
+    console.log('Generating application files...');
+    // Copy template contents into a new directory
+    const templateDir = node_path_1.default.join(__dirname, './templates/default');
+    await promises_1.default.cp(templateDir, destDir, { recursive: true });
+    // Define all variables used in template files with .tpl extension
+    const variables = {
+        NAME: name.charAt(0).toUpperCase() + name.slice(1),
+        LOWER_NAME: sanitizedName,
+        DESCRIPTION: description,
+        HOST: command.getOptionValue('host'),
+        PORT: command.getOptionValue('port'),
+        DEPENDENCIES: getNodeDependencies(command, runtime).join(',\n'),
+        DATABASE_URL: getDatabaseUrl(command, sanitizedName, 'dev'),
+        DATABASE_TEST_URL: getDatabaseUrl(command, sanitizedName, 'test'),
+        VERSION: pkg.version
+    };
+    // Process .tpl files: replace variables and remove .tpl extension
+    const templateFiles = await (0, glob_1.glob)('**/*.tpl', {
+        cwd: destDir,
+        absolute: true,
+        dot: true
+    });
+    for (const templateFile of templateFiles) {
+        let content = await promises_1.default.readFile(templateFile, 'utf8');
+        // Replace variables with values
+        for (const [key, value] of Object.entries(variables)) {
+            content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+        }
+        // Save output to new file and remove template file
+        const outputFile = templateFile.replace(/\.tpl$/, '');
+        await promises_1.default.writeFile(outputFile, content, 'utf8');
+        await promises_1.default.unlink(templateFile);
+    }
+    // Find all runtime-specific files and keep only those for current runtime
+    const runtimeFiles = await (0, glob_1.glob)(`**/*.{node,bun}`, {
+        cwd: destDir,
+        absolute: true,
+        dot: true
+    });
+    for (const runtimeFile of runtimeFiles) {
+        if (runtimeFile.endsWith(`.${runtime}`)) {
+            const outputFile = runtimeFile.replace(`.${runtime}`, '');
+            await promises_1.default.cp(runtimeFile, outputFile);
+        }
+        await promises_1.default.unlink(runtimeFile);
+    }
+    // Create test reports directory
+    await promises_1.default.mkdir(node_path_1.default.join(destDir, 'reports'));
+    // Add instructions for AI Agents and skill files
+    const agent = command.getOptionValue('agent');
+    if (agent !== 'none') {
+        let agentsDir;
+        if (['claude', 'junie', 'kiro', 'pi', 'opencode'].includes(agent)) {
+            agentsDir = `.${agent}`;
+        }
+        else if (agent === 'copilot') {
+            agentsDir = '.github';
+        }
+        else {
+            agentsDir = '.agents';
+        }
+        const guidelinesFileName = agent === 'claude' ? 'CLAUDE.md' : 'AGENTS.md';
+        // Copy skill and referenced files
+        const skillDir = node_path_1.default.join(__dirname, 'skill');
+        const projectSkillPath = node_path_1.default.join(agentsDir, 'skills', 'appweaver');
+        const projectSkillDir = node_path_1.default.join(destDir, projectSkillPath);
+        await promises_1.default.cp(skillDir, projectSkillDir, {
+            recursive: true
+        });
+        // Move the project guidelines file to the project root
+        const guidelinesSkillPath = node_path_1.default.join(projectSkillDir, 'GUIDELINES.md');
+        const guidelinesFilePath = node_path_1.default.join(destDir, guidelinesFileName);
+        await promises_1.default.rename(guidelinesSkillPath, guidelinesFilePath);
+        // Update project guidelines reference paths to point in skills directory
+        const guidelinesContents = await promises_1.default.readFile(guidelinesFilePath, 'utf8');
+        const referencesPath = node_path_1.default
+            .join(projectSkillPath, 'references')
+            .replace(/\\/g, '/');
+        const updatedGuidelinesContent = guidelinesContents.replace(/(\[.+]\()references\/(.+\))/g, `$1${referencesPath}/$2`);
+        await promises_1.default.writeFile(guidelinesFilePath, updatedGuidelinesContent, {
+            encoding: 'utf8'
+        });
+    }
+    console.log(`Done\n`);
+    if (command.getOptionValue('skipInstall')) {
+        console.log(`${name} created successfully!`);
+        return;
+    }
+    console.log(`Installing dependencies...`);
+    await runProcess(packageManager, ['install', '--no-audit', '--no-fund', '--loglevel=error'], { destDir });
+    console.log(`Done\n`);
+    console.log(`Configuring application...`);
+    await runProcess(packageManager, ['run', 'generate'], { destDir });
+    console.log(`Done\n`);
+    console.log(`${name} created successfully!`);
+})
+    .parse();
+function getNodeDependencies(command, runtime) {
+    const dependencies = [];
+    const adapters = {
+        sqlite: runtime === 'bun'
+            ? `"@prisma/adapter-libsql": "${prismaVersion}"`
+            : `"@prisma/adapter-better-sqlite3": "${prismaVersion}"`,
+        postgresql: `"@prisma/adapter-pg": "${prismaVersion}"`,
+        mysql: `"@prisma/adapter-mariadb": "${prismaVersion}"`,
+        sqlserver: `"@prisma/adapter-mssql": "${prismaVersion}"`
+    };
+    const database = command.getOptionValue('database');
+    const databaseDependency = adapters[database.toLowerCase()];
+    if (!databaseDependency) {
+        console.error(`Invalid database type: ${database}`);
+        process.exit(1);
+    }
+    dependencies.push(databaseDependency);
+    dependencies.push(`"@prisma/client": "${prismaVersion}"`);
+    dependencies.push(`"prisma": "${prismaVersion}"`);
+    if (!command.getOptionValue('noQueue')) {
+        dependencies.push('"bullmq": "5.70.1"');
+    }
+    if (!command.getOptionValue('noCron')) {
+        dependencies.push('"cron": "4.4.0"');
+    }
+    if (!command.getOptionValue('noRedis')) {
+        dependencies.push('"ioredis": "5.9.3"');
+    }
+    if (!command.getOptionValue('noMailer')) {
+        dependencies.push('"nodemailer": "8.0.5"');
+    }
+    return dependencies.sort().map((d) => `    ${d}`);
+}
+function getDatabaseUrl(command, name, mode) {
+    const dbName = mode === 'test' ? `${name}-test` : name;
+    const urls = {
+        sqlite: `file:./${mode === 'test' ? 'temp/' : ''}${dbName}.db`,
+        postgresql: `postgresql://${name}:${name}@localhost:5432/${dbName}?schema=public`,
+        mysql: `mysql://${name}:${name}@localhost:3306/${dbName}`,
+        sqlserver: `sqlserver://localhost:1433;database=${dbName};user=${name};password=${name};trustServerCertificate=true`
+    };
+    const database = command.getOptionValue('database');
+    const databaseUrl = urls[database.toLowerCase()];
+    if (!databaseUrl) {
+        console.error(`Invalid database type: ${database}`);
+        process.exit(1);
+    }
+    return databaseUrl;
+}
+function runProcess(cmd, args = [], params = {}) {
+    return new Promise((resolve, reject) => {
+        const { destDir, quiet } = params;
+        const command = args.length > 0 ? `${cmd} ${args.join(' ')}` : cmd;
+        const child = (0, node_child_process_1.spawn)(command, {
+            stdio: quiet ? 'ignore' : 'inherit',
+            shell: true,
+            cwd: destDir
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve(code);
+        });
+    });
+}
+function parseDatabaseType(value) {
+    const lowerDbType = value.toLowerCase();
+    if (!dbTypes.includes(lowerDbType)) {
+        throw new commander_1.InvalidOptionArgumentError(`Must be one of following: ${dbTypes.join(', ')}.`);
+    }
+    return lowerDbType;
+}
+function parsePortNumber(value) {
+    const int = parseInt(value, 10);
+    if (isNaN(int) || int < 0 || int > 65535) {
+        throw new commander_1.InvalidOptionArgumentError('Must be an integer between 0 and 65535.');
+    }
+    return int;
+}
+function parseHostname(value) {
+    try {
+        new URL(`http://${value}`);
+    }
+    catch {
+        throw new commander_1.InvalidOptionArgumentError('Must be a valid hostname or IP address.');
+    }
+    return value;
+}
+function parseAgentType(value) {
+    const lowerAgentType = value.toLowerCase();
+    if (!agentTypes.includes(lowerAgentType)) {
+        throw new commander_1.InvalidOptionArgumentError(`Must be one of following: ${agentTypes.join(', ')}.`);
+    }
+    return lowerAgentType;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@appweaver/create-weaver-app",
+  "version": "1.0.0",
+  "description": "Appweaver - simple, fast, and reliable web application builder tool (@create-weaver-app)",
+  "author": "Luka Matosevic",
+  "license": "UNLICENSED",
+  "main": "./create-weaver-app.js",
+  "types": "./create-weaver-app.d.ts",
+  "bin": {
+    "create-weaver-app": "./create-weaver-app.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lmatosevic/appweaver.git",
+    "directory": "packages/create-weaver-app"
+  },
+  "maintainers": [
+    {
+      "name": "Luka Matosevic",
+      "email": "lukamatosevic5@gmail.com",
+      "web": "https://lukamatosevic.com"
+    }
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "scripts": {
+    "create-weaver-app": "node ./dist/create-weaver-app.js"
+  },
+  "dependencies": {
+    "commander": "14.0.3",
+    "glob": "13.0.1"
+  }
+}

package/skill/GUIDELINES.md

@@ -0,0 +1,298 @@
+# Appweaver Guidelines
+
+Appweaver is a TypeScript/Node.js library for building web applications. Built on Fastify (HTTP) and Prisma (ORM), it
+provides factory methods for creating resource models, services, policies, and routes with sensible defaults.
+
+## Project structure
+
+- `database/` - migrations, seeders, generated Prisma client
+- `dist/` - transpiled JavaScript output
+- `public/` - static files (if enabled)
+- `src/features/` - application logic (vertical slice architecture)
+- `src/resources/` - resources (models, services, policies, routes)
+- `src/types/` - generated and manual types
+- `src/main.ts` - application entrypoint
+- `test/e2e/` - end-to-end tests
+- `test/unit/` - unit tests
+- `.env` / `.env.{env}` - environment variable overrides (optional)
+- `appweaver.json` / `appweaver.{env}.json` - central configuration
+- `Dockerfile` - Docker image definition
+
+**IMPORTANT:** `{env}` is controlled by `NODE_ENV` evironment variable.
+
+## Application entrypoint
+
+```ts
+// src/main.ts
+import { createApp } from '@appweaver/core';
+import { logger } from '@appweaver/common';
+
+createApp().catch((err) => logger.error(err));
+```
+
+## Creating resources
+
+Resources are the core building blocks. There are four types: **model**, **service**, **routes**, and **policy**.
+Exported resources are loaded automatically on application start.
+
+Dependency chain: **model** → **service** → **routes** → **policy**
+
+Only a model is required. If a service exists, a model must exist. If routes exist, a service must exist. Policy is
+independent.
+
+**DOS:**
+
+- Use default configuration values whenever possible
+- Rely on library defaults for `omit`/`pick`, and `input`/`output` settings
+- Use default `mimeType` and `namePattern` patterns in file configurations unless specifically requested
+- Prefer storing configuration in JSON file (`appweaver.json`) over environment (`.env`) file, but prefer it for secrets
+- Always create all four resource configs (model, service, routes, and policy) unless specified otherwise
+
+**DON'TS:**
+
+- Don't explicitly set default values in configuration unless specifically requested
+- Don't override `omit`/`pick` for `read`, `create` and `update` settings unnecessarily
+- Don't specify `input`/`output` configurations if defaults suffice
+- Don't modify file's `mimeType` and `namePattern` patterns unless specifically instructed
+- Don't customize index arrays without an explicit requirement
+
+### Model
+
+```ts
+// src/resources/product/model.ts
+import { createModel } from '@appweaver/core';
+
+export default createModel({
+  name: 'Product',
+  scalars: {
+    title: { type: 'string', minLength: 1, maxLength: 200 },
+    price: { type: 'float', minimum: 0 },
+    status: { type: 'enum', default: 'Draft', values: ['Draft', 'Active', 'Sold'] },
+    description: { type: 'string', required: false },
+    lastViewedAt: { type: 'dateTime', defaultGenerator: 'now()' },
+    enabled: { type: 'boolean', default: true }
+  },
+  relations: {
+    category: { model: 'Category', mappedBy: 'products', owner: true, output: { type: 'always' } }
+  },
+  files: {
+    photo: { mimeType: 'image/*', maxSize: '2 MB' }
+  },
+  create: { omit: ['status'] },
+  update: { pick: ['title', 'price', 'status', 'description'] },
+  index: ['title']
+});
+```
+
+### Service
+
+```ts
+// src/resources/product/service.ts
+import { createService } from '@appweaver/core';
+
+export default createService({
+  modelName: 'Product',
+  afterCreate: (resource) => {
+    console.log('Product created:', resource.id);
+  },
+  textSearch: {
+    title: { contains: '{input}', mode: 'insensitive' }
+  }
+});
+```
+
+### Routes
+
+```ts
+// src/resources/product/routes.ts
+import { createRoutes } from '@appweaver/core';
+
+export default createRoutes({
+  modelName: 'Product',
+  find: { cache: true, roles: ['Admin', 'User'], rateLimit: { max: 100 } },
+  query: { cacheTTL: 5000 },
+  create: { permissions: ['product:create'] },
+  delete: { exclude: true }
+});
+```
+
+### Policy
+
+```ts
+// src/resources/product/policy.ts
+import { createPolicy } from '@appweaver/core';
+
+export default createPolicy({
+  modelName: 'Product',
+  checkAccess: (action, resource) => resource.status === 'Draft',
+  readRestrictions: (action, resource) => {
+    enabled: true;
+  },
+  files: {
+    photo: { accessType: 'public' }
+  }
+});
+```
+
+### Auth model and service
+
+Use `createAuthModel` and `createAuthService` for authenticatable users. They must be used together.
+
+`createAuthModel` adds: `email`, `passwordHash`, `verifiedEmail`, `twoFactorAuth`, `enabled`, `logoutAt` scalars; a
+virtual `password` field; a `roles` relation; and optional `apiKeys` relation.
+
+```ts
+// src/resources/user/model.ts
+import { createAuthModel } from '@appweaver/core';
+
+export default createAuthModel({
+  name: 'User',
+  scalars: { name: { type: 'string', maxLength: 100 } },
+  files: { avatar: { mimeType: 'image/(png|jpeg|gif)', maxSize: '2 MB' } }
+});
+```
+
+```ts
+// src/resources/user/service.ts
+import { createAuthService } from '@appweaver/core';
+
+export default createAuthService({
+  modelName: 'User',
+  registrationData: (_, email, password) => ({ email, password, roles: [1, 2] })
+});
+```
+
+## Custom routes, models, and plugins
+
+### Custom route
+
+```ts
+// src/features/custom-route.ts
+import { registerRoute, Router } from '@appweaver/core';
+import { Type } from '@sinclair/typebox';
+
+registerRoute(
+  async function (router: Router) {
+    router.get('/search-result', {
+      schema: { summary: 'Search result', response: { 200: Type.Ref('SearchResult') } },
+      handler: async () => ({ message: 'Hello, world!' })
+    });
+  },
+  { public: true, cacheTTL: 15000 }
+);
+```
+
+### Custom model
+
+```ts
+// src/features/custom-model.ts
+import { registerModel } from '@appweaver/core';
+import { Type } from '@sinclair/typebox';
+
+registerModel(
+  Type.Object(
+    { id: Type.Number(), title: Type.String(), score: Type.Number({ minimum: 0, maximum: 1 }) },
+    { $id: 'SearchResult' }
+  )
+);
+```
+
+### Plugin
+
+```ts
+// src/plugins/audit-log.ts
+import { registerPlugin } from '@appweaver/core';
+
+registerPlugin('audit-log', async (server) => {
+  server.addHook('onResponse', async (request, reply) => {
+    console.log(`${request.method} ${request.url} → ${reply.statusCode}`);
+  });
+});
+```
+
+## Dependency injection
+
+```ts
+import { Cache } from '@appweaver/common';
+import { define, inject, loadProvider } from '@appweaver/core';
+
+define(RedisCacheService, Cache);                // register class under abstract token
+define('https://api.example.com', 'ApiBaseUrl'); // register plain value
+
+const cache = inject(Cache);                     // resolve singleton
+const url = inject<string>('ApiBaseUrl');        // resolve by string token
+
+// Dynamic provider loading (typical in main.ts)
+loadProvider(__dirname, config.CACHE_PROVIDER, Cache);
+loadProvider(__dirname, config.MAILER_PROVIDER, Mailer, false); // optional
+```
+
+## Seeders
+
+Seeder files export async functions and run in alphabetical order. Prefix filenames with ordinal numbers.
+
+```ts
+// database/seeders/001-create-admin-user.ts
+import { hashPassword } from '@appweaver/core';
+import { db } from '@db/client';
+
+export async function createAdminUser(): Promise<void> {
+  await db.user.create({
+    data: {
+      firstName: 'Admin',
+      lastName: 'Admin',
+      email: 'admin@appweaver.com',
+      roles: {
+        connectOrCreate: [
+          {
+            where: { name: 'Admin' },
+            create: {
+              name: 'Admin',
+              permissions: {
+                connectOrCreate: [
+                  { where: { name: '*.read' }, create: { name: '*.read' } },
+                  { where: { name: '*.write' }, create: { name: '*.write' } }
+                ]
+              }
+            }
+          }
+        ]
+      }
+    }
+  });
+}
+```
+
+## Common commands
+
+| Command                       | Description                               |
+|-------------------------------|-------------------------------------------|
+| `npm run generate`            | Generate TypeScript types + Prisma schema |
+| `npm run build`               | Build the application                     |
+| `npm run start`               | Start in production mode                  |
+| `npm run dev`                 | Start in development (watch) mode         |
+| `npm run seed`                | Seed the database                         |
+| `npm run migrate`             | Apply pending database migrations         |
+| `npm run test`                | Run unit tests                            |
+| `npm run e2e`                 | Run end-to-end tests                      |
+| `npm run format`              | Format code with Prettier                 |
+| `npm run lint`                | Lint code with ESLint                     |
+| `weaver migration new <name>` | Create a new database migration           |
+| `weaver update`               | Update all @appweaver/* packages          |
+| `weaver openapi`              | Generate OpenAPI specification            |
+
+## References
+
+- Application CLI (weaver): [cli.md](references/cli.md)
+- Application configuration: [configuration.md](references/configuration.md)
+- Application resources: [resources.md](references/resources.md)
+- Dependency injection: [dependency-injection.md](references/dependency-injection.md)
+- Security details: [security.md](references/security.md)
+- Storage & File management: [storage.md](references/storage.md)
+- Database & Migrations: [database.md](references/database.md)
+- Events & Hooks: [events.md](references/events.md)
+- Cache management: [cache.md](references/cache.md)
+- Queue jobs: [queue.md](references/queue.md)
+- Scheduling jobs: [scheduler.md](references/scheduler.md)
+- Sending emails: [mailer.md](references/mailer.md)
+- Generating an HTTP client for using API: [client.md](references/client.md)