@botlearn/code-gen 0.1.0

package/knowledge/domain.md

@@ -0,0 +1,344 @@
+---
+domain: code-gen
+topic: design-patterns-and-language-idioms
+priority: high
+ttl: 30d
+---
+
+# Code Generation — Design Patterns, Async Patterns & Error Handling
+
+## Creational Design Patterns
+
+### Factory Pattern
+- Use when object creation logic is complex or depends on runtime conditions
+- Encapsulate construction behind a factory function or class method
+- Return interface types rather than concrete implementations
+```typescript
+interface Logger { log(msg: string): void; }
+function createLogger(type: "console" | "file" | "remote"): Logger {
+  switch (type) {
+    case "console": return new ConsoleLogger();
+    case "file": return new FileLogger();
+    case "remote": return new RemoteLogger();
+    default: throw new InvalidLoggerTypeError(type);
+  }
+}
+```
+
+### Builder Pattern
+- Use for constructing complex objects with many optional parameters
+- Prefer over constructors with 4+ parameters
+- Chain methods and return `this` for fluent API
+```typescript
+const query = new QueryBuilder()
+  .select("name", "email")
+  .from("users")
+  .where("active", true)
+  .orderBy("created_at", "desc")
+  .limit(50)
+  .build();
+```
+
+### Singleton / Module Pattern
+- Use for shared resources: database connections, configuration, caches
+- In modern JS/TS: prefer module-level instances over class-based singletons
+- Always make singletons injectable for testability
+```typescript
+// Module singleton (preferred)
+const config = loadConfig();
+export { config };
+
+// Injectable singleton (testable)
+let instance: DbPool | null = null;
+export function getPool(factory = createPool): DbPool {
+  if (!instance) instance = factory();
+  return instance;
+}
+```
+
+## Structural Design Patterns
+
+### Adapter Pattern
+- Use to wrap third-party libraries behind your own interface
+- Isolates vendor lock-in; makes swapping implementations easy
+```typescript
+interface StorageAdapter {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+// RedisAdapter, MemcachedAdapter, InMemoryAdapter all implement StorageAdapter
+```
+
+### Repository Pattern
+- Abstract data access behind a repository interface
+- Keep business logic free from database query details
+```typescript
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  create(data: CreateUserDTO): Promise<User>;
+  update(id: string, data: UpdateUserDTO): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+```
+
+### Middleware / Pipeline Pattern
+- Chain processing steps for request handling, data transformation, or validation
+- Each middleware receives context and a `next` function
+```typescript
+type Middleware<T> = (ctx: T, next: () => Promise<void>) => Promise<void>;
+
+function compose<T>(middlewares: Middleware<T>[]): Middleware<T> {
+  return (ctx, next) => {
+    let index = -1;
+    function dispatch(i: number): Promise<void> {
+      if (i <= index) return Promise.reject(new Error("next() called multiple times"));
+      index = i;
+      const fn = i === middlewares.length ? next : middlewares[i];
+      return fn(ctx, () => dispatch(i + 1));
+    }
+    return dispatch(0);
+  };
+}
+```
+
+## Behavioral Design Patterns
+
+### Strategy Pattern
+- Use when an algorithm needs to vary at runtime
+- Define a common interface; inject the desired strategy
+```typescript
+interface CompressionStrategy {
+  compress(data: Buffer): Promise<Buffer>;
+  decompress(data: Buffer): Promise<Buffer>;
+}
+// GzipStrategy, BrotliStrategy, LZ4Strategy all implement CompressionStrategy
+```
+
+### Observer / Event Emitter Pattern
+- Use for decoupled communication between components
+- Prefer typed event maps over string-based events
+```typescript
+type EventMap = {
+  "user:created": { id: string; email: string };
+  "user:deleted": { id: string };
+  "order:completed": { orderId: string; total: number };
+};
+
+interface TypedEmitter<T extends Record<string, unknown>> {
+  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void;
+  emit<K extends keyof T>(event: K, data: T[K]): void;
+}
+```
+
+## Async Patterns
+
+### Promise Composition
+```typescript
+// Parallel execution — use when tasks are independent
+const [users, orders, products] = await Promise.all([
+  fetchUsers(),
+  fetchOrders(),
+  fetchProducts(),
+]);
+
+// Settled — use when you need results even if some fail
+const results = await Promise.allSettled([
+  riskyOperation1(),
+  riskyOperation2(),
+]);
+const successes = results.filter(r => r.status === "fulfilled");
+const failures = results.filter(r => r.status === "rejected");
+```
+
+### Retry with Exponential Backoff
+```typescript
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { maxRetries: number; baseDelay: number; maxDelay: number }
+): Promise<T> {
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === options.maxRetries) throw error;
+      const delay = Math.min(
+        options.baseDelay * Math.pow(2, attempt) + Math.random() * 100,
+        options.maxDelay
+      );
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error("Unreachable");
+}
+```
+
+### Async Iterator / Stream Processing
+```typescript
+async function* paginate<T>(
+  fetchPage: (cursor: string | null) => Promise<{ data: T[]; nextCursor: string | null }>
+): AsyncGenerator<T> {
+  let cursor: string | null = null;
+  do {
+    const { data, nextCursor } = await fetchPage(cursor);
+    for (const item of data) yield item;
+    cursor = nextCursor;
+  } while (cursor !== null);
+}
+```
+
+### Circuit Breaker
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private lastFailureTime = 0;
+  private state: "closed" | "open" | "half-open" = "closed";
+
+  constructor(
+    private readonly threshold: number,
+    private readonly resetTimeoutMs: number
+  ) {}
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === "open") {
+      if (Date.now() - this.lastFailureTime > this.resetTimeoutMs) {
+        this.state = "half-open";
+      } else {
+        throw new CircuitOpenError("Circuit breaker is open");
+      }
+    }
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  private onSuccess(): void {
+    this.failures = 0;
+    this.state = "closed";
+  }
+
+  private onFailure(): void {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+    if (this.failures >= this.threshold) this.state = "open";
+  }
+}
+```
+
+## Error Handling Patterns
+
+### Custom Error Hierarchy
+```typescript
+class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500,
+    public readonly isOperational: boolean = true,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string, public readonly fields: Record<string, string[]>) {
+    super(message, "VALIDATION_ERROR", 400);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} with id '${id}' not found`, "NOT_FOUND", 404);
+  }
+}
+
+class ExternalServiceError extends AppError {
+  constructor(service: string, cause: Error) {
+    super(`External service '${service}' failed: ${cause.message}`, "EXTERNAL_SERVICE_ERROR", 502, true, cause);
+  }
+}
+```
+
+### Result Type (Rust-inspired)
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+// Usage: eliminates try/catch proliferation
+async function parseConfig(path: string): Promise<Result<Config, ConfigError>> {
+  const raw = await readFile(path);
+  if (!raw) return err(new ConfigError("File not found"));
+  const parsed = JSON.parse(raw);
+  const validated = configSchema.safeParse(parsed);
+  if (!validated.success) return err(new ConfigError(validated.error.message));
+  return ok(validated.data);
+}
+```
+
+### Graceful Degradation
+```typescript
+async function getUserProfile(userId: string): Promise<UserProfile> {
+  const user = await userRepo.findById(userId); // Required — throw on failure
+  if (!user) throw new NotFoundError("User", userId);
+
+  // Optional enrichment — degrade gracefully
+  const [avatar, preferences] = await Promise.allSettled([
+    avatarService.getAvatar(userId),
+    preferencesService.getPreferences(userId),
+  ]);
+
+  return {
+    ...user,
+    avatar: avatar.status === "fulfilled" ? avatar.value : DEFAULT_AVATAR,
+    preferences: preferences.status === "fulfilled" ? preferences.value : DEFAULT_PREFERENCES,
+  };
+}
+```
+
+## Language-Specific Idioms
+
+### TypeScript
+- Use `unknown` instead of `any` for type-safe narrowing
+- Prefer `interface` for object shapes; `type` for unions, intersections, and mapped types
+- Use discriminated unions for state modeling
+- Leverage `as const` for literal types and exhaustive checks
+- Use branded types for domain identifiers (`type UserId = string & { __brand: "UserId" }`)
+
+### Python
+- Use dataclasses or Pydantic models for structured data
+- Use context managers (`with` statement) for resource management
+- Prefer `pathlib.Path` over string-based file operations
+- Use type hints with `TypeVar`, `Generic`, `Protocol` for generic code
+- Use `enum.Enum` for fixed sets of values; `@dataclass(frozen=True)` for value objects
+
+### Go
+- Return `(result, error)` tuples; check errors immediately
+- Use `context.Context` for cancellation and timeout propagation
+- Prefer composition over inheritance via struct embedding
+- Use interfaces implicitly (no `implements` keyword)
+- Use `defer` for cleanup; `sync.WaitGroup` for goroutine coordination
+
+### Rust
+- Leverage the ownership system; prefer `&str` over `String` in function signatures
+- Use `Result<T, E>` and the `?` operator for error propagation
+- Use `enum` for algebraic data types and state machines
+- Implement `From<OtherError>` for custom error types to enable `?`
+- Use `Iterator` trait methods instead of manual loops

package/manifest.json

@@ -0,0 +1,26 @@
+{
+  "name": "@botlearn/code-gen",
+  "version": "0.1.0",
+  "description": "Complete code generation with proper architecture, error handling, type safety, and test accompaniment for OpenClaw Agent",
+  "category": "programming-assistance",
+  "author": "BotLearn",
+  "benchmarkDimension": "code-generation",
+  "expectedImprovement": 50,
+  "dependencies": {},
+  "compatibility": {
+    "openclaw": ">=0.5.0"
+  },
+  "files": {
+    "skill": "skill.md",
+    "knowledge": [
+      "knowledge/domain.md",
+      "knowledge/best-practices.md",
+      "knowledge/anti-patterns.md"
+    ],
+    "strategies": [
+      "strategies/main.md"
+    ],
+    "smokeTest": "tests/smoke.json",
+    "benchmark": "tests/benchmark.json"
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@botlearn/code-gen",
+  "version": "0.1.0",
+  "description": "Complete code generation with proper architecture, error handling, type safety, and test accompaniment for OpenClaw Agent",
+  "type": "module",
+  "main": "manifest.json",
+  "files": [
+    "manifest.json",
+    "skill.md",
+    "knowledge/",
+    "strategies/",
+    "tests/",
+    "README.md"
+  ],
+  "keywords": [
+    "botlearn",
+    "openclaw",
+    "skill",
+    "programming-assistance"
+  ],
+  "author": "BotLearn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/readai-team/botlearn-awesome-skills.git",
+    "directory": "packages/skills/code-gen"
+  },
+  "homepage": "https://github.com/readai-team/botlearn-awesome-skills/tree/main/packages/skills/code-gen",
+  "bugs": {
+    "url": "https://github.com/readai-team/botlearn-awesome-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill.md

@@ -0,0 +1,43 @@
+---
+name: code-gen
+role: Code Generation Specialist
+version: 1.0.0
+triggers:
+  - "write code"
+  - "generate function"
+  - "create API"
+  - "implement feature"
+  - "code this"
+---
+
+# Role
+
+You are a Code Generation Specialist. When activated, you produce complete, production-ready code with proper architecture, comprehensive error handling, strong type safety, and accompanying tests. You transform high-level requirements into well-structured implementations that follow language idioms, framework conventions, and established design patterns.
+
+# Capabilities
+
+1. Analyze requirements to determine optimal architecture, language features, and design patterns before writing any code
+2. Generate complete implementations with proper module structure, interface definitions, error handling, and input validation
+3. Apply language-specific idioms and framework conventions (e.g., Pythonic patterns, idiomatic Go, modern TypeScript, Rust ownership)
+4. Produce typed interfaces and data models that enforce correctness at compile time and document intent
+5. Generate accompanying unit tests, integration tests, and usage examples alongside the implementation
+6. Implement comprehensive error handling with custom error types, recovery strategies, and meaningful error messages
+
+# Constraints
+
+1. Never generate code without first analyzing requirements and choosing an appropriate architecture
+2. Never omit error handling — every external interaction (I/O, network, parsing, user input) must have explicit error handling
+3. Never produce untyped code when the language supports a type system — always define interfaces, types, or schemas
+4. Never skip input validation — all public function parameters must be validated at the boundary
+5. Never generate code without at least one accompanying test or usage example
+6. Never use `any` type (TypeScript), bare `except` (Python), or equivalent type-erasure patterns unless explicitly justified
+
+# Activation
+
+WHEN the user requests code generation or implementation:
+1. Analyze the requirement to identify scope, constraints, target language, and quality expectations
+2. Select architecture and design patterns following strategies/main.md
+3. Apply language idioms and framework conventions from knowledge/domain.md
+4. Implement with type safety and error handling per knowledge/best-practices.md
+5. Verify against knowledge/anti-patterns.md to avoid common code generation mistakes
+6. Output complete implementation with types, error handling, tests, and usage documentation

package/strategies/main.md

@@ -0,0 +1,114 @@
+---
+strategy: code-gen
+version: 1.0.0
+steps: 6
+---
+
+# Code Generation Strategy
+
+## Step 1: Requirement Analysis
+- Parse the user's request to identify: **target language**, **framework/runtime**, **functional requirements**, **non-functional requirements** (performance, scale, security)
+- Classify the task type: utility function / API endpoint / data model / CLI tool / state machine / full-stack feature / library/SDK
+- Identify input/output contract: what data comes in, what data goes out, what types are involved
+- Determine the scope boundary: what this code is responsible for vs. what it delegates
+- IF requirements are ambiguous THEN ask one focused clarifying question before proceeding
+- Extract constraints: target runtime (Node.js, browser, serverless), dependencies allowed, coding standards, existing codebase conventions
+
+## Step 2: Architecture Decision
+- SELECT architecture pattern based on task type and complexity:
+  - Simple utility → Pure function with types and validation
+  - API endpoint → Controller + Service + Repository layers with DTO types
+  - Data pipeline → Pipeline/middleware pattern with typed stages
+  - State management → State machine with discriminated union states and typed transitions
+  - CLI tool → Command pattern with argument parsing, validation, and help generation
+  - Library/SDK → Public API with types, internal implementation, and barrel exports
+- SELECT design patterns from knowledge/domain.md:
+  - Use Factory when construction varies by input
+  - Use Strategy when algorithm varies at runtime
+  - Use Repository when abstracting data access
+  - Use Adapter when wrapping external services
+  - Use Builder when object construction has many optional parameters
+- DECIDE error handling strategy:
+  - Result type (functional style) for libraries and utilities
+  - Exception hierarchy (OOP style) for applications and APIs
+  - Error codes with typed payloads for cross-boundary communication
+- DOCUMENT the chosen architecture in a brief comment block at the top of the output
+
+## Step 3: Interface Design
+- Define all public types, interfaces, and data transfer objects BEFORE writing implementation
+- For each public function, specify:
+  - Parameter names and types (with validation constraints noted)
+  - Return type (including error cases)
+  - Side effects (I/O, mutations, logging)
+  - Preconditions and postconditions
+- Apply type safety practices from knowledge/best-practices.md:
+  - Use discriminated unions for state modeling
+  - Use branded types for domain identifiers
+  - Derive types from validation schemas when possible
+  - Prefer `readonly` for immutable data
+- Define error types specific to this module:
+  - One base error class extending the standard error
+  - Specific error subclasses for each failure mode
+  - Include contextual fields (resource name, expected vs. received values)
+- IF the code involves an API THEN define the request/response schemas with validation
+
+## Step 4: Implementation
+- Implement each function following the interface contracts from Step 3
+- Apply language idioms from knowledge/domain.md:
+  - TypeScript: strict mode, no `any`, discriminated unions, `async`/`await`
+  - Python: type hints, dataclasses/Pydantic, context managers, pathlib
+  - Go: error returns, context propagation, defer, interface composition
+  - Rust: ownership, Result/Option, trait implementations, iterators
+- IMPLEMENT error handling at every boundary:
+  - Validate all inputs at the function entry point
+  - Wrap external calls (I/O, network, parsing) in try/catch with specific error types
+  - Provide meaningful error messages with context (field name, expected format, received value)
+  - IF the function interacts with external services THEN implement timeout, retry, and circuit breaker as appropriate
+- Apply async patterns from knowledge/domain.md:
+  - Use `Promise.all` for independent parallel operations
+  - Use `Promise.allSettled` when partial success is acceptable
+  - Use async iterators for paginated or streaming data
+  - Implement cancellation support via AbortController or context
+- VERIFY against anti-patterns from knowledge/anti-patterns.md:
+  - No `any` types or bare catches
+  - No silent error swallowing
+  - No hard-coded configuration
+  - No god functions (each function < 40 lines of logic)
+  - No missing input validation
+
+## Step 5: Self-Testing
+- Generate unit tests for every public function:
+  - **Happy path**: valid input produces expected output
+  - **Edge cases**: empty input, boundary values, maximum sizes, unicode, zero/null
+  - **Error paths**: invalid input throws the correct error type with expected message
+- Follow Arrange-Act-Assert pattern (from knowledge/best-practices.md)
+- Name tests descriptively: `should [expected behavior] when [condition]`
+- For async code: test timeout behavior, cancellation, retry exhaustion
+- For state machines: test all valid transitions and verify invalid transitions are rejected
+- IF the code involves I/O THEN generate integration test scaffolding with mock setup
+- Target minimum coverage:
+  - All public functions have at least one test
+  - All error branches have at least one test
+  - All state transitions have at least one test
+
+## Step 6: Review & Output
+- SELF-REVIEW the generated code against this checklist:
+  - [ ] All public types are defined and exported
+  - [ ] All inputs are validated at the boundary
+  - [ ] All errors are handled with specific types and contextual messages
+  - [ ] No `any`, no bare catches, no silent swallowing
+  - [ ] Functions are under 40 lines of logic each
+  - [ ] At least one test per public function
+  - [ ] Usage example is included
+  - [ ] Dependencies are explicitly imported (no implicit globals)
+  - [ ] Configuration is externalized (no hard-coded URLs, keys, or magic numbers)
+  - [ ] Code follows the target language's naming conventions and idioms
+- IF any check fails THEN loop back to the relevant step and fix
+- FORMAT the output in this order:
+  1. Architecture comment block (pattern chosen, rationale)
+  2. Type definitions and interfaces
+  3. Error types
+  4. Implementation
+  5. Tests
+  6. Usage example
+- PROVIDE brief inline comments for non-obvious logic (the "why", not the "what")