ucode-agent 1.5.0 → 1.7.0

package/src/core/provider.js

@@ -22,6 +22,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import dotenv from 'dotenv';
 import OpenAI from 'openai';
+import { jsonrepair } from 'jsonrepair';
 import { Failure } from './failure.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -395,7 +396,14 @@ export function explain(err, id) {
       (Number.isFinite(asNumber) && asNumber > 0 ? asNumber : null) ??
       seconds(/try again in ([\dhms.]+)/i.exec(detail)?.[1]) ??
       null;
-    const daily = /per day|RPD|TPD|tokens per day/i.test(detail);
+    // The daily cap reads "free-models-per-day-high-balance", with hyphens, and
+    // names its source in the metadata. It is one cap across every free model,
+    // so it is reported at once rather than waited on model after model.
+    const meta = body?.error?.metadata ?? {};
+    const daily = /per[- ]day|RPD|TPD|daily/i.test(`${detail} ${meta.limit_source ?? ''}`);
+    const resetMs = Number(meta.headers?.['X-RateLimit-Reset'] ?? err?.headers?.get?.('x-ratelimit-reset'));
+    const resetAt = daily && Number.isFinite(resetMs) && resetMs > Date.now() ? new Date(resetMs) : null;
+    const cap = Number(meta.headers?.['X-RateLimit-Limit']) || null;
     const wait = Number.isFinite(retryAfter) && retryAfter
       ? (retryAfter >= 60 ? `${Math.ceil(retryAfter / 60)} min` : `${Math.ceil(retryAfter)}s`)
       : null;
@@ -404,14 +412,14 @@ export function explain(err, id) {
       kind: 'rate_limit',
       attempted,
       failed: daily
-        ? `The free daily request cap for ${modelName(id)} is used up.`
+        ? `This key's free daily limit${cap ? ` of ${cap} requests` : ''} is used up. It covers every free model, so switching will not help.`
         : `Too many requests for ${modelName(id)} just now${wait ? ` — clear in ${wait}` : ''}.`,
       fix: daily
-        ? 'Free caps reset each day. /model switches to another one, or add credit to ' +
-          'your account to lift the ceiling.'
+        ? `It resets ${resetAt ? `at ${resetAt.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}` : 'once a day'}. ` +
+          'Adding credit to your account raises the limit.'
         : 'ucode waits these out on its own. Free endpoints are shared, so it usually ' +
           'clears in seconds; /model moves to a quieter one.',
-      detail: { retryAfter, daily },
+      detail: { retryAfter, daily, resetAt: resetAt?.getTime() ?? null },
       cause: err,
     });
   }
