ucode-agent 1.0.0

package/skills/ui-ux/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: ui-ux
+description: How to design and build an interface that looks deliberate rather than generated — direction, tokens, layout, states, motion, accessibility. Loads itself for any work with a user interface in it.
+auto: app, apps, ui, ux, website, web app, webapp, web page, webpage, landing page, dashboard, frontend, front-end, interface, css, tailwind, html, react, vue, svelte, nextjs, next.js, redesign, restyle, responsive, dark mode, ugly, styling, stylesheet, mockup, prototype
+---
+
+# Interfaces
+
+The house style of a language model is a centred column, a purple-to-blue
+gradient, three equal cards and a lot of empty space. It is recognisable on
+sight, and everyone has now seen it a thousand times. Your job is to not
+produce it.
+
+This is not decoration applied at the end. It is the order the work happens in:
+direction, then structure, then tokens, then states, then verification.
+
+## 1. Decide the direction before writing any CSS
+
+Answer these to yourself in one line each, then build to the answers:
+
+1. **Job** — what does this screen actually do?
+2. **Who** — who opens it, how often, and what do they need first?
+3. **Tone** — pick one and commit: utilitarian, editorial, technical, playful,
+   industrial, calm, dense. "Modern and clean" is not a tone, it is a way of
+   avoiding the question.
+4. **One memorable detail** — a colour, a texture, a typographic move, a single
+   interaction. Exactly one. It is the difference between a design and a
+   template.
+
+## 2. Pick the mode from the surface, not the product
+
+The mode names what success looks like for the person in front of it. It
+decides how much the interface is allowed to perform.
+
+- **Operate** — they are completing a task. App UI, dashboards, editors,
+  admin, settings, tools. Scannability, consistency and speed beat expression
+  every time. The personality lives in precise details, not in the hero.
+- **Persuade** — they are deciding whether to act. Landing pages, pricing,
+  marketing. Here the design *is* the product; earn the attention.
+- **Read** — they are trying to understand something. Docs, articles, guides.
+  Structure for comprehension first, then make reading pleasant enough to stay.
+- **Experience** — they are looking at the work itself. Portfolios, galleries.
+  The artifact leads from the first screen and the interface gets out of the way.
+
+A tool's landing page is still Persuade. A dashboard is still Operate however
+beautiful the brand is. Never put a marketing hero on top of a working tool.
+
+## 3. Tokens first, then never a raw value again
+
+Set these at the top and use them everywhere. One-off hard-coded values are
+exactly how a design drifts out of alignment with itself.
+
+```css
+:root {
+  --font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mono: ui-monospace, SFMono-Regular, "Cascadia Code", Consolas, monospace;
+
+  /* One scale. Nothing between the steps. */
+  --text--1: .8125rem; --text-0: 1rem;   --text-1: 1.25rem;
+  --text-2:  1.5rem;   --text-3: 2rem;   --text-4: 2.75rem;
+
+  --s1: .25rem; --s2: .5rem; --s3: .75rem; --s4: 1rem;
+  --s5: 1.5rem; --s6: 2rem;  --s7: 3rem;   --s8: 4rem;
+
+  /* Neutrals carry a hue. Flat #808080 grey is what makes a UI look dead. */
+  --bg: #fbfaf9;  --surface: #ffffff; --line: #e6e2dd;
+  --ink: #17161a; --ink-2: #55525c;   --ink-3: #8a8792;
+
+  --accent: #2f6fe0; --accent-ink: #ffffff; --accent-soft: #eaf1fe;
+  --danger: #b42318; --ok: #217a4b; --warn: #b25e09;
+
+  --radius: 10px; --radius-sm: 6px;
+  --shadow: 0 1px 2px rgb(20 18 24 / .05), 0 8px 24px rgb(20 18 24 / .07);
+  --focus: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #101014;  --surface: #17171c; --line: #2a2a33;
+    --ink: #f2f1f5; --ink-2: #b3b0bd;   --ink-3: #807d8a;
+    --accent: #6fa4ff; --accent-ink: #0f1016; --accent-soft: #16203a;
+  }
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0; background: var(--bg); color: var(--ink);
+  font: var(--text-0)/1.6 var(--font);
+  -webkit-font-smoothing: antialiased;
+}
+h1, h2, h3 { margin: 0; line-height: 1.15; letter-spacing: -.02em; }
+:focus-visible { outline: none; box-shadow: var(--focus); }
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation: none !important; transition: none !important; }
+}
+```
+
+**Swap the four palette lines to change direction, and keep everything else:**
+
+- **Paper** — `--bg:#faf9f7; --surface:#fff; --ink:#1a1815; --accent:#b45309`.
+  Warm, calm, for reading and for tools used daily.
+- **Console** — `--bg:#0d1117; --surface:#161b22; --ink:#e6edf3; --accent:#2f81f7`
+  with `--line:#30363d`. Technical and dense, for dashboards and dev tools.
+- **Editorial** — `--bg:#fffdf8; --surface:#fff; --ink:#141414; --accent:#c2410c`
+  plus a serif on headings only. For content and landing pages.
+
+One direction, all the way through. Half Console and half Editorial reads as a
+mistake, because it is one.
+
+**The rules behind the tokens**, for when you need a value that is not in them:
+
+- **Spacing** — every value from the scale. Space *inside* a group must be
+  smaller than the space *around* it, or the grouping reads wrong however good
+  the rest is.
+- **Type** — one family for UI, at most one more for display. Body 15–17px,
+  line-height 1.5–1.65, measure capped at 65–75ch. Headings tighter: 1.1–1.25,
+  and `letter-spacing: -.02em` above 28px.
+- **Colour** — one accent hue, one neutral ramp, semantic red/amber/green. Never
+  pure `#000` on pure `#fff`.
+- **Radius** — pick one and derive: inputs and buttons 6–8, cards 10–12,
+  pills 999. Four unrelated radii look like an accident.
+- **Depth** — borders and background steps first, shadows last, and only for
+  things that genuinely float: menus, modals, toasts. A shadow on every card
+  flattens the hierarchy instead of building it.
+- **Dark mode** — swap the variables. Never invert. Surfaces get *lighter* as
+  they rise, and pure white on near-black is too harsh: use around 90%.
+
+## 4. Layout
+
+- Build hierarchy with size, weight and colour before reaching for a box.
+  Three levels — primary, secondary, muted — is usually all you need.
+- Align to a grid and share edges. Ragged left edges are the single most
+  common reason a page feels amateur.
+- Full width is not a layout. Constrain content to what the content needs: a
+  table wants width, prose does not.
+- One job per element. A card that is a link, a form and a menu is three cards.
+
+## 5. States are most of the work
+
+An interface that only handles the happy path is a mockup. For every screen:
+
+- **Empty** — first run, nothing there yet. Say what this is and how to make
+  the first one. Never a blank box.
+- **Loading** — skeletons shaped like the real content, or a spinner on the
+  control that was pressed. Do not blank the page.
+- **Error** — what failed and what they can do about it. Keep their input.
+- **Partial** — one row failed and the rest loaded.
+
+And for every interactive element: `:hover`, `:focus-visible`, `:active`,
+`:disabled`, and the selected state. A control with only a default state is
+unfinished, not minimal. `outline: none` with no replacement focus ring is a
+bug, not a style choice.
+
+```css
+.btn {
+  font: 500 var(--text-0)/1 var(--font);
+  padding: var(--s3) var(--s5);
+  border: 1px solid transparent; border-radius: var(--radius-sm);
+  background: var(--accent); color: var(--accent-ink);
+  cursor: pointer; transition: filter .15s, transform .05s;
+}
+.btn:hover    { filter: brightness(1.08); }
+.btn:active   { transform: translateY(1px); }
+.btn:disabled { opacity: .45; cursor: not-allowed; filter: none; }
+.btn--quiet   { background: transparent; color: var(--ink); border-color: var(--line); }
+.btn--quiet:hover { background: var(--accent-soft); }
+
+.input {
+  width: 100%; padding: var(--s3) var(--s4);
+  font: var(--text-0) var(--font); color: var(--ink);
+  background: var(--surface);
+  border: 1px solid var(--line); border-radius: var(--radius-sm);
+}
+.input::placeholder { color: var(--ink-3); }
+```
+
+## 6. Motion
+
+One authored moment, not effects scattered everywhere, and not the same
+entrance animation on every section. 120–200ms, on `transform`, `opacity`,
+`filter` and colour only — never on `height` or `width`. Ease out from a state
+that is already visible. Honour `prefers-reduced-motion` every time.
+
+## 7. Non-negotiable
+
+- Contrast 4.5:1 for body text and placeholders, 3:1 for large text and for
+  the borders of controls.
+- Every control reachable and operable by keyboard, in the order it appears.
+- Labels on inputs. A placeholder is not a label.
+- Touch targets 44px.
+- `<button>` for actions, `<a href>` for navigation. Never a `<div>` with an
+  onClick.
+- `aria-label` on any icon-only button; real `alt` text on meaningful images.
+- Nothing shifts as content loads: reserve the space, set image dimensions.
+- 16px minimum body text on mobile, and `<meta name="viewport" content="width=device-width, initial-scale=1">`.
+
+## 8. Do not
+
+These are the defaults of the category rather than laws — a brief can earn any
+of them — but reaching for one *because it was the first thing to hand* means
+you were not deciding.
+
+- Purple-to-blue gradient headers. Gradient text. Glassmorphism as decoration.
+- Three identical feature cards with a lorem sentence each. Same-size icon +
+  heading + text cards used as the whole page structure. Nested cards.
+- The hero-metric template: big number, small label, three supporting stats.
+- A tracked uppercase eyebrow over every section, or 01 / 02 / 03 section
+  numbers where the order carries no information.
+- Emoji as interface icons. Use an icon set or well-drawn inline SVG.
+- Monospace as a costume for "technical" when there is no code or data in it.
+- A modal for something that needs neither interruption nor protected focus.
+- Centring everything. Long centred paragraphs are genuinely harder to read.
+- Inventing a component library when the project already has one. Look for
+  existing components, tokens and utilities first, and use them.
+- Placeholder copy. Write the real words — they are part of the design.
+
+## 9. Before you say it is done
+
+Open it and look at it. Then walk this list and fix what fails. The last three
+are the ones that get skipped, so do not skip them:
+
+1. **375px wide.** No horizontal scrollbar, nothing overlapping, nothing cut
+   off. If you wrote no media query at all, you have not done this.
+2. **The longest realistic string** in every label and every cell. Does the row
+   hold, or does one long title break the layout?
+3. **Empty data.** Is there a real empty state, or a blank rectangle?
+4. **Keyboard only.** Tab through everything. Can you see where you are at
+   every step?
+5. **Count the accent hues.** More than one family means the palette got away
+   from you. Put it back.
+6. **Contrast.** `--ink-3` on `--bg` is for hints, never for anything that has
+   to be read.
+
+Then say which of these you actually checked and what you found. Do not claim
+it works on mobile if you never made it narrow. If it runs in a browser, start
+it with `run_command` and `background: true` and open it before you call it
+finished.

