ucode-agent 1.40.0 → 1.41.0

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.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

@@ -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',

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