parapet-rails 0.1.0

data/app/services/parapet/explorer_manager.rb

@@ -0,0 +1,402 @@
+module Parapet
+  class ExplorerManager
+    def self.storage_path(filename = nil)
+      base = Parapet::Engine.root.join("storage").to_s
+      filename ? File.join(base, filename) : base
+    end
+
+    def self.summary(type = 'project')
+      root_path = Parapet::Engine.root.to_s
+      scanner = Parapet::DirectoryScanner.new(root_path)
+      full_tree = scanner.scan
+
+      # Use virtualization to get the correct subset for counting
+      focused_tree = virtualize(full_tree, type)
+      files = flatten_files(focused_tree[:children] || [])
+
+      counts = { 'green' => 0, 'red' => 0, 'orange' => 0, 'grey' => 0 }
+      files.each do |f|
+        status = f[:status] || 'grey'
+        counts[status] += 1
+      end
+
+      { 'counts' => counts, 'total_files' => files.count }
+    end
+
+    def self.audit_data(type = 'css')
+      root_path = Parapet::Engine.root.to_s
+      scanner = Parapet::DirectoryScanner.new(root_path)
+      full_tree = scanner.scan
+
+      focused_tree = virtualize(full_tree, type)
+      files = flatten_files(focused_tree[:children] || [])
+
+      audit_stats = {
+        'legibility' => 0,
+        'ergonomic' => 0,
+        'protocol' => 0,
+        'grammar' => 0,
+        'parameter' => 0,
+        'z_collision' => 0 # Future implementation
+      }
+
+      files.each do |f|
+        full_path = File.join(Parapet::Engine.root, f[:path])
+        audit = QSS::QssAuditor.audit_file(full_path)
+        audit[:issues].each do |issue|
+          audit_stats[issue[:type]] += 1 if audit_stats.key?(issue[:type])
+        end
+      end
+
+      audit_stats
+    end
+
+    def self.virtualize(tree, type, perspective: 'project')
+      return nil if tree.nil?
+
+      # The 'perspective' parameter from the switcher overrides the base suite 'type'
+      # unless the perspective is 'project', in which case we use the suite's default view.
+      active_type = (perspective == 'project') ? type : perspective
+
+      case active_type
+      when 'tests', 'test', 'project'
+        # Focus on all test-related directories
+        test_dir = Parapet.test_root
+        test_dirs = [ test_dir, 'features', 'test', 'spec' ].uniq
+        nodes = tree[:children] || []
+        focused_nodes = nodes.select { |c| test_dirs.include?(c[:name]) }
+
+        {
+          name: 'Project Tests',
+          type: 'directory',
+          path: '/project-tests',
+          icon: 'icon-microscope',
+          children: focused_nodes,
+          health: calculate_virtual_health(flatten_files(focused_nodes))
+        }
+      when 'css', 'styles'
+        group_by_styles(tree)
+      when 'views'
+        group_by_views(tree)
+      when 'intentions', 'ideas'
+        group_by_intentions(tree)
+      when 'registry'
+        files = flatten_files(tree[:children] || [])
+        group_by_registry(files)
+      when 'coverage'
+        files = flatten_files(tree[:children] || [])
+        group_by_coverage(files)
+      when 'grammar'
+        group_by_grammar
+      else
+        tree
+      end
+    end
+
+    private
+
+    def self.group_by_views(tree)
+      return nil if tree.nil?
+      nodes = tree[:children] || []
+      app_node = nodes.find { |n| n[:name] == 'app' }
+      return tree unless app_node
+
+      focused_children = filter_view_files(app_node[:children] || [])
+
+      {
+        name: 'Views Suite',
+        type: 'directory',
+        path: '/views',
+        icon: 'icon-layout',
+        iconColor: 'text-emerald-400',
+        children: focused_children,
+        health: calculate_virtual_health(flatten_files(focused_children))
+      }
+    end
+
+    def self.filter_view_files(nodes)
+      nodes.map do |node|
+        if node[:type] == 'directory'
+          children = filter_view_files(node[:children] || [])
+          node.merge(children: children) if children.any?
+        elsif [ 'html', 'erb', 'qss' ].include?(node[:ext])
+          node
+        end
+      end.compact
+    end
+
+    def self.group_by_intentions(tree)
+      return nil if tree.nil?
+
+      # For "Intentions/Code Suite", we focus on the app directory as the source of truth
+      nodes = tree[:children] || []
+      app_node = nodes.find { |n| n[:name] == 'app' }
+
+      # If app doesn't exist (unlikely in Rails), fallback to tree
+      return tree unless app_node
+
+      {
+        name: 'Application Intentions',
+        type: 'directory',
+        path: '/intentions',
+        icon: 'icon-lightbulb',
+        children: app_node[:children],
+        health: app_node[:health]
+      }
+    end
+
+    def self.group_by_styles(tree)
+      return nil if tree.nil?
+
+      # For CSS Suite, we show both Views and Styles in their Rails hierarchy
+      nodes = tree[:children] || []
+
+      # Helper to find a path in the tree
+      find_node = ->(current_nodes, name) { (current_nodes || []).find { |n| n[:name] == name } }
+
+      app_node = find_node.call(nodes, 'app')
+      return tree unless app_node
+
+      # Filter for views and styles within the app directory
+      focused_children = filter_style_and_view_files(app_node[:children] || [])
+
+      {
+        name: 'Styles Suite',
+        type: 'directory',
+        path: '/styles',
+        icon: 'icon-palette',
+        iconColor: 'text-indigo-400',
+        children: focused_children,
+        health: calculate_virtual_health(flatten_files(focused_children))
+      }
+    end
+
+    def self.filter_style_and_view_files(nodes)
+      nodes.map do |node|
+        if node[:type] == 'directory'
+          children = filter_style_and_view_files(node[:children] || [])
+          node.merge(children: children) if children.any?
+        elsif [ 'html', 'erb' ].include?(node[:ext])
+          node
+        end
+      end.compact
+    end
+
+    def self.group_by_grammar
+      # Define the Agentic CSS Grammar categories
+      categories = [
+        {
+          name: 'Core Syntax',
+          icon: 'icon-code',
+          color: 'text-indigo-400',
+          rules: [
+            { name: 'Noun (ID)', syntax: '#[id]', description: 'Structural Identity' },
+            { name: 'Adjective (Class)', syntax: '.[class]', description: 'Characteristic' },
+            { name: 'Parameter (Bracket)', syntax: '[value]', description: 'Dimension/Attribute' }
+          ]
+        },
+        {
+          name: 'Spatial Coordinates',
+          icon: 'icon-move',
+          color: 'text-emerald-400',
+          rules: [
+            { name: 'X-Position', syntax: '.pos-x[0...2000]', description: 'Left offset in qss-units' },
+            { name: 'Y-Position', syntax: '.pos-y[0...2000]', description: 'Top offset in qss-units' },
+            { name: 'Right-Position', syntax: '.pos-r[0...2000]', description: 'Right offset in qss-units' },
+            { name: 'Bottom-Position', syntax: '.pos-b[0...2000]', description: 'Bottom offset in qss-units' }
+          ]
+        },
+        {
+          name: 'Dimensions',
+          icon: 'icon-maximize',
+          color: 'text-amber-400',
+          rules: [
+            { name: 'Width', syntax: '.w[0...2000]', description: 'Width in qss-units' },
+            { name: 'Height', syntax: '.h[0...2000]', description: 'Height in qss-units' },
+            { name: 'Width %', syntax: '.w-pct[0...1000]', description: 'Width in 0.1% increments' },
+            { name: 'Height %', syntax: '.h-pct[0...1000]', description: 'Height in 0.1% increments' }
+          ]
+        },
+        {
+          name: 'Visual Depth',
+          icon: 'icon-layers',
+          color: 'text-purple-400',
+          rules: [
+            { name: 'Canvas', syntax: '.depth[canvas]', description: 'z-index: 0' },
+            { name: 'Content', syntax: '.depth[content]', description: 'z-index: 100' },
+            { name: 'UI', syntax: '.depth[ui]', description: 'z-index: 500' },
+            { name: 'Overlay', syntax: '.depth[overlay]', description: 'z-index: 900' },
+            { name: 'Modal', syntax: '.depth[modal]', description: 'z-index: 1000' }
+          ]
+        }
+      ]
+
+      virtual_children = categories.map do |cat|
+        {
+          name: cat[:name],
+          type: 'directory',
+          path: "/grammar/#{cat[:name].parameterize}",
+          icon: cat[:icon],
+          iconColor: cat[:color],
+          children: cat[:rules].map { |r|
+            {
+              name: r[:name],
+              type: 'file',
+              path: "/grammar/#{cat[:name].parameterize}/#{r[:name].parameterize}",
+              icon: 'icon-file-text',
+              status: 'grey',
+              metadata: { syntax: r[:syntax], description: r[:description] }
+            }
+          },
+          health: nil
+        }
+      end
+
+      { name: 'Grammar', type: 'directory', path: '/grammar', icon: 'icon-book', children: virtual_children }
+    end
+
+    def self.group_by_registry(files)
+      # Filter for files that might contain QSS Nouns (views and partials)
+      view_files = files.select do |f|
+        [ 'html', 'erb', 'haml', 'slim' ].include?(f[:ext]) && !f[:path].include?('vendor')
+      end
+
+      registry_nodes = []
+
+      view_files.each do |f|
+        full_path = File.join(Parapet::Engine.root, f[:path])
+        nouns = Parapet::NounDiscovery.discover(full_path)
+        next if nouns.empty?
+
+        nouns.each do |noun|
+          # Find all files related to this noun (e.g. user.rb, user_spec.rb)
+          noun_id = noun[:id].downcase
+          related_files = files.select { |f| f[:name].downcase.start_with?(noun_id) }
+
+          registry_nodes << {
+            name: noun[:id],
+            type: 'directory',
+            path: "/registry/noun/#{noun[:id]}",
+            icon: 'icon-box',
+            iconColor: 'text-indigo-400',
+            children: related_files,
+            health: calculate_virtual_health(related_files),
+            metadata: {
+              source: f[:path],
+              adjectives: noun[:adjectives],
+              is_phantom: noun[:is_phantom],
+              type: 'Noun'
+            }
+          }
+        end
+      end
+
+      # Group nouns into logical categories or just alphabetical for now
+      # In a real app, we'd use metadata to categorize (UI, Layout, Form, etc.)
+      categories = [
+        { name: 'Core Layout', icon: 'icon-layout', color: 'text-blue-400' },
+        { name: 'UI Components', icon: 'icon-component', color: 'text-emerald-500' },
+        { name: 'Form Elements', icon: 'icon-input', color: 'text-amber-500' },
+        { name: 'Media Actors', icon: 'icon-image', color: 'text-purple-500' }
+      ]
+
+      virtual_children = categories.map do |cat|
+        {
+          name: cat[:name],
+          type: 'directory',
+          path: "/registry/#{cat[:name].parameterize}",
+          icon: cat[:icon],
+          iconColor: cat[:color],
+          children: [],
+          health: nil
+        }
+      end
+
+      # Distribute nouns into categories (simple heuristic for demo)
+      registry_nodes.sort_by { |n| n[:name] }.each_with_index do |node, idx|
+        cat_idx = idx % virtual_children.count
+        virtual_children[cat_idx][:children] << node
+      end
+
+      { name: 'Registry', type: 'directory', path: '/registry', icon: 'icon-database', children: virtual_children }
+    end
+
+    def self.group_by_coverage(files)
+      categories = get_categories('coverage')
+
+      virtual_children = categories.map do |cat|
+        # Filter files based on their determined status
+        status_map = {
+          'Regressions' => 'red',
+          'Critical Failures' => 'red',
+          'Healthy (Green Zone)' => 'green',
+          'The Danger Zone' => 'orange',
+          'General / Unsorted' => 'grey'
+        }
+
+        target_status = status_map[cat[:name]]
+        assigned_files = files.select { |f| f[:status] == target_status }
+
+        {
+          name: cat[:name],
+          type: 'directory',
+          path: "/coverage/#{cat[:name].parameterize}",
+          icon: cat[:icon],
+          iconColor: cat[:color],
+          children: assigned_files,
+          health: calculate_virtual_health(assigned_files)
+        }
+      end
+
+      { name: 'Coverage', type: 'directory', path: '/coverage', icon: 'icon-activity qss-icon-activity', children: virtual_children.reject { |c| c[:children].empty? } }
+    end
+
+    private
+
+    def self.flatten_files(nodes)
+      return [] if nodes.nil?
+      list = []
+      nodes.each do |node|
+        if node[:type] == 'file'
+          list << node
+        else
+          # It's a directory, recurse into children
+          list += flatten_files(node[:children])
+        end
+      end
+      list
+    end
+
+    def self.calculate_virtual_health(files)
+      return nil if files.empty?
+      counts = files.group_by { |f| f[:status] }.transform_values { |v| (v.count.to_f / files.count * 100).round }
+      counts.select { |k, v| v > 0 }
+    end
+
+    def self.get_categories(type)
+      base = case type
+      when 'registry'
+               [
+                 { name: 'Identity & Access', icon: 'icon-shield-check', color: 'text-blue-400' },
+                 { name: 'Commerce & Billing', icon: 'icon-credit-card', color: 'text-emerald-500' },
+                 { name: 'Inventory & Catalog', icon: 'icon-package', color: 'text-amber-500' },
+                 { name: 'Engagement & Comms', icon: 'icon-mail', color: 'text-blue-500' },
+                 { name: 'Infrastructure', icon: 'icon-cpu', color: 'text-slate-400' }
+               ]
+      when 'coverage'
+               [
+                 { name: 'Regressions', icon: 'icon-git-branch', color: 'text-red-600' },
+                 { name: 'Critical Failures', icon: 'icon-alert-octagon', color: 'text-red-500' },
+                 { name: 'Healthy (Green Zone)', icon: 'icon-check-circle', color: 'text-emerald-500' },
+                 { name: 'The Danger Zone', icon: 'icon-zap', color: 'text-yellow-500' }
+               ]
+      else
+               []
+      end
+
+      # Always add a catch-all for teaching/realism
+      base << { name: 'General / Unsorted', icon: 'icon-archive', color: 'text-slate-500' }
+      base
+    end
+  end
+end

