easy_creds 1.0.1

data/lib/easy_creds/onboarding/gem_setup.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Onboarding
+    class GemSetup
+      GLOBAL_DIRS = %w[log templates projects].freeze
+
+      def self.run(prompt:)
+        new(prompt: prompt).run
+      end
+
+      def initialize(prompt:)
+        @prompt = prompt
+      end
+
+      def run
+        Theme.section('easy_creds — first time setup')
+
+        global_dir = ask_global_dir
+        EasyCreds.configure { |c| c.global_dir = global_dir }
+        create_dirs(global_dir)
+        seed_default_template(global_dir)
+        seed_projects_registry(global_dir)
+        check_op_cli!
+        ensure_signed_in
+        vault = pick_vault
+        EasyCreds.configure { |c| c.default_vault = vault }
+        write_config(global_dir)
+
+        Theme.success("Setup complete. Config written to #{global_dir}/config.yml")
+        Theme.notice('Run `easy_creds onboard` inside a project to scaffold credentials.')
+        global_dir
+      end
+
+      private
+
+      def ask_global_dir
+        default = File.expand_path('~/.easy_creds')
+        raw = @prompt.ask('Global config directory:', default: default)
+        File.expand_path(raw)
+      end
+
+      def create_dirs(global_dir)
+        GLOBAL_DIRS.each { |sub| FileUtils.mkdir_p(File.join(global_dir, sub)) }
+        Theme.notice("Created #{global_dir}/")
+      end
+
+      def seed_default_template(global_dir)
+        dest = File.join(global_dir, 'templates', 'default.yml')
+        return if File.exist?(dest)
+
+        src = File.join(Templates::Registry::BUNDLED_DIR, 'default-beastmode.yml')
+        return unless File.exist?(src)
+
+        FileUtils.cp(src, dest)
+        Theme.notice("Seeded default template at #{dest}")
+      end
+
+      def seed_projects_registry(global_dir)
+        projects_path = File.join(global_dir, 'projects.yml')
+        return if File.exist?(projects_path)
+
+        data = { 'schema_version' => 1, 'projects' => [] }
+        File.write(projects_path, data.to_yaml)
+        FileUtils.chmod(0o600, projects_path)
+      end
+
+      def check_op_cli!
+        return if system('which op > /dev/null 2>&1')
+
+        Theme.failure('op CLI not found. Install with: brew install 1password-cli')
+        exit 2
+      end
+
+      def ensure_signed_in
+        return if op_signed_in?
+
+        Theme.notice('Not signed in to 1Password.')
+        puts "  Run #{Theme.bold('op signin')} in another terminal, then press Enter..."
+        $stdin.gets
+        ensure_signed_in
+      end
+
+      def op_signed_in?
+        system('op whoami > /dev/null 2>&1')
+      end
+
+      def pick_vault
+        VaultPicker.pick(@prompt)
+      end
+
+      def write_config(global_dir)
+        config_path = File.join(global_dir, 'config.yml')
+        Configuration.write_file!(EasyCreds.config, config_path)
+      end
+    end
+  end
+end

