tissues 0.5.2 → 0.6.1

package/src/lib/ai/adapters/openai.js

@@ -0,0 +1,44 @@
+import { BaseAdapter } from './base.js'
+
+const DEFAULT_MODEL = 'gpt-4o-mini'
+const DEFAULT_MAX_TOKENS = 4096
+const API_URL = 'https://api.openai.com/v1/chat/completions'
+
+export class OpenAIAdapter extends BaseAdapter {
+  get name() {
+    return 'openai'
+  }
+
+  async complete(messages, opts = {}) {
+    const apiKey = this.config.apiKey
+    if (!apiKey) throw new Error('OpenAI API key not configured (ai.keys.openai)')
+
+    const model = opts.model || DEFAULT_MODEL
+    const maxTokens = opts.maxTokens || DEFAULT_MAX_TOKENS
+
+    const body = {
+      model,
+      max_tokens: maxTokens,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    }
+
+    const res = await fetch(API_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`OpenAI API error ${res.status}: ${this.sanitizeErrorBody(text)}`)
+    }
+
+    const data = await res.json()
+    const content = data.choices?.[0]?.message?.content
+    if (!content) throw new Error('OpenAI returned no content')
+    return content
+  }
+}

package/src/lib/ai/body-template.js

@@ -0,0 +1,75 @@
+/**
+ * Rich body section guidance for the pipeline `format` step.
+ *
+ * Provides the target structure that the LLM should produce when formatting
+ * an issue body. Sections are conditionally included based on what upstream
+ * pipeline steps produced.
+ */
+
+export const RICH_BODY_SECTIONS = [
+  { key: 'summary', heading: 'Summary', always: true },
+  { key: 'context', heading: 'Context', requires: 'structuredContext' },
+  { key: 'problem', heading: 'Problem', always: true },
+  { key: 'files', heading: 'Files Involved', requires: 'scopeAnalysis' },
+  { key: 'solution', heading: 'Proposed Solution', always: true },
+  { key: 'acceptance', heading: 'Acceptance Criteria', always: true },
+  { key: 'complexity', heading: 'Scope & Complexity', requires: 'complexity' },
+]
+
+/**
+ * Build a guidance string for the `format` step's system prompt.
+ *
+ * Only includes section headings for which upstream data exists (or that are
+ * always-on). This prevents the LLM from hallucinating sections it has no
+ * data for.
+ *
+ * @param {object} ctx - PipelineContext accumulated so far
+ * @returns {string} markdown-formatted guidance
+ */
+export function buildBodyGuidance(ctx) {
+  const lines = [
+    'Structure the issue body with these markdown sections:',
+    '',
+  ]
+
+  for (const section of RICH_BODY_SECTIONS) {
+    if (section.always || ctx[section.requires] != null) {
+      lines.push(`## ${section.heading}`)
+    }
+  }
+
+  // Include sections for custom enhancement results not covered above
+  const knownKeys = new Set([
+    'structuredContext', 'scopeAnalysis', 'complexity', 'complexityRationale',
+    'risk', 'riskRationale', 'aiLabels', 'dedupScore', 'body',
+    'rawInput', 'title', 'description', 'instructions', 'templateBody',
+    'labels', 'existingIssues', 'repoLabels', '_stepConfigs', 'triage',
+  ])
+  for (const [key, value] of Object.entries(ctx)) {
+    if (!knownKeys.has(key) && value != null && !key.startsWith('_')) {
+      // Custom enhancement produced a result — add a section hint
+      const heading = key.charAt(0).toUpperCase() + key.slice(1).replace(/([A-Z])/g, ' $1')
+      lines.push(`## ${heading}`)
+    }
+  }
+
+  lines.push(
+    '',
+    'Rules:',
+    '- Use bullet points for lists, not paragraphs.',
+    '- Keep each section concise (2-5 bullet points).',
+    '- If a section has no relevant information, omit it entirely.',
+    '- Return ONLY the markdown body — no preamble, no explanation, no code fences.',
+  )
+
+  if (ctx.complexity != null && ctx.risk != null) {
+    lines.push(
+      '',
+      'In the "Scope & Complexity" section, include:',
+      `- Complexity: ${ctx.complexity}/10 — ${ctx.complexityRationale || ''}`,
+      `- Risk: ${ctx.risk}/10 — ${ctx.riskRationale || ''}`,
+    )
+  }
+
+  return lines.join('\n')
+}

