station-kit 1.0.6 → 1.0.8

package/src/cli/deploy.ts

@@ -0,0 +1,334 @@
+import {
+  writeFileSync,
+  readFileSync,
+  cpSync,
+  existsSync,
+  readdirSync,
+  rmSync,
+  mkdirSync,
+  statSync,
+} from "node:fs";
+import { join, resolve, dirname, relative } from "node:path";
+import { builtinModules } from "node:module";
+import { build } from "esbuild";
+import { loadConfig } from "../config/loader.js";
+import { ensureStationDir } from "../station-dir.js";
+
+const cwd = process.cwd();
+
+// Ensure .station/data exists before loading config — adapter constructors may open DBs
+const defaultStationDir = ".station";
+mkdirSync(join(cwd, defaultStationDir, "data"), { recursive: true });
+
+const config = await loadConfig(cwd);
+const { outDir } = ensureStationDir(cwd, config.stationDir);
+
+// ── Workspace resolution ────────────────────────────────────
+
+function findWorkspaceRoot(startDir: string): string | null {
+  let dir = startDir;
+  while (true) {
+    if (existsSync(join(dir, "pnpm-workspace.yaml"))) return dir;
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (pkg.workspaces) return dir;
+      } catch {}
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function resolveWorkspaceVersion(depName: string, startDir: string): string | null {
+  const root = findWorkspaceRoot(startDir);
+  if (!root) return null;
+  const candidate = join(root, "packages", depName, "package.json");
+  if (!existsSync(candidate)) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Production package.json ─────────────────────────────────
+
+interface PkgJson {
+  name?: string;
+  version?: string;
+  type?: string;
+  private?: boolean;
+  description?: string;
+  license?: string;
+  author?: unknown;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+const resolvedDeps: Array<{ dep: string; from: string; to: string }> = [];
+
+function buildProductionPackageJson(): PkgJson {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) {
+    console.error("[station] No package.json found.");
+    process.exit(1);
+  }
+
+  const raw: PkgJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
+
+  // Merge deps: all dependencies + station-* from devDependencies
+  const deps: Record<string, string> = { ...(raw.dependencies ?? {}) };
+  if (raw.devDependencies) {
+    for (const [name, version] of Object.entries(raw.devDependencies)) {
+      if (name.startsWith("station-") && !deps[name]) {
+        deps[name] = version;
+      }
+    }
+  }
+
+  // Resolve workspace:* → ^{version}
+  for (const [name, version] of Object.entries(deps)) {
+    if (version.startsWith("workspace:")) {
+      const resolved_version = resolveWorkspaceVersion(name, cwd);
+      if (resolved_version) {
+        const newVersion = `^${resolved_version}`;
+        resolvedDeps.push({ dep: name, from: version, to: newVersion });
+        deps[name] = newVersion;
+      } else {
+        console.warn(`[station] Could not resolve ${version} for "${name}" — ensure you are in a workspace or use real version numbers.`);
+      }
+    }
+  }
+
+  const out: PkgJson = {};
+  if (raw.name) out.name = raw.name;
+  if (raw.version) out.version = raw.version;
+  if (raw.type) out.type = raw.type;
+  if (raw.private !== undefined) out.private = raw.private;
+  if (raw.description) out.description = raw.description;
+  if (raw.license) out.license = raw.license;
+  if (raw.author) out.author = raw.author;
+  out.scripts = { start: "npx station --no-open --host 0.0.0.0" };
+  out.dependencies = deps;
+
+  return out;
+}
+
+// ── Discover entry points ───────────────────────────────────
+
+function discoverFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { recursive: true })) {
+    const full = join(dir, entry.toString());
+    if (statSync(full).isFile() && /\.(ts|js|mjs)$/.test(full)) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function findConfigFile(): string | null {
+  for (const name of ["station.config.ts", "station.config.js", "station.config.mjs"]) {
+    const candidate = join(cwd, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// ── Build ───────────────────────────────────────────────────
+
+console.log("\n[station] Building deploy bundle...\n");
+
+// Clean out directory
+if (existsSync(outDir)) {
+  rmSync(outDir, { recursive: true });
+}
+mkdirSync(outDir, { recursive: true });
+
+// Write production package.json first (need deps list for externals)
+const prodPkg = buildProductionPackageJson();
+writeFileSync(join(outDir, "package.json"), JSON.stringify(prodPkg, null, 2) + "\n");
+
+// Collect entry points
+const entryPoints: string[] = [];
+let signalCount = 0;
+let broadcastCount = 0;
+
+if (config.signalsDir) {
+  const signalsSrc = resolve(cwd, config.signalsDir);
+  const files = discoverFiles(signalsSrc);
+  signalCount = files.length;
+  entryPoints.push(...files);
+}
+
+if (config.broadcastsDir) {
+  const broadcastsSrc = resolve(cwd, config.broadcastsDir);
+  const files = discoverFiles(broadcastsSrc);
+  broadcastCount = files.length;
+  entryPoints.push(...files);
+}
+
+const configFile = findConfigFile();
+if (configFile) {
+  entryPoints.push(configFile);
+}
+
+if (entryPoints.length === 0) {
+  console.error("[station] No signals, broadcasts, or config found to bundle.");
+  process.exit(1);
+}
+
+// Collect externals: all npm deps + node builtins
+const external = [
+  ...Object.keys(prodPkg.dependencies ?? {}),
+  ...builtinModules,
+  ...builtinModules.map((m) => `node:${m}`),
+];
+
+// Run esbuild
+try {
+  const result = await build({
+    entryPoints,
+    outdir: outDir,
+    outbase: cwd,
+    bundle: true,
+    splitting: true,
+    format: "esm",
+    platform: "node",
+    target: "node20",
+    external,
+    logLevel: "warning",
+  });
+
+  if (result.errors.length > 0) {
+    console.error("[station] Build failed.");
+    process.exit(1);
+  }
+} catch (err: unknown) {
+  console.error("[station] Build failed:", (err as Error).message);
+  process.exit(1);
+}
+
+// Count shared chunks
+const outputFiles = readdirSync(outDir);
+const chunks = outputFiles.filter((f) => f.startsWith("chunk-") && f.endsWith(".js"));
+
+console.log(`  Bundled ${signalCount} signal${signalCount !== 1 ? "s" : ""}, ${broadcastCount} broadcast${broadcastCount !== 1 ? "s" : ""}`);
+if (chunks.length > 0) {
+  console.log(`  ${chunks.length} shared chunk${chunks.length !== 1 ? "s" : ""} extracted`);
+}
+if (configFile) {
+  console.log(`  Config compiled`);
+}
+
+// ── Copy deploy.include entries ─────────────────────────────
+
+if (config.deploy?.include) {
+  for (const entry of config.deploy.include) {
+    const src = resolve(cwd, entry);
+    if (!existsSync(src)) {
+      console.warn(`  [station] Warning: deploy.include path not found: ${entry}`);
+      continue;
+    }
+    const dest = join(outDir, entry);
+    if (statSync(src).isDirectory()) {
+      cpSync(src, dest, { recursive: true });
+    } else {
+      mkdirSync(dirname(dest), { recursive: true });
+      cpSync(src, dest);
+    }
+  }
+}
+
+// ── Dockerfile ──────────────────────────────────────────────
+
+function generateDockerfile(): string {
+  const port = config.port;
+  return [
+    `FROM node:20-alpine`,
+    `WORKDIR /app`,
+    ``,
+    `COPY package.json ./`,
+    `RUN npm install --omit=dev`,
+    ``,
+    `COPY . .`,
+    ``,
+    `EXPOSE ${port}`,
+    `ENV NODE_ENV=production`,
+    `ENV HOST=0.0.0.0`,
+    `ENV PORT=${port}`,
+    ``,
+    `# Set these in your deployment platform:`,
+    `# ENV STATION_AUTH_USERNAME=admin`,
+    `# ENV STATION_AUTH_PASSWORD=changeme`,
+    ``,
+    `CMD ["npx", "station", "--no-open", "--host", "0.0.0.0"]`,
+    ``,
+  ].join("\n");
+}
+
+// ── nixpacks.toml ───────────────────────────────────────────
+
+function generateNixpacks(): string {
+  return [
+    `[phases.setup]`,
+    `nixPkgs = ["nodejs_20"]`,
+    ``,
+    `[phases.install]`,
+    `cmds = ["npm install --omit=dev"]`,
+    ``,
+    `[start]`,
+    `cmd = "npx station --no-open --host 0.0.0.0"`,
+    ``,
+  ].join("\n");
+}
+
+// ── Write deployment files ──────────────────────────────────
+
+writeFileSync(join(outDir, "Dockerfile"), generateDockerfile());
+writeFileSync(join(outDir, "nixpacks.toml"), generateNixpacks());
+writeFileSync(join(outDir, ".dockerignore"), ["node_modules", ".station/data", "*.db", ".git", ""].join("\n"));
+writeFileSync(join(outDir, ".gitignore"), ["node_modules/", "data/", "*.db", ""].join("\n"));
+
+// ── Summary ─────────────────────────────────────────────────
+
+function listDir(dir: string, prefix = ""): string[] {
+  const entries: string[] = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      entries.push(`${prefix}${entry}/`);
+      entries.push(...listDir(full, `${prefix}  `));
+    } else {
+      entries.push(`${prefix}${entry}`);
+    }
+  }
+  return entries;
+}
+
+console.log(`\n  ${outDir}\n`);
+for (const line of listDir(outDir)) {
+  console.log(`    ${line}`);
+}
+
+if (resolvedDeps.length > 0) {
+  console.log(`\n  Resolved dependencies:`);
+  for (const r of resolvedDeps) {
+    console.log(`    ${r.dep}: ${r.from} → ${r.to}`);
+  }
+}
+
+console.log(`\n  Environment variables:`);
+console.log(`    STATION_AUTH_USERNAME  — dashboard login`);
+console.log(`    STATION_AUTH_PASSWORD  — dashboard password`);
+console.log(`    PORT                  — server port (default: ${config.port})`);
+
+console.log(`\n  Deploy:`);
+console.log(`    docker build -t station ${outDir}`);
+console.log(`    docker run -p ${config.port}:${config.port} station\n`);

package/src/cli/parse-args.ts

@@ -0,0 +1,99 @@
+export interface CliArgs {
+  port?: number;
+  host?: string;
+  dir?: string;
+  noOpen?: boolean;
+  noRunners?: boolean;
+  config?: string;
+  subcommand?: string;
+  help?: boolean;
+}
+
+const FLAGS_WITH_VALUE = new Set(["--port", "--host", "--dir", "--config"]);
+
+export function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {};
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg === "--help" || arg === "-h") {
+      args.help = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--no-open") {
+      args.noOpen = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--no-runners" || arg === "--read-only") {
+      args.noRunners = true;
+      i++;
+      continue;
+    }
+
+    if (FLAGS_WITH_VALUE.has(arg)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+
+      switch (arg) {
+        case "--port": {
+          const n = parseInt(value, 10);
+          if (isNaN(n) || n < 1 || n > 65535) {
+            throw new Error(`Invalid port: ${value}`);
+          }
+          args.port = n;
+          break;
+        }
+        case "--host":
+          args.host = value;
+          break;
+        case "--dir":
+          args.dir = value;
+          break;
+        case "--config":
+          args.config = value;
+          break;
+      }
+
+      i += 2;
+      continue;
+    }
+
+    // First positional arg that doesn't start with -- is a subcommand
+    if (!arg.startsWith("-")) {
+      args.subcommand = arg;
+      i++;
+      continue;
+    }
+
+    throw new Error(`Unknown flag: ${arg}`);
+  }
+
+  return args;
+}
+
+export function printUsage(): void {
+  console.log(`
+Usage: station [command] [options]
+
+Commands:
+  deploy          Generate deployment files (Dockerfile, nixpacks.toml)
+
+Options:
+  --port <n>      Override server port (default: 4400)
+  --host <s>      Override server host (default: localhost)
+  --dir <path>    Set station directory for generated files (default: .station)
+  --config <path> Path to config file (default: station.config.ts)
+  --no-open       Don't open browser on start
+  --no-runners    Don't execute signal/broadcast runners (read-only mode)
+  --read-only     Alias for --no-runners
+  -h, --help      Show this help message
+`.trim());
+}

