feat: range-based port allocation + framework-aware env vars (v0.7.1)

- Port ranges: each worktree gets a 10-port block (3000-3009, 3010-3019, etc.)
  configurable via [isolation] port_range_size in .workz.toml
- Framework detection: auto-detects 14 web frameworks from project files
  (Next.js, Vite, Express, NestJs, Django, Flask, FastAPI, Spring Boot, etc.)
- Framework-specific env vars: SERVER_PORT (Spring), FLASK_RUN_PORT (Flask),
  UVICORN_PORT (FastAPI), VITE_PORT (Vite) written alongside PORT
- MCP server: workz_start tool now accepts isolated parameter
- Backward compatible with existing ports.json (port_count defaults to 1)

Author: rohansx

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "workz"
-version = "0.7.0"
+version = "0.7.1"
 edition = "2021"
 description = "Zoxide for Git worktrees — zero-config sync, fuzzy switching, AI-ready"
 license = "MIT OR Apache-2.0"

Cargo.toml

@@ -10,6 +10,8 @@ pub struct Config {
     pub sync: SyncConfig,
     #[serde(default)]
     pub hooks: HooksConfig,
+    #[serde(default)]
+    pub isolation: IsolationConfig,
 }
 
 #[derive(Debug, Deserialize)]
@@ -38,6 +40,29 @@ pub struct HooksConfig {
     pub pre_done: Option<String>,
 }
 
