impr(cli + core + hql): ordered return values, helix restart, hql fixes, api verification (#841)

<!-- greptile_comment -->

<h2>Greptile Overview</h2>

<h3>Greptile Summary</h3>

This PR implements several major improvements across the CLI, core
database, and HQL compiler components.

**Key Changes:**

- **CLI Output System**: introduced a new structured output module
(`output.rs`) with verbosity control (quiet/normal/verbose), modern
spinner UI, and operation tracking - significantly improves developer
experience
- **Restart Command**: added `helix restart` command supporting both
local Docker instances and cloud deployments (Fly.io)
- **Ordered Return Values**: implemented ordered return values in HQL
queries using a struct-based approach instead of json! macros,
preserving field order as defined in queries
- **Variable Binding Fix**: fixed bug where variable bindings and map
variables weren't appearing in inline RETURN objects - now properly
handles scope variables vs schema properties
- **Test Infrastructure**: added comprehensive test utilities with
isolated temp directories and extensive lifecycle tests for
build/start/stop/restart workflows
- **API Key Verification**: added conditional API key verification for
schema introspection endpoint with feature flag support

**Technical Improvements:**

- Switched from `HashMap` to `IndexMap` in object validation to preserve
field ordering
- Enhanced return value generation to distinguish primitive types
(Count/Boolean/Scalar) from complex types (Nodes/Edges/Objects)
- Improved nested traversal handling with variable reference detection
- Updated all CLI commands to use new `Output`/`Step` helpers for
consistent UX

**Critical Issues:**

The test utilities use `unsafe` blocks to modify environment variables,
claiming safety based on isolation. However, environment variables are
process-global and this creates actual data races when tests run in
parallel. The `unsafe` blocks should be removed - the operations aren't
actually unsafe in Rust's memory safety sense, but the concurrency issue
remains.

<details><summary><h3>Important Files Changed</h3></summary>




| Filename | Overview |
|----------|----------|
| helix-cli/src/tests/test_utils.rs | new test utilities with isolated
temp directories and env variable management |
| helix-db/src/helixc/generator/queries.rs | implemented ordered return
values with struct-based approach and variable reference handling |
| helix-db/src/helixc/analyzer/methods/query_validation.rs | fixed
variable binding and map variable handling in return objects, added
primitive type detection |
| helix-db/src/helixc/analyzer/methods/object_validation.rs | improved
scope variable handling in property access, switched HashMap to IndexMap
for ordering |

</details>


</details>


<details><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Output
    participant Docker
    participant Compiler
    participant Generator
    participant Gateway

    User->>CLI: helix restart dev
    CLI->>Output: Operation::new("Restarting", "dev")
    Output-->>User: Display operation header
    
    CLI->>Docker: restart_instance()
    Docker->>Docker: check_runtime_available()
    Docker->>Docker: verify docker-compose.yml exists
    Docker->>Output: Step::start("Restarting container")
    Docker->>Docker: run_compose_command(["restart"])
    Docker->>Output: Step::done()
    Output-->>User: Display success

    Note over User,Gateway: Ordered Return Values Flow

    User->>CLI: helix build dev
    CLI->>Compiler: compile HQL queries
    Compiler->>Compiler: analyze_return_expr()
    Compiler->>Compiler: build_return_fields()
    Compiler->>Compiler: detect primitive vs struct types
    
    alt Primitive Type (Count/Boolean/Scalar)
        Compiler->>Generator: create primitive ReturnValueStruct
        Generator->>Generator: emit variable directly (no struct def)
    else Complex Type (Nodes/Edges/Objects)
        Compiler->>Generator: create nested ReturnValueStruct
        Generator->>Generator: generate struct definitions
        Generator->>Generator: handle variable references
        Generator->>Generator: map closure parameters
    end

    Generator->>Generator: format ordered return JSON
    Generator-->>CLI: compiled Rust code
    CLI->>Docker: build_instance()
    Docker-->>User: Built instance

    Note over User,Gateway: API Key Verification

    User->>Gateway: introspect_schema request
    Gateway->>Gateway: check API key feature flag
    
    alt API Key Enabled
        Gateway->>Gateway: validate API key
        alt Valid Key
            Gateway-->>User: return schema
        else Invalid Key
            Gateway-->>User: 401 Unauthorized
        end
    else API Key Disabled
        Gateway-->>User: return schema
    end
```
</details>


<!-- greptile_other_comments_section -->

<!-- /greptile_comment -->

Author: xav-db

.github/workflows/cli_tests.yml

@@ -0,0 +1,58 @@
+# name: CLI Tests
+
+# on:
+#   pull_request:
+#     branches: [main, dev]
+#     paths:
+#       - 'helix-cli/**'
+#       - 'helix-macros/**'
+#       - 'helix-container/**'
+#       - 'helix-db/**'
+#       - 'Cargo.toml'
+#       - 'Cargo.lock'
+
+# env:
+#   CARGO_TERM_COLOR: always
+#   RUST_BACKTRACE: 1
+
+# jobs:
+#   test:
+#     name: Test (${{ matrix.os }})
+#     runs-on: ${{ matrix.os }}
+#     strategy:
+#       fail-fast: false
+#       matrix:
+#         os: [ubuntu-latest, macos-latest, windows-latest]
+
+#     steps:
+#       - name: Checkout repository
+#         uses: actions/checkout@v4
+
+#       - name: Setup Rust toolchain
+#         uses: dtolnay/rust-toolchain@stable
+
+#       - name: Cache cargo registry
+#         uses: actions/cache@v4
+#         with:
+#           path: |
+#             ~/.cargo/registry
+#             ~/.cargo/git
+#             target
+#           key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+#           restore-keys: |
+#             ${{ runner.os }}-cargo-
+
+#       - name: Run helix-cli unit tests
+#         run: cargo test --release --package helix-cli
+#         env:
+#           # Use a unique temp directory for test isolation
+#           HELIX_CACHE_DIR: ${{ runner.temp }}/helix-test-cache-${{ github.run_id }}
+
+#       - name: Run helix-macros tests
+#         run: cargo test --release --package helix-macros
+
+#       # Integration tests that require repo cloning run serially
+#       - name: Run helix-cli integration tests (ignored tests)
+#         run: cargo test --release --package helix-cli -- --ignored --test-threads=1
+#         env:
+#           HELIX_CACHE_DIR: ${{ runner.temp }}/helix-test-cache-ignored-${{ github.run_id }}

.github/workflows/db_tests.yml

@@ -3,6 +3,11 @@ name: Core Database Tests
 on:
   pull_request:
     branches: [ main, dev ]
+    paths:
+      - 'helix-macros/**'
+      - 'helix-db/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
 
 jobs:
   test:
@@ -33,6 +38,6 @@ jobs:
           ${{ runner.os }}-cargo-
 
     - name: Run tests
-      run: | 
+      run: |
         cd helix-db
         cargo test --release --lib -- --skip concurrency_tests

.github/workflows/dev_instance_tests.yml

@@ -3,6 +3,12 @@ name: Core Database Tests In Dev Instance Mode
 on:
   pull_request:
     branches: [ main, dev ]
+    paths:
+      - 'helix-macros/**'
+      - 'helix-db/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+
 
 jobs:
   test:
@@ -33,6 +39,6 @@ jobs:
           ${{ runner.os }}-cargo-
 
     - name: Run dev instance tests
-      run: | 
+      run: |
         cd helix-db
         cargo test --release --lib --features dev-instance -- --skip concurrency_tests

.github/workflows/hql_tests.yml

@@ -3,6 +3,9 @@ name: HQL Tests
 on:
   pull_request:
     branches: [main, dev]
+    paths:
+      - 'helix-macros/**'
+      - 'helix-db/**'
 
 jobs:
   hql-tests:

.github/workflows/production_db_tests.yml

@@ -3,6 +3,11 @@ name: Core Database Tests In Production Mode
 on:
   pull_request:
     branches: [ main, dev ]
+    paths:
+      - 'helix-macros/**'
+      - 'helix-db/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
 
 jobs:
   test:

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "helix-cli"
-version = "2.2.5"
+version = "2.2.6"
 edition = "2024"
 
 [dependencies]
@@ -36,6 +36,7 @@ crossterm = "0.28"
 
 [dev-dependencies]
 tempfile = "3.23.0"
+serial_test = "3.2"
 
 [lib]
 name = "helix_cli"

helix-cli/Cargo.toml

@@ -7,9 +7,9 @@ export PATH="$HOME/.cargo/bin:$PATH"
 
 # if dev profile, build with dev profile
 if [ "$1" = "dev" ]; then
-    cargo install --profile dev --force --path . --root ~/.local
+    cargo install --debug --force --path . --root ~/.local
 else
-    cargo install --release --force --path . --root ~/.local
+    cargo install --force --path . --root ~/.local
 fi
 
 if ! echo "$PATH" | grep -q "$HOME/.local/bin"; then

helix-cli/build.sh

@@ -6,9 +6,10 @@ use crate::commands::integrations::helix::HelixManager;
 use crate::config::{BuildMode, CloudConfig, DbConfig, LocalInstanceConfig};
 use crate::docker::DockerManager;
 use crate::errors::project_error;
+use crate::output::{Operation, Step};
 use crate::project::ProjectContext;
 use crate::prompts;
-use crate::utils::{print_instructions, print_status, print_success};
+use crate::utils::print_instructions;
 use eyre::Result;
 use std::env;
 
@@ -84,10 +85,7 @@ async fn run_add_inner(
         .into());
     }
 
-    print_status(
-        "ADD",
-        &format!("Adding instance '{instance_name}' to Helix project"),
-    );
+    let op = Operation::new("Adding", &instance_name);
 
     // Backup the original config before any modifications
     let config_path = project_context.root.join("helix.toml");
@@ -115,7 +113,7 @@ async fn run_add_inner(
             let config_path = project_context.root.join("helix.toml");
             project_context.config.save_to_file(&config_path)?;
 
-            print_status("CLOUD", "Helix cloud instance configuration added");
+            Step::verbose_substep("Helix cloud instance configuration added");
 
             // Prompt user to create cluster now
             println!();
@@ -140,9 +138,7 @@ async fn run_add_inner(
 
                 // create_cluster::run() already saved the updated config with the real cluster_id
                 // Return early to avoid overwriting it with the stale in-memory config
-                print_success(&format!(
-                    "Instance '{instance_name}' added to Helix project"
-                ));
+                op.success();
 
                 print_instructions(
                     "Next steps:",
@@ -159,13 +155,10 @@ async fn run_add_inner(
                 return Ok(());
             } else {
                 println!();
-                print_status(
-                    "INFO",
-                    &format!(
-                        "Cluster creation skipped. Run 'helix create-cluster {}' when ready.",
-                        instance_name
-                    ),
-                );
+                crate::output::info(&format!(
+                    "Cluster creation skipped. Run 'helix create-cluster {}' when ready.",
+                    instance_name
+                ));
             }
         }
         CloudDeploymentTypeCommand::Ecr { .. } => {
@@ -196,7 +189,7 @@ async fn run_add_inner(
                 .cloud
                 .insert(instance_name.clone(), CloudConfig::Ecr(ecr_config.clone()));
 
-            print_status("ECR", "AWS ECR repository initialized successfully");
+            Step::verbose_substep("AWS ECR repository initialized successfully");
         }
         CloudDeploymentTypeCommand::Fly {
             auth,
@@ -246,17 +239,15 @@ async fn run_add_inner(
                 .config
                 .local
                 .insert(instance_name.clone(), local_config);
-            print_status("LOCAL", "Local instance configuration added");
+            Step::verbose_substep("Local instance configuration added");
         }
     }
 
     // Save the updated configuration
     let config_path = project_context.root.join("helix.toml");
     project_context.config.save_to_file(&config_path)?;
 
-    print_success(&format!(
-        "Instance '{instance_name}' added to Helix project"
-    ));
+    op.success();
 
     print_instructions(
         "Next steps:",