ucode-agent 1.40.0 → 1.41.1

package/README.md

@@ -27,7 +27,7 @@ corner:
          add a dark mode toggle that remembers the choice
 
 
-                                                                           v1.36.0
+                                                                           v1.41.0
 ```
 
 A light crosses the wordmark once as it opens, and the three lines under the box

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.40.0",
+  "version": "1.41.1",
   "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

@@ -1,94 +1,121 @@
-# 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.
+# 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.
+
+## 2a. Paths in `files` are not the paths in the page
+
+The two are relative to different things, and getting them confused is the
+commonest way a finished build comes up as bare markup. `files` paths are
+relative to the **project root**, so they carry the app folder. A link inside a
+page is relative to **that page**, so it must not.
+
+```
+create_app({ folder: "tide", name: "Tide", files: [
+  { path: "tide/index.html", content: "... <link rel=stylesheet href=\"styles.css\">
+                                            <script type=module src=\"app.js\"></script> ..." },
+  { path: "tide/styles.css", content: "..." },
+  { path: "tide/app.js",     content: "..." },
+]})
+```
+
+Wrong, and it 404s: `href="tide/styles.css"` inside `tide/index.html` — the
+browser resolves that to `tide/tide/styles.css`, so no stylesheet and no script
+load, and the page is unstyled markup with dead buttons.
+
+## 2b. Look before you create
+
+`create_app` refuses a folder that already has something in it unless you pass
+the app in `files` — and a folder you half-made on an earlier attempt counts.
+One `list_dir` in front of it costs a second and tells you whether you are
+starting or resuming. The same goes for any command that makes a directory.
+
+## 2c. 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/src/core/loop.js

@@ -634,6 +634,24 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '',
 
     '',
+    '',
+    'NEVER ASSUME A LIBRARY IS THERE. Not React, not lodash, not a component kit,',
+    'however well known it is. Check what this project already uses before you reach',
+    'for it: its package.json, the file next to the one you are writing, what the',
+    'starter actually shipped. The plain-html starter has no build step and no',
+    'packages at all, so JSX, TypeScript and bare module imports are not syntax it',
+    'can run — a JSX tag in a plain module is a page that renders nothing and one',
+    'unexpected-token error in the console. Write what the project can execute.',
+    '',
+    'CALL TOOLS TOGETHER WHEN THEY DO NOT DEPEND ON EACH OTHER. Several can go in',
+    'one reply and they run at the same time. Six files is one read_files in one',
+    'message, never six read_file calls in six — each of those is a round trip you',
+    'and the user sit through. Same for independent searches, same for commands',
+    'that do not feed each other.',
+    '',
+    'POINT AT CODE AS file:line. The filter is built in src/app.js:42 — not in the',
+    'app file somewhere near the filter. One of those the reader can open; the',
+    'other they have to go hunting from.',
     'Before you guess at an API, ask: type_of gives the exact signature from the',
     'TypeScript this project has installed, and find_symbol says where something is declared without',
     'reading five files to find it. Rename with rename_symbol rather than edit_file — a',
@@ -1087,6 +1105,7 @@ export class Agent {
     this.lookedThisTurn = false;
     this.reads = new Map();
     this.declines = 0;
+    this.apps = [];
     forgetReviews(); // a new request: its apps get a fresh design review
     const images = await this.attachImages(input);
     this.push(images.length
@@ -1664,6 +1683,13 @@ export class Agent {
     // a designer's review, and now the app actually driven — and it was the
     // quietest line on screen, saying only that it had happened. Its verdict
     // goes on the same line, the way a change carries its two numbers.
+    // Which app folders this turn actually made, so a second one can be
+    // refused before it is built and any leftovers can be counted at the end.
+    if (call.name === 'create_app' && call.args?.folder) {
+      const made = path.resolve(this.cwd, String(call.args.folder));
+      if (!(this.apps ??= []).includes(made)) this.apps.push(made);
+    }
+
     if (call.name === 'look_at_app') {
       const found = /^(\d+) problem/.exec(out.summary ?? '');
       this.ui.runStat?.(found ? `${found[1]} to fix` : 'clean');
@@ -1766,6 +1792,30 @@ export class Agent {
       this.reads.set(key, seen + 1);
     }
 
+    // Starting a second app instead of fixing the first.
+    //
+    // A traced build hit a problem in todo/, abandoned it and made todo-fixed/
+    // — three create_app calls, two folders, one broken, the app typed twice.
+    // Starting over is never the cheap way out of a problem in a file, and it
+    // leaves the user to work out which folder is the real one.
+    if (call.name === 'create_app' && call.args?.folder && (this.apps ?? []).length) {
+      const wanted = path.resolve(this.cwd, String(call.args.folder));
+      const already = this.apps.filter((f) => f !== wanted);
+      if (already.length && !this.apps.includes(wanted)) {
+        const show = already.map((f) => path.basename(f)).join(', ');
+        throw new ToolFailure({
+          kind: 'already_building',
+          attempted: `creating ${call.args.folder}`,
+          failed: `You already made ${show} this turn, and it is still there.`,
+          fix:
+            `Fix ${show} instead of starting again — whatever is wrong with it is a smaller `
+            + 'job than writing the whole app a second time, and a half-finished folder left '
+            + `beside the real one is worse than either. If ${show} genuinely cannot be saved, `
+            + 'delete it first, then create this one.',
+        });
+      }
+    }
+
     if (call.name === 'load_skill') return this.loadSkill(call.args?.name);
     if (call.name === 'update_plan') return this.updatePlan(call.args?.items);
     if (call.name === 'delegate') return this.delegate(call.args?.tasks);
@@ -2064,6 +2114,23 @@ export class Agent {
     const live = await this.liveErrors();
     if (live) problems.push(live);
 
+    // Two app folders, one of them abandoned.
+    //
+    // A build hit a problem in todo/, started todo-fixed/, then said in its
+    // reply that it had removed the duplicate — and had not. Both were still
+    // on disk for the user to sort out, and the claim that they were not is
+    // the failure this whole checking pass exists to catch: saying a thing is
+    // done when it is not. So it is checked rather than believed.
+    const apps = this.apps ?? [];
+    if (apps.length > 1) {
+      const names = apps.map((f) => path.basename(f));
+      problems.push(
+        `There are ${apps.length} app folders here now: ${names.join(', ')}. Only one of them is `
+        + 'the app. Delete the ones you are not shipping — actually delete them, do not just say '
+        + 'you have — and make sure the one you keep is the one that works.',
+      );
+    }
+
     // Then look at it, in the same pass that type-checks — not when the model
     // remembers to. A check that runs only when it is asked for reports
     // nothing on exactly the builds that needed it, and this is the only one

package/templates/plain-html/TEMPLATE.md

@@ -15,6 +15,21 @@ Open `index.html` in a browser, or serve the folder if the app fetches
 anything: `python -m http.server 8000`. There is nothing to install and
 nothing to compile, so a change is visible on refresh.
 
+## What this starter cannot run
+
+There is no build step, so there is no compiler to turn anything into browser
+JavaScript. That rules out, in `app.js` or any module it loads:
+
+- **JSX** — `render(<App />, root)` is a syntax error in a plain module. The
+  page renders nothing and the console says an unexpected token was found.
+- **TypeScript** — no types, no `interface`, no `as`.
+- **Bare imports** — `import React from "react"` has nowhere to resolve from.
+  Only relative paths (`./store.js`) and full URLs work.
+
+Write plain ES modules and DOM calls. If the app genuinely needs a framework,
+it needed `next-shadcn` instead, and that decision belongs before the first
+file, not after the page comes up blank.
+
 ## Conventions worth keeping
 
 - **One state object, one render.** Patching the DOM from several places is