pikuri-workspace 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd83aa622997eea8b09c700282cf401753d1925ace04a0c4ade3856c07ee8b4
-  data.tar.gz: 4cd46c7de8d42112e1119e68bab0ce7937ed9e5c270a29ceb34e5089178abd4c
+  metadata.gz: 3918af9bb28c07c5706f2738899b05cda0a9c65a3a59b7e10799a98c8b8bc0b8
+  data.tar.gz: 142a335f7f42891c0f9f5cd9964dc31202691f1fa470fef526ad61280a2f8bff
 SHA512:
-  metadata.gz: c818b87a2aca2f0f615d084cc7c6e0457d0a84e5cd5be8b061c36aba50a071ad2565c27170d33ae25ca810dee8a25b16b1a13b25477b21e1c00eb79d067f2bb0
-  data.tar.gz: 7277b1ba878546589d4107136f4d49e3dc68b0ee5aff80d3eeff8e06f9d97b4fa569eb8caf186337e39c72e9f33812e3963fd433eeb35f926f82bb6b681bb579
+  metadata.gz: a20b8468fa2fc9cbed1aed620b645443cc6fb8969aad611de24e8620c88efe16b692265aabb5520d0c5231f5f6da2c31a0cae3f815eed2fd4e7840ef13e637d5
+  data.tar.gz: b5c6f5bc61a0f45641127a252c5f55bac9e0d3f5bb5ee577abeed31419859454daf7b7db26a0f5880cd638304ab3bd7da5d63b910093c4223372f21b5a97f2cb

data/README.md

@@ -49,7 +49,7 @@ end
 `Workspace` is the "look-but-don't-leak" guard around filesystem
 access. Read tools route through `#resolve_for_read(path)`; mutating
 tools route through `#resolve_for_write(path)` + the Confirmer's
-`#confirm?(prompt:)`. Pass `temp: true` to mint an ephemeral
+`#confirm?(request:)`. Pass `temp: true` to mint an ephemeral
 writable playground via `Dir.mktmpdir` — its path is exposed as
 `workspace.temp` and auto-removed at process exit.
 

data/lib/pikuri/workspace/confirmer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'rainbow'
+
 module Pikuri
   module Workspace
     # Port for asking the user to confirm a potentially destructive tool
@@ -25,25 +27,74 @@ module Pikuri
     # == Seam discipline
     #
     # Tools that need confirmation take a {Confirmer} via constructor and
-    # invoke {#confirm?} with a fully-composed prompt String. Tools do
-    # *not* call +gets+ / +puts+ directly — same lesson as listeners,
-    # keep IO at the seam so a future TUI / web client can plug a
-    # different implementation in without touching tool code.
+    # invoke {#confirm?} with a semantic {Request} — *what* is being
+    # asked, never *how* it should look. All presentation belongs to the
+    # confirmer implementation: color, the answer cue, answer parsing,
+    # and — security-relevant — neutralizing hostile bytes in
+    # LLM-supplied text. The chrome-independent half of that (escape
+    # control bytes, flag bidi / zero-width / homoglyph spoofs) is the
+    # shared {Pikuri::Sanitizer}; the medium-specific half stays with the
+    # renderer that knows its medium (a terminal prints the sanitized
+    # text directly; a web client wraps it in HTML-escaping). Tools do *not*
+    # call +gets+ / +puts+ directly — same lesson as listeners, keep IO
+    # at the seam so a TUI / web client can plug a different
+    # implementation in without touching tool code.
     class Confirmer