@@ -554,7 +562,7 @@ const pause = (ms) => new Promise((r) => setTimeout(r, ms));
  * @param {Array}  messages neutral messages
  * @param {Array}  [tools]  neutral tool definitions
  * @param {object} [opts]   { model, temperature, signal, maxOutputTokens,
- *                            onText, onThinking, onWait }
+ *                            reasoning, attempts, onText, onThinking, onWait }
  */
 export async function ask(messages, tools = [], opts = {}) {
   const id = opts.model || current;
@@ -578,8 +586,11 @@ export async function ask(messages, tools = [], opts = {}) {
   }
   if (opts.temperature !== undefined) request.temperature = opts.temperature;
   if (opts.maxOutputTokens) request.max_tokens = opts.maxOutputTokens;
+  if (opts.reasoning) request.reasoning = opts.reasoning;
 
-  const attempts = 4;
+  // A side call (the design review) passes fewer: it is better skipped than
+  // waited on through a string of rate-limit pauses.
+  const attempts = opts.attempts ?? 4;
   let problem;
 
   // Text already on screen cannot be unprinted, so a stream is only safe to
@@ -710,7 +721,7 @@ async function streamed(request, opts, id) {
 
   const toolCalls = [];
   for (const [index, slot] of partial) {
-    toolCalls.push(readCall({ id: slot.id || `call_${index}`, name: slot.name, raw: slot.args }));
+    toolCalls.push(readCall({ id: slot.id || `call_${index}`, name: slot.name, raw: slot.args, cutOff: finishReason === 'length' }));
   }
 
   return {
@@ -727,6 +738,56 @@ async function streamed(request, opts, id) {
   };
 }
 
+/**
+ * Recover the files from a file-write call whose JSON will not parse.
+ *
+ * The usual cause is a double quote inside the code that the model forgot to
+ * escape — `className="flex"` — which ends the JSON string early. No general
+ * repair can know which quote was meant, but a file write has a fixed shape:
+ * "path", then "content", then either the next file or the end. Splitting on
+ * that shape and escaping the stray quotes gets every file back.
+ */
+export function salvageWrites(text) {
+  const heads = [...text.matchAll(/"path"\s*:\s*"((?:[^"\\]|\\.)*)"\s*,\s*"content"\s*:\s*"/g)];
+  if (!heads.length) return null;
+
+  const files = [];
+  for (let i = 0; i < heads.length; i++) {
+    const from = heads[i].index + heads[i][0].length;
+    const to = i + 1 < heads.length ? heads[i + 1].index : text.length;
+    // The string ends at the last quote that is followed by nothing but JSON
+    // punctuation — `"}, {`, or `"}}, {` when the model added a brace, or `"}]}`.
+    const body = text.slice(from, to).replace(/"[\s,{}[\]]*$/, '');
+    const content = unescapeLoose(body);
+    const pathValue = unescapeLoose(heads[i][1]);
+    if (!pathValue || !content) return null; // not the shape we thought — leave it an honest error
+    files.push({ path: pathValue, content });
+  }
+  return files.length ? files : null;
+}
+
+/**
+ * Decode a JSON string body the forgiving way: the standard escapes are
+ * honoured, and everything JSON would reject — a raw line break, a tab, a stray
+ * quote, an escape JSON does not know — is kept as the character it plainly is.
+ */
+function unescapeLoose(s) {
+  const simple = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', '"': '"', '\\': '\\', '/': '/' };
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c !== '\\' || i === s.length - 1) { out += c; continue; }
+    const next = s[++i];
+    if (next === 'u' && /^[0-9a-fA-F]{4}$/.test(s.slice(i + 1, i + 5))) {
+      out += String.fromCharCode(parseInt(s.slice(i + 1, i + 5), 16));
+      i += 4;
+    } else {
+      out += simple[next] ?? next;
+    }
+  }
+  return out;
+}
+
 /**
  * Parse one tool call's arguments.
  *
@@ -734,7 +795,7 @@ async function streamed(request, opts, id) {
  * back to the model, which usually fixes its own JSON on the next step —
  * cheaper than failing the whole turn over a stray comma.
  */
