add-velt 0.1.0

package/README.md

@@ -0,0 +1,503 @@
+# add-velt
+
+CLI tool to add Velt real-time collaboration to your Next.js application.
+
+## Features
+
+- **Smart Project Analysis**: Automatically detects your project structure and package manager
+- **Workspace Support**: Detects pnpm/yarn workspaces by checking parent directories
+- **Feature Flags**: Choose specific features (comments, notifications, CRDT types)
+- **Auto-Wiring**: Automatically configures VeltProvider and VeltCollaboration in your app layout
+- **Strict Scoping**: Only installs dependencies and scaffolds files for selected features
+- **Zero Config**: Works out of the box with App Router and Pages Router
+- **Latest Versions**: Always installs the latest package versions (no stale pinned versions)
+
+## Installation
+
+```bash
+npx add-velt
+```
+
+Or install globally:
+
+```bash
+npm install -g add-velt
+add-velt
+```
+
+## Quick Start
+
+```bash
+# Core only (minimal setup)
+npx add-velt
+
+# Add comments feature
+npx add-velt --comments
+
+# Add notifications feature
+npx add-velt --notifications
+
+# Add CRDT for ReactFlow canvas
+npx add-velt --reactflow-crdt
+
+# Add all features with Tiptap CRDT
+npx add-velt --all --tiptap-crdt
+```
+
+## Command Reference
+
+```bash
+npx add-velt [options]
+```
+
+### Feature Flags
+
+| Flag | Description |
+|------|-------------|
+| `--comments` | Add comments (VeltComments, VeltCommentsSidebar, VeltCursor) |
+| `--notifications` | Add notifications (VeltNotificationsTool, VeltCursor) |
+
+### CRDT Type Flags (choose one)
+
+| Flag | Description | Documentation |
+|------|-------------|---------------|
+| `--reactflow-crdt` | Add ReactFlow CRDT (canvas collaboration) | [ReactFlow CRDT Docs](https://docs.velt.dev/realtime-collaboration/crdt/setup/reactflow) |
+| `--tiptap-crdt` | Add Tiptap CRDT (rich text editor) | [Tiptap CRDT Docs](https://docs.velt.dev/realtime-collaboration/crdt/setup/tiptap) |
+| `--codemirror-crdt` | Add CodeMirror CRDT (code editor) | [CodeMirror CRDT Docs](https://docs.velt.dev/realtime-collaboration/crdt/setup/codemirror) |
+
+### Combined Flag
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Enable comments + notifications + CRDT (requires a CRDT type flag) |
+
+### Installation Flags
+
+| Flag | Description |
+|------|-------------|
+| `--force`, `-f` | Force overwrite existing files |
+| `--legacy-peer-deps` | Use legacy peer deps (npm only) |
+| `--help`, `-h` | Show help message |
+
+---
+
+## Feature Documentation
+
+### Comments
+
+**What it does**: Enables inline commenting on any element in your app. Users can click to add comments, reply to threads, and view all comments in a sidebar.
+
+**Documentation**: [Comments Overview](https://docs.velt.dev/async-collaboration/comments/overview)
+
+**Flags**: `--comments` or included with `--all`
+
+**Components generated**:
+- `VeltCollaboration.tsx` - Renders VeltComments, VeltCommentsSidebar, and VeltCursor
+- `VeltTools.tsx` - Renders VeltPresence and VeltSidebarButton
+
+**Code injected**:
+```tsx
+// In VeltCollaboration.tsx
+<VeltComments
+  popoverMode={true}
+  shadowDom={false}
+  textMode={false}
+  commentPinHighlighter={false}
+  dialogOnHover={false}
+/>
+<VeltCommentsSidebar groupConfig={{ enable: false }} />
+<VeltCursor />
+```
+
+**UI Customization files**:
+- `VeltCommentBubbleWf.tsx` - Custom comment bubble wireframe
+- `VeltCommentToolWf.tsx` - Custom comment tool wireframe
+- `styles.css` - Custom styling
+
+---
+
+### Notifications
+
+**What it does**: Adds a notification system that alerts users to comments, mentions, and other collaboration events.
+
+**Documentation**: [Notifications Setup](https://docs.velt.dev/async-collaboration/notifications/setup)
+
+**Flags**: `--notifications` or included with `--all`
+
+**Components generated**:
+- `VeltCollaboration.tsx` - Renders VeltCursor
+- `VeltTools.tsx` - Renders VeltPresence and VeltNotificationsTool
+
+**Code injected**:
+```tsx
+// In VeltTools.tsx
+<VeltNotificationsTool
+  settings={true}
+  shadowDom={false}
+  tabConfig={{
+    forYou: { name: "For You", enable: true },
+    documents: { name: "Documents", enable: true },
+    all: { name: "All", enable: true },
+  }}
+/>
+```
+
+**UI Customization files**:
+- `VeltNotificationsToolWf.tsx` - Custom notifications wireframe
+- `styles.css` - Custom styling
+
+---
+
+### Presence
+
+**What it does**: Shows which users are currently online/active in the document. Displays user avatars and status indicators.
+
+**Documentation**: [Presence Setup](https://docs.velt.dev/realtime-collaboration/presence/setup)
+
+**Flags**: Automatically included with `--comments`, `--notifications`, or any CRDT flag
+
+**Component generated**:
+- `VeltTools.tsx` - Contains VeltPresence
+
+**Code injected**:
+```tsx
+// In VeltTools.tsx
+<VeltPresence />
+```
+
+**Placement**: Render `<VeltTools />` in your toolbar or header area to display the presence indicators.
+
+---
+
+### Cursors
+
+**What it does**: Shows live cursor positions of other users in real-time. Users can see where others are pointing/working.
+
+**Documentation**: [Cursors Setup](https://docs.velt.dev/realtime-collaboration/cursors/setup)
+
+**Flags**: Automatically included with `--comments`, `--notifications`, or any CRDT flag
+
+**Component generated**:
+- `VeltCollaboration.tsx` - Contains VeltCursor
+
+**Code injected**:
+```tsx
+// In VeltCollaboration.tsx
+<VeltCursor />
+```
+
+**Placement**: The `<VeltCursor />` component is rendered inside `<VeltCollaboration />` which is auto-wired into your app layout. Cursors appear automatically across your app.
+
+---
+
+## Examples
+
+```bash
+# Core only (minimal setup)
+npx add-velt
+
+# Comments only (includes Presence + Cursors)
+npx add-velt --comments
+
+# Notifications only (includes Presence + Cursors)
+npx add-velt --notifications
+
+# ReactFlow CRDT only (includes Presence + Cursors)
+npx add-velt --reactflow-crdt
+
+# Tiptap CRDT only (includes Presence + Cursors)
+npx add-velt --tiptap-crdt
+
+# CodeMirror CRDT only (includes Presence + Cursors)
+npx add-velt --codemirror-crdt
+
+# Comments + Notifications (includes Presence + Cursors)
+npx add-velt --comments --notifications
+
+# Comments + Tiptap CRDT (includes Presence + Cursors)
+npx add-velt --comments --tiptap-crdt
+
+# All features with ReactFlow
+npx add-velt --all --reactflow-crdt
+
+# All features with Tiptap
+npx add-velt --all --tiptap-crdt
+
+# All features with CodeMirror
+npx add-velt --all --codemirror-crdt
+
+# Force overwrite existing files
+npx add-velt --all --reactflow-crdt --force
+```
+
+## Dependencies Installed
+
+All dependencies are installed at their **latest versions** (no pinned/stale versions).
+
+### Baseline (always)
+
+| Package | Type |
+|---------|------|
+| `@veltdev/react` | Production |
+| `@veltdev/types` | Development |
+
+### ReactFlow CRDT (`--reactflow-crdt`)
+
+| Package | Type |
+|---------|------|
+| `@veltdev/reactflow-crdt` | Production |
+| `yjs` | Production |
+
+### Tiptap CRDT (`--tiptap-crdt`)
+
+| Package | Type |
+|---------|------|
+| `@veltdev/tiptap-crdt` | Production |
+| `@veltdev/tiptap-crdt-react` | Production |
+| `@veltdev/tiptap-velt-comments` | Production |
+| `yjs` | Production |
+| `y-prosemirror` | Production |
+
+### CodeMirror CRDT (`--codemirror-crdt`)
+
+| Package | Type |
+|---------|------|
+| `@veltdev/codemirror-crdt` | Production |
+| `@veltdev/codemirror-crdt-react` | Production |
+| `yjs` | Production |
+| `y-codemirror.next` | Production |
+
+## Files Generated
+
+### Core (always created)
+
+```
+components/velt/
+├── VeltCollaboration.tsx       # Main collaboration wrapper (includes VeltCursor)
+├── VeltInitializeDocument.tsx  # Document initialization
+└── VeltInitializeUser.tsx      # User authentication hook
+```
+
+### With `--comments`
+
+```
+components/velt/
+├── VeltTools.tsx               # Toolbar (VeltPresence, VeltSidebarButton)
+└── ui-customization/
+    ├── VeltCustomization.tsx   # Dark mode + wireframe wrapper
+    ├── VeltCommentBubbleWf.tsx # Comment bubble wireframe
+    ├── VeltCommentToolWf.tsx   # Comment tool wireframe
+    └── styles.css              # Custom styles
+```
+
+### With `--notifications`
+
+```
+components/velt/
+├── VeltTools.tsx               # Toolbar (VeltPresence, VeltNotificationsTool)
+└── ui-customization/
+    ├── VeltCustomization.tsx   # Dark mode + wireframe wrapper
+    ├── VeltNotificationsToolWf.tsx # Notifications wireframe
+    └── styles.css              # Custom styles
+```
+
+### With `--comments --notifications`
+
+```
+components/velt/
+├── VeltTools.tsx               # Full toolbar
+└── ui-customization/
+    ├── VeltCustomization.tsx
+    ├── VeltCommentBubbleWf.tsx
+    ├── VeltCommentToolWf.tsx
+    ├── VeltNotificationsToolWf.tsx
+    ├── VeltSidebarButtonWf.tsx
+    └── styles.css
+```
+
+### With CRDT flags or `--all`
+
+```
+components/velt/
+├── VeltTools.tsx               # Full toolbar (+ VeltHuddleTool for ReactFlow)
+└── ui-customization/
+    ├── VeltCustomization.tsx
+    ├── VeltCommentBubbleWf.tsx
+    ├── VeltCommentToolWf.tsx
+    ├── VeltNotificationsToolWf.tsx
+    ├── VeltSidebarButtonWf.tsx
+    └── styles.css
+```
+
+## Auto-Wiring
+
+The CLI automatically modifies your app layout to include VeltProvider and VeltCollaboration:
+
+**App Router** (`app/layout.tsx`):
+- Adds imports for VeltProvider, useVeltAuthProvider, and VeltCollaboration
+- Creates a `VeltClientWrapper` component
+- Wraps `{children}` with the wrapper inside `<body>`
+
+**Pages Router** (`pages/_app.tsx`):
+- Adds the same imports
+- Wraps `<Component {...pageProps} />` with VeltClientWrapper
+
+The auto-wiring is **idempotent** - running the CLI again won't duplicate the wiring.
+
+## Strict Scoping Rules
+
+The CLI enforces strict scoping to avoid installing unnecessary dependencies or files:
+
+- **`--comments` only**: No notifications wireframes included
+- **`--notifications` only**: No comment wireframes included
+- **CRDT types**: Only ONE can be selected at a time
+- **`--all`**: REQUIRES a CRDT type flag
+
+## Setup After Installation
+
+### 1. Get Your API Key
+
+Get your API key from [Velt Console](https://console.velt.dev).
+
+### 2. Configure API Key
+
+After running the CLI, update your API key in the auto-wired layout:
+
+```tsx
+// In app/layout.tsx (auto-generated VeltClientWrapper)
+<VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY || 'YOUR_API_KEY'} authProvider={authProvider}>
+```
+
+Or set `NEXT_PUBLIC_VELT_API_KEY` in your `.env.local` file.
+
+### 3. Configure Document ID
+
+Update `components/velt/VeltInitializeDocument.tsx` with your document ID source:
+
+```tsx
+// Replace with your document ID logic
+const documentId = 'your-document-id';
+const documentName = 'your-document-name';
+```
+
+### 4. Configure User Authentication
+
+Update `components/velt/VeltInitializeUser.tsx` with your user context:
+
+```tsx
+// Replace with your user retrieval logic
+const user = {
+  userId: 'user-id',
+  organizationId: 'organization-id',
+  email: 'user@example.com',
+};
+```
+
+### 5. Add VeltTools (if using features)
+
+```tsx
+import VeltTools from '@/components/velt/VeltTools';
+
+export default function MyPage() {
+  return (
+    <>
+      <div className="toolbar">
+        <VeltTools />
+      </div>
+      {/* Your page content */}
+    </>
+  );
+}
+```
+
+### 6. CRDT-Specific Setup
+
+For CRDT integrations, see the relevant documentation:
+- **ReactFlow**: https://docs.velt.dev/realtime-collaboration/crdt/setup/reactflow
+- **Tiptap**: https://docs.velt.dev/realtime-collaboration/crdt/setup/tiptap
+- **CodeMirror**: https://docs.velt.dev/realtime-collaboration/crdt/setup/codemirror
+
+## Troubleshooting
+
+### Dependency Conflicts
+
+```bash
+npx add-velt --force
+# or
+npx add-velt --legacy-peer-deps
+```
+
+### Existing Files
+
+Use `--force` to overwrite:
+
+```bash
+npx add-velt --comments --force
+```
+
+### Multiple CRDT Types Error
+
+Only one CRDT type can be selected:
+
+```bash
+# Wrong - will error
+npx add-velt --reactflow-crdt --tiptap-crdt
+
+# Correct
+npx add-velt --reactflow-crdt
+```
+
+### --all Without CRDT Type Error
+
+The `--all` flag requires a CRDT type:
+
+```bash
+# Wrong - will error
+npx add-velt --all
+
+# Correct
+npx add-velt --all --reactflow-crdt
+```
+
+### Auto-Wiring Failed
+
+If no layout file was found, manually wrap your app:
+
+```tsx
+// app/layout.tsx
+import { VeltProvider } from '@veltdev/react';
+import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
+import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
+
+function VeltClientWrapper({ children }: { children: React.ReactNode }) {
+  const { authProvider } = useVeltAuthProvider();
+  return (
+    <VeltProvider apiKey="YOUR_API_KEY" authProvider={authProvider}>
+      <VeltCollaboration />
+      {children}
+    </VeltProvider>
+  );
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <VeltClientWrapper>{children}</VeltClientWrapper>
+      </body>
+    </html>
+  );
+}
+```
+
+## Version Compatibility
+
+- **Next.js**: 13.4.0+
+- **React**: 18.2.0+
+- **TypeScript**: 5.0.0+
+- **Node.js**: 18+
+
+## Support
+
+- [Velt Documentation](https://docs.velt.dev)
+- [Velt Console](https://console.velt.dev)

package/assets/icons/bell-icon.svg

@@ -0,0 +1,5 @@
+<svg preserveAspectRatio="none" width="100%" height="100%" overflow="visible" style="display: block;" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="tabler-icon-bell">
+<path id="Vector" d="M7.29441 13.7726V14.5828C7.29441 15.2274 7.55049 15.8456 8.00631 16.3015C8.46212 16.7573 9.08035 17.0133 9.72497 17.0133C10.3696 17.0133 10.9878 16.7573 11.4436 16.3015C11.8994 15.8456 12.1555 15.2274 12.1555 14.5828V13.7726M8.1046 4.05038C8.1046 3.62064 8.27532 3.20849 8.57919 2.90461C8.88307 2.60073 9.29522 2.43001 9.72497 2.43001C10.1547 2.43001 10.5669 2.60073 10.8707 2.90461C11.1746 3.20849 11.3453 3.62064 11.3453 4.05038C12.2758 4.49034 13.0689 5.17519 13.6398 6.03153C14.2107 6.88787 14.5378 7.88343 14.5861 8.9115V11.3421C14.6471 11.8457 14.8254 12.3281 15.1069 12.7503C15.3883 13.1724 15.7649 13.5226 16.2065 13.7726H3.24349C3.68499 13.5226 4.06162 13.1724 4.34306 12.7503C4.6245 12.3281 4.80289 11.8457 4.86386 11.3421V8.9115C4.91211 7.88343 5.23922 6.88787 5.81011 6.03153C6.38101 5.17519 7.17418 4.49034 8.1046 4.05038Z" stroke="var(--stroke-0, white)" stroke-width="1.21528" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+</svg>

package/assets/icons/inbox-icon.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" width="100%" height="100%" overflow="visible" style="display: block;" viewBox="0 0 16 15" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector 291" d="M1 8.31818L3.09957 2.28192C3.36653 1.5144 4.09009 1 4.9027 1H8H11.0973C11.9099 1 12.6335 1.5144 12.9004 2.28192L15 8.31818M1 8.31818H3.07287C3.57919 8.31818 4.06477 8.51932 4.4228 8.87734L5.84993 10.3045C6.20795 10.6625 6.69354 10.8636 7.19986 10.8636H8H8.80014C9.30646 10.8636 9.79204 10.6625 10.1501 10.3045L11.5772 8.87734C11.9352 8.51932 12.4208 8.31818 12.9271 8.31818H15M1 8.31818V11.6638C1 12.1701 1.20114 12.6557 1.55916 13.0137L1.71357 13.1681C2.07159 13.5261 2.55718 13.7273 3.0635 13.7273H8H12.9365C13.4428 13.7273 13.9284 13.5261 14.2864 13.1681L14.4408 13.0137C14.7989 12.6557 15 12.1701 15 11.6638V8.31818" stroke="var(--stroke-0, white)" stroke-width="1.25"/>
+</svg>