create-nestjs-sandbox

name	create-nestjs-sandbox
description	Generates containerized NestJS sandbox services from API request/response samples. Creates in-memory endpoints organized by dynamically identified controllers with sandbox lifecycle management. Use when building mock API services or creating sandbox environments from sample data.

Generates production-ready NestJS sandbox services from API request/response samples. Creates containerized services with in-memory storage, controller-based architecture, and Swagger documentation. Enables rapid API mocking for testing, demos, and development without backend dependencies.

<quick_start>

1. Provide API request/response data (file path, directory, or inline text)
2. Specify output directory (defaults to ./sandbox-service/)
3. Skill parses URLs into {api}/{controller}/{action} segments, generates NestJS modules, DTOs, and Docker files
4. If URL segments are ambiguous, the skill asks you to clarify which segment is which
5. Runs npm install && npm run build to verify
6. Provides run commands and Swagger URL at /api </quick_start>

<essential_principles>

Sandbox Isolation - Each sandbox (by sandboxId) maintains isolated in-memory data. Sandboxes do not share state.

Data Fidelity - Preserve exact field names, types, and nesting in per-endpoint response DTOs. Each endpoint's response DTO must match its actual API response structure exactly — no fields from other endpoints. Entity interfaces are internal superset types and may differ from any individual API response shape. DTOs are inferred from response JSON structures, with null values flagged for type verification.

Controller-Based Organization - URLs are parsed into {api}/{controller}/{action} segments. Each unique controller value gets its own NestJS module (controller, service, DTOs). When URL segments are ambiguous, ask the user for clarification using AskUserQuestion.

Entity-Based Data Model - Instead of storing static responses per endpoint, identify the domain entities from the API data dynamically. Entity types are NOT predetermined — they are discovered by analyzing recurring identifiers across request parameters and response fields. Determine the root entity (the one others relate to) and model relationships. The in-memory store holds entities, and controller services query entities to dynamically construct API responses. This enables realistic behavior like searching, filtering, and cross-entity lookups. See references/entity-model.md for the full entity identification and modeling process.

Metadata-Driven Relationships - Alongside the EntityStore, each sandbox maintains a SandboxMetadata object with three dynamic structures: (1) parentChildRelations — a Map keyed by root entity key, mapping to a Record of child entity type → child key arrays, (2) typeGroupings — a Record keyed by entity type name, each mapping entity keys to their type/category info, and (3) preComputedViews — a Record keyed by a view name, each mapping entity keys to pre-computed response fragments for aggregation endpoints. These structures are built dynamically based on whatever entities are discovered in the API data. Controller services use metadata for efficient cross-entity lookups and product grouping. Metadata is internal-only and NOT included in serialized API responses.

</essential_principles>

<sandbox_management_api> Every generated service includes a sandbox controller at /sandboxes:

• POST /sandboxes - Create sandbox with seed data. Accepts optional sandboxId in the request body; if provided, uses it as the sandbox identifier, otherwise generates a UUID.
• GET /sandboxes/:sandboxId - Get sandbox config and data models
• PUT /sandboxes/:sandboxId - Update sandbox endpoints or data
• DELETE /sandboxes/:sandboxId - Delete sandbox

Controller endpoints live under /sandbox/:sandboxId/{controller}/{action}. </sandbox_management_api>

<input_formats> Accepted API data formats:

• File path - Text file with URL + request + response blocks
• Directory path - Directory of API data files
• Inline data - Raw API data pasted in conversation

Output directory defaults to ./sandbox-service/ if not specified. </input_formats>

Follow `workflows/generate-service.md` to parse API data and generate the complete NestJS sandbox service. - references/data-parsing.md - Parse API URLs into `{api}/{controller}/{action}`, extract DTOs, handle ambiguity - references/entity-model.md - Entity identification, relationship mapping, entity store design, response builders - references/sandbox-architecture.md - NestJS module structure, in-memory storage patterns - references/docker-setup.md - Dockerfile, docker-compose patterns - templates/project-scaffold.md - package.json, tsconfig.json, nest-cli.json - templates/main-ts.md - main.ts with Swagger setup, app.module.ts - templates/sandbox-module.md - Sandbox management module (controller, service, DTOs) - templates/controller-module.md - Controller-specific module pattern (controller, service, DTOs) - templates/docker.md - Dockerfile + docker-compose.yml

<success_criteria> The skill is successful when:

• URLs are correctly parsed into {api}/{controller}/{action} segments (ambiguities resolved with user)
• Domain entities are dynamically identified with their primary keys and relationships (root entity confirmed with user)
• Generated service correctly implements all controllers and endpoints from input data
• Sandbox CRUD operations are functional at /sandboxes endpoints
• Entity store holds normalized entities, and controllers query entities to build responses dynamically
• Metadata dynamically tracks parent-child relations, type groupings, and pre-computed views for whatever entities were discovered
• Controller endpoints support realistic behavior (search, filter, cross-entity lookups) based on request parameters and metadata
• Per-endpoint response DTOs accurately match the specific endpoint's API response structure (no phantom fields from other endpoints)
• Request DTOs accurately match provided API request structures with Swagger decorators
• Fields with null values in samples are flagged with TODO comments for type verification
• Docker containerization is ready for deployment
• Swagger documentation is accessible at /api </success_criteria>