The-transit-Project/.github/agents/azure-debug-plan/references/plan-template.md

<!-- azure-cor-disclaimer -->
> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.

# Plan Template

> Generate `.azure/vscode-debug-plan.md` using this template. This file is the
> **single source of truth** for the generation phase. The generation phase reads this plan and
> generates all artifacts from it — no re-scanning of the workspace is needed.
>
> The plan is generated directly from the workspace scan. The user reviews the plan,
> edits it as needed, then approves it before generation proceeds.

## ⛔ BLOCKING REQUIREMENT

You **MUST** create this plan file and get user approval BEFORE generating any configuration files.

---

## Markdown Table Integrity

When editing markdown tables with `replace_string_in_file` or `multi_replace_string_in_file`, always **read the file back** after the edit and verify that each table row is on its own line. Markdown tables require exactly one row per line — a missing newline between `|---|` and `| data |` breaks parsing completely.

**Post-edit verification rule:** After any edit to `.azure/vscode-debug-plan.md` that modifies a table, immediately read the affected lines back to confirm the table renders correctly (header, separator, and each data row on separate lines). If rows are concatenated, fix before proceeding.

---

## ⚠️ Mermaid Label Quoting — ALWAYS Quote Every Label

In the `## Architecture Diagram` mermaid block, **every node label and every edge label MUST be wrapped in double quotes.** This rule is unconditional — quote every label, every time, even when it looks harmless.

```mermaid
graph LR
    %% ✅ CORRECT — every label quoted
    API["Commerce API<br/>Azure Functions :7071"] -->|"@azure/storage-blob"| AZ["Azurite<br/>:10000"]
    API -->|"pg"| PG[("PostgreSQL<br/>:5432")]

    %% ❌ WRONG — unquoted labels; the leading @ is a parse error
    %% API[Commerce API<br/>Azure Functions :7071] -->|@azure/storage-blob| AZ[Azurite]
```

**Why:** mermaid v11 uses `@` for edge-ID (`e1@-->`) and node-metadata (`id@{ shape: ... }`) syntax, so an `@` at the **start** of an unquoted label is lexed as a link ID and the whole diagram fails to parse with `Expecting 'AMP', 'COLON', ... got 'LINK_ID'`. Scoped npm package names (`@azure/storage-blob`, `@azure/identity`, `@prisma/client`) are the most common trigger, and they are exactly what shows up in Azure dependency edge labels. The debug-plan webview renders this block with mermaid — a parse error replaces the diagram with a raw `mermaid (error)` code block.

Quoting is always valid in mermaid and also protects labels containing `(`, `)`, `:`, `-`, `/`, `#`, or `·`. Do **not** try to detect which labels are "risky" — just quote all of them.

---

## Template

````markdown
# Azure Debug Plan

> This plan is the source of truth for generating the
> VS Code debug setup in this workspace.
>
> **Status:** {Planning | Approved | Executing | Implemented}
> **Execution Mode:** {Auto | Guided}
> **Created:** {ISO-8601 datetime}
> **Last Updated:** {ISO-8601 datetime}
>
> <!-- Guided Mode (default) - hand-holds the user through review and approval before generating. -->
> <!-- Auto Mode (aka YOLO mode) — skips approval gates and runs generation unattended. -->

---

## Prerequisites

