ucode-agent 1.5.0 → 1.6.0

package/src/tools/deploy.js

@@ -0,0 +1,283 @@
+/**
+ * deploy.js — put the app online on Vercel.
+ *
+ * The user says "deploy it" (or types /deploy) and gets a live link. ucode
+ * picks a short project name that fits the app and is actually free, creates
+ * or reuses the Vercel project, copies the app's .env keys to it as encrypted
+ * variables, refuses to upload code with a secret written into it, and hands
+ * the upload and build to the Vercel CLI — which knows every framework's
+ * build settings better than anything written here would.
+ *
+ * The token comes from VERCEL_TOKEN (~/.ucode/.env). It is never printed:
+ * anything the CLI says is scrubbed of it before it reaches the screen.
+ */
+
+import { spawn } from 'node:child_process';
+import { promises as fs, existsSync } from 'node:fs';
+import path from 'node:path';
+import { ToolFailure } from '../core/failure.js';
+import { ENV_FILE } from '../core/provider.js';
+import { resolveIn, result } from './shared.js';
+import { childEnv } from './shell.js';
+
+const API = 'https://api.vercel.com';
+const DEPLOY_TIMEOUT = 12 * 60_000;
+let fetchImpl = (...a) => fetch(...a);
+
+/** Tests hand in a fake fetch. */
+export function setFetch(f) { fetchImpl = f ?? ((...a) => fetch(...a)); }
+
+// ---------------------------------------------------------------------------
+// Names
+// ---------------------------------------------------------------------------
+
+/** "Food IQ" → "food-iq": lowercase, a-z 0-9 and dashes, short, cut at a word. */
+export function slugify(text, max = 20) {
+  let s = String(text ?? '').toLowerCase().replace(/^@[^/]+\//, '')
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (s.length > max) {
+    const cut = s.slice(0, max);
+    s = cut.includes('-') ? cut.slice(0, cut.lastIndexOf('-')) : cut;
+  }
+  return s || 'app';
+}
+
+/** Candidates in order of preference: the plain name first, then tidy variants. */
+export function nameCandidates(base) {
+  const b = slugify(base);
+  const words = ['app', 'web', 'live', 'hq', 'hub'];
+  const rand = () => Math.random().toString(36).slice(2, 6);
+  return [b, ...words.map((w) => `${b}-${w}`), b.replace(/-/g, ''), `${b}-${rand()}`, `${b}-${rand()}`]
+    .filter((v, i, a) => v && a.indexOf(v) === i);
+}
+
+/**
+ * Is <name>.vercel.app free? Not a project of this account, and no one
+ * else's deployment answers at that address.
+ */
+async function available(name, ctx) {
+  const mine = await ctx.api(`/v9/projects/${name}`);
+  if (mine.status === 200) return false;
+  try {
+    const r = await fetchImpl(`https://${name}.vercel.app`, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(8000) });
+    return r.status === 404 && /DEPLOYMENT_NOT_FOUND|NOT_FOUND/i.test(r.headers.get('x-vercel-error') ?? 'NOT_FOUND');
+  } catch {
+    return true; // nothing answered at all — the name is unclaimed
+  }
+}
+
+export async function pickName(base, ctx) {
+  for (const candidate of nameCandidates(base)) {
+    if (await available(candidate, ctx)) return candidate;
+  }
+  throw new ToolFailure({
+    kind: 'no_name', attempted: 'choosing a project name',
+    failed: `Every name tried for "${base}" is taken.`,
+    fix: 'Call deploy again with a different name.',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Secrets and env
+// ---------------------------------------------------------------------------
+
+const SECRET_PATTERNS = [
+  [/sk-or-v1-[0-9a-f]{20,}/, 'an API key (sk-or-v1-…)'],
+  [/\bsk-(?:proj-|ant-)?[A-Za-z0-9_-]{32,}/, 'an API key (sk-…)'],
+  [/\bvcp_[A-Za-z0-9]{20,}/, 'a Vercel token'],
+  [/\bAKIA[0-9A-Z]{16}\b/, 'an AWS access key'],
+  [/\bgh[pousr]_[A-Za-z0-9]{30,}/, 'a GitHub token'],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/, 'a Google API key'],
+];
+const SKIP_DIRS = new Set(['node_modules', '.next', '.git', '.vercel', 'dist', 'build', 'out', '.ucode', '.turbo']);
+const SCAN_EXT = /\.(?:[cm]?[jt]sx?|html?|vue|svelte|astro|json)$/i;
+
+/** Files with a secret written into them. `.env*` files are the right place, so they are skipped. */
+export async function scanSecrets(dir) {
+  const found = [];
+  async function walk(d) {
+    for (const entry of await fs.readdir(d, { withFileTypes: true }).catch(() => [])) {
+      if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name)) await walk(path.join(d, entry.name)); continue; }
+      if (entry.name.startsWith('.env') || entry.name === 'package-lock.json' || !SCAN_EXT.test(entry.name)) continue;
+      const file = path.join(d, entry.name);
+      const text = await fs.readFile(file, 'utf8').catch(() => '');
+      if (text.length > 1_000_000) continue;
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const hit = SECRET_PATTERNS.find(([re]) => re.test(lines[i]));
+        if (hit) found.push({ file: path.relative(dir, file).split(path.sep).join('/'), line: i + 1, what: hit[1] });
+      }
+    }
+  }
+  await walk(dir);
+  return found;
+}
+
+/** KEY=value pairs from .env, .env.local, .env.production — later files win. */
+export async function readEnv(dir) {
+  const vars = {};
+  for (const name of ['.env', '.env.local', '.env.production']) {
+    const text = await fs.readFile(path.join(dir, name), 'utf8').catch(() => '');
+    for (const line of text.split(/\r?\n/)) {
+      const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+      if (!m) continue;
+      vars[m[1]] = m[2].replace(/^(['"])(.*)\1$/, '$2');
+    }
+  }
+  return vars;
+}
+
+function frameworkOf(pkg, dir) {
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  if (deps.next) return 'nextjs';
+  if (deps.vite) return 'vite';
+  if (deps['react-scripts']) return 'create-react-app';
+  if (!pkg && existsSync(path.join(dir, 'index.html'))) return null;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// The tool
+// ---------------------------------------------------------------------------
+
+export async function deploy({ folder = '.', name } = {}, { onOutput } = {}) {
+  const token = process.env.VERCEL_TOKEN;
+  if (!token) {
+    throw new ToolFailure({
+      kind: 'no_token', attempted: 'deploying to Vercel',
+      failed: 'There is no Vercel token yet.',
+      fix: `Tell the user: make one at vercel.com/account/tokens (Create Token), then add a line VERCEL_TOKEN=... to ${ENV_FILE} and restart ucode.`,
+    });
+  }
+  const say = (line) => onOutput?.([line]);
+  const where = resolveIn(folder, 'deploy', 'folder');
+  const dir = where.abs;
+  const pkg = JSON.parse(await fs.readFile(path.join(dir, 'package.json'), 'utf8').catch(() => 'null'));
+  if (!pkg && !existsSync(path.join(dir, 'index.html'))) {
+    throw new ToolFailure({
+      kind: 'not_an_app', attempted: `deploying ${where.show}`,
+      failed: `${where.show} has no package.json or index.html, so there is nothing to deploy.`,
+      fix: 'Pass the folder of the app itself, e.g. deploy({ folder: "food-iq" }).',
+    });
+  }
+
+  const scrub = (s) => String(s).split(token).join('***');
+  const api = async (pathname, { method = 'GET', body } = {}) => {
+    const url = new URL(API + pathname);
+    if (ctx.teamId) url.searchParams.set('teamId', ctx.teamId);
+    const r = await fetchImpl(url, {
+      method, body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(20_000),
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    });
+    return { status: r.status, ok: r.ok, json: await r.json().catch(() => ({})) };
+  };
+  const ctx = { api, teamId: null };
+
+  say('Checking for secrets');
+  const leaks = await scanSecrets(dir);
+  if (leaks.length) {
+    const list = leaks.slice(0, 5).map((l) => `${l.file}:${l.line} (${l.what})`).join(', ');
+    throw new ToolFailure({
+      kind: 'secret_in_code', attempted: `deploying ${where.show}`,
+      failed: `The code has a secret written into it: ${list}. Once online, anyone could read it.`,
+      fix: 'Move the value to .env.local (e.g. OPENROUTER_API_KEY=...), read it with process.env in a ' +
+        'server route (Next.js: app/api/.../route.ts), call that route from the page, then deploy again. ' +
+        'ucode copies .env.local to Vercel for you.',
+    });
+  }
+
+  const me = await api('/v2/user');
+  if (!me.ok) {
+    throw new ToolFailure({
+      kind: 'bad_token', attempted: 'deploying to Vercel', failed: 'Vercel did not accept the token.',
+      fix: 'Tell the user to make a new token at vercel.com/account/tokens and put it in ~/.ucode/.env as VERCEL_TOKEN.',
+    });
+  }
+  ctx.teamId = me.json.user?.defaultTeamId ?? null;
+  const orgId = ctx.teamId ?? me.json.user?.id;
+
+  // Reuse the project this app was deployed to before, so the link stays the same.
+  const linkFile = path.join(dir, '.vercel', 'project.json');
+  let link = JSON.parse(await fs.readFile(linkFile, 'utf8').catch(() => 'null'));
+  if (link?.projectId) {
+    const still = await api(`/v9/projects/${link.projectId}`);
+    if (!still.ok) link = null;
+    else link.projectName = still.json.name;
+  }
+  if (!link?.projectId) {
+    say('Choosing a name');
+    const projectName = name ? slugify(name) : await pickName(pkg?.name || path.basename(dir), ctx);
+    const made = await api('/v11/projects', { method: 'POST', body: { name: projectName, framework: frameworkOf(pkg, dir) } });
+    if (!made.ok) {
+      throw new ToolFailure({
+        kind: 'vercel_error', attempted: `creating the Vercel project ${projectName}`,
+        failed: scrub(made.json?.error?.message ?? `HTTP ${made.status}`),
+        fix: 'Try again with a different name.',
+      });
+    }
+    link = { projectId: made.json.id, orgId, projectName };
+    await fs.mkdir(path.dirname(linkFile), { recursive: true });
+    await fs.writeFile(linkFile, JSON.stringify({ projectId: link.projectId, orgId }, null, 2));
+    const gi = path.join(dir, '.gitignore');
+    const ignore = await fs.readFile(gi, 'utf8').catch(() => '');
+    if (!/^\.vercel\/?$/m.test(ignore)) await fs.writeFile(gi, `${ignore.replace(/\n?$/, '\n')}.vercel\n`).catch(() => {});
+  }
+
+  const vars = await readEnv(dir);
+  const keys = Object.keys(vars);
+  if (keys.length) {
+    say(`Copying ${keys.length} key${keys.length === 1 ? '' : 's'} to Vercel`);
+    await api(`/v10/projects/${link.projectId}/env?upsert=true`, {
+      method: 'POST',
+      body: keys.map((key) => ({ key, value: vars[key], type: 'encrypted', target: ['production', 'preview'] })),
+    });
+  }
+
+  say('Uploading and building on Vercel');
+  const started = Date.now();
+  const { code, output } = await new Promise((resolve) => {
+    const args = ['--yes', 'vercel@latest', 'deploy', '--prod', '--yes', '--token', token];
+    const child = spawn(process.platform === 'win32' ? 'npx.cmd' : 'npx', args, {
+      cwd: dir, shell: process.platform === 'win32', windowsHide: true,
+      env: { ...childEnv(), VERCEL_ORG_ID: orgId, VERCEL_PROJECT_ID: link.projectId, VERCEL_TELEMETRY_DISABLED: '1' },
+    });
+    let output = '';
+    const take = (chunk) => {
+      const text = scrub(chunk).replace(/\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07/g, '');
+      output += text;
+      // Only lines that read as progress: no markup, no lone braces, no redraw leftovers.
+      const last = text.split(/\r?\n/).map((l) => l.replace(/\[[0-9;]*[A-Za-z]/g, '').trim())
+        .filter((l) => /[A-Za-z]{3}/.test(l) && !/^[<{}[\]]/.test(l)).at(-1);
+      if (last) say(last.replace(/^[▲✓>\s]+/, '').replace(/\s*\[\d+s\]$/, '').slice(0, 80));
+    };
+    child.stdout.on('data', take);
+    child.stderr.on('data', take);
+    const timer = setTimeout(() => child.kill(), DEPLOY_TIMEOUT);
+    child.on('error', (err) => { clearTimeout(timer); resolve({ code: -1, output: `${output}\n${err.message}` }); });
+    child.on('close', (c) => { clearTimeout(timer); resolve({ code: c, output }); });
+  });
+  const secs = Math.round((Date.now() - started) / 1000);
+
+  if (code !== 0) {
+    const tail = output.split(/\r?\n/).filter((l) => l.trim()).slice(-25).join('\n');
+    throw new ToolFailure({
+      kind: 'deploy_failed', attempted: `deploying ${where.show} to Vercel`,
+      failed: `The deploy failed after ${secs}s:\n${tail}`,
+      fix: 'The lines above name the problem — usually the same error `npm run build` shows locally. ' +
+        'Fix it, check the build passes, then deploy again.',
+    });
+  }
+
+  const live = `https://${link.projectName}.vercel.app`;
+  const ok = await fetchImpl(live, { signal: AbortSignal.timeout(15_000) }).then((r) => r.status < 400).catch(() => false);
+  const url = ok ? live : (output.match(/https:\/\/[a-z0-9.-]+\.vercel\.app/g) ?? [live]).at(-1);
+  return result(
+    [
+      `Live at ${url}`,
+      `Deployed in ${secs}s as the Vercel project "${link.projectName}".`,
+      keys.length ? `Copied to Vercel as encrypted variables: ${keys.join(', ')}` : '',
+      'Deploying again updates the same link.',
+    ].filter(Boolean).join('\n'),
+    `live · ${url} · ${secs}s`
+  );
+}

package/src/tools/files.js

@@ -15,6 +15,7 @@ import {
   changedRegion, renderDiff, renderNewFile, READ_LINES, MAX_FILE_OUTPUT,
 } from './shared.js';
 import { packageJsonWritten } from './shell.js';
+import { parse as parseSource } from '@babel/parser';
 
 export async function readFile({ path: p, offset = 1, limit = READ_LINES }) {
   const target = resolveIn(p, 'read_file');
@@ -94,6 +95,71 @@ function written(target, content) {
   if (path.basename(target.abs) === 'package.json') packageJsonWritten(target.abs, content);
 }
 
+const PARSEABLE = /\.(?:[cm]?[jt]sx?)$/i;
+
+/**
+ * Does this source parse? Checked the moment a file is written.
+ *
+ * Measured on a real build: a JSX typo sat unnoticed until `npm run build`,
+ * which takes up to a minute, failed on it — then the fix, then another full
+ * build. Parsing the file takes milliseconds, so the error comes back in the
+ * same step that wrote it, with the line, while the model still has the file
+ * in front of it. Syntax only: types are checked at the end of the turn.
+ */
+export function syntaxProblem(file, text) {
+  if (!PARSEABLE.test(file)) return null;
+  const ext = path.extname(file).toLowerCase();
+  const plugins = ext === '.tsx'
+    ? ['typescript', 'jsx']
+    : /^\.[cm]?ts$/.test(ext) ? ['typescript'] : ['jsx'];
+  const where = (loc) => (loc ? `line ${loc.line}, column ${loc.column + 1}` : 'somewhere in the file');
+  const clean = (m) => String(m).replace(/\s*\(\d+:\d+\)\s*$/, '');
+  try {
+    const ast = parseSource(text, {
+      sourceType: 'unambiguous',
+      plugins: [...plugins, 'decorators-legacy'],
+      errorRecovery: true,
+      allowReturnOutsideFunction: true,
+      allowAwaitOutsideFunction: true,
+    });
+    const first = ast.errors?.[0];
+    return first ? `${where(first.loc)}: ${clean(first.message)}` : null;
+  } catch (err) {
+    return `${where(err.loc)}: ${clean(err.message)}`;
+  }
+}
+
+/** The warning appended to a result when a file does not parse. */
+const brokenNote = (show, problem) =>
+  `\n\n⚠ ${show} does not parse — ${problem}. Fix it now: the build will fail on it.`;
+
+/** A file this short comes back whole after an edit; longer ones show the part around the change. */
+const SHOW_WHOLE = 250;
+const AROUND = 15;
+
+/**
+ * The file as it stands after an edit, with the same line-number gutter as
+ * read_file.
+ *
+ * Measured on a real build: the model read the same component thirteen times
+ * in one turn, because an edit's result showed only the lines it replaced and
+ * the next edit needed the file as it now was. Sending the current text back
+ * with the edit costs the same tokens the re-read would have, and saves the
+ * round trip every time.
+ */
+function nowReads(show, text, at, span) {
+  const lines = toLines(text);
+  const whole = lines.length <= SHOW_WHOLE;
+  const from = whole ? 1 : Math.max(1, at - AROUND);
+  const to = whole ? lines.length : Math.min(lines.length, at + span + AROUND);
+  const width = String(to).length;
+  const body = lines.slice(from - 1, to).map((l, i) => `${String(from + i).padStart(width)} | ${l}`).join('\n');
+  const heading = whole
+    ? `${show} now reads (all ${lines.length} lines`
+    : `${show} now reads, lines ${from}-${to} of ${lines.length}`;
+  return `\n\n${heading} — this is the current text, so there is no need to read it again):\n${body}`;
+}
+
 /** At most this many files in one read_files call. */
 const MAX_BATCH = 20;
 
@@ -216,6 +282,7 @@ async function put(target, content, { diffMax = 16 } = {}) {
     existed,
     lineCount,
     diff,
+    problem: syntaxProblem(target.abs, content),
     line: `${existed ? 'Overwrote' : 'Created'} ${target.show} ` +
       `(${lineCount} lines, ${bytes(Buffer.byteLength(content))})`,
   };
@@ -234,7 +301,10 @@ export async function writeFile({ path: p, content }) {
   await guard(target, `write ${target.abs}`);
 
   const written = await put(target, content);
-  const out = result(`${written.line}.`, `${written.existed ? 'overwrote' : 'created'} · ${written.lineCount} lines`);
+  const out = result(
+    `${written.line}.${written.problem ? brokenNote(target.show, written.problem) : ''}`,
+    `${written.existed ? 'overwrote' : 'created'} · ${written.lineCount} lines${written.problem ? ' · does not parse' : ''}`
+  );
   out.diff = written.diff;
   return out;
 }
@@ -258,6 +328,7 @@ export async function batchWrite({ files }) {
   const lines = [];
   const diff = [];
   let created = 0;
+  let broken = 0;
 
   for (const [index, file] of files.entries()) {
     const { path: p, content } = file ?? {};
@@ -277,13 +348,14 @@ export async function batchWrite({ files }) {
     // would bury the reply under three hundred lines of gutter.
     const written = await put(target, content, { diffMax: 6 });
     if (!written.existed) created++;
-    lines.push(written.line);
+    lines.push(written.line + (written.problem ? brokenNote(target.show, written.problem) : ''));
+    if (written.problem) broken++;
     diff.push(`~${target.show}`, ...written.diff);
   }
 
   const out = result(
     lines.join('\n'),
-    `${files.length} file${files.length === 1 ? '' : 's'} · ${created} new`
+    `${files.length} file${files.length === 1 ? '' : 's'} · ${created} new${broken ? ` · ${broken} do not parse` : ''}`
   );
   out.diff = diff;
   return out;
@@ -462,9 +534,13 @@ export async function editFile({ path: p, old_string, new_string }) {
   const change = delta === 0 ? 'same line count' : `${delta > 0 ? '+' : ''}${delta} lines`;
   const how = loose ? ', matched ignoring whitespace and re-indented to fit' : '';
 
+  const span = toLines(new_string).length;
   const out = result(
-    `Replaced one occurrence in ${target.show} at line ${at} (${change}${how}).`,
-    `1 change at line ${at} · ${change}${loose ? ' · whitespace-tolerant' : ''}`
+    `Replaced one occurrence in ${target.show} at line ${at} (${change}${how}).` +
+      (syntaxProblem(target.abs, text) ? brokenNote(target.show, syntaxProblem(target.abs, text)) : '') +
+      nowReads(target.show, text, at, span),
+    `1 change at line ${at} · ${change}${loose ? ' · whitespace-tolerant' : ''}${syntaxProblem(target.abs, text) ? ' · does not parse' : ''}`,
+    MAX_FILE_OUTPUT
   );
   // The replacement is diffed on its own and offset to where it landed, so
   // the gutter shows the file's line numbers rather than 1, 2, 3.
@@ -531,8 +607,11 @@ export async function multiEdit({ path: p, edits }) {
   const change = delta === 0 ? 'same line count' : `${delta > 0 ? '+' : ''}${delta} lines`;
 
   const out = result(
-    `Applied ${edits.length} edits to ${target.show} (${change}).`,
-    `${edits.length} edits · ${change}`
+    `Applied ${edits.length} edits to ${target.show} (${change}).` +
+      (syntaxProblem(target.abs, text) ? brokenNote(target.show, syntaxProblem(target.abs, text)) : '') +
+      nowReads(target.show, text, 1, toLines(text).length),
+    `${edits.length} edits · ${change}`,
+    MAX_FILE_OUTPUT
   );
   out.diff = diff;
   return out;
@@ -615,7 +694,11 @@ export async function editFiles({ files }) {
 
   const edits = planned.reduce((n, p) => n + p.count, 0);
   const out = result(
-    planned.map((p) => `Edited ${p.target.show} (${p.count} change${p.count === 1 ? '' : 's'})`).join('\n'),
+    planned.map((p) => {
+      const problem = syntaxProblem(p.target.abs, p.text);
+      return `Edited ${p.target.show} (${p.count} change${p.count === 1 ? '' : 's'})` +
+        (problem ? brokenNote(p.target.show, problem) : '');
+    }).join('\n'),
     `${planned.length} files · ${edits} edits`
   );
   out.diff = planned.flatMap((p) => p.diff);

package/src/tools/index.js

@@ -10,6 +10,7 @@ import { runCommand, runCommands } from './shell.js';
 import { webSearch } from './web.js';
 import { lookAtApp } from './browser.js';
 import { createApp } from './scaffold.js';
+import { deploy } from './deploy.js';
 import { clip, READ_LINES } from './shared.js';
 
 export { setRoot, setConfirm, getRoot } from './shared.js';
@@ -24,8 +25,8 @@ export const tools = [
     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 ' +
+      'is already known to build (Next.js 16, TypeScript, Tailwind 4, shadcn with 33 common ' +
+      'components, light/dark mode, toasts, a design preset of colours and fonts) 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: {
@@ -34,14 +35,43 @@ export const tools = [
         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.'),
+        design: {
+          type: 'string',
+          enum: ['ocean', 'grove', 'sunset', 'graphite', 'violet', 'citrus'],
+          description:
+            'The look: colours and fonts, light and dark. Pick the one that fits the app. ' +
+            'ocean - calm blue, for dashboards, finance, productivity (default). ' +
+            'grove - fresh green, for health, habits, food, nature. ' +
+            'sunset - warm coral with a serif, for travel, recipes, journaling, lifestyle. ' +
+            'graphite - monochrome and crisp, for developer tools, docs, portfolios. ' +
+            'violet - vivid violet, for AI tools, creative apps, music, learning. ' +
+            'citrus - bright lime and bold, for games, sport, kids, social.',
+        },
       },
       required: ['folder', 'name'],
     },
   },
+  {
+    name: 'deploy',
+    description:
+      'Put an app online on Vercel and get its live link - use it when the user asks to deploy, ' +
+      'publish, host or share the app. ucode picks a short free project name, copies the app\'s ' +
+      '.env keys to Vercel as encrypted variables, refuses code with a secret written into it ' +
+      '(move it to .env.local and a server route, then deploy again), and builds on Vercel. ' +
+      'Run the local build first so errors show up here. Deploying again updates the same link.',
+    parameters: {
+      type: 'object',
+      properties: {
+        folder: str('The app folder, relative to the project root, e.g. "food-iq". Defaults to ".".'),
+        name: str('Optional: a project name to use instead of the one ucode would choose.'),
+      },
+      required: [],
+    },
+  },
   {
     name: 'read_file',
     description:
-      'Read a text file. Comes back as numbered lines — the numbers are for you to ' +
+      'Read one text file - for two or more, use read_files instead. Comes back as numbered lines — the numbers are for you to ' +
       'refer to and must never appear in an edit_file argument. Long files arrive in ' +
       'pages; pass offset to keep going.',
     parameters: {
@@ -120,7 +150,8 @@ export const tools = [
       'Replace one exact piece of text in a file. old_string must match the file ' +
       'character for character, including indentation, and must occur exactly once — ' +
       'the edit is refused on zero matches and on two. This is the normal way to ' +
-      'change existing code.',
+      'change existing code. The result shows the file as it now stands, so do not ' +
+      'read it again afterwards.',
     parameters: {
       type: 'object',
       properties: {
@@ -294,9 +325,10 @@ export const tools = [
       '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.',
+      'fields. The first look at an app also brings a designer-style review of the ' +
+      'screenshots; later looks re-run only the fast checks. Use it once the dev server is ' +
+      'ready, fix what it reports, then look once more to confirm. Screenshots are saved ' +
+      'under .ucode/screenshots.',
     parameters: {
       type: 'object',
       properties: {
@@ -306,7 +338,6 @@ export const tools = [
           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'],
     },
@@ -345,11 +376,12 @@ const run = {
   web_search: webSearch,
   look_at_app: lookAtApp,
   create_app: createApp,
+  deploy,
 };
 
 /** Tools that change the project or execute code. */
 export const MUTATING = new Set([
-  'write_file', 'batch_write', 'edit_file', 'multi_edit', 'edit_files', 'run_command', 'run_commands',
+  'write_file', 'batch_write', 'edit_file', 'multi_edit', 'edit_files', 'run_command', 'run_commands', 'deploy',
 ]);
 
 /** Tools with no side effects, so several may run at the same time. */
@@ -358,7 +390,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', 'create_app',
+  'delegate', 'create_app', 'deploy',
 ]);
 
 /** Tools that change files on disk, which parallel workers take turns at. */
@@ -481,6 +513,8 @@ 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 'deploy':
+      return `Deploying ${clip(args.folder || '.', 30)} to Vercel`;
     case 'create_app':
       return `Creating ${clip(args.name || args.folder, 30)} from the Next.js starter`;
     case 'look_at_app':

package/src/tools/scaffold.js

@@ -64,7 +64,65 @@ async function copyTree(from, to, fill) {
  * @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 }) {
+/**
+ * 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',
@@ -110,6 +168,7 @@ export async function createApp({ folder, name, description, template = 'next-sh
 
   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');
@@ -120,6 +179,7 @@ export async function createApp({ folder, name, description, template = 'next-sh
 
   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`