@orchid-labs/pluxx 0.1.0 → 0.1.1

package/src/cli/mcp-proxy.ts

@@ -0,0 +1,322 @@
+import { mkdirSync, readFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+import * as readline from 'readline'
+import type { Readable, Writable } from 'stream'
+import { createMcpClient, McpIntrospectionError, type McpClient } from '../mcp/introspect'
+import { parseMcpSourceInput } from './init-from-mcp'
+
+interface ProxyTapeInteraction {
+  kind: 'request' | 'notify'
+  method: string
+  params?: Record<string, unknown>
+  result?: unknown
+  error?: {
+    code: number
+    message: string
+  }
+}
+
+interface ProxyTape {
+  version: 1
+  source?: string
+  interactions: ProxyTapeInteraction[]
+}
+
+interface McpProxyOptions {
+  source?: string
+  recordPath?: string
+  replayPath?: string
+}
+
+interface ProxyIo {
+  input: Readable
+  output: Writable
+  error: Writable
+}
+
+function usage(): string {
+  return [
+    'Usage: pluxx mcp proxy --from-mcp <source> [--record <tape.json>]',
+    '       pluxx mcp proxy --replay <tape.json>',
+    '',
+    'Acts as a local stdio MCP proxy for development and CI.',
+    '- --record stores normalized request/response interactions as a replay tape.',
+    '- --replay serves a deterministic stdio MCP session from a recorded tape.',
+  ].join('\n')
+}
+
+function readOption(rawArgs: string[], flag: string): string | undefined {
+  const index = rawArgs.indexOf(flag)
+  if (index === -1) return undefined
+
+  const value = rawArgs[index + 1]
+  if (!value || value.startsWith('-')) {
+    return undefined
+  }
+
+  return value
+}
+
+function parseOptions(rawArgs: string[]): McpProxyOptions {
+  const source = readOption(rawArgs, '--from-mcp')
+  const recordPath = readOption(rawArgs, '--record')
+  const replayPath = readOption(rawArgs, '--replay')
+
+  if (recordPath && replayPath) {
+    throw new Error('Choose either --record or --replay, not both.')
+  }
+
+  if (!source && !replayPath) {
+    throw new Error('Expected --from-mcp <source> for live proxying, or --replay <tape.json>.')
+  }
+
+  if ((recordPath || source) && replayPath && source) {
+    throw new Error('Replay mode does not accept --from-mcp.')
+  }
+
+  return {
+    source,
+    recordPath,
+    replayPath,
+  }
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value)
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(',')}]`
+  }
+
+  const entries = Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, nested]) => `${JSON.stringify(key)}:${stableStringify(nested)}`)
+  return `{${entries.join(',')}}`
+}
+
+function sameParams(
+  left: Record<string, unknown> | undefined,
+  right: Record<string, unknown> | undefined,
+): boolean {
+  return stableStringify(left ?? null) === stableStringify(right ?? null)
+}
+
+function sendEnvelope(output: Writable, envelope: Record<string, unknown>): void {
+  output.write(`${JSON.stringify(envelope)}\n`)
+}
+
+function sendError(output: Writable, id: number | string | null, code: number, message: string): void {
+  sendEnvelope(output, {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code,
+      message,
+    },
+  })
+}
+
+async function loadReplayTape(filepath: string): Promise<ProxyTape> {
+  const absolutePath = resolve(process.cwd(), filepath)
+  const tape = JSON.parse(readFileSync(absolutePath, 'utf-8')) as ProxyTape
+  if (tape.version !== 1 || !Array.isArray(tape.interactions)) {
+    throw new Error(`Replay tape is not a valid pluxx MCP tape: ${filepath}`)
+  }
+  return tape
+}
+
+async function writeTape(filepath: string, tape: ProxyTape): Promise<void> {
+  const absolutePath = resolve(process.cwd(), filepath)
+  mkdirSync(dirname(absolutePath), { recursive: true })
+  await Bun.write(absolutePath, `${JSON.stringify(tape, null, 2)}\n`)
+}
+
+function serializeError(error: unknown): { code: number; message: string } {
+  if (error instanceof McpIntrospectionError) {
+    return {
+      code: error.rpcCode ?? -32000,
+      message: error.message,
+    }
+  }
+
+  return {
+    code: -32000,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+async function proxyLiveSession(client: McpClient, options: McpProxyOptions, io: ProxyIo): Promise<void> {
+  const tape: ProxyTape | null = options.recordPath
+    ? {
+        version: 1,
+        source: options.source,
+        interactions: [],
+      }
+    : null
+
+  const rl = readline.createInterface({
+    input: io.input,
+    crlfDelay: Infinity,
+  })
+
+  try {
+    for await (const line of rl) {
+      if (!line.trim()) continue
+
+      let message: Record<string, unknown>
+      try {
+        message = JSON.parse(line) as Record<string, unknown>
+      } catch {
+        continue
+      }
+
+      const method = typeof message.method === 'string' ? message.method : undefined
+      if (!method) continue
+
+      const params = (typeof message.params === 'object' && message.params !== null)
+        ? message.params as Record<string, unknown>
+        : undefined
+      const id = typeof message.id === 'number' || typeof message.id === 'string'
+        ? message.id
+        : null
+
+      if (id === null) {
+        await client.notify(method, params)
+        tape?.interactions.push({
+          kind: 'notify',
+          method,
+          ...(params ? { params } : {}),
+        })
+        continue
+      }
+
+      try {
+        const result = await client.request<unknown>(method, params)
+        sendEnvelope(io.output, {
+          jsonrpc: '2.0',
+          id,
+          result,
+        })
+        tape?.interactions.push({
+          kind: 'request',
+          method,
+          ...(params ? { params } : {}),
+          result,
+        })
+      } catch (error) {
+        const serialized = serializeError(error)
+        sendError(io.output, id, serialized.code, serialized.message)
+        tape?.interactions.push({
+          kind: 'request',
+          method,
+          ...(params ? { params } : {}),
+          error: serialized,
+        })
+      }
+    }
+  } finally {
+    rl.close()
+    await client.close()
+    if (tape && options.recordPath) {
+      await writeTape(options.recordPath, tape)
+    }
+  }
+}
+
+async function replaySession(filepath: string, io: ProxyIo): Promise<void> {
+  const tape = await loadReplayTape(filepath)
+  const interactions = [...tape.interactions]
+  const rl = readline.createInterface({
+    input: io.input,
+    crlfDelay: Infinity,
+  })
+
+  try {
+    for await (const line of rl) {
+      if (!line.trim()) continue
+
+      let message: Record<string, unknown>
+      try {
+        message = JSON.parse(line) as Record<string, unknown>
+      } catch {
+        continue
+      }
+
+      const method = typeof message.method === 'string' ? message.method : undefined
+      if (!method) continue
+
+      const params = (typeof message.params === 'object' && message.params !== null)
+        ? message.params as Record<string, unknown>
+        : undefined
+      const id = typeof message.id === 'number' || typeof message.id === 'string'
+        ? message.id
+        : null
+      const expected = interactions.shift()
+
+      if (!expected) {
+        if (id !== null) {
+          sendError(io.output, id, -32001, `Replay tape exhausted before handling ${method}.`)
+        }
+        continue
+      }
+
+      if (expected.kind !== (id === null ? 'notify' : 'request') || expected.method !== method || !sameParams(expected.params, params)) {
+        if (id !== null) {
+          sendError(
+            io.output,
+            id,
+            -32002,
+            `Replay mismatch. Expected ${expected.kind} ${expected.method}, received ${id === null ? 'notify' : 'request'} ${method}.`,
+          )
+        }
+        continue
+      }
+
+      if (id === null) {
+        continue
+      }
+
+      if (expected.error) {
+        sendError(io.output, id, expected.error.code, expected.error.message)
+        continue
+      }
+
+      sendEnvelope(io.output, {
+        jsonrpc: '2.0',
+        id,
+        result: expected.result ?? null,
+      })
+    }
+  } finally {
+    rl.close()
+  }
+}
+
+export async function runMcpProxy(rawArgs: string[]): Promise<void> {
+  return await runMcpProxyWithIo(rawArgs, {
+    input: process.stdin,
+    output: process.stdout,
+    error: process.stderr,
+  })
+}
+
+export async function runMcpProxyWithIo(rawArgs: string[], io: ProxyIo): Promise<void> {
+  let options: McpProxyOptions
+  try {
+    options = parseOptions(rawArgs)
+  } catch (error) {
+    io.error.write(`${error instanceof Error ? error.message : String(error)}\n\n${usage()}\n`)
+    throw new Error('Invalid MCP proxy arguments.')
+  }
+
+  if (options.replayPath) {
+    await replaySession(options.replayPath, io)
+    return
+  }
+
+  const source = parseMcpSourceInput(options.source!)
+  const client = await createMcpClient(source)
+  await proxyLiveSession(client, options, io)
+}

package/src/cli/migrate.ts

@@ -1,5 +1,12 @@
-import { resolve, basename, join, relative } from 'path'
+import { resolve, basename } from 'path'
 import { existsSync, readdirSync, mkdirSync, cpSync, readFileSync } from 'fs'
+import {
+  MCP_SCAFFOLD_METADATA_PATH,
+  MCP_TAXONOMY_PATH,
+  type McpScaffoldMetadata,
+  type PersistedSkill,
+} from './init-from-mcp'
+import type { McpServer } from '../schema'
 
 type DetectedPlatform = 'claude-code' | 'cursor' | 'codex' | 'opencode'
 
@@ -55,6 +62,7 @@ interface MigrateResult {
     scripts: boolean
     assets: boolean
   }
+  persistedSkills: PersistedSkill[]
 }
 
 // ── Platform Detection ──────────────────────────────────────────
@@ -347,6 +355,237 @@ function detectDirectories(pluginDir: string) {
   }
 }
 
+function toKebabCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase()
+}
+
+function titleCaseFromDirName(value: string): string {
+  return value
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+function firstHeading(content: string): string | undefined {
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    const match = trimmed.match(/^#\s+(.+)$/)
+    if (match) {
+      return match[1].trim()
+    }
+  }
+  return undefined
+}
+
+function extractFrontmatterField(content: string, key: 'name' | 'description'): string | undefined {
+  const lines = content.split(/\r?\n/)
+  if (lines[0]?.trim() !== '---') return undefined
+
+  let endIndex = -1
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      endIndex = i
+      break
+    }
+  }
+
+  if (endIndex === -1) return undefined
+
+  for (const line of lines.slice(1, endIndex)) {
+    const match = line.match(new RegExp(`^${key}:\\s*(.*)$`))
+    if (!match) continue
+    return match[1].trim().replace(/^['"]|['"]$/g, '')
+  }
+
+  return undefined
+}
+
+function readMigratedSkills(pluginDir: string, dirs: MigrateResult['directories']): PersistedSkill[] {
+  const skills: PersistedSkill[] = []
+
+  if (dirs.skills) {
+    const skillsDir = resolve(pluginDir, 'skills')
+    const entries = readdirSync(skillsDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const dirName = entry.name
+      const skillPath = resolve(skillsDir, dirName, 'SKILL.md')
+      let title = titleCaseFromDirName(dirName)
+      let description: string | undefined
+
+      if (existsSync(skillPath)) {
+        const content = readFileSync(skillPath, 'utf-8')
+        title = extractFrontmatterField(content, 'name')
+          ?? firstHeading(content)
+          ?? title
+        description = extractFrontmatterField(content, 'description')
+      }
+
+      skills.push({
+        dirName,
+        title,
+        description,
+        toolNames: [],
+      })
+    }
+  }
+
+  if (skills.length === 0 && dirs.commands) {
+    const commandsDir = resolve(pluginDir, 'commands')
+    const entries = readdirSync(commandsDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+      const dirName = toKebabCase(entry.name.replace(/\.md$/, '')) || 'command'
+      const content = readFileSync(resolve(commandsDir, entry.name), 'utf-8')
+      skills.push({
+        dirName,
+        title: firstHeading(content) ?? titleCaseFromDirName(dirName),
+        description: extractFrontmatterField(content, 'description'),
+        toolNames: [],
+      })
+    }
+  }
+
+  return skills.sort((a, b) => a.dirName.localeCompare(b.dirName))
+}
+
+function primarySource(result: MigrateResult): McpServer {
+  const [serverName, server] = Object.entries(result.mcp)[0] ?? []
+  const auth = normalizeMigrateAuth(server?.auth)
+  if (server) {
+    if (server.transport === 'stdio') {
+      return {
+        transport: 'stdio',
+        command: server.command ?? 'TODO_MCP_COMMAND',
+        args: server.args ?? [],
+        ...(server.env ? { env: server.env } : {}),
+        ...(auth ? { auth } : {}),
+      }
+    }
+
+    if (server.transport === 'sse') {
+      return {
+        transport: 'sse',
+        url: server.url ?? `https://example.com/${serverName ?? 'mcp'}`,
+        ...(auth ? { auth } : {}),
+      }
+    }
+
+    return {
+      transport: 'http',
+      url: server.url ?? `https://example.com/${serverName ?? 'mcp'}`,
+      ...(auth ? { auth } : {}),
+    }
+  }
+
+  return {
+    transport: 'stdio',
+    command: 'TODO_MCP_COMMAND',
+    args: [],
+  }
+}
+
+function normalizeMigrateAuth(auth: ParsedMcp[string]['auth']) {
+  if (!auth) return undefined
+  if (auth.type === 'none') {
+    return { type: 'none' as const }
+  }
+  if (auth.type === 'bearer' && auth.envVar) {
+    return {
+      type: 'bearer' as const,
+      envVar: auth.envVar,
+      headerName: auth.headerName ?? 'Authorization',
+      headerTemplate: auth.headerTemplate ?? 'Bearer ${value}',
+    }
+  }
+  if (auth.type === 'header' && auth.envVar && auth.headerName) {
+    return {
+      type: 'header' as const,
+      envVar: auth.envVar,
+      headerName: auth.headerName,
+      headerTemplate: auth.headerTemplate ?? '${value}',
+    }
+  }
+  return undefined
+}
+
+function buildMigratedScaffoldMetadata(result: MigrateResult, outputDir: string): McpScaffoldMetadata {
+  const pluginName = result.manifest.name ?? 'my-plugin'
+  const displayName = result.manifest.name ? titleCaseFromDirName(result.manifest.name) : 'Migrated Plugin'
+  const description = result.manifest.description ?? 'Migrated plugin scaffold.'
+  const generatedHookEvents = Object.keys(result.hooks)
+  const managedFiles = [
+    ...(result.instructions ? [result.instructions.replace(/^\.\//, '')] : []),
+    ...(['skills', 'commands', 'agents', 'scripts', 'assets'] as const).flatMap((dir) => {
+      if (!result.directories[dir]) return []
+      const baseDir = dir
+      const dirPath = resolve(outputDir, baseDir)
+      if (!existsSync(dirPath)) return []
+      const entries = readdirSync(dirPath, { withFileTypes: true })
+      const files: string[] = []
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const nestedDir = resolve(dirPath, entry.name)
+          for (const nested of readdirSync(nestedDir, { withFileTypes: true })) {
+            if (nested.isFile()) {
+              files.push(`${baseDir}/${entry.name}/${nested.name}`)
+            }
+          }
+          continue
+        }
+        if (entry.isFile()) {
+          files.push(`${baseDir}/${entry.name}`)
+        }
+      }
+      return files
+    }),
+    'pluxx.config.ts',
+    MCP_TAXONOMY_PATH,
+    MCP_SCAFFOLD_METADATA_PATH,
+  ]
+
+  return {
+    version: 1,
+    source: primarySource(result),
+    serverInfo: {
+      name: pluginName,
+      title: displayName,
+      version: result.manifest.version ?? '0.1.0',
+      description,
+      ...(result.manifest.repository ? { websiteUrl: result.manifest.repository } : {}),
+    },
+    settings: {
+      pluginName,
+      displayName,
+      description,
+      skillGrouping: 'workflow',
+      requestedHookMode: generatedHookEvents.length > 0 ? 'safe' : 'none',
+      generatedHookMode: generatedHookEvents.length > 0 ? 'safe' : 'none',
+      generatedHookEvents,
+      runtimeAuthMode: 'inline',
+    },
+    userConfig: [],
+    tools: [],
+    resources: [],
+    resourceTemplates: [],
+    prompts: [],
+    skills: result.persistedSkills.map((skill) => ({
+      dirName: skill.dirName,
+      title: skill.title,
+      description: skill.description,
+      toolNames: skill.toolNames,
+    })),
+    managedFiles: [...new Set(managedFiles)].sort(),
+  }
+}
+
 // ── Copy Directories ────────────────────────────────────────────
 
 function copyDirectories(
@@ -559,12 +798,16 @@ export async function migrate(inputPath: string): Promise<void> {
 
   // 6. Detect directories
   const directories = detectDirectories(pluginDir)
+  const persistedSkills = readMigratedSkills(pluginDir, directories)
   const dirNames = Object.entries(directories)
     .filter(([_, exists]) => exists)
     .map(([name]) => name)
   if (dirNames.length > 0) {
     console.log(`  directories: ${dirNames.join(', ')}`)
   }
+  if (persistedSkills.length > 0) {
+    console.log(`  migrated skills: ${persistedSkills.map((skill) => skill.dirName).join(', ')}`)
+  }
 
   // 7. Build result
   const result: MigrateResult = {
@@ -574,6 +817,7 @@ export async function migrate(inputPath: string): Promise<void> {
     hooks,
     instructions,
     directories,
+    persistedSkills,
   }
 
   // 8. Generate config
@@ -606,9 +850,18 @@ export async function migrate(inputPath: string): Promise<void> {
     }
   }
 
+  // 11. Create synthetic migration metadata/taxonomy so Agent Mode and evals work.
+  const taxonomyPath = resolve(outputDir, MCP_TAXONOMY_PATH)
+  const metadataPath = resolve(outputDir, MCP_SCAFFOLD_METADATA_PATH)
+  mkdirSync(resolve(outputDir, '.pluxx'), { recursive: true })
+  await Bun.write(taxonomyPath, `${JSON.stringify(result.persistedSkills, null, 2)}\n`)
+  await Bun.write(metadataPath, `${JSON.stringify(buildMigratedScaffoldMetadata(result, outputDir), null, 2)}\n`)
+  console.log(`Generated: ${MCP_TAXONOMY_PATH}, ${MCP_SCAFFOLD_METADATA_PATH}`)
+
   console.log('')
   console.log('Migration complete! Next steps:')
   console.log('  1. Review pluxx.config.ts and fill in any TODOs')
-  console.log('  2. Run: pluxx validate')
-  console.log('  3. Run: pluxx build')
+  console.log('  2. Run: pluxx doctor')
+  console.log('  3. Run: pluxx eval')
+  console.log('  4. Run: pluxx build')
 }

package/src/cli/sync-from-mcp.ts

@@ -142,6 +142,13 @@ export async function syncFromMcp(options: SyncFromMcpOptions): Promise<SyncFrom
     const after = readFileSync(currentPath, 'utf-8')
     return before !== after
   })
