ucode-agent 1.26.1 → 1.27.0

package/README.md

@@ -137,13 +137,21 @@ model fixes them without being told.
 hard-linked into the next app — the same files under another name, so it costs
 no extra disk and skips the wait entirely.
 
-**Apps start from a ready-made starter.** Setting up Next.js and shadcn from
-nothing takes about four minutes — `create-next-app` and the shadcn CLI measured
-at 116s and 130s — plus a dozen model round trips. `create_app` copies ucode's
-starter instead: Next.js 16, TypeScript, Tailwind 4, shadcn/ui with 25 common
-components, light/dark mode, toasts and a considered theme, already known to
-build. The copy takes under a second, and its install runs in the background
-while the model writes the first components.
+**Apps start from a ready-made starter — and finish in the same call.**
+`create_app` copies a starter that is already known to build, and takes the
+app's files with it, so a one-page app is a single round trip: the starter
+lands, the model's files are written over it, and the starter's own files come
+back inside the result so there is nothing to read afterwards.
+
+The default starter is `plain-html`: one page, one stylesheet, one module,
+nothing to install and nothing to build. A tasks app, a game, a calculator or a
+visualisation is finished before a framework would have finished installing.
+`next-shadcn` is there for routes, a database or many screens — Next.js 16,
+TypeScript, Tailwind 4, shadcn/ui with 25 components, light/dark, toasts and a
+considered theme. Setting that up by hand is about four minutes
+(`create-next-app` and the shadcn CLI measured at 116s and 130s) plus a dozen
+round trips; the copy takes under a second, and its install runs in the
+background while the model writes the first components.
 
 **Built to be fast, and measured.** A traced build of a small Next.js app went
 from 17 minutes and 116 model steps to about 6 minutes and 25 steps, by fixing
@@ -161,10 +169,31 @@ where the time actually went:
   command fixes it.
 - The starter is the shadcn models already know (Radix), so the code they write
   compiles the first time.
+- A new app goes out without the tools it has nothing to point at — no symbol
+  lookup, no rename, no type query in an empty folder — and an instruction pack
+  that loads itself sends its short form, with the full one a `load_skill`
+  away. Both are re-read by the provider on every step, so what is not in the
+  request is time off every one of them.
+- Ready-made blocks for a page with no build step as well as for React: a list you
+  can add to, tick off, rename and remove, a filter row, a localStorage store, a
+  dialog, toasts, a theme toggle. Typing is the slowest part of a build, and each
+  block is a hundred lines nobody has to type.
+- A nested argument written the wrong way — a JSON string, a { path: contents } map
+  — is read rather than refused. Each refusal was a round trip spent being told
+  something that could simply be parsed.
+- A tool that was not offered is refused rather than quietly run, so withholding one
+  from a new project, or from plan mode, means what it says.
+- The closing message is cut to eight lines. A build that ends with the request
+  read back and every feature ticked off is a status report nobody asked for,
+  and it is the last thing left on screen.
 
 `UCODE_TRACE=1` writes every model call and tool, with its duration, to
 `~/.ucode/trace.jsonl`.
 
+Measured on "build me a simple todo app" — same prompt, same model, two traced
+runs: **27 model calls, 8 failed tool calls, no finished app** before this round of
+work; **14 model calls, no failures, a working app in under two minutes** after it.
+
 **Deploy in one line.** Say "deploy it", or type `/deploy [folder]`, and the app
 goes live on Vercel. ucode picks a short project name that fits the app and is
 free (`food-iq`, else `food-iq-app`…), copies the app's `.env` keys to Vercel as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.26.1",
+  "version": "1.27.0",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code, on NVIDIA and Cohere models.",
   "type": "module",
   "main": "ucode.js",

package/skills/build-app/DIGEST.md

