procdeck 1.0.0 → 1.1.0

package/dist/cli.js

@@ -45446,6 +45446,12 @@ var ProcSpecSchema = Schema_exports.Struct({
       examples: ["http://localhost:${port}"]
     })
   ),
+  port: Schema_exports.optionalKey(
+    Schema_exports.Number.annotate({
+      description: "Pin this proc's assigned `${port}` to a fixed public number instead of a random free one \u2014 dependents outside the deck (dotenv files, mobile simulators, teammates' scripts) keep their hardcoded addresses, and an observed proc still binds a hidden internal port behind the HTTP observer. Requires `${port}` somewhere in the spec.",
+      examples: [8787]
+    }).pipe(Schema_exports.check(Schema_exports.isInt(), Schema_exports.isBetween({ minimum: 1, maximum: 65535 })))
+  ),
   needs: Schema_exports.optionalKey(
     Schema_exports.Array(Schema_exports.String).annotate({
       description: "Ids of procs that must be ready before this one spawns. Declarative: readiness is auto-detected, no port numbers in the config.",
@@ -45553,6 +45559,25 @@ var validatePortTemplates = (procs) => {
   }
   return void 0;
 };
+var validatePinnedPorts = (config) => {
+  const uiPort = config.port ?? DEFAULT_UI_PORT;
+  const holders = /* @__PURE__ */ new Map();
+  for (const proc of config.procs) {
+    if (proc.port === void 0) continue;
+    if (!usesOwnPort(proc)) {
+      return `proc "${proc.id}" pins port ${proc.port} but does not use \${port} \u2014 the pin is the public side of an assigned port`;
+    }
+    if (proc.port === uiPort) {
+      return `proc "${proc.id}" pins port ${proc.port}, which is the deck UI's own port`;
+    }
+    const holder = holders.get(proc.port);
+    if (holder !== void 0) {
+      return `procs "${holder}" and "${proc.id}" pin the same port ${proc.port}`;
+    }
+    holders.set(proc.port, proc.id);
+  }
+  return void 0;
+};
 var ProcdeckConfigSchema = Schema_exports.Struct({
   // JSON configs point at the published schema for editor completion; the key
   // is meaningless at runtime but must be accepted, because Struct is exact.
@@ -45586,7 +45611,7 @@ var ProcdeckConfigSchema = Schema_exports.Struct({
 }).pipe(
   Schema_exports.check(
     Schema_exports.makeFilter(
-      (config) => validateGraph(config.procs) ?? validatePortTemplates(config.procs)
+      (config) => validateGraph(config.procs) ?? validatePortTemplates(config.procs) ?? validatePinnedPorts(config)
     )
   )
 ).annotate({
@@ -47320,12 +47345,18 @@ var make63 = Effect_exports.fn("procdeck.supervisor")(function* (loaded) {
   const live = yield* PubSub_exports.sliding({ capacity: LIVE_BUFFER });
   const wantsPort = loaded.config.procs.filter(usesOwnPort);
   const observedSpecs = wantsPort.filter((spec) => spec.observe !== false);
+  const unpinned = wantsPort.filter((spec) => spec.port === void 0);
   const freePorts = yield* Effect_exports.promise(
-    () => findFreePorts(wantsPort.length + observedSpecs.length)
+    () => findFreePorts(unpinned.length + observedSpecs.length)
   );
-  const assigned = new Map(wantsPort.map((spec, index2) => [spec.id, freePorts[index2]]));
+  const assigned = new Map([
+    ...wantsPort.flatMap(
+      (spec) => spec.port === void 0 ? [] : [[spec.id, spec.port]]
+    ),
+    ...unpinned.map((spec, index2) => [spec.id, freePorts[index2]])
+  ]);
   const internal = new Map(
-    observedSpecs.map((spec, index2) => [spec.id, freePorts[wantsPort.length + index2]])
+    observedSpecs.map((spec, index2) => [spec.id, freePorts[unpinned.length + index2]])
   );
   const runtimes = /* @__PURE__ */ new Map();
   for (const spec of loaded.config.procs) {
@@ -47340,6 +47371,7 @@ var make63 = Effect_exports.fn("procdeck.supervisor")(function* (loaded) {
       ),
       assignedPort,
       internalPort,
+      observerClose: void 0,
       status: { id: spec.id, state: "stopped" },
       proc: void 0,
       ready: Latch_exports.makeUnsafe(false),
@@ -47356,19 +47388,14 @@ var make63 = Effect_exports.fn("procdeck.supervisor")(function* (loaded) {
       rows: DEFAULT_ROWS
     });
   }
-  for (const [id2, internalPort] of internal) {
-    const runtime = runtimes.get(id2);
-    yield* Effect_exports.acquireRelease(
-      Effect_exports.promise(
-        () => startObserver({
-          publicPort: assigned.get(id2),
-          internalPort,
-          record: (capture) => runtime.http.record(capture)
-        })
-      ),
-      (close4) => Effect_exports.promise(close4)
-    );
-  }
+  yield* Effect_exports.acquireRelease(
+    Effect_exports.void,
+    () => Effect_exports.promise(
+      () => Promise.all(
+        [...runtimes.values()].map((runtime) => runtime.observerClose?.() ?? Promise.resolve())
+      ).then(() => void 0)
+    )
+  );
   const emit = (event) => {
     PubSub_exports.publishUnsafe(live, event);
   };
@@ -47431,6 +47458,28 @@ var make63 = Effect_exports.fn("procdeck.supervisor")(function* (loaded) {
       }
     }
   };
+  const bindObserver = (runtime) => startObserver({
+    publicPort: runtime.assignedPort,
+    internalPort: runtime.internalPort,
+    record: (capture) => runtime.http.record(capture)
+  }).then(
+    (close4) => {
+      runtime.observerClose = close4;
+      return true;
+    },
+    () => false
+  );
+  const parkOnTakenPort = (runtime) => {
+    const hint = `free :${runtime.assignedPort} (is "${runtime.spec.id}" already running outside procdeck?), then Start`;
+    say(
+      runtime,
+      `\r
+procdeck: pinned port :${runtime.assignedPort} is taken \u2014 cannot observe "${runtime.spec.id}"\r
+procdeck: hint: ${hint}\r
+`
+    );
+    setStatus2(runtime, { id: runtime.spec.id, state: "blocked", hint });
+  };
   const startSync = (runtime) => {
     if (runtime.proc !== void 0) return;
     setStatus2(runtime, { id: runtime.spec.id, state: "starting" });
@@ -47506,6 +47555,13 @@ ${lines2.join("\r\n")}\r
   const start = Effect_exports.fn("procdeck.start")(function* (id2) {
     const runtime = require_(id2);
     if (runtime.proc !== void 0 || runtime.waiter !== void 0) return;
+    if (runtime.internalPort !== void 0 && runtime.observerClose === void 0) {
+      const bound = yield* Effect_exports.promise(() => bindObserver(runtime));
+      if (!bound) {
+        parkOnTakenPort(runtime);
+        return;
+      }
+    }
     const needs = runtime.spec.needs ?? [];
     if (needs.length === 0 && runtime.spec.preflight === void 0) {
       return yield* Effect_exports.sync(() => startSync(runtime));
@@ -47581,7 +47637,9 @@ ${lines2.join("\r\n")}\r
     list: () => [...runtimes.values()].map((runtime) => ({
       id: runtime.spec.id,
       command: describeCommand(runtime.resolved),
-      ...runtime.resolved.url === void 0 ? {} : { url: runtime.resolved.url },
+      // A pinned proc has a stable public address even with no `url` in
+      // the config — derive the link instead of making the user repeat it.
+      ...runtime.resolved.url !== void 0 ? { url: runtime.resolved.url } : runtime.spec.port === void 0 ? {} : { url: `http://localhost:${runtime.spec.port}` },
       ...runtime.assignedPort === void 0 ? {} : { assignedPort: runtime.assignedPort },
       proxyUrl: `http://${runtime.spec.id}.localhost:${uiPort}`,
       status: runtime.status
@@ -47636,7 +47694,14 @@ ${lines2.join("\r\n")}\r
     discard: true
   });
   for (const runtime of runtimes.values()) {
-    if (runtime.spec.autostart !== false) yield* start(runtime.spec.id);
+    if (runtime.internalPort === void 0) continue;
+    const bound = yield* Effect_exports.promise(() => bindObserver(runtime));
+    if (!bound) parkOnTakenPort(runtime);
+  }
+  for (const runtime of runtimes.values()) {
+    if (runtime.spec.autostart !== false && runtime.status.state !== "blocked") {
+      yield* start(runtime.spec.id);
+    }
   }
   return { supervisor, stopAll };
 });

package/dist/public.d.ts

@@ -42,6 +42,13 @@ export type ProcSpec = {
     readonly autostart?: boolean;
     /** URL this process serves, shown in the UI as a link. */
     readonly url?: string;
+    /**
+     * Pin this proc's assigned `${port}` to a fixed public number instead of a
+     * random free one — dependents outside the deck keep their hardcoded
+     * addresses, and an observed proc still binds a hidden internal port.
+     * Requires `${port}` somewhere in the spec.
+     */
+    readonly port?: number;
     /** Ids of procs that must be ready before this one spawns. */
     readonly needs?: ReadonlyArray<string>;
     /** What "ready" means for dependents. Defaults to "listening". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procdeck",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Interactive dev-process multiplexer with a web UI: terminal panes in a browser tab, declarative dependencies, assigned ports and a *.localhost reverse proxy.",
   "keywords": [
     "cli",

package/readme.md

@@ -52,7 +52,9 @@ pnpm add -D procdeck      # npm i -D procdeck · bun add -d procdeck
 - **Ports that never collide.** Write `${port}` in a command, env value or url
   and procdeck assigns a free port before spawning. `${port:api}` is another
   proc's port, so dependents get wired — `API_URL=http://localhost:${port:api}`
-  — with no hardcoded numbers anywhere.
+  — with no hardcoded numbers anywhere. And when the world already knows the
+  address, `port: 8787` pins the public side to that exact number — dotenv
+  files and simulators keep working, the observer stays in front.
 - **A memorable address for each service.** `api.localhost:4820`,
   `web.localhost:4820` — whatever port the process actually got. Browsers
   resolve `*.localhost` themselves, so there is zero system setup, and

package/schema.json

@@ -118,6 +118,19 @@
               "http://localhost:${port}"
             ]
           },
+          "port": {
+            "description": "Pin this proc's assigned `${port}` to a fixed public number instead of a random free one — dependents outside the deck (dotenv files, mobile simulators, teammates' scripts) keep their hardcoded addresses, and an observed proc still binds a hidden internal port behind the HTTP observer. Requires `${port}` somewhere in the spec.",
+            "examples": [
+              8787
+            ],
+            "type": "integer",
+            "allOf": [
+              {
+                "minimum": 1,
+                "maximum": 65535
+              }
+            ]
+          },
           "needs": {
             "type": "array",
             "items": {