ucode-agent 1.4.0 → 1.5.0

package/README.md

@@ -111,12 +111,20 @@ chosen model gets another go a few minutes later.
 
 ## What it does
 
-**Fourteen tools.** `read_file`, `read_files`, `write_file`, `batch_write`,
-`edit_file`, `multi_edit`, `edit_files`, `list_dir`, `glob`, `grep`,
-`run_command`, `run_commands`, `look_at_app`, `web_search`. Read-only calls run in parallel,
+**Fifteen tools.** `create_app`, `read_file`, `read_files`, `write_file`,
+`batch_write`, `edit_file`, `multi_edit`, `edit_files`, `list_dir`, `glob`,
+`grep`, `run_command`, `run_commands`, `look_at_app`, `web_search`. Read-only calls run in parallel,
 and start the moment the model finishes writing them — while the rest of its
 reply is still arriving. Anything that writes runs on its own, in order.
 
+**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.
+
 **Parallel workers.** When a build splits into parts that touch different files
 — the API route, the upload component, the results view — the model hands them
 to up to three workers that build at the same time, each line in the transcript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code, on NVIDIA and Cohere models.",
   "type": "module",
   "main": "ucode.js",
@@ -10,7 +10,8 @@
   "files": [
     "ucode.js",
     "src/",
-    "skills/"
+    "skills/",
+    "templates/"
   ],
   "scripts": {
     "start": "node ucode.js",

package/skills/build-app/SKILL.md

@@ -31,7 +31,25 @@ 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. Scaffold without being asked questions
+## 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:

package/src/core/loop.js

@@ -240,6 +240,8 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '  one at a time when you already know which ones you want.',
     '- Put independent calls in the same message — several greps, a glob and a read.',
     '  Read-only calls in one message run at the same time.',
+    '- New Next.js app? create_app - one step, never create-next-app or shadcn init. It',
+    '  copies a starter that already builds and installs it in the background.',
     '- batch_write to lay out several new files at once, multi_edit for several changes',
     '  to one file, edit_files for a change that spans several files.',
     '- For work with three or more steps, keep a short plan with update_plan - at most',

package/src/tools/index.js

@@ -9,6 +9,7 @@ import { listDir, glob, grep } from './search.js';
 import { runCommand, runCommands } from './shell.js';
 import { webSearch } from './web.js';
 import { lookAtApp } from './browser.js';
+import { createApp } from './scaffold.js';
 import { clip, READ_LINES } from './shared.js';
 
 export { setRoot, setConfirm, getRoot } from './shared.js';
@@ -18,6 +19,25 @@ const int = (description) => ({ type: 'integer', description });
 const bool = (description) => ({ type: 'boolean', description });
 
 export const tools = [
+  {
+    name: 'create_app',
+    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 ' +
+      'starts installing its packages in the background so you can write components at once. ' +
+      'The result lists everything included.',
+    parameters: {
+      type: 'object',
+      properties: {
+        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.'),
+      },
+      required: ['folder', 'name'],
+    },
+  },
   {
     name: 'read_file',
     description:
@@ -324,6 +344,7 @@ const run = {
   run_commands: runCommands,
   web_search: webSearch,
   look_at_app: lookAtApp,
+  create_app: createApp,
 };
 
 /** Tools that change the project or execute code. */
@@ -337,7 +358,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',
+  'delegate', 'create_app',
 ]);
 
 /** Tools that change files on disk, which parallel workers take turns at. */
@@ -460,6 +481,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 'create_app':
+      return `Creating ${clip(args.name || args.folder, 30)} from the Next.js starter`;
     case 'look_at_app':
       return `Looking at ${clip(args.url, 40)} on a phone and a desktop`;
     case 'web_search':

package/src/tools/scaffold.js

@@ -0,0 +1,130 @@
+/**
+ * scaffold.js — starting an app from a starter that is known to work.
+ *
+ * Setting up a Next.js + shadcn project from nothing is four minutes of
+ * create-next-app and shadcn CLI runs — measured at 116s and 130s — plus a
+ * dozen model round trips to drive them and then theme the result. Every app
+ * starts from the same place anyway, so ucode ships that place: a project
+ * that has already been built and type-checked, copied in one step, with its
+ * install starting in the background while the model writes the first
+ * component.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolFailure } from '../core/failure.js';
+import { resolveIn, guard, result } from './shared.js';
+import { packageJsonWritten } from './shell.js';
+
+const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+
+/** npm silently drops these two names from published packages, so they ship renamed. */
+const RENAME = { _gitignore: '.gitignore', '_package-lock.json': 'package-lock.json' };
+
+/** Files the placeholders are filled into. Everything else is copied byte for byte. */
+const TEXT = /\.(?:json|md|mjs|css|tsx?)$/i;
+
+export const TEMPLATE_NAMES = ['next-shadcn'];
+
+function slug(name) {
+  return String(name).toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'app';
+}
+
+/** Text that is safe inside a JS string and a JSON string. */
+const plain = (s) => String(s ?? '').replace(/["'`\\<>]/g, '').replace(/\s+/g, ' ').trim();
+
+async function copyTree(from, to, fill) {
+  await fs.mkdir(to, { recursive: true });
+  const copied = [];
+  for (const entry of await fs.readdir(from, { withFileTypes: true })) {
+    const name = RENAME[entry.name] ?? entry.name;
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, name);
+    if (entry.isDirectory()) {
+      copied.push(...(await copyTree(src, dest, fill)).map((f) => `${name}/${f}`));
+    } else if (TEXT.test(entry.name) || entry.name in RENAME) {
+      let text = await fs.readFile(src, 'utf8');
+      for (const [token, value] of Object.entries(fill)) text = text.split(token).join(value);
+      await fs.writeFile(dest, text, 'utf8');
+      copied.push(name);
+    } else {
+      await fs.copyFile(src, dest);
+      copied.push(name);
+    }
+  }
+  return copied;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.folder       new, empty folder for the app
+ * @param {string} o.name         display name, e.g. "Stride"
+ * @param {string} [o.description]
+ * @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 }) {
+  if (!TEMPLATE_NAMES.includes(template)) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'creating an app',
+      failed: `There is no starter called "${template}".`,
+      fix: `Use one of: ${TEMPLATE_NAMES.join(', ')}.`,
+    });
+  }
+
+  const target = resolveIn(folder, 'create_app', 'folder');
+  const attempted = `creating an app in ${target.show}`;
+  if (target.show === '.') {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted,
+      failed: 'The app needs its own folder, not the project root.',
+      fix: 'Pass a new folder name, e.g. "stride".',
+    });
+  }
+  await guard(target, `create an app in ${target.abs}`);
+
+  let existing = [];
+  try {
+    existing = await fs.readdir(target.abs);
+  } catch {
+    existing = [];
+  }
+  if (existing.length) {
+    throw new ToolFailure({
+      kind: 'not_empty',
+      attempted,
+      failed: `${target.show} already has ${existing.length} item(s) in it: ${existing.slice(0, 5).join(', ')}.`,
+      fix: 'Pick a new folder name. If this folder is the app from an earlier attempt, work in it instead of creating it again.',
+    });
+  }
+
+  const display = plain(name) || path.basename(target.abs);
+  const fill = {
+    __APP_NAME__: display,
+    __APP_SLUG__: slug(display),
+    __APP_DESCRIPTION__: plain(description) || display,
+  };
+
+  const files = await copyTree(path.join(TEMPLATES, template), target.abs, fill);
+  await fs.mkdir(path.join(target.abs, 'public'), { recursive: true });
+
+  if (install) {
+    const pkg = path.join(target.abs, 'package.json');
+    packageJsonWritten(pkg, await fs.readFile(pkg, 'utf8'));
+  }
+
+  const guide = await fs.readFile(path.join(target.abs, 'TEMPLATE.md'), 'utf8').catch(() => '');
+
+  return result(
+    `Created ${target.show} from the ${template} starter — ${files.length} files, already known to build.\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`
+        : '') +
+      `Run this app's commands with cwd: "${target.show}" (npm run build, npm run dev).\n\n${guide}`,
+    `${files.length} files${install ? ' · installing in the background' : ''}`
+  );
+}

