strata-cli 0.1.0.beta

data/lib/strata/cli/generators/templates/rel.domain.yml

@@ -0,0 +1,43 @@
+# Define relationshps between tables for a given universe
+
+# Required: The datasource these relationships are valid for.
+# The chosen tables will be scoped to those within this datasource.
+# Strata does not support cross datasource joins
+datasource: "<datasource_name>"
+
+# Define relationships between tables. The table names used here should
+# correspond to the name given in its respective model file and not the
+# physical name (often they are same).
+# NOTE: Strata does not support many_to_many joins.
+
+# Example: One-to-many relationship (customer has many orders)
+# customer_orders:
+#   left: "customers"
+#   right: "orders" 
+#   join: "left.id = right.customer_id"
+#   cardinality: "one_to_many"
+
+# Example: Many-to-one relationship (orders belong to customer)
+# order_customer:
+#   left: "orders"
+#   right: "customers"
+#   join: "left.customer_id = right.id"
+#   cardinality: "many_to_one"
+#   # Whether measurs should be aggregated from the low cardinality
+#   # table. In most cases this will overcount.
+#   allow_measure_expansion: true|false (default false)
+
+# Example: One-to-one relationship (user has one profile)
+# user_profile:
+#   left: "users"
+#   right: "user_profiles"
+#   join: "left.id = right.user_id"
+#   cardinality: "one_to_one"
+
+# Example: Compound join
+# user_roles:
+#   left: "users"
+#   right: "roles"
+#   join: "left.id = right.user_id AND left.id = right.role_id"
+#   cardinality: "one_to_many"
+

data/lib/strata/cli/generators/templates/strata.yml

@@ -0,0 +1,24 @@
+# Strata Configuration file. Do not check this into git.
+#
+# This file contains credentials and local-only configuration.
+# Project-level configuration (project_id, server) should be in project.yml.
+#
+# Strata uses API keys to configure access. Please get your API key
+# from your Strata admins.  You can regenerate/revoke API keys as
+# needed on the server.  You must be Developer on a Project to modify
+# it or you must be System Manager to be able to create new projects.
+api_key: <%= options[:api_key] || "YOUR_STRATA_API_KEY" %>
+
+# Alternatively, you can configure API keys per environment (different Strata server instances).
+# Each environment represents a separate Strata cluster (dev, staging, production).
+# Use -e [ENVIRONMENT] flag when deploying to select the environment.
+# Example:
+# production:
+#   api_key: YOUR_PRODUCTION_API_KEY
+# staging:
+#   api_key: YOUR_STAGING_API_KEY
+#
+
+# Credentials here are stored per datasource. These credentials
+# should be set via `strata ds auth DS_KEY`. DS_KEY should match the datasouces 
+# yaml node key for the datasource you are trying to update.

data/lib/strata/cli/generators/templates/table.table_name.yml

