strata-cli 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e87ebe6383ea4dea3c2b0a57d47bc8a70cdbad507bcb9233614fb33161f5e71a
-  data.tar.gz: c343df7299ff6959a73e31e68ca3cc959c5e9596dceb671be4d25868c9c04a5e
+  metadata.gz: 4995c9ab5a77b99effe743f6518204ffe8c2417e06f2f3acac57efe5f82cd041
+  data.tar.gz: 89c9a32ddf48ac1e4e68a92aa0f6f8acf6f37fbc9267a0134fddc3a34a859ed0
 SHA512:
-  metadata.gz: 1629834279f085c6ef45b74f057f732e722fea8567a98d3ac48e2ae46ce51e0aff46219f41e392940198b5507a8c22d17b20851724c61136ba29d3837f8647b1
-  data.tar.gz: 7b37420ff55bdb3910e702e1cb349741d4aa629a67e14b8bb3651189d2d840916a92ac0dbf7e54473ebcc82c71191d3af702a4eb958252a03f97c3919510fd70
+  metadata.gz: ca85facb30bebc4b5ec05ca79b15e3e94434fa10122400baadab6b923700fa4117b39b5cc06fddb1ccbf791ee1d772d755e1618159a5957d761ac1851ead083f
+  data.tar.gz: 07e20501e723d426b03044996bd2a20748e4bd322fa71e43f6c193be8d0516a49672e0ed7acd94f81a451cc99c0c8b48b087b02af8f334b10e50157518df520e

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [0.1.10] - 2026-05-22
+
+### Added
+
+- **Agent mode (`--agent`)**: Structured JSON output for automation and agent workflows on read-only commands (`datasource tables`, `datasource meta`, `version`, and others). Interactive `create` flows return machine-readable errors with stable codes when agent mode is requested.
+- **Audit field validation**: Model audit checks allowed field keys, expression shape (string shortcut or mapping with `sql`), and `format` types (string shortcuts and hash forms).
+- **Audit import resolution**: Model checks resolve YAML imports via `YamlImportResolver` before validating table and relationship definitions.
+
+### Changed
+
+- **AGENTS.md template**: Updated project init template with semantic-model authoring guidance and `--agent` command usage.
+
+## [0.1.9] - 2026-05-13
+
+### Added
+
+- **Branch subcommands**: `strata branch` with `list` (local and server branches), `create`, `checkout`, and `delete` (remove a branch on the Strata server). Git helpers extended to support these flows.
+
+### Changed
+
+- **Terminal output**: Centralized printing through `Output`, reduced verbose logs from deployment monitoring and test reporting; removed `ColorHelper` in favor of shared output helpers.
+- **API client errors**: Added `ResponseErrorHandler` to centralize HTTP error handling and user-facing messages across the client and generators.
+- **AI table generation**: Updated `SYSTEM_PROMPT` for YAML model / field generation.
+
+### Fixed
+
+- **`list` command**: Correctly includes nested models in listings.
+- **Field editor**: Dimension lookup flags apply only to dimensions.
+
 ## [0.1.8] - 2026-04-28
 
 ### Changed

data/README.md

@@ -25,6 +25,30 @@ gem install strata-cli
 
 > 💡 **Tip:** Run `strata COMMAND --help` for detailed help, options, and examples on any command. The CLI help system provides comprehensive documentation for each command.
 
+## Agent mode (`--agent`)
+
+Pass `--agent` on any command for structured JSON output and no interactive prompts (where the command supports it).
+
+**Supported examples:**
+
+```bash
+strata datasource list --agent
+strata datasource tables my_db --agent
+strata datasource meta my_db orders --agent
+strata table list --agent
+strata audit all --agent
+strata deploy --yes --agent
+```
+
+**Not supported** — these commands are interactive generators; write YAML directly instead:
+
+```bash
+strata create table [TABLE_PATH]      # → models/tbl.*.yml
+strata create relation RELATION_PATH  # → models/rel.*.yml
+```
+
+Use `strata datasource meta DS_KEY TABLE_NAME --agent` for column metadata when authoring table models.
+
 <details>
 <summary><strong>Project Management</strong></summary>
 
@@ -127,7 +151,7 @@ strata datasource exec my_db -f queries/analysis.sql
 <summary><strong>Model Creation</strong></summary>
 
 ### `strata create table [TABLE_PATH]`
-Create a semantic table model from a datasource table.
+Create a semantic table model from a datasource table. **Not available with `--agent`** — write `models/tbl.*.yml` directly or use `strata datasource meta` for schema metadata.
 
 **Options:** `-d, --datasource DS_KEY`
 
