agents-mdx 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,193 @@
+# AGENTS.mdx
+
+**One source of truth for all your AI coding agents.**
+
+Stop copy-pasting guidelines between `CLAUDE.md`, `AGENTS.md`, and other agent config files. Write your conventions once in composable [MDX](https://mdxjs.com/) components, and let `agents-mdx` generate the right files for Claude Code, Cursor, Copilot, Codex, and more.
+
+## Why agents-mdx?
+
+  - 🧩 **Composable** — Break down conventions into reusable [MDX](https://mdxjs.com/) components
+  - 🔄 **Multi-agent** — Generate config files for multiple AI agents from a single source
+  - 🔌 **MCP support** — Define MCP servers once, generate configs for all agents
+  - 👥 **Team-friendly** — Self-serve onboarding lets developers pick the conventions they need
+  - ⚡ **Live reload** — Watch mode rebuilds on every change
+
+## Install
+
+```bash
+npm install agents-mdx
+```
+
+## Quick Start
+
+### 1. Create your conventions
+
+Organize your team's guidelines as MDX files in a `conventions/` directory:
+
+```
+your-project/
+├── conventions/
+│   ├── code-style.mdx
+│   ├── testing.mdx
+│   ├── git-workflow.mdx
+│   ├── security.mdx
+│   └── react-patterns.mdx
+├── AGENTS.mdx          # ← generated by setup, configurable by each dev on your team
+├── CLAUDE.md           # ← symlink, auto-generated
+└── AGENTS.md           # ← symlink, auto-generated
+```
+
+Each convention file is a standard MDX file:
+
+```md
+# Code Style
+
+- Use TypeScript strict mode
+- Prefer `const` over `let`
+- Use early returns to reduce nesting
+```
+
+### 2. Run setup
+
+```bash
+npx agents-mdx setup
+```
+
+This interactive wizard will:
+
+- Ask which AI agents you use (Claude Code, Cursor, Copilot, etc.)
+- Let you pick which conventions to include
+- Generate an `AGENTS.mdx` file that imports your conventions
+- Create `CLAUDE.md` / `AGENTS.md` files
+- Add `AGENTS.mdx`, `CLAUDE.md` and `AGENTS.md` to your `.gitignore`
+
+### 3. Watch for changes
+
+```bash
+npx agents-mdx start
+```
+
+This watches your `AGENTS.mdx` and all imported conventions, regenerating the output files on every save.
+
+
+## CI
+
+For CI environments like [claude-code-action](https://github.com/anthropics/claude-code-action), use the non-interactive flags to generate files automatically:
+
+```bash
+npx agents-mdx setup --force --agents claude-code --all-conventions
+```
+
+**All options:**
+
+```bash
+npx agents-mdx setup [path]
+  --force              # Overwrite existing files without prompting
+  --agents             # Pre-select agents: claude-code, cursor, copilot, codex, open-code
+  --conventions        # Custom conventions directory (default: "conventions")
+  --all-conventions    # Include all conventions without prompting
+```
+
+## How It Works
+
+The `AGENTS.mdx` file is git-ignored, so each developer can customize which conventions they want active. Your team commits the shared `conventions/` folder, but individuals choose what to include.
+
+Your `AGENTS.mdx` file imports conventions as components:
+
+```mdx
+import { defineConfig } from '@agents-mdx/runtime/config';
+import CodeStyle from './conventions/code-style.mdx';
+import Testing from './conventions/testing.mdx';
+
+export const config = defineConfig({
+  agents: ['claude-code', 'codex', 'copilot'],
+});
+
+# Project Guidelines
+
+<CodeStyle config={config} />
+<Testing config={config} />
+```
+
+Running `start` compiles this into `CLAUDE.md` and `AGENTS.md` — symlinked files that your AI agents read automatically.
+
+## MCP Servers
+
+Define MCP servers in your convention files and let `agents-mdx` generate the right config format for each agent.
+
+Environment variables are automatically transformed to each agent's format (`${env:VAR}` for Cursor, `${VAR}` for Claude Code).
+
+**In your convention file (`conventions/mcp-tools.mdx`):**
+
+```mdx
+export const mcpServers = {
+  'supabase-local': {
+    url: 'http://localhost:54321/mcp'
+  },
+  'supabase-staging': {
+    url: 'https://mcp.supabase.com/mcp?project_ref=${env:SUPABASE_PROJECT_REF}',
+    headers: {
+      Authorization: 'Bearer ${env:SUPABASE_ACCESS_TOKEN}'
+    },
+  }
+};
+
+## Database tables
+
+- Always ensure new tables have a `created_at`, `updated_at` and `deleted_at` columns
+
+## Database operations
+
+- Always soft deleted entries
+```
+
+**During setup**, you'll be prompted to select which MCP servers to enable. The `start` command then generates the appropriate config files:
+
+  - **Cursor** → `.cursor/mcp.json`
+  - **Claude Code** → `.mcp.json`
+  - **VSCode** → `.vscode/mcp.json`
+
+## Conditional Instructions
+
+Include or exclude content based on the environment. Import `env` from the runtime:
+
+```mdx
+import { env } from '@agents-mdx/runtime/env';
+```
+
+**What's available:**
+
+  - `env.CI` — detect GitHub Actions, useful for [claude-code-action](https://github.com/anthropics/claude-code-action) reviews
+  - `env.hasExecutable('tool')` — check if a CLI tool is installed
+  - `env.isClaudeMd` / `env.isAgentsMd` — check which output file is being generated
+
+**Example: tool-specific instructions**
+
+Only include instructions for [`ck`](https://github.com/nicholasgriffintn/ck) when it's installed:
+
+```mdx
+import { env } from '@agents-mdx/runtime/env';
+
+{(() => {
+  if (!env.hasExecutable('ck')) {
+    throw 'ignore-file';
+  }
+})()}
+
+## Semantic Search
+
+Use `ck` to find related code even without exact keywords:
+
+\`\`\`bash
+ck --sem "retry logic"
+\`\`\`
+
+```
+
+## License
+
+MIT
+
+Copyright (c) 2026–present [StackBlitz][stackblitz]
+
+[stackblitz]: https://stackblitz.com/

package/dist/index.js

@@ -1 +1,6 @@
-console.log('TODO');
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const agentsMdxEntryPoint = require.resolve('@agents-mdx/cli');
+spawnSync('node', [agentsMdxEntryPoint, ...process.argv.slice(2)], { stdio: 'inherit' });

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "agents-mdx",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "author": "Nemikolh",
   "license": "MIT",
-  "bugs": "https://github.com/stackblitz/agents-mdx/issues",
-  "homepage": "https://github.com/stackblitz/agents-mdx",
+  "bugs": "https://github.com/stackblitz/agents.mdx/issues",
+  "homepage": "https://github.com/stackblitz/agents.mdx",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/stackblitz/agents-mdx.git",
-    "directory": "packages/agents-mdx-cli"
+    "url": "git+https://github.com/stackblitz/agents.mdx.git",
+    "directory": "packages/agents-mdx"
   },
   "bin": {
     "agents-mdx": "dist/index.js"
   },
   "files": [
     "dist"
-  ]
-}
+  ],
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@agents-mdx/cli": "0.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}