Story 32: Multi-Instance Worktree Support

Add configurable port via STORYKIT_PORT env var (default 3001). Server
prints machine-readable STORYKIT_PORT=<port> on startup and writes
.story_kit_port file for discovery. Frontend proxy and WebSocket read
VITE_STORYKIT_PORT env var instead of hardcoding port 3001.

7 new tests (4 backend, 3 frontend) all passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/src/main.rs

@@ -14,9 +14,31 @@ use crate::store::JsonFileStore;
 use crate::workflow::WorkflowState;
 use poem::Server;
 use poem::listener::TcpListener;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
+const DEFAULT_PORT: u16 = 3001;
+
+fn parse_port(value: Option<String>) -> u16 {
+    value
+        .and_then(|v| v.parse::<u16>().ok())
+        .unwrap_or(DEFAULT_PORT)
+}
+
+fn resolve_port() -> u16 {
+    parse_port(std::env::var("STORYKIT_PORT").ok())
+}
+
+fn write_port_file(dir: &Path, port: u16) -> Option<PathBuf> {
+    let path = dir.join(".story_kit_port");
+    std::fs::write(&path, port.to_string()).ok()?;
+    Some(path)
+}
+
+fn remove_port_file(path: &Path) {
+    let _ = std::fs::remove_file(path);
+}
+
 #[tokio::main]
 async fn main() -> Result<(), std::io::Error> {
     let app_state = Arc::new(SessionState::default());
@@ -35,13 +57,55 @@ async fn main() -> Result<(), std::io::Error> {
 
     let app = build_routes(ctx);
 
+    let port = resolve_port();
+    let addr = format!("127.0.0.1:{port}");
+
     println!(
         "\x1b[95;1m  ____  _             _    ___ _   \n / ___|| |_ ___  _ __| | _|_ _| |_ \n \\___ \\| __/ _ \\| '__| |/ /| || __|\n  ___) | || (_) | |  |   < | || |_ \n |____/ \\__\\___/|_|  |_|\\_\\___|\\__|\n\x1b[0m"
     );
-    println!("\x1b[96;1mFrontend:\x1b[0m \x1b[94mhttp://127.0.0.1:3001\x1b[0m");
-    println!("\x1b[92;1mOpenAPI Docs:\x1b[0m \x1b[94mhttp://127.0.0.1:3001/docs\x1b[0m");
+    println!("STORYKIT_PORT={port}");
+    println!("\x1b[96;1mFrontend:\x1b[0m \x1b[94mhttp://{addr}\x1b[0m");
+    println!("\x1b[92;1mOpenAPI Docs:\x1b[0m \x1b[94mhttp://{addr}/docs\x1b[0m");
 
-    Server::new(TcpListener::bind("127.0.0.1:3001"))
-        .run(app)
-        .await
+    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let port_file = write_port_file(&cwd, port);
+
+    let result = Server::new(TcpListener::bind(&addr)).run(app).await;
+
+    if let Some(ref path) = port_file {
+        remove_port_file(path);
+    }
+
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_port_defaults_to_3001() {
+        assert_eq!(parse_port(None), 3001);
+    }
+
+    #[test]
+    fn parse_port_reads_valid_value() {
+        assert_eq!(parse_port(Some("4200".to_string())), 4200);
+    }
+
+    #[test]
+    fn parse_port_ignores_invalid_value() {
+        assert_eq!(parse_port(Some("not_a_number".to_string())), 3001);
+    }
+
+    #[test]
+    fn write_and_remove_port_file() {
+        let tmp = tempfile::tempdir().unwrap();
+
+        let path = write_port_file(tmp.path(), 4567).expect("should write port file");
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), "4567");
+
+        remove_port_file(&path);
+        assert!(!path.exists());
+    }
 }