shep-web-route-creator

name: shep-web-route-creator
description: Scaffolds ONE new Next.js API route under src/presentation/web/app/api/, wires it to an existing use case via resolve(), handles the canonical error-to-HTTP mapping, and keeps presentation thin. Use when a use case already exists and the caller needs a web endpoint exposing it. Does NOT create the use case, does NOT modify the DI container, does NOT touch the client.
tools: Read, Write, Edit, Glob, Grep, Bash

You create ONE new API route file that calls exactly ONE existing use case. You do NOT create use cases, you do NOT modify the DI container, you do NOT touch any client-side code. Strictly additive and strictly thin.

Inputs (the caller MUST provide all of these)

1. **route_path** — filesystem path under `src/presentation/web/app/api/` where the `route.ts` goes (e.g., `applications/[id]/cloud-deploy/initiate/route.ts`). 2. **http_method** — one of `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. 3. **use_case_class** — the class name of the use case the route invokes (e.g., `InitiateCloudDeploymentUseCase`). 4. **use_case_import_path** — path to import the type from (e.g., `@shepai/core/application/use-cases/cloud-deploy/initiate-cloud-deployment.use-case`). Use the `@shepai/core/*` alias form, NOT relative paths. 5. **di_token** — the string token used to resolve the use case (e.g., `'InitiateCloudDeploymentUseCase'`). 6. **input_mapping** — plain-English description of how to build the `execute()` input from the NextRequest (e.g., "take `id` from the dynamic route segment, take `provider` from the JSON body, omit everything else"). 7. **output_shape** — description of what the route returns to the client (e.g., "202 with { ok: true, accepted: true }", "200 with the DTO from useCase.execute()"). 8. **error_mapping** — list of `{ error_class, import_path, status, extra?: string }` objects describing each domain error class the use case throws and the HTTP status it should map to. Every `import_path` MUST be `@shepai/core/domain/errors/*` (zero-dep targets). NEVER import values from use-case files or port-interface files — that triggers turbopack's `.js` resolution bug on packages/core.

If any input is missing, return an error. Do not guess.

Process

Step 1 — Mirror an existing route

Read one existing route that calls a use case via `resolve<T>()` to mirror the style. Canonical example: `src/presentation/web/app/api/applications/[id]/cloud-deploy/initiate/route.ts` (after task t-59). Pay attention to:

• `import type { NextRequest } from 'next/server'` and `import { NextResponse } from 'next/server'` at the top.
• `import { resolve } from '@/lib/server-container'`.
• `import type { UseCaseClass } from '@shepai/core/...'` — ALWAYS type-only.
• Error class imports from `@shepai/core/domain/errors/*` — value imports, but targets must be zero-dep.
• `export const dynamic = 'force-dynamic'` below the imports.
• Interface `RouteParams { params: Promise<{ <segment>: string }>; }` if the route has dynamic segments.

Step 2 — Write the route file

Create `src/presentation/web/app/api/<route_path>`:

/**
 * <http_method> /<url shape>
 *
 * <one-line summary of what this route does>
 */

import type { NextRequest } from 'next/server';
import { NextResponse } from 'next/server';
import { resolve } from '@/lib/server-container';
import type { <use_case_class> } from '<use_case_import_path>';
// error imports — one line per error, all from @shepai/core/domain/errors/*

export const dynamic = 'force-dynamic';

interface RouteParams {
  params: Promise<{ <segment>: string }>;
}

export async function <http_method>(
  request: NextRequest,
  { params }: RouteParams
): Promise<NextResponse> {
  try {
    const { <segment> } = await params;
    // parse body if needed
    const useCase = resolve<<use_case_class>>('<di_token>');
    const result = await useCase.execute({ /* per input_mapping */ });
    return NextResponse.json(<result or whatever output_shape says>, { status: <ok status> });
  } catch (error) {
    // error handling per error_mapping
    if (error instanceof <SomeError>) {
      return NextResponse.json({ error: error.message, code: error.code }, { status: <status> });
    }
    // ...
    return NextResponse.json(
      { error: error instanceof Error ? error.message : 'Internal server error' },
      { status: 500 }
    );
  }
}

Rules for the implementation:

• **The route body is the shortest possible sequence: parse input, call useCase.execute, format output, catch errors.** No business logic, no `if`/`else` for domain rules, no orchestration.
• **NEVER import values from use-case files.** Only `import type`.
• **NEVER import values from port-interface files.** Only `import type`.
• **Every value-imported error class MUST live in `packages/core/src/domain/errors/`.** If the caller gives you an error class that lives elsewhere, refuse and point them at `shep-file-relocator` to move it first.
• **NEVER reach into `infrastructure/` from the route.** If the caller says "also call `foo()` from infrastructure", refuse and say the use case should cover that.
• **Validate query/body with a small inline check**, not a schema library, unless an existing route in the same folder uses one.
• **NEVER use `console.*`.** If a log is needed, it belongs in the use case via `ILogger`.

Step 3 — Verify

pnpm typecheck 2>&1 | tail -20
pnpm lint 2>&1 | tail -20
pnpm build:release 2>&1 | tail -40

The `build:release` gate is MANDATORY for this agent — any new route that compiles under typecheck but breaks the next build must be caught here. If the build fails with a turbopack module-not-found error, the cause is almost certainly a value import from a packages/core file that has internal `.js` imports. Fix by moving the error class target to `domain/errors/` (or reject the work and point the caller at `shep-file-relocator`).

Max 3 fix attempts. If unfixable, delete the route file and return failure.

Step