package/skills/write-tests/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: write-tests
+description: Write tests that fail for the right reason — behaviour over implementation, real edges, and no assertions that can never break.
+---
+
+# Writing tests
+
+The test that matters is the one that fails the day someone breaks the thing it
+covers. Every other test is overhead with a green tick on it.
+
+## Test behaviour, not implementation
+
+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.
+
+## Cover the edges, not five versions of the middle
+
+For each unit, the ones that actually find bugs:
+
+- 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.

package/src/core/failure.js

@@ -0,0 +1,70 @@
+/**
+ * failure.js — the single error shape used everywhere in ucode.
+ *
+ * A stack trace tells the user what line broke. It does not tell them what
+ * ucode was trying to do, or what they should do about it. Every failure in
+ * this program carries those three things as fields, so no screen ever has to
+ * fall back on a raw trace to explain itself.
+ */
+
+export class Failure extends Error {
+  /**
+   * @param {object} o
+   * @param {string}  o.kind       machine-readable category, e.g. 'rate_limit'
+   * @param {string}  o.attempted  what was happening: 'reading src/app.js'
+   * @param {string}  o.failed     what went wrong, in plain words
+   * @param {string} [o.fix]       the concrete next step
+   * @param {Error}  [o.cause]     the underlying error, kept for --debug
+   * @param {object} [o.detail]    structured extras (status, retryAfter, ...)
+   */
+  constructor({ kind, attempted, failed, fix, cause, detail }) {
+    super(`${attempted}: ${failed}`);
+    this.name = 'Failure';
+    this.kind = kind;
+    this.attempted = attempted;
+    this.failed = failed;
+    this.fix = fix;
+    this.cause = cause;
+    this.detail = detail ?? {};
+  }
+}
+
+/**
+ * A failure inside a tool.
+ *
+ * These never reach the user as a crash. They are handed back to the model as
+ * text, which is why they read like instructions to whoever caused them — the
+ * model can usually fix its own mistake on the next step if it is told what
+ * the mistake was.
+ */
+export class ToolFailure extends Failure {
+  constructor(fields) {
+    super(fields);
+    this.name = 'ToolFailure';
+  }
+
+  /** What the model is shown in place of a tool result. */
+  forModel() {
+    const out = [`ERROR (${this.kind}) while ${this.attempted}.`, this.failed];
+    if (this.fix) out.push(`Suggestion: ${this.fix}`);
+    return out.join('\n');
+  }
+}
+
+/** The user said no at a confirmation prompt. Their call, not a fault. */
+export class Declined extends ToolFailure {
+  constructor(what) {
+    super({
+      kind: 'declined',
+      attempted: what,
+      failed: 'The user declined this action.',
+      fix: 'Do not try it again. Say what you were going to do and ask how they want to proceed.',
+    });
+    this.name = 'Declined';
+  }
+}
+
+/** True for anything carrying the three-field shape, however it was made. */
+export function isFailure(err) {
+  return Boolean(err && typeof err === 'object' && err.attempted && err.failed);
+}

