@northguild/gmt 1.14.2 → 1.15.0

package/skills/_artifacts/skill_tree.yaml

@@ -1,278 +0,0 @@
-# skills/_artifacts/skill_tree.yaml
-# Generated by skill-tree-generator
-# Library: @northguild/gmt
-# Version: 1.14.0
-library:
-  name: '@northguild/gmt'
-  version: 1.14.0
-  repository: https://github.com/northguild/gmt.git
-  description: Temporal-based date and time utilities with timezone support and polyfill integration
-generated_from:
-  domain_map: 'skills/_artifacts/domain_map.yaml'
-  skill_spec: 'skills/_artifacts/skill_spec.md'
-generated_at: '2026-08-23'
-
-skills:
-  # Consumer-facing core skills
-  - name: Get Current Date/Time
-    slug: get-current
-    type: core
-    domain: core-date-operations
-    path: 'skills/get-current/SKILL.md'
-    package: 'packages/gmt'
-    description: Get the current date, time, or timestamp as ISO 8601 strings
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
-
-  - name: Parse Date/Time
-    slug: parse-date-time
-    type: core
-    domain: core-date-operations
-    path: 'skills/parse-date-time/SKILL.md'
-    package: 'packages/gmt'
-    description: Parse individual components from date/time strings; also parseRfc2822, parseHttp, parseSql, parseRfc3339 for decoding fixed interchange grammars (email Date headers, HTTP headers, SQL datetime literals, RFC 3339)
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/parse/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/parse/parseRfc2822.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/parse/parseHttp.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/parse/parseSql.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/parse/parseRfc3339.ts'
-
-  - name: Format Date/Time
-    slug: format-date-time
-    type: core
-    domain: core-date-operations
-    path: 'skills/format-date-time/SKILL.md'
-    package: 'packages/gmt'
-    description: Format date/time values for display with locale support; includes plain absolute (formatDate/Time/DateTime), plain relative (formatRelativeDate/Time/DateTime), standalone locale calendar-name lookups (getLocaleEraNames, getLocaleMonthNames, getLocaleWeekdayNames, getLocaleMeridiems), and fixed-grammar named machine formats (formatRfc2822, formatHttp, formatSql, formatRfc3339)
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/format/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/locale/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleEraNames.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleMonthNames.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleWeekdayNames.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/format/formatRfc2822.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/format/formatHttp.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/format/formatSql.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/format/formatRfc3339.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleMeridiems.ts'
-
-  - name: Format Relative Time
-    slug: format-relative-time
-    type: core
-    domain: core-date-operations
-    path: 'skills/format-relative-time/SKILL.md'
-    package: 'packages/gmt'
-    description: Produce human-friendly relative strings ("yesterday", "in 2 hours") across plain, zoned, unix, and utc values
-    requires:
-      - format-date-time
-    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'
-
-  - name: Calculate Dates
-    slug: calculate-dates
-    type: core
-    domain: core-date-operations
-    path: 'skills/calculate-dates/SKILL.md'
-    package: 'packages/gmt'
-    description: Add or subtract time from dates; add*/subtract* accept an optional overflow ("constrain" | "reject") option, diff* accept optional smallestUnit/roundingIncrement/roundingMode rounding options, addBusinessDays/subtractBusinessDays skip weekends for Mon–Fri arithmetic, clampDate restricts a date to a range, closestDateTo finds the nearest candidate by calendar distance, getLocaleStartOfWeek/getLocaleEndOfWeek compute locale-driven week boundaries
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/calculate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/calculate/clampDate.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/calculate/closestDateTo.ts'
-
-  - name: Durations
-    slug: durations
-    type: core
-    domain: core-date-operations
-    path: 'skills/durations/SKILL.md'
-    package: 'packages/gmt'
-    description: Parse, validate, combine, rebalance, and format ISO 8601 duration strings via isValidDuration, parseDuration, addDuration/subtractDuration, normalizeDuration, and formatDuration; bridge diff* functions to duration strings via diffDateAsDuration/diffDateTimeAsDuration/diffZonedAsDuration/diffUnixAsDuration/diffUtcAsDuration
-    requires:
-      - calculate-dates
-    sources:
-      - 'northguild/gmt:packages/gmt/src/duration/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/calculate/diffDateAsDuration.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/calculate/diffDateTimeAsDuration.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/diffZonedAsDuration.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/calculate/diffUnixAsDuration.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/calculate/diffUtcAsDuration.ts'
-
-  - name: Compare Dates
-    slug: compare-dates
-    type: core
-    domain: core-date-operations
-    path: 'skills/compare-dates/SKILL.md'
-    package: 'packages/gmt'
-    description: Compare date values for ordering; use isWeekend/isZonedWeekend for locale-aware weekend checks, isBusinessDay for fixed ISO Mon–Fri business-day checks, and getLocaleDayOfWeek/getLocaleZonedDayOfWeek for locale-relative day-of-week indices
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/compare/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
-
-  - name: Validate Dates
-    slug: validate-dates
-    type: core
-    domain: core-date-operations
-    path: 'skills/validate-dates/SKILL.md'
-    package: 'packages/gmt'
-    description: Validate date/time strings, timezone identifiers, intervals, and ranges; check whether a timezone observes daylight saving time (hasDaylightSaving); list DST transition instants for a timezone in a given year (getDstTransitions); check point-in-interval and interval-in-interval containment; merge overlapping or adjacent intervals; split intervals into sub-intervals by duration unit
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalContainsDate.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalContainsTime.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalContainsDateTime.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalUnionDate.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalUnionTime.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalUnionDateTime.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/splitIntervalByUnitDate.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/splitIntervalByUnitTime.ts'
-      - 'northguild/gmt:packages/gmt/src/plain/interval/splitIntervalByUnitDateTime.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/interval/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/interval/intervalContainsUtc.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/interval/intervalUnionUtc.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/interval/splitIntervalByUnitUtc.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/interval/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/interval/intervalContainsUnix.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/interval/intervalUnionUnix.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/interval/splitIntervalByUnitUnix.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/validate/hasDaylightSaving.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/get/getDstTransitions.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/interval/validate/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/interval/intervalContainsZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/interval/intervalUnionZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/interval/splitIntervalByUnitZoned.ts'
-
-  - name: Zoned Date Operations
-    slug: zoned-date-ops
-    type: core
-    domain: zoned-date-operations
-    path: 'skills/zoned-date-ops/SKILL.md'
-    package: 'packages/gmt'
-    description: Work with timezone-aware dates and times; includes formatZonedDateTime, formatZonedRange, formatRelativeZoned, convertPlainDateTimeToZoned with full DST disambiguation control, addZoned/subtractZoned with overlap-only DST disambiguation control, clampZoned/closestZonedTo for range restriction and nearest-candidate selection, and the startOfZoned/endOfZoned/startOfQuarterForZoned/endOfQuarterForZoned/mapZonedHoursInDay/getLocaleZonedStartOfWeek/getLocaleZonedEndOfWeek/getLocaleZonedDayOfWeek family (plus unix/ counterparts) with full disambiguation + offset control
-    sources:
-      - '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/zoned/convert/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/subtractZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/endOfZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfQuarterForZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/endOfQuarterForZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedStartOfWeek.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedEndOfWeek.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/clampZoned.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/calculate/closestZonedTo.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/map/mapZonedHoursInDay.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/calculate/startOfUnix.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/calculate/endOfUnix.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/calculate/startOfQuarterForUnix.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/calculate/endOfQuarterForUnix.ts'
-
-  - name: Convert Temporal Types
-    slug: convert-types
-    type: core
-    domain: conversion
-    path: 'skills/convert-types/SKILL.md'
-    package: 'packages/gmt'
-    description: Convert between plain and zoned (with DST disambiguation control), or unix/utc representations; convertDateToCalendar expresses a date in a non-Gregorian CalendarSystem (gregorian, hebrew, islamic-civil, islamic-tabular, islamic-umalqura, japanese, buddhist, taiwan, persian, indian, ethiopic, ethiopic-amete-alem, coptic)
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/convert/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/convert/index.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
-      - 'northguild/gmt:packages/gmt/src/types/calendar-system.ts'
-      - 'northguild/gmt:packages/gmt/src/internal/ethiopicFamilyCalendar.ts'
-
-  # Consumer-facing interval skills
-  - name: Interval Operations
-    slug: interval-ops
-    type: core
-    domain: interval-operations
-    path: 'skills/interval-ops/SKILL.md'
-    package: 'packages/gmt'
-    description: Range math over two-point intervals — validate, contain, overlap, intersect, union, difference, xor, abut, engulf, construct from a point + duration, split by duration unit, and count calendar-unit boundaries across plain, zoned, unix, and utc
-    requires: []
-    sources:
-      - 'northguild/gmt:packages/gmt/src/plain/interval/index.ts'
-      - 'northguild/gmt:packages/gmt/src/zoned/interval/index.ts'
-      - 'northguild/gmt:packages/gmt/src/unix/interval/index.ts'
-      - 'northguild/gmt:packages/gmt/src/utc/interval/index.ts'
-      - 'northguild/gmt:packages/gmt/src/duration/validate/isValidDuration.ts'
-
-  # Consumer-facing composition skills
-  - name: App Integration
-    slug: app-integration
-    type: composition
-    domain: integration
-    path: 'skills/app-integration/SKILL.md'
-    package: 'packages/gmt'
-    description: Integrate gmt with application frameworks
-
-  - name: Lint Package Suggestion
-    slug: lint-package-suggestion
-    type: composition
-    domain: integration
-    path: 'skills/lint-package-suggestion/SKILL.md'
-    package: 'packages/gmt'
-    description: Recommend appropriate lint packages from @northguild toolchain
-    requires: []
-
-  # Lifecycle skills
-  - name: Issue Creation
-    slug: issue-creation
-    type: lifecycle
-    domain: core-date-operations
-    path: 'skills/issue-creation/SKILL.md'
-    package: 'packages/gmt'
-    description: Create feature requests with proper details for maintainers
-
-  - name: PR Contribution
-    slug: pr-contribution
-    type: lifecycle
-    domain: integration
-    path: 'skills/pr-contribution/SKILL.md'
-    package: 'packages/gmt'
-    description: Contribute improvements via pull requests
-
-  # Maintainer skills (document how to work on gmt itself)
-  - name: New Method Implementation
-    slug: new-method-implementation
-    type: core
-    domain: core-date-operations
-    path: 'skills/new-method-implementation/SKILL.md'
-    package: 'packages/gmt'
-    description: Implement or extend a gmt API in packages/gmt/src
-
-  - name: Unit Test Generation
-    slug: unit-test-generation
-    type: core
-    domain: core-date-operations
-    path: 'skills/unit-test-generation/SKILL.md'
-    package: 'packages/gmt'
-    description: Write or update gmt unit tests with deterministic Temporal-safe patterns
-    requires:
-      - new-method-implementation
-
-  - name: API Expansion Workflow
-    slug: api-expansion-workflow
-    type: lifecycle
-    domain: core-date-operations
-    path: 'skills/api-expansion-workflow/SKILL.md'
-    package: 'packages/gmt'
-    description: Handle feature requests for missing gmt functionality

