# Dockerfile Flowchart

Generate a visual flowchart of Docker build layers from a Dockerfile. Each instruction becomes its own node. Supports Whimsical board and Mermaid file output.

**Trigger:** User asks to "create a flowchart of the Dockerfile", "visualize Docker layers", or similar.

---

## Step 1 — Find and read the Dockerfile

Look for `Dockerfile` in the current working directory. If not found, ask the user for the path.

Read the full file.

---

## Step 2 — Parse and build the node list

Do this immediately after reading — do not wait for user input first.

Walk the file and build a list of stages. Each stage is a `FROM ... AS <name>` block. For each stage record:

- **name** — the **AS** alias (or `anonymous` if none)
- **parent** — the image or stage name in **FROM**
- **instructions** — ordered list of every instruction in the block (one per logical line, collapsing `\` continuations)

**Identify special instructions:**

| Type | Rule |
|------|------|
| Library install | **RUN** whose command contains any of: `apt-get install`, `apt install`, `apk add`, `yum install`, `pip install`, `poetry install`, `npm install`, `yarn add`, `gem install`, `cargo install` |
| Directory copy | **COPY** or **ADD** where the source token has no file extension (no `.` in the final path component) and is not `/`. To find the source token, skip any leading tokens that begin with `--` (option flags such as `--chown=worker`, `--chmod=755`, `--link`). The source token is the first non-flag argument after the instruction keyword. |

**Node ID scheme** (for mermaid / internal reference):

- Stage header: `<stage_name>_from` (e.g. `dev_from`, `base`)
- Instructions: `<stage_name>_<index>` (e.g. `dev_1`, `dev_2`)
- **ECR** / registry parent: `ecr`

**Node label text:** the raw instruction as it appears, with `\` continuations collapsed to a single line using ` && ` or spaces as appropriate. After collapsing, identify **all-uppercase tokens** — whitespace-delimited tokens where every letter is uppercase (e.g. `RUN`, `COPY`, `ENV`, `ARG`). Tokens containing only digits or symbols are not uppercase tokens. These tokens will be bolded differently depending on output format (see Steps 4a and 4b).

**Color per stage** (use these hex values consistently):

| Stage role | Color |
|------------|-------|
| Registry parent image | `#2C88D9` (blue) |
| `base` (or first shared foundation stage) | `#788896` (silver) |
| Development stage (`dev`, `test`, etc.) | `#E8833A` (orange) |
| Utility stages (`update-lockfile`, `format`, `unit-lint`, `lint`, `integration`, etc.) | `#F7C325` (yellow) |
| Production / deploy stage | `#1AAE9F` (green) |

If a stage doesn't match a known role, pick the closest color or use silver.

---

## Step 3 — Determine output format

Check the user's original message for format keywords before asking:

- If it contains "whimsical", "board", or "live" → use **Whimsical**, skip the question.
- If it contains "mermaid", "mmd", or "file" → use **Mermaid**, skip the question.
- Otherwise, ask:

> Which output format?
> - **Whimsical** — creates a new board with live formatting
> - **Mermaid** — writes a `.mmd` file to the project root

---

## Step 4a — Whimsical output

All analysis is already complete. Do NOT call `inspect_state`. Make exactly three Whimsical calls in order.

### 4a-1 Build the Mermaid string (plain text labels)

Construct a `graph TD` Mermaid string. Use **plain text labels** — no `<b>` tags. Bold is applied separately in step 4a-3.

- One node definition per instruction (no newlines inside node labels)
- Chain instructions within each stage with `-->`
- Branch from the last instruction of the parent stage to the first node of each child stage
- Add `style <id> fill:#HEX,color:#fff` for every node using the stage color table above
- For library-install nodes, append `,stroke-dasharray:5 5` to the style
- For directory-copy nodes, use **cylinder shape** `[("label")]` instead of rectangle `["label"]` — Whimsical does not support `stroke-width` in style lines, so shape change is the visual cue

### 4a-2 Create the board and flowchart

```
board_create(title="<repo-name> Dockerfile Layers")
flowchart_create(board_id, mermaid)
```

`flowchart_create` returns EDNL with a short ID for every shape.

### 4a-3 Apply bold formatting in one batched edit

Call `flowchart_edit` once with an `update` array covering every node. For each node, rewrite `:body-rt` so that all-uppercase tokens are wrapped with `[:b ...]`:

```
flowchart_edit(
  shape_id=<any node id from step 4a-2>,
  update=[
    ["<id>", "[:shape {:body-rt [:p [:b \"RUN\"] \" apt-get install curl\"]}]"],
    ["<id>", "[:shape {:body-rt [:p [:b \"COPY\"] \" . /app\"]}]"],
    ...
  ]
)
```

Rules for building `:body-rt`:
- The block is always `[:p ...]`
- Each all-uppercase token becomes `[:b "TOKEN"]`
- Non-uppercase text between tokens is a plain string child of `[:p ...]`
- Example: `COPY --chown=worker src /app` → `[:p [:b "COPY"] " --chown=worker src /app"]`

---

## Step 4b — Mermaid output

Write `dockerfile-layers.mmd` to the project root. In node labels, bold all-uppercase tokens using `<b>TOKEN</b>` — standard Mermaid renderers support HTML tags in node labels.

Structure:

```mermaid
graph TD
    <node definitions>
    <edges>

    %% Stage colors: blue=registry, silver=base, orange=dev, yellow=utility, green=deploy
    %% Dashed border (stroke-dasharray:5 5) = installs system/language libraries
    %% Thick border (stroke-width:3px) = copies an entire directory

    <style lines>
```

Style rules per node type:

| Node type | Mermaid style |
|-----------|---------------|
| Normal | `fill:#HEX,color:#fff` |
| Library install | `fill:#HEX,color:#fff,stroke-dasharray:5 5` |
| Directory copy | `fill:#HEX,color:#fff,stroke-width:3px` (standard Mermaid renderers support this) |

---

## Visual convention summary

| Visual | Meaning |
|--------|---------|
| Filled rectangle | Normal instruction |
| Dashed border | Installs system or language packages |
| Cylinder shape | Copies an entire directory (Whimsical); thick border `stroke-width:3px` in Mermaid file output |
| Node color | Which stage the instruction belongs to |