@fire-spark/cli 0.0.0-stage → 0.13.2

package/src/commands/doctor/live/order.ts

@@ -0,0 +1,95 @@
+import { randomBytes } from "node:crypto";
+
+import type { LiveConfig, Menu, MenuProduct } from "./live.session";
+
+export const doctorOrderId = () => {
+  return `ord-doctor-${randomBytes(8).toString("hex")}`;
+};
+
+const money = (price: number) => {
+  const unit = {
+    unit_subtotal: price,
+    unit_discount: 0,
+    unit_tax_total: 0,
+    unit_total: price
+  };
+  const line = {
+    subtotal: price,
+    discount_total: 0,
+    tax_total: 0,
+    total: price
+  };
+  const groupUnit = {
+    unit_group_subtotal: price,
+    unit_group_discount: 0,
+    unit_group_tax_total: 0,
+    unit_group_total: price
+  };
+  const group = {
+    group_subtotal: price,
+    group_discount: 0,
+    group_tax_total: 0,
+    group_total: price
+  };
+  return { ...unit, ...line, ...groupUnit, ...group };
+};
+
+/** One unit of one product, no tax, no discount. Place sends cash. */
+export const buildOrderBody = (input: {
+  id: string;
+  config: LiveConfig;
+  product: MenuProduct;
+  menuId?: string;
+  lineUid: string;
+}) => {
+  const { config, product } = input;
+  const price = product.pricing?.price ?? 0;
+  const head = {
+    type: "PRODUCT",
+    uid: input.lineUid,
+    id: product.id,
+    parent_uid: null,
+    parent_id: null
+  };
+  const meta = {
+    name: product.name ?? product.id,
+    menu_id: input.menuId,
+    metadata: { source: "firespark-doctor" }
+  };
+  const rates = { quantity: 1, tax_rate: null, discount_rate: 0 };
+  const line = { ...head, ...meta, ...rates, ...money(price) };
+  const names = {
+    display_name: "Fire Spark Doctor",
+    first_name: "Fire Spark",
+    last_name: "Doctor"
+  };
+  const customer_info = { ...names, email: config.customerEmail };
+  const phone = { phone: "+593999999999" };
+  const customer = { customer_info: { ...customer_info, ...phone } };
+  const totals = {
+    currency: config.currency,
+    subtotal: price,
+    discount_rate: 0,
+    discount_total: 0,
+    tax_rate: 0,
+    tax_total: 0,
+    total: price
+  };
+  const scope = {
+    store_id: config.storeId,
+    channel_id: config.channelId,
+    fulfillment_id: config.fulfillmentId
+  };
+  const body = { id: input.id, ...scope, is_anonymous: false, customer };
+  return { ...body, lines: [line], totals };
+};
+
+/** The configured product, otherwise the lowest id that has a price. */
+export const pickProduct = (menus: Menu[], productId?: string) => {
+  const products = menus.flatMap(menu => menu.products ?? []);
+  if (productId) return products.find(product => product.id === productId);
+  const priced = products.filter(product => {
+    return typeof product.pricing?.price === "number" && product.id;
+  });
+  return priced.toSorted((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))[0];
+};

package/src/commands/doctor/live/realtime.ts

