@kaynooo/stack-tools 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaynooo <kaynooo@kevyn.fr>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# stack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Two stack helpers for Claude Code: a stable port per service name, and an audit of a compose release setup against its `release.config.ts`.
+
+```sh
+bun install -g @kaynooo/stack-tools
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `stack port <name>` | prints the port the name always hashes to (FNV-1a, 1024-65535), so a service keeps the same port on every machine |
+| `stack audit [dir]` | cross-checks `release.config.ts` in `dir` (the current directory) against the compose files it syncs |
+
+`stack port` takes `--min` and `--max` to change the range. When something on this machine already listens on the port it says so on stderr; the number is still printed and the exit code stays 0.
+
+## Audit
+
+The checks, in the order they are reported:
+
+- `sync` and `build`: every `deploySyncFiles` entry, `sourceDir`, `buildContext`, `dockerfile` and buildSecret `src` (a leading `~` is the home directory) exists, and a buildSecret `env` is set in the shell.
+- `compose`: `docker compose config` succeeds on the base file and on each overlay merged over it. The base is the shortest compose file name among `deploySyncFiles`.
+- `env`: every `${VAR}` without a default is in `requiredServerEnv`, and every listed key is referenced.
+- `version`: each `versionEnv` is interpolated by a compose file, and each `*_VERSION` a compose file interpolates is declared by a release.
+- `image`, `restart` and `post-deploy`: services the config names exist, and registry images are built by a release.
+- `health` and `routing`: restarted services have a healthcheck, ports and traefik labels live in overlays, and `composeArgs` does not drop them.
+- `layout`, `nuxt` and `gitignore`: bind mounts appear in the base file's header, `NUXT_*` variables match the runtime config, and `.release-logs` and `.release-worktrees` are ignored.
+
+Exit codes: 0 no error (warnings allowed), 1 at least one error, 2 no `release.config.ts`. `--json` prints `{ root, composeFiles, findings }` where a finding is `{ level, check, message }`.
+
+It needs docker for `docker compose config`. When the package `release.config.ts` imports `defineConfig` from is not installed, a stand-in that returns its argument is used.

package/dist/cli.js

@@ -0,0 +1,976 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/cli.ts
+import process7 from "process";
+
+// ../kit/src/args.ts
+import process2 from "process";
+import { parseArgs } from "util";
+
+// ../kit/src/style.ts
+import process from "process";
+
+// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-mtetydvc.js
+function x(s) {
+  let r = s.startsWith("#") ? s.slice(1).toLowerCase() : s.toLowerCase();
+  if (!/^[a-f0-9]+$/.test(r))
+    return [0, 0, 0];
+  let t = r.length, n = (c) => Number.parseInt(c, 16);
+  if (t === 3 || t === 4) {
+    let c = n(r[0] + r[0]), u = n(r[1] + r[1]), h = n(r[2] + r[2]), g = t === 4 ? n(r[3] + r[3]) : undefined;
+    return g !== undefined ? [c, u, h, g] : [c, u, h];
+  }
+  if (t !== 6 && t !== 8)
+    throw Error(`Invalid hex color length: ${t}`);
+  let a = n(r.slice(0, 2)), b = n(r.slice(2, 4)), o = n(r.slice(4, 6)), y = t === 8 ? n(r.slice(6, 8)) : undefined;
+  if ([a, b, o].some(Number.isNaN) || y !== undefined && Number.isNaN(y))
+    throw Error(`Invalid hex color value: ${s}`);
+  return y !== undefined ? [a, b, o, y] : [a, b, o];
+}
+function A(s) {
+  let [r, t, n, a] = s;
+  if (a)
+    return `#${(r << 24 | t << 16 | n << 8 | Math.round((a ?? 1) * 255)).toString(16).padStart(8, "0").toUpperCase()}`;
+  return `#${(r << 16 | t << 8 | n).toString(16).padStart(6, "0").toUpperCase()}`;
+}
+function R(s, r, t) {
+  s = (s % 360 + 360) % 360, t /= 100;
+  let n = r * Math.min(t, 1 - t) / 100, a = (b) => {
+    let o = (b + s / 30) % 12, y = t - n * Math.max(Math.min(o - 3, 9 - o, 1), -1);
+    return Math.round(255 * y);
+  };
+  return [a(0), a(8), a(4)];
+}
+function k(s) {
+  let [r, t, n] = s;
+  r /= 255, t /= 255, n /= 255;
+  let a = Math.max(r, t, n), b = Math.min(r, t, n), o = 0, y = 0, c = (a + b) / 2;
+  if (a !== b) {
+    let u = a - b;
+    if (y = c > 0 && c < 1 ? u / (1 - Math.abs(2 * c - 1)) : 0, a === r)
+      o = (t - n) / u + (t < n ? 6 : 0);
+    else if (a === t)
+      o = (n - r) / u + 2;
+    else
+      o = (r - t) / u + 4;
+    o /= 6;
+  }
+  return [Math.round(o * 360), Math.round(y * 100), Math.round(c * 100)];
+}
+function H(s, r, t) {
+  s = (s % 360 + 360) % 360, r /= 100, t /= 100;
+  let n = (a) => {
+    let b = (a + s / 60) % 6, o = t - t * r * Math.max(Math.min(b, 4 - b, 1), 0);
+    return Math.round(255 * o);
+  };
+  return [n(5), n(3), n(1)];
+}
+function f(s) {
+  let [r, t, n] = s;
+  r /= 255, t /= 255, n /= 255;
+  let a = Math.max(r, t, n), b = Math.min(r, t, n), o = a - b, y = 0, c = a === 0 ? 0 : o / a, u = a;
+  if (o !== 0) {
+    if (a === r)
+      y = (t - n) / o + (t < n ? 6 : 0);
+    else if (a === t)
+      y = (n - r) / o + 2;
+    else
+      y = (r - t) / o + 4;
+    y /= 6;
+  }
+  return [Math.round(y * 360), Math.round(c * 100), Math.round(u * 100)];
+}
+function O(s) {
+  let r = s[0] / 255, t = s[1] / 255, n = s[2] / 255, a = 1 - Math.max(r, t, n);
+  if (a === 1)
+    return [0, 0, 0, 100];
+  let b = (1 - r - a) / (1 - a), o = (1 - t - a) / (1 - a), y = (1 - n - a) / (1 - a);
+  return [Math.round(b * 100), Math.round(o * 100), Math.round(y * 100), Math.round(a * 100)];
+}
+function v(s, r, t, n) {
+  return s /= 100, r /= 100, t /= 100, n /= 100, [Math.round(255 * (1 - s) * (1 - n)), Math.round(255 * (1 - r) * (1 - n)), Math.round(255 * (1 - t) * (1 - n))];
+}
+var m = (s) => s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+var p = (s) => s <= 0.0031308 ? 12.92 * s : 1.055 * s ** 0.4166666666666667 - 0.055;
+var i = (s, r) => Math.round(s * 10 ** r) / 10 ** r;
+function T(s) {
+  let r = m(s[0] / 255), t = m(s[1] / 255), n = m(s[2] / 255), a = Math.cbrt(0.4122214708 * r + 0.5363325363 * t + 0.0514459929 * n), b = Math.cbrt(0.2119034982 * r + 0.6806995451 * t + 0.1073969566 * n), o = Math.cbrt(0.0883024619 * r + 0.2817188376 * t + 0.6299787005 * n);
+  return [i(0.2104542553 * a + 0.793617785 * b - 0.0040720468 * o, 4), i(1.9779984951 * a - 2.428592205 * b + 0.4505937099 * o, 4), i(0.0259040371 * a + 0.7827717662 * b - 0.808675766 * o, 4)];
+}
+function M(s, r, t) {
+  let n = (s + 0.3963377774 * r + 0.2158037573 * t) ** 3, a = (s - 0.1055613458 * r - 0.0638541728 * t) ** 3, b = (s - 0.0894841775 * r - 1.291485548 * t) ** 3, o = p(4.0767416621 * n - 3.3077115913 * a + 0.2309699292 * b), y = p(-1.2684380046 * n + 2.6097574011 * a - 0.3413193965 * b), c = p(-0.0041960863 * n - 0.7034186147 * a + 1.707614701 * b), u = (h) => Math.min(255, Math.max(0, Math.round(h * 255)));
+  return [u(o), u(y), u(c)];
+}
+function d(s) {
+  let [r, t, n] = T(s), a = Math.sqrt(t * t + n * n), b = (Math.atan2(n, t) * 180 / Math.PI + 360) % 360;
+  return [i(r, 4), i(a, 4), i(b, 2)];
+}
+function C(s, r, t) {
+  let n = t * Math.PI / 180;
+  return M(s, r * Math.cos(n), r * Math.sin(n));
+}
+function l(s) {
+  let r = s / 255;
+  return r <= 0.03928 ? r / 12.92 : ((r + 0.055) / 1.055) ** 2.4;
+}
+
+class e {
+  r;
+  g;
+  b;
+  a;
+  constructor(s, r, t, n = 1) {
+    this.r = s, this.g = r, this.b = t, this.a = n;
+  }
+  static from(s, r) {
+    if (s === "hex") {
+      let [t, n, a, b] = x(r);
+      return new e(t, n, a, b);
+    }
+    if (s === "rgb") {
+      if (Array.isArray(r)) {
+        let [o, y, c, u] = r;
+        return new e(o, y, c, u);
+      }
+      let { r: t, g: n, b: a, a: b } = r;
+      return new e(t, n, a, b);
+    }
+    if (s === "hsl") {
+      let t, n, a, b;
+      if (Array.isArray(r))
+        [t, n, a, b] = r;
+      else
+        ({ h: t, s: n, l: a, a: b } = r);
+      let [o, y, c] = R(t, n, a);
+      return new e(o, y, c, b);
+    }
+    if (s === "hsv") {
+      let t, n, a, b;
+      if (Array.isArray(r))
+        [t, n, a, b] = r;
+      else
+        ({ h: t, s: n, v: a, a: b } = r);
+      let [o, y, c] = H(t, n, a);
+      return new e(o, y, c, b);
+    }
+    if (s === "cmyk") {
+      let t, n, a, b, o;
+      if (Array.isArray(r))
+        [t, n, a, b, o] = r;
+      else
+        ({ c: t, m: n, y: a, k: b, a: o } = r);
+      let [y, c, u] = v(t, n, a, b);
+      return new e(y, c, u, o);
+    }
+    if (s === "oklch") {
+      let t, n, a, b;
+      if (Array.isArray(r))
+        [t, n, a, b] = r;
+      else
+        ({ l: t, c: n, h: a, a: b } = r);
+      let [o, y, c] = C(t, n, a);
+      return new e(o, y, c, b);
+    }
+    if (s === "oklab") {
+      let t, n, a, b;
+      if (Array.isArray(r))
+        [t, n, a, b] = r;
+      else
+        ({ l: t, a: n, b: a, alpha: b } = r);
+      let [o, y, c] = M(t, n, a);
+      return new e(o, y, c, b);
+    }
+    throw Error("Invalid input");
+  }
+  to(s) {
+    switch (s) {
+      case "rgb":
+        return [this.r, this.g, this.b];
+      case "rgba":
+        return [this.r, this.g, this.b, this.a];
+      case "hex":
+        return A([this.r, this.g, this.b]);
+      case "hexa":
+        return A([this.r, this.g, this.b, this.a]);
+      case "hsl":
+        return k([this.r, this.g, this.b]);
+      case "hsla":
+        return [...k([this.r, this.g, this.b]), this.a];
+      case "hsv":
+        return f([this.r, this.g, this.b]);
+      case "hsva":
+        return [...f([this.r, this.g, this.b]), this.a];
+      case "cmyk":
+        return O([this.r, this.g, this.b]);
+      case "cmyka":
+        return [...O([this.r, this.g, this.b]), this.a];
+      case "oklch":
+        return d([this.r, this.g, this.b]);
+      case "oklcha":
+        return [...d([this.r, this.g, this.b]), this.a];
+      case "oklab":
+        return T([this.r, this.g, this.b]);
+      case "oklaba":
+        return [...T([this.r, this.g, this.b]), this.a];
+      default:
+        return [this.r, this.g, this.b];
+    }
+  }
+  getLuminance() {
+    let s = l(this.r), r = l(this.g), t = l(this.b);
+    return 0.2126 * s + 0.7152 * r + 0.0722 * t;
+  }
+  contrastRatio(s) {
+    let r = this.getLuminance(), t = s.getLuminance(), [n, a] = r >= t ? [r, t] : [t, r];
+    return (n + 0.05) / (a + 0.05);
+  }
+  bestContrastForeground() {
+    let s = new e(255, 255, 255, 1), r = new e(0, 0, 0, 1), t = this.contrastRatio(s), n = this.contrastRatio(r);
+    return t >= n ? s : r;
+  }
+}
+
+// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-y1msbssb.js
+var r = 39;
+var o = 49;
+var f2 = "\x1B[";
+var C2 = { reset: [0, 0], bold: [1, 22], dim: [2, 22], italic: [3, 23], underline: [4, 24], inverse: [7, 27], hidden: [8, 28], strikethrough: [9, 29], black: [30, r], red: [31, r], green: [32, r], yellow: [33, r], blue: [34, r], magenta: [35, r], cyan: [36, r], white: [37, r], gray: [90, r], grey: [90, r], blackBright: [90, r], redBright: [91, r], greenBright: [92, r], yellowBright: [93, r], blueBright: [94, r], magentaBright: [95, r], cyanBright: [96, r], whiteBright: [97, r], bgBlack: [40, o], bgRed: [41, o], bgGreen: [42, o], bgYellow: [43, o], bgBlue: [44, o], bgMagenta: [45, o], bgCyan: [46, o], bgWhite: [47, o], bgBlackBright: [100, o], bgRedBright: [101, o], bgGreenBright: [102, o], bgYellowBright: [103, o], bgBlueBright: [104, o], bgMagentaBright: [105, o], bgCyanBright: [106, o], bgWhiteBright: [107, o], rgb: (i, n, a, l = "fg") => [`${l === "fg" ? 38 : 48};2;${i};${n};${a}`, l === "fg" ? r : o], hex: (i, n = "fg") => {
+  let [a, l, s] = e.from("hex", i).to("rgb");
+  return [`${n === "fg" ? 38 : 48};2;${a};${l};${s}`, n === "fg" ? r : o];
+}, ansi256: (i, n = "fg") => [`${n === "fg" ? 38 : 48};5;${i}`, n === "fg" ? r : o] };
+var b = new Set(["", "1", "2", "3", "true"]);
+function h(i, n = globalThis.process?.env ?? {}) {
+  if (n.FORCE_COLOR !== undefined)
+    return b.has(n.FORCE_COLOR);
+  if (n.NO_COLOR !== undefined || n.NODE_DISABLE_COLORS !== undefined || n.TERM === "dumb")
+    return false;
+  return i?.isTTY === true;
+}
+function d2(i, n, a) {
+  if (!h(a.stream ?? globalThis.process?.stdout, a.env))
+    return n;
+  let l = "", s = "";
+  for (let g = 0, y = i.length;g < y; g++) {
+    let [c, p] = i[g];
+    l += `${f2}${c}m`, s = `${f2}${p}m${s}`;
+  }
+  return l + n + s;
+}
+function u(i, n = []) {
+  return new Proxy((l) => d2(n, l, i), { get(l, s) {
+    let g = C2[s];
+    if (Array.isArray(g))
+      return u(i, [...n, g]);
+    if (typeof g === "function")
+      return (...y) => u(i, [...n, g(...y)]);
+    throw Error(`Unknown style: ${String(s)}`);
+  } });
+}
+function le(i = {}) {
+  return u(i);
+}
+var t = le();
+
+// ../kit/src/style.ts
+function takesControlCodes(stream, env = process.env) {
+  return stream.isTTY === true && env.NO_COLOR === undefined && env.NODE_DISABLE_COLORS === undefined && env.TERM !== "dumb";
+}
+function paint(stream, env = process.env) {
+  return le({ stream: { isTTY: takesControlCodes(stream, env) }, env });
+}
+var STATUSES = {
+  passed: { symbol: "\u2713", words: ["passed", "success", "succeeded", "ok"], paint: (colors) => colors.green },
+  failed: { symbol: "\u2717", words: ["failed", "failure", "error", "errored"], paint: (colors) => colors.red },
+  running: { symbol: "\u25CF", words: ["running", "in_progress", "started"], paint: (colors) => colors.cyan },
+  queued: { symbol: "\u25CB", words: ["queued", "waiting", "pending", "created", "blocked", "scheduled"], paint: (colors) => colors.yellow },
+  skipped: { symbol: "-", words: ["skipped", "cancelled", "canceled", "manual"], paint: (colors) => colors.dim }
+};
+var STATUS_OF = new Map(Object.entries(STATUSES).flatMap(([status, { words }]) => words.map((word) => [word, status])));
+
+// ../kit/src/format.ts
+function upTo(text, separator) {
+  const end = text.indexOf(separator);
+  return end === -1 ? text : text.slice(0, end);
+}
+var ESCAPE = String.fromCharCode(27);
+function printJson(value) {
+  console.log(JSON.stringify(value, undefined, 2));
+}
+
+// ../kit/src/args.ts
+function jsonOption(holds) {
+  return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
+}
+
+class Exit extends Error {
+  code;
+  hint;
+  constructor(message, code, hint) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+  }
+}
+function fail(message, code = 2, hint) {
+  throw new Exit(message, code, hint);
+}
+
+class UsageError extends Exit {
+  constructor(message) {
+    super(message, 2);
+  }
+}
+function badUsage(message) {
+  throw new UsageError(message);
+}
+
+class HelpShown extends Exit {
+  constructor() {
+    super("help shown", 0);
+  }
+}
+
+class Completing {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+}
+var completion = { active: false };
+var OPTIONAL = /\[[^\]]+\]/g;
+var USAGE_PREFIX = /^usage:\s*/i;
+function usageLine(usage, colors = paint(process2.stdout)) {
+  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
+}
+function helpText(usage, options, colors = paint(process2.stdout)) {
+  return [usageLine(usage, colors), "", colors.bold("Options:"), ...optionRows(options, colors)].join(`
+`);
+}
+function optionRows(options, colors = paint(process2.stdout)) {
+  const rows = Object.entries(options).map(([name, option]) => {
+    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
+    const value = option.type === "string" ? ` ${colors.dim("<value>")}` : "";
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? " <value>".length : 0), description: option.description };
+  });
+  const width = Math.max(0, ...rows.map((row) => row.width));
+  return rows.map((row) => `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+}
+function parse(args, usage, options, settings = {}) {
+  const all = { ...options, help: { type: "boolean", short: "h", description: "show this help" } };
+  if (completion.active)
+    throw new Completing(all);
+  const separator = settings.rest === true ? args.indexOf("--") : -1;
+  const own = separator === -1 ? args : args.slice(0, separator);
+  const rest = separator === -1 ? undefined : args.slice(separator + 1);
+  let parsed;
+  try {
+    parsed = parseArgs({ args: own, options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
+  } catch (error) {
+    badUsage(parseError(error));
+  }
+  if (parsed.values.help === true) {
+    console.log(helpText(usage, all));
+    throw new HelpShown;
+  }
+  if (settings.positionals !== undefined)
+    checkPositionals(parsed.positionals, settings.positionals);
+  return { ...parsed, positionals: parsed.positionals, rest };
+}
+function checkPositionals(given, names) {
+  const variadic = names.at(-1)?.replace("]", "").endsWith("...") === true;
+  const required = names.filter((name) => !name.startsWith("[")).length;
+  if (given.length < required)
+    badUsage(`missing ${names[given.length]}`);
+  if (!variadic && given.length > names.length)
+    badUsage(`unexpected argument ${given[names.length]}`);
+}
+function parseError(error) {
+  const message = upTo(error instanceof Error ? error.message : String(error), ". ");
+  return `${message.charAt(0).toLowerCase()}${message.slice(1)}`;
+}
+function wholeNumber(value, name, fallback, min = 1) {
+  if (value === undefined)
+    return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min)
+    badUsage(`--${name} takes a whole number from ${min}, not ${value}`);
+  return number;
+}
+// ../kit/src/cli.ts
+import process3 from "process";
+
+// ../kit/src/text.ts
+var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
+function distance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (const [i, left] of [...a].entries()) {
+    const current = [i + 1];
+    for (const [j, right] of [...b].entries())
+      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+
+// ../kit/src/cli.ts
+function closest(name, names) {
+  const started = names.find((known) => known.startsWith(name));
+  if (started !== undefined)
+    return started;
+  const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
+  return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
+}
+async function help({ path, header, commands, defaultCommand }, stream) {
+  const colors = paint(stream);
+  const width = Math.max(...Object.keys(commands).map((name) => name.length));
+  const prefix = path.join(" ");
+  const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
+  const options = fallback !== undefined && "run" in fallback ? await optionsOf(fallback.run) : undefined;
+  return [
+    header(colors),
+    "",
+    usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan("<command>") : `[${colors.cyan("<command>")}]`} [options]`, colors),
+    "",
+    colors.bold("Commands:"),
+    ...Object.entries(commands).map(([name, { summary }]) => `  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`),
+    ...options === undefined || Object.keys(options).length === 0 ? [] : ["", `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim("the command run when none is named")}`, ...optionRows(options, colors)],
+    "",
+    `${colors.dim("Run")} ${prefix} ${colors.cyan("<command>")} --help ${colors.dim("for its options.")}`
+  ].join(`
+`);
+}
+function printError(prefix, message, hint, cause) {
+  const colors = paint(process3.stderr);
+  const styled = takesControlCodes(process3.stderr);
+  const head = styled ? `${colors.red.bold("error")} ${colors.dim(`${prefix}:`)}` : `error: ${prefix}:`;
+  const under = (label, text, tint) => text === undefined ? "" : `
+  ${styled ? tint(label) : `${label}:`} ${text}`;
+  console.error(`${head} ${message}${under("cause", cause, colors.dim)}${under("hint", hint, colors.yellow)}`);
+}
+function reportThrown(prefix, error, redact = (text) => text) {
+  if (error instanceof HelpShown)
+    return 0;
+  const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
+  const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
+  const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
+  printError(prefix, redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
+  return error instanceof Exit ? error.code : 1;
+}
+async function dispatch(level, argv, { version, redact }) {
+  const [name, ...args] = argv;
+  const prefix = level.path.join(" ");
+  if (name === undefined && level.path.length > 1) {
+    console.error(await help(level, process3.stderr));
+    return 2;
+  }
+  if (name === undefined || name === "help" || name === "--help" || name === "-h") {
+    console.log(await help(level, process3.stdout));
+    return 0;
+  }
+  if (level.path.length === 1 && (name === "--version" || name === "-v")) {
+    console.log(version);
+    return 0;
+  }
+  let command = level.commands[level.aliases?.[name] ?? name];
+  let rest = args;
+  if (command === undefined && level.defaultCommand !== undefined) {
+    command = level.commands[level.defaultCommand];
+    rest = argv;
+  }
+  if (command === undefined) {
+    const meant = closest(name, Object.keys(level.commands));
+    printError(prefix, `no command ${name}`, meant === undefined ? `run ${prefix} --help for its commands` : `did you mean ${meant}?`);
+    return 2;
+  }
+  if ("commands" in command) {
+    const { summary } = command;
+    return dispatch({ path: [...level.path, name], header: (colors) => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined }, rest, { version, redact });
+  }
+  try {
+    return await command.run(rest);
+  } catch (error) {
+    return reportThrown(`${prefix} ${name}`, error, redact);
+  }
+}
+var COMPLETE = "__complete";
+var FILES = "__files__";
+async function optionsOf(run) {
+  completion.active = true;
+  try {
+    await run([]);
+  } catch (error) {
+    if (error instanceof Completing)
+      return error.options;
+  } finally {
+    completion.active = false;
+  }
+  return {};
+}
+async function leafCandidates(run, words) {
+  if (!(words.at(-1) ?? "").startsWith("-"))
+    return [FILES];
+  return Object.entries(await optionsOf(run)).map(([name, option]) => `--${name}	${option.description}`);
+}
+async function candidates(commands, aliases, defaultCommand, words) {
+  const [word = "", ...rest] = words;
+  const command = commands[aliases?.[word] ?? word];
+  if (rest.length === 0 && !word.startsWith("-"))
+    return Object.entries(commands).map(([name, { summary }]) => `${name}	${summary}`);
+  if (command === undefined) {
+    const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
+    return fallback !== undefined && "run" in fallback ? leafCandidates(fallback.run, words) : [];
+  }
+  return "commands" in command ? candidates(command.commands, command.aliases, undefined, rest) : leafCandidates(command.run, rest);
+}
+async function printCandidates(found) {
+  for (const line of await found)
+    console.log(line);
+  return 0;
+}
+async function runCli(cli, argv = process3.argv.slice(2)) {
+  if (argv[0] === COMPLETE)
+    return printCandidates(candidates(cli.commands, cli.aliases, cli.defaultCommand, argv.slice(1)));
+  return dispatch({ path: [cli.name], header: (colors) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand }, argv, { version: cli.version, redact: cli.redact });
+}
+// package.json
+var version = "0.1.2";
+
+// src/commands/audit.ts
+import { homedir } from "os";
+import { resolve as resolve2 } from "path";
+import process6 from "process";
+
+// src/audit/compose.ts
+import { join } from "path";
+import process5 from "process";
+var dockerCompose = async (root, files) => {
+  const args = ["docker", "compose", "--project-directory", root, ...files.flatMap((file) => ["-f", join(root, file)]), "config", "--no-interpolate", "--format", "json"];
+  const run = Bun.spawn(args, { stdout: "pipe", stderr: "pipe", env: { ...process5.env, COMPOSE_FILE: "" } });
+  const [out, err, code] = await Promise.all([run.stdout.text(), run.stderr.text(), run.exited]);
+  const last = err.trim().split(`
+`).at(-1) ?? "";
+  if (code !== 0)
+    throw new Error(last !== "" ? last : `exited with ${code}`);
+  return JSON.parse(out);
+};
+
+// src/audit/render.ts
+import { basename } from "path";
+var line = (finding) => `  ${finding.level === "error" ? "x" : "!"} [${finding.check}] ${finding.message}`;
+function errorsOf(result) {
+  return result.findings.filter((finding) => finding.level === "error");
+}
+function render(result) {
+  const errors = errorsOf(result);
+  const warnings = result.findings.filter((finding) => finding.level === "warn");
+  if (result.findings.length === 0)
+    return `ok ${basename(result.root)}: compose ${result.composeFiles.join(", ")} and release.config.ts agree.`;
+  return [
+    ...errors.length > 0 ? ["Errors", ...errors.map(line), ""] : [],
+    ...warnings.length > 0 ? ["Warnings", ...warnings.map(line), ""] : [],
+    `${errors.length} error(s), ${warnings.length} warning(s)`
+  ].join(`
+`);
+}
+
+// src/audit/run.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join4 } from "path";
+
+// src/audit/checks.ts
+import { existsSync, readFileSync } from "fs";
+import { join as join2, resolve } from "path";
+var ENV_REF = /\$\{([A-Z_]\w*)(\s*:?[-?][^}]*)?\}/gi;
+var YAML_FILE = /\.ya?ml$/;
+var LEADING_DOT_SLASH = /^\.\//;
+var SERVICES_KEY = /^services:/m;
+var EXEC_SERVICE = /\{compose\}(?:\s+--\S+)*\s+(?:exec|run)\s+(?:-\S+\s+)*([\w-]+)/;
+var services = (model) => Object.entries(model?.services ?? {});
+function before(text, separator) {
+  const at = text.indexOf(separator);
+  return at < 0 ? text : text.slice(0, at);
+}
+var stripDotSlash = (file) => file.replace(LEADING_DOT_SLASH, "");
+function composeLayout(root, config) {
+  const composeFiles = (config.deploySyncFiles ?? []).map(stripDotSlash).filter((file) => YAML_FILE.test(file) && existsSync(join2(root, file)));
+  const [base] = composeFiles.toSorted((a, b) => a.length - b.length);
+  return { composeFiles, base, overlays: composeFiles.filter((file) => file !== base) };
+}
+function syncFindings(root, config) {
+  return (config.deploySyncFiles ?? []).filter((file) => !existsSync(join2(root, stripDotSlash(file)))).map((file) => ({ level: "error", check: "sync", message: `deploySyncFiles entry does not exist: ${file}` }));
+}
+function buildFindings(root, releases, env, home) {
+  const findings = [];
+  const missing = (release, key) => {
+    const path = release[key];
+    if (path !== undefined && path !== "" && !existsSync(join2(root, path)))
+      findings.push({ level: "error", check: "build", message: `${release.slug}: ${key} does not exist: ${path}` });
+  };
+  for (const release of releases) {
+    missing(release, "sourceDir");
+    missing(release, "buildContext");
+    missing(release, "dockerfile");
+    for (const secret of release.buildSecrets ?? []) {
+      if (secret.src !== undefined && secret.src !== "") {
+        const path = secret.src.startsWith("~") ? join2(home, secret.src.slice(1)) : resolve(root, secret.src);
+        if (!existsSync(path))
+          findings.push({ level: "error", check: "build", message: `${release.slug}: buildSecret "${secret.id}" src does not exist: ${secret.src}` });
+      }
+      if (secret.env !== undefined && secret.env !== "" && (env[secret.env] ?? "") === "")
+        findings.push({ level: "warn", check: "build", message: `${release.slug}: buildSecret "${secret.id}" reads $${secret.env}, unset in this shell` });
+    }
+  }
+  return findings;
+}
+function envRefs(root, composeFiles) {
+  return composeFiles.flatMap((file) => [...readFileSync(join2(root, file), "utf8").matchAll(ENV_REF)].map((match) => ({ name: match[1], defaulted: Boolean(match[2]), file })));
+}
+function envFindings(refs, required) {
+  const findings = [];
+  const level = required.length > 0 ? "error" : "warn";
+  for (const name of new Set(refs.filter((ref) => !ref.defaulted).map((ref) => ref.name))) {
+    if (!name.endsWith("_VERSION") && !required.includes(name))
+      findings.push({ level, check: "env", message: `\${${name}} has no default in ${refs.find((ref) => ref.name === name)?.file} and is not in requiredServerEnv` });
+  }
+  for (const name of required) {
+    if (!refs.some((ref) => ref.name === name))
+      findings.push({ level: "warn", check: "env", message: `requiredServerEnv lists ${name}, which no compose file references` });
+  }
+  return findings;
+}
+function versionFindings(refs, releases) {
+  const findings = [];
+  const inCompose = new Set(refs.filter((ref) => ref.name.endsWith("_VERSION")).map((ref) => ref.name));
+  const inConfig = new Set(releases.map((release) => release.versionEnv).filter((name) => typeof name === "string" && name !== ""));
+  for (const name of inConfig) {
+    if (!inCompose.has(name))
+      findings.push({ level: "error", check: "version", message: `versionEnv ${name} is never interpolated by a compose file` });
+  }
+  for (const name of inCompose) {
+    if (!inConfig.has(name))
+      findings.push({ level: "error", check: "version", message: `compose interpolates \${${name}}, which no release declares as versionEnv` });
+  }
+  return findings;
+}
+function imageFindings(config, releases, model) {
+  const registry = config.registry ?? "";
+  if (registry === "")
+    return [];
+  const declared = new Set(releases.filter((release) => release.image !== undefined && release.image !== "").map((release) => `${registry}/${release.image}`));
+  const findings = [];
+  for (const [name, service] of services(model)) {
+    const repo = service.image === undefined ? undefined : before(service.image, ":");
+    if (repo !== undefined && repo.startsWith(registry) && !declared.has(repo))
+      findings.push({ level: "warn", check: "image", message: `service "${name}" pulls ${repo}, which no release in this config builds` });
+  }
+  return findings;
+}
+function restartFindings(config, releases, model, base) {
+  const known = new Set(Object.keys(model?.services ?? {}));
+  const findings = [];
+  for (const release of releases) {
+    for (const service of release.restartServices ?? []) {
+      if (!known.has(service))
+        findings.push({ level: "error", check: "restart", message: `${release.slug}: restartServices names "${service}", absent from ${base}` });
+    }
+  }
+  for (const server of config.servers ?? []) {
+    for (const [slug, override] of Object.entries(server.releaseOverrides ?? {})) {
+      for (const service of override.restartServices ?? []) {
+        if (!known.has(service))
+          findings.push({ level: "error", check: "restart", message: `server ${server.name}: releaseOverrides.${slug} names service "${service}", absent from ${base}` });
+      }
+    }
+  }
+  return findings;
+}
+function postDeployFindings(releases, model, base) {
+  const known = new Set(Object.keys(model?.services ?? {}));
+  const findings = [];
+  for (const release of releases) {
+    for (const command of release.postDeployCommands ?? []) {
+      const target = EXEC_SERVICE.exec(command)?.[1];
+      if (target !== undefined && !known.has(target))
+        findings.push({ level: "warn", check: "post-deploy", message: `${release.slug}: post-deploy command targets service "${target}", absent from ${base}` });
+    }
+  }
+  return findings;
+}
+var gatedServices = (releases) => new Set(releases.flatMap((release) => release.restartServices ?? []));
+function healthFindings(gated, model) {
+  return [...gated].filter((name) => {
+    const service = model?.services?.[name];
+    return service !== undefined && (service.healthcheck === undefined || service.healthcheck === null);
+  }).map((name) => ({ level: "warn", check: "health", message: `service "${name}" is restarted by a release but declares no healthcheck, so --wait will not gate it` }));
+}
+function routingFindings(config, gated, model, base, overlays) {
+  if (overlays.length === 0)
+    return [];
+  const findings = [];
+  for (const name of gated) {
+    const service = model?.services?.[name];
+    if (service === undefined)
+      continue;
+    if (service.ports !== undefined && service.ports.length > 0)
+      findings.push({ level: "error", check: "routing", message: `service "${name}" publishes ports in ${base}; publishing belongs in an overlay` });
+    if (Object.keys(service.labels ?? {}).some((key) => key.startsWith("traefik.")))
+      findings.push({ level: "error", check: "routing", message: `service "${name}" carries traefik labels in ${base}; routing belongs in an overlay` });
+  }
+  const composeArgs = config.composeArgs ?? [];
+  if (composeArgs.length > 0)
+    findings.push({ level: "error", check: "routing", message: `composeArgs is set (${composeArgs.join(" ")}) while ${overlays.length} overlay(s) exist: -f overrides each server's COMPOSE_FILE and drops them` });
+  for (const server of config.servers ?? []) {
+    if (server.composeArgs !== undefined && server.composeArgs.length > 0)
+      findings.push({ level: "warn", check: "routing", message: `server ${server.name} sets composeArgs; prefer its own COMPOSE_FILE` });
+  }
+  return findings;
+}
+function layoutFindings(root, base, model) {
+  if (base === undefined)
+    return [];
+  const header = readFileSync(join2(root, base), "utf8").split(SERVICES_KEY)[0] ?? "";
+  const findings = [];
+  for (const [name, service] of services(model)) {
+    for (const volume of service.volumes ?? []) {
+      const source = typeof volume === "string" ? before(volume, ":") : volume.source;
+      if (source?.startsWith(".") === true && !header.includes(stripDotSlash(source)))
+        findings.push({ level: "warn", check: "layout", message: `service "${name}" bind-mounts ${source}, absent from the header's expected server layout` });
+    }
+  }
+  return findings;
+}
+function gitignoreFindings(root) {
+  const path = join2(root, ".gitignore");
+  const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+  return [".release-logs", ".release-worktrees"].filter((entry) => !text.includes(entry)).map((entry) => ({ level: "warn", check: "gitignore", message: `${entry}/ is not in .gitignore` }));
+}
+
+// src/audit/nuxt.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { basename as basename2, join as join3 } from "path";
+var CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+var KEY = /([A-Z_]\w*)\s*(?:\?\s*)?:/gi;
+var OPENS_BRACE = /^\s*\{/;
+var envVarFor = (key) => key.replace(CAMEL_BOUNDARY, "$1_$2").toUpperCase();
+function braceBody(text, from) {
+  const open = text.indexOf("{", from);
+  if (open < 0)
+    return;
+  let depth = 0;
+  for (let i = open;i < text.length; i++) {
+    if (text[i] === "{")
+      depth++;
+    else if (text[i] === "}" && --depth === 0)
+      return { body: text.slice(open + 1, i), end: i };
+  }
+  return;
+}
+function leafPaths(body, prefix = []) {
+  const paths = [];
+  const key = new RegExp(KEY);
+  for (let match = key.exec(body);match !== null; match = key.exec(body)) {
+    const name = match[1];
+    const after = match.index + match[0].length;
+    if (OPENS_BRACE.test(body.slice(after))) {
+      const inner = braceBody(body, after);
+      if (inner === undefined)
+        continue;
+      paths.push(...leafPaths(inner.body, [...prefix, name]));
+      key.lastIndex = inner.end + 1;
+    } else {
+      paths.push([...prefix, name]);
+    }
+  }
+  return paths;
+}
+function schemaEnvNames(schema, iface, prefix) {
+  const at = schema.indexOf(`interface ${iface}`);
+  const body = at < 0 ? undefined : braceBody(schema, at);
+  return body === undefined ? [] : leafPaths(body.body).map((path) => prefix + path.map(envVarFor).join("_"));
+}
+function nuxtFindings(root, releases, model) {
+  const findings = [];
+  const dirs = [...new Set(releases.map((release) => release.buildContext).filter((context) => context !== undefined && context !== ""))].map((dir) => join3(root, dir)).filter((dir) => existsSync2(join3(dir, "nuxt.config.ts")));
+  for (const dir of dirs) {
+    const schemaPath = [join3(dir, ".nuxt/types/schema.d.ts"), join3(dir, ".nuxt/types/runtime-config.d.ts")].find((path) => existsSync2(path));
+    let allowed;
+    let level = "error";
+    let source;
+    if (schemaPath !== undefined) {
+      const schema = readFileSync2(schemaPath, "utf8");
+      allowed = new Set([
+        ...schemaEnvNames(schema, "SharedRuntimeConfig", "NUXT_"),
+        ...schemaEnvNames(schema, "SharedPublicRuntimeConfig", "NUXT_PUBLIC_")
+      ]);
+      source = `${basename2(dir)}/${schemaPath.slice(dir.length + 1)}`;
+    } else {
+      const config = readFileSync2(join3(dir, "nuxt.config.ts"), "utf8");
+      const at = config.indexOf("runtimeConfig:");
+      const block = at < 0 ? undefined : braceBody(config, at);
+      if (block === undefined)
+        continue;
+      allowed = new Set(leafPaths(block.body).map((path) => path[0] === "public" ? `NUXT_PUBLIC_${path.slice(1).map(envVarFor).join("_")}` : `NUXT_${path.map(envVarFor).join("_")}`));
+      level = "warn";
+      source = `${basename2(dir)}/nuxt.config.ts (run \`nuxt prepare\` in ${basename2(dir)} for the resolved config, modules included)`;
+    }
+    for (const [name, service] of Object.entries(model?.services ?? {})) {
+      for (const key of Object.keys(service.environment ?? {})) {
+        if (key.startsWith("NUXT_") && !allowed.has(key))
+          findings.push({ level, check: "nuxt", message: `service "${name}" sets ${key}, which matches no runtimeConfig key in ${source}` });
+      }
+    }
+  }
+  return findings;
+}
+
+// src/audit/run.ts
+var CONFIG_FILE = "release.config.ts";
+var DEFINE_CONFIG_IMPORT = /import\s*\{[^}]*\bdefineConfig\b[^}]*\}\s*from\s*['"]([^'"]+)['"]/;
+function installed(specifier, root) {
+  try {
+    Bun.resolveSync(specifier, root);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadConfig(root) {
+  const specifier = DEFINE_CONFIG_IMPORT.exec(await Bun.file(join4(root, CONFIG_FILE)).text())?.[1];
+  if (specifier !== undefined && !installed(specifier, root)) {
+    Bun.plugin({
+      name: "release-stand-in",
+      setup(build) {
+        build.module(specifier, () => ({ exports: { defineConfig: (config) => config }, loader: "object" }));
+      }
+    });
+  }
+  const config = (await import(join4(root, CONFIG_FILE))).default;
+  if (config === undefined)
+    fail(`${CONFIG_FILE} has no default export`);
+  return config;
+}
+async function composeModels(options, base, overlays) {
+  const findings = [];
+  const load = async (files) => {
+    try {
+      return await options.loadCompose(options.root, files);
+    } catch (error) {
+      findings.push({ level: "error", check: "compose", message: `docker compose config failed for ${files.join(" + ")}: ${error instanceof Error ? error.message : String(error)}` });
+      return;
+    }
+  };
+  if (base === undefined)
+    return { model: undefined, findings };
+  const model = await load([base]);
+  for (const overlay of overlays)
+    await load([base, overlay]);
+  return { model, findings };
+}
+async function audit(config, options) {
+  const { root } = options;
+  const releases = config.releases ?? [];
+  const required = config.requiredServerEnv ?? [];
+  const { composeFiles, base, overlays } = composeLayout(root, config);
+  const compose = await composeModels(options, base, overlays);
+  const refs = envRefs(root, composeFiles);
+  const gated = gatedServices(releases);
+  const findings = [
+    ...syncFindings(root, config),
+    ...buildFindings(root, releases, options.env, options.home),
+    ...compose.findings,
+    ...envFindings(refs, required),
+    ...versionFindings(refs, releases),
+    ...imageFindings(config, releases, compose.model),
+    ...restartFindings(config, releases, compose.model, base),
+    ...postDeployFindings(releases, compose.model, base),
+    ...healthFindings(gated, compose.model),
+    ...routingFindings(config, gated, compose.model, base, overlays),
+    ...layoutFindings(root, base, compose.model),
+    ...nuxtFindings(root, releases, compose.model),
+    ...gitignoreFindings(root)
+  ];
+  return { root, composeFiles, findings };
+}
+var hasConfig = (root) => existsSync3(join4(root, CONFIG_FILE));
+
+// src/commands/audit.ts
+var usage = `stack audit [dir]
+
+Cross-checks ${CONFIG_FILE} in dir (the current directory) against the compose files it syncs: sync files and build inputs exist, env variables are required or defaulted, versionEnv matches the compose interpolation, restart and post-deploy services exist, healthchecks, routing in overlays, bind mounts documented in the header, Nuxt runtimeConfig keys and .gitignore.
+Needs docker for \`docker compose config\`. Exits 1 on errors, 0 otherwise, 2 when there is no ${CONFIG_FILE}.`;
+var options = {
+  json: jsonOption("{ root, composeFiles, findings }")
+};
+async function audit2(args, overrides = {}) {
+  const parsed = parse(args, usage, options);
+  const root = resolve2(parsed.positionals[0] ?? ".");
+  if (!hasConfig(root)) {
+    console.error(`no ${CONFIG_FILE} in ${root}`);
+    return 2;
+  }
+  const result = await audit(await loadConfig(root), { root, loadCompose: dockerCompose, env: process6.env, home: homedir(), ...overrides });
+  if (parsed.values.json === true)
+    printJson(result);
+  else
+    console.log(render(result));
+  return errorsOf(result).length > 0 ? 1 : 0;
+}
+
+// src/port.ts
+var MIN_PORT = 1024;
+var MAX_PORT = 65535;
+function stringToPort(name, min = MIN_PORT, max = MAX_PORT) {
+  let hash = 2166136261;
+  for (let i = 0;i < name.length; i++) {
+    hash ^= name.charCodeAt(i);
+    hash = hash * 16777619 >>> 0;
+  }
+  return min + hash % (max - min + 1);
+}
+function isListening(port) {
+  try {
+    Bun.listen({ hostname: "0.0.0.0", port, socket: { data: () => {
+      return;
+    } } }).stop(true);
+    return false;
+  } catch (error) {
+    return error.code === "EADDRINUSE";
+  }
+}
+
+// src/commands/port.ts
+var usage2 = `stack port <name>
+
+Prints the port a name always hashes to (FNV-1a, ${MIN_PORT}-${MAX_PORT} by default), so a service keeps the same port on every machine.
+Says on stderr when something already listens on it; the exit code stays 0.`;
+var options2 = {
+  min: { type: "string", description: `lowest port (${MIN_PORT})` },
+  max: { type: "string", description: `highest port (${MAX_PORT})` }
+};
+async function port(args) {
+  const parsed = parse(args, usage2, options2);
+  const [name] = parsed.positionals;
+  if (name === undefined)
+    fail("a name is needed");
+  const min = wholeNumber(parsed.values.min, "min", MIN_PORT);
+  const max = wholeNumber(parsed.values.max, "max", MAX_PORT, min);
+  if (max > MAX_PORT)
+    fail(`--max goes up to ${MAX_PORT}, not ${max}`);
+  const number = stringToPort(name, min, max);
+  console.log(number);
+  if (isListening(number))
+    console.error(`port ${number} is already in use on this machine`);
+  return 0;
+}
+
+// src/cli.ts
+process7.exitCode = await runCli({
+  name: "stack",
+  version,
+  about: "a stable port per service name, and a compose release audit",
+  commands: {
+    port: { run: port, summary: "the port a name always hashes to, with a warning when something already listens on it" },
+    audit: { run: audit2, summary: "cross-check release.config.ts against its compose files" }
+  }
+});

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@kaynooo/stack-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.1.2",
+  "description": "stack: a stable port per service name, and an audit of a compose release setup against its release.config.ts.",
+  "author": "Kaynooo <kaynooo@kevyn.fr>",
+  "license": "MIT",
+  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/stack#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "directory": "packages/stack"
+  },
+  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "keywords": ["docker", "compose", "port", "release", "cli", "bun"],
+  "bin": {
+    "stack": "./dist/cli.js"
+  },
+  "files": ["dist"],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+  },
+  "scripts": {
+    "build": "$npm_execpath build src/cli.ts --target bun --outdir dist",
+    "stack": "$npm_execpath src/cli.ts"
+  },
+  "devDependencies": {
+    "@kaynooo/cli-kit": "workspace:*"
+  }
+}