data/app/services/parapet/file_save_service.rb

@@ -0,0 +1,21 @@
+require "fileutils"
+
+module Parapet
+  class FileSaveService
+    def initialize(user:, full_path:, relative_path:, content:, performed_via: "human")
+      @user = user
+      @full_path = full_path
+      @relative_path = relative_path
+      @content = content
+      @performed_via = performed_via
+    end
+
+    def save!
+      FileUtils.mkdir_p(File.dirname(@full_path))
+      File.write(@full_path, @content)
+      GitSideRefCommitter.new.record!(user: @user, path: @full_path)
+      DraftRecoveryStore.clear!(user: @user, path: @relative_path)
+      ActivityWriter.file_saved!(user: @user, path: @relative_path, performed_via: @performed_via)
+    end
+  end
+end

data/app/services/parapet/git_side_ref_committer.rb

@@ -0,0 +1,50 @@
+require "digest"
+require "open3"
+require "pathname"
+require "tmpdir"
+
+module Parapet
+  class GitSideRefCommitter
+    def initialize(root_path: Parapet::Engine.root.to_s)
+      @root_path = root_path
+    end
+
+    def record!(user:, path:)
+      repository_root = capture!("rev-parse", "--show-toplevel").strip
+      absolute_path = File.expand_path(path, @root_path)
+      relative_path = Pathname.new(absolute_path).relative_path_from(Pathname.new(repository_root)).to_s.tr("\\", "/")
+      raise ArgumentError, "File is outside the repository" if relative_path == ".." || relative_path.start_with?("../")
+
+      ref = "refs/parapet/file-editor-saves/#{user.id}/#{Digest::SHA256.hexdigest(relative_path)}"
+      parent = capture("rev-parse", "--verify", ref, chdir: repository_root)
+      parent_id = parent[:status].success? ? parent[:stdout].strip : nil
+
+      Dir.mktmpdir("parapet-index-") do |directory|
+        index_path = File.join(directory, "index")
+        env = { "GIT_INDEX_FILE" => index_path }
+        capture!("read-tree", "--empty", env: env, chdir: repository_root)
+        capture!("add", "-f", "--", relative_path, env: env, chdir: repository_root)
+        tree = capture!("write-tree", env: env, chdir: repository_root).strip
+        commit_args = [ "-c", "user.name=Parapet", "-c", "user.email=parapet@localhost", "commit-tree", tree ]
+        commit_args.concat([ "-p", parent_id ]) if parent_id
+        commit = capture!(*commit_args, input: "Parapet file save\n\nUser-ID: #{user.id}\n", chdir: repository_root).strip
+        capture!("update-ref", ref, commit, chdir: repository_root)
+        commit
+      end
+    end
+
+    private
+
+    def capture(*args, env: {}, input: nil, chdir: @root_path)
+      stdout, stderr, status = Open3.capture3(env, "git", *args, chdir: chdir, stdin_data: input)
+      { stdout: stdout, stderr: stderr, status: status }
+    end
+
+    def capture!(*args, env: {}, input: nil, chdir: @root_path)
+      result = capture(*args, env: env, input: input, chdir: chdir)
+      raise "Git operation failed: #{result[:stderr]}" unless result[:status].success?
+
+      result[:stdout]
+    end
+  end
+end

