ucode-agent 1.0.0 → 1.2.0

package/skills/write-tests/SKILL.md

@@ -1,47 +1,85 @@
 ---
 name: write-tests
-description: Write tests that fail for the right reason — behaviour over implementation, real edges, and no assertions that can never break.
+description: Write tests that catch real regressions — the right level for each behaviour, real edge cases, deterministic setups, mocks only at the boundaries, and proof that each test can actually fail.
+auto: write tests, add tests, add a test, unit test, unit tests, test coverage, integration test, e2e test, end to end test, testing, vitest, jest, pytest, playwright
 ---
 
 # Writing tests
 
-The test that matters is the one that fails the day someone breaks the thing it
+The test that matters is the one that fails the day someone breaks what it
 covers. Every other test is overhead with a green tick on it.
 
-## Test behaviour, not implementation
+## 1. Find how this project tests
 
-Assert on what a caller can observe: the return value, the state afterwards,
-the thing that was written. A test that checks a private helper was called
-locks the implementation in place and will need rewriting the first time
-anyone refactors — while still not proving the feature works.
+- Look for the runner and its config before writing anything: `vitest.config.*`,
+  `jest.config.*`, `playwright.config.*`, `pytest.ini`/`pyproject.toml`,
+  `go test`, the `test` script in `package.json`.
+- Match the existing style: file location (`__tests__/`, `*.test.ts` beside the
+  source, `tests/`), naming, helpers, fixtures. Use what is there.
+- If nothing exists, pick the standard for the stack — Vitest for Vite and
+  Next.js, pytest for Python, the built-in `go test` — and add the script.
 
-## Cover the edges, not five versions of the middle
+## 2. Pick the right level for each behaviour
 
-For each unit, the ones that actually find bugs:
+- **Unit** — pure logic: parsing, scoring, validation, formatting, reducers.
+  Fast, many, no I/O.
+- **Integration** — a route handler with its validation and error paths, a
+  component with its real children, a module against a real temporary
+  database or filesystem.
+- **End to end** — the one or two core user journeys, in a real browser
+  (Playwright). Few, because they are slow and brittle.
+
+Most value per minute is in unit tests of the logic that makes decisions and
+integration tests of the boundaries where data comes in.
+
+## 3. Test behaviour, not implementation
+
+Assert what a caller can observe — the return value, the rendered output, the
+response, the state afterwards. A test that checks a private helper was called
+breaks on every refactor while proving nothing about the feature.
+
+For UI, query the way a user finds things: by role, label and text
+(`getByRole('button', { name: /analyze/i })`), not by class names or test IDs
+unless there is no accessible alternative.
+
+## 4. Cover the cases that find bugs
+
+For every unit, go through:
 
 - empty, one, many
