fix: normalize framework identity to fix dead prompt guidance (#486)

Author: BlueHotDog

.changeset/fix-framework-prompt-mismatch.md

@@ -0,0 +1,10 @@
+---
+"@frontman/frontman-server-assets": patch
+"@frontman-ai/frontman-core": patch
+"@frontman-ai/nextjs": patch
+"@frontman-ai/vite": patch
+"@frontman-ai/astro": patch
+"@frontman-ai/client": patch
+---
+
+Fix framework-specific prompt guidance never being applied in production. The middleware sent display labels like "Next.js" but the server matched on "nextjs", so 120+ lines of Next.js expert guidance were silently skipped. Introduces a `Framework` module as single source of truth for framework identity, normalizes at the server boundary, and updates client adapters to send normalized IDs.

apps/frontman_server/lib/frontman_server/tasks/execution.ex

@@ -22,7 +22,7 @@ defmodule FrontmanServer.Tasks.Execution do
   alias FrontmanServer.Providers
   alias FrontmanServer.Providers.ResolvedKey
   alias FrontmanServer.Tasks
-  alias FrontmanServer.Tasks.Execution.{RootAgent, ToolExecutor}
+  alias FrontmanServer.Tasks.Execution.{Framework, RootAgent, ToolExecutor}
   alias FrontmanServer.Tasks.{Interaction, Task}
   alias SwarmAi.LLM.Chunk
   alias SwarmAi.Message
@@ -214,7 +214,8 @@ defmodule FrontmanServer.Tasks.Execution do
   defp build_agent(%Task{} = task, tools, opts, %ResolvedKey{} = resolved_key) do
     case Keyword.get(opts, :agent) do
       nil ->
-        has_typescript_react = task.framework in ["nextjs"]
+        fw = Framework.from_string(task.framework)
+        has_typescript_react = Framework.has_typescript_react?(fw)
 
         # Derive prompt data from task interactions
         project_rules =
@@ -245,7 +246,7 @@ defmodule FrontmanServer.Tasks.Execution do
           has_annotations: Interaction.has_annotations?(task.interactions),
           has_current_page: Interaction.has_current_page?(task.interactions),
           has_typescript_react: has_typescript_react,
-          framework: task.framework,
+          framework: fw,
           model: model_spec,
           llm_opts: llm_opts,
           project_rules: project_rules,

apps/frontman_server/lib/frontman_server/tasks/execution/framework.ex

@@ -0,0 +1,141 @@
+defmodule FrontmanServer.Tasks.Execution.Framework do
+  @moduledoc """
+  Single source of truth for framework identity.
+
+  Framework adapters (Next.js, Vite, Astro) each send a normalized ID on the
+  client which flows through ACP into the server. This module canonicalizes
+  those IDs into typed structs used for DB storage, prompt building, and
+  feature-flag derivation.
+
+  Unrecognized frameworks crash immediately — if we receive a value that isn't
+  one of our known adapters, that's a bug in the adapter or a missing server
+  mapping and we want to know about it loudly.
+
+  ## Usage
+
+      iex> Framework.from_client_label("nextjs")
+      %Framework{id: :nextjs, display_name: "Next.js"}
+
+      iex> Framework.to_string(%Framework{id: :nextjs, display_name: "Next.js"})
+      "nextjs"
+
+      iex> Framework.has_typescript_react?(%Framework{id: :nextjs, display_name: "Next.js"})
+      true
+  """
+
+  use TypedStruct
+
+  @type id :: :nextjs | :vite | :astro
+
+  typedstruct enforce: true do
+    @typedoc "Framework identity with display metadata"
+    field(:id, id())
+    field(:display_name, String.t())
+  end
+
+  # ── Constructors (private, build structs after typedstruct defines them) ──
+
+  defp build(:nextjs), do: %__MODULE__{id: :nextjs, display_name: "Next.js"}
+  defp build(:vite), do: %__MODULE__{id: :vite, display_name: "Vite"}
+  defp build(:astro), do: %__MODULE__{id: :astro, display_name: "Astro"}
+
+  # ── Public API ────────────────────────────────────────────────────────
+
+  @doc """
+  All known framework ids.
+  """
+  @spec known_ids() :: [id()]
+  def known_ids, do: [:nextjs, :vite, :astro]
+
+  @doc """
+  Normalize a raw client string into a framework struct.
+
+  Handles two forms:
+  1. Normalized IDs (current clients): `"nextjs"`, `"vite"`, `"astro"`
+  2. Legacy display labels: `"Next.js"`, `"Vite"`, `"Astro"`
+
+  Raises on unrecognized input — if we get a framework value we don't know
+  about, that's a bug that needs fixing, not silently swallowing.
+
+      iex> Framework.from_client_label("nextjs")
+      %Framework{id: :nextjs, display_name: "Next.js"}
+
+      iex> Framework.from_client_label("Next.js")
+      %Framework{id: :nextjs, display_name: "Next.js"}
+
+      iex> Framework.from_client_label("VITE")
+      %Framework{id: :vite, display_name: "Vite"}
+  """
+  @spec from_client_label(String.t()) :: t()
+  def from_client_label(label) when is_binary(label) do
+    case display_label_to_id(label) do
+      nil -> label |> normalize_raw() |> slug_to_id() |> build()
+      id -> build(id)
+    end
+  end
+
+  @doc """
+  Build a framework struct from a DB-stored string identifier.
+
+  The DB stores normalized strings like `"nextjs"`. Raises on unrecognized
+  values — if the DB contains garbage, that's a data integrity issue.
+
+      iex> Framework.from_string("nextjs")
+      %Framework{id: :nextjs, display_name: "Next.js"}
+  """
+  @spec from_string(String.t()) :: t()
+  def from_string("nextjs"), do: build(:nextjs)
+  def from_string("vite"), do: build(:vite)
+  def from_string("astro"), do: build(:astro)
+
+  @doc """
+  Serialize a framework struct to the string stored in the database.
+
+      iex> fw = Framework.from_string("nextjs")
+      iex> Framework.to_string(fw)
+      "nextjs"
+  """
+  @spec to_string(t()) :: String.t()
+  def to_string(%__MODULE__{id: :nextjs}), do: "nextjs"
+  def to_string(%__MODULE__{id: :vite}), do: "vite"
+  def to_string(%__MODULE__{id: :astro}), do: "astro"
+
+  # ── Feature flags ─────────────────────────────────────────────────────
+
+  @doc """
+  Whether the framework implies TypeScript + React tooling.
+
+  Currently only Next.js.
+
+      iex> fw = Framework.from_string("nextjs")
+      iex> Framework.has_typescript_react?(fw)
+      true
+
+      iex> fw = Framework.from_string("vite")
+      iex> Framework.has_typescript_react?(fw)
+      false
+  """
+  @spec has_typescript_react?(t()) :: boolean()
+  def has_typescript_react?(%__MODULE__{id: :nextjs}), do: true
+  def has_typescript_react?(%__MODULE__{}), do: false
+
+  # ── Internals ─────────────────────────────────────────────────────────
+
+  # Exact display-label → id (case-sensitive, fast path for legacy clients)
+  defp display_label_to_id("Next.js"), do: :nextjs
+  defp display_label_to_id("Vite"), do: :vite
+  defp display_label_to_id("Astro"), do: :astro
+  defp display_label_to_id(_), do: nil
+
+  # Defensive normalization: lowercase, strip non-alpha, then match.
+  defp normalize_raw(label) do
+    label
+    |> String.downcase()
+    |> String.replace(~r/[^a-z]/, "")
+  end
+
+  # Match the cleaned slug to a known id. No catch-all — crash on unknown.
+  defp slug_to_id("nextjs"), do: :nextjs
+  defp slug_to_id("vite"), do: :vite
+  defp slug_to_id("astro"), do: :astro
+end

apps/frontman_server/lib/frontman_server/tasks/execution/prompts.ex

@@ -6,6 +6,8 @@ defmodule FrontmanServer.Tasks.Execution.Prompts do
   - Root agent (dynamic, context-aware)
   """
 
+  alias FrontmanServer.Tasks.Execution.Framework
+
   # --- Root Agent Prompts ---
 
   @base_tool_selection_guidance """
@@ -169,8 +171,12 @@ defmodule FrontmanServer.Tasks.Execution.Prompts do
   defp maybe_append(prompt, true, guidance_fn), do: prompt <> "\n" <> guidance_fn.()
   defp maybe_append(prompt, false, _guidance_fn), do: prompt
 
-  defp append_framework_guidance(prompt, "nextjs"), do: prompt <> "\n" <> nextjs_guidance()
-  defp append_framework_guidance(prompt, _), do: prompt
+  defp append_framework_guidance(prompt, %Framework{id: :nextjs}),
+    do: prompt <> "\n" <> nextjs_guidance()
+
+  defp append_framework_guidance(prompt, %Framework{id: :vite}), do: prompt
+  defp append_framework_guidance(prompt, %Framework{id: :astro}), do: prompt
+  defp append_framework_guidance(prompt, nil), do: prompt
 
   defp append_project_structure(prompt, nil), do: prompt
   defp append_project_structure(prompt, ""), do: prompt

apps/frontman_server/lib/frontman_server/tasks/execution/root_agent.ex

@@ -16,14 +16,15 @@ defmodule FrontmanServer.Tasks.Execution.RootAgent do
 
   use TypedStruct
 
+  alias FrontmanServer.Tasks.Execution.Framework
   alias FrontmanServer.Tasks.Execution.{LLMClient, Prompts}
 
   typedstruct do
     field(:tools, [SwarmAi.Tool.t()], default: [])
     field(:has_annotations, boolean(), default: false)
     field(:has_current_page, boolean(), default: false)
     field(:has_typescript_react, boolean(), default: false)
-    field(:framework, String.t() | nil, default: nil)
+    field(:framework, Framework.t() | nil, default: nil)
     # llm_opts must include :api_key (resolved at domain layer)
     # May also include :requires_mcp_prefix and :identity_override for OAuth
     field(:llm_opts, keyword(), default: [])
@@ -42,7 +43,7 @@ defmodule FrontmanServer.Tasks.Execution.RootAgent do
   - `:tools` - List of SwarmAi.Tool structs available to the agent
   - `:has_annotations` - Whether the user has annotated elements in the UI
   - `:has_current_page` - Whether current page context is available
-  - `:framework` - Framework name (e.g., "nextjs") for framework-specific guidance
+  - `:framework` - `Framework.t()` struct for framework-specific guidance
   - `:llm_opts` - LLM options, must include `:api_key`. May include `:requires_mcp_prefix`
     and `:identity_override` for OAuth transformations (handled by LLMClient).
   - `:model` - LLM model spec (defaults to LLMClient default)

apps/frontman_server/lib/frontman_server_web/channels/tasks_channel.ex

@@ -12,6 +12,7 @@ defmodule FrontmanServerWeb.TasksChannel do
 
   alias AgentClientProtocol, as: ACP
   alias FrontmanServer.Tasks
+  alias FrontmanServer.Tasks.Execution.Framework
   alias FrontmanServer.Tasks.TitleGenerator
   alias FrontmanServerWeb.ACPHistory
 
@@ -113,8 +114,15 @@ defmodule FrontmanServerWeb.TasksChannel do
     Logger.info("ACP session/new request received with sessionId: #{session_id}")
 
     with :ok <- validate_uuid_format(session_id),
-         framework when framework != nil <- extract_framework(socket.assigns[:acp_client_info]),
-         {:ok, ^session_id} <- Tasks.create_task(socket.assigns.scope, session_id, framework) do
+         raw_framework when is_binary(raw_framework) <-
+           extract_framework(socket.assigns[:acp_client_info]),
+         fw = Framework.from_client_label(raw_framework),
+         {:ok, ^session_id} <-
+           Tasks.create_task(
+             socket.assigns.scope,
+             session_id,
+             Framework.to_string(fw)
+           ) do
       push_response(socket, id, ACP.build_session_new_result(session_id))
     else
       :error ->

apps/frontman_server/priv/repo/migrations/20260302000000_normalize_frameworks.exs

@@ -0,0 +1,41 @@
+defmodule FrontmanServer.Repo.Migrations.NormalizeFrameworks do
+  @moduledoc """
+  Normalize framework display labels to internal identifiers.
+
+  The framework middleware used to send display labels like "Next.js" which were
+  stored directly in the database. Now we normalize to lowercase identifiers
+  ("nextjs", "vite", "astro") at the channel ingestion boundary, and this
+  migration cleans up existing rows.
+  """
+  use Ecto.Migration
+
+  def up do
+    # Normalize known display labels to IDs
+    execute("UPDATE tasks SET framework = 'nextjs'  WHERE framework = 'Next.js'")
+    execute("UPDATE tasks SET framework = 'vite'    WHERE framework = 'Vite'")
+    execute("UPDATE tasks SET framework = 'astro'   WHERE framework = 'Astro'")
+
+    # Verify no unknown frameworks remain — crash the migration if so.
+    # If this fails, investigate what unexpected values exist before proceeding.
+    execute("""
+    DO $$
+    BEGIN
+      IF EXISTS (
+        SELECT 1 FROM tasks
+        WHERE framework NOT IN ('nextjs', 'vite', 'astro')
+           OR framework IS NULL
+      ) THEN
+        RAISE EXCEPTION 'Found tasks with unrecognized framework values. '
+          'Run: SELECT DISTINCT framework FROM tasks WHERE framework NOT IN (''nextjs'', ''vite'', ''astro'') '
+          'to investigate before migrating.';
+      END IF;
+    END $$;
+    """)
+  end
+
+  def down do
+    execute("UPDATE tasks SET framework = 'Next.js' WHERE framework = 'nextjs'")
+    execute("UPDATE tasks SET framework = 'Vite'    WHERE framework = 'vite'")
+    execute("UPDATE tasks SET framework = 'Astro'   WHERE framework = 'astro'")
+  end
+end