+  const scaffoldChanged = addedFiles.length > 0
+    || updatedFiles.length > 0
+    || removedFiles.length > 0
+    || renamedFiles.length > 0
+  if (scaffoldChanged) {
+    invalidateSavedAgentPack(options.rootDir)
+  }
 
   return {
     source,
@@ -216,6 +223,8 @@ export async function applyPersistedTaxonomy(rootDir: string): Promise<void> {
       writeFileSync(resolveWithinRoot(rootDir, file), previousInstructions, 'utf-8')
     }
   }
+
+  invalidateSavedAgentPack(rootDir)
 }
 
 export async function planSyncFromMcp(options: SyncFromMcpOptions): Promise<SyncFromMcpResult> {
@@ -309,6 +318,20 @@ function pruneEmptyDirectories(rootDir: string, startDir: string): void {
   }
 }
 
+const AGENT_PACK_FILES = [
+  '.pluxx/agent/context.md',
+  '.pluxx/agent/plan.json',
+  '.pluxx/agent/taxonomy-prompt.md',
+  '.pluxx/agent/instructions-prompt.md',
+  '.pluxx/agent/review-prompt.md',
+] as const
+
+function invalidateSavedAgentPack(rootDir: string): void {
+  for (const relativePath of AGENT_PACK_FILES) {
+    removeManagedFile(rootDir, relativePath)
+  }
+}
+
 /**
  * Detect tool renames by comparing old and new tool lists.
  * Returns a map of oldName -> newName for likely renames.