skrypt-ai 0.7.0 → 0.8.0

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

@@ -1,86 +0,0 @@
----
-title: Configuration
-description: Configure Skrypt with skrypt.config.yaml
----
-
-Configure Skrypt behavior with a `skrypt.config.yaml` file.
-
-## Basic Configuration
-
-```yaml
-source: ./src
-output: ./docs/src/app/docs
-provider: openai
-model: gpt-4o
-```
-
-## Full Reference
-
-```yaml
-output: ./docs
-
-model: gpt-4o             # Model name
-baseUrl: null             # Custom API URL (for Ollama/proxies)
-
-  publicOnly: true        # Only document exported/public APIs
-  multiLang: false        # Generate TypeScript + Python examples
-  byTopic: false          # Organize by topic instead of file structure
-  llmsTxt: true           # Generate llms.txt for AEO
-  projectName: "My Project"
-
-  - "**/*.test.ts"
-  - "**/__tests__/**"
-  - "name:internal*"
-  - "name:_*"
-
-```
-
-## Environment Variables
-
-```bash
-export OPENAI_API_KEY=sk-...
-export ANTHROPIC_API_KEY=sk-ant-...
-export DEEPSEEK_API_KEY=sk-...
-```
-
-## Provider Examples
-
-### OpenAI
-
-```yaml
-provider: openai
-model: gpt-4o
-```
-
-### Anthropic
-
-```yaml
-provider: anthropic
-model: claude-sonnet-4-6
-```
-
-### Ollama (Local)
-
-```yaml
-provider: ollama
-model: llama3.2
-baseUrl: http://localhost:11434
-```
-
-## Exclusion Patterns
-
-### File Patterns
-
-```yaml
-exclude:
-  - "**/*.test.ts"
-  - "**/internal/**"
-```
-
-### Name Patterns
-
-```yaml
-exclude:
-  - "name:_*"           # Private
-  - "name:internal*"    # Internal functions
-```

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

@@ -1,112 +0,0 @@
----
-title: Deployment Guide
-description: Deploy your Skrypt documentation site
----
-
-## Quick Deploy (Skrypt Cloud)
-
-```bash
-skrypt deploy
-```
-
-Your docs will be live at `https://your-project.skrypt.sh`.
-
-## Self-Hosted Setup
-
-### Prerequisites
-
-- Node.js 18+
-- Supabase account
-- Cloudflare account
-- Vercel account
-
-### 1. Clone and Install
-
-```bash
-git clone https://github.com/debgotwired/skrypt
-cd skrypt
-npm install
-npm run build
-```
-
-### 2. Supabase Setup
-
-```bash
-cd landing
-npx supabase login
-npx supabase link --project-ref YOUR_PROJECT_REF
-npx supabase db push
-```
-
-### 3. Environment Variables
-
-Create `.env.local`:
-
-```bash
-NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
-SUPABASE_SERVICE_ROLE_KEY=eyJ...
-
-STRIPE_SECRET_KEY=sk_live_...
-OPENAI_API_KEY=sk-...
-
-NEXT_PUBLIC_APP_URL=https://skrypt.sh
-```
-
-### 4. Deploy Landing
-
-```bash
-cd landing
-vercel
-```
-
-### 5. Cloudflare Pages
-
-For user docs hosting:
-
-1. Create Cloudflare Pages project
-2. Configure wildcard DNS: `*.skrypt.sh`
-
-### 6. Stripe Webhooks
-
-URL: `https://skrypt.sh/api/webhooks/stripe`
-
-Events:
-- `checkout.session.completed`
-- `customer.subscription.updated`
-- `customer.subscription.deleted`
-
----
-
-## CLI Installation
-
-### npm
-
-```bash
-npm install -g skrypt-ai
-```
-
-### Homebrew
-
-```bash
-brew tap debgotwired/tap
-brew install skrypt
-```
-
----
-
-## Troubleshooting
-
-### "API_KEY required"
-
-```bash
-export OPENAI_API_KEY=sk-...
-```
-
-### Build Errors
-
-```bash
-rm -rf node_modules
-npm install
-npm run build
-```