package/src/cli-main.ts

@@ -1,11 +1,38 @@
 import { loadConfig } from "./config/loader.js";
 import { createStation } from "./server/index.js";
+import { parseArgs, printUsage } from "./cli/parse-args.js";
 import { spawn, type ChildProcess } from "node:child_process";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 
+// Parse CLI arguments
+const cliArgs = parseArgs(process.argv.slice(2));
+
+if (cliArgs.help) {
+  printUsage();
+  process.exit(0);
+}
+
+if (cliArgs.subcommand === "deploy") {
+  await import("./cli/deploy.js");
+  process.exit(0);
+}
+
+if (cliArgs.subcommand) {
+  console.error(`[station] Unknown command: ${cliArgs.subcommand}`);
+  printUsage();
+  process.exit(1);
+}
+
 const cwd = process.cwd();
-const config = await loadConfig(cwd);
+const config = await loadConfig(cwd, cliArgs.config);
+
+// Apply CLI overrides
+if (cliArgs.port !== undefined) config.port = cliArgs.port;
+if (cliArgs.host !== undefined) config.host = cliArgs.host;
+if (cliArgs.dir !== undefined) config.stationDir = cliArgs.dir;
+if (cliArgs.noOpen) config.open = false;
+if (cliArgs.noRunners) config.runRunners = false;
 
 // Spawn Next.js standalone server for the dashboard
 const pkgRoot = resolve(import.meta.dirname, "..");

