@codyswann/lisa 1.48.0 → 1.49.0

package/plugins/lisa-nestjs/skills/nestjs-rules/SKILL.md

@@ -0,0 +1,536 @@
+---
+name: nestjs-rules
+description: Procedural rules and patterns for NestJS backend development. This skill should be used when creating new NestJS modules, services, resolvers, or controllers. It covers component generation with NestJS CLI, TDD patterns, module structure conventions, Lambda handler patterns, and configuration standards. Use this skill alongside nestjs-graphql for GraphQL-specific patterns.
+---
+
+# NestJS Development Rules
+
+## Overview
+
+This skill provides procedural rules for working with NestJS in this project. It covers component generation, testing patterns, module structure, and deployment configuration. For GraphQL-specific patterns (resolvers, types, auth decorators), use the `nestjs-graphql` skill.
+
+## Component Generation
+
+Always use NestJS CLI to create components rather than manually creating files.
+
+### Module Generation
+
+```bash
+bunx nest g module <name> --no-spec
+```
+
+### Service Generation
+
+```bash
+bunx nest g service <name> --no-spec
+```
+
+### Resolver Generation (GraphQL)
+
+```bash
+bunx nest g resolver <name> --no-spec
+```
+
+### Controller Generation (REST)
+
+```bash
+bunx nest g controller <name> --no-spec
+```
+
+### Why `--no-spec`
+
+The `--no-spec` flag is used because this project follows TDD (Test-Driven Development). Tests are written first with a custom test structure before implementation, not auto-generated by the CLI.
+
+## Database Migrations
+
+### Never Create Migration Files Manually
+
+Never create or modify a TypeORM migration file directly. Instead, use `migration:generate` from `package.json`:
+
+```bash
+bun run migration:generate
+```
+
+**Exception**: Direct modification is allowed only for changes that don't break syncing with entity files (e.g., adding indexes, comments, or non-structural changes).
+
+### Why Auto-Generation
+
+TypeORM compares your entity definitions against the current database schema to generate migrations. Manual creation can:
+- Introduce drift between entities and migrations
+- Miss important schema changes
+- Create migrations that don't match entity metadata
+
+## Test-Driven Development Pattern
+
+### Write Tests First
+
+Create test files before implementation:
+
+```typescript
+// src/feature/feature.service.test.ts
+import { Test, TestingModule } from "@nestjs/testing";
+import { FeatureService } from "./feature.service";
+
+describe("FeatureService", () => {
+  const service: FeatureService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [FeatureService],
+    }).compile();
+
+    service = module.get<FeatureService>(FeatureService);
+  });
+
+  describe("methodName", () => {
+    it("should do expected behavior", () => {
+      expect(service.methodName()).toBe("expected");
+    });
+  });
+});
+```
+
+### Test File Naming
+
+- Unit tests: `*.test.ts`
+- Integration tests: `*.integration.test.ts`
+
+### Running Tests
+
+```bash
+# Unit tests only
+bun run test:unit
+
+# Integration tests only
+bun run test:integration
+
+# All tests
+bun run test
+```
+
+## Module Structure
+
+### Feature Module Pattern
+
+```
+src/
+├── <feature>/
+│   ├── <feature>.module.ts        # Module definition
+│   ├── <feature>.service.ts       # Business logic
+│   ├── <feature>.service.test.ts  # Service unit tests
+│   ├── <feature>.resolver.ts      # GraphQL resolver (if applicable)
+│   ├── <feature>.resolver.test.ts # Resolver unit tests
+│   ├── <feature>.controller.ts    # REST controller (if applicable)
+│   ├── <feature>.controller.test.ts
+│   ├── dto/                       # Data transfer objects
+│   │   ├── create-<feature>.input.ts
+│   │   └── update-<feature>.input.ts
+│   └── entities/                  # Entity definitions
+│       └── <feature>.entity.ts
+```
+
+### Module Registration
+
+Register feature modules in `app.module.ts`:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { FeatureModule } from "./feature/feature.module";
+
+@Module({
+  imports: [
+    // ... other imports
+    FeatureModule,
+  ],
+})
+export class AppModule {}
+```
+
+## Lambda Handler Pattern
+
+### Entry Point Structure
+
+```typescript
+// src/main.ts
+import { NestFactory } from "@nestjs/core";
+import { configure as serverlessExpress } from "@vendia/serverless-express";
+import { AppModule } from "./app.module";
+
+type ServerlessHandler = ReturnType<typeof serverlessExpress>;
+
+/**
+ * Creates a lazy-initialized server getter using closure pattern
+ * @description Encapsulates mutable cache state for Lambda warm starts
+ * @returns Async function that returns the cached or newly created server
+ */
+const createServerGetter = (): (() => Promise<ServerlessHandler>) => {
+  // eslint-disable-next-line functional/no-let -- Required for Lambda warm start caching
+  let cachedServer: ServerlessHandler | null = null;
+
+  return async (): Promise<ServerlessHandler> => {
+    if (cachedServer) {
+      return cachedServer;
+    }
+
+    const nestApp = await NestFactory.create(AppModule, {
+      cors: {
+        origin: "*",
+        methods: "GET,HEAD,PUT,PATCH,POST,DELETE",
+        preflightContinue: false,
+        optionsSuccessStatus: 204,
+      },
+    });
+
+    await nestApp.init();
+    const app = nestApp.getHttpAdapter().getInstance();
+    cachedServer = serverlessExpress({ app });
+    return cachedServer;
+  };
+};
+
+const getServer = createServerGetter();
+
+/**
+ * Lambda handler function
+ * @param event - AWS Lambda event object
+ * @param context - AWS Lambda context object
+ * @returns Promise resolving to Lambda response
+ */
+export const handler = async (
+  event: unknown,
+  context: unknown
+): Promise<unknown> => {
+  const server = await getServer();
+  return server(event, context);
+};
+```
+
+### Key Lambda Concepts
+
+1. **Warm Start Caching**: Use closure pattern to cache the NestJS application between invocations
+2. **Serverless Express**: Use `@vendia/serverless-express` for Express adapter compatibility
+3. **CORS Configuration**: Configure CORS in NestFactory.create(), not in serverless.yml
+
+## Configuration Files
+
+### NestJS CLI Configuration
+
+```json
+// nest-cli.json
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}
+```
+
+### TypeScript Configuration
+
+Required settings for NestJS decorators:
+
+```json
+// tsconfig.json (additions)
+{
+  "compilerOptions": {
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "strictPropertyInitialization": false
+  }
+}
+```
+
+### Serverless Framework Configuration
+
+```yaml
+# serverless.yml
+service: project-name
+frameworkVersion: "^4.0.0"
+
+custom:
+  esbuild:
+    bundle: true
+    minify: false
+    sourcemap: true
+    keepNames: true
+    platform: node
+    target: node20
+    external:
+      - "fsevents"
+      - "@nestjs/websockets"
+      - "@nestjs/microservices"
+      - "@apollo/gateway"
+      - "@apollo/subgraph"
+      - "@as-integrations/fastify"
+      - "class-transformer/storage"
+
+plugins:
+  - serverless-esbuild
+  - serverless-offline
+
+provider:
+  name: aws
+  runtime: nodejs22.x
+  region: us-east-1
+  httpApi:
+    cors: true
+
+functions:
+  main:
+    handler: src/main.handler
+    timeout: 29
+    memorySize: 1024
+    events:
+      - httpApi:
+          method: any
+          path: /{proxy+}
+```
+
+## Documentation Standards
+
+### JSDoc for All Components
+
+Every exported function, class, and type must have JSDoc documentation:
+
+```typescript
+/**
+ * Service for managing user accounts
+ * @description Provides CRUD operations for user entities
+ * @remarks
+ * - All methods are idempotent
+ * - Throws NotFoundException for missing resources
+ */
+@Injectable()
+export class UserService {
+  /**
+   * Retrieves a user by their unique identifier
+   * @param id - The unique identifier of the user
+   * @returns The user if found, null otherwise
+   */
+  async findById(id: string): Promise<User | null> {
+    return this.repository.findOne({ where: { id } });
+  }
+}
+```
+
+### Module File Preambles
+
+Every file should have a preamble comment:
+
+```typescript
+/**
+ * @file user.service.ts
+ * @description Service providing user account management
+ * @module users
+ */
+```
+
+## DataLoader Integration
+
+### Batch Method Pattern
+
+Services that support DataLoader must implement batch methods:
+
+```typescript
+/**
+ * Batch loads entities by IDs (for DataLoader)
+ * @param ids - Array of entity IDs to load
+ * @returns Promise resolving to array of entities in same order as input
+ * @remarks Used by DataLoader for batching - maintains input order
+ */
+async findByIds(ids: readonly string[]): Promise<Entity[]> {
+  const entities = await this.repository.findBy({ id: In([...ids]) });
+  const entityMap = new Map(entities.map(e => [e.id, e]));
+  return ids.map(id => entityMap.get(id) ?? null);
+}
+```
+
+### Order Preservation
+
+Batch functions must return results in the same order as input keys. Always map input IDs to results to maintain order.
+
+## Common Patterns
+
+### Immutable Code
+
+Use `const` instead of `let` or `var`:
+
+```typescript
+// Good
+const users = await this.userService.findAll();
+const filtered = users.filter(u => u.active);
+
+// Bad
+let users = await this.userService.findAll();
+users = users.filter(u => u.active);
+```
+
+### Functional Transformations
+
+Use `reduce` instead of `push` or `pop`:
+
+```typescript
+// Good
+const userMap = users.reduce(
+  (acc, user) => ({ ...acc, [user.id]: user }),
+  {} as Record<string, User>
+);
+
+// Bad
+const userMap: Record<string, User> = {};
+users.forEach(user => {
+  userMap[user.id] = user;
+});
+```
+
+### Error Handling
+
+Use GraphQL errors with codes:
+
+```typescript
+import { GraphQLError } from "graphql";
+
+throw new GraphQLError("User not found", {
+  extensions: { code: "NOT_FOUND", id },
+});
+```
+
+## Configuration Management
+
+### Never Use process.env Directly
+
+Always use NestJS ConfigService instead of accessing `process.env` directly. This provides:
+- Type safety with full autocomplete
+- Centralized configuration management
+- Easier testing (mock ConfigService instead of environment)
+- Validation at startup
+
+### ConfigService in NestJS Context
+
+For services, resolvers, and controllers running within NestJS:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { Configuration } from "../config/configuration";
+
+@Injectable()
+export class MyService {
+  constructor(
+    private readonly configService: ConfigService<Configuration, true>
+  ) {}
+
+  someMethod(): void {
+    // Type-safe configuration access with autocomplete
+    const host = this.configService.get("database.host", { infer: true });
+    const isOffline = this.configService.get("app.isOffline", { infer: true });
+  }
+}
+```
+
+### ConfigService in Module Factories
+
+For dynamic module configuration (e.g., TypeOrmModule.forRootAsync):
+
+```typescript
+import { Module } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { Configuration } from "../config/configuration";
+
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService<Configuration, true>) =>
+        createTypeOrmOptionsFromConfigService(configService),
+    }),
+  ],
+})
+export class DatabaseModule {}
+```
+
+### Standalone Configuration (Lambda Handlers)
+
+For code running outside NestJS context (Lambda authorizers, WebSocket handlers):
+
+```typescript
+import { getStandaloneConfig } from "../../config/configuration";
+
+// Use getStandaloneConfig() for type-safe access outside NestJS
+const config = getStandaloneConfig();
+const host = config.valkey.host;
+const port = config.valkey.port;
+```
+
+### Configuration Schema
+
+All configuration is defined in `src/config/configuration.ts`:
+
+```typescript
+export interface Configuration {
+  readonly app: {
+    readonly nodeEnv: string;
+    readonly isOffline: boolean;
+  };
+  readonly database: {
+    readonly host: string;
+    readonly port: number;
+    readonly username: string;
+    readonly password: string;
+    readonly name: string;
+    // ... other database config
+  };
+  readonly valkey: {
+    readonly host: string;
+    readonly port: number;
+    readonly maxRetriesPerRequest: number;
+  };
+  // ... other configuration namespaces
+}
+```
+
+### Adding New Configuration
+
+1. Add the new property to the `Configuration` interface
+2. Add default values in the `configuration()` factory function
+3. Access via `configService.get("namespace.property", { infer: true })`
+
+### Testing with ConfigService
+
+Create mock ConfigService in tests:
+
+```typescript
+const createMockConfigService = (): ConfigService<Configuration, true> => {
+  const config = {
+    valkey: { host: "localhost", port: 6379, maxRetriesPerRequest: 3 },
+  };
+
+  return {
+    get: jest.fn((key: string) => {
+      const keys = key.split(".");
+      return keys.reduce((obj, k) => obj?.[k], config);
+    }),
+  } as unknown as ConfigService<Configuration, true>;
+};
+
+// In test setup
+const module = await Test.createTestingModule({
+  providers: [
+    MyService,
+    { provide: ConfigService, useValue: createMockConfigService() },
+  ],
+}).compile();
+```
+
+## Verification Checklist
+
+After creating or modifying NestJS components:
+
+1. **Unit tests pass**: `bun run test:unit`
+2. **Integration tests pass**: `bun run test:integration`
+3. **Linting passes**: `bun run lint`
+4. **Type check passes**: `bun run build`
+5. **Local server starts**: `bun run start:local`

