@hone-ai/cli 1.18.0 → 1.20.0

package/lib/schedule-cron.js

@@ -0,0 +1,141 @@
+'use strict';
+/**
+ * schedule-cron.js — HC-054f cron-hour analysis for `hone schedule install`.
+ *
+ * Adopters who install a workflow with a cron like "0 2 * * *" (2 AM
+ * UTC) almost always want Night Shift mode (--overnight) because a
+ * 2 AM run is by definition an overnight batch. Pre-HC-054f the CLI
+ * never passed --overnight to queue-stories so the scheduled workflow
+ * silently ran without auto-approve / longer timeouts / 25-story cap.
+ *
+ * **Timezone — load-bearing**: GitHub Actions cron runs in **UTC** by
+ * default. This helper analyzes the cron's hour field AS UTC. It does
+ * NOT translate to the adopter's local timezone. Adopters in non-UTC
+ * timezones who want overnight semantics in THEIR LOCAL TIME must
+ * write the cron's UTC equivalent (e.g., Tokyo adopter wanting
+ * 2 AM JST should write `"0 17 * * *"` because 2 AM JST = 17 UTC the
+ * previous day). Pass-1 review HIGH #2 caught the original docstring
+ * + roadmap incorrectly described the window as "local time" — this
+ * was misleading.
+ *
+ * HC-054f: when the cron expression's hour (UTC) is a LITERAL single
+ * value within the 18:00–05:59 UTC window, default --overnight=true.
+ * Ambiguous hour fields (wildcard, range, step) and out-of-window
+ * hours (06:00–17:59 UTC) DO NOT auto-default — adopter must
+ * explicitly opt in via --overnight yes.
+ *
+ * Window choice: [18, 23] ∪ [0, 5] UTC. 06:00 UTC itself is NOT
+ * overnight — a `"0 6 * * *"` cron is a morning queue, not an
+ * overnight one. The 5:59:59 UTC boundary matches "wake before 6 AM
+ * UTC" intuition. Adopters in distant timezones (JST, AEST, PST etc.)
+ * may need to translate; the CLI surfaces the UTC interpretation in
+ * its decision-reporting output so the adopter sees what the helper
+ * actually decided.
+ *
+ * Pure helper. No I/O. Unit-tested at cli/lib/schedule-cron.test.js.
+ */
+
+const OVERNIGHT_HOURS = Object.freeze(
+  Array.from({ length: 24 }, (_, h) => h).filter(h => h >= 18 || h < 6),
+);
+
+/**
+ * Analyze a cron expression to determine whether the schedule falls
+ * in the overnight window.
+ *
+ * @param {string} cronExpr — 5-field cron expression
+ * @returns {{ overnight: boolean, hour: number|null, reason: string }}
+ *   overnight: true ONLY when the hour field is a literal single value
+ *              within OVERNIGHT_HOURS.
+ *   hour:      the parsed hour (0-23) when literal; null for ambiguous.
+ *   reason:    short human-readable explanation for the CLI output.
+ */
+function analyzeCron(cronExpr) {
+  if (typeof cronExpr !== 'string') {
+    return { overnight: false, hour: null, reason: 'cron must be a string' };
+  }
+  const fields = cronExpr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    return { overnight: false, hour: null, reason: 'cron must have exactly 5 fields' };
+  }
+  const hourField = fields[1];
+
+  // Wildcard, range, step, list — all ambiguous (adopter could be
+  // running it during the day too). Don't auto-default; require
+  // explicit --overnight yes.
+  if (!/^\d+$/.test(hourField)) {
+    return { overnight: false, hour: null,
+             reason: `hour field "${hourField}" is not a literal — pass --overnight yes to enable Night Shift` };
+  }
+
+  const hour = parseInt(hourField, 10);
+  if (hour < 0 || hour > 23) {
+    return { overnight: false, hour: null,
+             reason: `hour field "${hourField}" out of range 0-23` };
+  }
+
+  if (OVERNIGHT_HOURS.includes(hour)) {
+    return { overnight: true, hour,
+             reason: `hour ${hour} UTC falls in the overnight window (18:00-05:59 UTC)` };
+  }
+  return { overnight: false, hour,
+           reason: `hour ${hour} UTC is daytime (06:00-17:59 UTC); pass --overnight yes to enable Night Shift anyway` };
+}
+
+// Accepted aliases for explicit modes. Lowercased before comparison so
+// `--overnight YES` and `--overnight Yes` both work — pass-1 review
+// HIGH caught that the original case-sensitive implementation silently
+// fell through to auto on uppercase aliases, contradicting adopter
+// intent without any signal.
+const YES_ALIASES = Object.freeze(new Set(['yes', 'true', '1', 'on', 'enable', 'enabled']));
+const NO_ALIASES  = Object.freeze(new Set(['no', 'false', '0', 'off', 'disable', 'disabled']));
+const AUTO_ALIASES = Object.freeze(new Set(['auto', 'default', '']));
+
+/**
+ * Check whether a `--overnight <mode>` value is a recognized mode (any
+ * known alias, case-insensitive). Caller uses this to validate the
+ * adopter's input UPFRONT and exit non-zero with a helpful message
+ * rather than silently falling back to auto on a typo.
+ *
+ * @param {string} mode
+ * @returns {boolean}
+ */
+function isKnownOvernightMode(mode) {
+  if (typeof mode !== 'string') return false;
+  const m = mode.trim().toLowerCase();
+  return YES_ALIASES.has(m) || NO_ALIASES.has(m) || AUTO_ALIASES.has(m);
+}
+
+/**
+ * Resolve the final overnight setting given the adopter's explicit
+ * mode (`auto`|`yes`|`no`, case-insensitive, with aliases) and the
+ * cron analysis.
+ *
+ * UNKNOWN modes are treated as `auto` per the historical fallback,
+ * BUT the CLI should reject unknown modes upfront via
+ * `isKnownOvernightMode` — this fallback exists so library callers
+ * that didn't validate get safe behavior.
+ *
+ * @param {string} mode — value of --overnight (auto|yes|no + aliases)
+ * @param {ReturnType<typeof analyzeCron>} analysis
+ * @returns {{ overnight: boolean, source: 'explicit-yes'|'explicit-no'|'auto-detect-yes'|'auto-detect-no' }}
+ */
+function resolveOvernight(mode, analysis) {
+  const m = typeof mode === 'string' ? mode.trim().toLowerCase() : '';
+  if (YES_ALIASES.has(m)) return { overnight: true,  source: 'explicit-yes' };
+  if (NO_ALIASES.has(m))  return { overnight: false, source: 'explicit-no' };
+  return {
+    overnight: analysis.overnight,
+    source: analysis.overnight ? 'auto-detect-yes' : 'auto-detect-no',
+  };
+}
+
+module.exports = {
+  OVERNIGHT_HOURS,
+  YES_ALIASES,
+  NO_ALIASES,
+  AUTO_ALIASES,
+  analyzeCron,
+  resolveOvernight,
+  isKnownOvernightMode,
+};