@fire-spark/cli 0.0.0-stage → 0.13.2

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

@@ -0,0 +1,346 @@
+import { access, readFile, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+import type { Locale } from "../../../core/i18n";
+import { translate } from "../../../core/i18n";
+import { UsageError, readString } from "../../../core/options";
+import type { OptionValues } from "../../../core/options";
+import { COPY } from "./copy";
+import { identityFromLegacy, identityOf, listManifests } from "./manifests";
+import { emptyChannel, parseDoctorYaml, writeDoctorYaml } from "./yaml";
+import type { DoctorFile, YamlChannel } from "./yaml";
+
+export interface TargetFlags {
+  url?: string;
+  dashboardUrl?: string;
+  apiUrl?: string;
+  storeId?: string;
+  fulfillmentId?: string;
+  payment?: string;
+  receiver?: string;
+  evidence?: string;
+  envName?: string;
+  merchantId?: string;
+  channelId?: string;
+  deployed: boolean;
+}
+
+const URL_FLAGS = ["url", "dashboard-url", "api-url", "receiver"] as const;
+
+export const REQUIRED_FIELDS = [
+  "url",
+  "dashboard_url",
+  "api_url",
+  "store_id",
+  "fulfillment_id",
+  "payment",
+  "receiver",
+  "evidence"
+] as const;
+
+export type RequiredField = (typeof REQUIRED_FIELDS)[number];
+
+export const CREDENTIAL_ENV = [
+  "FIRESPARK_DOCTOR_CUSTOMER_EMAIL",
+  "FIRESPARK_DOCTOR_CUSTOMER_PASSWORD"
+] as const;
+
+const httpUrl = (value: string) => /^https?:\/\//i.test(value);
+
+export const paymentOf = (value: string) => {
+  const text = value.trim().toLowerCase();
+  if (text === "cash" || text === "efectivo") return "cash";
+  if (text === "sandbox") return "sandbox";
+  return null;
+};
+
+export const readTargets = (values: OptionValues, locale: Locale) => {
+  const raw = (name: string) => readString(values, name);
+  for (const flag of URL_FLAGS) {
+    const value = raw(flag);
+    if (value && !httpUrl(value)) {
+      throw new UsageError(translate(locale, COPY.badUrl, { flag }));
+    }
+  }
+  const paymentText = raw("payment");
+  const payment = paymentText ? paymentOf(paymentText) : undefined;
+  if (paymentText && !payment) {
+    throw new UsageError(translate(locale, COPY.badPayment));
+  }
+  const flags: TargetFlags = {
+    url: raw("url"),
+    dashboardUrl: raw("dashboard-url"),
+    apiUrl: raw("api-url"),
+    storeId: raw("store-id"),
+    fulfillmentId: raw("fulfillment-id"),
+    payment: payment ?? undefined,
+    receiver: raw("receiver"),
+    evidence: raw("evidence"),
+    envName: raw("env"),
+    merchantId: raw("merchant-id"),
+    channelId: raw("channel-id"),
+    deployed: values.deployed === true
+  };
+  return flags;
+};
+
+const hasTarget = (flags: TargetFlags) => {
+  const { deployed, channelId, ...rest } = flags;
+  void channelId;
+  if (deployed) return true;
+  return Object.values(rest).some(value => value !== undefined);
+};
+
+const fill = (channel: YamlChannel, flags: TargetFlags): YamlChannel => {
+  const next: YamlChannel = { ...channel };
+  if (flags.url) next.url = flags.url;
+  if (flags.dashboardUrl) next.dashboard_url = flags.dashboardUrl;
+  if (flags.apiUrl) next.api_url = flags.apiUrl;
+  if (flags.storeId) next.store_id = flags.storeId;
+  if (flags.fulfillmentId) next.fulfillment_id = flags.fulfillmentId;
+  if (flags.payment) next.payment = flags.payment;
+  if (flags.receiver) next.receiver = flags.receiver;
+  if (flags.evidence) next.evidence = flags.evidence;
+  if (flags.envName) next.env = flags.envName;
+  if (flags.merchantId) next.merchant_id = flags.merchantId;
+  if (flags.deployed) next.deployed = true;
+  if (flags.channelId && channel.channel_id === flags.channelId) {
+    next.channel_id = flags.channelId;
+  }
+  return next;
+};
+
+export const applyTargets = (
+  channels: YamlChannel[],
+  flags: TargetFlags,
+  locale: Locale
+) => {
+  if (!hasTarget(flags)) return channels;
+  if (flags.channelId) {
+    const index = channels.findIndex(c => c.channel_id === flags.channelId);
+    if (index < 0) {
+      const id = flags.channelId;
+      throw new UsageError(translate(locale, COPY.unknownChannel, { id }));
+    }
+    return channels.map((channel, i) => {
+      return i === index ? fill(channel, flags) : channel;
+    });
+  }
+  if (channels.length !== 1) {
+    throw new UsageError(translate(locale, COPY.ambiguous));
+  }
+  const only = channels[0];
+  if (!only) return channels;
+  return [fill(only, flags)];
+};
+
+export const channelLabel = (channel: YamlChannel) => {
+  if (channel.name.trim()) return channel.name.trim();
+  if (channel.channel_id) return channel.channel_id;
+  return channel.template || "channel";
+};
+
+const missingField = (channel: YamlChannel): RequiredField | null => {
+  for (const field of REQUIRED_FIELDS) {
+    if (field === "payment") continue;
+    const value = channel[field];
+    if (typeof value !== "string" || value.trim() === "") return field;
+  }
+  const payment = channel.payment ? paymentOf(channel.payment) : null;
+  if (!payment) return "payment";
+  return null;
+};
+
+export interface PreflightGap {
+  channel: string;
+  field: string;
+}
+
+export const preflightGap = (
+  channels: YamlChannel[],
+  env: NodeJS.ProcessEnv
+): PreflightGap | null => {
+  for (const channel of channels) {
+    if (!channel.deployed) continue;
+    const field = missingField(channel);
+    if (field) return { channel: channelLabel(channel), field };
+    for (const name of CREDENTIAL_ENV) {
+      const value = env[name];
+      if (!value || !value.trim()) {
+        return { channel: channelLabel(channel), field: name };
+      }
+    }
+  }
+  return null;
+};
+
+export const fileExists = async (path: string) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const resolveConfigPath = async (
+  cwd: string,
+  flag: string | undefined,
+  locale: Locale
+) => {
+  if (flag) return isAbsolute(flag) ? flag : resolve(cwd, flag);
+  let names: string[] = [];
+  try {
+    names = await readdir(cwd);
+  } catch {
+    names = [];
+  }
+  const found = names.filter(name => name.endsWith(".doctor.yml")).sort();
+  if (found.length > 1) {
+    const files = found.join(", ");
+    throw new UsageError(translate(locale, COPY.manyConfigs, { files }));
+  }
+  const only = found[0];
+  if (only) return resolve(cwd, only);
+  return resolve(cwd, ".firespark.doctor.yml");
+};
+
+export const readConfig = async (path: string, locale: Locale) => {
+  const body = await readFile(path, "utf8");
+  return parseDoctorYaml(body, path, locale);
+};
+
+export const writeConfig = async (path: string, file: DoctorFile) => {
+  await writeFile(path, writeDoctorYaml(file), "utf8");
+};
+
+const YES = new Set(["si", "sí", "yes", "y", "s", "sim"]);
+const NO = new Set(["no", "n", "nao", "não"]);
+
+const foldAnswer = (value: string) => value.trim().toLowerCase();
+
+export interface Asker {
+  ask: (question: string) => Promise<string>;
+  interactive: boolean;
+}
+
+const askYes = async (channel: YamlChannel, locale: Locale, asker: Asker) => {
+  const labelText = channelLabel(channel);
+  const question = translate(locale, COPY.deployedAsk, { channel: labelText });
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const answer = foldAnswer(await asker.ask(question));
+    if (YES.has(answer)) return true;
+    if (NO.has(answer)) return false;
+  }
+  const vars = { channel: labelText };
+  throw new UsageError(translate(locale, COPY.answerYesNo, vars));
+};
+
+const ASK: Record<RequiredField, (typeof COPY)[keyof typeof COPY]> = {
+  url: COPY.askUrl,
+  dashboard_url: COPY.askDashboard,
+  api_url: COPY.askApi,
+  store_id: COPY.askStore,
+  fulfillment_id: COPY.askFulfillment,
+  payment: COPY.askPayment,
+  receiver: COPY.askReceiver,
+  evidence: COPY.askEvidence
+};
+
+const askField = async (
+  channel: YamlChannel,
+  field: RequiredField,
+  locale: Locale,
+  asker: Asker
+) => {
+  const labelText = channelLabel(channel);
+  const question = translate(locale, ASK[field], { channel: labelText });
+  const answer = (await asker.ask(question)).trim();
+  if (!answer) return null;
+  if (field === "payment") {
+    const payment = paymentOf(answer);
+    if (!payment)
+      throw new UsageError(translate(locale, COPY.badAnswerPayment));
+    return payment;
+  }
+  if (field === "url" || field === "dashboard_url" || field === "api_url") {
+    if (!httpUrl(answer)) {
+      throw new UsageError(translate(locale, COPY.badUrl, { flag: field }));
+    }
+  }
+  if (field === "receiver" && !httpUrl(answer)) {
+    throw new UsageError(translate(locale, COPY.badUrl, { flag: "receiver" }));
+  }
+  return answer;
+};
+
+const promptChannel = async (
+  channel: YamlChannel,
+  flags: TargetFlags,
+  locale: Locale,
+  asker: Asker,
+  askDeployed: boolean
+) => {
+  const next: YamlChannel = { ...channel };
+  const marked = flags.deployed && flags.channelId === channel.channel_id;
+  const sole = flags.deployed && !flags.channelId;
+  if (askDeployed && !next.deployed && asker.interactive && !marked && !sole) {
+    next.deployed = await askYes(next, locale, asker);
+  }
+  if (!next.deployed || !asker.interactive) return next;
+  for (const field of REQUIRED_FIELDS) {
+    const value = next[field];
+    if (typeof value === "string" && value.trim()) continue;
+    const answer = await askField(next, field, locale, asker);
+    if (answer) next[field] = answer;
+  }
+  return next;
+};
+
+export const promptAll = async (
+  channels: YamlChannel[],
+  flags: TargetFlags,
+  locale: Locale,
+  asker: Asker,
+  askDeployed: boolean
+) => {
+  const next: YamlChannel[] = [];
+  for (const channel of channels) {
+    const args = [channel, flags, locale, asker, askDeployed] as const;
+    const filled = await promptChannel(...args);
+    next.push(filled);
+  }
+  return next;
+};
+
+export const identitiesFromRepo = async (root: string) => {
+  const files = await listManifests(root);
+  const channels: YamlChannel[] = [];
+  for (const file of files) {
+    const read = file.kind === "json" ? identityOf : identityFromLegacy;
+    const channel = read(file.body);
+    if (channel) channels.push(channel);
+  }
+  return channels;
+};
+
+export const createConfig = async (
+  root: string,
+  flags: TargetFlags,
+  locale: Locale,
+  asker: Asker
+) => {
+  const seeded = await identitiesFromRepo(root);
+  let seed = seeded;
+  const empty = seeded.length === 0;
+  const targeted = hasTarget(flags) || flags.channelId;
+  const needsBlank = empty && targeted;
+  if (needsBlank) {
+    const blank = emptyChannel();
+    if (flags.channelId) blank.channel_id = flags.channelId;
+    seed = [blank];
+  }
+  const withFlags = applyTargets(seed, flags, locale);
+  const channels = await promptAll(withFlags, flags, locale, asker, true);
+  return { channels } satisfies DoctorFile;
+};

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

