@runeya/apps-cli 0.1.0

package/Dockerfile

@@ -0,0 +1,54 @@
+ARG BASE_TAG=latest
+
+FROM alpine:3.23 AS base
+RUN apk --no-cache add nodejs yarn git curl bash npm openssh
+ENV NODE_ENV production
+LABEL org.opencontainers.image.source https://github.com/runeya/runeya
+RUN yarn set version 4.0.1 && \
+  yarn config set httpTimeout 500000 && \
+  yarn config set compressionLevel mixed && \
+  yarn config set enableGlobalCache false && \
+  yarn config set nmHoistingLimits none && \
+  yarn config set nodeLinker node-modules && \
+  rm -f package.json
+
+FROM base AS build
+RUN apk --no-cache add gcc g++ make python3 vips-dev musl
+
+FROM build AS prune
+WORKDIR /app
+COPY . .
+RUN yarn dlx turbo prune @runeya/apps-cli --docker
+
+FROM build AS builder
+WORKDIR /app
+COPY .gitignore .gitignore
+COPY tsconfig.json tsconfig.json
+COPY packages/tsconfig/ packages/tsconfig/
+COPY --from=prune /app/out/json/ .
+COPY --from=prune /app/.turbo/ .
+COPY --from=prune /app/out/yarn.lock ./yarn.lock
+COPY --from=prune /app/.yarn/cach[e] .yarn/cache
+RUN yarn install
+COPY --from=prune /app/out/full/ .
+ARG TURBO_TEAM=""
+ARG TURBO_TOKEN=""
+RUN yarn turbo run build --filter=@runeya/apps-cli
+RUN node -e "const p=require('./package.json'); delete p.scripts.postinstall; delete p.scripts.prepare; require('fs').writeFileSync('package.json', JSON.stringify(p, null, 2))" && \
+    yarn workspaces focus -A --production
+RUN rm -rf .yarn/cache
+RUN rm -rf cache
+
+FROM base
+WORKDIR /app
+COPY --from=builder /app .
+RUN chmod +x /app/apps/cli/dist/index.js && \
+    ln -s /app/apps/cli/dist/index.js /usr/local/bin/runeya
+RUN mkdir /src
+WORKDIR /src
+ENV PATH="/home/runeya/.local/bin:$PATH"
+ARG BUILD_DATE
+ENV BUILD_DATE=$BUILD_DATE
+## Security: Running as root is intentional — Runeya needs to install
+## packages, manage processes, and write to arbitrary paths at runtime.
+CMD ["runeya"] # nosemgrep: dockerfile.security.missing-user.missing-user

package/README.md

