@orchid-labs/pluxx 0.1.0 → 0.1.3

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

@@ -1,1611 +0,0 @@
-import { existsSync } from 'fs'
-import { mkdir } from 'fs/promises'
-import { basename, resolve } from 'path'
-import type { HookEntry, McpServer, PluginConfig, TargetPlatform, UserConfigEntry } from '../schema'
-import type { IntrospectedMcpServer, IntrospectedMcpTool } from '../mcp/introspect'
-import { collectUserConfigEntries } from '../user-config'
-
-export interface McpScaffoldOptions {
-  rootDir: string
-  pluginName: string
-  authorName: string
-  targets: TargetPlatform[]
-  source: McpServer
-  introspection: IntrospectedMcpServer
-  serverName?: string
-  displayName?: string
-  description?: string
-  skillGrouping?: McpSkillGrouping
-  hookMode?: McpHookMode
-  runtimeAuthMode?: McpRuntimeAuthMode
-  persistedSkills?: PersistedSkill[]
-  toolRenames?: Map<string, string>
-}
-
-export interface McpScaffoldResult {
-  instructionsPath: string
-  skillDirectories: string[]
-  commandFiles: string[]
-  generatedFiles: string[]
-  generatedHookMode: McpHookMode
-  generatedHookEvents: string[]
-  metadataPath: string
-}
-
-export interface McpScaffoldPlannedFile {
-  relativePath: string
-  content: string
-  action: 'create' | 'update' | 'unchanged'
-}
-
-export interface McpScaffoldPlan extends McpScaffoldResult {
-  files: McpScaffoldPlannedFile[]
-}
-
-interface PlannedSkill {
-  dirName: string
-  title: string
-  description: string
-  tools: IntrospectedMcpTool[]
-}
-
-export interface PersistedSkill {
-  dirName: string
-  title: string
-  description?: string
-  toolNames: string[]
-}
-
-interface SchemaField {
-  name: string
-  type: string
-  required: boolean
-  description?: string
-}
-
-export type McpQualityLevel = 'warning' | 'info'
-
-export interface McpQualityIssue {
-  level: McpQualityLevel
-  code: string
-  title: string
-  detail: string
-  fix: string
-}
-
-export interface McpQualityReport {
-  ok: boolean
-  warnings: number
-  infos: number
-  issues: McpQualityIssue[]
-}
-
-export const MCP_SKILL_GROUPINGS = ['workflow', 'tool'] as const
-export type McpSkillGrouping = typeof MCP_SKILL_GROUPINGS[number]
-
-export const MCP_HOOK_MODES = ['none', 'safe'] as const
-export type McpHookMode = typeof MCP_HOOK_MODES[number]
-export const MCP_RUNTIME_AUTH_MODES = ['inline', 'platform'] as const
-export type McpRuntimeAuthMode = typeof MCP_RUNTIME_AUTH_MODES[number]
-
-interface GeneratedHookScaffold {
-  mode: McpHookMode
-  scriptsPath?: string
-  hookEntries?: Record<string, HookEntry[]>
-  files: Array<{ relativePath: string; content: string }>
-}
-
-export interface McpScaffoldMetadata {
-  version: 1
-  source: McpServer
-  serverInfo: IntrospectedMcpServer['serverInfo']
-  settings: {
-    pluginName: string
-    displayName: string
-    skillGrouping: McpSkillGrouping
-    requestedHookMode: McpHookMode
-    generatedHookMode: McpHookMode
-    generatedHookEvents: string[]
-    runtimeAuthMode: McpRuntimeAuthMode
-  }
-  userConfig: UserConfigEntry[]
-  tools: IntrospectedMcpTool[]
-  skills: Array<{
-    dirName: string
-    title: string
-    description?: string
-    toolNames: string[]
-  }>
-  managedFiles: string[]
-}
-
-export const MCP_SCAFFOLD_METADATA_PATH = '.pluxx/mcp.json'
-export const MCP_TAXONOMY_PATH = '.pluxx/taxonomy.json'
-export const PLUXX_GENERATED_START = '<!-- pluxx:generated:start -->'
-export const PLUXX_GENERATED_END = '<!-- pluxx:generated:end -->'
-export const PLUXX_CUSTOM_START = '<!-- pluxx:custom:start -->'
-export const PLUXX_CUSTOM_END = '<!-- pluxx:custom:end -->'
-
-const DEFAULT_INSTRUCTIONS_CUSTOM_CONTENT = 'Add custom plugin instructions here. This section is preserved across `pluxx sync --from-mcp`.'
-const DEFAULT_SKILL_CUSTOM_CONTENT = 'Add custom guidance, examples, or caveats here. This section is preserved across `pluxx sync --from-mcp`.'
-const LEGACY_MIXED_CONTENT_NOTE = 'Migrated from a previous unstructured scaffold. Review and trim this section as needed.'
-
-interface MixedMarkdownContent {
-  hasMarkers: boolean
-  customContent: string
-}
-
-const WORKFLOW_SKILL_DEFINITIONS = [
-  {
-    key: 'setup-and-auth',
-    title: 'Setup and Auth',
-    description: 'Confirm access, auth state, and session readiness before running operational workflows.',
-    match: ['connect', 'connected', 'connection', 'status', 'auth', 'session', 'cookie', 'workspace'],
-  },
-  {
-    key: 'workflow-design',
-    title: 'Workflow Design',
-    description: 'Define strategy, prompts, targeting, and workflow shape before building tables or running enrichments.',
-    match: ['workflow', 'design', 'play', 'prompt', 'icp', 'persona', 'audience', 'segment', 'brainstorm', 'outreach'],
-  },
-  {
-    key: 'account-research',
-    title: 'Account Research',
-    description: 'Research companies, organizations, and account context before taking action.',
-    match: ['organization', 'organisation', 'company', 'account', 'firmographic'],
-  },
-  {
-    key: 'contact-discovery',
-    title: 'Contact Discovery',
-    description: 'Find people, contacts, and buyer-side context at the right accounts.',
-    match: ['people', 'person', 'contact', 'prospect', 'decision maker', 'org chart'],
-  },
-  {
-    key: 'hiring-signals',
-    title: 'Hiring Signals',
-    description: 'Use hiring activity and open roles as timing signals for outreach and research.',
-    match: ['job', 'jobs', 'hiring', 'hire', 'role', 'roles', 'recruit', 'career'],
-  },
-  {
-    key: 'technographics',
-    title: 'Technographics',
-    description: 'Research technologies, tools, and stack adoption across target accounts.',
-    match: ['technology', 'technologies', 'tech', 'stack', 'tooling', 'software'],
-  },
-  {
-    key: 'table-operations',
-    title: 'Table Operations',
-    description: 'Build, inspect, run, document, and export tables, rows, and enrichment workflows.',
-    match: ['table', 'tables', 'schema', 'webhook', 'row', 'rows', 'export', 'audit', 'document', 'enrich', 'view'],
-  },
-  {
-    key: 'provider-research',
-    title: 'Provider Research',
-    description: 'Compare providers, integrations, and capability tradeoffs before choosing a workflow.',
-    match: ['provider', 'providers', 'integration', 'integrations', 'byoa', 'waterfall', 'compare', 'comparison'],
-  },
-  {
-    key: 'account-and-usage',
-    title: 'Account and Usage',
-    description: 'Check pricing, usage, limits, credits, and upgrade context for the current account.',
-    match: ['usage', 'tier', 'plan', 'pricing', 'price', 'cost', 'credits', 'checkout', 'upgrade', 'billing'],
-  },
-  {
-    key: 'general-research',
-    title: 'General Research',
-    description: 'Handle broad search and query workflows when there is not a more specific product surface match.',
-    match: ['search', 'query', 'lookup', 'look up', 'discover', 'find'],
-  },
-] as const
-
-const GENERIC_TOOL_NAMES = new Set([
-  'run',
-  'execute',
-  'query',
-  'invoke',
-  'action',
-  'tool',
-  'command',
-  'workflow',
-  'task',
-])
-
-export function parseMcpSourceInput(input: string, transportOverride?: string): McpServer {
-  const value = input.trim()
-  if (!value) {
-    throw new Error('Expected an MCP server URL or a local command.')
-  }
-
-  if (transportOverride && transportOverride !== 'http' && transportOverride !== 'sse') {
-    throw new Error('Transport must be one of: http, sse')
-  }
-
-  try {
-    const url = new URL(value)
-    if (url.protocol === 'http:' || url.protocol === 'https:') {
-      const normalizedPath = url.pathname.replace(/\/+$/, '')
-      const transport = transportOverride === 'sse' || (!transportOverride && normalizedPath.endsWith('/sse'))
-        ? 'sse' as const
-        : 'http' as const
-      return {
-        transport,
-        url: url.toString(),
-      }
-    }
-  } catch {
-    // Not a URL, treat it as a stdio command.
-  }
-
-  const parts = splitCommandString(value)
-  if (parts.length === 0) {
-    throw new Error('Expected an MCP server URL or a local command.')
-  }
-
-  return {
-    transport: 'stdio',
-    command: parts[0],
-    args: parts.slice(1),
-  }
-}
-
-export async function writeMcpScaffold(options: McpScaffoldOptions): Promise<McpScaffoldResult> {
-  const plan = await planMcpScaffold(options)
-  await applyMcpScaffoldPlan(options.rootDir, plan)
-
-  return {
-    instructionsPath: plan.instructionsPath,
-    skillDirectories: plan.skillDirectories,
-    commandFiles: plan.commandFiles,
-    generatedFiles: plan.generatedFiles,
-    generatedHookMode: plan.generatedHookMode,
-    generatedHookEvents: plan.generatedHookEvents,
-    metadataPath: plan.metadataPath,
-  }
-}
-
-export async function applyMcpScaffoldPlan(rootDir: string, plan: McpScaffoldPlan): Promise<void> {
-  for (const file of plan.files) {
-    const filePath = resolve(rootDir, file.relativePath)
-    const parentDir = file.relativePath.split('/').slice(0, -1).join('/')
-    if (parentDir) {
-      await mkdir(resolve(rootDir, parentDir), { recursive: true })
-    }
-    await Bun.write(filePath, file.content)
-  }
-}
-
-export async function planMcpScaffold(options: McpScaffoldOptions): Promise<McpScaffoldPlan> {
-  const pluginName = toKebabCase(options.pluginName) || 'mcp-plugin'
-  const displayName = options.displayName
-    ?? options.introspection.serverInfo.title
-    ?? humanizeName(pluginName)
-  const description = options.description
-    ?? options.introspection.serverInfo.description
-    ?? `Generated from the ${displayName} MCP server.`
-  const serverName = options.serverName
-    ?? toKebabCase(options.introspection.serverInfo.name)
-    ?? pluginName
-  const runtimeAuthMode = options.runtimeAuthMode ?? 'inline'
-
-  const instructionsPath = resolve(options.rootDir, 'INSTRUCTIONS.md')
-  const skillRoot = resolve(options.rootDir, 'skills')
-  const commandsRoot = resolve(options.rootDir, 'commands')
-  const plannedSkills = planSkillScaffoldsFromPersisted(
-    options.introspection.tools,
-    options.skillGrouping,
-    options.persistedSkills,
-    options.toolRenames,
-  )
-  const userConfigSource = {
-    targets: options.targets,
-    mcp: {
-      [serverName]: options.source,
-    },
-    platforms: runtimeAuthMode === 'platform'
-      ? {
-          'claude-code': { mcpAuth: 'platform' as const },
-          cursor: { mcpAuth: 'platform' as const },
-        }
-      : undefined,
-  } as PluginConfig
-  const userConfig = collectUserConfigEntries(userConfigSource)
-    .map(({ source: _source, ...entry }) => entry)
-  const skillDirectories: string[] = []
-  const commandFiles: string[] = []
-  const generatedFiles = ['pluxx.config.ts', './INSTRUCTIONS.md']
-  const generatedHooks = planGeneratedHooks(options.source, options.introspection.tools, serverName, options.hookMode)
-  const metadataPath = MCP_SCAFFOLD_METADATA_PATH
-  const taxonomyPath = MCP_TAXONOMY_PATH
-  const files: McpScaffoldPlannedFile[] = []
-
-  const addPlannedFile = async (relativePath: string, content: string) => {
-    const filePath = resolve(options.rootDir, relativePath)
-    const action = existsSync(filePath)
-      ? ((await Bun.file(filePath).text()) === content ? 'unchanged' : 'update')
-      : 'create'
-    files.push({ relativePath, content, action })
-  }
-
-  await addPlannedFile(
-    'pluxx.config.ts',
-    buildConfigTemplate({
-      pluginName,
-      authorName: options.authorName,
-      description,
-      displayName,
-      serverName,
-      source: options.source,
-      websiteUrl: options.introspection.serverInfo.websiteUrl,
-      targets: options.targets,
-      userConfig,
-      hooks: generatedHooks.hookEntries,
-      scriptsPath: generatedHooks.scriptsPath,
-      runtimeAuthMode,
-      commandsPath: './commands/',
-    }),
-  )
-
-  await addPlannedFile(
-    './INSTRUCTIONS.md',
-    wrapManagedMarkdown(
-        buildInstructionsContent({
-          displayName,
-          description,
-          source: options.source,
-          runtimeAuthMode,
-          instructions: options.introspection.instructions,
-          skills: plannedSkills,
-          tools: options.introspection.tools,
-          userConfig,
-        }),
-      existsSync(instructionsPath) ? await Bun.file(instructionsPath).text() : undefined,
-      {
-        customHeading: '## Custom Instructions',
-        defaultCustomContent: DEFAULT_INSTRUCTIONS_CUSTOM_CONTENT,
-      },
-    ),
-  )
-
-  for (const skill of plannedSkills) {
-    const relativeSkillPath = `skills/${skill.dirName}`
-    const skillPath = resolve(skillRoot, skill.dirName, 'SKILL.md')
-    const relativeCommandPath = `commands/${skill.dirName}.md`
-    const commandPath = resolve(commandsRoot, `${skill.dirName}.md`)
-    await addPlannedFile(
-      `${relativeSkillPath}/SKILL.md`,
-      wrapManagedMarkdown(
-        buildSkillContent(skill),
-        existsSync(skillPath) ? await Bun.file(skillPath).text() : undefined,
-        {
-          customHeading: '## Custom Notes',
-          defaultCustomContent: DEFAULT_SKILL_CUSTOM_CONTENT,
-        },
-      ),
-    )
-    skillDirectories.push(relativeSkillPath)
-    generatedFiles.push(`${relativeSkillPath}/SKILL.md`)
-
-    await addPlannedFile(
-      relativeCommandPath,
-      buildCommandContent(
-        skill,
-        existsSync(commandPath) ? await Bun.file(commandPath).text() : undefined,
-      ),
-    )
-    commandFiles.push(relativeCommandPath)
-    generatedFiles.push(relativeCommandPath)
-  }
-
-  for (const file of generatedHooks.files) {
-    await addPlannedFile(file.relativePath, file.content)
-    generatedFiles.push(file.relativePath)
-  }
-
-  const metadata = buildMcpScaffoldMetadata({
-    source: options.source,
-    introspection: options.introspection,
-    pluginName,
-    displayName,
-    skillGrouping: options.skillGrouping ?? 'workflow',
-    requestedHookMode: options.hookMode ?? 'none',
-    generatedHookMode: generatedHooks.mode,
-    generatedHookEvents: Object.keys(generatedHooks.hookEntries ?? {}),
-    runtimeAuthMode,
-    userConfig,
-    plannedSkills,
-    managedFiles: [...generatedFiles, taxonomyPath, metadataPath],
-  })
-  await addPlannedFile(taxonomyPath, `${JSON.stringify(buildPersistedTaxonomy(plannedSkills), null, 2)}\n`)
-  generatedFiles.push(taxonomyPath)
-  await addPlannedFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`)
-  generatedFiles.push(metadataPath)
-
-  return {
-    instructionsPath: './INSTRUCTIONS.md',
-    skillDirectories,
-    commandFiles,
-    generatedFiles,
-    generatedHookMode: generatedHooks.mode,
-    generatedHookEvents: Object.keys(generatedHooks.hookEntries ?? {}),
-    metadataPath,
-    files,
-  }
-}
-
-export function wrapManagedMarkdown(
-  generatedContent: string,
-  existingContent: string | undefined,
-  options: {
-    customHeading: string
-    defaultCustomContent: string
-  },
-): string {
-  const mixedContent = extractMixedMarkdownContent(existingContent, options.defaultCustomContent)
-  const customContent = mixedContent.customContent.trim() || options.defaultCustomContent
-  const { frontmatter, body } = splitMarkdownFrontmatter(generatedContent.trim())
-
-  const lines = [
-    ...(frontmatter ? [frontmatter, ''] : []),
-    PLUXX_GENERATED_START,
-    body.trim(),
-    PLUXX_GENERATED_END,
-    '',
-    options.customHeading,
-    '',
-    PLUXX_CUSTOM_START,
-    customContent,
-    PLUXX_CUSTOM_END,
-    '',
-  ]
-
-  return lines.join('\n')
-}
-
-function splitMarkdownFrontmatter(content: string): { frontmatter: string; body: string } {
-  const lines = content.split(/\r?\n/)
-  if (lines[0]?.trim() !== '---') {
-    return {
-      frontmatter: '',
-      body: content,
-    }
-  }
-
-  let endIndex = -1
-  for (let index = 1; index < lines.length; index += 1) {
-    if (lines[index].trim() === '---') {
-      endIndex = index
-      break
-    }
-  }
-
-  if (endIndex === -1) {
-    return {
-      frontmatter: '',
-      body: content,
-    }
-  }
-
-  return {
-    frontmatter: lines.slice(0, endIndex + 1).join('\n'),
-    body: lines.slice(endIndex + 1).join('\n').replace(/^\n+/, ''),
-  }
-}
-
-export function extractMixedMarkdownContent(
-  content: string | undefined,
-  defaultCustomContent: string,
-): MixedMarkdownContent {
-  if (!content) {
-    return {
-      hasMarkers: false,
-      customContent: defaultCustomContent,
-    }
-  }
-
-  const customStart = content.indexOf(PLUXX_CUSTOM_START)
-  const customEnd = content.indexOf(PLUXX_CUSTOM_END)
-
-  if (customStart !== -1 && customEnd !== -1 && customEnd > customStart) {
-    const customContent = content
-      .slice(customStart + PLUXX_CUSTOM_START.length, customEnd)
-      .trim()
-
-    return {
-      hasMarkers: true,
-      customContent: customContent || defaultCustomContent,
-    }
-  }
-
-  const trimmed = content.trim()
-  return {
-    hasMarkers: false,
-    customContent: trimmed
-      ? `${LEGACY_MIXED_CONTENT_NOTE}\n\n${trimmed}`
-      : defaultCustomContent,
-  }
-}
-
-export function hasMeaningfulCustomContent(content: string | undefined): boolean {
-  if (!content) return false
-
-  const extracted = extractMixedMarkdownContent(content, DEFAULT_INSTRUCTIONS_CUSTOM_CONTENT)
-  const normalized = extracted.customContent.trim()
-
-  return normalized !== '' && normalized !== DEFAULT_INSTRUCTIONS_CUSTOM_CONTENT && normalized !== DEFAULT_SKILL_CUSTOM_CONTENT
-}
-
-export function buildSkillContent(skill: PlannedSkill): string {
-  const description = buildSkillFrontmatterDescription(skill)
-  const exampleRequests = skill.tools
-    .map((tool) => buildToolExampleRequest(tool))
-    .filter((example, index, values) => values.indexOf(example) === index)
-
-  const lines = [
-    '---',
-    `name: ${JSON.stringify(skill.dirName)}`,
-    `description: ${JSON.stringify(description)}`,
-    '---',
-    '',
-    `# ${skill.title}`,
-    '',
-    skill.description,
-    '',
-    '## Tools In This Skill',
-    '',
-  ]
-
-  for (const tool of skill.tools) {
-    lines.push(`### \`${tool.name}\``)
-    lines.push('')
-    lines.push(tool.description ?? `Calls \`${tool.name}\` on the configured MCP server.`)
-    lines.push('')
-
-    const fields = getTopLevelSchemaFields(tool.inputSchema)
-    if (fields.length > 0) {
-      lines.push('Inputs:')
-      for (const field of fields) {
-        const required = field.required ? ', required' : ''
-        const detail = field.description ? `: ${field.description}` : ''
-        lines.push(`- \`${field.name}\` (${field.type}${required})${detail}`)
-      }
-      lines.push('')
-    }
-  }
-
-  lines.push(
-    '## Example Requests',
-    '',
-  )
-
-  for (const example of exampleRequests) {
-    lines.push(`- "${example}"`)
-  }
-
-  lines.push(
-    '',
-    '## Usage',
-    '',
-    '- Pick the most specific tool in this skill for the user request.',
-    '- Gather required inputs before calling a tool.',
-    '- Summarize the returned data clearly instead of dumping raw JSON unless the user asks for it.',
-    '',
-  )
-
-  return lines.join('\n')
-}
-
-export function buildCommandContent(skill: PlannedSkill, existingContent?: string): string {
-  const description = truncate(cleanSingleLineText(skill.description), 140)
-  const argumentHint = inferCommandArgumentHint(skill)
-  const generatedContent = [
-    '---',
-    `description: ${JSON.stringify(description)}`,
-    `argument-hint: ${JSON.stringify(argumentHint)}`,
-    '---',
-    '',
-    `Use the ${skill.title.toLowerCase()} workflow for this plugin.`,
-    '',
-    'Arguments: $ARGUMENTS',
-    '',
-    'Primary tools:',
-    ...skill.tools.map((tool) => `- \`${tool.name}\``),
-    '',
-    'Workflow:',
-    '',
-    '1. Interpret `$ARGUMENTS` as the user request for this workflow.',
-    '2. Choose the most specific tool in this surface.',
-    '3. Ask for missing required inputs only if the request does not already provide them.',
-    '4. Return a concise task-focused answer instead of raw JSON unless the user asks for it.',
-  ].join('\n')
-
-  return wrapManagedMarkdown(
-    generatedContent,
-    existingContent,
-    {
-      customHeading: '## Custom Notes',
-      defaultCustomContent: DEFAULT_SKILL_CUSTOM_CONTENT,
-    },
-  )
-}
-
-export function buildInstructionsContent(input: {
-  displayName: string
-  description: string
-  source: McpServer
-  runtimeAuthMode?: McpRuntimeAuthMode
-  instructions?: string
-  skills: PlannedSkill[]
-  tools: IntrospectedMcpTool[]
-  userConfig?: UserConfigEntry[]
-}): string {
-  const accessLine = describePluginAccess(input.displayName, input.source, input.runtimeAuthMode ?? 'inline')
-  const lines = [
-    `# ${input.displayName}`,
-    '',
-    input.description,
-    '',
-    accessLine,
-    '',
-    '## Workflow Guidance',
-    '',
-  ]
-
-  for (const skill of input.skills) {
-    lines.push(`- ${buildInstructionSkillSummary(skill)}`)
-  }
-
-  lines.push(
-    '',
-    '## Tool Routing',
-    '',
-  )
-
-  for (const tool of input.tools) {
-    lines.push(`- \`${tool.name}\`: ${summarizeToolForInstructions(tool)}`)
-  }
-
-  lines.push(
-    '',
-    '## Operating Notes',
-    '',
-    '- Prefer the most specific tool that matches the user request.',
-    '- Confirm required inputs before calling a tool.',
-    '- Summarize returned data instead of dumping raw JSON unless the user asks for it.',
-  )
-
-  if (input.userConfig && input.userConfig.length > 0) {
-    lines.push('', '## User Config', '')
-    for (const item of input.userConfig) {
-      const descriptor = [item.type ?? 'string', item.required === false ? 'optional' : 'required']
-        .filter(Boolean)
-        .join(', ')
-      const envVar = item.envVar ? ` — env: \`${item.envVar}\`` : ''
-      lines.push(`- \`${item.key}\` (${item.title}; ${descriptor})${envVar}: ${item.description}`)
-    }
-  }
-
-  if (input.instructions) {
-    const serverGuidance = summarizeServerGuidance(input.instructions)
-    if (serverGuidance.length > 0) {
-      lines.push('', '## Server Guidance', '')
-      for (const item of serverGuidance) {
-        lines.push(`- ${item}`)
-      }
-    }
-  }
-
-  lines.push('')
-  return lines.join('\n')
-}
-
-export function buildConfigTemplate(input: {
-  pluginName: string
-  authorName: string
-  description: string
-  displayName: string
-  serverName: string
-  source: McpServer
-  websiteUrl?: string
-  targets: TargetPlatform[]
-  userConfig?: UserConfigEntry[]
-  hooks?: Record<string, HookEntry[]>
-  scriptsPath?: string
-  runtimeAuthMode?: McpRuntimeAuthMode
-  commandsPath?: string
-}): string {
-  const targets = input.targets.map((target) => JSON.stringify(target)).join(', ')
-  const mcpBlock = buildMcpBlock(input.serverName, input.source)
-  const brandFields = [
-    `displayName: ${JSON.stringify(input.displayName)}`,
-    input.websiteUrl ? `websiteURL: ${JSON.stringify(input.websiteUrl)}` : null,
-  ].filter(Boolean).join(',\n    ')
-  const userConfigBlock = input.userConfig && input.userConfig.length > 0
-    ? `\n  userConfig: ${serializeUserConfig(input.userConfig)},\n`
-    : ''
-  const scriptsBlock = input.scriptsPath ? `  scripts: ${JSON.stringify(input.scriptsPath)},\n` : ''
-  const commandsBlock = input.commandsPath ? `  commands: ${JSON.stringify(input.commandsPath)},\n` : ''
-  const hooksBlock = input.hooks ? `\n  hooks: ${serializeHooks(input.hooks)},\n` : ''
-  const platformsBlock = input.runtimeAuthMode === 'platform'
-    ? `\n  platforms: {\n    'claude-code': {\n      mcpAuth: 'platform',\n    },\n    cursor: {\n      mcpAuth: 'platform',\n    },\n  },\n`
-    : ''
-
-  return `import { definePlugin } from 'pluxx'
-
-export default definePlugin({
-  name: ${JSON.stringify(input.pluginName)},
-  version: '0.1.0',
-  description: ${JSON.stringify(input.description)},
-  author: {
-    name: ${JSON.stringify(input.authorName)},
-  },
-  license: 'MIT',
-
-  skills: './skills/',
-${commandsBlock}
-  instructions: './INSTRUCTIONS.md',
-${userConfigBlock}
-${scriptsBlock}
-
-  mcp: {
-${mcpBlock}
-  },
-${hooksBlock}
-${platformsBlock}
-
-  brand: {
-    ${brandFields}
-  },
-
-  targets: [${targets}],
-})
-`
-}
-
-function buildMcpBlock(serverName: string, source: McpServer): string {
-  if (source.transport === 'stdio') {
-    const argsLine = source.args && source.args.length > 0
-      ? `,\n      args: ${JSON.stringify(source.args)}`
-      : ''
-    const envLine = source.env && Object.keys(source.env).length > 0
-      ? `,\n      env: ${JSON.stringify(source.env, null, 6).replace(/\n/g, '\n      ')}`
-      : ''
-
-    return `    ${JSON.stringify(serverName)}: {
-      transport: 'stdio',
-      command: ${JSON.stringify(source.command)}${argsLine}${envLine}
-    },`
-  }
-
-  const authLine = source.auth && source.auth.type !== 'none'
-    ? source.auth.type === 'platform'
-      ? `,\n      auth: {\n        type: 'platform',\n        mode: ${JSON.stringify(source.auth.mode ?? 'oauth')}\n      }`
-      : `,\n      auth: {\n        type: ${JSON.stringify(source.auth.type)},\n        envVar: ${JSON.stringify(source.auth.envVar)}${source.auth.type === 'header'
-          ? `,\n        headerName: ${JSON.stringify(source.auth.headerName)},\n        headerTemplate: ${JSON.stringify(source.auth.headerTemplate)}`
-          : ''}\n      }`
-    : ''
-  const transportLine = source.transport === 'sse'
-    ? `\n      transport: 'sse',`
-    : ''
-
-  return `    ${JSON.stringify(serverName)}: {${transportLine}
-      url: ${JSON.stringify(source.url)}${authLine}
-    },`
-}
-
-function serializeHooks(hooks: Record<string, HookEntry[]>): string {
-  const entries = Object.entries(hooks)
-    .map(([event, hookEntries]) => {
-      const serializedEntries = hookEntries
-        .map((entry) => {
-          const fields = [
-            entry.type && entry.type !== 'command' ? `type: ${JSON.stringify(entry.type)}` : null,
-            entry.command ? `command: ${JSON.stringify(entry.command)}` : null,
-            entry.prompt ? `prompt: ${JSON.stringify(entry.prompt)}` : null,
-            entry.model ? `model: ${JSON.stringify(entry.model)}` : null,
-            entry.timeout !== undefined ? `timeout: ${entry.timeout}` : null,
-            entry.matcher ? `matcher: ${JSON.stringify(entry.matcher)}` : null,
-            entry.failClosed !== undefined ? `failClosed: ${entry.failClosed}` : null,
-            entry.loop_limit !== undefined ? `loop_limit: ${entry.loop_limit}` : null,
-          ].filter(Boolean)
-
-          return `      {\n        ${fields.join(',\n        ')}\n      }`
-        })
-        .join(',\n')
-
-      return `    ${event}: [\n${serializedEntries}\n    ]`
-    })
-    .join(',\n')
-
-  return `{\n${entries}\n  }`
-}
-
-function serializeUserConfig(userConfig: UserConfigEntry[]): string {
-  const entries = userConfig
-    .map((item) => {
-      const fields = [
-        `key: ${JSON.stringify(item.key)}`,
-        `title: ${JSON.stringify(item.title)}`,
-        `description: ${JSON.stringify(item.description)}`,
-        `type: ${JSON.stringify(item.type ?? 'string')}`,
-        `required: ${item.required ?? true}`,
-        item.envVar ? `envVar: ${JSON.stringify(item.envVar)}` : null,
-        item.defaultValue !== undefined ? `defaultValue: ${JSON.stringify(item.defaultValue)}` : null,
-        item.placeholder ? `placeholder: ${JSON.stringify(item.placeholder)}` : null,
-        item.targets ? `targets: ${JSON.stringify(item.targets)}` : null,
-      ].filter(Boolean)
-
-      return `    {\n      ${fields.join(',\n      ')}\n    }`
-    })
-    .join(',\n')
-
-  return `[\n${entries}\n  ]`
-}
-
-const MUTATING_PREFIXES = [
-  'create', 'add', 'insert',
-  'update', 'edit', 'modify', 'patch',
-  'delete', 'remove', 'destroy', 'drop', 'purge',
-  'bulk', 'send', 'post', 'publish',
-] as const
-
-const MUTATING_PREFIX_PATTERN = new RegExp(`^(${MUTATING_PREFIXES.join('|')})\\b`, 'i')
-
-export function detectMutatingTools(tools: IntrospectedMcpTool[]): string[] {
-  return tools
-    .filter((tool) => {
-      const normalized = normalizeIdentifier(tool.name).trim().toLowerCase()
-      return MUTATING_PREFIX_PATTERN.test(normalized)
-    })
-    .map((tool) => tool.name)
-}
-
-function planGeneratedHooks(source: McpServer, tools: IntrospectedMcpTool[], serverName: string, hookMode: McpHookMode = 'none'): GeneratedHookScaffold {
-  if (hookMode !== 'safe') {
-    return { mode: 'none', files: [] }
-  }
-
-  const envVars = collectRequiredEnvVars(source)
-  const mutatingTools = detectMutatingTools(tools)
-
-  if (envVars.length === 0 && mutatingTools.length === 0) {
-    return { mode: 'none', files: [] }
-  }
-
-  const hookEntries: Record<string, HookEntry[]> = {}
-  const files: Array<{ relativePath: string; content: string }> = []
-
-  if (envVars.length > 0) {
-    hookEntries.sessionStart = [{
-      type: 'command',
-      command: 'bash "${PLUGIN_ROOT}/scripts/check-env.sh"',
-    }]
-    files.push({
-      relativePath: 'scripts/check-env.sh',
-      content: buildEnvValidationScript(envVars),
-    })
-  }
-
-  if (mutatingTools.length > 0) {
-    hookEntries.preToolUse = mutatingTools.map((toolName) => ({
-      type: 'command',
-      command: 'bash "${PLUGIN_ROOT}/scripts/confirm-mutation.sh"',
-      matcher: buildMcpToolMatcher(serverName, toolName),
-    }))
-    files.push({
-      relativePath: 'scripts/confirm-mutation.sh',
-      content: buildMutationConfirmationScript(mutatingTools),
-    })
-  }
-
-  return {
-    mode: 'safe',
-    scriptsPath: './scripts/',
-    hookEntries,
-    files,
-  }
-}
-
-export function buildMutationConfirmationScript(mutatingTools: string[]): string {
-  const toolList = JSON.stringify(mutatingTools.map(sanitizeShellCommentText))
-  return `#!/usr/bin/env bash
-set -euo pipefail
-# This hook runs before mutating MCP tools.
-# The platform will prompt the user for confirmation.
-# Mutating tools: ${toolList}
-echo "pluxx: This tool modifies data. The agent should confirm before proceeding." >&2
-`
-}
-
-function collectRequiredEnvVars(source: McpServer): string[] {
-  const envVars = new Set<string>()
-
-  if (source.auth?.type && source.auth.type !== 'none' && source.auth.type !== 'platform') {
-    if (isValidShellEnvVarName(source.auth.envVar)) {
-      envVars.add(source.auth.envVar)
-    }
-  }
-
-  if (source.transport === 'stdio') {
-    for (const key of Object.keys(source.env ?? {})) {
-      if (isValidShellEnvVarName(key)) {
-        envVars.add(key)
-      }
-    }
-  }
-
-  return [...envVars]
-}
-
-function buildEnvValidationScript(envVars: string[]): string {
-  const checks = envVars
-    .map((envVar) => `if [ -z "\${${envVar}:-}" ]; then
-  echo "pluxx: ${envVar} is not set. Export it before using this plugin." >&2
-  exit 1
-fi`)
-    .join('\n\n')
-
-  return `#!/usr/bin/env bash
-set -euo pipefail
-
-${checks}
-`
-}
-
-function buildMcpToolMatcher(serverName: string, toolName: string): string {
-  return `mcp__${serverName}__${toolName}`
-}
-
-function sanitizeShellCommentText(value: string): string {
-  return value.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, ' ').trim()
-}
-
-function isValidShellEnvVarName(value: string): boolean {
-  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value)
-}
-
-function buildMcpScaffoldMetadata(input: {
-  source: McpServer
-  introspection: IntrospectedMcpServer
-  pluginName: string
-  displayName: string
-  skillGrouping: McpSkillGrouping
-  requestedHookMode: McpHookMode
-  generatedHookMode: McpHookMode
-  generatedHookEvents: string[]
-  runtimeAuthMode: McpRuntimeAuthMode
-  userConfig: UserConfigEntry[]
-  plannedSkills: PlannedSkill[]
-  managedFiles: string[]
-}): McpScaffoldMetadata {
-  return {
-    version: 1,
-    source: input.source,
-    serverInfo: input.introspection.serverInfo,
-    settings: {
-      pluginName: input.pluginName,
-      displayName: input.displayName,
-      skillGrouping: input.skillGrouping,
-      requestedHookMode: input.requestedHookMode,
-      generatedHookMode: input.generatedHookMode,
-      generatedHookEvents: input.generatedHookEvents,
-      runtimeAuthMode: input.runtimeAuthMode,
-    },
-    userConfig: input.userConfig,
-    tools: input.introspection.tools,
-    skills: input.plannedSkills.map((skill) => ({
-      dirName: skill.dirName,
-      title: skill.title,
-      description: skill.description,
-      toolNames: skill.tools.map((tool) => tool.name),
-    })),
-    managedFiles: input.managedFiles,
-  }
-}
-
-export function planSkillScaffolds(
-  tools: IntrospectedMcpTool[],
-  grouping: McpSkillGrouping = 'workflow',
-): PlannedSkill[] {
-  if (grouping === 'tool') {
-    return allocateSkillDirectoryNames(
-      tools
-        .sort((a, b) => a.name.localeCompare(b.name))
-        .map((tool) => ({
-          dirName: toKebabCase(tool.name) || 'tool',
-          title: tool.title ?? humanizeName(tool.name),
-          description: tool.description ?? `Use the \`${tool.name}\` MCP tool for this workflow.`,
-          tools: [tool],
-        })),
-    )
-  }
-
-  const categoryBuckets = new Map<string, IntrospectedMcpTool[]>()
-  const standaloneTools: IntrospectedMcpTool[] = []
-
-  for (const tool of tools) {
-    const category = classifyToolWorkflow(tool)
-    if (!category) {
-      standaloneTools.push(tool)
-      continue
-    }
-
-    const bucket = categoryBuckets.get(category) ?? []
-    bucket.push(tool)
-    categoryBuckets.set(category, bucket)
-  }
-
-  const plannedSkills: PlannedSkill[] = []
-
-  for (const definition of WORKFLOW_SKILL_DEFINITIONS) {
-    const bucket = categoryBuckets.get(definition.key)
-    if (!bucket || bucket.length === 0) continue
-
-    plannedSkills.push({
-      dirName: definition.key,
-      title: definition.title,
-      description: definition.description,
-      tools: bucket.sort((a, b) => a.name.localeCompare(b.name)),
-    })
-  }
-
-  for (const tool of standaloneTools.sort((a, b) => a.name.localeCompare(b.name))) {
-    plannedSkills.push({
-      dirName: toKebabCase(tool.name) || 'tool',
-      title: tool.title ?? humanizeName(tool.name),
-      description: tool.description ?? `Use the \`${tool.name}\` MCP tool for this workflow.`,
-      tools: [tool],
-    })
-  }
-
-  return allocateSkillDirectoryNames(plannedSkills)
-}
-
-function planSkillScaffoldsFromPersisted(
-  tools: IntrospectedMcpTool[],
-  grouping: McpSkillGrouping = 'workflow',
-  persistedSkills: PersistedSkill[] = [],
-  toolRenames: Map<string, string> = new Map(),
-): PlannedSkill[] {
-  if (persistedSkills.length === 0) {
-    return planSkillScaffolds(tools, grouping)
-  }
-
-  const toolByName = new Map(tools.map((tool) => [tool.name, tool]))
-  const assigned = new Set<string>()
-  const planned: PlannedSkill[] = []
-
-  for (const skill of persistedSkills) {
-    const matchedTools: IntrospectedMcpTool[] = []
-
-    for (const originalToolName of skill.toolNames) {
-      const resolvedToolName = toolRenames.get(originalToolName) ?? originalToolName
-      const tool = toolByName.get(resolvedToolName)
-      if (!tool || assigned.has(tool.name)) continue
-      matchedTools.push(tool)
-      assigned.add(tool.name)
-    }
-
-    if (matchedTools.length === 0) continue
-
-    planned.push({
-      dirName: skill.dirName,
-      title: skill.title,
-      description: skill.description ?? `Handle ${skill.title.toLowerCase()} workflows.`,
-      tools: matchedTools,
-    })
-  }
-
-  const remainingTools = tools.filter((tool) => !assigned.has(tool.name))
-  if (remainingTools.length > 0) {
-    planned.push(...planSkillScaffolds(remainingTools, grouping))
-  }
-
-  return allocateSkillDirectoryNames(planned)
-}
-
-function buildPersistedTaxonomy(skills: PlannedSkill[]): PersistedSkill[] {
-  return skills.map((skill) => ({
-    dirName: skill.dirName,
-    title: skill.title,
-    description: skill.description,
-    toolNames: skill.tools.map((tool) => tool.name),
-  }))
-}
-
-export function analyzeMcpQuality(
-  tools: IntrospectedMcpTool[],
-  plannedSkills: PlannedSkill[] = planSkillScaffolds(tools, 'workflow'),
-): McpQualityReport {
-  const issues: McpQualityIssue[] = []
-
-  const genericNameTools = tools.filter((tool) => {
-    const normalized = toKebabCase(tool.name)
-    return GENERIC_TOOL_NAMES.has(normalized)
-  })
-
-  if (genericNameTools.length > 0) {
-    issues.push({
-      level: 'warning',
-      code: 'generic-tool-names',
-      title: 'Generic MCP tool names',
-      detail: `${genericNameTools.length} tool(s) use generic names: ${genericNameTools.slice(0, 5).map((tool) => tool.name).join(', ')}`,
-      fix: 'Add sharper tool names or use Agent Mode with docs/website context to recover better taxonomy.',
-    })
-  }
-
-  const missingDescriptionTools = tools.filter((tool) => cleanSingleLineText(tool.description).length < 12)
-  if (missingDescriptionTools.length > 0) {
-    issues.push({
-      level: 'warning',
-      code: 'missing-tool-descriptions',
-      title: 'Weak MCP tool descriptions',
-      detail: `${missingDescriptionTools.length} tool(s) have missing or too-short descriptions.`,
-      fix: 'Add clearer tool descriptions, or expect the scaffold to need more agent refinement.',
-    })
-  }
-
-  const verboseDescriptionTools = tools.filter((tool) => {
-    const description = tool.description ?? ''
-    return description.includes('\n') || /returns:|args:|usage:|example:/i.test(description) || description.length > 260
-  })
-  if (verboseDescriptionTools.length > 0) {
-    issues.push({
-      level: 'info',
-      code: 'verbose-tool-descriptions',
-      title: 'Tool descriptions look documentation-shaped',
-      detail: `${verboseDescriptionTools.length} tool(s) include long or multiline help text that may need agent cleanup in skills and instructions.`,
-      fix: 'Use autopilot or rerun agent refinement with docs/website context so the output becomes more product-shaped.',
-    })
-  }
-
-  const weakSchemaTools = tools.filter((tool) => {
-    const fields = getTopLevelSchemaFields(tool.inputSchema)
-    return fields.length >= 2 && fields.every((field) => !field.description)
-  })
-  if (weakSchemaTools.length > 0) {
-    issues.push({
-      level: 'info',
-      code: 'weak-input-schemas',
-      title: 'Input schemas lack field descriptions',
-      detail: `${weakSchemaTools.length} tool(s) define multi-field input schemas without per-field descriptions.`,
-      fix: 'Add input field descriptions or provide docs/context so agents can infer better examples and guidance.',
-    })
-  }
-
-  const workflowFallbackSkills = plannedSkills.filter((skill) => skill.tools.length === 1 && toKebabCase(skill.tools[0]?.name ?? '') === skill.dirName)
-  if (workflowFallbackSkills.length >= 2) {
-    issues.push({
-      level: 'warning',
-      code: 'workflow-fallback-skills',
-      title: 'Workflow grouping fell back to tool-level buckets',
-      detail: `${workflowFallbackSkills.length} generated skill(s) are still direct tool wrappers, which usually means the MCP metadata is too weak for clean workflow grouping.`,
-      fix: 'Use docs/website context, add pluxx.agent.md hints, or improve the MCP tool metadata before publishing.',
-    })
-  }
-
-  const warnings = issues.filter((issue) => issue.level === 'warning').length
-  const infos = issues.filter((issue) => issue.level === 'info').length
-
-  return {
-    ok: warnings === 0,
-    warnings,
-    infos,
-    issues,
-  }
-}
-
-function allocateSkillDirectoryNames(skills: PlannedSkill[]): PlannedSkill[] {
-  const used = new Set<string>()
-
-  return skills.map((skill) => {
-    const base = toKebabCase(skill.dirName) || 'skill'
-    let candidate = base
-    let suffix = 2
-
-    while (used.has(candidate)) {
-      candidate = `${base}-${suffix}`
-      suffix += 1
-    }
-
-    used.add(candidate)
-    return {
-      ...skill,
-      dirName: candidate,
-    }
-  })
-}
-
-function classifyToolWorkflow(tool: IntrospectedMcpTool): string | null {
-  const primaryText = [
-    normalizeIdentifier(tool.name).toLowerCase(),
-    normalizeIdentifier(tool.title ?? '').toLowerCase(),
-  ].join(' ')
-  const secondaryText = (tool.description ?? '').toLowerCase()
-
-  let bestMatch: string | null = null
-  let bestScore = 0
-
-  for (const definition of WORKFLOW_SKILL_DEFINITIONS) {
-    let score = 0
-
-    for (const needle of definition.match) {
-      if (primaryText.includes(needle)) {
-        score += 3
-      }
-      if (secondaryText.includes(needle)) {
-        score += 1
-      }
-    }
-
-    if (score > bestScore) {
-      bestScore = score
-      bestMatch = definition.key
-    }
-  }
-
-  return bestMatch
-}
-
-function buildSkillFrontmatterDescription(skill: PlannedSkill): string {
-  if (skill.tools.length === 1) {
-    const tool = skill.tools[0]
-    const cleanedDescription = cleanSingleLineText(tool.description)
-    const sentence = firstSentenceOf(cleanedDescription)
-
-    if (sentence) {
-      return truncate(sentence, 220)
-    }
-  }
-
-  return truncate(cleanSingleLineText(skill.description), 220)
-}
-
-function buildInstructionSkillSummary(skill: PlannedSkill): string {
-  const toolNames = skill.tools.map((tool) => `\`${tool.name}\``).join(', ')
-  const description = truncate(cleanSingleLineText(skill.description), 180)
-  return `\`${skill.dirName}\`: ${description} Primary tools: ${toolNames}.`
-}
-
-function inferCommandArgumentHint(skill: PlannedSkill): string {
-  const fieldHints = new Set<string>()
-
-  for (const tool of skill.tools) {
-    const fields = getTopLevelSchemaFields(tool.inputSchema)
-    const prioritizedFields = fields.filter((field) => field.required)
-    const candidates = (prioritizedFields.length > 0 ? prioritizedFields : fields).slice(0, 2)
-
-    for (const field of candidates) {
-      fieldHints.add(mapSchemaFieldToArgumentHint(field.name))
-      if (fieldHints.size >= 2) break
-    }
-
-    if (fieldHints.size >= 2) break
-  }
-
-  if (fieldHints.size === 0) {
-    return '[request]'
-  }
-
-  return [...fieldHints].slice(0, 2).map((hint) => `[${hint}]`).join(' ')
-}
-
-function mapSchemaFieldToArgumentHint(fieldName: string): string {
-  const value = fieldName.toLowerCase()
-
-  if (value.includes('query') || value.includes('search') || value.includes('keyword')) return 'query'
-  if (value.includes('company') || value.includes('organization') || value.includes('organisation') || value.includes('account')) return 'company'
-  if (value.includes('role') || value.includes('title')) return 'role'
-  if (value.includes('domain')) return 'domain'
-  if (value.includes('url')) return 'url'
-  if (value.includes('email')) return 'email'
-  if (value === 'id' || value.endsWith('id')) return 'id'
-  if (value.includes('name')) return 'name'
-
-  return value.replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'request'
-}
-
-function summarizeToolForInstructions(tool: IntrospectedMcpTool): string {
-  const fallback = 'Use this tool when its inputs match the user request.'
-  const description = tool.description ?? ''
-  const base = firstSentenceOf(cleanSingleLineText(description))
-  const bestFor = extractLabeledGuidance(description, 'Best for')
-  const useWhen = extractLabeledGuidance(description, 'Use when')
-
-  const parts = [base].filter(Boolean)
-  const guidance = bestFor || useWhen
-
-  if (guidance) {
-    parts.push(`Best for: ${guidance}.`)
-  }
-
-  if (parts.length === 0) {
-    return fallback
-  }
-
-  return truncate(parts.join(' '), 240)
-}
-
-function summarizeServerGuidance(value: string): string[] {
-  const lines = value
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .filter((line) => !line.startsWith('```'))
-    .map((line) => line.replace(/^#+\s*/, ''))
-    .map((line) => line.replace(/^[-*]\s+/, ''))
-    .filter((line) => !/^example:?$/i.test(line))
-    .map((line) => truncate(cleanSingleLineText(line), 220))
-    .filter(Boolean)
-
-  return [...new Set(lines)].slice(0, 4)
-}
-
-function extractLabeledGuidance(value: string | undefined, label: string): string {
-  if (!value) return ''
-
-  const normalizedLabel = `${label.toLowerCase()}:`
-  for (const rawLine of value.split('\n')) {
-    const line = rawLine
-      .trim()
-      .replace(/^\*+|\*+$/g, '')
-      .replace(/^[-*]\s*/, '')
-      .replace(/^\*+\s*/, '')
-      .replace(/\s+\*+$/, '')
-    if (!line) continue
-
-    const plain = line.replace(/[*`_]/g, '')
-    if (plain.toLowerCase().startsWith(normalizedLabel)) {
-      return truncate(cleanSingleLineText(plain.slice(normalizedLabel.length).trim()), 160)
-    }
-  }
-
-  return ''
-}
-
-function getTopLevelSchemaFields(inputSchema?: Record<string, unknown>): SchemaField[] {
-  if (!inputSchema) return []
-
-  const rawProperties = inputSchema.properties
-  if (!rawProperties || typeof rawProperties !== 'object') {
-    return []
-  }
-
-  const required = new Set(
-    Array.isArray(inputSchema.required)
-      ? inputSchema.required.filter((value): value is string => typeof value === 'string')
-      : [],
-  )
-
-  return Object.entries(rawProperties).map(([name, value]) => {
-    const schema = typeof value === 'object' && value !== null ? value as Record<string, unknown> : {}
-    return {
-      name,
-      type: formatSchemaType(schema.type),
-      required: required.has(name),
-      description: typeof schema.description === 'string' ? schema.description : undefined,
-    }
-  })
-}
-
-export function buildToolExampleRequest(tool: IntrospectedMcpTool): string {
-  const action = inferToolAction(tool)
-  const objectLabel = inferToolObject(tool)
-  const context = buildToolRequestContext(tool)
-
-  const sentence = context
-    ? `${action} ${objectLabel} ${context}.`
-    : `${action} ${objectLabel}.`
-
-  return sentence.charAt(0).toUpperCase() + sentence.slice(1)
-}
-
-function inferToolAction(tool: IntrospectedMcpTool): string {
-  const identifier = normalizeIdentifier(tool.title ?? tool.name).toLowerCase()
-
-  if (/^(get|fetch|lookup|look up)\b/.test(identifier)) return 'look up'
-  if (/^(create|add)\b/.test(identifier)) return 'create'
-  if (/^(update|edit)\b/.test(identifier)) return 'update'
-  if (/^(delete|remove)\b/.test(identifier)) return 'delete'
-  if (/^(list)\b/.test(identifier)) return 'list'
-  if (/^(query)\b/.test(identifier)) return 'query'
-  if (/^(search)\b/.test(identifier)) return 'search'
-  return 'find'
-}
-
-function inferToolObject(tool: IntrospectedMcpTool): string {
-  const raw = normalizeIdentifier(tool.title ?? tool.name).trim()
-  const stripped = raw.replace(/^(find|get|fetch|lookup|look up|search|list|create|add|update|edit|delete|remove|query)\s+/i, '')
-  const candidate = stripped || raw
-  return candidate ? candidate.toLowerCase() : 'results'
-}
-
-function buildToolRequestContext(tool: IntrospectedMcpTool): string {
-  const requiredFields = getTopLevelSchemaFields(tool.inputSchema).filter((field) => field.required)
-  const preferredField = requiredFields[0]
-
-  if (!preferredField) return ''
-
-  const placeholder = `<${preferredField.name}>`
-  const fieldName = preferredField.name.toLowerCase()
-
-  if (fieldName.endsWith('id') || fieldName === 'id') {
-    return `using ${placeholder}`
-  }
-
-  if (fieldName.includes('query') || fieldName.includes('keyword') || fieldName.includes('search')) {
-    return `matching ${placeholder}`
-  }
-
-  if (fieldName.includes('role') || fieldName.includes('title')) {
-    return `for ${placeholder}`
-  }
-
-  if (fieldName.includes('company') || fieldName.includes('organization') || fieldName.includes('organisation') || fieldName.includes('account')) {
-    return `for ${placeholder}`
-  }
-
-  if (fieldName.includes('domain') || fieldName.includes('email') || fieldName.includes('url')) {
-    return `using ${placeholder}`
-  }
-
-  return `with ${placeholder}`
-}
-
-function formatSchemaType(value: unknown): string {
-  if (typeof value === 'string') return value
-  if (Array.isArray(value)) {
-    const parts = value.filter((entry): entry is string => typeof entry === 'string')
-    if (parts.length > 0) return parts.join(' | ')
-  }
-  return 'unknown'
-}
-
-function describePluginAccess(displayName: string, source: McpServer, runtimeAuthMode: McpRuntimeAuthMode): string {
-  if (source.transport === 'stdio') {
-    const command = [source.command, ...(source.args ?? [])].join(' ')
-    const authLine = describeAuthRequirement(source)
-    return `${displayName} connects through a local stdio MCP command (\`${command}\`).${authLine ? ` ${authLine}` : ''}`
-  }
-
-  const transportLabel = source.transport === 'sse' ? 'legacy SSE' : 'HTTP'
-  const authLine = describeAuthRequirement(source, runtimeAuthMode)
-  return `${displayName} connects to its MCP over ${transportLabel}.${authLine ? ` ${authLine}` : ''}`
-}
-
-function describeAuthRequirement(source: McpServer, runtimeAuthMode: McpRuntimeAuthMode = 'inline'): string {
-  if (runtimeAuthMode === 'platform' && source.transport !== 'stdio') {
-    return 'Claude Code and Cursor use platform-managed auth at runtime (for example native OAuth/custom connector flows). Exported env vars remain useful for scaffold refreshes and other non-platform-managed targets.'
-  }
-
-  if (!source.auth || source.auth.type === 'none') {
-    return ''
-  }
-
-  if (source.auth.type === 'platform') {
-    return 'Use the platform-managed auth flow before calling authenticated tools.'
-  }
-
-  if (source.auth.type === 'header') {
-    return `Export \`${source.auth.envVar}\` so Pluxx can send ${source.auth.headerName ?? 'the required auth header'}.`
-  }
-
-  return `Export \`${source.auth.envVar}\` before using authenticated tools.`
-}
-
-function humanizeName(value: string): string {
-  return normalizeIdentifier(value)
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(' ')
-}
-
-function toKebabCase(value: string): string {
-  return normalizeIdentifier(value)
-    .toLowerCase()
-    .trim()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-}
-
-function normalizeIdentifier(value: string): string {
-  return value
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-    .replace(/[._/]+/g, ' ')
-    .replace(/-/g, ' ')
-}
-
-function truncate(value: string, maxLength: number): string {
-  if (value.length <= maxLength) return value
-  return `${value.slice(0, maxLength - 1).trimEnd()}…`
-}
-
-function cleanSingleLineText(value: string | undefined): string {
-  if (!value) return ''
-
-  return value
-    .replace(/\s+/g, ' ')
-    .replace(/\s*[-*]\s+/g, ' ')
-    .trim()
-}
-
-function firstSentenceOf(value: string): string {
-  if (!value) return ''
-
-  const match = value.match(/^(.+?[.?!])(?:\s|$)/)
-  return (match?.[1] ?? value).trim()
-}
-
-function splitCommandString(command: string): string[] {
-  const parts: string[] = []
-  let current = ''
-  let quote: '"' | "'" | null = null
-  let escaping = false
-
-  for (const char of command) {
-    if (escaping) {
-      current += char
-      escaping = false
-      continue
-    }
-
-    if (char === '\\') {
-      escaping = true
-      continue
-    }
-
-    if (quote) {
-      if (char === quote) {
-        quote = null
-      } else {
-        current += char
-      }
-      continue
-    }
-
-    if (char === '"' || char === "'") {
-      quote = char
-      continue
-    }
-
-    if (/\s/.test(char)) {
-      if (current) {
-        parts.push(current)
-        current = ''
-      }
-      continue
-    }
-
-    current += char
-  }
-
-  if (quote) {
-    throw new Error('Unterminated quote in MCP command.')
-  }
-
-  if (escaping) {
-    current += '\\'
-  }
-
-  if (current) {
-    parts.push(current)
-  }
-
-  return parts
-}
-
-export function derivePluginName(introspection: IntrospectedMcpServer, source: McpServer): string {
-  const candidates = [
-    introspection.serverInfo.name,
-    introspection.serverInfo.title,
-    source.transport === 'stdio' ? basename(source.command) : new URL(source.url).hostname.split('.')[0],
-  ].filter((value): value is string => Boolean(value))
-
-  for (const candidate of candidates) {
-    const normalized = toKebabCase(candidate)
-    if (normalized) return normalized
-  }
-
-  return 'mcp-plugin'
-}