@popoverai/dotrequirements 0.39.2 → 0.39.3

package/dist/commands/report.d.ts

@@ -5,6 +5,12 @@ interface ReportOptions {
     requirement?: string;
     branch?: string;
     since?: number;
+    /**
+     * The zone the console and Markdown reports write times in; the machine's
+     * when left out, as the command always leaves it (REPORT-CLOUD-2). Given
+     * by tests, so they don't depend on the zone they run in.
+     */
+    timeZone?: string;
 }
 export declare function reportCommand(options: ReportOptions): Promise<void>;
 export type { CoverageEntry };

package/dist/commands/report.js

@@ -3,8 +3,13 @@ import { findRequirementsDir, readCoverageCache } from "../harness/cache.js";
 import { formatUnrecordedNotice } from "../harness/reportingStatus.js";
 import { getProjectCoverage, getRequirementCoverage, } from "../requirements/cloud-coverage.js";
 import { buildLocalReport, } from "../requirements/coverage.js";
+import { formatInstant } from "../schema/time.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
 import { markVersionMessagesShown, versionMessages, } from "../version-messages.js";
+/** The zone this machine is set to, as "America/Los_Angeles". */
+function machineZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+}
 export async function reportCommand(options) {
     const source = options.source ?? "local";
     const format = options.format ?? "console";
@@ -39,6 +44,9 @@ export async function reportCommand(options) {
         return;
     }
     // source === "cloud"
+    // REPORT-CLOUD-2: what Casey reads is in their machine's zone; the JSON
+    // keeps the timestamps as recorded (2.4).
+    const timeZone = options.timeZone ?? machineZone();
     let projectId;
     let projectSecret;
     try {
@@ -60,7 +68,7 @@ export async function reportCommand(options) {
         console.log(printCloudRequirement(record, format, {
             branch: options.branch,
             since: options.since,
-        }, format === "json" ? await versionMessages() : []));
+        }, timeZone, format === "json" ? await versionMessages() : []));
         if (format === "json")
             markVersionMessagesShown();
         return;
@@ -72,7 +80,7 @@ export async function reportCommand(options) {
     console.log(printCloudProject(record, format, {
         branch: options.branch,
         since: options.since,
-    }, format === "json" ? await versionMessages() : []));
+    }, timeZone, format === "json" ? await versionMessages() : []));
     if (format === "json")
         markVersionMessagesShown();
 }
@@ -127,7 +135,7 @@ function formatLocalMarkdown(report) {
     }
     return out;
 }
