@orchid-labs/pluxx 0.1.0

package/src/compatibility/matrix.ts

@@ -0,0 +1,149 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,63 @@
+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

@@ -0,0 +1,188 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,35 @@
+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

@@ -0,0 +1,120 @@
+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)
+  }
+}