@fire-spark/cli 0.0.0-stage → 0.13.3

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

@@ -0,0 +1,246 @@
+import { spawn } from "node:child_process";
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+
+import type { Command, CommandContext } from "../../../core/command.types";
+import { renderCommandHelp } from "../../../core/help";
+import { translate } from "../../../core/i18n";
+import { UsageError, readString } from "../../../core/options";
+import { areaLabel, checkById, filterChecks } from "./catalog";
+import { CATALOG, parseCheckFilter, verificationLabel } from "./catalog";
+import type { CatalogCheck } from "./catalog";
+import { applyTargets, createConfig, fileExists, preflightGap } from "./config";
+import { promptAll, readConfig, readTargets } from "./config";
+import { resolveConfigPath, writeConfig } from "./config";
+import { COPY, DETAILS, DOCS_PAGE, SUMMARY, USAGE } from "./copy";
+import { CLIENT_OPTIONS } from "./options";
+import { BINDINGS, printRuns, runOne } from "./runner";
+import type { CheckRun } from "./runner";
+import type { YamlChannel } from "./yaml";
+
+const NAMES = new Set(["run", "init", "list", "show", "docs"]);
+
+const formatOf = (context: CommandContext) => {
+  const value = readString(context.options, "format") ?? "text";
+  if (value === "text" || value === "json") return value;
+  throw new UsageError(translate(context.locale, COPY.badFormat));
+};
+
+const wrote = (context: CommandContext, path: string) => {
+  const line = translate(context.locale, COPY.wrote, { path });
+  const json = readString(context.options, "format") === "json";
+  if (json) context.output.error(line);
+  else context.output.line(line);
+};
+
+const askerOf = (context: CommandContext) => {
+  const interactive = context.isTty === true;
+  const ask = async (question: string) => {
+    if (!interactive) return "";
+    if (context.ask) return context.ask(question);
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+      return await rl.question(question);
+    } finally {
+      rl.close();
+    }
+  };
+  return { ask, interactive };
+};
+
+const openPage = (url: string) => {
+  const command = process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    const child = spawn(command, [url], { stdio: "ignore", detached: true });
+    child.on("error", () => undefined);
+    child.unref();
+  } catch {
+    return;
+  }
+};
+
+const docs = (context: CommandContext) => {
+  const url = translate(context.locale, DOCS_PAGE);
+  context.output.line(translate(context.locale, COPY.docsLine, { url }));
+  if (context.isTty === true) openPage(url);
+  return 0;
+};
+
+const loadNew = async (context: CommandContext, path: string) => {
+  const flags = readTargets(context.options, context.locale);
+  const asker = askerOf(context);
+  const args = [context.cwd, flags, context.locale, asker] as const;
+  const file = await createConfig(...args);
+  await writeConfig(path, file);
+  wrote(context, path);
+  return file;
+};
+
+const loadExisting = async (context: CommandContext, path: string) => {
+  const flags = readTargets(context.options, context.locale);
+  const file = await readConfig(path, context.locale);
+  const channels = applyTargets(file.channels, flags, context.locale);
+  return { channels };
+};
+
+const selectedChecks = (context: CommandContext, ids: string[]) => {
+  const filter = parseCheckFilter(context.options, context.locale);
+  if (ids.length === 0) return filterChecks(CATALOG, filter);
+  const checks: CatalogCheck[] = [];
+  for (const id of ids) {
+    const check = checkById(id);
+    if (!check) {
+      const vars = { id };
+      const message = translate(context.locale, COPY.unknownCheck, vars);
+      throw new UsageError(message);
+    }
+    checks.push(check);
+  }
+  return filterChecks(checks, filter);
+};
+
+const showCheck = (context: CommandContext, check: CatalogCheck) => {
+  const { locale, output } = context;
+  const binding = BINDINGS[check.id];
+  const kind = binding ? binding.kind : "unbound";
+  const yes = translate(locale, COPY.yes);
+  const no = translate(locale, COPY.no);
+  const lines = [
+    check.id,
+    check.description,
+    check.acceptance,
+    `${check.channels.join(", ")}`,
+    `${check.platforms.join(", ")}`,
+    areaLabel(check.area, locale),
+    verificationLabel(check.verification, locale),
+    `${check.required ? yes : no}`,
+    `${check.fixable ? yes : no}`,
+    check.notes,
+    check.howTo,
+    kind
+  ];
+  for (const line of lines) output.line(line);
+};
+
+const listChecks = (context: CommandContext, checks: CatalogCheck[]) => {
+  const format = formatOf(context);
+  if (format === "json") {
+    const rows = checks.map(check => {
+      const b1 = { id: check.id, channels: check.channels };
+      const b2 = { platforms: check.platforms, required: check.required };
+      const b3 = { fixable: check.fixable, area: check.area };
+      const b4 = { verification: check.verification };
+      return { ...b1, ...b2, ...b3, ...b4 };
+    });
+    context.output.line(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  for (const check of checks) {
+    const area = areaLabel(check.area, context.locale);
+    const kind = verificationLabel(check.verification, context.locale);
+    context.output.line(`${check.id}  ${area}  ${kind}`);
+  }
+  return 0;
+};
+
+const runChecks = async (
+  context: CommandContext,
+  checks: CatalogCheck[],
+  channels: YamlChannel[],
+  ids: string[]
+) => {
+  const format = formatOf(context);
+  const fix = context.options.fix === true;
+  const strict = context.options.strict === true;
+  const named = new Set(ids.map(id => id.toUpperCase()));
+  const channelId = readString(context.options, "channel-id");
+  const b1 = { locale: context.locale, cwd: context.cwd, env: context.env };
+  const b2 = { channels, channelId, named, redactor: context.redactor };
+  const ctx = { ...b1, ...b2 };
+  const runs: CheckRun[] = [];
+  for (const check of checks) {
+    const outcome = await runOne(check, ctx, fix);
+    runs.push({ id: check.id, outcome });
+  }
+  return printRuns(context.output, context.locale, runs, format, strict);
+};
+
+const guard = (
+  context: CommandContext,
+  channels: Awaited<ReturnType<typeof loadExisting>>
+) => {
+  const gap = preflightGap(channels.channels, context.env);
+  if (!gap) return false;
+  const vars = { channel: gap.channel, field: gap.field };
+  const message = translate(context.locale, COPY.preflight, vars);
+  context.output.error(message);
+  return true;
+};
+
+export const runClientDoctor = async (
+  context: CommandContext,
+  command: Command
+) => {
+  const [name, ...rest] = context.positionals;
+  if (!name) {
+    context.output.line(renderCommandHelp(command, context.locale));
+    return 0;
+  }
+  if (!NAMES.has(name)) {
+    const vars = { name };
+    throw new UsageError(translate(context.locale, COPY.unknownCommand, vars));
+  }
+  if (rest.length > 0 && name !== "run" && name !== "show") {
+    const unknown = rest[0] ?? name;
+    const vars = { name: unknown };
+    const message = translate(context.locale, COPY.unknownCommand, vars);
+    throw new UsageError(message);
+  }
+  if (name === "docs") return docs(context);
+  const flag = readString(context.options, "config");
+  const path = await resolveConfigPath(context.cwd, flag, context.locale);
+  const exists = await fileExists(path);
+  if (name === "init") {
+    if (!exists) {
+      await loadNew(context, path);
+      return 0;
+    }
+    const flags = readTargets(context.options, context.locale);
+    const current = await readConfig(path, context.locale);
+    const merged = applyTargets(current.channels, flags, context.locale);
+    const asker = askerOf(context);
+    const args = [merged, flags, context.locale, asker, false] as const;
+    const channels = await promptAll(...args);
+    await writeConfig(path, { channels });
+    wrote(context, path);
+    return 0;
+  }
+  const read = exists ? loadExisting : loadNew;
+  const loaded = await read(context, path);
+  if (name === "list") return listChecks(context, selectedChecks(context, []));
+  if (name === "show") {
+    if (rest.length !== 1) {
+      throw new UsageError(translate(context.locale, COPY.showOne));
+    }
+    const checks = selectedChecks(context, rest);
+    const check = checks[0];
+    if (!check) throw new UsageError(translate(context.locale, COPY.none));
+    showCheck(context, check);
+    return 0;
+  }
+  if (guard(context, loaded)) return 1;
+  const checks = selectedChecks(context, rest);
+  if (checks.length === 0) {
+    throw new UsageError(translate(context.locale, COPY.none));
+  }
+  return runChecks(context, checks, loaded.channels, rest);
+};
+
+export const clientDoctorCommand: Command = {
+  name: "doctor",
+  usage: USAGE,
+  summary: SUMMARY,
+  details: DETAILS,
+  options: CLIENT_OPTIONS,
+  run: context => runClientDoctor(context, clientDoctorCommand)
+};

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;
+};