-      # @param prompt [String] human-readable question composed by the
-      #   calling tool. The confirmer renders it and parses the answer;
-      #   it does NOT compose its own prompt content. Caller owns the
-      #   closing punctuation and any "(y/n)" cue.
+      # The semantic payload of one confirmation. Two fields:
+      #
+      # * +question+ — one-line headline composed by the calling tool,
+      #   e.g. +"OK to overwrite foo.rb: 120 → 245 bytes?"+. The caller
+      #   owns the phrasing and punctuation; the renderer owns the
+      #   answer cue (+"(y/n)?"+, buttons, ...).
+      # * +detail+ — optional preformatted body, possibly multi-line:
+      #   the raw bash command for {Pikuri::Code::Bash}, +nil+ for
+      #   {Write}. Renderers typically display it monospaced / dimmed.
+      #
+      # Both fields are RAW, straight from tool arguments the LLM
+      # composed (+detail+ is the command verbatim; +question+ may embed
+      # an LLM-written description). Renderers MUST neutralize them before
+      # display — route through {Pikuri::Sanitizer} (see {Terminal}), and
+      # additionally HTML-escape in a web client.
+      Request = Data.define(:question, :detail) do
+        # @param question [String] one-line headline; caller owns phrasing
+        # @param detail [String, nil] optional preformatted body
+        def initialize(question:, detail: nil)
+          super
+        end
+      end
+
+      # @param request [Request] semantic content composed by the
+      #   calling tool. The confirmer renders it (escaping for its
+      #   medium), poses the question, and parses the answer.
       # @return [Boolean] +true+ iff approved
       # @raise [NotImplementedError] in the abstract base
-      def confirm?(prompt:)
+      def confirm?(request:)
         raise NotImplementedError, "#{self.class}#confirm? must be implemented"
       end
 
-      # Stdin/stdout implementation: prints +prompt+ on its own line (a
-      # leading +puts+ guarantees separation from any streamed output
-      # the +Terminal+ listener may have produced just above), reads one
-      # line from +$stdin+, parses it strictly:
+      # Stdin/stdout implementation. Renders the request as up to several
+      # lines (a leading +puts+ guarantees separation from any streamed
+      # output the +Terminal+ listener may have produced just above):
+      #
+      # 1. a bold-yellow warning block — one line per
+      #    {Pikuri::Sanitizer::Warning} — shown only when the sanitizer
+      #    flagged something suspicious in the question or detail
+      # 2. the question, bold
+      # 3. the detail, dim — omitted when +nil+
+      # 4. the +(y/n)?+ cue
+      #
+      # Both question and detail pass through {Pikuri::Sanitizer}, which
+      # neutralizes control bytes — without it, a model could craft a
+      # command or description containing +"\rrm -rf ~/"+ that visually
+      # overwrites the echoed line after the user has already read it —
+      # and reports *why* it was unsafe so the user reads the warning
+      # before answering. Colors come from Rainbow (already in the
+      # dependency closure via pikuri-core), which self-disables on
+      # non-TTY output; the bold-yellow warning rendering is this
+      # terminal chrome's call, not the sanitizer's (the +Warning+
+      # carries plain text only).
+      #
+      # Then reads one line from +$stdin+ and parses it strictly:
       #
       # * +"y"+ / +"yes"+ (case-insensitive, stripped) → +true+
       # * +"n"+ / +"no"+ → +false+
@@ -53,11 +104,21 @@ module Pikuri
       #
       # No retry cap; EOF eventually breaks adversarial input.
       class Terminal < Confirmer
-        # @param prompt [String]
+        # @param request [Request]
         # @return [Boolean]
-        def confirm?(prompt:)
+        def confirm?(request:)
+          question = Pikuri::Sanitizer.sanitize(request.question)
+          detail   = request.detail ? Pikuri::Sanitizer.sanitize(request.detail) : nil
+          warnings = question.warnings + (detail ? detail.warnings : [])
+
           puts
-          puts prompt
+          unless warnings.empty?
+            puts Rainbow('⚠ Suspicious content detected — read carefully before approving:').yellow.bold
+            warnings.each { |w| puts Rainbow("  ! #{w.explanation}").yellow }
+          end
+          puts Rainbow(question.text).bold
+          puts Rainbow(detail.text).dimgray if detail
+          puts '(y/n)?'
           $stdout.flush
           loop do
             line = $stdin.gets
@@ -78,9 +139,9 @@ module Pikuri
       # coordinate stdin. The name +AUTO_APPROVE+ matches the public
       # constant {AUTO_APPROVE}.
       class AutoApprove < Confirmer
-        # @param prompt [String] ignored
+        # @param request [Request] ignored
         # @return [true]
-        def confirm?(prompt:)
+        def confirm?(request:)
           true
         end
       end

data/lib/pikuri/workspace/filesystem.rb