-function readCall({ id, name, raw }) {
+export function readCall({ id, name, raw, cutOff = false }) {
   const call = { id, name, args: {} };
   const text = String(raw ?? '').trim();
   if (!text) return call;
@@ -743,6 +804,28 @@ function readCall({ id, name, raw }) {
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) call.args = parsed;
     else call.parseError = `arguments must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`;
   } catch (err) {
+    // A missing comma or a stray control character in a 3,000-token
+    // batch_write used to throw the whole step away — half a minute of output
+    // discarded over one character. Repair the usual slips instead. Never when
+    // the reply was cut off at the output limit, though: repairing that would
+    // close the string and quietly write half a file.
+    if (!cutOff) {
+      try {
+        const fixed = JSON.parse(jsonrepair(text));
+        if (fixed && typeof fixed === 'object' && !Array.isArray(fixed)) {
+          call.args = fixed;
+          call.repaired = true;
+          return call;
+        }
+      } catch { /* beyond general repair — try the file-write shape next */ }
+
+      const salvaged = (name === 'write_file' || name === 'batch_write') ? salvageWrites(text) : null;
+      if (salvaged) {
+        call.args = name === 'write_file' ? salvaged[0] : { files: salvaged };
+        call.repaired = true;
+        return call;
+      }
+    }
     call.parseError = `${err.message} — the raw arguments were: ${text.slice(0, 300)}`;
   }
   return call;
@@ -753,7 +836,7 @@ function normalize(data, id) {
   const message = choice?.message ?? {};
 
   const toolCalls = (message.tool_calls ?? []).map((c) =>
-    readCall({ id: c.id, name: c.function?.name, raw: c.function?.arguments })
+    readCall({ id: c.id, name: c.function?.name, raw: c.function?.arguments, cutOff: choice?.finish_reason === 'length' })
   );
 
   const u = data?.usage ?? {};

package/src/core/stuck.js

@@ -0,0 +1,269 @@
+/**
+ * stuck.js — noticing when the model is going round in circles.
+ *
+ * Measured on a real build (a tip calculator, 84 model steps): six edits whose
+ * old_string and new_string were identical, the same build failing three times
+ * running on the same two type errors, and thirty reads of files whose current
+ * text was already in the conversation. Every one of those is a whole round
+ * trip, and a small model that has started repeating itself rarely stops on
+ * its own — the error it keeps getting says what is wrong, but nothing says
+ * "you have tried exactly this before".
+ *
+ * So each finished tool call becomes an event, and the recent events are
+ * checked for four patterns:
+ *
+ *   repeat     the same call, with the same arguments, failing the same way
+ *   identical  edits refused because old_string and new_string are the same
+ *   reread     reading a file whose unchanged text is still in view
+ *   build      a build failing with the same error text
+ *
+ * The first time a pattern reaches its threshold, the result that completed it
+ * carries a firm, specific note: what was repeated, the error, what to do
+ * instead. If the same pattern turns up again after that note, a nudge has not
+ * worked, and the caller hands the turn to another model.
+ *
+ * Everything here is pure: events in, verdicts out. The loop owns the side
+ * effects — appending the text and switching the model.
+ */
+
+import { createHash } from 'node:crypto';
+
+/** How many recent tool calls the patterns are looked for in. */
+export const WINDOW = 20;
+
+/** Occurrences inside the window that make a hit. */
+export const THRESHOLDS = { repeat: 3, identical: 2, reread: 1, build: 3 };
+
+const hash = (s) => createHash('sha1').update(String(s)).digest('hex').slice(0, 16);
+
+/** Argument values compared the way a person would: whitespace runs do not make a call different. */
+function stable(value) {
+  if (typeof value === 'string') return value.replace(/\s+/g, ' ').trim();
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, stable(value[k])]));
+  }
+  return value;
+}
+
+/** Name and arguments, reduced to one short string. */
+export function signature(call) {
+  return `${call?.name}:${hash(JSON.stringify(stable(call?.args ?? {})))}`;
+}
+
+/** Commands whose job is to build or type-check the project. */
+const BUILD = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?build\b|\bnext\s+build\b|\bvite\s+build\b|\btsc\b(?![^&|;]*--watch)/i;
+
+export const isBuild = (command) => BUILD.test(String(command ?? ''));
+
+const ERROR_LINE = /\berror\b|Error:|Module not found|Can't resolve|Type error|is not defined|Unterminated/i;
+const GENERIC = /^(?:>\s*)?Build error occurred|Failed to (?:type check|compile)|build worker exited|exiting the build|^exit code:|^What to do:|^- |build failed with \d+ errors?|^Import trace|^\d+ errors? found/i;
+
+/**
+ * The part of a build's output that names what is wrong, with the noise that
+ * changes from run to run — timings, digests — taken out, so two failures on
+ * the same errors compare equal.
+ */
+export function buildErrors(output) {
+  const clean = (l) => l
+    .replace(/\b\d+(?:\.\d+)?\s?m?s\b/g, '')
+    .replace(/digest: '[^']*'/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  const lines = String(output ?? '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const errors = [...new Set(lines.filter((l) => ERROR_LINE.test(l) && !GENERIC.test(l)).map(clean))];
+  return (errors.length ? errors.slice(0, 12) : lines.slice(-5).map(clean)).join('\n');
+}
+
+/**
+ * One finished call as the detector sees it.
+ *
+ * @param {object} call          { name, args }
+ * @param {object} outcome
+ * @param {object} [outcome.out]      a tool result ({ content, exitCode? })
+ * @param {object} [outcome.err]      a ToolFailure
+ * @param {string[]} [outcome.rereads] files this call re-read while their text was still in view
+ */
+export function eventFor(call, { out, err, rereads = [] } = {}) {
+  const args = call?.args ?? {};
+  const event = { tool: call?.name, sig: signature(call), failed: false, rereads: [...rereads] };
+  event.path = args.path ?? args.files?.[0]?.path ?? null;
+
+  if (err) {
+    event.failed = true;
+    event.kind = err.kind ?? 'error';
+    event.error = String(err.failed ?? err.message ?? err);
+    event.identical = event.kind === 'bad_args' && /old_string and new_string are identical/.test(event.error);
+    return event;
+  }
+
+  if (call?.name === 'run_command' && out && out.exitCode !== undefined && out.exitCode !== 0) {
+    const command = String(args.command ?? '');
+    event.failed = true;
+    event.kind = `exit ${out.exitCode}`;
+    event.command = command;
+    if (isBuild(command)) {
+      event.build = true;
+      event.error = buildErrors(out.content);
+    } else {
+      event.error = buildErrors(out.content).slice(0, 400);
+    }
+  }
+  return event;
+}
+
+/**
+ * Does the latest event complete a pattern? Returns the hit, or null.
+ *
+ * Only the newest event can complete one: every earlier event was checked when
+ * it arrived, so looking again would report the same hit twice.
+ */
+export function detect(events, { window = WINDOW, thresholds = THRESHOLDS } = {}) {
+  const recent = events.slice(-window);
+  const last = recent[recent.length - 1];
+  if (!last) return null;
+
+  if (last.identical) {
+    const count = recent.filter((e) => e.identical).length;
+    return count >= thresholds.identical
+      ? { pattern: 'identical', key: 'identical', count, tool: last.tool, path: last.path, error: last.error }
+      : null;
+  }
+
+  if (last.build) {
+    const count = recent.filter((e) => e.build && e.error === last.error).length;
+    return count >= thresholds.build
+      ? { pattern: 'build', key: `build:${hash(last.error)}`, count, command: last.command, error: last.error }
+      : null;
+  }
+
+  if (last.rereads?.length) {
+    const count = recent.filter((e) => e.rereads?.length).length;
+    return count >= thresholds.reread
+      ? { pattern: 'reread', key: 'reread', count, paths: last.rereads }
+      : null;
+  }
+
+  if (last.failed) {
+    const same = (e) => e.failed && !e.identical && !e.build && e.sig === last.sig && e.kind === last.kind && e.error === last.error;
+    const count = recent.filter(same).length;
+    return count >= thresholds.repeat
+      ? {
+          pattern: 'repeat', key: `repeat:${last.sig}:${last.kind}:${hash(last.error)}`, count,
+          tool: last.tool, kind: last.kind, error: last.error, path: last.path, command: last.command,
+        }
+      : null;
+  }
+
+  return null;
+}
+
+/** What each pattern is, as a few words for the user and for the model-switch note. */
+export function describeHit(hit) {
+  switch (hit.pattern) {
+    case 'identical': return 'making edits that change nothing';
+    case 'build': return 'rebuilding on the same errors';
+    case 'reread': return 're-reading files it already has';
+    default: return `repeating a failing ${hit.tool}`;
+  }
+}
+
+const nth = (n) => `${n}${n % 10 === 1 && n % 100 !== 11 ? 'st' : n % 10 === 2 && n % 100 !== 12 ? 'nd' : n % 10 === 3 && n % 100 !== 13 ? 'rd' : 'th'}`;
+
+/** What to do instead, by the kind of failure being repeated. */
+function adviceFor(hit) {
+  if (hit.tool === 'run_command') {
+    return 'Read the output above: it names the problem. Change the cause - the code, the ' +
+      'command, or its cwd - before running it again, or take a different route.';
+  }
+  switch (hit.kind) {
+    case 'no_match':
+      return `Read ${hit.path ?? 'the file'} once, copy old_string from that result exactly as it ` +
+        'stands, without the line-number gutter - or, if the change is large, rewrite the file with write_file.';
+    case 'ambiguous':
+      return 'Add the lines around it to old_string until it matches one place only.';
+    case 'not_found':
+      return 'That path does not exist. Find the right one with glob or list_dir first.';
+    case 'bad_args':
+      return 'Fix exactly the argument the error names before calling it again.';
+    default:
+      return 'Change what the error points at, or take a different route.';
+  }
+}
+
+/** The note appended to the result that completed a hit. Empty when the result already says it. */
+export function nudge(hit, { switched = false } = {}) {
+  const lead = switched
+    ? 'ucode has handed this turn to another model, because the last one kept ' +
+      `${describeHit(hit)} after being told to stop. `
+    : '';
+
+  switch (hit.pattern) {
+    case 'identical':
+      return `${lead}STOP - that is ${hit.count} edits in a row whose old_string and new_string are ` +
+        'identical. An edit like that changes nothing, so it is refused every time. If ' +
+        `${hit.path ?? 'the file'} already says what you want, that part is finished: move on to the ` +
+        'next thing. If it does not, put the text you actually want in new_string.';
+    case 'build':
+      return `${lead}STOP - \`${hit.command}\` has now failed ${hit.count} times with the same errors:\n` +
+        `${hit.error}\n` +
+        'Building again without changing the code those lines point at fails the same way, and each ' +
+        'build takes most of a minute. Fix every error listed - in one pass, with edit_files or ' +
+        'multi_edit - then build once.';
+    case 'reread':
+      // The result itself already says the text was not sent again and why;
+      // only a model switch has anything to add.
+      return switched
+        ? `${lead}Work from the file text already in this conversation instead of reading it again.`
+        : '';
+    default:
+      return `${lead}STOP - this is the ${nth(hit.count)} time ${hit.tool} has been called with exactly ` +
+        `these arguments, and it failed the same way every time (${hit.kind}: ${oneLine(hit.error)}). ` +
+        `Calling it again will fail again. ${adviceFor(hit)}`;
+  }
+}
+
+const oneLine = (s) => {
+  const line = String(s ?? '').split('\n')[0];
+  return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+};
+
+/**
+ * The detector with memory: which hits have already had their nudge.
+ *
+ * observe() returns null, a nudge, or a switch. A nudge is remembered for as
+ * long as it is inside the window; the same pattern turning up again while it
+ * is remembered means the nudge did not work. After a switch the slate is
+ * wiped, so the new model gets a nudge of its own before any further switch.
+ */
+export class StuckWatch {
+  constructor({ window = WINDOW, thresholds = THRESHOLDS } = {}) {
+    this.window = window;
+    this.thresholds = thresholds;
+    this.events = [];
+    this.seq = 0;
+    this.nudged = new Map(); // hit key -> seq of the event that was nudged
+  }
+
+  observe(event) {
+    this.seq++;
+    this.events.push({ ...event, seq: this.seq });
+    if (this.events.length > this.window * 2) this.events.splice(0, this.events.length - this.window);
+
+    const hit = detect(this.events, { window: this.window, thresholds: this.thresholds });
+    if (!hit) return null;
+
+    const at = this.nudged.get(hit.key);
+    if (at !== undefined && this.seq - at < this.window) {
+      this.reset();
+      return { action: 'switch', hit, text: nudge(hit, { switched: true }) };
+    }
+    this.nudged.set(hit.key, this.seq);
+    return { action: 'nudge', hit, text: nudge(hit) };
+  }
+
+  reset() {
+    this.events = [];
+    this.nudged.clear();
+  }
+}

