@zintrust/core 0.4.17 → 0.4.18

package/README.md

@@ -1,66 +1,11 @@
-# ZinTrust Framework
+# Getting Started with ZinTrust
 
-[![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)
+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.
 
-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
+## Quick Start (2 minutes)
 
 ```bash
-# Install @zintrust/core (ZinTrust CLI) globally
+# Install @zintrust/core (ZinTrust CLI)
 npm install -g @zintrust/core
 
 # Create a new project
@@ -70,240 +15,224 @@ cd my-app
 # Install adapters as needed (example: SQLite)
 zin add db:sqlite
 
-# Start development server
+# Start development
 zin start
 ```
 
-New projects include an `.env` with safe defaults (and the generator will backfill them if missing):
+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`
 
-- `HOST=localhost`
-- `PORT=7777`
-- `LOG_LEVEL=debug`
+The canonical CLI is `zin`. `z` is a shorthand alias.
 
-## Adapters (on-demand installs)
+## Install adapters (database/cache/etc.)
 
-ZinTrust ships a minimal core. Database/cache/etc. integrations are installed explicitly via adapter packages.
+ZinTrust keeps the core package minimal. Integrations like database drivers are installed explicitly via adapter packages.
 
 ```bash
 # Database adapters
-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
+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
 ```
 
-The canonical CLI is `zin`. `z` is a documented shorthand alias.
+## What is ZinTrust?
 
-## Core Package Dependencies (CLI + DX)
+ZinTrust is a **minimal-core** backend framework built on:
 
-The npm package `@zintrust/core` includes a small set of runtime dependencies primarily to power the CLI and developer experience.
+- ✅ **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
 
-- `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
+## Key Features
 
-Some dependencies are used by built-in features/adapters:
+### 🚀 Blazing Fast
 
-- `bcrypt` - password hashing helpers
-- `jsonwebtoken` - JWT token signing/verification utilities
+- Native HTTP server - No framework overhead
+- Type-safe queries with automatic SQL injection prevention
+- Efficient memory management with built-in profiling
 
-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.
+### 🛡️ Secure by Default
 
-## Development
+- No raw SQL - QueryBuilder enforces parameterized queries
+- Automatic CSRF protection
+- JWT token management
+- XSS vulnerability prevention
 
-If you want to contribute to the framework:
+### 📊 Observable
 
-```bash
-# Clone the repository
-git clone https://github.com/ZinTrust/ZinTrust.git
-cd ZinTrust
-
-# Install dependencies
-npm install
-
-# Start development server
-zin start
-
-# Run tests
-npm test
+- Built-in N+1 query detection
+- Memory profiling per request
+- Request tracing across microservices
+- File-based logging system
 
-# Build for production
-npm run build
-```
-
-## Docker Images
-
-ZinTrust now publishes two framework runtime targets from the main Dockerfile:
+### 🔧 Developer Friendly
 
-- `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
+- Modern Active Record ORM
+- Fluent routing API with middleware
+- CLI scaffolding (models, migrations, controllers)
+- Comprehensive testing utilities
 
-Built-in base plugin packages:
+## Installation
 
-- `@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`
+### Prerequisites
 
-Worker image additions:
+- Node.js >= 20.0.0
+- Any npm-compatible package manager (npm, yarn, pnpm, bun)
 
-- `@zintrust/workers`
-- `@zintrust/queue-monitor`
+### From npm (Recommended)
 
-Local smoke commands:
+ZinTrust is distributed on npm as `@zintrust/core`.
 
 ```bash
-npm run docker:build
-npm run docker:build:worker
-npm run docker:smoke
+npm install -g @zintrust/core
+zin new my-app
 ```
 
-## Project Structure
+You can install it with any npm-compatible package manager:
 
-```
-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
-```
+```bash
+# npm
+npm install -g @zintrust/core
 
-## Documentation
+# yarn
+yarn global add @zintrust/core
 
-See [docs/](docs/) for comprehensive guides on:
+# pnpm
+pnpm add -g @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)
+# bun
+bun add -g @zintrust/core
+```
 
-Practical walkthroughs:
+### From source
 
-- [CLI Guide](docs/cli-guide.md)
-- [CLI Reference](docs/cli-reference.md)
-- [Tasks Demo (A–Z)](docs/tasks-demo.md)
+```bash
+git clone https://github.com/ZinTrust /ZinTrust .git
+cd ZinTrust
+npm install
+npm run build
+```
 
-## Import Patterns
+## Create Your First API
 
-Use path aliases for clean, maintainable imports:
+### 1. Define a Model
 
 ```typescript
