🚀 AgentStatic - AI-Native Static Site Generator

Modern TypeScript-First Static Site Generator with AI-Powered Extensibility
Build blazing-fast static sites with reusable TypeScript partials, Zod validation, and MCP integration

🎉 Major Milestone: Partial Registry System Complete!

Issue #7 (Partial Registry & Discovery System) has been COMPLETED with comprehensive TDD implementation featuring:

• ✅ 29 unit tests covering all functionality (100% pass rate)
• ✅ Automatic filesystem discovery of .partial.ts files
• ✅ Zod schema validation for type-safe props
• ✅ Dependency resolution with circular dependency detection
• ✅ Hot reload support for development workflow
• ✅ Performance optimization with validation caching
• ✅ Event-driven architecture for extensibility

✨ What This Means for You

Today You Can:

1. Use as GitHub Template - Create production-ready static sites in < 5 minutes
2. Build TypeScript Partials - Create reusable components with full type safety
3. Leverage Zod Validation - Runtime validation for all partial props
4. Enjoy Hot Reload - See changes instantly during development
5. Scale with Confidence - Production-ready architecture with comprehensive testing

Coming Soon:

• Markdown processing pipeline (Issue #11)
• Interactive CLI framework (Issue #15)
• Development server with live preview (Issue #16)
• MCP plugin architecture for AI-powered features

🏗️ Architecture Overview

AgentStatic is built on a solid foundation of modern TypeScript practices:

// Example: Creating a TypeScript partial with Zod validation
import { z } from 'zod';
import type { AgentPartial } from '@/types/partial';

export const heroPartial: AgentPartial<{
  title: string;
  subtitle?: string;
  ctaText: string;
  ctaUrl: string;
}> = {
  schema: z.object({
    title: z.string(),
    subtitle: z.string().optional(),
    ctaText: z.string(),
    ctaUrl: z.string().url(),
  }),
  template: (props, helpers) => `
    <section class="hero">
      <h1>${props.title}</h1>
      ${props.subtitle ? `<p class="subtitle">${props.subtitle}</p>` : ''}
      <a href="${props.ctaUrl}" class="cta">${props.ctaText}</a>
    </section>
  `,
  styles: `
    .hero { padding: 4rem 2rem; text-align: center; }
    .hero h1 { font-size: 3rem; margin-bottom: 1rem; }
    .subtitle { font-size: 1.5rem; color: #666; }
    .cta { display: inline-block; padding: 1rem 2rem; background: #007bff; color: white; text-decoration: none; border-radius: 4px; }
  `,
  metadata: {
    description: 'Hero section with title, subtitle, and CTA',
    category: 'layout',
    keywords: ['hero', 'header', 'cta', 'landing'],
    usageExamples: ['Landing pages', 'Marketing sites'],
  },
};

🎯 Development Status

✅ Completed Features

Feature	Status	Details
GitHub Template Repository	✅ Production Ready	One-click setup with automatic configuration
TypeScript Configuration	✅ Complete	Strict mode, ES modules, Node.js 24 support
Testing Foundation	✅ Complete	Vitest with 48 passing tests
Partial Registry System	✅ NEW!	Issue #7 complete with TDD implementation
Zod Integration	✅ Complete	Runtime validation for all partials
Hot Reload Foundation	✅ Complete	File watching with Chokidar
Event System	✅ Complete	EventEmitter for extensibility

🚧 In Active Development

Feature	Status	Issue	Target
Markdown Processing	🚧 In Progress	#11	Unified-based pipeline with frontmatter
Interactive CLI	🚧 In Progress	#15	Command-line interface for site management
Development Server	🚧 In Progress	#16	Live preview with hot reload
Content Discovery	📋 Planned	#14	Automatic content indexing

📋 Roadmap

Phase 1: Foundation (✅ COMPLETE)

• ✅ TypeScript setup with strict mode
• ✅ Testing infrastructure
• ✅ Partial registry system
• ✅ GitHub template functionality

Phase 2: Core Engine (🚧 CURRENT)

• 🚧 Markdown processing (#11)
• 🚧 Content discovery (#14)
• 🚧 CLI framework (#15)
• 🚧 Development server (#16)

Phase 3: Production Features

• 📋 Build pipeline (#23)
• 📋 Asset optimization (#24)
• 📋 Deployment automation (#25)

Phase 4: AI Integration

• 📋 MCP server foundation (#20)
• 📋 AI layout composition (#21)
• 📋 Natural language generation (#22)

🚀 Quick Start

As a GitHub Template

1. 📋 Use This Template - Create your repository
2. Enable GitHub Pages: Settings → Pages → Source: "GitHub Actions" → Save
3. Push content to main branch → Your site auto-deploys!

For Development

# Clone the repository
git clone https://github.com/conorluddy/AgentStatic.git
cd AgentStatic

# Install dependencies
npm install

# Run tests
npm test

# Type checking
npm run type-check

# Build for production
npm run build

🏗️ Project Structure

AgentStatic/
├── src/
│   ├── core/               # Core engine (PartialRegistry ✅)
│   │   ├── partial-registry.ts
│   │   └── index.ts
│   ├── types/              # TypeScript interfaces
│   │   ├── partial.ts      # AgentPartial interface
│   │   ├── content.ts      # Content types
│   │   └── template.ts     # Template types
│   ├── partials/           # Partial categories
│   │   ├── layout/         # Page structure partials
│   │   ├── content/        # Content display partials
│   │   ├── media/          # Media handling partials
│   │   └── interactive/    # Interactive components
│   ├── helpers/            # Utility functions
│   └── mcp/                # MCP integration (future)
├── tests/                  # Comprehensive test suite
│   └── unit/
│       ├── core/           # Core system tests
│       ├── types/          # Type system tests
│       └── config/         # Configuration tests
├── content/                # User content (markdown)
├── assets/                 # Media files
└── scripts/                # Build and deployment

📖 Understanding the Partial System

The heart of AgentStatic is its TypeScript-first partial system with Zod validation:

What are Partials?

Partials are reusable, self-contained components that include:

• Schema: Zod validation for type-safe props
• Template: HTML generation function
• Styles: Scoped CSS for the component
• Metadata: Discovery and documentation info

Creating Your First Partial

// src/partials/custom/my-card.partial.ts
import { z } from 'zod';
import type { AgentPartial } from '@/types/partial';

export const cardPartial: AgentPartial<{
  title: string;
  description: string;
  imageUrl?: string;
  link?: string;
}> = {
  schema: z.object({
    title: z.string().min(1),
    description: z.string().max(200),
    imageUrl: z.string().url().optional(),
    link: z.string().url().optional(),
  }),

  template: props => `
    <article class="card">
      ${props.imageUrl ? `<img src="${props.imageUrl}" alt="${props.title}">` : ''}
      <h3>${props.title}</h3>
      <p>${props.description}</p>
      ${props.link ? `<a href="${props.link}">Learn more →</a>` : ''}
    </article>
  `,

  styles: `
    .card {
      border: 1px solid #e0e0e0;
      border-radius: 8px;
      padding: 1.5rem;
      margin-bottom: 1rem;
    }
    .card img {
      width: 100%;
      height: 200px;
      object-fit: cover;
      border-radius: 4px;
      margin-bottom: 1rem;
    }
    .card h3 {
      margin: 0 0 0.5rem 0;
    }
    .card a {
      color: #007bff;
      text-decoration: none;
    }
  `,

  metadata: {
    description: 'Card component for displaying content previews',
    category: 'content',
    keywords: ['card', 'preview', 'component'],
    usageExamples: ['Blog post previews', 'Product cards', 'Team member profiles'],
  },
};

Using the Partial Registry

import { PartialRegistrySystem } from '@/core/partial-registry';

// Create registry instance
const registry = new PartialRegistrySystem();

// Register a partial
registry.register('my-card', cardPartial);

// Validate and use
const validatedProps = registry.validatePartialProps('my-card', {
  title: 'Hello World',
  description: 'This is a test card',
});

const partial = registry.get('my-card');
const html = partial.template(validatedProps, helpers);

Automatic Discovery

// Enable filesystem discovery
await registry.discoverPartials('./src/partials');

// Enable hot reload for development
registry.enableHotReload('./src/partials');

// Listen to events
registry.on('discover', (name, partial) => {
  console.log(`Discovered partial: ${name}`);
});

registry.on('reload', (name, partial) => {
  console.log(`Reloaded partial: ${name}`);
});

🧪 Testing

AgentStatic uses comprehensive TDD (Test-Driven Development):

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:coverage

# UI test runner
npm run test:ui

Test Structure

• Unit Tests: Core functionality, type safety, validation
• Integration Tests: Partial discovery, hot reload, events
• Performance Tests: Registry scaling, validation caching

🛠️ Development Commands

# TypeScript type checking
npm run type-check

# Linting
npm run lint
npm run lint:fix

# Code formatting
npm run format
npm run format:check

# Build
npm run build
npm run build:types

# Clean build artifacts
npm run clean

🆚 Why Choose AgentStatic?

Unique Features

• TypeScript-First Partials: Full type safety with Zod validation
• Hot Reload Architecture: Instant updates during development
• Event-Driven System: Extensible plugin architecture
• Production-Ready Foundation: 48 tests, 100% pass rate
• AI-Ready Design: MCP integration planned for next phase

Comparison

Feature	AgentStatic	Jekyll	Hugo	Gatsby
TypeScript Partials	✅ Native	❌ No	❌ No	🔧 Limited
Zod Validation	✅ Built-in	❌ No	❌ No	❌ No
Hot Reload	✅ Native	🔧 Plugin	✅ Yes	✅ Yes
GitHub Template	✅ One-click	❌ Manual	❌ Manual	❌ Manual
Test Coverage	✅ Comprehensive	🔧 Basic	🔧 Basic	✅ Good
AI Integration	🚧 Coming (MCP)	❌ No	❌ No	❌ No

🎯 Use Cases

Today (With Partial Registry)

• Component Libraries: Build reusable UI components with validation
• Design Systems: Type-safe component development
• Static Sites: GitHub Pages deployment ready
• Documentation: Structured content with TypeScript

Coming Soon (Next Phases)

• Portfolio Sites: Advanced media handling and galleries
• Marketing Sites: SEO optimization and performance
• Developer Blogs: Code highlighting and technical features
• AI-Enhanced Content: MCP-powered content generation

🤝 Contributing

AgentStatic welcomes contributions! We follow TDD practices and maintain high code quality standards.

How to Contribute

1. Check the Issues: Look for issues labeled good first issue or help wanted
2. Fork & Branch: Create a feature branch from main
3. Write Tests First: Follow TDD - tests before implementation
4. Submit PR: Include tests and update documentation

Development Guidelines

• TypeScript Strict Mode: No any types allowed
• Test Coverage: Maintain >90% coverage
• Conventional Commits: Use semantic commit messages
• Documentation: Update README and inline docs

Current Priority Areas

1. Markdown Processing (Issue #11) - Unified pipeline implementation
2. CLI Framework (Issue #15) - Interactive command interface
3. Development Server (Issue #16) - Live preview functionality
4. Documentation - Improve guides and examples

📊 Project Metrics

Code Quality

• TypeScript Coverage: 100% (strict mode)
• Test Coverage: 48 tests, 100% pass rate
• Dependencies: Modern, actively maintained
• Node.js: Requires 24+ for latest features

Performance

• Registry Operations: <1ms with caching
• Partial Discovery: Handles 1000+ partials
• Hot Reload: Instant file change detection
• Build Time: Sub-second builds (coming)

🚀 Future Vision

Near Term (Q1 2025)

• ✅ Partial Registry (COMPLETE)
• 🚧 Markdown Engine (In Progress)
• 🚧 CLI Tools (In Progress)
• 📋 Dev Server (Next Up)

Medium Term (Q2 2025)

• 📋 MCP Integration - AI-powered content
• 📋 Plugin Marketplace - Community extensions
• 📋 Advanced Media - Gallery components
• 📋 Theme System - Swappable designs

Long Term (Q3-Q4 2025)

• 📋 Multi-language - i18n support
• 📋 E-commerce - Shop components
• 📋 Analytics - Privacy-first tracking
• 📋 CDN Integration - Global deployment

📚 Resources

Documentation

• Project Architecture
• Contributing Guide
• GitHub Issues
• Discussions

Technologies

• TypeScript 5.7 - Type-safe development
• Zod - Runtime validation
• Vitest - Modern testing framework
• Model Context Protocol - AI integration (coming)

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

AgentStatic is built on the shoulders of giants:

• The TypeScript team for an amazing type system
• The Zod team for elegant runtime validation
• The Vitest team for a delightful testing experience
• The open source community for inspiration and support

Special recognition to early contributors who helped shape the vision and architecture.

---

🚀 Ready to Build Something Amazing?

📋 Use This Template | ⭐ Star on GitHub | 💬 Join Discussion

AgentStatic - Modern Static Sites with TypeScript Partials & AI-Ready Architecture

Building the future of static site generation, one partial at a time ✨