chatporter 1.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/API.md

@@ -0,0 +1,133 @@
+# v0 Platform API Integration
+
+ChatPorter integrates with the [v0 Platform API](https://v0.app/docs/api/platform) to create actual chat sessions from your markdown files.
+
+## API Reference
+
+Based on the [v0 Platform API documentation](https://v0.app/docs/api/platform/guides/start-from-existing-code), ChatPorter uses the `chats.init()` method to create chats from files.
+
+## Authentication
+
+Get your API key from: https://v0.app/settings/api
+
+Set it as an environment variable:
+```bash
+export V0_API_KEY=your_api_key_here
+```
+
+Or use the `--api-key` option:
+```bash
+chatporter upload docs/*.md --api --api-key your_key
+```
+
+## API Endpoints
+
+ChatPorter uses the following v0 Platform API endpoints:
+
+- **Create Chat**: `POST /v1/chats/init`
+  - Creates a new chat session with uploaded files
+  - Returns chat ID and URL
+
+## Implementation Details
+
+### SDK vs Direct API
+
+ChatPorter tries to use the `v0-sdk` package first (if installed), then falls back to direct HTTP API calls. This ensures compatibility even if the SDK package structure changes.
+
+### File Format
+
+Files are uploaded in the format expected by v0:
+
+```javascript
+{
+  type: 'files',
+  files: [
+    {
+      name: 'docs/filename.md',
+      content: 'file content...',
+      locked: false  // Whether AI can modify this file
+    }
+  ],
+  name: 'Chat Name',
+  lockAllFiles: false,
+  projectId: 'optional-project-id'
+}
+```
+
+### Response Format
+
+Successful API calls return:
+
+```javascript
+{
+  id: 'chat-id',
+  // ... other chat properties
+}
+```
+
+The chat URL is: `https://v0.dev/chat/{chat.id}`
+
+## Error Handling
+
+ChatPorter handles common API errors:
+
+- **401 Unauthorized**: Invalid or missing API key
+- **400 Bad Request**: Invalid file format or payload
+- **Network Errors**: Connection issues
+
+All errors are displayed with helpful messages and suggestions.
+
+## Rate Limits
+
+Refer to the [v0 Platform API rate limits](https://v0.app/docs/api/platform/rate-limits) documentation for current limits.
+
+## Examples
+
+### Basic API Usage
+
+```bash
+# Set API key
+export V0_API_KEY=your_key
+
+# Create chat
+chatporter upload docs/*.md --api
+```
+
+### With Options
+
+```bash
+chatporter upload docs/*.md \
+  --api \
+  --name "Project Documentation" \
+  --lock-files \
+  --project-id your-project-id
+```
+
+### Interactive Mode
+
+```bash
+chatporter
+# Select "v0.dev (API)" option
+# Enter API key if not set
+```
+
+## Troubleshooting
+
+**Issue**: `V0_API_KEY not found`
+- **Solution**: Set the environment variable or use `--api-key` option
+
+**Issue**: `API Error: 401`
+- **Solution**: Check that your API key is valid and not expired
+
+**Issue**: `v0-sdk not found`
+- **Solution**: This is fine - ChatPorter will use direct HTTP calls
+
+**Issue**: `Network error`
+- **Solution**: Check your internet connection and firewall settings
+
+## References
+
+- [v0 Platform API Docs](https://v0.app/docs/api/platform)
+- [Start from Existing Code Guide](https://v0.app/docs/api/platform/guides/start-from-existing-code)
+- [v0 SDK Package](https://www.npmjs.com/package/v0-sdk)
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+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

@@ -0,0 +1,207 @@
+# ChatPorter 🚀
+
+**Import repositories and directories from your local machine into v0.dev chats**
+
+ChatPorter is a CLI utility that imports your local codebases, repositories, and directories directly into v0.dev chats via the Platform API. Perfect for bringing your entire project context into v0 for AI-assisted development, code review, and technical discussions.
+
+## Features
+
+- 📁 **Import local directories** - Bring your entire local codebase into v0.dev
+- 📦 **Import GitHub repositories** - Import repos directly from GitHub URLs
+- 📎 **Import zip archives** - Import code from zip archive URLs
+- 📄 **Upload individual files** - Import specific markdown or code files
+- 🚀 **Create v0 chats via Platform API** - Directly creates chats in v0.dev
+- 🔗 **Automatic browser opening** - Opens your new chat automatically
+- 🔒 **File locking options** - Lock files to prevent AI modifications
+- ⚡ Fast, lightweight, zero-config CLI
+
+## Installation
+
+```bash
+npm install -g chatporter
+```
+
+Or use it directly with `npx`:
+
+```bash
+npx chatporter
+```
+
+## Quick Start
+
+### Import Local Directory (Most Common!)
+
+```bash
+# Set your API key first
+export V0_API_KEY=your_api_key_here
+
+# Import entire local directory into v0
+chatporter dir ./my-project
+
+# With custom chat name
+chatporter dir ./my-project --name "My Project"
+```
+
+### Import GitHub Repository
+
+```bash
+# Set your API key first
+export V0_API_KEY=your_api_key_here
+
+# Import entire GitHub repository
+chatporter repo https://github.com/username/my-project
+
+# With custom branch and name
+chatporter repo https://github.com/username/my-project --branch develop --name "My Project Dev"
+
+# Lock all files from AI modification
+chatporter repo https://github.com/username/my-project --lock-all-files
+```
+
+
+### Import Zip Archive
+
+```bash
+# Import from zip URL
+chatporter zip https://github.com/username/project/archive/main.zip
+
+# With custom name
+chatporter zip https://github.com/username/project/archive/main.zip --name "Project Archive"
+```
+
+### Upload Individual Files
+
+```bash
+# Create v0 chat from markdown files
+chatporter upload docs/*.md --platform v0 --api
+
+# With custom name and locked files
+chatporter upload docs/*.md --platform v0 --api --name "Project Docs" --lock-files
+```
+
+### Interactive mode
+
+```bash
+chatporter
+```
+
+This will prompt you to:
+1. Select files to upload
+2. Choose your target platform (v0 API, v0 formatted, ChatGPT, Claude, etc.)
+3. Create chat via API or generate formatted output
+
+## Usage
+
+### Basic Upload
+
+```bash
+chatporter upload <file1> [file2] [file3...]
+```
+
+### Format for Specific Platform
+
+```bash
+chatporter upload docs/timeline.md --platform v0
+chatporter upload docs/task-list.md --platform chatgpt
+```
+
+### Output to File
+
+```bash
+chatporter upload docs/*.md --output formatted-context.txt
+```
+
+### Open Directly
+
+```bash
+chatporter upload docs/spec.md --open v0
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+V0_API_KEY=your_v0_api_key_here
+```
+
+Get your API key from: https://v0.app/settings/api
+
+### Config File
+
+Create a `.chatporterrc.json` file in your project root:
+
+```json
+{
+  "defaultPlatform": "v0",
+  "includeMetadata": true,
+  "format": "concise",
+  "maxFileSize": "10MB"
+}
+```
+
+## Examples
+
+### Import Local Codebase (Primary Use Case)
+
+```bash
+# Import your local project directory
+chatporter dir ./my-project
+
+# Import with custom name
+chatporter dir ./my-project --name "Production Codebase"
+
+# Import and lock all files from modification
+chatporter dir ./my-project --lock-all-files
+```
+
+### Import from GitHub
+
+```bash
+# Import GitHub repository
+chatporter repo https://github.com/yourusername/your-project
+
+# Import specific branch
+chatporter repo https://github.com/yourusername/your-project --branch develop
+```
+
+### Import from Zip Archive
+
+```bash
+# Import from zip URL
+chatporter zip https://github.com/user/repo/archive/main.zip
+```
+
+### Upload Individual Files
+
+```bash
+# Upload markdown files to v0
+chatporter upload docs/*.md --platform v0 --api
+
+# Upload specific files with custom name
+chatporter upload docs/timeline.md docs/task-list.md --platform v0 --api --name "Project Timeline"
+```
+
+## How It Works
+
+1. **Scans** your local directory or repository for files
+2. **Reads** all code and documentation files (excluding node_modules, .git, etc.)
+3. **Uploads** files to v0.dev via the Platform API
+4. **Creates** a new chat session with your codebase as context
+5. **Opens** the chat in your browser automatically
+
+## Platform Support
+
+- ✅ **v0.dev** (Primary) - Direct API integration for creating chats
+- 📝 **Formatted output** - Also supports generating formatted text for ChatGPT, Claude, Cursor AI
+
+## License
+
+MIT
+
+## Contributing
+
+This is a standalone utility. Feel free to fork and adapt for your needs!
+

package/REPOSITORY.md

@@ -0,0 +1,183 @@
+# Repository Import Guide
+
+ChatPorter supports importing entire repositories into v0 chats, exactly as described in the [v0 Platform API documentation](https://v0.app/docs/api/platform/guides/start-from-existing-code).
+
+## Supported Import Types
+
+### 1. GitHub Repositories
+
+Import directly from public or private GitHub repositories:
+
+```bash
+chatporter repo https://github.com/username/my-react-app
+```
+
+**Options:**
+- `--branch <branch>` - Specify git branch (default: `main`)
+- `--name <name>` - Custom chat name
+- `--project-id <id>` - Associate with v0 project
+- `--lock-all-files` - Lock all files from AI modification
+- `--no-open` - Don't open browser after creation
+
+**Example:**
+```bash
+chatporter repo https://github.com/username/my-app \
+  --branch develop \
+  --name "Development Branch" \
+  --lock-all-files
+```
+
+### 2. Local Directories
+
+Import your entire local project directory:
+
+```bash
+chatporter dir ./my-project
+```
+
+**How it works:**
+- Recursively walks the directory
+- Automatically excludes: `node_modules`, `.git`, `.next`, `dist`, `build`, etc.
+- Reads all text files (skips binary files)
+- Uploads everything to v0
+
+**Options:**
+- `--name <name>` - Custom chat name
+- `--project-id <id>` - Associate with v0 project
+- `--lock-files` - Lock individual files from AI modification
+- `--lock-all-files` - Lock all files from AI modification
+- `--no-open` - Don't open browser after creation
+
+**Example:**
+```bash
+chatporter dir ../Cherry \
+  --name "Cherry Project" \
+  --lock-all-files
+```
+
+### 3. Zip Archives
+
+Import from zip archive URLs:
+
+```bash
+chatporter zip https://github.com/username/project/archive/refs/heads/main.zip
+```
+
+**Options:**
+- `--name <name>` - Custom chat name
+- `--project-id <id>` - Associate with v0 project
+- `--lock-all-files` - Lock all files from AI modification
+- `--no-open` - Don't open browser after creation
+
+**Example:**
+```bash
+chatporter zip https://github.com/user/repo/archive/main.zip \
+  --name "Project Archive"
+```
+
+## Auto-Detection
+
+The `upload` command automatically detects repository URLs and directories:
+
+```bash
+# GitHub URL - automatically uses repo import
+chatporter upload https://github.com/user/repo --platform v0 --api
+
+# Directory path - automatically uses directory import
+chatporter upload ./my-project --platform v0 --api
+
+# Individual files - uses file upload
+chatporter upload docs/*.md --platform v0 --api
+```
+
+## Use Cases
+
+### Import Your Current Project
+
+```bash
+# From your project root
+cd /path/to/your-project
+chatporter dir . --name "My Project"
+```
+
+### Import from GitHub
+
+```bash
+# Public repository
+chatporter repo https://github.com/vercel/next.js
+
+# Specific branch
+chatporter repo https://github.com/user/repo --branch feature-branch
+```
+
+### Import Cherry Project
+
+```bash
+# From Cherry directory
+cd /Users/stagner/workspace/Cherry
+chatporter dir . --name "Cherry Escrow Platform"
+```
+
+## File Locking
+
+Control which files the AI can modify:
+
+```bash
+# Lock all files (read-only)
+chatporter repo https://github.com/user/repo --lock-all-files
+
+# Lock individual files (for directory imports)
+chatporter dir ./project --lock-files
+```
+
+## Project Association
+
+Associate chats with v0 projects:
+
+```bash
+chatporter repo https://github.com/user/repo \
+  --project-id your-project-id \
+  --name "Project Chat"
+```
+
+## Interactive Mode
+
+Use interactive mode for guided repository imports:
+
+```bash
+chatporter
+# Select "GitHub Repository", "Local Directory", or "Zip Archive URL"
+# Follow prompts
+```
+
+## Best Practices
+
+1. **Use descriptive names**: `--name "Project Name - Feature Branch"`
+2. **Lock important files**: Use `--lock-all-files` for production code
+3. **Specify branches**: Use `--branch` for GitHub imports to get the right code
+4. **Associate with projects**: Use `--project-id` to organize chats
+
+## API Reference
+
+All repository imports use the v0 Platform API `chats.init()` method:
+
+- **Repositories**: `type: 'repo'`
+- **Directories**: `type: 'files'` (with all directory files)
+- **Zip Archives**: `type: 'zip'`
+
+See the [v0 Platform API documentation](https://v0.app/docs/api/platform/guides/start-from-existing-code) for details.
+
+## Troubleshooting
+
+**Issue**: `Repository not found` or `401 Unauthorized`
+- **Solution**: Check that the repository is accessible and your API key is valid
+
+**Issue**: `Directory is empty`
+- **Solution**: Ensure the directory contains files and isn't excluded by ignore patterns
+
+**Issue**: `Too many files`
+- **Solution**: v0 may have limits on file count. Try importing a subset or use a zip archive
+
+**Issue**: `Binary files skipped`
+- **Solution**: This is expected. Only text files are imported. Binary files are automatically skipped.
+