impel-cli 0.20.45 → 0.20.46-beta.2

package/src/autoReport.js

@@ -0,0 +1,289 @@
+// The automatic bug-report path: a failed `impel setup` or `impel update`
+// reporting itself.
+//
+// The manual command in `src/commands/report.js` has a person attached — they
+// typed it, they are watching, and an error they can read is a useful outcome.
+// This module has none of that. It runs inside a command that has already
+// failed, on a machine whose owner may have walked away, and the only two
+// things it owes anyone are the disclosure line and a promise never to make the
+// failure worse. Everything below follows from that asymmetry:
+//
+//   - Every gate returns silently. There is no "reporting was skipped because…"
+//     sentence, because nobody asked for a report and a refusal is not news.
+//   - The whole body is wrapped in a `try`/`catch` that swallows (KTD10). A
+//     throw from here would surface as a crash inside a command that had
+//     already decided how it wanted to fail.
+//   - `process.exitCode` is never written. The failing command owns its exit
+//     code; the report is a side effect, not an outcome.
+//
+// What is *sent* is identical to the manual path — same `buildEnvelope`, same
+// origin check, same spool — because "the automatic sender cannot send
+// something the manual sender would not" has to be a property of the code
+// rather than a habit. This file only decides *whether* to send.
+//
+// The suppression marker lives under `CONFIG_DIR`, so `impel nuke` erases it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  buildEnvelope,
+  deliverWithRetry,
+  MAX_DIAGNOSTIC_KEYS,
+  REPORT_SPOOL_DIR,
+  resolveReportOrigin,
+  sleep,
+  spoolReport,
+  writeJsonAtomically,
+} from "./bugReport.js";
+import { resolveDefaultAppUrl } from "./config.js";
+import { fetchHttp1 } from "./http1.js";
+import { sanitizeInstallFailureEnvelope } from "./installRecovery/redact.js";
+import {
+  DO_NOT_TRACK_ENV,
+  firstPartyCli,
+  managedMarkerPresent,
+  reportEnvOptOut,
+} from "./telemetryConsent.js";
+
+/**
+ * Shorter than `impel report`'s 10 s: this timeout is spent by a command that
+ * has already failed and wants to exit. Three attempts at 5 s plus 500/1,500 ms
+ * of backoff is ~17 s worst case against a black hole (KTD5).
+ */
+export const AUTO_REPORT_TIMEOUT_MS = 5_000;
+
+/** R4's record of what this machine has already reported. */
+export const AUTO_REPORT_MARKER_NAME = ".last-auto-report.json";
+
+/**
+ * The marker sits beside the spooled reports rather than in its own directory,
+ * so one `impel nuke` erases both and a test that redirects `spoolDir`
+ * redirects the marker with it.
+ */
+export function autoReportMarkerPath(spoolDir = REPORT_SPOOL_DIR) {
+  return path.join(spoolDir, AUTO_REPORT_MARKER_NAME);
+}
+
+/** R4's window. A failure that recurs the next day is worth hearing about again. */
+export const AUTO_REPORT_SUPPRESSION_MS = 24 * 60 * 60 * 1_000;
+
+/**
+ * A list, not a single slot (KTD4). One machine reaches more than one failure
+ * mode, and two alternating failures sharing a slot would evict each other's
+ * record so neither is ever suppressed — the exact case automatic dispatch
+ * makes common.
+ */
+export const AUTO_REPORT_MARKER_ENTRIES = 32;
+
+/**
+ * `buildEnvelope` adds `tenant` and `reportId` of its own, and this mapping adds
+ * four more, so the failure's own diagnostics are trimmed to leave room.
+ * Exceeding `MAX_DIAGNOSTIC_KEYS` throws, and a report lost to a crowded
+ * diagnostics bag is a worse outcome than a report missing its 19th diagnostic.
+ */
+const RESERVED_DIAGNOSTIC_KEYS = 6;
+
+/* -------------------------------------------------------------------------- */
+/* Envelope                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Fold the sanitized install-failure envelope into the bug-report field bag.
+ *
+ * The two shapes are close enough to look interchangeable and are not.
+ * `bugReportEnvelopeSchema` is `.strict()`, so `scope`, `tenantId`, `step`, and
+ * `signal` have no top-level home and must travel inside `diagnostics`. Each
+ * mismatch left uncorrected is a 400, not a dropped field.
+ *
+ * The wire's own bounds are not re-applied here: `buildEnvelope` already
+ * truncates each field to its schema length and drops a falsy one rather than
+ * sending it, which is the same answer the sanitizer's `null`s want. A second
+ * copy of `64` in this file would be a bound that can drift from the one the
+ * server actually enforces.
+ *
+ * `step` doubles as `command` when the failure has none, so the server's task
+ * title has something to name.
+ */
+function reportFields(sanitized) {
+  const own = Object.entries(sanitized.diagnostics || {})
+    .slice(0, MAX_DIAGNOSTIC_KEYS - RESERVED_DIAGNOSTIC_KEYS);
+  return {
+    message: sanitized.message,
+    command: sanitized.command || sanitized.step,
+    errorCode: sanitized.errorCode,
+    exitCode: sanitized.exitCode,
+    log: sanitized.stderr || sanitized.stdout || "",
+    diagnostics: {
+      ...Object.fromEntries(own),
+      scope: sanitized.scope,
+      step: sanitized.step,
+      ...(sanitized.tenantId ? { tenantId: sanitized.tenantId } : {}),
+      ...(sanitized.signal ? { signal: sanitized.signal } : {}),
+    },
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Suppression marker                                                         */
+/* -------------------------------------------------------------------------- */
+
+/** An unreadable or malformed marker reads as absent: it must not block a report. */
+function readMarker(markerPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+    if (!Array.isArray(parsed?.entries)) return [];
+    return parsed.entries.filter((entry) => (
+      entry && typeof entry.reportId === "string" && typeof entry.sentAt === "string"
+    ));
+  } catch {
+    return [];
+  }
+}
+
+function alreadyReported(entries, reportId, now) {
+  return entries.some((entry) => {
+    if (entry.reportId !== reportId) return false;
+    const sentAt = Date.parse(entry.sentAt);
+    return Number.isFinite(sentAt) && now - sentAt < AUTO_REPORT_SUPPRESSION_MS;
+  });
+}
+
+/**
+ * Record this send.
+ *
+ * Losing the marker costs one duplicate report; refusing to report because the
+ * marker could not be written costs the report. So every failure here is
+ * swallowed by the caller.
+ */
+function writeMarker(markerPath, entries, reportId, now) {
+  const kept = entries
+    .filter((entry) => entry.reportId !== reportId)
+    .filter((entry) => {
+      const sentAt = Date.parse(entry.sentAt);
+      return Number.isFinite(sentAt) && now - sentAt < AUTO_REPORT_SUPPRESSION_MS;
+    });
+  // Newest first, so the cap drops the oldest.
+  const next = [{ reportId, sentAt: new Date(now).toISOString() }, ...kept]
+    .slice(0, AUTO_REPORT_MARKER_ENTRIES);
+  writeJsonAtomically(markerPath, { entries: next });
+}
+
+/* -------------------------------------------------------------------------- */
+/* Dispatch                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * File a bug report for a failed install, or do nothing.
+ *
+ * `failure` is the same object the command already hands `io.recoverInstall`,
+ * so a call site adds no new data collection — it hands over what it had
+ * assembled anyway.
+ *
+ * `io` is the *calling command's* bag, which carries none of the delivery
+ * seams: `impel setup` and `impel update` have no `fetchImpl`, no `spoolDir`,
+ * no `sleep`. Those defaults are supplied here and caller keys win, so a test
+ * can inject a fake fetch and a command does not have to grow twelve fields it
+ * has no other use for.
+ */
+export async function reportInstallFailure({ failure, config, io = {} }) {
+  try {
+    const environment = io.environment || process.env;
+    const homeDir = io.homeDir || os.homedir();
+
+    // KTD2's order. `firstPartyCli` leads: a rebranded fork must not inherit
+    // Impel's phone-home, and that answer does not depend on this machine's
+    // config, environment, or PAT — so it is also the only gate that can be
+    // decided without reading any of them.
+    if (!firstPartyCli()) return;
+    if (reportEnvOptOut(environment)) return;
+    // Before the marker check only because it is a property read and that one
+    // walks `realpath` up the ancestor chain. Nothing to authenticate with is
+    // just as final an answer, and this is a command that has already failed
+    // and wants to exit.
+    if (!config?.pat) return;
+    // Not a consent question (R7): a managed vendor app profile may reach the
+    // gateway and nothing else, so a report from inside one presents as an
+    // unexpected egress call from a profile holding app credentials.
+    if (managedMarkerPresent(environment, homeDir)) return;
+
+    const delivery = {
+      environment,
+      homeDir,
+      fetchImpl: fetchHttp1,
+      spoolDir: REPORT_SPOOL_DIR,
+      timeoutMs: AUTO_REPORT_TIMEOUT_MS,
+      now: Date.now(),
+      platform: process.platform,
+      sleep,
+      log: console.log,
+      warn: console.warn,
+      ...io,
+    };
+
+    // The same destination the manual command resolves, through the same
+    // check, for the same reason and one more: this sender has no user to
+    // notice that `appUrl` was hand-edited. A rejection is a gate like any
+    // other and returns silently — there is no `--app` flag to correct.
+    let appUrl;
+    try {
+      appUrl = resolveReportOrigin(config.appUrl || resolveDefaultAppUrl());
+    } catch {
+      return;
+    }
+
+    // Sanitize first, then build — not instead of building. The sanitizer
+    // removes credentials, home paths, and emails from the recovery envelope;
+    // `buildEnvelope` is what makes it a wire-legal bug report.
+    const sanitized = sanitizeInstallFailureEnvelope(failure, { homeDir });
+    const { envelope, reportId } = buildEnvelope({
+      fields: reportFields(sanitized),
+      config,
+      io: delivery,
+    });
+
+    // R4. Read before printing: a suppressed report prints nothing at all,
+    // because the disclosure line exists to explain a send that is happening.
+    const markerPath = autoReportMarkerPath(delivery.spoolDir);
+    const entries = readMarker(markerPath);
+    if (alreadyReported(entries, reportId, delivery.now)) return;
+
+    // R9/KTD6: before the request, and worded as an attempt. The id is a
+    // fingerprint of the envelope so it is already known, and up to ~17 s of
+    // retries against an unreachable control plane should not be a silent
+    // pause. A past-tense claim would be false in exactly the case that
+    // matters — a spooled report announcing a send that never happened.
+    delivery.log(`Reporting this failure automatically (id ${reportId}). Set ${DO_NOT_TRACK_ENV}=1 to disable.`);
+
+    const { outcome } = await deliverWithRetry({
+      envelope,
+      appUrl,
+      currentPat: config.pat,
+      io: delivery,
+    });
+
+    if (!outcome) {
+      // The outcome line that corrects the attempt line. Nothing drains this
+      // directory — the spool is a local paper trail, not a queue — so the next
+      // occurrence of this failure dispatches again rather than being
+      // suppressed, which is also why the marker below is not written here.
+      const filePath = spoolReport({ envelope, reportId, appUrl, io: delivery });
+      delivery.log(`The report could not be sent. It is saved at ${filePath}`);
+      return;
+    }
+
+    // A successful send prints nothing further, and is the only thing that
+    // suppresses a repeat. Marker failures are swallowed on purpose.
+    try {
+      writeMarker(markerPath, entries, reportId, delivery.now);
+    } catch {
+      // Costs one duplicate report. Refusing to report would cost the report.
+    }
+  } catch {
+    // KTD10. The command that called this is already failing; the reporting
+    // path must not add a second failure mode, and there is nobody here to
+    // tell. Deliberately empty: a warning printed from this catch would be the
+    // second error message R10 promises the user will not see.
+  }
+}