-- the boundary: 0, -1, the last index, the maximum
-- null, undefined, the missing field, the wrong type
-- the failure path: the dependency throws, the network times out, the file is
-  gone
-- the second call: is it idempotent, is state left behind?
-
-## Make each test readable on its own
-
-- The name says the behaviour: `returns null when the session file is missing`.
-- Arrange, act, assert, in that order and visibly separated.
-- One reason to fail per test. Six assertions in a row means the first failure
-  hides the other five.
-- No shared mutable state between tests, and no dependence on the order they
-  run in.
-- Real values over mocks wherever it is affordable. Mock the network and the
-  clock; do not mock the thing you are testing.
-
-## Prove the test works
-
-Break the code on purpose and watch the test fail, then put it back. A test
-that has never failed is a test you have no reason to trust. If a test cannot
-fail — an assertion on a constant, a mock asserting itself — delete it.
-
-Then run the whole suite and report the real numbers, including anything that
-was already failing before you started.
+- boundaries: 0, -1, the exact threshold, just over and just under it, the max
+- missing: `null`, `undefined`, missing field, empty string, wrong type
+- malformed input: invalid JSON, a string where a number was expected,
+  a reply wrapped in prose
+- failure paths: the dependency throws, times out, returns an error status
+- repetition: the second call, the same input twice, concurrent calls
+
+A threshold rule ("sodium over 600mg is flagged") needs a test at 599, 600 and
+601. That is where the off-by-one lives.
+
+## 5. Keep tests deterministic and independent
+
+- Control time (`vi.useFakeTimers()`, a fixed clock) and randomness (a seed).
+- No real network. Mock at the boundary — the HTTP call, the SDK client — and
+  never mock the thing under test.
+- Each test sets up what it needs and cleans up after. No reliance on order.
+- Build test data with small factories so each test states only what matters
+  to it.
+- One behaviour per test, named for it:
+  `flags sodium when it is over the daily threshold`.
+- Arrange, act, assert — visibly separated.
+- Snapshots only for stable, small output; a 400-line snapshot gets approved
+  without being read.
+
+## 6. Prove each test can fail
+
+Break the code on purpose — flip a comparison, delete a branch — and watch the
+test fail, then restore it. A test that has never failed is a test you have no
+reason to trust. Delete tests that cannot fail (asserting a constant, a mock
+asserting itself).
+
+## 7. Run and report
+
+Run the whole suite, not only the new file. Report the real numbers — passed,
+failed, skipped — including anything that was already failing before you
+started, and anything you could not cover and why.

package/src/core/loop.js

@@ -1053,8 +1053,9 @@ export class Agent {
       .slice(-count);
 
     for (const m of tail) {
-      if (m.role === 'user') this.ui.write(`${blue('›')} ${dim(m.content.split('\n')[0])}`);
-      else this.ui.assistant(m.content);
+      if (m.role !== 'user') this.ui.assistant(m.content);
+      else if (this.ui.userMessage) this.ui.userMessage(m.content);
+      else this.ui.write(`${blue('›')} ${dim(m.content.split('\n')[0])}`);
     }
     if (tail.length) this.ui.write(dim('  ── picking up here ──\n'));
   }

package/src/core/provider.js

