codeply-cli 0.1.0

package/lib/ai.js

@@ -0,0 +1,181 @@
+/**
+ * Codeply CLI — AI client
+ *
+ * Two backends, selected by lib/config.js:
+ *
+ *   codeply  the 'ai-proxy' Supabase Edge Function the desktop app uses (see
+ *            Codeply-App/supabase/functions/ai-proxy). No provider key lives in
+ *            this CLI; it authenticates with the signed-in session from
+ *            lib/auth.js, so usage counts against that account's daily cap.
+ *
+ *   ollama   Ollama's OpenAI-compatible /v1/chat/completions, either the cloud
+ *            (ollama.com, bearer key) or a local daemon (no key). No Codeply
+ *            sign-in required, and no daily cap.
+ *
+ * Both return the identical shape — {success, data:{choices:[{message}]}, …} —
+ * so nothing downstream (agent loop, edit engine) knows or cares which ran.
+ */
+const { SUPABASE_URL, SUPABASE_ANON_KEY, getAccessToken } = require('./auth');
+const { getConfig } = require('./config');
+
+const AI_PROXY_URL = `${SUPABASE_URL}/functions/v1/ai-proxy`;
+
+function isRateLimitError(msg) {
+  const s = String(msg || '').toLowerCase();
+  return s.includes('rate limit') || s.includes('429') || s.includes('tokens per day')
+    || s.includes('tokens per minute') || s.includes(' tpd') || s.includes(' tpm')
+    || s.includes('quota') || s.includes('daily ai request limit');
+}
+
+const MAX_ATTEMPTS = 3;
+const RETRY_BACKOFF_MS = [1200, 4000];
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Statuses worth retrying. 546 is Supabase's own code for an Edge Function
+ * killed for exceeding its resource limits (WORKER_LIMIT) — it fires on long
+ * generations and is usually transient, so a retry is far more useful to the
+ * user than surfacing "HTTP 546". 5xx and 429 get the same treatment.
+ */
+function isTransientStatus(status) {
+  return status === 429 || status >= 500;
+}
+
+/** Turn a bare status into something a user can act on. */
+function describeStatus(status) {
+  if (status === 546) {
+    return 'The AI service hit its resource limit mid-request (Supabase 546). ' +
+      'This usually happens on very long generations — try a narrower request, ' +
+      'or ask for a targeted edit instead of a full-file rewrite.';
+  }
+  if (status === 504 || status === 408) return 'The AI service timed out. Try a smaller request.';
+  if (status === 429) return 'Rate limited by the AI service. Wait a moment and try again.';
+  if (status >= 500) return `The AI service is temporarily unavailable (HTTP ${status}).`;
+  return `HTTP ${status}`;
+}
+
+/**
+ * Retry wrapper shared by both backends.
+ * `send` returns { done, value } to stop, or { retryable, error } to try again.
+ */
+async function withRetries(send) {
+  let lastError = 'Request failed';
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    if (attempt > 0) await sleep(RETRY_BACKOFF_MS[attempt - 1] ?? 4000);
+    const step = await send();
+    if (step.done) return step.value;
+    lastError = step.error;
+    if (!step.retryable) return { success: false, error: lastError };
+  }
+  return { success: false, error: lastError };
+}
+
+async function chatViaProxy(messages, opts) {
+  const token = await getAccessToken();
+  if (!token) return { success: false, error: 'Not signed in. Run `codeply login` first.' };
+
+  return withRetries(async () => {
+    let res;
+    try {
+      res = await fetch(AI_PROXY_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`,
+          'apikey': SUPABASE_ANON_KEY,
+        },
+        body: JSON.stringify({ messages, opts }),
+      });
+    } catch (e) {
+      // Network-level failure — also worth another go.
+      return { retryable: true, error: e.message };
+    }
+
+    const body = await res.json().catch(() => ({}));
+    if (res.ok && body.success) {
+      return { done: true, value: { success: true, data: body.data, modelUsed: body.modelUsed } };
+    }
+
+    // A structured error from the function itself is final: it means the
+    // function ran and deliberately rejected us (auth, daily cap, provider
+    // error). Retrying that just burns the user's quota.
+    if (body.error) return { done: true, value: { success: false, error: body.error } };
+
+    return { retryable: isTransientStatus(res.status), error: describeStatus(res.status) };
+  });
+}
+
+async function chatViaOllama(messages, opts, cfg) {
+  const { host, model, apiKey } = cfg.ollama;
+  const isLocal = /localhost|127\.0\.0\.1/.test(host);
+  if (!apiKey && !isLocal) {
+    return { success: false, error: `No Ollama API key set for ${host}. Run \`codeply provider ollama --key <key>\`.` };
+  }
+
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+
+  return withRetries(async () => {
+    let res;
+    try {
+      res = await fetch(`${host}/v1/chat/completions`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          model,
+          messages,
+          temperature: opts.temperature ?? 0,
+          ...(opts.maxTokens ? { max_tokens: opts.maxTokens } : {}),
+          ...(opts.json ? { response_format: { type: 'json_object' } } : {}),
+          stream: false,
+        }),
+      });
+    } catch (e) {
+      const hint = isLocal ? ' Is `ollama serve` running?' : '';
+      return { retryable: true, error: e.message + hint };
+    }
+
+    const body = await res.json().catch(() => ({}));
+
+    if (res.ok && body.choices?.[0]) {
+      // Already OpenAI-shaped, so it drops straight into the same call sites.
+      return { done: true, value: { success: true, data: body, modelUsed: body.model || model } };
+    }
+
+    const apiError = body?.error?.message || body?.error;
+    if (apiError) {
+      const msg = typeof apiError === 'string' ? apiError : JSON.stringify(apiError);
+      // A missing/unknown model won't fix itself on retry.
+      const fatal = /not found|does not exist|unknown model|unauthor|invalid.*key|forbidden/i.test(msg);
+      if (fatal) return { done: true, value: { success: false, error: `Ollama: ${msg}` } };
+      return { retryable: isTransientStatus(res.status), error: `Ollama: ${msg}` };
+    }
+
+    return { retryable: isTransientStatus(res.status), error: describeStatus(res.status) };
+  });
+}
+
+/**
+ * @param {Array<{role:string, content:string}>} messages
+ * @param {{ json?: boolean, maxTokens?: number, temperature?: number }} opts
+ * @returns {Promise<{success:boolean, data?:object, error?:string, modelUsed?:string}>}
+ */
+async function chat(messages, opts = {}) {
+  const cfg = getConfig();
+  return cfg.provider === 'ollama'
+    ? chatViaOllama(messages, opts, cfg)
+    : chatViaProxy(messages, opts);
+}
+
+/** Chat helper that expects a JSON object back and parses it. */
+async function chatJson(messages, opts = {}) {
+  const r = await chat(messages, { ...opts, json: true });
+  if (!r.success) return { success: false, error: r.error };
+  let parsed = null;
+  try { parsed = JSON.parse(r.data.choices[0].message.content); }
+  catch { return { success: false, error: 'AI returned an unreadable response.' }; }
+  return { success: true, json: parsed, usage: r.data.usage || {}, modelUsed: r.modelUsed };
+}
+
+module.exports = { chat, chatJson, isRateLimitError };

