veodl 1.9.0 → 1.10.0

package/src/config-editor.js

@@ -4,7 +4,8 @@ import { PassThrough } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
 import { parseConfigText } from './config.js';
 import { semanticIssue, editorCompletions } from './config-diagnostics.js';
-import { configClipboard } from './config-clipboard.js';
+import { configClipboard } from './config-clipboard.js';
+import { addConfigGuide, configGuideState, removeConfigGuide } from './config-template.js';
 
 const safe = text => text.replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
 
@@ -21,7 +22,7 @@ export async function validateEditorText(text) {
 }
 
 // A small text buffer shared by the keyboard handler and focused editing tests.
-export class EditorBuffer {
+export class EditorBuffer {
   constructor(text) { this.text = text; this.cursor = 0; this.anchor = null; }
   get selection() {
     return this.anchor === null ? [this.cursor, this.cursor] : [Math.min(this.anchor, this.cursor), Math.max(this.anchor, this.cursor)];
@@ -70,7 +71,33 @@ export class EditorBuffer {
     if (name === 'return') this.insert('\n');
     if (name === 'tab') this.insert('  ');
   }
-}
+}
+
+class EditorHistory {
+  constructor(buffer) { this.buffer = buffer; this.undoStack = []; this.redoStack = []; this.group = null; }
+  snapshot() { return { text: this.buffer.text, cursor: this.buffer.cursor, anchor: this.buffer.anchor }; }
+  breakGroup() { this.group = null; }
+  record(before, kind, groupable = false) {
+    if (before.text === this.buffer.text) return;
+    const now = Date.now();
+    if (!groupable || this.group?.kind !== kind || now - this.group.at > 600) {
+      this.undoStack.push(before);
+      if (this.undoStack.length > 100) this.undoStack.shift();
+    }
+    this.redoStack.length = 0;
+    this.group = groupable ? { kind, at: now } : null;
+  }
+  change(direction) {
+    const from = direction === 'undo' ? this.undoStack : this.redoStack;
+    if (!from.length) return false;
+    const to = direction === 'undo' ? this.redoStack : this.undoStack;
+    to.push(this.snapshot());
+    const state = from.pop();
+    Object.assign(this.buffer, state);
+    this.breakGroup();
+    return true;
+  }
+}
 
 export function colorLine(line, enabled = true) {
   const clean = safe(line);
@@ -83,20 +110,27 @@ export async function editConfig(file, { input = process.stdin, output = process
   if (!input.isTTY || !output.isTTY || !input.setRawMode) throw new Error('The config editor requires an interactive terminal. Set EDITOR to use an external editor.');
   const original = await readFile(file, 'utf8');
   const newline = original.includes('\r\n') ? '\r\n' : '\n';
-  const buffer = new EditorBuffer(original.replace(/\r\n/g, '\n'));
+  const buffer = new EditorBuffer(original.replace(/\r\n/g, '\n'));
+  const history = new EditorHistory(buffer);
   let saved = buffer.text, disk = original, issue = await validateEditorText(buffer.text);
-  let top = 0, left = 0, followCursor = true, question = false, busy = false, closed = false, timer;
-  let status = '', revision = 0;
+  let top = 0, left = 0, followCursor = true, question = false, guidePrompt = false, busy = false, closed = false, timer;
+  const guideState = configGuideState(buffer.text);
+  let status = guideState === 'outdated' ? 'Updated config guide available. Press F3 to choose.' :
+    guideState === 'current' ? 'Generated guide in file. Press F3 to remove it if duplicated.' : '', revision = 0;
   let viewport, dragging = false, completion = null;
   const wasRaw = input.isRaw, wasPaused = input.isPaused();
   const render = () => {
     if (closed) return;
     const width = Math.max(1, (output.columns || 80) - 1);
-    const diagnosis = issue ? `${issue.line ? `Line ${issue.line}, column ${issue.column}: ` : ''}${issue.message}` : '';
-    const detail = safe(completion ? `Options (${completion.index + 1}/${completion.choices.length}): ${JSON.stringify(completion.choices[completion.index])} | Up/Down choose, Enter apply, Esc cancel` :
-      status ? `${status}${diagnosis ? ` | ${diagnosis}` : ''}` : diagnosis || 'Config OK');
-    const detailRows = Math.min(3, Math.max(1, Math.ceil(detail.length / width)));
-    const height = Math.max(1, (output.rows || 24) - 2 - detailRows);
+    const diagnosis = issue ? `${issue.line ? `Line ${issue.line}, column ${issue.column}: ` : ''}${issue.message}` : '';
+    const detail = safe(completion ? `Options (${completion.index + 1}/${completion.choices.length}): ${JSON.stringify(completion.choices[completion.index])} | Up/Down choose, Enter apply, Esc cancel` :
+      status ? `${status}${diagnosis ? ` | ${diagnosis}` : ''}` : diagnosis || 'Config OK');
+    const detailRows = Math.min(3, Math.max(1, Math.ceil(detail.length / width)));
+    const helpLines = question ? ['Discard unsaved changes? Y = discard, N / Esc = keep editing'] :
+      guidePrompt ? ['Guide: A add/update | R remove | Esc cancel'] :
+        ['F3 Guide | F2 Options | Ctrl+S Save | Ctrl+Z Undo | Ctrl+Y Redo',
+          'Ctrl+A All | Ctrl+C Copy | Ctrl+V Paste | Esc / Ctrl+Q Exit'];
+    const height = Math.max(1, (output.rows || 24) - 1 - helpLines.length - detailRows);
     const lines = buffer.text.split('\n'), { row, col } = buffer.position;
     const gutter = Math.min(width - 1, String(lines.length).length + 2), available = Math.max(1, width - gutter);
     if (followCursor) {
@@ -121,22 +155,54 @@ export async function editConfig(file, { input = process.stdin, output = process
         screen.push(to > from ? prefix + colorLine(content.slice(0, from), color) + '\x1b[41;97m' + safe(content.slice(from, to)) + '\x1b[0m' + colorLine(content.slice(to), color) : prefix + colorLine(content, color));
       } else screen.push(index + 1 === issue?.line && color ? `\x1b[41;97m${prefix}${safe(content)}\x1b[0m` : prefix + colorLine(content, color));
       offset += (line || '').length + 1;
-    }
-    const position = `Ln ${row + 1}, Col ${col + 1}`;
-    const help = safe(question ? 'Discard unsaved changes? Y = discard, N / Esc = keep editing' : 'Ctrl+S Save | Ctrl+C Copy | Ctrl+V Paste | Esc Exit | F2 Options | Wheel Scroll');
-    const helpWidth = Math.max(0, width - position.length - 1);
-    screen.push((help.slice(0, helpWidth) + ' '.repeat(Math.max(1, width - position.length - Math.min(help.length, helpWidth))) + position).slice(0, width));
-    for (let index = 0; index < detailRows; index++) screen.push(detail.slice(index * width, (index + 1) * width));
+    }
+    const position = `Ln ${row + 1}, Col ${col + 1}`;
+    for (let index = 0; index < helpLines.length; index++) {
+      const last = index === helpLines.length - 1;
+      const helpWidth = Math.max(0, width - (last ? position.length + 1 : 0));
+      const visibleHelp = safe(helpLines[index]).slice(0, helpWidth);
+      const footer = last ? visibleHelp + ' '.repeat(Math.max(1, width - position.length - visibleHelp.length)) + position : visibleHelp;
+      screen.push(color ? footer.replace(/Ctrl\+[A-Z]|F[23]|Esc|\b[A,R]\b/g, match => `\x1b[1;36m${match}\x1b[0m`) : footer);
+    }
+    for (let index = 0; index < detailRows; index++) {
+      const line = detail.slice(index * width, (index + 1) * width);
+      const tone = completion ? 33 : issue ? 31 : status ? 32 : 90;
+      screen.push(color && line ? `\x1b[${tone}m${line}\x1b[0m` : line);
+    }
     const cursorVisible = row >= top && row < top + height;
     output.write('\x1b[?25l\x1b[H' + screen.map(line => line + '\x1b[K').join('\r\n') +
       (cursorVisible ? `\x1b[${row - top + 2};${gutter + col - left + 1}H\x1b[?25h` : ''));
   };
   await new Promise((resolve, reject) => {
-    const keyboard = new PassThrough();
-    const decoder = new StringDecoder('utf8');
-    let pending = '', mouseTimer;
-    const mouse = (button, x, y, release) => {
-      if (busy || closed || question) return;
+    const keyboard = new PassThrough();
+    const decoder = new StringDecoder('utf8');
+    let pending = '', mouseTimer;
+    let dragTimer, dragDirection = 0, dragX = 1;
+    const stopDragScroll = () => { clearInterval(dragTimer); dragTimer = undefined; dragDirection = 0; };
+    const stopDrag = () => { dragging = false; stopDragScroll(); };
+    const extendAt = (x, y) => {
+      const screenRow = Math.max(0, Math.min(viewport.height - 1, y - 2));
+      buffer.point(top + screenRow, left + x - viewport.gutter - 1, true);
+    };
+    const scrollDrag = () => {
+      if (!dragging || !dragDirection || closed) return stopDragScroll();
+      const lastTop = top;
+      top = Math.max(0, Math.min(top + dragDirection, Math.max(0, buffer.text.split('\n').length - viewport.height)));
+      if (top === lastTop) return stopDragScroll();
+      followCursor = false;
+      extendAt(dragX, dragDirection < 0 ? 2 : viewport.height + 1);
+      render();
+    };
+    const updateDragScroll = (x, y) => {
+      dragX = x;
+      const direction = y <= 2 ? -1 : y >= viewport.height + 1 ? 1 : 0;
+      if (direction === dragDirection) return;
+      stopDragScroll();
+      dragDirection = direction;
+      if (direction) dragTimer = setInterval(scrollDrag, 90);
+    };
+    const mouse = (button, x, y, release) => {
+      if (busy || closed || question) return;
       if (button & 64) {
         if (!release) {
           followCursor = false;
@@ -144,20 +210,25 @@ export async function editConfig(file, { input = process.stdin, output = process
           render();
         }
         return;
-      }
-      completion = null;
-      if ((button & 3) !== 0) return;
-      const inside = y >= 2 && y <= viewport.height + 1 && x >= 1 && x <= viewport.width;
-      if (!inside && !dragging) return;
-      if (!(button & 32) && !release) {
-        followCursor = true;
-        buffer.point(top + y - 2, left + x - viewport.gutter - 1);
-        buffer.anchor = buffer.cursor; dragging = true;
-      } else if (dragging) {
-        buffer.point(top + Math.max(0, Math.min(viewport.height - 1, y - 2)), left + x - viewport.gutter - 1, true);
-      }
-      if (release) dragging = false;
-      render();
+      }
+      completion = null;
+      if (release) {
+        if (dragging) extendAt(x, y);
+        stopDrag(); render(); return;
+      }
+      if ((button & 3) !== 0) return;
+      const inside = y >= 2 && y <= viewport.height + 1 && x >= 1 && x <= viewport.width;
+      if (!inside && !dragging) return;
+      if (!(button & 32)) {
+        stopDrag(); history.breakGroup();
+        followCursor = true;
+        buffer.point(top + y - 2, left + x - viewport.gutter - 1);
+        buffer.anchor = buffer.cursor; dragging = true;
+      } else if (dragging) {
+        extendAt(x, y);
+        updateDragScroll(x, y);
+      }
+      render();
     };
     // Filter SGR mouse reports before readline so their digits never enter the file.
     const onData = chunk => {
@@ -179,7 +250,7 @@ export async function editConfig(file, { input = process.stdin, output = process
     };
     const finish = error => {
       if (closed) return;
-      closed = true; clearTimeout(timer); clearTimeout(mouseTimer);
+      closed = true; clearTimeout(timer); clearTimeout(mouseTimer); stopDrag();
       input.off('data', onData); keyboard.off('keypress', onKey); keyboard.destroy();
       input.off('keypress', onKey); input.off('end', onEnd); input.off('error', onError); output.off('resize', render);
       input.setRawMode(Boolean(wasRaw)); if (wasPaused) input.pause();
@@ -188,31 +259,67 @@ export async function editConfig(file, { input = process.stdin, output = process
     };
     const onEnd = () => finish();
     const onError = error => finish(error);
-    const onKey = async (text, key = {}) => {
-      if (busy || closed) return;
+    const onKey = async (text, key = {}) => {
+      if (busy || closed) return;
+      if (dragging) stopDrag();
       try {
-        if (question) {
+        if (question) {
           if (text?.toLowerCase() === 'y') return finish();
           if (text?.toLowerCase() === 'n' || key.name === 'escape') question = false;
-          render(); return;
-        }
-        if (completion) {
+          render(); return;
+        }
+        if (guidePrompt) {
+          guidePrompt = false;
+          if (text?.toLowerCase() === 'a' || text?.toLowerCase() === 'r') {
+            const before = history.snapshot();
+            const updated = text.toLowerCase() === 'a' ? addConfigGuide(buffer.text) : removeConfigGuide(buffer.text);
+            if (updated !== buffer.text) {
+              buffer.text = updated; buffer.cursor = 0; buffer.anchor = null; followCursor = true;
+              history.record(before, 'guide');
+              revision++; clearTimeout(timer);
+              busy = true; issue = await validateEditorText(buffer.text); busy = false;
+              status = text.toLowerCase() === 'a' ? 'Guide added/updated. Ctrl+S saves it.' : 'Generated guide removed. Ctrl+S saves it.';
+            } else status = text.toLowerCase() === 'r' ? 'No generated guide to remove.' : 'Guide is already current.';
+          }
+          render(); return;
+        }
+        if (key.ctrl && key.name === 'a') {
+          history.breakGroup();
+          completion = null; buffer.anchor = 0; buffer.cursor = buffer.text.length; followCursor = true;
+          status = 'All text selected.'; render(); return;
+        }
+        if (key.ctrl && ['z', 'y'].includes(key.name)) {
+          completion = null;
+          const direction = key.name === 'z' ? 'undo' : 'redo';
+          if (history.change(direction)) {
+            followCursor = true; revision++; clearTimeout(timer);
+            busy = true; issue = await validateEditorText(buffer.text); busy = false;
+            status = direction === 'undo' ? 'Undone.' : 'Redone.';
+          } else status = direction === 'undo' ? 'Nothing to undo.' : 'Nothing to redo.';
+          render(); return;
+        }
+        if (completion) {
           if (key.name === 'escape') completion = null;
           else if (['up', 'down', 'tab'].includes(key.name)) completion.index = (completion.index + (key.name === 'up' ? -1 : 1) + completion.choices.length) % completion.choices.length;
-          else if (key.name === 'return') {
-            buffer.anchor = completion.start; buffer.cursor = completion.end;
-            buffer.insert(JSON.stringify(completion.choices[completion.index]));
+          else if (key.name === 'return') {
+            const before = history.snapshot();
+            buffer.anchor = completion.start; buffer.cursor = completion.end;
+            buffer.insert(JSON.stringify(completion.choices[completion.index]));
+            history.record(before, 'completion');
             completion = null; status = ''; revision++; clearTimeout(timer);
             busy = true; issue = await validateEditorText(buffer.text); busy = false;
           }
           render(); return;
         }
-        if (key.name === 'f2' || (key.ctrl && key.name === 'space')) {
+        if (key.name === 'f2' || (key.ctrl && key.name === 'space')) {
           const options = editorCompletions(buffer.text, buffer.cursor);
           completion = options ? { ...options, index: 0 } : null;
           status = options ? '' : 'No options here. Place the cursor on a property or value in valid JSON.';
-          render(); return;
-        }
+          render(); return;
+        }
+        if (key.name === 'f3') {
+          completion = null; guidePrompt = true; render(); return;
+        }
         if (key.ctrl && key.name === 'c') {
           const [start, end] = buffer.selection;
           if (start === end) status = 'Select text first, then press Ctrl+C.';
@@ -224,12 +331,14 @@ export async function editConfig(file, { input = process.stdin, output = process
           }
           render(); return;
         }
-        if (key.ctrl && key.name === 'v') {
-          busy = true;
-          try {
-            const pasted = (await clipboard.paste()).replace(/\r\n?|\n/g, '\n').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
-            if (pasted) {
-              buffer.insert(pasted); followCursor = true;
+        if (key.ctrl && key.name === 'v') {
+          busy = true;
+          try {
+            const pasted = (await clipboard.paste()).replace(/\r\n?|\n/g, '\n').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+            if (pasted) {
+              const before = history.snapshot();
+              buffer.insert(pasted); followCursor = true;
+              history.record(before, 'paste');
               status = ''; issue = await validateEditorText(buffer.text);
               revision++; clearTimeout(timer);
             } else status = 'Clipboard has no text.';
@@ -244,8 +353,9 @@ export async function editConfig(file, { input = process.stdin, output = process
           if (buffer.text === saved) return finish();
           question = true; render(); return;
         }
-        if (key.ctrl && key.name === 's') {
-          followCursor = true;
+        if (key.ctrl && key.name === 's') {
+          history.breakGroup();
+          followCursor = true;
           revision++; clearTimeout(timer); buffer.anchor = null;
           busy = true;
           issue = await validateEditorText(buffer.text);
@@ -260,19 +370,24 @@ export async function editConfig(file, { input = process.stdin, output = process
           }
           busy = false; render(); return;
         }
-        if (key.ctrl || key.meta) return;
-        followCursor = true;
-        const before = buffer.text;
-        if (key.name === 'pageup' || key.name === 'pagedown') buffer.move((key.name === 'pageup' ? -1 : 1) * viewport.height);
-        else if (['left', 'right', 'up', 'down', 'home', 'end', 'backspace', 'delete', 'return', 'tab'].includes(key.name)) buffer.key(key.name);
-        else if (text && !/[\x00-\x1f\x7f-\x9f]/.test(text)) buffer.insert(text);
-        if (before !== buffer.text) {
-          status = ''; issue = null; const current = ++revision; clearTimeout(timer);
+        if (key.ctrl || key.meta) return;
+        followCursor = true;
+        const before = history.snapshot();
+        const hadSelection = buffer.selection[0] !== buffer.selection[1];
+        if (key.name === 'pageup' || key.name === 'pagedown') buffer.move((key.name === 'pageup' ? -1 : 1) * viewport.height);
+        else if (['left', 'right', 'up', 'down', 'home', 'end', 'backspace', 'delete', 'return', 'tab'].includes(key.name)) buffer.key(key.name);
+        else if (text && !/[\x00-\x1f\x7f-\x9f]/.test(text)) buffer.insert(text);
+        if (before.text !== buffer.text) {
+          const typing = text && text.length === 1 && !/[\x00-\x1f\x7f-\x9f]/.test(text) && !hadSelection &&
+            !['return', 'tab', 'backspace', 'delete'].includes(key.name);
+          const deleting = ['backspace', 'delete'].includes(key.name) && !hadSelection;
+          history.record(before, typing ? 'typing' : deleting ? key.name : key.name || 'edit', typing || deleting);
+          status = ''; issue = null; const current = ++revision; clearTimeout(timer);
           timer = setTimeout(async () => {
             const result = await validateEditorText(buffer.text);
             if (!closed && current === revision) { issue = result; render(); }
           }, 150);
-        }
+        } else history.breakGroup();
         render();
       } catch (error) { finish(error); }
     };

package/src/config-template.js

@@ -1,5 +1,4 @@
 import { createHash } from 'node:crypto';
-import { translateLegacyConfigComments } from './legacy-config-comments.js';
 
 export const TEMPLATE_MARKER = '// veo: commented configuration template';
 
@@ -8,7 +7,7 @@ export const SOURCE_OPTIONS_GUIDE = String.raw`// veo: source discovery options
 // "deepScan": true,          // Verify every observed media candidate instead of the first 30
 // "timeout": "2m",          // Discovery deadline: 5s to 10m; plain numbers mean seconds
 // "listSources": false,     // true = list sources and exit for single-URL calls
-// "autoListSources": false, // true = search after extraction fails, without a yes/no prompt
+// "autoListSources": true,  // Search after extraction fails; false disables fallback
 // Command-line flags override these values, including --no-deep-scan and --no-list-sources.
 `;
 
@@ -25,7 +24,7 @@ export const PROFILE_OPTIONS_GUIDE = String.raw`${PROFILE_OPTIONS_MARKER}
 // "deepScan": true,           // Check every observed source candidate
 // "timeout": "2m",           // Source-search deadline, 5s to 10m
 // "listSources": false,      // List sources and exit for one URL
-// "autoListSources": true,   // Search after extraction fails, without asking
+// "autoListSources": true,   // Search after extraction fails (default)
 // "playlist": true,            // Enable only for playlist downloads
 // "playlistConcurrency": 2,    // Simultaneous entries: 1-4; default 2
 // "checkSpace": true,          // Estimate free cache/output space first
@@ -96,8 +95,10 @@ ${SOURCE_OPTIONS_GUIDE}
   // "embedMetadata": true,      // Embed the title, date and other metadata
   // "embedThumbnail": true,     // Embed the thumbnail
 
-  // The default profile is used automatically unless you select another profile.
-${PROFILE_OPTIONS_GUIDE}
+  // The default profile is used automatically unless you select another profile.
+  // Use veo profile NAME to make any named profile the default for future commands.
+  // The active choice is stored at the top level: "activeProfile": "music",
+${PROFILE_OPTIONS_GUIDE}
   // Select other profiles with --profile NAME or in the interactive wizard.
   // Example: veo "https://example.com/video.mp4" --profile music
   "profiles": {
@@ -126,18 +127,62 @@ ${PROFILE_OPTIONS_GUIDE}
 }
 `;
 
-// The revision follows the template content, so future examples refresh without
-// maintaining a separate version number.
+// The guide revision follows its content so the editor can offer an update.
 const TEMPLATE_REVISION = createHash('sha256').update(TEMPLATE_SOURCE).digest('hex').slice(0, 12);
-const REVISION_LINE = `// veo: template revision ${TEMPLATE_REVISION}`;
-const REFERENCE_BEGIN = '// veo: template reference begin';
-const REFERENCE_END = '// veo: template reference end';
-export const CONFIG_TEMPLATE = TEMPLATE_SOURCE.replace(TEMPLATE_MARKER, `${TEMPLATE_MARKER}\n${REVISION_LINE}`);
-
-function currentReference() {
-  const examples = CONFIG_TEMPLATE.split('\n').slice(2).map(line => `// ${line}`).join('\n');
-  return `${REFERENCE_BEGIN} ${TEMPLATE_REVISION}\n// This generated reference is refreshed when the template changes. Keep personal notes below it.\n// Current veo options: copy the settings you need below.\n${examples}\n${REFERENCE_END}`;
-}
+const REFERENCE_BEGIN = '// veo: template reference begin';
+const REFERENCE_END = '// veo: template reference end';
+export const CONFIG_TEMPLATE = `{
+  "profiles": {
+    "default": {},
+    "kompatibel": { "audio": false, "format": "mp4", "compatible": true, "recode": false },
+    "music": { "audio": true, "format": "mp3" },
+    "archive": { "quality": "1080p", "embedMetadata": true, "subLangs": "de,en" }
+  }
+}
+`;
+
+// Kept in the program. It is inserted into a config only when requested.
+export const CONFIG_GUIDE = `${REFERENCE_BEGIN} ${TEMPLATE_REVISION}\n// Current veo options. Copy only the settings you want into the JSON below.\n${TEMPLATE_SOURCE.split('\n').slice(1).map(line => line.startsWith('//') ? line : `// ${line}`).join('\n').trimEnd()}\n${REFERENCE_END}\n`;
+
+function generatedRange(text) {
+  const begin = text.indexOf(REFERENCE_BEGIN);
+  const end = begin < 0 ? -1 : text.indexOf(REFERENCE_END, begin);
+  if (begin < 0) {
+    const legacyHeader = /^\uFEFF?\/\/ veo: commented configuration template\r?\n\/\/ Reference: copy any examples/;
+    const settingsMarker = '// Your existing settings:';
+    const markerAt = legacyHeader.test(text) ? text.indexOf(settingsMarker) : -1;
+    if (markerAt < 0) return null;
+    const lineEnd = text.indexOf('\n', markerAt);
+    return { start: 0, stop: lineEnd < 0 ? text.length : lineEnd + 1, revision: 'legacy' };
+  }
+  if (end < 0) return null;
+  let start = begin;
+  const before = text.slice(0, begin);
+  if (/^\uFEFF?\/\/ veo: commented configuration template\r?\n$/.test(before)) start = 0;
+  const lineEnd = text.indexOf('\n', end);
+  let stop = lineEnd < 0 ? text.length : lineEnd + 1;
+  if (text.slice(stop).startsWith('// Your existing settings:\n')) stop += '// Your existing settings:\n'.length;
+  return { start, stop, revision: text.slice(begin, text.indexOf('\n', begin) < 0 ? text.length : text.indexOf('\n', begin)) };
+}
+
+export function configGuideState(text) {
+  const range = generatedRange(text);
+  if (!range) return text.includes(REFERENCE_BEGIN) || text.includes('// Reference: copy any examples') ? 'incomplete' : 'absent';
+  return range.revision === `${REFERENCE_BEGIN} ${TEMPLATE_REVISION}` ? 'current' : 'outdated';
+}
+
+export function addConfigGuide(text) {
+  const range = generatedRange(text);
+  if (!range && configGuideState(text) === 'incomplete') return text;
+  const bom = text.startsWith('\uFEFF') ? '\uFEFF' : '';
+  if (range) return (range.start === 0 ? bom : text.slice(0, range.start)) + CONFIG_GUIDE + text.slice(range.stop);
+  return bom + CONFIG_GUIDE + text.slice(bom.length);
+}
+
+export function removeConfigGuide(text) {
+  const range = generatedRange(text);
+  return range ? (range.start === 0 && text.startsWith('\uFEFF') ? '\uFEFF' : text.slice(0, range.start)) + text.slice(range.stop) : text;
+}
 
 // Remove comments only outside JSON strings. Whitespace replacement preserves
 // token boundaries, so malformed input cannot become valid by joining tokens.
@@ -165,60 +210,5 @@ export function stripConfigComments(text) {
       if (!closed) throw Object.assign(new Error('Unterminated block comment; add */ to close it.'), { position: commentStart });
     } else result += char;
   }
-  return result;
-}
-
-export function withConfigTemplate(text) {
-  text = translateLegacyConfigComments(text);
-  text = addDefaultProfile(text);
-  if (!text.replace(/^\uFEFF/, '').trim()) return CONFIG_TEMPLATE;
-  text = text.replace(/^\uFEFF/, '');
-  const reference = currentReference();
-  const begin = text.indexOf(REFERENCE_BEGIN);
-  const end = begin < 0 ? -1 : text.indexOf(REFERENCE_END, begin);
-  if (begin >= 0 && end < 0) return text; // Never replace an incomplete user-edited block.
-  if (begin >= 0 && end >= 0) {
-    if (text.slice(begin, end).startsWith(`${REFERENCE_BEGIN} ${TEMPLATE_REVISION}\n`)) return text;
-    const endOfLine = text.indexOf('\n', end);
-    const after = endOfLine < 0 ? text.length : endOfLine;
-    return text.slice(0, begin) + reference + text.slice(after);
-  }
-  if (text.startsWith(TEMPLATE_MARKER) && text.slice(0, 200).includes(REVISION_LINE)) return text;
-  if (text.startsWith(TEMPLATE_MARKER)) {
-    // Replace the older generated reference prefix, if present. Everything
-    // below the user's settings marker stays exactly as it was.
-    const settingsMarker = '// Your existing settings:';
-    const settingsAt = text.indexOf(settingsMarker);
-    if (text.includes('// Reference: copy any examples') && settingsAt >= 0) {
-      return `${TEMPLATE_MARKER}\n${reference}\n${text.slice(settingsAt)}`;
-    }
-    return text.replace(TEMPLATE_MARKER, `${TEMPLATE_MARKER}\n${reference}`);
-  }
-  return `${TEMPLATE_MARKER}\n${reference}\n// Your existing settings:\n${text}`;
-}
-
-function addDefaultProfile(text) {
-  // Insert only the missing profile, preserving user comments and formatting.
-  let clean, config;
-  try { clean = stripConfigComments(text); config = JSON.parse(clean); } catch { return text; }
-  if (!config || Array.isArray(config) || typeof config !== 'object') return text;
-  if (config.profiles && Object.hasOwn(config.profiles, 'default')) return text;
-  if (config.profiles !== undefined && (!config.profiles || Array.isArray(config.profiles) || typeof config.profiles !== 'object')) return text;
-  text = text.replace(/^\uFEFF/, '');
-  // Track depth to find the top-level profiles object, never a profile named profiles.
-  let depth = 0;
-  const tokens = /"(?:\\.|[^"\\])*"|[{}]/g;
-  for (const token of clean.matchAll(tokens)) {
-    if (token[0] === '{') depth++;
-    else if (token[0] === '}') depth--;
-    else if (depth === 1 && token[0] === '"profiles"') {
-      const after = token.index + token[0].length;
-      const match = /^\s*:\s*\{/.exec(clean.slice(after));
-      if (!match) continue;
-      const index = after + match[0].length;
-      return text.slice(0, index) + '\n    // Used automatically when no other profile is selected.\n    "default": {}' + (Object.keys(config.profiles).length ? ',' : '') + '\n' + text.slice(index);
-    }
-  }
-  const index = clean.indexOf('{') + 1;
-  return text.slice(0, index) + '\n  // Used automatically when no other profile is selected.\n  "profiles": { "default": {} }' + (Object.keys(config).length ? ',' : '') + '\n' + text.slice(index);
-}
+  return result;
+}