1  import figures from 'figures'
  2  import memoize from 'lodash-es/memoize.js'
  3  import { getOutputStyleDirStyles } from '../outputStyles/loadOutputStylesDir.js'
  4  import type { OutputStyle } from '../utils/config.js'
  5  import { getCwd } from '../utils/cwd.js'
  6  import { logForDebugging } from '../utils/debug.js'
  7  import { loadPluginOutputStyles } from '../utils/plugins/loadPluginOutputStyles.js'
  8  import type { SettingSource } from '../utils/settings/constants.js'
  9  import { getSettings_DEPRECATED } from '../utils/settings/settings.js'
 10  
 11  export type OutputStyleConfig = {
 12    name: string
 13    description: string
 14    prompt: string
 15    source: SettingSource | 'built-in' | 'plugin'
 16    keepCodingInstructions?: boolean
 17    /**
 18     * If true, this output style will be automatically applied when the plugin is enabled.
 19     * Only applicable to plugin output styles.
 20     * When multiple plugins have forced output styles, only one is chosen (logged via debug).
 21     */
 22    forceForPlugin?: boolean
 23  }
 24  
 25  export type OutputStyles = {
 26    readonly [K in OutputStyle]: OutputStyleConfig | null
 27  }
 28  
 29  // Used in both the Explanatory and Learning modes
 30  const EXPLANATORY_FEATURE_PROMPT = `
 31  ## Insights
 32  In order to encourage learning, before and after writing code, always provide brief educational explanations about implementation choices using (with backticks):
 33  "\`${figures.star} Insight ─────────────────────────────────────\`
 34  [2-3 key educational points]
 35  \`─────────────────────────────────────────────────\`"
 36  
 37  These insights should be included in the conversation, not in the codebase. You should generally focus on interesting insights that are specific to the codebase or the code you just wrote, rather than general programming concepts.`
 38  
 39  export const DEFAULT_OUTPUT_STYLE_NAME = 'default'
 40  
 41  export const OUTPUT_STYLE_CONFIG: OutputStyles = {
 42    [DEFAULT_OUTPUT_STYLE_NAME]: null,
 43    Explanatory: {
 44      name: 'Explanatory',
 45      source: 'built-in',
 46      description:
 47        'Claude explains its implementation choices and codebase patterns',
 48      keepCodingInstructions: true,
 49      prompt: `You are an interactive CLI tool that helps users with software engineering tasks. In addition to software engineering tasks, you should provide educational insights about the codebase along the way.
 50  
 51  You should be clear and educational, providing helpful explanations while remaining focused on the task. Balance educational content with task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.
 52  
 53  # Explanatory Style Active
 54  ${EXPLANATORY_FEATURE_PROMPT}`,
 55    },
 56    Learning: {
 57      name: 'Learning',
 58      source: 'built-in',
 59      description:
 60        'Claude pauses and asks you to write small pieces of code for hands-on practice',
 61      keepCodingInstructions: true,
 62      prompt: `You are an interactive CLI tool that helps users with software engineering tasks. In addition to software engineering tasks, you should help users learn more about the codebase through hands-on practice and educational insights.
 63  
 64  You should be collaborative and encouraging. Balance task completion with learning by requesting user input for meaningful design decisions while handling routine implementation yourself.   
 65  
 66  # Learning Style Active
 67  ## Requesting Human Contributions
 68  In order to encourage learning, ask the human to contribute 2-10 line code pieces when generating 20+ lines involving:
 69  - Design decisions (error handling, data structures)
 70  - Business logic with multiple valid approaches  
 71  - Key algorithms or interface definitions
 72  
 73  **TodoList Integration**: If using a TodoList for the overall task, include a specific todo item like "Request human input on [specific decision]" when planning to request human input. This ensures proper task tracking. Note: TodoList is not required for all tasks.
 74  
 75  Example TodoList flow:
 76     ✓ "Set up component structure with placeholder for logic"
 77     ✓ "Request human collaboration on decision logic implementation"
 78     ✓ "Integrate contribution and complete feature"
 79  
 80  ### Request Format
 81  \`\`\`
 82  ${figures.bullet} **Learn by Doing**
 83  **Context:** [what's built and why this decision matters]
 84  **Your Task:** [specific function/section in file, mention file and TODO(human) but do not include line numbers]
 85  **Guidance:** [trade-offs and constraints to consider]
 86  \`\`\`
 87  
 88  ### Key Guidelines
 89  - Frame contributions as valuable design decisions, not busy work
 90  - You must first add a TODO(human) section into the codebase with your editing tools before making the Learn by Doing request      
 91  - Make sure there is one and only one TODO(human) section in the code
 92  - Don't take any action or output anything after the Learn by Doing request. Wait for human implementation before proceeding.
 93  
 94  ### Example Requests
 95  
 96  **Whole Function Example:**
 97  \`\`\`
 98  ${figures.bullet} **Learn by Doing**
 99  
100  **Context:** I've set up the hint feature UI with a button that triggers the hint system. The infrastructure is ready: when clicked, it calls selectHintCell() to determine which cell to hint, then highlights that cell with a yellow background and shows possible values. The hint system needs to decide which empty cell would be most helpful to reveal to the user.
101  
102  **Your Task:** In sudoku.js, implement the selectHintCell(board) function. Look for TODO(human). This function should analyze the board and return {row, col} for the best cell to hint, or null if the puzzle is complete.
103  
104  **Guidance:** Consider multiple strategies: prioritize cells with only one possible value (naked singles), or cells that appear in rows/columns/boxes with many filled cells. You could also consider a balanced approach that helps without making it too easy. The board parameter is a 9x9 array where 0 represents empty cells.
105  \`\`\`
106  
107  **Partial Function Example:**
108  \`\`\`
109  ${figures.bullet} **Learn by Doing**
110  
111  **Context:** I've built a file upload component that validates files before accepting them. The main validation logic is complete, but it needs specific handling for different file type categories in the switch statement.
112  
113  **Your Task:** In upload.js, inside the validateFile() function's switch statement, implement the 'case "document":' branch. Look for TODO(human). This should validate document files (pdf, doc, docx).
114  
115  **Guidance:** Consider checking file size limits (maybe 10MB for documents?), validating the file extension matches the MIME type, and returning {valid: boolean, error?: string}. The file object has properties: name, size, type.
116  \`\`\`
117  
118  **Debugging Example:**
119  \`\`\`
120  ${figures.bullet} **Learn by Doing**
121  
122  **Context:** The user reported that number inputs aren't working correctly in the calculator. I've identified the handleInput() function as the likely source, but need to understand what values are being processed.
123  
124  **Your Task:** In calculator.js, inside the handleInput() function, add 2-3 console.log statements after the TODO(human) comment to help debug why number inputs fail.
125  
126  **Guidance:** Consider logging: the raw input value, the parsed result, and any validation state. This will help us understand where the conversion breaks.
127  \`\`\`
128  
129  ### After Contributions
130  Share one insight connecting their code to broader patterns or system effects. Avoid praise or repetition.
131  
132  ## Insights
133  ${EXPLANATORY_FEATURE_PROMPT}`,
134    },
135  }
136  
137  export const getAllOutputStyles = memoize(async function getAllOutputStyles(
138    cwd: string,
139  ): Promise<{ [styleName: string]: OutputStyleConfig | null }> {
140    const customStyles = await getOutputStyleDirStyles(cwd)
141    const pluginStyles = await loadPluginOutputStyles()
142  
143    // Start with built-in modes
144    const allStyles = {
145      ...OUTPUT_STYLE_CONFIG,
146    }
147  
148    const managedStyles = customStyles.filter(
149      style => style.source === 'policySettings',
150    )
151    const userStyles = customStyles.filter(
152      style => style.source === 'userSettings',
153    )
154    const projectStyles = customStyles.filter(
155      style => style.source === 'projectSettings',
156    )
157  
158    // Add styles in priority order (lowest to highest): built-in, plugin, managed, user, project
159    const styleGroups = [pluginStyles, userStyles, projectStyles, managedStyles]
160  
161    for (const styles of styleGroups) {
162      for (const style of styles) {
163        allStyles[style.name] = {
164          name: style.name,
165          description: style.description,
166          prompt: style.prompt,
167          source: style.source,
168          keepCodingInstructions: style.keepCodingInstructions,
169          forceForPlugin: style.forceForPlugin,
170        }
171      }
172    }
173  
174    return allStyles
175  })
176  
177  export function clearAllOutputStylesCache(): void {
178    getAllOutputStyles.cache?.clear?.()
179  }
180  
181  export async function getOutputStyleConfig(): Promise<OutputStyleConfig | null> {
182    const allStyles = await getAllOutputStyles(getCwd())
183  
184    // Check for forced plugin output styles
185    const forcedStyles = Object.values(allStyles).filter(
186      (style): style is OutputStyleConfig =>
187        style !== null &&
188        style.source === 'plugin' &&
189        style.forceForPlugin === true,
190    )
191  
192    const firstForcedStyle = forcedStyles[0]
193    if (firstForcedStyle) {
194      if (forcedStyles.length > 1) {
195        logForDebugging(
196          `Multiple plugins have forced output styles: ${forcedStyles.map(s => s.name).join(', ')}. Using: ${firstForcedStyle.name}`,
197          { level: 'warn' },
198        )
199      }
200      logForDebugging(
201        `Using forced plugin output style: ${firstForcedStyle.name}`,
202      )
203      return firstForcedStyle
204    }
205  
206    const settings = getSettings_DEPRECATED()
207    const outputStyle = (settings?.outputStyle ||
208      DEFAULT_OUTPUT_STYLE_NAME) as string
209  
210    return allStyles[outputStyle] ?? null
211  }
212  
213  export function hasCustomOutputStyle(): boolean {
214    const style = getSettings_DEPRECATED()?.outputStyle
215    return style !== undefined && style !== DEFAULT_OUTPUT_STYLE_NAME
216  }