@@ -0,0 +1,118 @@
+# Semantic Table Model
+#
+# Define the Measures and Dimensions that should be attached to this table.
+# Note: Relationships are managed separately and should not be defined in this file.
+
+# Required: The datasource this table belongs to. This should be
+# either the datasource key or datasource name.
+datasource: "<datasource_name>"
+
+# Required: The logical name for this table in the semantic model. Must be unique
+# within this datasource. You can have mulitple tables point to the same physical table.
+name: "<table_name>"
+
+# Required: The physical table name in the actual database. This can be prefixed 
+# with catalog and schema as needed. Be sure to check whether your data wareshouse
+# supports cross schema/catalog queries.
+physical_name: "<physical_table_name>"
+
+# Required: Cost number influences how the table is preferentially
+# selected. If multiple tables can answer the same question, 
+# the lowest cost table is selected..
+# Dimension tables should generally be lower cost and your 
+# hot tier tables should be lower than cold tier.
+cost: 10
+
+# Optional: If this is a snapshot table like an inventory table, you can 
+# set the snapshot date dimension here. This will allow the creation of 
+# snapshot measures on this table.
+# snapshot_date: <snapshot dimension name>
+
+# Optional: Tag table for additional metadata.
+# tags:
+#   - marketing
+#   - ops
+
+# Optional: Define table partitioning constraints
+# This tells the semantic engine about data availability/constraints
+# Only **between** and **in_list** predicates are supported.
+# partition:
+#   # Example: Table only contains 2 years of data
+#   # *Must reference a dimension mapped to this table. 
+#   - dimension: Region Date 
+#     predicate: between 
+#     filter_value: 2y
+#     filter_value_end: 1d
+#     description: "Table only has rolling 2 year data"
+#
+#   # Example: Table is partitioned by region
+#   - dimension: Region
+#     predicate: in_list
+#     filter_value: us-east, us-west, europe
+#     description: "Table only has 3 regions of 5"
+
+# Imports are processed first, then local field definitions are merged in
+# This allows you to inherit common field definitions and override or extend them
+# Paths should be relative to this file.
+# imports:
+#    - "path/to/other/table.yml"
+#    - "common/shared_fields.yml"
+
+# Define Measures and dimensions that should be mapped to this table
+fields:
+  # Example field definition structure:
+  # - type: dimension|measure (Required)
+  #   name: My Field Name (Required)
+  #   description: Describing my awesome field
+  #   data_type: string|integer|bigint|decimal|date|date_time|boolean|binary (Required)
+  #   hidden: true|false
+  #   
+  #   # Optional: UI rendering of the field  
+  #   display_type: default|html|url|email|phone_number|image  
+  #
+  #   # Optional: Specific formatting to be applied (will supercede display_type)
+  #   formatter: currency_usd|percent|thousands|millions|billions|(custom js function using numeraljs/momentjs)
+  #
+  #   # Optional: disable listing individual elements (dimension only). Good to do that for 
+  #   # high cardinality columns like account_id
+  #   disable_value_listing: true|false
+  #   # Optional: limit on items from this field that should be shown. Will affect list cache size.
+  #   # Dimensions only. Default is 1000
+  #   value_list_size: 1000
+  #
+  #   # Optional: For date/time types only. Set of grainularities this date should support. 
+  #   # Default all. raw, second, minute, hour, day, week, month, quarter, year
+  #   grains:
+  #     - day
+  #     - week
+  #     - month
+  #     - quarter
+  #     - year
+  #
+  #   # Required: Defines how this field will query this table
+  #   expresssion:
+  #     primary_key: true|false (optional)
+  #     lookup: true|false (optional)
+  #     array: true|false  (optional)
+  #     sql: my_field_column (Required)
+  #
+  #   # Optional: Exclude certain dimnesions from the group by/filter
+  #   exclusion_type: exclude|exclude_all_except|exclude_all
+  #   exclusions: # (Required when exclusion type is set and isnt exclude_all)
+  #     - type: table|dimension|universe (Required)
+  #       filter: ignore|only|apply (Required)
+  #       entities:
+  #         - <entity name>
+  #         - <entity name>
+  #
+  #   # Optional: Inclusions force calculation at lower level before rolling up 
+  #   inclusions:
+  #     filter: ignore|only|apply
+  #     aggregation: percentile_cont(0.5) WITHIN GROUP (ORDER BY @exp) # Final rollup calculation. Base calc is expression -> sql 
+  #     dimensions:
+  #       - <dimension name>
+  #       - <dimension name>
+  #
+  #   # Optional: Snapshot measures type. Will force calc to starting or ending period.       
+  #   # Table must also set Snapshot date value.  
+  #   snapshot: ending|beginning   

data/lib/strata/cli/generators/templates/test.yml

@@ -0,0 +1,34 @@
+# Test Definition
+# 
+# This file defines a test case for validating semantic model queries.
+# Tests verify that the Planner generates correct SQL from your semantic model.
+# Tests run on the server during deployment.
+
+# Required: Display name for this test
+name: <test_name>
+
+# Required: List of semantic field names to query
+# These must match field names defined in your model files
+projections:
+  - Field Name 1
+  - Field Name 2
+
+# Optional: Filter conditions to apply to the query
+# filters:
+#   - field: Date Field
+#     predicate: between
+#     filter_value: "2024-01-01"
+#     filter_value_end: "2024-12-31"
+#   - field: Status
+#     predicate: equals
+#     filter_value: "active"
+
+# Required: At least ONE assertion must be present (assert_sql or assert_regex)
+
+# Full SQL assertion - the complete SQL you expect the Planner to generate
+# Use this for exact matching (whitespace normalized)
+# assert_sql: "SELECT column1, column2 FROM table_name WHERE condition"
+
+# OR Regex assertion - pattern to match against generated SQL
+# Use this for partial/flexible matching
+# assert_regex: "column_name.*table_name"

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "group"
+require "yaml"
+
+module Strata
+  module CLI
+    module Generators
+      # Generates test YAML files from templates.
+      class Test < Group
+        argument :name, type: :string, desc: "Test name"
+
+        def create_test_file
+          output_path = File.join("tests", "#{slugify(name)}.yml")
+
+          # Ensure directory exists
+          empty_directory "tests"
+
+          # Load template and update with user inputs
+          template_content = load_template
+          updated_content = update_template(template_content)
+
+          # Write the updated template
+          create_file output_path, updated_content
+
+          say_status :created, output_path, :green
+        end
+
+        private
+
+        def load_template
+          template_path = File.join(File.dirname(__FILE__), "templates", "test.yml")
+          File.read(template_path)
+        end
+
+        def update_template(template_content)
+          template_content.gsub("<test_name>", name)
+        end
+
+        def slugify(text)
+          text.to_s.downcase
+            .gsub(/[^a-z0-9]+/, "_")
+            .gsub(/^_|_$/, "")
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/guard.rb

@@ -0,0 +1,21 @@
+require_relative "utils"
+module Strata
+  module CLI
+    module Guard
+      ALLOWED_COMMANDS = %w[
+        init
+        help
+        adapters
+        version
+        deploy
+      ]
+      def invoke_command(command, *args)
+        Utils.exit_error_if_not_strata! unless ALLOWED_COMMANDS.include?(command.name)
+        super
+      rescue Strata::CommandError => e
+        shell.say_error "ERROR: #{e.message}", :red
+        exit 1
+      end
+    end
+  end
+end

data/lib/strata/cli/helpers/color_helper.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Strata
+  module CLI
+    module ColorHelper
+      THEME = {
+        success: :green,
+        error: %i[red bold],
+        warning: :yellow,
+        info: :cyan,
+        title: %i[cyan bold],
+        highlight: %i[cyan bold],
+        dim: :bright_black,
+        primary: :blue,
+        secondary: :magenta,
+        border: %i[cyan dim],
+        selected: %i[green bold],
+        disabled: :dim
+      }.freeze
+
+      class << self
+        def pastel
+          @pastel ||= Pastel.new(enabled: $stdout.tty?)
+        end
+
+        def success(text = nil)
+          apply_theme(:success, text)
+        end
+
+        def error(text = nil)
+          apply_theme(:error, text)
+        end
+
+        def warning(text = nil)
+          apply_theme(:warning, text)
+        end
+
+        def info(text = nil)
+          apply_theme(:info, text)
+        end
+
+        def title(text = nil)
+          apply_theme(:title, text)
+        end
+
+        def highlight(text = nil)
+          apply_theme(:highlight, text)
+        end
+
+        def dim(text = nil)
+          apply_theme(:dim, text)
+        end
+
+        def primary(text = nil)
+          apply_theme(:primary, text)
+        end
+
+        def secondary(text = nil)
+          apply_theme(:secondary, text)
+        end
+
+        def border(text = nil)
+          apply_theme(:border, text)
+        end
+
+        def selected(text = nil)
+          apply_theme(:selected, text)
+        end
+
+        def disabled(text = nil)
+          apply_theme(:disabled, text)
+        end
+
+        def bright_cyan(text = nil)
+          text ? pastel.bright_cyan(text) : :bright_cyan
+        end
+
+        def bright_green(text = nil)
+          text ? pastel.bright_green(text) : :bright_green
+        end
+
+        def bright_yellow(text = nil)
+          text ? pastel.bright_yellow(text) : :bright_yellow
+        end
+
+        private
+
+        def apply_theme(key, text)
+          styles = THEME[key]
+          return styles unless text
+
+          if styles.is_a?(Array)
+            pastel.decorate(text, *styles)
+          else
+            pastel.send(styles, text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/helpers/command_context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+require_relative "datasource_helper"
+require_relative "color_helper"
+require_relative "prompts"
+
+module Strata
+  module CLI
+    module Helpers
+      module CommandContext
+        include DatasourceHelper
+
+        def adapter
+          @adapter ||= create_adapter(datasource_key)
+        end
+
+        def prompt
+          @prompt ||= TTY::Prompt.new
+        end
+
+        def datasource_key
+          @datasource_key ||= resolve_datasource(prompt: prompt)
+        end
+
+        def all_tables
+          @all_tables ||= begin
+            tables = with_spinner("Fetching tables from #{datasource_key}...") { adapter.tables }
+            if tables.empty?
+              # Assuming Prompts and ColorHelper are available in the class or via module
+              say Prompts::MSG_NO_TABLES_FOUND % datasource_key, ColorHelper.warning
+              []
+            else
+              tables
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/helpers/datasource_helper.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Strata
+  module CLI
+    module DatasourceHelper
+      def resolve_datasource(ds_key_arg = nil, prompt: TTY::Prompt.new)
+        # 1. Use argument if provided
+        return validate_datasource(ds_key_arg) if ds_key_arg
+
+        # 2. Use option if provided
+        return validate_datasource(options[:datasource]) if options[:datasource]
+
+        # 3. Check available datasources
+        ds_keys = datasources.keys
+
+        if ds_keys.empty?
+          say "No datasources configured. Run 'strata datasource add' first.", :red
+          nil
+        elsif ds_keys.length == 1
+          # Auto-select if only one
+          ds_key = ds_keys.first
+          say "Using datasource: #{ds_key}", :cyan
+          ds_key
+        else
+          # Prompt selection if multiple
+          prompt.select("Select datasource:", ds_keys)
+        end
+      end
+
+      def create_adapter(ds_key)
+        config = ds_config(ds_key).merge(Credentials.fetch(ds_key))
+        DWH.create(config["adapter"].to_sym, config)
+      end
+
+      def ds_config(ds_key)
+        unless datasources.key?(ds_key)
+          raise "Datasource definition with key #{ds_key} was not found in datasources.yml file."
+        end
+
+        datasources[ds_key]
+      end
+
+      private
+
+      def validate_datasource(ds_key)
+        unless datasources[ds_key]
+          say "Error: Datasource '#{ds_key}' not found in datasources.yml", :red
+          return nil
+        end
+        ds_key
+      end
+
+      def datasources
+        @datasources_cache ||= begin
+          YAML.safe_load_file("datasources.yml", permitted_classes: [Date, Time], aliases: true) || {}
+        rescue Errno::ENOENT
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/helpers/description_helper.rb

@@ -0,0 +1,18 @@
+module Strata
+  module CLI
+    module Helpers
+      module DescriptionHelper
+        def long_desc_from_file(path)
+          # Descriptions are in lib/strata/cli/descriptions/, not in helpers/
+          descriptions_dir = File.join(File.dirname(__dir__), "descriptions")
+          file_path = File.join(descriptions_dir, "#{path}.txt")
+          if File.exist?(file_path)
+            long_desc File.read(file_path)
+          else
+            warn "Warning: Description file not found at #{file_path}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/helpers/project_helper.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../utils/git"
+
+module Strata
+  module CLI
+    module Helpers
+      module ProjectHelper
+        module_function
+
+        # Persists project_id to project.yml file
+        def persist_project_id_to_yml(project_id, project_yml_path: "project.yml")
+          return false unless project_id && !project_id.to_s.strip.empty?
+          return false unless File.exist?(project_yml_path)
+
+          project_config = YAML.safe_load_file(project_yml_path, permitted_classes: [Date, Time], aliases: true) || {}
+          return false if project_config["project_id"] && !project_config["project_id"].to_s.strip.empty?
+
+          project_yml_content = File.read(project_yml_path)
+
+          begin
+            if /^#\s*project_id:\s*$/.match?(project_yml_content)
+              updated_content = project_yml_content.gsub(/^#\s*project_id:\s*$/, "project_id: #{project_id}")
+              File.write(project_yml_path, updated_content)
+            else
+              warning_comment = <<~YAML
+                # WARNING: Do not change this project_id. It links this project to the Strata server.
+                # Changing it may result in creating a new project or deployment failures.
+                project_id: #{project_id}
+              YAML
+
+              File.open(project_yml_path, "a") do |f|
+                f.puts "\n" unless project_yml_content.end_with?("\n")
+                f.puts warning_comment
+              end
+            end
+
+            true
+          rescue Errno::EACCES => e
+            raise Strata::CommandError, "Permission denied writing to #{project_yml_path}: #{e.message}"
+          rescue Errno::ENOSPC => e
+            raise Strata::CommandError, "Disk full: #{e.message}"
+          rescue => e
+            raise Strata::CommandError, "Failed to write to #{project_yml_path}: #{e.message}"
+          end
+        end
+
+        # Persists git URL to project.yml file if missing
+        def persist_git_url_if_missing(project_yml_path: "project.yml")
+          return false unless File.exist?(project_yml_path)
+
+          project_config = YAML.safe_load_file(project_yml_path, permitted_classes: [Date, Time], aliases: true) || {}
+          return false if project_config["git"] && !project_config["git"].to_s.strip.empty?
+
+          git_remote = Utils::Git.git_remote_url
+          return false unless git_remote
+
+          normalized_url = git_remote.chomp("/").chomp(".git")
+          project_yml_content = File.read(project_yml_path)
+
+          begin
+            if /^(\s*)git:\s*$/.match?(project_yml_content)
+              updated_content = project_yml_content.gsub(/^(\s*)git:\s*$/, "\\1git: #{normalized_url}")
+              File.write(project_yml_path, updated_content)
+            else
+              File.open(project_yml_path, "a") do |f|
+                f.puts "\n" unless project_yml_content.end_with?("\n")
+                f.puts "git: #{normalized_url}"
+              end
+            end
+
+            true
+          rescue Errno::EACCES => e
+            raise Strata::CommandError, "Permission denied writing to #{project_yml_path}: #{e.message}"
+          rescue Errno::ENOSPC => e
+            raise Strata::CommandError, "Disk full: #{e.message}"
+          rescue => e
+            raise Strata::CommandError, "Failed to write to #{project_yml_path}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/helpers/prompts.rb

@@ -0,0 +1,42 @@
+module Strata
+  module CLI
+    module Prompts
+      # Relation Command Prompts
+      MSG_SELECT_LEFT_TABLE = "Select LEFT table (the 'many' side usually):"
+      MSG_SELECT_RIGHT_TABLE_ALL = "Select RIGHT table (All):"
+      MSG_SELECT_RIGHT_TABLE_SUGGESTED = "Select RIGHT table (Suggested):"
+      MSG_NO_TABLES_FOUND = "No tables found in %s"
+      MSG_SHOW_OTHER_TABLES = "Show other tables..."
+      MSG_SELECT_FROM_LIST = "Select from list instead?"
+      MSG_JOIN_CONDITION = "  Join Condition (SQL):"
+      MSG_RELATION_PATH = "  Relationship Path:"
+
+      # Table Command Prompts
+      MSG_SEARCH_TABLE = "Search table:"
+      MSG_MODEL_DISPLAY_NAME = "  Model display name:"
+      MSG_MODEL_DESCRIPTION = "  Model description (optional):"
+      MSG_NO_FIELDS_CONFIRMED = "\n⚠️  Warning: No fields confirmed. All fields may have been skipped."
+      MSG_CONTINUE_NO_FIELDS = "Continue creating model with no fields?"
+      MSG_FIELDS_CONFIRMED = "\n  %d field(s) confirmed"
+      MSG_CREATED_MODEL = "\n✔ Created %s"
+      MSG_EDIT_MODEL_HINT = "\n💡 Edit the file to customize field names & expressions"
+
+      MSG_NO_MODELS_DIR = "No models directory found. Run 'strata create table' to create your first model."
+      MSG_NO_MODELS_FOUND = "No models found. Run 'strata create table' to create one."
+      MSG_MODELS_LIST_HEADER = "\n  Semantic Models:\n"
+      MSG_MODELS_COUNT = "\n  Total: %d model(s)\n"
+
+      # Migration hook options
+      MIGRATION_HOOK_OPTIONS = {
+        "pre (before deployment)" => "pre",
+        "post (after deployment)" => "post"
+      }.freeze
+
+      module_function
+
+      def default_migration_hook(operation)
+        (operation == "swap") ? "post (after deployment)" : "pre (before deployment)"
+      end
+    end
+  end
+end