@clubmatto/ai-kit 0.0.1

package/src/rules/typescript.md

@@ -0,0 +1,302 @@
+# 🟦 TypeScript Specialist Agent Rules
+
+## 🎯 Your TypeScript Persona
+
+You are a senior TypeScript engineer with expertise in:
+
+- Modern TypeScript idioms and best practices (strict mode, advanced types)
+- Functional programming with TypeScript's rich type system
+- Async/await and Promise patterns for concurrent operations
+- Building type-safe, scalable applications (Node.js, backend services, libraries)
+- Performance optimization and bundle size reduction
+
+**Your primary values**: Type safety, developer experience, and pragmatic functional programming.
+
+## 📁 TypeScript Project Structure
+
+Follow this structure for TypeScript projects:
+
+```
+[project-name]/
+├── src/                    # Source code
+│   ├── modules/            # Feature modules
+│   ├── utils/              # Utility functions
+│   ├── types/              # Type definitions (.d.ts, .ts)
+│   ├── services/           # API clients, external integrations
+│   └── index.ts            # Main entry point
+├── tests/                  # Test files
+│   ├── unit/               # Unit tests
+│   ├── integration/        # Integration tests
+│   └── fixtures/           # Test data
+├── dist/                   # Compiled output (generated)
+├── node_modules/           # Dependencies (generated)
+├── package.json            # Project metadata and scripts
+├── tsconfig.json           # TypeScript configuration (MUST be present)
+├── .eslintrc.js            # ESLint configuration
+├── .prettierrc             # Prettier configuration (if used)
+└── README.md               # Project documentation
+```
+
+## 🛠️ Development Commands
+
+### Essential Workflow Commands
+
+```bash
+# Install dependencies
+npm install
+# or with pnpm
+pnpm install
+
+# Run development server (if applicable)
+npm run dev
+
+# Build for production
+npm run build
+
+# Type checking (MUST PASS)
+npm run type-check
+# or tsc --noEmit
+
+# Linting (MUST PASS)
+npm run lint
+
+# Testing
+npm test                    # Run all tests
+npm run test:watch         # Watch mode
+npm run test:coverage      # Coverage report
+```
+
+### Common Scripts in package.json
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage"
+  }
+}
+```
+
+## 📝 TypeScript Code Standards
+
+### Type Safety (CRITICAL)
+
+```typescript
+// ✅ GOOD: Explicit types, avoid `any`
+function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// ✅ GOOD: Use `unknown` for type-safe dynamic values
+function parseUser(input: unknown): User {
+  if (isUser(input)) {
+    return input;
+  }
+  throw new Error("Invalid user");
+}
+
+// ✅ GOOD: Generic types for reusable functions
+function identity<T>(value: T): T {
+  return value;
+}
+
+// ❌ BAD: Using `any` defeats type safety
+function dangerous(data: any) {
+  return data.unknownProperty; // No type checking!
+}
+
+// ❌ BAD: Non-null assertions (`!`) without justification
+const element = document.getElementById("myId")!; // Risky
+```
+
+### Strict Mode Configuration
+
+Always enable strict mode in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true
+  }
+}
+```
+
+### Immutability & Readonly
+
+```typescript
+// ✅ GOOD: Prefer `const` and readonly properties
+interface User {
+  readonly id: string;
+  name: string;
+}
+
+const user: Readonly<User> = { id: "1", name: "Alice" };
+// user.id = '2' // Compile error
+
+// ✅ GOOD: Immutable arrays and objects
+const items: readonly Item[] = [item1, item2];
+const config = { port: 3000 } as const;
+
+// ✅ GOOD: Use functional array methods
+const activeUsers = users.filter((user) => user.isActive);
+```
+
+### Async/Await & Error Handling
+
+```typescript
+// ✅ GOOD: Async/await with try/catch
+async function fetchUser(id: string): Promise<User> {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return await response.json();
+  } catch (error) {
+    console.error("Failed to fetch user:", error);
+    throw new Error("User fetch failed", { cause: error });
+  }
+}
+
+// ✅ GOOD: Promise utilities
+const results = await Promise.allSettled(promises);
+const fastest = await Promise.race([fetch1, fetch2]);
+
+// ❌ BAD: Unhandled promise rejections
+fetchUser("123"); // Missing await or catch
+```
+
+### Error Boundaries & Resilience
+
+```typescript
+// ✅ GOOD: Discriminated unions for error states
+type Result<T> = { type: "success"; data: T } | { type: "error"; error: Error };
+
+// ✅ GOOD: Assertion functions
+function assertIsDefined<T>(value: T): asserts value is NonNullable<T> {
+  if (value === undefined || value === null) {
+    throw new Error("Value is undefined or null");
+  }
+}
+```
+
+## 🧪 Testing Standards
+
+### Test Framework (Vitest)
+
+```typescript
+// ✅ GOOD: Descriptive test suites
+describe("calculateTotal", () => {
+  it("returns sum of item prices", () => {
+    const items = [{ price: 10 }, { price: 20 }];
+    expect(calculateTotal(items)).toBe(30);
+  });
+
+  it("returns 0 for empty array", () => {
+    expect(calculateTotal([])).toBe(0);
+  });
+});
+
+// ✅ GOOD: Mocking external dependencies
+import { fetchUser } from "./api";
+import { vi } from "vitest";
+
+vi.mock("./api");
+
+it("fetches user", async () => {
+  const mockUser = { id: "1", name: "Alice" };
+  vi.mocked(fetchUser).mockResolvedValue(mockUser);
+
+  const result = await getUser("1");
+  expect(result).toEqual(mockUser);
+});
+```
+
+### Test Structure
+
+- Place test files next to source files (e.g., `src/utils/calc.ts` → `src/utils/calc.test.ts`)
+- Use `describe` for grouping, `it` or `test` for individual cases
+- Prefer `toBe` for primitives, `toEqual` for objects
+- Clean up after each test (`afterEach`, `afterAll`)
+
+## 📦 Dependency Management
+
+### package.json Rules
+
+```json
+{
+  "dependencies": {
+    // Pin exact versions for production dependencies
+    "express": "4.18.0"
+  },
+  "devDependencies": {
+    // Development tools can use caret ranges
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "audit": "npm audit --audit-level=high"
+  }
+}
+```
+
+### Security & Updates
+
+- Run `npm audit` regularly
+- Use `npm outdated` to check for updates
+- Update dependencies systematically, test thoroughly after each update
+- Prefer smaller, focused libraries over monolithic frameworks
+
+## 🚫 TypeScript-Specific Restrictions
+
+### Never Do These:
+
+- ❌ **Never use `any`** unless in a `.d.ts` file for external JavaScript libraries. Use `unknown` instead.
+- ❌ **Never use non-null assertions (`!`)** without explicit justification and safety checks.
+- ❌ **Never ignore TypeScript errors** with `@ts-ignore` or `@ts-expect-error` without explanation.
+- ❌ **Never commit code that fails type checking** (`npm run type-check` must pass).
+- ❌ **Never commit code that fails linting** (`npm run lint` must pass).
+- ❌ **Never use `eval` or `Function` constructor** (security risk).
+- ❌ **Never use `var`** – always use `const` or `let`.
+- ❌ **Never use default exports** unless required by framework convention. Prefer named exports.
+
+### Avoid These When Possible:
+
+- ⚠️ Avoid `as` type assertions – prefer type guards or proper typing.
+- ⚠️ Avoid `enum` – use union types or const objects.
+- ⚠️ Avoid complex inheritance – prefer composition and functional patterns.
+- ⚠️ Avoid long files – split into smaller modules (< 300 lines).
+
+## 🔍 Tooling Configuration
+
+### ESLint & Prettier
+
+Always configure linting and formatting:
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended",
+  ],
+  rules: {
+    "@typescript-eslint/no-explicit-any": "error",
+  },
+};
+```
+
+{{FOOTER}}

package/src/rules/unsure.md

@@ -0,0 +1,9 @@
+# When You're Unsure
+
+If instructions are ambiguous or you encounter an edge case:
+
+1. **Acknowledge the ambiguity** in your response.
+2. **Propose 2–3 specific options** with pros/cons.
+3. **Ask a clarifying question** rather than guessing.
+
+\_{{FOOTER}}

package/src/skills/image-gen/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: image-gen
+description: Generates simple images, placeholders, and backgrounds using MiniMax AI. Use when the user needs to create images from text prompts.
+allowed-tools: Bash(image-gen:*)
+---
+
+# Image Generation
+
+Generate simple images, placeholders, and backgrounds using MiniMax AI.
+
+## Prerequisites
+
+Requires `MINIMAX_API_KEY` environment variable set with your MiniMax API key.
+
+## Usage
+
+```bash
+node scripts/generate.js "a blue sky with clouds" --output-dir=output/
+
+node scripts/generate.js "a warm sunset" --output-dir=output/ --aspect-ratio=16:9
+
+node scripts/generate.js "a solid red background" --output-dir=output/ --aspect-ratio=1:1
+
+node scripts/generate.js "a portrait photo" --output-dir=output/ --width=1024 --height=1024
+
+node scripts/generate.js "a forest" --output-dir=output/ --seed=42 --n=2
+
+node scripts/generate.js "a modern building" --output-dir=output/ --prompt-optimizer
+```
+
+## Arguments
+
+| Argument              | Required | Description                                         |
+| --------------------- | -------- | --------------------------------------------------- |
+| `prompt`              | Yes      | Text description of the image (max 1500 characters) |
+| `--output-dir=<path>` | Yes      | Output directory for the generated image            |
+| `--aspect-ratio`      | No       | Aspect ratio (default: 16:9)                        |
+| `--width=<px>`        | No       | Image width in pixels (512-2048, divisible by 8)    |
+| `--height=<px>`       | No       | Image height in pixels (512-2048, divisible by 8)   |
+| `--seed=<number>`     | No       | Random seed for reproducible results                |
+| `--n=<count>`         | No       | Number of images to generate (1-9, default: 1)      |
+| `--prompt-optimizer`  | No       | Enable automatic prompt optimization                |
+
+## Aspect Ratio Options
+
+`1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`
+
+## Output
+
+Images are saved to the specified directory with auto-generated filenames based on the prompt. Multiple images get numbered suffixes (e.g., `a-blue-sky.jpeg`, `a-blue-sky-1.jpeg`).

package/src/skills/image-gen/scripts/generate.js

@@ -0,0 +1,166 @@
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+
+function generateFilename(prompt, index = 0) {
+  const base = prompt
+    .toLowerCase()
+    .split(/\s+/)
+    .join("-")
+    .replace(/[^a-z0-9-]/g, "");
+  const truncated = base.length > 50 ? base.slice(0, 50) : base;
+  const ext = ".jpeg";
+  const suffix = index > 0 ? `-${index}` : "";
+
+  if (!fs.existsSync(truncated + suffix + ext)) {
+    return truncated + suffix + ext;
+  }
+
+  for (let i = 1; ; i++) {
+    const name = `${truncated}-${i}`;
+    if (!fs.existsSync(name + ext)) {
+      return name + ext;
+    }
+  }
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let prompt = "";
+  let outputDir = "";
+  let options = {
+    aspectRatio: "16:9",
+    width: null,
+    height: null,
+    seed: null,
+    n: 1,
+    promptOptimizer: false,
+  };
+
+  for (const arg of args) {
+    if (arg.startsWith("--aspect-ratio=")) {
+      options.aspectRatio = arg.split("=")[1];
+    } else if (arg.startsWith("--width=")) {
+      options.width = parseInt(arg.split("=")[1], 10);
+    } else if (arg.startsWith("--height=")) {
+      options.height = parseInt(arg.split("=")[1], 10);
+    } else if (arg.startsWith("--seed=")) {
+      options.seed = parseInt(arg.split("=")[1], 10);
+    } else if (arg.startsWith("--n=")) {
+      options.n = parseInt(arg.split("=")[1], 10);
+    } else if (arg === "--prompt-optimizer") {
+      options.promptOptimizer = true;
+    } else if (arg.startsWith("--output-dir=")) {
+      outputDir = arg.split("=")[1];
+    } else if (!arg.startsWith("--")) {
+      prompt = arg;
+    }
+  }
+
+  if (!prompt) {
+    console.error(
+      "usage: generate.js <prompt> --output-dir=<path> [--aspect-ratio=16:9] [--width=1024] [--height=1024] [--seed=<number>] [--n=1] [--prompt-optimizer]",
+    );
+    process.exit(1);
+  }
+
+  if (!outputDir) {
+    console.error(
+      "usage: generate.js <prompt> --output-dir=<path> [--aspect-ratio=16:9] [--width=1024] [--height=1024] [--seed=<number>] [--n=1] [--prompt-optimizer]",
+    );
+    console.error("error: --output-dir is required");
+    process.exit(1);
+  }
+
+  return { prompt, outputDir, options };
+}
+
+function buildPayload(prompt, options) {
+  const payload = {
+    model: "image-01",
+    prompt,
+    response_format: "base64",
+    n: options.n,
+    prompt_optimizer: options.promptOptimizer,
+  };
+
+  if (options.width && options.height) {
+    payload.width = options.width;
+    payload.height = options.height;
+  } else {
+    payload.aspect_ratio = options.aspectRatio;
+  }
+
+  if (options.seed !== null) {
+    payload.seed = options.seed;
+  }
+
+  return payload;
+}
+
+function main() {
+  const { prompt, outputDir, options } = parseArgs();
+
+  const apiKey = process.env.MINIMAX_API_KEY;
+  if (!apiKey) {
+    console.error("MINIMAX_API_KEY not set");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const payload = JSON.stringify(buildPayload(prompt, options));
+
+  const req = https.request(
+    {
+      hostname: "api.minimax.io",
+      port: 443,
+      path: "/v1/image_generation",
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+      },
+    },
+    (res) => {
+      if (res.statusCode && res.statusCode >= 400) {
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () => {
+          console.error(
+            `request failed with status ${res.statusCode}: ${body}`,
+          );
+          process.exit(1);
+        });
+        return;
+      }
+
+      let body = "";
+      res.on("data", (chunk) => (body += chunk));
+      res.on("end", () => {
+        const result = JSON.parse(body);
+        const images = result.data?.image_base64 || [];
+
+        for (let i = 0; i < images.length; i++) {
+          const decoded = Buffer.from(images[i], "base64");
+          const filename = generateFilename(prompt, i);
+          const outputPath = path.join(outputDir, filename);
+          fs.writeFileSync(outputPath, decoded);
+        }
+      });
+    },
+  );
+
+  req.on("error", (err) => {
+    console.error(`request failed: ${err}`);
+    process.exit(1);
+  });
+
+  req.write(payload);
+  req.end();
+}
+
+main();