@orchid-labs/pluxx 0.1.0 → 0.1.3

package/src/compatibility/matrix.ts

@@ -1,149 +0,0 @@
-import type { TargetPlatform } from '../schema'
-import { PLATFORM_VALIDATION_RULES, type PlatformRules } from '../validation/platform-rules'
-
-export interface PlatformCompatibilityRow {
-  platform: TargetPlatform
-  status: 'Primary' | 'Beta'
-  docsBasis: string
-  manifest: string
-  hooks: string
-  mcp: string
-  instructions: string
-  verification: string
-}
-
-const ALL_TARGET_PLATFORMS: TargetPlatform[] = [
-  'claude-code',
-  'cursor',
-  'codex',
-  'opencode',
-  'github-copilot',
-  'openhands',
-  'warp',
-  'gemini-cli',
-  'roo-code',
-  'cline',
-  'amp',
-]
-
-const PRIMARY_TARGETS = new Set<TargetPlatform>(['claude-code', 'cursor', 'codex', 'opencode'])
-const RELEASE_SMOKE_TARGETS = new Set<TargetPlatform>(['claude-code', 'cursor', 'codex', 'opencode'])
-const GENERATOR_FIXTURE_TARGETS = new Set<TargetPlatform>(ALL_TARGET_PLATFORMS)
-
-const INHERITED_RULES: Partial<Record<TargetPlatform, keyof typeof PLATFORM_VALIDATION_RULES>> = {
-  'github-copilot': 'claude-code',
-}
-
-function getRuleEntry(platform: TargetPlatform): {
-  rules: PlatformRules
-  docsBasis: string
-} {
-  const directRule = PLATFORM_VALIDATION_RULES[platform as keyof typeof PLATFORM_VALIDATION_RULES]
-  if (directRule) {
-    return {
-      rules: directRule,
-      docsBasis: 'Official docs audited',
-    }
-  }
-
-  const inheritedPlatform = INHERITED_RULES[platform]
-  if (!inheritedPlatform) {
-    throw new Error(`No platform rules available for ${platform}`)
-  }
-
-  return {
-    rules: PLATFORM_VALIDATION_RULES[inheritedPlatform],
-    docsBasis: `Inherits ${humanizePlatformName(inheritedPlatform)} packaging`,
-  }
-}
-
-const PLATFORM_LABELS: Record<TargetPlatform, string> = {
-  'claude-code': 'Claude Code',
-  cursor: 'Cursor',
-  codex: 'Codex',
-  opencode: 'OpenCode',
-  'github-copilot': 'GitHub Copilot',
-  openhands: 'OpenHands',
-  warp: 'Warp',
-  'gemini-cli': 'Gemini CLI',
-  'roo-code': 'Roo Code',
-  cline: 'Cline',
-  amp: 'AMP',
-}
-
-function humanizePlatformName(platform: TargetPlatform): string {
-  return PLATFORM_LABELS[platform]
-}
-
-function formatFiles(files: string[], emptyLabel: string): string {
-  return files.length > 0 ? files.join(', ') : emptyLabel
-}
-
-function getVerificationLabel(platform: TargetPlatform): string {
-  const labels: string[] = []
-
-  if (RELEASE_SMOKE_TARGETS.has(platform)) {
-    labels.push('Release smoke')
-  }
-
-  if (GENERATOR_FIXTURE_TARGETS.has(platform)) {
-    labels.push('Generator fixture')
-  }
-
-  return labels.join(' + ')
-}
-
-export function getPlatformCompatibilityMatrix(): PlatformCompatibilityRow[] {
-  return ALL_TARGET_PLATFORMS.map((platform) => {
-    const { rules, docsBasis } = getRuleEntry(platform)
-
-    return {
-      platform,
-      status: PRIMARY_TARGETS.has(platform) ? 'Primary' : 'Beta',
-      docsBasis,
-      manifest: formatFiles(rules.manifest.files, 'No dedicated manifest'),
-      hooks: rules.hooks.supported
-        ? formatFiles(rules.hooks.files, 'Supported')
-        : 'No documented standalone hook surface',
-      mcp: formatFiles(rules.mcp.files, 'None documented'),
-      instructions: formatFiles(rules.instructions.files, 'None documented'),
-      verification: getVerificationLabel(platform),
-    }
-  })
-}
-
-export function renderCompatibilityMatrixMarkdown(): string {
-  const rows = getPlatformCompatibilityMatrix()
-
-  const lines = [
-    '<!-- Generated by `bun scripts/generate-compatibility-matrix.ts`. Do not edit by hand. -->',
-    '# Compatibility Matrix',
-    '',
-    'This matrix is generated from the repo-owned platform rules and verification surface.',
-    '',
-    'Verification labels:',
-    '- `Release smoke`: exercised end to end by the real CLI against the real example plugins on the core four.',
-    '- `Generator fixture`: covered by the repo build/test fixture layer.',
-    '',
-    '| Platform | Status | Docs Basis | Manifest | Hooks | MCP | Instructions | Verification |',
-    '|----------|--------|------------|----------|-------|-----|--------------|--------------|',
-  ]
-
-  for (const row of rows) {
-    lines.push(
-      `| ${humanizePlatformName(row.platform)} | ${row.status} | ${row.docsBasis} | ${row.manifest} | ${row.hooks} | ${row.mcp} | ${row.instructions} | ${row.verification} |`,
-    )
-  }
-
-  lines.push(
-    '',
-    '## Notes',
-    '',
-    '- The prime-time launch path remains Claude Code, Cursor, Codex, and OpenCode.',
-    '- GitHub Copilot currently inherits the Claude Code packaging model in Pluxx rather than using its own separately audited plugin surface.',
-    '- Beta platforms are generated and fixture-tested, but they do not yet have the same release-smoke coverage as the core four.',
-    '',
-  )
-
-  return `${lines.join('\n')}\n`
-}

