@whatalo/cli-kit 1.0.0

package/dist/env-file-KvUHlLtI.d.cts

@@ -0,0 +1,67 @@
+/**
+ * Configuration shape for `whatalo.app.toml`.
+ * Generated by `whatalo init`, read by all CLI commands.
+ */
+interface WhataloAppConfig {
+    plugin: {
+        /** Human-readable plugin name */
+        name: string;
+        /** Marketplace public ID for the plugin (NanoID from marketplace_apps.public_id) */
+        plugin_id: string;
+        /** URL-safe slug (lowercase, hyphens) */
+        slug: string;
+    };
+    build: {
+        /** Command to run the dev server */
+        dev_command: string;
+        /** Command to build for production */
+        build_command: string;
+        /** Build output directory */
+        output_dir: string;
+    };
+    dev: {
+        /** Local dev server port */
+        port: number;
+    };
+}
+/** Required fields checked during config read */
+declare const REQUIRED_FIELDS: readonly ["plugin.name", "plugin.plugin_id", "plugin.slug", "build.dev_command", "build.build_command", "build.output_dir", "dev.port"];
+/** Default config file name */
+declare const CONFIG_FILE_NAME = "whatalo.app.toml";
+
+/**
+ * Reads and validates `whatalo.app.toml` from the given directory.
+ * Throws with a clear message if the file is missing, corrupt, or
+ * lacks required fields.
+ */
+declare function readConfig(dir: string): Promise<WhataloAppConfig>;
+/**
+ * Writes a `whatalo.app.toml` file to the given directory.
+ */
+declare function writeConfig(dir: string, config: WhataloAppConfig): Promise<void>;
+
+/**
+ * .env file management with comment and non-Whatalo variable preservation.
+ * Used by `whatalo env pull` to write environment variables to disk
+ * without destroying existing developer configuration.
+ */
+interface EnvEntry {
+    /** Original line (comment, blank, or KEY=VALUE) */
+    raw: string;
+    /** Parsed key, undefined for comments/blanks */
+    key?: string;
+    /** Parsed value, undefined for comments/blanks */
+    value?: string;
+}
+/**
+ * Parses a .env file content preserving comments and empty lines.
+ * Each line is returned as an EnvEntry with optional key/value.
+ */
+declare function parseEnvFile(content: string): EnvEntry[];
+/**
+ * Updates WHATALO_* variables in a .env file, preserving everything else.
+ * Creates the file if it does not exist. Does NOT delete non-Whatalo variables.
+ */
+declare function updateEnvFile(filePath: string, vars: Record<string, string>): Promise<void>;
+
+export { CONFIG_FILE_NAME as C, type EnvEntry as E, REQUIRED_FIELDS as R, type WhataloAppConfig as W, parseEnvFile as p, readConfig as r, updateEnvFile as u, writeConfig as w };

package/dist/env-file-KvUHlLtI.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Configuration shape for `whatalo.app.toml`.
+ * Generated by `whatalo init`, read by all CLI commands.
+ */
+interface WhataloAppConfig {
+    plugin: {
+        /** Human-readable plugin name */
+        name: string;
+        /** Marketplace public ID for the plugin (NanoID from marketplace_apps.public_id) */
+        plugin_id: string;
+        /** URL-safe slug (lowercase, hyphens) */
+        slug: string;
+    };
+    build: {
+        /** Command to run the dev server */
+        dev_command: string;
+        /** Command to build for production */
+        build_command: string;
+        /** Build output directory */
+        output_dir: string;
+    };
+    dev: {
+        /** Local dev server port */
+        port: number;
+    };
+}
+/** Required fields checked during config read */
+declare const REQUIRED_FIELDS: readonly ["plugin.name", "plugin.plugin_id", "plugin.slug", "build.dev_command", "build.build_command", "build.output_dir", "dev.port"];
+/** Default config file name */
+declare const CONFIG_FILE_NAME = "whatalo.app.toml";
+
+/**
+ * Reads and validates `whatalo.app.toml` from the given directory.
+ * Throws with a clear message if the file is missing, corrupt, or
+ * lacks required fields.
+ */
+declare function readConfig(dir: string): Promise<WhataloAppConfig>;
+/**
+ * Writes a `whatalo.app.toml` file to the given directory.
+ */
+declare function writeConfig(dir: string, config: WhataloAppConfig): Promise<void>;
+
+/**
+ * .env file management with comment and non-Whatalo variable preservation.
+ * Used by `whatalo env pull` to write environment variables to disk
+ * without destroying existing developer configuration.
+ */
+interface EnvEntry {
+    /** Original line (comment, blank, or KEY=VALUE) */
+    raw: string;
+    /** Parsed key, undefined for comments/blanks */
+    key?: string;
+    /** Parsed value, undefined for comments/blanks */
+    value?: string;
+}
+/**
+ * Parses a .env file content preserving comments and empty lines.
+ * Each line is returned as an EnvEntry with optional key/value.
+ */
+declare function parseEnvFile(content: string): EnvEntry[];
+/**
+ * Updates WHATALO_* variables in a .env file, preserving everything else.
+ * Creates the file if it does not exist. Does NOT delete non-Whatalo variables.
+ */
+declare function updateEnvFile(filePath: string, vars: Record<string, string>): Promise<void>;
+
+export { CONFIG_FILE_NAME as C, type EnvEntry as E, REQUIRED_FIELDS as R, type WhataloAppConfig as W, parseEnvFile as p, readConfig as r, updateEnvFile as u, writeConfig as w };

