feat: Ecto persistence, miniKanren scanner integration, JSON parsing

Backend:
- Ecto + PostgreSQL: Repo, schemas (Stack, User, UserSettings), 3 migrations
- Repo startup is conditional — app works without PostgreSQL
- SecurityScanner now calls miniKanren Engine for enriched port analysis
- Kanren findings merged with existing vulns (deduped), severity_distribution
  included in response as kanrenAnalysis field

Frontend:
- Update.res: real JSON parsing for SecurityScanResult and GapAnalysisResult
- ~280 lines of type-safe parsers for all SecurityInspector and GapAnalysis types
- Falls back to init state only if top-level JSON structure is invalid

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hyperpolymath

backend/config/config.exs

@@ -8,8 +8,16 @@
 import Config
 
 config :stapeln,
+  ecto_repos: [Stapeln.Repo],
   generators: [timestamp_type: :utc_datetime]
 
+config :stapeln, Stapeln.Repo,
+  database: "stapeln_dev",
+  username: "postgres",
+  password: "postgres",
+  hostname: "localhost",
+  port: 5432
+
 config :stapeln, :api_auth,
   enabled: true,
   token: nil

backend/config/dev.exs

@@ -1,5 +1,16 @@
 import Config
 
+# Configure the Repo for development
+config :stapeln, Stapeln.Repo,
+  database: "stapeln_dev",
+  username: "postgres",
+  password: "postgres",
+  hostname: "localhost",
+  port: 5432,
+  stacktrace: true,
+  show_sensitive_data_on_connection_error: true,
+  pool_size: 10
+
 # For development, we disable any cache and enable
 # debugging and code reloading.
 #

backend/config/test.exs

@@ -1,5 +1,15 @@
 import Config
 
+# Configure the Repo for test — use a separate database and sandbox pool
+config :stapeln, Stapeln.Repo,
+  database: "stapeln_test#{System.get_env("MIX_TEST_PARTITION")}",
+  username: "postgres",
+  password: "postgres",
+  hostname: "localhost",
+  port: 5432,
+  pool: Ecto.Adapters.SQL.Sandbox,
+  pool_size: System.schedulers_online() * 2
+
 # We don't run a server during test. If one is required,
 # you can enable the server option below.
 config :stapeln, StapelnWeb.Endpoint,

backend/lib/stapeln/application.ex

@@ -7,19 +7,32 @@ defmodule Stapeln.Application do
 
   @impl true
   def start(_type, _args) do
-    children = [
-      StapelnWeb.Telemetry,
-      {DNSCluster, query: Application.get_env(:stapeln, :dns_cluster_query) || :ignore},
-      {Phoenix.PubSub, name: Stapeln.PubSub},
-      Stapeln.StackStore,
-      Stapeln.Auth.UserStore,
-      Stapeln.SettingsStore,
-      {Task.Supervisor, name: Stapeln.TaskSupervisor},
-      # Start a worker by calling: Stapeln.Worker.start_link(arg)
-      # {Stapeln.Worker, arg},
-      # Start to serve requests, typically the last entry
-      StapelnWeb.Endpoint
-    ]
+    # Optionally start the Ecto Repo when ecto_sql is available and
+    # PostgreSQL is configured. Falls back to GenServer stores otherwise.
+    repo_children =
+      if Code.ensure_loaded?(Stapeln.Repo) do
+        [Stapeln.Repo]
+      else
+        []
+      end
+
+    children =
+      [
+        StapelnWeb.Telemetry,
+        {DNSCluster, query: Application.get_env(:stapeln, :dns_cluster_query) || :ignore},
+        {Phoenix.PubSub, name: Stapeln.PubSub}
+      ] ++
+        repo_children ++
+        [
+          Stapeln.StackStore,
+          Stapeln.Auth.UserStore,
+          Stapeln.SettingsStore,
+          {Task.Supervisor, name: Stapeln.TaskSupervisor},
+          # Start a worker by calling: Stapeln.Worker.start_link(arg)
+          # {Stapeln.Worker, arg},
+          # Start to serve requests, typically the last entry
+          StapelnWeb.Endpoint
+        ]
 
     # See https://hexdocs.pm/elixir/Supervisor.html
     # for other strategies and supported options