package/src/core/history.js

@@ -0,0 +1,278 @@
+/**
+ * history.js — conversations on disk.
+ *
+ * One JSON file per session under ~/.ucode/sessions. The file always holds the
+ * complete history, tool calls and results included, even when the copy being
+ * sent to the model has had its older turns folded into a summary.
+ *
+ * Saving happens after every turn and after every tool result, so a crash, a
+ * Ctrl+C or a closed terminal costs nothing.
+ */
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Failure } from './failure.js';
+
+export const HOME = path.join(os.homedir(), '.ucode');
+
+export function sessionsDir(home = HOME) {
+  return path.join(home, 'sessions');
+}
+
+export function sessionFile(id, home = HOME) {
+  return path.join(sessionsDir(home), `${id}.json`);
+}
+
+/**
+ * A session's label, taken from the first thing the user said.
+ *
+ * This is what the resume list shows, so it has to read like a name rather
+ * than like the top of a paragraph.
+ */
+export function titleFrom(text) {
+  const first = String(text ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .find(Boolean);
+
+  if (!first) return 'Untitled';
+
+  let title = first
+    .replace(/^\/+/, '')
+    .replace(/^[-*>#\s]+/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (!title) return 'Untitled';
+  if (title.length > 60) title = `${title.slice(0, 59).trimEnd()}…`;
+  return title[0].toUpperCase() + title.slice(1);
+}
+
+export function newSession(cwd = process.cwd(), model = '') {
+  const now = new Date().toISOString();
+  return {
+    id: `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`,
+    title: 'Untitled',
+    cwd: path.resolve(cwd),
+    model,
+    createdAt: now,
+    updatedAt: now,
+    usage: { promptTokens: 0, outputTokens: 0, totalTokens: 0, turns: 0 },
+    messages: [],
+  };
+}
+
+async function ensureDir(home) {
+  const dir = sessionsDir(home);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch (err) {
+    throw new Failure({
+      kind: 'sessions_unwritable',
+      attempted: `creating ${dir}`,
+      failed: `${err.code ?? ''} ${err.message}`.trim(),
+      fix: 'Check that your home directory is writable, or point HOME somewhere that is.',
+      cause: err,
+    });
+  }
+  return dir;
+}
+
+/**
+ * Write the session out.
+ *
+ * Via a temp file and a rename, so a save interrupted halfway can never leave
+ * a truncated session behind — the previous good file stays until the new one
+ * is complete.
+ */
+export async function save(session, { home = HOME } = {}) {
+  await ensureDir(home);
+
+  session.updatedAt = new Date().toISOString();
+  if (!session.title || session.title === 'Untitled') {
+    const first = session.messages.find((m) => m.role === 'user');
+    if (first) session.title = titleFrom(first.content);
+  }
+
+  const target = sessionFile(session.id, home);
+  const temp = `${target}.${process.pid}.tmp`;
+
+  try {
+    await fs.writeFile(temp, JSON.stringify(session, null, 2), 'utf8');
+    await fs.rename(temp, target);
+  } catch (err) {
+    await fs.rm(temp, { force: true }).catch(() => {});
+    throw new Failure({
+      kind: 'save_failed',
+      attempted: `saving this session to ${target}`,
+      failed: `${err.code ?? ''} ${err.message}`.trim(),
+      fix:
+        'Check free space and permissions on ~/.ucode/sessions. The conversation is ' +
+        'still in memory, so fixing it means the next turn saves everything.',
+      cause: err,
+    });
+  }
+
+  return target;
+}
+
+export async function load(id, { home = HOME } = {}) {
+  const file = sessionFile(id, home);
+  let raw;
+
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Failure({
+        kind: 'no_such_session',
+        attempted: `resuming ${id}`,
+        failed: `There is no session file at ${file}.`,
+        fix: 'Run /resume to see the sessions that do exist.',
+        cause: err,
+      });
+    }
+    throw new Failure({
+      kind: 'session_unreadable',
+      attempted: `reading session ${id}`,
+      failed: `${err.code ?? ''} ${err.message}`.trim(),
+      fix: 'Check permissions on ~/.ucode/sessions.',
+      cause: err,
+    });
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Failure({
+      kind: 'session_corrupt',
+      attempted: `resuming ${id}`,
+      failed: `${file} is not valid JSON (${err.message}) — most likely truncated by a hard kill.`,
+      fix: `Start fresh with /new. Deleting ${file} is safe; it only affects that one conversation.`,
+      cause: err,
+    });
+  }
+
+  if (!parsed || !Array.isArray(parsed.messages)) {
+    throw new Failure({
+      kind: 'session_corrupt',
+      attempted: `resuming ${id}`,
+      failed: `${file} is valid JSON but holds no message history.`,
+      fix: `Start fresh with /new. The file is at ${file} if you want to look at it.`,
+    });
+  }
+
+  // Fill in whatever an older or hand-edited file happens to be missing.
+  return {
+    usage: { promptTokens: 0, outputTokens: 0, totalTokens: 0, turns: 0 },
+    title: 'Untitled',
+    cwd: process.cwd(),
+    model: '',
+    createdAt: parsed.updatedAt ?? new Date().toISOString(),
+    ...parsed,
+    id: parsed.id ?? id,
+  };
+}
+
+/** The opening line of a conversation, for the resume list. */
+function previewOf(messages) {
+  const first = messages.find((m) => m.role === 'user' && m.content?.trim());
+  if (!first) return '';
+  const line = first.content.split('\n').map((l) => l.trim()).find(Boolean) ?? '';
+  return line.length > 96 ? `${line.slice(0, 95)}…` : line;
+}
+
+/** When something last happened, and when it started. */
+function lastReplyOf(messages) {
+  const last = [...messages].reverse().find((m) => m.role === 'assistant' && m.content?.trim());
+  if (!last) return '';
+  const line = last.content.split('\n').map((l) => l.trim()).find(Boolean) ?? '';
+  return line.length > 96 ? `${line.slice(0, 95)}…` : line;
+}
+
+/**
+ * Every saved session, newest first, with the ones belonging to this folder
+ * pulled to the front — which is the whole point of the list when you have
+ * conversations spread across a dozen projects.
+ *
+ * A file that will not parse is reported separately rather than breaking the
+ * listing: one bad session must never hide the other forty.
+ */
+export async function list({ home = HOME, cwd = null } = {}) {
+  const dir = sessionsDir(home);
+
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return Object.assign([], { unreadable: [] });
+    throw new Failure({
+      kind: 'list_failed',
+      attempted: `listing ${dir}`,
+      failed: `${err.code ?? ''} ${err.message}`.trim(),
+      fix: 'Check that ~/.ucode/sessions exists and is readable.',
+      cause: err,
+    });
+  }
+
+  const here = cwd ? path.resolve(cwd) : null;
+  const sessions = [];
+  const unreadable = [];
+
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      const parsed = JSON.parse(await fs.readFile(path.join(dir, file), 'utf8'));
+      if (!parsed || !Array.isArray(parsed.messages)) throw new Error('no messages');
+      const where = parsed.cwd ?? '';
+      const turns = parsed.messages.filter((m) => m.role === 'user').length;
+      sessions.push({
+        id: parsed.id ?? path.basename(file, '.json'),
+        title: parsed.title ?? 'Untitled',
+        cwd: where,
+        model: parsed.model ?? '',
+        createdAt: parsed.createdAt ?? parsed.updatedAt ?? null,
+        updatedAt: parsed.updatedAt ?? parsed.createdAt ?? null,
+        messageCount: parsed.messages.length,
+        turns,
+        preview: previewOf(parsed.messages),
+        lastReply: lastReplyOf(parsed.messages),
+        usage: parsed.usage ?? null,
+        mine: here ? path.resolve(where || '.') === here : false,
+      });
+    } catch {
+      unreadable.push(file);
+    }
+  }
+
+  const byRecency = (a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? ''));
+  const ordered = here
+    ? [...sessions.filter((s) => s.mine).sort(byRecency), ...sessions.filter((s) => !s.mine).sort(byRecency)]
+    : sessions.sort(byRecency);
+
+  return Object.assign(ordered, { unreadable });
+}
+
+/** The most recent session started in this folder, if there is one. */
+export async function latestHere(cwd, { home = HOME } = {}) {
+  const all = await list({ home, cwd });
+  return all.find((s) => s.mine) ?? null;
+}
+
+export async function remove(id, { home = HOME } = {}) {
+  await fs.rm(sessionFile(id, home), { force: true });
+}
+
+export async function removeAll({ home = HOME } = {}) {
+  const dir = sessionsDir(home);
+  try {
+    for (const file of await fs.readdir(dir)) {
+      if (file.endsWith('.json')) await fs.rm(path.join(dir, file), { force: true });
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}