skrypt-ai 0.3.4 → 0.4.0

package/dist/template/src/app/docs/cli/page.mdx

@@ -0,0 +1,217 @@
+---
+title: CLI Reference
+description: Complete reference for all Skrypt CLI commands
+---
+
+All available commands in the Skrypt CLI.
+
+## Core Commands
+
+### `skrypt init`
+
+Initialize a new documentation site.
+
+```bash
+skrypt init [directory] --name <project-name>
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `directory` | Target directory | `.` |
+| `--name` | Project name | `my-docs` |
+
+### `skrypt generate`
+
+Generate documentation from source code.
+
+```bash
+skrypt generate <source> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Output directory |
+| `-c, --config <file>` | Config file path |
+| `--provider <name>` | LLM provider (openai, anthropic, deepseek, ollama) |
+| `--model <name>` | Model name |
+| `--dry-run` | Scan only, don't generate |
+| `--multi-lang` | Generate TypeScript + Python examples |
+| `--by-topic` | Organize by topic instead of file |
+| `--public-only` | Only document exported APIs |
+| `--openapi <file>` | Include OpenAPI spec |
+| `--llms-txt` | Generate llms.txt for AEO |
+| `--exclude <patterns>` | Exclude patterns |
+
+**Example:**
+
+```bash
+skrypt generate ./src -o ./docs \
+  --provider openai \
+  --model gpt-4o \
+  --public-only \
+  --llms-txt
+```
+
+### `skrypt deploy`
+
+Deploy docs to Skrypt Cloud.
+
+```bash
+skrypt deploy [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dir <path>` | Docs directory (default: current) |
+
+---
+
+## Watch Mode
+
+### `skrypt watch`
+
+Watch for changes and regenerate docs.
+
+```bash
+skrypt watch <source> [options]
+```
+
+Same options as `generate`, plus continuous watching.
+
+---
+
+## Quality Commands
+
+### `skrypt lint`
+
+Check documentation for issues.
+
+```bash
+skrypt lint [directory]
+```
+
+### `skrypt check-links`
+
+Validate all links in documentation.
+
+```bash
+skrypt check-links [directory]
+```
+
+### `skrypt test` (Pro)
+
+Validate code examples are runnable.
+
+```bash
+skrypt test [directory]
+```
+
+---
+
+## Pro Commands
+
+These require authentication via `skrypt login`.
+
+### `skrypt monitor` (Pro)
+
+Detect documentation drift from code changes.
+
+```bash
+skrypt monitor [options]
+```
+
+### `skrypt autofix` (Pro)
+
+AI-powered documentation healing.
+
+```bash
+skrypt autofix [options]
+```
+
+### `skrypt review-pr` (Pro)
+
+Review pull request for doc impact.
+
+```bash
+skrypt review-pr <pr-number>
+```
+
+### `skrypt sdk` (Pro)
+
+Generate SDK code samples in multiple languages.
+
+```bash
+skrypt sdk --openapi <spec> --output <dir>
+```
+
+### `skrypt mcp` (Pro)
+
+Start MCP server for AI tool integration.
+
+```bash
+skrypt mcp
+```
+
+---
+
+## Utility Commands
+
+### `skrypt i18n`
+
+Generate translations for documentation.
+
+```bash
+skrypt i18n --locales <codes>
+```
+
+### `skrypt llms-txt`
+
+Generate llms.txt for Answer Engine Optimization.
+
+```bash
+skrypt llms-txt --project-name <name>
+```
+
+### `skrypt gh-action`
+
+Generate GitHub Action workflow.
+
+```bash
+skrypt gh-action
+```
+
+### `skrypt cron`
+
+Set up automated doc updates.
+
+```bash
+skrypt cron
+```
+
+---
+
+## Authentication
+
+### `skrypt login`
+
+Authenticate with Skrypt Cloud.
+
+```bash
+skrypt login
+```
+
+### `skrypt logout`
+
+Clear local authentication.
+
+```bash
+skrypt logout
+```
+
+### `skrypt whoami`
+
+Show current authentication status.
+
+```bash
+skrypt whoami
+```

package/dist/template/src/app/docs/config/page.mdx