+#[derive(Debug, Deserialize)]
+pub struct IsolationConfig {
+    /// Number of ports to allocate per worktree (default: 10)
+    #[serde(default = "default_port_range_size")]
+    pub port_range_size: u16,
+
+    /// Base port for first worktree (default: 3000)
+    #[serde(default = "default_base_port")]
+    pub base_port: u16,
+}
+
+fn default_port_range_size() -> u16 { 10 }
+fn default_base_port() -> u16 { 3000 }
+
+impl Default for IsolationConfig {
+    fn default() -> Self {
+        Self {
+            port_range_size: default_port_range_size(),
+            base_port: default_base_port(),
+        }
+    }
+}
+
 fn default_symlink_dirs() -> Vec<String> {
     [
         // JavaScript / Node
@@ -171,5 +196,14 @@ fn merge_configs(global: Config, project: Config) -> Config {
         pre_done: project.hooks.pre_done.or(global.hooks.pre_done),
     };
 
-    Config { sync, hooks }
+    let default_iso = IsolationConfig::default();
+    let isolation = if project.isolation.port_range_size != default_iso.port_range_size
+        || project.isolation.base_port != default_iso.base_port
+    {
+        project.isolation
+    } else {
+        global.isolation
+    };
+
+    Config { sync, hooks, isolation }
 }

src/config.rs

@@ -140,7 +140,7 @@ pub fn cmd_start(
     println!("\nsyncing dependencies...");
     for (i, (ft, wt_path)) in created.iter().enumerate() {
         print!("  [{}/{}] {}... ", i + 1, n, ft.branch);
-        sync::sync_worktree(&root, wt_path, &config.sync)?;
+        let _framework = sync::sync_worktree(&root, wt_path, &config.sync)?;
         println!("done");
     }
 

src/fleet.rs

@@ -4,6 +4,8 @@ use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
+use crate::sync::Framework;
+
 // ── Registry types ───────────────────────────────────────────────────────────
 
 #[derive(Serialize, Deserialize, Debug, Default)]
@@ -21,15 +23,24 @@ fn default_base_port() -> u16 {
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct PortAllocation {
     pub port: u16,
+    /// Number of ports in the allocated range (backward compat: defaults to 1).
+    #[serde(default = "default_port_count")]
+    pub port_count: u16,
     pub branch: String,
     pub db_name: String,
     pub compose_project: String,
     pub worktree_path: String,
     pub allocated_at: String,
 }
 
+fn default_port_count() -> u16 {
+    1
+}
+
 pub struct IsolationConfig {
     pub port: u16,
+    pub port_end: u16,
+    pub port_count: u16,
     pub db_name: String,
     pub compose_project: String,
 }
@@ -79,30 +90,57 @@ pub fn branch_to_slug(branch: &str) -> String {
 
 // ── Port allocation ──────────────────────────────────────────────────────────
 
-fn next_available_port(registry: &PortRegistry) -> u16 {
-    let used: std::collections::HashSet<u16> =
-        registry.allocations.values().map(|a| a.port).collect();
+/// Allocate a contiguous block of `range_size` ports that doesn't overlap any
+/// existing allocation. Aligns to `range_size` boundaries for clean ranges.
+fn next_available_port_range(registry: &PortRegistry, range_size: u16) -> u16 {
+    let occupied: Vec<(u16, u16)> = registry
+        .allocations
+        .values()
+        .map(|a| (a.port, a.port + a.port_count))
+        .collect();
+
     let base = if registry.base_port == 0 { 3000 } else { registry.base_port };
-    let mut port = base;
-    while used.contains(&port) {
-        port += 1;
+    let mut candidate = base;
+
+    // Align to range_size boundaries
+    if range_size > 1 && candidate % range_size != 0 {
+        candidate = candidate + range_size - (candidate % range_size);
+    }
+
+    loop {
+        let candidate_end = candidate + range_size;
+        let overlaps = occupied
+            .iter()
+            .any(|&(start, end)| candidate < end && candidate_end > start);
+        if !overlaps {
+            return candidate;
+        }
+        candidate += range_size;
+        if candidate > 60000 {
+            return candidate;
+        }
     }
-    port
 }
 
 // ── Main API ─────────────────────────────────────────────────────────────────
 
-/// Allocate a port, compute derived names, update registry, write .env.local.
-pub fn setup_isolation(branch: &str, wt_path: &Path) -> Result<IsolationConfig> {
+/// Allocate a port range, compute derived names, update registry, write .env.local.
+pub fn setup_isolation(
+    branch: &str,
+    wt_path: &Path,
+    range_size: u16,
+    framework: Framework,
+) -> Result<IsolationConfig> {
     let mut registry = load_registry();
     let slug = branch_to_slug(branch);
 
     let alloc = if let Some(existing) = registry.allocations.get(&slug) {
         existing.clone()
     } else {
-        let port = next_available_port(&registry);
+        let port = next_available_port_range(&registry, range_size);
         let alloc = PortAllocation {
             port,
+            port_count: range_size,
             branch: branch.to_string(),
             db_name: slug.clone(),
             compose_project: slug.clone(),
@@ -114,10 +152,12 @@ pub fn setup_isolation(branch: &str, wt_path: &Path) -> Result<IsolationConfig>
         alloc
     };
 
-    write_env_local(wt_path, &alloc)?;
+    write_env_local(wt_path, &alloc, framework)?;
 
     Ok(IsolationConfig {
         port: alloc.port,
+        port_end: alloc.port + alloc.port_count - 1,
+        port_count: alloc.port_count,
         db_name: alloc.db_name.clone(),
         compose_project: alloc.compose_project.clone(),
     })
@@ -157,19 +197,46 @@ pub fn get_allocation(branch: &str) -> Option<PortAllocation> {
 
 // ── .env.local writer ────────────────────────────────────────────────────────
 
-fn write_env_local(wt_path: &Path, alloc: &PortAllocation) -> Result<()> {
-    let content = format!(
-        "# Generated by workz --isolated — do not edit manually\n\
-         PORT={port}\n\
-         DB_NAME={db}\n\
-         DATABASE_URL=postgres://localhost/{db}\n\
-         COMPOSE_PROJECT_NAME={compose}\n\
-         REDIS_URL=redis://localhost:{redis}\n",
-        port    = alloc.port,
-        db      = alloc.db_name,
-        compose = alloc.compose_project,
-        redis   = alloc.port + 1000,
-    );
+fn write_env_local(wt_path: &Path, alloc: &PortAllocation, framework: Framework) -> Result<()> {
+    let port = alloc.port;
+    let port_end = alloc.port + alloc.port_count - 1;
+
+    let mut lines = vec![
+        "# Generated by workz --isolated — do not edit manually".to_string(),
+        format!("PORT={}", port),
+    ];
+
+    // Only write PORT_END when we have a range (not a single port)
+    if alloc.port_count > 1 {
+        lines.push(format!("PORT_END={}", port_end));
+    }
+
+    // Framework-specific port vars
+    match framework {
+        Framework::SpringBoot => {
+            lines.push(format!("SERVER_PORT={}", port));
+        }
+        Framework::Flask => {
+            lines.push(format!("FLASK_RUN_PORT={}", port));
+        }
+        Framework::FastApi => {
+            lines.push(format!("UVICORN_PORT={}", port));
+        }
+        Framework::Vite => {
+            lines.push(format!("VITE_PORT={}", port));
+        }
+        _ => {}
+    }
+
+    lines.push(format!("DB_NAME={}", alloc.db_name));
+    lines.push(format!("DATABASE_URL=postgres://localhost/{}", alloc.db_name));
+    lines.push(format!("COMPOSE_PROJECT_NAME={}", alloc.compose_project));
+
+    // Redis on port+1 (within the allocated range, not port+1000)
+    let redis_port = if alloc.port_count > 1 { port + 1 } else { port + 1000 };
+    lines.push(format!("REDIS_URL=redis://localhost:{}", redis_port));
+
+    let content = lines.join("\n") + "\n";
     std::fs::write(wt_path.join(".env.local"), content)?;
     Ok(())
 }
@@ -228,4 +295,57 @@ mod tests {
         // 2024-03-04T12:00:00Z = 1709553600
         assert_eq!(unix_secs_to_rfc3339(1709553600), "2024-03-04T12:00:00Z");
     }
+
+    #[test]
+    fn range_allocation_no_overlap() {
+        let mut registry = PortRegistry { base_port: 3000, allocations: HashMap::new() };
+
+        let port1 = next_available_port_range(&registry, 10);
+        assert_eq!(port1, 3000);
+
+        registry.allocations.insert("first".into(), PortAllocation {
+            port: 3000, port_count: 10,
+            branch: "a".into(), db_name: "a".into(),
+            compose_project: "a".into(), worktree_path: "/tmp/a".into(),
+            allocated_at: "2024-01-01T00:00:00Z".into(),
+        });
+
+        let port2 = next_available_port_range(&registry, 10);
+        assert_eq!(port2, 3010);
+    }
+
+    #[test]
+    fn range_allocation_backward_compat() {
+        let mut registry = PortRegistry { base_port: 3000, allocations: HashMap::new() };
+        registry.allocations.insert("old".into(), PortAllocation {
+            port: 3000, port_count: 1,
+            branch: "old".into(), db_name: "old".into(),
+            compose_project: "old".into(), worktree_path: "/tmp/old".into(),
+            allocated_at: "2024-01-01T00:00:00Z".into(),
+        });
+
+        let port = next_available_port_range(&registry, 10);
+        assert_eq!(port, 3010);
+    }
+
+    #[test]
+    fn range_allocation_gap_filling() {
+        let mut registry = PortRegistry { base_port: 3000, allocations: HashMap::new() };
+
+        registry.allocations.insert("first".into(), PortAllocation {
+            port: 3000, port_count: 10,
+            branch: "a".into(), db_name: "a".into(),
+            compose_project: "a".into(), worktree_path: "/tmp/a".into(),
+            allocated_at: "2024-01-01T00:00:00Z".into(),
+        });
+        registry.allocations.insert("third".into(), PortAllocation {
+            port: 3020, port_count: 10,
+            branch: "c".into(), db_name: "c".into(),
+            compose_project: "c".into(), worktree_path: "/tmp/c".into(),
+            allocated_at: "2024-01-01T00:00:00Z".into(),
+        });
+
+        let port = next_available_port_range(&registry, 10);
+        assert_eq!(port, 3010);
+    }
 }

src/isolation.rs

@@ -87,9 +87,10 @@ fn cmd_start(
     git::worktree_add(&wt_path, branch, base)?;
     println!("  worktree created at {}", wt_path.display());
 
-    if !no_sync {
-        let config = config::load_config(&root)?;
-        sync::sync_worktree(&root, &wt_path, &config.sync)?;
+    let config = config::load_config(&root)?;
+
+    let framework = if !no_sync {
+        let fw = sync::sync_worktree(&root, &wt_path, &config.sync)?;
 
         // Run post_start hook if configured
         if let Some(hook) = &config.hooks.post_start {
@@ -102,15 +103,29 @@ fn cmd_start(
                 eprintln!("  warning: post_start hook exited with {}", status);
             }
         }
-    }
+        fw
+    } else {
+        sync::Framework::Unknown
+    };
 
     if isolated {
-        let iso = isolation::setup_isolation(branch, &wt_path)?;
+        let iso = isolation::setup_isolation(
+            branch,
+            &wt_path,
+            config.isolation.port_range_size,
+            framework,
+        )?;
         println!("  isolated environment:");
-        println!("    PORT={}                 → .env.local", iso.port);
+        if iso.port_count > 1 {
+            println!("    PORT={}..{}            → .env.local", iso.port, iso.port_end);
+        } else {
+            println!("    PORT={}                 → .env.local", iso.port);
+        }
         println!("    DB_NAME={}", iso.db_name);
         println!("    COMPOSE_PROJECT_NAME={}", iso.compose_project);
-        println!("    REDIS_URL=redis://localhost:{}", iso.port + 1000);
+        if framework != sync::Framework::Unknown {
+            println!("    framework={:?}", framework);
+        }
     }
 
     if docker {
@@ -428,7 +443,7 @@ fn cmd_sync() -> Result<()> {
 
     let config = config::load_config(&root)?;
     println!("syncing worktree at {}", cwd.display());
-    sync::sync_worktree(&root, &cwd, &config.sync)?;
+    let _framework = sync::sync_worktree(&root, &cwd, &config.sync)?;
     println!("done!");
     Ok(())
 }
@@ -464,7 +479,13 @@ fn cmd_status() -> Result<()> {
         let docker = if has_compose { "  [docker]" } else { "" };
 
         let port_info = isolation::get_allocation(&wt.branch)
-            .map(|a| format!("  PORT:{}", a.port))
+            .map(|a| {
+                if a.port_count > 1 {
+                    format!("  PORT:{}-{}", a.port, a.port + a.port_count - 1)
+                } else {
+                    format!("  PORT:{}", a.port)
+                }
+            })
             .unwrap_or_default();
 
         println!(