fuz-stack #

Overview
#

Coding conventions and patterns for the @fuzdev TypeScript and Svelte 5 ecosystem. These conventions keep agent-assisted development consistent across ~20 repos — from naming and file organization to error handling, testing, and validation patterns.

This content is AI-generated and mostly poorly reviewed. Not all patterns described here are endorsed, and some may be out of date or incorrect.

The full skill documentation is at skills/fuz-stack.

Conventions
#

Area	Convention
Naming	snake_case functions/variables, PascalCase types/components, SCREAMING_SNAKE_CASE constants
File organization	`src/lib/` for library code, `src/test/` for tests (not co-located), `src/routes/` for SvelteKit
Imports	Always include `.js` extension, import directly from source module (no re-exports)
Formatting	Prettier with tabs, 100 char width
Breaking changes	Acceptable — delete unused code, don't shim or alias
Flat namespace	All exported identifiers unique across all modules; `gro gen` enforces
Build	`gro check` runs typecheck + test + gen --check + format --check + lint

// snake_case functions — domain-prefix when bare name would be ambiguous
function git_push() {}  // git_* cluster, "push" alone is ambiguous
function truncate() {}  // action-first, self-descriptive

// PascalCase types and components
type PackageJson = {};
// file: DocsLink.svelte

// .js extension in imports, even for .ts files
import {git_push} from './git.js';

Core patterns
#

Beyond surface conventions, several deeper patterns define how @fuzdev code is structured:

Pattern	Convention
Error handling	`Result<TValue, TError>` discriminated union — never throw for expected errors
Dependency injection	Small `*Deps` interfaces for all I/O, plain object mocks — no mocking libraries
Validation	`z.strictObject()` by default, PascalCase schema naming, `.brand()` for nominal types
Testing	Fixture-based testing for parsers — input files, generated `expected.json`, never manually edit

// Result pattern — properties directly on the result object
function parse_config(text: string): Result<{value: Config}, {error: ParseError}> {
	return {ok: true, value: JSON.parse(text)};
}

// Deps pattern — small interfaces, no god types
export interface FsDeps {
	read_file: (path: string) => Promise<string>;
	write_file: (path: string, content: string) => Promise<void>;
}

References
#

14 detailed reference documents:

Reference	Covers
Async Patterns	Concurrency primitives — semaphore, deferred, concurrent map/each
Code Generation	Gro gen system — .gen.* files, dependencies, output formats
Common Utilities	Result type, Logger, Timings, DAG execution
CSS Patterns	fuz_css styling — variables, utility classes, modifiers, extraction
Dependency Injection	Injectable *Deps interfaces, mock factories, composition patterns
Documentation System	Docs pipeline — Tome system, layout architecture, project setup
Rust Conventions for the Fuz Ecosystem	Shared Rust patterns — edition 2024, unsafe forbid, lints, crate structure
Svelte 5 Patterns	Svelte 5 runes, contexts, snippets, attachments, Cell pattern
Task Patterns	Gro task system — .task.ts files, TaskContext, error handling
Testing Patterns	Vitest patterns, fixtures, mocks, assertion helpers
TSDoc Comment Style Guide	TSDoc style guide — tags, conventions, auditing
Type Utilities	Nominal typing (Flavored/Branded), strict utility types
WASM Patterns for the Fuz Ecosystem	WASM build targets — wasm-bindgen, component model, JS interop
Zod Schemas	Zod conventions — strictObject, branded types, introspection

Stack
#

fuz_util → gro + fuz_css → fuz_ui → fuz_* apps

gro is a temporary build tool, to be replaced by fuz (Rust daemon + CLI). See stack for the full dependency graph and package details.

For cross-repo coordination patterns — planning, TODOs, and multi-repo goals — see grimoire.