@flowapt/flowiq-cli 0.6.8 → 0.7.1

package/src/insights-config.js

@@ -0,0 +1,69 @@
+// Pure helpers for `flowiq insights` — turning flags a human types
+// (`--weekly monday`, `--monthly last`) into the `schedules[]` entries the
+// export-insights scheduler reads, and describing a config the way the
+// scheduler will actually run it. No I/O; unit-tested in insights-config.test.mjs.
+
+export const DOW = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+export const DOW_LABEL = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+
+/** "monday" | "mon" | "1" → 1. Bare `--weekly` (true) → Monday, the scheduler's default. */
+export function parseWeekday(v) {
+  if (v === true || v === undefined || v === null || v === "") return 1;
+  const s = String(v).trim().toLowerCase();
+  if (/^[0-6]$/.test(s)) return Number(s);
+  const idx = DOW.findIndex((d) => d === s || d.slice(0, 3) === s);
+  if (idx >= 0) return idx;
+  throw new Error(`--weekly expects a day (monday … sunday, or 0-6), got "${v}"`);
+}
+
+/** "last" | "15" → "last" | 15. Bare `--monthly` (true) → "last", the scheduler's default. */
+export function parseMonthlyDay(v) {
+  if (v === true || v === undefined || v === null || v === "") return "last";
+  const s = String(v).trim().toLowerCase();
+  if (s === "last") return "last";
+  if (/^\d{1,2}$/.test(s)) {
+    const n = Number(s);
+    if (n >= 1 && n <= 28) return n;
+  }
+  throw new Error(`--monthly expects a day of the month (1-28) or "last", got "${v}"`);
+}
+
+/**
+ * Build schedules[] from the enable flags. Returns null when no cadence flag
+ * was given (the server then keeps what exists, or applies its default).
+ *   opts: { daily?, weekly?, monthly?, report?, storeOnly? }
+ */
+export function schedulesFromOpts(opts = {}) {
+  const report = opts.report ?? "standard";
+  if (!["standard", "advanced"].includes(report)) throw new Error(`--report must be standard or advanced, got "${report}"`);
+  const storeOnly = opts.storeOnly === true;
+  const out = [];
+  if (opts.daily) out.push({ frequency: "daily", report_type: report, store_only: storeOnly });
+  if (opts.weekly !== undefined) out.push({ frequency: "weekly", weekly_day: parseWeekday(opts.weekly), report_type: report, store_only: storeOnly });
+  if (opts.monthly !== undefined) out.push({ frequency: "monthly", monthly_day: parseMonthlyDay(opts.monthly), report_type: report, store_only: storeOnly });
+  return out.length ? out : null;
+}
+
+/** One line per schedule, in the scheduler's own vocabulary. */
+export function describeSchedule(s) {
+  const tag = `${s.report_type ?? "standard"}${s.store_only ? "/store-only" : ""}`;
+  if (s.frequency === "daily") return `daily [${tag}]`;
+  if (s.frequency === "weekly") return `weekly ${DOW_LABEL[typeof s.weekly_day === "number" ? s.weekly_day : 1]} [${tag}]`;
+  if (s.frequency === "monthly") return `monthly day=${s.monthly_day ?? "last"} [${tag}]`;
+  return `${s.frequency} [${tag}]`;
+}
+
+/**
+ * A YYYY-MM-DD typed by a South African becomes the SAST day boundary, not
+ * UTC's — otherwise `--from 2026-09-01` silently starts at 02:00 SAST.
+ * `end` covers the whole day. Full ISO strings pass through untouched.
+ */
+export function sastRange(from, to) {
+  const day = /^\d{4}-\d{2}-\d{2}$/;
+  const start = day.test(from) ? new Date(`${from}T00:00:00+02:00`) : new Date(from);
+  const end = day.test(to) ? new Date(`${to}T23:59:59.999+02:00`) : new Date(to);
+  if (Number.isNaN(start.getTime())) throw new Error(`--from "${from}" is not a date`);
+  if (Number.isNaN(end.getTime())) throw new Error(`--to "${to}" is not a date`);
+  if (start >= end) throw new Error("--from must be before --to");
+  return { start: start.toISOString(), end: end.toISOString() };
+}