@@ -0,0 +1,228 @@
+import type { Copy } from "../../../core/i18n";
+
+const text = (es: string, en: string, pt: string): Copy => {
+  return { "es-EC": es, "en-US": en, "pt-BR": pt };
+};
+
+export const DOCS_PAGE: Copy = {
+  "es-EC": "https://firespark.cloud/docs/es/guides/doctor",
+  "en-US": "https://firespark.cloud/docs/guides/doctor",
+  "pt-BR": "https://firespark.cloud/docs/guides/doctor"
+};
+
+export const SUMMARY = text(
+  "Revisa el FireSpark ya desplegado de un merchant.",
+  "Checks a merchant's already deployed FireSpark.",
+  "Verifica o FireSpark já implantado de um merchant."
+);
+
+export const USAGE =
+  "firespark doctor <run|list|show|init|docs> [ID ...] [options]";
+
+const detailsEs = [
+  "Comandos: run [ID ...], list, show <ID>, init [--config <archivo>], docs.",
+  "run ejecuta los checks contra el FireSpark ya desplegado. Sin --fix solo informa.",
+  "Si falta el YAML, se crea aquí con init y se pregunta solo lo que falte.",
+  "Un canal que nunca se desplegó puede quedar solo con su identidad.",
+  "ORD-01 crea una orden de prueba solo si lo nombras y el pago es cash o sandbox. Antes de place se une al canal realtime y espera a que el checkout se libere.",
+  `La documentación está aquí: ${DOCS_PAGE["es-EC"]}`
+].join("\n");
+
+const detailsEn = [
+  "Commands: run [ID ...], list, show <ID>, init [--config <file>], docs.",
+  "run checks an already deployed FireSpark. Without --fix it only reports.",
+  "If the YAML is missing, init creates it here and asks only for what is missing.",
+  "A channel that was never deployed can keep identity only.",
+  "ORD-01 places a test order only when you name it and payment is cash or sandbox. It joins the realtime channel before place and waits until checkout is released.",
+  `Documentation: ${DOCS_PAGE["en-US"]}`
+].join("\n");
+
+const detailsPt = [
+  "Comandos: run [ID ...], list, show <ID>, init [--config <arquivo>], docs.",
+  "run verifica o FireSpark já implantado. Sem --fix, só informa.",
+  "Se o YAML não existe, o init cria o arquivo aqui e pergunta só o que falta.",
+  "Um canal que nunca foi implantado pode ficar só com a identidade.",
+  "ORD-01 cria um pedido de teste só se você o nomear e o pagamento for cash ou sandbox. Ele entra no canal realtime antes do place e espera o checkout ser liberado.",
+  `A documentação está aqui: ${DOCS_PAGE["pt-BR"]}`
+].join("\n");
+
+export const DETAILS: Copy = {
+  "es-EC": detailsEs,
+  "en-US": detailsEn,
+  "pt-BR": detailsPt
+};
+
+export const COPY = {
+  unknownCommand: text(
+    "Comando desconocido: {name}. Usa run, list, show, init o docs.",
+    "Unknown command: {name}. Use run, list, show, init, or docs.",
+    "Comando desconhecido: {name}. Use run, list, show, init ou docs."
+  ),
+  unknownCheck: text(
+    "Check desconocido: {id}",
+    "Unknown check: {id}",
+    "Check desconhecido: {id}"
+  ),
+  none: text(
+    "Ningún check coincide con esos filtros.",
+    "No check matches those filters.",
+    "Nenhum check corresponde a esses filtros."
+  ),
+  showOne: text(
+    "show necesita un solo ID.",
+    "show needs exactly one ID.",
+    "show precisa de um único ID."
+  ),
+  manyConfigs: text(
+    "Hay varios YAML ({files}). Pasa --config con el archivo que quieres.",
+    "Several YAML files ({files}). Pass --config with the one you want.",
+    "Há vários YAML ({files}). Passe --config com o arquivo que você quer."
+  ),
+  ambiguous: text(
+    "Hay varios canales. Pasa --channel-id para aplicar esas flags.",
+    "There are several channels. Pass --channel-id to apply those flags.",
+    "Há vários canais. Passe --channel-id para aplicar essas flags."
+  ),
+  unknownChannel: text(
+    "No existe un canal con channel_id {id} en el YAML.",
+    "No channel with channel_id {id} exists in the YAML.",
+    "Não existe um canal com channel_id {id} no YAML."
+  ),
+  badPayment: text(
+    "--payment solo acepta cash o sandbox.",
+    "--payment only accepts cash or sandbox.",
+    "--payment só aceita cash ou sandbox."
+  ),
+  badFormat: text(
+    "--format solo acepta text o json.",
+    "--format only accepts text or json.",
+    "--format só aceita text ou json."
+  ),
+  badUrl: text(
+    "--{flag} tiene que ser una URL http o https.",
+    "--{flag} must be an http or https URL.",
+    "--{flag} tem que ser uma URL http ou https."
+  ),
+  badYaml: text(
+    "No pude leer {path}: {detail}",
+    "Could not read {path}: {detail}",
+    "Não consegui ler {path}: {detail}"
+  ),
+  preflight: text(
+    "El canal {channel} está desplegado y le falta {field}. No se ejecutó ningún check.",
+    "Channel {channel} is deployed and is missing {field}. No checks ran.",
+    "O canal {channel} está implantado e falta {field}. Nenhum check rodou."
+  ),
+  wrote: text(
+    "Configuración lista: {path}",
+    "Configuration ready: {path}",
+    "Configuração pronta: {path}"
+  ),
+  deployedAsk: text(
+    "¿El canal {channel} está desplegado? (sí/no) ",
+    "Is channel {channel} deployed? (yes/no) ",
+    "O canal {channel} está implantado? (sim/não) "
+  ),
+  answerYesNo: text(
+    "Responde sí o no para el canal {channel}. No adivino si está desplegado.",
+    "Answer yes or no for channel {channel}. I will not guess if it is deployed.",
+    "Responda sim ou não para o canal {channel}. Não adivinho se está implantado."
+  ),
+  askUrl: text(
+    "URL pública de {channel}: ",
+    "Public URL of {channel}: ",
+    "URL pública de {channel}: "
+  ),
+  askDashboard: text(
+    "URL del dashboard de {channel}: ",
+    "Dashboard URL of {channel}: ",
+    "URL do dashboard de {channel}: "
+  ),
+  askApi: text(
+    "URL de la API de {channel}: ",
+    "API URL of {channel}: ",
+    "URL da API de {channel}: "
+  ),
+  askStore: text(
+    "store-id de {channel}: ",
+    "store-id of {channel}: ",
+    "store-id de {channel}: "
+  ),
+  askFulfillment: text(
+    "fulfillment-id de {channel}: ",
+    "fulfillment-id of {channel}: ",
+    "fulfillment-id de {channel}: "
+  ),
+  askPayment: text(
+    "Pago de {channel} (cash o sandbox): ",
+    "Payment of {channel} (cash or sandbox): ",
+    "Pagamento de {channel} (cash ou sandbox): "
+  ),
+  askReceiver: text(
+    "URL del receptor de webhooks de {channel}: ",
+    "Webhook receiver URL of {channel}: ",
+    "URL do receptor de webhooks de {channel}: "
+  ),
+  askEvidence: text(
+    "Ruta de evidencia de {channel}: ",
+    "Evidence path of {channel}: ",
+    "Caminho de evidência de {channel}: "
+  ),
+  badAnswerPayment: text(
+    "El pago tiene que ser cash o sandbox.",
+    "Payment has to be cash or sandbox.",
+    "O pagamento tem que ser cash ou sandbox."
+  ),
+  docsLine: text(
+    "La documentación está aquí: {url}",
+    "Documentation: {url}",
+    "A documentação está aqui: {url}"
+  ),
+  orderMissing: text(
+    "El canal {channel} le falta {field}. No se creó ninguna orden.",
+    "Channel {channel} is missing {field}. No order was created.",
+    "O canal {channel} falta {field}. Nenhum pedido foi criado."
+  ),
+  orderNoChannel: text(
+    "Falta channel_id para elegir el canal. No se creó ninguna orden.",
+    "channel_id is missing, so no channel was chosen. No order was created.",
+    "Falta channel_id para escolher o canal. Nenhum pedido foi criado."
+  ),
+  orderSkipped: text(
+    "ORD-01 solo corre cuando lo nombras. No se creó ninguna orden.",
+    "ORD-01 runs only when you name it. No order was created.",
+    "ORD-01 só roda quando você o nomeia. Nenhum pedido foi criado."
+  ),
+  orderNoFix: text(
+    "No hay un arreglo automático para ORD-01. No se creó ninguna orden.",
+    "There is no automatic repair for ORD-01. No order was created.",
+    "Não há um reparo automático para ORD-01. Nenhum pedido foi criado."
+  ),
+  unbound: text(
+    "Este check todavía no tiene flujo en esta versión.",
+    "This check has no flow in this version yet.",
+    "Este check ainda não tem fluxo nesta versão."
+  ),
+  noManifests: text(
+    "Este repo no tiene apps/*/src/channel-manifest.json.",
+    "This repo has no apps/*/src/channel-manifest.json.",
+    "Este repo não tem apps/*/src/channel-manifest.json."
+  ),
+  duplicateId: text(
+    "channel_id {id} está en {left} y en {right}.",
+    "channel_id {id} is in {left} and in {right}.",
+    "channel_id {id} está em {left} e em {right}."
+  ),
+  noSafeFix: text(
+    "No hay un arreglo automático que no invente un channel_id. No cambié ningún archivo.",
+    "There is no automatic repair that does not invent a channel_id. No file was changed.",
+    "Não há um reparo automático que não invente um channel_id. Nenhum arquivo mudou."
+  ),
+  strictSkipped: text(
+    "Modo estricto: hay checks omitidos.",
+    "Strict mode: some checks were skipped.",
+    "Modo estrito: há checks omitidos."
+  ),
+  yes: text("sí", "yes", "sim"),
+  no: text("no", "no", "não")
+} as const;