package/src/lib/ai/enhance.js

@@ -0,0 +1,107 @@
+/**
+ * Bridge between the create command and the pipeline runner.
+ *
+ * Sets up the PipelineContext, resolves routing, filters steps by config,
+ * and calls runPipeline.
+ */
+
+import { resolveRoute } from './router.js'
+import { runPipeline } from './pipeline.js'
+import { ALL_STEPS } from './steps.js'
+import { checkBudgets, recordUsage } from './index.js'
+import { loadAllEnhancements } from '../enhancements.js'
+import { enhancementToStep } from './enhancement-adapter.js'
+
+/**
+ * Run the full enhancement pipeline.
+ *
+ * @param {object} config - merged config
+ * @param {object} input - { title, description, instructions, templateBody, labels, existingIssues, repoLabels, rawInput }
+ * @param {object} [callbacks] - pipeline callbacks for progress display
+ * @param {{ provider?: string, model?: string, template?: string, enhancements?: string[] }} [routeContext] - routing context
+ * @returns {Promise<object>} PipelineContext with all accumulated results
+ */
+export async function runEnhancePipeline(config, input, callbacks, routeContext = {}) {
+  const ai = config.ai || {}
+  const budgets = ai.budgets || {}
+  const pipelineConfig = ai.pipeline || {}
+
+  // Resolve adapter + model
+  const route = resolveRoute(config, routeContext)
+
+  // Load all enhancements (three-tier: repo > user > built-in)
+  let enhancements
+  try {
+    enhancements = loadAllEnhancements(input._repoRoot)
+  } catch {
+    enhancements = null
+  }
+
+  let activeSteps
+  let stepConfigs = {}
+
+  if (enhancements && enhancements.length > 0) {
+    // Enhancement-based resolution
+    const enhancementNames = routeContext.enhancements || route.enhancements || null
+
+    // Build step configs from config (supports both old `steps` and new `enhancements` key)
+    const cfgEnhancements = pipelineConfig.enhancements || pipelineConfig.steps || {}
+
+    // Filter enhancements if specific names requested
+    let filtered = enhancements
+    if (enhancementNames && enhancementNames.length > 0) {
+      const requested = new Set(enhancementNames)
+      // Always include structural enhancements (triage, format)
+      filtered = enhancements.filter(
+        (enh) => enh.isStructural || requested.has(enh.key),
+      )
+    }
+
+    // Build step configs and convert to step objects
+    for (const enh of filtered) {
+      stepConfigs[enh.key] = cfgEnhancements[enh.key] || enh.mode || 'auto'
+    }
+
+    activeSteps = filtered
+      .filter((enh) => stepConfigs[enh.key] !== 'never')
+      .map((enh) => enhancementToStep(enh))
+  } else {
+    // Fallback: use hardcoded ALL_STEPS (backward compat)
+    const cfgSteps = pipelineConfig.steps || {}
+    for (const step of ALL_STEPS) {
+      stepConfigs[step.name] = cfgSteps[step.name] || 'auto'
+    }
+    activeSteps = ALL_STEPS.filter((s) => stepConfigs[s.name] !== 'never')
+  }
+
+  // Build the initial PipelineContext
+  const ctx = {
+    // Input data
+    rawInput: input.rawInput || '',
+    title: input.title,
+    description: input.description || '',
+    instructions: input.instructions || '',
+    templateBody: input.templateBody || '',
+    labels: input.labels || [],
+    existingIssues: input.existingIssues || [],
+    repoLabels: input.repoLabels || [],
+
+    // Step config (internal)
+    _stepConfigs: stepConfigs,
+
+    // Accumulated results — steps populate these
+    dedupScore: null,
+    structuredContext: null,
+    scopeAnalysis: null,
+    complexity: null,
+    complexityRationale: null,
+    risk: null,
+    riskRationale: null,
+    aiLabels: null,
+    body: input.templateBody || '', // fallback to template
+  }
+
+  await runPipeline(activeSteps, ctx, route, config, budgets, callbacks, { checkBudgets, recordUsage })
+
+  return ctx
+}

package/src/lib/ai/enhancement-adapter.js