@@ -0,0 +1,143 @@
+# @runeya/apps-cli
+
+**CLI tout-en-un** pour Runeya qui rassemble le serveur, l'agent et le frontend web dans un seul package (~2.3MB) prêt à l'emploi.
+
+## Architecture
+
+Le CLI orchestre les trois composants principaux de Runeya:
+
+1. **Serveur** (`@runeya/apps-server`) — API tRPC, orchestration, persistence JSON
+2. **Agent local** — Spawné automatiquement par le serveur pour exécuter les processus
+3. **Frontend web** (`@runeya/apps-web`) — Interface Vue 3, servie en fichiers statiques
+
+## Installation en développement
+
+```bash
+# Depuis la racine du monorepo
+yarn install
+yarn build
+```
+
+## Utilisation
+
+### Lancer Runeya (tout-en-un)
+
+```bash
+# Depuis la racine du monorepo
+node apps/cli/dist/index.js
+
+# Ou via yarn
+yarn workspace @runeya/apps-cli start
+```
+
+Le CLI démarrera:
+- Le serveur sur `http://127.0.0.1:4000` (API + frontend)
+- L'agent local sur `http://127.0.0.1:4001`
+
+Ouvrez votre navigateur à `http://127.0.0.1:4000` pour accéder à l'interface.
+
+### Variables d'environnement
+
+```bash
+RUNEYA_HTTP_PORT=3000 HOST=127.0.0.1 node apps/cli/dist/index.js
+```
+
+- `RUNEYA_HTTP_PORT` — Port du serveur (défaut: `4000`) — prend la priorité sur `PORT`
+- `PORT` — Port du serveur (rétrocompat, défaut: `4000`) — utilisez `RUNEYA_HTTP_PORT` de préférence
+- `HOST` — Host du serveur (défaut: `127.0.0.1`)
+- `NODE_ENV` — Mode (`development` ou `production`)
+
+Les variables pour l'agent sont héritées automatiquement (voir `apps/server/src/services/agent-spawner.ts`).
+
+## Distribution
+
+Le CLI nécessite Node.js 22+ installé sur la machine cible.
+
+### Option 1: Distribuer le dossier `dist/` (recommandé)
+
+Le plus simple est de distribuer tout le dossier `apps/cli/dist/` qui contient déjà tout:
+
+```bash
+# Après yarn build, créer une archive
+cd apps/cli
+tar -czf runeya-cli.tar.gz dist/
+
+# Sur la machine cible
+tar -xzf runeya-cli.tar.gz
+node dist/index.js
+```
+
+**Structure distribuée (~2.3MB):**
+```
+dist/
+├── index.js           (point d'entrée)
+├── dist-*.js          (serveur bundlé)
+├── agent/             (agent embarqué)
+└── web/               (frontend embarqué)
+```
+
+### Option 2: Créer un wrapper shell
+
+Créer un script `runeya` à la racine pour faciliter l'utilisation:
+
+```bash
+#!/usr/bin/env bash
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec node "$DIR/dist/index.js" "$@"
+```
+
+Rendre exécutable: `chmod +x runeya`
+
+Utiliser: `./runeya` ou `/usr/local/bin/runeya`
+
+### Note sur les binaires standalone
+
+Les outils comme `pkg` ne supportent pas encore Node.js 22+. Pour créer un vrai binaire standalone, il faudrait:
+- Downgrade à Node.js 20 (dernière version supportée par pkg)
+- Ou attendre que `pkg` / `@yao-pkg/pkg` supporte Node 22+
+- Ou utiliser des solutions alternatives comme Deno compile ou Bun build
+
+## Architecture interne
+
+Le CLI:
+1. Importe `createLocalServer()` de `@runeya/apps-server`
+2. Configure Express pour servir les fichiers statiques de `@runeya/apps-web/dist`
+3. Le serveur spawn automatiquement l'agent local via `AgentSpawner`
+4. Gère le graceful shutdown (SIGTERM/SIGINT)
+
+### Ordre de démarrage
+
+```
+CLI démarre
+  ↓
+createLocalServer()
+  ├─> Initialise les stores (projects, services, agents, settings)
+  ├─> Lance les migrations de schéma
+  ├─> Configure tRPC (HTTP + WebSocket)
+  └─> Spawn l'agent local (via AgentSpawner)
+       ↓
+       Agent démarre sur port 4001
+       ↓
+       Agent envoie son passphrase sur stdout
+       ↓
+       Serveur récupère le passphrase et enregistre l'agent
+  ↓
+Serveur prêt sur port 4000
+  ↓
+CLI configure Express pour servir le frontend web
+  ↓
+Tout est prêt! 🚀
+```
+
+## Notes
+
+- Le CLI est conçu pour l'exécution locale (mode `local-simple`)
+- Le frontend est servi depuis `apps/web/dist/` — assurez-vous de builder le web avant le CLI
+- Hot reload en dev: le serveur watch `apps/agent/dist/index.js` et restart l'agent automatiquement
+
+## Voir aussi
+
+- [apps/server/README.md](../server/README.md) — Documentation du serveur
+- [apps/agent/README.md](../agent/README.md) — Documentation de l'agent
+- [apps/web/README.md](../web/README.md) — Documentation du frontend
+- [CLAUDE.md](/CLAUDE.md) — Guide complet du projet