data/lib/easy_creds/onboarding/project_wizard.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Onboarding
+    class ProjectWizard
+      def self.run(prompt:, root: nil, force: false, non_interactive: false)
+        new(prompt: prompt, root: root, force: force,
+            non_interactive: non_interactive).run
+      end
+
+      def initialize(prompt:, root: nil, force: false, non_interactive: false)
+        @prompt          = prompt
+        @root            = root ? Pathname.new(root) : detect_root
+        @force           = force
+        @non_interactive = non_interactive
+        @rails           = @root.join('config/application.rb').exist?
+      end
+
+      def run
+        show_detected_mode
+        template   = pick_template
+        dest       = pick_destination_path
+        customised = customise(template)
+        write_example(customised, dest)
+        offer_bootstrap if @rails && !@non_interactive
+      end
+
+      private
+
+      def show_detected_mode
+        mode = @rails ? Theme.ok("Rails (#{@root})") : Theme.info("Standalone (#{slug})")
+        puts ''
+        puts "  #{Theme.dim('Project:')} #{mode}"
+        puts ''
+      end
+
+      def pick_template
+        global_dir = EasyCreds.config.global_dir
+        if @non_interactive
+          Templates::Registry.new(global_dir: global_dir).load(:default)
+        else
+          TemplatePicker.choose(prompt: @prompt, global_dir: global_dir)
+        end
+      end
+
+      def pick_destination_path
+        choices  = destination_choices
+        dest_key = @non_interactive ? :project : @prompt.select('Save example to:', choices, cycle: true)
+        resolve_dest(dest_key)
+      end
+
+      def destination_choices
+        global_dir = EasyCreds.config.global_dir
+        choices = []
+        choices << { name: "project  — #{@root}/config/credentials/example.yml", value: :project } if @rails
+        choices << { name: "global   — #{global_dir}/projects/#{slug}/example.yml", value: :global }
+        choices
+      end
+
+      def resolve_dest(dest_key)
+        global_dir = EasyCreds.config.global_dir
+        if dest_key == :project
+          @root.join('config/credentials/example.yml')
+        else
+          Pathname.new(File.join(global_dir, 'projects', slug, 'example.yml'))
+        end
+      end
+
+      def customise(template)
+        return template if @non_interactive
+
+        renderer = Templates::Renderer.new(template)
+        renderer.customise(@prompt)
+      end
+
+      def write_example(template, dest)
+        if dest.exist? && !@force
+          Theme.failure("#{dest} already exists. Use --force to overwrite.")
+          return
+        end
+
+        dest.parent.mkpath
+        dest.write(template.to_yaml)
+        Theme.success("Wrote #{dest}")
+      end
+
+      def offer_bootstrap
+        return unless @prompt.yes?('Bootstrap config/credentials/development.yml.enc now?', default: false)
+
+        io = CredentialsIO.new(@root)
+        io.ensure_key!('development') unless io.key_exists?('development')
+        Theme.success('Key generated at config/credentials/development.key')
+      end
+
+      def slug
+        File.basename(@root)
+      end
+
+      def detect_root
+        dir = Pathname.new(Dir.pwd)
+        dir = dir.parent until dir.root? || dir.join('config/application.rb').exist?
+        dir.root? ? Pathname.new(Dir.pwd) : dir
+      end
+    end
+  end
+end

data/lib/easy_creds/onboarding/register_prompt.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Onboarding
+    module RegisterPrompt
+      # Returns :registered, :continue, or :quit
+      def self.run(prompt:, project:, registry:)
+        return :continue if registry.find_by_path(project.root)
+
+        Theme.section("New project detected at #{project.root}")
+        choice = prompt.select(
+          'Register this project with easy_creds?',
+          [
+            { name: 'register and continue', value: :register },
+            { name: 'continue without registering', value: :skip },
+            { name: 'quit', value: :quit }
+          ],
+          cycle: true
+        )
+
+        case choice
+        when :register
+          registry.register(
+            name:       project_name(project),
+            path:       project.root.to_s,
+            kind:       project.rails? ? :rails : :standalone,
+            github_url: detect_github_url(project.root)
+          )
+          :registered
+        when :skip then :continue
+        else            :quit
+        end
+      end
+
+      def self.project_name(project)
+        File.basename(project.root.to_s)
+      end
+
+      def self.detect_github_url(root)
+        url = `git -C #{Shellwords.escape(root.to_s)} remote get-url origin 2>/dev/null`.strip
+        url.empty? ? nil : url
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/easy_creds/onboarding/runner.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Onboarding
+    class Runner
+      def self.start(project: nil, **)
+        prompt     = TTY::Prompt.new(interrupt: :exit)
+        config_path = File.join(EasyCreds.config.global_dir, 'config.yml')
+
+        GemSetup.run(prompt: prompt) unless File.exist?(config_path)
+
+        root = project&.root || Dir.pwd
+        ProjectWizard.run(prompt: prompt, root: root, **)
+      end
+    end
+  end
+end

