little_ghost 0.7.0 → 0.8.0

data/lib/little_ghost/cli.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require_relative "generators/application_generator"
+require "bundler"
+require "pathname"
+
+module LittleGhost
+  class BundleInstaller # :nodoc:
+    def initialize(stdout:, stderr:, executable: nil, process_runner: nil)
+      @stdout = stdout
+      @stderr = stderr
+      @executable = executable || -> { Gem.bin_path("bundler", "bundle") }
+      @process_runner = process_runner || method(:run_bundle)
+    end
+
+    def install(root)
+      executable = @executable.call
+      environment = {"BUNDLE_GEMFILE" => File.join(root, "Gemfile")}
+      if (bundle_path = ENV["BUNDLE_PATH"])
+        environment["BUNDLE_PATH"] = Pathname.new(bundle_path).absolute? ? bundle_path : File.expand_path(bundle_path, root)
+      end
+      status = @process_runner.call(environment, executable, root)
+      status.success?
+    rescue Gem::Exception, SystemCallError => error
+      @stderr.puts("Could not run bundle install: #{error.message}")
+      false
+    end
+
+    private
+
+    def run_bundle(environment, executable, root)
+      Bundler.with_unbundled_env do
+        process = Process.spawn(environment, executable, "install", chdir: root, out: @stdout, err: @stderr)
+        Process.wait2(process).last
+      end
+    end
+  end
+
+  # Command-line entrypoint for generating standalone LittleGhost applications.
+  class CLI # :nodoc:
+    USAGE = <<~TEXT
+      Usage:
+        little_ghost new APP_NAME
+        little_ghost console
+        little_ghost --version
+        little_ghost --help
+    TEXT
+
+    def initialize(
+      arguments,
+      stdout: $stdout,
+      stderr: $stderr,
+      current_directory: Dir.pwd,
+      generator_class: Generators::ApplicationGenerator,
+      bundle_installer: nil,
+      console_runner: nil,
+      source_path: nil
+    )
+      @arguments = Array(arguments).dup
+      @stdout = stdout
+      @stderr = stderr
+      @current_directory = File.expand_path(current_directory)
+      @generator_class = generator_class
+      @bundle_installer = bundle_installer || BundleInstaller.new(stdout:, stderr:)
+      @console_runner = console_runner
+      @source_path = source_path
+    end
+
+    def run
+      case arguments.first
+      when "--help", "-h", nil
+        return usage_error("--help does not accept arguments") if arguments.length > 1
+
+        stdout.write(USAGE)
+        0
+      when "--version", "-v"
+        return usage_error("--version does not accept arguments") if arguments.length > 1
+
+        stdout.puts("little_ghost #{VERSION}")
+        0
+      when "new"
+        generate_application
+      when "console"
+        open_console
+      else
+        usage_error("Unknown command: #{arguments.first}")
+      end
+    end
+
+    private
+
+    attr_reader :arguments, :stdout, :stderr, :current_directory, :generator_class, :bundle_installer, :source_path
+
+    def generate_application
+      return usage_error("APP_NAME is required") if arguments.length == 1
+      return usage_error("new accepts exactly one APP_NAME") if arguments.length > 2
+
+      application = generator_class.new(name: arguments.fetch(1), current_directory:, dependency_path: source_path)
+      stdout.puts("Running bundle install...")
+      bundle_installed = false
+      destination = application.generate do |staging|
+        bundle_installed = bundle_installer.install(staging)
+      end
+      stdout.puts("Created #{destination}")
+      unless bundle_installed
+        stderr.puts("Error: bundle install failed; the application was created at #{destination}")
+        return 1
+      end
+      stdout.puts("Run `cd #{application.directory_name} && bin/little_ghost console` to get started.")
+      0
+    rescue Generators::ApplicationGenerator::Error => error
+      stderr.puts("Error: #{error.message}")
+      1
+    end
+
+    def open_console
+      return usage_error("console does not accept arguments") if arguments.length > 1
+
+      runner = @console_runner
+      unless runner
+        require_relative "console"
+        runner = Console.method(:start)
+      end
+      runner.call(root: current_directory)
+      0
+    rescue LittleGhost::Error, LoadError, SystemCallError => error
+      stderr.puts("Error: #{error.message}")
+      1
+    end
+
+    def usage_error(message)
+      stderr.puts("Error: #{message}")
+      stderr.write(USAGE)
+      1
+    end
+  end
+end

data/lib/little_ghost/console.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "irb"
+require_relative "../little_ghost"
+
+module LittleGhost
+  class Console # :nodoc:
+    def self.start(root:)
+      configuration = Configuration.new(root:)
+      LittleGhost.with_configuration(configuration) do
+        LittleGhost.runtime
+        IRB.setup(nil, argv: [])
+        IRB::Irb.new.run(IRB.conf)
+      end
+    end
+  end
+end