@@ -0,0 +1,109 @@
+/**
+ * Bridge between enhancement descriptors and pipeline step objects.
+ *
+ * Converts enhancement descriptors (from enhancements.js) into step objects
+ * that pipeline.js can execute. Built-in steps retain their specialized
+ * shouldRun/parseResponse logic; custom steps get generic implementations.
+ */
+
+import { BUILT_IN_STEPS_MAP, tryParseJSON, contextSummary, priorStepsSummary } from './steps.js'
+import { buildBodyGuidance } from './body-template.js'
+
+/**
+ * Convert an enhancement descriptor into a pipeline step object.
+ *
+ * @param {object} enhancement - descriptor from enhancements.js
+ * @returns {object} step object compatible with pipeline.js
+ */
+export function enhancementToStep(enhancement) {
+  const builtInStep = BUILT_IN_STEPS_MAP[enhancement.key]
+
+  // If this is a built-in enhancement, use the built-in step's specialized
+  // shouldRun and parseResponse, but allow the prompt to be overridden
+  if (builtInStep) {
+    const promptOverridden = enhancement.source && enhancement.source !== 'built-in'
+
+    return {
+      name: enhancement.key,
+      displayName: enhancement.name,
+      maxTokens: enhancement.maxTokens,
+      provider: enhancement.provider || null,
+
+      shouldRun: builtInStep.shouldRun,
+      parseResponse: builtInStep.parseResponse,
+
+      buildMessages(ctx) {
+        if (promptOverridden && enhancement.prompt) {
+          // Use the user/repo-overridden prompt with the standard user message
+          return buildCustomMessages(enhancement, ctx)
+        }
+        return builtInStep.buildMessages(ctx)
+      },
+    }
+  }
+
+  // Custom enhancement — generic implementation
+  return {
+    name: enhancement.key,
+    displayName: enhancement.name,
+    maxTokens: enhancement.maxTokens,
+    provider: enhancement.provider || null,
+
+    shouldRun(ctx) {
+      // Check requires — all required context keys must be present
+      if (enhancement.requires?.length > 0) {
+        return enhancement.requires.every((key) => ctx[key] != null)
+      }
+      return true
+    },
+
+    buildMessages(ctx) {
+      return buildCustomMessages(enhancement, ctx)
+    },
+
+    parseResponse(raw, ctx) {
+      if (enhancement.format === 'json') {
+        try {
+          const parsed = tryParseJSON(raw)
+          ctx[enhancement.contextKey] = parsed
+        } catch {
+          ctx[enhancement.contextKey] = null
+        }
+      } else {
+        // markdown — store raw text
+        let cleaned = raw.trim()
+        const fenceMatch = cleaned.match(/^```(?:markdown|md)?\n([\s\S]*)\n```$/)
+        if (fenceMatch) cleaned = fenceMatch[1].trim()
+        if (cleaned.length > 0) {
+          ctx[enhancement.contextKey] = cleaned
+        }
+      }
+    },
+  }
+}
+
+/**
+ * Build messages for a custom or prompt-overridden enhancement.
+ */
+function buildCustomMessages(enhancement, ctx) {
+  let systemContent = enhancement.prompt
+
+  // For the format step, append body guidance
+  if (enhancement.key === 'format') {
+    const guidance = buildBodyGuidance(ctx)
+    systemContent = systemContent + '\n\n' + guidance
+  }
+
+  // For the labels step, inject available labels
+  if (enhancement.key === 'labels' && ctx.repoLabels?.length) {
+    systemContent = systemContent.replace(
+      /Return ONLY valid JSON\.$/m,
+      `Available labels in this repo: ${ctx.repoLabels.join(', ')}\nReturn ONLY valid JSON.`,
+    )
+  }
+
+  return [
+    { role: 'system', content: systemContent },
+    { role: 'user', content: contextSummary(ctx) + priorStepsSummary(ctx) },
+  ]
+}

package/src/lib/ai/index.js