package/lib/ai.mjs

@@ -0,0 +1,6 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const ai = require('../lib/ai.js');
+export default ai;
+export const { chat, chatJson, isRateLimitError } = ai;

package/lib/apply-limit.js

@@ -0,0 +1,41 @@
+/**
+ * Codeply CLI — daily apply cap
+ *
+ * Reuses the EXACT same Supabase table/RPC the desktop app checks against
+ * (apply_history + get_daily_apply_count(), see Codeply-App/supabase/
+ * apply_limit.sql) — an apply from the CLI counts toward the same account's
+ * 100/day cap as an apply from the desktop app, not a separate bucket.
+ */
+const { getClient, getSession } = require('./auth');
+
+const DAILY_APPLY_LIMIT = 100;
+
+/** Returns { allowed, count, limit }. Fails OPEN on a DB hiccup, same as the desktop app. */
+async function checkApplyLimit() {
+  const session = await getSession();
+  if (!session) return { allowed: false, count: 0, limit: DAILY_APPLY_LIMIT, error: 'Not signed in. Run `codeply login` first.' };
+
+  const supabase = getClient();
+  try {
+    const { data, error } = await supabase.rpc('get_daily_apply_count');
+    if (error || typeof data !== 'number') throw error || new Error('unexpected response');
+    return { allowed: data < DAILY_APPLY_LIMIT, count: data, limit: DAILY_APPLY_LIMIT };
+  } catch (e) {
+    console.warn('[apply-limit] check failed, allowing:', e.message);
+    return { allowed: true, count: 0, limit: DAILY_APPLY_LIMIT };
+  }
+}
+
+/** Records one successful file write toward the daily cap. Fire-and-forget. */
+async function recordApplyEvent(filePath) {
+  const session = await getSession();
+  if (!session) return;
+  const supabase = getClient();
+  try {
+    await supabase.from('apply_history').insert({ user_id: session.user.id, file_path: filePath || '' });
+  } catch (e) {
+    console.warn('[apply-limit] record failed:', e.message);
+  }
+}
+
+module.exports = { DAILY_APPLY_LIMIT, checkApplyLimit, recordApplyEvent };