@@ -0,0 +1,161 @@
+export interface WebSocketLike {
+  send: (data: string) => void;
+  close: () => void;
+  addEventListener: (
+    type: string,
+    listener: (event: { data?: unknown }) => void
+  ) => void;
+}
+
+export type WebSocketFactory = (url: string) => WebSocketLike;
+
+export const ORDER_CHANGED_EVENT = "order.changed";
+const HEARTBEAT_MS = 25_000;
+
+export interface OrderChanged {
+  order_id?: string;
+  checkout_state?: string;
+  error?: { message?: string } | null;
+}
+
+export interface SubscribeInput {
+  url: string;
+  key: string;
+  topic: string;
+  accessToken: string;
+  joinTimeoutMs: number;
+  createSocket: WebSocketFactory;
+}
+
+export interface Subscription {
+  joined: Promise<void>;
+  events: OrderChanged[];
+  waitFor: (
+    match: (event: OrderChanged) => boolean,
+    timeoutMs: number
+  ) => Promise<OrderChanged | undefined>;
+  close: () => void;
+}
+
+export const socketUrl = (url: string, key: string) => {
+  const base = url.replace(/\/+$/, "").replace(/^http/i, "ws");
+  const apikey = encodeURIComponent(key);
+  return `${base}/realtime/v1/websocket?apikey=${apikey}&vsn=1.0.0`;
+};
+
+interface PhoenixMessage {
+  topic?: string;
+  event?: string;
+  ref?: string | null;
+  payload?: {
+    status?: string;
+    event?: string;
+    payload?: unknown;
+    response?: { reason?: string };
+  };
+}
+
+const parseMessage = (data: unknown): PhoenixMessage | undefined => {
+  if (typeof data !== "string") return undefined;
+  try {
+    return JSON.parse(data) as PhoenixMessage;
+  } catch {
+    return undefined;
+  }
+};
+
+const joinPayload = (accessToken: string) => {
+  const broadcast = { ack: false, self: false };
+  const presence = { key: "" };
+  const config = { broadcast, presence, postgres_changes: [], private: true };
+  return { config, access_token: accessToken };
+};
+
+/** One private broadcast channel. Join before place, then wait. */
+export const subscribe = (input: SubscribeInput): Subscription => {
+  const channelTopic = `realtime:${input.topic}`;
+  const events: OrderChanged[] = [];
+  const waiters = new Set<(event: OrderChanged) => void>();
+  const socket = input.createSocket(socketUrl(input.url, input.key));
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let ref = 0;
+  const send = (topic: string, event: string, payload: unknown) => {
+    ref += 1;
+    const id = String(ref);
+    const frame = { topic, event, payload, ref: id, join_ref: "1" };
+    socket.send(JSON.stringify(frame));
+    return id;
+  };
+  const push = (changed: OrderChanged) => {
+    events.push(changed);
+    for (const waiter of waiters) waiter(changed);
+  };
+  let joinRef = "";
+  const joined = new Promise<void>((resolveJoin, rejectJoin) => {
+    const timer = setTimeout(() => {
+      rejectJoin(new Error("join timeout"));
+    }, input.joinTimeoutMs);
+    timer.unref?.();
+    socket.addEventListener("open", () => {
+      const payload = joinPayload(input.accessToken);
+      joinRef = send(channelTopic, "phx_join", payload);
+      heartbeat = setInterval(() => {
+        send("phoenix", "heartbeat", {});
+      }, HEARTBEAT_MS);
+      heartbeat.unref?.();
+    });
+    socket.addEventListener("error", () => {
+      rejectJoin(new Error("websocket error"));
+    });
+    socket.addEventListener("close", () => {
+      rejectJoin(new Error("websocket closed"));
+    });
+    socket.addEventListener("message", event => {
+      const message = parseMessage(event.data);
+      if (!message || message.topic !== channelTopic) return;
+      const reply = message.event === "phx_reply" && message.ref === joinRef;
+      if (reply) {
+        clearTimeout(timer);
+        if (message.payload?.status === "ok") resolveJoin();
+        else {
+          const reason = message.payload?.response?.reason ?? "join rejected";
+          rejectJoin(new Error(reason));
+        }
+        return;
+      }
+      if (message.event === "phx_error") {
+        rejectJoin(new Error("channel error"));
+      }
+      if (message.event !== "broadcast") return;
+      if (message.payload?.event !== ORDER_CHANGED_EVENT) return;
+      push(message.payload.payload as OrderChanged);
+    });
+  });
+  joined.catch(() => undefined);
+  const waitFor: Subscription["waitFor"] = (match, timeoutMs) => {
+    const seen = events.find(match);
+    if (seen) return Promise.resolve(seen);
+    return new Promise(resolveWait => {
+      const done = (value: OrderChanged | undefined) => {
+        clearTimeout(timer);
+        waiters.delete(listener);
+        resolveWait(value);
+      };
+      const listener = (event: OrderChanged) => {
+        if (match(event)) done(event);
+      };
+      const timer = setTimeout(() => done(undefined), timeoutMs);
+      waiters.add(listener);
+    });
+  };
+  const close = () => {
+    if (heartbeat) clearInterval(heartbeat);
+    waiters.clear();
+    try {
+      socket.close();
+    } catch {
+      // already closed
+    }
+  };
+  return { joined, events, waitFor, close };
+};

