robodev 0.22.0 → 0.24.0

package/templates/marketplace/.rulesync/rules/robodev-auth.md

@@ -0,0 +1,40 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Reserved Robodev /api/user auth contracts."
+globs: ["**/*.ts", "apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when touching auth, login, register, or /api/user clients."
+  globs:
+    [
+      "database.ts",
+      "api/**/*.ts",
+      "apps/fe/src/components/features/auth/**/*.{ts,tsx}",
+      "apps/fe/src/clients/**/*.ts",
+    ]
+---
+
+# Robodev Auth
+
+End-user auth is reserved on the project host. Do not implement `api/user/**` in this project.
+
+## Contracts
+
+| Method  | Path                                      | Notes                                                   |
+| ------- | ----------------------------------------- | ------------------------------------------------------- |
+| POST    | `/api/user/auth/login`                    | `{ email, password }` → `{ accessToken, refreshToken }` |
+| POST    | `/api/user/auth/register`                 | password min 12, 201, token pair                        |
+| POST    | `/api/user/auth/refresh`                  | `{ refreshToken }` → new pair                           |
+| GET     | `/api/user/auth/magic-link`               | query `email`, generic status                           |
+| GET     | `/api/user/auth/magic-link/callback`      | query `code` → tokens                                   |
+| POST    | `/api/user/auth/forgot-password`          | `{ email }`                                             |
+| POST    | `/api/user/auth/forgot-password/callback` | `{ code, password }`                                    |
+| GET     | `/api/user/auth/google`                   | start OAuth; `redirect_uri` required                    |
+| GET/PUT | `/api/user/me`                            | flat `{ id, name, email }`                              |
+
+Access tokens last 15 minutes. Refresh tokens last 30 days. Frontend stores both and refreshes on 401 via `UserAuthApi.accessToken`.
+
+Error `code` is top-level: `invalid-credentials`, `identity-already-exists`, `identity-not-found`, `nonce-invalid`.
+
+Codegen operationIds stay Tiny-shaped (`UserAuthLocalPasswordController_login`, `UserMeController_get`, …) in `openapi.json`.

package/templates/marketplace/.rulesync/rules/robodev-database.md

@@ -0,0 +1,22 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Robodev database.ts Drizzle schema and deploy sync."
+globs: ["database.ts"]
+cursor:
+  alwaysApply: false
+  description: "Apply when editing the Starbase database schema."
+  globs: ["database.ts"]
+---
+
+# Robodev Database
+
+The backend schema lives in `database.ts` at the project root. Default-export `defineDatabase` with Drizzle `pgTable` definitions. `robodev deploy` from this root creates or syncs the named Postgres database. There are no migration files.
+
+## Rules
+
+- Import table helpers from `@robodev-ai/sdk` (`pgTable`, `uuid`, `text`, `timestamp`, `integer`, and query helpers).
+- Do not recreate User or auth tables. End users live in platform `robodev_auth`. Store `userId` as `text` matching `ctx.user.id`.
+- Prefer scalar columns and foreign keys. Destructive drops need deploy confirmation or `--force`.
+- Export named tables so API files can import them from `../database` or `api/_lib.ts`.
+- Seed demo rows in API handlers on first read (see `api/_lib.ts` `ensureSeed`), not with a separate seed runner.

package/templates/marketplace/.rulesync/rules/role-based-app-structure.md

@@ -0,0 +1,36 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Conditional role-based frontend and API structure for apps with distinct user roles."
+globs: ["apps/fe/src/**/*.{ts,tsx}", "api/**/*.ts"]
+cursor:
+  alwaysApply: false
+  description: "Apply only when an app has multiple user roles with distinct UI surfaces or business workflows."
+  globs: ["apps/fe/src/**/*.{ts,tsx}", "api/**/*.ts"]
+---
+
+# Role-Based App Structure
+
+Apply this rule only when the app has multiple user roles with meaningfully different UI surfaces or business workflows. For single-role apps or small permission differences, keep normal feature-based structure and express authorization in handlers, ACL metadata, or UI affordances.
+
+## Frontend Structure
+
+Split role-specific frontend code by role first:
+
+- `apps/fe/src/components/features/<role>/<feature>/...` for role-owned feature UI, such as `admin/companies`, `manager/projects`, or `worker/timesheets`.
+- `apps/fe/src/pages/(private)/(<role>)/...` for role-owned private routes and layout guards.
+- Shared auth, profile, layout, and role-neutral UI should stay outside role folders.
+
+When two roles touch the same entity with different screens or permissions, prefer separate role-owned feature components over a single component with many role branches.
+
+## API Structure
+
+Create role-prefixed `defineApi` files for role-owned behavior even when the backing table is shared. For example, use `api/manager/projects.ts` and `api/worker/projects.ts` when managers can create projects while workers can only list assigned ones.
+
+Role-prefixed routes should keep the role visible across the API surface:
+
+- Files: `api/<role>/<resource>.ts`, such as `api/manager/projects.ts`.
+- HTTP paths: `/api/<role>/<resource>`, such as `/api/manager/projects/paginate`.
+- Generated client modules should follow the same names.
+
+Keep shared auth, user, and media contracts role-neutral. Auth stays reserved at `/api/user/*`.

package/templates/marketplace/.rulesync/skills/media-feature/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: media-feature
+description: "Use when adding or changing feature-level media/file upload support or frontend FileUpload handling."
+targets: ["claudecode", "codexcli", "cursor"]
+codexcli:
+  short-description: Add or update media upload support for features.
+---
+
+# Media Feature Skill
+
+Preserve the upload contract:
+
+1. Frontend selects `File` values and keeps them local until submit. Do not call `/api/files/*`.
+2. Feature create/update is one `multipart/form-data` request (`POST` / `PUT`) with text fields and one or more files (`file` / `files`). Cap is about 8 images (jpeg/png/webp, 2MB each).
+3. The handler validates text fields, calls `saveListingImage` for each file (`ctx.storage.upload` public, resource name `listing-image`), and writes `listing_images` rows.
+4. Update may append new files and/or remove existing images by media id (`removeImageIds`). New files are added after remaining images.
+5. Feature reads resolve stored media IDs to `images: { id, url }[]`.
+
+Never use a standalone files API. File bytes stay on the device until submit.
+
+Media metadata lives in the `media` table in `database.ts`. Bytes live in Robodev storage. Listing images use resource name `listing-image`.

package/templates/marketplace/.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/marketplace/.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/marketplace/.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/marketplace/.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/marketplace/README.md

@@ -0,0 +1,40 @@
+# {{NAME}}
+
+Starter from `robodev create --starter marketplace`: Tiny C2C marketplace schema (`categories`, `listings`, `cart_items`, `orders`, `watches`, `reviews`, `media`), file-based APIs in `api/`, and a Povio UI in `apps/fe`.
+
+After a CLI create or deploy with `.robodev` `frontend` set (the default for this starter), the project host serves the built Tiny SPA at `GET /`. APIs and Swagger still win over static files.
+
+Local Starbase occupies FE **:3000** and BE **:4000**. Point the CLI at it, then run starter Vite on **3001** so it does not steal the dashboard port:
+
+```bash
+STARBASE_URL=http://localhost:4000 STARBASE_FE_URL=http://localhost:3000
+# from starter root: auth / link / deploy as today
+cd apps/fe
+bun install
+bun openapi:gen
+bunx --bun vite --port 3001
+```
+
+`bun` is required for `apps/fe`.
+
+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`, rewrite `.config/local.spa.yml` so the FE talks to the project host, and (when `apps/fe/package.json` exists) add a `frontend` block to `.robodev`. `robodev deploy` then runs the local Vite build and uploads the static output.
+
+Dashboard create deploys schema + APIs only. The Tiny FE tree is copied by `robodev create`; a later CLI deploy hosts the SPA.
+
+Auth stays reserved at `/api/user/*`. Do not add `api/user/**`.
+
+Regenerate AI rules after editing `.rulesync/`:
+
+```bash
+bun rules:gen
+```
+
+Docs: https://robodev.povio.dev/docs