robodev 0.10.0 → 0.12.0

package/templates/space/.rulesync/skills/povio-ui-styling/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: povio-ui-styling
+description: Mandatory first skill for any Tiny Template web frontend UI work in apps/fe. Load and apply it before other frontend, design, UX, accessibility, responsive, animation, or performance skills when creating, changing, reviewing, debugging, polishing, or refactoring pages and React components. It requires checking and using @povio/ui primitives before raw HTML or custom controls, and governs UIConfig defaults, UIOverrides, Tailwind utilities, semantic tokens, shared UI wrappers, and dedicated CSS files.
+---
+
+# Povio UI Styling
+
+Apply the narrowest styling layer that expresses the intended scope. Preserve one source of truth for each visual rule.
+
+## Priority and Coordination
+
+This is the foundation skill for every UI task under `apps/fe`. Apply it first, before broader design, UX, accessibility, animation, responsive, or React performance skills. Those skills may improve the result, but they must preserve the component and styling decisions defined here.
+
+Use this skill for all work that creates, changes, reviews, or diagnoses visible or interactive frontend UI, including:
+
+- Pages, layouts, navigation, dashboards, cards, lists, and empty states
+- Forms, filters, search, inputs, validation, uploads, and settings
+- Buttons, links, menus, dialogs, drawers, popovers, tooltips, and toasts
+- Tables, pagination, tags, badges, typography, icons, and loading states
+- Responsive behavior, theming, accessibility, motion, and visual polish
+- Component extraction, shared wrappers, design-system alignment, and Figma implementation
+
+This skill does not replace feature-specific skills. Apply the relevant feature skill as well, after establishing the Povio UI component and styling layer.
+
+## Inspect Before Styling
+
+1. Read the target component and nearby feature components.
+2. Inspect existing `@povio/ui` usage in `apps/fe` for the relevant primitive.
+3. Inspect `apps/fe/src/styles/overrides/uiOverrides.override.ts` and the matching file under `styles/overrides/defaults` before changing a Povio primitive.
+4. Inspect `apps/fe/src/styles/theme.css` for available generated tokens, but never edit that file manually.
+5. Inspect `apps/fe/src/styles/base.css` and `globals.css` before adding global rules or tokens.
+
+## Use This Decision Order
+
+### 1. Use an Existing Povio UI Component
+
+Use `@povio/ui` whenever it provides the semantic control or presentation primitive. This includes buttons, links, typography, icons, inputs, textareas, selects, checkboxes, radios, switches, forms, uploads, tags, badges, tables, pagination, menus, tooltips, modals, confirmations, drawers, popovers, toasts, loading indicators, and empty or feedback states.
+
+Prefer the component's supported props and variants over restyling its internals. Do not recreate a primitive with a raw HTML element merely to get a different appearance.
+
+Before introducing a native interactive element, a custom control, or a third-party UI component, search `@povio/ui` exports and existing feature usage for an existing equivalent. Native structural elements such as `main`, `section`, `article`, `nav`, and layout containers remain appropriate when no Povio semantic component exists.
+
+### 2. Use `UIConfig` for Application-Wide Defaults
+
+Use the root `UIConfig.Provider` when an existing Povio variant or option is correct and only its default should change across the application.
+
+Examples:
+
+- Make all inputs default to `small`.
+- Set the default table-cell typography size.
+- Set the default tag text size.
+
+Do not use `UIConfig` for a one-off screen or to invent a new variant.
+
+### 3. Use Tailwind for Composition and Local Presentation
+
+Use Tailwind classes in JSX for:
+
+- Page and component layout
+- Grid and flex behavior
+- Width, height, spacing, alignment, and overflow
+- Responsive composition
+- A one-instance surface, border, or text treatment
+- State selectors that remain short and readable
+
+Use semantic project utilities such as `bg-elevation-fill-default-1`, `text-text-default-1`, and `border-elevation-outline-default-1`. Do not use removed default palette utilities such as `bg-blue-500`, and do not repeat raw hex values in components.
+
+Keep Povio component `className` additions focused on outer layout or a genuinely local treatment. Do not pile conflicting utilities onto a component to fight its configured CVA variants. If the same correction is required on most instances, move it to `UIConfig` or `UIOverrides`.
+
+### 4. Use `UIOverrides` for Design-System-Level Povio Changes
+
+Use `UIOverrides.defineOverride(...)` when a Povio primitive must change consistently throughout the application:
+
+- Change the base classes of every instance.
+- Add or change supported variants.
+- Change compound-variant behavior.
+- Change internal slots not exposed by ordinary component props.
+- Align a primitive with the application's Figma design system.
+
+Place overrides under `apps/fe/src/styles/overrides/defaults/<component>.override.ts` and register them in `uiOverrides.override.ts`. Use the existing `mode`, `base`, `config`, variant, and compound-variant patterns.
+
+Update `apps/fe/src/types/ui.d.ts` when a new override variant must augment public Povio component types.
+
+Do not use `UIOverrides` for:
+
+- Page layout
+- One feature's special card
+- One exceptional component instance
+- A workaround that can be expressed through an existing prop
+
+Changing an override affects every consumer. Search all uses of the primitive and verify representative screens before finishing.
+
+### 5. Use a Shared Wrapper for Repeated Product Semantics
+
+Create a component under `apps/fe/src/components/shared` when several features need the same product-specific composition but the base Povio primitive should remain unchanged.
+
+Examples:
+
+- `StatusTag` mapping domain statuses to Povio `Tag` variants
+- `WalkSchedule` composing typography, icons, and layout
+- `PageCard` applying a repeated application surface
+
+Expose semantic props rather than forwarding a growing collection of styling flags.
+
+### 6. Use Dedicated CSS for Selector-Heavy or Browser-Level Behavior
+
+Create or extend a `.css` file when CSS communicates the rule more clearly than Tailwind:
+
+- Pseudo-elements used for connected timelines or route lines
+- Multi-step keyframes
+- Complex descendant, sibling, or state selectors
+- Calendar grids and overlapping appointments
+- Map-library markers, popups, or third-party DOM overrides
+- Print styles
+- Browser-global behavior such as scrollbars
+- Rules driven by CSS custom properties that many descendants consume
+
+Co-locate feature CSS with its owning component and import it there. Use a narrow, feature-prefixed class namespace, for example `walk-route__marker`. Keep truly global rules in `globals.css` or `base.css`.
+
+Do not create a CSS file for ordinary spacing, flex/grid layout, a simple hover, or a semantic color already expressible with a short Tailwind class list.
+
+## Scope Guide
+
+| Desired scope                                                  | Styling layer               |
+| -------------------------------------------------------------- | --------------------------- |
+| Existing primitive behavior                                    | Povio UI props/variants     |
+| Default for every instance                                     | `UIConfig`                  |
+| One page or component composition                              | Tailwind                    |
+| Every instance or internal Povio slot                          | `UIOverrides`               |
+| Repeated product-specific composition                          | Shared wrapper              |
+| Pseudo-elements, keyframes, complex selectors, third-party DOM | Scoped `.css`               |
+| Generated design tokens                                        | Figma-generated `theme.css` |
+| Handwritten global token or browser rule                       | `base.css` or `globals.css` |
+
+## Guardrails
+
+- Use `@povio/ui` before creating a custom primitive.
+- Do not let guidance from a general frontend or design skill replace an available `@povio/ui` primitive with raw HTML, a local reimplementation, or another component library.
+- Use semantic Tailwind tokens from the project theme.
+- Never manually edit `apps/fe/src/styles/theme.css`.
+- Avoid `!important`; resolve ownership or specificity instead.
+- Avoid inline `style` except for truly runtime numeric values such as map coordinates or calculated dimensions. Prefer CSS custom properties when descendants need the value.
+- Avoid Sass, CSS-in-JS, and a second styling system.
+- Preserve visible focus, disabled, hover, pressed, error, and loading states.
+- Respect `prefers-reduced-motion` for nonessential animation.
+- Keep touch targets at least 44 by 44 CSS pixels where practical.
+- Verify changes at mobile and desktop breakpoints.
+
+## Examples
+
+Use Tailwind for local layout:
+
+```tsx
+<section className="grid gap-4 rounded-modal-rounding-default border border-elevation-outline-default-1 bg-elevation-fill-default-1 p-4">
+  <Typography size="title-4">{title}</Typography>
+  {children}
+</section>
+```
+
+Use `UIConfig` for an existing global default:
+
+```tsx
+<UIConfig.Provider
+  config={{
+    input: { size: "small" },
+  }}
+>
+  {children}
+</UIConfig.Provider>
+```
+
+Use a scoped CSS file for a connected route line:
+
+```css
+.walk-route__marker::after {
+  content: "";
+  position: absolute;
+  inset-block: 1.25rem -0.75rem;
+  inset-inline-start: 50%;
+  width: 0.125rem;
+  background: rgb(var(--elevation-outline-default-1-base));
+  transform: translateX(-50%);
+}
+```
+
+Use `UIOverrides` only when the same primitive-level change is intentionally global:
+
+```ts
+export const tagOverride = UIOverrides.defineOverride("tag.cva", {
+  mode: "overrideCva",
+  base: ["inline-flex items-center border"],
+  config: {
+    variants: {
+      color: {
+        success: "border-interactive-subtle-success-idle bg-interactive-subtle-success-idle",
+      },
+    },
+  },
+});
+```
+
+## Verification
+
+1. Run formatting, linting, and TypeScript checks relevant to `apps/fe`.
+2. Inspect at least one representative use for every globally changed primitive.
+3. Check keyboard focus and disabled/error states.
+4. Check mobile and desktop layouts.
+5. Confirm no raw default-palette classes or duplicated design values were introduced.