package/src/core/tests.js

@@ -0,0 +1,86 @@
+/**
+ * tests.js — running the tests a change actually affects.
+ *
+ * A project's whole suite is too slow to run after every edit, and running
+ * nothing means the model learns a change was wrong from the user rather than
+ * from the code. Both vitest and jest can be asked which tests reach a given
+ * file and run only those, which is usually a second or two.
+ *
+ * Nothing is installed to make this work. If the project has no test runner,
+ * or has one that cannot answer "which tests cover this file", the checks
+ * stay as they were: this adds a signal where one is available, and is silent
+ * where it is not.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+const has = (deps, name) => Boolean(deps[name]);
+
+/** A file that is itself a test, and so is its own related test. */
+export const isTestFile = (rel) =>
+  /(?:^|[\\/])(?:__tests__|tests?)[\\/]/.test(rel) || /\.(?:test|spec)\.[cm]?[jt]sx?$/i.test(rel) ||
+  /(?:^|[\\/])test_[^\\/]+\.py$/i.test(rel) || /_test\.py$/i.test(rel);
+
+/**
+ * Which runner this project uses, read from its package.json. Only runners
+ * that can select tests by the file they cover are worth naming here.
+ */
+export async function testRunnerFor(dir) {
+  const raw = await fs.readFile(path.join(dir, 'package.json'), 'utf8').catch(() => null);
+  if (raw) {
+    let pkg;
+    try { pkg = JSON.parse(raw); } catch { pkg = null; }
+    if (pkg) {
+      const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+      const script = String(pkg.scripts?.test ?? '');
+      if (has(deps, 'vitest') || /\bvitest\b/.test(script)) return 'vitest';
+      if (has(deps, 'jest') || /\bjest\b/.test(script)) return 'jest';
+    }
+  }
+  const py = await Promise.all(
+    ['pytest.ini', 'pyproject.toml', 'setup.cfg', 'tox.ini'].map((f) =>
+      fs.access(path.join(dir, f)).then(() => true, () => false))
+  );
+  return py.some(Boolean) ? 'pytest' : null;
+}
+
+/** Quote a path for a shell, and use forward slashes so Windows agrees. */
+const arg = (p) => `"${p.replace(/\\/g, '/')}"`;
+
+/**
+ * The command that runs only the tests reaching these files, or null when
+ * this runner cannot narrow it down.
+ *
+ * pytest has no "which tests cover this file", so it gets the test files from
+ * among those changed — enough to catch a test edited into failing, and
+ * honest about being less than the others.
+ */
+export function relatedCommand(runner, files) {
+  const list = files.filter(Boolean);
+  if (!list.length) return null;
+
+  if (runner === 'vitest') {
+    return `npx --no-install vitest related --run --passWithNoTests ${list.map(arg).join(' ')}`;
+  }
+  if (runner === 'jest') {
+    return `npx --no-install jest --findRelatedTests --passWithNoTests --silent ${list.map(arg).join(' ')}`;
+  }
+  if (runner === 'pytest') {
+    const tests = list.filter(isTestFile);
+    if (!tests.length) return null;
+    return `python -m pytest -q ${tests.map(arg).join(' ')}`;
+  }
+  return null;
+}
+
+/** The failing part of a test run, kept to what a model can act on. */
+export function summariseFailures(runner, output, limit = 40) {
+  const lines = String(output ?? '').split('\n');
+  const interesting = lines.filter((l) =>
+    /^\s*(?:✗|×|✕|FAIL|●|E\s|_{3,}|AssertionError|Expected|Received|at\s)/.test(l) ||
+    /\b\d+ failed\b/i.test(l) || /^FAILED /.test(l)
+  );
+  const kept = (interesting.length ? interesting : lines.filter((l) => l.trim())).slice(0, limit);
+  return kept.join('\n');
+}