@@ -174,12 +174,6 @@ module Pikuri
       # raised at construction time for a denied project root.
       class Error < StandardError; end
 
-      # Parent directory under which every workspace mints its
-      # umbrella ({#internal_temp}). Honors +XDG_CACHE_HOME+ when set,
-      # else +~/.cache+; the +pikuri+ subdir is owned by us.
-      # +mkdir_p+'d lazily on first umbrella access.
-      CACHE_BASE = File.join(ENV['XDG_CACHE_HOME'] || File.join(Dir.home, '.cache'), 'pikuri')
-
       # Umbrella dirs older than this are reaped by
       # {.sweep_stale_internal_temps!} at gem load. Generous enough
       # that a long-lived pikuri session in another shell isn't
@@ -279,7 +273,7 @@ module Pikuri
       end
 
       # Per-workspace ephemeral umbrella. Minted lazily on first call
-      # under {CACHE_BASE}. Registered with {Pikuri::Finalizers} for
+      # under {Paths::cache}. Registered with {Pikuri::Finalizers} for
       # removal the moment it's minted, so anything subsequently placed inside
       # (the playground, {Pikuri::Code::Bash::Sandbox::Bubblewrap}'s
       # overlay state) gets wiped together. Callers that want
@@ -298,8 +292,8 @@ module Pikuri
       # one registry. The +path.exist?+ guard makes the removal a no-op
       # when the dir is already gone (test cleanup, manual rm).
       def self.mint_internal_temp
-        FileUtils.mkdir_p(CACHE_BASE)
-        path = Pathname.new(Dir.mktmpdir('workspace-', CACHE_BASE)).realpath
+        FileUtils.mkdir_p(Paths.cache)
+        path = Pathname.new(Dir.mktmpdir('workspace-', Paths.cache)).realpath
         Pikuri::Finalizers.register { FileUtils.remove_entry(path.to_s) if path.exist? }
         path
       end
@@ -307,18 +301,18 @@ module Pikuri
       # Reap +workspace-*+ umbrella dirs that have outlived
       # {INTERNAL_TEMP_STALE_SECONDS}. Called once at gem load via
       # {Pikuri::Workspace} so each process boot inherits a tidy
-      # {CACHE_BASE}. Failures (permission denied, racing concurrent
+      # {Paths::cache}. Failures (permission denied, racing concurrent
       # sweeper) are swallowed — best-effort cleanup; the
       # {Pikuri::Finalizers} removal is the load-bearing path.
       #
       # @return [void]
       def self.sweep_stale_internal_temps!
-        return unless File.directory?(CACHE_BASE)
+        return unless File.directory?(Paths.cache)
 
         cutoff = Time.now - INTERNAL_TEMP_STALE_SECONDS
-        Dir.children(CACHE_BASE).each do |entry|
+        Dir.children(Paths.cache).each do |entry|
           next unless entry.start_with?('workspace-')
-          path = File.join(CACHE_BASE, entry)
+          path = File.join(Paths.cache, entry)
           next unless File.directory?(path)
           next if File.mtime(path) > cutoff
 

data/lib/pikuri/workspace/read.rb

@@ -27,7 +27,7 @@ module Pikuri
     #
     # The line/byte windowing is delegated to
     # {Pikuri::FileType.read_as_text_paged}, which returns a
-    # {Pikuri::FileType::Page} this tool renders; the same windower
+    # {Pikuri::Extractor::Page} this tool renders; the same windower
     # backs +VectorDb::Tools::Read+. Two independent limits, whichever fires
     # first wins:
     #
@@ -38,27 +38,29 @@ module Pikuri
     # Additionally, individual lines longer than {MAX_LINE_LENGTH} chars
     # are truncated with {LINE_TRUNCATION_MARKER} appended; the model is
     # told to reach for +grep+ to find content inside such files. (These
-    # constants alias the +PAGE_*+ ones on {Pikuri::FileType} — one
+    # constants alias the +PAGE_*+ ones on {Pikuri::Extractor} — one
     # source of truth, shared with +VectorDb::Tools::Read+.)
     #
-    # == PDF extraction
+    # == PDF (and other extracted formats)
     #
