fluncle 0.213.0 → 0.214.0

package/bin/fluncle.mjs

@@ -610,7 +610,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.213.0".trim() ? "0.213.0".trim() : "0.1.0";
+  currentVersion = "0.214.0".trim() ? "0.214.0".trim() : "0.1.0";
 });
 
 // src/update-notifier.ts
@@ -2452,7 +2452,7 @@ function parseVersion2(version) {
 var currentVersion2, latestReleaseUrl = "https://api.github.com/repos/mauricekleine/fluncle/releases/latest";
 var init_version2 = __esm(() => {
   init_output();
-  currentVersion2 = "0.213.0".trim() ? "0.213.0".trim() : "0.1.0";
+  currentVersion2 = "0.214.0".trim() ? "0.214.0".trim() : "0.1.0";
 });
 
 // ../../packages/registry/src/index.ts
@@ -4478,9 +4478,21 @@ __export(exports_admin_telemetry, {
 });
 async function telemetryCommand(options) {
   const params = new URLSearchParams({ limit: String(options.limit) });
+  if (options.blind === true) {
+    params.set("blind", "true");
+  }
   if (options.cursor !== undefined) {
     params.set("cursor", options.cursor);
   }
+  if (options.liar === true) {
+    params.set("liar", "true");
+  }
+  if (options.missing === true) {
+    params.set("missing", "true");
+  }
+  if (options.missingField !== undefined) {
+    params.set("missingField", options.missingField);
+  }
   if (options.ok !== undefined) {
     params.set("ok", String(options.ok));
   }
@@ -4507,16 +4519,50 @@ function cell(value) {
 function padded(columns, widths) {
   return columns.map((column, index) => column.padEnd(widths[index] ?? 0)).join("  ").trimEnd();
 }
-function telemetryLines(page) {
+function cadence(expectedIntervalMs) {
+  if (expectedIntervalMs === null) {
+    return "-";
+  }
+  const units = [
+    { label: "d", milliseconds: 24 * 60 * 60 * 1000 },
+    { label: "h", milliseconds: 60 * 60 * 1000 },
+    { label: "m", milliseconds: 60 * 1000 },
+    { label: "s", milliseconds: 1000 }
+  ];
+  for (const unit of units) {
+    if (expectedIntervalMs % unit.milliseconds === 0) {
+      return `${expectedIntervalMs / unit.milliseconds}${unit.label}`;
+    }
+  }
+  return `${expectedIntervalMs}ms`;
+}
+function telemetryLines(page, options = {}) {
   if (!page.available) {
     return ["Telemetry database is not configured."];
   }
-  if (page.rows.length === 0) {
+  if (options.missing === true || page.missingRoster.length > 0) {
+    if (page.missingRoster.length === 0) {
+      return ["No expected writers are missing."];
+    }
+    const missingHeader = ["MISSING UNIT", "CADENCE"];
+    const missingRows = page.missingRoster.map((entry) => [
+      entry.unit,
+      cadence(entry.expectedIntervalMs)
+    ]);
+    const missingWidths = missingHeader.map((header, index) => Math.max(header.length, ...missingRows.map((row) => row[index]?.length ?? 0)));
+    return [
+      `Expected writers with no run (${missingRows.length})`,
+      padded(missingHeader, missingWidths),
+      ...missingRows.map((row) => padded(row, missingWidths))
+    ];
+  }
+  if (page.rows.length === 0 && page.rollups.length === 0) {
     return ["No run events matched."];
   }
-  const rollupHeader = ["UNIT", "RUNS", "LAST", "OK=0", "LIAR", "BLIND"];
+  const rollupHeader = ["UNIT", "CADENCE", "RUNS", "LAST", "OK=0", "LIAR", "BLIND"];
   const rollupRows = page.rollups.map((rollup) => [
     rollup.unit,
+    cadence(rollup.expectedIntervalMs),
     String(rollup.runCount),
     rollup.lastOccurredAt,
     String(rollup.failedCount),
@@ -4547,15 +4593,18 @@ function telemetryLines(page) {
     row.summaryStatus
   ]);
   const runWidths = runHeader.map((header, index) => Math.max(header.length, ...runRows.map((row) => row[index]?.length ?? 0)));
-  const lines = [
-    `Unit rollups (${page.totalCount} matching runs)`,
-    padded(rollupHeader, rollupWidths),
-    ...rollupRows.map((row) => padded(row, rollupWidths)),
-    "",
-    `Runs (${page.rows.length} on this page)`,
-    padded(runHeader, runWidths),
-    ...runRows.map((row) => padded(row, runWidths))
-  ];
+  const lines = [];
+  if (rollupRows.length > 0) {
+    lines.push("Unit rollups (all runs in the selected time/unit window)", padded(rollupHeader, rollupWidths), ...rollupRows.map((row) => padded(row, rollupWidths)));
+  }
+  if (lines.length > 0) {
+    lines.push("");
+  }
+  if (runRows.length === 0) {
+    lines.push("No evidence rows matched.");
+  } else {
+    lines.push(`Evidence rows (${page.rows.length} of ${page.totalCount} matching; this page)`, padded(runHeader, runWidths), ...runRows.map((row) => padded(row, runWidths)));
+  }
   if (page.nextCursor !== null) {
     lines.push("", `Next cursor: ${page.nextCursor}`);
   }
@@ -9768,7 +9817,19 @@ function addAdminCommands(program2) {
   adminTelemetry.action(() => {
     adminTelemetry.outputHelp();
   });
-  adminTelemetry.command("read").description("Run-ledger rows plus per-unit rollups").option("--unit <unit>", "Only this systemd unit").option("--since <iso>", "Only runs at or after this occurred-at instant").option("--until <iso>", "Only runs at or before this occurred-at instant").option("--ok <true|false>", "Filter by the Worker's derived run verdict").option("--limit <limit>", "Rows to show (1-100)", "50").option("--cursor <cursor>", "Opaque cursor from the previous page").option("--json", "Print the lossless 20-column rows as JSON", false).action(async (options) => {
+  adminTelemetry.command("read").description("Run-ledger rows plus per-unit rollups").option("--unit <unit>", "Only this systemd unit").option("--since <iso|age>", "Only runs at or after this instant (ISO, 24h, or 90m)").option("--until <iso>", "Only runs at or before this occurred-at instant").option("--ok <true|false>", "Filter by the Worker's derived run verdict").option("--liar", "Only rows whose claimed ok contradicts the derived verdict").option("--blind", "Only rows missing every work counter").option("--missing-field <name>", "Only rows missing this canonical counter").option("--missing", "List expected writers with no run in the selected window").option("--limit <limit>", "Rows to show (1-100)", "50").option("--cursor <cursor>", "Opaque cursor from the previous page").option("--json", "Print lossless rows, rollups, and missing writers as JSON", false).addHelpText("after", `
+Evidence and rollups:
+  --ok, --liar, --blind, and --missing-field filter evidence rows only.
+  RUNS always counts every run in the selected --unit/--since/--until window.
+  --missing is a separate roster view; combine it only with --unit/--since/--until.
+  --missing-field names: checked, produced, queue_depth, errors, expected_interval_ms.
+
+JSON field reference:
+  top-level ok        Request acknowledgement only; never a run verdict.
+  rows[].ok           Worker's derived verdict for that run.
+  rollups[]           Whole-window unit totals, including expectedIntervalMs.
+  missingRoster[]     Expected writers with no run in the selected window.
+`).action(async (options) => {
     const { telemetryCommand: telemetryCommand2 } = await Promise.resolve().then(() => (init_admin_telemetry(), exports_admin_telemetry));
     await runAdminTelemetry(options, telemetryCommand2);
   });
@@ -12677,13 +12738,62 @@ function parseTelemetryOk(value) {
   }
   return value === "true";
 }
-function parseTelemetryTimestamp(value, flag) {
+var telemetryMissingFields = [
+  "checked",
+  "errors",
+  "expected_interval_ms",
+  "produced",
+  "queue_depth"
+];
+function parseTelemetryMissingField(value) {
   if (value === undefined) {
     return;
   }
+  const field = telemetryMissingFields.find((candidate) => candidate === value);
+  if (field === undefined) {
+    throw new Error(`--missing-field must be one of: ${telemetryMissingFields.join(", ")}`);
+  }
+  return field;
+}
+function parseExplicitTelemetryInstant(value) {
+  if (value.length > 64) {
+    return null;
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.exec(value);
+  if (match === null) {
+    return null;
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  const maximumDay = daysInMonth[month - 1];
+  if (maximumDay === undefined || day < 1 || day > maximumDay) {
+    return null;
+  }
   const timestamp = new Date(value);
-  if (Number.isNaN(timestamp.getTime())) {
-    throw new Error(`${flag} must be an ISO-8601 timestamp`);
+  return Number.isNaN(timestamp.getTime()) ? null : timestamp;
+}
+function parseTelemetryTimestamp(value, flag) {
+  if (value === undefined) {
+    return;
+  }
+  const relative = flag === "--since" ? value.match(/^([1-9]\d*)([mhdw])$/) : null;
+  if (relative !== null) {
+    const amount = Number(relative[1]);
+    const unitMs = relative[2] === "w" ? 604800000 : relative[2] === "d" ? 86400000 : relative[2] === "h" ? 3600000 : 60000;
+    const durationMs = amount * unitMs;
+    const maximumDurationMs = 315360000000;
+    if (value.length > 32 || !Number.isSafeInteger(amount) || !Number.isSafeInteger(durationMs) || durationMs > maximumDurationMs) {
+      throw new Error("--since relative age must not exceed 3650d");
+    }
+    return value;
+  }
+  const timestamp = parseExplicitTelemetryInstant(value);
+  if (timestamp === null) {
+    const expected = flag === "--since" ? "an explicit ISO-8601 instant (with Z or offset) or a relative age like 24h or 90m" : "an explicit ISO-8601 instant with Z or offset";
+    throw new Error(`${flag} must be ${expected}`);
   }
   return timestamp.toISOString();
 }
@@ -12755,14 +12865,23 @@ async function runAdminAttention(options, attentionQueueCommand2) {
 `));
 }
 async function runAdminTelemetry(options, telemetryCommand2) {
+  if (options.missing === true && (options.blind === true || options.cursor !== undefined || options.liar === true || options.missingField !== undefined || options.ok !== undefined)) {
+    throw new Error("--missing cannot be combined with --ok, --liar, --blind, --missing-field, or --cursor");
+  }
   const since = parseTelemetryTimestamp(options.since, "--since");
   const until = parseTelemetryTimestamp(options.until, "--until");
-  if (since !== undefined && until !== undefined && since > until) {
+  const sinceMs = since === undefined ? Number.NaN : Date.parse(since);
+  const untilMs = until === undefined ? Number.NaN : Date.parse(until);
+  if (Number.isFinite(sinceMs) && Number.isFinite(untilMs) && sinceMs > untilMs) {
     throw new Error("--since must be before or equal to --until");
   }
   const page = await telemetryCommand2({
+    blind: options.blind,
     cursor: options.cursor,
+    liar: options.liar,
     limit: parseTelemetryLimit(options.limit),
+    missing: options.missing,
+    missingField: parseTelemetryMissingField(options.missingField),
     ok: parseTelemetryOk(options.ok),
     since,
     unit: options.unit,
@@ -12773,7 +12892,7 @@ async function runAdminTelemetry(options, telemetryCommand2) {
     return;
   }
   const { telemetryLines: telemetryLines2 } = await Promise.resolve().then(() => (init_admin_telemetry(), exports_admin_telemetry));
-  console.log(telemetryLines2(page).join(`
+  console.log(telemetryLines2(page, { missing: options.missing === true }).join(`
 `));
 }
 async function runAdminQueue(options, queueCommand2) {
@@ -13240,6 +13359,7 @@ var stringOptions = new Set([
   "--max-hop",
   "--max-overlap",
   "--metrics",
+  "--missing-field",
   "--mime",
   "--min-phrase-words",
   "--model",
@@ -13323,5 +13443,6 @@ if (__require.main == __require.module) {
   await main();
 }
 export {
+  parseTelemetryTimestamp,
   createProgram
 };

package/package.json

@@ -31,5 +31,5 @@
     "url": "git+https://github.com/mauricekleine/fluncle.git"
   },
   "type": "module",
-  "version": "0.213.0"
+  "version": "0.214.0"
 }