-// 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';
+// 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',
+  },
+});
+```
 
-// Services & Microservices
-import { MicroserviceBootstrap } from '@microservices/MicroserviceBootstrap';
+### 2. Create a Route
 
-// Application code (app folder)
+```typescript
+// routes/api.ts
+import { Application } from '@zintrust/core';
 import { User } from '@app/Models/User';
-import { UserController } from '@app/Controllers/UserController';
 
-// Serverless
-import { handler } from '@functions/lambda';
-
-// Microservices
-import { usersService } from '@services/ecommerce/users';
+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 });
+  });
+}
 ```
 
-## Architecture
-
-ZinTrust is built on proven architectural patterns for modern backend development:
+### 3. Run Your API
 
-- **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
+```bash
+zin start
+```
 
-## Contributing
+Test it:
 
-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.
+```bash
+# Get all users
+curl http://localhost:7777/api/users
 
-### Quality Assurance
+# Create a user
+curl -X POST http://localhost:7777/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"John","email":"john@example.com"}'
+```
 
-ZinTrust enforces strict quality standards. Before submitting a PR, ensure you run:
+## Next Steps
 
-```bash
-zin qa
-```
+- 📖 [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
 
-This will run linting, type-checking, and tests to ensure your changes meet our standards.
+## Architecture Overview
 
-## Security
+ZinTrust uses a proven layered architecture:
 
-If you discover a security vulnerability within ZinTrust, please see our [Security Policy](SECURITY.md).
+```
+┌─────────────────────────────────┐
+│      HTTP Request/Response      │
+├─────────────────────────────────┤
+│      Router (URL Matching)      │
+├─────────────────────────────────┤
+│    Middleware Pipeline          │
+├─────────────────────────────────┤
+│    Controllers/Handlers         │
+├─────────────────────────────────┤
+│    Service Layer                │
+├─────────────────────────────────┤
+│    ORM Models                   │
+├─────────────────────────────────┤
+│    QueryBuilder (Type-Safe SQL) │
+├─────────────────────────────────┤
+│    Database Adapter             │
+├─────────────────────────────────┤
+│    Native Database Driver       │
+└─────────────────────────────────┘
+```
 
 ## Community & Support
 
-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)
+- 📚 [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)
 
 ## License
 
-MIT
-
----
-
-**Copyright © 2025 ZinTrust Framework. All rights reserved.**
+MIT - See [LICENSE](../LICENSE) for details

package/bin/z.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env -S node --import tsx
+/**
+ * ZinTrust CLI Shortcut - 'z'
+ * Mirrors bin/zintrust.ts for convenience
+ */
+export {};
+//# sourceMappingURL=z.d.ts.map

package/bin/z.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"z.d.ts","sourceRoot":"","sources":["../../bin/z.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/bin/z.js

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

package/bin/zin.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env -S node --import tsx
+/**
+ * ZinTrust CLI Shortcut - 'zin'
+ * Mirrors bin/zintrust.ts for convenience
+ */
+export {};
+//# sourceMappingURL=zin.d.ts.map

package/bin/zin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zin.d.ts","sourceRoot":"","sources":["../../bin/zin.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/bin/zin.js

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

package/bin/zintrust-main.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export declare function run(): Promise<void>;
+export {};
+//# sourceMappingURL=zintrust-main.d.ts.map

package/bin/zintrust-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zintrust-main.d.ts","sourceRoot":"","sources":["../../bin/zintrust-main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuGH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAgFzC;AAED,OAAO,EAAE,CAAC"}