@botlearn/code-gen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BotLearn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @botlearn/code-gen
+
+> Complete code generation with proper architecture, error handling, type safety, and test accompaniment for OpenClaw Agent
+
+## Installation
+
+```bash
+# via npm
+npm install @botlearn/code-gen
+
+# via clawhub
+clawhub install @botlearn/code-gen
+```
+
+## Category
+
+programming-assistance
+
+## Dependencies
+
+None
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `manifest.json` | Skill metadata and configuration |
+| `skill.md` | Role definition and activation rules |
+| `knowledge/` | Domain knowledge documents |
+| `strategies/` | Behavioral strategy definitions |
+| `tests/` | Smoke and benchmark tests |
+
+## License
+
+MIT

package/knowledge/anti-patterns.md

@@ -0,0 +1,212 @@
+---
+domain: code-gen
+topic: anti-patterns
+priority: medium
+ttl: 30d
+---
+
+# Code Generation — Anti-Patterns
+
+## Type Safety Anti-Patterns
+
+### 1. `any` Type Abuse
+- **Problem**: Using `any` (TypeScript), `object` (C#), or `interface{}` (Go) to bypass the type system, silencing compiler checks and hiding bugs
+- **Impact**: Runtime crashes that should have been caught at compile time; no IDE autocompletion; impossible to refactor safely
+- **Fix**: Use `unknown` with type guards, generic constraints, or explicit union types
+```typescript
+// BAD
+function processData(data: any): any {
+  return data.items.map((i: any) => i.name);
+}
+
+// GOOD
+function processData<T extends { items: Array<{ name: string }> }>(data: T): string[] {
+  return data.items.map(i => i.name);
+}
+```
+
+### 2. Stringly-Typed Code
+- **Problem**: Using plain strings for states, roles, event names, and identifiers instead of enums or literal types
+- **Impact**: Typos become silent bugs; no autocompletion; refactoring misses string constants
+- **Fix**: Use string literal unions, enums, or const objects
+```typescript
+// BAD
+function setStatus(status: string) { ... }
+setStatus("actve"); // Typo — no compiler error
+
+// GOOD
+type Status = "active" | "inactive" | "suspended";
+function setStatus(status: Status) { ... }
+setStatus("actve"); // Compiler error
+```
+
+### 3. Type Assertion Over-Use
+- **Problem**: Using `as Type` or `!` (non-null assertion) to force types instead of proper narrowing
+- **Impact**: Bypasses type safety; runtime will crash when the assertion is wrong
+- **Fix**: Use type guards, null checks, or schema validation
+```typescript
+// BAD
+const user = response.data as User; // What if data is null?
+
+// GOOD
+const parsed = userSchema.safeParse(response.data);
+if (!parsed.success) throw new ValidationError(parsed.error);
+const user = parsed.data;
+```
+
+## Error Handling Anti-Patterns
+
+### 4. Silent Catch (Swallowed Errors)
+- **Problem**: Catching exceptions and doing nothing — losing error context and hiding failures
+- **Impact**: Bugs become invisible; system enters corrupt state silently; debugging becomes extremely difficult
+- **Fix**: Always log, re-throw, or return an error result. At minimum log the error.
+```typescript
+// BAD
+try {
+  await saveOrder(order);
+} catch (e) {
+  // silently swallowed
+}
+
+// GOOD
+try {
+  await saveOrder(order);
+} catch (error) {
+  logger.error("Failed to save order", { orderId: order.id, error });
+  throw new OrderPersistenceError(order.id, error);
+}
+```
+
+### 5. Catching Generic Exceptions
+- **Problem**: Using bare `catch` (Python), `catch (Exception e)` (Java), or `catch (e)` without type narrowing
+- **Impact**: Catches programming errors (null references, type errors) along with expected failures; masks bugs
+- **Fix**: Catch specific error types; let unexpected errors propagate to the global error handler
+```python
+# BAD
+try:
+    result = process_payment(order)
+except Exception:
+    return {"error": "something went wrong"}
+
+# GOOD
+try:
+    result = process_payment(order)
+except PaymentDeclinedError as e:
+    return {"error": f"Payment declined: {e.reason}", "code": "PAYMENT_DECLINED"}
+except PaymentGatewayTimeout as e:
+    logger.warning("Payment gateway timeout", extra={"order_id": order.id})
+    raise RetryableError("Payment processing timed out") from e
+```
+
+### 6. Error Messages Without Context
+- **Problem**: Throwing errors with generic messages like "An error occurred" or "Invalid input"
+- **Impact**: Debugging requires reproducing the issue; no information about what was expected vs. received
+- **Fix**: Include the field name, the received value (sanitized), and the expected format
+```typescript
+// BAD
+throw new Error("Invalid input");
+
+// GOOD
+throw new ValidationError(
+  `Field 'email' is invalid: received '${sanitize(input.email)}', expected a valid email address`
+);
+```
+
+## Validation Anti-Patterns
+
+### 7. No Input Validation
+- **Problem**: Assuming inputs are well-formed; passing user input directly to database queries, file operations, or shell commands
+- **Impact**: SQL injection, path traversal, command injection, data corruption, and crashes on unexpected types
+- **Fix**: Validate and sanitize all external input at the boundary; use parameterized queries
+```typescript
+// BAD
+app.get("/users/:id", async (req, res) => {
+  const user = await db.query(`SELECT * FROM users WHERE id = '${req.params.id}'`);
+  res.json(user);
+});
+
+// GOOD
+app.get("/users/:id", async (req, res) => {
+  const id = z.string().uuid().parse(req.params.id);
+  const user = await db.query("SELECT * FROM users WHERE id = $1", [id]);
+  if (!user) throw new NotFoundError("User", id);
+  res.json(user);
+});
+```
+
+### 8. Validation Logic Scattered Across Codebase
+- **Problem**: Validating the same field in multiple places with inconsistent rules
+- **Impact**: Contradictory validation; bypass by calling the inner function directly; maintenance nightmare
+- **Fix**: Define validation schemas once; apply at the API boundary; trust validated data internally
+
+## Architecture Anti-Patterns
+
+### 9. God Function / God Class
+- **Problem**: A single function or class that handles multiple unrelated responsibilities (parse + validate + transform + save + notify)
+- **Impact**: Impossible to test in isolation; changes ripple unpredictably; functions exceed 100 lines
+- **Fix**: Extract each responsibility into a separate function or class; compose them in a pipeline
+```typescript
+// BAD: one function does everything
+async function handleOrder(rawData: unknown) {
+  // 200 lines of parsing, validating, saving, emailing, logging...
+}
+
+// GOOD: composed pipeline
+async function handleOrder(rawData: unknown): Promise<OrderResult> {
+  const validated = validateOrderInput(rawData);
+  const order = buildOrder(validated);
+  const saved = await orderRepo.save(order);
+  await notificationService.sendConfirmation(saved);
+  return toOrderResult(saved);
+}
+```
+
+### 10. Hard-Coded Configuration
+- **Problem**: Embedding URLs, connection strings, API keys, timeouts, and feature flags directly in source code
+- **Impact**: Cannot change behavior without code changes; secrets leak into version control; different environments require code modifications
+- **Fix**: Use environment variables, configuration files, or a config module with validation
+```typescript
+// BAD
+const API_URL = "https://api.production.com/v2";
+const TIMEOUT = 5000;
+
+// GOOD
+const config = loadConfig({
+  apiUrl: envVar("API_URL").required().url(),
+  timeout: envVar("REQUEST_TIMEOUT_MS").default(5000).int().min(100).max(60000),
+});
+```
+
+### 11. Premature Abstraction
+- **Problem**: Creating generic frameworks, complex inheritance hierarchies, or elaborate plugin systems before having concrete use cases
+- **Impact**: Over-engineered code that is harder to understand and modify than the problem warrants; abstractions that don't match real usage patterns
+- **Fix**: Follow the "Rule of Three" — wait until you have three concrete examples before extracting an abstraction. Start concrete, refactor to abstract when patterns emerge.
+
+### 12. Missing Dependency Injection
+- **Problem**: Functions that directly instantiate their dependencies (e.g., `new Database()`, `axios.get()`) instead of accepting them as parameters
+- **Impact**: Impossible to unit test without mocking module internals; tight coupling; cannot swap implementations
+- **Fix**: Accept dependencies as function/constructor parameters; provide defaults for production
+```typescript
+// BAD: hard-wired dependency
+async function getUser(id: string) {
+  const db = new Database(); // untestable
+  return db.query("SELECT * FROM users WHERE id = $1", [id]);
+}
+
+// GOOD: injectable dependency
+async function getUser(id: string, db: Database = defaultDb): Promise<User | null> {
+  return db.query("SELECT * FROM users WHERE id = $1", [id]);
+}
+```
+
+## Output Anti-Patterns
+
+### 13. Code Without Usage Examples
+- **Problem**: Generating a function or class without showing how to call it
+- **Impact**: User must read the entire implementation to understand the API; incorrect usage leads to bugs
+- **Fix**: Always include at least one usage example with realistic arguments and expected output
+
+### 14. Incomplete Implementations
+- **Problem**: Generating skeleton code with `// TODO` placeholders or `pass` statements in critical paths
+- **Impact**: User deploys incomplete code; runtime failures in production
+- **Fix**: Generate complete implementations; if a feature is beyond scope, throw a `NotImplementedError` with a descriptive message rather than silently passing

package/knowledge/best-practices.md

@@ -0,0 +1,228 @@
+---
+domain: code-gen
+topic: type-safety-validation-and-testing
+priority: high
+ttl: 30d
+---
+
+# Code Generation — Best Practices
+
+## Type Safety
+
+### 1. Define Types at the Boundary
+- Define input/output types for every public function, API endpoint, and module boundary
+- Use schema validation libraries (Zod, Pydantic, JSON Schema) to enforce types at runtime boundaries
+- Keep internal logic strongly typed; only marshal/unmarshal at edges
+
+```typescript
+// Define the contract
+interface CreateOrderRequest {
+  userId: string;
+  items: Array<{ productId: string; quantity: number }>;
+  shippingAddress: Address;
+}
+
+interface CreateOrderResponse {
+  orderId: string;
+  status: "pending" | "confirmed";
+  estimatedDelivery: string;
+}
+
+// Validate at the boundary
+const createOrderSchema = z.object({
+  userId: z.string().uuid(),
+  items: z.array(z.object({
+    productId: z.string().uuid(),
+    quantity: z.number().int().positive().max(100),
+  })).min(1).max(50),
+  shippingAddress: addressSchema,
+});
+```
+
+### 2. Use Discriminated Unions for State
+- Model mutually exclusive states as discriminated unions instead of optional fields
+- Eliminates impossible states at the type level
+
+```typescript
+// BAD: allows impossible states (loading=true AND error set)
+interface DataState {
+  loading: boolean;
+  data?: User[];
+  error?: string;
+}
+
+// GOOD: each state is explicit and exhaustive
+type DataState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; data: User[] }
+  | { status: "error"; error: string; retryCount: number };
+```
+
+### 3. Prefer Narrow Types Over Broad Ones
+- Use string literal unions instead of `string` for known value sets
+- Use branded/opaque types for domain identifiers to prevent mixing
+- Use `readonly` arrays and objects where mutation is not needed
+
+```typescript
+type Currency = "USD" | "EUR" | "GBP" | "JPY";
+type OrderStatus = "draft" | "pending" | "confirmed" | "shipped" | "delivered" | "cancelled";
+
+// Branded types prevent accidental swaps
+type UserId = string & { readonly __brand: unique symbol };
+type OrderId = string & { readonly __brand: unique symbol };
+
+function getOrder(orderId: OrderId): Promise<Order>; // Cannot pass UserId here
+```
+
+## Input Validation
+
+### 4. Validate All External Input
+- Every public API, CLI argument, environment variable, and file read must be validated
+- Fail fast with descriptive error messages that name the invalid field and expected format
+- Never trust client-side validation alone; always re-validate on the server
+
+```typescript
+function validateEnvConfig(): AppConfig {
+  const errors: string[] = [];
+
+  const port = Number(process.env.PORT);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    errors.push("PORT must be an integer between 1 and 65535");
+  }
+
+  const dbUrl = process.env.DATABASE_URL;
+  if (!dbUrl || !dbUrl.startsWith("postgresql://")) {
+    errors.push("DATABASE_URL must be a valid PostgreSQL connection string");
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigValidationError(errors);
+  }
+
+  return { port, dbUrl: dbUrl! };
+}
+```
+
+### 5. Sanitize Before Processing
+- Trim whitespace from string inputs
+- Normalize Unicode (NFC) for text comparison
+- Escape special characters for SQL, HTML, shell, and regex contexts
+- Limit input length to prevent resource exhaustion
+
+### 6. Use Schema Validation Libraries
+- Zod (TypeScript): composable schemas with type inference
+- Pydantic (Python): model-based validation with automatic parsing
+- joi / yup (JavaScript): mature schema validation
+- Always derive TypeScript types from the schema, not the other way around
+
+```typescript
+// Schema is the source of truth; type is derived
+const userSchema = z.object({
+  name: z.string().min(1).max(200).trim(),
+  email: z.string().email().toLowerCase(),
+  age: z.number().int().min(0).max(150).optional(),
+  role: z.enum(["admin", "user", "viewer"]).default("user"),
+});
+
+type User = z.infer<typeof userSchema>; // Type derived from schema
+```
+
+## Test Accompaniment
+
+### 7. Generate Tests Alongside Code
+- Every generated function should include at least one unit test
+- Test the happy path, one edge case, and one error case at minimum
+- Use descriptive test names that state the expected behavior
+
+```typescript
+describe("calculateDiscount", () => {
+  it("should apply percentage discount to the subtotal", () => {
+    expect(calculateDiscount(100, { type: "percentage", value: 15 })).toBe(85);
+  });
+
+  it("should not reduce price below zero for large discounts", () => {
+    expect(calculateDiscount(10, { type: "fixed", value: 25 })).toBe(0);
+  });
+
+  it("should throw ValidationError for negative discount values", () => {
+    expect(() =>
+      calculateDiscount(100, { type: "percentage", value: -5 })
+    ).toThrow(ValidationError);
+  });
+});
+```
+
+### 8. Test Structure: Arrange-Act-Assert
+- **Arrange**: set up preconditions and inputs
+- **Act**: execute the code under test
+- **Assert**: verify the expected outcome
+- Keep each test focused on a single behavior
+
+### 9. Test Error Paths Explicitly
+- Verify that error messages are descriptive and actionable
+- Verify that error types are correct (not just that an error was thrown)
+- Test timeout behavior, retry logic, and graceful degradation
+
+```typescript
+it("should throw NotFoundError with resource name and id", async () => {
+  await expect(userRepo.findById("nonexistent-id"))
+    .rejects
+    .toThrow(new NotFoundError("User", "nonexistent-id"));
+});
+
+it("should retry 3 times before throwing on transient failure", async () => {
+  const mockFn = jest.fn()
+    .mockRejectedValueOnce(new TransientError())
+    .mockRejectedValueOnce(new TransientError())
+    .mockRejectedValueOnce(new TransientError())
+    .mockResolvedValue("success");
+
+  await expect(withRetry(mockFn, { maxRetries: 2 })).rejects.toThrow(TransientError);
+  expect(mockFn).toHaveBeenCalledTimes(3);
+});
+```
+
+## Code Organization
+
+### 10. Single Responsibility per Module
+- Each file/module should have one clear purpose
+- Group related types, functions, and constants together
+- Keep files under 300 lines; split when complexity grows
+
+### 11. Explicit Exports
+- Export only the public API; keep internals private
+- Use barrel files (`index.ts`) to aggregate public exports
+- Document exported functions with JSDoc or docstrings
+
+### 12. Consistent Naming Conventions
+| Entity | Convention | Example |
+|--------|-----------|---------|
+| Functions | camelCase (JS/TS), snake_case (Python/Rust/Go) | `getUserById`, `get_user_by_id` |
+| Classes/Types | PascalCase | `UserRepository`, `OrderStatus` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
+| Boolean vars | is/has/can/should prefix | `isActive`, `hasPermission` |
+| Files | kebab-case (JS/TS), snake_case (Python) | `user-repository.ts`, `user_repository.py` |
+
+## Documentation
+
+### 13. Self-Documenting Code with Strategic Comments
+- Choose descriptive names that make code readable without comments
+- Add comments for **why**, not **what** — explain non-obvious decisions
+- Document public APIs with parameter descriptions, return types, and examples
+- Include `@throws` / `Raises` annotations for functions that throw
+
+```typescript
+/**
+ * Calculates the shipping cost based on package weight and destination zone.
+ *
+ * Uses a tiered pricing model: base rate + per-kg surcharge above the free tier.
+ * International zones (4+) include an additional customs processing fee.
+ *
+ * @param weightKg - Package weight in kilograms (must be > 0)
+ * @param zone - Destination shipping zone (1-6)
+ * @returns The total shipping cost in cents
+ * @throws {ValidationError} If weight is non-positive or zone is out of range
+ */
+function calculateShippingCost(weightKg: number, zone: ShippingZone): number {
+```