package/lib/auth.js

@@ -0,0 +1,112 @@
+/**
+ * Codeply CLI — auth
+ *
+ * Passwordless (email + 6-digit code) sign-in against the SAME Supabase
+ * project the desktop app uses — same account, same ai-proxy access, same
+ * daily request/apply caps either way. The session is cached in
+ * ~/.codeply/auth.json, mirroring the desktop app's own file-based session
+ * storage (there's no OS keychain dependency to add for a CLI).
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline/promises');
+const { createClient } = require('@supabase/supabase-js');
+
+const SUPABASE_URL = 'https://zswkhfkfseclgadhvobg.supabase.co';
+const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Inpzd2toZmtmc2VjbGdhZGh2b2JnIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODAyMzYyOTgsImV4cCI6MjA5NTgxMjI5OH0.EoTQdIGQQDrN1uEqQfya3VmrQMT68jkzPLphbLwNTWg';
+
+const configDir = path.join(os.homedir(), '.codeply');
+const sessionPath = path.join(configDir, 'auth.json');
+
+function ensureConfigDir() {
+  fs.mkdirSync(configDir, { recursive: true });
+}
+
+// File-based storage adapter for Supabase session persistence (Node has no
+// localStorage) — same pattern the desktop app uses in main.js.
+const fileStorage = {
+  getItem(key) {
+    try { const d = JSON.parse(fs.readFileSync(sessionPath, 'utf8')); return d[key] || null; }
+    catch { return null; }
+  },
+  setItem(key, value) {
+    ensureConfigDir();
+    let d = {};
+    try { d = JSON.parse(fs.readFileSync(sessionPath, 'utf8')); } catch { }
+    d[key] = value;
+    try { fs.writeFileSync(sessionPath, JSON.stringify(d)); } catch { }
+  },
+  removeItem(key) {
+    let d = {};
+    try { d = JSON.parse(fs.readFileSync(sessionPath, 'utf8')); } catch { }
+    delete d[key];
+    try { fs.writeFileSync(sessionPath, JSON.stringify(d)); } catch { }
+  },
+};
+
+let client = null;
+function getClient() {
+  if (!client) {
+    client = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+      auth: {
+        storage: fileStorage,
+        autoRefreshToken: true,
+        persistSession: true,
+        detectSessionInUrl: false,
+      },
+    });
+  }
+  return client;
+}
+
+async function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await rl.question(question)).trim(); }
+  finally { rl.close(); }
+}
+
+/** Interactive email + 6-digit-code sign-in. Prints its own progress/errors. */
+async function login() {
+  const supabase = getClient();
+  const email = await prompt('Email: ');
+  if (!email) { console.error('No email entered.'); return false; }
+
+  const { error: otpErr } = await supabase.auth.signInWithOtp({ email, options: { shouldCreateUser: false } });
+  if (otpErr) {
+    console.error(`Could not send a code: ${otpErr.message}`);
+    console.error('(No account with that email? Sign up in the Codeply desktop app first.)');
+    return false;
+  }
+
+  console.log(`Code sent to ${email}.`);
+  const code = await prompt('6-digit code: ');
+  const { data, error } = await supabase.auth.verifyOtp({ email, token: code.replace(/\s+/g, ''), type: 'email' });
+  if (error || !data?.session) {
+    console.error(`Sign-in failed: ${error?.message || 'invalid code'}`);
+    return false;
+  }
+
+  console.log(`Signed in as ${data.session.user.email}.`);
+  return true;
+}
+
+async function logout() {
+  const supabase = getClient();
+  try { await supabase.auth.signOut(); } catch { }
+  console.log('Signed out.');
+}
+
+/** Returns the current session, refreshing it if the client already has one. */
+async function getSession() {
+  const supabase = getClient();
+  const { data: { session } } = await supabase.auth.getSession();
+  return session || null;
+}
+
+async function getAccessToken() {
+  const session = await getSession();
+  return session?.access_token || null;
+}
+
+module.exports = { SUPABASE_URL, SUPABASE_ANON_KEY, getClient, login, logout, getSession, getAccessToken };

