procdeck 0.5.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.",
@@ -45501,7 +45507,11 @@ var resolveSpec = (spec, assigned, internal) => {
     ...spec,
     ...spec.shell === void 0 ? {} : { shell: bind6(spec.shell) },
     ...spec.cmd === void 0 ? {} : { cmd: spec.cmd.map(bind6) },
-    ...spec.env === void 0 ? {} : { env: Object.fromEntries(Object.entries(spec.env).map(([key, value3]) => [key, bind6(value3)])) },
+    ...spec.env === void 0 ? {} : {
+      env: Object.fromEntries(
+        Object.entries(spec.env).map(([key, value3]) => [key, bind6(value3)])
+      )
+    },
     ...spec.url === void 0 ? {} : { url: publicOnly(spec.url) }
   };
 };
@@ -45549,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.
@@ -45582,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({
@@ -46120,7 +46149,7 @@ var selfLogs = (follow) => Effect_exports.gen(function* () {
     }),
     (onChange) => Effect_exports.sync(() => unwatchFile(file6, onChange))
   );
-  yield* Effect_exports.never;
+  return yield* Effect_exports.never;
 }).pipe(Effect_exports.scoped);
 var logsQuery = (options) => Effect_exports.gen(function* () {
   let sinceMs;
@@ -46299,7 +46328,9 @@ var errors2 = Command_exports.make(
     const render = (group2) => {
       const head = `[${group2.proc}] ${group2.count}\xD7 \xB7 last ${ago(group2.lastTs)}${group2.count > 1 ? ` \xB7 first ${ago(group2.firstTs)}` : ""}`;
       const sample = group2.sample.slice(0, SAMPLE_SHOWN).map((line) => `  ${line}`);
-      const more = group2.sample.length > SAMPLE_SHOWN ? [`  \u2026 +${group2.sample.length - SAMPLE_SHOWN} more lines (\`procdeck logs ${group2.proc}\`)`] : [];
+      const more = group2.sample.length > SAMPLE_SHOWN ? [
+        `  \u2026 +${group2.sample.length - SAMPLE_SHOWN} more lines (\`procdeck logs ${group2.proc}\`)`
+      ] : [];
       return [head, ...sample, ...more].join("\n");
     };
     yield* Console_exports.log(groups.map(render).join("\n\n"));
@@ -46317,9 +46348,10 @@ var agents = Command_exports.make(
     const root = path11.dirname(configPath);
     const actions = setupAgents(root);
     yield* Console_exports.log(
-      ["procdeck: introducing the deck to coding agents", ...actions.map((line) => `  ${line}`)].join(
-        "\n"
-      )
+      [
+        "procdeck: introducing the deck to coding agents",
+        ...actions.map((line) => `  ${line}`)
+      ].join("\n")
     );
     yield* Console_exports.log(
       "tip:  `claude mcp add procdeck -- procdeck mcp` adds the MCP tools in every procdeck project at once"
@@ -46334,9 +46366,7 @@ var mcp = Command_exports.make(
   "mcp",
   {
     mutations: Flag_exports.boolean("mutations").pipe(
-      Flag_exports.withDescription(
-        "also expose restart_proc / stop_proc / start_proc (default: read-only)"
-      )
+      Flag_exports.withDescription("also expose restart_proc / stop_proc / start_proc (default: read-only)")
     )
   },
   // The server owns stdout from here on: no Console.log in this branch,
@@ -46782,7 +46812,9 @@ var planInit = (root) => {
     );
   }
   const globs = workspaceGlobs(root);
-  const dirs = [...new Set(globs.filter((g) => !g.startsWith("!")).flatMap((g) => expandGlob(root, g)))];
+  const dirs = [
+    ...new Set(globs.filter((g) => !g.startsWith("!")).flatMap((g) => expandGlob(root, g)))
+  ];
   const fromWorkspaces = [];
   const workspaceNotes = [];
   for (const dir2 of dirs) {
@@ -46812,7 +46844,9 @@ var planInit = (root) => {
   }
   return done4(
     [{ id: "app", shell: "echo 'edit procdeck.config.json'; sleep 1000" }],
-    ["nothing recognisable here (package.json scripts, Procfile, Django/Go/Rust/Rails/compose) \u2014 wrote a template to edit"],
+    [
+      "nothing recognisable here (package.json scripts, Procfile, Django/Go/Rust/Rails/compose) \u2014 wrote a template to edit"
+    ],
     "template"
   );
 };
@@ -47311,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) {
@@ -47325,9 +47365,13 @@ var make63 = Effect_exports.fn("procdeck.supervisor")(function* (loaded) {
     const resolved2 = resolveSpec(spec, assigned, internal);
     runtimes.set(spec.id, {
       spec,
-      resolved: assignedPort === void 0 ? resolved2 : { ...resolved2, env: { PORT: String(internalPort ?? assignedPort), ...resolved2.env } },
+      resolved: assignedPort === void 0 ? resolved2 : (
+        // The PaaS contract: the port to bind also arrives as `PORT`.
+        { ...resolved2, env: { PORT: String(internalPort ?? assignedPort), ...resolved2.env } }
+      ),
       assignedPort,
       internalPort,
+      observerClose: void 0,
       status: { id: spec.id, state: "stopped" },
       proc: void 0,
       ready: Latch_exports.makeUnsafe(false),
@@ -47344,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);
   };
@@ -47385,9 +47424,7 @@ var make63 = Effect_exports.fn("procdeck.supervisor")(function* (loaded) {
       return Stream_exports.concat(
         Stream_exports.fromIterable(backlog),
         Stream_exports.fromSubscription(subscription).pipe(
-          Stream_exports.filter(
-            (event) => event.type !== "log" || event.seq >= (seen.get(event.id) ?? 0)
-          )
+          Stream_exports.filter((event) => event.type !== "log" || event.seq >= (seen.get(event.id) ?? 0))
         )
       );
     })
@@ -47421,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" });
@@ -47496,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));
@@ -47571,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
@@ -47626,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 };
 });
@@ -47840,6 +47915,7 @@ var routes = (supervisor, deck, hooks) => HttpRouter_exports.addAll([
           root: instance.root,
           port: instance.port,
           startedAt: instance.startedAt,
+          version: instance.version,
           self: instance.root === deck.root
         }))
       )
