@codyswann/lisa 1.47.1 → 1.49.0

package/plugins/src/expo/skills/testing-library/references/query-priority.md

@@ -0,0 +1,291 @@
+# Query Priority Guide
+
+This reference provides detailed guidance on selecting the appropriate query for each testing scenario.
+
+## Priority Order
+
+The Testing Library team recommends queries in this priority order, based on how accessible they are to users and assistive technologies.
+
+### Priority 1: getByRole
+
+`getByRole` queries elements by their ARIA role, which is the primary way screen readers identify elements. This should be the default query for almost everything.
+
+```typescript
+// Buttons
+screen.getByRole("button", { name: "Submit" });
+screen.getByRole("button", { name: /save/i }); // Case-insensitive regex
+
+// Headings
+screen.getByRole("heading", { name: "Welcome" });
+screen.getByRole("heading", { level: 1 }); // h1
+screen.getByRole("heading", { level: 2, name: "Details" }); // h2 with name
+
+// Links
+screen.getByRole("link", { name: "View Profile" });
+
+// Form elements
+screen.getByRole("textbox"); // Input without specific type
+screen.getByRole("textbox", { name: "Email" }); // With accessible name
+screen.getByRole("checkbox", { name: "Accept terms" });
+screen.getByRole("radio", { name: "Option A" });
+screen.getByRole("combobox"); // Select/dropdown
+screen.getByRole("switch"); // Toggle switch
+
+// Status elements
+screen.getByRole("alert"); // Alert messages
+screen.getByRole("progressbar"); // Loading indicators
+screen.getByRole("status"); // Status updates
+
+// Navigation
+screen.getByRole("navigation");
+screen.getByRole("menu");
+screen.getByRole("menuitem", { name: "Settings" });
+
+// Tables
+screen.getByRole("table");
+screen.getByRole("row");
+screen.getByRole("cell", { name: "John Doe" });
+
+// Dialogs
+screen.getByRole("dialog");
+screen.getByRole("alertdialog");
+```
+
+#### Role Options
+
+```typescript
+// Filter by state
+screen.getByRole("button", { name: "Submit", disabled: true });
+screen.getByRole("checkbox", { checked: true });
+screen.getByRole("option", { selected: true });
+screen.getByRole("textbox", { busy: true });
+
+// Filter by expanded state (accordion, dropdown)
+screen.getByRole("button", { expanded: true });
+screen.getByRole("button", { expanded: false });
+
+// Filter by pressed state (toggle buttons)
+screen.getByRole("button", { pressed: true });
+```
+
+#### When getByRole Works with Split Text
+
+```typescript
+// Component with split text:
+// <Button><Icon /> Submit Form</Button>
+
+// This fails - text is split by Icon
+screen.getByText("Submit Form"); // Fails!
+
+// This works - queries by accessible name
+screen.getByRole("button", { name: /submit form/i }); // Works!
+```
+
+### Priority 2: getByLabelText
+
+Use for form fields that have associated labels. This is how users identify form inputs.
+
+```typescript
+// Standard label association
+// <label htmlFor="email">Email Address</label>
+// <input id="email" />
+screen.getByLabelText("Email Address");
+
+// Aria-labelledby
+// <span id="label-1">Username</span>
+// <input aria-labelledby="label-1" />
+screen.getByLabelText("Username");
+
+// Aria-label
+// <input aria-label="Search" />
+screen.getByLabelText("Search");
+
+// Case-insensitive matching
+screen.getByLabelText(/email/i);
+
+// Exact match
+screen.getByLabelText("Email", { exact: true });
+```
+
+### Priority 3: getByPlaceholderText
+
+Use when a form field has placeholder text but no visible label. Note: Placeholders are not a substitute for labels.
+
+```typescript
+// <input placeholder="Enter your email" />
+screen.getByPlaceholderText("Enter your email");
+screen.getByPlaceholderText(/email/i);
+```
+
+### Priority 4: getByText
+
+Use for non-interactive content like paragraphs, spans, and div text.
+
+```typescript
+// Static text content
+screen.getByText("Welcome to our app");
+screen.getByText(/welcome/i); // Case-insensitive
+
+// Partial matching
+screen.getByText("Welcome", { exact: false });
+
+// Custom normalizer (for whitespace issues)
+screen.getByText("Hello World", {
+  normalizer: str => str.replace(/\s+/g, " ").trim(),
+});
+```
+
+### Priority 5: getByDisplayValue
+
+Use for inputs with visible values (like filled form fields).
+
+```typescript
+// <input value="john@example.com" />
+screen.getByDisplayValue("john@example.com");
+
+// Select with selected option
+screen.getByDisplayValue("United States");
+```
+
+### Priority 6: getByAltText
+
+Use for images and elements with alt text.
+
+```typescript
+// <img alt="User avatar" src="..." />
+screen.getByAltText("User avatar");
+screen.getByAltText(/avatar/i);
+```
+
+### Priority 7: getByTitle
+
+Use for elements with title attribute. Less common in React Native.
+
+```typescript
+// <span title="Close">X</span>
+screen.getByTitle("Close");
+```
+
+### Priority 8: getByTestId (Last Resort)
+
+Use only when semantic queries are not possible. Adding unnecessary test IDs clutters components.
+
+```typescript
+// <View testID="custom-component">...</View>
+screen.getByTestId("custom-component");
+```
+
+#### Valid Use Cases for getByTestId
+
+1. Dynamic content that changes frequently
+2. Elements without semantic meaning
+3. Container elements that group other elements
+4. Canvas or custom drawing components
+
+```typescript
+// Valid: Dynamic chart container
+screen.getByTestId("chart-container");
+
+// Valid: Animation container
+screen.getByTestId("animation-wrapper");
+
+// Invalid: Button (use getByRole)
+screen.getByTestId("submit-button"); // Don't do this
+```
+
+## React Native Specific Roles
+
+React Native components map to accessibility roles:
+
+| Component          | Accessible Role    | Query Example                          |
+| ------------------ | ------------------ | -------------------------------------- |
+| `Button`           | `button`           | `getByRole("button")`                  |
+| `Text`             | `text`             | `getByRole("text")`                    |
+| `TextInput`        | `textbox`          | `getByRole("textbox")`                 |
+| `Switch`           | `switch`           | `getByRole("switch")`                  |
+| `Image`            | `image`            | `getByRole("image")` or `getByAltText` |
+| `Pressable`        | Depends on content | Set `accessibilityRole` explicitly     |
+| `TouchableOpacity` | Depends on content | Set `accessibilityRole` explicitly     |
+
+### Setting Explicit Roles
+
+```tsx
+// Pressable as a button
+<Pressable accessibilityRole="button" accessibilityLabel="Save">
+  <Text>Save</Text>
+</Pressable>
+
+// Custom checkbox
+<Pressable
+  accessibilityRole="checkbox"
+  accessibilityState={{ checked: isChecked }}
+  accessibilityLabel="Accept terms"
+>
+  <CheckIcon />
+</Pressable>
+
+// Link
+<Pressable accessibilityRole="link" accessibilityLabel="View profile">
+  <Text>Profile</Text>
+</Pressable>
+```
+
+## Common Mistakes
+
+### Using getByTestId When Semantic Query Works
+
+```typescript
+// Wrong
+screen.getByTestId("login-button");
+
+// Correct
+screen.getByRole("button", { name: "Login" });
+```
+
+### Using getByText for Interactive Elements
+
+```typescript
+// Wrong - getByText works but doesn't verify accessibility
+screen.getByText("Submit");
+
+// Correct - verifies element is actually a button
+screen.getByRole("button", { name: "Submit" });
+```
+
+### Case Sensitivity Issues
+
+```typescript
+// May fail if case doesn't match
+screen.getByText("Submit");
+
+// More robust - case insensitive
+screen.getByRole("button", { name: /submit/i });
+```
+
+### Querying Hidden Elements
+
+```typescript
+// By default, queries ignore hidden elements
+screen.getByRole("button", { name: "Submit" });
+
+// To include hidden elements
+screen.getByRole("button", { name: "Submit", hidden: true });
+```
+
+## Query Decision Tree
+
+1. Is it an interactive element (button, link, input)?
+   - Yes → Use `getByRole`
+2. Is it a form field with a label?
+   - Yes → Use `getByLabelText`
+3. Is it a form field with only placeholder?
+   - Yes → Use `getByPlaceholderText`
+4. Is it static text content?
+   - Yes → Use `getByText`
+5. Is it an image?
+   - Yes → Use `getByAltText`
+6. Does it have a value?
+   - Yes → Use `getByDisplayValue`
+7. None of the above?
+   - Consider if the component is accessible
+   - If not fixable, use `getByTestId` as last resort