data/lib/little_ghost/errors.rb

@@ -12,7 +12,7 @@ module LittleGhost
   class SandboxConfigurationError < ConfigurationError; end
   # Raised when a sandbox backend does not support the current operating system.
   class UnsupportedPlatformError < SandboxConfigurationError; end
-  # Raised when an explicitly selected sandbox backend dependency is unavailable.
+  # Raised when an explicitly selected optional integration or backend dependency is unavailable.
   class DependencyError < SandboxConfigurationError; end
   # Raised when a backend cannot enforce a requested sandbox capability.
   class CapabilityError < SandboxConfigurationError; end

data/lib/little_ghost/generators/application_generator.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../version"
+
+module LittleGhost
+  module Generators # :nodoc:
+    # Creates one conventional standalone LittleGhost application.
+    class ApplicationGenerator # :nodoc:
+      class Error < StandardError; end # :nodoc:
+      class InvalidNameError < Error; end # :nodoc:
+      class DestinationExistsError < Error; end # :nodoc:
+      class GenerationError < Error; end # :nodoc:
+
+      NAME_PATTERN = /\A[A-Za-z](?:[A-Za-z0-9]|[-_](?=[A-Za-z0-9]))*\z/ # :nodoc:
+      TEMPLATE_ROOT = File.expand_path("templates/application", __dir__) # :nodoc:
+      EMPTY_DIRECTORIES = %w[app/assemblies app/tools app/skills].freeze # :nodoc:
+
+      attr_reader :directory_name
+
+      def initialize(name:, current_directory: Dir.pwd, template_root: TEMPLATE_ROOT, dependency_path: nil)
+        @name = name.to_s
+        @current_directory = File.expand_path(current_directory)
+        @template_root = File.expand_path(template_root)
+        @dependency_path = dependency_path && File.expand_path(dependency_path)
+        @directory_name = normalize_name
+        @class_name = directory_name.split("_").map(&:capitalize).join
+      end
+
+      def generate
+        destination = File.join(current_directory, directory_name)
+        raise DestinationExistsError, "#{destination} already exists" if File.symlink?(destination) || File.exist?(destination)
+
+        identity = nil
+        begin
+          Dir.mkdir(destination, 0o700)
+        rescue Errno::EEXIST
+          raise DestinationExistsError, "#{destination} already exists"
+        rescue SystemCallError => error
+          raise GenerationError, "Could not create #{directory_name}: #{error.message}"
+        end
+
+        begin
+          identity = directory_identity(destination)
+          files = rendered_files
+          create_directories(destination, identity, files)
+          create_files(destination, identity, files)
+          directory_mode = File.stat(File.join(destination, "app")).mode & 0o777
+          verify_destination!(destination, identity)
+          yield(destination) if block_given?
+          restore_directory_mode(destination, identity, directory_mode)
+          destination
+        rescue Error
+          remove_created_destination(destination, identity) if identity
+          raise
+        rescue => error
+          remove_created_destination(destination, identity) if identity
+          raise GenerationError, "Could not create #{directory_name}: #{error.message}"
+        end
+      end
+
+      private
+
+      attr_reader :name, :current_directory, :template_root, :class_name, :dependency_path
+
+      def normalize_name
+        unless NAME_PATTERN.match?(name)
+          raise InvalidNameError, "APP_NAME must begin with a letter and contain only letters, numbers, hyphens, or underscores"
+        end
+
+        normalized = name
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, "\\1_\\2")
+          .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+          .tr("-", "_")
+          .downcase
+        raise InvalidNameError, "APP_NAME must identify a Ruby constant" unless /\A[a-z][a-z0-9_]*\z/.match?(normalized)
+
+        normalized
+      end
+
+      def create_directories(destination, identity, files)
+        files
+          .each_key
+          .map { |relative_destination| File.dirname(relative_destination) }
+          .reject { |directory| directory == "." }
+          .flat_map { |directory| directory.split("/").each_index.map { |index| directory.split("/").first(index + 1).join("/") } }
+          .uniq
+          .sort_by { |directory| directory.count("/") }
+          .each do |directory|
+            verify_destination!(destination, identity)
+            Dir.mkdir(File.join(destination, directory))
+          end
+      end
+
+      def create_files(destination, identity, files)
+        files.each do |relative_destination, contents|
+          create_file(destination, identity, relative_destination, contents)
+        end
+      end
+
+      def create_file(destination, identity, relative_destination, contents)
+        verify_destination!(destination, identity)
+        target = File.join(destination, relative_destination)
+        File.open(target, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+          file.write(contents)
+          file.chmod(0o755) if relative_destination == "bin/little_ghost"
+        end
+      end
+
+      def template_destinations
+        [
+          ["Gemfile.tt", "Gemfile"],
+          ["README.md.tt", "README.md"],
+          ["gitignore.tt", ".gitignore"],
+          ["config/little_ghost.rb.tt", "config/little_ghost.rb"],
+          ["app/agents/application_agent.rb.tt", "app/agents/#{directory_name}_agent.rb"],
+          ["app/prompts/application/system.erb.tt", "app/prompts/#{directory_name}/system.erb"],
+          ["bin/application.tt", "bin/little_ghost"],
+          *EMPTY_DIRECTORIES.map { |directory| ["keep.tt", "#{directory}/.keep"] }
+        ]
+      end
+
+      def rendered_files
+        template_destinations.to_h do |template, relative_destination|
+          [relative_destination, render(File.binread(File.join(template_root, template)))]
+        end
+      end
+
+      def render(template)
+        template
+          .gsub("{{DIRECTORY_NAME}}", directory_name)
+          .gsub("{{CLASS_NAME}}", class_name)
+          .gsub("{{LITTLE_GHOST_DEPENDENCY}}", little_ghost_dependency)
+          .gsub("{{VERSION}}", VERSION)
+      end
+
+      def little_ghost_dependency
+        return %(gem "little_ghost", path: #{dependency_path.dump}) if dependency_path
+
+        %(gem "little_ghost", "~> #{VERSION}")
+      end
+
+      def directory_identity(destination)
+        stat = File.lstat(destination)
+        raise GenerationError, "Destination changed during generation" unless stat.directory? && !stat.symlink?
+
+        [stat.dev, stat.ino].freeze
+      end
+
+      def restore_directory_mode(destination, identity, mode, nofollow_supported: File.const_defined?(:NOFOLLOW))
+        if nofollow_supported
+          File.open(destination, File::RDONLY | File::NOFOLLOW) do |directory|
+            stat = directory.stat
+            raise GenerationError, "Destination changed during generation" unless [stat.dev, stat.ino] == identity
+
+            directory.chmod(mode)
+          end
+        else
+          verify_destination!(destination, identity)
+          File.chmod(mode, destination)
+        end
+      end
+
+      def verify_destination!(destination, identity)
+        raise GenerationError, "Destination changed during generation" unless directory_identity(destination) == identity
+      rescue Errno::ENOENT
+        raise GenerationError, "Destination changed during generation"
+      end
+
+      def remove_created_destination(destination, identity)
+        return unless directory_identity(destination) == identity
+
+        FileUtils.remove_entry_secure(destination)
+      rescue Errno::ENOENT, GenerationError
+        nil
+      end
+    end
+  end
+end

data/lib/little_ghost/generators/templates/application/Gemfile.tt

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+{{LITTLE_GHOST_DEPENDENCY}}

data/lib/little_ghost/generators/templates/application/README.md.tt

@@ -0,0 +1,29 @@
+# {{CLASS_NAME}}
+
+This LittleGhost application includes one Agent, a prompt view, and a
+bundle-aware local command.
+
+## Open the console
+
+Install or refresh the application's bundle whenever its dependencies change:
+
+```sh
+$ bundle install
+```
+
+Then start the console:
+
+```sh
+$ export OPENROUTER_API_KEY="..."
+$ bin/little_ghost console
+```
+
+The generator runs `bundle install` when it creates the directory. If that
+initial install cannot finish, the application remains in place so you can fix
+the cause and run `bundle install` again. The console uses the application's
+bundle, loads `config/little_ghost.rb` and the classes under `app/`, and then
+starts IRB:
+
+```ruby
+{{CLASS_NAME}}Agent.ask("Say hello").response
+```

data/lib/little_ghost/generators/templates/application/app/agents/application_agent.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class {{CLASS_NAME}}Agent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+end

data/lib/little_ghost/generators/templates/application/app/prompts/application/system.erb.tt

@@ -0,0 +1 @@
+You are a helpful assistant. Give clear, concise answers to the user's instructions.

data/lib/little_ghost/generators/templates/application/bin/application.tt

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+app_root = File.expand_path("..", __dir__)
+ENV["BUNDLE_GEMFILE"] = File.join(app_root, "Gemfile")
+
+require "bundler/setup"
+require "little_ghost/cli"
+
+exit LittleGhost::CLI.new(ARGV, current_directory: app_root).run

data/lib/little_ghost/generators/templates/application/config/little_ghost.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+LittleGhost.configure do |config|
+  config.service_name "{{DIRECTORY_NAME}}"
+end

data/lib/little_ghost/generators/templates/application/gitignore.tt

@@ -0,0 +1,2 @@
+.bundle/
+vendor/bundle/