/noop:entity-add - Add Domain Entity

Generate complete CRUD infrastructure for a new domain entity in an existing noop-based project.

Framework Context

Generator Instructions (FOLLOW THESE TEMPLATES)

@docs/universal-framework/GENERATOR_INSTRUCTIONS.md

Coding Conventions (NAMING & PATTERNS)

@docs/universal-framework/CONVENTIONS.md

Architecture Specification (LAYER RESPONSIBILITIES)

@docs/universal-framework/ARCHITECTURE_SPEC.md

---

What This Creates

For a new entity (e.g., Product):

1. Type definitions - src/types/product.types.ts
2. Database operations - src/db/pg/ProductOps.ts
3. HTTP handler - src/handlers/productHandler.ts
4. Migration SQL - Added to latest migration or new version
5. Route registration - Updated in src/routes.ts
6. Store registration - Updated in src/db/pg/PgClientStore.ts
7. Type exports - Updated in src/types/index.ts

Arguments

$ARGUMENTS format: <EntityName> [--fields=field1:type,field2:type]

• EntityName (required): PascalCase entity name (e.g., Product, OrderItem)
• --fields (optional): Custom fields beyond id, name, description, timestamps

Examples:

/noop:entity-add Product
/noop:entity-add Product --fields=price:number,sku:string,inStock:boolean
/noop:entity-add OrderItem --fields=quantity:number,unitPrice:number,productId:string

Naming Conventions

Input	Derived	Example
Entity name	PascalCase	Product
entityLower	camelCase	product
entityPlural	plural	products
tableName	snake_case plural	products
Type file	{entity}.types.ts	product.types.ts
Ops file	{Entity}Ops.ts	ProductOps.ts
Handler file	{entity}Handler.ts	productHandler.ts
Store property	camelCase plural	dbStore.products

Execution Steps

Step 1: Validate Project Structure

Verify this is a noop-based project by checking for:

• src/db/pg/PgClientStore.ts
• src/handlers/
• src/types/
• src/routes.ts

If missing, abort with: "This doesn't appear to be a noop project. Run /noop:make first."

Step 2: Parse Entity Information

From $ARGUMENTS, extract entity name and derive all naming variants.

Step 3: Check for Conflicts

Verify entity doesn't already exist. If exists, ask to overwrite.

Step 4: Generate Type Definitions

Create src/types/{entity}.types.ts:

export interface {Entity}Info {
  id: string
  name: string
  description?: string
  // Custom fields from --fields
  organizationId: string
  createdAt: Date
  updatedAt: Date
}

export type Create{Entity}Input = Omit<{Entity}Info, 'id' | 'organizationId' | 'createdAt' | 'updatedAt'>
export type Update{Entity}Input = Partial<Create{Entity}Input>

Step 5: Generate Database Operations

Create src/db/pg/{Entity}Ops.ts with:

• Constructor taking PgClient
• create(data, organizationId) - MUST validate organizationId
• getById(id, organizationId) - MUST filter by organizationId
• list(organizationId, options) - MUST filter by organizationId
• update(id, organizationId, data) - MUST filter by organizationId
• delete(id, organizationId) - MUST filter by organizationId
• Private mapRowTo{Entity}(row) method

CRITICAL: Every method MUST require and validate organizationId

Step 6: Generate Handler

Create src/handlers/{entity}Handler.ts with:

• create - POST handler
• get - GET /:id handler
• list - GET handler with pagination
• update - PUT /:id handler
• remove - DELETE /:id handler

All handlers MUST:

• Use asyncHandler wrapper
• Use createError factories
• Use sendSuccess / sendPaginatedResponse
• Get dbStore via getDbStore()

Step 7: Add Migration SQL

Find latest src/db/pg/migrations/sql/v*.sql and add:

CREATE TABLE {table_name} (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(255) NOT NULL,
  description TEXT,
  -- Custom fields
  organization_id UUID NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_{table_name}_organization ON {table_name}(organization_id);
CREATE INDEX idx_{table_name}_created_at ON {table_name}(created_at DESC);

Step 8: Update Registrations

Update src/db/pg/PgClientStore.ts:

• Add import
• Add property
• Add initialization in constructor

Update src/routes.ts:

• Add import
• Add all 5 CRUD routes

Update src/types/index.ts:

• Add type exports

Step 9: Verify

npm run typecheck
npm run lint

Step 10: Report Success

Entity "{Entity}" created successfully!

Files created:
- src/types/{entity}.types.ts
- src/db/pg/{Entity}Ops.ts
- src/handlers/{entity}Handler.ts

Files updated:
- src/db/pg/PgClientStore.ts
- src/routes.ts
- src/types/index.ts
- src/db/pg/migrations/sql/v0.0.X.sql

New endpoints:
- GET    /api/v1/{entities}
- POST   /api/v1/{entities}
- GET    /api/v1/{entities}/:id
- PUT    /api/v1/{entities}/:id
- DELETE /api/v1/{entities}/:id