data/lib/easy_creds/onboarding/template_picker.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Onboarding
+    class TemplatePicker
+      def self.choose(prompt:, global_dir: nil)
+        new(prompt: prompt, global_dir: global_dir).choose
+      end
+
+      def initialize(prompt:, global_dir: nil)
+        @prompt     = prompt
+        @global_dir = global_dir
+      end
+
+      def choose
+        registry = Templates::Registry.new(global_dir: @global_dir)
+        choices  = build_choices(registry)
+        name     = @prompt.select('Select a template:', choices, cycle: true)
+        name == :blank ? {} : registry.load(name)
+      end
+
+      private
+
+      def build_choices(registry)
+        choices = registry.list.map { |name| { name: display_name(name, registry), value: name } }
+        choices << { name: 'custom (blank)', value: :blank }
+        choices
+      end
+
+      def display_name(name, registry)
+        source = registry.user_defined?(name) ? Theme.ok('user') : Theme.dim('built-in')
+        "#{name.to_s.ljust(30)} #{source}"
+      end
+    end
+  end
+end

data/lib/easy_creds/overlay.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'active_support/encrypted_configuration'
+require 'active_support/ordered_options'
+require 'active_support/core_ext/hash/deep_merge'
+require 'active_support/core_ext/hash/keys'
+
+module EasyCreds
+  module Overlay
+    # Merge config/credentials/<env>_local.yml.enc on top of the base credentials.
+    #
+    # Accepts either a Rails application (the form the installer-generated
+    # initializer uses) or the explicit (creds, root, env) triple:
+    #
+    #   EasyCreds::Overlay.apply!(Rails.application)
+    #   EasyCreds::Overlay.apply!(Rails.application.credentials, Rails.root, Rails.env)
+    #
+    # @param app_or_creds [#credentials, #root, #env] a Rails application, or the
+    #   credentials object when root/env are supplied explicitly
+    # @param root [String, Pathname, nil] project root (omit when passing an app)
+    # @param env [String, Symbol, nil] environment name (omit when passing an app)
+    # @return [void]
+    def self.apply!(app_or_creds, root = nil, env = nil)
+      if root.nil? && env.nil?
+        app   = app_or_creds
+        creds = app.credentials
+        root  = app.root
+        env   = app.env.to_s
+      else
+        creds = app_or_creds
+        env   = env.to_s
+      end
+
+      enc = Pathname.new(root).join("config/credentials/#{env}_local.yml.enc")
+      key = Pathname.new(root).join("config/credentials/#{env}_local.key")
+
+      return unless enc.exist? && key.exist?
+
+      overlay = ActiveSupport::EncryptedConfiguration.new(
+        config_path: enc.to_s,
+        key_path: key.to_s,
+        env_key: 'RAILS_MASTER_KEY_LOCAL_UNUSED',
+        raise_if_missing_key: false
+      ).config.deep_symbolize_keys
+
+      overlay.each do |top_key, value|
+        merge_key(creds, top_key, value)
+      end
+    rescue StandardError => e
+      warn "[easy_creds_overlay] skipped: #{e.class}: #{e.message}"
+    end
+
+    def self.merge_key(creds, top_key, value)
+      if value.is_a?(Hash)
+        existing = creds.public_send(top_key)
+        base     = existing.respond_to?(:to_h) ? existing.to_h.deep_symbolize_keys : {}
+        creds.public_send(:"#{top_key}=", to_ordered_options(base.deep_merge(value)))
+      else
+        creds.public_send(:"#{top_key}=", value)
+      end
+    end
+    private_class_method :merge_key
+
+    def self.to_ordered_options(hash)
+      hash.each_with_object(ActiveSupport::OrderedOptions.new) do |(k, v), opts|
+        opts[k] = v.is_a?(Hash) ? to_ordered_options(v) : v
+      end
+    end
+    private_class_method :to_ordered_options
+  end
+end

