codeply-cli 0.1.1 → 0.3.0

package/lib/design-library/make-table-data.mjs

@@ -0,0 +1,39 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const idx = JSON.parse(readFileSync(path.join(__dirname, 'index.json'), 'utf8'));
+
+const CATEGORY_LABELS = {
+  productivity: 'Productivity',
+  finance: 'Finance',
+  shopping: 'Shopping',
+  social: 'Social',
+  travel: 'Travel',
+  food_delivery: 'Food Delivery',
+  health_fitness: 'Health & Fitness',
+  education: 'Education',
+  entertainment: 'Entertainment',
+  real_estate: 'Real Estate',
+};
+
+const rows = [];
+for (const [cat, apps] of Object.entries(idx.categories)) {
+  for (const a of apps) {
+    rows.push({
+      n: a.name,
+      c: cat,
+      r: a.rating ? Math.round(a.rating * 10) / 10 : null,
+      rc: a.ratingCount || 0,
+      s: a.screenshots.length,
+      u: a.appStoreUrl,
+      i: a.icon,
+    });
+  }
+}
+rows.sort((x, y) => y.s - x.s);
+
+const out = { generatedAt: new Date().toISOString(), labels: CATEGORY_LABELS, rows };
+writeFileSync(path.join(__dirname, 'table-data.json'), JSON.stringify(out));
+console.log('rows:', rows.length);

package/lib/design-library/query.mjs

@@ -0,0 +1,104 @@
+/**
+ * Query interface for the private design reference library built in
+ * index.json (914 apps / 6,433 real App Store screenshots across 10
+ * categories, sourced from Apple's public iTunes Search API). Loaded lazily
+ * and cached in memory - the file is ~2MB, cheap to hold for the life of one
+ * Craft process, not worth re-reading per call.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const INDEX_PATH = path.join(__dirname, 'index.json');
+
+export const CATEGORY_LABELS = {
+  productivity: 'Productivity',
+  finance: 'Finance',
+  shopping: 'Shopping',
+  social: 'Social',
+  travel: 'Travel',
+  food_delivery: 'Food Delivery',
+  health_fitness: 'Health & Fitness',
+  education: 'Education',
+  entertainment: 'Entertainment',
+  real_estate: 'Real Estate',
+};
+
+let cached = null;
+function load() {
+  if (cached) return cached;
+  cached = JSON.parse(readFileSync(INDEX_PATH, 'utf8'));
+  return cached;
+}
+
+export function designLibraryConfigured() {
+  try {
+    load();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function listCategories() {
+  const idx = load();
+  return Object.entries(idx.categories).map(([key, apps]) => ({
+    key,
+    label: CATEGORY_LABELS[key] || key,
+    appCount: apps.length,
+    screenshotCount: apps.reduce((s, a) => s + a.screenshots.length, 0),
+  }));
+}
+
+/**
+ * Search the library by free-text term (matched against app name) and/or an
+ * exact category key. Returns apps ranked by rating count (a rough proxy for
+ * "this is the version of the pattern worth matching," not just whichever
+ * came back first), each capped to `maxScreenshotsPerApp` URLs so a broad
+ * query doesn't return hundreds of image links at once.
+ */
+export function searchLibrary({ term = '', category = '', maxApps = 8, maxScreenshotsPerApp = 4 } = {}) {
+  const idx = load();
+  const normTerm = term.trim().toLowerCase();
+  const catKey = category.trim().toLowerCase().replace(/\s+/g, '_');
+
+  const categories = catKey && idx.categories[catKey] ? [catKey] : Object.keys(idx.categories);
+
+  function collect(matchTerm) {
+    const results = [];
+    for (const cat of categories) {
+      for (const app of idx.categories[cat]) {
+        if (matchTerm && !app.name.toLowerCase().includes(matchTerm)) continue;
+        results.push({ ...app, category: cat });
+      }
+    }
+    return results;
+  }
+
+  // The library only indexes app NAMES, not per-screen content - there is no
+  // app literally called "settings" or "onboarding", so a natural
+  // pattern-style query like that would always come back empty even though
+  // the category itself has plenty of real screens worth looking at. A given
+  // category is a reliable signal on its own; falling back to its top-rated
+  // apps (ignoring the term) beats returning nothing.
+  let results = collect(normTerm);
+  let usedFallback = false;
+  if (!results.length && normTerm && catKey && idx.categories[catKey]) {
+    results = collect('');
+    usedFallback = true;
+  }
+
+  results.sort((a, b) => (b.ratingCount || 0) - (a.ratingCount || 0));
+  results = results.slice(0, maxApps).map((app) => ({
+    name: app.name,
+    category: app.category,
+    categoryLabel: CATEGORY_LABELS[app.category] || app.category,
+    rating: app.rating ? Math.round(app.rating * 10) / 10 : null,
+    appStoreUrl: app.appStoreUrl,
+    screenshots: app.screenshots.slice(0, maxScreenshotsPerApp),
+  }));
+
+  results.usedFallback = usedFallback;
+  return results;
+}

