@mecha.im/cli 0.3.4

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@mecha.im/cli",
+  "version": "0.3.4",
+  "description": "An army of agents — run autonomous Claude bots in Docker containers",
+  "type": "module",
+  "bin": {
+    "mecha": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist/src/",
+    "dist/shared/",
+    "dist/agent/",
+    "shared/",
+    "agent/*.ts",
+    "agent/types.ts",
+    "agent/tools/",
+    "agent/routes/",
+    "agent/dashboard/dist/",
+    "agent/dashboard/public/",
+    "agent/dashboard/package.json",
+    "agent/dashboard/src/",
+    "agent/dashboard/tsconfig.json",
+    "agent/dashboard/index.html",
+    "s6/",
+    "Dockerfile",
+    "tsconfig.json",
+    "tsconfig.agent.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "build:agent": "tsc -p tsconfig.agent.json",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "build:dashboard": "cd dashboard && npm ci && npm run build",
+    "build:bot-dashboard": "cd agent/dashboard && npm ci && npm run build",
+    "build:all": "npm run build && npm run build:dashboard && npm run build:bot-dashboard",
+    "dev": "tsc -b --watch",
+    "test": "node --import tsx test/run-fast.ts",
+    "test:docker": "node --import tsx test/run-docker.ts",
+    "test:live": "node --import tsx test/run-live.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xiaolai/mecha.im.v3"
+  },
+  "homepage": "https://mecha.im",
+  "keywords": [
+    "claude",
+    "agent",
+    "bot",
+    "docker",
+    "ai",
+    "automation",
+    "mecha"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.0",
+    "@anthropic-ai/sdk": "^0.52.0",
+    "@hono/node-server": "^1.14.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "commander": "^14.0.0",
+    "croner": "^9.0.0",
+    "dockerode": "^4.0.7",
+    "hono": "^4.7.0",
+    "node-pty": "^1.1.0",
+    "ora": "^8.2.0",
+    "picocolors": "^1.1.1",
+    "ws": "^8.19.0",
+    "yaml": "^2.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.35",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/s6/mecha-agent/finish

@@ -0,0 +1,4 @@
+#!/bin/bash
+echo "mecha-agent exited with code $1, signal $2"
+# Give time for graceful shutdown
+sleep 2

package/s6/mecha-agent/run

@@ -0,0 +1,39 @@
+#!/bin/bash
+exec 2>&1
+
+# Fix ownership of volume-mounted config dirs (recursive — these are small)
+chown -R appuser:appuser /home/appuser/.claude /home/appuser/.codex 2>/dev/null
+# Workspace ownership: only fix top-level dir, not recursive (can be large)
+chown appuser:appuser /home/appuser/workspace 2>/dev/null
+
+# Ensure .claude.json has onboarding complete (use node for safe JSON handling)
+CLAUDE_JSON="/home/appuser/.claude.json"
+s6-setuidgid appuser env HOME=/home/appuser node -e '
+  const fs = require("fs");
+  const p = process.argv[1];
+  let data = {};
+  try {
+    const raw = fs.readFileSync(p, "utf-8");
+    data = JSON.parse(raw);
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      // File missing — will create fresh
+    } else {
+      // Malformed — back up before overwriting
+      try { fs.copyFileSync(p, p + ".bak"); } catch {}
+      console.error("Warning: .claude.json was malformed, backed up to .claude.json.bak");
+    }
+  }
+  data.hasCompletedOnboarding = true;
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n");
+' "$CLAUDE_JSON"
+
+# Check for stop request (dashboard-initiated stop) — bring down the entire container
+if [ -f /state/stop-requested ]; then
+  rm -f /state/stop-requested
+  echo "Stop requested — shutting down container"
+  s6-svscanctl -t /run/service 2>/dev/null || kill 1
+  exit 0
+fi
+
+exec s6-setuidgid appuser env HOME=/home/appuser node /app/agent/entry.js

package/s6/mecha-agent/type

@@ -0,0 +1 @@
+longrun

package/s6/tailscale-up/type

@@ -0,0 +1 @@
+oneshot

package/s6/tailscale-up/up

