@mulmoclaude/common 1.2.0 → 1.3.0

package/dist/envCoerce.d.ts

@@ -0,0 +1,21 @@
+export interface IntRange {
+    min?: number;
+    max?: number;
+}
+/**
+ * `Number()`-based integer coercion with an optional range, falling back when the
+ * value is absent, empty, non-integer, or out of range.
+ *
+ * `Number()` — not `parseInt` — on purpose: it is what the server has always used,
+ * so `0x1f`, `1e3`, `+3100` and `3100.0` coerce exactly as they did, and a
+ * whitespace-only value coerces to 0. Anything stricter here would silently
+ * disagree with the backend.
+ */
+export declare function asInt(value: string | undefined, fallback: number, opts?: IntRange): number;
+/** The port range the backend accepts, so both sides bound the value identically.
+ *  `min: 0` is deliberate — 0 asks the OS for an ephemeral port.
+ *
+ *  `Required<IntRange>`, not `IntRange`: both bounds are always present here, and
+ *  saying so lets a caller compare against them (`port <= PORT_RANGE.max`) without
+ *  a non-null assertion. Still assignable wherever an `IntRange` is expected. */
+export declare const PORT_RANGE: Required<IntRange>;

package/dist/envCoerce.js

@@ -0,0 +1,36 @@
+// Env-var type coercion for ports and other integer settings.
+//
+// It started inside `server/system/env.ts` (#504-era), moved to
+// `server/utils/envCoerce.ts` when #2650 needed the SAME rule for `yarn dev`'s
+// Vite proxy — the proxy has to resolve `PORT` exactly as the backend does, or
+// the two point at different servers — and moved here when #3084 needed it for
+// the messaging bridges too. A second opinion about "is this a port" is that
+// bug one level down, so there is exactly one copy and every tier imports it.
+/**
+ * `Number()`-based integer coercion with an optional range, falling back when the
+ * value is absent, empty, non-integer, or out of range.
+ *
+ * `Number()` — not `parseInt` — on purpose: it is what the server has always used,
+ * so `0x1f`, `1e3`, `+3100` and `3100.0` coerce exactly as they did, and a
+ * whitespace-only value coerces to 0. Anything stricter here would silently
+ * disagree with the backend.
+ */
+export function asInt(value, fallback, opts = {}) {
+    if (value === undefined || value === "")
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        return fallback;
+    if (opts.min !== undefined && parsed < opts.min)
+        return fallback;
+    if (opts.max !== undefined && parsed > opts.max)
+        return fallback;
+    return parsed;
+}
+/** The port range the backend accepts, so both sides bound the value identically.
+ *  `min: 0` is deliberate — 0 asks the OS for an ephemeral port.
+ *
+ *  `Required<IntRange>`, not `IntRange`: both bounds are always present here, and
+ *  saying so lets a caller compare against them (`port <= PORT_RANGE.max`) without
+ *  a non-null assertion. Still assignable wherever an `IntRange` is expected. */
+export const PORT_RANGE = Object.freeze({ min: 0, max: 65_535 });

package/dist/index.d.ts

@@ -79,3 +79,4 @@ export interface JwtSegments {
 export declare function splitJwtSegments(token: string): JwtSegments | null;
 export { scanEnvOptions, snakeToLowerCamel, type ScanEnvOptionsConfig } from "./envScan.js";
 export type { MinimalLogger, StructuredLogger } from "./logger.js";
+export { asInt, PORT_RANGE, type IntRange } from "./envCoerce.js";

package/dist/index.js

@@ -134,3 +134,4 @@ export function splitJwtSegments(token) {
     return { headerSegment, payloadSegment, signatureSegment };
 }
 export { scanEnvOptions, snakeToLowerCamel } from "./envScan.js";
+export { asInt, PORT_RANGE } from "./envCoerce.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/common",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "General-purpose pure utilities (type guards, etc.) shared across the MulmoClaude host, bridges, and plugins",
   "type": "module",
   "main": "./dist/index.js",