Unspec'd 🚀

📋 Table of Contents

• ✨ What is Unspec'd?
• 🌟 Key Features
• 📦 Installation
• 🚀 Quick Start
• 📖 Core Concepts
• 📚 Examples
• 🛠️ Advanced Features
• 🔧 CLI Commands
• 📁 Project Structure
• 🔧 Configuration
• 🌐 Deployment
• 🤝 Contributing
• 📄 License

✨ What is Unspec'd?

Building internal tools often feels like choosing between two painful options: wrestling with complex frontend frameworks or waiting months for a dedicated frontend team. Unspec'd offers a third path.

Unspec'd is a declarative UI framework designed for backend and TypeScript developers who know exactly what data they need, but don't want to get bogged down in frontend complexity.

🎯 Core Philosophy

The idea is elegantly simple: you define a clear, typed "spec" for your tool—a table, form, dashboard, or workflow—and Unspec'd translates it into a dynamic, production-ready user interface.

• You focus on data and business logic (what you're good at)
• Unspec'd handles the UI complexity (what it's good at)
• Result: Tools built in minutes, not weeks

🌟 Key Features

🎨 Declarative, Spec-Based UI

Define complex interfaces like editable tables, multi-step forms, and real-time dashboards using simple, readable TypeScript objects. You declare what you want, and the framework handles the how.

🔧 Backend-Developer-Focused

Write your data fetching, updates, and business logic in plain, asynchronous TypeScript functions. If you can write a Promise, you can build a tool with Unspec'd.

⚡ Powerful Smart Components

Leverage a rich library of pre-built components that handle the hard parts of UI development:

• SmartTable: Sortable, filterable, editable tables with real-time updates
• SmartForm: Multi-step forms with validation and dynamic fields
• ActionButton: Server-side actions with loading states and feedback
• DisplayRecord: Beautiful data presentation with custom formatting
• StreamingTable: Real-time data streaming with automatic updates

🔒 Type-Safe by Design

The entire spec is strongly typed, giving you autocompletion in your editor and catching errors before you even run your code. Your IDE becomes your primary development partner.

🤖 AI-Ready Architecture

The structured, predictable nature of Unspec'd specs makes them perfect targets for AI-assisted code generation, enabling even faster development workflows.

🚀 Multiple Usage Modes

• Library Mode: Import as a dependency and integrate into existing projects
• CLI Mode: Auto-discovery of tools with zero configuration
• Development Server: Hot-reload development environment with instant preview

📦 Installation

# npm
npm install @glyphtek/unspecd

# yarn
yarn add @glyphtek/unspecd

# pnpm
pnpm add @glyphtek/unspecd

# bun
bun add @glyphtek/unspecd

🚀 Quick Start

Option 1: Library Mode (Recommended)

Create a new file and start building:

// my-dashboard.ts
import { UnspecdUI, startServer } from '@glyphtek/unspecd';

const userManagementTool = {
  id: 'user-management',
  title: 'User Management',
  content: {
    type: 'smartTable',
    description: 'Manage system users with inline editing capabilities.',
    tableConfig: {
      columns: [
        { label: 'Name', field: 'name', editable: true },
        { label: 'Email', field: 'email', editable: true },
        { label: 'Role', field: 'role', editable: true },
        { label: 'Status', field: 'status', type: 'badge' }
      ],
      enableInlineEdit: true,
      enableRefresh: true
    },
    dataSource: {
      functionName: 'fetchUsers'
    },
    updateSource: {
      functionName: 'updateUser'
    }
  },
  functions: {
    fetchUsers: async () => {
      // Your data fetching logic
      return {
        items: [
          { id: 1, name: 'John Doe', email: '[email protected]', role: 'Admin', status: 'Active' },
          { id: 2, name: 'Jane Smith', email: '[email protected]', role: 'User', status: 'Active' }
        ]
      };
    },
    updateUser: async (params: any) => {
      console.log('Updating user:', params);
      // Your update logic here
      return { success: true };
    }
  }
};

// Initialize and start server
const app = new UnspecdUI({ tools: [userManagementTool] });
await startServer(app);

Run your dashboard:

bun run my-dashboard.ts
# Server starts at http://localhost:3000

Option 2: CLI Mode (Zero Configuration)

1. Initialize a new project:

npx @glyphtek/unspecd init
bun install

2. Create tool files:

// analytics-dashboard.tool.ts
export default {
  id: 'analytics',
  title: 'Analytics Dashboard',
  content: {
    type: 'displayRecord',
    description: 'Real-time analytics overview',
    displayConfig: {
      fields: [
        { label: 'Active Users', field: 'activeUsers', type: 'number' },
        { label: 'Revenue', field: 'revenue', type: 'currency' },
        { label: 'Conversion Rate', field: 'conversionRate', type: 'percentage' }
      ]
    },
    dataSource: { functionName: 'getAnalytics' }
  },
  functions: {
    getAnalytics: async () => ({
      activeUsers: 1247,
      revenue: 48392.50,
      conversionRate: 3.24
    })
  }
};

3. Start the development server:

bunx unspecd dev
# Auto-discovers all *.tool.ts files
# Server starts at http://localhost:3000

📖 Core Concepts

Tool Specification

Every tool in Unspec'd follows a simple structure:

interface ToolSpec {
  id: string;           // Unique identifier
  title: string;        // Display name
  content: Content;     // UI specification
  functions?: Functions; // Server-side logic
}

Content Types

Unspec'd provides several powerful content types:

SmartTable

Perfect for data management with CRUD operations:

content: {
  type: 'smartTable',
  tableConfig: {
    columns: [
      { label: 'Name', field: 'name', editable: true },
      { label: 'Status', field: 'status', type: 'badge' }
    ],
    enableInlineEdit: true,
    enableRefresh: true
  },
  dataSource: { functionName: 'fetchData' },
  updateSource: { functionName: 'updateRecord' }
}

SmartForm

For data input and multi-step workflows:

content: {
  type: 'smartForm',
  formConfig: {
    fields: [
      { label: 'Full Name', field: 'name', editorType: 'text', required: true },
      { label: 'Department', field: 'dept', editorType: 'select', 
        options: ['Engineering', 'Sales', 'Marketing'] }
    ]
  },
  submitAction: { functionName: 'createUser' }
}

ActionButton

For triggering server-side actions:

content: {
  type: 'actionButton',
  description: 'Generate monthly reports',
  buttonConfig: { label: 'Generate Reports', variant: 'primary' },
  action: { 
    functionName: 'generateReports',
    onSuccess: { message: 'Reports generated successfully!' }
  }
}

StreamingTable

For real-time data updates:

content: {
  type: 'streamingTable',
  tableConfig: {
    columns: [
      { label: 'Order ID', field: 'orderId' },
      { label: 'Status', field: 'status', type: 'badge' },
      { label: 'Amount', field: 'amount', type: 'currency' }
    ],
    maxRows: 100
  },
  streamingSource: { functionName: 'orderStream' }
}

📚 Examples

The framework includes comprehensive examples:

Library Mode Examples

• User Role Editor: Complete user management with role assignment
• Task Dashboard: Project management with real-time updates
• Batch Order Updater: Bulk operations with progress tracking
• GitHub Firehose Viewer: Real-time event streaming
• Live Orders Dashboard: E-commerce order monitoring

CLI Mode Examples

• System Monitor: Server health and performance metrics
• Cache Invalidator: Redis cache management interface
• User Management: CRUD operations with validation

Run any example:

# Library mode
bun run examples/lib/user-role-editor.ts

# CLI mode  
bunx unspecd dev --cwd examples/cli

🛠️ Advanced Features

Custom Styling

Unspec'd uses Tailwind CSS and provides customization options:

content: {
  type: 'smartTable',
  tableConfig: {
    className: 'custom-table-styles',
    rowClassName: (item) => item.priority === 'high' ? 'bg-red-50' : ''
  }
}

Data Transformation

Transform data before display:

content: {
  dataSource: {
    functionName: 'fetchRawData',
    transform: (data) => data.map(item => ({
      ...item,
      displayName: `${item.firstName} ${item.lastName}`
    }))
  }
}

Error Handling

Built-in error handling with custom messages:

functions: {
  riskyOperation: async (params) => {
    try {
      return await performOperation(params);
    } catch (error) {
      return { 
        error: true, 
        message: 'Operation failed. Please try again.' 
      };
    }
  }
}

🔧 CLI Commands

# Initialize new project
unspecd init

# Start development server with auto-discovery
unspecd dev [directory]

# Run specific tool file
unspecd exec <tool-file>

# Development server with custom port
unspecd dev --port 8080

# Help
unspecd --help

📁 Project Structure

my-unspecd-project/
├── package.json
├── unspecd.config.ts          # Optional configuration
├── tools/                     # CLI mode tools
│   ├── users.tool.ts
│   ├── analytics.tool.ts
│   └── reports.tool.ts
└── src/                       # Library mode integration
    └── dashboard.ts

🔧 Configuration

unspecd.config.ts

export default {
  tools: [
    '**/*.tool.ts',           // Auto-discover pattern
    'custom/admin-*.ts',      // Custom patterns
    'src/tools/**/*.ts'
  ]
};

TypeScript Configuration

Unspec'd works best with modern TypeScript:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

🌐 Deployment

Production Build

# Build for production
bun run build

# Deploy built assets
npm publish

Docker Deployment

FROM oven/bun:latest
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --production
COPY . .
RUN bun run build
EXPOSE 3000
CMD ["bun", "run", "start"]

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the linter: bun run lint
5. Submit a pull request

Development Setup

git clone https://github.com/glyphtek/unspecd.git
cd unspecd
bun install
bun run dev

Running Tests

bun test                    # Run test suite
bun run test:examples      # Test example projects
bun run lint               # Check code quality

📄 License

Unspec'd is open-source software licensed under the MIT License.