@whatalo/cli-kit 1.0.0

package/dist/output/index.mjs

@@ -0,0 +1,221 @@
+// src/output/format.ts
+import chalk from "chalk";
+function banner(title, version) {
+  console.log();
+  console.log(`  ${chalk.bold.cyan(title)} ${chalk.dim(`v${version}`)}`);
+  console.log();
+}
+function success(message) {
+  console.log(`  ${chalk.green("\u2713")} ${message}`);
+}
+function error(message) {
+  console.log(`  ${chalk.red("\u2717")} ${message}`);
+}
+function warn(message) {
+  console.log(`  ${chalk.yellow("\u26A0")} ${message}`);
+}
+function info(message) {
+  console.log(`  ${chalk.blue("\u2139")} ${message}`);
+}
+function link(url) {
+  return chalk.underline.cyan(url);
+}
+function code(text) {
+  return chalk.dim("`") + chalk.bold(text) + chalk.dim("`");
+}
+function table(headers, rows) {
+  if (headers.length === 0) return;
+  const widths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const headerLine = headers.map((h, i) => h.padEnd(widths[i] ?? h.length)).join("  ");
+  console.log(`  ${chalk.bold(headerLine)}`);
+  const separator = widths.map((w) => "\u2500".repeat(w)).join("  ");
+  console.log(`  ${separator}`);
+  for (const row of rows) {
+    const line = row.map((cell, i) => cell.padEnd(widths[i] ?? cell.length)).join("  ");
+    console.log(`  ${line}`);
+  }
+}
+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")
+};
+function renderTasks(tasks) {
+  for (const task of tasks) {
+    const icon = STATUS_ICONS[task.status];
+    const label = task.status === "error" ? chalk.red(task.label) : task.status === "warning" ? chalk.yellow(task.label) : task.status === "skipped" ? chalk.dim(task.label) : task.label;
+    console.log(`  ${icon} ${label}`);
+    if (task.detail) {
+      console.log(`    ${chalk.dim(task.detail)}`);
+    }
+  }
+}
+function renderInfoPanel(title, sections) {
+  console.log();
+  console.log(`  ${chalk.bold(title)}`);
+  console.log(`  ${"\u2550".repeat(title.length)}`);
+  for (const section of sections) {
+    console.log();
+    console.log(`  ${chalk.bold.dim(section.heading)}`);
+    const maxKeyLen = Math.max(...section.rows.map((r) => r.key.length));
+    for (const row of section.rows) {
+      console.log(
+        `    ${chalk.dim(row.key.padEnd(maxKeyLen))}  ${row.value}`
+      );
+    }
+  }
+  console.log();
+}
+function renderTable(options) {
+  table(options.headers, options.rows);
+}
+
+// src/output/spinner.ts
+import chalk2 from "chalk";
+var SPINNER_FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
+var FRAME_INTERVAL_MS = 100;
+function createSpinner(message) {
+  let frameIndex = 0;
+  let stopped = false;
+  const timer = setInterval(() => {
+    if (stopped) return;
+    const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+    process.stdout.write(`\x1B[2K\r  ${chalk2.magenta(frame)} ${message}`);
+    frameIndex++;
+  }, FRAME_INTERVAL_MS);
+  const firstFrame = SPINNER_FRAMES[0];
+  process.stdout.write(`  ${chalk2.magenta(firstFrame)} ${message}`);
+  return {
+    stop(finalMessage) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.stdout.write(`\x1B[2K\r`);
+      if (finalMessage) {
+        console.log(`  ${chalk2.green("\u2713")} ${finalMessage}`);
+      }
+    }
+  };
+}
+
+// src/output/errors.ts
+var WhataloAuthError = class extends Error {
+  constructor(message = "Authentication required") {
+    super(message);
+    this.name = "WhataloAuthError";
+  }
+};
+var WhataloConfigError = class extends Error {
+  suggestion;
+  constructor(message, suggestion) {
+    super(message);
+    this.name = "WhataloConfigError";
+    this.suggestion = suggestion;
+  }
+};
+var WhataloNetworkError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "WhataloNetworkError";
+    this.statusCode = statusCode;
+  }
+};
+var WhataloValidationError = class extends Error {
+  field;
+  constructor(message, field) {
+    super(message);
+    this.name = "WhataloValidationError";
+    this.field = field;
+  }
+};
+
+// src/output/error-handler.ts
+function withErrorHandler(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      handleCliError(err);
+    }
+  };
+}
+function handleCliError(error2) {
+  if (error2 instanceof WhataloAuthError) {
+    error(error2.message);
+    info("Run `whatalo login` to re-authenticate.");
+    process.exit(1);
+  }
+  if (error2 instanceof WhataloConfigError) {
+    error(error2.message);
+    if (error2.suggestion) {
+      info(`Fix: ${error2.suggestion}`);
+    }
+    process.exit(2);
+  }
+  if (error2 instanceof WhataloNetworkError) {
+    error("Could not connect to Whatalo API.");
+    if (error2.statusCode === 429) {
+      warn("Rate limit reached. Wait a moment and try again.");
+    } else {
+      info("Check your internet connection and try again.");
+    }
+    if (error2.message && error2.message !== "Could not connect to Whatalo API.") {
+      info(`Details: ${error2.message}`);
+    }
+    process.exit(1);
+  }
+  if (error2 instanceof WhataloValidationError) {
+    error(error2.message);
+    if (error2.field) {
+      info(`Field: ${error2.field}`);
+    }
+    process.exit(1);
+  }
+  error("An unexpected error occurred.");
+  if (error2 instanceof Error) {
+    info(`Details: ${error2.message}`);
+  }
+  info(
+    "If this persists, run `whatalo info --json` and report the issue."
+  );
+  process.exit(1);
+}
+
+// src/output/non-tty.ts
+function failMissingNonTTYFlags(requiredFlags, options) {
+  if (process.stdout.isTTY) return;
+  const missing = requiredFlags.filter((flag) => !options[flag]);
+  if (missing.length > 0) {
+    throw new WhataloValidationError(
+      `${missing.map((f) => `--${f}`).join(", ")} required in non-interactive environments (CI/CD).`,
+      missing[0]
+    );
+  }
+}
+export {
+  WhataloAuthError,
+  WhataloConfigError,
+  WhataloNetworkError,
+  WhataloValidationError,
+  banner,
+  code,
+  createSpinner,
+  error,
+  failMissingNonTTYFlags,
+  handleCliError,
+  info,
+  link,
+  renderInfoPanel,
+  renderTable,
+  renderTasks,
+  success,
+  table,
+  warn,
+  withErrorHandler
+};

