@1tool/js-boost 1.0.0

package/src/generators/agents.js

@@ -0,0 +1,64 @@
+import { buildMcpMarkdownSection } from '../utils/mcp.js';
+
+/**
+ * Generate AGENTS.md — the universal standard read by Codex, Cursor,
+ * GitHub Copilot, Gemini CLI, and most other agents.
+ *
+ * This is the single source of truth. All other agent files reference this.
+ */
+export function generateAgentsMd(guidelines, skills, mcpServers, config = {}) {
+  const projectName = config.projectName || 'this project';
+  const projectDescription = config.projectDescription || '';
+  const sections = [];
+
+  // Header
+  sections.push(`# AGENTS.md`);
+  sections.push(`> Agent instructions for ${projectName}. Generated by [js-boost](https://github.com/your-org/js-boost) — do not edit manually.`);
+  if (projectDescription) sections.push(`\n${projectDescription}`);
+  sections.push('');
+
+  // Table of contents hint
+  sections.push('---');
+  sections.push('');
+
+  // Guidelines — inline all content from .ai/guidelines/
+  if (guidelines.length > 0) {
+    sections.push('## Guidelines');
+    sections.push('');
+    sections.push('These guidelines define conventions, patterns, and best practices for this project.');
+    sections.push('');
+
+    for (const g of guidelines) {
+      // Include the full content of each guideline file
+      sections.push(g.content);
+      sections.push('');
+    }
+  }
+
+  // Skills — reference section with name + description
+  if (skills.length > 0) {
+    sections.push('## Agent Skills');
+    sections.push('');
+    sections.push('The following skills are available in `.ai/skills/`. Load a skill when the task matches its description.');
+    sections.push('');
+
+    for (const skill of skills) {
+      sections.push(`### ${skill.name}`);
+      if (skill.description) sections.push(`${skill.description}`);
+      sections.push(`- **Skill file:** \`.ai/skills/${skill.dir}/SKILL.md\``);
+      sections.push('');
+    }
+  }
+
+  // MCP section
+  if (Object.keys(mcpServers).length > 0) {
+    sections.push(buildMcpMarkdownSection(mcpServers));
+  }
+
+  // Footer
+  sections.push('---');
+  sections.push('');
+  sections.push('*This file is auto-generated by `js-boost`. Run `npx js-boost generate` to regenerate.*');
+
+  return sections.join('\n');
+}

package/src/generators/claude.js

@@ -0,0 +1,60 @@
+import { buildMcpMarkdownSection } from '../utils/mcp.js';
+
+/**
+ * Generate CLAUDE.md for Claude Code.
+ *
+ * Claude Code reads CLAUDE.md from the project root. We include the full
+ * guidelines content here (Claude benefits from having everything upfront),
+ * plus Claude-specific directives for loading skills.
+ */
+export function generateClaudeMd(guidelines, skills, mcpServers, config = {}) {
+  const projectName = config.projectName || 'this project';
+  const sections = [];
+
+  sections.push(`# CLAUDE.md — ${projectName}`);
+  sections.push('');
+  sections.push('> Generated by [js-boost](https://github.com/your-org/js-boost). Do not edit manually — edit `.ai/guidelines/` and `.ai/skills/` instead, then run `npx js-boost generate`.');
+  sections.push('');
+  sections.push('---');
+  sections.push('');
+
+  // Claude Code: Skills loading instruction
+  if (skills.length > 0) {
+    sections.push('## Skills');
+    sections.push('');
+    sections.push('When starting work on a task, check if any of the following skills apply and load the relevant `SKILL.md` file before proceeding:');
+    sections.push('');
+    for (const skill of skills) {
+      sections.push(`- **${skill.name}** — ${skill.description || 'see SKILL.md'}`);
+      sections.push(`  - Load: \`.ai/skills/${skill.dir}/SKILL.md\``);
+    }
+    sections.push('');
+    sections.push('---');
+    sections.push('');
+  }
+
+  // Include all guidelines inline
+  if (guidelines.length > 0) {
+    sections.push('## Project Guidelines');
+    sections.push('');
+    for (const g of guidelines) {
+      sections.push(g.content);
+      sections.push('');
+    }
+    sections.push('---');
+    sections.push('');
+  }
+
+  // MCP section
+  if (Object.keys(mcpServers).length > 0) {
+    sections.push(buildMcpMarkdownSection(mcpServers));
+    sections.push('');
+    sections.push('> MCP servers are configured in `.mcp.json`. Claude Code will pick them up automatically.');
+    sections.push('');
+  }
+
+  sections.push('---');
+  sections.push('*Auto-generated by `js-boost`. Source: `.ai/`*');
+
+  return sections.join('\n');
+}