data/app/services/parapet/noun_discovery.rb

@@ -0,0 +1,26 @@
+module Parapet
+  # Discovers the QSS nouns (element ids) a view file declares, so the CSS Suite can list the
+  # elements on the page in view.
+  #
+  # PLACEHOLDER. Noun Discovery is shelved until the CSS Suite is built (decision 2026-09-25).
+  # It discovers nothing yet. Callers expect a list, so it returns an empty one, and it says so
+  # in the log (once per process) so the gap is never silent. The pending example in
+  # spec/services/parapet/noun_discovery_spec.rb describes the real behavior and starts failing
+  # loudly, as RSpec requires, the moment that behavior exists.
+  class NounDiscovery
+    REMINDER = "[Parapet] Noun Discovery is a placeholder (shelved until the CSS Suite): " \
+                 "Parapet::NounDiscovery.discover returns no nouns, so registry views list none."
+
+    def self.discover(_path)
+      remind_once
+      []
+    end
+
+    def self.remind_once
+      return if @reminded
+      @reminded = true
+      Rails.logger&.warn(REMINDER)
+    end
+    private_class_method :remind_once
+  end
+end

data/app/services/parapet/publish_gate.rb

@@ -0,0 +1,83 @@
+require 'open3'
+
+module Parapet
+  class PublishGate
+    class Result
+      attr_reader :run_history
+
+      def initialize(run_history)
+        @run_history = run_history
+      end
+
+      def passed?
+        @run_history.passed?
+      end
+    end
+
+    def initialize(triggered_by_actor_type: "human", user: Current.user, performed_via: nil)
+      @actor_type = triggered_by_actor_type
+      @user = user
+      @performed_via = performed_via || (triggered_by_actor_type == "ai_agent" ? "ai_agent" : "human")
+      # Use Rails.root to point to the host application, but fallback to Engine root
+      # if we are in the engine's own development environment (where Rails.root is dummy)
+      @root_path = if defined?(Rails) && Rails.root.join('spec').exist?
+                     Rails.root.to_s
+      elsif defined?(Rails) && Rails.root.join('features').exist?
+                     Rails.root.to_s
+      else
+                     Parapet::Engine.root.to_s
+      end
+    end
+
+    def run
+      run_history = Parapet::RunHistory.create!(
+        run_type: "publish",
+        status: "running",
+        triggered_by_actor_type: @actor_type,
+        user_id: @user&.id,
+        performed_via: @performed_via,
+        started_at: Time.current,
+        command: "bundle exec rspec && bundle exec cucumber"
+      )
+
+      full_output = ""
+      final_status = "passed"
+      final_exit_code = 0
+
+      # Determine which commands to run based on presence of directories
+      commands = []
+      commands << "bundle exec rspec" if Dir.exist?(File.join(@root_path, 'spec'))
+      commands << "bundle exec cucumber" if Dir.exist?(File.join(@root_path, 'features'))
+
+      # If no commands to run, it passes by default (or should it fail? Spec implies both run)
+      # Spec says: "Run RSpec, then Cucumber... fail fast"
+
+      commands.each do |cmd|
+        stdout, stderr, status = Open3.capture3(cmd, chdir: @root_path)
+        full_output += stdout + stderr
+
+        if status.exitstatus != 0
+          final_status = "failed"
+          final_exit_code = status.exitstatus
+          break
+        end
+      end
+
+      run_history.update!(
+        status: final_status,
+        exit_code: final_exit_code,
+        raw_output: full_output,
+        finished_at: Time.current
+      )
+
+      ActivityWriter.run!(
+        run_history: run_history,
+        user: @user,
+        action: "publish",
+        performed_via: @performed_via
+      )
+
+      Result.new(run_history)
+    end
+  end
+end