npm package: @jancer/codesync
Description: CLI tool to sync code changes with ProjectBrain architecture map
Latest version: 1.1.2

# CodeSync CLI

Automatically sync your code structure to ProjectBrain's architecture map.

CodeSync watches your Prisma schemas and API routes, parses them, and updates your ProjectBrain architecture map in real-time.

## Features

- **Prisma Schema Parsing** - Extracts tables, columns, and relationships
- **API Route Detection** - Finds all Next.js API route handlers
- **File Watching** - Automatically syncs on file changes
- **Incremental Updates** - Only sends changes, merges with existing data
- **Content Attach** - Uploads file content for server-side ingestion
- **Doctor Command** - Pre-flight checks for configuration and connectivity

## Prerequisites

- Node.js 18+
- A ProjectBrain project with CodeSync enabled

## Quick Start

### 1. Enable CodeSync in ProjectBrain

In your ProjectBrain project settings, enable CodeSync. This will generate an API key.

### 2. Initialize CodeSync

```bash
npx @jancer/codesync@latest init \
  --project-id YOUR_PROJECT_ID \
  --api-key YOUR_API_KEY
```

This creates a `.codesync` config file in your project root. The API URL defaults to the production Vercel deployment.

### 3. Run Doctor (optional)

```bash
npx @jancer/codesync@latest doctor
```

Checks configuration, connectivity, UUID validity, API key format, and scan results.

### 4. Start Watching

```bash
npx @jancer/codesync@latest watch
```

CodeSync will now automatically sync whenever you modify:
- `prisma/schema.prisma` (or `prisma/schema/*.prisma`)
- `app/api/**/route.ts`
- `src/app/api/**/route.ts`

## Commands

### `codesync init`

Initialize CodeSync in current directory.

```bash
npx @jancer/codesync@latest init --project-id <id> --api-key <key> [--api-url <url>]
```

Options:
- `--project-id` (required) - Your ProjectBrain project ID
- `--api-key` (required) - CodeSync API key from ProjectBrain
- `--api-url` (optional) - ProjectBrain API URL (default: https://projectbrain-nine.vercel.app)

### `codesync sync`

Perform a one-time sync.

```bash
npx @jancer/codesync@latest sync
```

### `codesync watch`

Watch for file changes and sync automatically.

```bash
npx @jancer/codesync@latest watch [--no-initial-sync]
```

Options:
- `--no-initial-sync` - Skip the initial sync when starting

### `codesync scan`

Preview what would be synced (dry run).

```bash
npx @jancer/codesync@latest scan
```

### `codesync doctor`

Run pre-flight checks on configuration and connectivity.

```bash
npx @jancer/codesync@latest doctor
```

Checks:
- `.codesync` file exists and parses
- `apiUrl` is reachable
- `projectId` is a valid UUID
- `apiKey` is present and formatted
- Project scan finds key files with content

### `codesync status`

Show current CodeSync status and configuration.

```bash
npx @jancer/codesync@latest status
```

### `codesync --version`

Show version and build info.

```bash
npx @jancer/codesync@latest --version
```

Prints: package version, git commit SHA, build timestamp, contentAttach flag, and Node.js version.

## Configuration

The `.codesync` file stores your configuration:

```json
{
  "apiUrl": "https://projectbrain-nine.vercel.app",
  "projectId": "your-project-uuid",
  "apiKey": "cs_your_api_key",
  "watchPaths": [
    "prisma/schema.prisma",
    "app/api/**/*.ts"
  ]
}
```

### Environment Variables

Alternatively, configure via environment variables:

```bash
CODESYNC_API_URL=https://projectbrain-nine.vercel.app
CODESYNC_PROJECT_ID=your-project-uuid
CODESYNC_API_KEY=cs_your_api_key
```

### Debug Logging

Set `CODESYNC_DEBUG=1` to enable verbose debug logging:

```bash
CODESYNC_DEBUG=1 npx @jancer/codesync@latest sync
```

## What Gets Synced

### Database Tables (from Prisma)

CodeSync extracts:
- Table/model names
- Column names and types
- Relationships between models
- Doc comments as descriptions

### API Routes

CodeSync detects exported HTTP method handlers from Next.js App Router and Pages Router.

### File Content

Each key file's content is read from disk and sent to the server for ingestion into the `public.files` table. Files exceeding 500KB or detected as binary are skipped.

## How It Works

1. **Watch** - Chokidar monitors specified file patterns
2. **Parse** - On change, parsers extract structured data
3. **Content Attach** - File content is read and included in payload
4. **Debounce** - Waits 2s for burst changes to settle
5. **Sync** - Sends payload to ProjectBrain API
6. **Merge** - Server merges with existing architecture map
7. **Ingest** - Server upserts file content into `public.files`
8. **Version** - New version created with `source: 'codesync'`

## Troubleshooting

### "CodeSync is not enabled for this project"

Enable CodeSync in your ProjectBrain project settings first.

### "Invalid API key"

Regenerate your API key in ProjectBrain settings.

### "No data to sync"

CodeSync only syncs Prisma schemas and API routes. Make sure:
- You have a `prisma/schema.prisma` file, OR
- You have `app/api/**/route.ts` files

### Changes not syncing

1. Run `npx @jancer/codesync@latest doctor` to check configuration
2. Check the watched paths in `.codesync`
3. Ensure files match the glob patterns
4. Enable debug logging: `CODESYNC_DEBUG=1`

## Security

- API keys are hashed (SHA-256) before storage
- Keys are only shown once when generated
- `.codesync` should be in `.gitignore`
- Use environment variables in CI/CD

## License

MIT