package/src/config/define.ts

@@ -1,20 +0,0 @@
-import { type PluginConfig, PluginConfigSchema } from '../schema'
-
-/**
- * Define a plugin configuration with full type checking and validation.
- *
- * Usage in pluxx.config.ts:
- * ```ts
- * import { definePlugin } from 'pluxx'
- *
- * export default definePlugin({
- *   name: 'my-plugin',
- *   description: 'My awesome plugin',
- *   author: { name: 'Me' },
- *   // ...
- * })
- * ```
- */
-export function definePlugin(config: PluginConfig): PluginConfig {
-  return PluginConfigSchema.parse(config)
-}

package/src/config/load.ts

@@ -1,74 +0,0 @@
-import { resolve, extname, dirname } from 'path'
-import { existsSync } from 'fs'
-import { rm } from 'fs/promises'
-import { fileURLToPath, pathToFileURL } from 'url'
-import { PluginConfigSchema, type PluginConfig } from '../schema'
-
-export const CONFIG_FILES = [
-  'pluxx.config.ts',
-  'pluxx.config.js',
-  'pluxx.config.json',
-]
-
-function getRuntimePackageEntry(): string {
-  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
-  const distEntry = resolve(packageRoot, 'dist', 'index.js')
-
-  if (existsSync(distEntry)) {
-    return distEntry
-  }
-
-  return resolve(packageRoot, 'src', 'index.ts')
-}
-
-async function importConfigModule(filepath: string): Promise<unknown> {
-  const ext = extname(filepath)
-  const runtimeEntryUrl = pathToFileURL(getRuntimePackageEntry()).href
-  const source = await Bun.file(filepath).text()
-  const rewritten = source
-    .replace(/from\s+(['"])pluxx\1/g, `from ${JSON.stringify(runtimeEntryUrl)}`)
-    .replace(/import\s+(['"])pluxx\1/g, `import ${JSON.stringify(runtimeEntryUrl)}`)
-
-  const transpiler = new Bun.Transpiler({
-    loader: ext === '.ts' ? 'ts' : 'js',
-  })
-
-  const tempFile = resolve(
-    dirname(filepath),
-    `.pluxx-load-config-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`,
-  )
-  await Bun.write(tempFile, transpiler.transformSync(rewritten))
-
-  try {
-    const mod = await import(`${pathToFileURL(tempFile).href}?t=${Date.now()}`)
-    return mod.default ?? mod
-  } finally {
-    await rm(tempFile, { force: true })
-  }
-}
-
-/**
- * Load and validate a pluxx config from the given directory.
- */
-export async function loadConfig(dir: string = process.cwd()): Promise<PluginConfig> {
-  for (const filename of CONFIG_FILES) {
-    const filepath = resolve(dir, filename)
-    if (!existsSync(filepath)) continue
-
-    const ext = extname(filename)
-
-    if (ext === '.ts' || ext === '.js') {
-      const raw = await importConfigModule(filepath)
-      return PluginConfigSchema.parse(raw)
-    }
-
-    if (ext === '.json') {
-      const text = await Bun.file(filepath).text()
-      return PluginConfigSchema.parse(JSON.parse(text))
-    }
-  }
-
-  throw new Error(
-    `No pluxx config found in ${dir}. Expected one of: ${CONFIG_FILES.join(', ')}`
-  )
-}

package/src/generators/amp/index.ts

@@ -1,63 +0,0 @@
-import { existsSync } from 'fs'
-import { Generator } from '../base'
-import { warnDroppedHookFields } from '../hooks-warning'
-import type { TargetPlatform } from '../../schema'
-
-/**
- * Amp uses AGENT.md for instructions, .amp/settings.json for hooks,
- * MCP config, and skills/ for skills. No plugin manifest.
- */
-export class AmpGenerator extends Generator {
-  readonly platform: TargetPlatform = 'amp'
-
-  async generate(): Promise<void> {
-    await Promise.all([
-      this.generateAgentMd(),
-      this.generateSettings(),
-      this.generateMcpConfig('mcp.json'),
-    ])
-
-    this.copySkills()
-    this.copyScripts()
-  }
-
-  private async generateAgentMd(): Promise<void> {
-    if (!this.config.instructions) return
-    const srcPath = this.resolveConfigPath(this.config.instructions, 'instructions')
-    if (!existsSync(srcPath)) return
-
-    const content = await Bun.file(srcPath).text()
-
-    const agentMd = [
-      `# ${this.config.brand?.displayName ?? this.config.name}`,
-      '',
-      this.config.brand?.shortDescription ?? this.config.description,
-      '',
-      content,
-    ].join('\n')
-
-    await this.writeFile('AGENT.md', agentMd)
-  }
-
-  private async generateSettings(): Promise<void> {
-    if (!this.config.hooks) return
-
-    // Amp hooks use a post-execute format
-    const hooks: Record<string, unknown[]> = {}
-
-    for (const [event, entries] of Object.entries(this.config.hooks)) {
-      if (!entries) continue
-      warnDroppedHookFields(this.platform, event, entries)
-      const commandEntries = entries.filter(entry => entry.type !== 'prompt' && entry.command)
-      if (commandEntries.length === 0) continue
-      hooks[event] = commandEntries.map(entry => ({
-        type: 'post-execute',
-        command: entry.command!.replace('${PLUGIN_ROOT}', '.'),
-        ...(entry.timeout ? { timeout: entry.timeout } : {}),
-      }))
-    }
-
-    await this.writeJson('.amp/settings.json', { hooks })
-  }
-
-}

package/src/generators/base.ts

@@ -1,188 +0,0 @@
-import { resolve, join, relative } from 'path'
-import { mkdirSync, existsSync, cpSync } from 'fs'
-import type { PluginConfig, TargetPlatform, McpServer } from '../schema'
-
-type McpRemoteServer = Exclude<McpServer, { transport: 'stdio' }>
-
-interface McpConfigOptions {
-  includeDefaultAuthHeaders?: boolean
-  transformRemoteEntry?: (context: {
-    name: string
-    server: McpRemoteServer
-    entry: Record<string, unknown>
-  }) => Record<string, unknown>
-}
-
-export abstract class Generator {
-  abstract readonly platform: TargetPlatform
-
-  constructor(
-    protected config: PluginConfig,
-    protected rootDir: string,
-  ) {}
-
-  /** The output directory for this platform */
-  get outDir(): string {
-    return resolve(this.rootDir, this.config.outDir, this.platform)
-  }
-
-  /** Generate all platform-specific files */
-  abstract generate(): Promise<void>
-
-  /** Write a file to the output directory */
-  protected async writeFile(relativePath: string, content: string): Promise<void> {
-    const filepath = join(this.outDir, relativePath)
-    const dir = filepath.substring(0, filepath.lastIndexOf('/'))
-    mkdirSync(dir, { recursive: true })
-    await Bun.write(filepath, content)
-  }
-
-  /** Write JSON to the output directory */
-  protected async writeJson(relativePath: string, data: unknown): Promise<void> {
-    await this.writeFile(relativePath, JSON.stringify(data, null, 2) + '\n')
-  }
-
-  /** Copy a directory from source to output */
-  protected copyDir(srcRelative: string, destRelative: string, configKey: string): void {
-    const src = this.resolveConfigPath(srcRelative, configKey)
-    if (!existsSync(src)) return
-    const dest = join(this.outDir, destRelative)
-    mkdirSync(dest, { recursive: true })
-    cpSync(src, dest, { recursive: true })
-  }
-
-  /** Resolve a user-configured path and ensure it stays within the project root. */
-  protected resolveConfigPath(configPath: string, configKey: string): string {
-    const resolvedPath = resolve(this.rootDir, configPath)
-    const rel = relative(this.rootDir, resolvedPath)
-    if (rel.startsWith('..')) {
-      throw new Error(
-        `${configKey} path "${configPath}" resolves outside the project root.`
-      )
-    }
-    return resolvedPath
-  }
-
-  /** Copy skills directory, applying any platform-specific frontmatter */
-  protected copySkills(): void {
-    this.copyDir(this.config.skills, 'skills/', 'skills')
-  }
-
-  /** Copy commands directory if it exists */
-  protected copyCommands(): void {
-    if (this.config.commands) {
-      this.copyDir(this.config.commands, 'commands/', 'commands')
-    }
-  }
-
-  /** Copy agents directory if it exists */
-  protected copyAgents(): void {
-    if (this.config.agents) {
-      this.copyDir(this.config.agents, 'agents/', 'agents')
-    }
-  }
-
-  /** Copy scripts directory if it exists */
-  protected copyScripts(): void {
-    if (this.config.scripts) {
-      this.copyDir(this.config.scripts, 'scripts/', 'scripts')
-    }
-  }
-
-  /** Copy assets directory if it exists */
-  protected copyAssets(): void {
-    if (this.config.assets) {
-      this.copyDir(this.config.assets, 'assets/', 'assets')
-    }
-  }
-
-  /** Build canonical MCP server configs for target-specific output shaping. */
-  protected buildMcpServers(options: McpConfigOptions = {}): Record<string, unknown> | undefined {
-    if (!this.config.mcp) return undefined
-
-    const {
-      includeDefaultAuthHeaders = true,
-      transformRemoteEntry,
-    } = options
-
-    const mcpServers: Record<string, unknown> = {}
-
-    for (const [name, server] of Object.entries(this.config.mcp)) {
-      if (server.transport === 'stdio') {
-        mcpServers[name] = {
-          command: server.command,
-          args: server.args ?? [],
-          env: server.env ?? {},
-        }
-        continue
-      }
-
-      const remoteServer: McpRemoteServer = server
-
-      let entry: Record<string, unknown> = {
-        url: remoteServer.url,
-      }
-
-      if (includeDefaultAuthHeaders) {
-        const headers = this.getMcpAuthHeaders(remoteServer)
-        if (headers) {
-          entry.headers = headers
-        }
-      }
-
-      if (transformRemoteEntry) {
-        entry = transformRemoteEntry({ name, server: remoteServer, entry })
-      }
-
-      mcpServers[name] = entry
-    }
-
-    return mcpServers
-  }
-
-  protected getMcpAuthMode(): 'inline' | 'platform' {
-    if (this.platform === 'claude-code') {
-      return this.config.platforms?.['claude-code']?.mcpAuth ?? 'inline'
-    }
-
-    if (this.platform === 'cursor') {
-      return this.config.platforms?.cursor?.mcpAuth ?? 'inline'
-    }
-
-    return 'inline'
-  }
-
-  /** Generate MCP config JSON in the common `{ mcpServers }` shape. */
-  protected async generateMcpConfig(relativePath: string, options: McpConfigOptions = {}): Promise<void> {
-    const mcpServers = this.buildMcpServers(options)
-    if (!mcpServers) return
-    await this.writeJson(relativePath, { mcpServers })
-  }
-
-  private getMcpAuthHeaders(server: McpRemoteServer): Record<string, string> | undefined {
-    if (this.getMcpAuthMode() === 'platform' || server.auth?.type === 'platform') {
-      return undefined
-    }
-
-    if (server.auth?.type === 'bearer' && server.auth.envVar) {
-      return {
-        Authorization: `Bearer ${this.getEnvVarReference(server.auth.envVar)}`,
-      }
-    }
-
-    if (server.auth?.type === 'header' && server.auth.envVar) {
-      return {
-        [server.auth.headerName]: server.auth.headerTemplate.replace(
-          '${value}',
-          this.getEnvVarReference(server.auth.envVar),
-        ),
-      }
-    }
-
-    return undefined
-  }
-
-  private getEnvVarReference(envVar: string): string {
-    return `\${${envVar}}`
-  }
-}

package/src/generators/claude-code/index.ts

@@ -1,29 +0,0 @@
-import { Generator } from '../base'
-import { generateClaudeFamilyOutputs } from '../shared/claude-family'
-import type { TargetPlatform } from '../../schema'
-
-export class ClaudeCodeGenerator extends Generator {
-  readonly platform: TargetPlatform = 'claude-code'
-
-  async generate(): Promise<void> {
-    await generateClaudeFamilyOutputs({
-      config: this.config,
-      rootDir: this.rootDir,
-      platform: this.platform,
-      options: {
-        manifestPath: '.claude-plugin/plugin.json',
-        instructionsFile: 'CLAUDE.md',
-        pluginRootVar: 'CLAUDE_PLUGIN_ROOT',
-        includeStandardHooksManifest: false,
-      },
-      writeJson: (relativePath, data) => this.writeJson(relativePath, data),
-      writeFile: (relativePath, content) => this.writeFile(relativePath, content),
-    })
-
-    this.copySkills()
-    this.copyCommands()
-    this.copyAgents()
-    this.copyScripts()
-    this.copyAssets()
-  }
-}

package/src/generators/cline/index.ts

@@ -1,35 +0,0 @@
-import { existsSync } from 'fs'
-import { Generator } from '../base'
-import type { TargetPlatform } from '../../schema'
-
-/**
- * Cline uses .clinerules for instructions, .cline/mcp.json for MCP config,
- * and .cline/skills/ for skills. No plugin manifest.
- */
-export class ClineGenerator extends Generator {
-  readonly platform: TargetPlatform = 'cline'
-
-  async generate(): Promise<void> {
-    await Promise.all([
-      this.generateMcpConfig('.cline/mcp.json'),
-      this.generateRules(),
-    ])
-
-    this.copyClineSkills()
-    this.copyScripts()
-  }
-
-  private async generateRules(): Promise<void> {
-    if (!this.config.instructions) return
-    const srcPath = this.resolveConfigPath(this.config.instructions, 'instructions')
-    if (!existsSync(srcPath)) return
-
-    const content = await Bun.file(srcPath).text()
-    await this.writeFile('.clinerules', content)
-  }
-
-  /** Copy skills into .cline/skills/ instead of the default skills/ */
-  private copyClineSkills(): void {
-    this.copyDir(this.config.skills, '.cline/skills/', 'skills')
-  }
-}

package/src/generators/codex/index.ts

@@ -1,120 +0,0 @@
-import { existsSync } from 'fs'
-import { Generator } from '../base'
-import type { TargetPlatform } from '../../schema'
-
-export class CodexGenerator extends Generator {
-  readonly platform: TargetPlatform = 'codex'
-
-  async generate(): Promise<void> {
-    await Promise.all([
-      this.generateManifest(),
-      this.generateMcpConfig('.mcp.json', {
-        includeDefaultAuthHeaders: false,
-        transformRemoteEntry: ({ name, server }) => {
-          const entry: Record<string, unknown> = {
-            url: server.url,
-          }
-
-          if (server.auth?.type === 'bearer' && server.auth.envVar) {
-            entry.bearer_token_env_var = server.auth.envVar
-          } else if (server.auth?.type === 'header' && server.auth.envVar) {
-            const isBearerAuthorizationHeader =
-              server.auth.headerName === 'Authorization'
-              && server.auth.headerTemplate === 'Bearer ${value}'
-
-            if (isBearerAuthorizationHeader) {
-              entry.bearer_token_env_var = server.auth.envVar
-            } else if (server.auth.headerTemplate === '${value}') {
-              entry.env_http_headers = {
-                [server.auth.headerName]: server.auth.envVar,
-              }
-            } else if (!server.auth.headerTemplate.includes('${value}')) {
-              entry.http_headers = {
-                [server.auth.headerName]: server.auth.headerTemplate,
-              }
-            } else {
-              console.warn(
-                `[pluxx] codex generator: MCP server "${name}" uses auth.type "header" with a templated header Codex cannot express exactly. `
-                + 'Supported Codex auth outputs are bearer_token_env_var, env_http_headers, and http_headers; this header was omitted.'
-              )
-            }
-          }
-
-          return entry
-        },
-      }),
-      this.generateAgentsMd(),
-    ])
-
-    this.copySkills()
-    this.copyAgents()
-    this.copyScripts()
-    this.copyAssets()
-  }
-
-  private async generateManifest(): Promise<void> {
-    const manifest: Record<string, unknown> = {
-      name: this.config.name,
-      version: this.config.version,
-      description: this.config.description,
-      author: this.config.author,
-    }
-
-    if (this.config.repository) manifest.homepage = this.config.repository
-    if (this.config.repository) manifest.repository = this.config.repository
-    if (this.config.license) manifest.license = this.config.license
-    if (this.config.keywords) manifest.keywords = this.config.keywords
-
-    manifest.skills = './skills/'
-    if (this.config.mcp) manifest.mcpServers = './.mcp.json'
-
-    // Codex supports rich interface metadata
-    if (this.config.brand) {
-      const iface: Record<string, unknown> = {
-        displayName: this.config.brand.displayName,
-        shortDescription: this.config.brand.shortDescription ?? this.config.description,
-        category: this.config.brand.category,
-      }
-
-      if (this.config.brand.longDescription) {
-        iface.longDescription = this.config.brand.longDescription
-      }
-      if (this.config.brand.color) {
-        iface.brandColor = this.config.brand.color
-      }
-      if (this.config.brand.icon) {
-        iface.composerIcon = this.config.brand.icon
-        iface.logo = this.config.brand.icon
-      }
-      if (this.config.brand.defaultPrompts) {
-        iface.defaultPrompt = this.config.brand.defaultPrompts
-      }
-      if (this.config.brand.websiteURL) {
-        iface.websiteURL = this.config.brand.websiteURL
-      }
-      if (this.config.brand.screenshots) {
-        iface.screenshots = this.config.brand.screenshots
-      }
-
-      // Merge Codex-specific interface overrides
-      const codexOverrides = this.config.platforms?.codex?.interface
-      if (codexOverrides) {
-        Object.assign(iface, codexOverrides)
-      }
-
-      iface.developerName = this.config.author.name
-
-      manifest.interface = iface
-    }
-
-    await this.writeJson('.codex-plugin/plugin.json', manifest)
-  }
-  private async generateAgentsMd(): Promise<void> {
-    if (!this.config.instructions) return
-    const srcPath = this.resolveConfigPath(this.config.instructions, 'instructions')
-    if (!existsSync(srcPath)) return
-
-    const content = await Bun.file(srcPath).text()
-    await this.writeFile('AGENTS.md', content)
-  }
-}