feat: add --no-ui flag to serve command to disable web UI at launch

When --no-ui is passed to `code-iq serve`, the React SPA is excluded
and only the REST API and MCP server remain active. Useful for headless
or CI environments.

- CodeIqApplication.main() detects --no-ui before Spring context init
  and sets codeiq.ui.enabled=false as a system property
- SpaController gains @ConditionalOnProperty so it is only registered
  when codeiq.ui.enabled=true (default: true / matchIfMissing=true)
- CodeIqConfig gains uiEnabled field bound to codeiq.ui.enabled
- application.yml sets codeiq.ui.enabled: true as default
- ServeCommand: added --no-ui option; startup log now states whether
  Web UI is enabled or disabled
- Tests: 2 new --no-ui flag tests in ServeCommandTest, 5 new
  SpaControllerConditionalTest tests (1447 total, 0 failures)

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: aksOps

src/main/java/io/github/randomcodespace/iq/CodeIqApplication.java

@@ -67,6 +67,12 @@ public static void main(String[] args) {
                 System.setProperty("server.port", portStr);
             }
 
+            // Disable web UI if --no-ui flag is present
+            boolean noUi = Arrays.asList(args).contains("--no-ui");
+            if (noUi) {
+                System.setProperty("codeiq.ui.enabled", "false");
+            }
+
             // Resolve codebase root so Neo4j points to the correct graph.db
             String codebasePath = extractPositionalArg(args, "serve");
             java.nio.file.Path root = java.nio.file.Path.of(

src/main/java/io/github/randomcodespace/iq/cli/ServeCommand.java

@@ -42,6 +42,10 @@ public class ServeCommand implements Callable<Integer> {
     @Option(names = {"--graph"}, description = "Path to shared graph directory (overrides default)")
     private Path graphPath;
 
+    @Option(names = {"--no-ui"}, defaultValue = "false",
+            description = "Disable the web UI (React SPA). API and MCP endpoints remain active.")
+    private boolean noUi;
+
     @Autowired
     private CodeIqConfig config;
 
@@ -73,7 +77,11 @@ public Integer call() {
 
         CliOutput.step("\uD83D\uDE80", "@|bold,green Server started|@");
         System.out.println();
-        CliOutput.info("  URL:       http://" + host + ":" + port);
+        if (noUi) {
+            CliOutput.info("  Web UI:    disabled (API and MCP active at :" + port + ")");
+        } else {
+            CliOutput.info("  Web UI:    http://" + host + ":" + port + " (React SPA)");
+        }
         CliOutput.info("  REST API:  http://" + host + ":" + port + "/api");
         CliOutput.info("  MCP:       http://" + host + ":" + port + "/mcp");
         CliOutput.info("  Health:    http://" + host + ":" + port + "/actuator/health");
@@ -94,4 +102,5 @@ public Integer call() {
     public int getPort() { return port; }
     public String getHost() { return host; }
     public Path getGraphPath() { return graphPath; }
+    public boolean isNoUi() { return noUi; }
 }

src/main/java/io/github/randomcodespace/iq/config/CodeIqConfig.java

@@ -28,6 +28,9 @@ public class CodeIqConfig {
     /** Graph configuration sub-properties. */
     private Graph graph = new Graph();
 
+    /** Whether to serve the React web UI. Set to false via --no-ui flag. */
+    private boolean uiEnabled = true;
+
     public static class Graph {
         private String path = ".osscodeiq/graph.db";
 
@@ -95,4 +98,12 @@ public Graph getGraph() {
     public void setGraph(Graph graph) {
         this.graph = graph;
     }
+
+    public boolean isUiEnabled() {
+        return uiEnabled;
+    }
+
+    public void setUiEnabled(boolean uiEnabled) {
+        this.uiEnabled = uiEnabled;
+    }
 }

src/main/java/io/github/randomcodespace/iq/web/SpaController.java

@@ -1,5 +1,6 @@
 package io.github.randomcodespace.iq.web;
 
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.context.annotation.Profile;
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -10,9 +11,12 @@
  * <p>
  * Only matches paths without a file extension (e.g. /topology, /explorer/class)
  * so static assets (.js, .css, .html, .svg) are served normally.
+ * <p>
+ * Disabled when {@code codeiq.ui.enabled=false} (i.e. {@code --no-ui} flag passed to serve).
  */
 @Controller
 @Profile("serving")
+@ConditionalOnProperty(name = "codeiq.ui.enabled", havingValue = "true", matchIfMissing = true)
 public class SpaController {
 
     @GetMapping(value = {

src/main/resources/application.yml

@@ -30,6 +30,8 @@ codeiq:
   max-depth: 10
   max-radius: 10
   batch-size: 500
+  ui:
+    enabled: true
 
 spring.ai.mcp.server:
   name: code-iq

src/test/java/io/github/randomcodespace/iq/cli/ServeCommandTest.java

@@ -48,4 +48,20 @@ void customPortIsParsed() {
         cmdLine.parseArgs("--port", "9090");
         assertEquals(9090, cmd.getPort());
     }
+
+    @Test
+    void noUiDefaultsToFalse() {
+        var cmd = new ServeCommand();
+        var cmdLine = new CommandLine(cmd);
+        cmdLine.parseArgs();
+        assertEquals(false, cmd.isNoUi());
+    }
+
+    @Test
+    void noUiFlagIsRecognized() {
+        var cmd = new ServeCommand();
+        var cmdLine = new CommandLine(cmd);
+        cmdLine.parseArgs("--no-ui");
+        assertEquals(true, cmd.isNoUi());
+    }
 }

src/test/java/io/github/randomcodespace/iq/web/SpaControllerConditionalTest.java

@@ -0,0 +1,54 @@
+package io.github.randomcodespace.iq.web;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.context.annotation.Profile;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Verifies that SpaController is conditionally registered based on codeiq.ui.enabled.
+ */
+class SpaControllerConditionalTest {
+
+    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
+            .withUserConfiguration(SpaController.class)
+            .withSystemProperties("spring.profiles.active=serving");
+
+    @Test
+    void spaControllerHasConditionalOnPropertyAnnotation() {
+        var annotation = SpaController.class.getAnnotation(ConditionalOnProperty.class);
+        assertThat(annotation).isNotNull();
+        assertThat(annotation.name()).contains("codeiq.ui.enabled");
+        assertThat(annotation.havingValue()).isEqualTo("true");
+        assertThat(annotation.matchIfMissing()).isTrue();
+    }
+
+    @Test
+    void spaControllerRegisteredWhenUiEnabledTrue() {
+        contextRunner
+                .withPropertyValues("codeiq.ui.enabled=true")
+                .run(context -> assertThat(context).hasSingleBean(SpaController.class));
+    }
+
+    @Test
+    void spaControllerRegisteredWhenPropertyAbsent() {
+        contextRunner
+                .run(context -> assertThat(context).hasSingleBean(SpaController.class));
+    }
+
+    @Test
+    void spaControllerNotRegisteredWhenUiEnabledFalse() {
+        contextRunner
+                .withPropertyValues("codeiq.ui.enabled=false")
+                .run(context -> assertThat(context).doesNotHaveBean(SpaController.class));
+    }
+
+    @Test
+    void spaControllerHasProfileAnnotation() {
+        var annotation = SpaController.class.getAnnotation(Profile.class);
+        assertThat(annotation).isNotNull();
+        assertThat(annotation.value()).contains("serving");
+    }
+}