package/templates/space/.rulesync/skills/povio-ui-styling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Povio UI Styling"
+  short_description: "Required first for all apps/fe UI work"
+  default_prompt: "Use $povio-ui-styling first for this apps/fe UI task, preserving @povio/ui primitives before applying other frontend guidance."

package/templates/space/.rulesync/skills/robodev-api-route/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: robodev-api-route
+description: Add a defineApi route under api/.
+---
+
+# Add a Robodev API route
+
+1. Create `api/<path>.ts` or `api/<path>/[id].ts`.
+2. Export HTTP methods with `defineApi` from `@robodev-ai/sdk`.
+3. Use `auth: "required"` unless the route is public.
+4. Keep JSON shapes aligned with `openapi.json`.
+5. Do not create `api/user/**` files.
+6. Deploy from the project root (`robodev deploy`), then `bun openapi:gen` in `apps/fe` if the contract changed.

package/templates/space/.rulesync/skills/robodev-table/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: robodev-table
+description: Add a Drizzle table to database.ts and wire it into defineApi handlers.
+---
+
+# Add a Robodev table
+
+1. Add a `pgTable` to `database.ts` and include it in `defineDatabase({ tables })`.
+2. Do not add a User table. Auth users are platform-managed; store `userId` as text.
+3. Import the table in `api/_lib.ts` or the route file that needs it.
+4. Deploy from the project root with `robodev deploy`. Destructive drops need confirmation or `--force`.
+5. If the frontend needs the new fields, update `openapi.json` and run `bun openapi:gen` from `apps/fe`.

