@plaited/development-skills 0.5.0 → 0.6.1

package/src/scaffold-rules.ts

@@ -2,40 +2,42 @@
 /**
  * Scaffold development rules from templates
  *
- * Reads bundled rule templates, processes template variables and conditionals,
+ * Reads bundled rule templates, processes template variables,
  * and outputs JSON for agent consumption.
  *
- * Supports 2 target formats:
- * - claude: Claude Code with .claude/rules/ directory
- * - agents-md: Universal AGENTS.md format with .plaited/rules/
- *   (works with Cursor, Factory, Copilot, Windsurf, Cline, Aider, and 60,000+ others)
+ * All agents use `.plaited/rules/` as the unified default location.
+ * AGENTS.md serves as the single source of truth for rules content,
+ * while CLAUDE.md simply references it via @AGENTS.md syntax.
  *
  * Options:
- * - --agent, -a: Target format (claude | agents-md)
- * - --rules-dir, -d: Custom rules directory path (overrides default)
- * - --agents-md-path, -m: Custom AGENTS.md file path (default: AGENTS.md)
+ * - --rules-dir, -d: Custom rules directory path (overrides default .plaited/rules)
  * - --rules, -r: Filter to specific rules (can be used multiple times)
+ * - --list, -l: List available rules without full output
+ *
+ * Output includes:
+ * - agentsMdSection: Marker-wrapped section with markdown links for AGENTS.md
+ * - claudeMdReference: Short reference snippet pointing to @AGENTS.md
+ * - templates: Processed rule content for each selected rule
  *
  * Template syntax:
  * - {{LINK:rule-id}} - Cross-reference to another rule
- * - {{#if development-skills}}...{{/if}} - Conditional block
- * - {{#if capability}}...{{/if}} - Capability-based conditional
- * - {{^if condition}}...{{/if}} - Inverse conditional
+ * - {{#if development-skills}}...{{/if}} - Conditional block (always true when using CLI)
+ * - {{^if development-skills}}...{{/if}} - Inverse conditional
  * - <!-- RULE TEMPLATE ... --> - Template header (removed)
  *
- * Capabilities:
- * - has-sandbox: Agent runs in sandboxed environment (Claude Code only)
- * - supports-slash-commands: Agent has /command syntax (Claude Code only)
- *
  * @example
  * ```bash
- * # Default paths
- * bunx @plaited/development-skills scaffold-rules --agent=claude
- * bunx @plaited/development-skills scaffold-rules --agent=agents-md
+ * # Default: outputs to .plaited/rules/
+ * bunx @plaited/development-skills scaffold-rules
+ *
+ * # Custom rules directory
+ * bunx @plaited/development-skills scaffold-rules --rules-dir=.cursor/rules
  *
- * # Custom paths
- * bunx @plaited/development-skills scaffold-rules --agent=agents-md --rules-dir=.cursor/rules
- * bunx @plaited/development-skills scaffold-rules --agent=agents-md --agents-md-path=docs/AGENTS.md
+ * # Filter specific rules
+ * bunx @plaited/development-skills scaffold-rules --rules testing --rules bun-apis
+ *
+ * # List available rules
+ * bunx @plaited/development-skills scaffold-rules --list
  * ```
  */
 
@@ -44,144 +46,101 @@ import { join } from 'node:path'
 import { parseArgs } from 'node:util'
 
 /**
- * Supported agent targets
+ * Marker delimiters for programmatic file updates
  *
  * @remarks
- * - claude: Claude Code with its own .claude/ directory structure
- * - agents-md: Universal AGENTS.md format (works with Cursor, Factory, Copilot,
- *   Windsurf, Cline, Aider, and 60,000+ other projects)
+ * These markers allow scaffold-rules to update CLAUDE.md and AGENTS.md
+ * without destroying user content outside the marked section.
+ *
+ * Use these markers to implement idempotent updates:
+ * 1. Find existing markers in file content
+ * 2. Replace content between markers (inclusive) with new section
+ * 3. If no markers exist, append section to end of file
+ *
+ * @property start - Opening marker to place before rules section
+ * @property end - Closing marker to place after rules section
+ *
+ * @public
  */
