ui-syncup 0.3.13 → 0.4.0-beta.1

package/Dockerfile

@@ -0,0 +1,84 @@
+# ============================================================================
+# Multi-Stage Production Dockerfile for UI SyncUp
+# ============================================================================
+# Optimized for self-hosting. Published to ghcr.io/bykhd/ui-syncup on release.
+#
+# Build:  docker build -t ui-syncup .
+# Run:    docker run -p 3000:3000 --env-file .env.production ui-syncup
+# ============================================================================
+
+# ---------------------------------------------------------------------------
+# Stage 1: Install dependencies
+# ---------------------------------------------------------------------------
+FROM oven/bun:1-alpine AS deps
+
+WORKDIR /app
+
+COPY package.json bun.lock* ./
+
+RUN bun install --frozen-lockfile
+
+# ---------------------------------------------------------------------------
+# Stage 2: Build the application
+# ---------------------------------------------------------------------------
+FROM oven/bun:1-alpine AS builder
+
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV NODE_ENV=production
+ENV SKIP_ENV_VALIDATION=true
+# Use ARG for build-time-only dummy values so they are not baked into image layers
+ARG DATABASE_URL=postgres://dummy:dummy@localhost:5432/dummy
+ARG BETTER_AUTH_SECRET=dummy-secret-32-characters-long!!
+ARG BETTER_AUTH_URL=http://localhost:3000
+ARG NEXT_PUBLIC_APP_URL=http://localhost:3000
+ARG NEXT_PUBLIC_API_URL=http://localhost:3000
+ARG STORAGE_ENDPOINT=http://localhost:9000
+ARG STORAGE_ATTACHMENTS_PUBLIC_URL=http://localhost:9000
+ARG STORAGE_MEDIA_PUBLIC_URL=http://localhost:9000
+ARG RESEND_API_KEY=re_dummy
+
+RUN bun run build
+
+# ---------------------------------------------------------------------------
+# Stage 3: Production runtime (oven/bun for migration support)
+# ---------------------------------------------------------------------------
+FROM oven/bun:1-alpine AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV HOSTNAME="0.0.0.0"
+ENV PORT=3000
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+# Copy Next.js standalone output
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+# Copy migration assets needed by the compose entrypoint: bun run db:migrate
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/bun.lock* ./
+COPY --from=builder /app/scripts/migrate.ts ./scripts/migrate.ts
+COPY --from=builder /app/drizzle ./drizzle
+
+# Install production deps (drizzle-orm, postgres, dotenv needed by migration)
+RUN bun install --production --frozen-lockfile
+
+RUN chown -R nextjs:nodejs /app/drizzle /app/scripts /app/package.json
+
+USER nextjs
+
+EXPOSE 3000
+
+# Default CMD for standalone runs without compose.
+# The compose entrypoint overrides this with: sh -c "bun run db:migrate && node server.js"
+CMD ["node", "server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BYKHD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,94 +1,363 @@
-# ui-syncup CLI
+# UI-Syncup
 
-Self-host [UI SyncUp](https://github.com/BYKHD/ui-syncup) with a single command. No infrastructure knowledge required.
+[![CI](https://github.com/BYKHD/ui-syncup/actions/workflows/ci.yml/badge.svg)](https://github.com/BYKHD/ui-syncup/actions/workflows/ci.yml)
+[![GHCR](https://img.shields.io/badge/GHCR-ghcr.io%2Fbykhd%2Fui--syncup-blue)](https://ghcr.io/bykhd/ui-syncup)
 
-## Requirements
+A visual feedback and issue tracking platform for design-to-development collaboration. UI-Syncup enables designers, QA engineers, and developers to annotate UI mockups, create issues from visual feedback, and track them through a structured workflow from creation to resolution.
 
-- [Docker](https://docs.docker.com/get-docker/) ≥ 24
-- Node.js ≥ 20 (only needed to run the CLI — the app itself runs in Docker)
+## Features
 
-## Quick Start
+- **Visual Annotations**: Pin-based and box annotations on images/mockups with threaded comments
+- **Issue Management**: Create, track, and resolve UI/UX issues with workflow states (Open → In Progress → In Review → Resolved → Archived)
+- **Team & Project Organization**: Multi-team workspace with project-based access control
+- **Two-Tier Role System**: Management roles (OWNER, ADMIN) for team settings + Operational roles (EDITOR, MEMBER, VIEWER) for content access
+- **Plan-Based Limits**: Free tier (10 users, 1 project, 50 issues) and Pro tier (unlimited users, 50 projects, unlimited issues)
+
+## Tech Stack
+
+- **Framework & Runtime**: Next.js 16 (App Router), React 19.2, TypeScript 5, Node 20 LTS, Bun
+- **UI & Styling**: shadcn/ui, Radix UI, Tailwind CSS 4, Framer Motion, Lucide React, next-themes
+- **Data & State**: TanStack Query 5, Zod, React Hook Form
+- **Database**: PostgreSQL 15 (Supabase), Drizzle ORM, Supabase CLI
+- **Storage**: Cloudflare R2 (S3-compatible)
+- **Auth & Security**: better-auth, @node-rs/argon2, ioredis (rate limiting)
+- **Email**: Resend, React Email
+- **Testing**: Vitest, Playwright, fast-check (property-based), PGlite 
+
+## Getting Started
+
+### Prerequisites
+
+**Self-hosting:** Docker (compose v2+)
+
+**Development:** Node 20 LTS + Bun (see [.nvmrc](.nvmrc))
+
+### Quick Installation (Self-Hosting)
+
+The fastest way to deploy UI SyncUp is the one-command installer — no Bun or Node required, just Docker:
 
 ```bash
-mkdir my-syncup && cd my-syncup
-npx ui-syncup init
+curl -fsSL https://raw.githubusercontent.com/BYKHD/ui-syncup/main/install.sh | bash
+```
+
+The wizard will ask four questions (database, cache, storage, email) and start the stack automatically.
+
+> **Requires Docker** — Docker Engine 24+ with Compose v2 must be installed and running.
+
+### Local Development Setup
+
+```bash
+# 1. Clone and install dependencies
+git clone https://github.com/BYKHD/ui-syncup.git
+cd ui-syncup
+bun install
+
+# 2. Configure environment
+cp .env.example .env.local
+# Edit .env.local with your database / auth / storage credentials
+
+# 3. Start development server
+bun dev
 ```
 
-The wizard downloads `compose.yml`, walks you through service configuration, and starts the stack.
+Open [http://localhost:3000](http://localhost:3000) in your browser.
 
-## Commands
+### Development Commands
 
-### Setup & Lifecycle
+```bash
+# Development
+bun dev                 # Start dev server (http://localhost:3000)
+bun build              # Production build
+bun start              # Start production server
 
-| Command | Description |
-|---|---|
-| `init` | Guided first-time setup wizard |
-| `start` | Start the stack (reads `COMPOSE_PROFILES` from `.env`) |
-| `stop` | Stop gracefully — data is preserved |
-| `restart [service]` | Restart all services or a single one |
-| `remove` | Remove containers (`--volumes` to also wipe all data) |
+# Code Quality
+bun typecheck          # Run TypeScript compiler checks
+bun lint               # Run ESLint
+bun format             # Format code with Prettier
 
-### Observability
+# Testing (⚠️ Use 'bun run test', NOT 'bun test')
+bun run test           # Run unit tests (Vitest) - SAFE
+bun run test:watch     # Run tests in watch mode
+bun run test:ui        # Run E2E tests (Playwright)
 
-| Command | Description |
-|---|---|
-| `status` | Show container states, health, and app URL |
-| `logs [service]` | Tail last 200 lines (`-F` to stream live) |
-| `doctor` | Validate env vars, health endpoint, and disk space |
-| `open` | Open the app in your default browser |
+# Database
+bun run db:generate    # Generate Drizzle migrations
+bun run db:migrate     # Run migrations
+bun run db:studio      # Open Drizzle Studio
+bun run db:seed        # Seed database with test data
 
-### Maintenance
+# Supabase (Local Development)
+bun run supabase:start # Start local Supabase stack
+bun run supabase:stop  # Stop local Supabase
+bun run supabase:status # Check status and connection details
+
+# Validation
+bun run validate-env   # Validate environment variables
+```
 
-| Command | Description |
-|---|---|
-| `upgrade` | Pull latest image and restart (migrations apply automatically) |
-| `backup` | Dump PostgreSQL + MinIO to a timestamped `.tar.gz` |
-| `restore <archive>` | Restore from a backup archive |
+### CLI (Self-Hosting)
 
-## Usage Examples
+The `ui-syncup` npm package provides three commands for managing a self-hosted deployment. No Bun required — runs on Node 20+.
 
 ```bash
-# First-time setup
+# One-time setup wizard (Docker-native, downloads compose.yml + configures .env)
 npx ui-syncup init
 
-# Day-to-day
-ui-syncup status
-ui-syncup logs -F              # stream all logs
-ui-syncup logs app -F          # stream app logs only
-ui-syncup restart app          # restart just the app container
+# Pull latest image and restart
+npx ui-syncup upgrade
 
-# Upgrades
+# Diagnose your deployment (Docker, env vars, /api/health, disk space)
+npx ui-syncup doctor
+```
+
+Or install globally:
+
+```bash
+npm install -g ui-syncup
+
+ui-syncup init
 ui-syncup upgrade
+ui-syncup doctor
+```
+
+See [docs/cli/CLI_GUIDE.md](docs/cli/CLI_GUIDE.md) for full reference.
+
+## Project Structure
+
+### Architecture Principles
+
+- **Feature-first organization**: Code is organized by product feature (not by technical type)
+- **Strict layering**: server/api → features/hooks → features/components → app/pages
+- **Thin pages pattern**: Pages are route handlers, screens contain UI logic
+- **Typed boundaries**: All network boundaries validated with Zod schemas
+- **Clean imports**: Barrel exports maintain stable public APIs
+
+### Directory Layout
+
+```
+src/
+├── app/                    # Next.js App Router (routing only)
+│   ├── (protected)/        # Auth-required routes
+│   ├── (public)/           # Public routes
+│   └── api/                # API route handlers
+├── features/               # Feature modules (mini-packages)
+│   ├── annotations/        # Visual annotation system
+│   ├── auth/               # Authentication & onboarding
+│   ├── issues/             # Issue tracking
+│   ├── projects/           # Project management
+│   ├── teams/              # Team management
+│   ├── team-settings/      # Team configuration
+│   └── user-settings/      # User preferences
+├── components/
+│   ├── ui/                 # shadcn primitives
+│   └── shared/             # Cross-feature widgets
+├── config/                 # Single sources of truth
+├── lib/                    # App-wide utilities
+├── server/                 # Server-only logic (auth, DB, RBAC)
+│   ├── auth/               # Session, tokens, RBAC
+│   │   ├── cookies.ts      # httpOnly cookie management
+│   │   ├── password.ts     # Argon2 password hashing
+│   │   ├── rate-limiter.ts # Redis-based rate limiting
+│   │   ├── rbac.ts         # Role-based access control
+│   │   ├── session.ts      # Session management
+│   │   └── tokens.ts       # JWT token handling
+│   ├── db/                 # Database client & schema
+│   │   ├── schema/         # Drizzle schema definitions
+│   │   └── index.ts        # Database client
+│   ├── email/              # Email service
+│   │   ├── client.ts       # Resend client
+│   │   ├── queue.ts        # Email queue management
+│   │   ├── templates/      # React Email templates
+│   │   └── worker.ts       # Background email processor
+│   └── teams/              # Team management services
+│       ├── team-service.ts       # Core team operations
+│       ├── member-service.ts     # Member management
+│       ├── invitation-service.ts # Invitation handling
+│       ├── billable-seats.ts     # Billing calculations
+│       └── plan-limits.ts        # Plan enforcement
+├── mocks/                  # Mock data for development
+└── hooks/                  # Global hooks
+
+drizzle/                    # Database migrations
+supabase/                   # Supabase configuration and seed data
+```
+
+### Feature Module Anatomy
+
+Each feature follows this structure:
+- `api/` - Fetchers + DTO schemas (no React)
+- `hooks/` - React Query wrappers
+- `components/` - Feature-specific UI
+- `screens/` - Screen components (compose hooks)
+- `types/` - Domain models
+- `utils/` - Feature-specific helpers
+- `index.ts` - Barrel export (public API)
+
+## Role System
+
+### Management Roles (Team Settings Access)
+
+- **TEAM_OWNER**: Full control over team, billing, members. Can delete team and transfer ownership. Not billable by itself.
+- **TEAM_ADMIN**: Manage members, projects, integrations. Cannot delete team or transfer ownership. Not billable by itself.
 
-# Backup & restore
-ui-syncup backup -o ~/backups
-ui-syncup restore ~/backups/ui-syncup-backup-2026-03-19T12-00.tar.gz
+### Operational Roles (Content Access & Billing)
 
-# Teardown
-ui-syncup remove               # keep data volumes
-ui-syncup remove --volumes     # wipe everything
+- **TEAM_EDITOR**: Create and manage issues/annotations. **Billable ($8/month)**. Auto-assigned when user becomes PROJECT_OWNER or PROJECT_EDITOR.
+- **TEAM_MEMBER**: View projects and comment. Can be assigned to projects. **Free**.
+- **TEAM_VIEWER**: Read-only access. **Free**.
+
+### Project Roles
+
+- **PROJECT_OWNER**: Full project control. Auto-promotes to TEAM_EDITOR (billable).
+- **PROJECT_EDITOR**: Create/manage issues. Auto-promotes to TEAM_EDITOR (billable).
+- **PROJECT_DEVELOPER**: Update issue status and comment. **Free**.
+- **PROJECT_VIEWER**: Read-only project access. **Free**.
+
+### Target Users
+
+- **Designers/QA** (PROJECT_EDITOR + TEAM_EDITOR): Create issues, annotate mockups, review implementations
+- **Developers** (PROJECT_DEVELOPER + TEAM_MEMBER): View issues, update status, implement fixes
+- **Project Managers** (PROJECT_OWNER + TEAM_EDITOR): Manage projects, assign roles, track progress
+- **Team Admins** (TEAM_ADMIN + TEAM_MEMBER/VIEWER): Manage team settings without content creation (free) or with content creation (billable)
+
+## Testing
+
+### Important: Test Runner
+
+⚠️ **ALWAYS** use `bun run test` (or `vitest`).
+
+**NEVER** use `bun test` (Bun's native runner) - it ignores our test configuration and will write junk data to your local database.
+
+### Test Types
+
+- **Unit/Integration**: Vitest with PGlite - SAFE
+- **Property-based**: fast-check for generative testing (use `*.property.test.ts` naming)
+- **E2E**: Playwright - uses local Supabase database
+- **Component**: React Testing Library with jsdom/happy-dom
+- **Coverage target**: ≥ 80% for business-critical features
+
+### Test Structure
+
+Tests are co-located with source files:
+
+```
+src/
+├── lib/
+│   ├── __tests__/
+│   │   ├── auth-config.test.ts
+│   │   └── logger.property.test.ts
+│   └── auth-config.ts
+├── server/
+│   └── teams/
+│       ├── __tests__/
+│       │   ├── team-service.test.ts
+│       │   └── team-creation.property.test.ts
+│       └── team-service.ts
+└── features/
+    └── issues/
+        └── components/
+            ├── issue-list.tsx
+            └── issue-list.test.tsx
+
+tests/
+└── e2e/
+    ├── helpers/
+    │   └── test-fixtures.ts
+    └── auth.spec.ts
+```
+
+## Database & Local Development
+
+This project uses **PostgreSQL 15** via **Supabase** with **Drizzle ORM**.
+
+### Local Development with Supabase CLI
+
+```bash
+# Start local Supabase stack (Postgres, Auth, Storage, Studio)
+bun run supabase:start
+
+# Stop local Supabase
+bun run supabase:stop
+
+# Check status and get connection details
+bun run supabase:status
+
+# Access Supabase Studio at http://127.0.0.1:54323
+# Local database runs on port 54322 (not 5432)
+```
+
+### Schema Management
+
+- Migrations in `drizzle/` directory
+- Schema defined in [src/server/db/schema/](src/server/db/schema/) (modular)
+- Supabase config in `supabase/` directory
+- Use Drizzle Kit for schema changes
+- See `docs/SUPABASE_LOCAL_SETUP.md` for detailed setup
+
+## Environment Variables
+
+Copy `.env.example` to `.env.local` and configure:
+
+- **Database**: PostgreSQL connection string (`DATABASE_URL` / `DIRECT_URL`)
+- **Authentication**: `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`
+- **Storage**: S3-compatible credentials (AWS S3, Cloudflare R2, or bundled MinIO)
+- **Email**: Resend API key or SMTP credentials
+- **Redis**: `REDIS_URL` for rate limiting (bundled Redis or external)
+
+Validate your configuration:
+
+```bash
+bun run validate-env
 ```
 
-## Bundled Services (Docker Compose profiles)
+Environment variables are validated at build time using Zod schemas in [src/lib/env.ts](src/lib/env.ts).
+
+For detailed setup instructions, see `docs/ENVIRONMENT_CONFIG.md`.
+
+## Development Guidelines
+
+### Layer Contracts (Import Rules)
+
+- **app/** can import: `features/*`, `components/*`, `hooks`, `lib`, `config`
+- **features/\<name\>/components** can import: own `hooks`, `types`, `utils` + `components/ui`, `components/shared`, `lib`, `config`
+- **features/\<name\>/hooks** can import: own `api`, `types`, `utils` + `lib`
+- **features/\<name\>/api** can import: `lib`, own `types`/`utils` (no React)
+- **components/ui** can import: `lib`, `utils` (never `features/*`)
+- **components/shared** can import: `components/ui`, `lib`, `utils` (never `features/*`)
+- **server/** is server-only; never import from client components
+
+### Naming Conventions
+
+- **Files**: kebab-case (`create-issue-dialog.tsx`, `use-issues.ts`)
+- **Components**: PascalCase (`CreateIssueDialog`)
+- **Hooks**: camelCase with `use` prefix (`useIssue`, `useIssues`)
+- **API functions**: verb-noun (`getIssues`, `createIssue`)
+- **Types**: PascalCase (`Issue`, `IssueStatus`)
+- **Constants**: UPPER_SNAKE_CASE (`ISSUE_WORKFLOW`, `PLANS`)
+
+### Code Quality
 
-`init` lets you choose which services to bundle. Your selection is saved as `COMPOSE_PROFILES` in `.env` so subsequent `start`/`upgrade` commands pick it up automatically.
+- Typecheck, lint, and tests must pass before merging
+- Use ESLint import rules to enforce layer contracts
+- Keep pre-commit hooks under 5 seconds
 
-| Profile | Service | Use when |
-|---|---|---|
-| `db` | PostgreSQL 15 | No external database |
-| `cache` | Redis 7 | No external Redis/Upstash |
-| `storage` | MinIO | No external S3/R2/Backblaze |
+## Documentation
 
-## Backup Details
+For comprehensive architecture and scaffolding guidelines, see:
 
-`backup` only exports data for active profiles:
+- [AGENTS.md](./AGENTS.md) - Complete project scaffolding guide
+- [.ai/steering/product.md](./.ai/steering/product.md) - Product overview
+- [.ai/steering/structure.md](./.ai/steering/structure.md) - Project structure
+- [.ai/steering/tech.md](./.ai/steering/tech.md) - Tech stack details
 
-- **PostgreSQL** (`db` profile) — `pg_dumpall` → `postgres.sql`
-- **MinIO** (`storage` profile) — volume tar → `minio_data.tar.gz`
-- Redis is intentionally excluded (cache — not persistent state)
+## Contributing
 
-Output is a single `.tar.gz` archive you can store offsite.
+1. Follow the architecture guidelines in [AGENTS.md](./AGENTS.md)
+2. Keep features isolated and portable
+3. Write tests for business-critical features
+4. Ensure all checks pass: `bun typecheck && bun lint && bun run test`
+5. Use conventional commits
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+**Do not** open a public GitHub issue for security vulnerabilities.
+
+Please report via a [GitHub Private Security Advisory](https://github.com/BYKHD/ui-syncup/security/advisories/new).
+
+We will respond within 72 hours and coordinate a fix and disclosure timeline.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| Latest  | ✅ |
+| < 0.2   | ❌ |