<!-- All required tools and VS Code extensions with install status — list both the Run and Debug tool sets defined in prerequisites.md. -->
<!-- Service(s): the service(s) that need the tool (e.g. `api`, `worker`); use `*` for global toolchain shared by all services. -->
<!-- Installed/Version come from the detection pass and must be re-run whenever the whole plan is (re)generated or the tool set changes — never leave a placeholder. Installed is only ✅ (found) or ❓ (couldn't confirm). ❓ is informational — it just prompts the user to double-check the tool is installed. -->
<!-- Do NOT add an Install column or any install links/URLs. The plan webview appends an Install link deterministically from a built-in catalog keyed on the tool name; links authored here are ignored. -->

| Tool / Extension | Category | Service(s) | Installed | Version |
|------------------|----------|------------|-----------|---------|
| {name} | {Runtime / Package manager / …} | {service(s) or *} | {✅/❓} | {version or —} |

> ⚠️ **Action required:** Confirm any tool or extension marked ❓ is installed and ready before approving this plan — rerun the recheck to confirm CLI tools provided by a version manager.

---

## Debug Configurations

<!-- One row per detected service root. Each row maps to a VS Code debug configuration in launch.json. -->
<!-- The generation phase loads project-types.md and runtimes.md based on these values. -->
<!-- Services with Generate = No are excluded from all generation but shown for reference. -->
<!-- Azure Dependencies drive emulator matching — see Emulators section. -->
<!-- Debug Config Name is the VS Code debug configuration display name shown in the Run & Debug dropdown. -->
<!-- For multi-service workspaces, include a compound debug config row at the end. -->
<!-- ✏️ User can edit: Generate (check/uncheck), Debug Config Name -->

Each checked row below produces a VS Code debug configuration in the `.vscode/launch.json`.

| Generate | Debug Config Name | Service Label | Service Root | Project Type | Runtime | Version | Azure Dependencies |
|----------|--------------------|---------------|--------------|--------------|---------|---------|-----|
| {[x] / [ ]} | {e.g. Payments API (debug)} | {label} | {path} | {type} | {runtime} | {version} | {comma-separated azure service labels} |

<!-- Example: -->
<!-- | [x] | Payments API (debug) | Payments API | ./api | functions | node-ts | 20.x | Azure Storage, Azure PostgreSQL | -->
<!-- | [x] | Customer Portal (debug) | Customer Portal | ./web | frontend-spa | node-ts | 20.x | — | -->
<!-- | [x] | Debug All Services | Debug All Services | | *Compound Config* |||| -->

<!-- Project Type descriptions are shown in a collapsible block so the table stays compact. -->
<!-- Only include project types that appear in the table above. -->

<details>
<summary>ℹ️ Project Type Descriptions</summary>

| Project Type | Description |
|-------------|-------------|
| {type} | {brief description of what this project type means} |

<!-- Example: -->
<!-- | functions | Azure Functions — serverless compute with triggers and bindings | -->
<!-- | frontend-spa | Single-page application served by a dev server (Vite, Next.js, Angular, etc.) | -->
<!-- | app-service | HTTP server application (Express, Fastify, Flask, ASP.NET, Spring Boot, etc.) | -->
<!-- | container-app | Containerized application running via Dockerfile | -->

</details>

<!-- If a frontend SPA has a proxy config pointing to a local backend, add a note: -->
<!-- > ℹ️ **Proxy detected:** Customer Portal proxies requests to Payments API (via `vite.config.ts`). The compound config should start backends before frontends. -->

---

## Orchestrator

<!-- Records the container runtime and Compose provider used to run the emulator containers. -->
<!-- Container Runtime is Docker, Podman, or "Podman (Docker-compatible)"; Compose Command is the CLI the generation phase writes into every emulator task (`docker compose` or `podman compose`). -->
<!-- Detected from the workspace (e.g. an existing docker-compose.yml) and the container-runtime detection pass in prerequisites.md. -->
<!-- Prefer the Podman engine when it's detected as ready (native Podman, else Podman via Docker's socket), even if Docker is too; otherwise Docker. If no runtime is detected, default to Docker Compose (Docker). The generated compose file is identical for every case. -->
<!-- Docker-compatibility mode: when `docker`/`docker compose` is backed by the Podman engine, record Container Runtime = "Podman (Docker-compatible)" but keep Compose Command = `docker compose` — that's the command that talks to the Docker-compatible socket. -->
<!-- ✏️ User can edit: Container Runtime / Compose Command (to switch engines, e.g. Docker → Podman) -->

| Orchestrator | Container Runtime | Compose Command | Description |
|-------------|-------------------|-----------------|-------------|
| {Docker Compose / Podman Compose} | {Docker / Podman / Podman (Docker-compatible)} | {`docker compose` / `podman compose`} | {description} |