package/dist/template/src/app/docs/generator/generator.md

@@ -1,504 +0,0 @@
-# Generator.ts
-
-## Functions
-
-### `generateForElement`
-
-```typescript
-async function generateForElement(element: APIElement, client: LLMClient, options: GenerationOptions, onProgress?: (progress: GenerationProgress) => void): Promise<GeneratedDoc>
-```
-
-Use this to generate documentation for a single API element using an LLM client, without running any test validation on the output.
-
-This is the core documentation generation function — pass it a parsed API element (function, class, type, etc.), an LLM client, and generation options to receive structured documentation. Optionally track progress in real time via the `onProgress` callback.
-
-## Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `element` | `APIElement` | ✅ | The parsed API element to document (function, class, interface, etc.) |
-| `client` | `LLMClient` | ✅ | Configured LLM client used to generate the documentation |
-| `options` | `GenerationOptions` | ✅ | Controls generation behavior: model, style, language, max tokens, etc. |
-| `onProgress` | `(progress: GenerationProgress) => void` | ❌ | Optional callback invoked during generation to report progress stages |
-
-## Returns
-
-Returns a `Promise<GeneratedDoc>` that resolves to a structured documentation object containing:
-
-| Field | Description |
-|-------|-------------|
-| `markdown` | The generated documentation as a markdown string |
-| `element` | Reference back to the source `APIElement` |
-| `metadata` | Generation metadata (model used, token counts, timestamp) |
-
-Rejects with an error if the LLM client fails or the element cannot be processed.
-
-**Example:**
-
-```typescript example.ts
-// ─── Inline type definitions (no external imports needed) ───────────────────
-
-type APIElement = {
-  name: string
-  kind: 'function' | 'class' | 'interface' | 'type'
-  signature: string
-  docstring?: string
-  filePath: string
-}
-
-type GenerationOptions = {
-  model: string
-  style: 'concise' | 'detailed'
-  language: 'typescript' | 'javascript'
-  maxTokens?: number
-}
-
-type GenerationProgress = {
-  stage: 'preparing' | 'generating' | 'formatting' | 'complete'
-  percentComplete: number
-  message: string
-}
-
-type GeneratedDoc = {
-  markdown: string
-  element: APIElement
-  metadata: {
-    model: string
-    tokensUsed: number
-    generatedAt: string
-  }
-}
-
-type LLMClient = {
-  apiKey: string
-  baseUrl: string
-  complete: (prompt: string, maxTokens: number) => Promise<string>
-}
-
-// ─── Simulated implementations ───────────────────────────────────────────────
-
-function createLLMClient(apiKey: string): LLMClient {
-  return {
-    apiKey,
-    baseUrl: 'https://api.openai.com/v1',
-    complete: async (prompt: string, maxTokens: number): Promise<string> => {
-      // Simulates an LLM response for demonstration
-      return `Use this to calculate the total price including tax.\n\n**Parameters:**\n- \`price\`: number — base price\n- \`taxRate\`: number — tax rate as a decimal\n\n**Returns:** \`number\` — final price with tax applied`
-    }
-  }
-}
-
-async function generateForElement(
-  element: APIElement,
-  client: LLMClient,
-  options: GenerationOptions,
-  onProgress?: (progress: GenerationProgress) => void
-): Promise<GeneratedDoc> {
-  const reportProgress = (stage: GenerationProgress['stage'], percent: number, message: string) => {
-    onProgress?.({ stage, percentComplete: percent, message })
-  }
-
-  reportProgress('preparing', 10, `Preparing context for "${element.name}"`)
-  await new Promise(r => setTimeout(r, 50)) // simulate async work
-
-  reportProgress('generating', 40, `Sending "${element.name}" to ${options.model}`)
-  const prompt = `Generate ${options.style} documentation for:\n${element.signature}`
-  const rawDoc = await client.complete(prompt, options.maxTokens ?? 1024)
-
-  reportProgress('formatting', 80, 'Formatting output')
-  await new Promise(r => setTimeout(r, 30))
-
-  reportProgress('complete', 100, 'Documentation generated successfully')
-
-  return {
-    markdown: rawDoc,
-    element,
-    metadata: {
-      model: options.model,
-      tokensUsed: rawDoc.split(' ').length * 2, // rough estimate for demo
-      generatedAt: new Date().toISOString()
-    }
-  }
-}
-
-// ─── Usage example ────────────────────────────────────────────────────────────
-
-const apiElement: APIElement = {
-  name: 'calculateTotalPrice',
-  kind: 'function',
-  signature: 'function calculateTotalPrice(price: number, taxRate: number): number',
-  docstring: 'Calculates the total price including tax.',
-  filePath: 'src/pricing/utils.ts'
-}
-
-const client = createLLMClient(process.env.OPENAI_API_KEY || 'sk-your-api-key-here')
-
-const options: GenerationOptions = {
-  model: 'gpt-4o',
-  style: 'detailed',
-  language: 'typescript',
-  maxTokens: 512
-}
-
-async function main() {
-  try {
-    console.log(`Generating docs for: ${apiElement.name}\n`)
-
-    const doc = await generateForElement(
-      apiElement,
-      client,
-      options,
-      (progress: GenerationProgress) => {
-        console.log(`[${progress.percentComplete}%] ${progress.stage}: ${progress.message}`)
-      }
-    )
-
-    console.log('\n─── Generated Documentation ───────────────────────────')
-    console.log(doc.markdown)
-    console.log('\n─── Metadata ──────────────────────────────────────────')
-    console.log(`Model:        ${doc.metadata.model}`)
-    console.log(`Tokens used:  ${doc.metadata.tokensUsed}`)
-    console.log(`Generated at: ${doc.metadata.generatedAt}`)
-
-    // Expected output:
-    // [10%] preparing: Preparing context for "calculateTotalPrice"
-    // [40%] generating: Sending "calculateTotalPrice" to gpt-4o
-    // [80%] formatting: Formatting output
-    // [100%] complete: Documentation generated successfully
-    //
-    // ─── Generated Documentation ───
-    // Use this to calculate the total price including tax.
-    // ...
-  } catch (error) {
-    console.error('Documentation generation failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-### `generateForElements`
-
-```typescript
-async function generateForElements(elements: APIElement[], client: LLMClient, options: GenerationOptions): Promise<GeneratedDoc[]>
-```
-
-Use this to batch-generate documentation for multiple API elements in a single call, processing an entire scanned API surface and returning structured docs for each element.
-
-This is the primary entry point for bulk documentation generation — pass in your parsed API elements, an LLM client, and generation options to get back a full array of generated documentation objects.
-
-## Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `elements` | `APIElement[]` | Yes | Array of parsed API elements (functions, classes, types, etc.) to generate docs for |
-| `client` | `LLMClient` | Yes | Configured LLM client used to generate the documentation content |
-| `options` | `GenerationOptions` | Yes | Controls generation behavior: model selection, output format, concurrency, etc. |
-
-## Returns
-
-Returns `Promise<GeneratedDoc[]>` — resolves to an array of generated documentation objects, one per input element, in the same order as the input `elements` array.
-
-| Scenario | Result |
-|----------|--------|
-| All elements processed successfully | Array of `GeneratedDoc` objects with markdown/content for each element |
-| Empty `elements` array | Resolves to `[]` |
-| LLM client error on an element | Rejects or returns partial results depending on `options.onError` strategy |
-
-**Example:**
-
-```typescript example.ts
-// ─── Inline type definitions (no external imports needed) ───────────────────
-
-type APIElement = {
-  name: string
-  kind: 'function' | 'class' | 'type' | 'interface' | 'variable'
-  signature: string
-  docstring?: string
-  filePath: string
-}
-
-type GeneratedDoc = {
-  elementName: string
-  kind: APIElement['kind']
-  markdown: string
-  generatedAt: Date
-}
-
-type GenerationOptions = {
-  model?: string
-  maxConcurrency?: number
-  outputFormat?: 'markdown' | 'html'
-  onError?: 'skip' | 'throw'
-}
-
-type LLMClient = {
-  apiKey: string
-  baseUrl: string
-  complete: (prompt: string) => Promise<string>
-}
-
-// ─── Simulated implementation of generateForElements ────────────────────────
-
-async function generateForElements(
-  elements: APIElement[],
-  client: LLMClient,
-  options: GenerationOptions
-): Promise<GeneratedDoc[]> {
-  const {
-    maxConcurrency = 3,
-    outputFormat = 'markdown',
-    onError = 'skip',
-  } = options
-
-  const results: GeneratedDoc[] = []
-
-  // Process in batches to respect maxConcurrency
-  for (let i = 0; i < elements.length; i += maxConcurrency) {
-    const batch = elements.slice(i, i + maxConcurrency)
-
-    const batchResults = await Promise.allSettled(
-      batch.map(async (element) => {
-        const prompt = `Generate ${outputFormat} documentation for: ${element.signature}`
-
-        try {
-          const content = await client.complete(prompt)
-          return {
-            elementName: element.name,
-            kind: element.kind,
-            markdown: content,
-            generatedAt: new Date(),
-          } satisfies GeneratedDoc
-        } catch (err) {
-          if (onError === 'throw') throw err
-          console.warn(`Skipping ${element.name} due to error:`, err)
-          return null
-        }
-      })
-    )
-
-    for (const result of batchResults) {
-      if (result.status === 'fulfilled' && result.value !== null) {
-        results.push(result.value)
-      }
-    }
-  }
-
-  return results
-}
-
-// ─── Simulated LLM client (replace complete() with real API call) ────────────
-
-function createLLMClient(apiKey: string): LLMClient {
-  return {
-    apiKey,
-    baseUrl: 'https://api.openai.com/v1',
-    complete: async (prompt: string): Promise<string> => {
-      // Simulate LLM latency
-      await new Promise((r) => setTimeout(r, 50))
-      return `**Auto-generated doc**\n\nPrompt received: "${prompt.slice(0, 60)}..."`
-    },
-  }
-}
-
-// ─── Example usage ───────────────────────────────────────────────────────────
-
-const elements: APIElement[] = [
-  {
-    name: 'fetchUser',
-    kind: 'function',
-    signature: 'async function fetchUser(id: string): Promise<User>',
-    docstring: 'Fetches a user by ID',
-    filePath: 'src/api/users.ts',
-  },
-  {
-    name: 'UserService',
-    kind: 'class',
-    signature: 'class UserService { constructor(db: Database) }',
-    filePath: 'src/services/UserService.ts',
-  },
-  {
-    name: 'UserRole',
-    kind: 'type',
-    signature: "type UserRole = 'admin' | 'editor' | 'viewer'",
-    filePath: 'src/types/roles.ts',
-  },
-]
-
-const client = createLLMClient(process.env.LLM_API_KEY || 'sk-your-api-key-here')
-
-const options: GenerationOptions = {
-  model: 'gpt-4o',
-  maxConcurrency: 2,
-  outputFormat: 'markdown',
-  onError: 'skip',
-}
-
-async function main() {
-  try {
-    console.log(`Generating docs for ${elements.length} elements...\n`)
-
-    const docs = await generateForElements(elements, client, options)
-
-    console.log(`✅ Generated ${docs.length} documentation entries:\n`)
-
-    for (const doc of docs) {
-      console.log(`─── ${doc.elementName} (${doc.kind}) ───`)
-      console.log(doc.markdown)
-      console.log(`Generated at: ${doc.generatedAt.toISOString()}\n`)
-    }
-
-    // Expected output:
-    // ✅ Generated 3 documentation entries:
-    // ─── fetchUser (function) ───
-    // **Auto-generated doc**
-    // Prompt received: "Generate markdown documentation for: async function fe..."
-    // Generated at: 2024-11-15T10:23:45.123Z
-    // ... (one entry per element)
-  } catch (error) {
-    console.error('Documentation generation failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-### `formatAsMarkdown`
-
-```typescript
-function formatAsMarkdown(docs: GeneratedDoc[], title: string): string
-```
-
-Use this to convert an array of generated documentation objects into a formatted Markdown string, ready to write to a `.md` file or display in a docs site.
-
-Takes structured doc data (functions, classes, methods) and a page title, and returns a complete Markdown document with sections organized by element type.
-
-## Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `docs` | `GeneratedDoc[]` | ✅ | Array of generated documentation objects, each containing an element descriptor and its rendered doc content |
-| `title` | `string` | ✅ | The top-level heading for the Markdown document (rendered as `# title`) |
-
-## Returns
-
-A `string` containing the full Markdown file content, with:
-- A `# Title` heading at the top
-- Sections grouped by element kind: **Functions**, **Classes**, and **Methods**
-- Each doc entry rendered under its appropriate section
-
----MARKDOWN---
-
-**Example:**
-
-```typescript example.ts
-// ---- Inline types (mirrors the real GeneratedDoc / APIElement shape) ----
-type ElementKind = 'function' | 'class' | 'method'
-
-interface APIElement {
-  name: string
-  kind: ElementKind
-  signature?: string
-}
-
-interface GeneratedDoc {
-  element: APIElement
-  documentation: string
-}
-
-// ---- Inline implementation of formatAsMarkdown ----
-function formatAsMarkdown(docs: GeneratedDoc[], title: string): string {
-  let content = `# ${title}\n\n`
-
-  const functions = docs.filter(d => d.element.kind === 'function')
-  const classes   = docs.filter(d => d.element.kind === 'class')
-  const methods   = docs.filter(d => d.element.kind === 'method')
-
-  function renderSection(heading: string, items: GeneratedDoc[]): string {
-    if (items.length === 0) return ''
-    let section = `## ${heading}\n\n`
-    for (const doc of items) {
-      section += `### \`${doc.element.name}\`\n\n`
-      if (doc.element.signature) {
-        section += `\`\`\`ts\n${doc.element.signature}\n\`\`\`\n\n`
-      }
-      section += `${doc.documentation}\n\n`
-    }
-    return section
-  }
-
-  content += renderSection('Functions', functions)
-  content += renderSection('Classes', classes)
-  content += renderSection('Methods', methods)
-
-  return content.trimEnd() + '\n'
-}
-
-// ---- Realistic sample data ----
-const sampleDocs: GeneratedDoc[] = [
-  {
-    element: {
-      name: 'fetchUser',
-      kind: 'function',
-      signature: 'function fetchUser(id: string): Promise<User>',
-    },
-    documentation:
-      'Fetches a user record by ID from the remote API. Throws `NotFoundError` if the user does not exist.',
-  },
-  {
-    element: {
-      name: 'UserService',
-      kind: 'class',
-      signature: 'class UserService',
-    },
-    documentation:
-      'Provides high-level methods for managing user accounts, including creation, updates, and deletion.',
-  },
-  {
-    element: {
-      name: 'UserService.update',
-      kind: 'method',
-      signature: 'update(id: string, patch: Partial<User>): Promise<User>',
-    },
-    documentation:
-      'Applies a partial update to an existing user. Returns the updated user object.',
-  },
-]
-
-// ---- Run the example ----
-try {
-  const markdown = formatAsMarkdown(sampleDocs, 'API Reference')
-  console.log(markdown)
-  /*
-  Expected output:
-  ─────────────────────────────────────────
-  # API Reference
-
-  ## Functions
-
-  ### `fetchUser`
-
-  ```ts
-  function fetchUser(id: string): Promise<User>
-  ```
-
-  Fetches a user record by ID from the remote API. Throws `NotFoundError` if the user does not exist.
-
-  ## Classes
-
-  ### `UserService`
-  ...
-
-  ## Methods
-
-  ### `UserService.update`
-  ...
-  ─────────────────────────────────────────
-  */
-} catch (error) {
-  console.error('formatAsMarkdown failed:', error)
-}
-```
-