package/src/commands/doctor/live/result.ts

@@ -0,0 +1,76 @@
+import type { Copy, Vars } from "../../../core/i18n";
+
+export interface Text {
+  copy: Copy;
+  vars?: Vars;
+}
+
+export interface CheckFail {
+  status: "fail";
+  hop: string;
+  reason: Text;
+}
+
+export interface CheckSkip {
+  status: "skip";
+  reason: Text;
+}
+
+const text = (copy: Copy, vars?: Vars): Text => {
+  return { copy, vars };
+};
+
+export const fail = (hop: string, copy: Copy, vars?: Vars): CheckFail => {
+  return { status: "fail", hop, reason: text(copy, vars) };
+};
+
+export const skip = (copy: Copy, vars?: Vars): CheckSkip => {
+  return { status: "skip", reason: text(copy, vars) };
+};
+
+/** Reasons the live order path can still surface. */
+export const REASONS = {
+  mismatch: {
+    "es-EC": "Se esperaba {expected} y llegó {actual}.",
+    "en-US": "Expected {expected}, got {actual}.",
+    "pt-BR": "Esperava {expected} e chegou {actual}."
+  },
+  httpStatus: {
+    "es-EC": "{method} {path} respondió {status}: {detail}",
+    "en-US": "{method} {path} answered {status}: {detail}",
+    "pt-BR": "{method} {path} respondeu {status}: {detail}"
+  },
+  network: {
+    "es-EC": "No se pudo llegar a {target}: {detail}",
+    "en-US": "Could not reach {target}: {detail}",
+    "pt-BR": "Não foi possível chegar a {target}: {detail}"
+  },
+  badShape: {
+    "es-EC": "La respuesta no trae {field}.",
+    "en-US": "The response has no {field}.",
+    "pt-BR": "A resposta não traz {field}."
+  },
+  liveMissing: {
+    "es-EC": "falta configurar {names}",
+    "en-US": "missing configuration: {names}",
+    "pt-BR": "falta configurar {names}"
+  },
+  emptyList: {
+    "es-EC": "{what} llegó vacío.",
+    "en-US": "{what} came back empty.",
+    "pt-BR": "{what} veio vazio."
+  },
+  checkoutFailed: {
+    "es-EC": "El checkout falló: {detail}.",
+    "en-US": "Checkout failed: {detail}.",
+    "pt-BR": "O checkout falhou: {detail}."
+  },
+  timeout: {
+    "es-EC":
+      "Pasaron {seconds} s y el checkout no se liberó. Último estado: {last}.",
+    "en-US":
+      "{seconds} s passed and checkout was not released. Last state: {last}.",
+    "pt-BR":
+      "Passaram {seconds} s e o checkout não foi liberado. Último estado: {last}."
+  }
+} satisfies Record<string, Copy>;

package/src/commands/index.ts

@@ -0,0 +1,8 @@
+import type { Command } from "../core/command.types";
+import { clientDoctorCommand } from "./doctor/client/command";
+
+export const COMMANDS: Command[] = [clientDoctorCommand];
+
+export const findCommand = (name: string) => {
+  return COMMANDS.find(command => command.name === name);
+};

package/src/core/command.types.ts