package/src/generators/cursor.js

@@ -0,0 +1,69 @@
+/**
+ * Generate .cursor/rules/js-boost.mdc for Cursor.
+ *
+ * Cursor reads .cursorrules (legacy) or .cursor/rules/*.mdc (v0.43+).
+ * We generate the modern .cursor/rules/ format.
+ * Each guideline becomes its own rule file for better organization.
+ */
+export function generateCursorRules(guidelines, skills, config = {}) {
+  const sections = [];
+
+  sections.push('---');
+  sections.push('description: Project guidelines and conventions');
+  sections.push('globs: ["**/*"]');
+  sections.push('alwaysApply: true');
+  sections.push('---');
+  sections.push('');
+
+  // Inline all guidelines
+  if (guidelines.length > 0) {
+    for (const g of guidelines) {
+      sections.push(g.content);
+      sections.push('');
+    }
+  }
+
+  // Skills reference
+  if (skills.length > 0) {
+    sections.push('## Available Skills');
+    sections.push('');
+    for (const skill of skills) {
+      sections.push(`- **${skill.name}**: \`.ai/skills/${skill.dir}/SKILL.md\``);
+      if (skill.description) sections.push(`  ${skill.description}`);
+    }
+    sections.push('');
+  }
+
+  sections.push('---');
+  sections.push('*Auto-generated by `js-boost`*');
+
+  return sections.join('\n');
+}
+
+/**
+ * Also generate legacy .cursorrules for older Cursor versions
+ */
+export function generateCursorRulesLegacy(guidelines, skills, config = {}) {
+  const sections = [];
+
+  sections.push('# Cursor Rules');
+  sections.push('# Generated by js-boost — edit .ai/guidelines/ instead');
+  sections.push('');
+
+  if (guidelines.length > 0) {
+    for (const g of guidelines) {
+      // Strip markdown headings for legacy format compatibility
+      sections.push(g.content);
+      sections.push('');
+    }
+  }
+
+  if (skills.length > 0) {
+    sections.push('## Skills');
+    for (const skill of skills) {
+      sections.push(`- ${skill.name}: .ai/skills/${skill.dir}/SKILL.md`);
+    }
+  }
+
+  return sections.join('\n');
+}

package/src/generators/junie.js

@@ -0,0 +1,42 @@
+/**
+ * Generate .junie/guidelines.md for JetBrains Junie.
+ *
+ * Junie reads .junie/guidelines.md and uses it as persistent context
+ * for every task. Skills need to be referenced explicitly since Junie
+ * doesn't auto-load them from directories.
+ */
+export function generateJunieGuidelines(guidelines, skills, config = {}) {
+  const projectName = config.projectName || 'this project';
+  const sections = [];
+
+  sections.push(`# Junie Guidelines — ${projectName}`);
+  sections.push('');
+  sections.push('> Generated by [js-boost](https://github.com/your-org/js-boost). Do not edit manually.');
+  sections.push('');
+
+  // Inline all guidelines
+  if (guidelines.length > 0) {
+    for (const g of guidelines) {
+      sections.push(g.content);
+      sections.push('');
+    }
+  }
+
+  // Skills reference
+  if (skills.length > 0) {
+    sections.push('## Available Skills');
+    sections.push('');
+    sections.push('The following skill files contain detailed patterns. Read the relevant SKILL.md before working on tasks in that domain:');
+    sections.push('');
+    for (const skill of skills) {
+      sections.push(`- **${skill.name}**: \`.ai/skills/${skill.dir}/SKILL.md\``);
+      if (skill.description) sections.push(`  ${skill.description}`);
+    }
+    sections.push('');
+  }
+
+  sections.push('---');
+  sections.push('*Auto-generated by `js-boost`. Source: `.ai/`*');
+
+  return sections.join('\n');
+}