-    # PDFs are detected by their +%PDF-+ magic prefix in the sample bytes
-    # and routed through {Pikuri::FileType.read_as_text_paged} instead of
-    # the binary-refusal path. The extractor walks pages lazily via
-    # +pdf-reader+, emitting one synthetic +"--- Page N ---"+ header line
-    # per page followed by that page's text. The offset / limit /
-    # MAX_BYTES contract is identical to the text path — extraction stops
-    # as soon as the line or byte cap is hit, so reading the first window
-    # of a 500-page PDF only parses the few pages needed. Line numbers in
-    # PDF output are for citation back to the user only; PDFs are not
-    # editable through {Edit}.
+    # Which formats read as text is the {Pikuri::Extractor} registry's
+    # business, not this tool's: with pikuri-pdf's extractor
+    # registered, PDFs are claimed by their +%PDF-+ magic prefix ahead
+    # of the binary refusal and extracted with one synthetic
+    # +"--- Page N ---"+ header line per page (see
+    # +Pikuri::Extractors::PDF+); a gem plugging another extractor
+    # into the registry extends this tool for free. Extraction is lazy
+    # where the format allows (+extract_lines+): reading the first
+    # window of a 500-page PDF parses only the pages the window needs.
+    # Formats without a lazy line shape (HTML) are extracted in full
+    # and then windowed. Line numbers in PDF output are for citation
+    # back to the user only; PDFs are not editable through {Edit}.
     #
     # PDFs with no extractable text (scanned images, empty documents) come
     # back with an LLM-actionable hint string rather than an empty
     # observation. Encrypted / malformed / XFA-form PDFs surface as
-    # +"Error: cannot extract PDF text: ..."+ — same convention as other
-    # tool errors the model can react to. No OCR.
+    # +"Error: ..."+ — same convention as other tool errors the model
+    # can react to. No OCR.
     #
     # == Image attachments
     #
@@ -96,36 +98,38 @@ module Pikuri
     # * Image larger than {MAX_IMAGE_BYTES} → +"Error: image too large…"+,
     #   leaving the model to pick a different file or ask the user to
     #   resize.
-    # * Binary content → {Pikuri::FileType.binary?} on the sample; any
-    #   +NUL+ byte or a sample dense in control characters triggers
-    #   refusal. Catches archives and compiled artifacts without an
-    #   extension list to maintain. PDFs and supported images are
-    #   intercepted by their respective magic-byte checks via
-    #   {Pikuri::FileType.detect_mime} before the binary sniff — see
-    #   above.
+    # * Binary content → nothing in the {Pikuri::Extractor} registry
+    #   claims it ({Pikuri::Extractor::Passthrough} declines on the
+    #   {Pikuri::FileType.binary?} heuristic: any +NUL+ byte or a
+    #   sample dense in control characters). Catches archives and
+    #   compiled artifacts without an extension list to maintain.
+    #   Registered extractors (pikuri-pdf's PDF, pikuri-extractors'
+    #   office formats) claim their bytes ahead of that refusal;
+    #   images are intercepted here via {Pikuri::FileType.detect_mime}
+    #   before extraction is attempted — see above.
     # * Offset past EOF → +"Error: offset N is beyond end of file (M lines total)"+.
     class Read < Pikuri::Tool
-      # The windowing constants live on {Pikuri::FileType} now (shared
+      # The windowing constants live on {Pikuri::Extractor} (shared
       # with +VectorDb::Tools::Read+); these aliases keep the names this tool's
       # description and specs reference pointing at the single source.
 
       # @return [Integer] default value of the +limit+ parameter (number
       #   of lines to read per call).
-      DEFAULT_LIMIT = Pikuri::FileType::PAGE_DEFAULT_LIMIT
+      DEFAULT_LIMIT = Pikuri::Extractor::PAGE_DEFAULT_LIMIT
 
       # @return [Integer] per-line character cap; longer lines are
       #   truncated with {LINE_TRUNCATION_MARKER}.
-      MAX_LINE_LENGTH = Pikuri::FileType::PAGE_MAX_LINE_LENGTH
+      MAX_LINE_LENGTH = Pikuri::Extractor::PAGE_MAX_LINE_LENGTH
 
       # @return [String] suffix appended to lines truncated by
       #   {MAX_LINE_LENGTH}.
