@whatalo/cli-kit 1.0.0

package/dist/session/index.mjs

@@ -0,0 +1,139 @@
+// src/session/store.ts
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+function getSessionDir() {
+  return path.join(os.homedir(), ".whatalo");
+}
+function getSessionPath() {
+  return path.join(getSessionDir(), "session.json");
+}
+async function saveSession(session) {
+  const dir = getSessionDir();
+  const filePath = getSessionPath();
+  await fs.mkdir(dir, { recursive: true, mode: 448 });
+  await fs.writeFile(filePath, JSON.stringify(session, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+  await fs.chmod(filePath, 384);
+}
+async function getSession() {
+  try {
+    const raw = await fs.readFile(getSessionPath(), { encoding: "utf-8" });
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function clearSession() {
+  try {
+    await fs.unlink(getSessionPath());
+  } catch (err) {
+    const error = err;
+    if (error.code !== "ENOENT") throw err;
+  }
+}
+function isSessionValid(session) {
+  const expiresAt = new Date(session.expiresAt).getTime();
+  const now = Date.now();
+  const SKEW_BUFFER_MS = 6e4;
+  return expiresAt - SKEW_BUFFER_MS > now;
+}
+
+// src/session/types.ts
+var POLL_STATUS = {
+  PENDING: "pending",
+  AUTHORIZED: "authorized",
+  EXPIRED: "expired",
+  DENIED: "denied"
+};
+
+// src/session/device-flow.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function requestDeviceCode(portalUrl) {
+  const res = await fetch(`${portalUrl}/api/auth/device-code`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ clientId: "whatalo-cli" }),
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "Unknown error");
+    throw new Error(`Failed to request device code (${res.status}): ${body}`);
+  }
+  return await res.json();
+}
+async function* pollForToken(portalUrl, deviceCode, initialInterval) {
+  let interval = Math.max(initialInterval, 5);
+  while (true) {
+    await sleep(interval * 1e3);
+    const res = await fetch(`${portalUrl}/api/auth/device-token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        deviceCode,
+        grantType: "urn:ietf:params:oauth:grant-type:device_code"
+      }),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (res.ok) {
+      const data = await res.json();
+      yield { status: POLL_STATUS.AUTHORIZED, token: data };
+      return;
+    }
+    let errorCode = "unknown";
+    try {
+      const errorBody = await res.json();
+      errorCode = errorBody.error ?? "unknown";
+    } catch {
+      yield { status: POLL_STATUS.EXPIRED };
+      return;
+    }
+    switch (errorCode) {
+      case "authorization_pending":
+        yield { status: POLL_STATUS.PENDING };
+        break;
+      case "slow_down":
+        interval += 5;
+        yield { status: POLL_STATUS.PENDING };
+        break;
+      case "expired_token":
+        yield { status: POLL_STATUS.EXPIRED };
+        return;
+      case "access_denied":
+        yield { status: POLL_STATUS.DENIED };
+        return;
+      default:
+        yield { status: POLL_STATUS.EXPIRED };
+        return;
+    }
+  }
+}
+async function refreshAccessToken(portalUrl, refreshToken) {
+  const res = await fetch(`${portalUrl}/api/auth/refresh`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      refreshToken,
+      grantType: "refresh_token"
+    }),
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "Unknown error");
+    throw new Error(`Failed to refresh token (${res.status}): ${body}`);
+  }
+  return await res.json();
+}
+export {
+  POLL_STATUS,
+  clearSession,
+  getSession,
+  getSessionDir,
+  isSessionValid,
+  pollForToken,
+  refreshAccessToken,
+  requestDeviceCode,
+  saveSession
+};

package/dist/tunnel/index.cjs

@@ -0,0 +1,252 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/tunnel/index.ts
+var tunnel_exports = {};
+__export(tunnel_exports, {
+  createTunnel: () => createTunnel,
+  ensureCloudflared: () => ensureCloudflared
+});
+module.exports = __toCommonJS(tunnel_exports);
+
+// src/tunnel/cloudflared.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+var import_node_os = __toESM(require("os"), 1);
+var import_node_https = __toESM(require("https"), 1);
+
+// src/output/format.ts
+var import_chalk = __toESM(require("chalk"), 1);
+function info(message) {
+  console.log(`  ${import_chalk.default.blue("\u2139")} ${message}`);
+}
+var STATUS_ICONS = {
+  pending: import_chalk.default.dim("\u25CB"),
+  running: import_chalk.default.cyan("\u25C9"),
+  success: import_chalk.default.green("\u2713"),
+  error: import_chalk.default.red("\u2717"),
+  warning: import_chalk.default.yellow("\u26A0"),
+  skipped: import_chalk.default.dim("\u2013")
+};
+
+// src/tunnel/cloudflared.ts
+var TUNNEL_START_TIMEOUT_MS = 15e3;
+var TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+function getBinDir() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".whatalo", "bin");
+}
+function getManagedBinaryPath() {
+  return import_node_path.default.join(getBinDir(), "cloudflared");
+}
+function findOnSystemPath() {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  const result = (0, import_node_child_process.spawnSync)(cmd, ["cloudflared"], { encoding: "utf-8" });
+  if (result.status === 0 && result.stdout.trim()) {
+    return result.stdout.trim().split("\n")[0] ?? null;
+  }
+  return null;
+}
+async function ensureCloudflared() {
+  const systemPath = findOnSystemPath();
+  if (systemPath) return systemPath;
+  const managedPath = getManagedBinaryPath();
+  if ((0, import_node_fs.existsSync)(managedPath)) return managedPath;
+  return downloadCloudflared(managedPath);
+}
+function resolvePlatformInfo() {
+  const platform = process.platform;
+  const arch = process.arch === "x64" ? "amd64" : process.arch;
+  if (platform === "darwin") {
+    return { os: "darwin", arch, ext: "tgz" };
+  }
+  if (platform === "linux") {
+    return { os: "linux", arch, ext: "binary" };
+  }
+  throw new Error(
+    `Unsupported platform: ${platform}. Install cloudflared manually: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/`
+  );
+}
+function buildDownloadUrl(osName, arch, ext) {
+  const base = "https://github.com/cloudflare/cloudflared/releases/latest/download";
+  if (ext === "tgz") {
+    return `${base}/cloudflared-${osName}-${arch}.tgz`;
+  }
+  return `${base}/cloudflared-${osName}-${arch}`;
+}
+async function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const follow = (targetUrl) => {
+      import_node_https.default.get(targetUrl, (res) => {
+        if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
+          follow(res.headers.location);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(
+            new Error(
+              `Download failed with HTTP ${res.statusCode}: ${targetUrl}`
+            )
+          );
+          return;
+        }
+        const file = (0, import_node_fs.createWriteStream)(dest);
+        res.pipe(file);
+        file.on("finish", () => file.close(() => resolve()));
+        file.on("error", (err) => {
+          file.close();
+          reject(err);
+        });
+      }).on("error", reject);
+    };
+    follow(url);
+  });
+}
+async function downloadCloudflared(targetPath) {
+  const { os: osName, arch, ext } = resolvePlatformInfo();
+  const downloadUrl = buildDownloadUrl(osName, arch, ext);
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(targetPath), { recursive: true });
+  info(`Downloading cloudflared for ${osName}/${arch}\u2026`);
+  info(`Source: ${downloadUrl}`);
+  const tmpPath = `${targetPath}.tmp`;
+  try {
+    await downloadFile(downloadUrl, tmpPath);
+    if (ext === "tgz") {
+      const tarResult = (0, import_node_child_process.spawnSync)(
+        "tar",
+        ["xzf", tmpPath, "-C", import_node_path.default.dirname(targetPath), "cloudflared"],
+        { encoding: "utf-8" }
+      );
+      if (tarResult.status !== 0) {
+        throw new Error(
+          `tar extraction failed: ${tarResult.stderr || (tarResult.error?.message ?? "unknown error")}`
+        );
+      }
+      await (0, import_promises.unlink)(tmpPath).catch(() => void 0);
+    } else {
+      await (0, import_promises.rename)(tmpPath, targetPath);
+    }
+    if (!(0, import_node_fs.existsSync)(targetPath)) {
+      throw new Error(
+        "Binary extraction completed but cloudflared was not found at the expected path."
+      );
+    }
+    (0, import_node_fs.chmodSync)(targetPath, 493);
+  } catch (err) {
+    await (0, import_promises.unlink)(tmpPath).catch(() => void 0);
+    throw new Error(
+      `Could not download cloudflared. Install manually: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/
+  Original error: ${err.message}`
+    );
+  }
+  info(`cloudflared saved to ${targetPath}`);
+  return targetPath;
+}
+async function createTunnel(options) {
+  const { localPort, protocol = "http" } = options;
+  const binaryPath = await ensureCloudflared();
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)(
+      binaryPath,
+      [
+        "tunnel",
+        "--url",
+        `${protocol}://localhost:${localPort}`,
+        "--no-autoupdate"
+      ],
+      {
+        // Inherit environment so cloudflared can read system certificates
+        env: { ...process.env },
+        // stdout flows to the terminal; stderr is captured for URL extraction
+        stdio: ["ignore", "inherit", "pipe"]
+      }
+    );
+    let urlFound = false;
+    let lineBuffer = "";
+    const timeout = setTimeout(() => {
+      if (!urlFound) {
+        child.kill("SIGTERM");
+        reject(
+          new Error(
+            `Tunnel failed to start. Check if port ${localPort} is accessible.`
+          )
+        );
+      }
+    }, TUNNEL_START_TIMEOUT_MS);
+    child.stderr?.on("data", (chunk) => {
+      lineBuffer += chunk.toString("utf-8");
+      const lines = lineBuffer.split("\n");
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const match = TUNNEL_URL_REGEX.exec(line);
+        if (match && !urlFound) {
+          urlFound = true;
+          clearTimeout(timeout);
+          const tunnelUrl = match[0];
+          const kill = () => new Promise((res) => {
+            if (child.exitCode !== null) {
+              res();
+              return;
+            }
+            child.once("exit", () => res());
+            child.kill("SIGTERM");
+          });
+          resolve({ url: tunnelUrl, process: child, kill });
+        }
+      }
+    });
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      if (!urlFound) {
+        reject(
+          new Error(
+            `Tunnel failed to start. Check if port ${localPort} is accessible.
+  Original error: ${err.message}`
+          )
+        );
+      }
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timeout);
+      if (!urlFound) {
+        reject(
+          new Error(
+            code != null && code !== 0 ? `Could not extract tunnel URL. Try with \`--tunnel-url\` flag.` : `Tunnel failed to start. Check if port ${localPort} is accessible.`
+          )
+        );
+      }
+    });
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createTunnel,
+  ensureCloudflared
+});

