@1tool/js-boost 1.0.0

package/README.md

@@ -0,0 +1,200 @@
+# ⚡ js-boost
+
+> Laravel Boost for JavaScript — generate agent files for Claude Code, Cursor, Junie, Codex, Copilot, Kiro, and more from a single `.ai/` source of truth.
+
+Instead of manually maintaining separate instruction files for each AI agent, you write your guidelines and skills once in `.ai/` and `js-boost` generates all the agent-specific files automatically.
+
+---
+
+## How it works
+
+```
+.ai/
+├── guidelines/
+│   ├── general.md       ← coding conventions
+│   └── testing.md       ← testing standards
+└── skills/
+    └── my-skill/
+        └── SKILL.md     ← on-demand skill (loaded when relevant)
+```
+
+Run `npx js-boost generate` and get the right file for each configured agent:
+
+| File | Agent |
+|---|---|
+| `AGENTS.md` | Amp, Codex, GitHub Copilot, Gemini, OpenCode |
+| `CLAUDE.md` | Claude Code |
+| `.mcp.json` | Claude Code + Codex |
+| `.junie/guidelines.md` + `.junie/mcp.json` | JetBrains Junie |
+| `.cursor/rules/js-boost.mdc` + `.cursorrules` | Cursor |
+| `.kiro/steering/guidelines.md` | Kiro |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Scaffold .ai/ and select your agents
+npx js-boost init
+
+# 2. Edit guidelines and skills in .ai/
+
+# 3. Generate agent files
+npx js-boost generate
+
+# 4. (Optional) Watch mode — auto-regenerate on save
+npx js-boost watch
+```
+
+---
+
+## Commands
+
+### `js-boost init`
+
+Scaffolds the `.ai/` folder with placeholder guidelines and a starter skill. Prompts you to select which AI agents to configure and saves the selection to `js-boost.config.json`.
+
+```bash
+npx js-boost init
+npx js-boost init --force    # overwrite existing files
+npx js-boost init --dir ./my-project
+```
+
+### `js-boost agents`
+
+Re-run the agent selection prompt without re-scaffolding `.ai/`. Use this to add or remove agents after the initial setup.
+
+```bash
+npx js-boost agents
+```
+
+### `js-boost mcp`
+
+Interactive wizard to add, remove, or toggle MCP servers. Changes are saved to `js-boost.config.json` — run `generate` afterwards to apply them to agent files.
+
+```bash
+npx js-boost mcp
+```
+
+**Add a remote server:**
+```
+✔ Server key: my-api
+✔ Server type: Remote (HTTP / SSE url)
+✔ URL: https://my-mcp.com/mcp
+✔ Description (optional): Internal API tools
+```
+
+**Add a local (stdio) server:**
+```
+✔ Server key: local-tools
+✔ Server type: Local (stdio process)
+✔ Command: node
+✔ Arguments: ./mcp-server.js --port 3000
+✔ Environment variables: API_KEY=secret,NODE_ENV=production
+```
+
+### `js-boost generate`
+
+Reads `.ai/guidelines/*.md` and `.ai/skills/*/SKILL.md`, then generates files for all selected agents. Falls back to generating all supported formats if no agents are configured.
+
+```bash
+npx js-boost generate
+npx js-boost gen             # alias
+npx js-boost generate --verbose
+```
+
+### `js-boost watch`
+
+Watches `.ai/` for changes and regenerates automatically (debounced 300ms).
+
+```bash
+npx js-boost watch
+```
+
+### `js-boost status`
+
+Shows configured agents, guidelines, skills, MCP servers, and which files will be generated.
+
+```bash
+npx js-boost status
+```
+
+---
+
+## Supported Agents
+
+| Key | Agent | Auto-detected |
+|---|---|---|
+| `amp` | Amp | `amp` in PATH or `~/.amp` |
+| `claude_code` | Claude Code | `~/.claude` |
+| `codex` | Codex | `codex` in PATH |
+| `copilot` | GitHub Copilot | — |
+| `cursor` | Cursor | `~/.cursor` |
+| `gemini` | Gemini | — |
+| `junie` | JetBrains Junie | `.junie/` in project |
+| `kiro` | Kiro | `~/.kiro` |
+| `opencode` | OpenCode | `opencode` in PATH |
+
+During `init` (and `agents`), installed agents are pre-selected automatically based on what's detected on your system.
+
+---
+
+## Configuration
+
+`js-boost.config.json` is managed by the CLI commands (`init`, `agents`, `mcp`) and committed to your repo.
+
+```json
+{
+  "projectName": "my-app",
+  "projectDescription": "",
+  "agents": ["claude_code", "cursor", "codex"],
+  "mcpServers": {
+    "my-api": {
+      "type": "remote",
+      "url": "https://my-mcp.com/mcp",
+      "description": "Internal API tools"
+    },
+    "local-tools": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./mcp-server.js"],
+      "env": { "API_KEY": "secret" }
+    }
+  },
+  "disableMcpServers": []
+}
+```
+
+MCP servers are written to the right format per agent:
+
+| Agent | Format | Remote servers |
+|---|---|---|
+| Claude Code, Codex | `.mcp.json` | wrapped in `mcp-remote` |
+| Junie | `.junie/mcp.json` | referenced by URL directly |
+
+---
+
+## Skills
+
+Skills in `.ai/skills/` use a `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: Use this skill when doing X.
+---
+
+# My Skill
+
+Steps, patterns, and examples...
+```
+
+- **Claude Code** loads skills on-demand based on the `description`
+- **Codex** supports `$skill-name` invocation and implicit matching
+- **Junie / Cursor / Kiro** receive a reference list pointing to each `SKILL.md`
+
+---
+
+## License
+
+MIT

package/bin/js-boost.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@1tool/js-boost",
+  "version": "1.0.0",
+  "description": "Laravel Boost-inspired CLI for JavaScript projects — generates agent files from your .ai/ folder",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "js-boost": "bin/js-boost.js"
+  },
+  "scripts": {
+    "start": "node bin/js-boost.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "ai",
+    "agents",
+    "mcp",
+    "claude",
+    "codex",
+    "junie",
+    "cursor",
+    "kiro"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.3.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0"
+  }
+}

package/src/agents.js

@@ -0,0 +1,62 @@
+export const AGENTS = {
+  amp: {
+    key: 'amp',
+    name: 'Amp',
+    hint: 'ampcode.com',
+    generates: ['AGENTS.md'],
+  },
+  claude_code: {
+    key: 'claude_code',
+    name: 'Claude Code',
+    hint: 'by Anthropic',
+    generates: ['CLAUDE.md', '.mcp.json'],
+  },
+  codex: {
+    key: 'codex',
+    name: 'Codex',
+    hint: 'by OpenAI',
+    generates: ['AGENTS.md', '.mcp.json'],
+  },
+  copilot: {
+    key: 'copilot',
+    name: 'GitHub Copilot',
+    hint: 'by GitHub',
+    generates: ['AGENTS.md'],
+  },
+  cursor: {
+    key: 'cursor',
+    name: 'Cursor',
+    hint: 'cursor.sh',
+    generates: ['.cursor/rules/js-boost.mdc', '.cursorrules'],
+  },
+  gemini: {
+    key: 'gemini',
+    name: 'Gemini',
+    hint: 'by Google',
+    generates: ['AGENTS.md'],
+  },
+  junie: {
+    key: 'junie',
+    name: 'Junie',
+    hint: 'by JetBrains',
+    generates: ['.junie/guidelines.md', '.junie/mcp.json'],
+  },
+  kiro: {
+    key: 'kiro',
+    name: 'Kiro',
+    hint: 'by Amazon',
+    generates: ['.kiro/steering/guidelines.md'],
+  },
+  opencode: {
+    key: 'opencode',
+    name: 'OpenCode',
+    hint: 'opencode.ai',
+    generates: ['AGENTS.md'],
+  },
+};
+
+/** Agents that consume the shared AGENTS.md format */
+export const AGENTS_MD_CONSUMERS = ['amp', 'codex', 'copilot', 'gemini', 'opencode'];
+
+/** Agents that consume .mcp.json */
+export const MCP_JSON_CONSUMERS = ['claude_code', 'codex'];

package/src/cli.js

@@ -0,0 +1,162 @@
+import { program } from 'commander';
+import path from 'path';
+import chalk from 'chalk';
+import { generate } from './index.js';
+import { init, selectAgents } from './init.js';
+import { watch } from './watch.js';
+
+program
+  .name('js-boost')
+  .description('Generate agent files (AGENTS.md, CLAUDE.md, .mcp.json, Junie, Cursor) from your .ai/ folder')
+  .version('1.0.0');
+
+// ─── js-boost init ───────────────────────────────────────────────────────────
+program
+  .command('init')
+  .description('Scaffold the .ai/ folder with example guidelines and skills')
+  .option('--force', 'Overwrite existing files')
+  .option('--dir <path>', 'Project directory', process.cwd())
+  .action(async (options) => {
+    const projectDir = path.resolve(options.dir);
+    await init(projectDir, { force: options.force });
+  });
+
+// ─── js-boost generate ───────────────────────────────────────────────────────
+program
+  .command('generate')
+  .alias('gen')
+  .description('Generate all agent files from .ai/guidelines/ and .ai/skills/')
+  .option('--dir <path>', 'Project directory', process.cwd())
+  .option('--verbose', 'Show skipped files')
+  .action(async (options) => {
+    const projectDir = path.resolve(options.dir);
+    try {
+      await generate(projectDir, { verbose: options.verbose });
+    } catch (err) {
+      console.error(chalk.red('Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── js-boost watch ──────────────────────────────────────────────────────────
+program
+  .command('watch')
+  .description('Watch .ai/ for changes and regenerate automatically')
+  .option('--dir <path>', 'Project directory', process.cwd())
+  .action((options) => {
+    const projectDir = path.resolve(options.dir);
+    watch(projectDir);
+  });
+
+// ─── js-boost agents ─────────────────────────────────────────────────────────
+program
+  .command('agents')
+  .description('Select which AI agents to configure (updates js-boost.config.json)')
+  .option('--dir <path>', 'Project directory', process.cwd())
+  .action(async (options) => {
+    const projectDir = path.resolve(options.dir);
+    const { readConfig, writeFile } = await import('./utils/reader.js');
+    const configPath = `${projectDir}/js-boost.config.json`;
+    const config = readConfig(projectDir);
+
+    const selected = await selectAgents(projectDir, config.agents ?? null);
+    config.agents = selected;
+
+    writeFile(configPath, JSON.stringify(config, null, 2));
+    console.log('');
+    console.log(chalk.green('  ✓ Agent configuration saved to js-boost.config.json'));
+    console.log('');
+    console.log(chalk.dim(`  Selected: ${selected.join(', ')}`));
+    console.log('');
+  });
+
+// ─── js-boost mcp ────────────────────────────────────────────────────────────
+program
+  .command('mcp')
+  .description('Configure MCP servers — add, remove, or toggle built-in defaults')
+  .option('--dir <path>', 'Project directory', process.cwd())
+  .action(async (options) => {
+    const projectDir = path.resolve(options.dir);
+    const { configureMcp } = await import('./configure/mcp.js');
+    await configureMcp(projectDir);
+  });
+
+// ─── js-boost status ─────────────────────────────────────────────────────────
+program
+  .command('status')
+  .description('Show what .ai/ contains and what would be generated')
+  .option('--dir <path>', 'Project directory', process.cwd())
+  .action(async (options) => {
+    const projectDir = path.resolve(options.dir);
+    const { readGuidelines, readSkills, readConfig } = await import('./utils/reader.js');
+    const { buildMcpServers } = await import('./utils/mcp.js');
+    const { AGENTS, AGENTS_MD_CONSUMERS, MCP_JSON_CONSUMERS } = await import('./agents.js');
+    const aiDir = path.join(projectDir, '.ai');
+    const config = readConfig(projectDir);
+
+    const guidelines = await readGuidelines(aiDir);
+    const skills = await readSkills(aiDir);
+    const mcpServers = buildMcpServers(config);
+
+    const allAgentKeys = Object.keys(AGENTS);
+    const activeAgents = new Set(config.agents ?? allAgentKeys);
+    const has = (key) => activeAgents.has(key);
+    const hasAny = (keys) => keys.some(k => activeAgents.has(k));
+
+    console.log('');
+    console.log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — status'));
+    console.log('');
+
+    // Agents
+    console.log(chalk.bold('  Agents') + chalk.dim(` (${activeAgents.size} of ${allAgentKeys.length} selected)`));
+    for (const [key, agent] of Object.entries(AGENTS)) {
+      const active = activeAgents.has(key);
+      const icon = active ? chalk.green('✓') : chalk.dim('–');
+      const label = active ? chalk.cyan(agent.name) : chalk.dim(agent.name);
+      const hint = chalk.dim(`(${agent.hint})`);
+      console.log(`    ${icon} ${label} ${hint}`);
+    }
+    if (config.agents == null) console.log(chalk.dim('    (all agents — run `js-boost agents` to configure)'));
+    console.log('');
+
+    console.log(chalk.bold('  Guidelines') + chalk.dim(` (${guidelines.length})`));
+    for (const g of guidelines) {
+      console.log(`    ${chalk.green('•')} ${chalk.cyan(g.filename)} — ${chalk.dim(g.title)}`);
+    }
+    if (guidelines.length === 0) console.log(chalk.dim('    none — add .ai/guidelines/*.md'));
+    console.log('');
+
+    console.log(chalk.bold('  Skills') + chalk.dim(` (${skills.length})`));
+    for (const s of skills) {
+      console.log(`    ${chalk.green('•')} ${chalk.cyan(s.name)} — ${chalk.dim(s.description || s.dir)}`);
+    }
+    if (skills.length === 0) console.log(chalk.dim('    none — add .ai/skills/<name>/SKILL.md'));
+    console.log('');
+
+    console.log(chalk.bold('  MCP Servers') + chalk.dim(` (${Object.keys(mcpServers).length})`));
+    for (const [key, srv] of Object.entries(mcpServers)) {
+      const url = srv.url || `${srv.command} ${(srv.args || []).join(' ')}`;
+      console.log(`    ${chalk.green('•')} ${chalk.cyan(key)} — ${chalk.dim(url)}`);
+    }
+    console.log('');
+
+    console.log(chalk.bold('  Will generate:'));
+    const willGenerate = [
+      hasAny(AGENTS_MD_CONSUMERS) && ['AGENTS.md', 'Amp, Codex, Copilot, Gemini, OpenCode'],
+      has('claude_code')          && ['CLAUDE.md', 'Claude Code'],
+      hasAny(MCP_JSON_CONSUMERS)  && ['.mcp.json', 'Claude Code + Codex MCP'],
+      has('junie')                && ['.junie/guidelines.md + .junie/mcp.json', 'JetBrains Junie'],
+      has('cursor')               && ['.cursor/rules/js-boost.mdc + .cursorrules', 'Cursor'],
+      has('kiro')                 && ['.kiro/steering/guidelines.md', 'Kiro'],
+    ].filter(Boolean);
+
+    for (const [file, label] of willGenerate) {
+      console.log(`    ${chalk.green('•')} ${chalk.cyan(file.padEnd(42))} ${chalk.dim(label)}`);
+    }
+    if (willGenerate.length === 0) {
+      console.log(chalk.dim('    none — run `js-boost agents` to select agents'));
+    }
+    console.log('');
+  });
+
+program.parse();

package/src/configure/mcp.js

@@ -0,0 +1,223 @@
+import path from 'path';
+import chalk from 'chalk';
+import { text, select, multiselect, isCancel } from '@clack/prompts';
+import { DEFAULT_MCP_SERVERS } from '../utils/mcp.js';
+import { readConfig, writeFile } from '../utils/reader.js';
+
+function displayServers(config) {
+  const userServers = config.mcpServers || {};
+  const disabled = new Set(config.disableMcpServers || []);
+  const builtinKeys = Object.keys(DEFAULT_MCP_SERVERS);
+
+  if (builtinKeys.length > 0) {
+    console.log(chalk.bold('  Built-in'));
+    for (const key of builtinKeys) {
+      const srv = DEFAULT_MCP_SERVERS[key];
+      const status = disabled.has(key) ? chalk.dim('disabled') : chalk.green('enabled');
+      console.log(`    ${chalk.cyan(key.padEnd(18))} ${chalk.dim(srv.url)}  [${status}]`);
+    }
+    console.log('');
+  }
+
+  console.log(chalk.bold('  Custom'));
+  const userEntries = Object.entries(userServers);
+  if (userEntries.length === 0) {
+    console.log(chalk.dim('    (none)'));
+  } else {
+    for (const [key, srv] of userEntries) {
+      const addr = srv.type === 'remote'
+        ? srv.url
+        : `${srv.command}${srv.args?.length ? ' ' + srv.args.join(' ') : ''}`;
+      console.log(`    ${chalk.cyan(key.padEnd(18))} ${chalk.dim(addr)}  ${chalk.dim(`(${srv.type})`)}`);
+    }
+  }
+  console.log('');
+}
+
+async function addServer(config) {
+  const name = await text({
+    message: 'Server key',
+    placeholder: 'my-api',
+    validate: (v) => {
+      if (!v.trim()) return 'Key is required';
+      if ((config.mcpServers || {})[v.trim()]) return `"${v.trim()}" already exists`;
+      if (DEFAULT_MCP_SERVERS[v.trim()]) return `"${v.trim()}" is a built-in — use "Toggle built-ins" to enable/disable it`;
+      if (!/^[a-z0-9_-]+$/.test(v.trim())) return 'Use only lowercase letters, numbers, hyphens, underscores';
+    },
+  });
+  if (isCancel(name)) return;
+
+  const type = await select({
+    message: 'Server type',
+    options: [
+      { value: 'remote', label: 'Remote', hint: 'HTTP / SSE url' },
+      { value: 'stdio',  label: 'Local',  hint: 'stdio process (node, python, etc.)' },
+    ],
+  });
+  if (isCancel(type)) return;
+
+  const key = name.trim();
+
+  if (type === 'remote') {
+    const url = await text({
+      message: 'URL',
+      placeholder: 'https://my-mcp.com/mcp',
+      validate: (v) => v.trim() ? undefined : 'URL is required',
+    });
+    if (isCancel(url)) return;
+
+    const description = await text({
+      message: 'Description (optional)',
+      placeholder: 'What does this server provide?',
+    });
+    if (isCancel(description)) return;
+
+    config.mcpServers[key] = {
+      type: 'remote',
+      url: url.trim(),
+      ...(description.trim() ? { description: description.trim() } : {}),
+    };
+  } else {
+    const command = await text({
+      message: 'Command',
+      placeholder: 'node',
+      validate: (v) => v.trim() ? undefined : 'Command is required',
+    });
+    if (isCancel(command)) return;
+
+    const argsRaw = await text({
+      message: 'Arguments (space-separated, optional)',
+      placeholder: './mcp-server.js --port 3000',
+    });
+    if (isCancel(argsRaw)) return;
+
+    const envRaw = await text({
+      message: 'Environment variables (KEY=VALUE, comma-separated, optional)',
+      placeholder: 'API_KEY=secret,NODE_ENV=production',
+    });
+    if (isCancel(envRaw)) return;
+
+    const args = argsRaw.trim() ? argsRaw.trim().split(/\s+/) : [];
+
+    const env = {};
+    if (envRaw.trim()) {
+      for (const pair of envRaw.trim().split(',')) {
+        const eq = pair.indexOf('=');
+        if (eq > 0) {
+          const k = pair.slice(0, eq).trim();
+          const v = pair.slice(eq + 1).trim();
+          if (k) env[k] = v;
+        }
+      }
+    }
+
+    config.mcpServers[key] = {
+      type: 'stdio',
+      command: command.trim(),
+      ...(args.length ? { args } : {}),
+      ...(Object.keys(env).length ? { env } : {}),
+    };
+  }
+
+  console.log(`  ${chalk.green('✓')} Added ${chalk.cyan(key)}`);
+}
+
+async function removeServer(config) {
+  const keys = Object.keys(config.mcpServers);
+  if (keys.length === 0) {
+    console.log(chalk.dim('  No custom servers to remove.'));
+    return;
+  }
+
+  const toRemove = await multiselect({
+    message: 'Select servers to remove',
+    options: keys.map((k) => {
+      const srv = config.mcpServers[k];
+      const addr = srv.type === 'remote'
+        ? srv.url
+        : `${srv.command}${srv.args?.length ? ' ' + srv.args.join(' ') : ''}`;
+      return { value: k, label: k, hint: addr };
+    }),
+    required: false,
+  });
+  if (isCancel(toRemove)) return;
+
+  for (const k of toRemove) {
+    delete config.mcpServers[k];
+  }
+
+  if (toRemove.length) {
+    console.log(`  ${chalk.green('✓')} Removed: ${toRemove.map(k => chalk.cyan(k)).join(', ')}`);
+  }
+}
+
+async function toggleDefaults(config) {
+  const keys = Object.keys(DEFAULT_MCP_SERVERS);
+  if (keys.length === 0) {
+    console.log(chalk.dim('  No built-in servers configured.'));
+    return;
+  }
+
+  const disabled = new Set(config.disableMcpServers || []);
+
+  const enabled = await multiselect({
+    message: 'Which built-in servers should be enabled?',
+    options: keys.map((k) => ({
+      value: k,
+      label: k,
+      hint: DEFAULT_MCP_SERVERS[k].url,
+    })),
+    initialValues: keys.filter((k) => !disabled.has(k)),
+    required: false,
+  });
+  if (isCancel(enabled)) return;
+
+  const enabledSet = new Set(enabled);
+  config.disableMcpServers = keys.filter((k) => !enabledSet.has(k));
+}
+
+export async function configureMcp(projectDir) {
+  const configPath = path.join(projectDir, 'js-boost.config.json');
+  const config = readConfig(projectDir);
+  config.mcpServers = config.mcpServers || {};
+  config.disableMcpServers = config.disableMcpServers || [];
+
+  console.log('');
+  console.log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — MCP server configuration'));
+  console.log('');
+
+  let running = true;
+
+  while (running) {
+    displayServers(config);
+
+    const hasCustom = Object.keys(config.mcpServers).length > 0;
+    const hasBuiltins = Object.keys(DEFAULT_MCP_SERVERS).length > 0;
+
+    const options = [
+      { value: 'add', label: 'Add a server' },
+      ...(hasCustom   ? [{ value: 'remove', label: 'Remove a server' }] : []),
+      ...(hasBuiltins ? [{ value: 'toggle', label: 'Disable / enable built-in servers' }] : []),
+      { value: 'done', label: 'Save and exit' },
+    ];
+
+    const action = await select({ message: 'What would you like to do?', options });
+
+    if (isCancel(action) || action === 'done') {
+      running = false;
+      break;
+    }
+
+    console.log('');
+    if (action === 'add')    await addServer(config);
+    if (action === 'remove') await removeServer(config);
+    if (action === 'toggle') await toggleDefaults(config);
+    console.log('');
+  }
+
+  writeFile(configPath, JSON.stringify(config, null, 2));
+  console.log('');
+  console.log(chalk.green('  ✓ Saved to js-boost.config.json'));
+  console.log(chalk.dim('  Run `js-boost generate` to apply changes to agent files.'));
+  console.log('');
+}