package/templates/space/README.md

@@ -1,17 +1,36 @@
 # {{NAME}}
 
-Starter app from `robodev create`: a `space` database (`planets`, `rockets`), file-based APIs in `api/`, and a React UI.
+Starter from `robodev create`: Tiny Template schema (`planets`, `aliens`, `media`, `planet_likes`), file-based APIs in `api/`, and a **local** Povio UI in `apps/fe`.
 
-The project host is the app. After create or deploy, open the printed App URL — no `npm run dev` required. Local Vite is optional:
+The project host is **API-only**. After create or deploy, the printed App URL serves APIs and Swagger — not the SPA. Run the UI with bun:
 
 ```bash
-npm run dev
+cd apps/fe
+bun install
+bun openapi:gen
+bun dev
 ```
 
-Local Vite reads `VITE_API_URL` from `.env` (written by `robodev create` / `robodev link`). Hosted builds use the same origin as the APIs.
+Vite defaults to port **3000** (`VITE_DEV_PORT`). `bun` is required for `apps/fe`.
 
-Docs: https://robodev.povio.dev/docs
+Auth, link, and deploy from this **root**:
+
+```bash
+npx robodev auth
+npx robodev link
+npx robodev deploy
+```
+
+`robodev create` / `robodev link` write `VITE_API_URL`, `VITE_PUBLIC_API_URL`, and `APP_PUBLIC_API_URL` in `.env`, and rewrite `.config/local.spa.yml` so the FE talks to the project host.
+
+Dashboard create deploys schema + APIs only. The Tiny FE tree is copied by `robodev create`.
 