package/src/tools/blocks.js

@@ -0,0 +1,117 @@
+/**
+ * blocks.js — pieces of an app that are already right.
+ *
+ * A model writing a table from scratch writes a passable one: no empty state,
+ * no sort, numbers left-aligned, and nothing that works on a phone. It is not
+ * that it cannot do better, it is that doing better costs steps and attention
+ * that belong to the thing being built.
+ *
+ * These are the parts every app needs, written once and carefully: a shell, a
+ * page header, an empty state, a table, a row of stats. They are copied into
+ * the app as ordinary source files for the model to edit, not imported from a
+ * library it cannot change.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolFailure } from '../core/failure.js';
+import { resolveIn, guard, result } from './shared.js';
+
+const BLOCKS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', 'blocks');
+
+/** What each block is for, and what it needs to be handed. */
+export const CATALOGUE = {
+  'app-shell': {
+    what: 'The frame every page sits in: sidebar on desktop, the same nav behind a button on a phone.',
+    exports: 'AppShell',
+    use: '<AppShell title="Stride" nav={[{ href: "/", label: "Home" }]} current="/">…</AppShell>',
+  },
+  'page-header': {
+    what: 'The top of a page: title, a line about it, and the actions available here.',
+    exports: 'PageHeader',
+    use: '<PageHeader title="Invoices" description="Everything you have billed." actions={<Button>New</Button>} />',
+  },
+  'empty-state': {
+    what: 'What a list looks like before anything is in it, with the one action that fills it.',
+    exports: 'EmptyState',
+    use: '<EmptyState title="No invoices yet" description="They will appear here." actionLabel="New invoice" />',
+  },
+  'data-table': {
+    what: 'A table you can search and sort, with an empty state and numbers aligned right.',
+    exports: 'DataTable, Column',
+    use: '<DataTable rows={rows} columns={[{ key: "name", header: "Name" }, { key: "total", header: "Total", numeric: true }]} />',
+  },
+  'stat-cards': {
+    what: 'The row of numbers at the top of a dashboard, each with what it is measured against.',
+    exports: 'StatCards, Stat',
+    use: '<StatCards stats={[{ label: "Revenue", value: "£12,400", change: 8 }]} />',
+  },
+};
+
+export const BLOCK_NAMES = Object.keys(CATALOGUE);
+
+const listing = () =>
+  BLOCK_NAMES.map((name) => `  ${name} — ${CATALOGUE[name].what}`).join('\n');
+
+/**
+ * Copy a block into an app, or list what there is. The file lands in
+ * src/components/blocks/ and is the app's to edit from then on.
+ */
+export async function addBlock({ name, folder = '.' }) {
+  const wanted = String(name ?? '').trim();
+
+  if (!wanted) {
+    return result(
+      `Blocks you can add, with add_block({ name, folder }):\n\n${listing()}\n\n` +
+      'Each one is copied into the app as a source file you can then edit.',
+      `${BLOCK_NAMES.length} blocks`
+    );
+  }
+
+  if (!CATALOGUE[wanted]) {
+    throw new ToolFailure({
+      kind: 'no_such_block',
+      attempted: `adding the "${wanted}" block`,
+      failed: `There is no block called "${wanted}".`,
+      fix: `Pick one of: ${BLOCK_NAMES.join(', ')}. Call add_block with no name to see what each is for.`,
+    });
+  }
+
+  const target = resolveIn(folder || '.', 'add_block', 'folder');
+  await guard(target, `add the ${wanted} block to ${target.abs}`);
+
+  const source = await fs.readFile(path.join(BLOCKS, `${wanted}.tsx`), 'utf8').catch(() => null);
+  if (source === null) {
+    throw new ToolFailure({
+      kind: 'block_missing',
+      attempted: `adding the "${wanted}" block`,
+      failed: `The ${wanted} block is listed but its file is not installed.`,
+      fix: 'Write the component by hand, or reinstall ucode.',
+    });
+  }
+
+  const rel = path.join('src', 'components', 'blocks', `${wanted}.tsx`);
+  const dest = path.join(target.abs, rel);
+
+  if (await fs.stat(dest).catch(() => null)) {
+    return result(
+      `${rel} is already in ${target.show}; it has been left as it is so your edits survive.\n` +
+      `Import: import { ${CATALOGUE[wanted].exports.split(',')[0].trim()} } from "@/components/blocks/${wanted}";`,
+      'already there'
+    );
+  }
+
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.writeFile(dest, source, 'utf8');
+
+  const first = CATALOGUE[wanted].exports.split(',')[0].trim();
+  return result(
+    `Added ${rel} to ${target.show}.\n\n` +
+    `import { ${CATALOGUE[wanted].exports} } from "@/components/blocks/${wanted}";\n\n` +
+    `${CATALOGUE[wanted].use}\n\n` +
+    `It is an ordinary file now — edit it to suit the app rather than working around it. ` +
+    `It uses the shadcn components already in the starter, so nothing needs installing.`,
+    `${first} added`
+  );
+}