package/skills/api-expansion-workflow/SKILL.md

@@ -1,52 +0,0 @@
----
-name: api-expansion-workflow
-description: >
-  Handle feature requests for missing gmt functionality by checking existing
-  APIs first, then proposing a Temporal-backed custom method path with required
-  issue/PR guidance and test-backed behavioral specs.
-metadata:
-  library_version: 1.14.2
----
-
-# API Expansion Workflow
-
-Use this skill when a user asks for behavior that is not currently covered by gmt.
-
-## Decision flow
-
-1. Check existing APIs first
-- Search `packages/gmt/src/plain` and `packages/gmt/src/zoned`.
-- If capability exists, use the existing method and do not add new API.
-
- - When evaluating whether to add a new API, enforce the library's strict input/output policy: new public methods must accept explicit shapes (ISO 8601 strings, IANA timezone ids, or numeric unix epochs) and return normalized outputs. If the requested capability implies permissive parsing, recommend implementing a small adapter outside of core gmt instead of widening gmt's surface.
-
-2. If capability does not exist
-- Tell the user it is possible with Temporal because gmt ships Temporal.
-- Tell the user it requires a new custom method in gmt.
-
-3. Ask for product feedback loop
-- Recommend opening a GitHub issue requesting the method.
-- Suggest they include use case, expected input/output, and timezone expectations.
-
-4. If implementing now
-- Implement method with Temporal using gmt conventions.
-- Add solid unit tests in the same change.
-- Suggest opening a PR against gmt or attaching exact proposal text to the issue.
-
-## Required issue template guidance
-
-Encourage users to include:
-
-1. Problem statement and current workaround.
-2. Proposed method name.
-3. Input and output examples.
-4. Invalid input behavior expectations.
-5. Plain vs zoned expectations and locale/timezone constraints.
-
-## Test requirements for expansion work
-
-1. Happy-path coverage for core scenarios.
-2. Invalid-input fallback coverage.
-3. Boundary coverage for date/time edges.
-4. Zoned/DST coverage when timezone logic is involved.
-5. Locale matrix coverage when locale options are part of API behavior.

