@fevernova90/beckon 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# beckon
+
+> AI-native local tunnels on your own domain. `beckon up` exposes your local dev ports to stable,
+> deterministic public HTTPS URLs — driven from one command (or your AI coding agent).
+
+```bash
+npm i -g @fevernova90/beckon
+```
+
+**Prerequisites:** Node ≥ 20 and a system `ssh` client (built in on macOS/Linux). beckon connects to
+a [sish](https://github.com/antoniomika/sish) edge you control.
+
+## Usage
+
+```bash
+beckon login                 # authenticate in the browser (OAuth); stores a token + your slug
+beckon up                    # read ./tunnel.yaml, open tunnels, print live URLs as JSON
+beckon status                # show live tunnels
+beckon down                  # tear down this repo's tunnels
+```
+
+`beckon login <token>` also works for a pasted token (CI / headless). Override the edge with
+`--edge`, `--ssh-port`, `--base-domain`, or pin a transport key with `--identity`.
+
+### `tunnel.yaml`
+
+```yaml
+app: themebuilder
+tunnels:
+  web:  5173   # → themebuilder-web-<slug>.<base-domain>
+  api:  3000
+  hook: 4000   # webhook receiver — bodies + signature headers pass through byte-exact
+```
+
+Hostnames are a pure function of `{app}-{role}-{slug}`, so a URL is predictable before the tunnel
+starts — write it into `.env` / Clerk / Stripe once.
+
+## License
+
+MIT

package/dist/bin.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { spawn as spawn2 } from "child_process";
+import { Command } from "commander";
+
+// ../core/src/labels.ts
+var LABEL_PART = /^[a-z0-9-]+$/;
+function assertDnsLabelPart(field, value) {
+  if (value.length === 0) {
+    throw new Error(`beckon: ${field} must not be empty`);
+  }
+  if (!LABEL_PART.test(value)) {
+    throw new Error(
+      `beckon: invalid ${field} "${value}" \u2014 must contain only lowercase a-z, 0-9, or hyphen`
+    );
+  }
+  if (value.startsWith("-") || value.endsWith("-")) {
+    throw new Error(`beckon: invalid ${field} "${value}" \u2014 must not start or end with a hyphen`);
+  }
+}
+
+// ../core/src/naming.ts
+var DEFAULT_BASE_DOMAIN = "beckon.gotelz.com";
+function hostnameFor(name, opts) {
+  assertDnsLabelPart("app", name.app);
+  assertDnsLabelPart("role", name.role);
+  assertDnsLabelPart("slug", name.slug);
+  const label = `${name.app}-${name.role}-${name.slug}`;
+  if (label.length > 63) {
+    throw new Error(
+      `beckon: hostname label "${label}" is ${label.length} chars \u2014 DNS labels are limited to 63`
+    );
+  }
+  const baseDomain = opts?.baseDomain ?? DEFAULT_BASE_DOMAIN;
+  return `${label}.${baseDomain}`;
+}
+
+// ../core/src/config.ts
+import { parse } from "yaml";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseTunnelConfig(source) {
+  const raw = parse(source);
+  if (!isRecord(raw)) {
+    throw new Error("beckon: tunnel.yaml must be a mapping with `app` and `tunnels`");
+  }
+  const app = raw["app"];
+  if (typeof app !== "string" || app.length === 0) {
+    throw new Error("beckon: tunnel.yaml is missing a string `app` name");
+  }
+  assertDnsLabelPart("app", app);
+  const tunnelsRaw = raw["tunnels"];
+  if (!isRecord(tunnelsRaw) || Object.keys(tunnelsRaw).length === 0) {
+    throw new Error("beckon: tunnel.yaml must define at least one entry under `tunnels`");
+  }
+  const tunnels = Object.entries(tunnelsRaw).map(([role, port]) => {
+    assertDnsLabelPart("role", role);
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error(
+        `beckon: tunnel "${role}" has an invalid port ${JSON.stringify(port)} \u2014 must be an integer 1..65535`
+      );
+    }
+    return { role, port };
+  });
+  return { app, tunnels };
+}
+
+// ../core/src/plan.ts
+function planTunnels(config, opts) {
+  return config.tunnels.map((tunnel) => {
+    const hostname = hostnameFor(
+      { app: config.app, role: tunnel.role, slug: opts.slug },
+      { baseDomain: opts.baseDomain }
+    );
+    return { role: tunnel.role, port: tunnel.port, hostname, url: `https://${hostname}` };
+  });
+}
+
+// ../core/src/token.ts
+import { randomBytes, createHash, timingSafeEqual } from "crypto";
+
+// src/settings.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+var FILE = "config.json";
+function settingsDir(env, home) {
+  const xdg = env["XDG_CONFIG_HOME"];
+  const base = xdg && xdg.length > 0 ? xdg : join(home, ".config");
+  return join(base, "beckon");
+}
+function readSettings(dir) {
+  const path = join(dir, FILE);
+  if (!existsSync(path)) {
+    return {};
+  }
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function writeSettings(dir, settings) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, FILE), `${JSON.stringify(settings, null, 2)}
+`, { mode: 384 });
+}
+function resolveToken(env, settings) {
+  return env["BECKON_TOKEN"] ?? settings.token;
+}
+
+// src/state.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
+import { dirname } from "path";
+function readState(path) {
+  if (!existsSync2(path)) {
+    return {};
+  }
+  return JSON.parse(readFileSync2(path, "utf8"));
+}
+function writeState(path, state) {
+  mkdirSync2(dirname(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(state, null, 2)}
+`, { mode: 384 });
+}
+function putApp(state, entry) {
+  return { ...state, [entry.app]: entry };
+}
+function removeApp(state, app) {
+  const next = { ...state };
+  delete next[app];
+  return next;
+}
+
+// src/ssh.ts
+function buildSshArgs(conn, forwards) {
+  const args = ["-p", String(conn.port)];
+  if (conn.identityFile) {
+    args.push("-i", conn.identityFile, "-o", "IdentitiesOnly=yes");
+  }
+  args.push(
+    "-o",
+    "ExitOnForwardFailure=yes",
+    "-o",
+    "ServerAliveInterval=15",
+    "-o",
+    "ServerAliveCountMax=3",
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    "-o",
+    "BatchMode=yes"
+  );
+  for (const forward of forwards) {
+    args.push("-R", `${forward.label}:${forward.remotePort}:localhost:${forward.localPort}`);
+  }
+  args.push(`${conn.token}@${conn.edgeHost}`);
+  return args;
+}
+
+// src/supervisor.ts
+var defaultSchedule = (cb, ms) => {
+  setTimeout(cb, ms);
+};
+function supervise(opts) {
+  const schedule = opts.schedule ?? defaultSchedule;
+  const backoff = opts.backoffMs ?? 1e3;
+  let stopped = false;
+  let restarts = 0;
+  let current = null;
+  function start() {
+    current = opts.spawn();
+    current.once("exit", () => {
+      if (stopped) {
+        return;
+      }
+      restarts += 1;
+      opts.onRestart?.(restarts);
+      schedule(start, backoff);
+    });
+  }
+  start();
+  return {
+    stop() {
+      stopped = true;
+      current?.kill();
+    },
+    get restarts() {
+      return restarts;
+    },
+    get pid() {
+      return current?.pid;
+    }
+  };
+}
+
+// src/loopback.ts
+import http from "http";
+import { randomBytes as randomBytes2 } from "crypto";
+import { spawn } from "child_process";
+function parseCallback(reqUrl, expectedState) {
+  const url = new URL(reqUrl, "http://127.0.0.1");
+  if (url.searchParams.get("state") !== expectedState) {
+    return { ok: false, error: "state mismatch" };
+  }
+  const error = url.searchParams.get("error");
+  if (error) {
+    return { ok: false, error };
+  }
+  const token = url.searchParams.get("token");
+  if (!token) {
+    return { ok: false, error: "no token in callback" };
+  }
+  return { ok: true, token, slug: url.searchParams.get("slug") ?? void 0 };
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+function loopbackLogin(opts) {
+  const state = randomBytes2(16).toString("hex");
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const result = parseCallback(req.url ?? "/", state);
+      res.writeHead(result.ok ? 200 : 400, { "content-type": "text/html" });
+      res.end(
+        `<!doctype html><meta charset=utf-8><body style="font-family:system-ui;padding:3rem;text-align:center">` + (result.ok ? "<h2>beckon: you're logged in \u2713</h2>" : `<h2>beckon login failed</h2><p>${result.error ?? ""}</p>`) + "<p>You can close this tab and return to the terminal.</p>"
+      );
+      server.close();
+      resolve(result);
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      const authorizeUrl = new URL("/cli/authorize", opts.dashboardUrl);
+      authorizeUrl.searchParams.set("port", String(port));
+      authorizeUrl.searchParams.set("state", state);
+      if (opts.slug) {
+        authorizeUrl.searchParams.set("slug", opts.slug);
+      }
+      opts.onAuthorizeUrl(authorizeUrl.toString());
+      openBrowser(authorizeUrl.toString());
+    });
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("login timed out after waiting for the browser"));
+    }, opts.timeoutMs ?? 12e4);
+    server.on("close", () => clearTimeout(timer));
+  });
+}
+
+// src/bin.ts
+var DEFAULT_EDGE = "edge.beckon.gotelz.com";
+var DEFAULT_SSH_PORT = 2222;
+var DEFAULT_DASHBOARD = process.env.BECKON_DASHBOARD_URL ?? "https://web-production-60e7b.up.railway.app";
+function fail(message) {
+  process.stderr.write(`beckon: ${message}
+`);
+  process.exit(1);
+}
+function configDir() {
+  return settingsDir(process.env, homedir());
+}
+function loadSettings() {
+  return readSettings(configDir());
+}
+function loadTunnelConfig() {
+  const path = join2(process.cwd(), "tunnel.yaml");
+  if (!existsSync3(path)) {
+    fail("no tunnel.yaml in this directory \u2014 see tunnel.yaml.example");
+  }
+  return parseTunnelConfig(readFileSync3(path, "utf8"));
+}
+function planFor(settings) {
+  const config = loadTunnelConfig();
+  const slug = settings.slug;
+  if (!slug) {
+    fail("no slug configured \u2014 run `beckon login <token> --slug <handle>`");
+  }
+  return { app: config.app, slug, plan: planTunnels(config, { slug, baseDomain: settings.baseDomain }) };
+}
+function urlsJson(app, plan) {
+  return Object.fromEntries(plan.map((t) => [`${app}-${t.role}`, t.url]));
+}
+var program = new Command();
+program.name("beckon").description("AI-native local tunnels on your own domain").version("0.1.0");
+program.command("login").description("authenticate via the browser (OAuth); or pass a token to store it directly").argument("[token]", "beckon token (bk_live_\u2026); omit to log in through the browser").option("--slug <handle>", "hostname slug (provisions it on first browser login)").option("--edge <host>", "sish edge host", DEFAULT_EDGE).option("--ssh-port <port>", "sish ssh port", String(DEFAULT_SSH_PORT)).option("--base-domain <domain>", "wildcard base domain").option("--identity <file>", "ssh identity file").option("--dashboard <url>", "beckon dashboard URL", DEFAULT_DASHBOARD).action(async (token, opts) => {
+  const dir = configDir();
+  const applyCommon = (s) => {
+    if (opts["edge"]) s.edgeHost = opts["edge"];
+    if (opts["sshPort"]) s.sshPort = Number(opts["sshPort"]);
+    if (opts["baseDomain"]) s.baseDomain = opts["baseDomain"];
+    if (opts["identity"]) s.identityFile = opts["identity"];
+    return s;
+  };
+  if (token) {
+    const next2 = applyCommon({ ...readSettings(dir), token });
+    if (opts["slug"]) next2.slug = opts["slug"];
+    writeSettings(dir, next2);
+    process.stdout.write(`beckon: saved credentials to ${join2(dir, "config.json")}
+`);
+    return;
+  }
+  process.stdout.write("beckon: opening your browser to authenticate\u2026\n");
+  const result = await loopbackLogin({
+    dashboardUrl: opts["dashboard"] ?? DEFAULT_DASHBOARD,
+    slug: opts["slug"],
+    onAuthorizeUrl: (url) => process.stdout.write(`  if it doesn't open, visit:
+  ${url}
+`)
+  });
+  if (!result.ok || !result.token) {
+    if (result.error === "no_slug") {
+      fail("no slug yet \u2014 run `beckon login --slug <handle>` to provision it in one step");
+    }
+    fail(`login failed: ${result.error ?? "unknown error"}`);
+  }
+  const next = applyCommon({ ...readSettings(dir), token: result.token });
+  if (result.slug) next.slug = result.slug;
+  else if (opts["slug"]) next.slug = opts["slug"];
+  writeSettings(dir, next);
+  process.stdout.write(`beckon: logged in${next.slug ? ` as "${next.slug}"` : ""} \u2713
+`);
+});
+program.command("up").description("open this repo's tunnels (reads ./tunnel.yaml)").option("--dry-run", "print the URLs without opening tunnels").action((opts) => {
+  const settings = loadSettings();
+  const { app, slug, plan } = planFor(settings);
+  process.stdout.write(`${JSON.stringify(urlsJson(app, plan), null, 2)}
+`);
+  if (opts.dryRun) {
+    return;
+  }
+  const token = resolveToken(process.env, settings);
+  if (!token) {
+    fail("no token \u2014 run `beckon login <token>` or set BECKON_TOKEN");
+  }
+  const edgeHost = settings.edgeHost ?? DEFAULT_EDGE;
+  const port = settings.sshPort ?? DEFAULT_SSH_PORT;
+  const forwards = plan.map((t) => ({
+    label: `${app}-${t.role}-${slug}`,
+    remotePort: 80,
+    localPort: t.port
+  }));
+  const args = buildSshArgs({ edgeHost, port, token, identityFile: settings.identityFile }, forwards);
+  const spawnSsh = () => {
+    const child = spawn2("ssh", args, { stdio: ["ignore", "ignore", "inherit"] });
+    return {
+      pid: child.pid,
+      once: (event, cb) => child.once(event, () => cb()),
+      kill: (signal) => {
+        child.kill(signal);
+      }
+    };
+  };
+  const sup = supervise({ spawn: spawnSsh });
+  const statePath = join2(configDir(), "state.json");
+  writeState(
+    statePath,
+    putApp(readState(statePath), {
+      app,
+      slug,
+      pid: process.pid,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tunnels: plan.map((t) => ({ role: t.role, port: t.port, url: t.url }))
+    })
+  );
+  const shutdown = () => {
+    sup.stop();
+    writeState(statePath, removeApp(readState(statePath), app));
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+});
+program.command("status").description("show live tunnels").option("--json", "output JSON").action((opts) => {
+  const state = readState(join2(configDir(), "state.json"));
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(state, null, 2)}
+`);
+    return;
+  }
+  const rows = Object.values(state);
+  if (rows.length === 0) {
+    process.stdout.write("no active tunnels\n");
+    return;
+  }
+  for (const entry of rows) {
+    process.stdout.write(`${entry.app} (pid ${entry.pid}, since ${entry.startedAt})
+`);
+    for (const t of entry.tunnels) {
+      process.stdout.write(`  ${t.role.padEnd(8)} :${t.port} \u2192 ${t.url}
+`);
+    }
+  }
+});
+program.command("down").description("tear down this repo's tunnels").action(() => {
+  const config = loadTunnelConfig();
+  const statePath = join2(configDir(), "state.json");
+  const state = readState(statePath);
+  const entry = state[config.app];
+  if (!entry) {
+    process.stdout.write(`beckon: no active tunnels for "${config.app}"
+`);
+    return;
+  }
+  try {
+    process.kill(entry.pid, "SIGTERM");
+  } catch {
+  }
+  writeState(statePath, removeApp(state, config.app));
+  process.stdout.write(`beckon: stopped "${config.app}"
+`);
+});
+program.parseAsync(process.argv).catch((err) => {
+  fail(err instanceof Error ? err.message : String(err));
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@fevernova90/beckon",
+  "version": "0.1.0",
+  "description": "AI-native local tunnels on your own domain — the beckon CLI",
+  "type": "module",
+  "bin": {
+    "beckon": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "tunnel",
+    "localhost",
+    "ssh",
+    "ngrok-alternative",
+    "sish",
+    "cli",
+    "webhooks"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "@beckon/core": "0.0.0"
+  },
+  "scripts": {
+    "beckon": "tsx src/bin.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}