ucode-agent 1.3.0 → 1.5.0

package/src/core/updater.js

@@ -0,0 +1,95 @@
+/**
+ * updater.js — staying current without anyone running npm by hand.
+ *
+ * On every launch ucode asks the registry, in the background, whether a newer
+ * version exists. If one does, it installs it globally, detached, while you
+ * work. The version you are running carries on untouched; the next launch is
+ * the new one. Nothing about starting ucode waits on any of this.
+ *
+ * It stays out of the way in three cases: a development checkout (updating
+ * would overwrite the `npm link` that points at your working copy), when
+ * UCODE_NO_UPDATE is set, and when another ucode is already updating.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from './version.js';
+
+const PACKAGE = 'ucode-agent';
+const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const HOME = path.join(os.homedir(), '.ucode');
+const LOCK = path.join(HOME, 'update.lock');
+const LOG = path.join(HOME, 'update.log');
+const LOCK_TTL = 10 * 60_000;
+
+/** "1.10.0" > "1.9.3" — numeric, part by part. */
+export function newer(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  }
+  return false;
+}
+
+function isDevCheckout() {
+  return existsSync(path.join(PACKAGE_ROOT, '.git'));
+}
+
+async function latestVersion() {
+  const res = await fetch(`https://registry.npmjs.org/${PACKAGE}/latest`, {
+    signal: AbortSignal.timeout(5_000),
+    headers: { accept: 'application/json' },
+  });
+  if (!res.ok) return null;
+  return (await res.json())?.version ?? null;
+}
+
+async function takeLock() {
+  try {
+    const stat = await fs.stat(LOCK);
+    if (Date.now() - stat.mtimeMs < LOCK_TTL) return false;   // someone else is on it
+  } catch { /* no lock — good */ }
+  await fs.mkdir(HOME, { recursive: true });
+  await fs.writeFile(LOCK, String(process.pid));
+  return true;
+}
+
+/**
+ * Check, and install if there is something newer.
+ *
+ * @param {object} o
+ * @param {(v: string) => void} [o.onUpdated]  called when the install finishes
+ */
+export async function autoUpdate({ onUpdated } = {}) {
+  try {
+    if (process.env.UCODE_NO_UPDATE || isDevCheckout() || !VERSION) return;
+    const latest = await latestVersion();
+    if (!latest || !newer(latest, VERSION)) return;
+    if (!(await takeLock())) return;
+
+    const log = await fs.open(LOG, 'w');
+    const child = spawn(`npm install -g ${PACKAGE}@${latest} --no-audit --no-fund`, {
+      shell: true,
+      detached: true,
+      windowsHide: true,
+      stdio: ['ignore', log.fd, log.fd],
+    });
+    await log.close();
+    child.unref();
+
+    child.on('exit', async (code) => {
+      await fs.rm(LOCK, { force: true }).catch(() => {});
+      if (code === 0) onUpdated?.(latest);
+    });
+    child.on('error', async () => {
+      await fs.rm(LOCK, { force: true }).catch(() => {});
+    });
+  } catch {
+    // An update check must never be the reason ucode misbehaves. Offline,
+    // registry down, no permission to install globally: all silently skipped.
+  }
+}

package/src/tools/browser.js

