@whatalo/cli-kit 1.0.0

package/dist/tunnel/index.mjs

@@ -0,0 +1,214 @@
+// src/tunnel/cloudflared.ts
+import { spawnSync, spawn } from "child_process";
+import { existsSync, chmodSync, mkdirSync, createWriteStream } from "fs";
+import { unlink, rename } from "fs/promises";
+import path from "path";
+import os from "os";
+import https from "https";
+
+// src/output/format.ts
+import chalk from "chalk";
+function info(message) {
+  console.log(`  ${chalk.blue("\u2139")} ${message}`);
+}
+var STATUS_ICONS = {
+  pending: chalk.dim("\u25CB"),
+  running: chalk.cyan("\u25C9"),
+  success: chalk.green("\u2713"),
+  error: chalk.red("\u2717"),
+  warning: chalk.yellow("\u26A0"),
+  skipped: chalk.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 path.join(os.homedir(), ".whatalo", "bin");
+}
+function getManagedBinaryPath() {
+  return path.join(getBinDir(), "cloudflared");
+}
+function findOnSystemPath() {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  const result = 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 (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) => {
+      https.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 = 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);
+  mkdirSync(path.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 = spawnSync(
+        "tar",
+        ["xzf", tmpPath, "-C", path.dirname(targetPath), "cloudflared"],
+        { encoding: "utf-8" }
+      );
+      if (tarResult.status !== 0) {
+        throw new Error(
+          `tar extraction failed: ${tarResult.stderr || (tarResult.error?.message ?? "unknown error")}`
+        );
+      }
+      await unlink(tmpPath).catch(() => void 0);
+    } else {
+      await rename(tmpPath, targetPath);
+    }
+    if (!existsSync(targetPath)) {
+      throw new Error(
+        "Binary extraction completed but cloudflared was not found at the expected path."
+      );
+    }
+    chmodSync(targetPath, 493);
+  } catch (err) {
+    await 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 = 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.`
+          )
+        );
+      }
+    });
+  });
+}
+export {
+  createTunnel,
+  ensureCloudflared
+};

package/dist/types-DunvRQ0f.d.cts

@@ -0,0 +1,63 @@
+/**
+ * Represents a persisted developer authentication session.
+ * Stored at ~/.whatalo/session.json
+ */
+interface WhataloSession {
+    accessToken: string;
+    refreshToken: string;
+    /** ISO 8601 expiry timestamp */
+    expiresAt: string;
+    /** developer_profiles.id (UUID) */
+    developerId: string;
+    email: string;
+    /** URL of the Developer Portal that issued the tokens */
+    portalUrl: string;
+}
+/**
+ * Response from the device authorization endpoint.
+ * Returned when initiating the Device Authorization Grant (RFC 8628).
+ */
+interface DeviceCodeResponse {
+    deviceCode: string;
+    /** Short user-facing code to enter at the verification URI */
+    userCode: string;
+    verificationUri: string;
+    /** Lifetime of the device code in seconds */
+    expiresIn: number;
+    /** Minimum polling interval in seconds (never poll faster than this) */
+    interval: number;
+}
+/**
+ * Token payload returned by the authorization server after successful device grant.
+ */
+interface TokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Lifetime of the access token in seconds */
+    expiresIn: number;
+    /** developer_profiles.id (UUID) */
+    developerId: string;
+    email: string;
+}
+/**
+ * Discriminated union for each poll attempt during the Device Authorization Grant.
+ */
+declare const POLL_STATUS: {
+    readonly PENDING: "pending";
+    readonly AUTHORIZED: "authorized";
+    readonly EXPIRED: "expired";
+    readonly DENIED: "denied";
+};
+type PollStatus = (typeof POLL_STATUS)[keyof typeof POLL_STATUS];
+type PollResult = {
+    status: typeof POLL_STATUS.PENDING;
+} | {
+    status: typeof POLL_STATUS.AUTHORIZED;
+    token: TokenResponse;
+} | {
+    status: typeof POLL_STATUS.EXPIRED;
+} | {
+    status: typeof POLL_STATUS.DENIED;
+};
+
+export { type DeviceCodeResponse as D, type PollResult as P, type TokenResponse as T, type WhataloSession as W, type PollStatus as a, POLL_STATUS as b };

package/dist/types-DunvRQ0f.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Represents a persisted developer authentication session.
+ * Stored at ~/.whatalo/session.json
+ */
+interface WhataloSession {
+    accessToken: string;
+    refreshToken: string;
+    /** ISO 8601 expiry timestamp */
+    expiresAt: string;
+    /** developer_profiles.id (UUID) */
+    developerId: string;
+    email: string;
+    /** URL of the Developer Portal that issued the tokens */
+    portalUrl: string;
+}
+/**
+ * Response from the device authorization endpoint.
+ * Returned when initiating the Device Authorization Grant (RFC 8628).
+ */
+interface DeviceCodeResponse {
+    deviceCode: string;
+    /** Short user-facing code to enter at the verification URI */
+    userCode: string;
+    verificationUri: string;
+    /** Lifetime of the device code in seconds */
+    expiresIn: number;
+    /** Minimum polling interval in seconds (never poll faster than this) */
+    interval: number;
+}
+/**
+ * Token payload returned by the authorization server after successful device grant.
+ */
+interface TokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Lifetime of the access token in seconds */
+    expiresIn: number;
+    /** developer_profiles.id (UUID) */
+    developerId: string;
+    email: string;
+}
+/**
+ * Discriminated union for each poll attempt during the Device Authorization Grant.
+ */
+declare const POLL_STATUS: {
+    readonly PENDING: "pending";
+    readonly AUTHORIZED: "authorized";
+    readonly EXPIRED: "expired";
+    readonly DENIED: "denied";
+};
+type PollStatus = (typeof POLL_STATUS)[keyof typeof POLL_STATUS];
+type PollResult = {
+    status: typeof POLL_STATUS.PENDING;
+} | {
+    status: typeof POLL_STATUS.AUTHORIZED;
+    token: TokenResponse;
+} | {
+    status: typeof POLL_STATUS.EXPIRED;
+} | {
+    status: typeof POLL_STATUS.DENIED;
+};
+
+export { type DeviceCodeResponse as D, type PollResult as P, type TokenResponse as T, type WhataloSession as W, type PollStatus as a, POLL_STATUS as b };

package/dist/version/index.cjs

@@ -0,0 +1,204 @@
+"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/version/index.ts
+var version_exports = {};
+__export(version_exports, {
+  checkSdkCompatibility: () => checkSdkCompatibility,
+  getUpgradeCommand: () => getUpgradeCommand,
+  isNewerVersion: () => isNewerVersion,
+  scheduleVersionCheck: () => scheduleVersionCheck
+});
+module.exports = __toCommonJS(version_exports);
+
+// src/version/check.ts
+var import_promises2 = require("fs/promises");
+var import_node_path2 = __toESM(require("path"), 1);
+var import_chalk = __toESM(require("chalk"), 1);
+
+// src/session/store.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+function getSessionDir() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".whatalo");
+}
+
+// src/version/check.ts
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REGISTRY_TIMEOUT_MS = 3e3;
+function getCachePath() {
+  return import_node_path2.default.join(getSessionDir(), "version-check.json");
+}
+async function readCache() {
+  try {
+    const raw = await (0, import_promises2.readFile)(getCachePath(), "utf-8");
+    const cache = JSON.parse(raw);
+    const lastCheck = new Date(cache.lastCheck).getTime();
+    if (Date.now() - lastCheck < CHECK_INTERVAL_MS) {
+      return cache;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeCache(cache) {
+  try {
+    const dir = getSessionDir();
+    await (0, import_promises2.mkdir)(dir, { recursive: true, mode: 448 });
+    await (0, import_promises2.writeFile)(getCachePath(), JSON.stringify(cache, null, 2), "utf-8");
+  } catch {
+  }
+}
+async function fetchLatestVersion(packageName) {
+  try {
+    const res = await fetch(
+      `https://registry.npmjs.org/${packageName}/latest`,
+      { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) }
+    );
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isNewerVersion(current, latest) {
+  const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+  const c = parse(current);
+  const l = parse(latest);
+  for (let i = 0; i < 3; i++) {
+    if ((l[i] ?? 0) > (c[i] ?? 0)) return true;
+    if ((l[i] ?? 0) < (c[i] ?? 0)) return false;
+  }
+  return false;
+}
+function getUpgradeCommand() {
+  const pm = detectPackageManager();
+  switch (pm) {
+    case "pnpm":
+      return "pnpm add -g @whatalo/cli";
+    case "yarn":
+      return "yarn global add @whatalo/cli";
+    case "npm":
+      return "npm install -g @whatalo/cli";
+  }
+}
+function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  if (userAgent.includes("pnpm")) return "pnpm";
+  if (userAgent.includes("yarn")) return "yarn";
+  if (userAgent.includes("npm")) return "npm";
+  return "pnpm";
+}
+function scheduleVersionCheck(currentVersion) {
+  const checkPromise = (async () => {
+    const cached = await readCache();
+    if (cached && cached.currentVersion === currentVersion) {
+      return cached.latestVersion !== currentVersion && isNewerVersion(currentVersion, cached.latestVersion) ? cached.latestVersion : null;
+    }
+    const latestVersion = await fetchLatestVersion("@whatalo/cli");
+    if (!latestVersion) return null;
+    await writeCache({
+      lastCheck: (/* @__PURE__ */ new Date()).toISOString(),
+      latestVersion,
+      currentVersion
+    });
+    return isNewerVersion(currentVersion, latestVersion) ? latestVersion : null;
+  })();
+  process.on("exit", () => {
+    checkPromise.then((latestVersion) => {
+      if (!latestVersion) return;
+      const upgradeCmd = getUpgradeCommand();
+      const box = [
+        "",
+        import_chalk.default.yellow("\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"),
+        import_chalk.default.yellow("\u2502                                          \u2502"),
+        import_chalk.default.yellow("\u2502") + `   Update available: ${import_chalk.default.dim(currentVersion)} ${import_chalk.default.yellow("\u2192")} ${import_chalk.default.green(latestVersion)}       ` + import_chalk.default.yellow("\u2502"),
+        import_chalk.default.yellow("\u2502") + `   Run: ${import_chalk.default.cyan(upgradeCmd)}          ` + import_chalk.default.yellow("\u2502"),
+        import_chalk.default.yellow("\u2502                                          \u2502"),
+        import_chalk.default.yellow("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"),
+        ""
+      ];
+      for (const line of box) {
+        process.stderr.write(line + "\n");
+      }
+    }).catch(() => {
+    });
+  });
+}
+
+// src/version/compatibility.ts
+var import_node_fs = require("fs");
+var import_node_path3 = __toESM(require("path"), 1);
+function checkSdkCompatibility(cliVersion, projectDir) {
+  const sdkVersion = getSdkVersion(projectDir);
+  if (!sdkVersion) return null;
+  const cliMajor = parseMajor(cliVersion);
+  const sdkMajor = parseMajor(sdkVersion);
+  if (cliMajor !== sdkMajor) {
+    return `SDK version ${sdkVersion} may not be compatible with CLI ${cliVersion}. Run: pnpm update @whatalo/app-sdk`;
+  }
+  const cliMinor = parseMinor(cliVersion);
+  const sdkMinor = parseMinor(sdkVersion);
+  if (cliMinor - sdkMinor > 1) {
+    return `SDK version ${sdkVersion} is behind CLI ${cliVersion}. Run: pnpm update @whatalo/app-sdk`;
+  }
+  return null;
+}
+function getSdkVersion(projectDir) {
+  try {
+    const pkgPath = import_node_path3.default.join(
+      projectDir,
+      "node_modules",
+      "@whatalo",
+      "app-sdk",
+      "package.json"
+    );
+    const raw = (0, import_node_fs.readFileSync)(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw);
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function parseMajor(version) {
+  return parseInt(version.replace(/^v/, "").split(".")[0] ?? "0", 10);
+}
+function parseMinor(version) {
+  return parseInt(version.replace(/^v/, "").split(".")[1] ?? "0", 10);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkSdkCompatibility,
+  getUpgradeCommand,
+  isNewerVersion,
+  scheduleVersionCheck
+});

package/dist/version/index.d.cts

@@ -0,0 +1,41 @@
+/**
+ * Non-blocking CLI version check against the npm registry.
+ * Displays an update notice AFTER the command completes, never blocks execution.
+ *
+ * Cached to ~/.whatalo/version-check.json with a 24-hour TTL.
+ */
+interface VersionCheckResult {
+    updateAvailable: boolean;
+    currentVersion: string;
+    latestVersion: string;
+    upgradeCommand: string;
+}
+/**
+ * Compares two semver version strings.
+ * Returns true if `latest` is newer than `current`.
+ */
+declare function isNewerVersion(current: string, latest: string): boolean;
+/**
+ * Detects how the CLI was installed and returns the correct upgrade command.
+ */
+declare function getUpgradeCommand(): string;
+/**
+ * Fire-and-forget version check. Displays an update notice AFTER the command
+ * completes by registering a process.on("exit") handler.
+ *
+ * NEVER blocks command execution. Errors are silently ignored.
+ */
+declare function scheduleVersionCheck(currentVersion: string): void;
+
+/**
+ * SDK version compatibility checker.
+ * Compares the installed @whatalo/app-sdk version against the CLI version
+ * and returns a warning if they are potentially incompatible.
+ */
+/**
+ * Checks if the installed @whatalo/app-sdk version is compatible with the CLI.
+ * Returns a warning message or null if compatible.
+ */
+declare function checkSdkCompatibility(cliVersion: string, projectDir: string): string | null;
+
+export { type VersionCheckResult, checkSdkCompatibility, getUpgradeCommand, isNewerVersion, scheduleVersionCheck };

package/dist/version/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Non-blocking CLI version check against the npm registry.
+ * Displays an update notice AFTER the command completes, never blocks execution.
+ *
+ * Cached to ~/.whatalo/version-check.json with a 24-hour TTL.
+ */
+interface VersionCheckResult {
+    updateAvailable: boolean;
+    currentVersion: string;
+    latestVersion: string;
+    upgradeCommand: string;
+}
+/**
+ * Compares two semver version strings.
+ * Returns true if `latest` is newer than `current`.
+ */
+declare function isNewerVersion(current: string, latest: string): boolean;
+/**
+ * Detects how the CLI was installed and returns the correct upgrade command.
+ */
+declare function getUpgradeCommand(): string;
+/**
+ * Fire-and-forget version check. Displays an update notice AFTER the command
+ * completes by registering a process.on("exit") handler.
+ *
+ * NEVER blocks command execution. Errors are silently ignored.
+ */
+declare function scheduleVersionCheck(currentVersion: string): void;
+
+/**
+ * SDK version compatibility checker.
+ * Compares the installed @whatalo/app-sdk version against the CLI version
+ * and returns a warning if they are potentially incompatible.
+ */
+/**
+ * Checks if the installed @whatalo/app-sdk version is compatible with the CLI.
+ * Returns a warning message or null if compatible.
+ */
+declare function checkSdkCompatibility(cliVersion: string, projectDir: string): string | null;
+
+export { type VersionCheckResult, checkSdkCompatibility, getUpgradeCommand, isNewerVersion, scheduleVersionCheck };