@zintrust/core 0.1.27 → 0.1.28

package/README.md

@@ -1,11 +1,52 @@
-# Getting Started with ZinTrust
+# ZinTrust Framework
 
-Welcome to ZinTrust, a production-grade TypeScript backend framework with proven architectural patterns and a minimal core (no Express/Fastify). The published npm package also includes a few runtime dependencies for the CLI and developer experience.
+[![Website](https://img.shields.io/badge/website-zintrust.com-blue)](https://zintrust.com)
+[![CI/CD Pipeline](https://github.com/ZinTrust/ZinTrust/actions/workflows/ci.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/ci.yml)
+[![SonarQube Analysis](https://github.com/ZinTrust/ZinTrust/actions/workflows/sonarqube.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/sonarqube.yml)
+[![SonarCloud Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=ZinTrust_ZinTrust&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ZinTrust_ZinTrust)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ZinTrust_ZinTrust&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ZinTrust_ZinTrust)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=ZinTrust_ZinTrust&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=ZinTrust_ZinTrust)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=ZinTrust_ZinTrust&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ZinTrust_ZinTrust)
+[![Security Scan](https://github.com/ZinTrust/ZinTrust/actions/workflows/security.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/security.yml)
+[![Known Vulnerabilities](https://snyk.io/test/github/ZinTrust/ZinTrust/badge.svg)](https://snyk.io/test/github/ZinTrust/ZinTrust)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@zintrust/core.svg)](https://www.npmjs.com/package/@zintrust/core)
 
-## Quick Start (2 minutes)
+Production-grade TypeScript backend framework with a “minimal core” (no Express/Fastify) and a batteries-included CLI + developer experience. Visit [zintrust.com](https://zintrust.com) for more information.
+
+## Status
+
+| Check        | Status                                                                                                                                                                                                                                                                                                                                           |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Build**    | [![CI/CD Pipeline](https://github.com/ZinTrust/ZinTrust/actions/workflows/ci.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/ci.yml)                                                                                                                                                                                      |
+| **Quality**  | [![SonarQube Analysis](https://github.com/ZinTrust/ZinTrust/actions/workflows/sonarqube.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/sonarqube.yml)                                                                                                                                                                    |
+| **Security** | [![Security Scan](https://github.com/ZinTrust/ZinTrust/actions/workflows/security.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/security.yml) [![Known Vulnerabilities](https://snyk.io/test/github/ZinTrust/ZinTrust/badge.svg)](https://snyk.io/test/github/ZinTrust/ZinTrust)                                        |
+| **Docker**   | [![Publish Docker Image](https://github.com/ZinTrust/ZinTrust/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/ZinTrust/ZinTrust/actions/workflows/docker-publish.yml) [![Docker Image](https://img.shields.io/badge/image-ghcr.io%2FZinTrust%2FZinTrust-blue)](https://github.com/ZinTrust/ZinTrust/pkgs/container/zintrust) |
+| **Tests**    | ![Tests Passing](https://img.shields.io/badge/tests-passing-brightgreen)                                                                                                                                                                                                                                                                         |
+
+### SonarCloud
+
+- Quality Gate + key measures: [https://sonarcloud.io/summary/new_code?id=ZinTrust_ZinTrust](https://sonarcloud.io/summary/new_code?id=ZinTrust_ZinTrust)
+
+If you want PR-specific “New Code” numbers in GitHub, rely on the SonarCloud PR Check (that’s where `pullRequest=...` links come from); the README badges above intentionally track the project overview so they stay stable.
+
+## Features
+
+✅ **Type-Safe ORM & Query Builder** – No raw SQL, chainable queries
+✅ **Multi-Database Support** – SQLite, PostgreSQL, MySQL, SQL Server via adapters
+✅ **Declarative Routing** – Groups, resources, nested routes
+✅ **Service Container** – Dependency injection out of the box
+✅ **Migrations & Seeding** – Schema versioning, factory-based test data
+✅ **N+1 Detection** – Built-in query optimization monitoring
+✅ **Memory Profiling** – Heap/GC tracking per request
+✅ **SQL Injection Prevention** – Parameterized queries by default
+✅ **Multi-Cloud Ready** – Docker, AWS, Cloudflare Wrangler, Deno
+✅ **Production Quality** – SonarQube integration, 90%+ test coverage
+
+## Quick Start
 
 ```bash
-# Install @zintrust/core (ZinTrust CLI)
+# Install @zintrust/core (ZinTrust CLI) globally
 npm install -g @zintrust/core
 
 # Create a new project
@@ -15,223 +56,201 @@ cd my-app
 # Install adapters as needed (example: SQLite)
 zin add db:sqlite
 
-# Start development
+# Start development server
 zin start
 ```
 
-Your API is now running at `http://localhost:7777`
-
-If you’re targeting a different runtime:
-
-- Cloudflare Workers (Wrangler): `zin start --wg`
-- AWS Lambda adapter mode: `zin start --lambda`
-- Deno adapter mode: `zin start --deno`
+New projects include an `.env` with safe defaults (and the generator will backfill them if missing):
 
-The canonical CLI is `zin`. `z` is a shorthand alias.
+- `HOST=localhost`
+- `PORT=7777`
+- `LOG_LEVEL=debug`
 
-## Install adapters (database/cache/etc.)
+## Adapters (on-demand installs)
 
-ZinTrust keeps the core package minimal. Integrations like database drivers are installed explicitly via adapter packages.
+ZinTrust ships a minimal core. Database/cache/etc. integrations are installed explicitly via adapter packages.
 
 ```bash
 # Database adapters
-zin add db:sqlite    # @zintrust/db-sqlite
-zin add db:postgres  # @zintrust/db-postgres
-zin add db:mysql     # @zintrust/db-mysql
-zin add db:mssql     # @zintrust/db-sqlserver
+zin add db:sqlite    # installs @zintrust/db-sqlite
+zin add db:postgres  # installs @zintrust/db-postgres
+zin add db:mysql     # installs @zintrust/db-mysql
+zin add db:mssql     # installs @zintrust/db-sqlserver
 ```
 
-## What is ZinTrust?
+The canonical CLI is `zin`. `z` is a documented shorthand alias.
 
-ZinTrust is a **minimal-core** backend framework built on:
+## Core Package Dependencies (CLI + DX)
 
-- ✅ **Pure Node.js** - No Express, Fastify, or external HTTP libraries
-- ✅ **Type-Safe** - Strict TypeScript with 100% type coverage
-- ✅ **Microservices** - Built-in service discovery and orchestration
-- ✅ **Production Ready** - Used in high-traffic applications
+The npm package `@zintrust/core` includes a small set of runtime dependencies primarily to power the CLI and developer experience.
 
-## Key Features
+- `commander` - command parsing and `--help` UX for the `zin` CLI
+- `inquirer` - interactive prompts (project scaffolding, generators)
+- `chalk` - terminal colors for readable CLI output
+- `tsx` - runs TypeScript-based CLI entrypoints without requiring a separate build step during development
 
-### 🚀 Blazing Fast
+Some dependencies are used by built-in features/adapters:
 
-- Native HTTP server - No framework overhead
-- Type-safe queries with automatic SQL injection prevention
-- Efficient memory management with built-in profiling
+- `bcrypt` - password hashing helpers
+- `jsonwebtoken` - JWT token signing/verification utilities
 
-### 🛡️ Secure by Default
+Database drivers are provided by adapter packages (for example, `@zintrust/db-sqlite` depends on `better-sqlite3`).
+Note: native modules like `better-sqlite3` may require build tools on certain platforms.
 
-- No raw SQL - QueryBuilder enforces parameterized queries
-- Automatic CSRF protection
-- JWT token management
-- XSS vulnerability prevention
+## Development
 
-### 📊 Observable
+If you want to contribute to the framework:
 
-- Built-in N+1 query detection
-- Memory profiling per request
-- Request tracing across microservices
-- File-based logging system
-
-### 🔧 Developer Friendly
-
-- Modern Active Record ORM
-- Fluent routing API with middleware
-- CLI scaffolding (models, migrations, controllers)
-- Comprehensive testing utilities
+```bash
+# Clone the repository
+git clone https://github.com/ZinTrust/ZinTrust.git
+cd ZinTrust
 
-## Installation
+# Install dependencies
+npm install
 
-### Prerequisites
+# Start development server
+zin start
 
-- Node.js >= 20.0.0
-- Any npm-compatible package manager (npm, yarn, pnpm, bun)
+# Run tests
+npm test
 
-### From npm (Recommended)
+# Build for production
+npm run build
+```
 
-ZinTrust is distributed on npm as `@zintrust/core`.
+## Project Structure
 
-```bash
-npm install -g @zintrust/core
-zin new my-app
+```
+zintrust/
+├── app/                    # Application code (Controllers, Models, Middleware)
+├── bin/                    # CLI tools and commands
+├── packages/                # Optional adapter packages (cache/db/mail/queue/storage)
+├── routes/                 # Route definitions
+├── services/                # Example microservices (ecommerce)
+├── src/                    # Framework & services
+│   ├── config/             # Centralized configuration (env, app, database, security, etc.)
+│   ├── database/           # Migrations, seeders, factories
+│   ├── functions/          # Serverless handlers (Lambda, Deno, Cloudflare)
+│   ├── orm/                # Object-Relational Mapping
+│   ├── routing/            # Routing engine
+│   ├── middleware/         # Middleware system
+│   ├── container/          # Service container (DI)
+│   ├── http/               # Request/Response handlers
+│   ├── microservices/      # Microservices framework
+│   ├── security/           # Security utilities
+│   ├── validation/         # Input validation
+│   ├── profiling/          # Performance profiling
+│   └── deployment/         # Cloud adapters (AWS, Cloudflare, Deno)
+├── tests/                  # Test files
+│   ├── unit/               # Unit tests
+│   └── integration/        # Integration tests
+├── docs/                   # Public documentation
+├── docs-website/            # Docs site build output/tools
+└── md/                     # Internal documentation
 ```
 
-You can install it with any npm-compatible package manager:
+## Documentation
 
-```bash
-# npm
-npm install -g @zintrust/core
+See [docs/](docs/) for comprehensive guides on:
 
-# yarn
-yarn global add @zintrust/core
+- [Getting Started](docs/getting-started.md)
+- [Models & ORM](docs/models.md)
+- [Advanced ORM Relationships](docs/orm-advanced-relationships.md)
+- [Query Builder](docs/query-builder.md)
+- [Routing](docs/routing.md)
+- [Middleware](docs/middleware.md)
+- [Testing](docs/testing.md)
+- [Deployment](docs/deployment.md)
 
-# pnpm
-pnpm add -g @zintrust/core
+Practical walkthroughs:
 
-# bun
-bun add -g @zintrust/core
-```
+- [CLI Guide](docs/cli-guide.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Tasks Demo (A–Z)](docs/tasks-demo.md)
 
-### From source
+## Import Patterns
 
-```bash
-git clone https://github.com/ZinTrust /ZinTrust .git
-cd ZinTrust
-npm install
-npm run build
-```
+Use path aliases for clean, maintainable imports:
+
+```typescript
+// Configuration
+import { appConfig } from '@config/app';
+import { databaseConfig } from '@config/database';
+import { securityConfig } from '@config/security';
 
-## Create Your First API
+// ORM & Database
+import { Model } from '@orm/Model';
+import { Database } from '@orm/Database';
 
-### 1. Define a Model
+// Routing
+import { Router } from '@routing/Router';
 
-```typescript
-// app/Models/User.ts
-import { Model } from '@zintrust/core';
-
-export const User = Model.define({
-  table: 'users',
-  fillable: ['name', 'email', 'password'],
-  hidden: ['password'],
-  timestamps: true,
-  casts: {
-    is_admin: 'boolean',
-  },
-});
-```
+// HTTP
+import { Request } from '@http/Request';
+import { Response } from '@http/Response';
 
-### 2. Create a Route
+// Services & Microservices
+import { MicroserviceBootstrap } from '@microservices/MicroserviceBootstrap';
 
-```typescript
-// routes/api.ts
-import { Application } from '@zintrust/core';
+// Application code (app folder)
 import { User } from '@app/Models/User';
+import { UserController } from '@app/Controllers/UserController';
 
-export function registerRoutes(app: Application): void {
-  const router = app.getRouter();
-
-  // Get all users
-  router.get('/api/users', async (req, res) => {
-    const users = await User.all();
-    res.json({ data: users });
-  });
-
-  // Get user by ID
-  router.get('/api/users/:id', async (req, res) => {
-    const user = await User.find(req.getParam('id'));
-    if (!user) {
-      return res.setStatus(404).json({ error: 'User not found' });
-    }
-    res.json({ data: user });
-  });
-
-  // Create user
-  router.post('/api/users', async (req, res) => {
-    const user = await User.create(req.getBody());
-    res.setStatus(201).json({ data: user });
-  });
-}
-```
-
-### 3. Run Your API
+// Serverless
+import { handler } from '@functions/lambda';
 
-```bash
-zin start
+// Microservices
+import { usersService } from '@services/ecommerce/users';
 ```
 
-Test it:
+## Architecture
 
-```bash
-# Get all users
-curl http://localhost:7777/api/users
+ZinTrust is built on proven architectural patterns for modern backend development:
 
-# Create a user
-curl -X POST http://localhost:7777/api/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"John","email":"john@example.com"}'
-```
+- **Models first**: Define your data schema with explicit models
+- **Type safety**: Full TypeScript with strict mode enabled
+- **Testing focus**: Vitest integration with fast, isolated tests
+- **Performance by default**: N+1 detection, memory profiling built-in
+- **Minimal core**: Core HTTP/routing logic avoids external web frameworks; the published package still includes CLI/DX dependencies listed above
 
-## Next Steps
+## Contributing
 
-- 📖 [Models & ORM](https://zintrust.com/doc/models) - Database patterns and relationships
-- 🛣️ [Routing](https://zintrust.com/doc/routing) - HTTP routing and middleware
-- 🏗️ [Microservices](https://zintrust.com/doc/microservices) - Build distributed systems
-- ⚙️ [CLI Commands](https://zintrust.com/doc/cli-reference) - Code generation and management
-- 📝 [API Reference](https://zintrust.com/doc/api-reference) - Complete API documentation
+We welcome contributions! Please see our **[Contributor & QA Guide](docs/contributing.md)** for details on our code of conduct, and the process for submitting pull requests.
 
-## Architecture Overview
+### Quality Assurance
 
-ZinTrust uses a proven layered architecture:
+ZinTrust enforces strict quality standards. Before submitting a PR, ensure you run:
 
-```
-┌─────────────────────────────────┐
-│      HTTP Request/Response      │
-├─────────────────────────────────┤
-│      Router (URL Matching)      │
-├─────────────────────────────────┤
-│    Middleware Pipeline          │
-├─────────────────────────────────┤
-│    Controllers/Handlers         │
-├─────────────────────────────────┤
-│    Service Layer                │
-├─────────────────────────────────┤
-│    ORM Models                   │
-├─────────────────────────────────┤
-│    QueryBuilder (Type-Safe SQL) │
-├─────────────────────────────────┤
-│    Database Adapter             │
-├─────────────────────────────────┤
-│    Native Database Driver       │
-└─────────────────────────────────┘
+```bash
+zin qa
 ```
 
+This will run linting, type-checking, and tests to ensure your changes meet our standards.
+
+## Security
+
+If you discover a security vulnerability within ZinTrust, please see our [Security Policy](SECURITY.md).
+
 ## Community & Support
 
-- 📚 [Documentation](https://zintrust.com)
-- 💬 [Discord Community](https://discord.gg/zintrust)
-- 🐦 [Follow on X](https://x.com/zintrust)
-- 🐛 [Issue Tracker](https://github.com/ZinTrust /ZinTrust /issues)
-- 🤝 [Contributing Guide](./contributing.md)
+Join our community and stay updated:
+
+- **Website**: [zintrust.com](https://zintrust.com)
+- **X (Twitter)**: [@zintrust](https://x.com/zintrust)
+- **Discord**: [Join our server](https://discord.gg/zintrust)
+- **Slack**: [Join our workspace](https://slack.zintrust.com)
+- **Reddit**: [r/zintrust](https://reddit.com/r/zintrust)
+- **Dev.to**: [zintrust](https://dev.to/zintrust)
+- **Medium**: [@zintrust](https://medium.com/@zintrust)
+- **Stack Overflow**: [zintrust](https://stackoverflow.com/users/32073668/zintrust)
+- **LinkedIn**: [ZinTrust](https://linkedin.com/company/zintrustjs)
+- **YouTube**: [@zintrust](https://youtube.com/@zintrust)
 
 ## License
 
-MIT - See [LICENSE](../LICENSE) for details
+MIT
+
+---
+
+**Copyright © 2025 ZinTrust Framework. All rights reserved.**

package/bin/z.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S node --import tsx
+
+/**
+ * ZinTrust CLI Shortcut - 'z'
+ * Mirrors bin/zintrust.ts for convenience
+ */
+
+import { run } from './zintrust-main.js';
+
+await run();

package/bin/zin.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S node --import tsx
+
+/**
+ * ZinTrust CLI Shortcut - 'zin'
+ * Mirrors bin/zintrust.ts for convenience
+ */
+
+import { run } from './zintrust-main';
+
+await run();

package/bin/zintrust-main.ts

@@ -0,0 +1,130 @@
+/**
+ * ZinTrust CLI - Main Entry Point (hashbang-free)
+ *
+ * This module contains the CLI implementation without a hashbang so that it can
+ * be imported by other bin shortcuts (zin/z/zt) without parse errors.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const loadPackageVersionFast = (): string => {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packagePath = path.join(here, '../package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8')) as { version?: string };
+    return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+};
+
+const stripLeadingScriptArg = (rawArgs: string[]): string[] => {
+  if (rawArgs.length === 0) return rawArgs;
+  const first = rawArgs[0];
+  const looksLikeScript =
+    typeof first === 'string' && (first.endsWith('.ts') || first.endsWith('.js'));
+  return looksLikeScript ? rawArgs.slice(1) : rawArgs;
+};
+
+const getArgsFromProcess = (): { rawArgs: string[]; args: string[] } => {
+  const rawArgs = process.argv.slice(2);
+  return { rawArgs, args: stripLeadingScriptArg(rawArgs) };
+};
+
+const isVersionRequest = (args: string[]): boolean => {
+  return args.includes('-v') || args.includes('--version');
+};
+
+const printFancyVersion = (version: string): void => {
+  const framework = 'ZinTrust Framework';
+  const bannerWidth = 46;
+  const env = (process.env['NODE_ENV'] ?? 'development').toString();
+  const db = (process.env['DB_CONNECTION'] ?? 'sqlite').toString();
+
+  // Keep this dependency-free and fast; version flags should return instantly.
+  // (No logger, no config boot, no CLI registration.)
+
+  console.log('┌' + '─'.repeat(bannerWidth) + '┐');
+
+  console.log(`│ Framework: ${framework.padEnd(bannerWidth - 11)}│`);
+
+  console.log(`│ Version:   ${version.padEnd(bannerWidth - 11)}│`);
+
+  console.log(`│ Env:       ${env.padEnd(bannerWidth - 11)}│`);
+
+  console.log(`│ Database:  ${db.padEnd(bannerWidth - 11)}│`);
+
+  console.log('└' + '─'.repeat(bannerWidth) + '┘');
+
+  console.log();
+};
+
+const shouldDebugArgs = (rawArgs: string[]): boolean => {
+  return process.env['ZINTRUST_CLI_DEBUG_ARGS'] === '1' && rawArgs.includes('--verbose');
+};
+
+const handleCliFatal = async (error: unknown, context: string): Promise<never> => {
+  try {
+    const { Logger } = await import('@config/logger');
+    Logger.error(context, error);
+  } catch {
+    // best-effort logging
+  }
+
+  try {
+    const { ErrorHandler } = await import('@cli/ErrorHandler');
+    ErrorHandler.handle(error as Error);
+  } catch {
+    // best-effort error handling
+  }
+
+  process.exit(1);
+};
+
+export async function run(): Promise<void> {
+  try {
+    // Fast path: print version and exit without bootstrapping the CLI.
+    // This keeps `zin -v` / `zin --version` snappy and avoids any debug output.
+    const { rawArgs: _rawArgs0, args: args0 } = getArgsFromProcess();
+    if (isVersionRequest(args0)) {
+      printFancyVersion(loadPackageVersionFast());
+      return;
+    }
+
+    const { EnvFileLoader } = await import('@cli/utils/EnvFileLoader');
+    EnvFileLoader.ensureLoaded();
+
+    // Ensure project-installed adapters/drivers are registered for CLI commands.
+    // (This is driven by src/zintrust.plugins.ts generated by `zin plugin install`.)
+    try {
+      const { PluginAutoImports } = await import('@runtime/PluginAutoImports');
+      await PluginAutoImports.tryImportProjectAutoImports();
+    } catch {
+      // best-effort; CLI should still run even if plugins file is missing
+    }
+
+    const { CLI } = await import('@cli/CLI');
+
+    const cli = CLI.create();
+
+    // When executing via tsx (e.g. `npx tsx bin/zin.ts ...`), the script path can
+    // appear as the first element of `process.argv.slice(2)`. Commander expects
+    // args to start at the command name, so we strip a leading script path if present.
+    const { rawArgs, args } = getArgsFromProcess();
+    if (shouldDebugArgs(rawArgs)) {
+      try {
+        process.stderr.write(`[zintrust-cli] process.argv=${JSON.stringify(process.argv)}\n`);
+        process.stderr.write(`[zintrust-cli] rawArgs=${JSON.stringify(rawArgs)}\n`);
+      } catch {
+        // ignore
+      }
+    }
+    await cli.run(args);
+  } catch (error) {
+    await handleCliFatal(error, 'CLI execution failed');
+  }
+}
+
+export {};