the claude code sourcemaps leaked march 31
1import { join } from 'path'
2import { getClaudeConfigHomeDir } from '../../utils/envUtils.js'
3import { getFsImplementation } from '../../utils/fsOperations.js'
4
5/**
6 * Get the Magic Docs update prompt template
7 */
8function getUpdatePromptTemplate(): string {
9 return `IMPORTANT: This message and these instructions are NOT part of the actual user conversation. Do NOT include any references to "documentation updates", "magic docs", or these update instructions in the document content.
10
11Based on the user conversation above (EXCLUDING this documentation update instruction message), update the Magic Doc file to incorporate any NEW learnings, insights, or information that would be valuable to preserve.
12
13The file {{docPath}} has already been read for you. Here are its current contents:
14<current_doc_content>
15{{docContents}}
16</current_doc_content>
17
18Document title: {{docTitle}}
19{{customInstructions}}
20
21Your ONLY task is to use the Edit tool to update the documentation file if there is substantial new information to add, then stop. You can make multiple edits (update multiple sections as needed) - make all Edit tool calls in parallel in a single message. If there's nothing substantial to add, simply respond with a brief explanation and do not call any tools.
22
23CRITICAL RULES FOR EDITING:
24- Preserve the Magic Doc header exactly as-is: # MAGIC DOC: {{docTitle}}
25- If there's an italicized line immediately after the header, preserve it exactly as-is
26- Keep the document CURRENT with the latest state of the codebase - this is NOT a changelog or history
27- Update information IN-PLACE to reflect the current state - do NOT append historical notes or track changes over time
28- Remove or replace outdated information rather than adding "Previously..." or "Updated to..." notes
29- Clean up or DELETE sections that are no longer relevant or don't align with the document's purpose
30- Fix obvious errors: typos, grammar mistakes, broken formatting, incorrect information, or confusing statements
31- Keep the document well organized: use clear headings, logical section order, consistent formatting, and proper nesting
32
33DOCUMENTATION PHILOSOPHY - READ CAREFULLY:
34- BE TERSE. High signal only. No filler words or unnecessary elaboration.
35- Documentation is for OVERVIEWS, ARCHITECTURE, and ENTRY POINTS - not detailed code walkthroughs
36- Do NOT duplicate information that's already obvious from reading the source code
37- Do NOT document every function, parameter, or line number reference
38- Focus on: WHY things exist, HOW components connect, WHERE to start reading, WHAT patterns are used
39- Skip: detailed implementation steps, exhaustive API docs, play-by-play narratives
40
41What TO document:
42- High-level architecture and system design
43- Non-obvious patterns, conventions, or gotchas
44- Key entry points and where to start reading code
45- Important design decisions and their rationale
46- Critical dependencies or integration points
47- References to related files, docs, or code (like a wiki) - help readers navigate to relevant context
48
49What NOT to document:
50- Anything obvious from reading the code itself
51- Exhaustive lists of files, functions, or parameters
52- Step-by-step implementation details
53- Low-level code mechanics
54- Information already in CLAUDE.md or other project docs
55
56Use the Edit tool with file_path: {{docPath}}
57
58REMEMBER: Only update if there is substantial new information. The Magic Doc header (# MAGIC DOC: {{docTitle}}) must remain unchanged.`
59}
60
61/**
62 * Load custom Magic Docs prompt from file if it exists
63 * Custom prompts can be placed at ~/.claude/magic-docs/prompt.md
64 * Use {{variableName}} syntax for variable substitution (e.g., {{docContents}}, {{docPath}}, {{docTitle}})
65 */
66async function loadMagicDocsPrompt(): Promise<string> {
67 const fs = getFsImplementation()
68 const promptPath = join(getClaudeConfigHomeDir(), 'magic-docs', 'prompt.md')
69
70 try {
71 return await fs.readFile(promptPath, { encoding: 'utf-8' })
72 } catch {
73 // Silently fall back to default if custom prompt doesn't exist or fails to load
74 return getUpdatePromptTemplate()
75 }
76}
77
78/**
79 * Substitute variables in the prompt template using {{variable}} syntax
80 */
81function substituteVariables(
82 template: string,
83 variables: Record<string, string>,
84): string {
85 // Single-pass replacement avoids two bugs: (1) $ backreference corruption
86 // (replacer fn treats $ literally), and (2) double-substitution when user
87 // content happens to contain {{varName}} matching a later variable.
88 return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) =>
89 Object.prototype.hasOwnProperty.call(variables, key)
90 ? variables[key]!
91 : match,
92 )
93}
94
95/**
96 * Build the Magic Docs update prompt with variable substitution
97 */
98export async function buildMagicDocsUpdatePrompt(
99 docContents: string,
100 docPath: string,
101 docTitle: string,
102 instructions?: string,
103): Promise<string> {
104 const promptTemplate = await loadMagicDocsPrompt()
105
106 // Build custom instructions section if provided
107 const customInstructions = instructions
108 ? `
109
110DOCUMENT-SPECIFIC UPDATE INSTRUCTIONS:
111The document author has provided specific instructions for how this file should be updated. Pay extra attention to these instructions and follow them carefully:
112
113"${instructions}"
114
115These instructions take priority over the general rules below. Make sure your updates align with these specific guidelines.`
116 : ''
117
118 // Substitute variables in the prompt
119 const variables = {
120 docContents,
121 docPath,
122 docTitle,
123 customInstructions,
124 }
125
126 return substituteVariables(promptTemplate, variables)
127}