package/plugins/src/nestjs/.claude-plugin/plugin.json

@@ -0,0 +1,86 @@
+{
+  "name": "nestjs",
+  "version": "1.0.0",
+  "description": "Claude Code governance plugin for NestJS/GraphQL projects — includes all universal skills, agents, hooks, and rules from Lisa plus NestJS-specific tooling (GraphQL, TypeORM, security scanning)",
+  "author": "Cody Swann",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "find ${CLAUDE_PLUGIN_ROOT}/rules -name '*.md' -exec cat {} \\;"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforce-plan-rules.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code user-prompt-submit || true"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/format-on-edit.sh" },
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sg-scan-on-edit.sh" },
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lint-on-edit.sh" }
+        ]
+      },
+      {
+        "matcher": "TaskCreate|TaskUpdate",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sync-tasks.sh" }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          { "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code post-task || true" }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          { "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code post-todo || true" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          { "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code pre-task || true" }
+        ]
+      }
+    ],
+    "Stop": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/verify-completion.sh" }] },
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/notify-ntfy.sh" }] },
+      { "matcher": "", "hooks": [{ "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code stop || true" }] }
+    ],
+    "SessionStart": [
+      { "matcher": "startup", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/install-pkgs.sh" }] },
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/setup-jira-cli.sh" }] },
+      { "matcher": "", "hooks": [{ "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code session-start || true" }] }
+    ],
+    "SessionEnd": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code session-end || true" }] }
+    ]
+  }
+}

