backdraw 0.0.0-stage → 2.1.0

package/lib/results.js

@@ -0,0 +1,170 @@
+'use strict';
+// The text lines of a tool result for a job. Pure (no file or bridge access) so every status can
+// be tested; mcp-server.js adds the preview images.
+const { intArg } = require('./args');
+// pct: the warning quotes the same rounded shares as the prompt ChatGPT got.
+const { TOLERANCE, aspectOption, safeBand, pct: percent } = require('./aspect');
+
+const FINAL = new Set(['succeeded', 'failed', 'cancelled', 'needs_reference', 'text_reply']);
+// Each tool call returns within this many seconds by default: some clients that reach the PC from
+// the cloud give up on a tool call after 60 s, and generating takes 1-3 minutes.
+const DEFAULT_WAIT = 45;
+// How long a tool call may wait for its job: wait_seconds as whole seconds within 0-900.
+const waitSeconds = args => intArg(args.wait_seconds, 0, 900, DEFAULT_WAIT);
+const checkAgain = id => `Call job_status with job_id="${id}" and wait_seconds=${DEFAULT_WAIT} again (repeat until it finishes), or cancel_job to stop it.`;
+// A prompt that asks to change an existing image rather than draw a new one.
+const EDIT_INTENT = /\b(edit(s|ed|ing)?|modif(y|ies|ied|ying)|retouch(es|ed|ing)?|inpaint(s|ed|ing)?|change only|only change|change [a-z ]{1,30} only|keep (everything|it|the rest)|pixel-identical|same (pose|image|drawing|character))\b|düzenle|değiştir|aynı (kalsın|bırak|tut)|koru(yarak)?\b/i;
+
+const neutral = (pct, against) => `Similarity to ${against}: ${pct}% (a local edit keeps ~95-100%, a redraw is usually under 60%).`;
+
+function editCheckLines(job) {
+  const check = job.editCheck;
+  if (!check || !check.results || !check.results.length) return [];
+  // Each result is an output image's closest match; judge by the least similar output.
+  const worst = check.results.reduce((a, b) => (b.similarity < a.similarity ? b : a));
+  // Judged on the shown percentage, so the verdict never contradicts the number next to it.
+  const pct = Math.round(worst.similarity * 100);
+  // Only collection images attached: they are style or character references, so a new picture is
+  // what was asked for, not a failed edit.
+  const col = job.collection;
+  if (col && (job.references || []).length <= col.used.length) return [neutral(pct, worst.against)];
+  if (pct >= 75) return [`Edit check: ${pct}% of the image is unchanged compared with ${worst.against} — this looks like a real edit (edited: true).`];
+  if (EDIT_INTENT.test(job.prompt || '')) {
+    return [`⚠ EDIT CHECK (edited: false): only ${pct}% of the image matches ${worst.against}. ChatGPT most likely drew a NEW picture instead of editing (a real local edit keeps ~95-100%). ` +
+      'Tell the user; if an exact edit is needed, call generate_image again WITHOUT conversation_url and with reference_images=[the original image file].'];
+  }
+  return [neutral(pct, worst.against)];
+}
+
+// Collection images come after the caller's own reference images in job.references.
+function referenceLines(job) {
+  const refs = job.references || [];
+  const col = job.collection;
+  const own = col ? refs.slice(0, Math.max(0, refs.length - col.used.length)) : refs;
+  const lines = own.length ? [`Reference images attached: ${own.map(r => r.name).join(', ')}`] : [];
+  if (col) {
+    const left = col.skipped && col.skipped.length ? `; left out: ${col.skipped.join(', ')}` : '';
+    lines.push(`References: collection "${col.name}": used ${col.used.length} of ${col.total} (${col.used.join(', ')})${left}`);
+  }
+  return lines;
+}
+
+const MISSING = '⚠ TRANSPARENT BACKGROUND MISSING';
+const RETRY = 'Tell the user; retry once in a fresh chat or remove the background with another tool.';
+const KINDS = { png: 'PNG', jpg: 'JPEG', jpeg: 'JPEG', webp: 'WebP', gif: 'GIF' };
+const COLOR_TYPES = { 0: 'grayscale', 2: 'RGB', 3: 'palette' };
+
+// ChatGPT was told what the crop may cut: nothing for a ratio it draws itself, the edges outside the
+// safe band beyond 1:3..3:1. When it drew another shape, the crop cut more and may have hit the subject.
+function cropWarning(im) {
+  const { full } = im;
+  if (!im.aspect || !im.width || !im.height || !full.width || !full.height) return null;
+  const p = aspectOption(im.aspect);
+  const axis = im.width < full.width ? 'width' : 'height';
+  const kept = axis === 'width' ? im.width / full.width : im.height / full.height;
+  const band = safeBand(p);
+  const allowed = band && band.axis === axis ? band.share : 1;
+  if (kept >= allowed * (1 - TOLERANCE)) return null;
+  const edges = axis === 'height' ? 'top and bottom' : 'left and right';
+  return `⚠ ChatGPT drew ${full.width}x${full.height} instead of ${p.generate.label}, so the crop removed ${percent(1 - kept)} of the ${axis} ` +
+    `(${percent((1 - kept) / 2)} at the ${edges} each${allowed < 1 ? `; it was told only ${percent((1 - allowed) / 2)} each may be cut off` : ''}). ` +
+    'Check the saved image for cut-off subjects or text; the full image is kept too.';
+}
+
+function aspectLine(im) {
+  const [w, h] = im.aspect.split(':').map(Number);
+  if (!im.width || !im.height) return `Aspect ratio: ${im.aspect} requested; the image size is unknown, so it was not cropped.`;
+  const got = `${im.width}x${im.height}`;
+  if (Math.abs(im.width * h - im.height * w) <= TOLERANCE * im.height * w) return `Aspect ratio: ${im.aspect} requested, got ${got} (within ${TOLERANCE * 100}%, not cropped).`;
+  return `⚠ Aspect ratio: ${im.aspect} requested, got ${got}; it could not be cropped.`;
+}
+
+// Judged on ChatGPT's own file: a cropped copy is always an RGBA PNG (canvas), whatever came in.
+// The pixels were measured on the saved (cropped) image.
+function transparencyLine(im) {
+  const ext = (String((im.full || im).path).match(/\.([a-z0-9]+)$/i) || [])[1] || '';
+  const kind = KINDS[ext.toLowerCase()] || 'image';
+  const share = im.alpha ? im.alpha.transparentShare : null;
+  // Only a PNG header, a JPEG or measured pixels tell whether there is an alpha channel at all.
+  if (!im.png && kind !== 'JPEG' && share === null) return `Transparent background: ${kind}; whether it is transparent could not be measured.`;
+  const channel = im.png ? im.png.alphaChannel || im.png.trns : kind !== 'JPEG' && share > 0;
+  if (!channel) {
+    const format = im.png ? `${COLOR_TYPES[im.png.colorType] || `color type ${im.png.colorType}`} PNG` : kind;
+    return `${MISSING}: ChatGPT returned an image without an alpha channel (${format}), so the background is not transparent. ${RETRY}`;
+  }
+  if (share === null) return `Transparent background: ${kind} with an alpha channel; how much of it is transparent could not be measured.`;
+  if (share > 0.02) return `Transparent background: yes — ${kind} with an alpha channel, ${Math.round(share * 100)}% of the pixels are transparent.`;
+  return `${MISSING}: the ${kind} has an alpha channel but ${share > 0 ? 'almost ' : ''}every pixel is opaque. ${RETRY}`;
+}
+
+// The Saved line of one image, plus what was asked about its shape and background.
+function imageLines(job, im) {
+  const lines = [];
+  if (im.full) {
+    lines.push(`Saved: ${im.path} (${im.width ? `${im.width}x${im.height}, ` : ''}cropped from the centre to ${im.aspect})`,
+      `Full image before cropping: ${im.full.path}${im.full.width ? ` (${im.full.width}x${im.full.height})` : ''}`);
+    // Only a generated image was drawn to a requested shape; a fetched one is simply cropped.
+    const warning = job.mode !== 'collect' && cropWarning(im);
+    if (warning) lines.push(warning);
+  } else {
+    lines.push(`Saved: ${im.path}${im.width ? ` (${im.width}x${im.height})` : ''}`);
+    if (im.aspect) lines.push(aspectLine(im));
+  }
+  if (job.transparent) lines.push(transparencyLine(im));
+  return lines;
+}
+
+function resultLines(job) {
+  const lines = [];
+  switch (job.status) {
+    case 'succeeded':
+      lines.push(`SUCCESS — ChatGPT generated ${job.images.length} image(s). Job ${job.id}.`);
+      break;
+    case 'needs_reference':
+      lines.push(`NEEDS REFERENCE IMAGE — ChatGPT could not access the image it should edit and asked for it to be uploaded again (job ${job.id}).${job.reattached ? ' It still asked after the bridge re-attached the image.' : ''}`,
+        'Do NOT resend the same prompt. Next step: call generate_image again with reference_images=[the local file of the image to edit] — most reliable WITHOUT conversation_url (a fresh chat). ' +
+        'Alternatively pass auto_reattach=true to let the bridge attach the chat\'s latest image itself.');
+      break;
+    case 'text_reply':
+      lines.push(`CHATGPT REPLIED WITHOUT AN IMAGE (job ${job.id}). Read its reply below and act on it — do not resend the identical prompt. ` +
+        'If it asked a question, answer it with generate_image(conversation_url=<the link below>, prompt=<your answer>, send_as_is=true); if it refused, rephrase the request.');
+      break;
+    case 'failed':
+      lines.push(`FAILED — ${job.error || 'unknown error'} (job ${job.id})`);
+      break;
+    case 'cancelled':
+      lines.push(`CANCELLED — job ${job.id}.`);
+      break;
+    case 'needs_human':
+      lines.push(`NEEDS USER ACTION — ${job.message} (job ${job.id})`,
+        'Ask the user to open the ChatGPT tab in Chrome and complete it themselves; do not try to get around it. ' +
+        `The job continues automatically for up to 10 minutes; check it with job_status(job_id="${job.id}", wait_seconds=${DEFAULT_WAIT}).`);
+      break;
+    case 'queued':
+      lines.push(`QUEUED — position ${job.queuePosition || '?'} in the queue (position 1 starts as soon as the running job, if any, is done). Job ${job.id}. ${checkAgain(job.id)}`);
+      break;
+    default:
+      lines.push(`STILL RUNNING — ${job.message || job.step}. Job ${job.id}. ${checkAgain(job.id)}`);
+  }
+  if (job.conversationUrl) lines.push(`ChatGPT conversation: ${job.conversationUrl}`);
+  // The ratio belongs to this job: a later fetch_images only crops when it is given the ratio again.
+  if (job.status === 'failed' && job.conversationUrl && job.aspect) {
+    lines.push(`If the chat finishes later, fetch_images(conversation_url=<the link above>, aspect_ratio="${job.aspect}") saves the image cropped the same way.`);
+  }
+  lines.push(...referenceLines(job));
+  if (job.reattached && job.status === 'succeeded') lines.push('Note: ChatGPT first asked for the image again; the bridge re-attached it and asked once more.');
+  for (const im of job.images || []) lines.push(...imageLines(job, im));
+  for (const c of job.copies || []) lines.push(`Copied to: ${c}`);
+  if (job.copyError) lines.push(`Could not copy into output_dir: ${job.copyError}`);
+  lines.push(...editCheckLines(job));
+  if (job.assistantText) {
+    lines.push(job.status === 'succeeded' ? `ChatGPT's text: ${job.assistantText.slice(0, 1500)}` : `ChatGPT's reply:\n${job.assistantText.slice(0, 3000)}`);
+  }
+  if (job.chatImages && job.chatImages.length) {
+    lines.push('Images already saved from this chat (newest first) — usable as reference_images:');
+    for (const im of job.chatImages) lines.push(`- ${im.path}  (${im.job}: "${im.prompt}")`);
+  }
+  return lines;
+}
+
+module.exports = { FINAL, DEFAULT_WAIT, EDIT_INTENT, waitSeconds, editCheckLines, imageLines, referenceLines, resultLines };