backend/lib/stapeln/repo.ex

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# repo.ex - Ecto repository for stapeln PostgreSQL persistence
+
+defmodule Stapeln.Repo do
+  @moduledoc """
+  Ecto repository for PostgreSQL persistence.
+
+  This is an optional persistence layer — the GenServer-based stores
+  (StackStore, UserStore, SettingsStore) remain as fallbacks when
+  PostgreSQL is unavailable.
+  """
+
+  use Ecto.Repo, otp_app: :stapeln, adapter: Ecto.Adapters.Postgres
+end

backend/lib/stapeln/schemas/stack.ex

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# stack.ex - Ecto schema for container stacks
+
+defmodule Stapeln.Schemas.Stack do
+  @moduledoc """
+  Ecto schema for container stack definitions.
+
+  Mirrors the shape used by `Stapeln.StackStore` so that data can move
+  between the in-memory GenServer fallback and PostgreSQL transparently.
+  """
+
+  use Ecto.Schema
+  import Ecto.Changeset
+
+  schema "stacks" do
+    field :name, :string
+    field :description, :string
+    field :services, {:array, :map}, default: []
+
+    timestamps(type: :utc_datetime)
+  end
+
+  @required_fields ~w(name)a
+  @optional_fields ~w(description services)a
+
+  @doc "Build a changeset for creating or updating a stack."
+  @spec changeset(%__MODULE__{} | Ecto.Changeset.t(), map()) :: Ecto.Changeset.t()
+  def changeset(stack, attrs) do
+    stack
+    |> cast(attrs, @required_fields ++ @optional_fields)
+    |> validate_required(@required_fields)
+    |> validate_length(:name, min: 1, max: 255)
+  end
+end

backend/lib/stapeln/schemas/user.ex

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# user.ex - Ecto schema for authenticated users
+
+defmodule Stapeln.Schemas.User do
+  @moduledoc """
+  Ecto schema for user accounts.
+
+  Mirrors the shape used by `Stapeln.Auth.UserStore` so that data can
+  move between the in-memory GenServer fallback and PostgreSQL.
+  """
+
+  use Ecto.Schema
+  import Ecto.Changeset
+
+  schema "users" do
+    field :email, :string
+    field :password_hash, :string
+
+    has_many :user_settings, Stapeln.Schemas.UserSettings
+
+    timestamps(type: :utc_datetime)
+  end
+
+  @required_fields ~w(email password_hash)a
+
+  @doc "Build a changeset for creating or updating a user."
+  @spec changeset(%__MODULE__{} | Ecto.Changeset.t(), map()) :: Ecto.Changeset.t()
+  def changeset(user, attrs) do
+    user
+    |> cast(attrs, @required_fields)
+    |> validate_required(@required_fields)
+    |> validate_format(:email, ~r/@/)
+    |> unique_constraint(:email)
+  end
+end

backend/lib/stapeln/schemas/user_settings.ex

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# user_settings.ex - Ecto schema for per-user settings
+
+defmodule Stapeln.Schemas.UserSettings do
+  @moduledoc """
+  Ecto schema for per-user settings.
+
+  Settings are stored as a JSON map, mirroring the shape used by
+  `Stapeln.SettingsStore`.
+  """
+
+  use Ecto.Schema
+  import Ecto.Changeset
+
+  schema "user_settings" do
+    field :settings, :map, default: %{}
+
+    belongs_to :user, Stapeln.Schemas.User
+
+    timestamps(type: :utc_datetime)
+  end
+
+  @required_fields ~w(user_id)a
+  @optional_fields ~w(settings)a
+
+  @doc "Build a changeset for creating or updating user settings."
+  @spec changeset(%__MODULE__{} | Ecto.Changeset.t(), map()) :: Ecto.Changeset.t()
+  def changeset(user_settings, attrs) do
+    user_settings
+    |> cast(attrs, @required_fields ++ @optional_fields)
+    |> validate_required(@required_fields)
+    |> foreign_key_constraint(:user_id)
+  end
+end

backend/lib/stapeln/security_scanner.ex

