zaileys 2.2.6 → 3.0.0

package/.gsd/docs/token-optimization-guide.md

@@ -0,0 +1,207 @@
+# Token Optimization Guide
+
+> Practical strategies for reducing token consumption while maintaining quality.
+
+---
+
+## Why Token Optimization Matters
+
+| Issue | Impact |
+|-------|--------|
+| Excessive file loading | Higher costs, slower responses |
+| Context accumulation | Quality degradation after 50% |
+| Re-reading files | Wasted tokens on understood content |
+| Full files when snippets suffice | 10x token usage |
+
+**Goal:** Maximize output quality per token spent.
+
+---
+
+## The Token Efficiency Stack
+
+```
+┌─────────────────────────────────────┐
+│ 1. Search-First (context-fetch)    │ ← Find before loading
+├─────────────────────────────────────┤
+│ 2. Budget Tracking (token-budget)  │ ← Know your limits
+├─────────────────────────────────────┤
+│ 3. Compression (context-compressor)│ ← Minimize footprint
+├─────────────────────────────────────┤
+│ 4. Health Monitoring               │ ← Prevent degradation
+└─────────────────────────────────────┘
+```
+
+---
+
+## Quick Reference: Token Costs
+
+### By Content Type
+
+| Type | Tokens/Line | 100 Lines = |
+|------|-------------|-------------|
+| Dense code | 6 | ~600 tokens |
+| Standard code | 4 | ~400 tokens |
+| Markdown | 3 | ~300 tokens |
+| Sparse YAML | 2 | ~200 tokens |
+
+### By File Size
+
+| File Lines | Strategy |
+|------------|----------|
+| <50 | Load freely |
+| 50-200 | Outline first |
+| 200-500 | Search + snippets |
+| 500+ | Never load fully |
+
+---
+
+## Optimization Patterns
+
+### Pattern 1: Search → Outline → Target
+
+```
+Step 1: Search for "handlePayment"
+  → Found in: payment.ts:45, checkout.ts:120
+
+Step 2: Get outline of payment.ts
+  → L45-80: handlePayment function
+
+Step 3: Load only L45-80
+  → 35 lines (~140 tokens) vs 400 lines (~1600 tokens)
+  → Saved: ~90%
+```
+
+### Pattern 2: Summarize After Understanding
+
+```
+After reading auth.ts:
+
+## Summary: auth.ts
+- Exports: login, logout, validateToken
+- Pattern: Express middleware
+- DB: queries users table
+- JWT: uses jose library
+
+Next time: Reference summary, don't reload
+```
+
+### Pattern 3: Progressive Disclosure
+
+```
+Need: Understand login flow
+
+Level 1: Outline
+  → "login at L45, uses validateCredentials at L67"
+  → Often sufficient
+
+Level 2: Key function
+  → Load L45-65 only
+  → Understand core logic
+
+Level 3: Dependencies
+  → Load validateCredentials (L67-85)
+  → Only if L2 insufficient
+
+Level 4: Full file
+  → Last resort, re-compress after
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ The "Context Dump"
+
+```
+BAD:
+"Let me read all the files in src/ to understand the project"
+→ 50 files × 200 lines × 4 tokens = 40,000 tokens
+
+GOOD:
+"Let me search for 'main entry' and 'router'"
+→ 2 targeted searches, ~500 tokens
+```
+
+### ❌ The "Just In Case" Load
+
+```
+BAD:
+"Loading utils.ts in case I need it later"
+→ Probably won't need it, wasted tokens
+
+GOOD:
+"Noting utils.ts exists, will load if needed"
+→ Zero tokens until actually needed
+```
+
+### ❌ The Re-Read
+
+```
+BAD:
+"Reading config.ts again to check the port"
+→ Already read it twice = 1200 tokens
+
+GOOD:
+"From my earlier analysis, port is on L15"
+→ Zero additional tokens
+```
+
+---
+
+## Budget Checkpoints
+
+### Before Starting Work
+
+```markdown
+□ Do I know my current budget usage?
+□ Have I tried searching before loading?
+□ Am I loading files I've already understood?
+```
+
+### During Execution
+
+```markdown
+□ Am I at >50%? Time to compress.
+□ Am I re-reading files? Use summaries.
+□ Can I use outline instead of full file?
+```
+
+### After Each Wave
+
+```markdown
+□ Have I compressed context for next wave?
+□ Are summaries documented in STATE.md?
+□ Would a fresh session be more efficient?
+```
+
+---
+
+## Integration with GSD
+
+| GSD Workflow | Token Optimization |
+|--------------|-------------------|
+| `/map` | Generate outline, not full read |
+| `/plan` | Budget estimate per task |
+| `/execute` | Load minimal per task |
+| `/verify` | Targeted evidence only |
+| `/pause` | Compress and dump state |
+
+---
+
+## Metrics
+
+Track these for improvement:
+
+| Metric | Good | Poor |
+|--------|------|------|
+| Files fully loaded | <3 per wave | 10+ |
+| Search:Load ratio | 3:1 | 1:3 |
+| Re-reads | 0 | 3+ |
+| Budget at wave end | <50% | >70% |
+
+---
+
+*See also:*
+- *[.agent/skills/token-budget/SKILL.md](.agent/skills/token-budget/SKILL.md)*
+- *[.agent/skills/context-compressor/SKILL.md](.agent/skills/context-compressor/SKILL.md)*
+- *[PROJECT_RULES.md](PROJECT_RULES.md) — Token Efficiency Rules*

package/.gsd/model_capabilities.yaml

@@ -0,0 +1,108 @@
+# Model Capabilities Registry
+#
+# This file is OPTIONAL. GSD works without it.
+# If present, it provides guidance for model selection.
+#
+# Usage: Reference this file when choosing models by capability.
+# Do NOT make any workflow depend on this file existing.
+
+# Capability definitions
+capabilities:
+  thinking_mode:
+    description: "Extended reasoning with internal monologue"
+    benefits:
+      - Better for complex planning
+      - Improved debugging hypotheses
+      - More thorough architecture analysis
+    
+  long_context:
+    description: "Context window > 100k tokens"
+    benefits:
+      - Can analyze multiple files at once
+      - Better for large refactors
+      - Full codebase reviews
+    
+  tools:
+    description: "Function/tool calling support"
+    benefits:
+      - Execute verification commands
+      - Interact with external systems
+      - Structured outputs
+    
+  speed_tier:
+    description: "Response latency tier"
+    values:
+      - fast: "< 2s average, good for iteration"
+      - standard: "2-5s average, balanced"
+      - reasoning: "> 5s average, deep analysis"
+
+# Example model profiles (illustrative, not exhaustive)
+# These show how to categorize models by capability type.
+
+profiles:
+  # Fast iteration models
+  fast_coder:
+    speed_tier: fast
+    thinking_mode: false
+    long_context: false
+    tools: true
+    best_for:
+      - Quick edits
+      - Simple implementations
+      - Frequent iteration cycles
+    examples:
+      - "Flash/Turbo variants"
+      - "Smaller parameter models"
+  
+  # Standard balanced models
+  standard:
+    speed_tier: standard
+    thinking_mode: false
+    long_context: true
+    tools: true
+    best_for:
+      - Most development tasks
+      - Moderate refactoring
+      - General coding
+    examples:
+      - "Pro/Standard variants"
+      - "Mid-tier models"
+  
+  # Deep reasoning models
+  reasoning:
+    speed_tier: reasoning
+    thinking_mode: true
+    long_context: true
+    tools: true
+    best_for:
+      - Architecture planning
+      - Complex debugging
+      - Security analysis
+    examples:
+      - "Thinking/Reasoning variants"
+      - "Advanced reasoning models"
+
+# Phase recommendations (suggestions, not requirements)
+phase_recommendations:
+  planning:
+    preferred_profile: reasoning
+    reason: "Complex decisions benefit from extended thinking"
+    
+  implementation:
+    preferred_profile: fast_coder
+    reason: "Frequent iteration needs speed"
+    
+  refactoring:
+    preferred_profile: standard
+    reason: "Balance of context and speed"
+    
+  debugging:
+    preferred_profile: reasoning
+    reason: "Hypothesis generation needs depth"
+    
+  review:
+    preferred_profile: standard
+    reason: "Large context for full diffs"
+
+# IMPORTANT: This file is for guidance only.
+# Never fail a workflow because a specific model capability is missing.

package/.gsd/phases/1/1-PLAN.md

@@ -0,0 +1,44 @@
+---
+phase: 1
+plan: 1
+wave: 1
+---
+
+# Plan 1.1: Database Configuration & Auth State
+
+## Objective
+Migrate fundamental DB configuration handling and authentication module to LMDB.
+
+## Context
+- src/Config/database.ts
+- src/Auth/state.ts
+
+## Tasks
+
+<task type="auto">
+  <name>Configure Native LMDB</name>
+  <files>src/Config/database.ts</files>
+  <action>
+    - Import `open` from `lmdb`.
+    - Change `CredsDatabase`, `KeysDatabase`, and `WaDatabase` to return native `lmdb` instances calling `open({ path: ..., compression: true/false })` natively.
+    - Remove JetDB-specific configurations like flushMode, hotThreshold that don't apply directly.
+  </action>
+  <verify>npm run build</verify>
+  <done>database.ts is updated to use solely lmdb.</done>
+</task>
+
+<task type="auto">
+  <name>Migrate Auth State to LMDB</name>
+  <files>src/Auth/state.ts</files>
+  <action>
+    - Update type handling for `credsDb` and `keysDb`.
+    - Replace `keysDb.batchSet(operations)` and `keysDb.batchDelete(deleteKeys)` with a single native LMDB `transaction(() => { ... })` combining `put` and `remove` calls.
+    - Remove `.flush()` if unnecessary (LMDB auto-syncs), or ignore as it's safe to drop.
+  </action>
+  <verify>npm run build</verify>
+  <done>Authentication state reads and writes natively using lmdb.</done>
+</task>
+
+## Success Criteria
+- [ ] database.ts returns LMDB instances.
+- [ ] state.ts successfully manipulates those instances directly.

package/.gsd/phases/1/2-PLAN.md

@@ -0,0 +1,54 @@
+---
+phase: 1
+plan: 2
+wave: 1
+---
+
+# Plan 1.2: Refactor Health, Client and Cleanup Logic
+
+## Objective
+Migrate secondary database consumers (Health Manager, Background Cleanup, Client API) to LMDB.
+
+## Context
+- src/Classes/client.ts
+- src/Library/health-manager.ts
+- src/Library/cleanup-manager.ts
+
+## Tasks
+
+<task type="auto">
+  <name>Update Client Database Return Type</name>
+  <files>src/Classes/client.ts</files>
+  <action>
+    - Update the return type of the `db(scope)` to `RootDatabase` from `lmdb` instead of `JetDB`.
+    - Drop `JetDB` import.
+  </action>
+  <verify>npx tsc --noEmit</verify>
+  <done>Client TS types reflect LMDB Database instance correctly.</done>
+</task>
+
+<task type="auto">
+  <name>Migrate Health Manager Session Repairs</name>
+  <files>src/Library/health-manager.ts</files>
+  <action>
+    - Replace JetDB `.batchDelete(keys)` with LMDB `transaction(() => ...)` deleting the keys via `.remove()`.
+    - Delete the `keysDb.flush()` call.
+  </action>
+  <verify>npx tsc --noEmit</verify>
+  <done>Health manager appropriately issues deletes using LMDB's API.</done>
+</task>
+
+<task type="auto">
+  <name>Migrate Cleanup Manager Queries</name>
+  <files>src/Library/cleanup-manager.ts</files>
+  <action>
+    - Convert complex `.query().where().get()` filter to a fast LMDB `.getRange()` filtering values or scanning keys that contain timestamps.
+    - Because LMDB items might have different schemas, ensure iteration only fetches values parsing their timestamps cleanly, or implement secondary indexes later if too slow.
+    - Alternatively, migrate to storing time-sorted keys if necessary. Keep it simple: loop through keys and check JSON value timestamp.
+  </action>
+  <verify>npx tsc --noEmit</verify>
+  <done>Cleanup manager safely scans and bulk deletes old elements using LMDB directly.</done>
+</task>
+
+## Success Criteria
+- [ ] Classes correctly access LMDB native methods.

package/.gsd/phases/1/3-PLAN.md

@@ -0,0 +1,46 @@
+---
+phase: 1
+plan: 3
+wave: 2
+---
+
+# Plan 1.3: Refactor Listener Messages & Socket
+
+## Objective
+Migrate complex message parsing queries from JetDB's API structure to LMDB.
+
+## Context
+- src/Listener/messages.ts
+- src/Listener/index.ts
+- src/Config/socket.ts
+
+## Tasks
+
+<task type="auto">
+  <name>Migrate Message Upserts & Indexes</name>
+  <files>src/Listener/index.ts</files>
+  <action>
+    - Instead of `db.batchUpsert('messages', messages, 'key.id')`, use an LMDB transaction to iterate over models and `.put(item.key.id, item)`.
+    - Drop `.createIndex()` as LMDB doesn't natively use that wrapper technique. We can rely on primary key lookups if `key.id` is the main PK.
+  </action>
+  <verify>npx tsc --noEmit</verify>
+  <done>Listener correctly transaction-saves batch array payloads into LMDB.</done>
+</task>
+
+<task type="auto">
+  <name>Rewrite Message Retrieve Queries</name>
+  <files>
+    src/Listener/messages.ts
+    src/Config/socket.ts
+  </files>
+  <action>
+    - Replace JetDB `.getByIndex('messages', 'key.id', key.id)` and `.query(output.roomId).where('key.id', '=', universalId).first()` with simple native DB operations like `.get(key.id)` since we will model the DB to be keyed by `key.id`.
+    - Update schema logic: `put(item.key.id, item)` natively provides instant `.get(item.key.id)` without index lookups.
+  </action>
+  <verify>npx tsc --noEmit</verify>
+  <done>Message handlers directly retrieve and decode items from LMDB database nodes using direct `.get()` operations.</done>
+</task>
+
+## Success Criteria
+- [ ] No `.query(...)` calls remain in the Listeners codebase.
+- [ ] Batch transactions successfully execute insertions.

package/.gsd/phases/1/4-PLAN.md

@@ -0,0 +1,39 @@
+---
+phase: 1
+plan: 4
+wave: 3
+---
+
+# Plan 1.4: Dependencies & Final Build Verification
+
+## Objective
+Finalize the dependency manifest and perform a complete TypeScript build to catch any lingering `jetdb` interfaces.
+
+## Context
+- package.json
+
+## Tasks
+
+<task type="auto">
+  <name>Update Package Dependencies</name>
+  <files>package.json</files>
+  <action>
+    - Drop `jetdb` completely from `dependencies`/`devDependencies`.
+    - Ensure `lmdb` is present in dependencies.
+  </action>
+  <verify>npm list jetdb --depth=0 || true</verify>
+  <done>package.json correctly declares lmdb.</done>
+</task>
+
+<task type="auto">
+  <name>Verify Production Build</name>
+  <files>src/*</files>
+  <action>
+    - Run `pnpm run build` or `npm run build` to verify standard TSC emissions succeed without syntax or structural property errors concerning missing jetdb functionality across the workspace.
+  </action>
+  <verify>npm run build</verify>
+  <done>Build finishes successfully with exit code 0.</done>
+</task>
+
+## Success Criteria
+- [ ] Build verifies entirely.

package/.gsd/phases/2/2-1-SUMMARY.md

@@ -0,0 +1,8 @@
+# Plan 2.1 Summary
+
+## What was done
+- **Refactor Object Helpers**: Eliminated the bulky custom 15-line nested path retrieval algorithm in `src/Utils/helper.ts` -> `pickKeysFromArray`. Simplified the empty check parameters logic utilizing `radashi.get` and `radashi.isEmpty`.
+- **Refactor Chunking Integrations**: Safely migrated the `500` index slicing array mechanism spanning across Database operations in both `src/Library/cleanup-manager.ts` and `src/Auth/state.ts`. Utilized the concise `radashi.cluster(array, size)` iterator.
+
+## Verification
+- `pnpm tsc --noEmit` returned exactly `0` errors, proving the native drop-in typings provided by `.cluster` match natively with the codebase iteration loops.

package/.gsd/phases/2/2-PLAN.md

@@ -0,0 +1,47 @@
+---
+phase: 2
+plan: 1
+wave: 1
+---
+
+# Plan 2.1: Native to Radashi Optimization
+
+## Objective
+Convert bloated, boilerplate native javascript abstractions (such as nested object retrieval and array chunking) to clean, elegant Radashi utility methods `radashi.get`, `radashi.isEmpty`, and `radashi.cluster`. This shrinks the codebase, reduces cognitive load, and leverages reliable community-tested utility patterns without adding extra dependencies.
+
+## Context
+- .gsd/ROADMAP.md
+- src/Utils/helper.ts
+- src/Library/cleanup-manager.ts
+- src/Auth/state.ts
+
+## Tasks
+
+<task type="auto">
+  <name>Refactor Object Helpers</name>
+  <files>src/Utils/helper.ts</files>
+  <action>
+    - Refactor `pickKeysFromArray`. Radashi's `get(obj, path)` can completely replace the 15+ lines of the `getNested` custom path parser algorithm.
+    - Rewrite custom `isEmpty` function. We can use `radashi.isEmpty()` alongside a `.trim()` check to maintain space-only string detection.
+    - Replace `findNestedByKeys` iterations with pure functional Radashi implementations.
+  </action>
+  <verify>pnpm tsc --noEmit</verify>
+  <done>Boilerplate manual loops inside `helper.ts` are eliminated, leveraging minimal lines with Radashi object traversals.</done>
+</task>
+
+<task type="auto">
+  <name>Refactor Chunking Integrations</name>
+  <files>src/Library/cleanup-manager.ts, src/Auth/state.ts</files>
+  <action>
+    - Both `cleanup-manager.ts` and `state.ts` contain manual 500-size array slicing chunk mechanisms.
+    - Replace `for (let i = 0; i < operations.length; i += chunkSize) { const chunk = operations.slice(...) }` with an elegant iteration over `radashi.cluster`(array, size).
+    - Ensure asynchronous arrays `Promise.all()` operate smoothly on the returned sub-matrices.
+  </action>
+  <verify>pnpm tsc --noEmit</verify>
+  <done>Array partitioning is successfully replaced with `radashi.cluster` leading to less cognitive complexity.</done>
+</task>
+
+## Success Criteria
+- [ ] Nested path abstractions (`obj[arrayKey][index]`) are successfully abstracted via `radashi.get`
+- [ ] Array chunking `slice` boilerplate loops are replaced natively with `radashi.cluster(arr, 500)`
+- [ ] TypeScript validations complete with exactly `0` errors.

package/.gsd/phases/3/3-1-SUMMARY.md

@@ -0,0 +1,8 @@
+# Plan 3.1 Summary
+
+## What was done
+- **Refactor Text Normalizer**: Dropped the heavy `unorm` module from `src/Utils/validate.ts`. Replaced `unorm.nfkd(char)` and `unorm.nfkc(char)` looping mechanics entirely with modern, faster V8 operations `.normalize('NFKD')` and `.normalize('NFKC')`.
+- **Clear Dependencies**: Removed the `unorm` entry from `package.json` utilizing `pnpm remove unorm`.
+
+## Verification
+- `pnpm tsc --noEmit && pnpm build` finished flawlessly, signifying the JavaScript Unicode implementation operates as intended across transpiled CommonJS and ESM scopes.

package/.gsd/phases/3/3-PLAN.md

@@ -0,0 +1,43 @@
+---
+phase: 3
+plan: 1
+wave: 1
+---
+
+# Plan 3.1: Native Unicode V8 Normalization
+
+## Objective
+Remove the `unorm` library from `package.json` entirely. Utilize native Javascript `String.prototype.normalize()` which natively supports `NFKD` and `NFKC` parsing without external dependency injections, optimizing overall application bundle size and memory usage.
+
+## Context
+- `src/Utils/validate.ts`
+- `package.json`
+
+## Tasks
+
+<task type="auto">
+  <name>Refactor Text Normalizer</name>
+  <files>src/Utils/validate.ts</files>
+  <action>
+    - Remove the `unorm` import block.
+    - Rewrite `.map((char) => unorm.nfkd(char))` into native Javascript: `.map((char) => char.normalize('NFKD'))`
+    - Rewrite `.map((char) => unorm.nfkc(char))` into native Javascript: `.map((char) => char.normalize('NFKC'))`
+  </action>
+  <verify>pnpm tsc --noEmit</verify>
+  <done>Text normalization succeeds using purely standard internal string iterations without `unorm` fallback.</done>
+</task>
+
+<task type="auto">
+  <name>Clear Dependencies</name>
+  <files>package.json</files>
+  <action>
+    - Remove `"unorm": "^1.6.0"` from `"dependencies"`.
+    - Run an installation cleanup.
+  </action>
+  <verify>bun pm ls</verify>
+  <done>Package directory explicitly flags `unorm` as non-existent.</done>
+</task>
+
+## Success Criteria
+- [ ] Codebase compiles natively via `tsc` with `0` errors.
+- [ ] No footprint of `unorm` exists in `package.json`.

package/.gsd/phases/4/4-1-PLAN.md

@@ -0,0 +1,44 @@
+---
+phase: 4
+plan: 1
+wave: 1
+---
+
+# Plan 4.1: Setup Valibot and Wrapper Migration
+
+## Objective
+Uninstall `zod` and `zod-validation-error`. Install completely modular `valibot` dependency. Replace the library validation wrapper with `valibot` semantics (`v.safeParse` and `v.summarize`/`v.flatten`).
+
+## Context
+- `package.json`
+- `src/Library/zod.ts` (This file should be renamed to `src/Library/valibot.ts`!)
+
+## Tasks
+
+<task type="auto">
+  <name>Dependency Swap</name>
+  <files>package.json</files>
+  <action>
+    - Execute `pnpm remove zod zod-validation-error`.
+    - Execute `pnpm add valibot`.
+  </action>
+  <verify>bun pm ls</verify>
+  <done>package.json explicitly lists `valibot` and omits entirely `zod` and `zod-validation-error`.</done>
+</task>
+
+<task type="auto">
+  <name>Implement Valibot Wrapper</name>
+  <files>src/Library/zod.ts</files>
+  <action>
+    - Rename the file gracefully from `src/Library/zod.ts` to `src/Library/valibot.ts`.
+    - Drop `zod` and `fromError` imports. Import `* as v from 'valibot'`.
+    - Create an export `parseValibot = <T extends v.BaseSchema<any, any, any>>(schema: T, data: unknown)` that executes `v.safeParse`.
+    - If `result.issues` exist, extract and throw an Error via `v.summarize(result.issues)` or by joining `v.flatten()`.
+  </action>
+  <verify>test -f src/Library/valibot.ts && ! test -f src/Library/zod.ts</verify>
+  <done>Wrapper has successfully transitioned to `valibot` with functional Error reporting.</done>
+</task>
+
+## Success Criteria
+- [ ] Dependencies swapped cleanly.
+- [ ] `valibot.ts` gracefully replaces `zod.ts`.

package/.gsd/phases/4/4-1-SUMMARY.md

@@ -0,0 +1,8 @@
+# Plan 4.1 Summary
+
+## What was done
+- **Dependency Swap**: Ran `pnpm remove zod zod-validation-error` and `pnpm add valibot`.
+- **Implement Wrapper**: Replaced `src/Library/zod.ts` with `src/Library/valibot.ts`. Implemented a `parseValibot()` higher-order validation wrapper throwing formatted stringified `v.flatten()` errors securely. 
+
+## Verification
+- Dependencies matched specifications and `parseValibot` wraps inputs correctly.