package/plugins/src/nestjs/skills/nestjs-graphql/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: nestjs-graphql
+description: Comprehensive guide for NestJS GraphQL development using Apollo and code-first approach. This skill should be used when writing GraphQL resolvers, mutations, queries, types, subscriptions, or implementing advanced features like field middleware, complexity limits, and custom scalars. Also covers project-specific patterns including zero-trust auth decorators and DataLoader integration.
+---
+
+# NestJS GraphQL Development Guide
+
+## Overview
+
+This skill provides comprehensive guidance for building GraphQL APIs with NestJS using Apollo Server and the code-first approach. It covers official NestJS GraphQL patterns plus project-specific implementations for authentication, authorization, and data loading.
+
+## When to Use This Skill
+
+- Writing new GraphQL resolvers, queries, or mutations
+- Creating GraphQL object types, input types, or enums
+- Implementing field resolvers or computed fields
+- Adding subscriptions for real-time updates
+- Configuring query complexity limits
+- Creating custom scalars or field middleware
+- Implementing authentication/authorization on GraphQL operations
+- Setting up DataLoader for N+1 prevention
+
+## Quick Reference
+
+### Core Decorators
+
+| Decorator | Purpose | Import |
+|-----------|---------|--------|
+| `@Resolver()` | Define resolver class | `@nestjs/graphql` |
+| `@Query()` | Define query operation | `@nestjs/graphql` |
+| `@Mutation()` | Define mutation operation | `@nestjs/graphql` |
+| `@Args()` | Extract arguments | `@nestjs/graphql` |
+| `@Context()` | Access GraphQL context | `@nestjs/graphql` |
+| `@Parent()` | Access parent in field resolver | `@nestjs/graphql` |
+| `@ResolveField()` | Define field resolver | `@nestjs/graphql` |
+| `@ObjectType()` | Define GraphQL object type | `@nestjs/graphql` |
+| `@InputType()` | Define GraphQL input type | `@nestjs/graphql` |
+| `@Field()` | Define field on type | `@nestjs/graphql` |
+| `@Extensions()` | Attach metadata to fields | `@nestjs/graphql` |
+
+### Type Decorators
+
+| Decorator | GraphQL Type | TypeScript Type |
+|-----------|-------------|-----------------|
+| `@Field(() => String)` | "String!" | `string` |
+| `@Field(() => Int)` | "Int!" | `number` |
+| `@Field(() => Float)` | "Float!" | `number` |
+| `@Field(() => Boolean)` | "Boolean!" | `boolean` |
+| `@Field(() => ID)` | "ID!" | `string` |
+| `@Field(() => [String])` | "[String!]!" | `string[]` |
+| `@Field({ nullable: true })` | `String` | `string \| null` |
+
+## Code-First Patterns
+
+### Basic Resolver Structure
+
+```typescript
+import { Args, Context, Mutation, Query, Resolver } from "@nestjs/graphql";
+import { Public, Authed } from "../auth";
+
+@Resolver(() => Entity)
+export class EntityResolver {
+  constructor(private readonly entityService: EntityService) {}
+
+  @Query(() => Entity, { description: "Retrieve entity by ID" })
+  @Authed()
+  async entity(@Args("id", { type: () => ID }) id: string): Promise<Entity> {
+    return this.entityService.findById(id);
+  }
+
+  @Mutation(() => Entity, { description: "Create new entity" })
+  @Authed()
+  async createEntity(
+    @Args("input") input: CreateEntityInput,
+    @Context() { req }: GraphQLContext
+  ): Promise<Entity> {
+    return this.entityService.create(input, req.user.id);
+  }
+}
+```
+
+### Object Type Definition
+
+```typescript
+import { Field, ID, ObjectType } from "@nestjs/graphql";
+
+@ObjectType({ description: "Represents a user in the system" })
+export class User {
+  @Field(() => ID, { description: "Unique identifier" })
+  id: string;
+
+  @Field(() => String, { description: "User's email address" })
+  email: string;
+
+  @Field(() => String, { nullable: true, description: "Display name" })
+  displayName?: string;
+
+  @Field(() => Date, { description: "Account creation timestamp" })
+  createdAt: Date;
+}
+```
+
+### Input Type Definition
+
+```typescript
+import { Field, InputType } from "@nestjs/graphql";
+
+@InputType({ description: "Input for creating a new user" })
+export class CreateUserInput {
+  @Field(() => String, { description: "User's email address" })
+  email: string;
+
+  @Field(() => String, { description: "User's password" })
+  password: string;
+
+  @Field(() => String, { nullable: true, description: "Optional display name" })
+  displayName?: string;
+}
+```
+
+## References
+
+This skill includes detailed reference files for specific topics:
+
+### references/quick-start.md
+Setup and configuration for NestJS GraphQL with Apollo driver, module configuration, and code-first vs schema-first approaches.
+
+### references/resolvers-mutations.md
+Comprehensive guide to writing resolvers, queries, mutations, field resolvers, and using decorators like @Args, @Context, @Parent.
+
+### references/types-scalars.md
+Creating object types, input types, enums, interfaces, unions, and custom scalars. Includes mapped types (PartialType, PickType, etc.).
+
+### references/advanced-features.md
+Field middleware, query complexity, plugins, subscriptions, and extensions.
+
+### references/project-patterns.md
+Project-specific patterns including zero-trust auth decorators (@Public, @Authed, @Owner, @Groups), DataLoader integration, and GraphQL documentation standards.
+
+## Common Tasks
+
+### Adding a New Query
+
+1. Add method to resolver with `@Query()` decorator
+2. Add auth decorator (`@Public()`, `@Authed()`, or `@Groups()`)
+3. Define return type in decorator: `@Query(() => ReturnType)`
+4. Add description: `@Query(() => ReturnType, { description: "..." })`
+5. Use `@Args()` for parameters with descriptions
+
+### Adding a New Mutation
+
+1. Add method to resolver with `@Mutation()` decorator
+2. Add auth decorator (mutations typically use `@Authed()`)
+3. Create InputType for complex inputs
+4. Access user context via `@Context() { req }: GraphQLContext`
+
+### Adding Field Resolver
+
+```typescript
+@ResolveField(() => [Comment], { description: "Entity's comments" })
+async comments(
+  @Parent() entity: Entity,
+  @Context() { loaders }: GraphQLContext
+): Promise<Comment[]> {
+  return loaders.commentsLoader.load(entity.id);
+}
+```
+
+### Adding DataLoader for New Entity
+
+1. Add batch method to service: `getByIds(ids: string[]): Promise<Entity[]>`
+2. Add loader type to `IDataLoaders` interface
+3. Create loader in `DataLoaderService.getLoaders()`
+4. Use in resolver: `loaders.entityLoader.load(id)`
+
+See `references/project-patterns.md` for detailed DataLoader patterns.