data/lib/easy_creds/project.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  # Detects whether the current working directory is a Rails project or a
+  # standalone directory, and exposes project-scoped paths (credentials dir,
+  # log dir, etc.) to the rest of the gem without coupling to Rails constants.
+  module Project
+    # Returns a Rails or Standalone project object for the given path.
+    def self.detect(cwd = Dir.pwd)
+      root = find_rails_root(Pathname.new(cwd.to_s))
+      root ? Project::Rails.new(root: root) : build_standalone(cwd)
+    end
+
+    def self.build_standalone(cwd)
+      slug       = Pathname.new(cwd.to_s).basename.to_s.gsub(/[^a-z0-9_-]/i, '-').downcase
+      global_dir = Pathname.new(EasyCreds.config.global_dir).expand_path
+      Standalone.new(root: Pathname.new(cwd.to_s), slug: slug, global_dir: global_dir)
+    end
+    private_class_method :build_standalone
+
+    def self.find_rails_root(dir)
+      until dir.root?
+        return dir if dir.join('config/application.rb').exist?
+
+        dir = dir.parent
+      end
+      nil
+    end
+    private_class_method :find_rails_root
+
+    # Represents a Rails application project.
+    class Rails
+      attr_reader :root
+
+      def initialize(root:)
+        @root = Pathname.new(root.to_s)
+      end
+
+      def rails? = true
+      def standalone? = false
+
+      def log_dir         = @root.join('log')
+      def credentials_dir = @root.join('config/credentials')
+      def environments_dir = @root.join('config/environments')
+      def gitignore_path  = @root.join('.gitignore')
+      def git_repo?       = @root.join('.git').exist?
+      def example_template_path = credentials_dir.join('example.yml')
+      def config_file_path = @root.join('config/easy_creds.yml')
+      def slug = @root.basename.to_s
+    end
+
+    # Represents a non-Rails directory (standalone usage).
+    class Standalone
+      attr_reader :root, :slug, :global_dir
+
+      def initialize(root:, slug:, global_dir:)
+        @root       = Pathname.new(root.to_s)
+        @slug       = slug
+        @global_dir = Pathname.new(global_dir.to_s)
+      end
+
+      def rails? = false
+      def standalone? = true
+
+      def log_dir          = @global_dir.join('log')
+      def credentials_dir  = @global_dir.join('projects', slug)
+      def environments_dir = nil
+      def gitignore_path   = @root.join('.gitignore')
+      def git_repo?        = @root.join('.git').exist?
+      def example_template_path = credentials_dir.join('example.yml')
+      def config_file_path = nil
+    end
+  end
+end

