@coopcli/specsketch 0.1.2 → 0.1.3

package/README.md

@@ -51,7 +51,10 @@ specsketch <path-to-openspec-change-dir> [--port <n>]
 ```
 
 - The directory is created if it doesn't exist; its basename becomes the change name.
-- `--port` defaults to 8787. Binds to 127.0.0.1 exclusively — there is no `--host`.
+- `--port` sets the preferred port (default 8787). If it's already in use — say another
+  specsketch session is running — the server moves to the next available port and the
+  printed URL reflects the one actually bound. Binds to 127.0.0.1 exclusively — there is
+  no `--host`.
 - **Model picker** (top bar): `claude-opus-4-8` (default), `claude-sonnet-5`, or
   `claude-fable-5`. The choice is saved with the change directory. Fable runs with
   server-side refusal fallbacks to Opus and requires your org to allow 30-day data
@@ -65,7 +68,7 @@ specsketch <path-to-openspec-change-dir> [--port <n>]
 | Startup warning "No Anthropic credentials detected" | Set `ANTHROPIC_API_KEY` or run `ant auth login`, then restart |
 | Generate fails with a 401 / "anthropic-auth" | Same as above — the server found no credentials, or the login profile expired (`ant auth status`) |
 | "Node NN detected — specsketch needs Node >= 22" | Upgrade Node (https://nodejs.org) |
-| Port already in use | Pass `--port <n>` |
+| Port already in use | Handled automatically — the server moves to the next free port and prints it; `--port <n>` sets the preferred starting port |
 | Regeneration changed a file you hand-edited | Expected when the drawing implicates it — the diagram is the source of truth; use `git diff`/`git checkout` to recover, and keep change dirs in version control |
 
 More: [getting started page](https://coopcli.com/products/specsketch) ·

package/dist/cli/index.js

@@ -374,7 +374,10 @@ var USAGE = `Usage: specsketch <path-to-openspec-change-dir> [--port <n>]
 
 The directory is created if it doesn't exist. Diagrams autosave to
 diagram.excalidraw inside it; Generate Spec writes proposal.md, design.md,
-tasks.md and specs/<capability>/spec.md alongside.`;
+tasks.md and specs/<capability>/spec.md alongside.
+
+--port sets the preferred port (default 8787); if it's already in use the
+server moves to the next available port and prints the actual URL.`;
 var UsageError = class extends Error {
 };
 function parseCliArgs(argv) {
@@ -396,6 +399,18 @@ function parseCliArgs(argv) {
   }
   return { dir, port };
 }
+var PORT_SCAN_LIMIT = 100;
+async function bindAvailablePort(start, tryBind) {
+  const end = Math.min(start + PORT_SCAN_LIMIT - 1, 65535);
+  for (let port = start; port <= end; port++) {
+    try {
+      return { port: await tryBind(port), moved: port !== start };
+    } catch (err) {
+      if (err.code !== "EADDRINUSE") throw err;
+    }
+  }
+  throw new Error(`no free port between ${start} and ${end} \u2014 free one up or pass --port`);
+}
 var MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -457,7 +472,7 @@ function preflight(log = console.log) {
     process.exit(1);
   }
 }
-function main(argv) {
+async function main(argv) {
   preflight();
   let args;
   try {
@@ -479,20 +494,42 @@ ${USAGE}` : err);
     const res = staticResponse(clientDir, new URL(c.req.url).pathname);
     return res ?? c.notFound();
   });
-  serve({ fetch: app.fetch, port: args.port, hostname: "127.0.0.1" }, () => {
-    const source = detectCredentialSource();
-    console.log(`coopcli specsketch`);
-    console.log(`  workspace: ${workspace.dir}`);
-    console.log(`  open:      http://127.0.0.1:${args.port}`);
-    if (source) {
-      console.log(`  auth:      ${source}`);
-    } else {
-      console.log(`
+  const tryBind = (port2) => new Promise((bound, failed) => {
+    const server = serve(
+      { fetch: app.fetch, port: port2, hostname: "127.0.0.1" },
+      (info) => bound(info.port)
+    );
+    server.once("error", (err) => {
+      try {
+        server.close();
+      } catch {
+      }
+      failed(err);
+    });
+  });
+  let port;
+  let moved;
+  try {
+    ({ port, moved } = await bindAvailablePort(args.port, tryBind));
+  } catch (err) {
+    console.error(`specsketch: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  const source = detectCredentialSource();
+  console.log(`coopcli specsketch`);
+  console.log(`  workspace: ${workspace.dir}`);
+  console.log(`  open:      http://127.0.0.1:${port}`);
+  if (moved) {
+    console.log(`  port:      ${args.port} was in use \u2014 moved to ${port}`);
+  }
+  if (source) {
+    console.log(`  auth:      ${source}`);
+  } else {
+    console.log(`
 \u26A0 ${CREDENTIALS_HINT}
 `);
-    }
-  });
+  }
 }
 
 // server/cli-entry.ts
-main(process.argv.slice(2));
+void main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coopcli/specsketch",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "coopcli specsketch — draw an architecture diagram, generate an OpenSpec change proposal into your openspec/ change directory. Local-only.",
   "type": "module",
   "bin": {