package/dist/tunnel/index.d.cts

@@ -0,0 +1,70 @@
+import { ChildProcess } from 'node:child_process';
+
+/** Options for creating a local tunnel */
+interface TunnelOptions {
+    /** Local port to expose */
+    localPort: number;
+    /** Protocol to use for the tunnel connection (default: "http") */
+    protocol?: "http" | "https";
+}
+/**
+ * Represents a running tunnel process.
+ * Consumers must call kill() when done to avoid orphaned processes.
+ */
+interface TunnelProcess {
+    /** The public HTTPS URL assigned by the tunnel provider */
+    url: string;
+    /** Reference to the underlying child process */
+    process: ChildProcess;
+    /** Sends SIGTERM to the process and waits for it to exit */
+    kill(): Promise<void>;
+}
+/** Progress info emitted while downloading the tunnel binary */
+interface TunnelDownloadProgress {
+    platform: string;
+    arch: string;
+    downloadUrl: string;
+    targetPath: string;
+}
+
+/**
+ * Cloudflare tunnel integration for local development.
+ *
+ * Provides two main functions:
+ *  - ensureCloudflared(): resolves or downloads the cloudflared binary
+ *  - createTunnel():      spawns a tunnel and resolves the public URL
+ *
+ * Binary resolution order:
+ *  1. System PATH  (user's global install, resolved via `which`/`where`)
+ *  2. ~/.whatalo/bin/cloudflared  (previously downloaded by the CLI)
+ *  3. Download from GitHub releases → ~/.whatalo/bin/cloudflared
+ *
+ * Note: process-spawning helpers use spawnSync / spawn (not exec/execSync)
+ * to avoid shell interpolation entirely — all arguments are passed as an
+ * array and never concatenated into a shell string.
+ */
+
+/**
+ * Resolves the path to a usable cloudflared binary.
+ *
+ * 1. Checks the system PATH
+ * 2. Checks ~/.whatalo/bin/cloudflared
+ * 3. Downloads the latest release binary for the current platform/arch
+ *
+ * @returns Absolute path to the cloudflared executable
+ * @throws If the binary cannot be found or downloaded
+ */
+declare function ensureCloudflared(): Promise<string>;
+/**
+ * Spawns a cloudflared quick tunnel targeting the given local port.
+ *
+ * Streams stderr line-by-line to detect the assigned public URL.
+ * Resolves once the URL is found or rejects after TUNNEL_START_TIMEOUT_MS.
+ *
+ * @param options - localPort is required; protocol defaults to "http"
+ * @returns A TunnelProcess containing the public URL and a kill() helper
+ * @throws If the process exits before printing a URL, or if startup times out
+ */
+declare function createTunnel(options: TunnelOptions): Promise<TunnelProcess>;
+
+export { type TunnelDownloadProgress, type TunnelOptions, type TunnelProcess, createTunnel, ensureCloudflared };

