adopt typebox #78

New Issue

The goal is better hand-written YAML configuration, not a mechanical schema-library port. A # yaml-language-server: $schema=... header must provide useful diagnostics, completion and descriptions in Neovim.

Remove AJV completely from @luzzle/web.config; retain it in core for user-authored piece JSON Schemas.
Replace json2ts with TypeBox inference and use TypeBox runtime defaulting/validation (When uses Value.Default and Value.Errors). The earlier proposal to retain AJV as a migration bridge is superseded.
Review complex existing rules and simplify them where helpful. Existing behavior is a reference, not a requirement to preserve every awkward rule. Agree concrete YAML/rule changes before implementing them.
Generate editor JSON Schema from the same authored definitions. Prefer one useful editor artifact, not a second strict JSON artifact retained solely for the old AJV pipeline. Audit existing schema-header paths before any filename change.
Express constraints in the generated schema wherever practical, rather than moving them into runtime-only callbacks and losing editor warnings. Environment resolution and genuinely semantic rules still need runtime checks; editor validation cannot prove deployment secrets exist.

Implementation outline

Review YAML design: current versus proposed minimal/full examples for auth, AI, defaults/optional sections, unknown keys and environment references. Explain editor behavior and migration cost for each simplification.
Prove editor behavior: validate partial/invalid/valid examples through the actual YAML language server, including header resolution, defaults, required fields and branch diagnostics. The repository already uses yaml-language-server in @luzzle/lsp; no browser framework or Neovim configuration changes are needed.
Implement the coherent migration: TypeBox source + inferred types + runtime validation + generated editor schema; update affected consumers and remove config's AJV/json2ts machinery. No permanent legacy-validator bridge.
Verify and document: generated-artifact freshness checks, executable examples, runtime tests for resolved values/defaults/variants, approved non-build repository gates, and owner review of the Neovim authoring experience. Document intentional configuration changes explicitly.

Coordinate necessary loader/diagnostic work with #104 instead of duplicating it or preserving an awkward loader solely to maintain an artificial ticket boundary. Workflow/publish/logging tickets #99–#103 remain separate.

No root/web/theme/content builds, live CSS regeneration, dependency installation, or production implementation occurred during this planning work. Rule/shape proposals are the next review step.

## Agreed direction after the When review The goal is **better hand-written YAML configuration**, not a mechanical schema-library port. A `# yaml-language-server: $schema=...` header must provide useful diagnostics, completion and descriptions in Neovim. - Remove AJV completely from `@luzzle/web.config`; retain it in core for user-authored piece JSON Schemas. - Replace `json2ts` with TypeBox inference and use TypeBox runtime defaulting/validation (When uses `Value.Default` and `Value.Errors`). The earlier proposal to retain AJV as a migration bridge is superseded. - Review complex existing rules and simplify them where helpful. Existing behavior is a reference, not a requirement to preserve every awkward rule. Agree concrete YAML/rule changes before implementing them. - Generate editor JSON Schema from the same authored definitions. Prefer one useful editor artifact, not a second strict JSON artifact retained solely for the old AJV pipeline. Audit existing schema-header paths before any filename change. - Express constraints in the generated schema wherever practical, rather than moving them into runtime-only callbacks and losing editor warnings. Environment resolution and genuinely semantic rules still need runtime checks; editor validation cannot prove deployment secrets exist. ## Implementation outline 1. **Review YAML design:** current versus proposed minimal/full examples for auth, AI, defaults/optional sections, unknown keys and environment references. Explain editor behavior and migration cost for each simplification. 2. **Prove editor behavior:** validate partial/invalid/valid examples through the actual YAML language server, including header resolution, defaults, required fields and branch diagnostics. The repository already uses `yaml-language-server` in `@luzzle/lsp`; no browser framework or Neovim configuration changes are needed. 3. **Implement the coherent migration:** TypeBox source + inferred types + runtime validation + generated editor schema; update affected consumers and remove config's AJV/json2ts machinery. No permanent legacy-validator bridge. 4. **Verify and document:** generated-artifact freshness checks, executable examples, runtime tests for resolved values/defaults/variants, approved non-build repository gates, and owner review of the Neovim authoring experience. Document intentional configuration changes explicitly. Coordinate necessary loader/diagnostic work with #104 instead of duplicating it or preserving an awkward loader solely to maintain an artificial ticket boundary. Workflow/publish/logging tickets #99–#103 remain separate. No root/web/theme/content builds, live CSS regeneration, dependency installation, or production implementation occurred during this planning work. Rule/shape proposals are the next review step.

eleith referenced this issue from a commit

2026-10-05 21:12:50 +00:00

[config,web] adopt TypeBox configuration contracts

eleith referenced this issue from a commit

2026-10-05 21:12:50 +00:00

[docs] document TypeBox web configuration

eleith referenced a pull request that will close this issue

2026-10-05 21:14:24 +00:00

Adopt TypeBox for web configuration #107

eleith closed this issue

2026-10-05 21:18:24 +00:00

Sign in to join this conversation.