ucode-agent 1.5.0 → 1.7.0

package/src/tools/browser.js

@@ -25,6 +25,7 @@ const WIDTHS = [
   { name: 'desktop', width: 1440, height: 900 },
 ];
 const LOCAL = /^https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)/i;
+const MAX_SHOT_HEIGHT = 3000;
 
 let browserPromise = null;
 
@@ -131,7 +132,8 @@ async function review(shots) {
       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 ' +
+        'and one at desktop width. Each screenshot is the whole page, top to bottom, so anything not ' +
+        'in it is genuinely not there. 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, ' +
@@ -144,11 +146,40 @@ async function review(shots) {
       images: shots.map((s) => s.dataUrl),
     },
   ];
-  const reply = await ask(request, [], { model: VISION_MODEL, temperature: 0.2, maxOutputTokens: 900 });
-  return reply.text.trim();
+  const reply = await ask(request, [], {
+    model: VISION_MODEL,
+    temperature: 0.2,
+    // A reasoning model spends its budget thinking before it writes; 900
+    // tokens came back as an empty review. Keep the thinking short, and leave
+    // room for the answer.
+    maxOutputTokens: 4000,
+    reasoning: { effort: 'low' },
+    // The free vision model is often busy. One try, and a hard cap: a review
+    // that cannot run is skipped, never waited on.
+    attempts: 1,
+    signal: AbortSignal.timeout(REVIEW_BUDGET_MS),
+  });
+  const text = reply.text.trim();
+  if (!text) throw new Error('the vision model returned an empty review');
+  return text;
 }
 