@@ -142,7 +166,7 @@ strata create table contact/dse.call_center_d  # With schema
 **Process:** Checks table existence → Fetches metadata → AI suggests fields → Interactive editor → Generates model file
 
 ### `strata create relation RELATION_PATH`
-Create a relation (join) definition file.
+Create a relation (join) definition file. **Not available with `--agent`** — write `models/rel.*.yml` directly.
 
 **Options:** `-d, --datasource DS_KEY`
 

data/lib/strata/cli/agent_mode.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "agent_output"
+
+module Strata
+  module CLI
+    module AgentMode
+      def self.included(base)
+        base.class_option :agent, type: :boolean, default: false,
+          desc: "Agent mode: structured output, no interactive prompts"
+      end
+
+      def agent_mode?
+        value = options[:agent]
+        value = options["agent"] if value.nil?
+        value == true
+      end
+
+      def reject_agent_mode!(message, code: "agent_mode_unsupported")
+        return unless agent_mode?
+
+        AgentOutput.emit_error(message, code: code)
+      end
+    end
+  end
+end

data/lib/strata/cli/agent_output.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Strata
+  module CLI
+    module AgentOutput
+      module_function
+
+      def emit_json(data)
+        $stdout.puts(JSON.generate(data))
+      end
+
+      def emit_error(message, code: "agent_mode_unsupported", **metadata)
+        payload = {error: message, code: code}.merge(metadata)
+        warn(JSON.generate(payload))
+        exit(1)
+      end
+    end
+  end
+end

data/lib/strata/cli/ai/services/table_generator.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../client"
+require_relative "../../output"
 require "yaml"
 
 module Strata
@@ -14,17 +15,29 @@ module Strata
             You are a semantic modeling expert for the Strata Business Intelligence platform.
             Analyze database columns and generate semantic field definitions.
 
-            You must understand that Names are extremely important in the Strata application.  When the same named dimension 
+            You must understand that Names are extremely important in the Strata application. When the same named dimension
             is mapped to multiple tables, Strata treats them as the same entity but with multiple potential tables. Strata
-            will at query generation time choose the best table.  Therefore it is extremely important to consider whether a 
-            potential dimension or measure is the same as an existing one. You can try and infer that based on the table name, 
-            column name, and the existing fields.  In general, you should use existing names for the same schema type if it makes sense.
+            will at query generation time choose the best table. Therefore it is extremely important to consider whether a
+            potential dimension or measure is the same as an existing one. You can infer that based on the table name,
+            column name, existing fields, and business context. Reuse an existing dimension name only when it represents
+            the same business concept across tables. If the same column label describes the current table's own entity,
+            lifecycle, or attributes, create a table-specific name instead of reusing a generic existing name.
+            Example:
+              existing dimension name: Record Start Date
+              table name: web_page
+              column name: record_start_date
+              dimension name: Web Page Record Start Date
+            Example:
+              existing dimension name: Country
+              table name: customer
+              column name: country
+              dimension name: Country
             The edge case is when you have a Dimension table like Customer with column first_name and another Dimension
             table called Billed Customer with first_name, then they are likely not the same. A dimension created from
             Billed Customer should be given an appropriately prefixed name: Billed Customer First Name.
 
-            Next, if the column is something highly ambigous and the current table is likely a dimension table, we should prefix 
-            then dimension name with approprite prefix based on the name of the dimension table.
+            Next, if the column is something highly ambiguous and the current table is likely a dimension table, prefix
+            the dimension name with an appropriate prefix based on the name of the dimension table.
             Example:
               table name: item_dim
               column name: color
@@ -48,8 +61,8 @@ module Strata
               Example: "State" in a geography table → ["province"]
               Example: "Customer Return Date" → [] -- name has high specificity already so no synonyms needed 
 
-            In cases where a dimension already exists (i.e. a dimension with same name exists), omit everything 
-            except the following fields: name, schema_type, data_type, expression.
+            In cases where you intentionally reuse an existing dimension name because it is the same business concept,
+            omit everything except the following fields: name, schema_type, data_type, expression.
 
             Output ONLY valid JSON array, no explanations.
           PROMPT
@@ -68,7 +81,7 @@ module Strata
           # @return [Hash, nil] Generated model data or nil if AI disabled
           def call(table_name:, columns:, datasource:, user_context: nil)
             unless ai_available?
-              warn "AI not available - using rule-based fallback"
+              Output.print_warning("AI not available - using rule-based fallback")
               return fallback_fields(columns)
             end
 
@@ -85,7 +98,7 @@ module Strata
               parse_response(response, columns)
             rescue => e
               # Fallback to basic field generation on AI error
-              warn "AI failed to generate fields: #{e.message} - performing basic field generation"
+              Output.print_warning("AI failed to generate fields: #{e.message} - performing basic field generation")
               fallback_fields(columns)
             end
           end
@@ -99,8 +112,7 @@ module Strata
           # @return [Array<Hash>] Regenerated fields
           def call_with_prompt(table_name:, columns:, datasource:, user_prompt:, current_fields:)
             unless ai_available?
-              warn "AI not available - could not use prompt mode"
-              return nil
+              raise AIError, "AI is not available - configure ai_api_key in .strata"
             end
 
             prompt = build_prompt_with_user_input(
@@ -114,8 +126,7 @@ module Strata
               response = @client.complete(prompt, system_prompt: SYSTEM_PROMPT)
               parse_response(response, columns)
             rescue => e
-              warn "AI failed to generate fields: #{e.message}"
-              nil
+              raise AIError, "AI failed to generate fields: #{e.message}"
             end
           end
 
@@ -134,7 +145,7 @@ module Strata
             end.join("\n")
 
             context_section = if existing_models_context && !existing_models_context.empty?
-              "\n\nExisting model patterns for consistency:\n#{existing_models_context}"
+              "\n\nExisting semantic model fields for naming comparison:\n#{existing_models_context}"
             else
               ""
             end
@@ -168,7 +179,7 @@ module Strata
 
             existing_models = load_existing_models_context
             context_section = if existing_models && !existing_models.empty?
-              "\n\nExisting model patterns for consistency:\n#{existing_models}"
+              "\n\nExisting semantic model fields for naming comparison:\n#{existing_models}"
             else
               ""
             end
@@ -190,17 +201,21 @@ module Strata
           def load_existing_models_context
             return nil unless Dir.exist?("models")
 
-            model_files = Dir.glob("models/**/tbl.*.yml").first(100) # Limit to 5 for performance
+            model_files = Dir.glob("models/**/tbl[._]*.yml").first(100) # Limit to 5 for performance
             return nil if model_files.empty?
 
             contexts = model_files.filter_map do |file|
               model = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true) || {}
               fields_summary = (model["fields"] || []).map do |f|
-                "#{f["name"]} (#{f["type"]}) data type: #{f["data_type"]}"
+                expression = f["expression"]
+                expression_sql = expression.is_a?(Hash) ? expression["sql"] : expression
+                "#{f["name"]} (#{f["type"]}) data type: #{f["data_type"]}, expression: #{expression_sql}"
               end.join("\n\t")
-              "Model: #{model["name"]} \n Fields: \n\t#{fields_summary}"
+              "Model: #{model["name"]}, physical table: #{model["physical_name"]}\n Fields: \n\t#{fields_summary}"
             rescue => e
-              warn "Failed to load model file #{file}: #{e.message}" if ENV["DEBUG"]
+              if ENV["DEBUG"]
+                Output.print_warning("Failed to load model file #{file}: #{e.message}")
+              end
               nil
             end
 

data/lib/strata/cli/api/client.rb

@@ -4,12 +4,14 @@ require "faraday"
 require "faraday/multipart"
 require "json"
 require_relative "connection_error_handler"
+require_relative "response_error_handler"
 
 module Strata
   module CLI
     module API
       class Client
         include ConnectionErrorHandler
+        include ResponseErrorHandler
 
         def initialize(server_url, api_key)
           @server_url = server_url.chomp("/")
@@ -65,6 +67,21 @@ module Strata
           deployments.first
         end
 
+        def branches(project_id)
+          response = with_connection_error_handling(@server_url) { connection.get(branches_url(project_id)) }
+          return [] if response.status == 404
+
+          handle_response(response)
+        end
+
+        def delete_branch(project_id, branch_id)
+          response = with_connection_error_handling(@server_url) { connection.delete(branch_url(project_id, branch_id)) }
+          return false if response.status == 404
+
+          handle_response(response)
+          true
+        end
+
         def create_project(name, uid, description: nil, git: nil, production_branch: "main")
           url = "#{@server_url}/api/v1/projects"
           response = with_connection_error_handling(@server_url) do
@@ -96,73 +113,16 @@ module Strata
           end
         end
 
-        def handle_response(response)
-          case response.status
-          when 200..299
-            response.body
-          when 401
-            raise Strata::CommandError, "Authentication failed. Check your API key."
-          when 403
-            raise Strata::CommandError, "Access denied. You don't have permission for this action."
-          when 404
-            raise Strata::CommandError, "Resource not found."
-          when 422
-            errors = extract_errors(response.body)
-            raise Strata::CommandError, "Validation failed: #{errors}"
-          when 500..599
-            raise Strata::CommandError, "Server error: #{response.status}"
-          else
-            raise Strata::CommandError, "Unexpected response: #{response.status}"
-          end
-        rescue Faraday::Error => e
-          raise Strata::CommandError, "Network error: #{e.message}"
+        def deployment_url(project_id, branch_id)
+          "#{@server_url}/api/v1/projects/#{project_id}/b/#{branch_id}/deploys"
         end
 
-        def extract_errors(body)
-          # Handle nil or empty body
-          return "Unknown error" if body.nil? || body.empty?
-
-          # Check if it's an HTML error page (Rails error page)
-          if body.is_a?(String) && body.include?("<!DOCTYPE html>")
-            # Try to extract error message from HTML
-            if body =~ %r{<h1[^>]*>(.*?)</h1>}
-              return "Server error: #{::Regexp.last_match(1).strip}"
-            elsif body =~ %r{<title[^>]*>(.*?)</title>}
-              return "Server error: #{::Regexp.last_match(1).strip}"
-            else
-              return "Server returned an HTML error page. Check server logs for details."
-            end
-          end
-
-          # Parse JSON string if needed
-          parsed_body = if body.is_a?(String)
-            begin
-              JSON.parse(body)
-            rescue JSON::ParserError
-              return body[0..200] # Return first 200 chars if not JSON
-            end
-          else
-            body
-          end
-
-          # Extract error messages from various formats
-          if parsed_body.is_a?(Hash)
-            if parsed_body["errors"].is_a?(Array)
-              parsed_body["errors"].join(", ")
-            elsif parsed_body["error"].is_a?(String)
-              parsed_body["error"]
-            elsif parsed_body["message"].is_a?(String)
-              parsed_body["message"]
-            else
-              parsed_body.to_json
-            end
-          else
-            parsed_body.to_s[0..200] # Limit length
-          end
+        def branches_url(project_id)
+          "#{@server_url}/api/v1/projects/#{project_id}/branches"
         end
 
-        def deployment_url(project_id, branch_id)
-          "#{@server_url}/api/v1/projects/#{project_id}/b/#{branch_id}/deploys"
+        def branch_url(project_id, branch_id)
+          "#{@server_url}/api/v1/projects/#{project_id}/b/#{branch_id}"
         end
       end
     end

data/lib/strata/cli/api/response_error_handler.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Strata
+  module CLI
+    module API
+      module ResponseErrorHandler
+        DETAIL_LIMIT = 200
+
+        private
+
+        def handle_response(response)
+          case response.status
+          when 200..299
+            response.body
+          else
+            raise Strata::CommandError, response_error_message(response)
+          end
+        rescue Faraday::Error => e
+          raise Strata::CommandError, "Network error: #{e.message}"
+        end
+
+        def response_error_message(response, default_message: nil)
+          status = response.status
+          return "Server error: #{status}" if (500..599).cover?(status)
+
+          message = default_message || base_response_error_message(status)
+          details = extract_error_details(response.body)
+          return message unless details
+
+          return "#{message}: #{details}" if status == 422
+
+          "#{message} Details: #{details}"
+        end
+
+        def base_response_error_message(status)
+          case status
+          when 401
+            "Authentication failed. Check your API key."
+          when 403
+            "Access denied. You don't have permission for this action."
+          when 404
+            "Resource not found."
+          when 422
+            "Validation failed"
+          else
+            "Request failed with status #{status}."
+          end
+        end
+
+        def extract_error_details(body)
+          return nil if body.nil? || (body.respond_to?(:empty?) && body.empty?)
+
+          return extract_html_error_details(body) if body.is_a?(String) && body.include?("<!DOCTYPE html>")
+
+          parsed_body = parse_error_body(body)
+          details = details_from_parsed_body(parsed_body)
+          truncate_error_detail(details)
+        end
+
+        def extract_html_error_details(body)
+          detail = if body =~ %r{<h1[^>]*>(.*?)</h1>}m
+            ::Regexp.last_match(1)
+          elsif body =~ %r{<title[^>]*>(.*?)</title>}m
+            ::Regexp.last_match(1)
+          else
+            "Server returned an HTML error page."
+          end
+
+          truncate_error_detail(detail)
+        end
+
+        def parse_error_body(body)
+          return body unless body.is_a?(String)
+
+          JSON.parse(body)
+        rescue JSON::ParserError
+          body
+        end
+
+        def details_from_parsed_body(parsed_body)
+          case parsed_body
+          when Hash
+            parsed_body = parsed_body.transform_keys(&:to_s)
+
+            if parsed_body["errors"].is_a?(Array)
+              parsed_body["errors"].join(", ")
+            elsif parsed_body["errors"].is_a?(Hash)
+              parsed_body["errors"].flat_map do |field, messages|
+                Array(messages).map { |message| "#{field} #{message}" }
+              end.join(", ")
+            elsif parsed_body["error"].is_a?(String)
+              parsed_body["error"]
+            elsif parsed_body["message"].is_a?(String)
+              parsed_body["message"]
+            else
+              parsed_body.to_json
+            end
+          else
+            parsed_body.to_s
+          end
+        end
+
+        def truncate_error_detail(detail)
+          detail = detail.to_s.gsub(/\s+/, " ").strip
+          return nil if detail.empty?
+
+          (detail.length > DETAIL_LIMIT) ? "#{detail[0...DETAIL_LIMIT]}..." : detail
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/error_reporter.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "time"
+require_relative "output"
 
 module Strata
   module CLI