package/lib/term.js

@@ -0,0 +1,22 @@
+'use strict';
+// Terminal output for setup and doctor: a status symbol per line, in colour only on a terminal that
+// wants it (NO_COLOR, a pipe or a file get plain text, which stays readable).
+
+const SYMBOLS = { ok: '✓', warn: '⚠', fail: '✗', info: '·' };
+const COLORS = { ok: 32, warn: 33, fail: 31, info: 90, bold: 1, dim: 90 };
+
+function useColor(stream = process.stdout, env = process.env) {
+  return !!(stream && stream.isTTY) && !('NO_COLOR' in env) && env.TERM !== 'dumb';
+}
+
+function painter(color) {
+  return (kind, text) => (color && COLORS[kind] ? `\x1b[${COLORS[kind]}m${text}\x1b[0m` : text);
+}
+
+// "✓ Label   detail", with the symbol coloured.
+function line(paint, status, label, detail, width = 0) {
+  const head = `${paint(status, SYMBOLS[status])} ${width ? label.padEnd(width) : label}`;
+  return detail ? `${head} ${detail}` : head;
+}
+
+module.exports = { SYMBOLS, useColor, painter, line };

package/lib/toml.js

@@ -0,0 +1,248 @@
+'use strict';
+// Just enough TOML to keep one MCP server table up to date in Codex's config.toml without a parser
+// dependency: find the [a.b] table (and its [a.b.*] sub-tables), set or replace a few single keys in
+// it, or drop it, and leave every other line of the file exactly as it was. Forms this can't edit
+// safely (the table written as dotted keys or as an inline table) are refused instead of guessed at.
+
+// Splits a key path such as  mcp_servers . "backdraw"  into its parts; null if it isn't one.
+function keyPath(text) {
+  const parts = [];
+  let s = text.trim();
+  while (s) {
+    let m;
+    if ((m = /^"((?:[^"\\]|\\.)*)"/.exec(s))) parts.push(unescapeBasic(m[1]));
+    else if ((m = /^'([^']*)'/.exec(s))) parts.push(m[1]);
+    else if ((m = /^[A-Za-z0-9_-]+/.exec(s))) parts.push(m[0]);
+    else return null;
+    s = s.slice(m[0].length).trim();
+    if (!s) break;
+    if (s[0] !== '.') return null;
+    s = s.slice(1).trim();
+    if (!s) return null;
+  }
+  return parts.length ? parts : null;
+}
+
+// The escapes of a TOML basic string ("…").
+function unescapeBasic(body) {
+  const simple = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+  return body.replace(/\\(u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8}|.)/g, (all, e) => {
+    if (e.length > 1) return String.fromCodePoint(parseInt(e.slice(1), 16));
+    return e in simple ? simple[e] : all;
+  });
+}
+
+const startsWith = (parts, prefix) => prefix.every((p, i) => parts[i] === p);
+const samePath = (a, b) => a.length === b.length && startsWith(a, b);
+
+// Reads one line from `state` ({ ml: open multi-line string quote or null, depth: open [ and { of a
+// value }), skipping strings and comments. Returns the state at the end of the line and the text
+// before any comment.
+function tokenize(line, state) {
+  let { ml, depth } = state;
+  let i = 0;
+  let codeEnd = line.length;
+  while (i < line.length) {
+    if (ml) {
+      if (ml === '"""' && line[i] === '\\') { i += 2; continue; }
+      if (line.startsWith(ml, i)) {
+        i += 3;
+        while (line[i] === ml[0]) i++; // up to two quotes may end the content
+        ml = null;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    const c = line[i];
+    if (c === '#') { codeEnd = i; break; }
+    if (line.startsWith('"""', i) || line.startsWith("'''", i)) { ml = line.slice(i, i + 3); i += 3; continue; }
+    if (c === '"' || c === "'") {
+      i++;
+      while (i < line.length && line[i] !== c) i += c === '"' && line[i] === '\\' ? 2 : 1;
+      i++;
+      continue;
+    }
+    if (c === '[' || c === '{') depth++;
+    else if (c === ']' || c === '}') depth = Math.max(0, depth - 1);
+    i++;
+  }
+  return { state: { ml, depth }, code: line.slice(0, codeEnd).trimEnd() };
+}
+
+// One entry per line:
+//   header  its table path, when the line is a [a.b] or [[a.b]] header
+//   table   the table the line is in
+//   cont    the line continues a value from the line before (a multi-line string or array)
+//   blank / comment  nothing but whitespace / only a comment
+function scan(lines) {
+  let table = [];
+  let state = { ml: null, depth: 0 };
+  return lines.map(line => {
+    const cont = !!state.ml || state.depth > 0;
+    if (!cont) {
+      const m = /^\s*\[\[?([^\[\]]+)\]\]?\s*(?:#.*)?$/.exec(line);
+      const header = m && keyPath(m[1]);
+      if (header) { table = header; return { header, table, cont: false }; }
+    }
+    const t = tokenize(line, state);
+    state = t.state;
+    return { header: null, table, cont, blank: !cont && !line.trim(), comment: !cont && /^\s*#/.test(line) };
+  });
+}
+
+// Ranges [start, end) of the lines that belong to the table at `parts` or one of its sub-tables.
+// Comments and blank lines right before the next header belong to that next table.
+function tableRanges(info, parts) {
+  const ranges = [];
+  for (let i = 0; i < info.length; i++) {
+    if (!info[i].header || !startsWith(info[i].header, parts)) continue;
+    let end = i + 1;
+    while (end < info.length && !(info[end].header && !startsWith(info[end].header, parts))) end++;
+    let last = end;
+    if (end < info.length) while (last > i + 1 && (info[last - 1].blank || info[last - 1].comment)) last--;
+    ranges.push([i, last]);
+    i = end - 1;
+  }
+  return ranges;
+}
+
+// The key path and value text of a `key = value` line, or null.
+function assignment(line) {
+  const m = /^\s*((?:"(?:[^"\\]|\\.)*"|'[^']*'|[^=#"'])+?)\s*=\s*(.*)$/.exec(line);
+  const key = m && keyPath(m[1]);
+  return key ? { key, value: m[2] } : null;
+}
+
+// The table (or a parent of it) written some other way, as dotted keys (a.b.key = …) or as an
+// inline table (a = { b = … }), can't be edited line by line: a [a.b] header next to it would even
+// make the file invalid.
+function assertPlainTable(lines, info, parts) {
+  lines.forEach((line, i) => {
+    if (info[i].header || info[i].cont || startsWith(info[i].table, parts)) return;
+    const a = assignment(line);
+    if (!a) return;
+    const full = [...info[i].table, ...a.key];
+    if (startsWith(full, parts) || startsWith(parts, full)) {
+      throw new Error(`${parts.join('.')} is written in a form Backdraw doesn't edit (line ${i + 1}); change it by hand`);
+    }
+  });
+}
+
+const tomlString = s => `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+function tomlValue(v) {
+  if (Array.isArray(v)) return `[${v.map(tomlValue).join(', ')}]`;
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  return tomlString(v);
+}
+
+// The line after a key's value (a value may go on over continuation lines).
+function valueEnd(info, i) {
+  let end = i + 1;
+  while (end < info.length && info[end].cont) end++;
+  return end;
+}
+
+// Removes `key = value` from the table's own lines starting at `from`; returns whether it was there.
+function dropKey(lines, info, from, key) {
+  for (let i = from; i < lines.length && !info[i].header; i++) {
+    if (info[i].cont) continue;
+    const a = assignment(lines[i]);
+    if (!a || a.key.length !== 1 || a.key[0] !== key) continue;
+    const end = valueEnd(info, i);
+    lines.splice(i, end - i);
+    info.splice(i, end - i);
+    return true;
+  }
+  return false;
+}
+
+function splitLines(text) {
+  const eol = /\r\n/.test(text) ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
+  if (lines.length && lines[lines.length - 1] === '') lines.pop();
+  return { lines, eol };
+}
+
+const joinLines = (lines, eol) => (lines.length ? lines.join(eol) + eol : '');
+
+const ownTable = (info, parts) => tableRanges(info, parts).find(([start]) => samePath(info[start].header, parts));
+
+// Sets `values` (key -> string/array/number/boolean) in the table at `parts`, creating the table at
+// the end of the file if it isn't there. Other keys and sub-tables of the table stay as they are.
+function setTable(text, parts, values) {
+  const { lines, eol } = splitLines(text);
+  const info = scan(lines);
+  assertPlainTable(lines, info, parts);
+  const own = ownTable(info, parts);
+  const assignments = Object.entries(values).map(([k, v]) => `${/^[A-Za-z0-9_-]+$/.test(k) ? k : tomlString(k)} = ${tomlValue(v)}`);
+  if (!own) {
+    if (lines.length && lines[lines.length - 1].trim() !== '') lines.push('');
+    lines.push(`[${parts.map(p => (/^[A-Za-z0-9_-]+$/.test(p) ? p : tomlString(p))).join('.')}]`, ...assignments);
+    return joinLines(lines, eol);
+  }
+  const [start] = own;
+  for (const key of Object.keys(values)) dropKey(lines, info, start + 1, key);
+  lines.splice(start + 1, 0, ...assignments);
+  return joinLines(lines, eol);
+}
+
+// Drops the table at `parts` with its sub-tables (and the blank lines left in front of it).
+function removeTable(text, parts) {
+  const { lines, eol } = splitLines(text);
+  const info = scan(lines);
+  assertPlainTable(lines, info, parts);
+  for (const [start, end] of tableRanges(info, parts).reverse()) {
+    let from = start;
+    while (from > 0 && lines[from - 1].trim() === '') from--;
+    lines.splice(from, end - from);
+    while (from < lines.length && lines[from].trim() === '') lines.splice(from, 1);
+    if (from > 0 && from < lines.length) lines.splice(from, 0, '');
+  }
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+  return joinLines(lines, eol);
+}
+
+// Reads the plain string / array-of-strings values of the table at `parts`, or null without it.
+// Only what Backdraw itself writes is understood; other values come back as their raw text.
+function readTable(text, parts) {
+  const { lines } = splitLines(text);
+  const info = scan(lines);
+  const own = ownTable(info, parts);
+  if (!own) return null;
+  const out = {};
+  for (let i = own[0] + 1; i < lines.length && !info[i].header; i++) {
+    if (info[i].cont) continue;
+    const a = assignment(lines[i]);
+    if (!a || a.key.length !== 1) continue;
+    const end = valueEnd(info, i);
+    let state = { ml: null, depth: 0 };
+    const parts2 = [];
+    for (const l of [a.value, ...lines.slice(i + 1, end)]) {
+      const t = tokenize(l, state);
+      state = t.state;
+      parts2.push(t.code.trim());
+    }
+    out[a.key[0]] = parseValue(parts2.join(' ').trim());
+  }
+  return out;
+}
+
+function parseString(s) {
+  if (s.startsWith('"')) return unescapeBasic(s.slice(1, -1));
+  if (s.startsWith("'")) return s.slice(1, -1);
+  return s;
+}
+
+function parseValue(raw) {
+  if (/^("(?:[^"\\]|\\.)*"|'[^']*')$/.test(raw)) return parseString(raw);
+  const arr = /^\[(.*)\]$/s.exec(raw);
+  if (arr) {
+    const items = arr[1].match(/"(?:[^"\\]|\\.)*"|'[^']*'/g) || [];
+    return items.map(parseString);
+  }
+  return raw;
+}
+
+module.exports = { keyPath, setTable, removeTable, readTable };