package/lib/diagnostics.js

@@ -0,0 +1,192 @@
+/**
+ * Quick syntax checks on a file the agent just wrote or edited, so a broken
+ * change is reported in the same step instead of surfacing three steps later
+ * (or never). Syntax only, and fast: nothing here type-checks a whole project
+ * or needs a language server. Idea from opencode, which appends LSP errors to
+ * edit results.
+ *
+ * checkFile() never throws; when a checker is missing or unsure it stays quiet.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+
+const TIMEOUT_MS = 8000;
+const MAX_PROBLEMS = 10;
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: TIMEOUT_MS, windowsHide: true, maxBuffer: 1024 * 1024, ...opts }, (err, stdout, stderr) => {
+      resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, out: `${stdout || ''}${stderr || ''}`, missing: err && err.code === 'ENOENT' });
+    });
+  });
+}
+
+// ── JavaScript ──
+async function checkJs(file) {
+  const r = await run(process.execPath, ['--check', file], { env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' } });
+  if (r.code === 0) return [];
+  const text = r.out.trim();
+  // JSX in a .js file (common in React projects) is not plain JS; node can't judge it.
+  if (/Unexpected token '<'|Unexpected token <|JSX/.test(text)) return [];
+  const loc = text.match(/:(\d+)\r?\n/);
+  const msg = (text.match(/^(SyntaxError: .+)$/m) || [null, text.split('\n').find((l) => l.trim()) || 'syntax error'])[1];
+  return [`${loc ? `line ${loc[1]}: ` : ''}${msg}`];
+}
+
+// ── JSON ──
+const JSONC_NAMES = /^(tsconfig.*|jsconfig.*|\.eslintrc|devcontainer|settings|launch|tasks|extensions)\.json$/i;
+function checkJson(file, text) {
+  if (JSONC_NAMES.test(path.basename(file)) || /[\\/]\.vscode[\\/]/.test(file)) return [];
+  try { JSON.parse(text.replace(/^\uFEFF/, '')); return []; }
+  catch (e) {
+    const pos = Number((e.message.match(/position (\d+)/) || [])[1]);
+    const line = Number.isFinite(pos) ? text.slice(0, pos).split('\n').length : null;
+    return [`${line ? `line ${line}: ` : ''}invalid JSON (${e.message.replace(/ in JSON at position \d+.*$/, '')})`];
+  }
+}
+
+// ── TypeScript / TSX, through the project's own compiler, syntax only ──
+function findUp(start, rel, stop) {
+  let dir = start;
+  while (true) {
+    const p = path.join(dir, rel);
+    if (fs.existsSync(p)) return p;
+    const up = path.dirname(dir);
+    if (up === dir || (stop && dir === stop)) return null;
+    dir = up;
+  }
+}
+// ── Real type checking (semantic), in a warm worker per project ──
+const { fork } = require('child_process');
+const workers = new Map(); // project root -> { proc, pending, nextId, ready }
+const FIRST_CHECK_MS = 25000; // a big project's first build can take a while
+const CHECK_MS = 10000;
+
+function typeWorker(projectRoot, tsDir) {
+  let w = workers.get(projectRoot);
+  if (w && !w.dead) return w;
+  const proc = fork(path.join(__dirname, 'typecheck-worker.js'), [projectRoot, tsDir], {
+    env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+    stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+    windowsHide: true,
+  });
+  w = { proc, pending: new Map(), nextId: 1, checks: 0, dead: false };
+  proc.on('message', (m) => {
+    const p = m && m.id != null && w.pending.get(m.id);
+    if (p) { w.pending.delete(m.id); p(m); }
+  });
+  proc.on('exit', () => { w.dead = true; for (const [, p] of w.pending) p({ error: 'worker exited' }); w.pending.clear(); });
+  proc.unref();
+  workers.set(projectRoot, w);
+  return w;
+}
+
+function typeCheck(file, projectRoot, tsDir) {
+  const w = typeWorker(projectRoot, tsDir);
+  const timeout = w.checks++ === 0 ? FIRST_CHECK_MS : CHECK_MS;
+  return new Promise((resolve) => {
+    const id = w.nextId++;
+    const timer = setTimeout(() => { w.pending.delete(id); resolve(null); }, timeout);
+    w.pending.set(id, (m) => { clearTimeout(timer); resolve(m.error ? null : m.problems); });
+    try { w.proc.send({ id, file }); } catch { clearTimeout(timer); resolve(null); }
+  });
+}
+process.on('exit', () => { for (const [, w] of workers) try { w.proc.kill(); } catch {} });
+
+/**
+ * Code navigation through the project's own TypeScript (works for .ts, .tsx, .js, .jsx).
+ * @param {{op:'definition'|'references'|'implementation'|'hover'|'documentSymbol'|'workspaceSymbol', file?:string, line?:number, character?:number, symbol?:string, query?:string}} req
+ * @returns {Promise<{ok:boolean, text:string}>}
+ */
+async function navigate(req, cwd) {
+  const start = req.file ? path.dirname(req.file) : cwd;
+  const tsDir = findUp(start, path.join('node_modules', 'typescript'), path.parse(cwd).root);
+  if (!tsDir) return { ok: false, text: 'Code navigation needs TypeScript installed in the project (run npm install typescript). Use search instead.' };
+  const cfg = findUp(start, 'tsconfig.json', path.parse(cwd).root) || findUp(start, 'jsconfig.json', path.parse(cwd).root);
+  const projectRoot = cfg ? path.dirname(cfg) : cwd;
+  const w = typeWorker(projectRoot, tsDir);
+  const timeout = w.checks++ === 0 ? FIRST_CHECK_MS : CHECK_MS;
+  return new Promise((resolve) => {
+    const id = w.nextId++;
+    const timer = setTimeout(() => { w.pending.delete(id); resolve({ ok: false, text: 'Code navigation timed out (the project is still loading). Try again, or use search.' }); }, timeout + 10000);
+    w.pending.set(id, (m) => { clearTimeout(timer); resolve(m.error ? { ok: false, text: `Code navigation failed: ${m.error}` } : { ok: true, text: m.text }); });
+    try { w.proc.send({ id, ...req }); } catch { clearTimeout(timer); resolve({ ok: false, text: 'Code navigation is unavailable.' }); }
+  });
+}
+
+async function checkTs(file, text, cwd) {
+  const tsDir = findUp(path.dirname(file), path.join('node_modules', 'typescript'), path.parse(cwd).root);
+  if (!tsDir) return [];
+  // With a tsconfig/jsconfig the project is set up for type checking: ask
+  // the worker for real (semantic) errors. It falls back to the syntax-only
+  // pass below when it's slow or unavailable.
+  const cfg = findUp(path.dirname(file), 'tsconfig.json', path.parse(cwd).root) || findUp(path.dirname(file), 'jsconfig.json', path.parse(cwd).root);
+  if (cfg) {
+    const problems = await typeCheck(file, path.dirname(cfg), tsDir);
+    if (problems) return problems;
+  }
+  let ts;
+  try { ts = require(tsDir); } catch { return []; }
+  const out = ts.transpileModule(text, {
+    fileName: file,
+    reportDiagnostics: true,
+    compilerOptions: { jsx: file.endsWith('x') ? ts.JsxEmit.Preserve : undefined, target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext },
+  });
+  return (out.diagnostics || []).filter((d) => d.category === ts.DiagnosticCategory.Error).map((d) => {
+    const line = d.file && d.start != null ? d.file.getLineAndCharacterOfPosition(d.start).line + 1 : null;
+    return `${line ? `line ${line}: ` : ''}${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`;
+  });
+}
+
+// ── CSS: unbalanced braces are the classic broken-edit symptom ──
+function checkCss(text) {
+  const clean = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, '""');
+  let depth = 0, line = 1;
+  for (const ch of clean) {
+    if (ch === '\n') line++;
+    else if (ch === '{') depth++;
+    else if (ch === '}' && --depth < 0) return [`line ${line}: a "}" with no matching "{"`];
+  }
+  return depth > 0 ? [`${depth} "{" never closed (end of file)`] : [];
+}
+
+// ── Python ──
+let pythonCmd; // undefined = not probed yet, null = none found
+async function checkPy(file) {
+  if (pythonCmd === undefined) {
+    pythonCmd = null;
+    for (const c of process.platform === 'win32' ? ['py', 'python', 'python3'] : ['python3', 'python']) {
+      const r = await run(c, ['--version']);
+      if (r.code === 0 && /Python 3/.test(r.out)) { pythonCmd = c; break; }
+    }
+  }
+  if (!pythonCmd) return [];
+  const code = 'import sys,ast\nsrc=open(sys.argv[1],encoding="utf-8").read()\ntry:\n ast.parse(src)\nexcept SyntaxError as e:\n print(f"line {e.lineno}: SyntaxError: {e.msg}");sys.exit(1)';
+  const r = await run(pythonCmd, ['-c', code, file]);
+  return r.code === 0 ? [] : [r.out.trim().split('\n').pop()];
+}
+
+/**
+ * @param {string} abs  absolute path of the file that just changed
+ * @param {string} cwd  project root
+ * @returns {Promise<string[]>} problems, empty when clean or not checkable
+ */
+async function checkFile(abs, cwd) {
+  try {
+    const ext = path.extname(abs).toLowerCase();
+    if (!['.js', '.cjs', '.mjs', '.json', '.ts', '.tsx', '.mts', '.cts', '.jsx', '.css', '.py'].includes(ext)) return [];
+    const stat = fs.statSync(abs);
+    if (stat.size > 2_000_000) return [];
+    const text = fs.readFileSync(abs, 'utf8');
+    let problems = [];
+    if (ext === '.js' || ext === '.cjs' || ext === '.mjs') problems = await checkJs(abs);
+    else if (ext === '.json') problems = checkJson(abs, text);
+    else if (ext === '.jsx' || ext.startsWith('.ts') || ext === '.mts' || ext === '.cts') problems = await checkTs(abs, text, cwd);
+    else if (ext === '.css') problems = checkCss(text);
+    else if (ext === '.py') problems = await checkPy(abs);
+    return problems.filter(Boolean).slice(0, MAX_PROBLEMS);
+  } catch { return []; }
+}
+
+module.exports = { checkFile, navigate };