package/plugins/lisa-nestjs/skills/plan-add-test-coverage/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: plan-add-test-coverage
+description: This skill should be used when increasing test coverage to a specified threshold percentage. It runs the coverage report, identifies files with the lowest coverage, generates a brief with coverage gaps, and creates a plan with tasks to add the missing tests.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Increase Test Coverage
+
+Target threshold: $ARGUMENTS%
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Find coverage config** (jest.config.js, vitest.config.ts, .nycrc, etc.)
+2. **Run coverage report** to get current state:
+   ```bash
+   bun run test:cov 2>&1 | head -100
+   ```
+3. **Identify the 20 files with lowest coverage**, noting:
+   - File path
+   - Current coverage % (lines, branches, functions)
+   - Which lines/branches are uncovered
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Increase test coverage from [current]% to $ARGUMENTS%.
+
+Files needing coverage (ordered by coverage gap):
+1. [file] - [current]% coverage (target: $ARGUMENTS%)
+   - Uncovered: [lines]
+   - Missing branch coverage: [lines]
+2. ...
+
+Configuration: [config file path], update thresholds to $ARGUMENTS%
+
+Verification: `bun run test:cov` → Expected: All thresholds pass at $ARGUMENTS%
+```
+
+Invoke `/plan-execute` with this brief to create the implementation plan.

package/plugins/lisa-nestjs/skills/plan-execute/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: plan-execute
+description: This skill should be used for any non-trivial request — features, bugs, stories, epics, spikes, or multi-step tasks. It accepts a ticket URL (Jira, Linear, GitHub), a file path containing a spec, or a plain-text prompt. It assembles an agent team, breaks the work into structured tasks, and manages the full lifecycle from research through implementation, code review, deploy, and empirical verification.
+---
+
+
+$ARGUMENTS is either a url to a ticket containing the request, a pointer to a file containing the request or the request in text format.
+
+If it's a ticket, use either the Jira CLI (if it's a jira ticket), the Linear CLI (if it's a linear ticket) or the Github CLI (if it's a github ticket) to read and fully understand the request, including any comments or meta data associated with the ticket.
+
+If it's a file, read the entire file without offset or limit to understand the request.
+
+Is this a simple request? Just execute it as usual and ignore the rest...
+
+Otherwise:
+
+
+Review all available agent types listed in the Task tool's `subagent_type` options. This includes built-in agents (like `Explore`, `general-purpose`), custom agents (from `.claude/agents/`), and plugin agents (from `.claude/settings.json` `enabledPlugins`). For each agent, explain in one sentence why it IS or IS NOT relevant to this task. Then select all agents that are relevant. You MUST justify excluding an agent — inclusion is the default.
+
+When deciding the agents to use, consider:
+* Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
+* Each task must be reviewed by the team to make sure their verification passes.
+* Each task must have their learnings reviewed by the learner subagent.
+
+NOTE: Every team must include the Explore agent
+
+Create an agent team composed of the selected agents. Spawn every agent with `mode: "plan"` so they must submit their plan for team lead approval before making any file changes.
+
+Use the TeamCreate tool to create the team before doing anything else.
+
+Using the general-purpose agent in Team Lead session, Determine the name of this plan
+
+Using the general-purpose agent in Team Lead session, Determine what branch to use:
+1. Are we already on a feature branch with an open pull request? Use that and set the target branch to the existing target of the pull request
+2. Are we on a feature branch without an open pull request? Use the branch, but ask the human what branch to target for the PR
+3. Are we on an environment branch (dev, staging, main, prod, production)? Check out a feature branch named for this plan and set the target branch of the PR to the environment branch
+
+Using the general-purpose agent in Team Lead session, Determine what type of request this is for:
+1. Informational/Spike
+2. Task
+3. Bug
+4. Feature/Story
+5. Epic
+
+IF it's a bug, Using the general-purpose agent in Team Lead session, determine how you will replicate the bug empirically:
+1. Examples:
+   1. Write a simple API client and call the offending API
+   2. Start the server on localhost and Use the Playwright CLI or Chrome DevTools
+
+Using the general-purpose agent in Team Lead session, determine how you will know that the task is fully complete
+1. Examples
+   1. Direct deploy the changes to dev and then Write a simple API client and call the offending API
+   2. Start the server on localhost and then Use the Playwright CLI or Chrome DevTools
+
+Using the general-purpose agent in Team Lead session, create tasks needed to complete the request.
+
+Every task MUST include this JSON metadata block. Do NOT omit `skills` (use `[]` if none), `learnings` (use `[]` if none) or `verification`.
+
+```json
+{
+  "plan": "<plan-name>",
+  "type": "spike|bug|task|epic|story",
+  "acceptance_criteria": ["..."],
+  "relevant_documentation": "",
+  "testing_requirements": ["..."],
+  "skills": ["..."],
+  "learnings": ["..."],
+  "verification": {
+    "type": "test|ui-recording|test-coverage|api-test|manual-check|documentation",
+    "command": "the proof command",
+    "expected": "what success looks like"
+  }
+}
+```
+
+Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
+
+Each task must be reviewed by the team to make sure their verification passes.
+Each task must have their learnings reviewed by the learner subagent.
+
+Before shutting down the team:
+
+1. Commit ALL outstanding changes in logical batches on the branch (minus sensitive data/information) — not just changes made by the agent team. This includes pre-existing uncommitted changes that were on the branch before the plan started. Do NOT filter commits to only "task-related" files. If it shows up in git status, it gets committed (unless it contains secrets).
+2. Push the changes - if any pre-push hook blocks you, create a task for the agent team to fix the error/problem whether it was pre-existing or not
+3. Open a pull request with auto-merge on
+4. Monitor the PR. Create a task for the agent team to resolve any code review comments by either implementing the suggestions or commenting why they should not be implemented and close the comment. Fix any failing checks and repush. Continue all checks pass
+5. Monitor the deploy action that triggers automatically from the successful merge
+6. If it fails, create a task for the agent team to fix the failure, open a new PR and then go back to step 4
+7. Execute empirical verification. If empirical verification succeeds, you're finished, otherwise, create a task for the agent team to find out why it failed, fix it and return to step 1 (repeat this until you get all the way through)