@@ -0,0 +1,428 @@
+## Functions
+
+### `findConfigFile`
+
+```typescript
+function findConfigFile(dir: string): string | null
+```
+
+Use this to locate a Skrypt configuration file by searching a directory for any of the supported config filenames (`.skrypt.yaml`, `.skrypt.yml`, `skrypt.yaml`, `skrypt.yml`).
+
+Returns the **full path** to the first matching config file found, or `null` if none exist in the given directory. Useful for resolving config before initializing your toolchain, or for validating that a project is properly configured.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ | Absolute or relative path to the directory to search for a config file |
+
+#### Returns
+
+| Value | When |
+|-------|------|
+| `string` | Full file path (e.g. `/projects/myapp/.skrypt.yaml`) when a config file is found |
+| `null` | No supported config filename exists in the given directory |
+
+**Example:**
+
+```typescript example.ts
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+// Supported config filenames (in priority order)
+const CONFIG_FILENAMES = ['.skrypt.yaml', '.skrypt.yml', 'skrypt.yaml', 'skrypt.yml']
+
+// Inline implementation of findConfigFile
+function findConfigFile(dir: string): string | null {
+  for (const filename of CONFIG_FILENAMES) {
+    const filepath = join(dir, filename)
+    if (existsSync(filepath)) {
+      return filepath
+    }
+  }
+  return null
+}
+
+// --- Usage Example ---
+
+// Search the current working directory for a config file
+const projectDir = process.env.PROJECT_DIR || process.cwd()
+
+try {
+  const configPath = findConfigFile(projectDir)
+
+  if (configPath) {
+    console.log('Config file found:', configPath)
+    // Output: Config file found: /projects/myapp/.skrypt.yaml
+  } else {
+    console.log('No config file found in:', projectDir)
+    // Output: No config file found in: /projects/myapp
+  }
+
+  // Common pattern: fall back to a default config location
+  const searchDirs = [
+    projectDir,
+    join(projectDir, 'config'),
+    process.env.HOME || '/tmp',
+  ]
+
+  const found = searchDirs.map(dir => ({
+    dir,
+    config: findConfigFile(dir),
+  }))
+
+  const firstMatch = found.find(entry => entry.config !== null)
+
+  if (firstMatch?.config) {
+    console.log('Using config from:', firstMatch.config)
+    // Output: Using config from: /projects/myapp/.skrypt.yaml
+  } else {
+    console.log('No config found in any search path — using defaults')
+  }
+} catch (error) {
+  console.error('Error while searching for config file:', error)
+}
+```
+
+### `loadConfig`
+
+```typescript
+function loadConfig(configPath?: string): Config
+```
+
+Use this to load a configuration file for autodocs, either from a specific path or by auto-discovering it from standard locations in your project.
+
+Searches for config files in common locations (e.g., `autodocs.config.yml`, `.autodocs.yml`) when no path is provided. Throws an error if an explicit path is given but the file does not exist.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `configPath` | `string` | No | Absolute or relative path to a YAML/JSON config file. If omitted, auto-discovery is used. |
+
+#### Returns
+
+Returns a `Config` object populated with values from the config file, merged with defaults for any missing fields.
+
+| Scenario | Result |
+|----------|--------|
+| `configPath` provided and file exists | `Config` loaded from that file |
+| `configPath` provided but file missing | Throws `Error: Config file not found: <path>` |
+| No `configPath`, file auto-discovered | `Config` loaded from discovered file |
+| No `configPath`, no file found | `Config` with default values |
+
+**Example:**
+
+```typescript example.ts
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+// --- Inline types (mirrors autodocs internals) ---
+type LLMProvider = 'openai' | 'anthropic' | 'gemini'
+
+interface Config {
+  provider: LLMProvider
+  model: string
+  outputDir: string
+  include: string[]
+  exclude: string[]
+  apiKey?: string
+}
+
+const DEFAULT_CONFIG: Config = {
+  provider: 'openai',
+  model: 'gpt-4o',
+  outputDir: './docs',
+  include: ['src/**/*.ts'],
+  exclude: ['**/*.test.ts'],
+}
+
+// --- Inline config search logic ---
+const SEARCH_PATHS = [
+  'autodocs.config.yml',
+  'autodocs.config.yaml',
+  '.autodocs.yml',
+  '.autodocs.yaml',
+  'autodocs.config.json',
+]
+
+function findConfigFile(): string | null {
+  for (const candidate of SEARCH_PATHS) {
+    const fullPath = join(process.cwd(), candidate)
+    if (existsSync(fullPath)) return fullPath
+  }
+  return null
+}
+
+function parseConfig(raw: string, filePath: string): Partial<Config> {
+  // Minimal parser: supports JSON only for this self-contained example
+  if (filePath.endsWith('.json')) {
+    return JSON.parse(raw) as Partial<Config>
+  }
+  // For YAML files, a real implementation would use js-yaml
+  throw new Error('YAML parsing requires js-yaml — use a .json config in this example')
+}
+
+// --- Self-contained loadConfig implementation ---
+function loadConfig(configPath?: string): Config {
+  let resolvedPath: string | null = null
+
+  if (configPath) {
+    if (!existsSync(configPath)) {
+      throw new Error(`Config file not found: ${configPath}`)
+    }
+    resolvedPath = configPath
+  } else {
+    resolvedPath = findConfigFile()
+  }
+
+  if (!resolvedPath) {
+    console.log('No config file found — using defaults.')
+    return { ...DEFAULT_CONFIG }
+  }
+
+  const raw = readFileSync(resolvedPath, 'utf-8')
+  const userConfig = parseConfig(raw, resolvedPath)
+
+  return { ...DEFAULT_CONFIG, ...userConfig }
+}
+
+// --- Usage examples ---
+async function main() {
+  try {
+    // Example 1: Auto-discover config
+    console.log('=== Auto-discovery ===')
+    const autoConfig = loadConfig()
+    console.log('Loaded config:', autoConfig)
+    // Output: Config with defaults (or merged values if a config file exists)
+
+    // Example 2: Explicit path
+    console.log('\n=== Explicit path ===')
+    const explicitConfig = loadConfig(
+      process.env.AUTODOCS_CONFIG || './autodocs.config.json'
+    )
+    console.log('Loaded config:', explicitConfig)
+    // Output: Config merged from the specified file + defaults
+
+  } catch (error) {
+    if (error instanceof Error) {
+      // Common case: explicit path was wrong
+      console.error('Failed to load config:', error.message)
+      // e.g. "Config file not found: ./autodocs.config.json"
+    }
+  }
+}
+
+main()
+```
+
+### `validateConfig`
+
+```typescript
+function validateConfig(config: Config): string[]
+```
+
+Use this to validate a configuration object before using it, catching all errors upfront instead of failing at runtime.
+
+Returns an array of error message strings — an empty array means the config is valid. Each string describes a specific validation failure, making it easy to surface all problems at once rather than one at a time.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| config | `Config` | ✅ | The configuration object to validate |
+
+### The `Config` Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| version | `number` | ✅ | Must be `1` — any other value produces a validation error |
+| ...other fields | `any` | varies | Additional fields validated by the function |
+
+#### Returns
+
+| Value | Meaning |
+|-------|---------|
+| `[]` (empty array) | Config is valid — safe to use |
+| `string[]` (non-empty) | One or more validation errors found — each string describes a problem |
+
+### Common Patterns
+
+```typescript
+const errors = validateConfig(config)
+
+// Guard pattern — stop early if invalid
+if (errors.length > 0) {
+  throw new Error(`Invalid config:\n${errors.join('\n')}`)
+}
+
+// Collect and display all errors
+errors.forEach(err => console.warn('Config error:', err))
+```
+
+**Example:**
+
+```typescript example.ts
+// Inline type definition — mirrors the real Config shape
+type LLMProvider = 'openai' | 'anthropic' | 'gemini'
+
+type Config = {
+  version: number
+  provider?: LLMProvider
+  apiKey?: string
+  outputDir?: string
+  license?: string
+}
+
+// Inline implementation — mirrors the real validation logic
+function validateConfig(config: Config): string[] {
+  const errors: string[] = []
+
+  if (config.version !== 1) {
+    errors.push(`Unsupported config version: ${config.version}`)
+  }
+
+  if (!config.provider) {
+    errors.push('Missing required field: provider')
+  }
+
+  if (!config.apiKey) {
+    errors.push('Missing required field: apiKey')
+  }
+
+  return errors
+}
+
+// --- Example usage ---
+
+const validConfig: Config = {
+  version: 1,
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY || 'sk-abc123xyz',
+  outputDir: './docs',
+  license: 'MIT'
+}
+
+const invalidConfig: Config = {
+  version: 2,           // wrong version
+  provider: undefined,  // missing provider
+  apiKey: undefined     // missing API key
+}
+
+function applyConfig(config: Config) {
+  try {
+    const errors = validateConfig(config)
+
+    if (errors.length > 0) {
+      // Surface ALL problems at once instead of failing one at a time
+      throw new Error(`Invalid configuration:\n  - ${errors.join('\n  - ')}`)
+    }
+
+    console.log('✅ Config is valid — proceeding with:', {
+      version: config.version,
+      provider: config.provider,
+      outputDir: config.outputDir ?? '(default)'
+    })
+  } catch (error) {
+    console.error('❌', (error as Error).message)
+  }
+}
+
+console.log('--- Valid config ---')
+applyConfig(validConfig)
+// Output:
+// ✅ Config is valid — proceeding with: { version: 1, provider: 'openai', outputDir: '(default)' }
+
+console.log('\n--- Invalid config ---')
+applyConfig(invalidConfig)
+// Output:
+// ❌ Invalid configuration:
+//   - Unsupported config version: 2
+//   - Missing required field: provider
+//   - Missing required field: apiKey
+```
+
+### `checkApiKey`
+
+```typescript
+function checkApiKey(provider: LLMProvider): { ok: boolean; envKey: string | null }
+```
+
+Use this to verify whether a required API key environment variable is set for a given LLM provider before making requests.
+
+Returns `{ ok: true }` for providers that don't require an API key (e.g., Ollama), and checks the appropriate environment variable for cloud providers (e.g., OpenAI, Anthropic). Use this at startup or before inference calls to give users clear, actionable feedback when credentials are missing.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `provider` | `LLMProvider` | ✅ | The LLM provider to check (e.g., `'openai'`, `'anthropic'`, `'ollama'`) |
+
+#### Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ok` | `boolean` | `true` if the API key is present or not required; `false` if a key is required but missing |
+| `envKey` | `string \| null` | The name of the environment variable checked (e.g., `'OPENAI_API_KEY'`), or `null` if no key is needed |
+
+### Behavior by Provider
+
+- **Providers requiring a key** (e.g., `openai`, `anthropic`): Returns `{ ok: false, envKey: 'OPENAI_API_KEY' }` when the variable is unset, or `{ ok: true, envKey: 'OPENAI_API_KEY' }` when it is set.
+- **Self-hosted providers** (e.g., `ollama`): Always returns `{ ok: true, envKey: null }` — no key needed.
+
+**Example:**
+
+```typescript example.ts
+// Inline types — do not import from autodocs
+type LLMProvider = 'openai' | 'anthropic' | 'ollama' | 'gemini'
+
+// Maps each provider to its required environment variable (null = no key needed)
+const PROVIDER_ENV_KEYS: Record<LLMProvider, string | null> = {
+  openai: 'OPENAI_API_KEY',
+  anthropic: 'ANTHROPIC_API_KEY',
+  gemini: 'GEMINI_API_KEY',
+  ollama: null, // self-hosted, no key required
+}
+
+// Inline implementation matching autodocs behavior
+function checkApiKey(provider: LLMProvider): { ok: boolean; envKey: string | null } {
+  const envKey = PROVIDER_ENV_KEYS[provider]
+
+  // Provider doesn't need an API key (e.g. Ollama)
+  if (!envKey) {
+    return { ok: true, envKey: null }
+  }
+
+  const ok = Boolean(process.env[envKey])
+  return { ok, envKey }
+}
+
+// --- Usage ---
+
+const providers: LLMProvider[] = ['openai', 'anthropic', 'ollama', 'gemini']
+
+for (const provider of providers) {
+  try {
+    const result = checkApiKey(provider)
+
+    if (!result.ok) {
+      console.warn(
+        `[${provider}] ❌ Missing API key — set the ${result.envKey} environment variable`
+      )
+    } else if (result.envKey === null) {
+      console.log(`[${provider}] ✅ No API key required (self-hosted)`)
+    } else {
+      console.log(`[${provider}] ✅ API key found in ${result.envKey}`)
+    }
+  } catch (error) {
+    console.error(`[${provider}] Failed to check API key:`, error)
+  }
+}
+
+// Example output (when only OPENAI_API_KEY is set):
+// [openai]    ✅ API key found in OPENAI_API_KEY
+// [anthropic] ❌ Missing API key — set the ANTHROPIC_API_KEY environment variable
+// [ollama]    ✅ No API key required (self-hosted)
+// [gemini]    ❌ Missing API key — set the GEMINI_API_KEY environment variable
+```
+