package/lib/edit-engine.js

@@ -1,8 +1,8 @@
 /**
- * Codeply CLI — surgical SEARCH/REPLACE edit engine
+ * Codeply CLI - surgical SEARCH/REPLACE edit engine
  *
  * Adapted from Codeply-App/main.js's computeInstructionEdits/
- * applySearchReplace/applyEditsToContent — same approach (small verified
+ * applySearchReplace/applyEditsToContent - same approach (small verified
  * diffs instead of a full-file rewrite), trimmed for a stateless single-shot
  * CLI: no local usage-history file, no .codeply/ response cache, no
  * multi-turn conversation context (each CLI invocation is its own process).
@@ -16,6 +16,15 @@ const ai = require('./ai');
 // runs), skipping blank lines on both sides. Re-indents the replacement to fit.
 // Returns { ok, content } or { ok:false, error:'notfound'|'multiple'|'empty' }.
 function applySearchReplace(fileContent, searchBlock, replaceBlock) {
+  // Matching works on LF text; a CRLF file is written back as CRLF so an edit
+  // never rewrites every line ending in the file (a whole-file diff, and a
+  // mixed-ending file once a later write adds LF lines).
+  const res = applySearchReplaceLF(fileContent, searchBlock, replaceBlock);
+  if (res.ok && /\r\n/.test(fileContent || '')) res.content = res.content.replace(/\r?\n/g, '\r\n');
+  return res;
+}
+
+function applySearchReplaceLF(fileContent, searchBlock, replaceBlock) {
   const nl = (s) => (s || '').replace(/\r\n/g, '\n');
   fileContent = nl(fileContent); searchBlock = nl(searchBlock); replaceBlock = nl(replaceBlock);
   if (!searchBlock.trim()) return { ok: false, error: 'empty' };
@@ -66,7 +75,7 @@ function applySearchReplace(fileContent, searchBlock, replaceBlock) {
   if (matches.length === 0) {
     // Last resort: anchor on the first AND last non-blank lines of the search
     // block (recovers when the AI dropped/added a line in the middle). Kept
-    // conservative — both anchors must be unique and the span must be modest.
+    // conservative - both anchors must be unique and the span must be modest.
     const sNon = searchLines.map(l => l.trim()).filter(x => x !== '');
     if (sNon.length >= 2) {
       const firstHits = [], lastHits = [];
@@ -84,7 +93,17 @@ function applySearchReplace(fileContent, searchBlock, replaceBlock) {
         }
       }
     }
-    return { ok: false, error: 'notfound' };
+    const fuzzy = fuzzyLocate(fileContent, searchBlock);
+    if (fuzzy.ok) {
+      const at = fileContent.indexOf(fuzzy.span);
+      // The model's replacement carries the indentation it wrongly assumed;
+      // move it to where the block really sits.
+      const text = fuzzy.reindent
+        ? reindentBlock(replaceBlock, (fuzzy.span.split('\n').find((l) => l.trim()) || '').match(/^[ \t]*/)[0])
+        : replaceBlock;
+      return { ok: true, content: fileContent.slice(0, at) + text + fileContent.slice(at + fuzzy.span.length), fuzzy: true };
+    }
+    return { ok: false, error: fuzzy.error === 'multiple' ? 'multiple' : 'notfound' };
   }
   if (matches.length > 1) return { ok: false, error: 'multiple' };
 
