@venizia/ignis-docs 0.0.3 → 0.0.4-0

package/wiki/guides/get-started/setup.md

@@ -0,0 +1,157 @@
+# Setup
+
+Everything you need to start building with Ignis. This guide covers installation for macOS, Linux, and Windows (via WSL2).
+
+## Requirements
+
+| Tool | Version | Required | Notes |
+|------|---------|----------|-------|
+| **Bun** | >= 1.3 | Yes | Primary runtime, fastest performance |
+| **Node.js** | >= 18 | Alternative | Use if Bun isn't available |
+| **PostgreSQL** | >= 14 | Yes | Primary database |
+| **VS Code** | Latest | Recommended | Best IDE experience with extensions |
+
+## Install Runtime
+
+### Bun (Recommended)
+
+```bash
+# macOS / Linux
+curl -fsSL https://bun.sh/install | bash
+
+# Windows (use WSL2)
+# First install WSL2: wsl --install
+# Then run the curl command above in WSL
+
+# Verify
+bun --version  # Should be 1.3+
+```
+
+### Node.js (Alternative)
+
+```bash
+# macOS (Homebrew)
+brew install node@18
+
+# Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Windows
+# Download from https://nodejs.org/
+
+# Verify
+node --version  # Should be 18+
+```
+
+## Install PostgreSQL
+
+### macOS
+
+```bash
+brew install postgresql@14
+brew services start postgresql@14
+```
+
+### Ubuntu/Debian
+
+```bash
+sudo apt-get update
+sudo apt-get install postgresql-14
+sudo service postgresql start
+```
+
+### Windows
+
+Download from [postgresql.org/download/windows](https://www.postgresql.org/download/windows/) or use WSL2.
+
+### Create Database
+
+```bash
+# macOS
+psql postgres -c "CREATE DATABASE my_app_db;"
+
+# Linux (Ubuntu/Debian)
+sudo -u postgres psql -c "CREATE DATABASE my_app_db;"
+
+# Verify
+psql my_app_db -c "SELECT 1;"  # Should return 1
+```
+
+## VS Code Setup (Recommended)
+
+### Extensions
+
+```bash
+# Essential
+code --install-extension dbaeumer.vscode-eslint
+code --install-extension esbenp.prettier-vscode
+
+# Recommended
+code --install-extension usernamehw.errorlens
+code --install-extension humao.rest-client
+code --install-extension prisma.prisma  # Works with Drizzle too
+```
+
+### Settings
+
+Create `.vscode/settings.json`:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  }
+}
+```
+
+## Verify Setup
+
+```bash
+bun --version      # >= 1.3 (or node --version >= 18)
+psql --version     # >= 14
+```
+
+## Troubleshooting
+
+### Bun not found after install
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+
+# Then reload
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### PostgreSQL permission denied
+
+```bash
+# Linux: Use sudo -u postgres
+sudo -u postgres psql -c "CREATE DATABASE my_app_db;"
+
+# macOS: Check if PostgreSQL is running
+brew services list | grep postgresql
+```
+
+### PostgreSQL connection refused
+
+```bash
+# Check if running
+pg_isready
+
+# Start service
+# macOS
+brew services start postgresql@14
+
+# Linux
+sudo service postgresql start
+```
+
+## Next Steps
+
+- [5-Minute Quickstart](./5-minute-quickstart.md) — Build your first API
+- [Complete Installation](../tutorials/complete-installation.md) — Full project setup

package/wiki/guides/index.md

@@ -0,0 +1,89 @@
+# Getting Started with Ignis
+
+Welcome to Ignis — a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
+
+<div class="guide-cards">
+
+<a href="./get-started/setup" class="guide-card">
+<span class="guide-icon">🛠️</span>
+<h3>Setup</h3>
+<p>Install Bun, PostgreSQL, and configure your IDE</p>
+</a>
+
+<a href="./get-started/5-minute-quickstart" class="guide-card highlight">
+<span class="guide-icon">⚡</span>
+<h3>5-Min Quickstart</h3>
+<p>Your first endpoint in 5 minutes</p>
+</a>
+
+<a href="./tutorials/complete-installation" class="guide-card">
+<span class="guide-icon">📦</span>
+<h3>Full Installation</h3>
+<p>Production-ready project setup</p>
+</a>
+
+<a href="./tutorials/building-a-crud-api" class="guide-card">
+<span class="guide-icon">🗄️</span>
+<h3>Build a CRUD API</h3>
+<p>Complete Todo API with database</p>
+</a>
+
+<a href="./tutorials/testing" class="guide-card">
+<span class="guide-icon">🧪</span>
+<h3>Testing</h3>
+<p>Write tests for your application</p>
+</a>
+
+<a href="./get-started/philosophy" class="guide-card">
+<span class="guide-icon">💡</span>
+<h3>Philosophy</h3>
+<p>Why Ignis? Design decisions explained</p>
+</a>
+
+</div>
+
+## Learning Roadmap
+
+<div class="roadmap">
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">1</span>
+<h4>First Steps</h4>
+</div>
+<p><a href="./get-started/setup">Setup</a> → <a href="./get-started/5-minute-quickstart">5-Min Quickstart</a></p>
+<span class="stage-desc">Get your environment ready and build your first endpoint</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">2</span>
+<h4>Build Something Real</h4>
+</div>
+<p><a href="./tutorials/complete-installation">Full Installation</a> → <a href="./tutorials/building-a-crud-api">CRUD API</a> → <a href="./tutorials/testing">Testing</a></p>
+<span class="stage-desc">Create a complete API with database, validation, and tests</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">3</span>
+<h4>Understand the Framework</h4>
+</div>
+<p><a href="./core-concepts/application">Application</a> → <a href="./core-concepts/controllers">Controllers</a> → <a href="./core-concepts/services">Services</a> → <a href="./core-concepts/dependency-injection">DI</a></p>
+<span class="stage-desc">Deep dive into core concepts and architecture patterns</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">4</span>
+<h4>Go to Production</h4>
+</div>
+<p><a href="/best-practices/">Best Practices</a> → <a href="/references/">API Reference</a></p>
+<span class="stage-desc">Learn patterns, security, performance, and deployment</span>
+</div>
+
+</div>
+
+::: tip New to backend development?
+Check out our [Glossary](./reference/glossary) for explanations of key terms like Controllers, Repositories, and Dependency Injection.
+:::

package/wiki/guides/reference/glossary.md

@@ -0,0 +1,243 @@
+# Glossary for Beginners
+
+Quick reference for key terms in Ignis documentation.
+
+
+## Core Framework Terms
+
+| Term | Description |
+|------|-------------|
+| **Application** | Main entry point extending `BaseApplication`. Registers all components. |
+| **Controller** | Handles HTTP requests, defines API endpoints (`@controller`, `@get`, `@post`) |
+| **Service** | Contains business logic between controllers and repositories |
+| **Repository** | Database operations for one entity (`find`, `create`, `updateById`, etc.) |
+| **DataSource** | Database connection configuration (host, port, credentials) |
+| **Model/Entity** | Defines data structure and relationships using Drizzle schema |
+| **Component** | Reusable plugin that bundles related functionality |
+| **DI Container** | Central registry that stores and resolves dependencies. The `Application` class acts as the container. |
+
+```typescript
+// Application registers everything
+export class Application extends BaseApplication {
+  preConfigure() {
+    this.dataSource(PostgresDataSource);
+    this.repository(TodoRepository);
+    this.controller(TodoController);
+  }
+}
+
+// Controller handles HTTP
+const TodoRoutes = {
+  GET_ALL: {
+    method: HTTP.Methods.GET,
+    path: '/',
+    responses: jsonResponse({ schema: z.array(z.object({ id: z.string() })) }),
+  },
+} as const;
+
+@controller({ path: '/todos' })
+export class TodoController extends BaseController {
+  @get({ configs: TodoRoutes.GET_ALL })
+  async getAll(c: TRouteContext<typeof TodoRoutes.GET_ALL>) {
+    const todos = await this.repository.find({});
+    return c.json(todos, HTTP.ResultCodes.RS_2.Ok);
+  }
+}
+
+// Repository handles database
+@repository({ model: Todo, dataSource: PostgresDataSource })
+export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {}
+```
+
+**Related:** [Application](../core-concepts/application/) | [Controllers](../core-concepts/controllers) | [Services](../core-concepts/services) | [Repositories](../../references/base/repositories/)
+
+
+## TypeScript & Pattern Terms
+
+### Decorators
+Annotations starting with `@` that add behavior to classes/methods.
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@controller` | Marks class as controller |
+| `@model` | Marks class as model/entity |
+| `@repository` | Marks class as repository |
+| `@datasource` | Marks class as datasource |
+| `@inject` | Requests dependency from container |
+| `@get`, `@post`, `@patch`, `@delete` | HTTP route handlers |
+
+### Dependency Injection (DI)
+Classes receive dependencies from an external container instead of creating them internally. Benefits: testable, flexible, maintainable.
+
+```typescript
+// ❌ Without DI - creates own dependencies
+class TodoController {
+  private repository = new TodoRepository(new PostgresDataSource());
+}
+
+// ✅ With DI - receives from container
+class TodoController {
+  constructor(
+    @inject({ key: 'repositories.TodoRepository' })
+    private repository: TodoRepository
+  ) {}
+}
+```
+
+### Container & Binding
+Container stores all dependencies. Binding registers classes/values under keys.
+
+```typescript
+// Register in Application
+this.repository(TodoRepository);  // Key: 'repositories.TodoRepository'
+this.bind({ key: 'config.apiKey' }).toValue('sk_live_xxx');
+
+// Resolve via @inject
+@inject({ key: 'repositories.TodoRepository' }) private repository: TodoRepository;
+```
+
+### Generic Types
+TypeScript feature for reusable components: `<T>` or `<SomeType>`.
+
+```typescript
+class DefaultCRUDRepository<TSchema> { find(): TSchema[] { ... } }
+class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {}
+```
+
+**Related:** [Dependency Injection Guide](../core-concepts/dependency-injection)
+
+
+## Database Terms
+
+| Term | Description |
+|------|-------------|
+| **ORM** | Tool to work with databases using code instead of raw SQL. Ignis uses Drizzle ORM. |
+| **Drizzle ORM** | Type-safe ORM library. [Docs](https://orm.drizzle.team/) |
+| **Schema** | Table structure definition using Drizzle syntax |
+| **Migration** | Script that creates/modifies tables. Version control for database structure. |
+| **Connector** | Database driver that executes queries (via `dataSource.connector`) |
+| **Relations** | Connections between tables (hasMany, belongsTo, hasOne) |
+
+```typescript
+// Schema definition
+export const todoTable = pgTable('Todo', {
+  id: text('id').primaryKey(),
+  title: text('title').notNull(),
+  completed: boolean('completed').default(false),
+});
+
+// Relations
+export const userRelations = createRelations({
+  source: userTable,
+  relations: [{ type: 'hasMany', model: () => Post, foreignKey: 'authorId' }],
+});
+
+// Query with relations
+await userRepo.find({ filter: { include: [{ relation: 'posts' }] } });
+```
+
+```bash
+# Migrations
+bun run drizzle-kit generate  # Generate from schema changes
+bun run migrate:dev           # Apply to database
+```
+
+
+## Query & Filter Terms
+
+### Filter Object
+Specifies what data to retrieve: `where`, `limit`, `order`, `include`.
+
+```typescript
+await repository.find({
+  filter: {
+    where: { status: 'active', age: { gte: 18 } },
+    order: ['createdAt DESC'],
+    limit: 10,
+    include: [{ relation: 'author' }],
+  }
+});
+```
+
+### Operators
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| `eq` | Equal | `{ status: { eq: 'active' } }` |
+| `ne` | Not equal | `{ status: { ne: 'deleted' } }` |
+| `gt`, `gte` | Greater than (or equal) | `{ age: { gte: 18 } }` |
+| `lt`, `lte` | Less than (or equal) | `{ price: { lt: 100 } }` |
+| `like`, `ilike` | Pattern match | `{ name: { like: '%john%' } }` |
+| `in`, `nin` | In list / not in list | `{ id: { in: [1, 2, 3] } }` |
+| `between` | Range | `{ age: { between: [18, 65] } }` |
+
+**Related:** [Filter System](../../references/base/filter-system/) | [Repositories](../../references/base/repositories/)
+
+
+## HTTP & API Terms
+
+### REST API Methods
+
+| Method | URL | Action |
+|--------|-----|--------|
+| GET | `/todos` | List all |
+| GET | `/todos/:id` | Get one |
+| POST | `/todos` | Create |
+| PATCH | `/todos/:id` | Update |
+| DELETE | `/todos/:id` | Delete |
+
+```typescript
+const TodoRoutes = {
+  GET_ALL: { method: HTTP.Methods.GET, path: '/', responses: jsonResponse({ schema: z.array(z.any()) }) },
+  GET_BY_ID: { method: HTTP.Methods.GET, path: '/:id', request: { params: z.object({ id: z.string() }) }, responses: jsonResponse({ schema: z.any() }) },
+  CREATE: { method: HTTP.Methods.POST, path: '/', request: { body: jsonContent({ schema: z.any() }) }, responses: jsonResponse({ schema: z.any() }) },
+} as const;
+
+@controller({ path: '/todos' })
+class TodoController {
+  @get({ configs: TodoRoutes.GET_ALL })
+  async getAll(c: TRouteContext<typeof TodoRoutes.GET_ALL>) { ... }
+
+  @get({ configs: TodoRoutes.GET_BY_ID })
+  async getById(c: TRouteContext<typeof TodoRoutes.GET_BY_ID>) {
+    const { id } = c.req.valid('param');
+    ...
+  }
+
+  @post({ configs: TodoRoutes.CREATE })
+  async create(c: TRouteContext<typeof TodoRoutes.CREATE>) {
+    const data = c.req.valid('json');
+    ...
+  }
+}
+```
+
+| Term | Description |
+|------|-------------|
+| **Endpoint** | URL path that API responds to (e.g., `GET /todos`) |
+| **Route Parameter** | Variable in URL marked with `:` (e.g., `:id`) |
+| **Request Body** | JSON data sent with POST/PATCH requests |
+| **OpenAPI/Swagger** | Auto-generated API docs at `/docs` |
+
+
+## Environment & Configuration
+
+Environment variables store configuration outside code (in `.env` files). Ignis uses `APP_ENV_` prefix to avoid system conflicts.
+
+```bash
+# .env file
+APP_ENV_POSTGRES_HOST=localhost
+APP_ENV_POSTGRES_PASSWORD=secret123
+APP_ENV_SERVER_PORT=3000
+```
+
+```typescript
+const host = process.env.APP_ENV_POSTGRES_HOST;
+```
+
+**Related:** [Environment Variables Reference](../../references/configuration/environment-variables)
+
+
+## See Also
+
+[5-Minute Quickstart](../get-started/5-minute-quickstart) | [Building a CRUD API](../tutorials/building-a-crud-api) | [Repositories](../../references/base/repositories/)

package/wiki/{get-started → guides/reference}/mcp-docs-server.md

@@ -594,7 +594,6 @@ AI: [Uses listCategories, then listDocs with category filter]
 AI: "The Helpers category contains: Redis, Logger, Queue..."
 ```
 
----
 
 ## Local Development Setup
 
@@ -649,7 +648,6 @@ Use absolute paths in your config:
 }
 ```
 
----
 
 ## Comprehensive Troubleshooting Guide
 
@@ -678,7 +676,6 @@ cat ~/.config/claude-code/config.json | python -m json.tool
 - Ask: `Can you search the Ignis docs for "controller"?`
 - Look for: `[Using tool: searchDocs]`
 
----
 
 ### Common Issues and Solutions
 
@@ -725,7 +722,6 @@ cat ~/.config/claude-code/config.json | python -m json.tool
    npm install -g @venizia/ignis-docs
    ```
 
----
 
 #### ❌ Issue #2: AI assistant doesn't use MCP tools
 
@@ -784,7 +780,6 @@ cat ~/.config/claude-code/config.json | python -m json.tool
    # Should NOT error. Press Ctrl+C to stop.
    ```
 
----
 
 #### ❌ Issue #3: "Module not found" errors
 
@@ -818,7 +813,6 @@ cat ~/.config/claude-code/config.json | python -m json.tool
    bun x -p @venizia/ignis-docs@latest ignis-docs-mcp
    ```
 
----
 
 #### ❌ Issue #4: First search takes 10+ seconds
 
@@ -831,7 +825,6 @@ cat ~/.config/claude-code/config.json | python -m json.tool
 
 **Not an error - just one-time startup cost.**
 
----
 
 #### ❌ Issue #5: Config file doesn't exist
 
@@ -854,7 +847,6 @@ cat > ~/.config/claude-code/config.json <<'EOF'
 EOF
 ```
 
----
 
 ### 🐛 Advanced Troubleshooting
 
@@ -894,7 +886,6 @@ If this works, the issue is specific to `@venizia/ignis-docs`.
   - Error messages
   - Your config file (remove secrets)
 
----
 
 ## What's Next?
 
@@ -902,7 +893,6 @@ If this works, the issue is specific to `@venizia/ignis-docs`.
 - **Advanced Usage:** Explore how to chain tools for complex documentation queries
 - **Contribute:** Help improve the docs or add new features
 
----
 
 ## FAQ