@knowcode/doc-builder 1.8.0 → 1.8.1

package/user-management/README.md

@@ -1,81 +1,306 @@
-# User Management for Doc-Builder Sites
+# Doc-Builder User Management System
 
-This directory contains a simple scripted solution for managing user access to Supabase-authenticated documentation sites.
+A comprehensive user management solution for Supabase-authenticated documentation sites using the Supabase CLI.
 
-## Quick Start
+## 🚀 Quick Start
 
 ```bash
-# List all documentation sites
-./add-users.sh sites
+# Initial setup
+./add-users.sh setup
+
+# Add a user
+./add-users.sh add wru-bid-analysis.vercel.app user@email.com
+
+# List all users for a site
+./add-users.sh list wru-bid-analysis.vercel.app
+```
+
+## 📋 Prerequisites
+
+1. **Install Supabase CLI**:
+   ```bash
+   npm install -g supabase
+   ```
+
+2. **Login to Supabase**:
+   ```bash
+   supabase login
+   ```
+
+3. **Link your project** (or use the setup command):
+   ```bash
+   ./add-users.sh setup
+   ```
+
+## 🔧 Installation
+
+The user management system is self-contained in this folder:
+
+```
+user-management/
+├── add-users.sh     # Main script
+├── users.txt        # Example bulk user file
+├── README.md        # This documentation
+└── .env.example     # Environment variables template
+```
+
+## 📖 Commands
+
+### Setup
+
+Initialize and link your Supabase project:
+
+```bash
+./add-users.sh setup
+```
+
+This will:
+- Check if Supabase CLI is installed
+- Verify you're logged in
+- Link your project (prompts for project ID)
+- Test the database connection
+- Save configuration for future use
+
+### Add User
+
+Create a user and grant them access to a specific site:
 
-# Add a single user to a site
-./add-users.sh add wru-bid-analysis.vercel.app john@example.com
+```bash
+./add-users.sh add <site-url> <email>
+
+# Example
+./add-users.sh add docs.example.com john@company.com
+```
+
+This will:
+- Create the user account if it doesn't exist
+- Send them a password reset email
+- Grant access to the specified site
+- Show confirmation of access granted
 
-# Add multiple users from a file
-./add-users.sh bulk wru-bid-analysis.vercel.app users.txt
+### Bulk Add Users
 
-# List all users with access to a site
+Add multiple users from a file:
+
+```bash
+./add-users.sh bulk <site-url> <file>
+
+# Example
+./add-users.sh bulk docs.example.com users.txt
+```
+
+File format (users.txt):
+```
+# Comments start with #
+# One email per line
+john@example.com
+jane@example.com
+admin@company.com
+```
+
+### List Users
+
+Show all users with access to a site:
+
+```bash
+./add-users.sh list <site-url>
+
+# Example
 ./add-users.sh list wru-bid-analysis.vercel.app
+```
+
+Output includes:
+- Email address
+- When user was created
+- When access was granted
+- Last login time
+- Total user count
+
+### Check User
 
-# Check if a user has access
-./add-users.sh check wru-bid-analysis.vercel.app john@example.com
+Check a user's status across all sites:
 
-# Remove user access
-./add-users.sh remove wru-bid-analysis.vercel.app john@example.com
+```bash
+./add-users.sh check <email>
+
+# Example
+./add-users.sh check user@example.com
 ```
 
-## How It Works
+Shows:
+- If user exists
+- All sites they have access to
+- Last login information
+
+### Remove Access
 
-1. The script generates SQL commands based on your input
-2. Copy the generated SQL and run it in the Supabase SQL Editor
-3. For new users, you'll need to create them in Supabase Dashboard first
+Remove a user's access to a specific site:
 
-## Files
+```bash
+./add-users.sh remove <site-url> <email>
 
-- `add-users.sh` - Main user management script
-- `users.txt` - Example file for bulk user additions
-- `USER-MANAGEMENT.md` - This documentation
+# Example
+./add-users.sh remove docs.example.com user@example.com
+```
 
-## Important URLs
+Note: This only removes access, it doesn't delete the user account.
 
-- Supabase SQL Editor: https://supabase.com/dashboard/project/xcihhnfcitjrwbynxmka/sql
-- Supabase User Management: https://supabase.com/dashboard/project/xcihhnfcitjrwbynxmka/auth/users
+### List Sites
 
-## Workflow for Adding New Users
+Show all documentation sites in the system:
 
-1. First check if the user exists:
-   ```bash
-   ./add-users.sh check site-url user@email.com
-   ```
+```bash
+./add-users.sh sites
+```
 