@@ -55,28 +55,28 @@ dotenv.config({ path: join(PACKAGE_ROOT, '.env'), quiet: true });
  */
 export const MODELS = {
   'nvidia/nemotron-3-ultra-550b-a55b:free': {
-    name: 'Nemotron 3 Ultra (free)',
+    name: 'Nemotron 3 Ultra',
     context: 1_000_000,
     star: true,
     note: 'deepest reasoning, 1M context — the default',
   },
   'nvidia/nemotron-3.5-lightning:free': {
-    name: 'Nemotron 3.5 Lightning (free)',
+    name: 'Nemotron 3.5 Lightning',
     context: 1_000_000,
     note: 'same huge window, answers much sooner',
   },
   'nvidia/nemotron-3-super-120b-a12b:free': {
-    name: 'Nemotron 3 Super (free)',
+    name: 'Nemotron 3 Super',
     context: 262_144,
     note: 'strong all-rounder, quick to first token',
   },
   'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free': {
-    name: 'Nemotron 3 Nano Omni (free)',
+    name: 'Nemotron 3 Nano Omni',
     context: 256_000,
     note: 'small and fast, reasoning tuned',
   },
   'cohere/north-mini-code:free': {
-    name: 'North Mini Code (free)',
+    name: 'North Mini Code',
     context: 256_000,
     star: true,
     note: 'code and UI specialist — reach for it on frontend work',
@@ -121,7 +121,7 @@ export function setModel(id) {
   return current;
 }
 
-/** The short name for a model id: "Nemotron 3 Ultra (free)". */
+/** The short name for a model id: "Nemotron 3 Ultra". */
 export function modelName(id = current) {
   return MODELS[id]?.name ?? id;
 }
@@ -179,16 +179,18 @@ export function estimateConversation(messages) {
  * of first-run convenience is worth handing out a live credential.
  */
 function apiKey() {
-  const key = (process.env.OPENROUTER_API_KEY ?? '').trim();
+  // UCODE_API_KEY is the documented name. The provider's own variable name is
+  // still read, so a key set up for another tool keeps working here.
+  const key = (process.env.UCODE_API_KEY || process.env.OPENROUTER_API_KEY || '').trim();
   if (!key) {
     throw new Failure({
       kind: 'no_api_key',
-      attempted: 'connecting to OpenRouter',
-      failed: 'OPENROUTER_API_KEY is not set in the environment or in any .env file.',
+      attempted: 'connecting to the model',
+      failed: 'No API key is set - UCODE_API_KEY is missing from the environment and from every .env file.',
       fix:
-        `Put OPENROUTER_API_KEY=your-key in ${ENV_FILE} — that applies to every ` +
+        `Put UCODE_API_KEY=your-key in ${ENV_FILE} — that applies to every ` +
         'project on this machine — or in a .env file beside your code. ' +
-        'Keys are free at https://openrouter.ai/keys',
+        'Free keys: https://openrouter.ai/keys',
     });
   }
   return key;
@@ -349,10 +351,10 @@ export function explain(err, id) {
     return new Failure({
       kind: 'invalid_api_key',
       attempted,
-      failed: `OpenRouter rejected the API key (HTTP ${status ?? 401}).`,
+      failed: `The API key was rejected (HTTP ${status ?? 401}).`,
       fix:
-        'Check OPENROUTER_API_KEY for a typo or trailing space, and confirm the key ' +
-        'is still active at https://openrouter.ai/keys',
+        'Check UCODE_API_KEY in ~/.ucode/.env for a typo or trailing space, and ' +
+        'confirm the key is still active in your account.',
       cause: err,
     });
   }
@@ -380,8 +382,8 @@ export function explain(err, id) {
         ? `The free daily request cap for ${modelName(id)} is used up.`
         : `Too many requests for ${modelName(id)} just now${wait ? ` — clear in ${wait}` : ''}.`,
       fix: daily
-        ? 'Free caps reset each day. /model switches to another one, or add credit at ' +
-          'https://openrouter.ai/credits to lift the ceiling.'
+        ? 'Free caps reset each day. /model switches to another one, or add credit to ' +
+          'your account to lift the ceiling.'
         : 'ucode waits these out on its own. Free endpoints are shared, so it usually ' +
           'clears in seconds; /model moves to a quieter one.',
       detail: { retryAfter, daily },
@@ -406,7 +408,7 @@ export function explain(err, id) {
     return new Failure({
       kind: 'bad_model',
       attempted,
-      failed: `OpenRouter has no model "${id}" available to this key.`,
+      failed: `No model "${id}" is available to this key.`,
       fix: `Run /model. ucode ships with: ${Object.keys(MODELS).join(', ')}`,
       cause: err,
     });
@@ -435,7 +437,7 @@ export function explain(err, id) {
       attempted,
       failed: noTools
         ? `${modelName(id)} cannot call tools, which ucode needs for every task.`
-        : `OpenRouter rejected the request as malformed (HTTP 400): ${detail}`,
+        : `The request was rejected as malformed (HTTP 400): ${detail}`,
       fix: noTools
         ? 'Run /model and pick another one.'
         : 'Usually an oversized conversation. /new starts a fresh one.',
@@ -497,7 +499,7 @@ export function explain(err, id) {
     return new Failure({
       kind: 'network',
       attempted,
-      failed: `The connection to OpenRouter dropped: ${raw}`,
+      failed: `The connection to the model dropped: ${raw}`,
       fix:
         'ucode retries this by itself. If it keeps happening, check your connection, ' +
         'VPN and any corporate proxy (HTTPS_PROXY) — or /model to a lighter one, since ' +

package/src/core/version.js

@@ -0,0 +1,16 @@
+/**
+ * version.js — the version, read from package.json rather than typed twice.
+ *
+ * package.json always ships in an npm package, so this is right wherever ucode
+ * is installed, and it can never drift from what `npm publish` released.
+ */
+
+import { readFileSync } from 'node:fs';
+
+export const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return '';
+  }
+})();