package/templates/next-shadcn/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

package/templates/next-shadcn/README.md

@@ -0,0 +1,9 @@
+# __APP_NAME__
+
+Built with ucode on Next.js and shadcn/ui.
+
+```bash
+npm run dev
+```
+
+Then open http://localhost:3000

package/templates/next-shadcn/TEMPLATE.md

@@ -0,0 +1,39 @@
+# What this project already has
+
+It was created by ucode's `create_app` from a starter that is known to build.
+Do not re-run create-next-app or `shadcn init` — everything below is in place.
+
+## Stack
+
+- Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4
+- shadcn/ui ("base-nova" style, built on `@base-ui/react`), lucide-react icons
+- next-themes (light / dark / system), sonner toasts, date-fns
+
+Next 16 changed APIs. `AGENTS.md` explains, and `node_modules/next/dist/docs/`
+has the guides — check them before using an API you are unsure of.
+
+## Already wired
+
+- `src/app/layout.tsx` — font (Geist, registered as `--font-sans`), `ThemeProvider`,
+  `TooltipProvider`, and `<Toaster />`. Call `toast()` from `sonner` anywhere.
+- `src/components/theme-toggle.tsx` — a light/dark button, ready to place.
+- `src/app/globals.css` — the design tokens. The palette is a starting point:
+  re-tint `--primary`, `--accent` and the neutrals for this app's direction.
+  `--success` and `--warning` exist alongside `--destructive`
+  (`bg-success`, `text-warning`, ...).
+- `src/app/page.tsx` — a placeholder. Replace it.
+
+## Components in `src/components/ui/`
+
+alert-dialog, avatar, badge, button, calendar, card, checkbox, command, dialog,
+dropdown-menu, input, input-group, label, popover, progress, scroll-area, select,
+separator, sheet, skeleton, sonner, switch, tabs, textarea, tooltip
+
+Anything else: `npx shadcn@latest add <name> -y`.
+
+## Conventions
+
+- One component per file, grouped by feature: `src/components/<feature>/`.
+- Shared types in `src/lib/types.ts`, helpers in `src/lib/`.
+- `"use client"` only on components that need state or events.
+- `cn()` from `@/lib/utils` to merge class names.

package/templates/next-shadcn/_gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts