pikuri-workspace 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cd37f2cda8958c1a0098160a71b6a0a3e375cd6f8169c298909950a8c6fdb87
-  data.tar.gz: fb99c3d2b8dcb886f5f5e93bb6562bf2e87b8bad0d44cdf71da2ece883ef3270
+  metadata.gz: 4be40e803f487eb130b8ee758b86efb7a744c92691a1dd103aae68d91e59a2f9
+  data.tar.gz: 981478770e9e7f8acef1fb1ca2b1896cf6a25c7eb73c01c1d57592f81583cf0f
 SHA512:
-  metadata.gz: 4a79642151199e5e4ceeefda2130c270de29015350fa5a128d54d1a692fac9e37949363db2f4222d635d7619e09409140d6bad41c7cc841f1b9f1cde58762fc0
-  data.tar.gz: eb45fe6977711e452f399f58a9e4f0d80450e62008c1af32fc6c0d9fe04d7b3c63b8149c685f296dbed1de3e9f9cd883dea13714e23baa87681abeb28eb02f05
+  metadata.gz: a211df218e4270acbe737f624cc8a77cc145d8a051c3500131036692168996c800a0110a27bd714a7cad3fb5cb9dd3e25fdfdeefb917fb73ccead021cd807c94
+  data.tar.gz: fe2ff7510012d619caa166252ccef80148750e35fa58a68cd1722cec372758dc17e5605cbe380c4f106538b301134402da32e0fb13c6f23d6acec7c4aceb301e

data/README.md

@@ -4,15 +4,17 @@ Filesystem tools + Workspace/Confirmer seams for the
 [pikuri](https://codeberg.org/mvysny/pikuri) AI-assistant toolkit.
 
 Self-contained "operate on a directory tree" toolkit:
-- `Pikuri::Tool::Workspace` — abstract base + bundled
-  `Workspace::Cwd` that scopes filesystem access to a chosen root,
-  rejecting `..`-escapes and symlinks that resolve outside the root.
-- `Pikuri::Tool::Confirmer` — abstract base + `AUTO_APPROVE` /
+- `Pikuri::Workspace::Filesystem` — scopes filesystem access to a
+  project root + explicit readable / writable prefix lists, with an
+  optional ephemeral temp playground. Rejects `..`-escapes and
+  symlinks that resolve outside the configured roots.
+- `Pikuri::Workspace::Confirmer` — abstract base + `AUTO_APPROVE` /
   `TERMINAL` for user-state mutations.
-- Five file tools: `Pikuri::Tool::Read`, `Pikuri::Tool::Write`,
-  `Pikuri::Tool::Edit`, `Pikuri::Tool::Grep`, `Pikuri::Tool::Glob`.
+- Five file tools: `Pikuri::Workspace::Read`,
+  `Pikuri::Workspace::Write`, `Pikuri::Workspace::Edit`,
+  `Pikuri::Workspace::Grep`, `Pikuri::Workspace::Glob`.
 
-No shell execution — `Pikuri::Tool::Bash` ships in
+No shell execution — `Pikuri::Code::Bash` ships in
 [`pikuri-code`](../pikuri-code/README.md) on top of these.
 
 ## Install
@@ -28,23 +30,36 @@ gem 'pikuri-workspace'
 require 'pikuri-core'
 require 'pikuri-workspace'
 
-workspace = Pikuri::Tool::Workspace::Cwd.new(root: Dir.pwd)
-confirmer = Pikuri::Tool::Confirmer::TERMINAL
+workspace = Pikuri::Workspace::Filesystem.new(project_root: Dir.pwd)
+confirmer = Pikuri::Workspace::Confirmer::TERMINAL
 
 agent = Pikuri::Agent.new(
   transport: ...,
   system_prompt: ...,
 ) do |c|
-  c.add_tool Pikuri::Tool::Read.new(workspace: workspace)
-  c.add_tool Pikuri::Tool::Grep.new(workspace: workspace)
-  c.add_tool Pikuri::Tool::Glob.new(workspace: workspace)
-  c.add_tool Pikuri::Tool::Edit.new(workspace: workspace)
-  c.add_tool Pikuri::Tool::Write.new(workspace: workspace, confirmer: confirmer)
+  c.add_tool Pikuri::Workspace::Read.new(workspace: workspace)
+  c.add_tool Pikuri::Workspace::Grep.new(workspace: workspace)
+  c.add_tool Pikuri::Workspace::Glob.new(workspace: workspace)
+  c.add_tool Pikuri::Workspace::Edit.new(workspace: workspace)
+  c.add_tool Pikuri::Workspace::Write.new(workspace: workspace, confirmer: confirmer)
   c.add_listener ...
 end
 ```
 
-`Workspace::Cwd` is the "look-but-don't-leak" guard around filesystem
+`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:)`.
+`#confirm?(prompt:)`. 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.
+
+## Further reading
+
+- **Narrative walkthrough:** the "Workspace seam" and "Confirmer
+  seam" sections of
+  [chapter 8 of the pikuri guide](../docs/guide/08-code.md) — what
+  each kwarg of `Filesystem.new` controls, when to use the
+  `AllowAll` variant, and how the seams fit alongside `Sandbox`.
+- **API reference:** browse the YARD docs at
+  <https://rubydoc.info/gems/pikuri-workspace> (once published),
+  or run `bundle exec yard` in this directory for a local copy.

