pantheon-opencode 1.0.0

package/scripts/install/agents-md.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * agents-md.mjs — Dynamic AGENTS.md generator from canonical agent frontmatter
+ *
+ * Reads all agents/*.agent.md files, extracts name + description from frontmatter,
+ * and generates AGENTS.md content dynamically. Eliminates hardcoded agent tables
+ * in platform installers (claude.mjs, cursor.mjs, windsurf.mjs, cline.mjs, etc.).
+ *
+ * Usage (CLI):
+ *   node agents-md.mjs                      # write AGENTS.md to cwd
+ *   node agents-md.mjs /target/dir          # write AGENTS.md to target dir
+ *   node agents-md.mjs /target/dir "Claude" # with platform name
+ *
+ * Usage (import):
+ *   import { readCanonicalAgents, generateAgentsMd } from './agents-md.mjs';
+ *   const agents = readCanonicalAgents();
+ *   const md = generateAgentsMd(agents, 'Claude Code', extraSections);
+ *   writeFileSync('/path/AGENTS.md', md);
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const ROOT = join(__dirname, '..', '..')
+export const AGENTS_DIR = join(ROOT, 'src', 'agents')
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML frontmatter from an agent markdown file content.
+ *
+ * @param {string} content - Raw content of a .agent.md file
+ * @returns {{ name: string, description: string, color?: string } | null}
+ *   Parsed agent metadata, or null if no valid frontmatter with a `name` field.
+ */
+function parseAgentFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return null
+
+  try {
+    const fm = yaml.load(match[1])
+    if (!fm || typeof fm !== 'object' || !fm.name) return null
+    return {
+      name: String(fm.name),
+      description: fm.description ? String(fm.description) : '',
+      color: fm.color ? String(fm.color) : undefined,
+    }
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exported API
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all canonical agents/*.agent.md files, parse frontmatter,
+ * and return an array of agent metadata objects sorted alphabetically by name.
+ *
+ * Skips files that don't match the `*.agent.md` pattern, files without
+ * valid YAML frontmatter, and entries without a `name` field.
+ *
+ * @returns {Array<{ name: string, description: string, color?: string }>}
+ */
+export function readCanonicalAgents() {
+  if (!existsSync(AGENTS_DIR)) return []
+
+  const files = readdirSync(AGENTS_DIR)
+    .filter((f) => f.endsWith('.agent.md') || f.endsWith('.md'))
+    .sort()
+
+  const agents = []
+  for (const file of files) {
+    const filePath = join(AGENTS_DIR, file)
+    let content
+    try {
+      content = readFileSync(filePath, 'utf8')
+    } catch {
+      continue // skip unreadable files
+    }
+
+    const parsed = parseAgentFrontmatter(content)
+    if (parsed) {
+      agents.push(parsed)
+    }
+  }
+
+  return agents.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Generate a markdown table from an agents array.
+ *
+ * @param {Array<{ name: string, description: string }>} agents
+ * @returns {string} Markdown table string.
+ *
+ * @example
+ *   | Agent | Role |
+ *   |-------|------|
+ *   | @zeus | Central orchestrator |
+ *   | @hermes | Backend (FastAPI) |
+ */
+export function generateAgentsTable(agents) {
+  const rows = ['| Agent | Role |', '|-------|------|']
+  for (const agent of agents) {
+    const role = (agent.description || '').replace(/\n/g, ' ')
+    rows.push(`| @${agent.name} | ${role} |`)
+  }
+  return rows.join('\n')
+}
+
+/**
+ * Generate complete AGENTS.md content.
+ *
+ * @param {Array<{ name: string, description: string }>} agents
+ *   Agent list from `readCanonicalAgents()`.
+ * @param {string} [platformName='']
+ *   Optional platform name appended to the title (e.g., 'Cursor', 'Cline').
+ * @param {string} [extraSections='']
+ *   Optional extra markdown content inserted between the agent table and
+ *   the Commands section. Pass platform-specific notes, workflow references,
+ *   setup instructions, etc.
+ * @returns {string} Complete AGENTS.md content.
+ *
+ * @example
+ *   const md = generateAgentsMd(agents, 'Cline', '## Cline Setup\n...');
+ *   writeFileSync('AGENTS.md', md);
+ */
+export function generateAgentsMd(agents, platformName = '', extraSections = '') {
+  const agentCount = agents.length
+  const title = platformName
+    ? `# Pantheon Agent System — ${platformName}`
+    : '# Pantheon Agent System'
+  const agentTable = generateAgentsTable(agents)
+
+  const sections = [
+    title,
+    '',
+    `This project uses the Pantheon multi-agent framework with ${agentCount} specialized agents.`,
+    '',
+    '## Available Agents',
+    '',
+    agentTable,
+  ]
+
+  if (extraSections) {
+    sections.push('', extraSections.trimEnd())
+  }
+
+  sections.push(
+    '',
+    '## Commands',
+    '',
+    '- Build: `npm run build`',
+    '- Test: `npm test`',
+    '- Lint: `npm run lint`',
+    '',
+    '## Conventions',
+    '',
+    '- TDD: Write failing test first, then implement',
+    '- Coverage minimum: 80%',
+    '- Async/await on all I/O',
+    '- Type hints on all functions',
+    '',
+  )
+
+  return sections.join('\n')
+}
+
+/**
+ * High-level convenience function that reads canonical agents, generates
+ * AGENTS.md content, and writes it to the target directory.
+ *
+ * @param {string} targetDir - Directory to write AGENTS.md into.
+ * @param {string} [platformName=''] - Optional platform name for the title.
+ * @param {string} [extraSections=''] - Optional extra sections to include.
+ * @returns {string} The generated content (also written to disk).
+ */
+export function generateAgentsMdForPlatform(targetDir, platformName = '', extraSections = '') {
+  const agents = readCanonicalAgents()
+  const content = generateAgentsMd(agents, platformName, extraSections)
+  const outputPath = join(targetDir, 'AGENTS.md')
+  writeFileSync(outputPath, content, 'utf8')
+  return content
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const targetDir = process.argv[2] || process.cwd()
+  const platformName = process.argv[3] || ''
+  const extraSections = process.argv[4] || ''
+
+  try {
+    const content = generateAgentsMdForPlatform(targetDir, platformName, extraSections)
+    const agentCount = (content.match(/^\| @/gm) || []).length
+    console.log(`✅ Generated AGENTS.md in ${targetDir} (${agentCount} agents)`)
+  } catch (err) {
+    console.error(`❌ Failed to generate AGENTS.md: ${err.message}`)
+    process.exit(1)
+  }
+}

package/scripts/install/health-check.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+/**
+ * health-check.mjs — Post-installation validation checks
+ *
+ * Usage:
+ *   node scripts/install/health-check.mjs --target ~/.config/opencode
+ *   node scripts/install/health-check.mjs --target ~/.config/opencode --dry-run
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Run health checks against a Pantheon installation target.
+ * Reports results as { passed, failed, warnings } arrays.
+ * NON-FATAL — all checks are reported, none throw.
+ *
+ * @param {string} target - Installation directory
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ passed: Array<{check: string, detail: string}>, failed: Array<{check: string, detail: string}>, warnings: Array<{check: string, detail: string}> }}
+ */
+export function healthCheck(target, { dryRun = false } = {}) {
+  const results = { passed: [], failed: [], warnings: [] }
+  const python = findPython(target)
+
+  // Check 1: Critical runtime scripts exist
+  const scripts = ['mcp_persistence_server.py', '_pantheon_paths.py']
+  for (const script of scripts) {
+    const path = join(target, 'scripts', script)
+    if (existsSync(path)) {
+      results.passed.push({ check: `scripts/${script}`, detail: 'exists' })
+    } else {
+      results.failed.push({
+        check: `scripts/${script}`,
+        detail: 'NOT FOUND',
+      })
+    }
+  }
+
+  if (dryRun) return results
+
+  // Check 2: Syntax check on each MCP server script
+  const mcpScripts = [
+    'mcp_persistence_server.py',
+    'mcp_resources_server.py',
+    'code_mode_server.py',
+    'memory_mcp_server.py',
+  ]
+  for (const script of mcpScripts) {
+    const path = join(target, 'scripts', script)
+    if (existsSync(path) && python) {
+      const result = spawnSync(python, ['-m', 'py_compile', path], {
+        stdio: 'pipe',
+      })
+      if (result.status === 0) {
+        results.passed.push({
+          check: `syntax:${script}`,
+          detail: 'valid',
+        })
+      } else {
+        results.failed.push({
+          check: `syntax:${script}`,
+          detail: result.stderr.toString().trim().split('\n').slice(-1)[0],
+        })
+      }
+    }
+  }
+
+  // Check 3: _pantheon_paths import works
+  if (python) {
+    const importCmd = [
+      '-c',
+      "import sys; sys.path.insert(0, '" +
+        join(target, 'scripts') +
+        "'); " +
+        'from _pantheon_paths import pantheon_home; print(pantheon_home())',
+    ]
+    const result = spawnSync(python, importCmd, { stdio: 'pipe' })
+    if (result.status === 0) {
+      results.passed.push({
+        check: '_pantheon_paths import',
+        detail: result.stdout.toString().trim(),
+      })
+    } else {
+      results.failed.push({
+        check: '_pantheon_paths import',
+        detail: result.stderr.toString().trim().split('\n').slice(-1)[0],
+      })
+    }
+  }
+
+  // Check 3.5: mcp SDK importable (required by ALL MCP servers)
+  if (python) {
+    const mcpResult = spawnSync(
+      python,
+      ['-c', 'from mcp.server.fastmcp import FastMCP; print(FastMCP.__module__)'],
+      { stdio: 'pipe' },
+    )
+    if (mcpResult.status === 0) {
+      results.passed.push({ check: 'mcp-sdk', detail: mcpResult.stdout.toString().trim() })
+    } else {
+      results.failed.push({ check: 'mcp-sdk', detail: 'NOT INSTALLED — all MCP servers will fail' })
+    }
+  }
+  // Check 4: chromadb importable
+  if (python) {
+    const result = spawnSync(
+      python,
+      ['-c', 'from fastembed import TextEmbedding; print(TextEmbedding.__module__)'],
+      { stdio: 'pipe' },
+    )
+    if (result.status === 0) {
+      results.passed.push({
+        check: 'chromadb',
+        detail: result.stdout.toString().trim(),
+      })
+    } else {
+      results.warnings.push({
+        check: 'chromadb',
+        detail: 'NOT INSTALLED — semantic search will fail',
+      })
+    }
+  }
+
+  // Check 5: SQLite FTS5 available
+  if (python) {
+    const fts5Cmd = [
+      '-c',
+      'import sqlite3; ' +
+        "row = sqlite3.connect(':memory:').execute('PRAGMA compile_options').fetchall(); " +
+        "fts5 = any('ENABLE_FTS5' in str(r[0]) for r in row); " +
+        "print(f'SQLite {sqlite3.sqlite_version} FTS5={fts5}')",
+    ]
+    const result = spawnSync(python, fts5Cmd, { stdio: 'pipe' })
+    if (result.status === 0) {
+      results.passed.push({
+        check: 'sqlite-fts5',
+        detail: result.stdout.toString().trim(),
+      })
+    } else {
+      results.failed.push({
+        check: 'sqlite-fts5',
+        detail: result.stderr.toString().trim().split('\n').slice(-1)[0],
+      })
+    }
+  }
+
+  return results
+}
+
+/**
+ * Find the target's venv python, falling back to system python3.
+ * @param {string} target
+ * @returns {string|null}
+ */
+function findPython(target) {
+  const candidates = [
+    join(target, '.venv', 'bin', 'python3'),
+    join(target, '.venv', 'bin', 'python'),
+  ]
+  for (const c of candidates) {
+    if (existsSync(c)) return c
+  }
+  // Check if python3 is even available
+  const probe = spawnSync('which', ['python3'], { stdio: 'pipe' })
+  return probe.status === 0 ? 'python3' : null
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+function main() {
+  const args = process.argv.slice(2)
+  const targetIdx = args.indexOf('--target')
+  const target = targetIdx !== -1 ? args[targetIdx + 1] : process.cwd()
+  const dryRun = args.includes('--dry-run')
+
+  const results = healthCheck(target, { dryRun })
+
+  console.log('\n  📊 Health Check:')
+  for (const p of results.passed) console.log(`    ✅ ${p.check}: ${p.detail}`)
+  for (const w of results.warnings) console.log(`    ⚠️  ${w.check}: ${w.detail}`)
+  for (const f of results.failed) console.log(`    ❌ ${f.check}: ${f.detail}`)
+
+  console.log(
+    `\n  Summary: ${results.passed.length} passed, ${results.warnings.length} warnings, ${results.failed.length} failed`,
+  )
+
+  if (results.failed.length > 0) process.exit(1)
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  main()
+}

package/scripts/install/migrate.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * migrate.mjs — Multi-version migration logic for Pantheon installations
+ *
+ * Usage:
+ *   node scripts/install/migrate.mjs --target ~/.config/opencode
+ *   node scripts/install/migrate.mjs --target ~/.config/opencode --dry-run
+ *   node scripts/install/migrate.mjs --target ~/.config/opencode --force
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, '..', '..')
+
+// Package version from project root
+const PANTHON_VERSION = readPackageVersion()
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+    return pkg.version || '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+/**
+ * Read the installed version from the target's install state file.
+ * @param {string} target
+ * @returns {string|null} - version string or null for fresh install
+ */
+export function detectVersion(target) {
+  const stateFile = join(target, '.pantheon', 'install-state.json')
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf8'))
+      return state.pantheon_version || state.version || 'unknown'
+    } catch {
+      /* corrupted state — treat as unknown */
+    }
+  }
+  return null // fresh install
+}
+
+/**
+ * Run version-specific migrations sequentially.
+ *
+ * @param {string} target - Installation directory
+ * @param {string|null} currentVersion - Detected version (null = fresh install)
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ applied: number, messages: string[] }}
+ */
+export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
+  const applied = []
+  const semver = parseSemver(currentVersion)
+
+  // ── Migration: v3.10.0 → v3.18.0 ──────────────────────────────────
+  // Fix dangling references, add Memory Protocol
+  if (semver && lt(semver, [3, 18, 0])) {
+    applied.push({
+      from: formatSemver(semver),
+      to: '3.18.0',
+      description: 'Fix dangling references, add Memory Protocol',
+    })
+    semver[0] = 3
+    semver[1] = 18
+    semver[2] = 0
+  }
+
+  // ── Migration: v3.18.0 → v3.19.0 ──────────────────────────────────
+  // Add runtime component, _pantheon_paths
+  if (semver && lt(semver, [3, 19, 0])) {
+    applied.push({
+      from: formatSemver(semver),
+      to: '3.19.0',
+      description: 'Add runtime component, _pantheon_paths',
+    })
+    semver[0] = 3
+    semver[1] = 19
+    semver[2] = 0
+  }
+
+  // ── Migration: v3.19.0 → v3.19.1 ──────────────────────────────────
+  // Add persistence MCP, fix 157 dangling refs
+  if (semver && lt(semver, [3, 19, 1])) {
+    applied.push({
+      from: formatSemver(semver),
+      to: '3.19.1',
+      description: 'Add persistence MCP, fix dangling refs',
+    })
+    semver[0] = 3
+    semver[1] = 19
+    semver[2] = 1
+  }
+
+  // ── Write updated state ───────────────────────────────────────────
+  if (applied.length > 0 && !dryRun) {
+    writeInstallState(target, formatSemver(semver))
+  }
+
+  return {
+    applied: applied.length,
+    messages: applied.map((m) => `${m.from} → ${m.to}: ${m.description}`),
+  }
+}
+
+/**
+ * Write install state with current version to target.
+ */
+function writeInstallState(target, version) {
+  const stateDir = join(target, '.pantheon')
+  const stateFile = join(stateDir, 'install-state.json')
+  if (!existsSync(stateDir)) {
+    mkdirSync(stateDir, { recursive: true })
+  }
+  const state = {
+    pantheon_version: version,
+    updated_at: new Date().toISOString(),
+  }
+  writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+}
+
+// ---------------------------------------------------------------------------
+// Minimal semver helpers (no external deps)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse "x.y.z" → [major, minor, patch] or null.
+ * @param {string|null} v
+ * @returns {number[]|null}
+ */
+function parseSemver(v) {
+  if (!v || typeof v !== 'string') return null
+  const parts = v.split('.').map(Number)
+  if (parts.length < 2 || parts.some(Number.isNaN)) return null
+  return [parts[0], parts[1], parts[2] ?? 0]
+}
+
+/**
+ * Format [major, minor, patch] → "x.y.z".
+ * @param {number[]} v
+ * @returns {string}
+ */
+function formatSemver(v) {
+  return `${v[0]}.${v[1]}.${v[2]}`
+}
+
+/**
+ * Compare two semver arrays: is a < b?
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {boolean}
+ */
+function lt(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) {
+      return (a[i] ?? 0) < (b[i] ?? 0)
+    }
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+function main() {
+  const args = process.argv.slice(2)
+  const targetIdx = args.indexOf('--target')
+  const target = targetIdx !== -1 ? args[targetIdx + 1] : process.cwd()
+  const dryRun = args.includes('--dry-run')
+  const force = args.includes('--force')
+
+  const currentVersion = detectVersion(target)
+  if (!currentVersion) {
+    // Fresh install — write state and exit
+    if (!dryRun) {
+      writeInstallState(target, PANTHON_VERSION)
+      console.log(`  ✅ Fresh install — state written (${PANTHON_VERSION})`)
+    } else {
+      console.log(`  ✅ Fresh install — would write state (${PANTHON_VERSION})`)
+    }
+    return
+  }
+
+  console.log(`  Current version: ${currentVersion}`)
+
+  if (!force && currentVersion === PANTHON_VERSION) {
+    console.log('  ⏭️  Already at latest version — no migrations needed')
+    return
+  }
+
+  const migration = runMigrations(target, currentVersion, { dryRun })
+
+  if (migration.applied > 0) {
+    console.log(`  ✅ Applied ${migration.applied} migration(s):`)
+    for (const msg of migration.messages) {
+      console.log(`     • ${msg}`)
+    }
+  } else {
+    console.log('  ⏭️  No applicable migrations')
+  }
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  main()
+}