package/src/cli.ts

@@ -23,7 +23,7 @@ if (!process.env[MARKER]) {
   }
 
   const main = fileURLToPath(new URL("./cli-main.js", import.meta.url));
-  const child = spawn(execPath, ["--import", tsxSpecifier, main], {
+  const child = spawn(execPath, ["--import", tsxSpecifier, main, ...process.argv.slice(2)], {
     stdio: "inherit",
     env: { ...process.env, [MARKER]: "1", __STATION_TSX: tsxSpecifier },
   });

package/src/config/loader.ts

@@ -9,10 +9,14 @@ const CONFIG_NAMES = [
   "station.config.mjs",
 ];
 
-export async function loadConfig(cwd: string): Promise<StationConfig> {
-  const configPath = findConfigFile(cwd);
+export async function loadConfig(cwd: string, configFile?: string): Promise<StationConfig> {
+  const configPath = configFile ? resolve(cwd, configFile) : findConfigFile(cwd);
 
-  if (!configPath) {
+  if (!configPath || !existsSync(configPath)) {
+    if (configFile) {
+      console.error(`[station] Config file not found: ${configFile}`);
+      process.exit(1);
+    }
     console.log("[station] No config file found. Using defaults.");
     return resolveConfig({});
   }

package/src/config/schema.ts

@@ -18,6 +18,10 @@ export interface BroadcastRunnerConfig {
   pollIntervalMs: number;
 }
 
+export interface DeployConfig {
+  include?: string[];
+}
+
 export interface StationConfig {
   port: number;
   host: string;
@@ -25,12 +29,14 @@ export interface StationConfig {
   broadcastAdapter?: BroadcastQueueAdapter;
   signalsDir?: string;
   broadcastsDir?: string;
+  stationDir: string;
   runner: RunnerConfig;
   broadcastRunner: BroadcastRunnerConfig;
   runRunners: boolean;
   open: boolean;
   logLevel: "debug" | "info" | "warn" | "error";
   auth?: AuthConfig;
+  deploy?: DeployConfig;
 }
 
 export type StationUserConfig = Partial<Omit<StationConfig, "runner" | "broadcastRunner">> & {
@@ -41,6 +47,7 @@ export type StationUserConfig = Partial<Omit<StationConfig, "runner" | "broadcas
 const DEFAULTS: StationConfig = {
   port: 4400,
   host: "localhost",
+  stationDir: ".station",
   runner: {
     pollIntervalMs: 1000,
     maxConcurrent: 5,
@@ -56,13 +63,31 @@ const DEFAULTS: StationConfig = {
 };
 
 export function resolveConfig(input: StationUserConfig): StationConfig {
+  const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+  const envHost = process.env.HOST;
+  const envAuthUser = process.env.STATION_AUTH_USERNAME;
+  const envAuthPass = process.env.STATION_AUTH_PASSWORD;
+
+  // Env vars for auth: override config values, or create auth if both are set
+  let auth = input.auth;
+  if (auth) {
+    auth = {
+      ...auth,
+      username: envAuthUser ?? auth.username,
+      password: envAuthPass ?? auth.password,
+    };
+  } else if (envAuthUser && envAuthPass) {
+    auth = { username: envAuthUser, password: envAuthPass };
+  }
+
   return {
-    port: input.port ?? DEFAULTS.port,
-    host: input.host ?? DEFAULTS.host,
+    port: input.port ?? envPort ?? DEFAULTS.port,
+    host: input.host ?? envHost ?? DEFAULTS.host,
     adapter: input.adapter,
     broadcastAdapter: input.broadcastAdapter,
     signalsDir: input.signalsDir,
     broadcastsDir: input.broadcastsDir,
+    stationDir: input.stationDir ?? DEFAULTS.stationDir,
     runner: {
       pollIntervalMs: input.runner?.pollIntervalMs ?? DEFAULTS.runner.pollIntervalMs,
       maxConcurrent: input.runner?.maxConcurrent ?? DEFAULTS.runner.maxConcurrent,
@@ -75,6 +100,7 @@ export function resolveConfig(input: StationUserConfig): StationConfig {
     runRunners: input.runRunners ?? DEFAULTS.runRunners,
     open: input.open ?? DEFAULTS.open,
     logLevel: input.logLevel ?? DEFAULTS.logLevel,
-    auth: input.auth,
+    auth,
+    deploy: input.deploy,
   };
 }

package/src/index.ts

@@ -4,4 +4,6 @@ export function defineConfig(config: StationUserConfig): StationUserConfig {
   return config;
 }
 
-export type { StationConfig, StationUserConfig, AuthConfig } from "./config/schema.js";
+export type { StationConfig, StationUserConfig, AuthConfig, DeployConfig } from "./config/schema.js";
+export { resolveConfig } from "./config/schema.js";
+export { loadConfig } from "./config/loader.js";

package/src/server/index.ts

@@ -9,6 +9,7 @@ import { BroadcastRunner, BroadcastMemoryAdapter } from "station-broadcast";
 import type { SignalQueueAdapter } from "station-signal";
 import type { BroadcastQueueAdapter } from "station-broadcast";
 import type { StationConfig } from "../config/schema.js";
+import { ensureStationDir } from "../station-dir.js";
 import { WebSocketHub } from "./ws.js";
 import { SSEHub } from "./sse.js";
 import { LogBuffer } from "./log-buffer.js";
@@ -32,9 +33,16 @@ import { v1KeyRoutes } from "./routes/v1/keys.js";
 import { v1AuthRoutes } from "./routes/v1/auth.js";
 import { v1EventRoutes } from "./routes/v1/events.js";
 
+export { KeyStore } from "./auth/keys.js";
+export type { ApiKey } from "./auth/keys.js";
+
 export interface StationInstance {
   start(): Promise<void>;
   stop(): Promise<void>;
+  /** The KeyStore instance (available when auth is configured). */
+  keyStore?: KeyStore;
+  /** The resolved data directory path. */
+  dataDir: string;
 }
 
 export async function createStation(config: StationConfig, cwd: string, nextPort?: number): Promise<StationInstance> {
@@ -42,17 +50,19 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   const broadcastAdapter: BroadcastQueueAdapter | undefined =
     config.broadcastAdapter ?? (config.broadcastsDir ? new BroadcastMemoryAdapter() : undefined);
 
+  const { dataDir } = ensureStationDir(cwd, config.stationDir);
+
   const wsHub = new WebSocketHub();
   const sseHub = new SSEHub();
   const logBuffer = new LogBuffer();
-  const logStore = new LogStore(resolve(cwd, "station-logs.db"));
+  const logStore = new LogStore(resolve(dataDir, "station-logs.db"));
 
   // Auth: create KeyStore and SessionConfig if auth is configured
   let keyStore: KeyStore | undefined;
   let sessionConfig: SessionConfig | undefined;
 
   if (config.auth) {
-    keyStore = new KeyStore(resolve(cwd, "station-keys.db"));
+    keyStore = new KeyStore(resolve(dataDir, "station-keys.db"));
     sessionConfig = {
       username: config.auth.username,
       password: config.auth.password,
@@ -288,6 +298,8 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   let httpServer: Server | null = null;
 
   return {
+    keyStore,
+    dataDir,
     async start() {
       // Start runners (non-blocking — they have internal poll loops)
       if (config.runRunners) {

package/src/station-dir.ts

@@ -0,0 +1,24 @@
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+export interface StationDirs {
+  baseDir: string;
+  dataDir: string;
+  outDir: string;
+}
+
+export function ensureStationDir(cwd: string, stationDir: string): StationDirs {
+  const baseDir = resolve(cwd, stationDir);
+  const dataDir = join(baseDir, "data");
+  const outDir = join(baseDir, "out");
+
+  mkdirSync(dataDir, { recursive: true });
+  mkdirSync(outDir, { recursive: true });
+
+  const gitignorePath = join(baseDir, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, "data/\n");
+  }
+
+  return { baseDir, dataDir, outDir };
+}