Rename @reviq/utils to @reviq/server-utils and add package READMEs

- Rename packages/utils/ to packages/server-utils/
- Update all imports and package.json references
- Add READMEs for frontend-utils, server-utils, and common packages
- Update main README with new package structure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -26,9 +26,11 @@ A modern publisher dashboard for managing organizations, members, and sites. Bui
 
 ### Shared Packages
 - `@reviq/api-contract` - Shared API contract (oRPC)
+- `@reviq/common` - Shared utilities for frontend and backend
 - `@reviq/db` - Database client and queries
 - `@reviq/db-schema` - Database schema and codegen
-- `@reviq/utils` - Shared utilities
+- `@reviq/frontend-utils` - Frontend-specific utilities
+- `@reviq/server-utils` - Server/CLI utilities
 
 ## Project Structure
 
@@ -40,10 +42,12 @@ publisher-dashboard/
 │   └── publisher-dashboard/  # SvelteKit frontend
 ├── packages/
 │   ├── api-contract/      # Shared oRPC contract
+│   ├── common/            # Shared utilities (frontend + backend)
 │   ├── db/                # Database client
 │   ├── db-schema/         # DB schema & codegen
-│   ├── testing/           # Test utilities
+│   ├── frontend-utils/    # Frontend utilities
-│   └── utils/             # Shared utilities
+│   ├── server-utils/      # Server/CLI utilities
+│   └── testing/           # Test utilities
 └── db/                    # Database migrations
 ```
 

apps/api-server/package.json

@@ -19,7 +19,7 @@
     "@reviq/api-contract": "workspace:*",
     "@reviq/db": "workspace:*",
     "@reviq/db-schema": "workspace:*",
-    "@reviq/utils": "workspace:*",
+    "@reviq/server-utils": "workspace:*",
     "@scure/base": "^2.0.0",
     "@simplewebauthn/server": "^13.2.2",
     "@simplewebauthn/types": "^12.0.0",

apps/api-server/src/utils/crypto.ts

@@ -1,4 +1,4 @@
-import { generateSecureBase58Token } from "@reviq/utils";
+import { generateSecureBase58Token } from "@reviq/server-utils";
 import { base58 } from "@scure/base";
 
 // Re-export for convenience

apps/api-server/src/utils/password.ts

@@ -1,7 +1,7 @@
 import {
   hashPassword as hashPasswordUtil,
   verifyPassword as verifyPasswordUtil,
-} from "@reviq/utils";
+} from "@reviq/server-utils";
 import zxcvbn from "zxcvbn";
 
 export interface PasswordValidationResult {

bun.lock

@@ -22,7 +22,7 @@
         "@reviq/api-contract": "workspace:*",
         "@reviq/db": "workspace:*",
         "@reviq/db-schema": "workspace:*",
-        "@reviq/utils": "workspace:*",
+        "@reviq/server-utils": "workspace:*",
         "@scure/base": "^2.0.0",
         "@simplewebauthn/server": "^13.2.2",
         "@simplewebauthn/types": "^12.0.0",
@@ -148,7 +148,7 @@
       "dependencies": {
         "@noble/hashes": "^2.0.1",
         "@reviq/db-schema": "workspace:*",
-        "@reviq/utils": "workspace:*",
+        "@reviq/server-utils": "workspace:*",
         "@scure/base": "^2.0.0",
         "kysely": "^0.28.9",
         "pg": "^8.13.1",
@@ -191,6 +191,18 @@
         "typescript": "catalog:",
       },
     },
+    "packages/server-utils": {
+      "name": "@reviq/server-utils",
+      "version": "0.0.1",
+      "devDependencies": {
+        "@cloudflare/workers-types": "^4.20250529.0",
+        "@macalinao/eslint-config": "catalog:",
+        "@macalinao/tsconfig": "catalog:",
+        "@types/bun": "catalog:",
+        "eslint": "catalog:",
+        "typescript": "catalog:",
+      },
+    },
     "packages/testing/test-helpers": {
       "name": "@reviq/test-helpers",
       "version": "0.0.1",
@@ -224,18 +236,6 @@
         "typescript": "catalog:",
       },
     },
-    "packages/utils": {
-      "name": "@reviq/utils",
-      "version": "0.0.1",
-      "devDependencies": {
-        "@cloudflare/workers-types": "^4.20250529.0",
-        "@macalinao/eslint-config": "catalog:",
-        "@macalinao/tsconfig": "catalog:",
-        "@types/bun": "catalog:",
-        "eslint": "catalog:",
-        "typescript": "catalog:",
-      },
-    },
   },
   "catalog": {
     "@macalinao/eslint-config": "^7.0.3",
@@ -456,9 +456,9 @@
 
     "@reviq/frontend-utils": ["@reviq/frontend-utils@workspace:packages/frontend-utils"],
 
-    "@reviq/test-helpers": ["@reviq/test-helpers@workspace:packages/testing/test-helpers"],
+    "@reviq/server-utils": ["@reviq/server-utils@workspace:packages/server-utils"],
 
-    "@reviq/utils": ["@reviq/utils@workspace:packages/utils"],
+    "@reviq/test-helpers": ["@reviq/test-helpers@workspace:packages/testing/test-helpers"],
 
     "@reviq/virtual-authenticator": ["@reviq/virtual-authenticator@workspace:packages/testing/virtual-authenticator"],
 

db/schema.sql

@@ -1,3 +1,4 @@
+\restrict QhAmrcKtCrf6P0ZFpXVcs0q7Otge0aJb6nxv7mivONqZesSRXpctyFKRRYQlfqj
 
 -- Dumped from database version 17.7
 -- Dumped by pg_dump version 17.7
@@ -1083,6 +1084,7 @@ ALTER TABLE ONLY public.user_devices
 -- PostgreSQL database dump complete
 --
 
+\unrestrict QhAmrcKtCrf6P0ZFpXVcs0q7Otge0aJb6nxv7mivONqZesSRXpctyFKRRYQlfqj
 
 
 --

packages/common/README.md

@@ -1,6 +1,8 @@
 # @reviq/common
 
-Shared utilities for all RevIQ applications. This package contains environment-agnostic code that works in browsers, Node.js, Bun, and other JavaScript runtimes.
+Shared utilities for frontend and backend. This package contains environment-agnostic code that works in browsers, Node.js, Bun, and Cloudflare Workers.
+
+Use this package for utilities that need to work in both the publisher dashboard and the API server.
 
 ## Installation
 

packages/db/package.json

@@ -19,7 +19,7 @@
   "dependencies": {
     "@noble/hashes": "^2.0.1",
     "@reviq/db-schema": "workspace:*",
-    "@reviq/utils": "workspace:*",
+    "@reviq/server-utils": "workspace:*",
     "@scure/base": "^2.0.0",
     "kysely": "^0.28.9",
     "pg": "^8.13.1"

packages/db/src/helpers/execute-bootstrap.ts

@@ -7,7 +7,7 @@
 
 import type { Database } from "@reviq/db-schema";
 import type { Kysely, Transaction } from "kysely";
-import { hashPassword } from "@reviq/utils";
+import { hashPassword } from "@reviq/server-utils";
 import { generateToken, hashToken } from "./token.js";
 
 /**

packages/frontend-utils/README.md

@@ -0,0 +1,15 @@
+# @reviq/frontend-utils
+
+Frontend-specific utilities for the RevIQ publisher dashboard.
+
+## Usage
+
+```typescript
+import { getOrgColor, getOrgInitials } from "@reviq/frontend-utils";
+```
+
+## Exports
+
+- `getOrgInitials(org)` - Get display initials from an organization's slug or display name
+- `getOrgColor(org)` - Get a consistent HSL color based on the organization slug
+- `OrgLike` - Type interface for organization objects

packages/server-utils/README.md

@@ -0,0 +1,24 @@
+# @reviq/server-utils
+
+Server and CLI utilities for the RevIQ platform. These utilities use crypto APIs and are designed for Cloudflare Workers compatibility.
+
+## Usage
+
+```typescript
+import {
+  generateSecureBase58Token,
+  hashPassword,
+  verifyPassword,
+} from "@reviq/server-utils";
+```
+
+## Exports
+
+### Token Generation
+- `generateSecureBase58Token(prefix)` - Generate a secure random token with a prefix (e.g., `reviq_`)
+- `parseBase58Token(token)` - Parse and validate a base58-encoded token
+- `isBase58(str)` - Check if a string is valid base58
+
+### Password Hashing
+- `hashPassword(password)` - Hash a password using PBKDF2-SHA256
+- `verifyPassword(password, hash)` - Verify a password against a stored hash

packages/server-utils/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@reviq/utils",
+  "name": "@reviq/server-utils",
   "version": "0.0.1",
   "type": "module",
   "main": "./dist/index.js",