rigortype 0.2.1 → 0.2.3

data/lib/rigor/cli/docs_command.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module Rigor
+  class CLI
+    # `rigor docs` — serve the documentation bundled with the
+    # `rigortype` gem OFFLINE (ADR-74). The skills (`rigor skill <name>`)
+    # already ride in the gem; this is the doc twin, so once Rigor is
+    # installed an agent can read the guidance the SKILL-driven UX routes
+    # to without the network. The canonical web copy is
+    # rigor.typedduck.fail/llms.txt; the gem ships `docs/install.md`,
+    # `docs/llms.txt`, and the full user-facing **manual** and
+    # **handbook** (the drive-Rigor chapters — the contributor-facing
+    # ADR / spec / notes corpus stays web-only).
+    #
+    # Grammar (mirrors `rigor skill`): the positional slot is always a
+    # doc *name*; alternative outputs are flags, so a page named `list`
+    # or `path` can never be shadowed by a verb.
+    #
+    # - `rigor docs`                  — print the bundled `llms.txt` index.
+    # - `rigor docs <name>`           — print a doc page to stdout.
+    # - `rigor docs --path <name>`    — one-line absolute path, for a Read tool.
+    # - `rigor docs --list [<cat>]`   — table of name + path (optionally one category).
+    #
+    # `<name>` resolves a category-qualified path (`handbook/03-narrowing`),
+    # a prefixed basename (`03-narrowing`), or a short name (`narrowing`,
+    # when it is unique across categories).
+    #
+    # The pre-v0.3.0 verb spellings `rigor docs list` / `rigor docs path
+    # <name>` still work but emit a stderr deprecation notice; they are
+    # removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI
+    # deprecations").
+    class DocsCommand < Command
+      USAGE = <<~USAGE
+        Usage: rigor docs [<name>] [--path <name>] [--list [<category>]]
+
+        With no argument, prints the bundled llms.txt offline doc index.
+
+          rigor docs                      Print the offline doc index (llms.txt)
+          rigor docs <name>               Print a doc page to stdout
+          rigor docs --path <name>        Print the absolute path of a doc
+          rigor docs --list [<category>]  List bundled docs (optionally one category)
+
+        Categories: manual, handbook (plus the top-level install guide).
+        A page is addressable by its category-qualified path
+        (`handbook/03-narrowing`), its prefixed name (`03-narrowing`),
+        or its short name (`narrowing`, when unique across categories).
+
+        Examples:
+          rigor docs
+          rigor docs install
+          rigor docs handbook/03-narrowing
+          rigor docs editor-integration
+          rigor docs --path 17-driving-improvement
+          rigor docs --list handbook
+
+        Deprecated (removed in v0.3.0) — use the flags above:
+          rigor docs list           ->  rigor docs --list
+          rigor docs path <name>    ->  rigor docs --path <name>
+      USAGE
+
+      # The bundled docs live at `<gem_root>/docs/`. From
+      # `lib/rigor/cli/docs_command.rb` that is three directories up.
+      DOCS_ROOT = File.expand_path("../../../docs", __dir__)
+      MANUAL_ROOT = File.join(DOCS_ROOT, "manual")
+      HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
+      LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
+
+      # The verb subcommands the flags superseded keep working with a
+      # stderr deprecation notice until this version drops them. Each maps
+      # to the canonical advice printed and the flag it rewrites to.
+      LEGACY_VERB_REMOVAL = "v0.3.0"
+      LEGACY_VERBS = {
+        "list" => { old: "list",        advice: "--list",        flag: "--list" },
+        "path" => { old: "path <name>", advice: "--path <name>", flag: "--path" }
+      }.freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        rewrite_legacy_verb!
+
+        case @argv.first
+        when nil
+          run_index
+        when "-h", "--help", "help"
+          @out.puts(USAGE)
+          0
+        when "--list"
+          @argv.shift
+          run_list(@argv.shift)
+        when "--path"
+          @argv.shift
+          run_path(@argv.shift)
+        when "--print"
+          @argv.shift
+          run_print(@argv.shift)
+        else
+          run_print(@argv.shift)
+        end
+      end
+
+      private
+
+      # Translate a deprecated verb spelling into its flag form, warning
+      # once on stderr, so the dispatch above only handles canonical forms.
+      def rewrite_legacy_verb!
+        spec = LEGACY_VERBS[@argv.first]
+        return unless spec
+
+        @err.puts(
+          "rigor docs: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
+          "#{LEGACY_VERB_REMOVAL}; use `rigor docs #{spec.fetch(:advice)}` instead."
+        )
+        @argv[0] = spec.fetch(:flag)
+      end
+
+      def run_index
+        if File.file?(LLMS_INDEX)
+          @out.write(File.read(LLMS_INDEX))
+          0
+        else
+          run_list(nil)
+        end
+      end
+
+      def run_list(category)
+        docs = discover_docs
+        if category
+          categories = docs.map { |doc| doc.fetch(:category) }.uniq
+          unless categories.include?(category)
+            @err.puts("Unknown category: #{category}")
+            @err.puts("Available categories: #{categories.join(', ')}")
+            return 1
+          end
+          docs = docs.select { |doc| doc.fetch(:category) == category }
+        end
+
+        if docs.empty?
+          @err.puts("No bundled docs found under #{DOCS_ROOT}")
+          return 1
+        end
+
+        width = docs.map { |doc| doc.fetch(:relative).length }.max
+        docs.each do |doc|
+          @out.puts(format("%-#{width}s  %s", doc.fetch(:relative), doc.fetch(:path)))
+        end
+        0
+      end
+
+      def run_print(name)
+        return usage_error("a doc name is required") if name.nil?
+
+        doc = resolve_doc(name)
+        return doc if doc.is_a?(Integer) # error status, already reported
+
+        # ASCII-only provenance header: the doc body is read with the
+        # external encoding (US-ASCII under a C locale), so a UTF-8 header
+        # would set the output buffer to UTF-8 and clash with the body.
+        @out.puts("<!-- rigor docs #{doc.fetch(:name)} (rigortype #{Rigor::VERSION}, offline) -->")
+        @out.puts
+        @out.write(File.read(doc.fetch(:path)))
+        0
+      end
+
+      def run_path(name)
+        return usage_error("`--path` requires a doc name") if name.nil?
+
+        doc = resolve_doc(name)
+        return doc if doc.is_a?(Integer)
+
+        @out.puts(doc.fetch(:path))
+        0
+      end
+
+      # Resolve a query to a single doc. Exact relative-path and
+      # prefixed-basename aliases are unique; a short (prefix-stripped)
+      # name is accepted only when one category owns it.
+      #
+      # @return [Hash, Integer] the doc entry, or an error exit status
+      #   after the error has been written to `@err`.
+      def resolve_doc(query)
+        docs = discover_docs
+
+        exact = docs.find { |doc| doc.fetch(:exact_aliases).include?(query) }
+        return exact if exact
+
+        short = docs.select { |doc| doc.fetch(:short_name) == query }
+        case short.size
+        when 1 then short.first
+        when 0 then name_error(query)
+        else ambiguous_error(query, short)
+        end
+      end
+
+      # Every bundled doc, each carrying the aliases `rigor docs <name>`
+      # accepts and the category used by `--list`. `install.md` sits at
+      # the docs root (category `guide`); the rest are manual / handbook
+      # chapters.
+      def discover_docs
+        paths = [File.join(DOCS_ROOT, "install.md")]
+        paths += Dir.glob(File.join(MANUAL_ROOT, "**", "*.md")) # Dir.glob is already sorted
+        paths += Dir.glob(File.join(HANDBOOK_ROOT, "**", "*.md"))
+        paths.select { |path| File.file?(path) }.map { |path| doc_entry(path) }
+      end
+
+      def doc_entry(path)
+        relative = path.delete_prefix("#{DOCS_ROOT}/").delete_suffix(".md")
+        base = File.basename(path, ".md")
+        short = base.sub(/\A\d+-/, "")
+        segments = relative.split("/")
+        category = segments.size > 1 ? segments.first : "guide"
+        {
+          name: base,
+          relative: relative,
+          path: path,
+          category: category,
+          # Always-unique addresses: the `docs/`-relative path and the
+          # prefixed basename. `handbook/03-narrowing` and `03-narrowing`.
+          exact_aliases: [relative, base].uniq,
+          # The prefix-stripped short name (`narrowing`); ambiguous when
+          # two categories carry the same chapter slug (`plugins`).
+          short_name: short
+        }
+      end
+
+      def name_error(name)
+        @err.puts("Unknown doc: #{name}")
+        @err.puts("Available docs (try `rigor docs --list`):")
+        discover_docs.each { |doc| @err.puts("  #{doc.fetch(:relative)}") }
+        1
+      end
+
+      def ambiguous_error(query, candidates)
+        @err.puts("Ambiguous doc name: #{query}")
+        @err.puts("Matches several docs — qualify with the category path:")
+        candidates.each { |doc| @err.puts("  #{doc.fetch(:relative)}") }
+        1
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        @err.puts(USAGE)
+        Rigor::CLI::EXIT_USAGE
+      end
+    end
+  end
+end