package/dist/tunnel/index.d.ts

@@ -0,0 +1,70 @@
+import { ChildProcess } from 'node:child_process';
+
+/** Options for creating a local tunnel */
+interface TunnelOptions {
+    /** Local port to expose */
+    localPort: number;
+    /** Protocol to use for the tunnel connection (default: "http") */
+    protocol?: "http" | "https";
+}
+/**
+ * Represents a running tunnel process.
+ * Consumers must call kill() when done to avoid orphaned processes.
+ */
+interface TunnelProcess {
+    /** The public HTTPS URL assigned by the tunnel provider */
+    url: string;
+    /** Reference to the underlying child process */
+    process: ChildProcess;
+    /** Sends SIGTERM to the process and waits for it to exit */
+    kill(): Promise<void>;
+}
+/** Progress info emitted while downloading the tunnel binary */
+interface TunnelDownloadProgress {
+    platform: string;
+    arch: string;
+    downloadUrl: string;
+    targetPath: string;
+}
+
+/**
+ * Cloudflare tunnel integration for local development.
+ *
+ * Provides two main functions:
+ *  - ensureCloudflared(): resolves or downloads the cloudflared binary
+ *  - createTunnel():      spawns a tunnel and resolves the public URL
+ *
+ * Binary resolution order:
+ *  1. System PATH  (user's global install, resolved via `which`/`where`)
+ *  2. ~/.whatalo/bin/cloudflared  (previously downloaded by the CLI)
+ *  3. Download from GitHub releases → ~/.whatalo/bin/cloudflared
+ *
+ * Note: process-spawning helpers use spawnSync / spawn (not exec/execSync)
+ * to avoid shell interpolation entirely — all arguments are passed as an
+ * array and never concatenated into a shell string.
+ */
+
+/**
+ * Resolves the path to a usable cloudflared binary.
+ *
+ * 1. Checks the system PATH
+ * 2. Checks ~/.whatalo/bin/cloudflared
+ * 3. Downloads the latest release binary for the current platform/arch
+ *
+ * @returns Absolute path to the cloudflared executable
+ * @throws If the binary cannot be found or downloaded
+ */
+declare function ensureCloudflared(): Promise<string>;
+/**
+ * Spawns a cloudflared quick tunnel targeting the given local port.
+ *
+ * Streams stderr line-by-line to detect the assigned public URL.
+ * Resolves once the URL is found or rejects after TUNNEL_START_TIMEOUT_MS.
+ *
+ * @param options - localPort is required; protocol defaults to "http"
+ * @returns A TunnelProcess containing the public URL and a kill() helper
+ * @throws If the process exits before printing a URL, or if startup times out
+ */
+declare function createTunnel(options: TunnelOptions): Promise<TunnelProcess>;
+
+export { type TunnelDownloadProgress, type TunnelOptions, type TunnelProcess, createTunnel, ensureCloudflared };