-`GET /me` and `GET /api/me` (`api/me.ts`) require a Robodev Auth Bearer token. Planet and rocket routes stay public. Optional browser helper: `@robodev-ai/client`. Auth how-to: https://robodev.povio.dev/docs/auth
+Auth stays reserved at `/api/user/*`. Do not add `api/user/**`.
 
-Edit files in the dashboard Code page, or here, then Save / `npx robodev deploy`.
+Regenerate AI rules after editing `.rulesync/`:
+
+```bash
+bun rules:gen
+```
+
+Docs: https://robodev.povio.dev/docs

package/templates/space/api/_lib.ts

@@ -0,0 +1,359 @@
+import { asc, eq, type InferSelectModel } from "@robodev-ai/sdk";
+import type { ApiHandlerContext } from "@robodev-ai/sdk";
+import { aliens, media, planetLikes, planets } from "../database";
+
+export const PLANET_IMAGE_RESOURCE = "planet-image";
+const DEFAULT_ORDER = "+name";
+const SORTABLE = new Set(["id", "name", "discoveryDate", "createdAt", "updatedAt"]);
+
+export const ALIEN_NAMES = [
+  "Andromedan",
+  "Arcturian",
+  "Betelgeusian",
+  "Centaurian",
+  "Denebian",
+  "Eridanian",
+  "Fomalhautian",
+  "Ganymedean",
+  "Hydran",
+  "Lyran",
+  "Orionid",
+  "Vegan",
+] as const;
+
+export const PLANET_SEEDS = [
+  ["Mercury", "Small rocky world closest to the system star"],
+  ["Venus", "Dense atmosphere with extreme surface temperatures"],
+  ["Earth", "Temperate ocean world with abundant life"],
+  ["Mars", "Cold desert world with polar ice caps"],
+  ["Jupiter", "Massive gas giant with a long-lived storm system"],
+  ["Saturn", "Ringed gas giant with many icy moons"],
+  ["Uranus", "Ice giant with a tilted rotation axis"],
+  ["Neptune", "Distant ice giant with high-speed winds"],
+  ["Kepler-22b", "Exoplanet candidate in a habitable-zone orbit"],
+  ["Proxima Centauri b", "Nearby terrestrial exoplanet orbiting a red dwarf"],
+  ["TRAPPIST-1e", "Compact-system rocky planet in a temperate orbit"],
+  ["HD 209458 b", "Hot gas giant with an observed atmosphere"],
+  ["Gliese 581g", "Candidate super-Earth in a nearby stellar system"],
+  ["LHS 1140 b", "Dense rocky super-Earth in a habitable-zone orbit"],
+  ["TOI-700 d", "Earth-size planet orbiting a small cool star"],
+  ["K2-18 b", "Sub-Neptune with detected atmospheric molecules"],
+  ["WASP-12b", "Ultra-hot gas giant closely orbiting its star"],
+  ["55 Cancri e", "Super-Earth with a very short orbital period"],
+  ["Kepler-452b", "Large terrestrial candidate orbiting a Sun-like star"],
+  ["GJ 1214 b", "Sub-Neptune with a hazy atmosphere"],
+  ["Ross 128 b", "Nearby temperate exoplanet around a quiet red dwarf"],
+  ["Tau Ceti e", "Candidate planet in a nearby Sun-like system"],
+  ["Wolf 1061 c", "Rocky candidate near the inner habitable zone"],
+  ["Teegarden's Star b", "Temperate Earth-mass candidate around a red dwarf"],
+  ["Kapteyn b", "Candidate super-Earth around an old nearby star"],
+  ["Kepler-186f", "Earth-size planet in a cool star's habitable zone"],
+  ["OGLE-2005-BLG-390Lb", "Cold distant world found by microlensing"],
+  ["HAT-P-7b", "Hot Jupiter with unusual atmospheric circulation"],
+  ["WASP-19b", "Hot Jupiter with a compact orbit"],
+  ["CoRoT-7b", "Rocky exoplanet with extreme dayside heating"],
+] as const;
+
+export type PlanetRow = InferSelectModel<typeof planets>;
+export type AlienRow = InferSelectModel<typeof aliens>;
+export type MediaRow = InferSelectModel<typeof media>;
+
+export type PlanetFilter = {
+  search?: string | null;
+  alienId?: string | null;
+  discoveryDate?: { start?: string | null; end?: string | null } | null;
+};
+
+export type PlanetDto = {
+  id: string;
+  userId: string;
+  alienId?: string | null;
+  discoveryDate?: string | null;
+  name: string;
+  description?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  image?: { id: string; url: string } | null;
+  creatorName?: string;
+  alienName?: string;
+  likesCount: number;
+  likedByMe: boolean;
+};
+
+export function fail(status: number, message: string) {
+  return { status, body: { message } };
+}
+
+export function iso(value: Date | string | null | undefined): string | null {
+  if (!value) return null;
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+export function requiredIso(value: Date | string | null | undefined): string {
+  return iso(value) ?? new Date().toISOString();
+}
+
+export function parseFilter(query: Record<string, unknown>): PlanetFilter {
+  const raw = query.filter;
+  if (typeof raw === "string" && raw.trim()) {
+    try {
+      return parseFilter(JSON.parse(raw) as Record<string, unknown>);
+    } catch {
+      return { search: raw };
+    }
+  }
+  if (raw && typeof raw === "object") {
+    const filter = raw as Record<string, unknown>;
+    const discovery = filter.discoveryDate;
+    return {
+      search: typeof filter.search === "string" ? filter.search : undefined,
+      alienId: typeof filter.alienId === "string" ? filter.alienId : null,
+      discoveryDate:
+        discovery && typeof discovery === "object"
+          ? (discovery as PlanetFilter["discoveryDate"])
+          : undefined,
+    };
+  }
+  const start = query["filter[discoveryDate][start]"] ?? query.discoveryDateStart;
+  const end = query["filter[discoveryDate][end]"] ?? query.discoveryDateEnd;
+  return {
+    search:
+      typeof query["filter[search]"] === "string"
+        ? (query["filter[search]"] as string)
+        : typeof query.search === "string"
+          ? query.search
+          : undefined,
+    alienId:
+      typeof query["filter[alienId]"] === "string"
+        ? (query["filter[alienId]"] as string)
+        : typeof query.alienId === "string"
+          ? query.alienId
+          : undefined,
+    discoveryDate:
+      typeof start === "string" || typeof end === "string"
+        ? {
+            start: typeof start === "string" ? start : null,
+            end: typeof end === "string" ? end : null,
+          }
+        : undefined,
+  };
+}
+
+function parseOrder(order: string | null | undefined) {
+  return (order || DEFAULT_ORDER)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((item) => {
+      const direction = item.startsWith("-") ? "desc" : "asc";
+      const key = item.replace(/^[+-]/, "");
+      return SORTABLE.has(key) ? { key, direction } : undefined;
+    })
+    .filter((item): item is { key: string; direction: "asc" | "desc" } => Boolean(item));
+}
+
+function compare(a: PlanetRow, b: PlanetRow, key: string, direction: "asc" | "desc") {
+  const aValue = a[key as keyof PlanetRow];
+  const bValue = b[key as keyof PlanetRow];
+  if (!aValue && !bValue) return 0;
+  if (!aValue) return 1;
+  if (!bValue) return -1;
+  const left = aValue instanceof Date ? aValue.toISOString() : String(aValue);
+  const right = bValue instanceof Date ? bValue.toISOString() : String(bValue);
+  const result = left.localeCompare(right);
+  return direction === "asc" ? result : -result;
+}
+
+export function sortPlanets(rows: PlanetRow[], order: string | null | undefined) {
+  const sorting = parseOrder(order);
+  return [...rows].sort((a, b) => {
+    for (const sort of sorting) {
+      const result = compare(a, b, sort.key, sort.direction);
+      if (result !== 0) return result;
+    }
+    return a.name.localeCompare(b.name);
+  });
+}
+
+export function filterPlanetRows(
+  rows: PlanetRow[],
+  alienById: Map<string, AlienRow>,
+  filters: PlanetFilter | undefined,
+) {
+  if (!filters) return rows;
+  const search = filters.search?.trim().toLocaleLowerCase();
+  return rows.filter((planet) => {
+    if (search) {
+      const haystack = [
+        planet.name,
+        planet.description,
+        planet.creatorName,
+        planet.alienId ? alienById.get(planet.alienId)?.name : undefined,
+      ];
+      if (!haystack.some((value) => value?.toLocaleLowerCase().includes(search))) {
+        return false;
+      }
+    }
+    if (filters.alienId && planet.alienId !== filters.alienId) return false;
+    const range = filters.discoveryDate;
+    if (range?.start || range?.end) {
+      if (!planet.discoveryDate) return false;
+      const timestamp = Date.parse(requiredIso(planet.discoveryDate));
+      if (range.start && timestamp < Date.parse(range.start)) return false;
+      if (range.end && timestamp > Date.parse(range.end)) return false;
+    }
+    return true;
+  });
+}
+
+export function paginate<T>(items: T[], page?: number, limit?: number) {
+  const currentPage = page && page > 0 ? page : 1;
+  const currentLimit = limit && limit > 0 ? Math.min(limit, 20) : 20;
+  const start = (currentPage - 1) * currentLimit;
+  const nextPage = currentPage * currentLimit < items.length ? currentPage + 1 : null;
+  return {
+    items: items.slice(start, start + currentLimit),
+    page: currentPage,
+    cursor: String(currentPage),
+    nextCursor: nextPage ? String(nextPage) : null,
+    limit: currentLimit,
+    totalItems: items.length,
+  };
+}
+
+export async function ensureSeed(db: ApiHandlerContext<unknown, unknown>["db"], userId: string) {
+  const existingAliens = await db.select({ id: aliens.id }).from(aliens).limit(1);
+  if (existingAliens.length === 0) {
+    const now = new Date();
+    try {
+      await db.insert(aliens).values(
+        ALIEN_NAMES.map((name) => ({
+          name,
+          createdAt: now,
+          updatedAt: now,
+        })),
+      );
+    } catch {
+      // First request won the seed race.
+    }
+  }
+
+  const existingPlanets = await db.select({ id: planets.id }).from(planets).limit(1);
+  if (existingPlanets.length > 0) return;
+
+  const alienRows = await db.select().from(aliens).orderBy(asc(aliens.name));
+  if (alienRows.length === 0) return;
+  const now = new Date();
+  try {
+    await db.insert(planets).values(
+      PLANET_SEEDS.map(([name, description], index) => ({
+        userId,
+        creatorName: "Demo User",
+        alienId: alienRows[index % alienRows.length]?.id ?? null,
+        discoveryDate:
+          index % 2 === 0
+            ? new Date(`20${String(index + 1).padStart(2, "0")}-01-01T00:00:00.000Z`)
+            : null,
+        name,
+        description,
+        createdAt: now,
+        updatedAt: now,
+      })),
+    );
+  } catch {
+    // First request won the seed race.
+  }
+}
+
+export async function resolveImage(
+  ctx: ApiHandlerContext<unknown, unknown>,
+  imageId: string | null | undefined,
+): Promise<{ id: string; url: string } | null> {
+  if (!imageId) return null;
+  const [row] = await ctx.db.select().from(media).where(eq(media.id, imageId)).limit(1);
+  if (!row?.uploaded) return null;
+  try {
+    const url = await ctx.storage.getUrl(row.key);
+    return { id: row.id, url };
+  } catch {
+    return { id: row.id, url: `/storage/objects/${encodeURIComponent(row.key)}` };
+  }
+}
+
+export async function enrichPlanet(
+  ctx: ApiHandlerContext<unknown, unknown>,
+  planet: PlanetRow,
+  currentUserId: string,
+  alienById: Map<string, AlienRow>,
+  likes: { planetId: string; userId: string }[],
+): Promise<PlanetDto> {
+  const planetLikes = likes.filter((like) => like.planetId === planet.id);
+  return {
+    id: planet.id,
+    userId: planet.userId,
+    alienId: planet.alienId,
+    discoveryDate: iso(planet.discoveryDate),
+    name: planet.name,
+    description: planet.description,
+    createdAt: requiredIso(planet.createdAt),
+    updatedAt: requiredIso(planet.updatedAt),
+    image: await resolveImage(ctx, planet.imageId),
+    creatorName: planet.creatorName ?? undefined,
+    alienName: planet.alienId ? alienById.get(planet.alienId)?.name : undefined,
+    likesCount: planetLikes.length,
+    likedByMe: planetLikes.some((like) => like.userId === currentUserId),
+  };
+}
+
+export async function loadLookups(db: ApiHandlerContext<unknown, unknown>["db"]) {
+  const [alienRows, likeRows] = await Promise.all([
+    db.select().from(aliens),
+    db.select({ planetId: planetLikes.planetId, userId: planetLikes.userId }).from(planetLikes),
+  ]);
+  return {
+    alienById: new Map(alienRows.map((row) => [row.id, row])),
+    likes: likeRows,
+  };
+}
+
+export async function enrichOne(
+  ctx: ApiHandlerContext<unknown, unknown>,
+  planet: PlanetRow,
+  currentUserId: string,
+) {
+  const lookups = await loadLookups(ctx.db);
+  return enrichPlanet(ctx, planet, currentUserId, lookups.alienById, lookups.likes);
+}
+
+export async function findPlanet(db: ApiHandlerContext<unknown, unknown>["db"], id: string) {
+  const [row] = await db.select().from(planets).where(eq(planets.id, id)).limit(1);
+  return row ?? null;
+}
+
+export async function validateAlien(
+  db: ApiHandlerContext<unknown, unknown>["db"],
+  alienId: string | null | undefined,
+) {
+  if (!alienId) return null;
+  const [row] = await db.select().from(aliens).where(eq(aliens.id, alienId)).limit(1);
+  return row ?? null;
+}
+
+export async function validateImage(
+  db: ApiHandlerContext<unknown, unknown>["db"],
+  image: { id: string } | null | undefined,
+  userId: string,
+) {
+  if (!image) return null;
+  const [row] = await db.select().from(media).where(eq(media.id, image.id)).limit(1);
+  if (!row) return { error: fail(404, "Media not found") };
+  if (row.userId !== userId) return { error: fail(403, "You can only use your own media") };
+  if (row.resourceName !== PLANET_IMAGE_RESOURCE) {
+    return { error: fail(400, "Media cannot be used as a planet image") };
+  }
+  if (!row.uploaded)
+    return { error: fail(400, "Media must be uploaded before it can be attached") };
+  return { id: row.id };
+}
+
+export { aliens, media, planetLikes, planets };

package/templates/space/api/aliens/labels.ts

@@ -0,0 +1,19 @@
+import { defineApi, z } from "@robodev-ai/sdk";
+import { aliens, ensureSeed } from "../_lib";
+
+export const get = defineApi({
+  auth: "required",
+  query: z.object({
+    search: z.string().optional(),
+  }),
+  handler: async (ctx) => {
+    await ensureSeed(ctx.db, ctx.user!.id);
+    const search = ctx.query.search?.trim().toLocaleLowerCase();
+    const rows = await ctx.db.select().from(aliens);
+    return rows
+      .filter((row) => !search || row.name.toLocaleLowerCase().includes(search))
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .slice(0, 50)
+      .map((row) => ({ id: row.id, label: row.name }));
+  },
+});