@@ -0,0 +1,25 @@
+import type { Copy, Locale } from "./i18n";
+import type { OptionSpec, OptionValues } from "./options";
+import type { Output } from "./output";
+import type { Redactor } from "./redact";
+
+export interface CommandContext {
+  locale: Locale;
+  options: OptionValues;
+  positionals: string[];
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+  output: Output;
+  redactor: Redactor;
+  isTty?: boolean;
+  ask?: (question: string) => Promise<string>;
+}
+
+export interface Command {
+  name: string;
+  summary: Copy;
+  usage: string;
+  options: OptionSpec[];
+  details?: Copy;
+  run: (context: CommandContext) => Promise<number>;
+}

package/src/core/help.ts

@@ -0,0 +1,85 @@
+import type { Command } from "./command.types";
+import { translate } from "./i18n";
+import type { Copy, Locale } from "./i18n";
+import { GLOBAL_OPTIONS } from "./options";
+import type { OptionSpec } from "./options";
+
+const HEADINGS = {
+  usage: { "es-EC": "Uso", "en-US": "Usage", "pt-BR": "Uso" },
+  commands: { "es-EC": "Comandos", "en-US": "Commands", "pt-BR": "Comandos" },
+  options: { "es-EC": "Opciones", "en-US": "Options", "pt-BR": "Opções" },
+  env: { "es-EC": "variable", "en-US": "env", "pt-BR": "variável" },
+  secret: { "es-EC": "secreto", "en-US": "secret", "pt-BR": "secreto" },
+  default: { "es-EC": "por defecto", "en-US": "default", "pt-BR": "padrão" },
+  more: {
+    "es-EC": "Ejecuta `firespark <comando> --help` para ver sus opciones.",
+    "en-US": "Run `firespark <command> --help` to see its options.",
+    "pt-BR": "Execute `firespark <comando> --help` para ver as opções."
+  }
+} satisfies Record<string, Copy>;
+
+const flagLabel = (spec: OptionSpec) => {
+  const value = spec.kind === "boolean" ? "" : " <value>";
+  const short = spec.short ? `-${spec.short}, ` : "";
+  return `${short}--${spec.name}${value}`;
+};
+
+const optionNotes = (spec: OptionSpec, locale: Locale) => {
+  const notes: string[] = [];
+  if (spec.env) notes.push(`${translate(locale, HEADINGS.env)}: ${spec.env}`);
+  if (spec.secret) notes.push(translate(locale, HEADINGS.secret));
+  if (spec.defaultValue !== undefined) {
+    const label = translate(locale, HEADINGS.default);
+    notes.push(`${label}: ${spec.defaultValue}`);
+  }
+  return notes.length > 0 ? ` (${notes.join("; ")})` : "";
+};
+
+export const renderOptions = (specs: OptionSpec[], locale: Locale) => {
+  const width = Math.max(...specs.map(s => flagLabel(s).length));
+  return specs.map(spec => {
+    const label = flagLabel(spec).padEnd(width);
+    const text = translate(locale, spec.description);
+    return `  ${label}  ${text}${optionNotes(spec, locale)}`;
+  });
+};
+
+export const renderRootHelp = (commands: Command[], locale: Locale) => {
+  const width = Math.max(...commands.map(c => c.name.length));
+  const rows = commands.map(command => {
+    const summary = translate(locale, command.summary);
+    return `  ${command.name.padEnd(width)}  ${summary}`;
+  });
+  const usage = `${translate(locale, HEADINGS.usage)}: firespark <command> [options]`;
+  const commandsTitle = `${translate(locale, HEADINGS.commands)}:`;
+  const optionsTitle = `${translate(locale, HEADINGS.options)}:`;
+  const globals = renderOptions(GLOBAL_OPTIONS, locale);
+  const more = translate(locale, HEADINGS.more);
+  return [
+    usage,
+    "",
+    commandsTitle,
+    ...rows,
+    "",
+    optionsTitle,
+    ...globals,
+    "",
+    more
+  ].join("\n");
+};
+
+export const renderCommandHelp = (command: Command, locale: Locale) => {
+  const usage = `${translate(locale, HEADINGS.usage)}: ${command.usage}`;
+  const summary = translate(locale, command.summary);
+  const details = command.details
+    ? ["", translate(locale, command.details)]
+    : [];
+  const optionsTitle = `${translate(locale, HEADINGS.options)}:`;
+  const options = renderOptions(
+    [...command.options, ...GLOBAL_OPTIONS],
+    locale
+  );
+  return [usage, "", summary, ...details, "", optionsTitle, ...options].join(
+    "\n"
+  );
+};

