zdev 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, January 2026
+
+ Copyright (C) 2026 5hanth
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

package/README.md

@@ -0,0 +1,311 @@
+# 🐂 zdev
+
+Multi-agent worktree development environment for Vite/TanStack projects.
+
+Built for [Clawdbot](https://docs.clawd.bot) users who want to run multiple AI coding agents on different features simultaneously.
+
+Supports:
+- **Vite** / **TanStack Start** frontends
+- **Convex** backend (optional — auto-detected)
+- **Monorepos** with `web/`, `apps/web/`, etc.
+
+## Features
+
+- **Worktree Management** — Isolated git worktrees per feature
+- **Port Allocation** — Automatic port assignment, no conflicts
+- **Preview URLs** — Public HTTPS URLs via Traefik (optional)
+- **Config Auto-Copy** — `.env.local` and other files copied automatically
+- **Vite Support** — Auto-patches `allowedHosts` for external access
+- **Convex Integration** — Auto-detected; runs `convex dev` if present
+- **Monorepo Support** — Auto-detects `web/`, `frontend/`, `apps/web/`, etc.
+
+## Installation
+
+```bash
+# Run directly
+bunx zdev
+
+# Or install globally
+bun add -g zdev
+```
+
+## Using with AI Agents
+
+### Claude Code / Clawdbot
+
+Add the zdev skill to teach your agent the workflow:
+
+```bash
+npx add-skill 5hanth/zdev-skill
+```
+
+Then prompt your agent:
+```
+Use zdev to create a new project called my-app and start a feature branch for authentication.
+```
+
+### Manual Setup
+
+If your agent doesn't support skills, copy the [SKILL.md](https://github.com/5hanth/zdev-skill/blob/main/SKILL.md) contents into your agent's context or system prompt.
+
+## Prerequisites
+
+### Required
+- [Bun](https://bun.sh) — `curl -fsSL https://bun.sh/install | bash`
+- Git repository with Vite-based frontend
+
+### Optional
+- [Convex](https://convex.dev) — auto-detected if `convex/` directory exists
+
+### Optional (for public preview URLs)
+- [Traefik](https://traefik.io) reverse proxy with file provider
+- DNS wildcard record (`*.dev.yourdomain.com`)
+
+See [Traefik Setup](#traefik-setup-for-preview-urls) below.
+
+## Quick Start
+
+### New Project
+
+```bash
+# Create a new TanStack Start project
+zdev create my-app
+
+# Or with Convex backend
+zdev create my-app --convex
+
+# Flat structure (no monorepo)
+zdev create my-app --convex --flat
+```
+
+### Existing Project
+
+```bash
+# 1. Initialize your project
+cd your-project
+zdev init
+
+# 2. (Convex only) Setup Convex once if not already done
+cd web  # or wherever package.json is
+bunx convex dev  # select project, then Ctrl+C
+
+# 3. Start a feature
+zdev start my-feature -p /path/to/project
+
+# 4. Work on it
+cd ~/.zdev/worktrees/project-my-feature
+
+# 5. Stop when done
+zdev stop my-feature -p /path/to/project
+```
+
+## Commands
+
+### `zdev create <name>`
+Create a new TanStack Start project from scratch.
+
+```bash
+zdev create my-app             # Basic TanStack Start
+zdev create my-app --convex    # With Convex backend
+zdev create my-app --flat      # Flat structure (no monorepo)
+```
+
+By default creates a monorepo with `web/` subdirectory. Use `--flat` for single-package structure.
+
+### `zdev init [path]`
+Initialize zdev for an existing project. Creates seed data from current Convex state.
+
+```bash
+zdev init                    # Current directory
+zdev init ./my-project       # Specific path
+zdev init -s                 # Also create seed snapshot
+```
+
+### `zdev start <feature>`
+Start working on a feature. Creates worktree, installs deps, starts servers.
+
+```bash
+zdev start auth -p ./my-project
+zdev start auth -p ./my-project --local      # Skip public URL
+zdev start auth -p ./my-project --port 3000  # Specific port
+zdev start auth -p ./my-project --seed       # Import seed data
+zdev start auth --base-branch origin/develop # Different base
+```
+
+### `zdev stop <feature>`
+Stop servers for a feature.
+
+```bash
+zdev stop auth -p ./my-project
+zdev stop auth --keep        # Keep worktree, just stop servers
+```
+
+### `zdev list`
+List all active features and their status.
+
+```bash
+zdev list
+zdev list --json
+```
+
+### `zdev clean <feature>`
+Remove a feature worktree completely (use after PR merged).
+
+```bash
+zdev clean auth -p ./my-project
+zdev clean auth --force      # Force even if git fails
+```
+
+### `zdev seed export/import`
+Manage database seed data.
+
+```bash
+zdev seed export             # Export current Convex state
+zdev seed import             # Import into current worktree
+```
+
+### `zdev config`
+View and manage configuration.
+
+```bash
+zdev config --list
+zdev config --set devDomain=dev.example.com
+zdev config --set traefikConfigDir=/etc/traefik/dynamic
+zdev config --add .env.production
+zdev config --remove .env.production
+```
+
+## Setup Script
+
+zdev uses `.zdev/setup.sh` in your project to run setup commands when creating worktrees.
+
+**Default (generated by `zdev create`):**
+```bash
+#!/bin/bash
+# .zdev/setup.sh - Runs after worktree creation
+
+set -e
+bun install
+```
+
+**Customize it:**
+```bash
+#!/bin/bash
+set -e
+
+# Use a different package manager
+pnpm install
+
+# Generate Prisma client
+bunx prisma generate
+
+# Copy secrets from parent
+cp ../.env.local .
+```
+
+This file is committed to git, so all team members use the same setup.
+
+## Configuration
+
+Config stored at `~/.zdev/config.json`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `devDomain` | (empty) | Domain for preview URLs (e.g., `dev.example.com`) |
+| `dockerHostIp` | `172.17.0.1` | How Traefik (in Docker) reaches host services |
+| `traefikConfigDir` | `/infra/traefik/dynamic` | Directory where Traefik watches for route configs (see below) |
+| `copyPatterns` | `.env.local`, etc. | Files to auto-copy to worktrees |
+
+## Traefik Setup for Preview URLs
+
+> **What's a "dynamic config directory"?**
+> 
+> Traefik can be configured to watch a folder for `.yml` files. Each file defines a route (e.g., "requests to `auth.dev.example.com` go to port 5173"). When you add/remove files, Traefik automatically updates its routing — no restart needed.
+> 
+> zdev uses this to create/remove routes on-the-fly as you start/stop features.
+
+To get public HTTPS URLs for each feature:
+
+### 1. DNS Wildcard
+Add a wildcard A record pointing to your server:
+```
+*.dev.example.com → your-server-ip
+```
+
+### 2. Traefik with File Provider
+Configure Traefik to watch a dynamic config directory:
+
+```yaml
+# traefik.yml
+providers:
+  file:
+    directory: /etc/traefik/dynamic  # zdev writes route files here
+    watch: true
+
+entryPoints:
+  web:
+    address: ":80"
+  websecure:
+    address: ":443"
+
+certificatesResolvers:
+  letsencrypt:
+    acme:
+      email: you@example.com
+      storage: /etc/traefik/acme.json
+      httpChallenge:
+        entryPoint: web
+```
+
+### 3. Configure zdev
+```bash
+zdev config --set devDomain=dev.example.com
+zdev config --set traefikConfigDir=/etc/traefik/dynamic
+zdev config --set dockerHostIp=172.17.0.1  # or host.docker.internal on Mac
+```
+
+### How It Works
+When you run `zdev start my-feature`, it creates a file like `/etc/traefik/dynamic/project-my-feature.yml`:
+
+```yaml
+http:
+  routers:
+    project-my-feature:
+      rule: "Host(`project-my-feature.dev.example.com`)"
+      service: project-my-feature
+      entryPoints:
+        - websecure
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    project-my-feature:
+      loadBalancer:
+        servers:
+          - url: "http://172.17.0.1:5173"  # Host port from Docker's perspective
+```
+
+Traefik watches the directory and automatically picks up the new route.
+
+## Multi-Agent Workflow
+
+1. **Agent A** works on auth: `zdev start auth -p ./project`
+2. **Agent B** works on billing: `zdev start billing -p ./project`
+3. Each gets isolated worktree + ports + preview URL
+4. No conflicts, parallel development
+
+## Directory Structure
+
+```
+~/.zdev/
+├── config.json           # Global config
+├── worktrees/            # All worktrees live here
+│   ├── project-auth/
+│   └── project-billing/
+└── seeds/                # Seed data snapshots
+    └── project.zip
+```
+
+## License
+
+[WTFPL](LICENSE)

package/bun.lock

@@ -0,0 +1,29 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "zebu",
+      "dependencies": {
+        "commander": "^12.0.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
+
+    "@types/node": ["@types/node@25.0.10", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-zWW5KPngR/yvakJgGOmZ5vTBemDoSqF3AcV/LrO5u5wTWyEAVVh+IT39G4gtyAkh3CtTZs8aX/yRM82OfzHJRg=="],
+
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+
+    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}