releasehx 0.1.0

data/build/docs/sourcerer_readme.html

@@ -0,0 +1,46 @@
+<div class="paragraph">
+<p>This gem introduces a module called Sourcerer, by which AsciiDoc files can be parsed and their contents harvested for use in the application build.
+The module also handles Liquid template processing with enhanced attribute resolution capabilities.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+Sourcerer is intended to be spun off as its own gem once it successfully proves the concept in this gem.
+It will probably be called <em>AsciiSourcerer</em> and may replace an older and unmaintained utility of mine called LiquiDoc.
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>It is invoked in the Rakefile, establishing global namespaces:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>ReleaseHx::ATTRIBUTES[:globals]</code> (derived from this <code>README.adoc</code> file)</p>
+</li>
+<li>
+<p><code>ReleaseHx.read_built_snippet(:&lt;name&gt;)</code> (such as <code>:helpscreen</code>)</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The Sourcerer module also generates files like <code>build/docs/manpage.adoc</code>, which generates the formatted terminal manual, using content from <code>build/docs/config-reference.adoc</code> and this README (<code>tags="cli_options"</code>, for instance).</p>
+</div>
+<div class="paragraph">
+<p>It also generates an AsciiDoc-formatted configuration reference, a machine-readable JSON reference, and a sample config using the <code>specs/data/config-def.yml</code> file.
+The Sourcerer system now supports <strong>attribute resolution</strong> from AsciiDoc source files, enabling templates to access README attributes during rendering, ensuring configuration documentation reflects actual default values.</p>
+</div>
+<div class="paragraph">
+<p>Sourcerer also performs basic testing of select commands in the ASciiDoc file that have been assigned a <code>testable</code> role.</p>
+</div>
+<div class="paragraph">
+<p>This is mostly just showing off what Sourcerer can do, and hopefully setting into habit some best practices for my more complicated apps.</p>
+</div>
+<div class="paragraph">
+<p>Sourcerer is also where integration with Jekyll&#8217;s extensions of Liquid occurs, bringing ReleaseHx&#8217;s templating powers closely in line with how Jekyll&#8217;s work, as described in <a href="#custom-liquid">[custom-liquid]</a>.</p>
+</div>

data/build/snippets/helpscreen.txt

@@ -0,0 +1,29 @@
+Usage: rhx VERSION|FILE [options]
+
+Options:
+  --md [PATH]            Draft to Markdown
+  --adoc, --ad [PATH]    Draft to AsciiDoc
+  --yaml, --yml [PATH]   Draft to YAML
+  --html [PATH]          Enrich to HTML
+  --pdf [PATH]           Enrich to PDF
+  --output-dir PATH      Establish base target path for generated files
+  --api-data PATH        Ingest from a JSON file instead of REST response
+
+  --config PATH          Config location (default: ./{app_default_config_path})
+  --mapping PATH         Alternate API mapping location
+  --payload PATH         Store payload as JSON file at PATH or default
+  --fetch                Refresh data from source
+  --append               Add any new issues to the end of local YAML source
+  --over, --force        Overwrite any existing files without prompting
+  --check, --scan        Find issues with missing release note
+  --empty, -e [RULE]     Set/reverse policy on issues "awaiting notes"
+  --internal             Include issues marked internal or likewise
+  --[no-]wrap            Enrich HTML with/out head and body tags
+  --[no-]frontmatter     Enrich or draft with/out frontmatter
+
+  --manpage, --man       Show the full manpage documentation
+  --verbose              Express each step to console
+  --debug                Express each step and show inferred states
+  --debug-dump           Complete debugging with raw data
+  --quiet                Suppress all output, including warnings
+  --version              Display the ReleaseHx version code

