conflux-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Conflux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# Conflux
+
+**One config to rule them all.** Define your AI coding tool configuration once in `.ai/config.yaml` — sync to Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Aider, and more.
+
+[![npm version](https://img.shields.io/npm/v/conflux-ai)](https://www.npmjs.com/package/conflux-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## The Problem
+
+Using multiple AI coding tools means maintaining duplicate configuration files:
+
+```
+CLAUDE.md          ← Claude Code (project instructions)
+AGENTS.md          ← Codex CLI (same content, different name)
+.claude/settings.json  ← hooks + MCP + permissions (JSON)
+.codex/hooks.json      ← same hooks (different format)
+.codex/config.toml     ← same MCP servers (TOML)
+.cursorrules           ← same instructions again
+```
+
+Add a new MCP server or project rule, and you update 5+ files across 3+ formats.
+
+## The Solution
+
+Conflux lets you define everything **once** in `.ai/config.yaml` and syncs it to each tool in its native format:
+
+```bash
+conflux init     # Scan existing configs → .ai/config.yaml
+conflux sync     # Generate all tool-specific configs
+conflux status   # Check for drift (manual edits)
+```
+
+```yaml
+# .ai/config.yaml
+version: 1
+
+instructions:
+  primary: AGENTS.md
+
+mcp:
+  servers:
+    filesystem:
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+
+hooks:
+  SessionStart:
+    - command: "python hooks/session-start.py"
+      timeout: 15
+
+providers:
+  enabled: [claude-code, codex, cursor]
+```
+
+One `conflux sync` generates:
+- `CLAUDE.md` → wrapper pointing to `@AGENTS.md`
+- `AGENTS.md` → primary instruction file
+- `.claude/settings.json` → merged hooks + MCP + permissions
+- `.codex/hooks.json` → Codex hook format
+- `.cursor/mcp.json` → Cursor MCP format
+
+## Quick Start
+
+```bash
+# Install
+npm install -g conflux-ai
+
+# Initialize in your project
+cd your-project
+conflux init
+
+# Review and customize .ai/config.yaml
+# Then sync
+conflux sync
+
+# See what's supported
+conflux providers
+```
+
+## Features
+
+### 5 Configuration Dimensions
+
+| Dimension | Description | Example Outputs |
+|-----------|------------|----------------|
+| 📋 **Instructions** | Project rules & context | `CLAUDE.md`, `AGENTS.md`, `.cursorrules` |
+| 🪝 **Hooks** | Lifecycle events | `.claude/settings.json`, `.codex/hooks.json` |
+| 🔌 **MCP Servers** | Model Context Protocol | `.claude/settings.json`, `.cursor/mcp.json` |
+| 🔒 **Permissions** | Allow/deny rules | `.claude/settings.json`, `.codex/config.toml` |
+| ⚡ **Skills** | Reusable commands | `.claude/skills/`, `.cursor/skills/` |
+
+### Supported Tools (MVP)
+
+| Tool | Instructions | Hooks | MCP | Permissions | Skills |
+|------|:-----------:|:-----:|:---:|:-----------:|:------:|
+| **Claude Code** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Codex CLI** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Cursor** | ✅ | ❌ | ✅ | ⚠️ | ✅ |
+
+More tools coming in v1.0: Windsurf, GitHub Copilot, Gemini CLI, Aider.
+
+### Key Capabilities
+
+- **Auto-detect** — finds which AI tools you use
+- **Drift detection** — warns when generated files are manually edited
+- **Capability-aware** — gracefully skips unsupported features per tool
+- **Provider overrides** — tool-specific customizations when needed
+- **JSON Schema** — IDE autocompletion for `.ai/config.yaml`
+- **Dry-run mode** — preview changes before writing
+
+## CLI Commands
+
+```
+conflux init         # Create .ai/config.yaml from existing configs
+conflux sync         # Sync config to all detected tools
+conflux status       # Check for drift (coming in v1.0)
+conflux providers    # List supported tools
+conflux doctor       # Validate and diagnose (coming in v1.0)
+conflux clean        # Remove generated configs (coming in v1.0)
+```
+
+### Global Options
+
+```
+-d, --dry-run        Preview changes without writing
+-v, --verbose        Verbose output
+-p, --project <path> Project root (default: cwd)
+--json               Machine-readable output
+-y, --yes            Skip confirmation prompts
+```
+
+## Programmatic Usage
+
+```typescript
+import { loadConfig, registry } from "conflux-ai";
+
+const config = loadConfig("/path/to/project");
+const provider = registry.get("claude-code");
+const result = await provider?.sync("/path/to/project", config);
+
+console.log(result?.filesWritten.map(f => f.path));
+// ["CLAUDE.md", ".claude/settings.json"]
+```
+
+## Roadmap
+
+### v0.1 (MVP) — Current
+- [x] 3 providers: Claude Code, Codex CLI, Cursor
+- [x] 2 dimensions: Instructions + MCP
+- [x] `init` + `sync` + `providers` commands
+- [x] JSON Schema for IDE autocompletion
+
+### v1.0 — Next
+- [ ] All 5 dimensions (hooks + permissions + skills)
+- [ ] 7 providers (+ Windsurf, Copilot, Gemini CLI, Aider)
+- [ ] `status` (drift detection) + `doctor` + `clean`
+- [ ] Monorepo support
+
+### v2.0 — Future
+- [ ] 15+ providers
+- [ ] File watching (auto-sync on save)
+- [ ] Community plugin SDK (`@conflux/provider-sdk`)
+- [ ] VS Code extension
+- [ ] GitHub Actions CI integration
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) (coming soon).
+
+### Adding a Provider
+
+Create a new provider by extending `AIProvider`:
+
+```typescript
+import { AIProvider, ProviderCapability } from "conflux-ai";
+
+export class MyProvider extends AIProvider {
+  id = "my-tool";
+  name = "My Tool";
+  version = "1.0.0";
+  capabilities = [ProviderCapability.INSTRUCTIONS, ProviderCapability.MCP];
+
+  detect(projectPath: string): boolean {
+    // Check for marker files
+  }
+
+  generateInstructions(config): GeneratedFile[] {
+    // Generate tool-specific instruction files
+  }
+
+  // ...implement other methods
+}
+```
+
+## Related Projects
+
+- [std-agent](https://github.com/StringKe/std-ai) — Go-based config sync for 22 tools
+- [AgentBrew](https://www.npmjs.com/package/agentbrew) — TypeScript skill manager for 45+ agents
+- [AGENTS.md Standard](https://github.com/agentmd/agent.md) — Emerging standard for agent instructions
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node