npm - robodev - Versions diffs - 0.11.0 → 0.13.0 - Mend

robodev 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (329) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "robodev",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "CLI for Robodev Starbase — create, auth, link, and deploy hosted apps",
   "type": "module",
   "license": "MIT",

package/src/collect-files.test.ts CHANGED Viewed

@@ -45,3 +45,22 @@ test("collectFiles includes hosted sources and skips denied paths", async () =>
     await rm(root, { recursive: true, force: true });
   }
 });
+test("collectFiles skips nested apps/fe sources", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rd-cli-"));
+  try {
+    await writeFile(join(root, "database.ts"), "export default {}");
+    await mkdir(join(root, "apps/fe/src"), { recursive: true });
+    await writeFile(join(root, "apps/fe/src/main.tsx"), "export {}");
+    await writeFile(join(root, "apps/fe/index.html"), "<html></html>");
+    await writeFile(join(root, "apps/fe/package.json"), "{}");
+    const files = await collectFiles(root);
+    const paths = new Set(files.map((file) => file.path));
+    assert.ok(paths.has("database.ts"));
+    assert.ok(!paths.has("apps/fe/src/main.tsx"));
+    assert.ok(!paths.has("apps/fe/index.html"));
+    assert.ok(!paths.has("apps/fe/package.json"));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/collect-files.ts CHANGED Viewed

@@ -86,6 +86,7 @@ function isUnsafe(path: string): boolean {
 function isDenied(path: string): boolean {
   const top = path.split("/")[0];
   if (SKIP_DIRS.has(top)) return true;
+  if (path === "apps" || path.startsWith("apps/")) return true;
   if (path === ".env" || path.startsWith(".env.")) return true;
   const name = basename(path);
   if (name.startsWith(".") && name !== ".gitignore") return true;

package/src/config.test.ts ADDED Viewed

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { writeViteApiUrl } from "./config.js";
+test("writeViteApiUrl sets Vite and Povio public API URLs", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rd-env-"));
+  try {
+    await mkdir(join(root, ".config"), { recursive: true });
+    await writeFile(
+      join(root, ".config/local.spa.template.yml"),
+      `APP_PUBLIC_API_URL: &APP_PUBLIC_API_URL "http://localhost:4000"\nVITE_PUBLIC_API_URL: *APP_PUBLIC_API_URL\n`,
+    );
+    await writeViteApiUrl("https://prj.example.test", root);
+    const env = await readFile(join(root, ".env"), "utf8");
+    assert.match(env, /^VITE_API_URL=https:\/\/prj\.example\.test$/m);
+    assert.match(env, /^VITE_PUBLIC_API_URL=https:\/\/prj\.example\.test$/m);
+    assert.match(env, /^APP_PUBLIC_API_URL=https:\/\/prj\.example\.test$/m);
+    const spa = await readFile(join(root, ".config/local.spa.yml"), "utf8");
+    assert.match(spa, /APP_PUBLIC_API_URL: &APP_PUBLIC_API_URL "https:\/\/prj\.example\.test"/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/config.ts CHANGED Viewed

@@ -65,7 +65,17 @@ export async function writeLink(link: ProjectLink, cwd = process.cwd()): Promise
   await writeFile(linkPath(cwd), `${JSON.stringify(link, null, 2)}\n`);
 }
-/** Sets `VITE_API_URL` so the starter UI talks to the deployed project host. */
+const PROJECT_API_ENV_KEYS = ["VITE_API_URL", "VITE_PUBLIC_API_URL", "APP_PUBLIC_API_URL"] as const;
+function upsertEnvKey(content: string, key: string, value: string): string {
+  const line = `${key}=${value}`;
+  const pattern = new RegExp(`^${key}=.*$`, "m");
+  if (pattern.test(content)) return content.replace(pattern, line);
+  const trimmed = content.replace(/\s*$/, "");
+  return `${trimmed}${trimmed ? "\n" : ""}${line}\n`;
+}
+/** Sets Vite / Povio API URLs so starter UIs talk to the deployed project host. */
 export async function writeViteApiUrl(projectApiUrl: string, cwd = process.cwd()): Promise<void> {
   const envPath = join(cwd, ".env");
   let content = "";
@@ -74,10 +84,29 @@ export async function writeViteApiUrl(projectApiUrl: string, cwd = process.cwd()
   } catch {
     content = "";
   }
-  if (/^VITE_API_URL=/m.test(content)) {
-    content = content.replace(/^VITE_API_URL=.*$/m, `VITE_API_URL=${projectApiUrl}`);
-  } else {
-    content = `${content.replace(/\s*$/, "")}${content ? "\n" : ""}VITE_API_URL=${projectApiUrl}\n`;
+  for (const key of PROJECT_API_ENV_KEYS) {
+    content = upsertEnvKey(content, key, projectApiUrl);
   }
   await writeFile(envPath, content.endsWith("\n") ? content : `${content}\n`);
+  await rewriteLocalSpaConfig(projectApiUrl, cwd);
+}
+async function rewriteLocalSpaConfig(projectApiUrl: string, cwd: string): Promise<void> {
+  const configDir = join(cwd, ".config");
+  const templatePath = join(configDir, "local.spa.template.yml");
+  const destPath = join(configDir, "local.spa.yml");
+  let source: string;
+  try {
+    source = await readFile(templatePath, "utf8");
+  } catch {
+    try {
+      source = await readFile(destPath, "utf8");
+    } catch {
+      return;
+    }
+  }
+  const quoted = JSON.stringify(projectApiUrl);
+  const next = source.replace(/^(APP_PUBLIC_API_URL:\s*&APP_PUBLIC_API_URL\s+).+$/m, `$1${quoted}`);
+  await mkdir(configDir, { recursive: true });
+  await writeFile(destPath, next.endsWith("\n") ? next : `${next}\n`);
 }

package/src/emit-starter.test.ts ADDED Viewed

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { collectFiles } from "./collect-files.js";
+import { cliRoot, emitStarter } from "./emit-starter.js";
+const versions = { robodev: "0.12.0", sdk: "0.12.0", client: "0.12.0" };
+test("emitStarter rewrites root package.json name only", async () => {
+  const dest = await mkdtemp(join(tmpdir(), "rd-emit-"));
+  try {
+    await emitStarter(join(cliRoot(), "..", "starters", "space"), dest, {
+      name: "Orbit",
+      packageName: "orbit-app",
+      title: "Space",
+      versions,
+    });
+    const rootPkg = JSON.parse(await readFile(join(dest, "package.json"), "utf8")) as {
+      name: string;
+    };
+    const fePkg = JSON.parse(await readFile(join(dest, "apps/fe/package.json"), "utf8")) as {
+      name: string;
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    assert.equal(rootPkg.name, "orbit-app");
+    assert.equal(fePkg.name, "fe");
+    assert.equal(fePkg.dependencies?.robodev, undefined);
+    assert.equal(fePkg.devDependencies?.robodev, undefined);
+    const overview = await readFile(join(dest, ".rulesync/rules/project-overview.md"), "utf8");
+    assert.match(overview, /^# Space starter AI rules/m);
+    const readme = await readFile(join(dest, "README.md"), "utf8");
+    assert.match(readme, /^# Orbit/m);
+  } finally {
+    await rm(dest, { recursive: true, force: true });
+  }
+});
+test("collectFiles for auth-chat starter is Tiny APIs without apps/fe", async () => {
+  const files = await collectFiles(join(cliRoot(), "..", "starters", "auth-chat"));
+  const paths = new Set(files.map((file) => file.path));
+  assert.ok(paths.has("database.ts"));
+  assert.ok(paths.has("api/messages.ts"));
+  assert.ok(paths.has("api/invite.ts"));
+  assert.ok(paths.has("api/health.ts"));
+  assert.ok(paths.has("api/me.ts"));
+  assert.ok(!paths.has("index.html"));
+  assert.ok(!paths.has("src/main.tsx"));
+  assert.ok([...paths].every((path) => !path.startsWith("apps/")));
+  assert.ok(files.length < 200);
+});
+test("collectFiles for space starter is Tiny APIs without apps/fe", async () => {
+  const files = await collectFiles(join(cliRoot(), "..", "starters", "space"));
+  const paths = new Set(files.map((file) => file.path));
+  assert.ok(paths.has("database.ts"));
+  assert.ok(paths.has("api/planets.ts"));
+  assert.ok(paths.has("api/planets/paginate.ts"));
+  assert.ok(paths.has("api/aliens/labels.ts"));
+  assert.ok(paths.has("api/files/presigned-url.ts"));
+  assert.ok(paths.has("api/files/upload.ts"));
+  assert.ok(!paths.has("index.html"));
+  assert.ok(!paths.has("src/main.tsx"));
+  assert.ok([...paths].every((path) => !path.startsWith("apps/")));
+  assert.ok(files.length < 200);
+});

package/src/emit-starter.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 export type Starter = {
@@ -23,6 +23,20 @@ export type EmitContext = {
 };
 const SKIP_DIRS = new Set(["node_modules", ".robodev", ".git"]);
+const BINARY_COPY_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".ico",
+  ".bmp",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".otf",
+]);
 type DepMap = Record<string, string>;
@@ -103,22 +117,35 @@ export async function loadPackageVersions(): Promise<PackageVersions> {
 }
 /** Copies a starter tree and applies package + display rewrites used by create and prepack. */
-export async function emitStarter(src: string, dest: string, ctx: EmitContext): Promise<void> {
+export async function emitStarter(
+  src: string,
+  dest: string,
+  ctx: EmitContext,
+  isRoot = true,
+): Promise<void> {
   await mkdir(dest, { recursive: true });
   const entries = await readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name)) continue;
-      await emitStarter(join(src, entry.name), join(dest, entry.name), ctx);
+      await emitStarter(join(src, entry.name), join(dest, entry.name), ctx, false);
       continue;
     }
     if (!entry.isFile() || entry.name === ".env") continue;
-    const content = await readFile(join(src, entry.name), "utf8");
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (BINARY_COPY_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      await copyFile(srcPath, destPath);
+      continue;
+    }
+    const content = await readFile(srcPath, "utf8");
     const next =
       entry.name === "package.json"
-        ? rewritePackageJson(content, ctx)
-        : rewriteDisplay(content, ctx);
-    await writeFile(join(dest, entry.name), next);
+        ? rewritePackageJson(content, ctx, isRoot)
+        : shouldRewriteDisplay(entry.name, isRoot)
+          ? rewriteDisplay(content, ctx)
+          : content;
+    await writeFile(destPath, next);
   }
 }
@@ -154,9 +181,14 @@ async function readPackageVersion(path: string, fallback?: string): Promise<stri
   throw new Error(`Missing version in ${path}`);
 }
-function rewritePackageJson(raw: string, ctx: EmitContext): string {
+function shouldRewriteDisplay(fileName: string, isRoot: boolean): boolean {
+  if (!isRoot) return false;
+  return fileName === "README.md" || fileName.endsWith(".html");
+}
+function rewritePackageJson(raw: string, ctx: EmitContext, isRoot: boolean): string {
   const pkg = JSON.parse(raw) as PackageJson;
-  pkg.name = ctx.packageName;
+  if (isRoot) pkg.name = ctx.packageName;
   const pins: Record<string, string> = {
     robodev: `^${ctx.versions.robodev}`,
@@ -172,9 +204,11 @@ function rewritePackageJson(raw: string, ctx: EmitContext): string {
   }
   const moved = pkg.dependencies?.robodev;
-  if (pkg.dependencies) delete pkg.dependencies.robodev;
-  pkg.devDependencies = pkg.devDependencies ?? {};
-  pkg.devDependencies.robodev = pkg.devDependencies.robodev ?? moved ?? pins.robodev;
+  if (isRoot) {
+    if (pkg.dependencies) delete pkg.dependencies.robodev;
+    pkg.devDependencies = pkg.devDependencies ?? {};
+    pkg.devDependencies.robodev = pkg.devDependencies.robodev ?? moved ?? pins.robodev;
+  }
   return `${JSON.stringify(pkg, null, 2)}\n`;
 }

package/src/index.ts CHANGED Viewed

@@ -397,6 +397,36 @@ async function npmInstall(root: string): Promise<void> {
   });
 }
+async function bunAvailable(): Promise<boolean> {
+  try {
+    await execFileAsync("bun", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function hasAppsFe(root: string): Promise<boolean> {
+  try {
+    return (await stat(join(root, "apps/fe"))).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function printFeNextSteps(displayPath: string): void {
+  if (displayPath !== ".") {
+    console.log(`  cd ${displayPath}`);
+  }
+  console.log("  cd apps/fe");
+  console.log("  bun install");
+  console.log("  bun openapi:gen");
+  console.log("  bun dev");
+  console.log(
+    "  Open the Vite URL (default http://localhost:3000). The project App URL is APIs and Swagger, not this UI.",
+  );
+}
 /** Creates a Starbase project, copies the chosen starter, links, deploys, and installs deps. */
 async function runCreate(args: string[]): Promise<void> {
   const parsed = parseCreateArgs(args);
@@ -442,6 +472,9 @@ async function runCreate(args: string[]): Promise<void> {
         "npm install failed. Copy the API URL printed above into Lovable, Bolt, or v0 as VITE_API_URL.",
       );
       console.log("https://robodev.povio.dev/docs/frontend");
+    } else if (await hasAppsFe(root)) {
+      console.log("Run `npm install` in the project folder.");
+      console.log("bun is required for apps/fe. APIs are already deployed.");
     } else {
       console.log("Run `npm install` in the project folder, then `npm run dev`.");
     }
@@ -451,14 +484,22 @@ async function runCreate(args: string[]): Promise<void> {
   const displayPath = relative(process.cwd(), root) || ".";
   console.log("");
   console.log("Next:");
-  if (displayPath !== ".") {
-    console.log(`  cd ${displayPath}`);
-  }
-  if (starter.kind === "backend") {
+  if (await hasAppsFe(root)) {
+    if (!(await bunAvailable())) {
+      console.log("bun is required for apps/fe. APIs are already deployed.");
+    }
+    printFeNextSteps(displayPath);
+  } else if (starter.kind === "backend") {
+    if (displayPath !== ".") {
+      console.log(`  cd ${displayPath}`);
+    }
     console.log("  Copy the API URL printed above into Lovable, Bolt, or v0 as VITE_API_URL.");
     console.log("  Do not run robodev deploy or npm run build inside those tools.");
     console.log("  https://robodev.povio.dev/docs/frontend");
   } else {
+    if (displayPath !== ".") {
+      console.log(`  cd ${displayPath}`);
+    }
     console.log("  npm run dev");
   }
 }

package/templates/auth-chat/.config/local.spa.template.yml ADDED Viewed

@@ -0,0 +1,27 @@
+STAGE: "local"
+OUTPUT: "export"
+ANALYZE: "false"
+NEXT_TELEMETRY_DISABLED: "1"
+VITE_PUBLIC_RELEASE: ${env:RELEASE}
+VITE_PUBLIC_STAGE: ${func:stage}
+APP_PUBLIC_API_URL: &APP_PUBLIC_API_URL "http://localhost:4000"
+APP_PUBLIC_API_MODE: &APP_PUBLIC_API_MODE "real"
+VITE_PUBLIC_API_URL: *APP_PUBLIC_API_URL
+VITE_PUBLIC_API_MODE: *APP_PUBLIC_API_MODE
+VITE_PUBLIC_LOG_LEVEL: "trace"
+VITE_PUBLIC_SENTRY_DSN: ""
+VITE_PUBLIC_SENTRY_ENVIRONMENT: ${func:stage}
+VITE_PUBLIC_SENTRY_TRACES_SAMPLE_RATE: "0"
+VITE_PUBLIC_SENTRY_REPLAYS_SESSION_SAMPLE_RATE: "0"
+VITE_PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE: "0"
+VITE_PUBLIC_AUTH_CUSTOM_JWT_ENABLE_MAGIC_LINK: "true"
+VITE_PUBLIC_GOOGLE_ANALYTICS_MEASUREMENT_ID: ""
+VITE_DEV_PORT: "3000"

package/templates/auth-chat/.oxlint-base.json ADDED Viewed

@@ -0,0 +1,29 @@
+{
+  "$schema": "apps/fe/node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "typescript", "unicorn", "import", "oxc", "promise", "vitest"],
+  "categories": {
+    "correctness": "error",
+    "perf": "error",
+    "pedantic": "off",
+    "style": "off",
+    "restriction": "off",
+    "suspicious": "off",
+    "nursery": "off"
+  },
+  "env": {
+    "builtin": true,
+    "node": true,
+    "shared-node-browser": true
+  },
+  "rules": {
+    "eslint/eqeqeq": [
+      "error",
+      "always",
+      {
+        "null": "ignore"
+      }
+    ],
+    "typescript/no-floating-promises": "off",
+    "eslint/capitalized-comments": "off"
+  }
+}

package/templates/auth-chat/.oxlintrc.json ADDED Viewed

@@ -0,0 +1,78 @@
+{
+  "$schema": "apps/fe/node_modules/oxlint/configuration_schema.json",
+  "extends": [".oxlint-base.json"],
+  "plugins": [
+    "eslint",
+    "typescript",
+    "unicorn",
+    "import",
+    "vitest",
+    "react",
+    "react-perf",
+    "jsx-a11y"
+  ],
+  "categories": {
+    "style": "error"
+  },
+  "ignorePatterns": [
+    "openapi-codegen.config.ts",
+    "postcss.config.js",
+    "out",
+    "dist",
+    "public",
+    "scripts",
+    ".vscode",
+    ".turbo",
+    "node_modules",
+    "apps/fe/src/routeTree.gen.ts",
+    "apps/fe/src/openapi",
+    "apps/fe/public"
+  ],
+  "overrides": [
+    {
+      "files": ["vite-plugin-*.ts", "apps/fe/vite-plugin-*.ts"],
+      "rules": {
+        "import/no-nodejs-modules": "off"
+      }
+    }
+  ],
+  "rules": {
+    "eslint/no-implicit-coercion": "off",
+    "no-map-spread": "off",
+    "eslint/sort-keys": "off",
+    "eslint/sort-imports": "off",
+    "eslint/no-ternary": "off",
+    "eslint/id-length": "off",
+    "eslint/no-magic-numbers": "off",
+    "eslint/arrow-body-style": "off",
+    "eslint/max-params": "off",
+    "eslint/func-style": "off",
+    "eslint/new-cap": "off",
+    "eslint/no-continue": "off",
+    "eslint/max-statements": "off",
+    "eslint/no-duplicate-imports": [
+      "error",
+      {
+        "allowSeparateTypeImports": true
+      }
+    ],
+    "react/exhaustive-deps": "off",
+    "react/jsx-props-no-spreading": "off",
+    "react/jsx-max-depth": "off",
+    "react-perf/jsx-no-new-object-as-prop": "off",
+    "react-perf/jsx-no-new-function-as-prop": "off",
+    "react-perf/jsx-no-new-array-as-prop": "off",
+    "react-perf/jsx-no-jsx-as-prop": "off",
+    "typescript/no-empty-interface": "off",
+    "import/no-named-export": "off",
+    "import/group-exports": "off",
+    "import/prefer-default-export": "off",
+    "import/exports-last": "off",
+    "import/consistent-type-specifier-style": "off",
+    "jest/require-hook": "off",
+    "unicorn/filename-case": "off",
+    "unicorn/prefer-global-this": "off",
+    "unicorn/no-await-expression-member": "off",
+    "unicorn/no-null": "off"
+  }
+}

package/templates/auth-chat/.rulesync/rules/frontend-api-boundary.md ADDED Viewed

@@ -0,0 +1,36 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend must consume generated OpenAPI queries and models, not backend internals."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when editing frontend components, hooks, providers, pages, or clients that call the API."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+# Frontend API Boundary
+Frontend application code must consume the API through generated files in `apps/fe/src/openapi`.
+Use generated modules such as:
+- `@/openapi/<domain>/<domain>.queries`
+- `@/openapi/<domain>/<domain>.models`
+- `@/openapi/queryModules`
+For generated mutations, pass invalidation through the mutation options instead of importing `queryClient` or calling `invalidateQueries` with generated query keys. The current module is invalidated by default through `invalidateCurrentModule: true`; invalidate dependent modules explicitly with `invalidateModules: [QueryModule.someModule]`.
+After mutations, derive follow-up UI state from canonical API response or query state instead of leaving action controls unchanged. Disable duplicate submissions when the API state already represents a pending or completed action, and surface mutation errors through the default generated-client error handler or a feature-specific message.
+Do not import `@robodev-ai/sdk`, `database.ts`, Drizzle tables, or API helper modules into frontend features.
+`apps/fe/src/openapi` is generated by `@povio/openapi-codegen-cli` from root `openapi.json` (or a live project `/openapi.json` when `OPENAPI_LIVE=true`). Do not hand-edit generated OpenAPI client files.
+When API contracts change:
+1. Update `api/` handlers and `openapi.json` if the documented contract changed.
+2. Run `bun openapi:gen` from `apps/fe`.
+3. Update frontend code to use the regenerated queries and models.
+Point `VITE_PUBLIC_API_URL` at the Starbase project host origin only. Do not append `/api`.

package/templates/auth-chat/.rulesync/rules/frontend-component-structure.md ADDED Viewed

@@ -0,0 +1,38 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend component extraction and feature subcomponent structure conventions."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when organizing frontend feature components, page sections, mapped items, or reusable UI."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+# Frontend Component Structure
+Extract repeatable UI into subcomponents. Every named React component should live in its own file, even when it is currently used only once. Keep the component file near the feature, layout, page, or shared UI area that owns it.
+Extract large or complex sections of pages into named components so route and page components stay readable. Anything mapped from an array should usually be a component, such as cards, table row actions, repeated sections, or list items.
+The planets feature is the reference example while the template is still a prototype:
+- `PlanetCard` for mapped grid cards.
+- `PlanetsFilters` for shared filter controls.
+- `PlanetsTableActions` for repeated row actions.
+- `PlanetsTable` and `PlanetsTableInfinite` for table wrappers.
+- `PlanetDetailsPage` and `PlanetEditPage` for large route-owned views.
+When implementing a real app, remove the planets and aliens links from app navigation such as `apps/fe/src/components/layout/AppHeader.tsx` so these examples are not directly accessible in the product UI, but keep the example implementation available as a reference unless the team intentionally deletes the demo layer.
+Route files should own routing, document metadata, and route data boundaries. Feature components should own the page UI and interaction details.
+Exception: route-local wrappers such as `PageComponent` or layout guard components may stay in route files when they only connect routing primitives to feature components.
+## Shared Utilities
+Keep generic formatting, parsing, calculation, and data-shaping helpers in `apps/fe/src/utils/*.utils.ts` files instead of defining them inside component files. Export helpers through namespaces such as `DateUtils.formatDate(...)` or `NumberUtils.formatInteger(...)` so call sites stay explicit and related helpers stay grouped.
+Component files may keep UI-local glue helpers only when the logic is tightly coupled to that component's JSX, such as adapting one component's prop shape or handling a local event. If the helper describes dates, numbers, arrays, strings, IDs, or other domain-neutral data, move it into a shared utility file.
+For apps with multiple user roles that require distinct UI or business workflows, also apply the role-based app structure rule.

package/templates/auth-chat/.rulesync/rules/frontend-forms.md ADDED Viewed

@@ -0,0 +1,32 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend form patterns with Povio UI useForm, generated schemas, and formControl wiring."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when building or changing frontend forms, modals, edit pages, or input components."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+# Frontend Forms
+Use `useForm` and form-aware inputs from `@povio/ui/tanstack` with generated OpenAPI Zod schemas for API-backed forms. The planets feature is the reference example while the template is still a prototype:
+- Create form: `apps/fe/src/components/features/planets/list/PlanetCreateModal.tsx`
+- Edit form: `apps/fe/src/components/features/planets/details/PlanetEditPage.tsx`
+Prefer this shape:
+```tsx
+const form = useForm({
+  zodSchema: PlanetsModels.PlanetsCreateInputSchema,
+  defaultValues: { name: "" },
+});
+```
+Pass form state into Povio UI inputs with `field={{ form, name: "fieldName" }}`. Use `form.handleSubmit`, `form.reset`, and `form.setFieldValue` for form actions, and `useFormValue(form, selector)` for reactive field reads.
+Avoid local `useState`, custom `value`, and custom `onChange` plumbing for fields that belong to the form. Use TanStack Form's `form.Field` adapter only when a component cannot accept the Povio UI `field` binding.
+Use generated OpenAPI queries and mutations for submit handlers. Keep toast feedback and navigation close to the feature interaction that owns them.

package/templates/auth-chat/.rulesync/rules/frontend-notifications.md ADDED Viewed

@@ -0,0 +1,24 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend notification inbox, preferences, push permission, service worker, and token registration boundaries."
+globs: ["apps/fe/src/**/*.{ts,tsx}", "apps/fe/public/**/*.{js,ts}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when frontend work handles notifications, push permission, service workers, push tokens, unread counts, or notification preferences."
+  globs: ["apps/fe/src/**/*.{ts,tsx}", "apps/fe/public/**/*.{js,ts}"]
+---
+# Frontend Notifications
+Use generated `@/openapi` queries, mutations, and models for notification history, preferences, and push-token registration. Do not import `@robodev-ai/sdk` or `database.ts` into frontend feature code.
+Request push permission only after an explanatory UI and explicit user gesture. Never request it automatically during initial application load. Handle unsupported, default, denied, granted, registered, expired, and failed-registration states.
+Register the service worker and provider subscription through a small browser integration, then persist the token/subscription through the generated authenticated user API. Clean up or detach the current device registration on logout when required by the security model.
+Keep push payloads minimal and privacy-safe. Validate internal deep links before navigation. Never depend on push as the only record of an important event; provide a paginated in-app notification list and unread state.
+Use generated mutation invalidation options for unread counts, mark-read actions, preferences, and token changes. Do not access the query client directly for generated API state.
+Use `@povio/ui` for permission prompts, notification lists, menus/popovers, tags, forms, confirmations, and toasts. Use `povio-ui-styling` for styling-layer decisions.