@@ -0,0 +1,122 @@
+import { resolveRoute, resolveProviderAdapter, listProviders, listAllProviders } from './router.js'
+import { buildMessages } from './prompt.js'
+
+export { listProviders, listAllProviders, resolveProviderAdapter }
+
+// ---------------------------------------------------------------------------
+// Token usage tracking (in-memory, resets on process exit)
+// ---------------------------------------------------------------------------
+
+const tokenLog = []
+
+export function recordUsage(tokens) {
+  tokenLog.push({ tokens, timestamp: Date.now() })
+}
+
+function getUsage(windowMs) {
+  const cutoff = Date.now() - windowMs
+  return tokenLog
+    .filter((e) => e.timestamp >= cutoff)
+    .reduce((sum, e) => sum + e.tokens, 0)
+}
+
+/**
+ * Check token budgets before making a request.
+ * Throws if a budget would be exceeded.
+ */
+export function checkBudgets(budgets, requestTokens) {
+  if (!budgets) return
+
+  if (budgets.maxTokensPerRequest && requestTokens > budgets.maxTokensPerRequest) {
+    throw new Error(
+      `Token budget: request (${requestTokens}) exceeds per-request limit (${budgets.maxTokensPerRequest})`,
+    )
+  }
+
+  if (budgets.maxTokensPerHour) {
+    const hourlyUsed = getUsage(60 * 60 * 1000)
+    if (hourlyUsed + requestTokens > budgets.maxTokensPerHour) {
+      throw new Error(
+        `Token budget: hourly usage (${hourlyUsed} + ${requestTokens}) would exceed limit (${budgets.maxTokensPerHour})`,
+      )
+    }
+  }
+
+  if (budgets.maxTokensPerDay) {
+    const dailyUsed = getUsage(24 * 60 * 60 * 1000)
+    if (dailyUsed + requestTokens > budgets.maxTokensPerDay) {
+      throw new Error(
+        `Token budget: daily usage (${dailyUsed} + ${requestTokens}) would exceed limit (${budgets.maxTokensPerDay})`,
+      )
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if AI enhancement is available (enabled + key configured).
+ *
+ * @param {object} config - merged config
+ * @param {{ provider?: string }} [context]
+ * @returns {boolean}
+ */
+export function checkAvailable(config, context = {}) {
+  const ai = config.ai || {}
+  if (!ai.enabled) return false
+  try {
+    const { adapter } = resolveRoute(config, context)
+    return adapter.isConfigured()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Enhance an issue body using AI.
+ *
+ * @param {object} config - merged config
+ * @param {string} title - issue title
+ * @param {string} description - actual issue content
+ * @param {string} templateBody - already-rendered template
+ * @param {string} [instructions] - optional AI guidance
+ * @param {{ template?: string, labels?: string[], provider?: string, model?: string }} [context] - routing context
+ * @returns {Promise<string>} enhanced body
+ */
+export async function enhance(config, title, description, templateBody, instructions, context = {}) {
+  const ai = config.ai || {}
+  const budgets = ai.budgets || {}
+  const { adapter, model } = resolveRoute(config, context)
+  const messages = buildMessages(title, description, templateBody, instructions)
+
+  // Enforce per-request cap: clamp maxTokens to budget
+  const requestMax = budgets.maxTokensPerRequest || 4096
+
+  // Check rolling budgets before the call
+  checkBudgets(budgets, requestMax)
+
+  let result = await adapter.complete(messages, { model, maxTokens: requestMax })
+
+  // Strip wrapping code fences (```markdown ... ```) that LLMs often add
+  const fenceMatch = result.match(/^```(?:markdown|md)?\n([\s\S]*)\n```$/)
+  if (fenceMatch) result = fenceMatch[1].trim()
+
+  // Record approximate usage (response length in chars / 4 is a rough token estimate)
+  const approxTokens = Math.ceil(result.length / 4)
+  recordUsage(approxTokens)
+
+  return result
+}
+
+/**
+ * Get current token usage stats.
+ * @returns {{ hourly: number, daily: number }}
+ */
+export function getTokenUsage() {
+  return {
+    hourly: getUsage(60 * 60 * 1000),
+    daily: getUsage(24 * 60 * 60 * 1000),
+  }
+}

package/src/lib/ai/pipeline.js

@@ -0,0 +1,97 @@
+/**
+ * Pipeline runner for multi-step AI issue enhancement.
+ *
+ * Executes steps sequentially, accumulating state in a shared PipelineContext.
+ * Failed steps log a warning and continue (graceful degradation).
+ */
+
+import { resolveProviderAdapter } from './router.js'
+
+/**
+ * Run a sequence of pipeline steps.
+ *
+ * @param {object[]} steps - array of step objects (from steps.js)
+ * @param {object} ctx - mutable PipelineContext, accumulates results
+ * @param {{ adapter: object, model: string }} route - resolved adapter + model
+ * @param {object} [config] - merged config object (enables per-step provider overrides)
+ * @param {object} [budgets] - token budget config
+ * @param {object} [callbacks] - { onStepStart, onStepDone, onStepSkip, onStepFail }
+ * @param {{ checkBudgets: Function, recordUsage: Function }} [budgetHelpers]
+ * @returns {Promise<object>} the final ctx
+ */
+export async function runPipeline(steps, ctx, route, config, budgets, callbacks, budgetHelpers) {
+  const { adapter: defaultAdapter, model: defaultModel } = route
+  const cb = callbacks || {}
+  const { checkBudgets, recordUsage } = budgetHelpers || {}
+
+  let budgetExhausted = false
+
+  for (const step of steps) {
+    // If budget was exhausted, skip all remaining steps except format (which degrades gracefully)
+    if (budgetExhausted && step.name !== 'format') {
+      cb.onStepSkip?.(step, 'budget exhausted')
+      continue
+    }
+
+    // Check shouldRun
+    const stepConfig = ctx._stepConfigs?.[step.name] || 'auto'
+    if (stepConfig === 'never') {
+      cb.onStepSkip?.(step, 'disabled')
+      continue
+    }
+    if (stepConfig === 'auto' && !step.shouldRun(ctx)) {
+      cb.onStepSkip?.(step, 'auto-skipped')
+      continue
+    }
+
+    cb.onStepStart?.(step)
+
+    // Resolve per-step adapter override
+    let adapter = defaultAdapter
+    let model = defaultModel
+    if (step.provider && config) {
+      try {
+        const override = resolveProviderAdapter(config, step.provider)
+        adapter = override.adapter
+        model = override.model
+      } catch (err) {
+        // Unknown/unconfigured provider — warn and fall back to default
+        cb.onStepFail?.(step, new Error(`Provider override "${step.provider}" failed: ${err.message}, using default`))
+        // Continue with default adapter (don't skip — aligns with "never lose data" principle)
+      }
+    }
+
+    try {
+      // Check budget before the call (skip for format when budget already exhausted — it degrades gracefully)
+      if (checkBudgets && budgets && !budgetExhausted) {
+        try {
+          checkBudgets(budgets, step.maxTokens)
+        } catch {
+          budgetExhausted = true
+          cb.onStepFail?.(step, new Error('Token budget exceeded'))
+          continue
+        }
+      }
+
+      // Build messages and call the adapter
+      const messages = step.buildMessages(ctx)
+      const raw = await adapter.complete(messages, { model, maxTokens: step.maxTokens })
+
+      // Record approximate usage
+      if (recordUsage) {
+        const approxTokens = Math.ceil(raw.length / 4)
+        recordUsage(approxTokens)
+      }
+
+      // Parse response and update context
+      step.parseResponse(raw, ctx)
+
+      cb.onStepDone?.(step, ctx)
+    } catch (err) {
+      cb.onStepFail?.(step, err)
+      // Non-fatal — continue to next step
+    }
+  }
+
+  return ctx
+}

package/src/lib/ai/prompt.js

@@ -0,0 +1,39 @@
+/**
+ * Build messages array for AI enhancement of an issue body.
+ *
+ * @param {string} title - issue title
+ * @param {string} description - actual issue content (what the issue is about)
+ * @param {string} templateBody - already-rendered template body
+ * @param {string} [instructions] - optional AI prompt guidance (not issue content)
+ * @returns {Array<{ role: 'system'|'user', content: string }>}
+ */
+export function buildMessages(title, description, templateBody, instructions) {
+  const systemContent = [
+    'You are an expert at writing clear, well-structured GitHub issues.',
+    'Given an issue title, description, and a rendered template, improve the issue body.',
+    'Fill in template sections with relevant detail inferred from the title and description.',
+    'Keep the markdown structure intact. Be concise and actionable.',
+    'Return ONLY the improved issue body markdown — no preamble, no explanation, no code fences.',
+  ]
+  if (instructions) {
+    systemContent.push('', 'Additional instructions from the user:', instructions)
+  }
+
+  const userContent = [
+    `Title: ${title}`,
+    '',
+    description ? `Description: ${description}` : '',
+    '',
+    'Template body to improve:',
+    '```',
+    templateBody,
+    '```',
+  ]
+    .filter((line) => line !== undefined)
+    .join('\n')
+
+  return [
+    { role: 'system', content: systemContent.join('\n') },
+    { role: 'user', content: userContent },
+  ]
+}