@northguild/gmt 1.14.2 → 1.15.0

package/skills/gmt-basics/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: gmt-basics
+description: >
+  Core date/time basics — get current values, parse components, format for
+  display, format relative time, compare dates, and validate
+  strings/timezones/intervals. Reads the installed package README.md and source
+  JSDoc for API details; this skill is a routing pointer, not an API dump.
+sources:
+  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/parse/index.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/locale/index.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/compare/index.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.15.0'
+---
+
+# GMT Basics
+
+Use this skill when the task touches core date/time read operations: getting the
+current time, parsing components out of a date string, formatting for display,
+producing human-friendly relative strings, comparing two values, or validating
+input before you act on it.
+
+## When to load
+
+- The user needs "now" as an ISO string, or a formatted/localized display value.
+- The user wants to extract a year/month/day/hour from a date string.
+- The user needs "yesterday" or "in 2 hours" style output.
+- The user is comparing or sorting two date strings.
+- The user wants to guard a call with a validity check first.
+
+## Core rules
+
+1. **ISO 8601 strings in.** Public APIs consume ISO strings, IANA timezone ids,
+   or numeric Unix epochs — never `new Date()`.
+2. **Sentinel returns, never throws.** `""` for strings, `null` for numbers,
+   `false` for booleans, `[]` for arrays. Always check before using.
+3. **Read the README.** This skill is a routing pointer. For full API
+   signatures, locale matrices, and code examples, read the installed package's
+   `README.md` and the source JSDoc of the function you intend to call.
+
+## Key functions
+
+- **Current values**: `getNow`, `getToday`, `getUtcNow`, `getUnixNow`,
+  `getSystemTimeZone`, `getTimeZones`
+- **Parsing**: `parseYearFromDate`, `parseMonthFromDate`,
+  `parseDateTimeWithPattern`, `parseRfc3339`, `parseHttp`, `parseSql`
+- **Formatting**: `formatDate`, `formatTime`, `formatDateTime`,
+  `formatRelativeDate`, `formatCalendar`, `formatRfc3339`
+- **Locale names**: `getLocaleMonthNames`, `getLocaleWeekdayNames`,
+  `getLocaleMeridiems`, `getLocaleEraNames`
+- **Comparison**: `isAfterDate`, `isBeforeDate`, `areDatesEqual`,
+  `areDatesEqualBy`, `isWeekend`, `isBusinessDay`, `nextWeekday`
+- **Validation**: `isValidDate`, `isValidTime`, `isValidTimeZone`,
+  `isValidZonedDateTime`, `isValidDateInterval`
+
+## Common pitfalls
+
+- `formatRelativeDate` requires a `reference` option — without it, you get `""`.
+- `parseDateWithPattern` returns `""` on shape-valid-but-unreal dates (regex
+  only proves shape; Temporal validates the real value).
+- Week numbers are ambiguous across year boundaries — pair
+  `parseWeekFromDate` with `getWeekYear`.
+- `isWeekend` is locale-aware via `Intl.Locale.weekInfo`; `isBusinessDay` is
+  fixed ISO Mon–Fri with no locale and no holidays.
+
+## References
+
+- [README — API Surface and Quick Start](README.md)
+- [Full API reference](/reference/plain)

package/skills/gmt-integration/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: gmt-integration
+description: >
+  Application integration patterns — stable cache keys, router/query params,
+  table-sort keys, and lint package selection (ESLint, Biome, Oxlint). Reads the
+  installed package README.md and lint-package READMEs for API details; this
+  skill is a routing pointer, not an API dump.
+sources:
+  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+metadata:
+  type: composition
+  library: '@northguild/gmt'
+  library_version: '1.15.0'
+---
+
+# GMT Integration
+
+Use this skill when integrating GMT into an application framework or choosing
+which lint package to install for Date-ban enforcement.
+
+## When to load
+
+- The user asks about cache keys, router params, or table-sort keys for dates.
+- The user wants to validate a timezone id before using it as a cache key.
+- The user is picking an ESLint, Biome, or Oxlint plugin to ban `Date` APIs.
+- The user has a lint package but not the gmt runtime (or vice versa).
+
+## Core rules
+
+1. **Canonical, stable representations at boundaries.** Use ISO 8601 strings or
+   normalized epoch numbers for cache keys — never `Date` objects or fuzzy
+   strings. Different environments must produce the same key.
+2. **Validate before you key.** Always run `isValidTimeZone` on a timezone parameter
+   before using it as a cache key or router param — `"Invalid/Zone"` is a sentinel
+   failure, not a real zone.
+3. **Pick one canonical Unix unit.** If you mix epoch seconds and milliseconds,
+   convert explicitly with `convertUtcToUnix` / `convertUtcToUnixMs` rather than
+   dividing/multiplying by hand.
+4. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
+   only the one matching the project's existing linter; do not force all three.
+5. **Read the READMEs.** This skill is a routing pointer. For full integration
+   guidance, read the installed package's `README.md` and the matching
+   `@northguild/gmt-eslint` / `gmt-oxlint` / `gmt-biome` README.
+
+## Lint package selection
+
+| Current lint stack | Recommend |
+| --- | --- |
+| ESLint | `@northguild/gmt-eslint` |
+| Biome | `@northguild/gmt-biome` |
+| Oxlint | `@northguild/gmt-oxlint` |
+| No linter yet | Add one of the above; install `@northguild/gmt` first |
+
+These can be used individually or together. If the project has a lint package
+but no `@northguild/gmt`, suggest adding gmt to support safe Date-to-Temporal
+refactors. Lint findings should point toward existing gmt methods first; only
+suggest a new Temporal custom method (and an issue) when no gmt helper covers
+the pattern.
+
+## Integration guidance
+
+- **Query/cache keys**: `['events', { start: '2024-02-29', end: '2024-03-01' }]`
+  — ISO strings, validated.
+- **Router params**: validate with `isValidDate` / `isValidTimeZone` before use.
+- **Table sorting**: use ISO strings as sort keys for consistent ordering.
+- **State management**: canonicalized strings/numbers at boundaries only.
+
+## References
+
+- [README — Install and Design Philosophy](README.md)
+- [Lint Package Selection guide](/guides/integration/linting/)
+- [Core Rules](/core-rules/)

