pikuri-skills 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8ffca294daaa6b3ecdf2b24aa4a61cabcb447181067aa937a793def7f158a8
-  data.tar.gz: 61bc4b765ad51cfab254e89086bcd6ac8bd26410caa5707afb42acc98d696ec5
+  metadata.gz: 9c98e45fc109b71c03ed61bcc841eda71bbb74454bab297087fe100401ce7185
+  data.tar.gz: 18d24a2ac73b760da78df70fe18d551ff7d24ca9c99b4cf0e63f364cd36beabf
 SHA512:
-  metadata.gz: 0be0e990da5370c7863544ddf60f3137ce1a4170a8047b25950a344dfbf3fd08a9b493dcc204f9e2c976b634c13a5df48c8f909592afa5a633b1d57937d3c117
-  data.tar.gz: 1689554961b21d618bd7507ca48cb8c36bf1c0ddecc11d85311a8b45d67eaab5c241dbbbddf1bf98c09cd8825ee40a6b1d21bb0bf5fcfc95a872f21bccdc0113
+  metadata.gz: 9aed0f05b6f15478060c7ea4dee97e2dbb3f64f973a00f89118b4d12c328899b2f6115b7388234db8ac45a0842dcba633e68e2db766d7d9a314b36baf7daa66a
+  data.tar.gz: 18b79412748c6883e01b1d994349c2c5874173d94ec682dbe5cfac7a772bb4c82910d0226fcff174ea4c5c31bf01c7fdf2cb96c9397f5ba5525afe15d0bdc6d1

data/README.md