package/dist/index.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { fileURLToPath, URL as NodeURL } from "url";
+import { dirname, join, resolve } from "path";
+import { readFileSync } from "fs";
+import express from "express";
+import dotenv from "dotenv";
+import open from "open";
+
+// src/port-resolution.ts
+function resolvePort() {
+  const raw = process.env.RUNEYA_HTTP_PORT ?? process.env.PORT;
+  if (raw === void 0) return 4e3;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(
+      `Invalid port: ${JSON.stringify(raw)}. Must be an integer between 1 and 65535.`
+    );
+  }
+  return port;
+}
+
+// src/index.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var { version } = JSON.parse(
+  readFileSync(new NodeURL("../package.json", import.meta.url), "utf8")
+);
+function printStartupTable(port, appUrl) {
+  const rows = [
+    ["Version", version],
+    ["Port", String(port)],
+    ["Url", appUrl]
+  ];
+  const col0 = Math.max(...rows.map(([k]) => k.length));
+  const col1 = Math.max(...rows.map(([, v]) => v.length));
+  const pad = (s, n) => s.padEnd(n);
+  const hr = (l, m, r, f) => l + f.repeat(col0 + 2) + m + f.repeat(col1 + 2) + r;
+  console.log("");
+  console.log(hr("\u250C", "\u252C", "\u2510", "\u2500"));
+  for (const [key, value] of rows) {
+    console.log(`\u2502 ${pad(key, col0)} \u2502 ${pad(value, col1)} \u2502`);
+  }
+  console.log(hr("\u2514", "\u2534", "\u2518", "\u2500"));
+  console.log("");
+}
+var args = process.argv.slice(2);
+var flagsWithValues = /* @__PURE__ */ new Set(["--host", "--port", "-e", "--environment", "-s", "--service"]);
+var targetDir = args.find((a, i) => !a.startsWith("-") && !flagsWithValues.has(args[i - 1] ?? ""));
+if (targetDir) {
+  const resolved = resolve(targetDir);
+  process.chdir(resolved);
+  console.log(`[cli] Working directory: ${resolved}`);
+}
+dotenv.config();
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`Usage: runeya [path-to-your-stack] [options]
+
+Options:
+  --version               Show version number
+  --pe, --pull-env        Print env vars for a service to stdout (requires -e and -s)
+  -e, --environment <n>   Environment name or id
+  -s, --service <name>    Service name or id
+  --lan                   Expose server on the local network (shortcut for --host 0.0.0.0)
+  --host <address>        Host to bind to (default: 127.0.0.1)
+  --no-open               Do not open browser on startup
+  --agent                 Run as agent only (no server, no UI) \u2014 for remote machines
+  -h, --help              Show this help message
+`);
+  process.exit(0);
+}
+if (args.includes("--version")) {
+  console.log(version);
+  process.exit(0);
+}
+var noOpen = args.includes("--no-open") || !!process.env["VITEST"] || !!process.env["CI"] || process.env["NODE_ENV"] === "test";
+var isPullEnv = args.includes("--pull-env") || args.includes("--pe");
+if (isPullEnv) {
+  const toStderr = (...a) => process.stderr.write(a.join(" ") + "\n");
+  console.log = toStderr;
+  console.info = toStderr;
+}
+function getFlagValue(flags) {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  }
+  return void 0;
+}
+var serviceArg = getFlagValue(["-s", "--service"]);
+var environmentArg = getFlagValue(["-e", "--environment"]);
+if (process.env.RUNEYA_HTTP_PORT && !process.env.PORT) {
+  process.env.PORT = process.env.RUNEYA_HTTP_PORT;
+}
+if (process.env.AGENT_PORT && !process.env.RUNEYA_AGENT_PORT) {
+  process.env.RUNEYA_AGENT_PORT = process.env.AGENT_PORT;
+}
+var isLan = args.includes("--lan");
+var hostFlag = getFlagValue(["--host"]);
+var isLanProxy = isLan || process.env.RUNEYA_LAN_PROXY === "true" || process.env.RUNEYA_LAN_PROXY === "1";
+if (hostFlag) {
+  process.env.HOST = hostFlag;
+} else if (isLanProxy) {
+  process.env.HOST = "0.0.0.0";
+}
+if (isLanProxy) {
+  process.env.RUNEYA_LAN_PROXY = "true";
+}
+process.env.AGENT_BINARY_PATH = join(__dirname, "agent/index.js");
+var isAgentOnly = args.includes("--agent");
+if (isAgentOnly) {
+  const agentPort = getFlagValue(["--port"]);
+  const agentHost = getFlagValue(["--host"]);
+  if (agentPort) process.env.RUNEYA_AGENT_PORT = agentPort;
+  if (agentHost) {
+    process.env.RUNEYA_AGENT_HOST = agentHost;
+  } else if (isLanProxy) {
+    process.env.RUNEYA_AGENT_HOST = "0.0.0.0";
+  }
+}
+function listenWithRetry(server, port, host, wss, maxRetries = 20, delay = 500) {
+  return new Promise((resolve2, reject) => {
+    let attempts = 0;
+    const wssErrorHandler = () => {
+    };
+    wss?.on("error", wssErrorHandler);
+    const tryListen = () => {
+      const onError = (err) => {
+        server.removeAllListeners("listening");
+        if (err.code === "EADDRINUSE" && attempts < maxRetries) {
+          attempts++;
+          console.log(`[cli] Port ${port} in use, retrying in ${delay}ms (${attempts}/${maxRetries})...`);
+          setTimeout(tryListen, delay);
+        } else {
+          wss?.removeListener("error", wssErrorHandler);
+          reject(err);
+        }
+      };
+      server.once("error", onError);
+      server.listen(port, host, () => {
+        server.removeListener("error", onError);
+        wss?.removeListener("error", wssErrorHandler);
+        resolve2();
+      });
+    };
+    tryListen();
+  });
+}
+async function main() {
+  const { createLocalServer, pullEnv, PullEnvError } = await import("./dist-MFM5N25P.js");
+  if (isPullEnv) {
+    if (!serviceArg) {
+      console.error("Error: --service (-s) is required with --pull-env");
+      process.exit(1);
+    }
+    if (!environmentArg) {
+      console.error("Error: --environment (-e) is required with --pull-env");
+      process.exit(1);
+    }
+    try {
+      const output = await pullEnv({ service: serviceArg, environment: environmentArg });
+      if (output) process.stdout.write(output + "\n");
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof PullEnvError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(err.exitCode);
+      }
+      throw err;
+    }
+  }
+  if (isAgentOnly) {
+    const { spawn } = await import("child_process");
+    const agentBin = join(__dirname, "agent/index.js");
+    const child = spawn(process.execPath, [agentBin], { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code ?? 0));
+    process.on("SIGINT", () => {
+    });
+    process.on("SIGTERM", () => child.kill("SIGTERM"));
+    return;
+  }
+  console.log("[cli] Starting Runeya...");
+  const { app, server, wss, shutdown } = await createLocalServer();
+  const webDistPath = join(__dirname, "web");
+  app.use(express.static(webDistPath));
+  app.use((_req, res) => {
+    res.sendFile(join(webDistPath, "index.html"));
+  });
+  const port = resolvePort();
+  const host = process.env.HOST ?? "127.0.0.1";
+  await listenWithRetry(server, port, host, wss);
+  const appUrl = `http://${host}:${port}`;
+  if (!noOpen) {
+    await open(appUrl);
+  }
+  console.log("\n\u{1F680}  Runeya is running!");
+  if (isLanProxy) {
+    console.log("\u{1F310}  LAN mode: server and service ports exposed on local network");
+  }
+  printStartupTable(port, appUrl);
+  console.log("[cli] Press Ctrl+C to stop");
+  let shuttingDown = false;
+  const gracefulShutdown = async (signal) => {
+    if (shuttingDown) {
+      console.log(`[cli] Forced exit (second ${signal})`);
+      process.exit(1);
+    }
+    shuttingDown = true;
+    console.log(`
+[cli] Received ${signal}, shutting down gracefully...`);
+    if (process.env.NODE_ENV === "development") {
+      process.exit(0);
+    }
+    await shutdown();
+    console.log("[cli] Shutdown complete");
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+  process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+}
+main().catch((err) => {
+  console.error("[cli] Fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@runeya/apps-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "runeya": "./dist/index.js"
+  },
+  "repository": "https://github.com/runeya/runeya",
+  "scripts": {
+    "build": "tsup && node scripts/post-build.mjs",
+    "dev": "tsup --watch --onSuccess 'node dist/index.js'",
+    "start": "node dist/index.js",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@runeya/apps-agent": "0.1.0",
+    "@runeya/apps-server": "0.1.0",
+    "@runeya/apps-web": "0.1.0",
+    "dotenv": "^17.3.1",
+    "express": "^5.1.0",
+    "open": "^11.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@runeya/scripts-tsup-config": "0.1.0",
+    "@types/express": "^5.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.0"
+  }
+}

package/scripts/post-build.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { cp, mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliRoot = join(__dirname, '..');
+const monorepoRoot = join(cliRoot, '../..');
+
+async function copyDist(src, dest) {
+  console.log(`Copying ${src} -> ${dest}`);
+  await mkdir(dirname(dest), { recursive: true });
+  await cp(src, dest, { recursive: true, force: true });
+}
+
+async function main() {
+  console.log('[post-build] Copying agent and web builds into CLI dist...');
+
+  const cliDist = join(cliRoot, 'dist');
+
+  // Copy agent build
+  await copyDist(
+    join(monorepoRoot, 'apps/agent/dist'),
+    join(cliDist, 'agent')
+  );
+
+  // Copy web build
+  await copyDist(
+    join(monorepoRoot, 'apps/web/dist'),
+    join(cliDist, 'web')
+  );
+
+  // Create shell wrapper for easy execution
+  const wrapperContent = `#!/usr/bin/env bash
+# Runeya CLI launcher
+DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+exec node "$DIR/index.js" "$@"
+`;
+
+  const wrapperPath = join(cliDist, 'runeya');
+  await writeFile(wrapperPath, wrapperContent, { mode: 0o755 });
+  console.log('[post-build] Created shell wrapper: runeya');
+
+  console.log('[post-build] ✅ All builds copied successfully');
+  console.log(`[post-build] CLI dist structure:`);
+  console.log(`  ${cliDist}/`);
+  console.log(`  ├── index.js           (CLI entry point)`);
+  console.log(`  ├── runeya             (shell wrapper)`);
+  console.log(`  ├── dist-*.js          (bundled server code)`);
+  console.log(`  ├── agent/             (agent build)`);
+  console.log(`  │   └── index.js`);
+  console.log(`  └── web/               (web frontend build)`);
+  console.log(`      └── index.html`);
+  console.log('');
+  console.log('[post-build] Usage: ./apps/cli/dist/runeya');
+}
+
+main().catch((err) => {
+  console.error('[post-build] Failed:', err);
+  process.exit(1);
+});

package/src/__tests__/cli-port.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Tests for the CLI port resolution utility (port-resolution.ts).
+ *
+ * These tests are GREEN as soon as port-resolution.ts exists with the right
+ * implementation.  They also serve as the contract that the CLI's index.ts
+ * must satisfy when it calls resolvePort() to determine the listen port.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { resolvePort } from '../port-resolution.js';
+
+describe('resolvePort', () => {
+  const managedKeys = ['RUNEYA_HTTP_PORT', 'PORT'] as const;
+  const saved: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const k of managedKeys) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of managedKeys) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  // --- defaults ---
+
+  it('returns 4000 when no port env vars are set', () => {
+    expect(resolvePort()).toBe(4000);
+  });
+
+  // --- PORT only (backwards compat) ---
+
+  it('uses PORT when only PORT is set', () => {
+    process.env.PORT = '3333';
+    expect(resolvePort()).toBe(3333);
+  });
+
+  // --- RUNEYA_HTTP_PORT ---
+
+  it('uses RUNEYA_HTTP_PORT when only RUNEYA_HTTP_PORT is set', () => {
+    process.env.RUNEYA_HTTP_PORT = '3333';
+    expect(resolvePort()).toBe(3333);
+  });
+
+  it('RUNEYA_HTTP_PORT wins over PORT when both are set', () => {
+    process.env.RUNEYA_HTTP_PORT = '3333';
+    process.env.PORT = '9999';
+    expect(resolvePort()).toBe(3333);
+  });
+
+  // --- edge: extreme valid ports ---
+
+  it('accepts the minimum valid port (1)', () => {
+    process.env.RUNEYA_HTTP_PORT = '1';
+    expect(resolvePort()).toBe(1);
+  });
+
+  it('accepts the maximum valid port (65535)', () => {
+    process.env.RUNEYA_HTTP_PORT = '65535';
+    expect(resolvePort()).toBe(65535);
+  });
+
+  // --- validation errors ---
+
+  it('throws for RUNEYA_HTTP_PORT=0 (below minimum)', () => {
+    process.env.RUNEYA_HTTP_PORT = '0';
+    expect(() => resolvePort()).toThrow();
+  });
+
+  it('throws for RUNEYA_HTTP_PORT=99999 (above maximum)', () => {
+    process.env.RUNEYA_HTTP_PORT = '99999';
+    expect(() => resolvePort()).toThrow();
+  });
+
+  it('throws for RUNEYA_HTTP_PORT=abc (non-numeric)', () => {
+    process.env.RUNEYA_HTTP_PORT = 'abc';
+    expect(() => resolvePort()).toThrow();
+  });
+
+  it('throws for PORT=abc (non-numeric, no RUNEYA_HTTP_PORT set)', () => {
+    process.env.PORT = 'abc';
+    expect(() => resolvePort()).toThrow();
+  });
+
+  it('throws for a decimal value like 80.5', () => {
+    process.env.RUNEYA_HTTP_PORT = '80.5';
+    expect(() => resolvePort()).toThrow();
+  });
+});

