@fire-spark/cli 0.13.2 → 0.13.3

package/src/commands/doctor/client/content.flow.ts

@@ -0,0 +1,450 @@
+import type { Copy } from "../../../core/i18n";
+import { dataOf } from "../live/http";
+import { fromLive, isOutcome, isRecord, openLive, prepare } from "./flow";
+import { queryOf, say, textOf, trpcCall, withSafeFix } from "./flow";
+import { readSources } from "./repo.scan";
+import type { CheckBinding, Outcome, RunCtx } from "./runner";
+import type { YamlChannel } from "./yaml";
+
+const line = (es: string, en: string, pt: string): Copy => {
+  return { "es-EC": es, "en-US": en, "pt-BR": pt };
+};
+
+const COPY = {
+  channel: line(
+    "{id} no aplica al canal {template}.",
+    "{id} does not apply to the {template} channel.",
+    "{id} não se aplica ao canal {template}."
+  ),
+  list: line(
+    "El menú no es una lista.",
+    "The menu is not a list.",
+    "O cardápio não é uma lista."
+  ),
+  named: line(
+    "{id} solo corre cuando lo nombras. No cambié la cuenta.",
+    "{id} runs only when you name it. The account was not changed.",
+    "{id} só roda quando você o nomeia. A conta não foi alterada."
+  ),
+  need: line(
+    "{id} se omite: falta {field}.",
+    "{id} is skipped: {field} is missing.",
+    "{id} é omitido: falta {field}."
+  ),
+  home: line(
+    "CMS-02 se omite: este canal no publicó el bloque de home.",
+    "CMS-02 is skipped: this channel did not publish the home block.",
+    "CMS-02 é omitido: este canal não publicou o bloco da home."
+  ),
+  shape: line(
+    "El bloque de home no tiene la forma esperada.",
+    "The home block does not have the expected shape.",
+    "O bloco da home não tem a forma esperada."
+  ),
+  offline: line(
+    "El repo del canal no maneja imágenes sin red.",
+    "The channel repo does not handle images while offline.",
+    "O repo do canal não trata imagens sem rede."
+  ),
+  keypad: line(
+    "El repo del canal no tiene el keypad.",
+    "The channel repo does not include the keypad.",
+    "O repo do canal não tem o keypad."
+  ),
+  block: line(
+    "CMS-01 se omite: no hay un block de CMS publicado para este canal.",
+    "CMS-01 is skipped: there is no published CMS block for this channel.",
+    "CMS-01 é omitido: não há um block de CMS publicado para este canal."
+  ),
+  long: line(
+    "El block supera 25 ítems o un LIST supera 10 hijos.",
+    "The block has more than 25 items, or a LIST has more than 10 children.",
+    "O block passa de 25 itens ou um LIST passa de 10 filhos."
+  )
+};
+
+const LIVE = [
+  "api_url",
+  "channel_id",
+  "FIRESPARK_DOCTOR_CUSTOMER_EMAIL",
+  "FIRESPARK_DOCTOR_CUSTOMER_PASSWORD",
+  "FIRESPARK_DOCTOR_FIREBASE_API_KEY"
+] as const;
+
+const LIST_MAX = 25;
+const CHILD_MAX = 10;
+
+const applies = (ctx: RunCtx, id: string, allowed: ReadonlySet<string>) => {
+  const ready = prepare(ctx, ["channel_id"]);
+  if (isOutcome(ready)) return ready;
+  const template = textOf(ready.template);
+  if (allowed.has(template)) return null;
+  return say(ctx.locale, "skip", COPY.channel, { id, template });
+};
+
+const menusOf = async (ctx: RunCtx, channel: YamlChannel) => {
+  const live = openLive(ctx, channel);
+  const path = queryOf("/menus", { channel_id: textOf(channel.channel_id) });
+  const codes = [200];
+  const args = ["menus", "GET", path, codes] as const;
+  const step = await live.storefront<unknown>(...args);
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  if (!Array.isArray(step.value)) return say(ctx.locale, "fail", COPY.list);
+  return live;
+};
+
+const homeName = (template: string) => {
+  if (template === "app" || template === "kiosk") return "home-hero-video-app";
+  return "home-hero-banners-web";
+};
+
+const blockOf = async (ctx: RunCtx, channel: YamlChannel, name: string) => {
+  const live = openLive(ctx, channel);
+  const path = `/cms/blocks/${encodeURIComponent(name)}`;
+  const codes = [200, 404];
+  const args = ["cms", "GET", path, codes] as const;
+  const step = await live.probe(...args);
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  if (step.value.status === 404) return null;
+  const data = dataOf<unknown>(step.value);
+  if (data === undefined) return say(ctx.locale, "fail", COPY.shape);
+  return data;
+};
+
+const passwordToken = async (ctx: RunCtx, channel: YamlChannel) => {
+  const key = textOf(ctx.env.FIRESPARK_DOCTOR_FIREBASE_API_KEY);
+  const auth = textOf(ctx.env.FIRESPARK_DOCTOR_FIREBASE_AUTH_URL);
+  const email = textOf(ctx.env.FIRESPARK_DOCTOR_CUSTOMER_EMAIL);
+  const password = textOf(ctx.env.FIRESPARK_DOCTOR_CUSTOMER_PASSWORD);
+  const base = (auth || "https://identitytoolkit.googleapis.com").replace(
+    /\/$/,
+    ""
+  );
+  const url = `${base}/v1/accounts:signInWithPassword?key=${key}`;
+  const body = JSON.stringify({ email, password, returnSecureToken: true });
+  const headers = { "content-type": "application/json" };
+  const signal = AbortSignal.timeout(15000);
+  const signed = await fetch(url, { method: "POST", headers, body, signal });
+  const signedJson = (await signed.json()) as { idToken?: string };
+  if (!signed.ok || !signedJson.idToken) return "";
+  const api = textOf(channel.api_url).replace(/\/$/, "");
+  const grant = "urn:ietf:params:oauth:grant-type:token-exchange";
+  const subject = "urn:ietf:params:oauth:token-type:id_token";
+  const exchange = {
+    grant_type: grant,
+    subject_token: signedJson.idToken,
+    subject_token_type: subject
+  };
+  const exchangeUrl = `${api}/api/storefront/v1/oauth/exchange`;
+  const payload = JSON.stringify(exchange);
+  const init = { method: "POST", headers, body: payload, signal };
+  const traded = await fetch(exchangeUrl, init);
+  const bag = (await traded.json()) as {
+    access_token?: string;
+    data?: { access_token?: string };
+  };
+  return bag.access_token ?? bag.data?.access_token ?? "";
+};
+
+const runLog11 = async (ctx: RunCtx): Promise<Outcome> => {
+  const allowed = new Set(["kiosk", "web", "app", "call-center", "dashboard"]);
+  const skipped = applies(ctx, "LOG-11", allowed);
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  let token = "";
+  try {
+    token = await passwordToken(ctx, ready);
+  } catch {
+    return say(ctx.locale, "fail", COPY.shape);
+  }
+  if (!token) return say(ctx.locale, "fail", COPY.shape);
+  const channelId = textOf(ready.channel_id);
+  const api = textOf(ready.api_url).replace(/\/$/, "");
+  const menus = `${api}/api/storefront/v1/menus?channel_id=${channelId}`;
+  const authorization = `Bearer ${token}`;
+  try {
+    const response = await fetch(menus, { headers: { authorization } });
+    if (!response.ok) return say(ctx.locale, "fail", COPY.shape);
+  } catch {
+    return say(ctx.locale, "fail", COPY.shape);
+  }
+  return { status: "pass" };
+};
+
+const runCms02 = async (ctx: RunCtx): Promise<Outcome> => {
+  const allowed = new Set(["kiosk", "web", "app", "chat", "call-center"]);
+  const skipped = applies(ctx, "CMS-02", allowed);
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const name = homeName(textOf(ready.template));
+  const block = await blockOf(ctx, ready, name);
+  if (isOutcome(block)) return block;
+  if (!block) return say(ctx.locale, "skip", COPY.home);
+  if (
+    !isRecord(block) ||
+    !Array.isArray(block.items) ||
+    block.items.length === 0
+  ) {
+    return say(ctx.locale, "fail", COPY.shape);
+  }
+  const items = block.items.filter(isRecord);
+  const image = items.some(item => {
+    if (typeof item.image_url === "string" && item.image_url) return true;
+    return item.type === "IMAGE" || isRecord(item.image);
+  });
+  const video = items.some(item => {
+    if (typeof item.video_url === "string" && item.video_url) return true;
+    return item.type === "VIDEO" || isRecord(item.video);
+  });
+  const template = textOf(ready.template);
+  if (template === "app" || template === "kiosk") {
+    if (!video || !image) return say(ctx.locale, "fail", COPY.shape);
+    return { status: "pass" };
+  }
+  if (!image) return say(ctx.locale, "fail", COPY.shape);
+  return { status: "pass" };
+};
+
+const runCms01 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "CMS-01", new Set(["kiosk", "dashboard"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const block = await blockOf(ctx, ready, homeName(textOf(ready.template)));
+  if (isOutcome(block)) return block;
+  if (!isRecord(block) || !Array.isArray(block.items)) {
+    return say(ctx.locale, "skip", COPY.block);
+  }
+  const lists = block.items.filter(isRecord).filter(row => {
+    return row.type === "LIST";
+  });
+  const broken = lists.some(row => !Array.isArray(row.items));
+  if (broken) return say(ctx.locale, "fail", COPY.shape);
+  const overItems = block.items.length > LIST_MAX;
+  const overChildren = lists.some(row => {
+    return Array.isArray(row.items) && row.items.length > CHILD_MAX;
+  });
+  if (overItems || overChildren) return say(ctx.locale, "fail", COPY.long);
+  return { status: "pass" };
+};
+
+const onlyNamed = (ctx: RunCtx, id: string) => {
+  if (ctx.named.has(id)) return null;
+  return say(ctx.locale, "skip", COPY.named, { id });
+};
+
+const need = (ctx: RunCtx, id: string, field: string) => {
+  return say(ctx.locale, "skip", COPY.need, { id, field });
+};
+
+const deviceGap = (env: NodeJS.ProcessEnv) => {
+  if (!textOf(env.FIRESPARK_DOCTOR_DEVICE_UID)) {
+    return "FIRESPARK_DOCTOR_DEVICE_UID";
+  }
+  if (!textOf(env.FIRESPARK_DOCTOR_DEVICE_SECRET)) {
+    return "FIRESPARK_DOCTOR_DEVICE_SECRET";
+  }
+  return "";
+};
+
+const runLog12 = async (ctx: RunCtx): Promise<Outcome> => {
+  const allowed = new Set(["kiosk", "web", "app", "dashboard"]);
+  const skipped = applies(ctx, "LOG-12", allowed);
+  if (skipped) return skipped;
+  const named = onlyNamed(ctx, "LOG-12");
+  if (named) return named;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const live = openLive(ctx, ready);
+  const codes = [200];
+  const args = ["delete-customer", "DELETE", "/customers/me", codes] as const;
+  const step = await live.storefront<unknown>(...args);
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  return { status: "pass" };
+};
+
+const badPassword = async (ctx: RunCtx) => {
+  const key = textOf(ctx.env.FIRESPARK_DOCTOR_FIREBASE_API_KEY);
+  const authUrl = textOf(ctx.env.FIRESPARK_DOCTOR_FIREBASE_AUTH_URL);
+  const base = authUrl || "https://identitytoolkit.googleapis.com";
+  const email = textOf(ctx.env.FIRESPARK_DOCTOR_CUSTOMER_EMAIL);
+  const url = `${base}/v1/accounts:signInWithPassword?key=${key}`;
+  const body = { email, password: "not-the-password", returnSecureToken: true };
+  const signal = AbortSignal.timeout(15000);
+  const headers = { "content-type": "application/json" };
+  const payload = JSON.stringify(body);
+  const init = { method: "POST", headers, body: payload, signal };
+  try {
+    const response = await fetch(url, init);
+    return response.status;
+  } catch {
+    return 0;
+  }
+};
+
+const runLog13 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "LOG-13", new Set(["dashboard"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const loaded = await menusOf(ctx, ready);
+  if (isOutcome(loaded)) return loaded;
+  const status = await badPassword(ctx);
+  if (status !== 400 && status !== 401 && status !== 403) {
+    return say(ctx.locale, "fail", COPY.shape);
+  }
+  return { status: "pass" };
+};
+
+const runLog14 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "LOG-14", new Set(["dashboard"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const live = openLive(ctx, ready);
+  const codes = [200];
+  const args = ["preferences", "GET", "/preferences", codes] as const;
+  const step = await live.storefront<unknown>(...args);
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  const security = isRecord(step.value) ? step.value.security : undefined;
+  const required = isRecord(security) && security.mfa_required === true;
+  if (!required)
+    return need(ctx, "LOG-14", "preferences.security.mfa_required");
+  const secret = textOf(ctx.env.FIRESPARK_DOCTOR_TOTP_SECRET);
+  if (!secret) return need(ctx, "LOG-14", "FIRESPARK_DOCTOR_TOTP_SECRET");
+  return need(ctx, "LOG-14", "supabase.auth.mfa.challenge");
+};
+
+const heartbeat = async (ctx: RunCtx, channel: YamlChannel, path: string) => {
+  const live = openLive(ctx, channel);
+  const device_uid = textOf(ctx.env.FIRESPARK_DOCTOR_DEVICE_UID);
+  const device_secret = textOf(ctx.env.FIRESPARK_DOCTOR_DEVICE_SECRET);
+  const version = { app_version_code: 1, app_version_name: "doctor" };
+  const body = { device_uid, device_secret, ...version };
+  const codes = [200, 401, 403];
+  const args = ["device", "POST", path, codes, body] as const;
+  return live.probe(...args);
+};
+
+const runLog15 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "LOG-15", new Set(["pos", "dashboard"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const field = deviceGap(ctx.env);
+  if (field) return need(ctx, "LOG-15", field);
+  const step = await heartbeat(ctx, ready, "/pos/devices/me");
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  if (step.value.status !== 200) return say(ctx.locale, "fail", COPY.shape);
+  return { status: "pass" };
+};
+
+const runLog16 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "LOG-16", new Set(["kiosk", "pos"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const field = deviceGap(ctx.env);
+  if (field) return need(ctx, "LOG-16", field);
+  const pos = textOf(ready.template) === "pos";
+  const path = pos ? "/pos/devices/me" : "/kiosk/devices/me";
+  const step = await heartbeat(ctx, ready, path);
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  if (step.value.status !== 200) return say(ctx.locale, "fail", COPY.shape);
+  const live = openLive(ctx, ready);
+  const device_uid = textOf(ctx.env.FIRESPARK_DOCTOR_DEVICE_UID);
+  const version = { app_version_code: 1, app_version_name: "doctor" };
+  const body = { device_uid, device_secret: "invalid", ...version };
+  const codes = [401, 403];
+  const args = ["device-bad", "POST", path, codes, body] as const;
+  const rejected = await live.probe(...args);
+  if (!rejected.ok) return fromLive(ctx.locale, rejected.result);
+  return { status: "pass" };
+};
+
+const runImg01 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "IMG-01", new Set(["dashboard"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const cookie = textOf(ctx.env.FIRESPARK_DOCTOR_DASHBOARD_COOKIE);
+  if (!cookie) return need(ctx, "IMG-01", "FIRESPARK_DOCTOR_DASHBOARD_COOKIE");
+  const dash = textOf(ready.dashboard_url);
+  if (!dash) return need(ctx, "IMG-01", "dashboard_url");
+  const input = {
+    merchant_id: textOf(ready.merchant_id),
+    env: textOf(ready.env)
+  };
+  const step = await trpcCall(dash, cookie, "multimedia.selectByRange", input);
+  if (step.status < 200 || step.status >= 300) {
+    return say(ctx.locale, "fail", COPY.shape);
+  }
+  const limits = step.text.includes("5242880") || step.text.includes("5MB");
+  if (!limits && !step.text.includes("image")) {
+    return need(ctx, "IMG-01", "multimedia.image");
+  }
+  return { status: "pass" };
+};
+
+const runImg02 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "IMG-02", new Set(["kiosk", "pos"]));
+  if (skipped) return skipped;
+  const files = await readSources(ctx.cwd);
+  const found = files.some(file => {
+    if (file.body.includes("NetInfo")) return true;
+    return file.body.toLowerCase().includes("offline");
+  });
+  if (!found) return say(ctx.locale, "fail", COPY.offline);
+  return { status: "pass" };
+};
+
+const runHw01 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "HW-01", new Set(["kiosk", "dashboard"]));
+  if (skipped) return skipped;
+  const ready = prepare(ctx, LIVE);
+  if (isOutcome(ready)) return ready;
+  const live = openLive(ctx, ready);
+  const codes = [200];
+  const args = ["preferences", "GET", "/preferences", codes] as const;
+  const step = await live.storefront<unknown>(...args);
+  if (!step.ok) return fromLive(ctx.locale, step.result);
+  const pagers = isRecord(step.value) ? step.value.pagers : undefined;
+  if (!isRecord(pagers)) return need(ctx, "HW-01", "preferences.pagers");
+  const fields = [
+    "enabled",
+    "required",
+    "side",
+    "payment_ids",
+    "range_start",
+    "range"
+  ];
+  const missing = fields.find(field => pagers[field] === undefined);
+  if (missing) return need(ctx, "HW-01", `preferences.pagers.${missing}`);
+  return { status: "pass" };
+};
+
+const runHw03 = async (ctx: RunCtx): Promise<Outcome> => {
+  const skipped = applies(ctx, "HW-03", new Set(["pos"]));
+  if (skipped) return skipped;
+  const files = await readSources(ctx.cwd);
+  const found = files.some(file => file.body.toLowerCase().includes("keypad"));
+  if (!found) return say(ctx.locale, "fail", COPY.keypad);
+  return { status: "pass" };
+};
+
+export const CONTENT_BINDINGS: Record<string, CheckBinding> = {
+  "LOG-11": withSafeFix(runLog11),
+  "LOG-12": withSafeFix(runLog12),
+  "LOG-13": withSafeFix(runLog13),
+  "LOG-14": withSafeFix(runLog14),
+  "LOG-15": withSafeFix(runLog15),
+  "LOG-16": withSafeFix(runLog16),
+  "CMS-01": withSafeFix(runCms01),
+  "CMS-02": withSafeFix(runCms02),
+  "IMG-01": withSafeFix(runImg01),
+  "IMG-02": withSafeFix(runImg02),
+  "HW-01": withSafeFix(runHw01),
+  "HW-03": withSafeFix(runHw03)
+};

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

@@ -16,8 +16,8 @@ export const SUMMARY = text(
   "Verifica o FireSpark já implantado de um merchant."
 );
 
-export const USAGE =
-  "firespark doctor <run|list|show|init|docs> [ID ...] [options]";
+const usage = "firespark doctor <run|list|show|init|docs> [ID ...] [options]";
+export const USAGE = usage;
 
 const detailsEs = [
   "Comandos: run [ID ...], list, show <ID>, init [--config <archivo>], docs.",
@@ -218,6 +218,26 @@ export const COPY = {
     "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."
   ),
+  flowMissing: text(
+    "El canal {channel} le falta {field}.",
+    "Channel {channel} is missing {field}.",
+    "O canal {channel} falta {field}."
+  ),
+  flowNoChannel: text(
+    "Falta channel_id para elegir el canal.",
+    "channel_id is missing, so no channel was chosen.",
+    "Falta channel_id para escolher o canal."
+  ),
+  noSafeChange: text(
+    "No hay un arreglo automático que no invente datos. No cambié nada.",
+    "There is no automatic repair that does not invent data. Nothing was changed.",
+    "Não há um reparo automático que não invente dados. Nada foi alterado."
+  ),
+  namedOrder: text(
+    "{id} solo corre cuando lo nombras. No se creó ninguna orden.",
+    "{id} runs only when you name it. No order was created.",
+    "{id} só roda quando você o nomeia. Nenhum pedido foi criado."
+  ),
   strictSkipped: text(
     "Modo estricto: hay checks omitidos.",
     "Strict mode: some checks were skipped.",

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

@@ -0,0 +1,182 @@
+import type { Copy, Locale } from "../../../core/i18n";
+import { translate } from "../../../core/i18n";
+import type { LiveSession } from "../live/live.session";
+import { createLiveSession } from "../live/live.session";
+import type { CheckFail, CheckSkip } from "../live/result";
+import { channelLabel, paymentOf } from "./config";
+import { COPY } from "./copy";
+import { liveConfigOf } from "./order";
+import type { CheckBinding, Outcome, RunCtx } from "./runner";
+import type { YamlChannel } from "./yaml";
+
+export const textOf = (value: string | null | undefined) => {
+  return value?.trim() ?? "";
+};
+
+export const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};
+
+export const isOutcome = (value: unknown): value is Outcome => {
+  if (!isRecord(value)) return false;
+  const status = value.status;
+  if (status !== "pass" && status !== "fail" && status !== "skip") return false;
+  return true;
+};
+
+export const say = (
+  locale: Locale,
+  status: Outcome["status"],
+  copy: Copy,
+  vars?: Record<string, string | number>
+): Outcome => {
+  return { status, detail: translate(locale, copy, vars) };
+};
+
+export const chooseChannel = (ctx: RunCtx): YamlChannel | Outcome => {
+  const { channels, channelId, locale } = ctx;
+  if (channelId) {
+    const found = channels.find(item => item.channel_id === channelId);
+    if (found) return found;
+    const detail = translate(locale, COPY.unknownChannel, { id: channelId });
+    return { status: "fail", detail };
+  }
+  if (channels.length !== 1) {
+    return say(locale, "fail", COPY.flowNoChannel);
+  }
+  const only = channels[0];
+  if (!only) return say(locale, "fail", COPY.flowNoChannel);
+  return only;
+};
+
+export const fieldGap = (
+  channel: YamlChannel,
+  env: NodeJS.ProcessEnv,
+  fields: readonly string[]
+) => {
+  for (const field of fields) {
+    if (field.startsWith("FIRESPARK_")) {
+      if (!textOf(env[field])) return field;
+      continue;
+    }
+    if (field === "payment") {
+      const payment = channel.payment ? paymentOf(channel.payment) : null;
+      if (!payment) return "payment";
+      continue;
+    }
+    const bag = channel as unknown as Record<string, unknown>;
+    const value = bag[field];
+    if (typeof value !== "string" || !value.trim()) return field;
+  }
+  return "";
+};
+
+export const prepare = (ctx: RunCtx, fields: readonly string[]) => {
+  const chosen = chooseChannel(ctx);
+  if (isOutcome(chosen)) return chosen;
+  const field = fieldGap(chosen, ctx.env, fields);
+  if (!field) return chosen;
+  const channel = channelLabel(chosen);
+  const vars = { channel, field };
+  return say(ctx.locale, "fail", COPY.flowMissing, vars);
+};
+
+export const fromLive = (
+  locale: Locale,
+  result: CheckFail | CheckSkip
+): Outcome => {
+  const detail = translate(locale, result.reason.copy, result.reason.vars);
+  if (result.status === "skip") return { status: "skip", detail };
+  return { status: "fail", detail: `${result.hop}: ${detail}` };
+};
+
+export const openLive = (ctx: RunCtx, channel: YamlChannel): LiveSession => {
+  const config = liveConfigOf(channel, ctx.env);
+  return createLiveSession(config, { fetch }, ctx.redactor);
+};
+
+export const rowsOf = (value: unknown) => {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isRecord);
+};
+
+export const queryOf = (path: string, pairs: Record<string, string>) => {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(pairs)) {
+    if (value) params.set(key, value);
+  }
+  const query = params.toString();
+  if (!query) return path;
+  return `${path}?${query}`;
+};
+
+export const isLocalHost = (value: string) => {
+  try {
+    const host = new URL(value).hostname.toLowerCase();
+    if (host === "localhost" || host === "0.0.0.0") return true;
+    if (host === "127.0.0.1" || host === "::1") return true;
+    return host.endsWith(".local");
+  } catch {
+    return true;
+  }
+};
+
+export const withQuery = (url: string, key: string, value: string) => {
+  const parsed = new URL(url);
+  parsed.searchParams.set(key, value);
+  return parsed.toString();
+};
+
+export const readPage = async (url: string) => {
+  const signal = AbortSignal.timeout(15000);
+  const response = await fetch(url, { signal });
+  const body = await response.text();
+  return { status: response.status, body };
+};
+
+export const namedOrderSkip = (ctx: RunCtx, id: string): Outcome | null => {
+  if (ctx.named.has(id)) return null;
+  return say(ctx.locale, "skip", COPY.namedOrder, { id });
+};
+
+export const trpcCall = async (
+  base: string,
+  cookie: string,
+  procedure: string,
+  input: unknown
+) => {
+  const root = base.replace(/\/$/, "");
+  const url = `${root}/api/trpc/${procedure}`;
+  const headers = { "content-type": "application/json", cookie };
+  const signal = AbortSignal.timeout(15000);
+  const body = JSON.stringify({ json: input });
+  const init = { method: "POST", headers, body, signal };
+  try {
+    const response = await fetch(url, init);
+    const text = await response.text();
+    return { status: response.status, text };
+  } catch {
+    return { status: 0, text: "" };
+  }
+};
+
+export const withSafeFix = (
+  run: (ctx: RunCtx) => Promise<Outcome>
+): CheckBinding => {
+  const fix = async (ctx: RunCtx): Promise<Outcome> => {
+    const result = await run(ctx);
+    if (result.status !== "fail") return result;
+    const note = translate(ctx.locale, COPY.noSafeChange);
+    const detail = result.detail ? `${note} ${result.detail}` : note;
+    const failed: Outcome = { status: "fail", detail };
+    return failed;
+  };
+  return { kind: "script", run, fix };
+};
+
+export const ACTIVE = "ACTIVE";
+
+export const isActive = (row: Record<string, unknown>) => {
+  if (!("status" in row)) return true;
+  return row.status === ACTIVE;
+};