package/dist/session/index.cjs

@@ -0,0 +1,184 @@
+"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/session/index.ts
+var session_exports = {};
+__export(session_exports, {
+  POLL_STATUS: () => POLL_STATUS,
+  clearSession: () => clearSession,
+  getSession: () => getSession,
+  getSessionDir: () => getSessionDir,
+  isSessionValid: () => isSessionValid,
+  pollForToken: () => pollForToken,
+  refreshAccessToken: () => refreshAccessToken,
+  requestDeviceCode: () => requestDeviceCode,
+  saveSession: () => saveSession
+});
+module.exports = __toCommonJS(session_exports);
+
+// 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");
+}
+function getSessionPath() {
+  return import_node_path.default.join(getSessionDir(), "session.json");
+}
+async function saveSession(session) {
+  const dir = getSessionDir();
+  const filePath = getSessionPath();
+  await import_promises.default.mkdir(dir, { recursive: true, mode: 448 });
+  await import_promises.default.writeFile(filePath, JSON.stringify(session, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+  await import_promises.default.chmod(filePath, 384);
+}
+async function getSession() {
+  try {
+    const raw = await import_promises.default.readFile(getSessionPath(), { encoding: "utf-8" });
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function clearSession() {
+  try {
+    await import_promises.default.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();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  POLL_STATUS,
+  clearSession,
+  getSession,
+  getSessionDir,
+  isSessionValid,
+  pollForToken,
+  refreshAccessToken,
+  requestDeviceCode,
+  saveSession
+});

package/dist/session/index.d.cts

@@ -0,0 +1,82 @@
+import { W as WhataloSession, D as DeviceCodeResponse, P as PollResult, T as TokenResponse } from '../types-DunvRQ0f.cjs';
+export { b as POLL_STATUS, a as PollStatus } from '../types-DunvRQ0f.cjs';
+
+/**
+ * Persistent session store.
+ * Reads and writes ~/.whatalo/session.json with strict file-system permissions.
+ *
+ * Security contract:
+ *  - Directory: chmod 700 (owner read/write/execute only)
+ *  - File:      chmod 600 (owner read/write only)
+ */
+
+/** Returns the path to the ~/.whatalo config directory */
+declare function getSessionDir(): string;
+/**
+ * Persists a session to disk.
+ * Creates the ~/.whatalo directory if it does not exist, then writes the session
+ * file with restricted permissions so no other OS user can read the tokens.
+ */
+declare function saveSession(session: WhataloSession): Promise<void>;
+/**
+ * Reads the persisted session from disk.
+ * Returns null if the file is missing, unreadable, or contains invalid JSON —
+ * never throws, so callers can simply check for null.
+ */
+declare function getSession(): Promise<WhataloSession | null>;
+/**
+ * Removes the session file from disk.
+ * Silently ignores ENOENT so callers can call this unconditionally.
+ */
+declare function clearSession(): Promise<void>;
+/**
+ * Returns true if the session exists and the access token has not expired.
+ * A 60-second clock skew buffer is applied to avoid edge-case failures.
+ */
+declare function isSessionValid(session: WhataloSession): boolean;
+
+/**
+ * Client-side implementation of RFC 8628 — OAuth 2.0 Device Authorization Grant.
+ *
+ * This module only performs the CLIENT half of the flow:
+ *  1. Request a device code from the portal's /api/auth/device-code endpoint.
+ *  2. Poll /api/auth/device-token as an AsyncGenerator until the user authorizes
+ *     or the code expires.
+ *  3. Refresh an expired access token using /api/auth/refresh.
+ *
+ * The server-side implementation lives in the Developer Portal app.
+ */
+
+/**
+ * Initiates the Device Authorization Grant by requesting a device code.
+ *
+ * @param portalUrl - Base URL of the Developer Portal (e.g. https://developers.whatalo.com)
+ * @returns DeviceCodeResponse containing the user code and verification URI to display
+ */
+declare function requestDeviceCode(portalUrl: string): Promise<DeviceCodeResponse>;
+/**
+ * Polls the token endpoint until the user authorizes, denies, or the code expires.
+ *
+ * This is an AsyncGenerator — the caller drives the loop and can cancel at any time
+ * by breaking out. Each yielded value is a PollResult discriminated union.
+ *
+ * RFC 8628 compliance:
+ *  - Respects the server-mandated `interval` (minimum 5 seconds)
+ *  - Handles `slow_down` by increasing interval by 5 seconds
+ *  - Stops and returns on terminal states (authorized / expired / denied)
+ *
+ * @param portalUrl       - Base URL of the Developer Portal
+ * @param deviceCode      - Device code obtained from requestDeviceCode()
+ * @param initialInterval - Polling interval in seconds (from DeviceCodeResponse)
+ */
+declare function pollForToken(portalUrl: string, deviceCode: string, initialInterval: number): AsyncGenerator<PollResult>;
+/**
+ * Exchanges a refresh token for a new access token.
+ *
+ * @param portalUrl    - Base URL of the Developer Portal
+ * @param refreshToken - Refresh token from the current session
+ * @returns New TokenResponse with a fresh access token
+ */
+declare function refreshAccessToken(portalUrl: string, refreshToken: string): Promise<TokenResponse>;
+
+export { DeviceCodeResponse, PollResult, TokenResponse, WhataloSession, clearSession, getSession, getSessionDir, isSessionValid, pollForToken, refreshAccessToken, requestDeviceCode, saveSession };

package/dist/session/index.d.ts

@@ -0,0 +1,82 @@
+import { W as WhataloSession, D as DeviceCodeResponse, P as PollResult, T as TokenResponse } from '../types-DunvRQ0f.js';
+export { b as POLL_STATUS, a as PollStatus } from '../types-DunvRQ0f.js';
+
+/**
+ * Persistent session store.
+ * Reads and writes ~/.whatalo/session.json with strict file-system permissions.
+ *
+ * Security contract:
+ *  - Directory: chmod 700 (owner read/write/execute only)
+ *  - File:      chmod 600 (owner read/write only)
+ */
+
+/** Returns the path to the ~/.whatalo config directory */
+declare function getSessionDir(): string;
+/**
+ * Persists a session to disk.
+ * Creates the ~/.whatalo directory if it does not exist, then writes the session
+ * file with restricted permissions so no other OS user can read the tokens.
+ */
+declare function saveSession(session: WhataloSession): Promise<void>;
+/**
+ * Reads the persisted session from disk.
+ * Returns null if the file is missing, unreadable, or contains invalid JSON —
+ * never throws, so callers can simply check for null.
+ */
+declare function getSession(): Promise<WhataloSession | null>;
+/**
+ * Removes the session file from disk.
+ * Silently ignores ENOENT so callers can call this unconditionally.
+ */
+declare function clearSession(): Promise<void>;
+/**
+ * Returns true if the session exists and the access token has not expired.
+ * A 60-second clock skew buffer is applied to avoid edge-case failures.
+ */
+declare function isSessionValid(session: WhataloSession): boolean;
+
+/**
+ * Client-side implementation of RFC 8628 — OAuth 2.0 Device Authorization Grant.
+ *
+ * This module only performs the CLIENT half of the flow:
+ *  1. Request a device code from the portal's /api/auth/device-code endpoint.
+ *  2. Poll /api/auth/device-token as an AsyncGenerator until the user authorizes
+ *     or the code expires.
+ *  3. Refresh an expired access token using /api/auth/refresh.
+ *
+ * The server-side implementation lives in the Developer Portal app.
+ */
+
+/**
+ * Initiates the Device Authorization Grant by requesting a device code.
+ *
+ * @param portalUrl - Base URL of the Developer Portal (e.g. https://developers.whatalo.com)
+ * @returns DeviceCodeResponse containing the user code and verification URI to display
+ */
+declare function requestDeviceCode(portalUrl: string): Promise<DeviceCodeResponse>;
+/**
+ * Polls the token endpoint until the user authorizes, denies, or the code expires.
+ *
+ * This is an AsyncGenerator — the caller drives the loop and can cancel at any time
+ * by breaking out. Each yielded value is a PollResult discriminated union.
+ *
+ * RFC 8628 compliance:
+ *  - Respects the server-mandated `interval` (minimum 5 seconds)
+ *  - Handles `slow_down` by increasing interval by 5 seconds
+ *  - Stops and returns on terminal states (authorized / expired / denied)
+ *
+ * @param portalUrl       - Base URL of the Developer Portal
+ * @param deviceCode      - Device code obtained from requestDeviceCode()
+ * @param initialInterval - Polling interval in seconds (from DeviceCodeResponse)
+ */
+declare function pollForToken(portalUrl: string, deviceCode: string, initialInterval: number): AsyncGenerator<PollResult>;
+/**
+ * Exchanges a refresh token for a new access token.
+ *
+ * @param portalUrl    - Base URL of the Developer Portal
+ * @param refreshToken - Refresh token from the current session
+ * @returns New TokenResponse with a fresh access token
+ */
+declare function refreshAccessToken(portalUrl: string, refreshToken: string): Promise<TokenResponse>;
+
+export { DeviceCodeResponse, PollResult, TokenResponse, WhataloSession, clearSession, getSession, getSessionDir, isSessionValid, pollForToken, refreshAccessToken, requestDeviceCode, saveSession };