Initial Commit

openspec/archive/2026-04-20-enterprise-utils/proposal.md

@@ -0,0 +1,30 @@
+# Proposal: @suaveplan/utils — Universal Utility Library
+
+## Change ID
+`enterprise-utils`
+
+## Status
+Shipped
+
+## Summary
+Introduce `@suaveplan/utils` as a comprehensive universal utility library under `universal/data/utils`. This package provides commonly needed utilities: debug logging with deduplication, object manipulation (deep merge, clone, pick/omit, nested path access), platform detection (Node/Browser/Bun), float encoding utilities (Float16/32/64 pack/unpack), and pseudo-random array selection.
+
+## Motivation
+Shared utility functions currently duplicated across packages. Centralizing them in a single well-tested package reduces redundancy, increases reuse, and ensures consistent error handling with OTel instrumentation.
+
+## Scope (Part 1)
+- `debug`: Circular-buffer deduplication logger
+- `object`: 15 object manipulation utilities with OTel spans
+- `platform`: Injectable platform adapter with Node/Browser/Bun detection
+- `number`: Float16/32/64 pack/unpack with DataView
+- `random`: Deterministic pseudo-random array selection
+
+## Part 2 (follow-on)
+- `email`, `sound`, `string`, `validate`, `validation` modules
+
+## Dependencies
+- `@suaveplan/error` — error substrate
+- `@suaveplan/types` — shared type interfaces
+- `@opentelemetry/api` — observability
+- `zod` — schema validation
+- `tslib` — TypeScript helpers

openspec/archive/2026-04-20-enterprise-utils/tasks.md

@@ -0,0 +1,65 @@
+# Tasks: @suaveplan/utils Part 1
+
+## Task 4.1: OpenSpec + scaffold ✅
+- [x] Create openspec/changes/enterprise-utils/proposal.md
+- [x] Create openspec/changes/enterprise-utils/tasks.md
+- [x] Scaffold package directories and config files
+- [x] `bun install`
+- [x] Commit: `chore(utils): scaffold package`
+
+## Task 4.2: Error class ✅
+- [x] `src/errors/utils-error.ts` — UTILS_CODES + UtilsError
+- [x] `src/errors/index.ts`
+- [x] `src/types/types.ts`
+- [x] `src/types/index.ts`
+- [x] `src/index.ts`
+- [x] Commit: `feat(utils): add error class`
+
+## Task 4.3: debug module ✅
+- [x] TDD: write tests → fail → implement → pass
+- [x] `src/debug/debug.ts`
+- [x] `src/debug/debug.test.ts`
+- [x] `src/debug/debug.md`
+- [x] `src/debug/index.ts`
+- [x] Commit: `feat(utils): add debug module`
+
+## Task 4.4: object module ✅
+- [x] TDD
+- [x] `src/object/object.ts`
+- [x] `src/object/object.test.ts`
+- [x] `src/object/object.schemas.ts`
+- [x] `src/object/object.md`
+- [x] `src/object/index.ts`
+- [x] Commit: `feat(utils): add object module`
+
+## Task 4.5: platform module ✅
+- [x] TDD
+- [x] `src/platform/platform.ts`
+- [x] `src/platform/platform.test.ts`
+- [x] `src/platform/platform.schemas.ts`
+- [x] `src/platform/platform.md`
+- [x] `src/platform/index.ts`
+- [x] Commit: `feat(utils): add platform module`
+
+## Task 4.6: number module ✅
+- [x] TDD
+- [x] `src/number/number.ts`
+- [x] `src/number/number.test.ts`
+- [x] `src/number/number.schemas.ts`
+- [x] `src/number/number.md`
+- [x] `src/number/index.ts`
+- [x] Commit: `feat(utils): add number (float encoding) module`
+
+## Task 4.7: random module ✅
+- [x] TDD
+- [x] `src/random/pseudo.ts`
+- [x] `src/random/pseudo.test.ts`
+- [x] `src/random/pseudo.schemas.ts`
+- [x] `src/random/pseudo.md`
+- [x] `src/random/index.ts`
+- [x] Commit: `feat(utils): add random/pseudo module`
+
+## Final: Verification ✅
+- [x] `bunx turbo test --filter=@suaveplan/utils`
+- [x] `bunx turbo test:coverage --filter=@suaveplan/utils`
+- [x] Commit: `feat(utils): complete part 1`