@@ -0,0 +1,94 @@
+# Building something from nothing — the short form
+
+The failure mode is not bad code. It is a folder of files that has never been
+run, handed over as if it works.
+
+## 1. Decide the shape before any file exists
+
+One line each: **what it does**, **the core loop** (the one path that must work
+perfectly), **the stack**, **the file list**.
+
+| Need | Choose |
+| --- | --- |
+| One page, no secrets, no server | `create_app` with `plain-html` |
+| Interactive client app, no secrets | `plain-html` still, unless it truly needs a build |
+| Pages plus a server, secrets, API routes, SEO | `create_app` with `next-shadcn` |
+| An API on its own | Node (Hono/Express) or Python (FastAPI) |
+
+Pick the smallest one that does the job and mean it: a tasks app, a
+calculator, a timer, a game, a visualisation — all one page. Next.js costs an
+install and a build, minutes the user waits through, and buys nothing an app
+with no server needs.
+
+## 2. Start from the starter — and finish in the same call
+
+`create_app` takes `files`, so for a one-page app the scaffold and the whole
+app are one call:
+
+```
+create_app({ folder: "tide", name: "Tide", files: [
+  { path: "tide/index.html", content: "…" },
+  { path: "tide/styles.css", content: "…" },
+  { path: "tide/app.js",     content: "…" },
+]})
+```
+
+Every round trip is ten to forty seconds of the user's time, so one call
+instead of four is most of how long the build takes.
+
+- `plain-html` is the default: three files, no install, no build. Its files
+  come back in full inside the result — **never read them back**.
+- `next-shadcn` installs in the background; commands in that folder wait for
+  it on their own, so start writing components at once. Re-tint `globals.css`
+  for the app's direction rather than shipping the slate default.
+- Never run `create-next-app` or `shadcn init`. Nothing you run has a
+  keyboard: every scaffolder needs its answers as flags up front.
+
+## 2b. Do not type what already exists
+
+`add_block` has the pieces every app needs, written for whichever starter this
+one uses: a list you can add to, tick off, rename and remove; a filter row; a
+localStorage store; a dialog; toasts; a theme toggle; a table; an empty state.
+Call it before writing any of those by hand. Each is a hundred lines you skip,
+and typing is the slowest part of a build — a page assembled from blocks is
+done minutes before the same page typed out. Call `add_block` with no name to
+see what fits this app.
+
+## 3. Structure
+
+One component per file, named for what it is, not a 600-line `page.tsx`. In
+Next.js: `src/app` (routes, `globals.css`, `api/<name>/route.ts`),
+`src/components/<feature>/`, `src/lib/` for outside services and schemas.
+Server components by default, `"use client"` only where it is interactive.
+Types at every boundary; parse external data rather than trusting its shape.
+
+## 4. Secrets and outside services
+
+- **A key never reaches the browser.** It lives in a server route. Anything
+  imported by a `"use client"` file ships to every visitor, including a
+  "hardcoded for now" key — put it in a server-only module and say where.
+- Every outbound call gets a timeout (`AbortSignal.timeout(60_000)`), a status
+  check, and an error that says what failed — surfaced as a real message,
+  never a silent `catch {}`.
+- Calling a model: ask for JSON and parse it defensively (extract the first
+  `{...}`, validate, clamp numbers), put the judgement rules in the prompt
+  explicitly, and make the route timeout longer than the model takes.
+
+## 5. Build order
+
+Skeleton and design tokens first, so everything after is styled correctly the
+first time; then the server route with the real integration; then the core
+loop UI wired to it; then every state — empty, loading, success, error,
+invalid input; then polish: motion, responsive, copy, title and metadata.
+
+## 6. Prove it works, then report
+
+`npm run build` type-checks and lints — a build that fails is not done. Start
+it (`npm run dev` backgrounds itself and returns the URL; do not start it
+twice), then `look_at_app` on every page. A clean build proves it compiles,
+not that it works. Fix what you find and check again.
+
+Done means: the core loop works end to end, no TODO, no placeholder copy, no
+dead buttons, no console errors, every async action has its states, secrets
+server-side, build passes. Then say what you built, how to run it, and — in
+one sentence — anything you did not finish or could not test.

package/skills/build-app/SKILL.md

