@zintrust/core 0.1.28 → 0.1.30

package/README.md

@@ -1,52 +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.
-
-## 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
+## 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
@@ -56,201 +15,223 @@ 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`
+- 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
+- Built-in N+1 query detection
+- Memory profiling per request
+- Request tracing across microservices
+- File-based logging system
 
-# Install dependencies
-npm install
+### 🔧 Developer Friendly
 
-# Start development server
-zin start
+- Modern Active Record ORM
+- Fluent routing API with middleware
+- CLI scaffolding (models, migrations, controllers)
+- Comprehensive testing utilities
 
-# Run tests
-npm test
+## Installation
 
-# Build for production
-npm run build
-```
+### Prerequisites
 
-## Project Structure
+- Node.js >= 20.0.0
+- Any npm-compatible package manager (npm, yarn, pnpm, bun)
 
-```
-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
-```
+### From npm (Recommended)
 
-## Documentation
+ZinTrust is distributed on npm as `@zintrust/core`.
 
-See [docs/](docs/) for comprehensive guides on:
+```bash
+npm install -g @zintrust/core
+zin new my-app
+```
 
-- [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)
+You can install it with any npm-compatible package manager:
 
-Practical walkthroughs:
+```bash
+# npm
+npm install -g @zintrust/core
 
-- [CLI Guide](docs/cli-guide.md)
-- [CLI Reference](docs/cli-reference.md)
-- [Tasks Demo (A–Z)](docs/tasks-demo.md)
+# yarn
+yarn global add @zintrust/core
 
-## Import Patterns
+# pnpm
+pnpm add -g @zintrust/core
 
-Use path aliases for clean, maintainable imports:
+# bun
+bun add -g @zintrust/core
+```
 
-```typescript
-// Configuration
-import { appConfig } from '@config/app';
-import { databaseConfig } from '@config/database';
-import { securityConfig } from '@config/security';
+### From source
+
+```bash
+git clone https://github.com/ZinTrust /ZinTrust .git
+cd ZinTrust
+npm install
+npm run build
+```
 
-// ORM & Database
-import { Model } from '@orm/Model';
-import { Database } from '@orm/Database';
+## Create Your First API
 
-// Routing
-import { Router } from '@routing/Router';
+### 1. Define a Model
 
-// HTTP
-import { Request } from '@http/Request';
-import { Response } from '@http/Response';
+```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',
+  },
+});
+```
 
-// 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;AAgFH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA0CzC;AAED,OAAO,EAAE,CAAC"}

package/bin/zintrust-main.js

@@ -0,0 +1,110 @@
+/**
+ * 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 = () => {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const packagePath = path.join(here, '../package.json');
+        const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+const stripLeadingScriptArg = (rawArgs) => {
+    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 = () => {
+    const rawArgs = process.argv.slice(2);
+    return { rawArgs, args: stripLeadingScriptArg(rawArgs) };
+};
+const isVersionRequest = (args) => {
+    return args.includes('-v') || args.includes('--version');
+};
+const printFancyVersion = (version) => {
+    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) => {
+    return process.env['ZINTRUST_CLI_DEBUG_ARGS'] === '1' && rawArgs.includes('--verbose');
+};
+const handleCliFatal = async (error, context) => {
+    try {
+        const { Logger } = await import('../src/config/logger.js');
+        Logger.error(context, error);
+    }
+    catch {
+        // best-effort logging
+    }
+    try {
+        const { ErrorHandler } = await import('../src/cli/ErrorHandler.js');
+        ErrorHandler.handle(error);
+    }
+    catch {
+        // best-effort error handling
+    }
+    process.exit(1);
+};
+export async function run() {
+    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('../src/cli/utils/EnvFileLoader.js');
+        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('../src/runtime/PluginAutoImports.js');
+            await PluginAutoImports.tryImportProjectAutoImports();
+        }
+        catch {
+            // best-effort; CLI should still run even if plugins file is missing
+        }
+        const { CLI } = await import('../src/cli/CLI.js');
+        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');
+    }
+}

package/bin/zintrust-microservices.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * ZinTrust Microservices CLI
+ * Commands for generating, bundling, and managing microservices
+ */
+export {};
+//# sourceMappingURL=zintrust-microservices.d.ts.map

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

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