@fire-spark/cli 0.0.0-stage → 0.13.2

package/src/commands/doctor/client/manifests.ts

@@ -0,0 +1,161 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import { emptyChannel } from "./yaml";
+import type { YamlChannel } from "./yaml";
+
+export interface ManifestFile {
+  appDir: string;
+  file: string;
+  body: string;
+  kind: "json" | "ts";
+}
+
+const readOptional = async (path: string) => {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+/** JSON wins. A legacy `.ts` counts only when that app has no JSON. */
+export const listManifests = async (root: string) => {
+  const appsDir = join(root, "apps");
+  let names: string[] = [];
+  try {
+    names = await readdir(appsDir);
+  } catch {
+    return [];
+  }
+  const found: ManifestFile[] = [];
+  for (const name of names) {
+    const appDir = `apps/${name}`;
+    const jsonFile = `${appDir}/src/channel-manifest.json`;
+    const tsFile = `${appDir}/src/channel-manifest.ts`;
+    const json = await readOptional(join(root, jsonFile));
+    if (json !== null) {
+      found.push({ appDir, file: jsonFile, body: json, kind: "json" });
+      continue;
+    }
+    const ts = await readOptional(join(root, tsFile));
+    if (ts === null) continue;
+    found.push({ appDir, file: tsFile, body: ts, kind: "ts" });
+  }
+  return found.toSorted((a, b) => a.file.localeCompare(b.file));
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};
+
+const asText = (value: unknown) => {
+  return typeof value === "string" ? value : null;
+};
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+const TEMPLATES = new Set([
+  "server",
+  "web",
+  "app",
+  "kiosk",
+  "pos",
+  "call-center",
+  "chat"
+]);
+
+/** Null when the manifest is a channel the doctor can accept. */
+export const manifestProblem = (body: string) => {
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return "channel-manifest.json is not valid JSON";
+  }
+  if (!isRecord(json)) return "channel-manifest.json is not an object";
+  const template = json.template;
+  if (typeof template !== "string" || !TEMPLATES.has(template)) {
+    return "template is missing or unknown";
+  }
+  if (typeof json.name !== "string" || !json.name.trim()) {
+    return "name is missing";
+  }
+  const id = json.channel_id;
+  if (template !== "server" && typeof id !== "string") {
+    return "channel_id is missing";
+  }
+  if (template === "server" && id !== null) {
+    return "the server channel_id is set";
+  }
+  if (typeof json.templateVersion !== "string") {
+    return "templateVersion is missing";
+  }
+  if (!SEMVER.test(json.templateVersion)) {
+    return "templateVersion is not a version";
+  }
+  if (typeof json.sdkVersion !== "string") return "sdkVersion is missing";
+  if (!SEMVER.test(json.sdkVersion)) return "sdkVersion is not a version";
+  return null;
+};
+
+const ID_LINE = /^\s*id:\s*(null|"([^"]*)")/m;
+const TEMPLATE_LINE = /^\s*template:\s*"([^"]+)"/m;
+const NAME_LINE = /^\s*name:\s*"([^"]+)"/m;
+const VERSION_LINE = /^\s*templateVersion:\s*"([^"]+)"/m;
+const SDK_LINE = /^\s*sdkVersion:\s*"([^"]+)"/m;
+
+export interface LegacyManifest {
+  channelId: string | null;
+  name: string;
+  template: string;
+  templateVersion: string | null;
+  sdkVersion: string | null;
+}
+
+/** Legacy `channel-manifest.ts`. Missing versions stay null. */
+export const parseLegacyManifest = (body: string): LegacyManifest | null => {
+  const idMatch = ID_LINE.exec(body);
+  const template = TEMPLATE_LINE.exec(body)?.[1];
+  if (!idMatch || !template || !TEMPLATES.has(template)) return null;
+  const channelId = idMatch[1] === "null" ? null : (idMatch[2] ?? null);
+  return {
+    channelId,
+    name: NAME_LINE.exec(body)?.[1] ?? "",
+    template,
+    templateVersion: VERSION_LINE.exec(body)?.[1] ?? null,
+    sdkVersion: SDK_LINE.exec(body)?.[1] ?? null
+  };
+};
+
+/** Reads identity only. Operational keys in the manifest are dropped. */
+export const identityOf = (body: string): YamlChannel | null => {
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!isRecord(json)) return null;
+  if (manifestProblem(body)) return null;
+  const channel = emptyChannel();
+  const id = json.channel_id;
+  channel.channel_id = id === null ? null : asText(id);
+  channel.name = asText(json.name) ?? "";
+  channel.template = asText(json.template) ?? "";
+  channel.template_version = asText(json.templateVersion);
+  channel.sdk_version = asText(json.sdkVersion);
+  return channel;
+};
+
+export const identityFromLegacy = (body: string): YamlChannel | null => {
+  const parsed = parseLegacyManifest(body);
+  if (!parsed) return null;
+  const channel = emptyChannel();
+  channel.channel_id = parsed.channelId;
+  channel.name = parsed.name;
+  channel.template = parsed.template;
+  channel.template_version = parsed.templateVersion;
+  channel.sdk_version = parsed.sdkVersion;
+  return channel;
+};