package/src/core/i18n.ts

@@ -0,0 +1,49 @@
+export const LOCALES = ["es-EC", "en-US", "pt-BR"] as const;
+
+export type Locale = (typeof LOCALES)[number];
+
+export type Copy = Record<Locale, string>;
+
+export const DEFAULT_LOCALE: Locale = "es-EC";
+
+const byLanguage: Record<string, Locale> = { es: "es-EC", en: "en-US" };
+const byLanguagePt: Record<string, Locale> = { pt: "pt-BR" };
+const LANGUAGE_FALLBACK = { ...byLanguage, ...byLanguagePt };
+
+export const isLocale = (value: string): value is Locale => {
+  return (LOCALES as readonly string[]).includes(value);
+};
+
+export const matchLocale = (value: string | undefined) => {
+  if (!value) return undefined;
+  const tag = value.split(".")[0]!.replace("_", "-");
+  const exact = LOCALES.find(l => l.toLowerCase() === tag.toLowerCase());
+  if (exact) return exact;
+  const language = tag.split("-")[0]!.toLowerCase();
+  return LANGUAGE_FALLBACK[language];
+};
+
+export const resolveLocale = (
+  flag: string | undefined,
+  env: NodeJS.ProcessEnv
+) => {
+  const candidates = [flag, env.FIRESPARK_LOCALE, env.LC_ALL, env.LANG];
+  for (const candidate of candidates) {
+    const locale = matchLocale(candidate);
+    if (locale) return locale;
+  }
+  return DEFAULT_LOCALE;
+};
+
+export type Vars = Record<string, string | number>;
+
+export const format = (template: string, vars: Vars = {}) => {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => {
+    const value = vars[key];
+    return value === undefined ? match : String(value);
+  });
+};
+
+export const translate = (locale: Locale, copy: Copy, vars?: Vars) => {
+  return format(copy[locale], vars);
+};

package/src/core/options.ts