data/lib/easy_creds/projects/registry.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Projects
+    Project = Data.define(
+      :name, :path, :kind, :github_url, :template, :last_seen_at, :registered_at
+    ) do
+      def exists_on_disk? = File.directory?(path)
+      def display_path    = path.sub(Dir.home, '~')
+      def rails?          = kind == :rails
+
+      def to_h_yaml
+        {
+          'name'          => name,
+          'path'          => path,
+          'kind'          => kind.to_s,
+          'github_url'    => github_url,
+          'template'      => template&.to_s,
+          'last_seen_at'  => last_seen_at&.iso8601,
+          'registered_at' => registered_at&.iso8601
+        }.compact
+      end
+    end
+
+    class Registry
+      def self.registry_path
+        File.join(EasyCreds.config.global_dir, 'projects.yml')
+      end
+
+      def self.load
+        path = registry_path
+        unless File.exist?(path)
+          return new({ 'schema_version' => 1, 'projects' => [] })
+        end
+
+        data = YAML.safe_load_file(path) ||
+               { 'schema_version' => 1, 'projects' => [] }
+        new(data)
+      end
+
+      def initialize(data)
+        @data     = data
+        @projects = (data['projects'] || []).map { |h| build(h) }
+      end
+
+      attr_reader :projects
+
+      def find_by_path(path)
+        norm = File.expand_path(path.to_s)
+        @projects.find { |p| File.expand_path(p.path) == norm }
+      end
+
+      def find_containing(cwd)
+        norm = File.expand_path(cwd.to_s)
+        @projects
+          .select { |p| norm == File.expand_path(p.path) || norm.start_with?(File.expand_path(p.path) + '/') }
+          .max_by { |p| p.path.length }
+      end
+
+      def register(name:, path:, kind:, github_url: nil, template: nil)
+        norm = File.expand_path(path.to_s)
+        existing = find_by_path(norm)
+        if existing
+          touch(existing)
+          return existing
+        end
+
+        now  = Time.now.utc
+        proj = Project.new(
+          name: name, path: norm, kind: kind.to_sym,
+          github_url: github_url.presence, template: template&.to_sym,
+          last_seen_at: now, registered_at: now
+        )
+        @projects << proj
+        save!
+        proj
+      end
+
+      def touch(project)
+        idx = @projects.index { |p| p.path == project.path }
+        return unless idx
+
+        @projects[idx] = project.with(last_seen_at: Time.now.utc)
+        save!
+        @projects[idx]
+      end
+
+      def remove(project)
+        @projects.reject! { |p| p.path == project.path }
+        save!
+      end
+
+      def prune_missing!
+        gone = @projects.reject(&:exists_on_disk?)
+        return [] if gone.empty?
+
+        gone_paths = gone.map(&:path).to_set
+        @projects.reject! { |p| gone_paths.include?(p.path) }
+        save!
+        gone
+      end
+
+      def save!
+        path = self.class.registry_path
+        FileUtils.mkdir_p(File.dirname(path))
+        out = { 'schema_version' => 1, 'projects' => @projects.map(&:to_h_yaml) }
+        File.write(path, out.to_yaml)
+        FileUtils.chmod(0o600, path)
+      end
+
+      private
+
+      def build(h)
+        Project.new(
+          name:          h['name'] || File.basename(h['path'].to_s),
+          path:          h['path'].to_s,
+          kind:          (h['kind'] || 'standalone').to_sym,
+          github_url:    h['github_url'],
+          template:      h['template']&.to_sym,
+          last_seen_at:  parse_time(h['last_seen_at']),
+          registered_at: parse_time(h['registered_at'])
+        )
+      end
+
+      def parse_time(val)
+        return nil unless val
+        return val if val.is_a?(Time)
+
+        Time.parse(val.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/easy_creds/provider.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  # Registry of available secret-storage providers.
+  # v1 ships only :onepassword. Future providers (env-var, AWS Secrets Manager,
+  # HashiCorp Vault) register here without changing call-sites.
+  module Provider
+    @registry = {}
+
+    class << self
+      def register(name, klass)
+        @registry[name.to_sym] = klass
+      end
+
+      def fetch(name)
+        @registry.fetch(name.to_sym) do
+          raise ArgumentError, "Unknown provider '#{name}'. Registered: #{@registry.keys.join(', ')}"
+        end
+      end
+
+      def build(name, **opts)
+        fetch(name).new(**opts)
+      end
+
+      def registered
+        @registry.keys
+      end
+    end
+  end
+end

data/lib/easy_creds/providers/base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module EasyCreds
+  module Providers
+    # Abstract interface all EasyCreds providers must implement.
+    # Subclasses raise NotImplementedError for any unimplemented method.
+    class Base
+      def initialize(config: nil, logger: nil)
+        @config = config
+        @logger = logger
+      end
+
+      def signed_in?                               = raise(NotImplementedError, "#{self.class}#signed_in?")
+      def account_email                            = raise(NotImplementedError, "#{self.class}#account_email")
+      def vault_exists?                            = raise(NotImplementedError, "#{self.class}#vault_exists?")
+      def create_vault(name)                       = raise(NotImplementedError, "#{self.class}#create_vault")
+      def item(env)                                = raise(NotImplementedError, "#{self.class}#item")
+      def item_exists?(env)                        = raise(NotImplementedError, "#{self.class}#item_exists?")
+      def create_item(env, fields)                 = raise(NotImplementedError, "#{self.class}#create_item")
+      def update_item(env, all_fields)             = raise(NotImplementedError, "#{self.class}#update_item")
+      def read_credentials_key(env, item)          = raise(NotImplementedError, "#{self.class}#read_credentials_key")
+      def write_credentials_key(env, value, item)  = raise(NotImplementedError, "#{self.class}#write_credentials_key")
+    end
+  end
+end