@@ -0,0 +1,258 @@
+/**
+ * browser.js — looking at the app the way a person would.
+ *
+ * A build that passes and a page that works are different claims. This opens
+ * the running app in a real browser at a phone width and a desktop width, and
+ * reports what a person would run into: errors in the console, requests that
+ * failed, a layout that spills off the side of a phone, broken images,
+ * controls with no name. It saves a screenshot of each, and has the one model
+ * in the set that can see — Nemotron Nano Omni — review them as a designer
+ * would. The model building the app then has something concrete to fix.
+ *
+ * It drives the browser already on the machine (Edge or Chrome) through
+ * playwright-core, so there is no separate 150 MB browser download.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ToolFailure } from '../core/failure.js';
+import { ask } from '../core/provider.js';
+import { getRoot, result } from './shared.js';
+
+const VISION_MODEL = 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free';
+const WIDTHS = [
+  { name: 'phone', width: 375, height: 812 },
+  { name: 'desktop', width: 1440, height: 900 },
+];
+const LOCAL = /^https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)/i;
+
+let browserPromise = null;
+
+/**
+ * One browser for the whole session, started on first use. The installed
+ * Edge or Chrome is tried first; Playwright's own Chromium only if it happens
+ * to be installed.
+ */
+async function browser() {
+  if (browserPromise) return browserPromise;
+  browserPromise = (async () => {
+    let chromium;
+    try {
+      ({ chromium } = await import('playwright-core'));
+    } catch (err) {
+      throw new ToolFailure({
+        kind: 'no_playwright',
+        attempted: 'starting a browser',
+        failed: `playwright-core could not be loaded: ${err.message}`,
+        fix: 'Reinstall ucode (npm install -g ucode-agent). Carry on without looking at the app, and say so.',
+      });
+    }
+    const tried = [];
+    for (const channel of ['msedge', 'chrome', undefined]) {
+      try {
+        return await chromium.launch({ channel, headless: true });
+      } catch (err) {
+        tried.push(`${channel ?? 'bundled chromium'}: ${String(err.message).split('\n')[0]}`);
+      }
+    }
+    throw new ToolFailure({
+      kind: 'no_browser',
+      attempted: 'starting a browser',
+      failed: `No browser could be started. Tried ${tried.join('; ')}.`,
+      fix: 'Install Google Chrome or Microsoft Edge. Carry on without looking at the app, and say so.',
+    });
+  })();
+  browserPromise.catch(() => { browserPromise = null; });
+  return browserPromise;
+}
+
+/** Close the shared browser, if one was started. Called when ucode exits. */
+export async function closeBrowser() {
+  if (!browserPromise) return;
+  try { await (await browserPromise).close(); } catch { /* already gone */ }
+  browserPromise = null;
+}
+
+/** Layout and accessibility checks run inside the page. */
+function inspect() {
+  const vw = window.innerWidth;
+  const describeEl = (el) => {
+    const id = el.id ? `#${el.id}` : '';
+    const cls = typeof el.className === 'string' && el.className.trim()
+      ? `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}` : '';
+    const text = (el.innerText || el.getAttribute('aria-label') || '').trim().replace(/\s+/g, ' ').slice(0, 40);
+    return `<${el.tagName.toLowerCase()}${id}${cls}>${text ? ` "${text}"` : ''}`;
+  };
+
+  const overflow = document.documentElement.scrollWidth - vw;
+  const wide = [];
+  if (overflow > 1) {
+    for (const el of document.querySelectorAll('body *')) {
+      const r = el.getBoundingClientRect();
+      if (r.width > 0 && r.right > vw + 1 && getComputedStyle(el).position !== 'fixed') {
+        wide.push(`${describeEl(el)} reaches ${Math.round(r.right)}px`);
+        if (wide.length >= 5) break;
+      }
+    }
+  }
+
+  const broken = [...document.images].filter((i) => i.complete && i.naturalWidth === 0).map((i) => i.src.slice(0, 80));
+  const noAlt = [...document.images].filter((i) => !i.hasAttribute('alt')).length;
+  const unnamed = [...document.querySelectorAll('button, a[href], [role="button"]')]
+    .filter((el) => !(el.innerText || '').trim() && !el.getAttribute('aria-label') && !el.getAttribute('title')
+      && !el.querySelector('[aria-label], title, img[alt]:not([alt=""])'))
+    .slice(0, 5).map(describeEl);
+  const inputsNoLabel = [...document.querySelectorAll('input:not([type="hidden"]), textarea, select')]
+    .filter((el) => !(el.id && document.querySelector(`label[for="${el.id}"]`)) && !el.closest('label')
+      && !el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby'))
+    .length;
+  const tiny = vw < 600
+    ? [...document.querySelectorAll('button, a[href], [role="button"], input, select')]
+        .filter((el) => { const r = el.getBoundingClientRect(); return r.width > 0 && (r.height < 32 || r.width < 32); })
+        .length
+    : 0;
+  const smallText = [...document.querySelectorAll('p, li, span, a, button, label, td')]
+    .filter((el) => el.childElementCount === 0 && (el.innerText || '').trim() && parseFloat(getComputedStyle(el).fontSize) < 12)
+    .length;
+
+  return {
+    title: document.title,
+    overflow: overflow > 1 ? Math.round(overflow) : 0,
+    wide, broken, noAlt, unnamed, inputsNoLabel, tiny, smallText,
+    empty: !(document.body.innerText || '').trim(),
+  };
+}
+
+const safeName = (p) => (p === '/' ? 'home' : p.replace(/^\/+|\/+$/g, '').replace(/[^\w-]+/g, '_')) || 'page';
+
+async function review(shots) {
+  const request = [
+    {
+      role: 'system',
+      content:
+        'You are a senior product designer reviewing screenshots of a web app, one at a phone width ' +
+        'and one at desktop width. List the concrete visual problems a user would notice, most ' +
+        'important first: broken or cramped layout, overflow, misalignment, weak hierarchy (is the ' +
+        'most important thing the most prominent?), inconsistent spacing, low contrast, default-looking ' +
+        'components, awkward empty states, text that is too small. For each: where it is, what is wrong, ' +
+        'and the specific fix. At most 8 points, one or two lines each. If it genuinely looks polished, ' +
+        'say so in one line and name the one thing that would improve it most. No preamble.',
+    },
+    {
+      role: 'user',
+      content: shots.map((s) => `${s.label}`).join(' and ') + '.',
+      images: shots.map((s) => s.dataUrl),
+    },
+  ];
+  const reply = await ask(request, [], { model: VISION_MODEL, temperature: 0.2, maxOutputTokens: 900 });
+  return reply.text.trim();
+}
+
+export async function lookAtApp({ url, paths = ['/'], review: wantReview = true }) {
+  const base = String(url ?? '').trim().replace(/\/+$/, '');
+  if (!LOCAL.test(`${base}/`)) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'looking at the app',
+      failed: `"${url}" is not a local address. This only opens apps running on this machine.`,
+      fix: 'Pass the URL the dev server reported, e.g. http://localhost:3000',
+    });
+  }
+
+  const pages = (Array.isArray(paths) && paths.length ? paths : ['/'])
+    .map((p) => `/${String(p).trim().replace(/^\/+/, '')}`)
+    .slice(0, 4);
+
+  const shotsDir = path.join(getRoot(), '.ucode', 'screenshots');
+  await fs.mkdir(shotsDir, { recursive: true });
+
+  const b = await browser();
+  const sections = [];
+  const toReview = [];
+  let problems = 0;
+
+  for (const pagePath of pages) {
+    for (const size of WIDTHS) {
+      const context = await b.newContext({ viewport: { width: size.width, height: size.height }, deviceScaleFactor: 1 });
+      const page = await context.newPage();
+      const errors = [];
+      const failed = [];
+      page.on('console', (m) => {
+        if (m.type() === 'error' && !/devtools|download the react/i.test(m.text())) errors.push(m.text().slice(0, 200));
+      });
+      page.on('pageerror', (e) => errors.push(`uncaught: ${String(e.message).slice(0, 200)}`));
+      page.on('requestfailed', (r) => failed.push(`${r.method()} ${r.url().slice(0, 100)} — ${r.failure()?.errorText ?? 'failed'}`));
+      page.on('response', (r) => { if (r.status() >= 400) failed.push(`${r.status()} ${r.url().slice(0, 100)}`); });
+
+      const target = `${base}${pagePath}`;
+      let loadError = null;
+      try {
+        // A dev server compiles a page on its first request, which can take a
+        // while; networkidle then waits for the page's own data to arrive.
+        await page.goto(target, { waitUntil: 'networkidle', timeout: 60_000 });
+      } catch (err) {
+        try { await page.goto(target, { waitUntil: 'load', timeout: 30_000 }); }
+        catch (err2) { loadError = String(err2.message).split('\n')[0]; }
+      }
+      await page.waitForTimeout(600); // let entrance animations settle
+
+      const file = path.join(shotsDir, `${safeName(pagePath)}-${size.name}.jpg`);
+      let facts = null;
+      if (!loadError) {
+        facts = await page.evaluate(inspect).catch((err) => ({ error: err.message }));
+        const buffer = await page.screenshot({ type: 'jpeg', quality: 70, fullPage: false });
+        await fs.writeFile(file, buffer);
+        toReview.push({ label: `${pagePath} at ${size.width}px (${size.name})`, dataUrl: `data:image/jpeg;base64,${buffer.toString('base64')}` });
+      }
+      await context.close();
+
+      const lines = [`### ${pagePath} at ${size.width}px (${size.name})`];
+      if (loadError) {
+        lines.push(`Could not load: ${loadError}`);
+        problems++;
+      } else {
+        lines.push(`Screenshot: ${path.relative(getRoot(), file).split(path.sep).join('/')}`);
+        if (facts?.empty) { lines.push('- The page rendered no visible text at all.'); problems++; }
+        if (facts?.overflow) {
+          lines.push(`- Content is ${facts.overflow}px wider than the screen, so it scrolls sideways:`, ...facts.wide.map((w) => `  - ${w}`));
+          problems++;
+        }
+        if (facts?.broken?.length) { lines.push(`- Broken images: ${facts.broken.join(', ')}`); problems++; }
+        if (facts?.unnamed?.length) { lines.push(`- Buttons or links with no accessible name: ${facts.unnamed.join(', ')}`); problems++; }
+        if (facts?.inputsNoLabel) { lines.push(`- ${facts.inputsNoLabel} form field(s) without a label.`); problems++; }
+        if (facts?.noAlt) lines.push(`- ${facts.noAlt} image(s) without alt text.`);
+        if (facts?.tiny) lines.push(`- ${facts.tiny} tap target(s) smaller than 32px on a phone.`);
+        if (facts?.smallText) lines.push(`- ${facts.smallText} text element(s) under 12px.`);
+      }
+      if (errors.length) { lines.push('- Console errors:', ...[...new Set(errors)].slice(0, 6).map((e) => `  - ${e}`)); problems++; }
+      if (failed.length) { lines.push('- Failed requests:', ...[...new Set(failed)].slice(0, 6).map((f) => `  - ${f}`)); problems++; }
+      if (lines.length === 2 && !loadError) lines.push('- No errors, no overflow, nothing unlabeled.');
+      sections.push(lines.join('\n'));
+    }
+  }
+
+  let critique = '';
+  if (wantReview !== false && toReview.length) {
+    try {
+      critique = await review(toReview.slice(0, 4));
+    } catch (err) {
+      critique = `(The visual review could not run: ${err.failed ?? err.message}. The checks above still apply.)`;
+    }
+  }
+
+  const body = [
+    ...sections,
+    critique ? `## Visual review\n${critique}` : '',
+    '',
+    problems
+      ? 'Fix the problems above, then look again to confirm.'
+      : 'The automatic checks found nothing. Weigh the visual review, fix what is worth fixing.',
+  ].filter(Boolean).join('\n\n');
+
+  return result(
+    body,
+    problems
+      ? `${problems} problem${problems === 1 ? '' : 's'} found · screenshots in .ucode/screenshots`
+      : 'no errors · screenshots in .ucode/screenshots'
+  );
+}