@@ -0,0 +1,39 @@
+#!/command/execlineb -P
+foreground {
+  /bin/bash -c "
+    RETRIES=0
+    MAX_RETRIES=3
+    DELAY=5
+
+    while [ $RETRIES -lt $MAX_RETRIES ]; do
+      if [ -S /var/run/tailscale/tailscaled.sock ]; then
+        break
+      fi
+      RETRIES=$((RETRIES + 1))
+      echo \"Waiting for tailscaled... ($RETRIES/$MAX_RETRIES)\"
+      sleep $DELAY
+    done
+
+    if [ ! -S /var/run/tailscale/tailscaled.sock ]; then
+      echo 'WARNING: tailscaled not available, starting in local-only mode'
+      exit 0
+    fi
+
+    TS_ARGS=\"--hostname=mecha-${MECHA_BOT_NAME}\"
+
+    if [ -n \"$MECHA_TS_AUTH_KEY\" ]; then
+      export TS_AUTHKEY=\"$MECHA_TS_AUTH_KEY\"
+    fi
+
+    if [ -n \"$MECHA_TS_LOGIN_SERVER\" ]; then
+      TS_ARGS=\"$TS_ARGS --login-server=$MECHA_TS_LOGIN_SERVER\"
+    fi
+
+    /home/appuser/.local/bin/tailscale up $TS_ARGS --accept-routes || {
+      echo 'WARNING: tailscale up failed, continuing in local-only mode'
+      exit 0
+    }
+
+    echo \"Tailscale connected as mecha-${MECHA_BOT_NAME}\"
+  "
+}

package/s6/tailscaled/run

@@ -0,0 +1,14 @@
+#!/bin/bash
+exec 2>&1
+
+# If /dev/net/tun doesn't exist, Tailscale cannot run.
+# Sleep forever so s6 considers this longrun service "up",
+# allowing dependent services (tailscale-up → mecha-agent) to proceed.
+if [ ! -c /dev/net/tun ]; then
+  echo "WARNING: /dev/net/tun not available, tailscaled disabled"
+  exec sleep infinity
+fi
+
+exec /home/appuser/.local/bin/tailscaled \
+  --state=/state/tailscale/tailscaled.state \
+  --socket=/var/run/tailscale/tailscaled.sock

package/s6/tailscaled/type

@@ -0,0 +1 @@
+longrun

package/shared/atomic-write.ts

@@ -0,0 +1,58 @@
+import { writeFileSync, renameSync, mkdirSync, openSync, fsyncSync, closeSync, unlinkSync } from "node:fs";
+import { writeFile, rename, mkdir, open, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export function atomicWriteJson(filePath: string, data: unknown): void {
+  atomicWrite(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+
+export function atomicWriteText(filePath: string, content: string): void {
+  atomicWrite(filePath, content);
+}
+
+export async function atomicWriteJsonAsync(filePath: string, data: unknown): Promise<void> {
+  await atomicWriteAsync(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+
+export async function atomicWriteTextAsync(filePath: string, content: string): Promise<void> {
+  await atomicWriteAsync(filePath, content);
+}
+
+function atomicWrite(filePath: string, content: string): void {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpPath = join(dir, `.tmp-${randomBytes(8).toString("hex")}`);
+  try {
+    writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+    const fd = openSync(tmpPath, "r");
+    try {
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch { /* cleanup best-effort */ }
+    throw err;
+  }
+}
+
+async function atomicWriteAsync(filePath: string, content: string): Promise<void> {
+  const dir = dirname(filePath);
+  await mkdir(dir, { recursive: true });
+  const tmpPath = join(dir, `.tmp-${randomBytes(8).toString("hex")}`);
+  try {
+    await writeFile(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+    const fh = await open(tmpPath, "r");
+    try {
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    await rename(tmpPath, filePath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* cleanup best-effort */ }
+    throw err;
+  }
+}

package/shared/errors.ts

@@ -0,0 +1,137 @@
+export class MechaError extends Error {
+  readonly code: string;
+  readonly statusCode: number;
+  readonly exitCode: number;
+  readonly hint?: string;
+
+  constructor(
+    message: string,
+    opts: { code: string; statusCode: number; exitCode: number; cause?: unknown; hint?: string },
+  ) {
+    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+    this.name = this.constructor.name;
+    this.code = opts.code;
+    this.statusCode = opts.statusCode;
+    this.exitCode = opts.exitCode;
+    this.hint = opts.hint;
+  }
+}
+
+type ErrorOpts = { code: string; statusCode: number; exitCode: number; hint?: string };
+
+export function defError<A extends unknown[]>(
+  name: string,
+  opts: ErrorOpts,
+  msg: (...args: A) => string,
+) {
+  const arity = msg.length;
+  const cls = class extends MechaError {
+    constructor(...args: unknown[]) {
+      const last = args.length > arity ? args[args.length - 1] : undefined;
+      const hasCauseOpt = typeof last === "object" && last !== null && "cause" in (last as Record<string, unknown>);
+      const cause = hasCauseOpt ? (last as { cause?: unknown }).cause : undefined;
+      const msgArgs = (hasCauseOpt ? args.slice(0, arity) : args.slice(0, arity)) as A;
+      super(msg(...msgArgs), { ...opts, cause });
+      this.name = name;
+    }
+  };
+  Object.defineProperty(cls, "name", { value: name });
+  return cls as { new (...args: [...A] | [...A, { cause?: unknown }]): MechaError };
+}
+
+// --- Name/Config errors ---
+export const InvalidNameError = defError<[string]>(
+  "InvalidNameError",
+  { code: "INVALID_NAME", statusCode: 400, exitCode: 1 },
+  (input) => `Invalid name: "${input}" (must be lowercase, alphanumeric, hyphens, 1-32 chars)`,
+);
+
+export const ConfigValidationError = defError<[string]>(
+  "ConfigValidationError",
+  { code: "CONFIG_VALIDATION_ERROR", statusCode: 400, exitCode: 1 },
+  (detail) => `Invalid bot config: ${detail}`,
+);
+
+// --- Bot lifecycle errors ---
+export const BotNotFoundError = defError<[string]>(
+  "BotNotFoundError",
+  { code: "BOT_NOT_FOUND", statusCode: 404, exitCode: 1, hint: 'Run "mecha ls" to see available bots.' },
+  (name) => `bot "${name}" not found`,
+);
+
+export const BotAlreadyExistsError = defError<[string]>(
+  "BotAlreadyExistsError",
+  { code: "BOT_ALREADY_EXISTS", statusCode: 409, exitCode: 1 },
+  (name) => `bot "${name}" already exists`,
+);
+
+export const BotNotRunningError = defError<[string]>(
+  "BotNotRunningError",
+  { code: "BOT_NOT_RUNNING", statusCode: 409, exitCode: 1, hint: "Start it with: mecha start <name>" },
+  (name) => `bot "${name}" is not running`,
+);
+
+export const BotAlreadyRunningError = defError<[string]>(
+  "BotAlreadyRunningError",
+  { code: "BOT_ALREADY_RUNNING", statusCode: 409, exitCode: 1 },
+  (name) => `bot "${name}" is already running`,
+);
+
+export const BotBusyError = defError<[string]>(
+  "BotBusyError",
+  { code: "BOT_BUSY", statusCode: 409, exitCode: 1, hint: "Use --force to override, or wait for the current operation to finish." },
+  (name) => `bot "${name}" is busy processing a request`,
+);
+
+// --- Auth errors ---
+export const AuthProfileNotFoundError = defError<[string]>(
+  "AuthProfileNotFoundError",
+  { code: "AUTH_PROFILE_NOT_FOUND", statusCode: 404, exitCode: 1 },
+  (name) => `Auth profile "${name}" not found`,
+);
+
+export const AuthNotConfiguredError = defError<[]>(
+  "AuthNotConfiguredError",
+  { code: "AUTH_NOT_CONFIGURED", statusCode: 401, exitCode: 1 },
+  () => `No API key configured. Set ANTHROPIC_API_KEY or run: mecha auth add <profile> <key>`,
+);
+
+// --- Path errors ---
+export const PathNotFoundError = defError<[string]>(
+  "PathNotFoundError",
+  { code: "PATH_NOT_FOUND", statusCode: 400, exitCode: 1 },
+  (path) => `Path not found: "${path}"`,
+);
+
+export const PathNotDirectoryError = defError<[string]>(
+  "PathNotDirectoryError",
+  { code: "PATH_NOT_DIRECTORY", statusCode: 400, exitCode: 1 },
+  (path) => `Path is not a directory: "${path}"`,
+);
+
+// --- Port errors ---
+export const InvalidPortError = defError<[number]>(
+  "InvalidPortError",
+  { code: "INVALID_PORT", statusCode: 400, exitCode: 1 },
+  (port) => `Invalid port: ${port}`,
+);
+
+// --- Process errors ---
+export const ProcessSpawnError = defError<[string]>(
+  "ProcessSpawnError",
+  { code: "PROCESS_SPAWN_ERROR", statusCode: 500, exitCode: 2 },
+  (reason) => `Failed to spawn bot: ${reason}`,
+);
+
+export const ProcessHealthTimeoutError = defError<[string]>(
+  "ProcessHealthTimeoutError",
+  { code: "PROCESS_HEALTH_TIMEOUT", statusCode: 500, exitCode: 2 },
+  (name) => `bot "${name}" failed health check. Check logs with: mecha logs ${name}`,
+);
+
+// --- Config errors ---
+export const CorruptConfigError = defError<[string]>(
+  "CorruptConfigError",
+  { code: "CORRUPT_CONFIG", statusCode: 500, exitCode: 1 },
+  (file) => `Corrupt ${file} — delete and re-initialize`,
+);

package/shared/logger.ts

@@ -0,0 +1,50 @@
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const;
+type Level = keyof typeof LEVELS;
+
+// Keys are matched case-insensitively via k.toLowerCase(), so store only lowercase forms
+const REDACT_KEYS = new Set(["token", "key", "secret", "password", "authorization", "api_key", "apikey", "access_token", "auth_key"]);
+
+// Cache log level at startup (avoids env lookup on every emit)
+const currentLevel: Level = (() => {
+  const env = (process.env.MECHA_LOG_LEVEL ?? "info").toLowerCase();
+  return env in LEVELS ? (env as Level) : "info";
+})();
+
+function redact(obj: unknown, seen = new WeakSet<object>()): unknown {
+  if (typeof obj !== "object" || obj === null) return obj;
+  if (seen.has(obj)) return "[circular]";
+  seen.add(obj);
+  if (Array.isArray(obj)) return obj.map((v) => redact(v, seen));
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    if (REDACT_KEYS.has(k.toLowerCase())) {
+      result[k] = "***";
+    } else {
+      result[k] = redact(v, seen);
+    }
+  }
+  return result;
+}
+
+function emit(level: Level, msg: string, data?: Record<string, unknown>): void {
+  if (LEVELS[level] < LEVELS[currentLevel]) return;
+  const entry: Record<string, unknown> = {
+    level,
+    msg,
+    ts: new Date().toISOString(),
+  };
+  if (data) Object.assign(entry, redact(data));
+  const line = JSON.stringify(entry);
+  if (level === "error") {
+    process.stderr.write(line + "\n");
+  } else {
+    process.stdout.write(line + "\n");
+  }
+}
+
+export const log = {
+  debug: (msg: string, data?: Record<string, unknown>) => emit("debug", msg, data),
+  info: (msg: string, data?: Record<string, unknown>) => emit("info", msg, data),
+  warn: (msg: string, data?: Record<string, unknown>) => emit("warn", msg, data),
+  error: (msg: string, data?: Record<string, unknown>) => emit("error", msg, data),
+};

package/shared/mutex.ts

@@ -0,0 +1,73 @@
+type Release = () => void;
+
+export class Mutex {
+  private locked = false;
+  private queue: Array<() => void> = [];
+
+  acquire(): Promise<Release> {
+    return new Promise((resolve) => {
+      const tryAcquire = () => {
+        if (!this.locked) {
+          this.locked = true;
+          let released = false;
+          resolve(() => {
+            if (released) return;
+            released = true;
+            this.locked = false;
+            const next = this.queue.shift();
+            if (next) next();
+          });
+        }
+      };
+
+      if (!this.locked) {
+        tryAcquire();
+      } else {
+        this.queue.push(tryAcquire);
+      }
+    });
+  }
+
+  /** Non-blocking acquire — returns Release if lock is free, null otherwise. */
+  tryAcquire(): Release | null {
+    if (this.locked) return null;
+    this.locked = true;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.locked = false;
+      const next = this.queue.shift();
+      if (next) next();
+    };
+  }
+
+  get isLocked(): boolean {
+    return this.locked;
+  }
+}
+
+const locks = new Map<string, Mutex>();
+const MAX_MUTEX_KEYS = 1000;
+
+export function getMutex(key: string): Mutex {
+  let mutex = locks.get(key);
+  if (mutex) {
+    // Move to end for LRU ordering (Map preserves insertion order)
+    locks.delete(key);
+    locks.set(key, mutex);
+    return mutex;
+  }
+  // Evict oldest unlocked mutexes if map grows too large
+  if (locks.size >= MAX_MUTEX_KEYS) {
+    for (const [k, m] of locks) {
+      if (!m.isLocked) {
+        locks.delete(k);
+        if (locks.size < MAX_MUTEX_KEYS / 2) break;
+      }
+    }
+  }
+  mutex = new Mutex();
+  locks.set(key, mutex);
+  return mutex;
+}

package/shared/safe-read.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import type { ZodType } from "zod";
+
+export type SafeReadResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; reason: "missing" | "corrupt" | "schema" | "unreadable"; detail: string };
+
+export function safeReadJson<T>(
+  path: string,
+  label: string,
+  schema: ZodType<T>,
+): SafeReadResult<T>;
+export function safeReadJson(
+  path: string,
+  label: string,
+): SafeReadResult<unknown>;
+export function safeReadJson<T>(
+  path: string,
+  label: string,
+  schema?: ZodType<T>,
+): SafeReadResult<T> | SafeReadResult<unknown> {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      return { ok: false, reason: "missing", detail: `${label}: file not found` };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: "unreadable", detail: `${label}: ${msg}` };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: "corrupt", detail: `${label}: invalid JSON — ${msg}` };
+  }
+
+  if (schema) {
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+      return { ok: false, reason: "schema", detail: `${label}: schema validation failed` };
+    }
+    return { ok: true, data: result.data };
+  }
+
+  // Without schema, return as unknown (caller must validate)
+  return { ok: true, data: parsed };
+}

package/shared/totp.ts

@@ -0,0 +1,83 @@
+import { createHmac, randomBytes } from "node:crypto";
+
+// RFC 6238 TOTP — HMAC-SHA1, 6 digits, 30-second step
+
+const DIGITS = 6;
+const STEP = 30;
+const WINDOW = 1; // ±1 window tolerance
+
+const BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+export function generateSecret(): string {
+  const bytes = randomBytes(20);
+  return base32Encode(bytes);
+}
+
+export function base32Encode(buf: Buffer): string {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (const byte of buf) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += BASE32[(value >>> bits) & 0x1f];
+    }
+  }
+  if (bits > 0) {
+    out += BASE32[(value << (5 - bits)) & 0x1f];
+  }
+  return out;
+}
+
+export function base32Decode(encoded: string): Buffer {
+  const cleaned = encoded.replace(/[\s=]/g, "").toUpperCase();
+  let bits = 0;
+  let value = 0;
+  const bytes: number[] = [];
+  for (const ch of cleaned) {
+    const idx = BASE32.indexOf(ch);
+    if (idx === -1) throw new Error(`Invalid base32 character: ${ch}`);
+    value = (value << 5) | idx;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((value >>> bits) & 0xff);
+    }
+  }
+  return Buffer.from(bytes);
+}
+
+function hotp(secret: Buffer, counter: bigint): string {
+  const buf = Buffer.alloc(8);
+  buf.writeBigUInt64BE(counter);
+  const hmac = createHmac("sha1", secret).update(buf).digest();
+  const offset = hmac[hmac.length - 1]! & 0x0f;
+  const code =
+    ((hmac[offset]! & 0x7f) << 24) |
+    ((hmac[offset + 1]! & 0xff) << 16) |
+    ((hmac[offset + 2]! & 0xff) << 8) |
+    (hmac[offset + 3]! & 0xff);
+  return String(code % 10 ** DIGITS).padStart(DIGITS, "0");
+}
+
+export function generateTOTP(secretBase32: string, time?: number): string {
+  const secret = base32Decode(secretBase32);
+  const counter = BigInt(Math.floor((time ?? Date.now() / 1000) / STEP));
+  return hotp(secret, counter);
+}
+
+export function verifyTOTP(secretBase32: string, code: string, time?: number): boolean {
+  const secret = base32Decode(secretBase32);
+  const now = time ?? Date.now() / 1000;
+  const counter = Math.floor(now / STEP);
+  for (let i = -WINDOW; i <= WINDOW; i++) {
+    if (hotp(secret, BigInt(counter + i)) === code) return true;
+  }
+  return false;
+}
+
+export function totpUri(secret: string, issuer: string, account: string): string {
+  return `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(account)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=${DIGITS}&period=${STEP}`;
+}

package/shared/validation.ts

@@ -0,0 +1,29 @@
+export const NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+export const NAME_MAX_LENGTH = 32;
+
+export function isValidName(input: string): boolean {
+  if (input.length === 0 || input.length > NAME_MAX_LENGTH) return false;
+  return NAME_PATTERN.test(input);
+}
+
+export function assertValidName(input: string): void {
+  if (!isValidName(input)) {
+    throw new Error(`Invalid name: "${input}" (must be lowercase, alphanumeric, hyphens, 1-32 chars)`);
+  }
+}
+
+export function parsePort(raw: string): number | undefined {
+  if (!/^\d+$/.test(raw)) return undefined;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) return undefined;
+  return n;
+}
+
+export function isValidUrl(input: string): boolean {
+  try {
+    const url = new URL(input);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}