<!-- Example (native Podman, preferred when ready): -->
<!-- | Podman Compose | Podman | `podman compose` | Uses Podman (rootless) with `podman compose` to orchestrate emulators; the compose file is unchanged from Docker | -->
<!-- Example (Podman via Docker's socket — engine is Podman, command stays docker compose): -->
<!-- | Docker Compose | Podman (Docker-compatible) | `docker compose` | Runs the Podman engine through its Docker-compatible socket; `docker compose` drives Podman, compose file unchanged | -->
<!-- Example (Docker, the fallback): -->
<!-- | Docker Compose | Docker | `docker compose` | Uses Docker Compose to orchestrate emulators and dependent services during local development | -->

---

## Emulators

<!-- One row per deduplicated emulator. Dependent Service is the Azure service this emulator replaces. -->

| Dependent Service | Emulator | Purpose |
|-------------------|----------|---------|
| {azure service label} | {emulator name} | {description of what this emulator provides} |

<!-- Example: -->
<!-- | Azure Storage | Azurite Container | Blob and queue storage for photo uploads and background processing | -->
<!-- | PostgreSQL | PostgreSQL Container | Relational database for user accounts, couples, and photo metadata | -->

---

## Architecture Diagram

{One sentence describing how the app connects to its dependencies during debugging.}

```mermaid
graph LR
    %% Generated from Debug Configurations + Emulators tables above.
    %% Show each service as a node, each emulator as a node,
    %% and edges for the Azure Dependencies that connect them.
    %% MANDATORY: wrap EVERY node label and EVERY edge label in double quotes —
    %% e.g. API["Commerce API<br/>Azure Functions :7071"] -->|"@azure/storage-blob"| AZ["Azurite"]
    %% An unquoted leading @ (scoped npm packages) is parsed as mermaid edge-ID
    %% syntax and breaks the whole diagram. See "Mermaid Label Quoting" above.
```

---

## Migrations

<!-- Only include this section when database migrations are detected for one or more services. Omit entirely if not applicable. -->
<!-- ✏️ User can edit: Generate (check/uncheck) -->

When selected, the generation phase creates automated VS Code tasks that run migration scripts on launch — so emulator databases are automatically provisioned with the correct schema and seed data before the app starts debugging. No manual migration steps needed.

| Generate | Service | Migration Tool |
|----------|---------|---------------|
| {[x] / [ ]} | {service label} | {tool name, e.g. Prisma / Knex / Drizzle / EF Core} |

---

## API Test Collections

<!-- Only include this section when one or more services expose testable HTTP endpoints or triggers. Omit entirely if not applicable. -->
<!-- ✏️ User can edit: Generate (check/uncheck) -->

When selected, the generation phase produces lightweight, runnable API test scripts in the project so you can quickly smoke-test endpoints and triggers once everything is launched and connected locally.

| Generate | Service | Description |
|----------|---------|-------------|
| {[x] / [ ]} | {service label} | {collapsible lists of HTTP endpoints and/or triggers — see format below} |

<!-- Description cell format: use collapsible <details> blocks (collapsed by default) to keep the table compact. -->
<!-- Include an HTTP Endpoints section and/or a Triggers section as applicable. Each route/trigger on its own line. -->

<!-- Example: -->
<!-- | [x] | Functions API | <details><summary>HTTP Endpoints (16)</summary><br>GET /api/health<br>POST /api/auth/register<br>POST /api/auth/login<br>POST /api/auth/logout<br>GET /api/auth/me<br>GET /api/couples<br>POST /api/couples<br>GET /api/photos<br>POST /api/photos<br>DELETE /api/photos/:id<br>GET /api/albums<br>POST /api/albums<br>PUT /api/albums/:id<br>DELETE /api/albums/:id<br>GET /api/tags<br>POST /api/tags<br><br></details><details><summary>Triggers (2)</summary><br>blobTrigger — uploads<br>timerTrigger — cleanup</details> | -->

---

## Convenience Scripts

<!-- The generation phase generates only checked scripts into the project's script runner. -->
<!-- ✏️ User can edit: Generate (check/uncheck) -->

| Generate | Script | Registered In | Description |
|----------|--------|---------------|-------------|
| {[x] / [ ]} | {script name} | {path to file where script is registered, e.g. ./package.json} | {what the script does} |

<!-- Example: -->
<!-- | [x] | emulators:start | ./package.json | Start all emulators in the background, preserving existing data | -->
<!-- | [x] | emulators:stop | ./package.json | Stop all running emulators | -->
<!-- | [x] | emulators:clean | ./package.json | Stop emulators and delete all data (fresh start) | -->
<!-- | [x] | db:migrate | ./package.json | Apply pending database migrations to the emulator database | -->