@@ -48078,7 +48154,7 @@ var runServer = (loaded, configPath) => Effect_exports.gen(function* () {
   yield* Effect_exports.log(
     `procdeck ${VERSION} "${loaded.name}" listening on http://localhost:${port}${host === DEFAULT_UI_HOST ? "" : ` (bound to ${host})`} (pid ${process.pid}, ${mode})`
   );
-  yield* Effect_exports.never;
+  return yield* Effect_exports.never;
 }).pipe(Effect_exports.scoped);
 var fgFlag = Flag_exports.boolean("fg").pipe(
   Flag_exports.withDescription("run in the foreground \u2014 Ctrl-C stops the deck")
@@ -48100,6 +48176,7 @@ var upHandler = ({
     yield* Console_exports.log(
       `procdeck: "${running.name}" is already up \u2192 ${deckUrl(running)} (pid ${running.pid})`
     );
+    yield* versionNotice(running);
     if (open5) openBrowser(deckUrl(running));
     return;
   }
@@ -48122,6 +48199,9 @@ var upHandler = ({
   yield* Console_exports.log("  procdeck down \xB7 status \xB7 logs -f \xB7 open");
   if (open5) openBrowser(deckUrl(instance));
 });
+var versionNotice = (instance) => instance.version === VERSION ? Effect_exports.void : Console_exports.log(
+  `procdeck: deck runs v${instance.version}, CLI is v${VERSION} \u2014 \`procdeck restart\` picks up the new version`
+);
 var downHandler = ({ config }) => Effect_exports.gen(function* () {
   const root = yield* resolveRoot(config);
   const instance = findInstance(root);
@@ -48133,7 +48213,11 @@ var downHandler = ({ config }) => Effect_exports.gen(function* () {
   const outcome = yield* Effect_exports.promise(() => shutdown3(instance));
   yield* Console_exports.log(outcome === "stopped" ? "down" : "did not stop in time, killed");
 });
-var up = Command_exports.make("up", { config: configArgument, fg: fgFlag, open: openFlag }, upHandler).pipe(
+var up = Command_exports.make(
+  "up",
+  { config: configArgument, fg: fgFlag, open: openFlag },
+  upHandler
+).pipe(
   Command_exports.withDescription(
     "Start the deck and open its UI. Detaches by default: the deck keeps running after the terminal closes (`procdeck down` stops it). Idempotent \u2014 an already-running deck is just opened."
   )
@@ -48141,6 +48225,34 @@ var up = Command_exports.make("up", { config: configArgument, fg: fgFlag, open:
 var down = Command_exports.make("down", { config: configArgument }, downHandler).pipe(
   Command_exports.withDescription("Stop the deck: every process tree is terminated, then procdeck exits.")
 );
+var restartAllHandler = Effect_exports.gen(function* () {
+  const instances = listInstances();
+  if (instances.length === 0) return yield* Console_exports.log("procdeck: no decks are up");
+  let failures = 0;
+  for (const instance of instances) {
+    if (instance.mode === "foreground") {
+      yield* Console_exports.log(
+        `procdeck: skipping "${instance.name}" (${pretty2(instance.root)}) \u2014 foreground deck, restart it in its own terminal`
+      );
+      continue;
+    }
+    process.stdout.write(`procdeck: restarting "${instance.name}" (${pretty2(instance.root)})\u2026 `);
+    yield* Effect_exports.promise(() => shutdown3(instance));
+    const outcome = yield* Effect_exports.promise(async () => {
+      try {
+        const fresh2 = await detach(process.argv[1], instance.config, instance.root);
+        return `up \u2192 ${deckUrl(fresh2)} (v${fresh2.version})`;
+      } catch (cause) {
+        failures += 1;
+        return `failed: ${cause.message}`;
+      }
+    });
+    yield* Console_exports.log(outcome);
+  }
+  if (failures > 0) {
+    return yield* fail11(`${failures} deck${failures === 1 ? "" : "s"} did not come back \u2014 see above`);
+  }
+});
 var restart = Command_exports.make(
   "restart",
   {
@@ -48148,10 +48260,13 @@ var restart = Command_exports.make(
       Argument_exports.optional,
       Argument_exports.withDescription("proc id \u2014 restart just this process (default: the whole deck)")
     ),
+    all: Flag_exports.boolean("all").pipe(
+      Flag_exports.withDescription("restart every deck on this machine (e.g. after updating procdeck)")
+    ),
     fg: fgFlag,
     open: openFlag
   },
-  ({ fg, open: open5, proc }) => Option_exports.isSome(proc) ? Effect_exports.gen(function* () {
+  ({ all: all4, fg, open: open5, proc }) => all4 ? Option_exports.isSome(proc) ? fail11(`--all restarts every deck \u2014 drop "${proc.value}"`) : restartAllHandler : Option_exports.isSome(proc) ? Effect_exports.gen(function* () {
     const instance = yield* requireInstance(Option_exports.none());
     const procs = yield* callApi(() => apiGet(instance, "/procs"));
     if (!procs.some((info2) => info2.id === proc.value)) {
@@ -48170,7 +48285,7 @@ var restart = Command_exports.make(
   )
 ).pipe(
   Command_exports.withDescription(
-    "Restart one proc (`restart api`), or the whole deck (`restart`) \u2014 the latter after updating procdeck or editing the config."
+    "Restart one proc (`restart api`), the whole deck (`restart`), or every deck on this machine (`restart --all`) \u2014 the deck-wide forms after updating procdeck or editing the config."
   )
 );
 var status = Command_exports.make(
@@ -48192,8 +48307,9 @@ var status = Command_exports.make(
     }
     const procs = yield* fetchProcs2(instance);
     yield* Console_exports.log(
-      `${instance.name} \xB7 ${deckUrl(instance)} \xB7 up ${describeUptime(instance.startedAt)} \xB7 pid ${instance.pid} \xB7 ${countRunning(procs)}${instance.mode === "foreground" ? " \xB7 foreground" : ""}`
+      `${instance.name} \xB7 ${deckUrl(instance)} \xB7 up ${describeUptime(instance.startedAt)} \xB7 pid ${instance.pid} \xB7 ${countRunning(procs)} \xB7 v${instance.version}${instance.mode === "foreground" ? " \xB7 foreground" : ""}`
     );
+    yield* versionNotice(instance);
     if (procs === void 0 || procs.length === 0) return;
     yield* Console_exports.log(
       table2(
@@ -48225,10 +48341,16 @@ var ls = Command_exports.make(
           `:${instance.port}`,
           `up ${describeUptime(instance.startedAt)}`,
           countRunning(procs[i]),
+          `v${instance.version}`,
           pretty2(instance.root)
         ])
       )
     );
+    if (instances.some((instance) => instance.version !== VERSION)) {
+      yield* Console_exports.log(
+        `procdeck: some decks run a different procdeck than the CLI (v${VERSION}) \u2014 \`procdeck restart --all\` brings them over`
+      );
+    }
   })
 ).pipe(Command_exports.withDescription("Every running deck on this machine."));
 var open4 = Command_exports.make(
@@ -48318,12 +48440,7 @@ var NodeLayer = layer2.pipe(
       layer5,
       layer6,
       CliConfig_exports.layer({
-        builtIns: [
-          GlobalFlag_exports.Help,
-          GlobalFlag_exports.Version,
-          GlobalFlag_exports.Completions,
-          GlobalFlag_exports.LogLevel
-        ]
+        builtIns: [GlobalFlag_exports.Help, GlobalFlag_exports.Version, GlobalFlag_exports.Completions, GlobalFlag_exports.LogLevel]
       })
     )
   )
@@ -48333,9 +48450,11 @@ procdeck.pipe(
   Effect_exports.catchTag(
     "CliFailure",
     (failure) => Console_exports.error(`procdeck: ${failure.message}`).pipe(
-      Effect_exports.andThen(Effect_exports.sync(() => {
-        process.exitCode = failure.code ?? 1;
-      }))
+      Effect_exports.andThen(
+        Effect_exports.sync(() => {
+          process.exitCode = failure.code ?? 1;
+        })
+      )
     )
   ),
   Effect_exports.provide(NodeLayer),

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": "0.5.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",
@@ -24,18 +24,15 @@
     "url": "https://github.com/kondaurovDev/procdeck",
     "directory": "packages/procdeck"
   },
-  "type": "module",
-  "engines": {
-    "node": ">=22"
+  "bin": {
+    "procdeck": "./dist/cli.js"
   },
   "files": [
     "dist",
     "schema.json",
     "ui/dist"
   ],
-  "bin": {
-    "procdeck": "./dist/cli.js"
-  },
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/public.d.ts",
@@ -63,6 +60,9 @@
     "vite": "^6.2.0",
     "vitest": "^3.2.4"
   },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "ui:dev": "vite ui",
     "build": "pnpm run build:meta && pnpm run build:schema && pnpm run build:ui && pnpm run build:js && pnpm run build:types",