ace-handbook 0.19.0

data/lib/ace/handbook/organisms/provider_syncer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Handbook
+    module Organisms
+      class ProviderSyncer
+        attr_reader :project_root, :registry, :inventory, :config
+
+        def initialize(
+          project_root: Ace::Handbook.project_root,
+          registry: nil,
+          inventory: nil,
+          config: nil
+        )
+          @project_root = project_root
+          @registry = registry || Atoms::ProviderRegistry.new(project_root: project_root)
+          @inventory = inventory || SkillInventory.new(project_root: project_root)
+          @config = config || Ace::Handbook.config.resolve_namespace("handbook").to_h
+        end
+
+        def sync(provider: nil)
+          providers_to_sync(provider).map { |provider_id| sync_provider(provider_id) }
+        end
+
+        private
+
+        def sync_provider(provider)
+          output_dir = File.join(project_root, registry.output_dir(provider))
+          prepare_output_dir(output_dir)
+
+          expected = {}
+          updated_files = 0
+
+          inventory.all.each do |skill|
+            next unless Molecules::SkillProjection.projection_targets(skill.frontmatter, registry: registry).include?(provider)
+
+            frontmatter = Molecules::SkillProjection.projected_frontmatter(skill.frontmatter, provider: provider)
+            rendered = Molecules::SkillProjection.render(frontmatter, skill.body)
+            output_path = File.join(output_dir, skill.name, "SKILL.md")
+            expected[skill.name] = output_path
+
+            FileUtils.mkdir_p(File.dirname(output_path))
+            next if File.exist?(output_path) && File.read(output_path) == rendered
+
+            File.write(output_path, rendered)
+            updated_files += 1
+          end
+
+          removed_entries = prune_stale_entries(output_dir, expected.keys)
+
+          {
+            provider: provider,
+            relative_output_dir: registry.output_dir(provider),
+            projected_skills: expected.size,
+            updated_files: updated_files,
+            removed_entries: removed_entries
+          }
+        end
+
+        def providers_to_sync(requested_provider)
+          providers = if requested_provider
+            [requested_provider.to_s]
+          else
+            registry.providers
+          end
+
+          unknown = providers.reject { |provider| registry.known?(provider) }
+          raise ArgumentError, "Unknown provider: #{unknown.join(", ")}" if unknown.any?
+
+          enabled = providers.select { |provider| provider_enabled?(provider) }
+          return enabled if requested_provider.nil? || enabled.any?
+
+          raise ArgumentError, "Provider '#{requested_provider}' is disabled in handbook sync config"
+        end
+
+        def provider_enabled?(provider)
+          sync_config = config.fetch("sync", {})
+          providers = sync_config.fetch("providers", {})
+          enabled = Array(providers["enabled"]).map(&:to_s)
+          disabled = Array(providers["disabled"]).map(&:to_s)
+
+          return enabled.include?(provider) unless enabled.empty?
+
+          !disabled.include?(provider)
+        end
+
+        def prepare_output_dir(output_dir)
+          if File.symlink?(output_dir) || File.file?(output_dir)
+            FileUtils.rm_rf(output_dir)
+          end
+
+          FileUtils.mkdir_p(output_dir)
+        end
+
+        def prune_stale_entries(output_dir, expected_skill_names)
+          existing = Dir.glob(File.join(output_dir, "*")).select { |path| File.directory?(path) }
+          stale = existing.reject { |path| expected_skill_names.include?(File.basename(path)) }
+          stale.each { |path| FileUtils.rm_rf(path) }
+          stale.size
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/organisms/skill_inventory.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+require "ace/support/nav"
+
+module Ace
+  module Handbook
+    module Organisms
+      class SkillInventory
+        FRONTMATTER_PATTERN = /\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m
+
+        attr_reader :project_root
+
+        def initialize(project_root: Ace::Handbook.project_root)
+          @project_root = project_root
+        end
+
+        def all
+          scanner.find_resources("skill").filter_map do |resource|
+            parse_skill(resource.fetch(:path))
+          end
+        end
+
+        private
+
+        def scanner
+          source_registry = Ace::Support::Nav::Molecules::SourceRegistry.new(start_path: project_root)
+          config_loader = Ace::Support::Nav::Molecules::ConfigLoader.new(
+            File.join(project_root, ".ace", "nav"),
+            source_registry: source_registry
+          )
+
+          Ace::Support::Nav::Molecules::ProtocolScanner.new(config_loader: config_loader)
+        end
+
+        def parse_skill(path)
+          content = File.read(path)
+          match = content.match(FRONTMATTER_PATTERN)
+          return nil unless match
+
+          frontmatter = YAML.safe_load(match[1], permitted_classes: [Date, Time], aliases: true) || {}
+          return nil unless frontmatter.is_a?(Hash) && frontmatter["name"]
+
+          Models::SkillDocument.new(
+            source_path: path,
+            frontmatter: frontmatter,
+            body: match[2]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/organisms/status_collector.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Ace
+  module Handbook
+    module Organisms
+      class StatusCollector
+        attr_reader :project_root, :registry, :config, :inventory
+
+        def initialize(project_root: Ace::Handbook.project_root, registry: nil, inventory: nil, config: nil)
+          @project_root = project_root
+          @registry = registry || Atoms::ProviderRegistry.new(project_root: project_root)
+          @inventory = inventory || SkillInventory.new(project_root: project_root)
+          @config = config || Ace::Handbook.config.resolve_namespace("handbook").to_h
+        end
+
+        def collect(provider: nil)
+          skills = inventory.all
+
+          {
+            "canonical" => canonical_summary(skills),
+            "providers" => selected_providers(provider).map { |provider_id| provider_status(provider_id, skills) }
+          }
+        end
+
+        def to_table(snapshot)
+          summary_lines = canonical_summary_lines(snapshot.fetch("canonical"))
+          rows = snapshot.fetch("providers").map do |entry|
+            [
+              entry.fetch("provider"),
+              entry.fetch("enabled") ? "yes" : "no",
+              entry.fetch("path_type"),
+              entry.fetch("expected").to_s,
+              entry.fetch("installed").to_s,
+              entry.fetch("in_sync").to_s,
+              entry.fetch("outdated").to_s,
+              entry.fetch("missing").to_s,
+              entry.fetch("extra").to_s,
+              entry.fetch("relative_output_dir")
+            ]
+          end
+
+          widths = [
+            ["PROVIDER", *rows.map { |row| row[0] }].map(&:length).max,
+            ["ENABLED", *rows.map { |row| row[1] }].map(&:length).max,
+            ["TYPE", *rows.map { |row| row[2] }].map(&:length).max,
+            ["EXPECTED", *rows.map { |row| row[3] }].map(&:length).max,
+            ["INSTALLED", *rows.map { |row| row[4] }].map(&:length).max,
+            ["IN_SYNC", *rows.map { |row| row[5] }].map(&:length).max,
+            ["OUTDATED", *rows.map { |row| row[6] }].map(&:length).max,
+            ["MISSING", *rows.map { |row| row[7] }].map(&:length).max,
+            ["EXTRA", *rows.map { |row| row[8] }].map(&:length).max
+          ]
+
+          header = format(
+            "%-#{widths[0]}s  %-#{widths[1]}s  %-#{widths[2]}s  %#{widths[3]}s  %#{widths[4]}s  %#{widths[5]}s  %#{widths[6]}s  %#{widths[7]}s  %#{widths[8]}s  %s",
+            "PROVIDER", "ENABLED", "TYPE", "EXPECTED", "INSTALLED", "IN_SYNC", "OUTDATED", "MISSING", "EXTRA", "PATH"
+          )
+          lines = rows.map do |provider, enabled, type, expected, installed, in_sync, outdated, missing, extra, path|
+            format(
+              "%-#{widths[0]}s  %-#{widths[1]}s  %-#{widths[2]}s  %#{widths[3]}s  %#{widths[4]}s  %#{widths[5]}s  %#{widths[6]}s  %#{widths[7]}s  %#{widths[8]}s  %s",
+              provider, enabled, type, expected, installed, in_sync, outdated, missing, extra, path
+            )
+          end
+
+          (summary_lines + ["", header] + lines).join("\n")
+        end
+
+        private
+
+        def canonical_summary(skills)
+          counts = skills.group_by(&:source).transform_values(&:size)
+
+          {
+            "total" => skills.size,
+            "by_source" => counts.keys.sort.map do |source|
+              {"source" => source, "count" => counts.fetch(source)}
+            end
+          }
+        end
+
+        def provider_status(provider, skills)
+          relative_output_dir = registry.output_dir(provider)
+          output_dir = File.join(project_root, relative_output_dir)
+          expected = expected_projection_map(provider, skills)
+          installed_paths = installed_skill_paths(output_dir)
+          installed_names = installed_paths.map { |path| File.basename(File.dirname(path)) }
+
+          in_sync = 0
+          outdated = 0
+          extra = 0
+
+          installed_paths.each do |path|
+            skill_name = File.basename(File.dirname(path))
+            expected_content = expected[skill_name]
+
+            if expected_content.nil?
+              extra += 1
+            elsif File.read(path) == expected_content
+              in_sync += 1
+            else
+              outdated += 1
+            end
+          end
+
+          {
+            "provider" => provider,
+            "enabled" => provider_enabled?(provider),
+            "relative_output_dir" => relative_output_dir,
+            "output_dir" => output_dir,
+            "path_type" => path_type(output_dir),
+            "manifest_path" => registry.manifest(provider)["_manifest_path"],
+            "expected" => expected.size,
+            "installed" => installed_paths.size,
+            "in_sync" => in_sync,
+            "outdated" => outdated,
+            "missing" => (expected.keys - installed_names).size,
+            "extra" => extra
+          }
+        end
+
+        def expected_projection_map(provider, skills)
+          skills.each_with_object({}) do |skill, expected|
+            next unless Molecules::SkillProjection.projection_targets(skill.frontmatter, registry: registry).include?(provider)
+
+            frontmatter = Molecules::SkillProjection.projected_frontmatter(skill.frontmatter, provider: provider)
+            expected[skill.name] = Molecules::SkillProjection.render(frontmatter, skill.body)
+          end
+        end
+
+        def installed_skill_paths(output_dir)
+          return [] unless Dir.exist?(output_dir)
+
+          Dir.glob(File.join(output_dir, "*", "SKILL.md")).sort
+        end
+
+        def canonical_summary_lines(summary)
+          rows = summary.fetch("by_source").map { |entry| [entry.fetch("source"), entry.fetch("count").to_s] }
+          source_width = ["SOURCE", *rows.map { |row| row[0] }, "TOTAL"].map(&:length).max
+          count_width = ["COUNT", *rows.map { |row| row[1] }, summary.fetch("total").to_s].map(&:length).max
+
+          lines = [
+            "CANONICAL SKILLS",
+            format("%-#{source_width}s  %#{count_width}s", "SOURCE", "COUNT")
+          ]
+          rows.each do |source, count|
+            lines << format("%-#{source_width}s  %#{count_width}s", source, count)
+          end
+          lines << format("%-#{source_width}s  %#{count_width}s", "TOTAL", summary.fetch("total"))
+          lines
+        end
+
+        def selected_providers(provider)
+          selected = provider ? [provider.to_s] : registry.providers
+          unknown = selected.reject { |provider_id| registry.known?(provider_id) }
+          raise ArgumentError, "Unknown provider: #{unknown.join(", ")}" if unknown.any?
+
+          selected
+        end
+
+        def provider_enabled?(provider)
+          sync_config = config.fetch("sync", {})
+          providers = sync_config.fetch("providers", {})
+          enabled = Array(providers["enabled"]).map(&:to_s)
+          disabled = Array(providers["disabled"]).map(&:to_s)
+
+          return enabled.include?(provider) unless enabled.empty?
+
+          !disabled.include?(provider)
+        end
+
+        def path_type(path)
+          return "symlink" if File.symlink?(path)
+          return "directory" if File.directory?(path)
+          return "file" if File.file?(path)
+
+          "missing"
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ace
+  module Handbook
+    VERSION = "0.19.0"
+  end
+end

data/lib/ace/handbook.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ace/support/config"
+
+require_relative "handbook/version"
+require_relative "handbook/atoms/provider_registry"
+require_relative "handbook/models/skill_document"
+require_relative "handbook/molecules/skill_projection"
+require_relative "handbook/organisms/skill_inventory"
+require_relative "handbook/organisms/provider_syncer"
+require_relative "handbook/organisms/status_collector"
+
+module Ace
+  module Handbook
+    class << self
+      def config
+        @config ||= Ace::Support::Config.create(
+          gem_path: File.expand_path("../..", __dir__),
+          cache_namespaces: true
+        )
+      end
+
+      def project_root(start_path: Dir.pwd)
+        Ace::Support::Config.find_project_root(start_path: start_path) || Dir.pwd
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,227 @@
+--- !ruby/object:Gem::Specification
+name: ace-handbook
+version: !ruby/object:Gem::Version
+  version: 0.19.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: ace-support-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Standardized workflows for creating, reviewing, and maintaining ACE handbook
+  guides, workflow instructions, and agent definitions.
+email:
+- mc@cs3b.com
+executables:
+- ace-handbook
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/handbook/config.yml"
+- ".ace-defaults/nav/protocols/guide-sources/ace-handbook.yml"
+- ".ace-defaults/nav/protocols/tmpl-sources/ace-handbook.yml"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-handbook.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- exe/ace-handbook
+- handbook/guides/ai-agent-integration.g.md
+- handbook/guides/atom-pattern.g.md
+- handbook/guides/changelog.g.md
+- handbook/guides/cli-dry-cli.g.md
+- handbook/guides/cli-support-cli.g.md
+- handbook/guides/coding-standards.g.md
+- handbook/guides/coding-standards/ruby.md
+- handbook/guides/coding-standards/rust.md
+- handbook/guides/coding-standards/typescript.md
+- handbook/guides/debug-troubleshooting.g.md
+- handbook/guides/error-handling.g.md
+- handbook/guides/error-handling/ruby.md
+- handbook/guides/error-handling/rust.md
+- handbook/guides/error-handling/typescript.md
+- handbook/guides/meta/agents-definition.g.md
+- handbook/guides/meta/guides-definition.g.md
+- handbook/guides/meta/markdown-definition.g.md
+- handbook/guides/meta/tools-definition.g.md
+- handbook/guides/meta/workflow-instructions-definition.g.md
+- handbook/guides/mono-repo-patterns.g.md
+- handbook/guides/multi-agent-research.g.md
+- handbook/guides/performance.g.md
+- handbook/guides/performance/ruby.md
+- handbook/guides/performance/rust.md
+- handbook/guides/performance/typescript.md
+- handbook/guides/prompt-caching.g.md
+- handbook/guides/quality-assurance.g.md
+- handbook/guides/quality-assurance/ruby.md
+- handbook/guides/quality-assurance/rust.md
+- handbook/guides/quality-assurance/typescript.md
+- handbook/guides/strategic-planning.g.md
+- handbook/guides/troubleshooting/ruby.md
+- handbook/guides/troubleshooting/rust.md
+- handbook/guides/troubleshooting/typescript.md
+- handbook/guides/workflow-context-embedding.g.md
+- handbook/skills/as-handbook-init-project/SKILL.md
+- handbook/skills/as-handbook-manage-agents/SKILL.md
+- handbook/skills/as-handbook-manage-guides/SKILL.md
+- handbook/skills/as-handbook-manage-workflows/SKILL.md
+- handbook/skills/as-handbook-parallel-research/SKILL.md
+- handbook/skills/as-handbook-perform-delivery/SKILL.md
+- handbook/skills/as-handbook-review-guides/SKILL.md
+- handbook/skills/as-handbook-review-workflows/SKILL.md
+- handbook/skills/as-handbook-synthesize-research/SKILL.md
+- handbook/skills/as-handbook-update-docs/SKILL.md
+- handbook/skills/as-release-bump-version/SKILL.md
+- handbook/skills/as-release-rubygems-publish/SKILL.md
+- handbook/skills/as-release-update-changelog/SKILL.md
+- handbook/skills/as-release/SKILL.md
+- handbook/templates/completed-work-documentation.md
+- handbook/templates/cookbooks/cookbook.template.md
+- handbook/templates/research-comparison.template.md
+- handbook/workflow-instructions/handbook/init-project.wf.md
+- handbook/workflow-instructions/handbook/manage-agents.wf.md
+- handbook/workflow-instructions/handbook/manage-guides.wf.md
+- handbook/workflow-instructions/handbook/manage-workflows.wf.md
+- handbook/workflow-instructions/handbook/parallel-research.wf.md
+- handbook/workflow-instructions/handbook/perform-delivery.wf.md
+- handbook/workflow-instructions/handbook/research.wf.md
+- handbook/workflow-instructions/handbook/review-guides.wf.md
+- handbook/workflow-instructions/handbook/review-workflows.wf.md
+- handbook/workflow-instructions/handbook/synthesize-research.wf.md
+- handbook/workflow-instructions/handbook/update-docs.wf.md
+- lib/ace/handbook.rb
+- lib/ace/handbook/atoms/provider_registry.rb
+- lib/ace/handbook/cli.rb
+- lib/ace/handbook/cli/commands/status.rb
+- lib/ace/handbook/cli/commands/sync.rb
+- lib/ace/handbook/models/skill_document.rb
+- lib/ace/handbook/molecules/skill_projection.rb
+- lib/ace/handbook/organisms/provider_syncer.rb
+- lib/ace/handbook/organisms/skill_inventory.rb
+- lib/ace/handbook/organisms/status_collector.rb
+- lib/ace/handbook/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-handbook/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-handbook/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Standardized workflows for creating and managing guides, workflow instructions,
+  and agent definitions.
+test_files: []