te.js 1.3.0 → 2.0.0

package/docs/cli.md

@@ -0,0 +1,152 @@
+# CLI Reference
+
+Tejas includes a command-line interface for starting your server and generating API documentation.
+
+## Installation
+
+The CLI is included when you install te.js. It is available as the `tejas` command:
+
+```bash
+npm install te.js
+```
+
+If installed locally, use `npx tejas` to run commands.
+
+## Commands
+
+### tejas fly
+
+Start the Tejas server by running your application's entry point.
+
+```bash
+tejas fly [file]
+```
+
+**Entry point resolution** (first match wins):
+
+1. CLI argument — `tejas fly app.js`
+2. `tejas.config.json` — `"entry": "src/index.js"`
+3. `package.json` — `"main": "index.js"`
+4. Convention files — `index.js`, `app.js`, or `server.js` in the current directory
+
+**Examples:**
+
+```bash
+# Use automatic entry point resolution
+npx tejas fly
+
+# Specify an entry file explicitly
+npx tejas fly src/server.js
+```
+
+The server process inherits your environment and current working directory. Press `Ctrl+C` to stop.
+
+---
+
+### tejas generate:docs
+
+Generate an OpenAPI 3.0 specification from your registered targets using LLM-powered analysis.
+
+```bash
+tejas generate:docs [--ci]
+```
+
+#### Interactive Mode (default)
+
+Walks you through configuration step by step:
+
+```bash
+npx tejas generate:docs
+```
+
+You will be prompted for:
+
+| Prompt | Default | Description |
+|--------|---------|-------------|
+| Targets directory | `targets` | Directory containing `.target.js` files |
+| Output file | `./openapi.json` | Where to write the OpenAPI spec |
+| API title | `API` | Title in the spec's `info` block |
+| API version | `1.0.0` | Version in the spec's `info` block |
+| API description | *(empty)* | Optional description |
+| LLM provider base URL | `https://api.openai.com/v1` | Any OpenAI-compatible endpoint |
+| API key | *(from env)* | LLM provider API key |
+| Model | `gpt-4o-mini` | LLM model name |
+| Token usage level | `1` | Enhancement depth (1–3) |
+| Preview docs? | No | Serve a live Scalar UI preview |
+
+After generation, if you chose to preview, a local server starts on port 3333 (configurable via the `DOCS_PORT` env var).
+
+#### CI Mode
+
+Non-interactive mode for automated pipelines. Uses configuration from `tejas.config.json` and environment variables:
+
+```bash
+npx tejas generate:docs --ci
+```
+
+**Required environment:**
+
+| Variable | Fallback | Description |
+|----------|----------|-------------|
+| `LLM_API_KEY` | `OPENAI_API_KEY` | LLM provider API key |
+
+**Optional environment:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LLM_BASE_URL` | `https://api.openai.com/v1` | LLM provider base URL |
+| `LLM_MODEL` | `gpt-4o-mini` | LLM model name |
+
+All other options are read from the `docs` section of `tejas.config.json`. See [Auto-Documentation](./auto-docs.md) for the full config reference.
+
+---
+
+### tejas docs:on-push
+
+Generate documentation automatically when pushing to your production branch. Designed for use in a git `pre-push` hook.
+
+```bash
+tejas docs:on-push
+```
+
+This command reads git's pre-push stdin to determine which branch is being pushed. If it matches the configured production branch, it runs `generate:docs` in CI mode.
+
+**Setup with Husky:**
+
+```json
+// package.json
+{
+  "husky": {
+    "hooks": {
+      "pre-push": "tejas docs:on-push"
+    }
+  }
+}
+```
+
+**Configuration:**
+
+| Source | Key | Default |
+|--------|-----|---------|
+| `tejas.config.json` | `docs.productionBranch` | `"main"` |
+| Environment variable | `DOCS_PRODUCTION_BRANCH` | `"main"` |
+
+If the push is not targeting the production branch, the command exits silently with no action.
+
+---
+
+## Environment Variables Summary
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `LLM_API_KEY` | `generate:docs`, `docs:on-push` | LLM provider API key |
+| `OPENAI_API_KEY` | `generate:docs`, `docs:on-push` | Fallback API key |
+| `LLM_BASE_URL` | `generate:docs`, `docs:on-push` | LLM provider endpoint |
+| `LLM_MODEL` | `generate:docs`, `docs:on-push` | LLM model name |
+| `DOCS_PORT` | `generate:docs` | Preview server port (default `3333`) |
+| `DOCS_PRODUCTION_BRANCH` | `docs:on-push` | Branch name to trigger generation |
+
+## Next Steps
+
+- [Auto-Documentation](./auto-docs.md) — Enhancement levels, endpoint metadata, and Scalar UI
+- [Configuration](./configuration.md) — Full `tejas.config.json` reference