package/skills/app-integration/SKILL.md

@@ -1,38 +0,0 @@
----
-name: app-integration
-description: >
-  Guidance for integrating `@northguild/gmt` with application frameworks and
-  libraries (routers, query caches, table sorting, state management). Emphasizes
-  strict I/O, canonicalization, and cache-key hygiene.
-metadata:
-  library_version: 1.14.2
----
-
-# App Integration
-
-Use this skill when recommending or implementing integrations between gmt
-and application frameworks and libraries (routers, query caches, table
-sorting/grouping, state management, etc.).
-
-## Purpose
-
-- Encourage stable cache keys that depend on explicit, canonical representations (ISO 8601 strings or normalized epoch numbers) instead of `Date` objects or fuzzy strings.
-- Recommend validating and canonicalizing inputs with gmt validators/parsers before using them in keys or persisted state.
-
-## Recommendations
-
-- Use ISO 8601 strings for query/cache keys:
-
-  ```js
-  ['events', { start: '2024-02-29', end: '2024-03-01' }]
-  ```
-
-- Validate timezone params with `isValidTimezone` before using as a key.
-- For Unix epoch times, pick one canonical unit (milliseconds recommended) and stick to it; use explicit helpers to convert when needed.
-- Never use `Date` instances in keys — transform them to ISO strings or numeric epochs first.
-- When working with routers (Next.js, React Router, etc.), ensure date params are validated and canonicalized before use in loaders/components.
-- For table libraries (TanStack Table, etc.), use ISO strings for sort keys to ensure consistent ordering across environments.
-
-## Design Principle
-
-- Reiterate gmt's strict I/O philosophy: public APIs accept explicit shapes only (ISO 8601 strings, IANA timezone ids, epoch numbers). Keep canonicalized representations at boundaries to ensure cache stability and reproducible behavior across environments.