Initial Commit

openspec/archive/2026-04-19-enterprise-sitemap/proposal.md

@@ -0,0 +1,60 @@
+# OpenSpec Change: enterprise-sitemap
+
+- **Change ID**: enterprise-sitemap
+- **Package**: `@suaveplan/sitemap`
+- **Category**: universal
+- **Target path**: `universal/platform/sitemap`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/sitemap.md`
+
+## Summary
+
+Greenfield rebuild of `@suaveplan/sitemap` — RFC-compliant XML sitemap generator + parser with image, video, and news extensions; sitemap-index generator for sites > 50 k URLs; incremental builder with hash-based change detection; gzip compression with `Content-Encoding` headers; structured errors.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/types`
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`, `fflate` (compression), `fast-xml-parser`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Generator / parser
+
+- `SitemapGenerator`, `SitemapIndexGenerator`
+- Types: `SitemapOptions`, `SitemapUrl`, `SitemapImage`, `SitemapVideo`, `SitemapNews`, `SitemapIndex`, `ChangeFreq`, `RobotsRule`, `VALID_CHANGE_FREQS`, `SitemapIndexConfig`, `SitemapIndexResult`, `SubSitemap`
+
+### Extensions
+
+- Images: `addImagesToUrl`, `addImagesToUrlSet`, `countImages`, `createImageEntry`, `extractImageUrls`, `removeImagesFromUrl`, `validateImageData`, `validateImageSet`
+- Videos: `addVideosToUrl`, `addVideosToUrlSet`, `countVideos`, `createVideoEntry`, `extractVideoTitles`, `removeVideosFromUrl`, `validateVideoData`
+
+### Incremental
+
+- `IncrementalBuilder`, `computeUrlHash`, `IncrementalBuilderConfig`, `UrlChangeRecord`, `ChangeDetectionMode`, `ChangeDetectionResult`
+
+### Compression
+
+- `compressSitemap`, `decompressSitemap`, `estimateCompressedSize`, `formatSize`, `generateCompressionHeaders`
+- Types: `CompressionHeaders`, `CompressionResult`, `SizeEstimate`
+
+### Errors
+
+- `SitemapError`, `SitemapErrorCode`, `SitemapErrorContext`, `SITEMAP_ERROR_METADATA`, `registerSitemapErrorCodes`
+- `emptyUrls`, `fetchFailed`, `invalidChangeFreq`, `invalidPriority`, `invalidUrl`, `parseFailed`, `tooLarge`
+
+## New genesis additions
+
+- Zod schemas for every URL / image / video shape.
+- OTel histograms `sitemap.generate.duration_ms`, `sitemap.parse.duration_ms`; counter `sitemap.urls.total`.
+- Property tests: build → compress → decompress → parse yields identical URL set.
+
+## Impact
+
+- Adds one new package: `universal/platform/sitemap`
+- Adds one new spec capability: `sitemap`

openspec/archive/2026-04-19-enterprise-sitemap/specs/sitemap/spec.md

@@ -0,0 +1,37 @@
+# Capability Spec: sitemap
+
+**Package**: `@suaveplan/sitemap`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### SM-01 — Sitemap XML compliance
+
+`SitemapGenerator.build(urls, options?)` MUST produce XML conforming to `https://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd`. A single sitemap MUST NOT exceed 50 000 URLs or 50 MiB uncompressed; exceeding either MUST throw `SITEMAP.TOO_LARGE` recommending sharding via `SitemapIndexGenerator`.
+
+### SM-02 — URL validation
+
+`SitemapUrl.loc` MUST be absolute and ≤ 2 048 bytes. `priority` MUST be in `[0.0, 1.0]`. `changefreq` MUST be a member of `VALID_CHANGE_FREQS`. Invalid values MUST surface as `SITEMAP.INVALID_PRIORITY` / `SITEMAP.INVALID_CHANGE_FREQ` / `SITEMAP.INVALID_URL`.
+
+### SM-03 — Image / video extensions
+
+`addImagesToUrl(url, images)` and `addVideosToUrl(url, videos)` MUST emit the corresponding `image:image` / `video:video` child elements under the `xmlns:image` / `xmlns:video` namespaces. Up to 1 000 images per URL (per spec) and 1 000 videos per URL MUST be permitted.
+
+### SM-04 — Sitemap index
+
+`SitemapIndexGenerator.build(subSitemaps)` MUST emit a `sitemapindex` document. Each `<sitemap>` MUST carry `loc` + optional `lastmod`.
+
+### SM-05 — Incremental rebuild
+
+`computeUrlHash(url)` MUST produce a stable fingerprint over the URL + metadata such that reordering of insignificant fields does not affect the hash. `IncrementalBuilder` MUST report `ChangeDetectionResult { added, removed, modified }` given prior and current URL sets.
+
+### SM-06 — Compression
+
+`compressSitemap(xml)` MUST return `{ bytes, size, ratio }` using gzip level 6 by default. `decompressSitemap(bytes)` MUST round-trip back to the original XML. `generateCompressionHeaders` MUST return `{ 'content-encoding': 'gzip', 'content-type': 'application/xml' }`.
+
+### SM-07 — Observability
+
+Every build / parse / compress MUST record the corresponding duration histogram and outcome counter.

openspec/archive/2026-04-19-enterprise-sitemap/tasks.md

@@ -0,0 +1,43 @@
+# Tasks: enterprise-sitemap
+
+## 1. Scaffold
+
+- [x] 1.1 `universal/platform/sitemap/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+
+- [x] 2.1 `src/error-codes.ts`, `src/errors/sitemap-errors.ts` + helper factories.
+- [x] 2.2 Zod schemas for `SitemapUrl`, `SitemapImage`, `SitemapVideo`, `SitemapNews`, `SitemapOptions`, `SitemapIndex`.
+
+## 3. Generator
+
+- [x] 3.1 `src/generator/sitemap-generator.ts` — `SitemapGenerator`.
+- [x] 3.2 50 k-URL size limit enforcement.
+
+## 4. Index generator
+
+- [x] 4.1 `src/index-generator/sitemap-index.ts`.
+
+## 5. Extensions
+
+- [x] 5.1 `src/extensions/image-sitemap.ts`.
+- [x] 5.2 `src/extensions/video-sitemap.ts`.
+- [x] 5.3 News extension.
+
+## 6. Incremental builder
+
+- [x] 6.1 `src/incremental/incremental-builder.ts` — `computeUrlHash`, `IncrementalBuilder`.
+
+## 7. Compression
+
+- [x] 7.1 `src/compression/sitemap-compressor.ts` — gzip via `fflate`.
+
+## 8. Docs / barrel / subpath exports / README
+
+## 9. Benchmarks
+
+- [x] 9.1 Generate 50 k URLs + gzip round-trip.
+
+## 10. Ship gate
+
+- [x] 10.1 Verification sequence; fold + archive.