package/src/index.ts

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+import type { Server } from 'node:http';
+import type { WebSocketServer } from 'ws';
+import type { Request, Response } from 'express';
+import { fileURLToPath, URL as NodeURL } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import express from 'express';
+import dotenv from 'dotenv'
+import open from 'open';
+import { resolvePort } from './port-resolution.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const { version } = JSON.parse(
+  readFileSync(new NodeURL('../package.json', import.meta.url), 'utf8'),
+) as { version: string };
+
+function printStartupTable(port: number, appUrl: string): void {
+  const rows: [string, string][] = [
+    ['Version', version],
+    ['Port', String(port)],
+    ['Url', appUrl],
+  ];
+
+  const col0 = Math.max(...rows.map(([k]) => k.length));
+  const col1 = Math.max(...rows.map(([, v]) => v.length));
+
+  const pad = (s: string, n: number) => s.padEnd(n);
+  const hr = (l: string, m: string, r: string, f: string) =>
+    l + f.repeat(col0 + 2) + m + f.repeat(col1 + 2) + r;
+
+  console.log('');
+  console.log(hr('┌', '┬', '┐', '─'));
+  for (const [key, value] of rows) {
+    console.log(`│ ${pad(key, col0)} │ ${pad(value, col1)} │`);
+  }
+  console.log(hr('└', '┴', '┘', '─'));
+  console.log('');
+}
+
+// Parse CLI flags
+const args = process.argv.slice(2);
+
+// Resolve target directory (first positional arg, skipping flag values)
+const flagsWithValues = new Set(['--host', '--port', '-e', '--environment', '-s', '--service']);
+const targetDir = args.find((a, i) => !a.startsWith('-') && !flagsWithValues.has(args[i - 1] ?? ''));
+if (targetDir) {
+  const resolved = resolve(targetDir);
+  process.chdir(resolved);
+  console.log(`[cli] Working directory: ${resolved}`);
+}
+
+dotenv.config();
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: runeya [path-to-your-stack] [options]
+
+Options:
+  --version               Show version number
+  --pe, --pull-env        Print env vars for a service to stdout (requires -e and -s)
+  -e, --environment <n>   Environment name or id
+  -s, --service <name>    Service name or id
+  --lan                   Expose server on the local network (shortcut for --host 0.0.0.0)
+  --host <address>        Host to bind to (default: 127.0.0.1)
+  --no-open               Do not open browser on startup
+  --agent                 Run as agent only (no server, no UI) — for remote machines
+  -h, --help              Show this help message
+`);
+  process.exit(0);
+}
+
+if (args.includes('--version')) {
+  console.log(version);
+  process.exit(0);
+}
+
+const noOpen =
+  args.includes('--no-open') ||
+  !!process.env['VITEST'] ||
+  !!process.env['CI'] ||
+  process.env['NODE_ENV'] === 'test';
+
+// --pull-env flag — detect early so we can silence stdout before any log
+const isPullEnv = args.includes('--pull-env') || args.includes('--pe');
+
+// In pull-env mode, redirect console.log/info to stderr so only KEY=VALUE goes to stdout
+if (isPullEnv) {
+  const toStderr = (...a: unknown[]) => process.stderr.write(a.join(' ') + '\n');
+  console.log = toStderr;
+  console.info = toStderr;
+}
+
+function getFlagValue(flags: string[]): string | undefined {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  }
+  return undefined;
+}
+
+const serviceArg = getFlagValue(['-s', '--service']);
+const environmentArg = getFlagValue(['-e', '--environment']);
+
+// Configure environment BEFORE importing server (env is parsed at module load)
+// RUNEYA_HTTP_PORT takes priority over PORT
+if (process.env.RUNEYA_HTTP_PORT && !process.env.PORT) {
+  process.env.PORT = process.env.RUNEYA_HTTP_PORT;
+}
+// AGENT_PORT is an alias for RUNEYA_AGENT_PORT (used by e2e test-server and legacy tooling)
+if (process.env.AGENT_PORT && !process.env.RUNEYA_AGENT_PORT) {
+  process.env.RUNEYA_AGENT_PORT = process.env.AGENT_PORT;
+}
+// --lan shortcut sets host to 0.0.0.0; --host flag takes priority over HOST env var
+const isLan = args.includes('--lan');
+const hostFlag = getFlagValue(['--host']);
+const isLanProxy = isLan || process.env.RUNEYA_LAN_PROXY === 'true' || process.env.RUNEYA_LAN_PROXY === '1';
+if (hostFlag) {
+  process.env.HOST = hostFlag;
+} else if (isLanProxy) {
+  process.env.HOST = '0.0.0.0';
+}
+if (isLanProxy) {
+  process.env.RUNEYA_LAN_PROXY = 'true';
+}
+// Agent binary path (embedded in CLI dist during build)
+process.env.AGENT_BINARY_PATH = join(__dirname, 'agent/index.js');
+
+// --agent mode: run as standalone agent only (no server, no UI)
+const isAgentOnly = args.includes('--agent');
+if (isAgentOnly) {
+  const agentPort = getFlagValue(['--port']);
+  const agentHost = getFlagValue(['--host']);
+  if (agentPort) process.env.RUNEYA_AGENT_PORT = agentPort;
+  // --host in agent mode binds the agent (default 127.0.0.1 — use --host 0.0.0.0 for remote access)
+  // --lan also applies: sets agent host to 0.0.0.0 unless --host overrides it
+  if (agentHost) {
+    process.env.RUNEYA_AGENT_HOST = agentHost;
+  } else if (isLanProxy) {
+    process.env.RUNEYA_AGENT_HOST = '0.0.0.0';
+  }
+}
+// Data directory defaults to CWD/.runeya (server env.ts default)
+// so Runeya data lives alongside the target project.
+
+/**
+ * Listen with retry for EADDRINUSE — handles the race condition when the CLI
+ * restarts the server before the old process has fully released the port.
+ *
+ * The `wss` parameter is needed because the `ws` library re-emits HTTP server
+ * errors on the WebSocketServer — without a handler the error becomes unhandled.
+ */
+function listenWithRetry(
+  server: Server,
+  port: number,
+  host: string,
+  wss?: WebSocketServer,
+  maxRetries = 20,
+  delay = 500,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let attempts = 0;
+
+    // Absorb EADDRINUSE errors re-emitted by the ws library on the WSS
+    // during the retry window. Without this, Node.js crashes on unhandled error.
+    const wssErrorHandler = () => { /* absorbed — handled via server 'error' */ };
+    wss?.on('error', wssErrorHandler);
+
+    const tryListen = () => {
+      const onError = (err: NodeJS.ErrnoException) => {
+        // Clean up the 'listening' callback that server.listen() registered
+        server.removeAllListeners('listening');
+
+        if (err.code === 'EADDRINUSE' && attempts < maxRetries) {
+          attempts++;
+          console.log(`[cli] Port ${port} in use, retrying in ${delay}ms (${attempts}/${maxRetries})...`);
+          setTimeout(tryListen, delay);
+        } else {
+          wss?.removeListener('error', wssErrorHandler);
+          reject(err);
+        }
+      };
+
+      server.once('error', onError);
+      server.listen(port, host, () => {
+        server.removeListener('error', onError);
+        wss?.removeListener('error', wssErrorHandler);
+        resolve();
+      });
+    };
+
+    tryListen();
+  });
+}
+
+async function main() {
+  // Dynamic import ensures env is parsed AFTER we configure it
+  const { createLocalServer, pullEnv, PullEnvError } = await import('@runeya/apps-server');
+
+  // Handle --pull-env mode: resolve env vars and print, then exit
+  if (isPullEnv) {
+    if (!serviceArg) {
+      console.error('Error: --service (-s) is required with --pull-env');
+      process.exit(1);
+    }
+    if (!environmentArg) {
+      console.error('Error: --environment (-e) is required with --pull-env');
+      process.exit(1);
+    }
+    try {
+      const output = await pullEnv({ service: serviceArg, environment: environmentArg });
+      if (output) process.stdout.write(output + '\n');
+      process.exit(0);
+    } catch (err: unknown) {
+      if (err instanceof PullEnvError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(err.exitCode);
+      }
+      throw err;
+    }
+  }
+
+  // --agent mode: standalone agent, no server, no UI
+  if (isAgentOnly) {
+    const { spawn } = await import('node:child_process');
+    const agentBin = join(__dirname, 'agent/index.js');
+    const child = spawn(process.execPath, [agentBin], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    // SIGINT is already delivered to the child by the terminal (same process group).
+    // Intercept it here only to suppress Node's default exit so we stay alive
+    // until the child finishes its graceful shutdown.
+    process.on('SIGINT', () => { /* wait for child to exit */ });
+    process.on('SIGTERM', () => child.kill('SIGTERM'));
+    return;
+  }
+
+  console.log('[cli] Starting Runeya...');
+
+  // Create server (automatically spawns local agent)
+  const { app, server, wss, shutdown } = await createLocalServer();
+
+  // Serve static files from web frontend (embedded in CLI dist during build)
+  const webDistPath = join(__dirname, 'web');
+  app.use(express.static(webDistPath));
+
+  // Fallback to index.html for client-side routing (Vue Router)
+  // Express 5 requires explicit path patterns (not '*')
+  app.use((_req: Request, res: Response) => {
+    res.sendFile(join(webDistPath, 'index.html'));
+  });
+
+  // Start server — RUNEYA_HTTP_PORT takes priority over PORT
+  const port = resolvePort();
+  const host = process.env.HOST ?? '127.0.0.1';
+
+  await listenWithRetry(server, port, host, wss);
+
+  const appUrl = `http://${host}:${port}`;
+
+  if (!noOpen) {
+    await open(appUrl);
+  }
+
+  console.log('\n🚀  Runeya is running!');
+  if (isLanProxy) {
+    console.log('🌐  LAN mode: server and service ports exposed on local network');
+  }
+  printStartupTable(port, appUrl);
+  console.log('[cli] Press Ctrl+C to stop');
+
+  let shuttingDown = false;
+  const gracefulShutdown = async (signal: string) => {
+    if (shuttingDown) {
+      console.log(`[cli] Forced exit (second ${signal})`);
+      process.exit(1);
+    }
+    shuttingDown = true;
+    console.log(`\n[cli] Received ${signal}, shutting down gracefully...`);
+
+    // In dev, exit immediately — ports are freed on process death,
+    // and the 'exit' handler in agent-spawner SIGKILLs the agent.
+    if (process.env.NODE_ENV === 'development') {
+      process.exit(0);
+    }
+
+    await shutdown();
+    console.log('[cli] Shutdown complete');
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+  process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+}
+
+main().catch((err) => {
+  console.error('[cli] Fatal error:', err);
+  process.exit(1);
+});