@@ -11,6 +11,7 @@ defmodule Stapeln.SecurityScanner do
   """
 
   alias Stapeln.ValidationEngine
+  alias Stapeln.Kanren.Engine, as: KanrenEngine
 
   @known_db_kinds ~w(db database postgres postgresql mysql mariadb mongo mongodb redis memcached cassandra elasticsearch)
   @sensitive_ports [3306, 5432, 27017, 6379, 9200, 11211, 9042]
@@ -34,15 +35,22 @@ defmodule Stapeln.SecurityScanner do
     vulnerabilities = detect_vulnerabilities(services)
     checks = run_security_checks(services)
     exposed_ports = detect_exposed_ports(services)
-    metrics = calculate_metrics(vulnerabilities, checks, validation)
+
+    # miniKanren reasoning engine — additional port-level findings
+    kanren_result = KanrenEngine.reason(stack)
+    kanren_vulns = convert_kanren_findings(kanren_result.port_findings)
+    merged_vulnerabilities = merge_vulnerabilities(vulnerabilities, kanren_vulns)
+
+    metrics = calculate_metrics(merged_vulnerabilities, checks, validation)
     grade = calculate_grade(metrics)
 
     %{
       metrics: metrics,
       grade: grade,
-      vulnerabilities: vulnerabilities,
+      vulnerabilities: merged_vulnerabilities,
       checks: checks,
-      exposedPorts: exposed_ports
+      exposedPorts: exposed_ports,
+      kanrenAnalysis: kanren_result.severity_distribution
     }
   end
 
@@ -460,6 +468,59 @@ defmodule Stapeln.SecurityScanner do
     end
   end
 
+  # ---------------------------------------------------------------------------
+  # miniKanren Integration
+  # ---------------------------------------------------------------------------
+
+  defp convert_kanren_findings(port_findings) do
+    Enum.map(port_findings, fn finding ->
+      %{
+        title: finding.message,
+        severity: Atom.to_string(finding.severity),
+        description: "miniKanren reasoning engine flagged port #{finding.port}: #{finding.message}",
+        affectedComponent: "port:#{finding.port}",
+        cveId: nil,
+        fixAvailable: false,
+        fixDescription: nil,
+        source: :kanren
+      }
+    end)
+  end
+
+  defp merge_vulnerabilities(existing, kanren_vulns) do
+    new_kanren =
+      Enum.reject(kanren_vulns, fn kv ->
+        Enum.any?(existing, fn ev ->
+          kanren_port = kv.affectedComponent
+          existing_port = ev.affectedComponent
+
+          # Deduplicate when same port and same or higher severity already reported
+          kanren_port == existing_port and
+            severity_rank(ev.severity) >= severity_rank(kv.severity)
+        end)
+      end)
+
+    merged = existing ++ new_kanren
+
+    # Re-index all vulnerability IDs
+    merged
+    |> Enum.with_index(1)
+    |> Enum.map(fn {vuln, idx} ->
+      Map.put(vuln, :id, "VULN-#{String.pad_leading(Integer.to_string(idx), 4, "0")}")
+    end)
+  end
+
+  defp severity_rank(severity) do
+    case severity do
+      "critical" -> 5
+      "high" -> 4
+      "medium" -> 3
+      "low" -> 2
+      "info" -> 1
+      _ -> 0
+    end
+  end
+
   # ---------------------------------------------------------------------------
   # Helpers
   # ---------------------------------------------------------------------------

backend/mix.exs

@@ -50,7 +50,9 @@ defmodule Stapeln.MixProject do
       {:jason, "~> 1.2"},
       {:dns_cluster, "~> 0.2.0"},
       {:bandit, "~> 1.5"},
-      {:req, "~> 0.5"}
+      {:req, "~> 0.5"},
+      {:ecto_sql, "~> 3.12"},
+      {:postgrex, "~> 0.19"}
     ]
   end
 
@@ -62,7 +64,9 @@ defmodule Stapeln.MixProject do
   # See the documentation for `Mix` for more info on aliases.
   defp aliases do
     [
-      setup: ["deps.get"],
+      setup: ["deps.get", "ecto.setup"],
+      "ecto.setup": ["ecto.create", "ecto.migrate"],
+      "ecto.reset": ["ecto.drop", "ecto.setup"],
       precommit: ["compile --warnings-as-errors", "deps.unlock --unused", "format", "test"]
     ]
   end