feat(api): cute default box names (e.g. cozy-otter) (#853)

## Summary

Boxes created via the **cloud API** without an explicit name now get a
fun
default like `cozy-otter` instead of showing the bare box ID — drawn
from a
curated **80 adjective × 120 cute-animal** vocabulary (`nimble-otter`,
`cozy-quokka`, `brave-narwhal` …).

Scope: **apps/api only** (TypeScript). No Rust-core / local-SDK changes.

## Design decisions (per discussion)

- **Clean-first, box-id on collision.** The default is unsuffixed
  (`cozy-otter`). Only when it hits the per-org
`@Unique(['organizationId','name'])` constraint do we fall back
**exactly
once** to `cozy-otter-{boxId}`. The box id is unique by construction,
so:
  - common case = clean, no numbers, no id noise;
  - the fallback **can never collide** → no retry loop, no namespace to
    exhaust, works the same whether the org has 5 boxes or 50k.
- **Names stay unique** (Docker model). The cloud addresses boxes by *id
or
name* (`GET /boxes/:boxIdOrName`, stop/delete/resize/…), so duplicate
names
  would make name-based ops ambiguous. Keeping `@Unique` means **zero DB
  migration**.
- **Hyphen separator** — also a valid DNS label, in case box names ever
become
  subdomains.
- **Both create paths covered**: fresh `insert` and warm-pool `claim`.
  User-provided names are unchanged (one-shot, still 409 on conflict).

## Implementation

- `box-name-generator.ts`: `generateBoxName()` +
  `persistWithGeneratedBoxName(boxId, persist)` — encapsulates the
  generate → persist → id-fallback-on-23505 policy.
- `box.service.ts`: both `create` (insert) and `assignWarmPoolBox`
(update)
  use it when no caller name is given, passing the box id.

## Test plan

- [x] `nx test api box-name-generator` — clean shape, variety,
clean-on-first,
      id-appended-on-collision, no-fallback-on-unrelated-error
- [x] `nx build api` typechecks · `eslint` clean
- [ ] Dev smoke after merge: create a box without a name → expect e.g.
      `cozy-otter` in the dashboard list

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Automatically generate box names in an adjective-animal format when no
name is provided.
* **Bug Fixes**
* Improve uniqueness conflict handling during box creation, with clearer
messaging for caller-provided vs auto-generated names.
* Warm-pool box assignment now persists names more reliably, preventing
update failures related to name collision/guard logic.
* **Tests**
* Added Jest coverage for name generation formatting/variety and the
updated two-step collision retry behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: law-chain-hot

apps/api/src/box/services/box.service.ts

@@ -8,6 +8,7 @@ import { ForbiddenException, Injectable, Logger, NotFoundException, ConflictExce
 import { InjectRepository } from '@nestjs/typeorm'
 import { Not, Repository, LessThan, In, JsonContains, FindOptionsWhere, ILike } from 'typeorm'
 import { Box } from '../entities/box.entity'
+import { persistWithGeneratedBoxName } from '../utils/box-name-generator'
 import { CreateBoxDto } from '../dto/create-box.dto'
 import { ResizeBoxDto } from '../dto/resize-box.dto'
 import { BoxState } from '../enums/box-state.enum'
@@ -242,7 +243,15 @@ export class BoxService {
       box.runnerId = runner.id
       box.pending = true
 
-      const insertedBox = await this.boxRepository.insert(box)
+      // No caller-provided name -> assign a fun default (e.g. "cozy-otter"),
+      // falling back to "cozy-otter-{boxId}" if it collides with the per-org
+      // @Unique(['organizationId', 'name']) constraint.
+      const insertedBox = createBoxDto.name
+        ? await this.boxRepository.insert(box)
+        : await persistWithGeneratedBoxName(box.id, (name) => {
+            box.name = name
+            return this.boxRepository.insert(box)
+          })
 
       this.eventEmitter
         .emitAsync(BoxEvents.CREATED, new BoxCreatedEvent(insertedBox))
@@ -251,7 +260,11 @@ export class BoxService {
       return this.toBoxDto(insertedBox)
     } catch (error) {
       if (error.code === '23505') {
-        throw new ConflictException(`Box with name ${createBoxDto.name} already exists`)
+        throw new ConflictException(
+          createBoxDto.name
+            ? `Box with name ${createBoxDto.name} already exists`
+            : 'Could not allocate a unique box name, please retry',
+        )
       }
 
       throw error
@@ -271,10 +284,6 @@ export class BoxService {
       createdAt: now,
     }
 
-    if (createBoxDto.name) {
-      updateData.name = createBoxDto.name
-    }
-
     if (createBoxDto.autoStopInterval !== undefined) {
       updateData.autoStopInterval = this.resolveAutoStopInterval(createBoxDto.autoStopInterval)
     }
@@ -310,10 +319,19 @@ export class BoxService {
       )
     }
 
-    const updatedBox = await this.boxRepository.update(warmPoolBox.id, {
-      updateData,
-      entity: warmPoolBox,
-    })
+    // Resolve the name at persist time. A caller-provided name updates in one
+    // shot (reusing the pre-fetched entity). A generated default falls back to
+    // "{name}-{boxId}" on collision and omits `entity` so each attempt re-reads
+    // the row — reusing the mutated entity would corrupt the optimistic-update
+    // guard.
+    const updatedBox = createBoxDto.name
+      ? await this.boxRepository.update(warmPoolBox.id, {
+          updateData: { ...updateData, name: createBoxDto.name },
+          entity: warmPoolBox,
+        })
+      : await persistWithGeneratedBoxName(warmPoolBox.id, (name) =>
+          this.boxRepository.update(warmPoolBox.id, { updateData: { ...updateData, name } }),
+        )
 
     // Defensive invalidation of orgId cache since the box moved from unassigned to a real organization
     this.boxLookupCacheInvalidationService.invalidateOrgId({

apps/api/src/box/utils/box-name-generator.spec.ts

@@ -0,0 +1,59 @@
+import { generateBoxName, persistWithGeneratedBoxName } from './box-name-generator'
+
+const uniqueViolation = () => Object.assign(new Error('duplicate key'), { code: '23505' })
+
+describe('generateBoxName', () => {
+  it('defaults to a clean {adjective}-{animal} name (no suffix)', () => {
+    for (let i = 0; i < 100; i++) {
+      const name = generateBoxName()
+      const parts = name.split('-')
+      expect(parts).toHaveLength(2)
+      expect(parts[0]).toMatch(/^[a-z]+$/)
+      expect(parts[1]).toMatch(/^[a-z]+$/)
+    }
+  })
+
+  it('produces variety across many calls', () => {
+    const seen = new Set<string>()
+    for (let i = 0; i < 50; i++) seen.add(generateBoxName())
+    // 9600 base combos — <40 uniques out of 50 picks would mean the generator
+    // is stuck on a near-constant.
+    expect(seen.size).toBeGreaterThan(40)
+  })
+})
+
+describe('persistWithGeneratedBoxName', () => {
+  it('persists a clean (unsuffixed) name on the first try', async () => {
+    const names: string[] = []
+    const result = await persistWithGeneratedBoxName('aB3kF9mZ2pQ7', async (name) => {
+      names.push(name)
+      return name
+    })
+    expect(names).toHaveLength(1)
+    expect(result.split('-')).toHaveLength(2) // clean: adjective-animal
+  })
+
+  it('appends the box id when the clean name collides', async () => {
+    const names: string[] = []
+    const result = await persistWithGeneratedBoxName('aB3kF9mZ2pQ7', async (name) => {
+      names.push(name)
+      if (names.length === 1) throw uniqueViolation() // clean name taken
+      return name
+    })
+    expect(names).toHaveLength(2)
+    expect(names[0].split('-')).toHaveLength(2) // first attempt: clean adjective-animal
+    expect(result).toBe(`${names[0]}-aB3kF9mZ2pQ7`) // fallback reuses the base + box id
+    expect(result.endsWith('-aB3kF9mZ2pQ7')).toBe(true)
+  })
+
+  it('does not fall back on a non-unique-violation error', async () => {
+    let calls = 0
+    await expect(
+      persistWithGeneratedBoxName('aB3kF9mZ2pQ7', async () => {
+        calls++
+        throw new Error('connection reset')
+      }),
+    ).rejects.toThrow('connection reset')
+    expect(calls).toBe(1)
+  })
+})

apps/api/src/box/utils/box-name-generator.ts

@@ -0,0 +1,78 @@
+// Default box-name generator. Shape: "{adjective}-{animal}", e.g. "cozy-otter".
+//
+// Names are kept clean in the common case. On the rare collision with the
+// per-org @Unique(['organizationId', 'name']) constraint, the caller falls back
+// to "{adjective}-{animal}-{boxId}" (see persistWithGeneratedBoxName) — the box
+// id is unique by construction, so that single fallback can never collide.
+
+const ADJECTIVES = [
+  'agile', 'amber', 'astute', 'bold', 'bouncy', 'brave', 'breezy', 'brilliant', 'brisk', 'calm',
+  'cheery', 'clever', 'cosmic', 'cozy', 'crimson', 'crisp', 'dapper', 'daring', 'darting', 'deft',
+  'dreamy', 'dusky', 'eager', 'fierce', 'fluffy', 'fresh', 'gallant', 'gentle', 'gliding', 'glossy',
+  'golden', 'hearty', 'hovering', 'hushed', 'indigo', 'intrepid', 'ivory', 'jade', 'jaunty', 'jolly',
+  'jovial', 'keen', 'lively', 'lofty', 'lucid', 'lunar', 'mellow', 'mighty', 'mild', 'mystic',
+  'neat', 'nebular', 'nimble', 'opal', 'perky', 'placid', 'plucky', 'polished', 'prismatic', 'quick',
+  'radiant', 'savvy', 'serene', 'sharp', 'silver', 'sleek', 'snappy', 'snug', 'soaring', 'solar',
+  'sparkly', 'starry', 'swift', 'tidy', 'tranquil', 'valiant', 'vibrant', 'vivid', 'witty', 'zippy',
+] as const
+
+const ANIMALS = [
+  'alpaca', 'badger', 'bat', 'bear', 'beaver', 'bee', 'beluga', 'bluebird', 'bluejay', 'bobcat',
+  'bumblebee', 'bunny', 'butterfly', 'calf', 'canary', 'capybara', 'cardinal', 'cat', 'chameleon', 'chick',
+  'chickadee', 'chinchilla', 'chipmunk', 'cockatiel', 'corgi', 'cottontail', 'crab', 'cub', 'deer', 'dolphin',
+  'dove', 'dragonfly', 'duck', 'duckling', 'eagle', 'falcon', 'fawn', 'ferret', 'finch', 'firefly',
+  'flamingo', 'fox', 'frog', 'gecko', 'goldfinch', 'goose', 'gosling', 'guppy', 'hamster', 'hare',
+  'hawk', 'hedgehog', 'heron', 'hummingbird', 'joey', 'kangaroo', 'kit', 'kitten', 'koala', 'ladybug',
+  'lamb', 'lemur', 'llama', 'lovebird', 'lynx', 'magpie', 'manatee', 'marmot', 'meerkat', 'mole',
+  'mouse', 'narwhal', 'nightingale', 'ocelot', 'octopus', 'otter', 'owl', 'owlet', 'panda', 'parakeet',
+  'parrot', 'peacock', 'pelican', 'penguin', 'piglet', 'platypus', 'pony', 'porpoise', 'possum', 'puffin',
+  'pup', 'puppy', 'quokka', 'rabbit', 'raccoon', 'raven', 'robin', 'salamander', 'seahorse', 'seal',
+  'sheep', 'sloth', 'snail', 'sparrow', 'squirrel', 'starfish', 'stingray', 'swallow', 'swan', 'tadpole',
+  'tortoise', 'toucan', 'turtle', 'wallaby', 'walrus', 'whale', 'wolf', 'wombat', 'woodpecker', 'wren',
+] as const
+
+function pick<T>(arr: readonly T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)]
+}
+
+/**
+ * Generate a default box name like `cozy-otter`. Hyphen- (not underscore-)
+ * separated and all-lowercase, so the clean name is a valid DNS label in case
+ * box names ever become hostnames.
+ */
+export function generateBoxName(): string {
+  return `${pick(ADJECTIVES)}-${pick(ANIMALS)}`
+}
+
+// Postgres unique_violation — raised when a generated name hits the per-org
+// @Unique(['organizationId', 'name']) constraint.
+const PG_UNIQUE_VIOLATION = '23505'
+
+/**
+ * Run `persist` with a generated box name: clean first ("cozy-otter"). If that
+ * collides with the per-org unique-name constraint, fall back exactly once to
+ * "cozy-otter-{boxId}" — the box's own id is unique by construction, so the
+ * fallback can never collide. No retry loop, no numeric suffix, no namespace
+ * to exhaust.
+ *
+ * @param boxId - this box's id; appended verbatim on collision. It can contain
+ *   uppercase, so the fallback name (unlike the clean base) is not guaranteed
+ *   to be a DNS label — keep the id intact rather than lower-casing it, since
+ *   the suffix is meant to be the box id.
+ * @param persist - performs the insert/update for a candidate name; must throw
+ *   a Postgres unique-violation (code 23505) when that name is already taken.
+ */
+export async function persistWithGeneratedBoxName<T>(
+  boxId: string,
+  persist: (name: string) => Promise<T>,
+): Promise<T> {
+  const base = generateBoxName()
+  try {
+    return await persist(base)
+  } catch (error) {
+    if ((error as { code?: string })?.code !== PG_UNIQUE_VIOLATION) {
+      throw error
+    }
+    return await persist(`${base}-${boxId}`)
+  }
+}