package/src/commands/doctor/client/options.ts

@@ -0,0 +1,201 @@
+import type { Copy } from "../../../core/i18n";
+import type { OptionSpec } from "../../../core/options";
+
+const text = (es: string, en: string, pt: string): Copy => {
+  return { "es-EC": es, "en-US": en, "pt-BR": pt };
+};
+
+const option = (spec: OptionSpec) => spec;
+
+export const CLIENT_OPTIONS: OptionSpec[] = [
+  option({
+    name: "config",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_CONFIG",
+    description: text(
+      "YAML de config (por ejemplo .bembos.doctor.yml).",
+      "Config YAML (for example .bembos.doctor.yml).",
+      "YAML de config (por exemplo .bembos.doctor.yml)."
+    )
+  }),
+  option({
+    name: "channel",
+    kind: "string",
+    description: text(
+      "Filtra por canal: kiosk, pos, web, app, chat, call-center, server, dashboard.",
+      "Filter by channel: kiosk, pos, web, app, chat, call-center, server, dashboard.",
+      "Filtra por canal: kiosk, pos, web, app, chat, call-center, server, dashboard."
+    )
+  }),
+  option({
+    name: "platform",
+    kind: "string",
+    description: text(
+      "Filtra por capa: web, android, ios, dashboard.",
+      "Filter by platform: web, android, ios, dashboard.",
+      "Filtra por plataforma: web, android, ios, dashboard."
+    )
+  }),
+  option({
+    name: "required",
+    kind: "boolean",
+    description: text(
+      "Solo checks con Requerido = sí.",
+      "Only checks with Required = yes.",
+      "Só checks com Obrigatório = sim."
+    )
+  }),
+  option({
+    name: "area",
+    kind: "string",
+    description: text(
+      "Filtra por área (Pagos, Órdenes, Menú, SDK y config, …).",
+      "Filter by area (Payments, Orders, Menu, SDK and config, …).",
+      "Filtra por área (Pagamentos, Pedidos, Cardápio, SDK e config, …)."
+    )
+  }),
+  option({
+    name: "verification",
+    kind: "string",
+    description: text(
+      "Filtra por verificación: Determinística o Mezcla.",
+      "Filter by verification: Deterministic or Mixed.",
+      "Filtra por verificação: Determinística ou Mista."
+    )
+  }),
+  option({
+    name: "fix",
+    kind: "boolean",
+    description: text(
+      "Intenta arreglar los checks con Fixable = sí. Sin esta flag, solo informa.",
+      "Try to repair checks with Fixable = yes. Without this flag, only report.",
+      "Tenta reparar os checks com Fixable = sim. Sem esta flag, só informa."
+    )
+  }),
+  option({
+    name: "url",
+    kind: "string",
+    description: text(
+      "URL pública del canal desplegado.",
+      "Public URL of the deployed channel.",
+      "URL pública do canal implantado."
+    )
+  }),
+  option({
+    name: "dashboard-url",
+    kind: "string",
+    description: text(
+      "URL del dashboard desplegado.",
+      "URL of the deployed dashboard.",
+      "URL do dashboard implantado."
+    )
+  }),
+  option({
+    name: "api-url",
+    kind: "string",
+    env: "FIRESPARK_API_URL",
+    description: text(
+      "URL de la API del merchant.",
+      "Merchant API URL.",
+      "URL da API do merchant."
+    )
+  }),
+  option({
+    name: "merchant-id",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_MERCHANT_ID",
+    description: text("ID del merchant.", "Merchant id.", "ID do merchant.")
+  }),
+  option({
+    name: "env",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_ENVIRONMENT",
+    description: text(
+      "ID o nombre del ambiente.",
+      "Environment id or name.",
+      "ID ou nome do ambiente."
+    )
+  }),
+  option({
+    name: "store-id",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_STORE_ID",
+    description: text("ID de la tienda.", "Store id.", "ID da loja.")
+  }),
+  option({
+    name: "channel-id",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_CHANNEL_ID",
+    description: text(
+      "channel_id del canal en el YAML.",
+      "channel_id of the channel in the YAML.",
+      "channel_id do canal no YAML."
+    )
+  }),
+  option({
+    name: "fulfillment-id",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_FULFILLMENT_ID",
+    description: text(
+      "ID del fulfillment.",
+      "Fulfillment id.",
+      "ID do fulfillment."
+    )
+  }),
+  option({
+    name: "payment",
+    kind: "string",
+    description: text(
+      "Modo de pago: cash o sandbox. Nunca un cobro real.",
+      "Payment mode: cash or sandbox. Never a real charge.",
+      "Modo de pagamento: cash ou sandbox. Nunca uma cobrança real."
+    )
+  }),
+  option({
+    name: "receiver",
+    kind: "string",
+    description: text(
+      "URL del receptor de webhooks.",
+      "Webhook receiver URL.",
+      "URL do receptor de webhooks."
+    )
+  }),
+  option({
+    name: "evidence",
+    kind: "string",
+    description: text(
+      "Ruta local donde se guarda la evidencia.",
+      "Local path where evidence is stored.",
+      "Caminho local onde a evidência é guardada."
+    )
+  }),
+  option({
+    name: "format",
+    kind: "string",
+    env: "FIRESPARK_DOCTOR_FORMAT",
+    defaultValue: "text",
+    description: text(
+      "Formato de salida: text o json.",
+      "Output format: text or json.",
+      "Formato de saída: text ou json."
+    )
+  }),
+  option({
+    name: "strict",
+    kind: "boolean",
+    description: text(
+      "Falla si algún check se omite.",
+      "Fail when any check is skipped.",
+      "Falha se algum check for omitido."
+    )
+  }),
+  option({
+    name: "deployed",
+    kind: "boolean",
+    description: text(
+      "En init, marca el canal como desplegado.",
+      "On init, mark the channel as deployed.",
+      "No init, marca o canal como implantado."
+    )
+  })
+];

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

