@northguild/gmt 1.14.2

package/skills/format-relative-time/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: format-relative-time
+description: >
+  Produce human-friendly relative time strings ("yesterday", "in 2 hours", "3
+  days ago") for any gmt value type. Use formatRelativeDate, formatRelativeTime,
+  formatRelativeDateTime for plain values; formatRelativeZoned for IANA zoned
+  values; formatRelativeUnix for epoch ms/seconds; formatRelativeUtc for UTC ISO
+  strings. All accept a reference anchor and Intl.RelativeTimeFormat options
+  (numeric, style).
+sources:
+  - 'northguild/gmt:packages/gmt/src/plain/format/formatRelativeDate.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/format/formatRelativeTime.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/format/formatRelativeDateTime.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/format/formatRelativeZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/format/formatRelativeUnix.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/format/formatRelativeUtc.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.14.2'
+---
+
+# Format Relative Time
+
+Use this skill when you need a human-friendly relative time label — "yesterday", "in 5 minutes", "2 weeks ago" — instead of an absolute timestamp. There is one relative formatter per value type; pick the one matching the input.
+
+## Picking the right formatter
+
+| Input shape | Formatter | Module |
+|---|---|---|
+| ISO date `"2024-03-15"` | `formatRelativeDate` | `@northguild/gmt` |
+| ISO time `"14:30:45"` | `formatRelativeTime` | `@northguild/gmt` |
+| ISO datetime `"2024-03-15T14:30:45"` | `formatRelativeDateTime` | `@northguild/gmt` |
+| Zoned `"2024-03-15T14:30:45-05:00[America/New_York]"` | `formatRelativeZoned` | `@northguild/gmt/zoned` |
+| Unix epoch (ms or seconds) | `formatRelativeUnix` | `@northguild/gmt/unix` |
+| UTC ISO `"2024-03-15T14:30:45Z"` | `formatRelativeUtc` | `@northguild/gmt/utc` |
+
+## Core Patterns
+
+### Plain date relative
+
+```ts
+import { formatRelativeDate } from "@northguild/gmt";
+
+const ref = "2024-03-15";
+formatRelativeDate("2024-03-14", "en-US", { reference: ref }); // "yesterday"
+formatRelativeDate("2024-03-16", "en-US", { reference: ref }); // "tomorrow"
+formatRelativeDate("2024-03-12", "en-US", { reference: ref }); // "3 days ago"
+formatRelativeDate("2024-02-23", "en-US", {
+  reference: ref,
+  largestUnit: "week",
+  numeric: "always",
+}); // "3 weeks ago"
+```
+
+### Plain time relative
+
+```ts
+import { formatRelativeTime } from "@northguild/gmt";
+
+const ref = "12:00:00";
+formatRelativeTime("11:30:00", "en-US", { reference: ref }); // "30 minutes ago"
+formatRelativeTime("12:00:30", "en-US", { reference: ref }); // "in 30 seconds"
+```
+
+### Plain datetime relative
+
+```ts
+import { formatRelativeDateTime } from "@northguild/gmt";
+
+const ref = "2024-03-15T12:00:00";
+formatRelativeDateTime("2024-03-15T10:00:00", "en-US", { reference: ref });
+// "2 hours ago"
+```
+
+### Zoned relative (DST-safe)
+
+```ts
+import { formatRelativeZoned } from "@northguild/gmt/zoned";
+
+const ref = "2024-03-15T12:00:00-04:00[America/New_York]";
+formatRelativeZoned(
+  "2024-03-15T10:00:00-04:00[America/New_York]",
+  "en-US",
+  { reference: ref },
+); // "2 hours ago"
+```
+
+Zoned arithmetic uses `Temporal.ZonedDateTime`, so spans that cross DST transitions ("fall back" / "spring forward") are still wall-clock-correct.
+
+### Unix relative
+
+```ts
+import { formatRelativeUnix } from "@northguild/gmt/unix";
+
+// Default epoch unit is milliseconds.
+formatRelativeUnix(1710507600000, "en-US", { reference: 1710511200000 });
+// "1 hour ago"
+
+// Switch to seconds via epochUnit.
+formatRelativeUnix(1710507600, "en-US", {
+  reference: 1710511200,
+  epochUnit: "seconds",
+}); // "1 hour ago"
+```
+
+### UTC relative
+
+```ts
+import { formatRelativeUtc } from "@northguild/gmt/utc";
+
+formatRelativeUtc("2024-03-15T11:00:00Z", "en-US", {
+  reference: "2024-03-15T12:00:00Z",
+}); // "1 hour ago"
+```
+
+## Shared options
+
+All relative formatters accept the same option shape (besides their type-specific `reference`):
+
+- `reference` — **required** anchor of the same input shape (e.g. an ISO date for `formatRelativeDate`).
+- `numeric: "auto" | "always"` — default `"auto"`.
+  - `"auto"` produces phrases like `"yesterday"`, `"tomorrow"`, `"last week"`.
+  - `"always"` forces numeric form: `"1 day ago"`, `"in 1 day"`.
+- `style: "long" | "short" | "narrow"` — default `"long"`.
+  - `"long"`: `"3 minutes ago"`
+  - `"short"`: `"3 min. ago"`
+  - `"narrow"`: `"3m ago"`
+- `largestUnit` — pick a specific bucket (`"second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year"`). Useful when you want `"3 weeks ago"` even though the difference would auto-bucket to `"last month"`.
+- `roundingMethod: "floor" | "ceil" | "round"` — default `"round"`. Controls how the fractional distance rounds to the display unit; `"floor"`/`"ceil"` apply directly to the signed value (not its absolute value), so they respect whether the distance is past or future.
+
+## Runtime ICU data
+
+These formatters delegate locale rendering to the host runtime's `Intl.RelativeTimeFormat`. Output therefore depends on the ICU data shipped with the running Node (or browser):
+
+- **Full ICU** runtimes (official Node binaries from nodejs.org, all modern browsers) return fully localized strings — e.g. `formatRelativeDate("2023-03-15", "sv-SE", { reference: "2024-03-15" })` returns `"i fjol"`.
+- **Small/partial ICU** runtimes (some Node builds compiled with `--with-intl=small-icu` or repackaged distributions) fall back to a longer/different form — the same call may return `"förra året"`. Some locales (e.g. he-IL) also tack on a fallback numeric suffix like `"לפני שעתיים (2)"` instead of the full-ICU dual form `"לפני שעתיים"`.
+
+This is a property of the runtime, not gmt. For consistent non-English output, deploy on a full-ICU Node build or polyfill `Intl` with a package that bundles locale data.
+
+## Common Mistakes
+
+### HIGH Forgetting `reference`
+
+Wrong:
+
+```ts
+formatRelativeDate("2024-03-12"); // "" — no anchor to diff against
+```
+
+Correct:
+
+```ts
+formatRelativeDate("2024-03-12", "en-US", { reference: "2024-03-15" });
+// "3 days ago"
+```
+
+Source: `packages/gmt/src/plain/format/formatRelativeDate.ts` — `reference` is required.
+
+### HIGH Mismatched input shape between value and reference
+
+Wrong:
+
+```ts
+formatRelativeDate("2024-03-15T10:00:00", "en-US", {
+  reference: "2024-03-15", // datetime as value, date as reference
+}); // ""
+```
+
+Correct: match shapes — use `formatRelativeDateTime` for datetimes, `formatRelativeDate` for dates, etc.
+
+Source: each relative formatter validates its input shape and returns `""` on mismatch.
+
+### HIGH Hand-rolling diff math with `Date`
+
+Wrong:
+
+```ts
+const diffMs = new Date(value).getTime() - new Date(ref).getTime();
+const label = `${Math.round(diffMs / 60000)} minutes ago`; // ignores locale, DST
+```
+
+Correct:
+
+```ts
+import { formatRelativeDateTime } from "@northguild/gmt";
+
+formatRelativeDateTime(value, locale, { reference: ref });
+```
+
+Source: AGENTS.md — Never use JavaScript Date APIs.
+
+### MEDIUM Picking the wrong formatter for a Unix value
+
+Wrong:
+
+```ts
+import { formatRelativeUtc } from "@northguild/gmt/utc";
+
+formatRelativeUtc(1710507600000, "en-US", { reference: 1710511200000 });
+// "" — formatRelativeUtc expects ISO strings, not numbers
+```
+
+Correct:
+
+```ts
+import { formatRelativeUnix } from "@northguild/gmt/unix";
+
+formatRelativeUnix(1710507600000, "en-US", { reference: 1710511200000 });
+// "1 hour ago"
+```
+
+Source: `packages/gmt/src/unix/format/formatRelativeUnix.ts`.
+
+### LOW Relying on `"auto"` numeric for tomorrow/yesterday wording
+
+`numeric: "auto"` produces the locale's natural words ("yesterday", "ayer", "gestern") only when the diff is exactly ±1 of the largest unit. Past that boundary it falls back to numeric ("2 days ago"). If you need a consistent word-form output, pair `numeric: "auto"` with `largestUnit` to force a specific bucket.
+
+## References
+
+- [Intl.RelativeTimeFormat documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)
+- [Format Date/Time skill](../format-date-time/SKILL.md) — for absolute formatting
+- [Zoned date operations skill](../zoned-date-ops/SKILL.md) — for timezone-aware operations

package/skills/get-current/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: get-current
+description: >
+  Get the current date, time, or datetime as ISO 8601 strings. Use getNow(),
+  getToday(), getSystemTimeZone(), or getTimeZones() for current temporal
+  values. String output for logging; use Temporal for manipulation.
+sources:
+  - 'northguild/gmt:packages/gmt/src/plain/get/getNow.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/get/getToday.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/get/getSystemTimeZone.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/get/getTimeZones.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.14.2'
+---
+
+# Get Current Date/Time
+
+Use this skill when you need to get the current date, time, or datetime.
+
+## Setup
+
+```ts
+import { getNow, getToday } from "@northguild/gmt";
+import { getSystemTimeZone, getTimeZones } from "@northguild/gmt/zoned";
+import { getUtcNow, getUtcToday } from "@northguild/gmt/utc";
+import { getUnixNow, getUnixTimeMs } from "@northguild/gmt/unix";
+```
+
+## Core Patterns
+
+### Get current local date
+
+```ts
+// Returns current date as ISO string in system timezone
+const today = getToday(); // "2024-03-15"
+```
+
+### Get current local datetime
+
+```ts
+// Returns current datetime as ISO string in system timezone
+const now = getNow(); // "2024-03-15T14:30:45"
+```
+
+### Get current UTC date
+
+```ts
+import { getUtcToday } from "@northguild/gmt/utc";
+
+const utcToday = getUtcToday(); // "2024-03-15"
+```
+
+### Get current UTC datetime
+
+```ts
+import { getUtcNow } from "@northguild/gmt/utc";
+
+const utcNow = getUtcNow(); // "2024-03-15T14:30:45"
+```
+
+### Get current Unix timestamp (seconds)
+
+```ts
+import { getUnixNow } from "@northguild/gmt/unix";
+
+const unixNow = getUnixNow(); // 1710504645
+```
+
+### Get current Unix timestamp (milliseconds)
+
+```ts
+import { getUnixTimeMs } from "@northguild/gmt/unix";
+
+const unixMs = getUnixTimeMs(); // 1710504645000
+```
+
+### Get the system timezone
+
+```ts
+import { getSystemTimeZone } from "@northguild/gmt/zoned";
+
+const tz = getSystemTimeZone(); // "America/New_York"
+```
+
+### Get all available IANA timezones
+
+```ts
+import { getTimeZones } from "@northguild/gmt/zoned";
+
+const timeZones = getTimeZones(); // ["America/New_York", "Europe/London", ...]
+timeZones.length; // ~422 (varies by runtime/ICU)
+```
+
+### Using Temporal directly for manipulation
+
+```ts
+import { Temporal } from "@js-temporal/polyfill";
+
+// Current instant for precise timing
+const instant = Temporal.Now.instant(); // Temporal.Instant
+
+// Current plain date in system timezone
+const plainDate = Temporal.Now.plainDateISO(); // Temporal.PlainDate
+
+// Current plain datetime in system timezone
+const plainDateTime = Temporal.Now.plainDateTimeISO(); // Temporal.PlainDateTime
+
+// Current zoned datetime in system timezone
+const zonedDateTime = Temporal.Now.zonedDateTimeISO("America/New_York"); // Temporal.ZonedDateTime
+```
+
+## Common Mistakes
+
+### CRITICAL Using Date.now() instead of Temporal
+
+Wrong:
+
+```ts
+const now = Date.now(); // returns milliseconds number
+```
+
+Correct:
+
+```ts
+import { getUnixNow } from "@northguild/gmt/unix";
+
+const now = getUnixNow(); // returns number in seconds
+```
+
+Source: AGENTS.md — Never use JavaScript Date APIs
+
+### HIGH Using new Date() for current time
+
+Wrong:
+
+```ts
+const now = new Date(); // mutable Date object
+```
+
+Correct:
+
+```ts
+import { getNow } from "@northguild/gmt";
+
+const now = getNow(); // immutable ISO string
+```
+
+Source: AGENTS.md — String-only inputs/outputs
+
+### MEDIUM Not handling empty string on error
+
+Wrong:
+
+```ts
+const now = getToday();
+// Assume now is always valid
+process(now);
+```
+
+Correct:
+
+```ts
+const now = getToday();
+if (!now) {
+  throw new Error("Failed to get current date");
+}
+process(now);
+```
+
+Source: packages/gmt/src/plain/get/getNow.ts — Returns "" on error
+
+### MEDIUM Looking for value-taking `get*` functions here
+
+`getDaysInMonth`, `getDaysInYear`, `getDayOfYear`, `getWeeksInYear`,
+`getWeeksInMonth`, `getWeekOfMonth`, `getWeekYear`, `getLocaleWeekYear`,
+and `getWeeksInLocaleWeekYear` take a date value, so despite the
+`get` prefix they live in `calculate/`, not `get/`. GMT's `get/` namespaces
+are current-moment accessors only (no argument, or timezone only) — see
+`context/coding-standards.md`'s API Contract section.
+
+Wrong:
+
+```ts
+import { getDaysInMonth } from "@northguild/gmt/plain/get"; // not exported here
+```
+
+### MEDIUM Bucketing by week number without its week-year
+
+`weekOfYearForDate`/`getWeekNumber` return a week number alone (1-53),
+which is ambiguous across a year boundary: 2024-12-30 is a Monday in ISO
+week 1, but of **2025**, not 2024. A date-only week number will silently
+land December dates in the wrong bucket. Pair it with `getWeekYear`
+(ISO) or `getLocaleWeekYear` (locale-relative) whenever you bucket or key
+by week.
+
+Wrong:
+
+```ts
+const bucketKey = weekOfYearForDate(value); // "1" — but which year's week 1?
+```
+
+Correct:
+
+```ts
+import { getWeekYear, weekOfYearForDate } from "@northguild/gmt";
+
+const bucketKey = `${getWeekYear(value)}-W${weekOfYearForDate(value)}`;
+```
+
+Source: packages/gmt/src/plain/calculate/getWeekYear.ts, getLocaleWeekYear.ts, getWeeksInLocaleWeekYear.ts
+
+Correct:
+
+```ts
+import { getDaysInMonth } from "@northguild/gmt"; // or "@northguild/gmt/plain/calculate"
+
+getDaysInMonth("2024-02-15"); // 29
+```
+
+Source: context/coding-standards.md — `get/` namespaces hold current-moment accessors only
+
+## References
+
+- [Full get API](references/get-api.md)
+- [Temporal.Now documentation](https://tc39.es/proposal-temporal/docs/now.html)