@venizia/ignis-docs 0.0.6-2 → 0.0.7-0

package/wiki/best-practices/code-style-standards/constants-configuration.md

@@ -210,7 +210,7 @@ export class EnvironmentKeys {
 
 **Usage:**
 ```typescript
-import { applicationEnvironment } from '@venizia/ignis';
+import { applicationEnvironment } from '@venizia/ignis-helpers';
 import { EnvironmentKeys } from '@/common/environments';
 
 // Correct usage

package/wiki/best-practices/code-style-standards/control-flow.md

@@ -123,7 +123,7 @@ Use the `getError` helper and `HTTP` constants to throw consistent, formatted ex
 ### Basic Error
 
 ```typescript
-import { getError, HTTP } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
 
 if (!record) {
   throw getError({

package/wiki/best-practices/code-style-standards/function-patterns.md

@@ -125,7 +125,7 @@ async syncData() {
 **With the helper utility:**
 
 ```typescript
-import { executeWithPerformanceMeasure } from '@venizia/ignis';
+import { executeWithPerformanceMeasure } from '@venizia/ignis-helpers';
 
 await executeWithPerformanceMeasure({
   logger: this.logger.for('syncData'),

package/wiki/best-practices/common-pitfalls.md

@@ -66,7 +66,7 @@ export class Application extends BaseApplication {
 
 -   **Bad:**
     ```typescript
-    import { ApplicationError, getError } from '@venizia/ignis';
+    import { ApplicationError, getError } from '@venizia/ignis-helpers';
 
     // In a Controller
     async createUser(c: Context) {

package/wiki/best-practices/data-modeling.md

@@ -375,7 +375,39 @@ export class User extends BaseEntity<typeof User.schema> {
 
 > **Reference:** See [Hidden Properties](../references/base/models.md#hidden-properties) for complete documentation.
 
-## 6. Database Migrations
+## 6. Authorization Settings
+
+Declare your model's authorization principal in `@model` settings to make the model the single source of truth for permission subjects:
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    authorize: { principal: 'user' },
+    hiddenProperties: ['password'],
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    email: text('email').notNull(),
+    password: text('password'),
+  });
+}
+
+// User.AUTHORIZATION_SUBJECT === 'user' (auto-populated)
+```
+
+**Key points:**
+
+- `AUTHORIZATION_SUBJECT` is auto-set from `authorize.principal` by the `@model` decorator
+- Use `Model.AUTHORIZATION_SUBJECT` in route configs instead of hardcoded strings
+- Explicit `static AUTHORIZATION_SUBJECT = '...'` on the class takes precedence
+- The `authorize` settings are extensible via index signature for custom metadata
+
+> **Reference:** See [Model-Based Resource References](../references/components/authorization/usage#model-based-resource-references) for full authorization integration.
+
+## 7. Database Migrations
 
 Drizzle Kit handles schema migrations. Follow these best practices for safe migrations.
 

package/wiki/best-practices/error-handling.md

@@ -16,7 +16,7 @@ Comprehensive guide to handling errors gracefully in Ignis applications.
 Ignis provides `getError` for creating consistent, structured errors.
 
 ```typescript
-import { getError, HTTP } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
 
 // Basic error
 throw getError({
@@ -68,7 +68,8 @@ Database constraint violations (unique, foreign key, not null, check) are automa
 ### Service Layer Errors
 
 ```typescript
-import { BaseService, getError, HTTP } from '@venizia/ignis';
+import { BaseService } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
 
 export class UserService extends BaseService {
   async createUser(data: TCreateUserRequest): Promise<TUser> {
@@ -160,7 +161,8 @@ Database constraint violations (unique, foreign key, not null, check) are **auto
 You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
 
 ```typescript
-import { BaseRepository, getError, HTTP } from '@venizia/ignis';
+import { BaseRepository } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
 
 export class UserRepository extends BaseRepository<typeof User.schema> {
   async createWithCustomError(data: TCreateUser): Promise<TCreateResult<TUser>> {
@@ -185,7 +187,8 @@ export class UserRepository extends BaseRepository<typeof User.schema> {
 Ignis includes a built-in error handler. Customize behavior in your application:
 
 ```typescript
-import { BaseApplication, ApplicationError } from '@venizia/ignis';
+import { BaseApplication } from '@venizia/ignis';
+import { ApplicationError } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
   override setupMiddlewares(): void {

package/wiki/best-practices/performance-optimization.md

@@ -7,7 +7,7 @@ Optimize your Ignis application for speed and scalability.
 Identify bottlenecks before optimizing:
 
 ```typescript
-import { executeWithPerformanceMeasure } from '@venizia/ignis';
+import { executeWithPerformanceMeasure } from '@venizia/ignis-helpers';
 
 await executeWithPerformanceMeasure({
   logger: this.logger,

package/wiki/best-practices/security-guidelines.md

@@ -72,7 +72,8 @@ const SecureRoute = {
 
 **Access user in protected routes:**
 ```typescript
-import { Authentication, IJWTTokenPayload, ApplicationError, getError } from '@venizia/ignis';
+import { Authentication, IJWTTokenPayload } from '@venizia/ignis';
+import { ApplicationError, getError } from '@venizia/ignis-helpers';
 
 const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
 if (!user.roles.includes('admin')) {
@@ -132,7 +133,7 @@ When handling file uploads, prevent **path traversal attacks** and ensure safe f
 **Solution:** Use `sanitizeFilename()` to strip dangerous patterns:
 
 ```typescript
-import { sanitizeFilename } from '@venizia/ignis';
+import { sanitizeFilename } from '@venizia/ignis-helpers';
 
 // ❌ DANGEROUS - User-controlled filename
 const unsafeFilename = req.body.filename; // Could be "../../../etc/passwd"
@@ -154,7 +155,7 @@ fs.writeFileSync(`./uploads/${safeFilename}`, data);
 Use `createContentDispositionHeader()` for secure download responses:
 
 ```typescript
-import { createContentDispositionHeader, sanitizeFilename } from '@venizia/ignis';
+import { createContentDispositionHeader, sanitizeFilename } from '@venizia/ignis-helpers';
 
 async downloadFile(c: Context) {
   const filename = sanitizeFilename(c.req.param('filename'));
@@ -177,7 +178,7 @@ async downloadFile(c: Context) {
 Use `parseMultipartBody()` for safe file uploads with automatic sanitization:
 
 ```typescript
-import { parseMultipartBody } from '@venizia/ignis';
+import { parseMultipartBody } from '@venizia/ignis-helpers';
 
 async uploadFile(c: Context) {
   const files = await parseMultipartBody({

package/wiki/guides/core-concepts/components-guide.md

@@ -133,11 +133,11 @@ import {
   controller,
   post,
   inject,
-  HTTP,
   jsonContent,
   jsonResponse,
   TRouteContext,
 } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 import { NotificationService } from '../services';
 

package/wiki/guides/core-concepts/controllers.md

@@ -9,7 +9,8 @@ Controllers handle HTTP requests and return responses - they're your API endpoin
 Extend `BaseController` and use decorators to define routes:
 
 ```typescript
-import { BaseController, controller, get, jsonResponse, z, HTTP } from '@venizia/ignis';
+import { BaseController, controller, get, jsonResponse, z } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { Context } from 'hono';
 
 @controller({ path: '/users' })
@@ -70,7 +71,8 @@ The `opts` object contains a `configs` property that defines the route's path, r
 For optimal organization and type safety, define your route configurations in a constant with `as const`. This allows TypeScript to precisely infer the types for your request data and expected responses within your handler methods.
 
 ```typescript
-import { BaseController, controller, get, post, HTTP, jsonContent, jsonResponse, TRouteContext } from '@venizia/ignis';
+import { BaseController, controller, get, post, jsonContent, jsonResponse, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 
 // Define route configs as const for type inference
@@ -161,7 +163,8 @@ When using this method, you will override the `binding()` method in your control
 Use this method for defining a single API endpoint with all its configurations and handler. It also benefits from type inference when used with `TRouteContext`.
 
 ```typescript
-import { Authentication, HTTP, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { Authentication, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 // ... inside the binding() method
 
@@ -188,7 +191,8 @@ this.defineRoute({
 This method offers a fluent API for defining routes, similar to `defineRoute`, but structured for chaining. It also benefits from `TRouteContext` for type safety.
 
 ```typescript
-import { jsonResponse, z, TRouteContext, HTTP } from '@venizia/ignis';
+import { jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 // ... inside the binding() method
 
@@ -309,7 +313,7 @@ this.defineJSXRoute({
 
 ```typescript
 // src/views/pages/home.page.tsx
-import type { FC } from '@venizia/ignis';
+import type { FC } from '@venizia/ignis-helpers';
 import { MainLayout } from '../layouts/main.layout';
 
 interface HomePageProps {
@@ -330,7 +334,7 @@ export const HomePage: FC<HomePageProps> = ({ user }) => {
 
 ```typescript
 // src/views/layouts/main.layout.tsx
-import type { FC, PropsWithChildren } from '@venizia/ignis';
+import type { FC, PropsWithChildren } from '@venizia/ignis-helpers';
 
 interface MainLayoutProps {
   title: string;
@@ -369,7 +373,8 @@ When you define Zod schemas in your route's `request` configuration (whether wit
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { jsonContent, put, HTTP } from '@venizia/ignis';
+import { jsonContent, put } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 // ... inside a controller class
 
@@ -406,7 +411,8 @@ Using `c.req.valid()` is the recommended way to access request data as it ensure
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { jsonContent, put, TRouteContext, HTTP } from '@venizia/ignis';
+import { jsonContent, put, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 // ... inside a controller class
 

package/wiki/guides/core-concepts/persistent/models.md

@@ -208,6 +208,38 @@ const [fullUser] = await connector
 For complete hidden properties documentation, see the [Models Reference](../../../references/base/models.md#hidden-properties).
 :::
 
+## Authorization Settings
+
+Declare your model's authorization principal directly in `@model` settings. The decorator auto-populates `AUTHORIZATION_SUBJECT` for type-safe references in route configs:
+
+```typescript
+import { BaseEntity, generateIdColumnDefs, model, AuthorizationActions } from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+
+@model({
+  type: 'entity',
+  settings: {
+    authorize: { principal: 'article' },
+  },
+})
+export class Article extends BaseEntity<typeof Article.schema> {
+  static override schema = pgTable('Article', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    title: text('title').notNull(),
+  });
+}
+
+// Use in route configs — no hardcoded strings
+authorize: {
+  action: AuthorizationActions.READ,
+  resource: Article.AUTHORIZATION_SUBJECT, // 'article'
+}
+```
+
+:::tip
+For full authorization integration details, see the [Authorization Usage Reference](../../../references/components/authorization/usage#model-based-resource-references).
+:::
+
 ## Model Template
 
 ```typescript

package/wiki/guides/core-concepts/services.md

@@ -18,7 +18,8 @@ Services contain the core business logic of your application. They orchestrate t
 To create a service, you extend the `BaseService` class and inject the repositories or other services it depends on.
 
 ```typescript
-import { BaseService, inject, getError } from '@venizia/ignis';
+import { BaseService, inject } from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
 import { ConfigurationRepository } from '../repositories';
 import { UserRepository } from '../repositories';
 import { LoggingService } from './logging.service'; // Example of another service

package/wiki/guides/get-started/5-minute-quickstart.md

@@ -84,11 +84,11 @@ import {
   BaseController,
   controller,
   get,
-  HTTP,
   IApplicationInfo,
   jsonContent,
   SwaggerComponent,
 } from "@venizia/ignis";
+import { HTTP } from "@venizia/ignis-helpers";
 import { Context } from "hono";
 import appInfo from "./../package.json";
 

package/wiki/guides/reference/mcp-docs-server.md

@@ -18,7 +18,6 @@ Pick which AI assistant you're using:
 | Tool                                  | Best For                                 |
 | ------------------------------------- | ---------------------------------------- |
 | [Claude Code](#claude-code-cli-setup) | Terminal users, developers (Recommended) |
-| [Gemini CLI](#gemini-cli-setup)       | Google AI users                          |
 | [VS Code](#vs-code-setup)             | VS Code with MCP extensions              |
 | [Cursor](#cursor-setup)               | AI-first code editor                     |
 | [Windsurf](#windsurf-setup)           | Codeium's AI editor                      |
@@ -244,139 +243,6 @@ Once working, try these queries:
 "Show me an example of dependency injection in Ignis"
 ```
 
-## Gemini CLI Setup
-
-> **Important:** As of December 2024, Google's official Gemini CLI has limited MCP support. This setup is **experimental** and may require custom configuration.
-
-### Prerequisites
-
-1. **Install Google AI CLI tools:**
-
-   ```bash
-   # Option 1: Using pip (Python)
-   pip install google-generativeai
-
-   # Option 2: Using Node.js wrapper
-   npm install -g @google/generative-ai
-   ```
-
-2. **Get your API key:**
-   - Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
-   - Create a new API key
-   - Save it securely
-
-### Setup Steps
-
-#### 1. Configure environment
-
-```bash
-# Set your API key
-export GOOGLE_API_KEY="your-api-key-here"
-
-# Or add to your shell config (~/.bashrc, ~/.zshrc):
-echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.bashrc
-source ~/.bashrc
-```
-
-#### 2. Create MCP config directory
-
-```bash
-# Create config directory
-mkdir -p ~/.config/gemini
-
-# The config file location:
-# macOS/Linux: ~/.config/gemini/mcp_servers.json
-# Windows: %USERPROFILE%\.config\gemini\mcp_servers.json
-```
-
-#### 3. Add MCP Server Configuration
-
-Create `~/.config/gemini/mcp_servers.json`:
-
-**Recommended: Using npx**
-
-```json
-{
-  "mcpServers": {
-    "ignis-docs": {
-      "command": "npx",
-      "args": ["-y", "@venizia/ignis-docs"],
-      "env": {}
-    }
-  }
-}
-```
-
-**Alternative: Global install**
-
-```bash
-# First install globally
-npm install -g @venizia/ignis-docs
-```
-
-Then configure:
-
-```json
-{
-  "mcpServers": {
-    "ignis-docs": {
-      "command": "ignis-docs-mcp",
-      "env": {}
-    }
-  }
-}
-```
-
-#### 4. Test manually first
-
-Before integrating with Gemini, test the MCP server works:
-
-```bash
-# Test the MCP server can start
-npx @venizia/ignis-docs
-
-# Expected output:
-# "MCP Server listening on stdio..."
-# (Press Ctrl+C to stop)
-```
-
-#### 5. Use with Gemini (if supported)
-
-**Note:** MCP support in Gemini CLI is limited. Alternative approaches:
-
-**Option A: Use Google AI Python SDK with custom MCP wrapper**
-
-```python
-# This requires writing custom integration code
-# See: https://github.com/modelcontextprotocol/python-sdk
-```
-
-**Option B: Use via Claude Code CLI instead**
-
-- Gemini CLI MCP support is experimental
-- Claude Code has better MCP support out of the box
-- Recommendation: Use [Claude Code CLI setup](#claude-code-cli-setup) for Ignis docs
-
-#### Troubleshooting
-
-**"Command not found: gemini"**
-
-- Google doesn't have an official "gemini" CLI command
-- Use `gcloud ai` or Python SDK instead
-- Consider using Claude Code CLI for better MCP support
-
-**MCP server not loading**
-
-- Gemini CLI MCP support is experimental
-- Check if your Gemini CLI version supports MCP:
-  ```bash
-  gemini --version
-  gemini mcp list  # If this command doesn't exist, MCP isn't supported
-  ```
-
-**Recommended Alternative:**
-Use Claude Code CLI (see setup above) - it has full MCP support and works reliably.
-
 ## VS Code Setup
 
 VS Code supports MCP through various extensions. The setup process is similar to Microsoft's Playwright MCP integration.

package/wiki/guides/tutorials/building-a-crud-api.md

@@ -647,7 +647,8 @@ For complex validation or business rules, create a Service layer:
 
 ```typescript
 // src/services/todo.service.ts
-import { BaseService, inject, getError } from '@venizia/ignis';
+import { BaseService, inject } from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
 import { TodoRepository } from '@/repositories/todo.repository';
 
 export class TodoService extends BaseService {

package/wiki/guides/tutorials/complete-installation.md

@@ -259,9 +259,9 @@ import {
   BaseController,
   controller,
   api,
-  HTTP,
   jsonContent,
 } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 import { Context } from 'hono';
 
@@ -326,7 +326,7 @@ Create `src/index.ts` - this starts your application:
 
 ```typescript
 import { Application, appConfigs } from './application';
-import { LoggerFactory } from '@venizia/ignis';
+import { LoggerFactory } from '@venizia/ignis-helpers';
 
 const logger = LoggerFactory.getLogger(['main']);
 

package/wiki/guides/tutorials/ecommerce-api.md

@@ -922,10 +922,10 @@ import {
   controller,
   get,
   inject,
-  HTTP,
   jsonContent,
   TRouteContext,
 } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { ProductService } from '../services/product.service';
 
 // Define route configs with PascalCase type and SCREAMING_SNAKE_CASE keys
@@ -1013,10 +1013,10 @@ import {
   put,
   del,
   inject,
-  HTTP,
   jsonContent,
   TRouteContext,
 } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { CartService } from '../services/cart.service';
 
 const CartRoutes = {
@@ -1150,10 +1150,10 @@ import {
   get,
   post,
   inject,
-  HTTP,
   jsonContent,
   TRouteContext,
 } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { OrderService } from '../services/order.service';
 
 const OrderRoutes = {

package/wiki/guides/tutorials/realtime-chat.md

@@ -448,11 +448,10 @@ import {
   CoreBindings,
   inject,
   SocketIOBindingKeys,
-  SocketIOServerHelper,
   BindingKeys,
   BindingNamespaces,
 } from '@venizia/ignis';
-import { ISocketIOClient, getError } from '@venizia/ignis-helpers';
+import { ISocketIOClient, getError, SocketIOServerHelper } from '@venizia/ignis-helpers';
 import { Socket } from 'socket.io';
 import { MessageRepository } from '../repositories/message.repository';
 import { RoomRepository } from '../repositories/room.repository';
@@ -938,19 +937,21 @@ The application binds Redis, authentication, and the client connected handler vi
 ```typescript
 // src/application.ts
 import {
-  applicationEnvironment,
   BaseApplication,
   BindingKeys,
   BindingNamespaces,
   IApplicationConfigs,
   IApplicationInfo,
-  ISocketIOServerBaseOptions,
-  RedisHelper,
   SocketIOBindingKeys,
   SocketIOComponent,
-  SocketIOServerHelper,
   ValueOrPromise,
 } from '@venizia/ignis';
+import {
+  applicationEnvironment,
+  type ISocketIOServerBaseOptions,
+  RedisHelper,
+  SocketIOServerHelper,
+} from '@venizia/ignis-helpers';
 import { ChatService } from './services/chat.service';
 import { ChatController } from './controllers/chat.controller';
 import { UserRepository } from './repositories/user.repository';

package/wiki/index.md

@@ -64,7 +64,8 @@ bun add -d typescript @types/bun
 ```
 
 ```typescript
-import { BaseApplication, BaseController, controller, get, HTTP, jsonContent, SwaggerComponent } from '@venizia/ignis';
+import { BaseApplication, BaseController, controller, get, jsonContent, SwaggerComponent } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 
 // 1. Define your controller

package/wiki/references/base/components.md

@@ -306,7 +306,8 @@ export class HealthCheckComponent extends BaseComponent {
 
 ```typescript
 // src/components/auth/authenticate/component.ts
-import { BaseApplication, BaseComponent, inject, CoreBindings, Binding, ValueOrPromise, getError } from '@venizia/ignis';
+import { BaseApplication, BaseComponent, inject, CoreBindings, Binding, ValueOrPromise } from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
 import { AuthenticateBindingKeys, IAuthenticateOptions, IBasicTokenServiceOptions, IJWTTokenServiceOptions } from './common';
 import { BasicTokenService, JWTTokenService } from './services';
 import { defineAuthController } from './controllers';