@@ -2,7 +2,8 @@
 
 [Agent Skills standard](https://agentskills.io/specification)
 support for the [pikuri](https://codeberg.org/mvysny/pikuri)
-AI-assistant toolkit.
+AI-assistant toolkit — plus its human-invoked counterpart, slash
+commands.
 
 Provides:
 - `Pikuri::Skill::Catalog` — discovery + validation of skill folders
@@ -13,6 +14,11 @@ Provides:
   a skill's body into the conversation on demand.
 - `Pikuri::Skill::Extension` — wires both into a `Pikuri::Agent` via
   the `c.add_extension(...)` block API.
+- `Pikuri::Command::Registry` / `Pikuri::Command::Renderer` — slash
+  commands: prompt templates *you* invoke by typing `/name`, scanned
+  from `.pikuri/commands` and `.claude/commands` under the same search
+  bases. Never shown to the model, so they cost nothing in the system
+  prompt.
 
 ## Install
 
@@ -36,7 +42,7 @@ catalog = Pikuri::Skill::Catalog::Bundled.new(
 )
 
 agent = Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
-  c.add_extension(Pikuri::Skill::Extension.new(catalog: catalog))
+  c.add_extension(Pikuri::Skill::Extension.new(catalog: catalog, root: project_root))
 end
 ```
 
@@ -46,10 +52,79 @@ skill) and registers the `skill` tool. The LLM invokes `skill` with a
 name; the tool returns the skill's body wrapped with its base
 directory so the LLM can resolve sidecar files via `read`.
 
+## Skills that wait for the right project
+
+A skill only some projects need can say so in its frontmatter, and stay
+out of the prompt everywhere else:
+
+```yaml
+---
+name: writing-rdoc
+description: Writing Ruby doc comments — which level each fact belongs at.
+paths:
+  - "**/*.rb"
+  - "**/*.gemspec"
+when-to-use: >-
+  About to write or edit a # comment, or a @param/@return tag.
+---
+```
+
+Such a skill is withheld completely — no name, no description, and the
+`skill` tool refuses it exactly as it refuses a name that exists nowhere.
+The moment the agent reads, writes or edits a file matching one of the
+globs, its description arrives in the conversation and it becomes
+loadable. `/clear` hides it again.
+
+Patterns are gitignore syntax, so a slash-less pattern matches at any
+depth and a bare directory covers everything beneath it. Two things
+worth knowing before you write one:
+
+- **`paths: []` means *always advertised*, not "never"** — as does
+  `paths: ["**"]`, and a bare `paths:` with nothing under it.
+- **Give the agent an `interloper:`** (`Pikuri::Agent::Control::Interloper.new`).
+  A promotion arrives as a mid-loop injection, so without one there is
+  nowhere for it to land — pikuri then leaves every skill advertised and
+  logs a warning, rather than hiding one it could never bring back.
+
+## Slash commands
+
+A command is one Markdown file. The model is never told it exists —
+you invoke it by name, and what it expands to becomes *your* next
+message:
+
+```ruby
+registry = Pikuri::Command::Registry.new(
+  search_bases: [project_root, Dir.home]
+)
+
+# ~/.claude/commands/wh.md  ->  /wh
+text = registry.expand('wh', arguments: 'swingai')   # nil if no such command
+agent.run_loop(user_message: text)                   # it *is* your turn
+```
+
+`$ARGUMENTS` in the body becomes everything you typed after the name;
+`$1`…`$9` are its whitespace-separated words. Both are left alone
+inside backticks and fenced blocks, so a body that *writes about* its
+own arguments survives expansion. If the body mentions neither, what
+you typed is appended as `ARGUMENTS: …` instead of being dropped.
+
+A file's path is its name: `commands/frontend/deploy.md` is
+`/frontend:deploy`. Frontmatter is optional; `description` and
+`argument-hint` feed a menu, everything else is ignored — except
+`allowed-tools:`, which is refused, as is a body containing a
+`` !`cmd` `` directive. pikuri will not run a shell command because
+you typed a slash, and it will not silently *widen* a toolset an
+author asked to narrow. Add
+`Pikuri::Command::Extension.new(registry: registry)` to the agent so
+the trifecta report knows the commands are there.
+
+Try it in `bin/pikuri-code` or `bin/pikuri-assistant`: both list the
+commands they found at boot and dispatch a typed `/name`.
+
 ## Further reading
 
 - **Narrative walkthrough:**
-  [chapter 12 of the pikuri guide](../docs/guide/12-skills.md) —
+  [the skills chapter of the pikuri guide](../book/skills.md) —
   how skill folders are discovered, the `SKILL.md` format, and a
   worked drop-in example. (Currently a stub chapter; the API
   surface lives in the YARD docs below.)

data/lib/pikuri/bundle/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Discovery vocabulary shared by pikuri's *bundles* — Markdown files with
+  # YAML frontmatter, found by scanning a list of search bases rather than by
+  # being registered one at a time.
+  module Bundle
+    # One search base: a directory to scan, plus whether the bytes under it
+    # are the user's own.
+    #
+    #   Bundle::Base.new(dir: project_root, trusted: repo_sources_are_mine)
+    #   Bundle::Base.new(dir: Dir.home)              # trusted: false
+    #
+    # +trusted+ asks what +Pikuri::Workspace::Filesystem#trusted?+ asks for
+    # the file tools — user-authored bytes, or bytes that arrived with a
+    # clone? — but about *this root alone*. That is why it is a value the
+    # host passes rather than a reach into the workspace: the two objects
+    # reach different bytes, so a workspace whose +readable:+ carries
+    # +~/.m2/repository+ is honestly untrusted while the project's own
+    # +.pikuri/skills+ beside it is honestly the user's. Like +private:+, it
+    # is unverifiable, so silence buys +false+.
+    #
+    # A scanner grades its own untrusted trifecta leg by unioning this flag
+    # over the bundles it actually stored, so an untrusted base costs nothing
+    # while it holds nothing.
+    Base = Data.define(:dir, :trusted) do
+      # @param dir [String, Pathname] directory to scan for bundle subdirs
+      # @param trusted [Boolean] every byte under +dir+ is user-authored
+      # @return [Base]
+      def initialize(dir:, trusted: false) = super
+    end
+  end
+end

data/lib/pikuri/bundle/frontmatter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Pikuri
+  module Bundle
+    # Splits a bundle file into its YAML frontmatter and its body.
+    #
+    #   Frontmatter.split(File.read(path), path: path)
+    #   # => [{"description" => "Weekly work log"}, "# Weekly work log\n…"]
+    #
+    # A file with no +---+ block splits as +[nil, body]+ — the caller decides
+    # whether that is a skipped file or an ordinary one, and the two bundle
+    # surfaces answer differently. Malformed YAML degrades to +[{}, body]+
+    # with a warning rather than raising: a frontmatter typo should cost the
+    # keys, not the file.
+    module Frontmatter
+      LOGGER = Pikuri.logger_for('Bundles')
+      private_constant :LOGGER
+
+      module_function
+
+      # @param content [String] the whole file
+      # @param path [String] used in warnings only
+      # @return [Array(Hash{String=>Object}, String)] parsed keys and body
+      # @return [Array(nil, String)] when no frontmatter block is present
+      def split(content, path:)
+        normalized = content.gsub(/\r\n?/, "\n")
+        return [nil, normalized] unless normalized.start_with?("---\n")
+
+        end_marker = normalized.index("\n---", 4)
+        return [nil, normalized] unless end_marker
+
+        body = normalized[(end_marker + 4)..].to_s.sub(/\A\n/, '')
+        [parse(normalized[4...end_marker], path: path), body]
+      end
+
+      # @param yaml_str [String]
+      # @param path [String]
+      # @return [Hash{String=>Object}] +{}+ on a parse error or a non-Hash document
+      def parse(yaml_str, path:)
+        parsed =
+          begin
+            YAML.safe_load(yaml_str) || {}
+          rescue Psych::SyntaxError => e
+            LOGGER.warn("#{path}: frontmatter YAML parse error: #{e.message}")
+            {}
+          end
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+      private_class_method :parse
+    end
+  end
+end

data/lib/pikuri/command/extension.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Command
+    # Declares the command surface to {Pikuri::Trifecta}, and does nothing
+    # else — it registers no tool, renders no prompt snippet and binds no
+    # handle.
+    #
+    #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
+    #     c.add_extension Pikuri::Command::Extension.new(registry: registry)
+    #   end
+    #
+    # A host wires it purely so the boot banner tells the truth. Expansion
+    # needs none of this: {Registry} and {Renderer} are pure functions over
+    # disk, and a host dispatches a typed +/name+ itself.
+    #
+    # == Why an extension for one declaration
+    #
+    # The detector builds its tree from an agent's *tools* plus what its
+    # extensions contribute. A command is neither — so a wired command surface
+    # would land in that tree nowhere, and an agent that genuinely holds all
+    # three legs would report two. Skills don't have this problem only because
+    # their bytes ride {Pikuri::Skill::SkillTool}'s declaration; commands have
+    # no tool to ride.
+    #
+    # An object rather than a kwarg on the host side because the mistake
+    # should be unrepresentable, not something each host remembers.
+    class Extension
+      include Pikuri::Agent::Extension
+
+      # @param registry [Pikuri::Command::Registry]
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      # @return [Pikuri::Command::Registry]
+      attr_reader :registry
+
+      # The +untrusted+ leg, graded over the commands the registry stored:
+      # +:hard+ unless every one of them came from a base the host vouched
+      # for. No +private+ leg (a command reads nothing) and no egress leg (it
+      # sends nothing) — a command body is prose that lands in a user turn.
+      #
+      # @param tools [Array<Pikuri::Tool>] unused; commands contribute no children
+      # @return [Pikuri::Trifecta::Contribution, nil] +nil+ when there is
+      #   nothing to declare, so an empty or fully-vouched registry adds no row
+      def trifecta_contribution(tools)
+        level = @registry.untrusted_level
+        return nil if level == :none
+
+        Pikuri::Trifecta::Contribution.new(
+          label: '(commands)',
+          legs: Pikuri::Tool::TrifectaLegs.new(
+            private: false, untrusted: level, egress_payload_review: :no_egress
+          )
+        )
+      end
+    end
+  end
+end

data/lib/pikuri/command/refused_error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Command
+    # Raised by {Registry#get} for a command that exists on disk but cannot be
+    # run — it declares +allowed-tools:+, or its body carries a
+    # <code>!`cmd`</code> directive.
+    #
+    # Host-facing: it never reaches a tool, so the +"Error: …"+-string
+    # convention for model-visible failures does not apply. A REPL rescues it
+    # and prints {#message}; the command stays in {Registry#list} so a menu can
+    # still show it, greyed out or not.
+    #
+    #   begin
+    #     text = registry.expand(name, arguments: args)
+    #   rescue Pikuri::Command::RefusedError => e
+    #     puts "/#{name} is unavailable — #{e.message}"
+    #     next
+    #   end
+    class RefusedError < StandardError
+      # @return [String] path of the command file
+      attr_reader :location
+
+      # @param location [String] path of the command file
+      # @param reason [String] what the file did, phrased as the predicate of
+      #   "this command …"
+      def initialize(location, reason)
+        @location = location
+        super("#{location}: #{reason}")
+      end
+    end
+  end
+end

data/lib/pikuri/command/registry.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Slash commands: prompt templates a *human* invokes by typing +/name+.
+  #
+  # The counterpart of {Pikuri::Skill}, and deliberately not a variant of it.
+  # A skill is advertised to the model and loaded by the model, so it costs
+  # prompt tokens on every turn; a command is never advertised, costs nothing
+  # resident, and lands as the user's own turn when the human asks for it.
+  # {Registry} discovers them, {Renderer} expands one into the text a host
+  # then sends.
+  module Command
+    # On-disk registry of slash commands, over the same *search bases* as the
+    # skill catalog: under each base it scans +.pikuri/commands+ and
+    # +.claude/commands+ for +.md+ files.
+    #
+    #   registry = Pikuri::Command::Registry.new(search_bases: [
+    #     Pikuri::Bundle::Base.new(dir: project_root, trusted: repo_sources_are_mine),
+    #     Pikuri::Bundle::Base.new(dir: Dir.home, trusted: home_bundles_are_mine)
+    #   ])
+    #   text = registry.expand('wh', arguments: 'swingai')   # nil if no such command
+    #   agent.run_loop(user_message: text)                   # it *is* the human's turn
+    #
+    # == Names are paths
+    #
+    # A command's name is its file path under the scanned dir, +.md+ dropped
+    # and separators +:+-joined: +commands/frontend/deploy.md+ is
+    # +/frontend:deploy+. A frontmatter +name:+ is *ignored* (warned about) —
+    # for a skill the name is a label the model reads, but for a command it is
+    # the address the human types, and an address its location doesn't predict
+    # is not an address.
+    #
+    # == Precedence
+    #
+    # Bases left to right, +.pikuri/commands+ before +.claude/commands+; the
+    # first command seen for a name wins and later ones are dropped with a
+    # warning. Pass the project root first for "project beats global".
+    #
+    # A host resolving a typed +/name+ owes one more rule, since nothing here
+    # sees the other two namespaces: **host built-in > command > skill**.
+    # Match built-ins first or a cloned repo shipping
+    # +.claude/commands/plan.md+ captures a +/plan+ that flips a safety gate.
+    #
+    # == Validation, and the two refusals
+    #
+    # Nothing else is fatal. Frontmatter is optional (a bare +.md+ is all
+    # body); +description+ falls back to the name; unknown keys are ignored.
+    # A command that parses is a command the human can invoke — a menu entry
+    # that silently vanished would be the worse failure, since the human is
+    # looking straight at the list.
+    #
+    # Two things are refused, at {#get} rather than at scan time, so typing
+    # +/foo+ explains itself instead of the entry being mysteriously absent:
+    #
+    # * +allowed-tools:+ — a narrowing pikuri cannot honour, since an agent's
+    #   toolset is fixed at +configure+ time; ignoring the key would *widen*
+    #   what the author asked to fence.
+    # * a <code>!`cmd`</code> body directive — the shell command Claude Code
+    #   runs before sending the prompt. pikuri never runs it.
+    #
+    # Detection is over-eager on purpose and does *not* skip fenced blocks —
+    # the inverse of what {Renderer} does to the same characters, which is not
+    # an inconsistency; see there. Rationale for both refusals:
+    # +DECISIONS.md+ +D_command_inlining_legs+.
+    #
+    # == Trust
+    #
+    # {#untrusted_level} unions {Pikuri::Bundle::Base#trusted} over the
+    # commands actually stored, exactly as the skill catalog does, and
+    # {Extension} declares the result. A *refused* command never counts: its
+    # bytes cannot reach the context.
+    #
+    # Immutable.
+    class Registry
+      LOGGER = Pikuri.logger_for('Commands')
+      private_constant :LOGGER
+
+      # Subdirectory names scanned under each search base, in precedence
+      # order. No +.agents/commands+: no harness in +COMPARISON.md+ defines
+      # one, and an invented convention is worse than a missing one.
+      COMMAND_SUBDIRS = ['.pikuri/commands', '.claude/commands'].freeze
+      private_constant :COMMAND_SUBDIRS
+
+      # A loaded command. Bodies are eager-loaded at scan time; command files
+      # are small and expansion stays IO-free.
+      #
+      # @!attribute [r] name
+      #   @return [String] the address the human types, +/+ excluded
+      # @!attribute [r] description
+      #   @return [String] menu chrome; the name itself when the file gave none
+      # @!attribute [r] argument_hint
+      #   @return [String, nil] opaque display string, e.g. +"<label> [--since DATE]"+
+      # @!attribute [r] location
+      #   @return [String] absolute path of the +.md+
+      # @!attribute [r] body
+      #   @return [String] everything after the frontmatter, un-expanded
+      # @!attribute [r] refusal
+      #   @return [String, nil] why this cannot run, captured at scan time so
+      #     {#get} re-reads nothing; +nil+ when it can
+      # @!attribute [r] sidecars
+      #   @return [Boolean] the command's directory holds something the
+      #     registry did not load as a command — a non-Markdown file, or a
+      #     subdirectory holding none — which is what earns the expansion its
+      #     "this command lives in …" footer
+      Command = Data.define(:name, :description, :argument_hint, :location, :body, :refusal, :sidecars) do
+        # @return [Boolean] true when {#get} would raise instead of returning this
+        def refused? = !refusal.nil?
+
+        # @return [Boolean]
+        def sidecars? = sidecars
+      end
+
+      # @param search_bases [Array<Pikuri::Bundle::Base, String, Pathname>]
+      #   directories under which to look for command subdirs. Typical values:
+      #   the project root and +Dir.home+. Processed left to right. A bare
+      #   path means +Bundle::Base.new(dir: path)+ — untrusted, so the unsafe
+      #   value is the one you get by saying nothing.
+      # @return [Registry]
+      def initialize(search_bases:)
+        @roots = []
+        @commands = {}
+        @untrusted = false
+
+        search_bases.each do |entry|
+          base = entry.is_a?(Bundle::Base) ? entry : Bundle::Base.new(dir: entry)
+          COMMAND_SUBDIRS.each do |sub|
+            root = File.join(base.dir.to_s, sub)
+            next unless File.directory?(root)
+
+            @roots << root
+            scan_root(root, trusted: base.trusted)
+          end
+        end
+
+        @roots.freeze
+        @commands.freeze
+        @list = @commands.values.freeze
+        freeze
+      end
+
+      # @return [Array<Command>] commands in discovery order (which equals
+      #   precedence order), refused ones included so a menu can show them
+      attr_reader :list
+
+      # @return [Array<String>] absolute paths of the command directories this
+      #   registry covered, in scan order. Hosts fold these into
+      #   +Pikuri::Workspace::Filesystem+'s +readable:+ so the model can
+      #   +read+ a file a command body points at.
+      attr_reader :roots
+
+      # Look a command up by the name the human typed.
+      #
+      # Two outcomes beyond success, and they are different on purpose:
+      # *absent* is an ordinary thing a human causes by typo, while *refused*
+      # is a fact about a file on disk that retyping cannot fix.
+      #
+      # @param name [String] e.g. +"wh"+ or +"frontend:deploy"+
+      # @return [Command, nil] +nil+ when no command has that name
+      # @raise [RefusedError] when the command exists but cannot be run
+      def get(name)
+        command = @commands[name]
+        return nil if command.nil?
+        raise RefusedError.new(command.location, command.refusal) if command.refused?
+
+        command
+      end
+
+      # {#get} plus {Renderer.expand}, in one call. What comes back is the
+      # human's own *user* turn — see {Renderer} for what that rules out.
+      #
+      # @param name [String]
+      # @param arguments [String] everything typed after the command name
+      # @return [String, nil] +nil+ when no command has that name
+      # @raise [RefusedError] when the command exists but cannot be run
+      def expand(name, arguments: '')
+        command = get(name)
+        return nil if command.nil?
+
+        Renderer.expand(command, arguments: arguments)
+      end
+
+      # @return [Boolean] true when no base held a command; {Extension} then
+      #   declares nothing
+      def empty? = @list.empty?
+
+      # @return [Symbol] +:none+ when every runnable command came from a
+      #   +trusted+ base, else +:hard+
+      def untrusted_level = @untrusted ? :hard : :none
+
+      private
+
+      def scan_root(root, trusted:)
+        Dir.glob('**/*.md', base: root).sort.each do |relative|
+          path = File.join(root, relative)
+          next unless File.file?(path)
+
+          command = parse_command(path, name: relative.delete_suffix('.md').tr(File::SEPARATOR, ':'))
+          next if command.nil?
+
+          existing = @commands[command.name]
+          if existing
+            LOGGER.warn("command name '#{command.name}' at #{path} is shadowed by " \
+                        "earlier entry at #{existing.location}")
+          else
+            @commands[command.name] = command
+            @untrusted ||= !trusted && !command.refused?
+          end
+        end
+      end
+
+      def parse_command(path, name:)
+        frontmatter, body = Bundle::Frontmatter.split(File.read(path), path: path)
+        frontmatter ||= {}
+
+        declared = frontmatter['name'].to_s.strip
+        LOGGER.warn("#{path}: frontmatter name '#{declared}' ignored; a command is addressed " \
+                    "by its path, so this one is '#{name}'") if !declared.empty? && declared != name
+
+        description = frontmatter['description'].to_s.strip
+        LOGGER.warn("#{path}: no 'description'; the menu will show the name") if description.empty?
+
+        refusal = refusal_for(frontmatter, body)
+        LOGGER.warn("#{path}: #{refusal}; /#{name} will refuse to run") if refusal
+
+        Command.new(
+          name: name,
+          description: description.empty? ? name : description,
+          argument_hint: frontmatter['argument-hint']&.to_s,
+          location: path,
+          body: body,
+          refusal: refusal,
+          sidecars: sidecars?(File.dirname(path))
+        )
+      rescue Errno::ENOENT, Errno::EACCES => e
+        LOGGER.warn("#{path}: #{e.class}: #{e.message}; skipped")
+        nil
+      end
+
+      # Both spellings of the key: the documented +allowed-tools+ and the
+      # underscore form an author is as likely to write.
+      def refusal_for(frontmatter, body)
+        if frontmatter.key?('allowed-tools') || frontmatter.key?('allowed_tools')
+          'declares allowed-tools:, which pikuri cannot honour (an agent\'s toolset ' \
+          'is fixed at configure time, so ignoring the key would *widen* it)'
+        elsif body.match?(/!`/)
+          'contains a !`…` bash pre-execution directive, which pikuri never runs'
+        end
+      end
+
+      # True when +dir+ holds anything the registry did not load as a command.
+      # A subdirectory full of commands is a *namespace*, not a sidecar, so it
+      # does not count; a directory of nothing but commands — the common case
+      # — gets no footer and stays quiet.
+      def sidecars?(dir)
+        Dir.children(dir).any? do |entry|
+          child = File.join(dir, entry)
+          if File.directory?(child)
+            Dir.glob('**/*.md', base: child).empty?
+          else
+            !entry.end_with?('.md')
+          end
+        end
+      rescue Errno::ENOENT, Errno::EACCES
+        false
+      end
+    end
+  end
+end