STANDARD - TypeScript/Bun Package Development Standards

Purpose

Central repository defining development standards, templates, and automation tools for TypeScript/Bun packages across 40+ repositories.

Directory Structure

/assets/

Purpose: Media files only (images, videos, screenshots, recordings)

• For documentation illustrations
• Architecture diagrams
• Tutorial screenshots
• Currently empty - ready for media assets

/bin/

Purpose: Executable wrapper scripts (thin wrappers calling scripts/)

• harden-qat-hooks - Wrapper for QAT hook hardening
• qat-history-healer - Wrapper for legacy commit recovery
• resume-setup - Wrapper for setup resumption
• setup-quality-attestation - Wrapper for QAT installation
• setup-repository - Wrapper for repository initialization
• validate-repo-structure - Wrapper for structure validation

Pattern: Each wrapper is an executable bash script (no extension) that calls the corresponding implementation in scripts/

/scripts/

Purpose: Script implementations (NOT directly executable)

• harden-qat-hooks.sh - QAT hook hardening implementation
• qat-history-healer.sh - Legacy commit recovery implementation
• repo-structure-validator.ts - TypeScript validator implementation
• resume-setup.sh - Setup resumption implementation
• setup-quality-attestation.sh - QAT installation implementation
• setup-repository.sh - Repository initialization implementation

Pattern: Implementations are called by bin/ wrappers, allowing swap without breaking references

/boilerplate/

Purpose: Template files for new repositories

• package.json - Package manifest template
• tsconfig.json - TypeScript configuration template
• biome.json - Linting/formatting configuration template
• .gitignore - Git ignore rules template
• README.md - Documentation template
• setup-quality-attestation.sh - QAT setup script (copied into new repos)
• Complete directory structure (bin/, docs/, json/, logs/, out/, src/, scripts/)

Exception: Standard filenames (package.json, etc.) preserved for compatibility

/guides/

Purpose: Comprehensive documentation for the STANDARD

Primary Reference:

• STANDARD-BUN-PACKAGE.md - THE CANONICAL STANDARD (single source of truth)

Supporting Guides:

• AUTOMATION-USAGE.md - Automation and tooling guide
• BUN-PACKAGE-REVIEWER-PROMPT.md - Code review guidelines
• CI-CD-SECURITY-REQUIREMENTS.md - CI/CD security requirements
• GITHUB-ACTIONS-SETUP-GUIDE.md - GitHub Actions setup
• GITHUB-ACTIONS-SETUP-GUIDE-STANDARD.md - Standard GitHub Actions setup
• HARDEN-QAT-HOOKS.md - QAT hook hardening documentation
• IMAGE-ANALYSIS-REQUIREMENTS.md - Image analysis package requirements
• OPTIMIZATION-SUMMARY.md - Optimization guidelines
• QAT-AUTOPUSH-MIGRATION.md - QAT autopush migration guide
• QAT-HARDENING-RUNBOOK.md - Complete QAT hardening procedures
• QAT-HISTORY-HEALER.md - Legacy commit recovery documentation
• QAT-MERGE-CHECK-AUTO-PUSH.md - Merge check and auto-push guide
• SLASH-COMMAND-REVIEW.md - Slash command review workflow
• SONARCLOUD-INTEGRATION.md - SonarCloud integration guide
• TYPESCRIPT-BUN-STANDARDS.md - TypeScript/Bun standards overview
• validation-integration.md - Validation integration guide

/workflows/

Purpose: GitHub Actions workflow templates

Primary Workflow:

• qat.yml - Quality Attestation Token verification (THE STANDARD WORKFLOW)

Additional Workflows:

• claude-code-review.yml - Claude Code review automation
• claude-interactive-ci.yml - Claude interactive CI workflow

Examples:

• examples/ subdirectory containing example workflow configurations

/global/

Purpose: Shared configuration files used across all repositories

• biome.json - Shared Biome configuration (canonical linting/formatting)
• tsconfig.base.json - Base TypeScript configuration
• tsconfig.reference.json - TypeScript project references

/example/

Purpose: Reference implementation demonstrating the STANDARD in practice

• Complete working example of a compliant TypeScript/Bun package
• Shows correct directory structure, naming conventions, and patterns
• README.md contains detailed explanations of all patterns

Usage

Setup New Repository

/Users/matkoson/STANDARD/bin/setup-repository <repo-name>

Apply QAT System

bash /Users/matkoson/STANDARD/bin/setup-quality-attestation

Harden QAT Hooks (requires sudo)

sudo /Users/matkoson/STANDARD/bin/harden-qat-hooks /absolute/path/to/repository

Validate Repository Structure

/Users/matkoson/STANDARD/bin/validate-repo-structure /absolute/path/to/repository

Heal Legacy Commits

/Users/matkoson/STANDARD/bin/qat-history-healer

Naming Conventions

This repository follows kebab-case naming conventions:

• Directories: kebab-case (e.g., bin/, scripts/, guides/)
• Files: kebab-case (e.g., ensure-compliance, setup-repository.sh, pre-commit-logic.ts)
• Exceptions: Conventional names preserved where appropriate (e.g., README.md, .gitignore, package.json)

Script Organization Pattern

The Rule

Separate implementation from execution interface:

bin/command (executable wrapper)
    ↓ calls
scripts/command.sh (implementation)

Benefits

• Can swap implementations without breaking references to bin/
• Decouples interface from implementation details
• Standardized pattern across all scripts
• Single entry point for users (bin/ directory)

Example

# User calls:
/Users/matkoson/STANDARD/bin/harden-qat-hooks /path/to/repo

# Wrapper internally calls:
bash /Users/matkoson/STANDARD/scripts/harden-qat-hooks.sh /path/to/repo

The Canonical Standard

See guides/standard-bun-package.md for complete specification.

This is the single source of truth referenced by 40+ repositories.

Key Features

Quality Attestation Token (QAT) System

• Enforces quality standards locally before commits
• Cryptographic proof of quality checks
• Eliminates expensive CI/CD validation
• 95% reduction in GitHub Actions costs

Configuration-Driven Development

• All business logic driven by JSON configs in json/ directory
• Enables runtime behavior changes without code changes

Dual Output Pattern

• Console output for immediate feedback
• Persistent file output in out/ directory
• All executable code follows this pattern

100% Test Coverage

• Mandatory for all library repositories
• Enforced locally before commits allowed
• No exceptions permitted

Repository Standards

All 40+ repositories follow these standards:

• TypeScript exclusively
• Bun runtime exclusively
• Biome for linting/formatting
• kebab-case naming for all files and directories
• SCREAMING-PASCAL-CASE for JSON configs
• QAT system for quality enforcement

Migration Notes

This repository was recently reorganized:

• 2025-10-28: Eliminated BUN-TS-PACKAGE and __GUIDE duplication, separated script implementations from wrappers
• 2025-11-15: Migrated to standard naming conventions (kebab-case directories, snake_case files)

All path references updated to reflect new structure.