@@ -1,181 +1,222 @@
----
-name: build-app
-description: Take an app from nothing to running and finished — stack choice, non-interactive scaffolding, project structure, secrets, AI and API integration, error handling, and proving it works before saying it does.
-auto: scaffold, new project, from scratch, build an app, make an app, create an app, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app, full stack, fullstack, saas, mvp
----
-
-# Building something from nothing
-
-The failure mode is not bad code. It is a folder of files that has never been
-run, handed over as if it works. Everything here is ordered to prevent that.
-
-## 1. Decide the shape, out loud, before any file exists
-
-One line each:
-
-- **What it does** — the sentence a user would say.
-- **The core loop** — the one path through it that must work perfectly
-  (e.g. upload a photo → analysed → see a score and the problems).
-- **The stack, and why** — the smallest thing that does the job:
-
-  | Need | Choose |
-  | --- | --- |
-  | One page, no secrets, no server | a single `index.html`, no build step |
-  | Interactive client app, no secrets | Vite + React + TypeScript |
-  | Pages plus a server, secrets, API routes, SEO | Next.js App Router + TypeScript |
-  | An API on its own | Node (Hono/Express) or Python (FastAPI) |
-
-- **The file list** — the whole tree, before creating any of it.
-
-If there is a user interface, the `ui-ux` skill is already loaded. Decide the
-design direction now, not after the logic works. If the app calls a model,
-load `ai-features`; if it has accounts, keys or uploads, load `security`.
-
-## 2. Start from the starter
-
-**For a Next.js app, call `create_app`** — one step, about a second:
-
-```
-create_app({ folder: "my-app", name: "My App", description: "…" })
-```
-
-It copies ucode's ready-made starter — Next.js 16, TypeScript, Tailwind 4,
-shadcn/ui with 25 common components, light/dark mode, toasts, a considered
-theme — which is already known to build, and starts `npm install` in the
-background. Read the `TEMPLATE.md` it lists, then start writing components
-straight away; commands in that folder wait for the install on their own.
-Re-tint the palette in `globals.css` and swap the font for the app's direction.
-
-Never run `create-next-app` or `shadcn init` for a Next.js app — that is
-four minutes and a dozen steps the starter already did.
-
-### Other stacks
-
-Nothing you run has a keyboard. A scaffolder that asks "Would you like to use
-TypeScript?" gets no answer and fails, so give it every answer up front:
-
-```bash
-# Next.js into ./my-app (use . to fill the current folder — it must be empty)
-npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm --yes
-
-# shadcn/ui, from inside the project — every component you need, in one add
-npx shadcn@latest init -d -y
-npx shadcn@latest add button card input label badge progress separator skeleton sonner tooltip -y
-```
-
-- `create-next-app` refuses a folder that already has files. If the current
-  folder is not empty, scaffold into a named subfolder and pass it as `cwd` to
-  every later command.
-- For any other scaffolder, find the flag for every question (`--help`) first.
-- Install dependencies once, all together: `npm i zod lucide-react` — not one
-  `npm i` per package.
-
-## 3. Structure it like a real project
-
-For Next.js App Router:
-
-```
-src/
-  app/
-    layout.tsx          fonts, metadata, <body> shell, Toaster
-    page.tsx            the screen — composes components, holds little logic
-    globals.css         design tokens and the shadcn theme variables
-    api/<name>/route.ts server-only endpoints; the only place secrets live
-  components/
-    <feature>/          one folder per feature: its pieces, split by job
-    ui/                 shadcn components (generated — edit via the theme)
-  lib/
-    <service>.ts        calls to outside services, typed in and out
-    schemas.ts          zod schemas shared by client and server
-    utils.ts
-  types/                shared TypeScript types, if lib/ does not own them
-```
-
-- **One component per file**, named for what it is (`ScoreDial.tsx`,
-  `NutrientFindings.tsx`, `LabelUpload.tsx`), not a 600-line `page.tsx`.
-- Server components by default; `"use client"` only on the interactive parts.
-- Types at every boundary. Parse external data with zod rather than trusting
-  its shape.
-
-## 4. Secrets and outside services
-
-- **A key never reaches the browser.** It lives in a server route or server
-  action. Anything imported by a `"use client"` file ships to every visitor —
-  including a "hardcoded for now" key. If the user asks to hardcode one, put it
-  in a server-only module (`lib/server/*.ts`, or `import 'server-only'`) and
-  say where it is so they can move it to `.env.local` later.
-- Every outbound call gets: a timeout (`AbortSignal.timeout(60_000)`), a check
-  of the response status, and an error that says what failed — surfaced to the
-  UI as a real message, never a silent `catch {}`.
-
-### Calling an AI model (any OpenAI-compatible API)
-
-```ts
-// src/app/api/analyze/route.ts — runs on the server only
-export const runtime = 'nodejs';
-export const maxDuration = 60;
-
-const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
-  method: 'POST',
-  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    model: 'provider/model-id',
-    messages: [
-      { role: 'system', content: 'Reply with JSON only, matching this shape: {...}' },
-      { role: 'user', content: [
-        { type: 'text', text: 'Analyse this nutrition label.' },
-        { type: 'image_url', image_url: { url: dataUrl } },   // data:image/jpeg;base64,...
-      ] },
-    ],
-  }),
-  signal: AbortSignal.timeout(60_000),
-});
-```
-
-- **Ask for JSON and parse it defensively.** Models wrap JSON in prose or code
-  fences: extract the first `{...}` block, `JSON.parse` it, validate with zod,
-  and on failure return a clear "could not read the result" error rather than
-  crashing. Clamp numbers to their range.
-- **Put the judgement rules in the prompt, explicitly** — thresholds, what
-  counts as "too much", what to omit. A vague prompt gives a different answer
-  every time; a specific one gives the product its consistency.
-- **Images:** check type and size on the client (e.g. ≤ 5 MB, jpeg/png/webp),
-  downscale large photos in a canvas before upload, send as a base64 data URL.
-- Reasoning models may take 10–60s. Show progress, and make the route's
-  timeout longer than the model's.
-
-## 5. Build order
-
-1. Skeleton and design tokens, so every later piece is styled correctly first time.
-2. The server route with the real integration, tested with `curl` before any UI.
-3. The core loop UI, wired to the real route.
-4. Every state: empty, loading, success, error, and invalid input.
-5. Polish: motion, responsive, copy, favicon, page title and metadata.
-
-Use `batch_write` for the skeleton — one call, every file.
-
-## 6. Prove it works
-
-- `npm run build` — it type-checks and lints; a build that fails is not done.
-- Start it: `npm run dev` goes to the background on its own and comes back with
-  the URL once ready. Do not start it twice.
-- Exercise it: `curl` the API route with real input, then `look_at_app` on every
-  page — it loads them in a real browser at phone and desktop width and reports
-  errors, overflow and a visual review. A clean build proves it compiles, not
-  that it works.
-- Fix what you find and check again.
-
-## 7. Definition of done
-
-- The core loop works end to end against the real service.
-- No `TODO`, no placeholder copy, no dead buttons, no console errors.
-- Every async action has loading, success and error states.
-- Invalid input is caught with a useful message before it reaches the server.
-- Secrets only on the server.
-- `npm run build` passes.
-
-## 8. Report
-
-What you built, the URL, how to start it again, and what you checked. If
-anything is untested or unfinished, name it — one sentence of honesty saves the
-user an hour of finding out on their own.
+---
+name: build-app
+description: Take an app from nothing to running and finished — stack choice, non-interactive scaffolding, project structure, secrets, AI and API integration, error handling, and proving it works before saying it does.
+auto: scaffold, new project, from scratch, build an app, make an app, create an app, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app, full stack, fullstack, saas, mvp
+---
+
+# Building something from nothing
+
+The failure mode is not bad code. It is a folder of files that has never been
+run, handed over as if it works. Everything here is ordered to prevent that.
+
+## 1. Decide the shape, out loud, before any file exists
+
+One line each:
+
+- **What it does** — the sentence a user would say.
+- **The core loop** — the one path through it that must work perfectly
+  (e.g. upload a photo → analysed → see a score and the problems).
+- **The stack, and why** — the smallest thing that does the job:
+
+  | Need | Choose |
+  | --- | --- |
+  | One page, no secrets, no server | `create_app` with the `plain-html` starter |
+  | Interactive client app, no secrets | `plain-html` still, unless it truly needs a build |
+  | Pages plus a server, secrets, API routes, SEO | `create_app` with `next-shadcn` |
+  | An API on its own | Node (Hono/Express) or Python (FastAPI) |
+
+  Choose the smallest one that does the job, and mean it: a tasks app, a
+  calculator, a timer, a game, a visualisation, a converter — all one page.
+  Next.js costs an install and a build, minutes the user waits through, and
+  buys nothing an app with no server needs.
+
+- **The file list** — the whole tree, before creating any of it.
+
+If there is a user interface, the `ui-ux` skill is already loaded. Decide the
+design direction now, not after the logic works. If the app calls a model,
+load `ai-features`; if it has accounts, keys or uploads, load `security`.
+
+## 2. Start from the starter — and finish in the same call
+
+`create_app` copies a starter that is already known to build. It also takes
+`files`, so for a one-page app the scaffold and the whole app are one call:
+
+```
+create_app({
+  folder: "tide", name: "Tide", description: "…",
+  files: [
+    { path: "tide/index.html", content: "…" },
+    { path: "tide/styles.css", content: "…" },
+    { path: "tide/app.js",     content: "…" },
+  ],
+})
+```
+
+That is the whole build. Every round trip is ten to forty seconds of the
+user's time, so the difference between one call and four is most of how long
+this takes.
+
+- **`plain-html` is the default**: three files, no install, no build, opens in
+  a browser. Its files come back in full inside the result — **never read them
+  back**, they are already in front of you.
+- **`next-shadcn`** only when the app needs routes, a database or many
+  screens. It copies Next.js 16, TypeScript, Tailwind 4 and shadcn with its
+  components, light/dark and toasts, and starts `npm install` in the
+  background — commands in that folder wait for the install on their own, so
+  start writing components at once. Read the `TEMPLATE.md` in the result, and
+  re-tint `globals.css` for the app's direction.
+
+Never run `create-next-app` or `shadcn init` — that is four minutes and a
+dozen steps the starter already did.
+
+### Other stacks
+
+Nothing you run has a keyboard. A scaffolder that asks "Would you like to use
+TypeScript?" gets no answer and fails, so give it every answer up front:
+
+```bash
+# Next.js into ./my-app (use . to fill the current folder — it must be empty)
+npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm --yes
+
+# shadcn/ui, from inside the project — every component you need, in one add
+npx shadcn@latest init -d -y
+npx shadcn@latest add button card input label badge progress separator skeleton sonner tooltip -y
+```
+
+- `create-next-app` refuses a folder that already has files. If the current
+  folder is not empty, scaffold into a named subfolder and pass it as `cwd` to
+  every later command.
+- For any other scaffolder, find the flag for every question (`--help`) first.
+- Install dependencies once, all together: `npm i zod lucide-react` — not one
+  `npm i` per package.
+
+## 2b. Do not type what already exists
+
+`add_block` has the pieces every app needs, written once and carefully, for
+whichever starter this app uses. For a plain page: `item-list` (add, tick off,
+rename, remove, empty state, counts, keyboard), `filter-bar`, `store`
+(localStorage that survives private mode and stays in step across tabs),
+`modal`, `toast`, `theme-toggle`. For React: `app-shell`, `page-header`,
+`empty-state`, `data-table`, `stat-cards`.
+
+Call it before writing any of those by hand. Two reasons, and the second is
+the one that gets forgotten:
+
+- They are finished. Every state, the keyboard, small screens, the cases a
+  first draft skips.
+- They are already typed. Typing is the slowest part of a build — a few
+  thousand tokens at forty a second — so a page assembled from blocks is done
+  minutes before the same page written out line by line.
+
+They land as ordinary source files. Edit them to suit the app rather than
+working around them.
+
+## 3. Structure it like a real project
+
+For Next.js App Router:
+
+```
+src/
+  app/
+    layout.tsx          fonts, metadata, <body> shell, Toaster
+    page.tsx            the screen — composes components, holds little logic
+    globals.css         design tokens and the shadcn theme variables
+    api/<name>/route.ts server-only endpoints; the only place secrets live
+  components/
+    <feature>/          one folder per feature: its pieces, split by job
+    ui/                 shadcn components (generated — edit via the theme)
+  lib/
+    <service>.ts        calls to outside services, typed in and out
+    schemas.ts          zod schemas shared by client and server
+    utils.ts
+  types/                shared TypeScript types, if lib/ does not own them
+```
+
+- **One component per file**, named for what it is (`ScoreDial.tsx`,
+  `NutrientFindings.tsx`, `LabelUpload.tsx`), not a 600-line `page.tsx`.
+- Server components by default; `"use client"` only on the interactive parts.
+- Types at every boundary. Parse external data with zod rather than trusting
+  its shape.
+
+## 4. Secrets and outside services
+
+- **A key never reaches the browser.** It lives in a server route or server
+  action. Anything imported by a `"use client"` file ships to every visitor —
+  including a "hardcoded for now" key. If the user asks to hardcode one, put it
+  in a server-only module (`lib/server/*.ts`, or `import 'server-only'`) and
+  say where it is so they can move it to `.env.local` later.
+- Every outbound call gets: a timeout (`AbortSignal.timeout(60_000)`), a check
+  of the response status, and an error that says what failed — surfaced to the
+  UI as a real message, never a silent `catch {}`.
+
+### Calling an AI model (any OpenAI-compatible API)
+
+```ts
+// src/app/api/analyze/route.ts — runs on the server only
+export const runtime = 'nodejs';
+export const maxDuration = 60;
+
+const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    model: 'provider/model-id',
+    messages: [
+      { role: 'system', content: 'Reply with JSON only, matching this shape: {...}' },
+      { role: 'user', content: [
+        { type: 'text', text: 'Analyse this nutrition label.' },
+        { type: 'image_url', image_url: { url: dataUrl } },   // data:image/jpeg;base64,...
+      ] },
+    ],
+  }),
+  signal: AbortSignal.timeout(60_000),
+});
+```
+
+- **Ask for JSON and parse it defensively.** Models wrap JSON in prose or code
+  fences: extract the first `{...}` block, `JSON.parse` it, validate with zod,
+  and on failure return a clear "could not read the result" error rather than
+  crashing. Clamp numbers to their range.
+- **Put the judgement rules in the prompt, explicitly** — thresholds, what
+  counts as "too much", what to omit. A vague prompt gives a different answer
+  every time; a specific one gives the product its consistency.
+- **Images:** check type and size on the client (e.g. ≤ 5 MB, jpeg/png/webp),
+  downscale large photos in a canvas before upload, send as a base64 data URL.
+- Reasoning models may take 10–60s. Show progress, and make the route's
+  timeout longer than the model's.
+
+## 5. Build order
+
+1. Skeleton and design tokens, so every later piece is styled correctly first time.
+2. The server route with the real integration, tested with `curl` before any UI.
+3. The core loop UI, wired to the real route.
+4. Every state: empty, loading, success, error, and invalid input.
+5. Polish: motion, responsive, copy, favicon, page title and metadata.
+
+Use `batch_write` for the skeleton — one call, every file.
+
+## 6. Prove it works
+
+- `npm run build` — it type-checks and lints; a build that fails is not done.
+- Start it: `npm run dev` goes to the background on its own and comes back with
+  the URL once ready. Do not start it twice.
+- Exercise it: `curl` the API route with real input, then `look_at_app` on every
+  page — it loads them in a real browser at phone and desktop width and reports
+  errors, overflow and a visual review. A clean build proves it compiles, not
+  that it works.
+- Fix what you find and check again.
+
+## 7. Definition of done
+
+- The core loop works end to end against the real service.
+- No `TODO`, no placeholder copy, no dead buttons, no console errors.
+- Every async action has loading, success and error states.
+- Invalid input is caught with a useful message before it reaches the server.
+- Secrets only on the server.
+- `npm run build` passes.
+
+## 8. Report
+
+What you built, the URL, how to start it again, and what you checked. If
+anything is untested or unfinished, name it — one sentence of honesty saves the
+user an hour of finding out on their own.