initial commit

[jiashengguo]

Summary by CodeRabbit

Release Notes

• New Features

  • ZenStack Proxy CLI—a command-line tool for running a proxy server
  • Dynamic database support for SQLite, PostgreSQL, and MySQL
  • API endpoints for model operations and schema introspection
  • Telemetry and error tracking capabilities

• Documentation

  • Added README with installation, usage instructions, and API examples

• Chores

  • Added automated CI/CD workflows
  • Configured dependency management automation
  • Setup TypeScript project configuration

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new ZenStack Proxy CLI project with configuration files, GitHub Actions workflows for CI/CD and code review, TypeScript source code for a Node.js server, telemetry and utility modules, build scripts, and project documentation.

Changes

Cohort / File(s)	Summary
GitHub Configuration \.github/dependabot\.yml, \.github/workflows/build-test\.yml, \.github/workflows/claude-code-review\.yml, \.github/workflows/publish-release\.yml	Adds Dependabot configuration for weekly updates to devcontainers and npm. Defines three GitHub Actions workflows: one for running build and test on PRs to main/dev with pnpm caching, one for automated Claude-based code review on PRs, and one for publishing releases on pushes to main with changelog generation and GitHub Release creation.
Project Setup & Build Configuration package\.json, tsconfig\.json, \.gitignore, README\.md	Configures the CLI project with package metadata, bin entry point (zenstack-proxy → bin/cli.js), build scripts, and dependencies (Express, Prisma adapters, TypeScript). TypeScript config targets ES2020 with strict mode and Node module resolution. Ignore patterns for build artifacts, logs, and environment files. README documents CLI installation, usage, options, and API endpoints.
Build & Telemetry Injection scripts/post-build\.ts, src/constants\.ts	Post-build script reads TELEMETRY_TRACKING_TOKEN from environment and injects it into dist/constants.js. Exports a placeholder constant TELEMETRY_TRACKING_TOKEN replaced at build time.
CLI Entry Point & Error Handling src/index\.ts, src/cli-error\.ts	CLI entrypoint using Commander for argument parsing (zenstack path, port, schema, datasource URL, log levels). Validates ZModel schema, instantiates server, wraps execution with telemetry tracking, and handles CommanderError, CliError, and generic errors with colored output and graceful telemetry flush on exit. CliError is a semantic error class for CLI execution failures.
Express Server & Prisma Integration src/server\.ts	Core server module orchestrating Express app setup, dynamic Prisma client loading, adapter selection (SQLite/PostgreSQL/MySQL), ZenStack module resolution, middleware integration, API endpoints (/api/model for operations, /api/schema for metadata), and graceful shutdown. Resolves Prisma schema and adapter paths, validates database connectivity, and handles missing dependencies with descriptive errors.
Telemetry System src/telemetry\.ts	Implements Telemetry class with Mixpanel client initialization (conditional on DO_NOT_TRACK and token presence). Collects environment metadata (host machine ID, OS, Node/Prisma versions, CI/container context). Exports TelemetryEvents type with three events (proxy:start, proxy:complete, proxy:error). Provides track, trackError, trackSpan, and trackCli methods for event emission and duration measurement.
Utility Modules src/utils/exec-utils\.ts, src/utils/is-ci\.ts, src/utils/is-container\.ts, src/utils/is-docker\.ts, src/utils/is-wsl\.ts	Helper utilities for shell execution (execSync, execPackage with package manager detection), CI environment detection, container detection (Docker/Podman via /.dockerenv and /run/.containerenv), and WSL detection (/proc/version parsing).
Platform & Version Utilities src/utils/machine-id-utils\.ts, src/utils/version-utils\.ts	Cross-platform machine ID detection with SHA-256 hashing and fallback to random UUID. Version utilities to read app, ZenStack, and Prisma versions from package.json files with fallback paths; node_modules folder discovery via recursive upward traversal.
ZModel Schema Parser src/zmodel-parser\.ts	Parses ZModel schema to extract datasource (provider, URL), generator (provider, output, engineType), and Prisma schema path. Handles comment stripping, environment variable resolution, Prisma 7 config evaluation (prisma.config.ts), and datasource URL override. Throws CliError for missing required fields or malformed blocks.

Sequence Diagram

sequenceDiagram
    participant Client
    participant CLI
    participant Server
    participant Express
    participant Telemetry
    participant ZenStack
    participant Prisma
    participant DB as Database

    Client->>CLI: zenstack-proxy [options]
    activate CLI
    CLI->>CLI: Parse args & validate ZModel schema
    CLI->>Telemetry: Initialize (trackCli start)
    activate Telemetry
    
    CLI->>Server: startServer(options)
    activate Server
    
    Server->>Server: Load ZenStack & Prisma modules
    Server->>Prisma: Create PrismaClient with adapter
    activate Prisma
    Prisma->>DB: Connect & validate
    activate DB
    DB-->>Prisma: ✓ Connected
    deactivate DB
    Prisma-->>Server: ✓ Ready
    deactivate Prisma
    
    Server->>Express: Configure middlewares & routes
    activate Express
    Express-->>Server: ✓ Ready
    
    Server-->>CLI: Server listening on port
    deactivate Server
    
    Note over Client: API Request
    Client->>Express: POST /api/model/:model/:operation
    activate Express
    Express->>ZenStack: ZenStackMiddleware (getPrisma)
    activate ZenStack
    ZenStack->>Prisma: Execute operation via PrismaClient
    activate Prisma
    Prisma->>DB: Query
    activate DB
    DB-->>Prisma: Result
    deactivate DB
    Prisma-->>ZenStack: Data
    deactivate Prisma
    ZenStack-->>Express: Response
    deactivate ZenStack
    Express-->>Client: 200 + Result
    deactivate Express
    
    Note over Client: Schema Endpoint
    Client->>Express: GET /api/schema
    Express-->>Client: 200 + Schema metadata
    
    CLI->>Telemetry: trackSpan complete
    deactivate Telemetry
    deactivate CLI

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A proxy so fine, now hops through the CLI,
Express and Prisma dance way up high!
Telemetry tracks each swift operation,
ZenStack's magic in modular formation,
Build scripts and workflows—this bundle's a sight! 🚀

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between c5d4ccd and 46e9e31.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (22)

• .github/dependabot.yml
• .github/workflows/build-test.yml
• .github/workflows/claude-code-review.yml
• .github/workflows/publish-release.yml
• .gitignore
• README.md
• package.json
• scripts/post-build.ts
• src/cli-error.ts
• src/constants.ts
• src/index.ts
• src/server.ts
• src/telemetry.ts
• src/utils/exec-utils.ts
• src/utils/is-ci.ts
• src/utils/is-container.ts
• src/utils/is-docker.ts
• src/utils/is-wsl.ts
• src/utils/machine-id-utils.ts
• src/utils/version-utils.ts
• src/zmodel-parser.ts
• tsconfig.json

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jiashengguo]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.