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

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)

npx @jancer/codesync@latest doctor

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

4. Start Watching

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.

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.

npx @jancer/codesync@latest sync

codesync watch

Watch for file changes and sync automatically.

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).

npx @jancer/codesync@latest scan

codesync doctor

Run pre-flight checks on configuration and connectivity.

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.

npx @jancer/codesync@latest status

codesync --version

Show version and build info.

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:

{
  "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:

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:

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