data/lib/docopslab/mcp/asset_packager.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module DocOpsLab
+  module MCP
+    # Copies MCP resource assets into a packaged location for runtime access.
+    class AssetPackager
+      def initialize manifest:, asset_root:
+        raise ArgumentError, 'asset_root is required' if asset_root.nil? || asset_root == ''
+
+        @manifest = manifest
+        @asset_root = asset_root
+      end
+
+      def package!
+        FileUtils.mkdir_p(@asset_root)
+        @manifest.resources.each do |entry|
+          normalized = @manifest.normalize_resource(entry)
+          source_path = normalized[:source_path]
+          target_path = File.join(@asset_root, normalized[:packaged_name])
+          raise Errno::ENOENT, "Missing MCP resource source: #{source_path}" unless File.exist?(source_path)
+
+          FileUtils.mkdir_p(File.dirname(target_path))
+          FileUtils.cp(source_path, target_path)
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/mcp/manifest.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module DocOpsLab
+  module MCP
+    # Loads MCP resource and tool definitions from a YAML manifest.
+    class Manifest
+      def initialize data
+        @data = data
+      end
+
+      def self.load path
+        raise ArgumentError, 'Manifest path is required' if path.nil? || path == ''
+
+        new(YAML.safe_load_file(path, symbolize_names: true, aliases: true))
+      end
+
+      def resources
+        Array(@data[:resources])
+      end
+
+      def tools
+        Array(@data[:tools])
+      end
+
+      def normalize_resource entry
+        {
+          uri: entry[:href],
+          name: entry[:name],
+          description: entry[:desc],
+          mime_type: entry[:mime],
+          source_path: entry[:path],
+          packaged_name: entry[:file]
+        }
+      end
+
+      def normalize_tool entry
+        {
+          name: entry[:name],
+          # Convert dots to spaces, capitalize initials
+          title: entry[:title] || entry[:name].tr('.', ' ').split.map(&:capitalize).join(' '),
+          description: entry[:desc],
+          input_schema: normalize_schema(entry[:input_schema]),
+          annotations: entry[:annotations]
+        }
+      end
+
+      private
+
+      # Recursively normalize schema keys (ex: :desc to :description)
+      def normalize_schema value
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, inner), acc|
+            mapped_key = key == :desc ? :description : key
+            acc[mapped_key] = normalize_schema(inner)
+          end
+        when Array
+          value.map { |item| normalize_schema(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/mcp/resource_pack.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module DocOpsLab
+  module MCP
+    # Resolves MCP resources from a YAML manifest and packaged assets.
+    class ResourcePack
+      Resource = Struct.new(:uri, :name, :description, :mime_type, :path, keyword_init: true)
+
+      def initialize manifest:, asset_root:
+        raise ArgumentError, 'asset_root is required' if asset_root.nil? || asset_root == ''
+
+        @manifest = manifest
+        @asset_root = asset_root
+      end
+
+      def resources
+        @manifest.resources.map do |entry|
+          normalized = @manifest.normalize_resource(entry)
+          Resource.new(
+            uri: normalized[:uri],
+            name: normalized[:name],
+            description: normalized[:description],
+            mime_type: normalized[:mime_type],
+            path: File.join(@asset_root, normalized[:packaged_name]))
+        end
+      end
+
+      def list
+        resources.map(&:uri)
+      end
+
+      def find uri
+        resources.find { |entry| entry.uri == uri }
+      end
+
+      def read uri
+        resource = find(uri)
+        raise ArgumentError, "Unknown MCP resource: #{uri}" unless resource
+
+        raise Errno::ENOENT, "Missing MCP resource file: #{resource.path}" unless File.exist?(resource.path)
+
+        File.read(resource.path)
+      end
+    end
+  end
+end

data/lib/docopslab/mcp/server.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+module DocOpsLab
+  module MCP
+    # Hosts MCP resources and tools from a manifest-driven resource pack.
+    class Server
+      def initialize name:, manifest:, resource_pack:, tool_handler: nil
+        raise ArgumentError, 'name is required' if name.nil? || name == ''
+
+        @manifest = manifest
+        @resource_pack = resource_pack
+        @tool_handler = tool_handler
+        @server = ::MCP::Server.new(
+          name: name,
+          resources: mcp_resources,
+          tools: mcp_tools)
+
+        register_resource_reader
+      end
+
+      def start_stdio
+        transport = ::MCP::Server::Transports::StdioTransport.new(@server)
+        transport.open
+      end
+
+      def list_resources
+        @resource_pack.list
+      end
+
+      def get_resource uri
+        @resource_pack.read(uri)
+      end
+
+      private
+
+      def register_resource_reader
+        @server.resources_read_handler do |params|
+          uri = params[:uri]
+          resource = @resource_pack.find(uri)
+          raise ArgumentError, "Unknown MCP resource: #{uri}" unless resource
+
+          [{
+            uri:,
+            mimeType: resource.mime_type,
+            text: @resource_pack.read(uri)
+          }]
+        end
+      end
+
+      def mcp_resources
+        @resource_pack.resources.map do |entry|
+          ::MCP::Resource.new(
+            uri: entry.uri,
+            name: entry.name,
+            title: entry.name,
+            description: entry.description,
+            mime_type: entry.mime_type)
+        end
+      end
+
+      def mcp_tools
+        @manifest.tools.map do |tool|
+          normalized = @manifest.normalize_tool(tool)
+          build_tool(normalized)
+        end
+      end
+
+      def build_tool tool
+        tool_handler = @tool_handler
+        ::MCP::Tool.define(
+          name: tool[:name],
+          title: tool[:title],
+          description: tool[:description],
+          input_schema: tool[:input_schema],
+          annotations: tool[:annotations]) do |**args|
+          server_context = args.delete(:server_context)
+          raise ArgumentError, "No MCP tool handler configured for: #{tool[:name]}" unless tool_handler
+
+          tool_handler.call(tool[:name], args, server_context)
+        end
+      end
+
+      def handle_tool name, args, server_context
+        raise ArgumentError, "No MCP tool handler configured for: #{name}" unless @tool_handler
+
+        @tool_handler.call(name, args, server_context)
+      end
+    end
+  end
+end

data/lib/docopslab/mcp.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'mcp/manifest'
+require_relative 'mcp/resource_pack'
+require_relative 'mcp/asset_packager'
+require_relative 'mcp/server'