-      LINE_TRUNCATION_MARKER = Pikuri::FileType::PAGE_LINE_TRUNCATION_MARKER
+      LINE_TRUNCATION_MARKER = Pikuri::Extractor::PAGE_LINE_TRUNCATION_MARKER
 
       # @return [Integer] hard byte cap on input content collected per
       #   call. Counted on the line bytes (plus one for the joining
       #   newline); the rendered output is slightly larger due to the
       #   per-line +"%6d\t"+ prefix.
-      MAX_BYTES = Pikuri::FileType::PAGE_MAX_BYTES
+      MAX_BYTES = Pikuri::Extractor::PAGE_MAX_BYTES
 
       # @return [String] human-readable form of {MAX_BYTES} for the
       #   continuation marker.
@@ -221,11 +225,6 @@ module Pikuri
 
         mime = Pikuri::FileType.detect_mime(resolved)
         return format_image(path: path, resolved: resolved, mime: mime) if mime&.start_with?('image/')
-        # PDFs are binary by the heuristic, so the PDF route (handled
-        # inside read_as_text_paged) must win over the binary refusal.
-        if mime != 'application/pdf' && Pikuri::FileType.binary?(resolved)
-          return "Error: cannot read binary file: #{path}"
-        end
 
         page = Pikuri::FileType.read_as_text_paged(
           resolved, offset: offset, limit: limit,
@@ -236,18 +235,24 @@ module Pikuri
         "Error: #{e.message}"
       rescue Errno::EACCES => e
         "Error: cannot read #{path}: #{e.message}"
+      rescue ArgumentError
+        # Nothing in the Extractor registry claimed the content —
+        # read_as_text_paged's binary refusal (directories and images
+        # were already handled above).
+        "Error: cannot read binary file: #{path}"
       rescue RuntimeError => e
-        # Malformed / unsupported PDF surfaced by read_as_text_paged.
+        # Extraction failure (malformed / unsupported PDF, ...)
+        # surfaced by read_as_text_paged.
         "Error: #{e.message}"
       end
 
-      # Render a {Pikuri::FileType::Page} as the cat-n observation: a
+      # Render a {Pikuri::Extractor::Page} as the cat-n observation: a
       # six-column line number, a tab, then the (already-truncated)
       # content, followed by a trailer that tells the model whether to
       # page on. PDF pages carry +"--- Page N ---"+ marker lines from
       # the extractor; the +kind+ only changes trailer wording here.
       #
-      # @param page [Pikuri::FileType::Page]
+      # @param page [Pikuri::Extractor::Page]
       # @return [String]
       def self.render_page(page)
         if page.lines.empty?
@@ -281,7 +286,7 @@ module Pikuri
       # text-free PDF gets an LLM-actionable hint rather than the
       # plain-file "(Empty file)".
       #
-      # @param page [Pikuri::FileType::Page]
+      # @param page [Pikuri::Extractor::Page]
       # @return [String]
       def self.empty_message(page)
         if page.kind == :pdf

data/lib/pikuri/workspace/write.rb

@@ -111,8 +111,10 @@ module Pikuri
                    'file and try again.'
           end
 
-          prompt = "OK to overwrite #{path}: #{existing.bytesize} → #{content.bytesize} bytes? (y/n)"
-          return "Error: user declined the write to #{path}." unless confirmer.confirm?(prompt: prompt)
+          request = Confirmer::Request.new(
+            question: "OK to overwrite #{path}: #{existing.bytesize} → #{content.bytesize} bytes?"
+          )
+          return "Error: user declined the write to #{path}." unless confirmer.confirm?(request: request)
 
           write_bytes(resolved, content)
           "Updated #{path} (#{existing.bytesize} → #{content.bytesize} bytes)"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-workspace
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Martin Vysny
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pikuri-core
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
 description: |
   pikuri-workspace adds "operate on a directory tree" to pikuri-core
   agents: the +Pikuri::Workspace::Filesystem+ class that scopes
@@ -59,7 +58,6 @@ metadata:
   changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
   bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Filesystem tools (Read/Write/Edit/Grep/Glob) + Workspace + Confirmer seams
   for pikuri.