data/lib/pikuri/{tool → workspace}/confirmer.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Pikuri
-  class Tool
+  module Workspace
     # Port for asking the user to confirm a potentially destructive tool
-    # operation — currently {Tool::Bash} (every command) and
-    # {Tool::Write} (overwrite of an existing file with non-identical
+    # operation — currently {Pikuri::Code::Bash} (every command) and
+    # {Write} (overwrite of an existing file with non-identical
     # content). Subclass and implement {#confirm?}.
     #
     # == Why a Boolean return

data/lib/pikuri/{tool → workspace}/edit.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
 module Pikuri
-  class Tool
+  module Workspace
     # The +edit+ tool — exact-string replacement on an existing file.
-    # Instantiating +Tool::Edit.new(workspace: ws)+ produces a tool whose
-    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's.
-    # Same shape as {Tool::Read} (workspace captured by +execute+; no
+    # Instantiating +Edit.new(workspace: ws)+ produces a tool whose
+    # {Pikuri::Tool#to_ruby_llm_tool} wiring is identical to any bundled
+    # tool's. Same shape as {Read} (workspace captured by +execute+; no
     # confirmer needed).
     #
     # == Why no confirmer
     #
     # The +old_string+ argument is itself an implicit read-check: the
     # model can't write a correct +old_string+ without having seen the
-    # file (via {Tool::Read} or out-of-band), so the blast radius of any
+    # file (via {Read} or out-of-band), so the blast radius of any
     # Edit is bounded by the model's actual knowledge of file state.
     # That makes Edit safe to execute without prompting — by contrast,
-    # {Tool::Write} requires a confirmer because a hallucinated 500-line
+    # {Write} requires a confirmer because a hallucinated 500-line
     # +content+ could clobber unread bytes.
     #
     # == Matching is strict (no fuzz cascade)
@@ -23,7 +23,7 @@ module Pikuri
     # +old_string+ must match the file byte-for-byte. v1 ships *no*
     # fallback replacer (no whitespace-normalized, line-trimmed, block-
     # anchor, etc.). Predictability beats fuzz: when an Edit fails, the
-    # model re-reads with {Tool::Read} and retries — clear failure mode,
+    # model re-reads with {Read} and retries — clear failure mode,
     # no compounding-heuristic risk. opencode runs a 9-replacer cascade
     # under the hood despite its own description saying "must match
     # exactly"; pi stays strict. We match pi.
@@ -32,7 +32,7 @@ module Pikuri
     #
     # The one structural exception to "strict bytes": files with CRLF
     # line endings get matched in LF space, and the original line ending
-    # is restored on write. Reason: {Tool::Read} renders content via
+    # is restored on write. Reason: {Read} renders content via
     # +each_line+ + +chomp+, which strips +\r\n+ to +\n+ in what the
     # model sees. A pure strict byte-match would then never succeed on
     # CRLF files because the model can only ever supply LF. opencode and
@@ -62,7 +62,7 @@ module Pikuri
     #   multi-match error suggesting more context or +replace_all+.
     # * File missing / is a directory / is binary → respective error.
     # * Workspace boundary violation / EACCES → standard rescue path.
-    class Edit < Tool
+    class Edit < Pikuri::Tool
       # Description shown to the LLM. Follows the opencode-shape (summary
       # + +Usage:+ bullets) prescribed by the project's tool-description
       # convention. Per-parameter constraints live in the parameter
@@ -82,7 +82,7 @@ module Pikuri
         - CRLF files are matched in LF space; the original line endings are preserved on write.
       DESC
 
-      # @param workspace [Tool::Workspace] captured for path resolution;
+      # @param workspace [Filesystem] captured for path resolution;
       #   all reads/writes route through +workspace.resolve_for_write+
       #   (Edit modifies, so it uses the write-set even though it doesn't
       #   create files).
@@ -122,7 +122,7 @@ module Pikuri
       # binary), match +old_string+ in line-ending-normalized form, and
       # write the result back preserving the file's original line endings.
       #
-      # @param workspace [Tool::Workspace]
+      # @param workspace [Filesystem]
       # @param path [String] raw path as supplied by the LLM
       # @param old_string [String] text to find
       # @param new_string [String] text to substitute in
@@ -137,9 +137,9 @@ module Pikuri
         return "Error: file not found: #{path}" unless resolved.exist?
         return "Error: #{path} is a directory" if resolved.directory?
 
+        return "Error: cannot edit binary file: #{path}" if Pikuri::FileType.binary?(resolved)
+
         raw = resolved.binread
-        sample = raw.byteslice(0, Tool::Read::BINARY_SAMPLE_BYTES)
-        return "Error: cannot edit binary file: #{path}" if Tool::Read.binary?(sample)
 
         crlf    = raw.include?("\r\n")
         content = crlf ? raw.gsub("\r\n", "\n") : raw
@@ -173,7 +173,7 @@ module Pikuri
         resolved.write(final)
 
         "Edited #{path}: replaced #{replaced} occurrence#{replaced == 1 ? '' : 's'}."
-      rescue Tool::Workspace::Error => e
+      rescue Filesystem::Error => e
         "Error: #{e.message}"
       rescue Errno::EACCES => e
         "Error: cannot edit #{path}: #{e.message}"