-2. If the user doesn't exist:
-   - Go to Supabase Dashboard > Authentication > Users
-   - Click "Invite user"
-   - Enter the email address
-   - They'll receive an email to set their password
+Shows:
+- Site ID
+- Domain
+- Site name
+- Creation date
+- Number of users
 
-3. Grant access to the site:
+### Delete User
+
+Permanently delete a user (removes from ALL sites):
+
+```bash
+./add-users.sh delete-user <email>
+
+# Example
+./add-users.sh delete-user user@example.com
+```
+
+⚠️ **Warning**: This is permanent and cannot be undone!
+
+## ⚠️ Important Limitations
+
+The Supabase CLI doesn't support direct user creation. The script offers two workarounds:
+
+1. **Manual Creation** (Recommended): Opens the Supabase dashboard where you can invite users
+2. **Programmatic Creation** (Advanced): If you provide your service_role key, the script can create users using the Admin API
+
+## 🔐 Security Notes
+
+1. **User Creation**: When users are created, they receive a password reset email to set their own password
+2. **Access Control**: Users only see sites they have explicit access to
+3. **Audit Trail**: All access grants are timestamped in the database
+4. **No Passwords**: The system never handles or stores passwords directly
+5. **Service Role Key**: If using programmatic creation, your service_role key is never stored
+
+## 🛠️ Troubleshooting
+
+### "Supabase CLI not found"
+
+Install the Supabase CLI:
+```bash
+npm install -g supabase
+```
+
+### "Not logged in to Supabase"
+
+Login to your Supabase account:
+```bash
+supabase login
+```
+
+### "Project not linked"
+
+Run the setup command:
+```bash
+./add-users.sh setup
+```
+
+### "Site not found"
+
+Make sure the site exists in the `docbuilder_sites` table. You can check with:
+```bash
+./add-users.sh sites
+```
+
+### "User already exists"
+
+This is fine - the script will continue and grant access to the site.
+
+### "Access already granted"
+
+The user already has access to this site. No action needed.
+
+## 📊 Database Schema
+
+The system uses two main tables:
+
+### docbuilder_sites
+- `id` (UUID) - Primary key
+- `domain` (TEXT) - Site URL without https://
+- `name` (TEXT) - Display name
+- `created_at` (TIMESTAMP)
+
+### docbuilder_access
+- `user_id` (UUID) - References auth.users
+- `site_id` (UUID) - References docbuilder_sites
+- `created_at` (TIMESTAMP)
+
+## 🎯 Common Workflows
+
+### Setting up a new documentation site
+
+1. Add the site to the database (manually or via SQL)
+2. Add users who should have access:
    ```bash
-   ./add-users.sh add site-url user@email.com
+   ./add-users.sh add my-docs.vercel.app user1@example.com
+   ./add-users.sh add my-docs.vercel.app user2@example.com
    ```
-   Copy and run the generated SQL
 
-4. Verify access was granted:
+### Onboarding multiple team members
+
+1. Create a users.txt file with all email addresses
+2. Run bulk add:
    ```bash
-   ./add-users.sh list site-url
+   ./add-users.sh bulk my-docs.vercel.app users.txt
    ```
 
-## Bulk User Addition
+### Auditing access
+
+Check who has access to a site:
+```bash
+./add-users.sh list my-docs.vercel.app
+```
+
+Check what sites a user can access:
+```bash
+./add-users.sh check user@example.com
+```
+
+### Offboarding a user
+
+Remove from specific site:
+```bash
+./add-users.sh remove my-docs.vercel.app former-employee@example.com
+```
+
+Or remove completely:
+```bash
+./add-users.sh delete-user former-employee@example.com
+```
+
+## 🔧 Configuration
+
+The script stores its configuration in `.supabase-config` after setup. You can also set environment variables:
+
+- `SUPABASE_PROJECT_ID` - Your project ID
+- `SUPABASE_DB_URL` - Database connection URL (optional)
+
+## 📝 Notes
 
-1. Edit `users.txt` with one email per line
-2. Run: `./add-users.sh bulk site-url users.txt`
-3. The script will generate SQL for all users
-4. Create any missing users in Supabase first
-5. Run the SQL to grant access
+- Site URLs should be entered without `https://` prefix
+- Users receive password reset emails when created
+- The script uses the Supabase CLI for all operations
+- All actions are logged with colored output for clarity
+- Destructive operations require confirmation
 
-## Notes
+## 🆘 Support
 
-- Site URLs should be without the `https://` prefix
-- Users must exist in Supabase before you can grant them access
-- The script only generates SQL - you need to run it manually
-- This gives you a chance to review before making changes
+- GitHub: https://github.com/wapdat/doc-builder
+- Documentation: https://doc-builder-delta.vercel.app
+- Supabase Dashboard: https://supabase.com/dashboard