-export async function lookAtApp({ url, paths = ['/'], review: wantReview = true }) {
+const REVIEW_BUDGET_MS = 60_000;
+
+/**
+ * The designer's review is the slow part — a reasoning model looking at
+ * screenshots, most of a minute — so each app gets one per turn: a look after
+ * the fixes only re-runs the fast checks. A review that failed (busy model,
+ * empty reply) gets one more try on the next look, then is let go.
+ */
+const reviews = new Map(); // base URL -> { done, tries }
+
+/** A new request from the user: the apps may be reviewed afresh. */
+export function forgetReviews() {
+  reviews.clear();
+}
+
+export async function lookAtApp({ url, paths = ['/'] }) {
   const base = String(url ?? '').trim().replace(/\/+$/, '');
   if (!LOCAL.test(`${base}/`)) {
     throw new ToolFailure({
@@ -167,76 +198,104 @@ export async function lookAtApp({ url, paths = ['/'], review: wantReview = true
   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)}`); });
+  // Every page at every width opens at once, each in its own context: the
+  // wait is for the slowest one, not the sum of them all.
+  const checks = await Promise.all(pages.flatMap((pagePath) => WIDTHS.map(async (size) => {
+    let problems = 0;
+    let shot = null;
+    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 target = `${base}${pagePath}`;
+    let loadError = null;
+    try {
+      // 'load', not 'networkidle': a dev server holds a hot-reload
+      // connection open and polls, so the network may never go quiet and
+      // 'networkidle' would wait out its whole timeout on every page, at
+      // every width. 'load' covers the first-request compile; the page's own
+      // data then gets a short, bounded chance to settle.
+      await page.goto(target, { waitUntil: 'load', timeout: 90_000 });
+      await page.waitForLoadState('networkidle', { timeout: 1_500 }).catch(() => {});
+    } catch (err) {
+      loadError = String(err.message).split('\n')[0];
+    }
+    await page.waitForTimeout(400); // let entrance animations settle
 
-      const file = path.join(shotsDir, `${safeName(pagePath)}-${size.name}.jpg`);
-      let facts = null;
+    const file = path.join(shotsDir, `${safeName(pagePath)}-${size.name}.jpg`);
+    let facts = null;
+    try {
       if (!loadError) {
         facts = await page.evaluate(inspect).catch((err) => ({ error: err.message }));
-        const buffer = await page.screenshot({ type: 'jpeg', quality: 70, fullPage: false });
+        // The whole page, so the reviewer never reports as missing what is
+        // only below the fold — capped, so an endless feed stays one image.
+        const tall = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
+        const buffer = await page.screenshot({
+          type: 'jpeg',
+          quality: 70,
+          fullPage: true,
+          ...(tall > MAX_SHOT_HEIGHT ? { clip: { x: 0, y: 0, width: size.width, height: MAX_SHOT_HEIGHT } } : {}),
+        });
         await fs.writeFile(file, buffer);
-        toReview.push({ label: `${pagePath} at ${size.width}px (${size.name})`, dataUrl: `data:image/jpeg;base64,${buffer.toString('base64')}` });
+        shot = { label: `${pagePath} at ${size.width}px (${size.name})`, dataUrl: `data:image/jpeg;base64,${buffer.toString('base64')}` };
       }
-      await context.close();
+    } catch (err) {
+      loadError = `the page broke while being checked: ${String(err.message).split('\n')[0]}`;
+    } finally {
+      await context.close().catch(() => {});
+    }
 
-      const lines = [`### ${pagePath} at ${size.width}px (${size.name})`];
-      if (loadError) {
-        lines.push(`Could not load: ${loadError}`);
+    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++;
-      } 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'));
+      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.');
+    const broken = Boolean(loadError || errors.length || facts?.empty);
+    return { section: lines.join('\n'), shot, problems, broken };
+  })));
+
+  const sections = checks.map((c) => c.section);
+  const toReview = checks.map((c) => c.shot).filter(Boolean);
+  const problems = checks.reduce((n, c) => n + c.problems, 0);
+  const broken = checks.some((c) => c.broken);
 
+  // A page that crashed or threw is fixed first; reviewing a screenshot of an
+  // error overlay is a minute spent on nothing.
   let critique = '';
-  if (wantReview !== false && toReview.length) {
+  const state = reviews.get(base) ?? { done: false, tries: 0 };
+  if (!broken && !state.done && state.tries < 2 && toReview.length) {
+    state.tries++;
+    reviews.set(base, state);
     try {
       critique = await review(toReview.slice(0, 4));
+      state.done = true;
     } catch (err) {
-      critique = `(The visual review could not run: ${err.failed ?? err.message}. The checks above still apply.)`;
+      const why = String(err.failed ?? err.message).replace(/[.\s]+$/, '');
+      critique = `(The visual review could not run: ${why}. The checks above still apply.)`;
     }
   }
 
@@ -246,7 +305,10 @@ export async function lookAtApp({ url, paths = ['/'], review: wantReview = true
     '',
     problems
       ? 'Fix the problems above, then look again to confirm.'
-      : 'The automatic checks found nothing. Weigh the visual review, fix what is worth fixing.',
+      : state.done && critique
+        ? 'The automatic checks found nothing. Weigh the visual review, fix what is worth fixing - ' +
+          'the next look re-runs only the fast checks.'
+        : 'The automatic checks found nothing.',
   ].filter(Boolean).join('\n\n');
 
   return result(

package/src/tools/cache.js

@@ -0,0 +1,105 @@
+/**
+ * cache.js — the starter's packages, installed once and reused.
+ *
+ * A new app's `npm install` is a minute of the model waiting on the network
+ * for a tree it has installed a hundred times before. The first install of a
+ * starter is kept in ~/.ucode/cache, keyed by the lockfile, and every app
+ * after that gets it as hard links: the same files on disk under a new name,
+ * so it costs no extra space and finishes in seconds.
+ *
+ * Hard links rather than a junction or a symlink, because Turbopack refuses a
+ * node_modules that points outside the project. Anything that cannot be linked
+ * — another drive, a filesystem without links — is copied instead, and if even
+ * that fails the normal install runs as before.
+ *
+ * A cache entry is only used once its marker file is there, which is written
+ * last: a half-written cache from an interrupted copy is ignored, not used.
+ *
+ * The key is the *starter's* lockfile, never the app's. npm rewrites an app's
+ * package-lock.json as it installs, so keying on that would file the cache
+ * under one name and look it up under another — a cache that never hits and
+ * never says why.
+ */
+
+import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+const MARKER = '.ucode-complete';
+
+/** Written into node_modules by build tools; never worth carrying between apps. */
+const NOT_WORTH_KEEPING = new Set(['.cache', '.vite', '.turbo']);
+
+export const cacheRoot = (home = os.homedir()) => path.join(home, '.ucode', 'cache');
+
+/** Where this starter's install lives, given its lockfile text. */
+export function slotFor(template, lockText, home) {
+  const hash = createHash('sha1').update(String(lockText ?? '')).digest('hex').slice(0, 12);
+  return path.join(cacheRoot(home), `${template}-${hash}`);
+}
+
+/**
+ * Copy a tree as hard links, falling back to real copies where linking fails.
+ * `skip` names top-level entries to leave behind.
+ */
+export async function linkTree(from, to, skip = null) {
+  let files = 0;
+  const walk = async (src, dst, top) => {
+    await fs.mkdir(dst, { recursive: true });
+    for (const entry of await fs.readdir(src, { withFileTypes: true })) {
+      if (top && skip?.has(entry.name)) continue;
+      const a = path.join(src, entry.name);
+      const b = path.join(dst, entry.name);
+      if (entry.isDirectory()) {
+        await walk(a, b, false);
+      } else if (entry.isSymbolicLink()) {
+        const target = await fs.readlink(a).catch(() => null);
+        if (target) await fs.symlink(target, b).catch(() => fs.copyFile(a, b).catch(() => {}));
+      } else {
+        await fs.link(a, b).catch(() => fs.copyFile(a, b));
+        files++;
+      }
+    }
+  };
+  await walk(from, to, true);
+  return files;
+}
+
+/**
+ * Put the cached packages into the app, if this starter has been installed
+ * before. Returns how many files were linked, or 0 when there is no cache.
+ */
+export async function restore(appDir, template, lockText, { home } = {}) {
+  if (!lockText) return 0;
+  const slot = slotFor(template, lockText, home);
+  if (!(await fs.stat(path.join(slot, MARKER)).catch(() => null))) return 0;
+  const target = path.join(appDir, 'node_modules');
+  if (await fs.stat(target).catch(() => null)) return 0; // already installed
+  try {
+    return await linkTree(path.join(slot, 'node_modules'), target);
+  } catch {
+    await fs.rm(target, { recursive: true, force: true }).catch(() => {});
+    return 0; // a partial restore is worse than none: let npm do it
+  }
+}
+
+/**
+ * Keep this app's node_modules as the cache for its starter, so the next app
+ * starts from it. Runs after a successful install and never throws.
+ */
+export async function populate(appDir, template, lockText, { home } = {}) {
+  try {
+    if (!lockText) return false;
+    const slot = slotFor(template, lockText, home);
+    if (await fs.stat(path.join(slot, MARKER)).catch(() => null)) return false;
+    const from = path.join(appDir, 'node_modules');
+    if (!(await fs.stat(from).catch(() => null))) return false;
+    await fs.rm(slot, { recursive: true, force: true }).catch(() => {});
+    await linkTree(from, path.join(slot, 'node_modules'), NOT_WORTH_KEEPING);
+    await fs.writeFile(path.join(slot, MARKER), `${template}\n${new Date().toISOString()}\n`);
+    return true;
+  } catch {
+    return false; // the cache is an optimisation; never let it break a build
+  }
+}

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`
+  );
+}