package/src/tools/index.js

@@ -8,6 +8,8 @@ import { readFile, readFiles, writeFile, batchWrite, editFile, multiEdit, editFi
 import { listDir, glob, grep } from './search.js';
 import { runCommand, runCommands } from './shell.js';
 import { webSearch } from './web.js';
+import { lookAtApp } from './browser.js';
+import { createApp } from './scaffold.js';
 import { clip, READ_LINES } from './shared.js';
 
 export { setRoot, setConfirm, getRoot } from './shared.js';
@@ -17,6 +19,25 @@ const int = (description) => ({ type: 'integer', description });
 const bool = (description) => ({ type: 'boolean', description });
 
 export const tools = [
+  {
+    name: 'create_app',
+    description:
+      'Start a new Next.js + shadcn/ui app from the ready-made ucode starter. This is how every ' +
+      'Next.js app begins - never run create-next-app or shadcn init. It copies a project that ' +
+      'is already known to build (Next.js 16, TypeScript, Tailwind 4, shadcn with 25 common ' +
+      'components, light/dark mode, toasts, a considered theme) into a new empty folder, and ' +
+      'starts installing its packages in the background so you can write components at once. ' +
+      'The result lists everything included.',
+    parameters: {
+      type: 'object',
+      properties: {
+        folder: str('A new, empty folder for the app, relative to the project root, e.g. "stride".'),
+        name: str('The display name of the app, e.g. "Stride".'),
+        description: str('One line about the app, used in the page metadata.'),
+      },
+      required: ['folder', 'name'],
+    },
+  },
   {
     name: 'read_file',
     description:
@@ -267,6 +288,29 @@ export const tools = [
       required: ['commands'],
     },
   },
+  {
+    name: 'look_at_app',
+    description:
+      'Open the running app in a real browser at a phone width (375px) and a desktop width ' +
+      '(1440px) and report what a person would run into: console errors, failed requests, ' +
+      'content that spills off the side of the screen, broken images, unlabeled buttons and ' +
+      'fields - plus a designer-style review of the screenshots. Use it once the dev server ' +
+      'is ready, and again after visual changes, then fix what it reports. Screenshots are ' +
+      'saved under .ucode/screenshots.',
+    parameters: {
+      type: 'object',
+      properties: {
+        url: str('The local URL the dev server reported, e.g. http://localhost:3000'),
+        paths: {
+          type: 'array',
+          description: 'Pages to open, e.g. ["/", "/settings"]. Defaults to ["/"]. Up to 4.',
+          items: { type: 'string' },
+        },
+        review: bool('Include the visual design review of the screenshots. Defaults to true.'),
+      },
+      required: ['url'],
+    },
+  },
   {
     name: 'web_search',
     description:
@@ -299,6 +343,8 @@ const run = {
   run_command: runCommand,
   run_commands: runCommands,
   web_search: webSearch,
+  look_at_app: lookAtApp,
+  create_app: createApp,
 };
 
 /** Tools that change the project or execute code. */
@@ -312,7 +358,7 @@ export const PARALLEL_SAFE = new Set(['read_file', 'read_files', 'list_dir', 'gl
 /** Tools withheld in plan mode. Withholding beats asking a model not to. */
 export const WRITES = new Set([
   'write_file', 'batch_write', 'edit_file', 'multi_edit', 'edit_files', 'run_command', 'run_commands',
-  'delegate',
+  'delegate', 'create_app',
 ]);
 
 /** Tools that change files on disk, which parallel workers take turns at. */
@@ -435,6 +481,10 @@ export function describe(name, args = {}) {
       return `Running ${clip(args.command, 70)}${args.background ? ' in the background' : ''}`;
     case 'run_commands':
       return `Running ${args.commands?.length ?? 0} commands together`;
+    case 'create_app':
+      return `Creating ${clip(args.name || args.folder, 30)} from the Next.js starter`;
+    case 'look_at_app':
+      return `Looking at ${clip(args.url, 40)} on a phone and a desktop`;
     case 'web_search':
       return `Searching the web for ${clip(args.query, 60)}`;
     case 'load_skill':

package/src/tools/scaffold.js

@@ -0,0 +1,130 @@
+/**
+ * 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)
+ */
+export async function createApp({ folder, name, description, template = 'next-shadcn', 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 });
+
+  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` +
+      (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

@@ -200,7 +200,14 @@ function startServer(command, workdir, { env } = {}) {
         cwd: workdir.abs,
         shell: true,
         windowsHide: true,
-        detached: true,
+        // Not detached on Windows, and this is load-bearing. A detached process
+        // there has no console, and programs launched under it write nothing
+        // to a redirected file — measured: every one of node, npm and next
+        // produced an empty log, so a server's "ready" line never arrived and
+        // every start waited out the full timer. Attached, the output lands.
+        // The server itself still outlives ucode: only this shell is tied to
+        // ucode's job object, and the job lets grandchildren break away.
+        detached: process.platform !== 'win32',
         stdio: ['ignore', fd, fd],
         env,
       });

package/src/ui/screen.js

@@ -39,7 +39,7 @@ import chalk from 'chalk';
 import {
   theme, blue, sky, deep, dim, edge, ADDED, REMOVED, BANNER, BANNER_WIDTH, SPINNER,
   boxTop, boxBottom, boxRow, visLen, padVis, clip, wrapAnsi,
-  shortenPath, asLabel, ensureColour, planLine,
+  shortenPath, asLabel, ensureColour, planLine, bare,
 } from './theme.js';
 import { renderer, render, polish } from './markdown.js';
 import { VERSION } from '../core/version.js';
@@ -773,11 +773,15 @@ export class Screen {
    * cannot be given up permanently, because under alternate scroll the mouse
    * wheel arrives as arrow keys.
    */
-  pick(items, { active = 0, hint = 'enter to choose · esc to cancel' } = {}) {
+  pick(items, { active = 0, hint = 'enter to choose · esc to cancel', deletable = false } = {}) {
     this.picker = {
       items,
       index: Math.min(Math.max(0, active), Math.max(0, items.length - 1)),
       hint,
+      // With deletable, `d` twice on a row resolves { delete: index }. Twice,
+      // because a single stray keypress should never cost a conversation.
+      deletable,
+      armed: null,
     };
     this.render();
     return new Promise((resolve) => { this.pickerResolve = resolve; });
@@ -799,7 +803,7 @@ export class Screen {
    * about instead of a column of near-identical titles.
    */
   pickerLines(height) {
-    const { items, index, hint } = this.picker;
+    const { items, index, hint, armed } = this.picker;
     const room = Math.max(1, height - 2);
 
     // Rows per item, so the window can be sized in rows rather than in items.
@@ -821,12 +825,15 @@ export class Screen {
     for (let i = first; i <= last; i++) {
       const item = items[i];
       const body = typeof item === 'string' ? item : item.label;
-      out.push(i === index ? `${blue('❯')} ${chalk.bold.white(body)}` : `  ${dim(body)}`);
+      if (i === armed) out.push(`${theme.warn('✗')} ${theme.warn(bare(body))}`);
+      else out.push(i === index ? `${blue('❯')} ${chalk.bold.white(body)}` : `  ${dim(body)}`);
       if (typeof item !== 'string' && item.sub) out.push(`  ${item.sub}`);
     }
 
     out.push('');
-    out.push(dim(`  ${hint}`));
+    out.push(armed !== null && armed !== undefined
+      ? theme.warn('  press d again to delete this conversation · any other key keeps it')
+      : dim(`  ${hint}`));
     return out;
   }
 
@@ -932,6 +939,13 @@ export class Screen {
     // An open picker owns the keyboard until it closes.
     if (this.picker) {
       const last = this.picker.items.length - 1;
+      if (this.picker.deletable && (key === 'd' || key === 'D' || key === `${ESC}[3~`)) {
+        if (this.picker.armed === this.picker.index) { this.closePicker({ delete: this.picker.index }); return; }
+        this.picker.armed = this.picker.index;
+        this.render();
+        return;
+      }
+      this.picker.armed = null;   // any other key takes the delete back
       if (key === `${ESC}[A`) { this.picker.index = Math.max(0, this.picker.index - 1); this.render(); return; }
       if (key === `${ESC}[B`) { this.picker.index = Math.min(last, this.picker.index + 1); this.render(); return; }
       if (key === '\r' || key === '\n') { this.closePicker(this.picker.index); return; }
@@ -1149,7 +1163,7 @@ export class Screen {
 
     // The version, in the corner, and nothing else on the screen.
     if (VERSION) {
-      const tag = dim(`v${VERSION}`);
+      const tag = dim(this.facts.update ? `v${VERSION} · v${this.facts.update} installed, starts next time` : `v${VERSION}`);
       frame[this.rows - 1] = ' '.repeat(Math.max(0, g.cols - visLen(tag) - 2)) + tag;
     }
 

package/templates/next-shadcn/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->