package/src/port-resolution.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve the HTTP port Runeya should listen on.
+ *
+ * Priority: RUNEYA_HTTP_PORT > PORT > 4000 (default)
+ *
+ * Throws if the resolved value is not an integer in [1, 65535].
+ */
+export function resolvePort(): number {
+  const raw = process.env.RUNEYA_HTTP_PORT ?? process.env.PORT;
+  if (raw === undefined) return 4000;
+
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(
+      `Invalid port: ${JSON.stringify(raw)}. Must be an integer between 1 and 65535.`,
+    );
+  }
+  return port;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.bundled_lh0xis3zdq.mjs

@@ -0,0 +1,10 @@
+// tsup.config.ts
+import { defineConfig } from "tsup";
+import { getAppConfig } from "@runeya/scripts-tsup-config";
+var tsup_config_default = defineConfig(getAppConfig({
+  entry: ["src/index.ts"]
+}));
+export {
+  tsup_config_default as default
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsidHN1cC5jb25maWcudHMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbImNvbnN0IF9faW5qZWN0ZWRfZmlsZW5hbWVfXyA9IFwiL2hvbWUvY29jby9Qcm9qZWN0cy9ydW5leWEtcnVzdC9hcHBzL2NsaS90c3VwLmNvbmZpZy50c1wiO2NvbnN0IF9faW5qZWN0ZWRfZGlybmFtZV9fID0gXCIvaG9tZS9jb2NvL1Byb2plY3RzL3J1bmV5YS1ydXN0L2FwcHMvY2xpXCI7Y29uc3QgX19pbmplY3RlZF9pbXBvcnRfbWV0YV91cmxfXyA9IFwiZmlsZTovLy9ob21lL2NvY28vUHJvamVjdHMvcnVuZXlhLXJ1c3QvYXBwcy9jbGkvdHN1cC5jb25maWcudHNcIjtpbXBvcnQgeyBkZWZpbmVDb25maWcgfSBmcm9tICd0c3VwJztcbmltcG9ydCB7IGdldEFwcENvbmZpZyB9IGZyb20gJ0BydW5leWEvc2NyaXB0cy10c3VwLWNvbmZpZyc7XG5cbmV4cG9ydCBkZWZhdWx0IGRlZmluZUNvbmZpZyhnZXRBcHBDb25maWcoe1xuICBlbnRyeTogWydzcmMvaW5kZXgudHMnXSxcbn0pKTtcbiJdLAogICJtYXBwaW5ncyI6ICI7QUFBc1EsU0FBUyxvQkFBb0I7QUFDblMsU0FBUyxvQkFBb0I7QUFFN0IsSUFBTyxzQkFBUSxhQUFhLGFBQWE7QUFBQSxFQUN2QyxPQUFPLENBQUMsY0FBYztBQUN4QixDQUFDLENBQUM7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/tsup.config.bundled_qj1zdvku09a.mjs

@@ -0,0 +1,10 @@
+// tsup.config.ts
+import { defineConfig } from "tsup";
+import { getAppConfig } from "@runeya/scripts-tsup-config";
+var tsup_config_default = defineConfig(getAppConfig({
+  entry: ["src/index.ts"]
+}));
+export {
+  tsup_config_default as default
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsidHN1cC5jb25maWcudHMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbImNvbnN0IF9faW5qZWN0ZWRfZmlsZW5hbWVfXyA9IFwiL2hvbWUvY29jby9Qcm9qZWN0cy9ydW5leWEtcnVzdC9hcHBzL2NsaS90c3VwLmNvbmZpZy50c1wiO2NvbnN0IF9faW5qZWN0ZWRfZGlybmFtZV9fID0gXCIvaG9tZS9jb2NvL1Byb2plY3RzL3J1bmV5YS1ydXN0L2FwcHMvY2xpXCI7Y29uc3QgX19pbmplY3RlZF9pbXBvcnRfbWV0YV91cmxfXyA9IFwiZmlsZTovLy9ob21lL2NvY28vUHJvamVjdHMvcnVuZXlhLXJ1c3QvYXBwcy9jbGkvdHN1cC5jb25maWcudHNcIjtpbXBvcnQgeyBkZWZpbmVDb25maWcgfSBmcm9tICd0c3VwJztcbmltcG9ydCB7IGdldEFwcENvbmZpZyB9IGZyb20gJ0BydW5leWEvc2NyaXB0cy10c3VwLWNvbmZpZyc7XG5cbmV4cG9ydCBkZWZhdWx0IGRlZmluZUNvbmZpZyhnZXRBcHBDb25maWcoe1xuICBlbnRyeTogWydzcmMvaW5kZXgudHMnXSxcbn0pKTtcbiJdLAogICJtYXBwaW5ncyI6ICI7QUFBc1EsU0FBUyxvQkFBb0I7QUFDblMsU0FBUyxvQkFBb0I7QUFFN0IsSUFBTyxzQkFBUSxhQUFhLGFBQWE7QUFBQSxFQUN2QyxPQUFPLENBQUMsY0FBYztBQUN4QixDQUFDLENBQUM7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/tsup.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'tsup';
+import { getAppConfig } from '@runeya/scripts-tsup-config';
+
+export default defineConfig(getAppConfig({
+  entry: ['src/index.ts'],
+}));