data/lib/rigor/cli/skill_command.rb

@@ -2,8 +2,6 @@
 
 require_relative "command"
 
-require "optparse"
-
 module Rigor
   class CLI
     # `rigor skill` — discover and print the SKILL.md files
@@ -17,59 +15,112 @@ module Rigor
     # gem checkout — the project being analysed has no copy, so an
     # AI agent has no a priori way to find them.
     #
-    # This command exposes the bundled skills via three subcommands:
+    # Grammar (mirrors `rigor docs`): the positional slot is always a
+    # skill *name*; alternative outputs are flags, so a skill named
+    # `list` or `path` can never be shadowed by a verb.
     #
-    # - `rigor skill list`         — table of name + absolute path.
-    # - `rigor skill print <name>` — short header (paths + how to use)
-    #                                followed by the SKILL.md body. This
-    #                                is the form AI agents should call;
-    #                                the inline body plus the header's
-    #                                absolute paths together let the
-    #                                agent act with or without a file
-    #                                reading tool.
-    # - `rigor skill path <name>`  — one-line absolute path, suitable
-    #                                as input to a Read tool.
+    # - `rigor skill`              — list bundled skills (the default).
+    # - `rigor skill <name>`       — print the SKILL.md body (header + body).
+    #                                This is the form AI agents call; the
+    #                                inline body plus the header's absolute
+    #                                paths let the agent act with or without
+    #                                a file-reading tool.
+    # - `rigor skill --path <name>`— one-line absolute path, for a Read tool.
+    # - `rigor skill --list`       — table of name + absolute path.
+    # - `rigor skill --describe`   — ADR-73's live entry point: a cheap
+    #                                project-state probe + the recommended
+    #                                next skill + every skill's current
+    #                                description. The `rigor-next-steps`
+    #                                SKILL routes off this so no
+    #                                version-coupled guidance is frozen into
+    #                                the SKILL. Also spelled `describe`, and
+    #                                surfaced top-level as `rigor describe`.
     #