package/dist/http/index.cjs

@@ -0,0 +1,194 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/http/index.ts
+var http_exports = {};
+__export(http_exports, {
+  WhataloApiClient: () => WhataloApiClient
+});
+module.exports = __toCommonJS(http_exports);
+
+// src/http/client.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
+
+// src/output/errors.ts
+var WhataloAuthError = class extends Error {
+  constructor(message = "Authentication required") {
+    super(message);
+    this.name = "WhataloAuthError";
+  }
+};
+var WhataloNetworkError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "WhataloNetworkError";
+    this.statusCode = statusCode;
+  }
+};
+
+// src/http/client.ts
+var import_meta = {};
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_RETRIES = 3;
+var BASE_BACKOFF_MS = 1e3;
+function getCliVersion() {
+  try {
+    const __dirname = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+    const pkg = JSON.parse(
+      (0, import_node_fs.readFileSync)((0, import_node_path.join)(__dirname, "..", "package.json"), "utf-8")
+    );
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function buildUserAgent() {
+  const cliVersion = getCliVersion();
+  const nodeVersion = process.version;
+  const platform = process.platform;
+  const arch = process.arch;
+  return `whatalo-cli/${cliVersion} node/${nodeVersion} ${platform}/${arch}`;
+}
+var WhataloApiClient = class {
+  options;
+  timeout;
+  userAgent;
+  constructor(options) {
+    this.options = options;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.userAgent = buildUserAgent();
+  }
+  /** Sends an authenticated GET request and returns the parsed JSON body */
+  async get(path) {
+    return this.request("GET", path);
+  }
+  /** Sends an authenticated POST request with an optional JSON body */
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  /** Sends an authenticated PATCH request with an optional JSON body */
+  async patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  /** Sends an authenticated DELETE request */
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
+  /**
+   * Core request method with automatic token refresh on 401,
+   * retry with exponential backoff on 5xx, and rate limit handling.
+   */
+  async request(method, path, body) {
+    const session = await this.options.getSession();
+    if (!session) {
+      throw new WhataloAuthError("Not logged in. Run `whatalo login` first.");
+    }
+    const doFetch = async (token) => {
+      const url = `${this.options.portalUrl}${path}`;
+      return fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+          "User-Agent": this.userAgent
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    };
+    let res;
+    try {
+      res = await this.executeWithRetry(doFetch, session.accessToken);
+    } catch (err) {
+      if (err instanceof WhataloAuthError || err instanceof WhataloNetworkError) {
+        throw err;
+      }
+      const message = err instanceof Error ? err.message : "Unknown error";
+      throw new WhataloNetworkError(message);
+    }
+    if (res.status === 401) {
+      try {
+        const refreshed = await this.options.refreshSession();
+        res = await this.executeWithRetry(doFetch, refreshed.accessToken);
+      } catch (refreshErr) {
+        if (refreshErr instanceof WhataloNetworkError) throw refreshErr;
+        throw new WhataloAuthError(
+          "Session expired. Run `whatalo login` to re-authenticate."
+        );
+      }
+      if (res.status === 401) {
+        throw new WhataloAuthError(
+          "Session expired. Run `whatalo login` to re-authenticate."
+        );
+      }
+    }
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => "Unknown error");
+      throw new WhataloNetworkError(
+        `API error ${res.status}: ${errorBody}`,
+        res.status
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Executes a fetch with retry on 5xx and rate-limit (429) handling.
+   * Uses exponential backoff: 1s, 2s, 4s.
+   */
+  async executeWithRetry(doFetch, token) {
+    let lastResponse;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        lastResponse = await doFetch(token);
+      } catch (err) {
+        if (attempt === MAX_RETRIES - 1) {
+          const message = err instanceof Error ? err.message : "Network error";
+          throw new WhataloNetworkError(message);
+        }
+        await this.sleep(BASE_BACKOFF_MS * Math.pow(2, attempt));
+        continue;
+      }
+      if (lastResponse.status === 429) {
+        const retryAfter = lastResponse.headers.get("Retry-After");
+        const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : BASE_BACKOFF_MS * Math.pow(2, attempt);
+        if (attempt === MAX_RETRIES - 1) {
+          throw new WhataloNetworkError("Rate limit exceeded", 429);
+        }
+        await this.sleep(Math.min(waitMs, 3e4));
+        continue;
+      }
+      if (lastResponse.status >= 500 && attempt < MAX_RETRIES - 1) {
+        await this.sleep(BASE_BACKOFF_MS * Math.pow(2, attempt));
+        continue;
+      }
+      return lastResponse;
+    }
+    return lastResponse;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WhataloApiClient
+});

package/dist/http/index.d.cts

@@ -0,0 +1,56 @@
+import { W as WhataloSession } from '../types-DunvRQ0f.cjs';
+
+/**
+ * Authenticated HTTP client for the Whatalo Developer Portal API.
+ *
+ * Responsibilities:
+ *  - Attaches Bearer token to every request.
+ *  - On 401, attempts a single token refresh then retries.
+ *  - Retry with exponential backoff on 5xx errors (3 attempts).
+ *  - Auto-wait on 429 using Retry-After header.
+ *  - Configurable timeout (default 30s).
+ *  - User-Agent header for API diagnostics.
+ *  - NEVER logs tokens or auth headers.
+ */
+
+interface HttpClientOptions {
+    /** Base URL of the Developer Portal (e.g. https://developers.whatalo.com) */
+    portalUrl: string;
+    /** Returns the current session or null if not logged in */
+    getSession: () => Promise<WhataloSession | null>;
+    /**
+     * Refreshes an expired session and returns the updated one.
+     * Should persist the new session to disk before returning.
+     * Throws if the refresh token is also invalid.
+     */
+    refreshSession: () => Promise<WhataloSession>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+declare class WhataloApiClient {
+    private readonly options;
+    private readonly timeout;
+    private readonly userAgent;
+    constructor(options: HttpClientOptions);
+    /** Sends an authenticated GET request and returns the parsed JSON body */
+    get<T>(path: string): Promise<T>;
+    /** Sends an authenticated POST request with an optional JSON body */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /** Sends an authenticated PATCH request with an optional JSON body */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /** Sends an authenticated DELETE request */
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Core request method with automatic token refresh on 401,
+     * retry with exponential backoff on 5xx, and rate limit handling.
+     */
+    private request;
+    /**
+     * Executes a fetch with retry on 5xx and rate-limit (429) handling.
+     * Uses exponential backoff: 1s, 2s, 4s.
+     */
+    private executeWithRetry;
+    private sleep;
+}
+
+export { type HttpClientOptions, WhataloApiClient };

package/dist/http/index.d.ts

@@ -0,0 +1,56 @@
+import { W as WhataloSession } from '../types-DunvRQ0f.js';
+
+/**
+ * Authenticated HTTP client for the Whatalo Developer Portal API.
+ *
+ * Responsibilities:
+ *  - Attaches Bearer token to every request.
+ *  - On 401, attempts a single token refresh then retries.
+ *  - Retry with exponential backoff on 5xx errors (3 attempts).
+ *  - Auto-wait on 429 using Retry-After header.
+ *  - Configurable timeout (default 30s).
+ *  - User-Agent header for API diagnostics.
+ *  - NEVER logs tokens or auth headers.
+ */
+
+interface HttpClientOptions {
+    /** Base URL of the Developer Portal (e.g. https://developers.whatalo.com) */
+    portalUrl: string;
+    /** Returns the current session or null if not logged in */
+    getSession: () => Promise<WhataloSession | null>;
+    /**
+     * Refreshes an expired session and returns the updated one.
+     * Should persist the new session to disk before returning.
+     * Throws if the refresh token is also invalid.
+     */
+    refreshSession: () => Promise<WhataloSession>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+declare class WhataloApiClient {
+    private readonly options;
+    private readonly timeout;
+    private readonly userAgent;
+    constructor(options: HttpClientOptions);
+    /** Sends an authenticated GET request and returns the parsed JSON body */
+    get<T>(path: string): Promise<T>;
+    /** Sends an authenticated POST request with an optional JSON body */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /** Sends an authenticated PATCH request with an optional JSON body */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /** Sends an authenticated DELETE request */
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Core request method with automatic token refresh on 401,
+     * retry with exponential backoff on 5xx, and rate limit handling.
+     */
+    private request;
+    /**
+     * Executes a fetch with retry on 5xx and rate-limit (429) handling.
+     * Uses exponential backoff: 1s, 2s, 4s.
+     */
+    private executeWithRetry;
+    private sleep;
+}
+
+export { type HttpClientOptions, WhataloApiClient };

package/dist/http/index.mjs

@@ -0,0 +1,166 @@
+// src/http/client.ts
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// src/output/errors.ts
+var WhataloAuthError = class extends Error {
+  constructor(message = "Authentication required") {
+    super(message);
+    this.name = "WhataloAuthError";
+  }
+};
+var WhataloNetworkError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "WhataloNetworkError";
+    this.statusCode = statusCode;
+  }
+};
+
+// src/http/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_RETRIES = 3;
+var BASE_BACKOFF_MS = 1e3;
+function getCliVersion() {
+  try {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, "..", "package.json"), "utf-8")
+    );
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function buildUserAgent() {
+  const cliVersion = getCliVersion();
+  const nodeVersion = process.version;
+  const platform = process.platform;
+  const arch = process.arch;
+  return `whatalo-cli/${cliVersion} node/${nodeVersion} ${platform}/${arch}`;
+}
+var WhataloApiClient = class {
+  options;
+  timeout;
+  userAgent;
+  constructor(options) {
+    this.options = options;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.userAgent = buildUserAgent();
+  }
+  /** Sends an authenticated GET request and returns the parsed JSON body */
+  async get(path) {
+    return this.request("GET", path);
+  }
+  /** Sends an authenticated POST request with an optional JSON body */
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  /** Sends an authenticated PATCH request with an optional JSON body */
+  async patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  /** Sends an authenticated DELETE request */
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
+  /**
+   * Core request method with automatic token refresh on 401,
+   * retry with exponential backoff on 5xx, and rate limit handling.
+   */
+  async request(method, path, body) {
+    const session = await this.options.getSession();
+    if (!session) {
+      throw new WhataloAuthError("Not logged in. Run `whatalo login` first.");
+    }
+    const doFetch = async (token) => {
+      const url = `${this.options.portalUrl}${path}`;
+      return fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+          "User-Agent": this.userAgent
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    };
+    let res;
+    try {
+      res = await this.executeWithRetry(doFetch, session.accessToken);
+    } catch (err) {
+      if (err instanceof WhataloAuthError || err instanceof WhataloNetworkError) {
+        throw err;
+      }
+      const message = err instanceof Error ? err.message : "Unknown error";
+      throw new WhataloNetworkError(message);
+    }
+    if (res.status === 401) {
+      try {
+        const refreshed = await this.options.refreshSession();
+        res = await this.executeWithRetry(doFetch, refreshed.accessToken);
+      } catch (refreshErr) {
+        if (refreshErr instanceof WhataloNetworkError) throw refreshErr;
+        throw new WhataloAuthError(
+          "Session expired. Run `whatalo login` to re-authenticate."
+        );
+      }
+      if (res.status === 401) {
+        throw new WhataloAuthError(
+          "Session expired. Run `whatalo login` to re-authenticate."
+        );
+      }
+    }
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => "Unknown error");
+      throw new WhataloNetworkError(
+        `API error ${res.status}: ${errorBody}`,
+        res.status
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Executes a fetch with retry on 5xx and rate-limit (429) handling.
+   * Uses exponential backoff: 1s, 2s, 4s.
+   */
+  async executeWithRetry(doFetch, token) {
+    let lastResponse;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        lastResponse = await doFetch(token);
+      } catch (err) {
+        if (attempt === MAX_RETRIES - 1) {
+          const message = err instanceof Error ? err.message : "Network error";
+          throw new WhataloNetworkError(message);
+        }
+        await this.sleep(BASE_BACKOFF_MS * Math.pow(2, attempt));
+        continue;
+      }
+      if (lastResponse.status === 429) {
+        const retryAfter = lastResponse.headers.get("Retry-After");
+        const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : BASE_BACKOFF_MS * Math.pow(2, attempt);
+        if (attempt === MAX_RETRIES - 1) {
+          throw new WhataloNetworkError("Rate limit exceeded", 429);
+        }
+        await this.sleep(Math.min(waitMs, 3e4));
+        continue;
+      }
+      if (lastResponse.status >= 500 && attempt < MAX_RETRIES - 1) {
+        await this.sleep(BASE_BACKOFF_MS * Math.pow(2, attempt));
+        continue;
+      }
+      return lastResponse;
+    }
+    return lastResponse;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+export {
+  WhataloApiClient
+};