@zintrust/core 0.4.15 → 0.4.17

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ZinTrust
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,66 @@
-# 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.
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=dev&repo=ZinTrust/zintrust)
+
+## ⚡ Instant Development Environment
+
+Click the **"Open in GitHub Codespaces"** button above to launch a pre-configured sandbox.
+
+### Sandbox Details:
+
+- **Repository:** [ZinTrust/zintrust](https://github.com/ZinTrust/zintrust)
+- **Automatic Setup:** Uses `docker.io/zintrust/zintrust:latest`
+- **Active Port:** `7772` (The API will open automatically in your browser)
+- **Start Command:** `node --experimental-specifier-resolution=node dist/src/boot/bootstrap.js`
+
+## 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
+✅ **Edge Compatible** – Run API on Cloudflare Workers, process jobs on Node.js
+✅ **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,224 +70,240 @@ 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`
-- Cloudflare Containers proxy (Wrangler + Docker): `zin init:containers-proxy` then `zin docker -e staging`
-- 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
+```bash
+# Clone the repository
+git clone https://github.com/ZinTrust/ZinTrust.git
+cd ZinTrust
 
-### 🔧 Developer Friendly
+# Install dependencies
+npm install
 
-- Modern Active Record ORM
-- Fluent routing API with middleware
-- CLI scaffolding (models, migrations, controllers)
-- Comprehensive testing utilities
+# Start development server
+zin start
 
-## Installation
+# Run tests
+npm test
 
-### Prerequisites
+# Build for production
+npm run build
+```
 
-- Node.js >= 20.0.0
-- Any npm-compatible package manager (npm, yarn, pnpm, bun)
+## Docker Images
 
-### From npm (Recommended)
+ZinTrust now publishes two framework runtime targets from the main Dockerfile:
 
-ZinTrust is distributed on npm as `@zintrust/core`.
+- `zintrust/zintrust`: base runtime image with official built-in plugin registrations preloaded by default
+- `zintrust/zintrust-worker`: dedicated worker runtime image that starts the worker CLI entrypoint by default
 
-```bash
-npm install -g @zintrust/core
-zin new my-app
-```
+Built-in base plugin packages:
 
-You can install it with any npm-compatible package manager:
+- `@zintrust/db-postgres`
+- `@zintrust/db-mysql`
+- `@zintrust/db-sqlserver`
+- `@zintrust/db-sqlite`
+- `@zintrust/queue-redis`
+- `@zintrust/queue-rabbitmq`
+- `@zintrust/queue-sqs`
+- `@zintrust/cache-redis`
+- `@zintrust/cache-mongodb`
+- `@zintrust/mail-nodemailer`
+- `@zintrust/mail-smtp`
+- `@zintrust/mail-sendgrid`
+- `@zintrust/mail-mailgun`
+- `@zintrust/storage-s3`
+- `@zintrust/storage-r2`
+- `@zintrust/storage-gcs`
 
-```bash
-# npm
-npm install -g @zintrust/core
+Worker image additions:
 
-# yarn
-yarn global add @zintrust/core
+- `@zintrust/workers`
+- `@zintrust/queue-monitor`
 
-# pnpm
-pnpm add -g @zintrust/core
+Local smoke commands:
 
-# bun
-bun add -g @zintrust/core
+```bash
+npm run docker:build
+npm run docker:build:worker
+npm run docker:smoke
 ```
 
-### From source
+## Project Structure
 
-```bash
-git clone https://github.com/ZinTrust /ZinTrust .git
-cd ZinTrust
-npm install
-npm run build
+```
+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
 ```
 
-## Create Your First API
+## Documentation
 
-### 1. Define a Model
+See [docs/](docs/) for comprehensive guides on:
 
-```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',
-  },
-});
-```
+- [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)
+
+Practical walkthroughs:
 
-### 2. Create a Route
+- [CLI Guide](docs/cli-guide.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Tasks Demo (A–Z)](docs/tasks-demo.md)
+
+## Import Patterns
+
+Use path aliases for clean, maintainable imports:
 
 ```typescript
-// routes/api.ts
-import { Application } from '@zintrust/core';
-import { User } from '@app/Models/User';
+// Configuration
+import { appConfig } from '@config/app';
+import { databaseConfig } from '@config/database';
+import { securityConfig } from '@config/security';
 
-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 });
-  });
-}
-```
+// ORM & Database
+import { Model } from '@orm/Model';
+import { Database } from '@orm/Database';
 
-### 3. Run Your API
+// Routing
+import { Router } from '@routing/Router';
 
-```bash
-zin start
-```
+// HTTP
+import { Request } from '@http/Request';
+import { Response } from '@http/Response';
 
-Test it:
+// Services & Microservices
+import { MicroserviceBootstrap } from '@microservices/MicroserviceBootstrap';
 
-```bash
-# Get all users
-curl http://localhost:7777/api/users
+// Application code (app folder)
+import { User } from '@app/Models/User';
+import { UserController } from '@app/Controllers/UserController';
 
-# Create a user
-curl -X POST http://localhost:7777/api/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"John","email":"john@example.com"}'
+// Serverless
+import { handler } from '@functions/lambda';
+
+// Microservices
+import { usersService } from '@services/ecommerce/users';
 ```
 
-## Next Steps
+## Architecture
 
-- 📖 [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
+ZinTrust is built on proven architectural patterns for modern backend development:
 
-## Architecture Overview
+- **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
 
-ZinTrust uses a proven layered architecture:
+## Contributing
 
+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.
+
+### Quality Assurance
+
+ZinTrust enforces strict quality standards. Before submitting a PR, ensure you run:
+
+```bash
+zin qa
 ```
-┌─────────────────────────────────┐
-│      HTTP Request/Response      │
-├─────────────────────────────────┤
-│      Router (URL Matching)      │
-├─────────────────────────────────┤
-│    Middleware Pipeline          │
-├─────────────────────────────────┤
-│    Controllers/Handlers         │
-├─────────────────────────────────┤
-│    Service Layer                │
-├─────────────────────────────────┤
-│    ORM Models                   │
-├─────────────────────────────────┤
-│    QueryBuilder (Type-Safe SQL) │
-├─────────────────────────────────┤
-│    Database Adapter             │
-├─────────────────────────────────┤
-│    Native Database Driver       │
-└─────────────────────────────────┘
-```
+
+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();