-    # `rigor skill` with no subcommand is an alias for `list`.
+    # The pre-v0.3.0 verb spellings `rigor skill list` / `print <name>` /
+    # `path <name>` still work but emit a stderr deprecation notice; they
+    # are removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI
+    # deprecations"). `describe` is a no-argument action, not a name-slot
+    # verb, so it stays first-class alongside `--describe`.
     class SkillCommand < Command
       USAGE = <<~USAGE
-        Usage: rigor skill <subcommand> [args]
+        Usage: rigor skill [<name>] [--path <name>] [--list] [--describe]
+
+        With no argument, lists the bundled skills.
 
-        Subcommands:
-          list                  List bundled skills (default when no subcommand given)
-          print <name>          Print the SKILL.md body for <name> to stdout, with a header
-          path  <name>          Print the absolute path of the SKILL.md file for <name>
+          rigor skill                List bundled skills
+          rigor skill <name>         Print the SKILL.md body for <name> (with a header)
+          rigor skill --path <name>  Print the absolute path of the SKILL.md file for <name>
+          rigor skill --list         List bundled skills (name + absolute path)
+          rigor skill --describe     Report project state + recommend the next skill to run
 
         Examples:
-          rigor skill list
-          rigor skill print rigor-project-init
-          rigor skill path  rigor-baseline-reduce
+          rigor skill
+          rigor skill rigor-project-init
+          rigor skill --path rigor-baseline-reduce
+          rigor skill --describe        (also: rigor describe)
+
+        Deprecated (removed in v0.3.0) — use the forms above:
+          rigor skill list           ->  rigor skill --list
+          rigor skill print <name>   ->  rigor skill <name>
+          rigor skill path <name>    ->  rigor skill --path <name>
       USAGE
 
       # The bundled skills live at `<gem_root>/skills/`. From
       # `lib/rigor/cli/skill_command.rb` that is three directories up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
 