package/skills/gmt-timezone/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: gmt-timezone
+description: >
+  Timezone-aware operations — get zoned now, format zoned datetimes/ranges,
+  convert between plain↔zoned↔UTC↔Unix, and DST disambiguation control on
+  construction and arithmetic. Reads the installed package README.md and source
+  JSDoc for API details; this skill is a routing pointer, not an API dump.
+sources:
+  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/clampZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.15.0'
+---
+
+# GMT Timezone
+
+Use this skill when the task requires IANA time zone awareness — formatting,
+converting between time zones, or doing arithmetic that must respect DST.
+
+## When to load
+
+- The user needs the current time in a specific timezone (`"America/New_York"`).
+- The user wants to format a datetime with its zone attached.
+- The user needs to convert a plain datetime to a zoned instant, or between
+  timezones, or between UTC and Unix epochs.
+- The user is adding/subtracting durations across a DST transition.
+
+## Core rules
+
+1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[America/New_York]"`
+   is correct; bare `"-05:00"` loses the zone and can't observe DST rules.
+2. **DST disambiguation.** `convertPlainDateTimeToZoned`, `addZoned`, `startOfZoned`,
+   and `setZoned` accept `disambiguation` (`"compatible"` | `"earlier"` |
+   `"later"` | `"reject"`) for gap/overlap resolution. It only affects fall-back
+   overlaps, **not** spring-forward gaps — use `convertPlainDateTimeToZoned`
+   with `"reject"` for gap-safety.
+3. **The `offset` parameter.** Defaults to `"ignore"` so `disambiguation` takes
+   effect. Passing `offset: "prefer"` keeps the source offset and silently
+   disables `disambiguation` — leave it at default unless you need Temporal's
+   raw `.with()` semantics.
+4. **Calendar annotations.** GMT's zoned grammar puts `[u-ca=...]` **before**
+   `[timeZone]` — the reverse of RFC 9557. Only `addZoned`, `subtractZoned`,
+   `diffZoned`, and `convertZonedToCalendar` accept it; everything else rejects
+   it and returns `""`. Always produce these with `convertZonedToCalendar`.
+5. **Read the README.** This skill is a routing pointer. For the full DST
+   disambiguation walkthrough, code examples, and locale ICU notes, read the
+   installed package's `README.md` and the source JSDoc.
+
+## Key functions
+
+- **Current**: `getZonedNow`, `getZonedToday`
+- **Formatting**: `formatZonedDateTime`, `formatZonedRange`,
+  `formatRelativeZoned`, `formatTimeZoneName`
+- **Validation**: `isValidTimeZone`, `isValidZonedDateTime`,
+  `hasDaylightSaving`, `getDstTransitions`, `isInDaylightSaving`
+- **Conversion**: `convertPlainDateTimeToZoned`, `convertZonedToPlainDateTime`,
+  `convertUtcToZoned`, `convertZonedToUtc`, `convertZonedToCalendar`,
+  `convertUtcToUnix`, `convertUnixToUtc`
+- **Arithmetic (with disambiguation)**: `addZoned`, `subtractZoned`, `clampZoned`,
+  `closestZonedTo`, `startOfZoned`, `endOfZoned`, `startOfQuarterForZoned`,
+  `setZoned`, `cycleZoned`, `mapZonedHoursInDay`, `getHoursInZonedDay`
+- **Offset/DST reads**: `getZonedOffset`, `getZonedOffsetAs`,
+  `getTimeZoneOffset`, `parseTimezoneFromZoned`
+
+## References
+
+- [README — Timezone and Calendar examples](README.md)
+- [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/docs/dst-disambiguation/)