package/src/insights-config.test.mjs

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseWeekday, parseMonthlyDay, schedulesFromOpts, describeSchedule, sastRange } from "./insights-config.js";
+
+test("weekday parsing: names, abbreviations, digits, and the bare default", () => {
+  assert.equal(parseWeekday("monday"), 1);
+  assert.equal(parseWeekday("Fri"), 5);
+  assert.equal(parseWeekday("0"), 0);
+  assert.equal(parseWeekday(true), 1);
+  assert.throws(() => parseWeekday("someday"), /--weekly expects/);
+});
+
+test("monthly day: last, 1-28, bare default; 29+ refused (the scheduler never fires them)", () => {
+  assert.equal(parseMonthlyDay("last"), "last");
+  assert.equal(parseMonthlyDay("15"), 15);
+  assert.equal(parseMonthlyDay(true), "last");
+  assert.throws(() => parseMonthlyDay("31"), /1-28/);
+});
+
+test("no cadence flag → null (server keeps existing / applies default)", () => {
+  assert.equal(schedulesFromOpts({}), null);
+  assert.equal(schedulesFromOpts({ report: "advanced" }), null);
+});
+
+test("cadence flags build scheduler-shaped entries, store-only applies to all", () => {
+  const s = schedulesFromOpts({ daily: true, weekly: "monday", monthly: "last", report: "advanced", storeOnly: true });
+  assert.deepEqual(s, [
+    { frequency: "daily", report_type: "advanced", store_only: true },
+    { frequency: "weekly", weekly_day: 1, report_type: "advanced", store_only: true },
+    { frequency: "monthly", monthly_day: "last", report_type: "advanced", store_only: true },
+  ]);
+});
+
+test("bad report type is refused before anything reaches the server", () => {
+  assert.throws(() => schedulesFromOpts({ daily: true, report: "fancy" }), /--report must be/);
+});
+
+test("describeSchedule speaks the scheduler's vocabulary", () => {
+  assert.equal(describeSchedule({ frequency: "daily", report_type: "standard", store_only: true }), "daily [standard/store-only]");
+  assert.equal(describeSchedule({ frequency: "weekly", weekly_day: 3 }), "weekly Wednesday [standard]");
+  assert.equal(describeSchedule({ frequency: "weekly" }), "weekly Monday [standard]");
+  assert.equal(describeSchedule({ frequency: "monthly", report_type: "advanced" }), "monthly day=last [advanced]");
+});
+
+test("date-only --from/--to are SAST day boundaries, not UTC", () => {
+  const r = sastRange("2026-09-01", "2026-09-07");
+  assert.equal(r.start, "2026-08-31T22:00:00.000Z");
+  assert.equal(r.end, "2026-09-07T21:59:59.999Z");
+  assert.throws(() => sastRange("2026-09-07", "2026-09-01"), /before/);
+  assert.throws(() => sastRange("yesterday", "2026-09-01"), /not a date/);
+});

package/src/update-check.js

@@ -4,6 +4,14 @@
 // can never corrupt piped / --json output) when the installed version is older
 // than the latest published on npm.
 //
+// ⚠️ It used to be gated on `process.stderr.isTTY` as well, which meant it was
+// invisible to exactly the audience that most needs it: an AI assistant running
+// `flowiq` through a tool call gets a PIPE, not a TTY, so isTTY is undefined and
+// the hint never printed. Teammates' Claude sessions could therefore run a
+// months-old CLI forever without ever being told. Writing to stderr is already
+// the whole safety property (it cannot corrupt piped stdout or --json), so the
+// TTY gate bought nothing and cost everything. Removed 9 Sep 2026.
+//
 // The nudge is driven by a CACHED value read SYNCHRONOUSLY — zero network on the
 // hot path, so no command is ever slowed. The cache is refreshed at most once a
 // day by a DETACHED, unref'd child process, so even `flowiq --version` returns
@@ -88,16 +96,42 @@ async function refreshLatest(prevLatest) {
 
 // Print the nudge (from cache, synchronously) and, if the cache is stale, spawn
 // a detached child to refresh it for the NEXT run. Never throws, never blocks.
+/** The cached npm `latest` + when it was refreshed — used by `flowiq doctor`. */
+export function cachedLatest() {
+  const c = readCacheSync();
+  return { latest: c?.latest || null, checkedAt: c?.checked_at || null };
+}
+
+/** Ask npm for the latest version NOW (doctor only — never on the hot path). */
+export async function fetchLatestNow(timeoutMs = FETCH_TIMEOUT_MS) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(REGISTRY, { signal: ctrl.signal, headers: { Accept: "application/json" } });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (body?.version) await writeCache({ checked_at: Date.now(), latest: body.version });
+    return body?.version || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function maybeNotifyUpdate(currentVersion) {
   try {
     if (disabled()) return;
     const cache = readCacheSync();
     const latest = cache?.latest;
 
-    if (latest && process.stderr.isTTY && cmpVersion(latest, currentVersion) > 0) {
+    if (latest && cmpVersion(latest, currentVersion) > 0) {
+      // The marker line is deliberately stable and unambiguous: an assistant
+      // reading this in a tool result should update without needing to be asked.
       process.stderr.write(
-        `\n  ⬆ flowiq ${latest} is available (you're on ${currentVersion})\n` +
-        `    update:  npm i -g ${PKG}\n\n`
+        `\n  ⬆ FLOWIQ CLI OUT OF DATE — installed ${currentVersion}, latest ${latest}\n` +
+        `    Run this before continuing:  npm i -g ${PKG}@latest\n` +
+        `    (commands still work; newer ones may be missing or behave differently)\n\n`
       );
     }