+      # The verb subcommands the flags superseded keep working with a
+      # stderr deprecation notice until this version drops them. Each maps
+      # to the canonical advice printed and the flag it rewrites to.
+      LEGACY_VERB_REMOVAL = "v0.3.0"
+      LEGACY_VERBS = {
+        "list" => { old: "list",         advice: "--list", flag: "--list" },
+        "print" => { old: "print <name>", advice: "<name>", flag: "--print" },
+        "path" => { old: "path <name>", advice: "--path <name>", flag: "--path" }
+      }.freeze
+
       # @return [Integer] CLI exit status.
       def run
-        subcommand = @argv.shift || "list"
+        rewrite_legacy_verb!
 
-        case subcommand
-        when "list" then run_list
-        when "print" then run_print
-        when "path" then run_path
+        case @argv.first
+        when nil
+          run_list
         when "-h", "--help", "help"
           print_usage(@out)
           0
+        when "describe", "--describe"
+          @argv.shift
+          run_describe
+        when "--list"
+          @argv.shift
+          run_list
+        when "--path"
+          @argv.shift
+          run_path(@argv.shift)
+        when "--print"
+          @argv.shift
+          run_print(@argv.shift)
         else
-          @err.puts("Unknown subcommand: #{subcommand}")
-          print_usage(@err)
-          Rigor::CLI::EXIT_USAGE
+          run_print(@argv.shift)
         end
       end
 
       private
 
+      # Translate a deprecated verb spelling into its flag form, warning
+      # once on stderr, so the dispatch above only handles canonical forms.
+      def rewrite_legacy_verb!
+        spec = LEGACY_VERBS[@argv.first]
+        return unless spec
+
+        @err.puts(
+          "rigor skill: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
+          "#{LEGACY_VERB_REMOVAL}; use `rigor skill #{spec.fetch(:advice)}` instead."
+        )
+        @argv[0] = spec.fetch(:flag)
+      end
+
       def run_list
         skills = discover_skills
         if skills.empty?
@@ -84,9 +135,8 @@ module Rigor
         0
       end
 
-      def run_print
-        name = @argv.shift
-        return usage_error("`print` requires a skill name") if name.nil?
+      def run_print(name)
+        return usage_error("a skill name is required") if name.nil?
 
         skill = find_skill(name)
         return name_error(name) if skill.nil?
@@ -97,9 +147,8 @@ module Rigor
         0
       end
 
-      def run_path
-        name = @argv.shift
-        return usage_error("`path` requires a skill name") if name.nil?
+      def run_path(name)
+        return usage_error("`--path` requires a skill name") if name.nil?
 
         skill = find_skill(name)
         return name_error(name) if skill.nil?
@@ -108,11 +157,24 @@ module Rigor
         0
       end
 
+      # `rigor skill --describe` (also spelled `describe`) — ADR-73's
+      # live "brain", delegated to {SkillDescribe}: it probes the current
+      # project's state with cheap presence checks (it never runs `rigor
+      # check`), recommends the next skill to run, and prints every
+      # bundled skill's current frontmatter description, so the
+      # `rigor-next-steps` SKILL can route without copying any
+      # version-coupled guidance into itself.
+      def run_describe
+        require_relative "skill_describe"
+
+        @out.puts(SkillDescribe.new(skills: discover_skills).render)
+        0
+      end
+
       # The header that precedes the SKILL.md body when an agent
-      # runs `rigor skill print <name>`. Kept as `# `-prefixed
-      # comment lines so the combined output remains parseable as
-      # markdown — anything below `---` (the SKILL frontmatter
-      # marker) is unchanged.
+      # runs `rigor skill <name>`. Kept as `# `-prefixed comment lines
+      # so the combined output remains parseable as markdown — anything
+      # below `---` (the SKILL frontmatter marker) is unchanged.
       def render_print_header(skill)
         references_dir = File.join(File.dirname(skill.fetch(:path)), "references")
         ref_line = if File.directory?(references_dir)
@@ -147,7 +209,7 @@ module Rigor
 
       def name_error(name)
         @err.puts("Unknown skill: #{name}")
-        @err.puts("Available skills:")
+        @err.puts("Available skills (try `rigor skill --list`):")
         discover_skills.each { |s| @err.puts("  #{s.fetch(:name)}") }
         1
       end