package/lib/auth.mjs

@@ -0,0 +1,6 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const auth = require('./auth.js');
+export default auth;
+export const { SUPABASE_URL, SUPABASE_ANON_KEY, getClient, login, logout, getSession, getAccessToken } = auth;

package/lib/config.js

@@ -0,0 +1,89 @@
+/**
+ * Codeply CLI — model provider configuration.
+ *
+ * Lives in ~/.codeply/config.json, next to auth.json, deliberately OUTSIDE the
+ * repo: it holds an API key and must never be committable. Environment
+ * variables win over the file so a key can be supplied per-shell without ever
+ * touching disk.
+ *
+ * Providers:
+ *   codeply  the hosted ai-proxy (default; needs `codeply login`)
+ *   ollama   Ollama's OpenAI-compatible API — cloud (ollama.com, needs a key)
+ *            or a local daemon (http://localhost:11434, no key needed)
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const configDir = path.join(os.homedir(), '.codeply');
+const configPath = path.join(configDir, 'config.json');
+
+const DEFAULTS = {
+  provider: 'codeply',
+  ollama: {
+    host: 'https://ollama.com',
+    model: 'gemma4:31b',
+    apiKey: '',
+  },
+};
+
+function readFile() {
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Effective config: defaults ← file ← environment. */
+function getConfig() {
+  const file = readFile();
+  const provider = process.env.CODEPLY_PROVIDER || file.provider || DEFAULTS.provider;
+  const fileOllama = file.ollama || {};
+
+  return {
+    provider,
+    ollama: {
+      host: (process.env.OLLAMA_HOST || fileOllama.host || DEFAULTS.ollama.host).replace(/\/+$/, ''),
+      model: process.env.OLLAMA_MODEL || fileOllama.model || DEFAULTS.ollama.model,
+      apiKey: process.env.OLLAMA_API_KEY || fileOllama.apiKey || '',
+    },
+  };
+}
+
+/** Merge a patch into the stored config. Written user-only where supported. */
+function saveConfig(patch) {
+  const current = readFile();
+  const next = {
+    ...current,
+    ...patch,
+    ollama: { ...(current.ollama || {}), ...(patch.ollama || {}) },
+  };
+  try {
+    if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(next, null, 2), { mode: 0o600 });
+    // mkdir/writeFile modes are advisory on Windows; chmod is best-effort.
+    try { fs.chmodSync(configPath, 0o600); } catch {}
+    return { ok: true, path: configPath };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/** Never render a key in full — this is what goes on screen and in logs. */
+function maskKey(key) {
+  if (!key) return '(none)';
+  if (key.length <= 8) return '••••';
+  return key.slice(0, 4) + '…' + key.slice(-4);
+}
+
+/** One-line description of where completions are coming from. */
+function describeProvider(cfg = getConfig()) {
+  if (cfg.provider === 'ollama') {
+    const where = /localhost|127\.0\.0\.1/.test(cfg.ollama.host) ? 'local' : 'cloud';
+    return `ollama ${where} · ${cfg.ollama.model}`;
+  }
+  return 'codeply proxy';
+}
+
+module.exports = { getConfig, saveConfig, maskKey, describeProvider, configPath };

package/lib/edit-engine.js

@@ -0,0 +1,207 @@
+/**
+ * Codeply CLI — surgical SEARCH/REPLACE edit engine
+ *
+ * Adapted from Codeply-App/main.js's computeInstructionEdits/
+ * 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).
+ */
+const fs = require('fs');
+const path = require('path');
+const ai = require('./ai');
+
+// Apply ONE search/replace edit to a string. Exact match first, then
+// whitespace-tolerant (ignore leading/trailing space, then collapse internal
+// 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) {
+  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' };
+
+  const fileLines = fileContent.split('\n');
+  const searchLines = searchBlock.split('\n');
+
+  const lineStartOffset = (idx) => { let o = 0; for (let k = 0; k < idx; k++) o += fileLines[k].length + 1; return o; };
+
+  const reindentBlock = (block, indent) => {
+    const ls = block.split('\n');
+    const firstNonEmpty = ls.find(l => l.trim() !== '') || '';
+    const base = (firstNonEmpty.match(/^[ \t]*/) || [''])[0];
+    return ls.map(l => {
+      if (l.trim() === '') return '';
+      const stripped = l.startsWith(base) ? l.slice(base.length) : l.replace(/^[ \t]*/, '');
+      return indent + stripped;
+    }).join('\n');
+  };
+
+  const locate = (normalize) => {
+    const s = searchLines.map(normalize).filter(x => x !== '');
+    if (!s.length) return [];
+    const found = [];
+    for (let start = 0; start < fileLines.length; start++) {
+      if (normalize(fileLines[start]) !== s[0]) continue;
+      let fi = start, si = 0, end = start;
+      while (si < s.length && fi < fileLines.length) {
+        const nf = normalize(fileLines[fi]);
+        if (nf === '') { fi++; continue; }       // skip blank lines in the file
+        if (nf !== s[si]) break;
+        end = fi; fi++; si++;
+      }
+      if (si === s.length) found.push([start, end]);
+    }
+    return found;
+  };
+
+  const exact = fileContent.indexOf(searchBlock);
+  if (exact !== -1) {
+    if (exact !== fileContent.lastIndexOf(searchBlock)) return { ok: false, error: 'multiple' };
+    return { ok: true, content: fileContent.slice(0, exact) + replaceBlock + fileContent.slice(exact + searchBlock.length) };
+  }
+
+  let matches = locate(l => l.trim());
+  if (matches.length === 0) matches = locate(l => l.trim().replace(/\s+/g, ' '));
+
+  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.
+    const sNon = searchLines.map(l => l.trim()).filter(x => x !== '');
+    if (sNon.length >= 2) {
+      const firstHits = [], lastHits = [];
+      fileLines.forEach((l, i) => {
+        const t = l.trim();
+        if (t === sNon[0]) firstHits.push(i);
+        if (t === sNon[sNon.length - 1]) lastHits.push(i);
+      });
+      if (firstHits.length === 1 && lastHits.length === 1 && lastHits[0] >= firstHits[0]) {
+        const sL = firstHits[0], eL = lastHits[0];
+        if (eL - sL + 1 <= sNon.length * 3 + 5) {   // don't grab a huge region
+          const indent = (fileLines[sL].match(/^[ \t]*/) || [''])[0];
+          const reindented = reindentBlock(replaceBlock, indent);
+          return { ok: true, content: fileContent.slice(0, lineStartOffset(sL)) + reindented + fileContent.slice(lineStartOffset(eL) + fileLines[eL].length) };
+        }
+      }
+    }
+    return { ok: false, error: 'notfound' };
+  }
+  if (matches.length > 1) return { ok: false, error: 'multiple' };
+
+  const [startLine, endLine] = matches[0];
+  const indent = (fileLines[startLine].match(/^[ \t]*/) || [''])[0];
+  const reindented = reindentBlock(replaceBlock, indent);
+  const startChar = lineStartOffset(startLine);
+  const endChar = lineStartOffset(endLine) + fileLines[endLine].length;
+  return { ok: true, content: fileContent.slice(0, startChar) + reindented + fileContent.slice(endChar) };
+}
+
+// Apply an ordered list of verified {search, replace} hunks to file content,
+// 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++) {
+    const { search, replace } = edits[i];
+    const res = applySearchReplace(working, search, replace);
+    if (!res.ok) return { ok: false, error: res.error, index: i };
+    working = res.content;
+  }
+  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.
+
+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.
+6. Return ONLY valid JSON, no markdown, no commentary.
+
+Response format:
+{
+  "edits": [ { "search": "<exact verbatim block from the file>", "replace": "<that block with the change applied>" } ],
+  "reason": "<one short sentence>",
+  "confidence": <0-100>
+}`;
+
+/**
+ * Asks the AI for surgical edits, self-corrects up to twice against bad
+ * "search" matches, and returns only the edits that verify cleanly against
+ * the real file content.
+ * @returns {Promise<{success:boolean, edits?:Array, badCount?:number, reason?:string, confidence?:number, tokensUsed?:number, modelUsed?:string, error?:string}>}
+ */
+async function computeInstructionEdits(instruction, filePath) {
+  if (!fs.existsSync(filePath)) return { success: false, error: `File not found: ${filePath}` };
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  const probe = (search) => {
+    const res = applySearchReplace(content, search, search);
+    return res.ok ? 'ok' : res.error;
+  };
+
+  let totalTokens = 0;
+  let lastModelUsed = null;
+
+  const askModel = async (feedback) => {
+    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
+      // 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}` },
+    ];
+    if (feedback) messages.push({ role: 'user', content: feedback });
+
+    const aiResult = await ai.chat(messages, { json: true });
+    if (!aiResult.success) throw new Error(aiResult.error);
+    if (aiResult.modelUsed) lastModelUsed = aiResult.modelUsed;
+    const data = aiResult.data;
+    totalTokens += (data.usage || {}).total_tokens || 0;
+
+    let parsed;
+    try { parsed = JSON.parse(data.choices[0].message.content); }
+    catch { return { edits: [], confidence: 0, reason: '' }; }
+
+    const edits = Array.isArray(parsed.edits)
+      ? parsed.edits.filter(e => e && e.search && e.replace != null).map(e => ({ search: e.search, replace: e.replace }))
+      : [];
+    return { edits, confidence: parsed.confidence == null ? 75 : parsed.confidence, reason: parsed.reason || '' };
+  };
+
+  let edits, confidence, reason;
+  try {
+    ({ edits, confidence, reason } = await askModel());
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+
+  const verify = (list) => list.map((e) => ({ e, status: probe(e.search) }));
+  let checked = verify(edits);
+  let bad = checked.filter(c => c.status !== 'ok');
+
+  let pass = 0;
+  while (bad.length && pass < 2) {
+    pass++;
+    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}`
+      ).join('\n') +
+      `\nEvery "search" must be copied verbatim from the file shown above.`;
+    let retry;
+    try { retry = await askModel(feedback); }
+    catch (e) { break; }
+    if (retry.edits.length) { edits = retry.edits; confidence = retry.confidence; reason = retry.reason || reason; }
+    checked = verify(edits);
+    bad = checked.filter(c => c.status !== 'ok');
+  }
+
+  const good = checked.filter(c => c.status === 'ok').map(c => c.e);
+  return { success: true, edits: good, badCount: bad.length, confidence, reason, tokensUsed: totalTokens, modelUsed: lastModelUsed };
+}
+
+module.exports = { applySearchReplace, applyEditsToContent, computeInstructionEdits };