@@ -0,0 +1,261 @@
+import { randomUUID } from "node:crypto";
+
+import type { Locale } from "../../../core/i18n";
+import { translate } from "../../../core/i18n";
+import type { Redactor } from "../../../core/redact";
+import type { FetchLike } from "../live/http";
+import type { LiveConfig } from "../live/live.session";
+import { createLiveSession } from "../live/live.session";
+import type { RealtimeToken } from "../live/live.session";
+import { buildOrderBody, doctorOrderId, pickProduct } from "../live/order";
+import type { OrderChanged, WebSocketFactory } from "../live/realtime";
+import { subscribe } from "../live/realtime";
+import type { Subscription } from "../live/realtime";
+import { REASONS, fail } from "../live/result";
+import type { CheckFail, CheckSkip } from "../live/result";
+import { channelLabel, paymentOf } from "./config";
+import { COPY } from "./copy";
+import type { YamlChannel } from "./yaml";
+
+/** Sheet check: place an order on the channel. Not a CLI flag. */
+export const ORDER_CHECK_ID = "ORD-01";
+
+const PLACE_STATUSES = ["ACCEPTED", "IN_PROGRESS", "EXISTS"];
+const AUTH_URL = "https://identitytoolkit.googleapis.com";
+const HTTP_TIMEOUT_MS = 15000;
+const RELEASE_TIMEOUT_MS = 120000;
+
+const nativeSocket = (): WebSocketFactory | undefined => {
+  const Socket = globalThis.WebSocket;
+  if (!Socket) return undefined;
+  return url => new Socket(url) as unknown as ReturnType<WebSocketFactory>;
+};
+
+export interface OrderInput {
+  locale: Locale;
+  env: NodeJS.ProcessEnv;
+  channels: YamlChannel[];
+  channelId?: string;
+  redactor: Redactor;
+  fetch?: FetchLike;
+}
+
+const textOf = (value: string | null | undefined) => {
+  return value?.trim() ?? "";
+};
+
+/** First missing field the test order needs. Empty string means ready. */
+export const orderFieldGap = (channel: YamlChannel, env: NodeJS.ProcessEnv) => {
+  const payment = channel.payment ? paymentOf(channel.payment) : null;
+  if (!payment) return "payment";
+  if (!textOf(channel.merchant_id)) return "merchant_id";
+  if (!textOf(channel.api_url)) return "api_url";
+  if (!textOf(channel.store_id)) return "store_id";
+  if (!textOf(channel.channel_id)) return "channel_id";
+  if (!textOf(channel.fulfillment_id)) return "fulfillment_id";
+  const email = textOf(env.FIRESPARK_DOCTOR_CUSTOMER_EMAIL);
+  if (!email) return "FIRESPARK_DOCTOR_CUSTOMER_EMAIL";
+  const password = textOf(env.FIRESPARK_DOCTOR_CUSTOMER_PASSWORD);
+  if (!password) return "FIRESPARK_DOCTOR_CUSTOMER_PASSWORD";
+  const key = textOf(env.FIRESPARK_DOCTOR_FIREBASE_API_KEY);
+  if (!key) return "FIRESPARK_DOCTOR_FIREBASE_API_KEY";
+  return "";
+};
+
+const channelOf = (channels: YamlChannel[], channelId: string | undefined) => {
+  if (channelId) {
+    return channels.find(channel => channel.channel_id === channelId) ?? null;
+  }
+  if (channels.length !== 1) return null;
+  return channels[0] ?? null;
+};
+
+const missing = (locale: Locale, channel: string, field: string) => {
+  const vars = { channel, field };
+  const detail = translate(locale, COPY.orderMissing, vars);
+  return { status: "fail" as const, detail };
+};
+
+const detailOf = (locale: Locale, result: CheckFail | CheckSkip) => {
+  const message = translate(locale, result.reason.copy, result.reason.vars);
+  if (result.status === "fail") return `${result.hop}: ${message}`;
+  return message;
+};
+
+const msOf = (value: string | undefined, fallback: number) => {
+  const parsed = Number(value);
+  if (!value || !Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+};
+
+const liveConfigOf = (channel: YamlChannel, env: NodeJS.ProcessEnv) => {
+  const apiUrl = textOf(channel.api_url);
+  const firebaseApiKey = textOf(env.FIRESPARK_DOCTOR_FIREBASE_API_KEY);
+  const firebaseAuthUrl = textOf(env.FIRESPARK_DOCTOR_FIREBASE_AUTH_URL);
+  const customerEmail = textOf(env.FIRESPARK_DOCTOR_CUSTOMER_EMAIL);
+  const customerPassword = textOf(env.FIRESPARK_DOCTOR_CUSTOMER_PASSWORD);
+  const storeId = textOf(channel.store_id);
+  const channelId = textOf(channel.channel_id);
+  const fulfillmentId = textOf(channel.fulfillment_id);
+  const rawCurrency = textOf(env.FIRESPARK_DOCTOR_CURRENCY) || "USD";
+  const currency = rawCurrency.toUpperCase();
+  const httpName = env.FIRESPARK_DOCTOR_HTTP_TIMEOUT_MS;
+  const httpTimeoutMs = msOf(httpName, HTTP_TIMEOUT_MS);
+  const b1 = { apiUrl, firebaseApiKey };
+  const b2 = { firebaseAuthUrl: firebaseAuthUrl || AUTH_URL };
+  const b3 = { customerEmail, customerPassword, storeId, channelId };
+  const b4 = { fulfillmentId, currency, httpTimeoutMs };
+  const config: LiveConfig = { ...b1, ...b2, ...b3, ...b4 };
+  return config;
+};
+
+const placeBodyOf = () => {
+  const payment = { type: "CASH" };
+  return { payment };
+};
+
+const tokenGap = (token: RealtimeToken) => {
+  const fields = ["url", "key", "customer_topic", "access_token"] as const;
+  return fields.find(field => !token[field]);
+};
+
+const settled = (id: string, event: OrderChanged) => {
+  if (event.order_id !== id) return false;
+  if (event.checkout_state === "released") return true;
+  return event.checkout_state === "failed";
+};
+
+const joinFail = (locale: Locale, error: unknown) => {
+  const detail = error instanceof Error ? error.message : String(error);
+  const vars = { target: "realtime", detail };
+  const reason = fail("realtime-join", REASONS.network, vars);
+  return { status: "fail" as const, detail: detailOf(locale, reason) };
+};
+
+const releaseOf = (
+  locale: Locale,
+  event: OrderChanged | undefined,
+  seconds: number
+) => {
+  if (event?.checkout_state === "released") {
+    return { status: "pass" as const };
+  }
+  if (event?.checkout_state === "failed") {
+    const detail = event.error?.message?.trim() || "failed";
+    const reason = fail("checkout-release", REASONS.checkoutFailed, { detail });
+    return { status: "fail" as const, detail: detailOf(locale, reason) };
+  }
+  const last = event?.checkout_state || "—";
+  const vars = { seconds, last };
+  const reason = fail("checkout-release", REASONS.timeout, vars);
+  return { status: "fail" as const, detail: detailOf(locale, reason) };
+};
+
+/** Cash and sandbox both place a cash tender. Anything else never places. */
+export const runOrder = async (input: OrderInput) => {
+  const { locale, env, channels, channelId } = input;
+  const chosen = channelOf(channels, channelId);
+  if (!chosen) {
+    const detail = translate(locale, COPY.orderNoChannel);
+    return { status: "fail" as const, detail };
+  }
+  const field = orderFieldGap(chosen, env);
+  if (field) return missing(locale, channelLabel(chosen), field);
+  const config = liveConfigOf(chosen, env);
+  const fetchImpl = input.fetch ?? fetch;
+  const deps = { fetch: fetchImpl };
+  const live = createLiveSession(config, deps, input.redactor);
+  const menus = await live.menus();
+  if (!menus.ok) {
+    const detail = detailOf(locale, menus.result);
+    return { status: "fail" as const, detail };
+  }
+  const product = pickProduct(menus.value, env.FIRESPARK_DOCTOR_PRODUCT_ID);
+  if (!product?.id) {
+    const vars = { what: "menus[].products" };
+    const reason = fail("menu-fetch", REASONS.emptyList, vars);
+    return { status: "fail" as const, detail: detailOf(locale, reason) };
+  }
+  const id = doctorOrderId();
+  const menu = menus.value.find(item => item.products?.includes(product));
+  const lineUid = randomUUID();
+  const menuId = menu?.id;
+  const bodyArgs = { id, config, product, menuId, lineUid };
+  const built = buildOrderBody(bodyArgs);
+  const codes = [201, 202];
+  const createArgs = ["order-create", "POST", "/orders", codes, built] as const;
+  const created = await live.storefront<{ id?: string }>(...createArgs);
+  if (!created.ok) {
+    const detail = detailOf(locale, created.result);
+    return { status: "fail" as const, detail };
+  }
+  if (created.value.id !== id) {
+    const vars = { expected: id, actual: String(created.value.id) };
+    const reason = fail("order-create", REASONS.mismatch, vars);
+    return { status: "fail" as const, detail: detailOf(locale, reason) };
+  }
+  const token = await live.realtimeToken();
+  if (!token.ok) {
+    const detail = detailOf(locale, token.result);
+    return { status: "fail" as const, detail };
+  }
+  const createSocket = nativeSocket();
+  if (!createSocket) {
+    const field = "WebSocket";
+    const reason = fail("realtime-join", REASONS.badShape, { field });
+    return { status: "fail" as const, detail: detailOf(locale, reason) };
+  }
+  const absent = tokenGap(token.value);
+  if (absent) {
+    const reason = fail("realtime-token", REASONS.badShape, { field: absent });
+    return { status: "fail" as const, detail: detailOf(locale, reason) };
+  }
+  const url = token.value.url ?? "";
+  const key = token.value.key ?? "";
+  const topic = token.value.customer_topic ?? "";
+  const accessToken = token.value.access_token ?? "";
+  const joinTimeoutMs = config.httpTimeoutMs;
+  const b1 = { url, key, topic, accessToken };
+  const b2 = { joinTimeoutMs, createSocket };
+  const subscription = subscribe({ ...b1, ...b2 });
+  const joined = await openChannel(locale, subscription);
+  if (joined.status === "fail") return joined;
+  const placePath = `/orders/${encodeURIComponent(id)}/place`;
+  const pay = placeBodyOf();
+  const placeArgs = ["order-place", "POST", placePath, codes, pay] as const;
+  const placed = await live.storefront<{ status?: string }>(...placeArgs);
+  if (!placed.ok) {
+    subscription.close();
+    const detail = detailOf(locale, placed.result);
+    return { status: "fail" as const, detail };
+  }
+  const status = placed.value.status ?? "";
+  if (!PLACE_STATUSES.includes(status)) {
+    subscription.close();
+    const vars = { expected: PLACE_STATUSES.join(" | "), actual: status };
+    const reason = fail("order-place", REASONS.mismatch, vars);
+    return { status: "fail" as const, detail: detailOf(locale, reason) };
+  }
+  const timeoutMs = msOf(env.FIRESPARK_DOCTOR_TIMEOUT_MS, RELEASE_TIMEOUT_MS);
+  const match = (item: OrderChanged) => settled(id, item);
+  const event = await subscription.waitFor(match, timeoutMs);
+  subscription.close();
+  const seconds = Math.round(timeoutMs / 1000);
+  return releaseOf(locale, event, seconds);
+};
+
+const openChannel = async (locale: Locale, subscription: Subscription) => {
+  try {
+    await subscription.joined;
+    return { status: "pass" as const };
+  } catch (error) {
+    subscription.close();
+    return joinFail(locale, error);
+  }
+};
+
+/** `--fix` must not invent ids or place an order. */
+export const fixOrder = (locale: Locale) => {
+  const detail = translate(locale, COPY.orderNoFix);
+  return { status: "fail" as const, detail };
+};