package/src/generators/kiro.js

@@ -0,0 +1,35 @@
+/**
+ * Generate .kiro/steering/guidelines.md
+ * Kiro uses steering documents in .kiro/steering/ for project context.
+ */
+export function generateKiroSteering(guidelines, skills, config) {
+  const projectName = config.projectName || 'This project';
+  const lines = [];
+
+  lines.push('---');
+  lines.push('inclusion: always');
+  lines.push('---');
+  lines.push('');
+  lines.push(`# ${projectName} — AI Guidelines`);
+  lines.push('');
+
+  if (guidelines.length > 0) {
+    for (const g of guidelines) {
+      lines.push(g.content);
+      lines.push('');
+    }
+  }
+
+  if (skills.length > 0) {
+    lines.push('## Skills');
+    lines.push('');
+    lines.push('The following skills are available for this project:');
+    lines.push('');
+    for (const skill of skills) {
+      lines.push(`- **${skill.name}**: ${skill.description || skill.dir}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/index.js

@@ -0,0 +1,125 @@
+import path from 'path';
+import chalk from 'chalk';
+import { readGuidelines, readSkills, readConfig, writeFile } from './utils/reader.js';
+import { buildMcpServers, generateMcpJson, generateJunieMcpJson } from './utils/mcp.js';
+import { AGENTS_MD_CONSUMERS, MCP_JSON_CONSUMERS } from './agents.js';
+import { generateAgentsMd } from './generators/agents.js';
+import { generateClaudeMd } from './generators/claude.js';
+import { generateJunieGuidelines } from './generators/junie.js';
+import { generateCursorRules, generateCursorRulesLegacy } from './generators/cursor.js';
+import { generateKiroSteering } from './generators/kiro.js';
+
+export async function generate(projectDir, options = {}) {
+  const aiDir = path.join(projectDir, '.ai');
+  const config = readConfig(projectDir);
+  const verbose = options.verbose ?? false;
+
+  // Determine active agents — fall back to all agents if none configured
+  const activeAgents = new Set(config.agents ?? Object.keys(
+    { amp: 1, claude_code: 1, codex: 1, copilot: 1, cursor: 1, gemini: 1, junie: 1, kiro: 1, opencode: 1 }
+  ));
+
+  const has = (key) => activeAgents.has(key);
+  const hasAny = (keys) => keys.some(k => activeAgents.has(k));
+
+  const log = (msg) => console.log(msg);
+  const info = (label, file) => log(`  ${chalk.green('✓')} ${chalk.dim(label.padEnd(30))} ${chalk.cyan(file)}`);
+  const skip = (label, reason) => verbose && log(`  ${chalk.yellow('–')} ${chalk.dim(label.padEnd(30))} ${chalk.yellow(reason)}`);
+
+  log('');
+  log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — generating agent files'));
+  log('');
+
+  // 1. Read source files
+  const guidelines = await readGuidelines(aiDir);
+  const skills = await readSkills(aiDir);
+  const mcpServers = buildMcpServers(config);
+
+  if (guidelines.length === 0 && skills.length === 0) {
+    log(chalk.yellow('  ⚠ No guidelines or skills found in .ai/'));
+    log(chalk.dim('    Create .ai/guidelines/*.md or .ai/skills/*/SKILL.md to get started'));
+    log('');
+  } else {
+    log(chalk.dim(`  Found ${guidelines.length} guideline(s), ${skills.length} skill(s), ${Object.keys(mcpServers).length} MCP server(s)`));
+    log(chalk.dim(`  Agents: ${[...activeAgents].join(', ')}`));
+    log('');
+  }
+
+  const generatedFiles = [];
+
+  // 2. AGENTS.md — shared format for Codex, Copilot, Gemini, Amp, OpenCode
+  if (hasAny(AGENTS_MD_CONSUMERS)) {
+    const agentsMd = generateAgentsMd(guidelines, skills, mcpServers, config);
+    writeFile(path.join(projectDir, 'AGENTS.md'), agentsMd);
+    info('AGENTS.md', 'AGENTS.md');
+    generatedFiles.push('AGENTS.md');
+  } else {
+    skip('AGENTS.md', 'no AGENTS.md consumers selected');
+  }
+
+  // 3. CLAUDE.md — Claude Code
+  if (has('claude_code')) {
+    const claudeMd = generateClaudeMd(guidelines, skills, mcpServers, config);
+    writeFile(path.join(projectDir, 'CLAUDE.md'), claudeMd);
+    info('Claude Code', 'CLAUDE.md');
+    generatedFiles.push('CLAUDE.md');
+  } else {
+    skip('Claude Code', 'not selected');
+  }
+
+  // 4. .mcp.json — Claude Code + Codex
+  if (hasAny(MCP_JSON_CONSUMERS)) {
+    const mcpJson = generateMcpJson(mcpServers);
+    writeFile(path.join(projectDir, '.mcp.json'), mcpJson);
+    info('MCP (Claude/Codex)', '.mcp.json');
+    generatedFiles.push('.mcp.json');
+  } else {
+    skip('MCP', 'no MCP consumers selected');
+  }
+
+  // 5. .junie/ — JetBrains Junie
+  if (has('junie')) {
+    const junieGuidelines = generateJunieGuidelines(guidelines, skills, config);
+    writeFile(path.join(projectDir, '.junie', 'guidelines.md'), junieGuidelines);
+    info('Junie guidelines', '.junie/guidelines.md');
+    generatedFiles.push('.junie/guidelines.md');
+
+    const junieMcpJson = generateJunieMcpJson(mcpServers);
+    writeFile(path.join(projectDir, '.junie', 'mcp.json'), junieMcpJson);
+    info('Junie MCP', '.junie/mcp.json');
+    generatedFiles.push('.junie/mcp.json');
+  } else {
+    skip('Junie', 'not selected');
+  }
+
+  // 6. Cursor — .cursor/rules/ + legacy .cursorrules
+  if (has('cursor')) {
+    const cursorRules = generateCursorRules(guidelines, skills, config);
+    writeFile(path.join(projectDir, '.cursor', 'rules', 'js-boost.mdc'), cursorRules);
+    info('Cursor (modern)', '.cursor/rules/js-boost.mdc');
+    generatedFiles.push('.cursor/rules/js-boost.mdc');
+
+    const cursorLegacy = generateCursorRulesLegacy(guidelines, skills, config);
+    writeFile(path.join(projectDir, '.cursorrules'), cursorLegacy);
+    info('Cursor (legacy)', '.cursorrules');
+    generatedFiles.push('.cursorrules');
+  } else {
+    skip('Cursor', 'not selected');
+  }
+
+  // 7. Kiro — .kiro/steering/guidelines.md
+  if (has('kiro')) {
+    const kiroSteering = generateKiroSteering(guidelines, skills, config);
+    writeFile(path.join(projectDir, '.kiro', 'steering', 'guidelines.md'), kiroSteering);
+    info('Kiro', '.kiro/steering/guidelines.md');
+    generatedFiles.push('.kiro/steering/guidelines.md');
+  } else {
+    skip('Kiro', 'not selected');
+  }
+
+  log('');
+  log(chalk.green.bold(`  ✓ Generated ${generatedFiles.length} files successfully`));
+  log('');
+
+  return generatedFiles;
+}

package/src/init.js

@@ -0,0 +1,134 @@
+import path from 'path';
+import fs from 'fs';
+import chalk from 'chalk';
+import { multiselect, isCancel, cancel } from '@clack/prompts';
+import { writeFile } from './utils/reader.js';
+import { AGENTS } from './agents.js';
+import { detectInstalledAgents } from './utils/detect.js';
+
+const EXAMPLE_GUIDELINES = {
+  'general.md': `# General Guidelines
+
+## Code Style
+- TODO: describe your preferred language, style, and formatting conventions
+
+## Project Conventions
+- TODO: describe your folder structure and naming conventions
+
+## Git
+- TODO: describe your branching and commit message conventions
+`,
+
+  'testing.md': `# Testing Guidelines
+
+## Conventions
+- TODO: describe your test framework and file naming conventions
+- TODO: describe what should and should not be mocked
+`,
+};
+
+const EXAMPLE_SKILL = {
+  'SKILL.md': `---
+name: example-skill
+description: TODO: describe when the agent should use this skill.
+---
+
+# Example Skill
+
+TODO: describe the steps, patterns, or conventions the agent should follow.
+`
+};
+
+export async function selectAgents(projectDir, currentAgents = null) {
+  const detected = detectInstalledAgents(projectDir);
+
+  const options = Object.values(AGENTS).map(agent => ({
+    value: agent.key,
+    label: agent.name,
+    hint: agent.hint,
+  }));
+
+  const defaults = currentAgents
+    ? currentAgents
+    : detected.length > 0
+      ? detected
+      : Object.keys(AGENTS);
+
+  console.log('');
+  const selected = await multiselect({
+    message: 'Which AI agents would you like to configure?',
+    options,
+    initialValues: defaults,
+    required: true,
+  });
+
+  if (isCancel(selected)) {
+    cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  return selected;
+}
+
+export async function init(projectDir, options = {}) {
+  const aiDir = path.join(projectDir, '.ai');
+  const force = options.force ?? false;
+
+  console.log('');
+  console.log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — initializing .ai/ folder'));
+  console.log('');
+
+  if (fs.existsSync(aiDir) && !force) {
+    console.log(chalk.yellow('  ⚠ .ai/ folder already exists. Use --force to overwrite.'));
+    console.log('');
+    return;
+  }
+
+  // Create .ai/guidelines/ with example files
+  for (const [filename, content] of Object.entries(EXAMPLE_GUIDELINES)) {
+    const filePath = path.join(aiDir, 'guidelines', filename);
+    if (!fs.existsSync(filePath) || force) {
+      writeFile(filePath, content);
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan(`.ai/guidelines/${filename}`)}`);
+    }
+  }
+
+  // Create .ai/skills/example-skill/ placeholder
+  for (const [filename, content] of Object.entries(EXAMPLE_SKILL)) {
+    const filePath = path.join(aiDir, 'skills', 'example-skill', filename);
+    if (!fs.existsSync(filePath) || force) {
+      writeFile(filePath, content);
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan(`.ai/skills/example-skill/${filename}`)}`);
+    }
+  }
+
+  // Create js-boost.config.json with defaults (or read existing)
+  const configPath = path.join(projectDir, 'js-boost.config.json');
+  let existingConfig = {};
+  if (fs.existsSync(configPath) && !force) {
+    try { existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  }
+
+  // Agent selection
+  const selectedAgents = await selectAgents(projectDir, existingConfig.agents);
+
+  const config = {
+    projectName: existingConfig.projectName || path.basename(projectDir),
+    projectDescription: existingConfig.projectDescription || '',
+    agents: selectedAgents,
+    mcpServers: existingConfig.mcpServers || {},
+    disableMcpServers: existingConfig.disableMcpServers || [],
+  };
+
+  writeFile(configPath, JSON.stringify(config, null, 2));
+  console.log(`  ${chalk.green('✓')} ${chalk.cyan('js-boost.config.json')}`);
+
+  console.log('');
+  console.log(chalk.green.bold('  ✓ .ai/ folder initialized'));
+  console.log('');
+  console.log(chalk.dim('  Next steps:'));
+  console.log(chalk.dim('  1. Edit .ai/guidelines/*.md with your project conventions'));
+  console.log(chalk.dim('  2. Add skills in .ai/skills/<name>/SKILL.md'));
+  console.log(chalk.dim('  3. Run: npx js-boost generate'));
+  console.log('');
+}

package/src/utils/detect.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function dirExists(...segments) {
+  return fs.existsSync(path.join(...segments));
+}
+
+/**
+ * Detect which agents are installed on the system or present in the project.
+ * Returns an array of agent keys.
+ */
+export function detectInstalledAgents(projectDir = process.cwd()) {
+  const home = os.homedir();
+  const detected = [];
+
+  if (dirExists(home, '.claude') || dirExists(home, '.config', 'claude')) {
+    detected.push('claude_code');
+  }
+
+  if (dirExists(home, '.cursor') || dirExists(projectDir, '.cursor')) {
+    detected.push('cursor');
+  }
+
+  if (dirExists(projectDir, '.junie') || dirExists(home, '.junie')) {
+    detected.push('junie');
+  }
+
+  if (commandExists('codex')) {
+    detected.push('codex');
+  }
+
+  if (commandExists('amp') || dirExists(home, '.amp')) {
+    detected.push('amp');
+  }
+
+  if (dirExists(home, '.kiro') || dirExists(projectDir, '.kiro')) {
+    detected.push('kiro');
+  }
+
+  if (commandExists('opencode') || dirExists(home, '.opencode')) {
+    detected.push('opencode');
+  }
+
+  // Copilot and Gemini are harder to detect — skip auto-detection
+
+  return detected;
+}

package/src/utils/mcp.js

@@ -0,0 +1,97 @@
+/**
+ * Default MCP servers pre-configured for js-boost
+ */
+export const DEFAULT_MCP_SERVERS = {
+};
+
+/**
+ * Build the MCP servers object, merging defaults with user-defined servers
+ * from js-boost.config.json
+ */
+export function buildMcpServers(config = {}) {
+  const userServers = config.mcpServers || {};
+  const disabledDefaults = config.disableMcpServers || [];
+
+  const servers = {};
+
+  // Add default servers (unless disabled)
+  for (const [key, server] of Object.entries(DEFAULT_MCP_SERVERS)) {
+    if (!disabledDefaults.includes(key)) {
+      servers[key] = server;
+    }
+  }
+
+  // Merge user-defined servers (can override defaults)
+  for (const [key, server] of Object.entries(userServers)) {
+    servers[key] = server;
+  }
+
+  return servers;
+}
+
+/**
+ * Generate .mcp.json (used by Claude Code and Codex)
+ * Supports both stdio and remote (HTTP/SSE) server types
+ */
+export function generateMcpJson(servers) {
+  const mcpServers = {};
+
+  for (const [key, server] of Object.entries(servers)) {
+    if (server.type === 'stdio') {
+      mcpServers[key] = {
+        command: server.command,
+        args: server.args || [],
+        ...(server.env ? { env: server.env } : {})
+      };
+    } else if (server.type === 'remote') {
+      // Claude Code uses mcp-remote wrapper for HTTP/SSE servers
+      mcpServers[key] = {
+        command: 'npx',
+        args: ['-y', 'mcp-remote', server.url]
+      };
+    }
+  }
+
+  return JSON.stringify({ mcpServers }, null, 2);
+}
+
+/**
+ * Generate .junie/mcp.json (Junie format — supports URL directly)
+ */
+export function generateJunieMcpJson(servers) {
+  const mcpServers = {};
+
+  for (const [key, server] of Object.entries(servers)) {
+    if (server.type === 'stdio') {
+      mcpServers[key] = {
+        command: server.command,
+        args: server.args || [],
+        ...(server.env ? { env: server.env } : {})
+      };
+    } else if (server.type === 'remote') {
+      mcpServers[key] = {
+        url: server.url
+      };
+    }
+  }
+
+  return JSON.stringify({ mcpServers }, null, 2);
+}
+
+/**
+ * Generate human-readable MCP section for markdown files
+ */
+export function buildMcpMarkdownSection(servers) {
+  const lines = ['## MCP Servers', ''];
+  lines.push('The following MCP servers are configured for this project:\n');
+
+  for (const [key, server] of Object.entries(servers)) {
+    lines.push(`### ${key}`);
+    if (server.description) lines.push(`> ${server.description}`);
+    if (server.type === 'remote') lines.push(`- **URL:** \`${server.url}\``);
+    if (server.type === 'stdio') lines.push(`- **Command:** \`${server.command} ${(server.args || []).join(' ')}\``);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}