ucode-agent 1.4.0 → 1.6.0

package/src/tools/scaffold.js

@@ -0,0 +1,190 @@
+/**
+ * scaffold.js — starting an app from a starter that is known to work.
+ *
+ * Setting up a Next.js + shadcn project from nothing is four minutes of
+ * create-next-app and shadcn CLI runs — measured at 116s and 130s — plus a
+ * dozen model round trips to drive them and then theme the result. Every app
+ * starts from the same place anyway, so ucode ships that place: a project
+ * that has already been built and type-checked, copied in one step, with its
+ * install starting in the background while the model writes the first
+ * component.
+ */
+
+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';
+import { packageJsonWritten } from './shell.js';
+
+const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+
+/** npm silently drops these two names from published packages, so they ship renamed. */
+const RENAME = { _gitignore: '.gitignore', '_package-lock.json': 'package-lock.json' };
+
+/** Files the placeholders are filled into. Everything else is copied byte for byte. */
+const TEXT = /\.(?:json|md|mjs|css|tsx?)$/i;
+
+export const TEMPLATE_NAMES = ['next-shadcn'];
+
+function slug(name) {
+  return String(name).toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'app';
+}
+
+/** Text that is safe inside a JS string and a JSON string. */
+const plain = (s) => String(s ?? '').replace(/["'`\\<>]/g, '').replace(/\s+/g, ' ').trim();
+
+async function copyTree(from, to, fill) {
+  await fs.mkdir(to, { recursive: true });
+  const copied = [];
+  for (const entry of await fs.readdir(from, { withFileTypes: true })) {
+    const name = RENAME[entry.name] ?? entry.name;
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, name);
+    if (entry.isDirectory()) {
+      copied.push(...(await copyTree(src, dest, fill)).map((f) => `${name}/${f}`));
+    } else if (TEXT.test(entry.name) || entry.name in RENAME) {
+      let text = await fs.readFile(src, 'utf8');
+      for (const [token, value] of Object.entries(fill)) text = text.split(token).join(value);
+      await fs.writeFile(dest, text, 'utf8');
+      copied.push(name);
+    } else {
+      await fs.copyFile(src, dest);
+      copied.push(name);
+    }
+  }
+  return copied;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.folder       new, empty folder for the app
+ * @param {string} o.name         display name, e.g. "Stride"
+ * @param {string} [o.description]
+ * @param {string} [o.template]
+ * @param {boolean} [o.install]   start the background install (tests turn it off)
+ */
+/**
+ * Give the new app its look: one of the hand-picked presets in the starter's
+ * presets/ folder — a full light and dark palette and a font — written into
+ * globals.css and layout.tsx. Apps stop looking like the same default blue.
+ * Returns the preset used, or null when the starter has none.
+ */
+export async function applyDesign(appDir, design) {
+  const dir = path.join(appDir, 'presets');
+  const names = (await fs.readdir(dir).catch(() => [])).filter((f) => f.endsWith('.json'));
+  if (!names.length) return null;
+  const presets = await Promise.all(names.map(async (f) => JSON.parse(await fs.readFile(path.join(dir, f), 'utf8'))));
+  await fs.rm(dir, { recursive: true, force: true }); // the app needs the result, not the catalogue
+  const preset = presets.find((p) => p.name === design) ?? presets.find((p) => p.default) ?? presets[0];
+
+  const cssFile = path.join(appDir, 'src', 'app', 'globals.css');
+  let css = await fs.readFile(cssFile, 'utf8').catch(() => null);
+  if (css !== null) {
+    const retint = (selector, tokens) => {
+      const block = new RegExp(`(${selector}\\s*\\{)([\\s\\S]*?)(\\n\\})`);
+      css = css.replace(block, (all, open, body, close) => {
+        const seen = new Set();
+        let next = body.replace(/(\n\s*)--([\w-]+):\s*[^;]+;/g, (line, lead, key) => {
+          if (!(key in tokens)) return line;
+          seen.add(key);
+          return `${lead}--${key}: ${tokens[key]};`;
+        });
+        for (const [key, value] of Object.entries(tokens)) if (!seen.has(key)) next += `\n  --${key}: ${value};`;
+        return open + next + close;
+      });
+    };
+    retint(':root', { radius: preset.radius, ...preset.light });
+    retint('\\.dark', preset.dark);
+    await fs.writeFile(cssFile, css);
+  }
+
+  const sans = preset.fonts?.sans;
+  const layoutFile = path.join(appDir, 'src', 'app', 'layout.tsx');
+  if (sans && sans !== 'Geist') {
+    const id = sans.replace(/\s+/g, '_');
+    const layout = await fs.readFile(layoutFile, 'utf8').catch(() => null);
+    if (layout !== null) {
+      await fs.writeFile(layoutFile, layout
+        .replace('import { Geist, Geist_Mono } from "next/font/google";', `import { ${id}, Geist_Mono } from "next/font/google";`)
+        .replace('const sans = Geist({', `const sans = ${id}({`));
+    }
+  }
+
+  const guide = path.join(appDir, 'TEMPLATE.md');
+  const text = await fs.readFile(guide, 'utf8').catch(() => null);
+  if (text !== null) {
+    await fs.writeFile(guide, `${text.trimEnd()}\n\n## Design\n\nThis app uses the **${preset.name}** preset — ` +
+      `${preset.summary}. Font: ${sans ?? 'Geist'}. The palette lives in globals.css (light and dark): ` +
+      'build with the tokens (bg-primary, text-muted-foreground, border, ...) rather than raw colours, ' +
+      'so every screen stays in one look.\n');
+  }
+  return preset;
+}
+
+export async function createApp({ folder, name, description, template = 'next-shadcn', design, install = true }) {
+  if (!TEMPLATE_NAMES.includes(template)) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'creating an app',
+      failed: `There is no starter called "${template}".`,
+      fix: `Use one of: ${TEMPLATE_NAMES.join(', ')}.`,
+    });
+  }
+
+  const target = resolveIn(folder, 'create_app', 'folder');
+  const attempted = `creating an app in ${target.show}`;
+  if (target.show === '.') {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted,
+      failed: 'The app needs its own folder, not the project root.',
+      fix: 'Pass a new folder name, e.g. "stride".',
+    });
+  }
+  await guard(target, `create an app in ${target.abs}`);
+
+  let existing = [];
+  try {
+    existing = await fs.readdir(target.abs);
+  } catch {
+    existing = [];
+  }
+  if (existing.length) {
+    throw new ToolFailure({
+      kind: 'not_empty',
+      attempted,
+      failed: `${target.show} already has ${existing.length} item(s) in it: ${existing.slice(0, 5).join(', ')}.`,
+      fix: 'Pick a new folder name. If this folder is the app from an earlier attempt, work in it instead of creating it again.',
+    });
+  }
+
+  const display = plain(name) || path.basename(target.abs);
+  const fill = {
+    __APP_NAME__: display,
+    __APP_SLUG__: slug(display),
+    __APP_DESCRIPTION__: plain(description) || display,
+  };
+
+  const files = await copyTree(path.join(TEMPLATES, template), target.abs, fill);
+  await fs.mkdir(path.join(target.abs, 'public'), { recursive: true });
+  const look = await applyDesign(target.abs, design);
+
+  if (install) {
+    const pkg = path.join(target.abs, 'package.json');
+    packageJsonWritten(pkg, await fs.readFile(pkg, 'utf8'));
+  }
+
+  const guide = await fs.readFile(path.join(target.abs, 'TEMPLATE.md'), 'utf8').catch(() => '');
+
+  return result(
+    `Created ${target.show} from the ${template} starter — ${files.length} files, already known to build.\n` +
+      (look ? `Design: the ${look.name} preset (${look.summary}), font ${look.fonts?.sans ?? 'Geist'}.\n` : '') +
+      (install
+        ? `Its packages are installing in the background right now. Keep writing: any command you run in ` +
+          `${target.show} waits for that install first, so there is no need to run npm install.\n`
+        : '') +
+      `Run this app's commands with cwd: "${target.show}" (npm run build, npm run dev).\n\n${guide}`,
+    `${files.length} files${install ? ' · installing in the background' : ''}`
+  );
+}