-function printCloudRequirement(record, format, filters, messages = []) {
+function printCloudRequirement(record, format, filters, timeZone, messages = []) {
     if (format === "json") {
         // CLI-MSG-1.1: the cloud's messages for this version travel in the JSON.
         return JSON.stringify({ source: "cloud", requirement: record, messages }, null, 2);
@@ -136,13 +144,13 @@ function printCloudRequirement(record, format, filters, messages = []) {
         // REPORT-CLOUD-1.7: with filters in play, an empty record means nothing
         // matched them — say so rather than implying the requirement was never
         // tested at all
-        const filterNote = formatCloudFilters(filters);
+        const filterNote = formatCloudFilters(filters, timeZone);
         if (filterNote) {
             return `\n${record.requirementKey}: no coverage records match the requested filters (${filterNote.replace(/^Filters: /, "")}).\n`;
         }
         return `\n${record.requirementKey}: never tested on the cloud-persisted record.\n`;
     }
-    const lastTested = new Date(record.lastTestedAt).toISOString();
+    const lastTested = formatInstant(record.lastTestedAt, timeZone);
     const lines = [];
     lines.push(`\n=== Coverage for ${record.requirementKey} (cloud) ===\n`);
     lines.push(`Last tested: ${lastTested}`);
@@ -156,7 +164,7 @@ function printCloudRequirement(record, format, filters, messages = []) {
         for (const b of record.allBranches) {
             if (b.branch === record.branch)
                 continue;
-            lines.push(`  ${b.branch} — ${new Date(b.lastTestedAt).toISOString()}${b.testFile ? ` (${b.testFile}${b.testLine ? `:${b.testLine}` : ""})` : ""}`);
+            lines.push(`  ${b.branch} — ${formatInstant(b.lastTestedAt, timeZone)}${b.testFile ? ` (${b.testFile}${b.testLine ? `:${b.testLine}` : ""})` : ""}`);
         }
     }
     lines.push("");
@@ -174,7 +182,7 @@ function printCloudRequirement(record, format, filters, messages = []) {
     }
     return lines.join("\n");
 }
-function printCloudProject(record, format, filters, messages = []) {
+function printCloudProject(record, format, filters, timeZone, messages = []) {
     if (format === "json") {
         // CLI-MSG-1.1: the cloud's messages for this version travel in the JSON.
         return JSON.stringify({
@@ -186,7 +194,7 @@ function printCloudProject(record, format, filters, messages = []) {
         }, null, 2);
     }
     const summary = cloudSummary(record);
-    const filterNote = formatCloudFilters(filters);
+    const filterNote = formatCloudFilters(filters, timeZone);
     if (format === "markdown") {
         let out = `# Requirements Coverage Report (cloud)\n\n`;
         if (filterNote)
@@ -195,7 +203,7 @@ function printCloudProject(record, format, filters, messages = []) {
         if (record.tested.length > 0) {
             out += `## Tested\n\n`;
             for (const t of record.tested) {
-                out += `- **${t.requirementKey}** [${t.branch}] — ${new Date(t.lastTestedAt).toISOString()}\n`;
+                out += `- **${t.requirementKey}** [${t.branch}] — ${formatInstant(t.lastTestedAt, timeZone)}\n`;
             }
             out += "\n";
         }
@@ -214,7 +222,7 @@ function printCloudProject(record, format, filters, messages = []) {
     if (record.tested.length > 0) {
         out += "\n✓ Tested:\n";
         for (const t of record.tested) {
-            const date = new Date(t.lastTestedAt).toISOString();
+            const date = formatInstant(t.lastTestedAt, timeZone);
             out += `  ${t.requirementKey} [${t.branch}] — ${date}\n`;
         }
     }
@@ -234,12 +242,12 @@ function cloudSummary(record) {
     const coveragePercent = total > 0 ? parseFloat(((tested / total) * 100).toFixed(1)) : 0;
     return { total, tested, untested, coveragePercent };
 }
-function formatCloudFilters(filters) {
+function formatCloudFilters(filters, timeZone) {
     const parts = [];
     if (filters.branch)
         parts.push(`branch=${filters.branch}`);
     if (filters.since !== undefined) {
-        parts.push(`since=${new Date(filters.since).toISOString()}`);
+        parts.push(`since=${formatInstant(filters.since, timeZone)}`);
     }
     return parts.length > 0 ? `Filters: ${parts.join(", ")}` : "";
 }

package/dist/schema/browser.d.ts

@@ -14,4 +14,5 @@ export { composeMarkdownWithTitle, effectiveTitle, type SplitMarkdown, splitLead
 export { attachmentListsEqual } from "./attachment-lists.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
+export { formatDay, formatInstant, isTimeZone } from "./time.js";
 //# sourceMappingURL=browser.d.ts.map

package/dist/schema/browser.js

@@ -39,4 +39,7 @@ export { composeMarkdownWithTitle, effectiveTitle, splitLeadingH1, } from "./tit
 export { attachmentListsEqual } from "./attachment-lists.js";
 // Scenario building (pure TypeScript - browser-safe, used by Convex Node actions)
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
+// How a time is written for a person to read (LOCALTIME-2), shared with the
+// backend so the web's tools and Convex write the same string
+export { formatDay, formatInstant, isTimeZone } from "./time.js";
 //# sourceMappingURL=browser.js.map

package/dist/schema/time.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How the product writes a time for a person to read (LOCALTIME-2): the
+ * date, the time to the minute, and the zone by name, in the reader's zone,
+ * or in UTC, named as UTC, when the product hasn't seen it (2.3).
+ *
+ * The one formatter: the backend imports it by path for the text it writes
+ * for agents, the web for what its tools hand chat agents, and the CLI for
+ * its report (REPORT-CLOUD-2), so all three write the same string for the
+ * same moment. Dependency-free and browser-safe.
+ */
+/**
+ * An instant in a zone, as "Oct 1, 2026, 11:43 PM PDT": the zone as it
+ * stood at that moment, its US English abbreviation, or its offset where it
+ * has none, as "GMT+5:30" (LOCALTIME-2.1, 2.2). With no zone, UTC.
+ */
+export declare function formatInstant(at: number, timeZone: string | undefined): string;
+/** The day an instant falls on in a zone, as "Oct 1, 2026" (LOCALTIME-2.4). With no zone, UTC's. */
+export declare function formatDay(at: number, timeZone: string | undefined): string;
+/** Whether a string names a zone `Intl` accepts, as "America/Los_Angeles". */
+export declare function isTimeZone(name: string): boolean;
+//# sourceMappingURL=time.d.ts.map

package/dist/schema/time.js

@@ -0,0 +1,71 @@
+/**
+ * How the product writes a time for a person to read (LOCALTIME-2): the
+ * date, the time to the minute, and the zone by name, in the reader's zone,
+ * or in UTC, named as UTC, when the product hasn't seen it (2.3).
+ *
+ * The one formatter: the backend imports it by path for the text it writes
+ * for agents, the web for what its tools hand chat agents, and the CLI for
+ * its report (REPORT-CLOUD-2), so all three write the same string for the
+ * same moment. Dependency-free and browser-safe.
+ */
+const INSTANT = {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    timeZoneName: "short",
+};
+const DAY = {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+};
+/**
+ * Some ICU versions put a narrow no-break space before AM/PM. Written as a
+ * plain space, so every runtime gives the same string.
+ */
+function plain(text) {
+    return text.replace(/[\u202f\u00a0]/g, " ");
+}
+/**
+ * A formatter in the zone, or in UTC when this runtime doesn't know it: a
+ * zone is checked before it is stored, but a runtime with other zone data
+ * than the one that checked it would otherwise fail a whole tool call.
+ */
+function formatterIn(options, timeZone) {
+    try {
+        return new Intl.DateTimeFormat("en-US", {
+            ...options,
+            timeZone: timeZone ?? "UTC",
+        });
+    }
+    catch {
+        return new Intl.DateTimeFormat("en-US", { ...options, timeZone: "UTC" });
+    }
+}
+/**
+ * An instant in a zone, as "Oct 1, 2026, 11:43 PM PDT": the zone as it
+ * stood at that moment, its US English abbreviation, or its offset where it
+ * has none, as "GMT+5:30" (LOCALTIME-2.1, 2.2). With no zone, UTC.
+ */
+export function formatInstant(at, timeZone) {
+    return plain(formatterIn(INSTANT, timeZone).format(at));
+}
+/** The day an instant falls on in a zone, as "Oct 1, 2026" (LOCALTIME-2.4). With no zone, UTC's. */
+export function formatDay(at, timeZone) {
+    return plain(formatterIn(DAY, timeZone).format(at));
+}
+/** Whether a string names a zone `Intl` accepts, as "America/Los_Angeles". */
+export function isTimeZone(name) {
+    if (!name)
+        return false;
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=time.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.39.2",
+  "version": "0.39.3",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {
@@ -76,7 +76,7 @@
     "@types/node": "^22",
     "@types/uuid": "^11.0.0",
     "typescript": "^5",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.5"
   },
   "files": [
     "dist",