package/docs/configuration.md

@@ -0,0 +1,233 @@
+# Configuration
+
+Tejas provides a flexible configuration system that merges settings from multiple sources.
+
+## Configuration Sources
+
+Settings are loaded from three sources. Later sources override earlier ones:
+
+1. **`tejas.config.json`** — file in your project root (lowest priority)
+2. **Environment variables** — from `.env` or system environment
+3. **Constructor options** — passed to `new Tejas({...})` (highest priority)
+
+All configuration keys are normalized: nested objects are flattened with underscores and uppercased. For example, `log.http_requests` becomes the environment variable `LOG_HTTP_REQUESTS`.
+
+## Quick Start
+
+The simplest way to configure Tejas is with a `tejas.config.json` file:
+
+```json
+{
+  "port": 3000,
+  "dir": {
+    "targets": "targets"
+  },
+  "log": {
+    "http_requests": true,
+    "exceptions": true
+  }
+}
+```
+
+Or pass options directly to the constructor:
+
+```javascript
+import Tejas from 'te.js';
+
+const app = new Tejas({
+  port: 3000,
+  log: { http_requests: true }
+});
+
+app.takeoff();
+```
+
+## Complete Configuration Reference
+
+### Core
+
+| Config Key | Env Variable | Type | Default | Description |
+|------------|-------------|------|---------|-------------|
+| `entry` | `ENTRY` | string | *(auto-resolved)* | Entry file for `tejas fly`. Falls back to `package.json` `main`, then `index.js` / `app.js` / `server.js` |
+| `port` | `PORT` | number | `1403` | Server port |
+| `dir.targets` | `DIR_TARGETS` | string | `"targets"` | Directory containing `.target.js` files for auto-discovery |
+
+### Logging
+
+| Config Key | Env Variable | Type | Default | Description |
+|------------|-------------|------|---------|-------------|
+| `log.http_requests` | `LOG_HTTP_REQUESTS` | boolean | `false` | Log incoming HTTP requests (method, path, status, time) |
+| `log.exceptions` | `LOG_EXCEPTIONS` | boolean | `false` | Log unhandled exceptions and errors |
+
+### Request Body
+
+| Config Key | Env Variable | Type | Default | Description |
+|------------|-------------|------|---------|-------------|
+| `body.max_size` | `BODY_MAX_SIZE` | number | `10485760` (10 MB) | Maximum request body size in bytes. Requests exceeding this receive a 413 error |
+| `body.timeout` | `BODY_TIMEOUT` | number | `30000` (30 s) | Body parsing timeout in milliseconds. Requests exceeding this receive a 408 error |
+
+### Auto-Documentation
+
+These options configure the `tejas generate:docs` CLI command and the auto-documentation system. See [Auto-Documentation](./auto-docs.md) for full details.
+
+| Config Key | Env Variable | Type | Default | Description |
+|------------|-------------|------|---------|-------------|
+| `docs.dirTargets` | `DOCS_DIR_TARGETS` | string | `"targets"` | Target directory for doc generation (can differ from `dir.targets`) |
+| `docs.output` | — | string | `"./openapi.json"` | Output path for the generated OpenAPI spec |
+| `docs.title` | — | string | `"API"` | API title in the OpenAPI `info` block |
+| `docs.version` | — | string | `"1.0.0"` | API version in the OpenAPI `info` block |
+| `docs.description` | — | string | `""` | API description |
+| `docs.level` | — | number | `1` | LLM enhancement level (1–3). Higher = better docs, more tokens |
+| `docs.llm.baseURL` | `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint |
+| `docs.llm.apiKey` | `LLM_API_KEY` | string | — | LLM provider API key |
+| `docs.llm.model` | `LLM_MODEL` | string | `"gpt-4o-mini"` | LLM model name |
+| `docs.overviewPath` | — | string | `"./API_OVERVIEW.md"` | Path for the generated overview page (level 3 only) |
+| `docs.productionBranch` | `DOCS_PRODUCTION_BRANCH` | string | `"main"` | Git branch that triggers `docs:on-push` |
+
+## Configuration File
+
+Create a `tejas.config.json` in your project root:
+
+```json
+{
+  "entry": "app.js",
+  "port": 3000,
+  "dir": {
+    "targets": "targets"
+  },
+  "log": {
+    "http_requests": true,
+    "exceptions": true
+  },
+  "body": {
+    "max_size": 5242880,
+    "timeout": 15000
+  },
+  "docs": {
+    "output": "./openapi.json",
+    "title": "My API",
+    "version": "1.0.0",
+    "level": 2,
+    "productionBranch": "main"
+  }
+}
+```
+
+## Environment Variables
+
+Create a `.env` file in your project root. Tejas uses [tej-env](https://www.npmjs.com/package/tej-env) to load it automatically:
+
+```bash
+# Server
+PORT=3000
+
+# Logging
+LOG_HTTP_REQUESTS=true
+LOG_EXCEPTIONS=true
+
+# Body limits
+BODY_MAX_SIZE=5242880
+BODY_TIMEOUT=15000
+
+# Target directory
+DIR_TARGETS=targets
+
+# LLM (for tejas generate:docs)
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_API_KEY=sk-...
+LLM_MODEL=gpt-4o-mini
+```
+
+## Constructor Options
+
+Pass an object to `new Tejas()` using the same nested structure as `tejas.config.json`:
+
+```javascript
+import Tejas from 'te.js';
+
+const app = new Tejas({
+  port: 3000,
+  log: {
+    http_requests: true,
+    exceptions: true
+  },
+  body: {
+    max_size: 10 * 1024 * 1024,
+    timeout: 30000
+  }
+});
+```
+
+Constructor options have the highest priority and override both the config file and environment variables.
+
+## How Merging Works
+
+All configuration is flattened into a single-level object with uppercased keys:
+
+```javascript
+// tejas.config.json
+{ "log": { "http_requests": true } }
+
+// Becomes accessible as:
+env('LOG_HTTP_REQUESTS') // true
+```
+
+The merge order is: config file values, then env vars override those, then constructor options override everything.
+
+## Accessing Configuration at Runtime
+
+Use the `env()` function from `tej-env` to read any configuration value:
+
+```javascript
+import { env } from 'tej-env';
+
+target.register('/info', (ammo) => {
+  ammo.fire({
+    port: env('PORT'),
+    maxBodySize: env('BODY_MAX_SIZE')
+  });
+});
+```
+
+## Auto-Registration
+
+Tejas automatically discovers and imports all files ending in `.target.js` from the configured `dir.targets` directory (recursively, including subdirectories):
+
+```
+targets/
+├── user.target.js      --> Auto-loaded
+├── auth.target.js      --> Auto-loaded
+├── utils.js            --> Ignored (wrong suffix)
+└── api/
+    └── v1.target.js    --> Auto-loaded
+```
+
+To change the targets directory:
+
+```json
+{
+  "dir": {
+    "targets": "src/routes"
+  }
+}
+```
+
+## Database Configuration
+
+Database connections are configured via `takeoff()` options, not through the config file:
+
+```javascript
+app.takeoff({
+  withRedis: { url: 'redis://localhost:6379' },
+  withMongo: { uri: 'mongodb://localhost:27017/myapp' }
+});
+```
+
+See [Database Integration](./database.md) for details.
+
+## Next Steps
+
+- [Getting Started](./getting-started.md) — Build your first Tejas application
+- [Routing](./routing.md) — Define routes and endpoints
+- [Auto-Documentation](./auto-docs.md) — Generate OpenAPI docs from your code
+- [CLI Reference](./cli.md) — `tejas fly` and doc generation commands