-type Agent = 'claude' | 'agents-md'
+export const MARKERS = {
+  start: '<!-- PLAITED-RULES-START -->',
+  end: '<!-- PLAITED-RULES-END -->',
+} as const
 
-type AgentCapabilities = {
-  hasSandbox: boolean
-  multiFileRules: boolean
-  supportsSlashCommands: boolean
-  supportsAgentsMd: boolean
-}
+/**
+ * Unified rules directory path
+ *
+ * @remarks
+ * All agents use `.plaited/rules/` as the default location.
+ * This provides consistency and allows both CLAUDE.md and AGENTS.md
+ * to reference the same rule files.
+ */
+const UNIFIED_RULES_PATH = '.plaited/rules' as const
 
 type TemplateContext = {
-  agent: Agent
-  capabilities: AgentCapabilities
-  hasDevelopmentSkills: boolean
   rulesPath: string
 }
 
-type ProcessedTemplate = {
+/**
+ * Processed template with filename, content, and description
+ */
+export type ProcessedTemplate = {
   filename: string
   content: string
   description: string
 }
 
-type ScaffoldOutput = {
-  agent: Agent
-  rulesPath: string
-  agentsMdPath: string
-  format: 'multi-file' | 'agents-md'
-  supportsAgentsMd: boolean
-  agentsMdContent?: string
-  templates: Record<string, ProcessedTemplate>
-}
-
-/**
- * Agent capabilities matrix
- *
- * @remarks
- * - hasSandbox: Runs in restricted environment (affects git commands, temp files)
- * - multiFileRules: Supports directory of rule files vs single file
- * - supportsSlashCommands: Has /command syntax for invoking tools
- * - supportsAgentsMd: Reads AGENTS.md format
- *
- * Note: We only support 2 targets now:
- * - claude: Claude Code with unique .claude/ directory system
- * - agents-md: Universal format for all AGENTS.md-compatible agents
- *   (Cursor, Factory, Copilot, Windsurf, Cline, Aider, and 60,000+ others)
- */
-const AGENT_CAPABILITIES: Record<Agent, AgentCapabilities> = {
-  claude: {
-    hasSandbox: true,
-    multiFileRules: true,
-    supportsSlashCommands: true,
-    supportsAgentsMd: false,
-  },
-  'agents-md': {
-    hasSandbox: false,
-    multiFileRules: true,
-    supportsSlashCommands: false,
-    supportsAgentsMd: true,
-  },
-}
-
 /**
- * Evaluate a single condition against context
+ * Output from scaffold-rules CLI
  */
-const evaluateCondition = (condition: string, context: TemplateContext): boolean => {
-  // Check development-skills
-  if (condition === 'development-skills') {
-    return context.hasDevelopmentSkills
-  }
-
-  // Check capability-based conditions
-  if (condition === 'has-sandbox') {
-    return context.capabilities.hasSandbox
-  }
-  if (condition === 'multi-file-rules') {
-    return context.capabilities.multiFileRules
-  }
-  if (condition === 'supports-slash-commands') {
-    return context.capabilities.supportsSlashCommands
-  }
-  if (condition === 'supports-agents-md') {
-    return context.capabilities.supportsAgentsMd
-  }
-
-  // Check agent-specific conditions (legacy: agent:name)
-  const agentMatch = condition.match(/^agent:(\w+)$/)
-  if (agentMatch) {
-    return context.agent === agentMatch[1]
-  }
-
-  return false
+export type ScaffoldOutput = {
+  rulesPath: string
+  /** Marker-wrapped section with markdown links for AGENTS.md */
+  agentsMdSection: string
+  /** Short reference snippet for CLAUDE.md pointing to AGENTS.md */
+  claudeMdReference: string
+  templates: Record<string, ProcessedTemplate>
 }
 
 /**
  * Process template conditionals
  *
  * Handles:
- * - {{#if development-skills}}...{{/if}}
- * - {{#if capability}}...{{/if}} (has-sandbox, multi-file-rules, etc.)
- * - {{#if agent:name}}...{{/if}} (legacy, still supported)
- * - {{^if condition}}...{{/if}} (inverse)
+ * - {{#if development-skills}}...{{/if}} - Always true (using our CLI means dev-skills is installed)
+ * - {{^if development-skills}}...{{/if}} - Always false
  *
  * Processes iteratively to handle nested conditionals correctly.
  */
-const processConditionals = (content: string, context: TemplateContext): string => {
+const processConditionals = (content: string): string => {
   let result = content
   let previousResult = ''
+  const maxIterations = 100
+  let iterations = 0
 
   // Process iteratively until no more changes (handles nested conditionals)
-  while (result !== previousResult) {
+  while (result !== previousResult && iterations < maxIterations) {
     previousResult = result
+    iterations++
 
-    // Process positive conditionals {{#if condition}}...{{/if}}
-    // Use non-greedy match that doesn't cross other conditional boundaries
-    // Note: Nested quantifiers are safe here - input is trusted bundled templates, not user content
+    // Process positive conditionals {{#if development-skills}}...{{/if}}
+    // Always true - include the block content
     result = result.replace(
-      /\{\{#if ([\w:-]+)\}\}((?:(?!\{\{#if )(?!\{\{\^if )(?!\{\{\/if\}\})[\s\S])*?)\{\{\/if\}\}/g,
-      (_, condition, block) => {
-        return evaluateCondition(condition, context) ? block : ''
-      },
+      /\{\{#if development-skills\}\}((?:(?!\{\{#if )(?!\{\{\^if )(?!\{\{\/if\}\})[\s\S])*?)\{\{\/if\}\}/g,
+      (_, block) => block,
     )
 
-    // Process inverse conditionals {{^if condition}}...{{/if}}
+    // Process inverse conditionals {{^if development-skills}}...{{/if}}
+    // Always false - remove the block content
     result = result.replace(
-      /\{\{\^if ([\w:-]+)\}\}((?:(?!\{\{#if )(?!\{\{\^if )(?!\{\{\/if\}\})[\s\S])*?)\{\{\/if\}\}/g,
-      (_, condition, block) => {
-        return evaluateCondition(condition, context) ? '' : block
-      },
+      /\{\{\^if development-skills\}\}((?:(?!\{\{#if )(?!\{\{\^if )(?!\{\{\/if\}\})[\s\S])*?)\{\{\/if\}\}/g,
+      () => '',
     )
   }
 
+  if (iterations >= maxIterations) {
+    console.warn('Warning: Max iterations reached in template processing. Some conditionals may be unprocessed.')
+  }
+
   return result
 }
 
@@ -189,39 +148,23 @@ const processConditionals = (content: string, context: TemplateContext): string
  * Process template variables
  *
  * Handles:
- * - {{LINK:rule-id}} - Generate cross-reference
- * - {{AGENT_NAME}} - Agent name
+ * - {{LINK:rule-id}} - Generate cross-reference path
  * - {{RULES_PATH}} - Rules path
  */
 const processVariables = (content: string, context: TemplateContext): string => {
   let result = content
 
-  // Replace {{LINK:rule-id}} with appropriate cross-reference
+  // Replace {{LINK:rule-id}} with path reference
   result = result.replace(/\{\{LINK:(\w+)\}\}/g, (_, ruleId) => {
-    return generateCrossReference(ruleId, context)
+    return `${context.rulesPath}/${ruleId}.md`
   })
 
-  // Replace {{AGENT_NAME}}
-  result = result.replace(/\{\{AGENT_NAME\}\}/g, context.agent)
-
   // Replace {{RULES_PATH}}
   result = result.replace(/\{\{RULES_PATH\}\}/g, context.rulesPath)
 
   return result
 }
 
-/**
- * Generate cross-reference based on agent format
- */
-const generateCrossReference = (ruleId: string, context: TemplateContext): string => {
-  if (context.agent === 'claude') {
-    // Claude Code uses @ syntax for file references
-    return `@${context.rulesPath}/${ruleId}.md`
-  }
-  // Use context.rulesPath for cross-references (supports custom --rules-dir)
-  return `${context.rulesPath}/${ruleId}.md`
-}
-
 /**
  * Remove template headers
  */
@@ -238,7 +181,8 @@ const extractDescription = (content: string): string => {
   let description = ''
 
   for (let i = 1; i < lines.length; i++) {
-    const line = lines[i]?.trim()
+    // Non-null assertion safe: loop condition guarantees i < lines.length
+    const line = lines[i]!.trim()
     if (line && !line.startsWith('#') && !line.startsWith('**')) {
       description = line
       break
@@ -258,7 +202,7 @@ const processTemplate = (content: string, context: TemplateContext): string => {
   result = removeTemplateHeaders(result)
 
   // 2. Process conditionals
-  result = processConditionals(result, context)
+  result = processConditionals(result)
 
   // 3. Process variables
   result = processVariables(result, context)
@@ -270,27 +214,39 @@ const processTemplate = (content: string, context: TemplateContext): string => {
 }
 
 /**
- * Get rules path for agent
+ * Generate marker-wrapped reference snippet for CLAUDE.md
+ *
+ * @remarks
+ * Claude Code uses `@file.md` syntax to include file contents.
+ * This generates a short reference pointing to AGENTS.md as the single source of truth.
+ * The markers allow this section to be updated without affecting other content.
  */
-const getRulesPath = (agent: Agent): string => {
-  return agent === 'claude' ? '.claude/rules' : '.plaited/rules'
-}
+const generateClaudeMdReference = (): string => {
+  const lines = [
+    MARKERS.start,
+    '',
+    '## Project Rules',
+    '',
+    'See @AGENTS.md for shared development rules.',
+    '',
+    MARKERS.end,
+  ]
 
-/**
- * Get output format for agent
- */
-const getOutputFormat = (agent: Agent): 'multi-file' | 'agents-md' => {
-  return agent === 'claude' ? 'multi-file' : 'agents-md'
+  return lines.join('\n')
 }
 
 /**
- * Generate AGENTS.md content that links to rules directory
+ * Generate marker-wrapped section for AGENTS.md with dual format
+ *
+ * @remarks
+ * AGENTS.md uses both formats for maximum compatibility:
+ * - `@path` syntax for Claude Code to load file contents
+ * - `[name](path)` markdown links for other tools and GitHub rendering
+ * The markers allow this section to be updated without affecting other content.
  */
-const generateAgentsMd = (templates: Record<string, ProcessedTemplate>, rulesPath: string): string => {
+const generateAgentsMdSection = (templates: Record<string, ProcessedTemplate>, rulesPath: string): string => {
   const lines = [
-    '# AGENTS.md',
-    '',
-    'Development rules for AI coding agents.',
+    MARKERS.start,
     '',
     '## Rules',
     '',
@@ -300,14 +256,12 @@ const generateAgentsMd = (templates: Record<string, ProcessedTemplate>, rulesPat
   ]
 
   for (const [ruleId, template] of Object.entries(templates)) {
-    lines.push(`- [${ruleId}](${rulesPath}/${template.filename}) - ${template.description}`)
+    // Dual format: @ syntax for Claude Code, markdown link for other tools
+    lines.push(`- @${rulesPath}/${template.filename} - [${ruleId}](${rulesPath}/${template.filename})`)
   }
 
   lines.push('')
-  lines.push('## Quick Reference')
-  lines.push('')
-  lines.push('For detailed guidance on each topic, see the linked rule files above.')
-  lines.push('')
+  lines.push(MARKERS.end)
 
   return lines.join('\n')
 }
@@ -319,16 +273,6 @@ export const scaffoldRules = async (args: string[]): Promise<void> => {
   const { values } = parseArgs({
     args,
     options: {
-      agent: {
-        type: 'string',
-        short: 'a',
-        default: 'claude',
-      },
-      format: {
-        type: 'string',
-        short: 'f',
-        default: 'json',
-      },
       rules: {
         type: 'string',
         short: 'r',
@@ -338,54 +282,55 @@ export const scaffoldRules = async (args: string[]): Promise<void> => {
         type: 'string',
         short: 'd',
       },
-      'agents-md-path': {
-        type: 'string',
-        short: 'm',
+      list: {
+        type: 'boolean',
+        short: 'l',
       },
     },
     allowPositionals: true,
     strict: false,
   })
 
-  const agent = values.agent as Agent
   const rulesFilter = values.rules as string[] | undefined
   const customRulesDir = values['rules-dir'] as string | undefined
-  const customAgentsMdPath = values['agents-md-path'] as string | undefined
-
-  // Validate agent
-  const validAgents: Agent[] = ['claude', 'agents-md']
-  if (!validAgents.includes(agent)) {
-    console.error(`Error: Invalid agent "${agent}". Must be one of: ${validAgents.join(', ')}`)
-    console.error(
-      'Note: Use "agents-md" for Cursor, Factory, Copilot, Windsurf, Cline, Aider, and other AGENTS.md-compatible tools.',
-    )
-    process.exit(1)
-  }
+  const listOnly = values.list as boolean | undefined
 
   // Get bundled templates directory
-  const packageRulesDir = join(import.meta.dir, '../.claude/rules')
+  const packageRulesDir = join(import.meta.dir, '../.plaited/rules')
 
   // Read template files
   const templateFiles = await readdir(packageRulesDir)
 
   // Filter to .md files
   const mdFiles = templateFiles.filter((f) => f.endsWith('.md'))
+  const availableRuleIds = mdFiles.map((f) => f.replace('.md', ''))
+
+  // Validate requested rules exist
+  if (rulesFilter) {
+    const invalidRules = rulesFilter.filter((r) => !availableRuleIds.includes(r))
+    if (invalidRules.length > 0) {
+      console.error(`Warning: Unknown rules: ${invalidRules.join(', ')}`)
+      console.error(`Available rules: ${availableRuleIds.join(', ')}`)
+    }
+  }
+
+  // Handle --list flag: output available rules and exit
+  if (listOnly) {
+    const listOutput = availableRuleIds.map((id) => ({ id, filename: `${id}.md` }))
+    console.log(JSON.stringify(listOutput, null, 2))
+    return
+  }
 
   // Filter if specific rules requested
   const rulesToProcess = rulesFilter ? mdFiles.filter((f) => rulesFilter.includes(f.replace('.md', ''))) : mdFiles
 
   // Process each template
   const templates: Record<string, ProcessedTemplate> = {}
-  const capabilities = AGENT_CAPABILITIES[agent]
 
-  // Use custom paths or defaults
-  const rulesPath = customRulesDir ?? getRulesPath(agent)
-  const agentsMdPath = customAgentsMdPath ?? 'AGENTS.md'
+  // Use custom path or unified default
+  const rulesPath = customRulesDir ?? UNIFIED_RULES_PATH
 
   const context: TemplateContext = {
-    agent,
-    capabilities,
-    hasDevelopmentSkills: true, // Always true when using our CLI
     rulesPath,
   }
 
@@ -405,27 +350,23 @@ export const scaffoldRules = async (args: string[]): Promise<void> => {
         description: extractDescription(processed),
       }
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      console.error(`Error processing template ${file}: ${message}`)
+      console.error(`Error processing template ${file}:`, error)
       process.exit(1)
     }
   }
 
+  // Generate marker-wrapped section for AGENTS.md and reference for CLAUDE.md
+  const agentsMdSection = generateAgentsMdSection(templates, rulesPath)
+  const claudeMdReference = generateClaudeMdReference()
+
   // Build output
   const output: ScaffoldOutput = {
-    agent,
     rulesPath,
-    agentsMdPath,
-    format: getOutputFormat(agent),
-    supportsAgentsMd: capabilities.supportsAgentsMd,
+    agentsMdSection,
+    claudeMdReference,
     templates,
   }
 
-  // Generate AGENTS.md content for agents-md format
-  if (agent === 'agents-md') {
-    output.agentsMdContent = generateAgentsMd(templates, rulesPath)
-  }
-
   console.log(JSON.stringify(output, null, 2))
 }