@zintrust/core 3.5.0 → 3.5.1

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,50 @@
-# 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)
+[![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)                                                                                                                                                                                      |
+| **Tests**    | ![Tests Passing](https://img.shields.io/badge/tests-passing-brightgreen)                                                                                                                                                                                                                                                                         |
+
+## 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** – 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,28 +54,17 @@ 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`
-
-Fresh projects also include a default flat ESLint setup through `@zintrust/governance/eslint`, so `npm run lint` works immediately after scaffolding.
-
-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`
 
-## Reuse The Stock Bootstrap
-
-If your project needs a `src/boot/bootstrap.ts` entry for Docker, Node, or custom startup layout, you do not need to copy the full ZinTrust bootstrap implementation into your app.
-
-Use a thin bootstrap file that delegates to the published core boot entrypoint:
+If you need a project-local Node/Docker bootstrap file, reuse the stock core bootstrap instead of copying the full framework bootstrap into your app:
 
 ```typescript
 // src/boot/bootstrap.ts
@@ -45,213 +73,255 @@ import '@zintrust/core/boot';
 export {};
 ```
 
-In Node mode, `@zintrust/core/boot` now loads the project env files before it hands off to the stock bootstrap lifecycle, using the same env-file parsing semantics as the CLI startup path.
-
-Use a full custom bootstrap only when you intentionally need behavior different from the stock ZinTrust bootstrap. If you replace it completely, you are also responsible for running any worker startup lifecycle that your app depends on.
-
-## 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 free-form SQL - QueryBuilder enforces safe identifiers + parameterized values (see [Query Builder](./query-builder.md) for exists, joins, groupBy, latestPer)
-- 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/queue-cloudflare`
+- `@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/orm';
+- [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)
 
-export const User = Model.define({
-  table: 'users',
-  fillable: ['name', 'email', 'password'],
-  hidden: ['password'],
-  timestamps: true,
-  casts: {
-    is_admin: 'boolean',
-  },
-});
-```
+Practical walkthroughs:
+
+- [CLI Guide](docs/cli-guide.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Tasks Demo (A–Z)](docs/tasks-demo.md)
 
-### 2. Create a Route
+## Import Patterns
+
+Use path aliases for clean, maintainable imports:
 
 ```typescript
-// routes/api.ts
-import { Application } from '@zintrust/core';
+// Configuration
+import { appConfig } from '@config/app';
+import { databaseConfig } from '@config/database';
+import { securityConfig } from '@config/security';
+
+// ORM & Database
+import { Model } from '@orm/Model';
+import { Database } from '@orm/Database';
+
+// Routing
+import { Router } from '@routing/Router';
+
+// HTTP
+import { Request } from '@http/Request';
+import { Response } from '@http/Response';
+
+// Services & Microservices
+import { MicroserviceBootstrap } from '@microservices/MicroserviceBootstrap';
+
+// 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 });
-  });
-}
+// Serverless
+import { handler } from '@functions/lambda';
+
+// Microservices
+import { usersService } from '@services/ecommerce/users';
 ```
 
-### 3. Run Your API
+### Bundle-Optimized Imports
 
-```bash
-zin start
-```
+For production builds, import only what you need from `@zintrust/core` subpaths to reduce bundle size:
 
-Test it:
+```typescript
+// Cloudflare runtime helpers (Workers-specific)
+import { Cloudflare } from '@zintrust/core/cloudflare';
 
-```bash
-# Get all users
-curl http://localhost:7777/api/users
+// HTTP headers and MIME types
+import { HTTP_HEADERS, MIME_TYPES } from '@zintrust/core/constants';
+
+// Microservice management (optional, not all projects need this)
+import { MicroserviceManager } from '@zintrust/core/microservices';
+
+// Runtime-only entrypoint (excludes CLI, seeders, test helpers)
+import { ProjectRuntime } from '@zintrust/core/runtime';
 
-# Create a user
-curl -X POST http://localhost:7777/api/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"John","email":"john@example.com"}'
+// Other available subpaths
+import { Model } from '@zintrust/core/orm';
+import { Auth } from '@zintrust/core/auth';
+import { RedisKeyManager } from '@zintrust/core/redis';
+import { JwtManager, JwtSessions } from '@zintrust/core/security';
 ```
 
-## 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.**