@@ -96,8 +115,146 @@ function applySearchReplace(fileContent, searchBlock, replaceBlock) {
   return { ok: true, content: fileContent.slice(0, startChar) + reindented + fileContent.slice(endChar) };
 }
 
+// ─── Fallback matchers ──────────────────────────────────────────────────────
+//
+// Adapted from opencode (packages/opencode/src/tool/edit.ts), MIT License,
+// Copyright (c) 2025 opencode - https://github.com/sst/opencode
+//
+// Each matcher yields candidate spans that exist VERBATIM in the file for a
+// search block the model copied imperfectly (escaped quotes, shifted
+// indentation, a middle line reworded). They only run after the matcher above
+// has found nothing, and a candidate is used only when it occurs exactly once
+// and is not far larger than what the model asked for.
+
+function levenshtein(a, b) {
+  if (a === '' || b === '') return Math.max(a.length, b.length);
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+function spanOfLines(lines, start, end) {
+  return lines.slice(start, end + 1).join('\n');
+}
+
+const ANCHOR_SIMILARITY = 0.65;
+
+// First and last lines match exactly (trimmed); the middle only has to be
+// similar. Recovers a search block with one line misremembered.
+function* blockAnchorMatches(content, find) {
+  const lines = content.split('\n');
+  const want = find.split('\n');
+  if (want[want.length - 1] === '') want.pop();
+  if (want.length < 3) return;
+  const first = want[0].trim(), last = want[want.length - 1].trim();
+  const maxDelta = Math.max(1, Math.floor(want.length * 0.25));
+
+  const candidates = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() !== first) continue;
+    for (let j = i + 2; j < lines.length; j++) {
+      if (lines[j].trim() !== last) continue;
+      if (Math.abs(j - i + 1 - want.length) <= maxDelta) candidates.push([i, j]);
+      break;
+    }
+  }
+
+  let best = null, bestScore = -1;
+  for (const [s, e] of candidates) {
+    const size = e - s + 1;
+    const middle = Math.min(want.length - 2, size - 2);
+    let score = 1;
+    if (middle > 0) {
+      score = 0;
+      for (let k = 1; k < want.length - 1 && k < size - 1; k++) {
+        const a = lines[s + k].trim(), b = want[k].trim();
+        const len = Math.max(a.length, b.length);
+        score += len ? 1 - levenshtein(a, b) / len : 1;
+      }
+      score /= middle;
+    }
+    if (score > bestScore) { bestScore = score; best = [s, e]; }
+  }
+  if (best && bestScore >= ANCHOR_SIMILARITY) yield spanOfLines(lines, best[0], best[1]);
+}
+
+// Same block with its indentation shifted as a whole.
+function* indentationFlexibleMatches(content, find) {
+  const dedent = (text) => {
+    const ls = text.split('\n');
+    const indents = ls.filter((l) => l.trim()).map((l) => l.match(/^\s*/)[0].length);
+    if (!indents.length) return text;
+    const min = Math.min(...indents);
+    return ls.map((l) => (l.trim() ? l.slice(min) : l)).join('\n');
+  };
+  const target = dedent(find);
+  const lines = content.split('\n');
+  const n = find.split('\n').length;
+  for (let i = 0; i + n <= lines.length; i++) {
+    const block = lines.slice(i, i + n).join('\n');
+    if (dedent(block) === target) yield block;
+  }
+}
+
+// The model wrote \n, \" or \` escapes where the file has the real characters.
+function* escapeNormalizedMatches(content, find) {
+  const unescape = (s) => s.replace(/\\(n|t|r|'|"|`|\\|\n|\$)/g, (m, c) =>
+    ({ n: '\n', t: '\t', r: '\r', "'": "'", '"': '"', '`': '`', '\\': '\\', '\n': '\n', $: '$' }[c] ?? m));
+  const target = unescape(find);
+  if (target !== find && content.includes(target)) yield target;
+  const lines = content.split('\n');
+  const n = target.split('\n').length;
+  for (let i = 0; i + n <= lines.length; i++) {
+    const block = lines.slice(i, i + n).join('\n');
+    if (block !== target && unescape(block) === target) yield block;
+  }
+}
+
+// Stray blank lines or spaces around the block.
+function* trimmedBoundaryMatches(content, find) {
+  const t = find.trim();
+  if (t === find) return;
+  if (content.includes(t)) yield t;
+}
+
+const FALLBACK_MATCHERS = [indentationFlexibleMatches, escapeNormalizedMatches, trimmedBoundaryMatches, blockAnchorMatches];
+
+// A "match" many times bigger than the search block means an anchor latched
+// onto the wrong closing line; replacing it would silently delete code.
+function isDisproportionate(span, find) {
+  const spanLines = span.split('\n').length, findLines = find.split('\n').length;
+  if (spanLines >= Math.max(findLines + 3, findLines * 2)) return true;
+  if (findLines === 1) return false;
+  return span.trim().length > Math.max(find.trim().length + 500, find.trim().length * 4);
+}
+
+/**
+ * Find the one verbatim span in `content` that an imperfect search block most
+ * likely meant. @returns {{ok:true, span:string} | {ok:false, error:'notfound'|'multiple'|'disproportionate'}}
+ */
+function fuzzyLocate(content, find) {
+  let sawMultiple = false;
+  for (const matcher of FALLBACK_MATCHERS) {
+    for (const span of matcher(content, find)) {
+      if (!span.trim()) continue;
+      const at = content.indexOf(span);
+      if (at === -1) continue;
+      if (at !== content.lastIndexOf(span)) { sawMultiple = true; continue; }
+      if (isDisproportionate(span, find)) return { ok: false, error: 'disproportionate' };
+      return { ok: true, span, reindent: matcher === indentationFlexibleMatches || matcher === blockAnchorMatches };
+    }
+  }
+  return { ok: false, error: sawMultiple ? 'multiple' : 'notfound' };
+}
+
 // Apply an ordered list of verified {search, replace} hunks to file content,
-// all-or-nothing (pure — no disk write).
+// all-or-nothing (pure - no disk write).
 function applyEditsToContent(fileContent, edits) {
   let working = (fileContent || '').replace(/\r\n/g, '\n');
   for (let i = 0; i < edits.length; i++) {
@@ -109,14 +266,14 @@ function applyEditsToContent(fileContent, edits) {
   return { ok: true, content: working };
 }
 
-const SYSTEM_PROMPT = `You are a precise code editor. You receive an INSTRUCTION describing a small change, and the FULL current file. Make ONLY the specific change requested, as surgical SEARCH/REPLACE edits — do NOT reproduce the whole file.
+const SYSTEM_PROMPT = `You are a precise code editor. You receive an INSTRUCTION describing a small change, and the FULL current file. Make ONLY the specific change requested, as surgical SEARCH/REPLACE edits - do NOT reproduce the whole file.
 
 STRICT RULES:
 1. Return an "edits" array. Use the FEWEST edits that cleanly express the change.
-2. "search" must be copied VERBATIM from the file below — exact existing text being changed, with just enough surrounding lines to be unique.
-3. "replace" is that same block with ONLY the requested change applied — preserve everything else in it exactly (formatting, unrelated properties, comments, whitespace style).
-4. If the SAME property/selector/value appears more than once in the file (e.g. "top" set in both a "from" and a "to" block), do NOT pick the first or most obvious match — use every clue in the instruction to find the ONE correct occurrence: the CURRENT value it mentions, nearby selectors, rule/keyframe names, or ordering (first/last, start/end). If more than one occurrence still fits equally well after that, return an EMPTY "edits" array with a "reason" naming the ambiguity instead of guessing.
-5. If the instruction genuinely requires large new content that can't be expressed as a small edit (e.g. "build a whole new page/game/module from scratch"), return an EMPTY "edits" array — do not guess badly at a huge diff.
+2. "search" must be copied VERBATIM from the file below - exact existing text being changed, with just enough surrounding lines to be unique.
+3. "replace" is that same block with ONLY the requested change applied - preserve everything else in it exactly (formatting, unrelated properties, comments, whitespace style).
+4. If the SAME property/selector/value appears more than once in the file (e.g. "top" set in both a "from" and a "to" block), do NOT pick the first or most obvious match - use every clue in the instruction to find the ONE correct occurrence: the CURRENT value it mentions, nearby selectors, rule/keyframe names, or ordering (first/last, start/end). If more than one occurrence still fits equally well after that, return an EMPTY "edits" array with a "reason" naming the ambiguity instead of guessing.
+5. If the instruction genuinely requires large new content that can't be expressed as a small edit (e.g. "build a whole new page/game/module from scratch"), return an EMPTY "edits" array - do not guess badly at a huge diff.
 6. Return ONLY valid JSON, no markdown, no commentary.
 
 Response format:
@@ -148,7 +305,7 @@ async function computeInstructionEdits(instruction, filePath) {
     const messages = [
       { role: 'system', content: SYSTEM_PROMPT },
       // Large/stable content (the file) first, small/always-different content
-      // (the instruction) last — the ai-proxy's underlying model caches a
+      // (the instruction) last - the ai-proxy's underlying model caches a
       // repeated PREFIX, so this ordering matters for repeated calls against
       // the same file even when the instruction text differs each time.
       { role: 'user', content: `FULL FILE (${path.basename(filePath)}):\n${content}\n\nINSTRUCTION:\n${instruction}` },
@@ -188,8 +345,8 @@ async function computeInstructionEdits(instruction, filePath) {
     const feedback =
       `Some "search" blocks from your last answer are wrong. Return the COMPLETE corrected edits array again, fixing these:\n` +
       bad.map(c => c.status === 'multiple'
-        ? `- Matched MULTIPLE places — include more surrounding lines so it is unique:\n${c.e.search}`
-        : `- NOT found in the file — copy it EXACTLY from the FULL FILE above, character for character:\n${c.e.search}`
+        ? `- Matched MULTIPLE places - include more surrounding lines so it is unique:\n${c.e.search}`
+        : `- NOT found in the file - copy it EXACTLY from the FULL FILE above, character for character:\n${c.e.search}`
       ).join('\n') +
       `\nEvery "search" must be copied verbatim from the file shown above.`;
     let retry;
@@ -204,4 +361,4 @@ async function computeInstructionEdits(instruction, filePath) {
   return { success: true, edits: good, badCount: bad.length, confidence, reason, tokensUsed: totalTokens, modelUsed: lastModelUsed };
 }
 
-module.exports = { applySearchReplace, applyEditsToContent, computeInstructionEdits };
+module.exports = { applySearchReplace, applyEditsToContent, computeInstructionEdits, fuzzyLocate };