@@ -0,0 +1,131 @@
+import { parseArgs } from "node:util";
+
+import type { Copy } from "./i18n";
+
+export type OptionKind = "string" | "boolean" | "number";
+
+export interface OptionSpec {
+  name: string;
+  kind: OptionKind;
+  description: Copy;
+  env?: string;
+  secret?: boolean;
+  defaultValue?: string;
+  short?: string;
+}
+
+export type OptionValues = Record<string, string | boolean | undefined>;
+
+export const GLOBAL_OPTIONS: OptionSpec[] = [
+  {
+    name: "help",
+    kind: "boolean",
+    short: "h",
+    description: {
+      "es-EC": "Muestra esta ayuda.",
+      "en-US": "Show this help.",
+      "pt-BR": "Mostra esta ajuda."
+    }
+  },
+  {
+    name: "locale",
+    kind: "string",
+    env: "FIRESPARK_LOCALE",
+    description: {
+      "es-EC":
+        "Idioma de la salida: cualquier etiqueta BCP 47 (es, es-MX, en, pt-BR…); se muestra en es-EC, en-US o pt-BR según su idioma.",
+      "en-US":
+        "Output language: any BCP 47 tag (es, es-MX, en, pt-BR…); shown in es-EC, en-US or pt-BR by its language.",
+      "pt-BR":
+        "Idioma da saída: qualquer tag BCP 47 (es, es-MX, en, pt-BR…); exibida em es-EC, en-US ou pt-BR conforme o idioma."
+    }
+  },
+  {
+    name: "no-color",
+    kind: "boolean",
+    env: "NO_COLOR",
+    description: {
+      "es-EC": "Desactiva los colores.",
+      "en-US": "Disable colors.",
+      "pt-BR": "Desativa as cores."
+    }
+  }
+];
+
+export class UsageError extends Error {}
+
+const toParseOption = (spec: OptionSpec) => {
+  const type = spec.kind === "boolean" ? "boolean" : "string";
+  if (spec.short) return { type, short: spec.short } as const;
+  return { type } as const;
+};
+
+export const parseOptions = (argv: string[], specs: OptionSpec[]) => {
+  const options = Object.fromEntries(
+    specs.map(s => [s.name, toParseOption(s)])
+  );
+  try {
+    const config = {
+      args: argv,
+      options,
+      strict: true,
+      allowPositionals: true
+    };
+    const { values, positionals } = parseArgs(config);
+    return { values: values as OptionValues, positionals };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new UsageError(message);
+  }
+};
+
+const envValue = (spec: OptionSpec, env: NodeJS.ProcessEnv) => {
+  if (!spec.env) return undefined;
+  const value = env[spec.env];
+  if (value === undefined || value === "") return undefined;
+  return value;
+};
+
+const fromEnv = (spec: OptionSpec, raw: string) => {
+  if (spec.kind !== "boolean") return raw;
+  return !["0", "false", "no"].includes(raw.toLowerCase());
+};
+
+// Flags win over env vars, env vars win over defaults.
+export const resolveOptions = (
+  specs: OptionSpec[],
+  values: OptionValues,
+  env: NodeJS.ProcessEnv
+) => {
+  const resolved: OptionValues = {};
+  for (const spec of specs) {
+    const flag = values[spec.name];
+    const raw = envValue(spec, env);
+    if (flag !== undefined) resolved[spec.name] = flag;
+    else if (raw !== undefined) resolved[spec.name] = fromEnv(spec, raw);
+    else resolved[spec.name] = spec.defaultValue;
+  }
+  return resolved;
+};
+
+export const secretValues = (specs: OptionSpec[], resolved: OptionValues) => {
+  const secrets: string[] = [];
+  for (const spec of specs) {
+    const value = resolved[spec.name];
+    if (spec.secret && typeof value === "string") secrets.push(value);
+  }
+  return secrets;
+};
+
+export const readString = (values: OptionValues, name: string) => {
+  const value = values[name];
+  return typeof value === "string" && value !== "" ? value : undefined;
+};
+
+export const readNumber = (values: OptionValues, name: string) => {
+  const raw = readString(values, name);
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw new UsageError(`--${name}: ${raw}`);
+  return value;
+};

package/src/core/output.ts

@@ -0,0 +1,47 @@
+import type { Redactor } from "./redact";
+
+export interface Writer {
+  write: (text: string) => void;
+}
+
+export interface Output {
+  line: (text?: string) => void;
+  error: (text: string) => void;
+  color: Colors;
+}
+
+export interface Colors {
+  green: (text: string) => string;
+  red: (text: string) => string;
+  yellow: (text: string) => string;
+  dim: (text: string) => string;
+  bold: (text: string) => string;
+}
+
+const paint = (code: number, reset: number) => {
+  return (text: string) => `\u001b[${code}m${text}\u001b[${reset}m`;
+};
+
+const plain = (text: string) => text;
+
+export const createColors = (enabled: boolean): Colors => {
+  if (!enabled) {
+    return { green: plain, red: plain, yellow: plain, dim: plain, bold: plain };
+  }
+  const green = paint(32, 39);
+  const red = paint(31, 39);
+  const yellow = paint(33, 39);
+  return { green, red, yellow, dim: paint(2, 22), bold: paint(1, 22) };
+};
+
+// Every byte the CLI prints goes through the redactor.
+export const createOutput = (
+  out: Writer,
+  err: Writer,
+  redactor: Redactor,
+  colors: boolean
+): Output => {
+  const line = (text = "") => out.write(`${redactor.redact(text)}\n`);
+  const error = (text: string) => err.write(`${redactor.redact(text)}\n`);
+  return { line, error, color: createColors(colors) };
+};