@velaro/cli 1.4.101 → 1.4.102

package/lib/commands/enterprise-reports.js

@@ -1,5 +1,6 @@
 import { messagingGet, messagingPost } from '../api.js';
 import { runCommand } from '../run.js';
+import { yearInReviewBody } from '../year-in-review-range.js';
 
 // -- velaro enterprise-reports ----------------------------------------------------
 // Backend: velaro-messaging /api/enterprise-reports/* (Enterprise Reports package: enterprise-internal, default OFF;
@@ -20,6 +21,7 @@ const REPORTS = {
   'promise-ledger': 'Agent commitments made in chat and whether a follow-up appeared; overdue list',
   'promise-dismiss': 'Dismiss one promise by --id (managers only)',
   'weekly-brief-send-test': 'Email this week\'s brief to the signed-in user',
+  'year-in-review': 'Build the 12-month Year in review document: --from/--to (default last 12 whole Pacific months) starts a build and prints its id; --id <id> checks status and the download link',
 };
 
 export const enterpriseReportsCommand = {
@@ -43,12 +45,21 @@ export const enterpriseReportsCommand = {
     .option('time-zone', { type: 'string', describe: 'demand-coverage: IANA time zone (default America/Los_Angeles)' })
     .option('low-score', { type: 'number', describe: 'bot-containment: QA score below which a handed-off chat counts as regret (1-100, default 60)' })
     .option('include-demo', { type: 'boolean', describe: 'Show only the seeded sample (demo) data' })
-    .option('id', { type: 'string', describe: 'promise-dismiss: the promise id' }),
+    .option('id', { type: 'string', describe: 'promise-dismiss: the promise id; year-in-review: the build id to check' }),
   handler:  runCommand(async (argv) => {
     if (argv.report === 'weekly-brief-send-test') {
       console.log(JSON.stringify(await messagingPost('/api/enterprise-reports/weekly-brief/send-test', {}), null, 2));
       return;
     }
+    if (argv.report === 'year-in-review') {
+      // POST starts a build (202 {id}); with --id, GET its status {status: queued|building|completed|failed, downloadUrl, error}. 403 when the key is off.
+      if (argv.id) {
+        console.log(JSON.stringify(await messagingGet(`/api/enterprise-reports/year-in-review/${encodeURIComponent(String(argv.id))}`), null, 2));
+        return;
+      }
+      console.log(JSON.stringify(await messagingPost('/api/enterprise-reports/year-in-review', yearInReviewBody(argv.from, argv.to)), null, 2));
+      return;
+    }
     if (argv.report === 'promise-dismiss') {
       if (!argv.id) throw new Error('--id is required for promise-dismiss');
       console.log(JSON.stringify(await messagingPost(`/api/enterprise-reports/promise-ledger/${encodeURIComponent(String(argv.id))}/dismiss`, {}), null, 2));

package/lib/enterprise-reports.test.js

@@ -2,9 +2,28 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { enterpriseReportsCommand } from './commands/enterprise-reports.js';
+import { yearInReviewBody, lastTwelveWholeMonthsKeys } from './year-in-review-range.js';
 
 test('describe lists the five novel reports and the promise dismiss action', () => {
   for (const r of ['repeat-contact', 'demand-coverage', 'bot-containment', 'effort-index', 'promise-ledger', 'promise-dismiss']) {
     assert.ok(enterpriseReportsCommand.describe.includes(r), `${r} missing from describe`);
   }
 });
+
+// Year in review (item 16): the CLI sends Pacific-midnight instants, defaulting to the last 12 whole Pacific months.
+test('describe lists year-in-review', () => {
+  assert.ok(enterpriseReportsCommand.describe.includes('year-in-review'));
+});
+
+test('year-in-review default range is the last 12 whole Pacific months', () => {
+  const now = new Date('2026-10-14T20:00:00Z');
+  assert.deepEqual(lastTwelveWholeMonthsKeys(now), { from: '2025-10-01', to: '2026-09-30' });
+  assert.deepEqual(yearInReviewBody(undefined, undefined, now), { from: '2025-10-01T07:00:00.000Z', to: '2026-10-01T07:00:00.000Z' });
+});
+
+test('year-in-review uses Pacific, not UTC, at a month boundary and honours explicit dates (inclusive to)', () => {
+  assert.deepEqual(lastTwelveWholeMonthsKeys(new Date('2026-11-01T03:00:00Z')), { from: '2025-10-01', to: '2026-09-30' });
+  assert.deepEqual(yearInReviewBody('2026-01-01', '2026-01-31'), { from: '2026-01-01T08:00:00.000Z', to: '2026-02-01T08:00:00.000Z' });
+  assert.throws(() => yearInReviewBody('2026-02-01', '2026-01-01'), /on or before/);
+  assert.throws(() => yearInReviewBody('01/01/2026', '2026-01-31'), /yyyy-MM-dd/);
+});

package/lib/year-in-review-range.js

@@ -0,0 +1,44 @@
+// Year in review (Enterprise Reports item 16) range helpers. The default is the last 12 whole calendar months in Pacific time,
+// sent to the server as a half-open [from, to) pair of ISO instants (Pacific midnight), same rule as the Enterprise Reports tab.
+// mcp/server.js carries the same logic inline (it is a separate package); enterprise-reports.test.js pins this one.
+
+const ZONE = 'America/Los_Angeles';
+
+function offsetMs(instantMs) {
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone: ZONE, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit' }).formatToParts(new Date(instantMs));
+  const g = (t) => Number(parts.find((p) => p.type === t).value);
+  return Date.UTC(g('year'), g('month') - 1, g('day'), g('hour'), g('minute'), g('second')) - Math.floor(instantMs / 1000) * 1000;
+}
+
+/** ISO instant of Pacific midnight at the start of the yyyy-MM-dd calendar day. */
+export function pacificMidnightIso(key) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key || '');
+  if (!m) throw new Error(`Invalid date "${key}", expected yyyy-MM-dd`);
+  const wall = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  let t = wall - offsetMs(wall);
+  t = wall - offsetMs(t);
+  return new Date(t).toISOString();
+}
+
+export function addDays(key, n) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key);
+  return new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]) + n)).toISOString().slice(0, 10);
+}
+
+/** Last 12 whole Pacific calendar months as inclusive day keys: { from: first day, to: last day }. */
+export function lastTwelveWholeMonthsKeys(now = new Date()) {
+  const today = new Intl.DateTimeFormat('en-CA', { timeZone: ZONE, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now); // yyyy-MM-dd
+  const y = Number(today.slice(0, 4));
+  const mo = today.slice(5, 7);
+  const firstOfThisMonth = `${today.slice(0, 4)}-${mo}-01`;
+  return { from: `${String(y - 1).padStart(4, '0')}-${mo}-01`, to: addDays(firstOfThisMonth, -1) };
+}
+
+/** The request body: { from, to } instants. `from`/`to` are inclusive yyyy-MM-dd day keys; both default to the last 12 whole months. */
+export function yearInReviewBody(from, to, now = new Date()) {
+  const def = lastTwelveWholeMonthsKeys(now);
+  const f = from || def.from;
+  const t = to || def.to;
+  if (f > t) throw new Error('--from must be on or before --to');
+  return { from: pacificMidnightIso(f), to: pacificMidnightIso(addDays(t, 1)) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.101",
+  "version": "1.4.102",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {