@defai.digital/automatosx 12.8.7 → 13.1.3

package/examples/abilities/clean-code.md

@@ -1,398 +0,0 @@
-# Clean Code Ability
-
-Expert knowledge and application of clean code principles for writing maintainable, readable, and high-quality software.
-
-## Overview
-
-Clean code is code that is easy to read, understand, and modify. It communicates intent clearly and minimizes cognitive load for future developers (including yourself).
-
-## Fundamental Principles
-
-### 1. Meaningful Names
-
-**Rule**: Names should reveal intent without requiring comments
-
-**Guidelines**:
-- Use intention-revealing names
-- Avoid disinformation and encodings
-- Make meaningful distinctions
-- Use pronounceable and searchable names
-- Avoid mental mapping
-
-**Examples**:
-```typescript
-// ❌ BAD: Cryptic names
-const d = new Date(); // elapsed time in days
-const arr = ['Bob', 'Alice'];
-
-// ✅ GOOD: Intention-revealing
-const elapsedTimeInDays = new Date();
-const userNames = ['Bob', 'Alice'];
-
-// ❌ BAD: Hungarian notation, noise words
-const strName = 'Bob';
-const userData = { name: 'Bob' };
-const userInfo = { name: 'Bob' }; // What's the difference?
-
-// ✅ GOOD: Clean, semantic names
-const userName = 'Bob';
-const user = { name: 'Bob' };
-const userProfile = { name: 'Bob', bio: '...' };
-```
-
-**Variable Naming**:
-- Use nouns or noun phrases
-- Boolean: `isActive`, `hasPermission`, `canEdit`
-- Collections: Use plural (`users`, `orders`, `products`)
-
-**Function Naming**:
-- Use verbs or verb phrases
-- `getUser()`, `calculateTotal()`, `validateInput()`
-- Boolean returning: `isValid()`, `hasErrors()`, `canProceed()`
-
-**Class Naming**:
-- Use nouns
-- Avoid "Manager", "Processor", "Data" suffixes
-- `UserRepository`, `EmailService`, `OrderValidator`
-
-### 2. Functions
-
-**Rule**: Functions should do one thing, do it well, and do it only
-
-**Small Functions**:
-- Keep functions small (< 20 lines ideal)
-- Each function should be one level of abstraction
-- Functions should not have side effects
-
-**Single Responsibility**:
-```typescript
-// ❌ BAD: Multiple responsibilities
-function processUser(user: User) {
-  validateUser(user);
-  saveToDatabase(user);
-  sendEmail(user);
-  logAudit(user);
-  updateCache(user);
-}
-
-// ✅ GOOD: Single responsibility
-function registerUser(user: User) {
-  const validated = validateUser(user);
-  return userRepository.save(validated);
-}
-
-function notifyUserRegistered(user: User) {
-  emailService.sendWelcome(user);
-  auditLogger.log('USER_REGISTERED', user.id);
-}
-```
-
-**Function Arguments**:
-- Zero arguments (niladic) is ideal
-- One argument (monadic) is good
-- Two arguments (dyadic) are okay
-- Three+ arguments (triadic+) require justification
-- Avoid flag arguments (split into two functions)
-
-**Examples**:
-```typescript
-// ❌ BAD: Too many arguments
-function createUser(name: string, email: string, age: number, role: string, active: boolean) {}
-
-// ✅ GOOD: Use object parameter
-function createUser(userData: UserData) {}
-
-// ❌ BAD: Flag argument
-function saveUser(user: User, validate: boolean) {}
-
-// ✅ GOOD: Separate functions
-function saveUser(user: User) {}
-function saveUserWithoutValidation(user: User) {}
-```
-
-**Command Query Separation**:
-- Functions should either DO something or ANSWER something, not both
-- Commands modify state, queries return values
-
-```typescript
-// ❌ BAD: Does both
-function setAndReturn(value: string): boolean {
-  this.value = value; // Command
-  return this.value === value; // Query
-}
-
-// ✅ GOOD: Separated
-function setValue(value: string): void {
-  this.value = value;
-}
-
-function getValue(): string {
-  return this.value;
-}
-```
-
-### 3. Comments
-
-**Rule**: Good code mostly documents itself; use comments wisely
-
-**When to Comment**:
-- Explain WHY, not WHAT
-- Clarify complex business rules
-- Warn of consequences
-- TODO/FIXME notes (with tickets)
-- Legal comments (copyright, license)
-- API documentation (JSDoc, docstrings)
-
-**When NOT to Comment**:
-- Don't comment bad code, rewrite it
-- Avoid redundant comments
-- Don't comment out code (use version control)
-- Avoid journal comments
-- Avoid position markers
-
-**Examples**:
-```typescript
-// ❌ BAD: Redundant comments
-// Get the user by ID
-function getUserById(id: string): User {
-  // Return the user
-  return users.find(u => u.id === id);
-}
-
-// ✅ GOOD: Self-documenting code
-function getUserById(id: string): User {
-  return users.find(u => u.id === id);
-}
-
-// ❌ BAD: Commented-out code
-function processOrder(order: Order) {
-  // validateOrder(order);
-  // checkInventory(order);
-  saveOrder(order);
-}
-
-// ✅ GOOD: Clear intent without noise
-/**
- * Processes order for payment and fulfillment.
- * NOTE: Validation and inventory check are handled upstream.
- */
-function processOrder(order: Order) {
-  saveOrder(order);
-}
-```
-
-### 4. Formatting
-
-**Rule**: Code formatting is about communication
-
-**Vertical Formatting**:
-- Small files are better (< 500 lines)
-- Blank lines separate concepts
-- Related code should be close together
-- Declare variables close to usage
-- Dependent functions should be close
-
-**Horizontal Formatting**:
-- Keep lines short (< 120 characters)
-- Use whitespace to associate related things
-- Indent to show hierarchy
-
-**Example**:
-```typescript
-// ✅ GOOD: Well-formatted
-class UserService {
-  constructor(
-    private userRepository: UserRepository,
-    private emailService: EmailService
-  ) {}
-
-  async registerUser(userData: UserData): Promise<User> {
-    const validated = this.validateUserData(userData);
-    const user = await this.userRepository.create(validated);
-    await this.sendWelcomeEmail(user);
-    return user;
-  }
-
-  private validateUserData(userData: UserData): UserData {
-    if (!userData.email) throw new Error('Email required');
-    if (!userData.name) throw new Error('Name required');
-    return userData;
-  }
-
-  private async sendWelcomeEmail(user: User): Promise<void> {
-    await this.emailService.send(user.email, 'Welcome!');
-  }
-}
-```
-
-### 5. Objects and Data Structures
-
-**Rule**: Objects hide data, expose behavior. Data structures expose data, have no behavior.
-
-**Law of Demeter**:
-- Don't talk to strangers
-- Method should only call methods on:
-  - Itself
-  - Its parameters
-  - Objects it creates
-  - Its direct dependencies
-
-```typescript
-// ❌ BAD: Violates Law of Demeter (train wreck)
-const street = user.getAddress().getStreet().getName();
-
-// ✅ GOOD: Tell, don't ask
-const street = user.getStreetName();
-
-// Inside User class:
-getStreetName(): string {
-  return this.address.street.name;
-}
-```
-
-### 6. Error Handling
-
-**Rule**: Error handling is important, but it shouldn't obscure logic
-
-**Use Exceptions**:
-```typescript
-// ❌ BAD: Error codes
-function processPayment(amount: number): number {
-  if (amount <= 0) return -1;
-  if (insufficientFunds()) return -2;
-  return 0; // success
-}
-
-// ✅ GOOD: Exceptions
-function processPayment(amount: number): void {
-  if (amount <= 0) {
-    throw new InvalidAmountError('Amount must be positive');
-  }
-  if (insufficientFunds()) {
-    throw new InsufficientFundsError('Not enough balance');
-  }
-  // Process payment
-}
-```
-
-**Don't Return Null**:
-```typescript
-// ❌ BAD: Null checks everywhere
-const users = getUsers();
-if (users !== null) {
-  for (const user of users) {
-    if (user !== null) {
-      // ...
-    }
-  }
-}
-
-// ✅ GOOD: Return empty collection
-function getUsers(): User[] {
-  return users ?? [];
-}
-
-// Or use Optional/Maybe pattern
-function getUserById(id: string): User | undefined {
-  return users.find(u => u.id === id);
-}
-```
-
-### 7. DRY (Don't Repeat Yourself)
-
-**Rule**: Every piece of knowledge should have a single representation in the system
-
-```typescript
-// ❌ BAD: Duplication
-function calculateOrderTotal(order: Order): number {
-  let total = 0;
-  for (const item of order.items) {
-    total += item.price * item.quantity;
-  }
-  total += total * 0.1; // Tax
-  total += 5; // Shipping
-  return total;
-}
-
-function calculateInvoiceTotal(invoice: Invoice): number {
-  let total = 0;
-  for (const item of invoice.items) {
-    total += item.price * item.quantity;
-  }
-  total += total * 0.1; // Tax
-  total += 5; // Shipping
-  return total;
-}
-
-// ✅ GOOD: Extract common logic
-function calculateSubtotal(items: Item[]): number {
-  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
-}
-
-function addTaxAndShipping(subtotal: number): number {
-  const tax = subtotal * 0.1;
-  const shipping = 5;
-  return subtotal + tax + shipping;
-}
-
-function calculateTotal(items: Item[]): number {
-  const subtotal = calculateSubtotal(items);
-  return addTaxAndShipping(subtotal);
-}
-```
-
-## Code Quality Checklist
-
-**Naming**:
-- [ ] All names reveal intent
-- [ ] No abbreviations or encodings
-- [ ] Boolean names start with is/has/can
-- [ ] Collections are plural
-- [ ] Functions are verbs, classes are nouns
-
-**Functions**:
-- [ ] Functions are small (< 20 lines)
-- [ ] Functions do one thing
-- [ ] One level of abstraction per function
-- [ ] Few arguments (prefer 0-2)
-- [ ] No flag arguments
-- [ ] No side effects
-
-**Comments**:
-- [ ] Comments explain WHY, not WHAT
-- [ ] No commented-out code
-- [ ] No redundant comments
-- [ ] API documentation present where needed
-
-**Formatting**:
-- [ ] Consistent indentation
-- [ ] Lines < 120 characters
-- [ ] Blank lines separate concepts
-- [ ] Related code is together
-
-**Error Handling**:
-- [ ] Use exceptions, not error codes
-- [ ] Don't return null (use empty collections or Optional)
-- [ ] Exceptions are specific and meaningful
-
-**General**:
-- [ ] No duplication (DRY)
-- [ ] Code is self-documenting
-- [ ] Tests exist and pass
-- [ ] No dead code
-
-## The Boy Scout Rule
-
-**"Leave the code better than you found it."**
-
-- Clean up small messes when you see them
-- Improve names, extract functions, add tests
-- Continuous improvement over time
-- Don't need permission for small improvements
-
-## Further Reading
-
-- "Clean Code" by Robert C. Martin
-- "Code Complete" by Steve McConnell
-- "The Pragmatic Programmer" by Hunt and Thomas
-- "Refactoring" by Martin Fowler

package/examples/abilities/code-generation.md

@@ -1,333 +0,0 @@
-# Code Generation
-
-Generate high-quality, production-ready code following best practices and patterns.
-
-## Core Principles
-
-### 1. Type Safety & Validation
-- Use strong typing (TypeScript interfaces, Python type hints)
-- Validate inputs before processing
-- Define clear return types
-- Use enums for fixed value sets
-
-### 2. Error Handling
-- Use try-catch for I/O operations
-- Provide specific error messages with context
-- Log errors appropriately
-- Never swallow errors silently
-- Return typed error objects or throw typed exceptions
-
-### 3. Function Design
-- Single responsibility per function
-- Clear, descriptive names
-- Document complex logic with comments
-- Keep functions small (<50 lines)
-- Minimize side effects
-
-### 4. API Design
-- RESTful conventions (GET/POST/PUT/DELETE)
-- Consistent response formats
-- Proper HTTP status codes
-- Request/response validation
-- API versioning when needed
-
-### 5. Testing
-- Write unit tests for business logic
-- Test error cases and edge conditions
-- Use descriptive test names
-- Aim for >80% coverage on critical paths
-- Mock external dependencies
-
-### 6. Code Quality
-- Follow project coding standards
-- Use linting and formatting tools
-- Write self-documenting code
-- Keep complexity low (cyclomatic complexity <10)
-- Remove dead code and TODOs
-
-### 7. Security
-- Validate and sanitize all inputs
-- Use parameterized queries (prevent SQL injection)
-- Never log sensitive data
-- Follow principle of least privilege
-- Keep dependencies updated
-
-### 8. Performance
-- Avoid N+1 queries
-- Use appropriate data structures
-- Cache when beneficial
-- Lazy load when possible
-- Profile before optimizing
-
-## Language-Specific Patterns
-
-### TypeScript/JavaScript
-- Async/await for promises
-- Optional chaining (?.) and nullish coalescing (??)
-- Destructuring for cleaner code
-- Use const by default, let when needed
-- Avoid var
-
-### TypeScript with Zod (Preferred for Scripts)
-
-**IMPORTANT**: When writing JavaScript or TypeScript scripts, always use TypeScript with Zod for runtime type safety and validation.
-
-#### Why Zod?
-- Runtime type validation (catches errors TypeScript can't)
-- Schema-based validation with composable schemas
-- Automatic type inference (no duplicate type definitions)
-- Parse, validate, and transform data in one step
-- Excellent error messages for debugging
-
-#### Installation
-```bash
-npm install zod
-# or
-pnpm add zod
-```
-
-#### Basic Usage Pattern
-
-```typescript
-import { z } from 'zod';
-
-// ✅ Define schema (types are automatically inferred)
-const UserSchema = z.object({
-  id: z.number().positive(),
-  email: z.string().email(),
-  name: z.string().min(1).max(100),
-  age: z.number().int().min(0).max(150).optional(),
-  role: z.enum(['admin', 'user', 'guest']),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-});
-
-// Type is automatically inferred from schema
-type User = z.infer<typeof UserSchema>;
-
-// Parse and validate data
-function createUser(data: unknown): User {
-  // Throws ZodError if validation fails
-  return UserSchema.parse(data);
-}
-
-// Safe parsing (returns success/error object)
-function tryCreateUser(data: unknown): User | null {
-  const result = UserSchema.safeParse(data);
-  if (result.success) {
-    return result.data;
-  } else {
-    console.error('Validation failed:', result.error.issues);
-    return null;
-  }
-}
-```
-
-#### API Request/Response Validation
-
-```typescript
-import { z } from 'zod';
-
-// ✅ Input validation schema
-const CreatePostSchema = z.object({
-  title: z.string().min(1).max(200),
-  content: z.string().min(1),
-  tags: z.array(z.string()).max(10).optional(),
-  publishAt: z.string().datetime().optional(),
-});
-
-// ✅ Response schema
-const PostResponseSchema = z.object({
-  id: z.string().uuid(),
-  title: z.string(),
-  content: z.string(),
-  tags: z.array(z.string()),
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
-});
-
-type CreatePostInput = z.infer<typeof CreatePostSchema>;
-type PostResponse = z.infer<typeof PostResponseSchema>;
-
-// ✅ API handler with validation
-async function createPost(req: Request): Promise<PostResponse> {
-  // Validate request body
-  const input = CreatePostSchema.parse(await req.json());
-
-  // Business logic
-  const post = await db.posts.create({
-    title: input.title,
-    content: input.content,
-    tags: input.tags ?? [],
-  });
-
-  // Validate response before returning
-  return PostResponseSchema.parse({
-    id: post.id,
-    title: post.title,
-    content: post.content,
-    tags: post.tags,
-    createdAt: post.createdAt.toISOString(),
-    updatedAt: post.updatedAt.toISOString(),
-  });
-}
-```
-
-#### Configuration File Validation
-
-```typescript
-import { z } from 'zod';
-import { readFile } from 'fs/promises';
-
-// ✅ Configuration schema
-const ConfigSchema = z.object({
-  server: z.object({
-    port: z.number().int().min(1024).max(65535).default(3000),
-    host: z.string().default('localhost'),
-  }),
-  database: z.object({
-    url: z.string().url(),
-    poolSize: z.number().int().positive().default(10),
-    ssl: z.boolean().default(false),
-  }),
-  logging: z.object({
-    level: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
-    pretty: z.boolean().default(false),
-  }).optional(),
-});
-
-type Config = z.infer<typeof ConfigSchema>;
-
-// ✅ Load and validate configuration
-async function loadConfig(path: string): Promise<Config> {
-  const raw = await readFile(path, 'utf-8');
-  const json = JSON.parse(raw);
-
-  // Parse with defaults applied
-  return ConfigSchema.parse(json);
-}
-```
-
-#### CLI Argument Validation
-
-```typescript
-import { z } from 'zod';
-
-// ✅ CLI arguments schema
-const CliArgsSchema = z.object({
-  input: z.string().min(1),
-  output: z.string().min(1),
-  verbose: z.boolean().default(false),
-  format: z.enum(['json', 'yaml', 'csv']).default('json'),
-  limit: z.number().int().positive().optional(),
-});
-
-type CliArgs = z.infer<typeof CliArgsSchema>;
-
-// ✅ Parse CLI arguments
-function parseCliArgs(argv: string[]): CliArgs {
-  const args = {
-    input: argv[2],
-    output: argv[3],
-    verbose: argv.includes('--verbose'),
-    format: argv.includes('--format')
-      ? argv[argv.indexOf('--format') + 1]
-      : undefined,
-  };
-
-  return CliArgsSchema.parse(args);
-}
-```
-
-#### Data Transformation with Zod
-
-```typescript
-import { z } from 'zod';
-
-// ✅ Transform and validate data
-const TimestampSchema = z.string().transform((str) => new Date(str));
-
-const UserInputSchema = z.object({
-  email: z.string().email().transform((e) => e.toLowerCase()),
-  age: z.string().transform((s) => parseInt(s, 10)),
-  createdAt: TimestampSchema,
-});
-
-// Input: { email: 'USER@EXAMPLE.COM', age: '25', createdAt: '2024-01-01T00:00:00Z' }
-// Output: { email: 'user@example.com', age: 25, createdAt: Date object }
-```
-
-#### Error Handling Best Practices
-
-```typescript
-import { z } from 'zod';
-
-function processUserData(data: unknown) {
-  const result = UserSchema.safeParse(data);
-
-  if (!result.success) {
-    // ✅ Detailed error messages
-    const errors = result.error.issues.map((issue) => ({
-      field: issue.path.join('.'),
-      message: issue.message,
-      code: issue.code,
-    }));
-
-    throw new ValidationError('Invalid user data', errors);
-  }
-
-  return result.data;
-}
-```
-
-#### When to Use Zod
-
-**Always use Zod for**:
-- ✅ API request/response validation
-- ✅ Configuration file parsing
-- ✅ CLI argument validation
-- ✅ External data (files, databases, APIs)
-- ✅ User input from any source
-- ✅ Environment variable validation
-
-**TypeScript types alone are sufficient for**:
-- Internal function parameters (within same file)
-- Return types of pure functions
-- Class properties with known types
-- Type aliases and interfaces for documentation
-
-#### Quick Checklist for TypeScript + Zod
-
-Before submitting TypeScript code:
-- [ ] Installed Zod (`npm install zod`)
-- [ ] Defined schemas for all external data
-- [ ] Used `z.infer<typeof Schema>` for type inference
-- [ ] Validated inputs at boundaries (API, CLI, files)
-- [ ] Used `safeParse()` for better error handling
-- [ ] Included meaningful error messages
-- [ ] No `any` types (use `z.unknown()` if needed)
-
-### Python
-- Type hints for function signatures
-- List/dict comprehensions for data transformation
-- Context managers (with statement) for resources
-- Follow PEP 8 style guide
-- Use dataclasses for data models
-
-### SQL
-- Use indexes on frequently queried columns
-- Avoid SELECT *
-- Use JOINs efficiently
-- Parameterize queries
-- Use transactions for multi-step operations
-
-## Quick Checklist
-
-Before submitting code:
-- [ ] Types and interfaces defined
-- [ ] Error handling implemented
-- [ ] Input validation added
-- [ ] Tests written and passing
-- [ ] Code formatted and linted
-- [ ] No console.log/print in production code
-- [ ] Security considerations addressed
-- [ ] Performance optimized where needed