package/src/tools/shell.js

@@ -175,6 +175,14 @@ function stopHint(pid) {
  * is ready, it exits, or the wait runs out. Whichever comes first is reported
  * with the URL it is actually listening on.
  */
+/** Dev servers that said they were ready, newest last — for opening the app when a turn ends. */
+const readyServers = [];
+
+/** Servers that became ready at or after `since` (epoch ms). */
+export function serversReadySince(since = 0) {
+  return readyServers.filter((s) => s.at >= since);
+}
+
 function startServer(command, workdir, { env } = {}) {
   return new Promise((resolve, reject) => {
     let log;
@@ -292,6 +300,7 @@ function startServer(command, workdir, { env } = {}) {
       if ((ready && url) || graceOver || (ready && Date.now() - started > 1500)) {
         finish(() => {
           const where = url ? tidyUrl(url) : null;
+          if (where) readyServers.push({ url: where, pid: child.pid, at: Date.now() });
           return result(
             describeRun([
               `Running in the background as PID ${child.pid}, ready after ${seconds}s.`,
@@ -460,6 +469,78 @@ async function awaitInstall(command, workdir, onOutput) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// What a failed build is really asking for
+// ---------------------------------------------------------------------------
+
+/**
+ * Plain next steps for the build failures that send a model down a hole.
+ *
+ * Measured: a missing shadcn component failed the build, and instead of
+ * adding it the model spent a dozen steps listing node_modules, then deleted
+ * the app and started over. The error names exactly what is missing; this
+ * turns that into the one command that fixes it.
+ */
+export function buildHints(output, dir = null) {
+  const hints = [];
+  const seen = new Set();
+  const add = (key, text) => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    hints.push(text);
+  };
+
+  const UI = /(?:Can't resolve|Cannot find module) '@\/components\/ui\/([\w-]+)'/g;
+  for (const m of output.matchAll(UI)) {
+    add(`ui:${m[1]}`, `The shadcn component "${m[1]}" is not in this project. Add it with ` +
+      `\`npx shadcn@latest add ${m[1]} -y\` (cwd: the app folder), then build again. ` +
+      'Do not look inside node_modules.');
+  }
+
+  const PKG = /(?:Can't resolve|Cannot find module) '((?:@[\w.-]+\/)?[\w.-]+)(\/[^']*)?'/g;
+  for (const m of output.matchAll(PKG)) {
+    const [, pkg, subpath] = m;
+    if (pkg.startsWith('.')) continue;
+    if (subpath && dir && installed(dir, pkg)) {
+      // Installed, but that path inside it does not exist: an import copied
+      // from an older version. Installing it again changes nothing.
+      add(`sub:${pkg}${subpath}`, `"${pkg}" is installed, but "${pkg}${subpath}" does not exist — ` +
+        `that path is from an older version. Import from "${pkg}" itself` +
+        (pkg === 'next-themes'
+          ? '; for the provider\'s props use `React.ComponentProps<typeof NextThemesProvider>`.'
+          : ', or check its package.json "exports" for the right path.') +
+        ' Do not reinstall it.');
+      continue;
+    }
+    add(`pkg:${pkg}`, `The package "${pkg}" is not installed. Install it with ` +
+      `\`npm install ${pkg}\` (cwd: the app folder), then build again.`);
+  }
+
+  if (/Parsing ecmascript source code failed|Expression expected|Unexpected token/.test(output)) {
+    add('syntax', 'A file does not parse. Open the file and line the error names, fix that ' +
+      'syntax, then build again.');
+  }
+
+  return hints;
+}
+
+/** Is this package installed for the project at dir (or a folder above it)? */
+function installed(dir, pkg) {
+  for (let at = path.resolve(dir); ; at = path.dirname(at)) {
+    try {
+      statSync(path.join(at, 'node_modules', pkg, 'package.json'));
+      return true;
+    } catch { /* not here */ }
+    if (path.dirname(at) === at) return false;
+  }
+}
+
+/** The folder a command really runs in: its cwd, moved by a leading `cd x &&`. */
+function effectiveDir(command, workdir) {
+  const cd = /^\s*cd\s+(?:\/d\s+)?("?)([^"&|;]+?)\1\s*(?:&&|;)\s*/i.exec(command);
+  return cd ? path.resolve(workdir.abs, cd[2].trim()) : path.resolve(workdir.abs);
+}
+
 // ---------------------------------------------------------------------------
 // run_command
 // ---------------------------------------------------------------------------
@@ -474,6 +555,11 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
     });
   }
 
+  // `sleep 3 && curl localhost:3000` after the server already reported ready
+  // is a wait for nothing. Measured on a real build; the sleep is dropped.
+  const napping = /^\s*(?:sleep\s+\d+(?:\.\d+)?|timeout\s+\/t\s+\d+(?:\s+\/nobreak)?)\s*(?:&&|;)\s*/i.exec(command);
+  if (napping && readyServers.length) command = command.slice(napping[0].length);
+
   if (KILLS_EVERYTHING.test(command)) {
     throw new ToolFailure({
       kind: 'suicidal_command',
@@ -618,8 +704,10 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
       }
 
       const count = captured.trim() ? captured.trim().split(/\r?\n/).length : 0;
+      const hints = code !== 0 ? buildHints(captured, effectiveDir(command, workdir)) : [];
+      const advice = hints.length ? `\n\nWhat to do:\n${hints.map((h) => `- ${h}`).join('\n')}` : '';
       const out = result(
-        `exit code: ${code}\n\n${body}`,
+        `exit code: ${code}\n\n${body}${advice}`,
         `exit ${code} · ${count} line${count === 1 ? '' : 's'}`
       );
       out.exitCode = code;

package/src/ui/activity.js

@@ -0,0 +1,203 @@
+/**
+ * activity.js — what the status row shows while ucode is working.
+ *
+ * A long turn is minutes of the agent doing things the user did not type and
+ * cannot see coming. The status row is the one place that says it is still
+ * going, so it has to look alive at a glance without asking to be read: a
+ * spinner that turns, a soft band of light passing across the label, the
+ * step count ticking up, and the time the turn has taken so far.
+ *
+ * Everything here is a pure function of the text and the clock, so it can be
+ * tested without a terminal and painted at any frame rate.
+ */
+
+import chalk, { Chalk } from 'chalk';
+import { dim, sky, theme, clip, SPINNER } from './theme.js';
+
+/** One painter per colour level, so a test can ask for truecolour on a pipe. */
+const painters = new Map();
+const painter = (level) => {
+  if (!painters.has(level)) painters.set(level, new Chalk({ level }));
+  return painters.get(level);
+};
+
+/** One frame every 85ms — just under twelve a second, smooth without being busy. */
+export const FRAME_MS = 85;
+
+/**
+ * A duration as a person says it: 0.4s, 14s, 2m 04s, 1h 07m.
+ *
+ * Seconds are zero-padded once there are minutes, so the text after the timer
+ * does not shift sideways every time the seconds roll from 9 to 10.
+ */
+export function formatDuration(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value < 1000) return `${(value / 1000).toFixed(1)}s`;
+  const total = Math.floor(value / 1000);
+  if (total < 60) return `${total}s`;
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) return `${minutes}m ${String(total % 60).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+// ---------------------------------------------------------------------------
+// The shimmer
+// ---------------------------------------------------------------------------
+
+/**
+ * The two ends of the shimmer, both blue. The resting colour is muted enough
+ * to read as secondary text beside the model name; the peak is almost white,
+ * so the band reads as light passing over the words rather than a second
+ * colour arriving.
+ */
+const REST_RGB = [0x7a, 0x96, 0xc8];
+const PEAK_RGB = [0xe6, 0xf0, 0xff];
+
+/** Half the width of the band of light, in characters. */
+const BAND = 3;
+
+/** How fast the band travels, in characters a second. */
+const SPEED = 24;
+
+/** Characters' worth of dark between one pass and the next. */
+const PAUSE = 18;
+
+/** Brightness steps. Neighbouring letters that land on the same step share one escape code. */
+const STEPS = 8;
+
+const mix = (a, b, k) => a.map((v, i) => Math.round(v + (b[i] - v) * k));
+
+/**
+ * The text with a soft band of light passing across it, left to right, then a
+ * short rest, then again.
+ *
+ * `t` is milliseconds on any clock; the band's position is a function of it,
+ * so a slow frame skips ahead rather than slowing the sweep down.
+ *
+ * Needs 256 colours or more. With 16 there are no in-between blues to fade
+ * through, and a band that jumps between two colours reads as flicker rather
+ * than light — so below that the label is simply dim, and never moves.
+ */
+export function shimmer(text, t, { level = chalk.level } = {}) {
+  const s = String(text ?? '');
+  if (!s || level < 2) return dim(s);
+
+  const cycle = s.length + BAND * 2 + PAUSE;
+  const centre = ((Math.max(0, t) / 1000) * SPEED) % cycle - BAND;
+
+  let out = '';
+  let run = '';
+  let runStep = -1;
+  const flush = () => {
+    if (!run) return;
+    const [r, g, b] = mix(REST_RGB, PEAK_RGB, runStep / STEPS);
+    out += painter(level).rgb(r, g, b)(run);
+    run = '';
+  };
+
+  for (let i = 0; i < s.length; i++) {
+    const distance = Math.abs(i - centre);
+    // A cosine falloff: brightest at the centre, fading smoothly to nothing
+    // at the edge of the band, so the light has no hard edge to it.
+    const k = distance < BAND ? (Math.cos((Math.PI * distance) / BAND) + 1) / 2 : 0;
+    const step = Math.round(k * STEPS);
+    if (step !== runStep) { flush(); runStep = step; }
+    run += s[i];
+  }
+  flush();
+  return out;
+}
+
+/**
+ * The spinner glyph for a frame, breathing slowly between two blues.
+ *
+ * The pulse is slow — a little over a second a breath — so it reads as the
+ * glyph being alive rather than as a blink.
+ */
+export function spinnerGlyph(frame, t, { level = chalk.level } = {}) {
+  const glyph = SPINNER[((frame % SPINNER.length) + SPINNER.length) % SPINNER.length];
+  if (level < 2) return theme.blue(glyph);
+  const k = (Math.sin((Math.max(0, t) / 1300) * Math.PI * 2) + 1) / 2;
+  const [r, g, b] = mix([0x4d, 0x8d, 0xff], [0x9f, 0xc6, 0xff], k);
+  return painter(level).rgb(r, g, b)(glyph);
+}
+
+// ---------------------------------------------------------------------------
+// Fitting it into the room there is
+// ---------------------------------------------------------------------------
+
+/** Shorter than this, a label is a stub that says nothing, so it goes entirely. */
+const MIN_LABEL = 10;
+
+/**
+ * The middle of the status row, fitted to `room` columns.
+ *
+ * Parts, in the order they are given up when the terminal is too narrow for
+ * all of them:
+ *
+ *   1. the "esc to stop" hint     — useful once, known after that
+ *   2. the end of the label        — clipped with an ellipsis, down to a stub
+ *   3. the step count
+ *   4. the label itself
+ *   5. the elapsed time
+ *
+ * The spinner is the last thing standing: even with a single column left the
+ * row still shows that something is happening.
+ *
+ * `meta` is a list of { text, paint, keep } — keep marks the one that survives
+ * the longest (the timer). `paint` colours the label, which is where the
+ * shimmer comes in.
+ */
+export function fitActivity({ glyph, label = '', meta = [], hint = '', paint = dim }, room) {
+  if (room < 1) return '';
+  const items = meta.filter((m) => m && m.text);
+  const kept = items.filter((m) => m.keep);
+  const text = String(label ?? '');
+
+  const width = (labelLen, list, withHint) =>
+    1 +
+    (labelLen ? 1 + labelLen : 0) +
+    (list.length ? (labelLen ? 3 : 1) + list.map((m) => m.text).join(' · ').length : 0) +
+    (withHint && hint ? 2 + hint.length : 0);
+
+  const build = (labelText, list, withHint) => {
+    let out = glyph;
+    if (labelText) out += ` ${paint(labelText)}`;
+    if (list.length) {
+      out += labelText ? dim(' · ') : ' ';
+      out += list.map((m) => (m.paint ?? dim)(m.text)).join(dim(' · '));
+    }
+    if (withHint && hint) out += `  ${dim(hint)}`;
+    return out;
+  };
+
+  if (text) {
+    if (width(text.length, items, true) <= room) return build(text, items, true);
+    if (width(text.length, items, false) <= room) return build(text, items, false);
+    for (const list of [items, kept]) {
+      const labelRoom = room - width(0, list, false) - 1 - (list.length ? 2 : 0);
+      if (labelRoom >= MIN_LABEL) return build(clip(text, labelRoom), list, false);
+    }
+  }
+  for (const list of [items, kept, []]) {
+    if (width(0, list, false) <= room) return build('', list, false);
+  }
+  return glyph;
+}
+
+/**
+ * The line a finished turn leaves in the transcript: "✓ Done in 6m 12s · 25 steps".
+ *
+ * Green for the tick, because green means done and nothing else in this
+ * theme; the rest dim, because it is a footnote to the answer above it rather
+ * than something to read first.
+ */
+export function doneLine(ms, steps) {
+  const count = steps > 0 ? ` · ${steps} step${steps === 1 ? '' : 's'}` : '';
+  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}${count}`)}`;
+}
+
+/** The step count, brighter for a moment right after it goes up. */
+export function stepPaint(justMoved) {
+  return justMoved ? sky : dim;
+}

package/src/ui/plain.js

@@ -15,6 +15,7 @@ import {
   theme, blue, sky, dim, boxTop, boxBottom, boxRow,
   BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine,
 } from './theme.js';
+import { formatDuration, doneLine } from './activity.js';
 import { renderer, render } from './markdown.js';
 
 const COMMANDS = [
@@ -227,9 +228,11 @@ export class Plain {
   }
 
   paintSpinner() {
-    const secs = Math.round((Date.now() - this.since) / 1000);
-    const line = `  ${blue(SPINNER[this.frame])} ${dim(this.spinnerText)}` +
-      (secs >= 2 ? dim(` ${secs}s`) : '');
+    const since = this.turn?.start ?? this.since;
+    const secs = Math.round((Date.now() - since) / 1000);
+    const meta = [this.turn?.steps ? `step ${this.turn.steps}` : '', secs >= 2 ? formatDuration(secs * 1000) : '']
+      .filter(Boolean).join(' · ');
+    const line = `  ${blue(SPINNER[this.frame])} ${dim(this.spinnerText)}` + (meta ? dim(` · ${meta}`) : '');
     this.output.write(`\r\x1b[K${padVis(line, this.width() - 1)}`);
   }
 
@@ -246,6 +249,22 @@ export class Plain {
     this.output.write('\r\x1b[K');
   }
 
+  // -- the turn in flight ----------------------------------------------------
+
+  turnStart() {
+    this.turn = { start: Date.now(), steps: 0 };
+  }
+
+  step() {
+    if (this.turn) this.turn.steps++;
+  }
+
+  turnEnd({ ok = true } = {}) {
+    const t = this.turn;
+    this.turn = null;
+    if (t && ok && Date.now() - t.start >= 2000) this.write(`  ${doneLine(Date.now() - t.start, t.steps)}`);
+  }
+
   // -- input ---------------------------------------------------------------
 
   nextLine() {