@@ -63,7 +64,9 @@ module Strata
           f.puts("")
         end
       rescue => e
-        warn "Failed to write CLI log: #{e.message}" if ENV["DEBUG"]
+        if ENV["DEBUG"]
+          Output.print_warning("Failed to write CLI log: #{e.message}")
+        end
       end
     end
   end

data/lib/strata/cli/generators/datasource.rb

@@ -2,6 +2,7 @@
 
 require_relative "group"
 require "open3"
+require_relative "../output"
 
 module Strata
   module CLI
@@ -24,7 +25,7 @@ module Strata
 
         def add_datasource_config
           @ds_key = get_unique_ds_key
-          say_status :adapter, "adding #{adapter} config to datasources", :yellow
+          Output.print_status(:adapter, "adding #{adapter} config to datasources", type: :warning, context: self)
 
           # Interactive mode: write config directly from prompts
           config_yaml = {@ds_key => options[:config]}.to_yaml.sub(/^---\n/, "\n")
@@ -44,12 +45,12 @@ module Strata
         end
 
         def install_duckdb_gem
-          say_status :gem, "Installing duckdb gem...", :yellow
+          Output.print_status(:gem, "Installing duckdb gem...", type: :warning, context: self)
 
           begin
             # Install the duckdb gem
             run "gem install duckdb", verbose: false, capture: true
-            say_status :success, "duckdb gem installed successfully", :green
+            Output.print_status(:success, "duckdb gem installed successfully", type: :success, context: self)
           rescue => e
             raise DWH::ConfigError, "Failed to install duckdb gem: #{e.message}"
           end

data/lib/strata/cli/generators/group.rb

@@ -1,10 +1,47 @@
 # frozen_string_literal: true
 
+require_relative "../output"
+
 module Strata
   module CLI
     module Generators
       class Group < Thor::Group
         include Thor::Actions
+        include Output
+
+        class QuietActionsShell < Thor::Shell::Color
+          DEFAULT_ALLOWED_STATUSES = %w[
+            created
+            setup
+            clone
+            success
+            adapter
+            gem
+          ].freeze
+
+          def initialize(verbose: false, allowed_statuses: DEFAULT_ALLOWED_STATUSES)
+            super()
+            @verbose = verbose
+            @allowed_statuses = allowed_statuses
+          end
+
+          def say_status(status, message, log_status = true)
+            return super if @verbose
+            return if log_status == false
+
+            s = status.to_s
+            return super if @allowed_statuses.include?(s)
+
+            nil
+          end
+        end
+
+        no_commands do
+          def initialize(*args)
+            super
+            @shell = QuietActionsShell.new(verbose: options[:verbose] == true)
+          end
+        end
 
         def self.source_root
           File.expand_path("templates/", __dir__)

data/lib/strata/cli/generators/migration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "group"
+require_relative "../output"
 
 module Strata
   module CLI
@@ -28,7 +29,7 @@ module Strata
           # Write the updated template
           create_file output_path, updated_content
 
-          say_status :created, output_path, :green
+          Output.print_status(:created, output_path, type: :success, context: self)
         end
 
         private