pikuri-workspace 0.0.3

data/lib/pikuri/tool/workspace.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Pikuri
+  class Tool
+    # Defines which paths the agent can see and write to. Subclass and
+    # implement {#cwd}, {#resolve_for_read}, and {#resolve_for_write}.
+    # Returned Pathnames are absolute, post-symlink-resolution.
+    #
+    # == Read-set vs. write-set
+    #
+    # The two resolve methods exist because a future workspace may admit
+    # paths for reading that it refuses for writing — e.g. a multi-root
+    # workspace where +~/.claude/skills+ is readable but only the project
+    # CWD is writable. For v1's {Cwd} the two methods are the same: read-
+    # set and write-set are both the CWD subtree.
+    #
+    # == Existence is not the workspace's concern
+    #
+    # +resolve_for_read('foo.rb')+ succeeds (returns a +Pathname+) even if
+    # +foo.rb+ doesn't exist; the caller ({Tool::Read}) errors with
+    # file-not-found when it tries to open it. +resolve_for_write+
+    # tolerates entirely non-existent paths (Write can create
+    # +lib/new/dir/foo.rb+ even when +lib/new/+ doesn't exist) — the
+    # caller is responsible for any +mkdir_p+ before writing. This split
+    # keeps the workspace narrowly responsible for *containment*, not for
+    # filesystem-state checks.
+    #
+    # == Future extensions (out of scope for v1)
+    #
+    # * Multi-root workspace: +~/.claude/skills+ readable, CWD writable.
+    # * +Tool::Workspace::ALLOW_ALL+: no restriction, planned for Docker /
+    #   dev-container mode.
+    class Workspace
+      # Raised for any path that resolves outside the workspace. Recoverable
+      # at the tool layer — tools rescue this and emit +"Error: ..."+
+      # observations so the LLM can self-correct on the next turn.
+      class Error < StandardError; end
+
+      # Project anchor: where shells run, where modifications are made.
+      # For {Cwd} this is the constructor's +root:+ (after +realpath+);
+      # a future +ALLOW_ALL+ would return the user's invocation
+      # directory.
+      #
+      # @return [Pathname]
+      # @raise [NotImplementedError] in the abstract base
+      def cwd
+        raise NotImplementedError, "#{self.class}#cwd must be implemented"
+      end
+
+      # Resolve a user-supplied path against the workspace's read-set.
+      # Returned Pathname is absolute and may not exist on disk; the
+      # caller validates existence separately.
+      #
+      # @param path [String] user-supplied path, absolute or relative
+      # @return [Pathname]
+      # @raise [Error] if the resolved path falls outside the read-set
+      # @raise [NotImplementedError] in the abstract base
+      def resolve_for_read(path)
+        raise NotImplementedError, "#{self.class}#resolve_for_read must be implemented"
+      end
+
+      # Resolve a user-supplied path against the workspace's write-set.
+      # Same shape as {#resolve_for_read}; semantically distinct so a
+      # future workspace can permit reading paths it refuses to write.
+      #
+      # @param path [String]
+      # @return [Pathname]
+      # @raise [Error] if the resolved path falls outside the write-set
+      # @raise [NotImplementedError] in the abstract base
+      def resolve_for_write(path)
+        raise NotImplementedError, "#{self.class}#resolve_for_write must be implemented"
+      end
+
+      # Locks read+write to a single subtree (the +root:+ passed at
+      # construction, with symlinks resolved). +cwd+ equals the root.
+      #
+      # == Containment algorithm
+      #
+      # +#resolve+ walks up the input path to its deepest existing
+      # ancestor, +realpath+'s that ancestor (resolving any symlinks in
+      # the existing portion), then verifies the resolved anchor is
+      # +@root+ or a descendant. Four cases the algorithm must handle:
+      #
+      # 1. +lib/foo.rb+ (exists) → +existing+ = full path, +anchor+ in
+      #    root → returns the realpath'd file.
+      # 2. +lib/new/dir/foo.rb+ (intermediates missing) → walks up to
+      #    +@root/lib+, +anchor+ in root → returns the intended new path
+      #    (caller +mkdir_p+s the parent before writing).
+      # 3. +lib/../../etc/passwd+ (+..+ escape) → +cleanpath+ collapses
+      #    +..+ syntactically, walks land outside +@root+ → +Error+.
+      # 4. +link/foo.rb+ where +link → /etc+ (symlink escape) → walks to
+      #    +link+ (which exists), +realpath+ resolves through the
+      #    symlink to +/etc+, outside +@root+ → +Error+.
+      #
+      # Pure lexical normalization (+cleanpath+ + prefix check) catches
+      # cases 1–3 but misses case 4. The walk-up step adds the
+      # +realpath+ pass on the existing prefix, closing that gap.
+      class Cwd < Workspace
+        # @param root [String, Pathname] absolute (or working-directory-
+        #   relative) path to anchor the workspace at. +realpath+'d once
+        #   so subsequent comparisons happen in canonical form.
+        # @raise [Errno::ENOENT] if +root+ does not exist; surfaces
+        #   immediately so misconfigured callers fail loudly.
+        def initialize(root:)
+          @root = Pathname.new(root).realpath
+        end
+
+        # @return [Pathname]
+        def cwd
+          @root
+        end
+
+        # @param path [String]
+        # @return [Pathname]
+        # @raise [Error]
+        def resolve_for_read(path)
+          resolve(path)
+        end
+
+        # @param path [String]
+        # @return [Pathname]
+        # @raise [Error]
+        def resolve_for_write(path)
+          resolve(path)
+        end
+
+        private
+
+        # See class header for the algorithm rationale.
+        def resolve(path)
+          pn = Pathname.new(path)
+          pn = @root + pn unless pn.absolute?
+          cleaned = pn.cleanpath
+
+          existing = cleaned
+          existing = existing.parent until existing.exist? || existing.parent == existing
+          anchor = existing.realpath
+
+          unless anchor == @root || anchor.to_s.start_with?(@root.to_s + File::SEPARATOR)
+            raise Error, "path '#{path}' is outside the workspace '#{@root}'"
+          end
+
+          anchor + cleaned.relative_path_from(existing)
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/tool/write.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Pikuri
+  class Tool
+    # The +write+ tool, expressed as a {Tool} subclass: instantiating
+    # +Tool::Write.new(workspace: ws, confirmer: c)+ produces a tool whose
+    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's,
+    # so ruby_llm sees nothing special about it. Same shape as
+    # {Tool::SubAgent} and {Tool::Read} — workspace and confirmer are
+    # captured by the +execute+ closure at construction.
+    #
+    # == Policy
+    #
+    # Three branches based on the on-disk state of +path+:
+    #
+    # 1. *New file* — write, no prompt.
+    # 2. *Existing file, identical content* — return an +"Error: ..."+
+    #    no-op observation *before* invoking the confirmer; don't ask the
+    #    user to approve a write that wouldn't change the file. Comparison
+    #    is byte-strict, in BINARY encoding (trailing-newline-only
+    #    differences trigger the confirm path; encoding tags can't make
+    #    equal bytes compare unequal).
+    # 3. *Existing file, content differs* — confirm with
+    #    +"OK to overwrite <path>: <old> → <new> bytes?"+ via {Confirmer};
+    #    on yes, write. On no, return a decline-Error observation.
+    #
+    # == Why ask-on-overwrite (Edit doesn't)
+    #
+    # Edit's +old_string+ argument is an implicit read-check: the model
+    # can't write a correct +old_string+ without having read the file, so
+    # blast radius is bounded by what the model actually knows about file
+    # state. Write has no such check, so a hallucinated 500-line +content+
+    # could clobber unread work. The confirmation prompt guards exactly
+    # the gap Edit's argument shape already covers.
+    #
+    # == Side effects
+    #
+    # Parent directories are created (+FileUtils.mkdir_p+) before the
+    # write — matches the +git add lib/new/dir/foo.rb+ mental model and
+    # mirrors opencode's and pi's behavior. Edge case: +mkdir_p+ succeeds
+    # but the write fails; an empty directory is left behind. Accepted
+    # for v1 — users have version control.
+    #
+    # No atomic temp-file+rename. Plain +File.write+, same as opencode and
+    # pi. The crash-safety story is "the user has git".
+    class Write < 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
+      # descriptions; the +Usage:+ bullets are for "when do I pick this?
+      # how does it chain with other tools?".
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Write a file to the workspace, creating parent directories as needed.
+
+        Usage:
+        - Use for new files or full-file rewrites; for partial changes use `edit` instead.
+        - Overwriting an existing file requires user confirmation; identical content is rejected as a no-op error — if you see that error, re-read the file rather than trying again.
+        - Parent directories are created automatically (mkdir -p).
+        - Writes the exact bytes supplied: no trailing-newline normalization, no encoding conversion.
+        - Paths outside the workspace are refused.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for path resolution;
+      #   all writes route through +workspace.resolve_for_write+.
+      # @param confirmer [Tool::Confirmer] consulted before any overwrite
+      #   of an existing file with non-identical content.
+      # @return [Write]
+      def initialize(workspace:, confirmer:)
+        super(
+          name: 'write',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :path,
+                              'Path to the file to write. Relative paths ' \
+                              'resolve against the workspace root, e.g. ' \
+                              '"lib/foo.rb".'
+            p.required_string :content,
+                              'Full contents to write to the file, e.g. ' \
+                              '"class Foo\nend\n".'
+          },
+          execute: ->(path:, content:) {
+            Write.write(workspace: workspace, confirmer: confirmer, path: path, content: content)
+          }
+        )
+      end
+
+      # Resolve +path+ against +workspace+, apply the three-branch policy
+      # (new / identical / differs), and return either a success
+      # observation or an +"Error: ..."+ observation.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param confirmer [Tool::Confirmer]
+      # @param path [String] raw path as supplied by the LLM
+      # @param content [String] bytes to write
+      # @return [String] tool observation
+      def self.write(workspace:, confirmer:, path:, content:)
+        resolved = workspace.resolve_for_write(path)
+
+        if resolved.exist?
+          return "Error: #{path} is a directory" if resolved.directory?
+
+          existing = read_for_compare(resolved, path)
+
+          if existing == content.b
+            return "Error: #{path} already contains exactly this content — " \
+                   'no write needed. If you intended a change, re-read the ' \
+                   '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)
+
+          write_bytes(resolved, content)
+          "Updated #{path} (#{existing.bytesize} → #{content.bytesize} bytes)"
+        else
+          write_bytes(resolved, content)
+          "Created #{path} (#{content.bytesize} bytes)"
+        end
+      rescue Tool::Workspace::Error, Error => e
+        "Error: #{e.message}"
+      rescue Errno::EACCES => e
+        "Error: cannot write #{path}: #{e.message}"
+      end
+
+      # Internal-only signal for LLM-actionable preconditions that Write
+      # detects before any filesystem mutation — today, "existing file is
+      # unreadable so the identical-content check can't run". Mirrors
+      # {Tool::Workspace::Error} in shape: caught by {.write}'s outer
+      # rescue and rendered as a +"Error: ..."+ observation. The class
+      # is +private_constant+ to keep it from leaking out as a public
+      # exception type; callers should never +rescue+ this directly.
+      class Error < StandardError; end
+      private_constant :Error
+
+      # Read the existing file in BINARY mode so the equality check is
+      # purely byte-wise. Raises {Error} on +Errno::EACCES+ so {.write}'s
+      # outer rescue can render a specific "cannot read for overwrite
+      # check" message — without this conversion the bottom +Errno::EACCES+
+      # rescue would mislabel the read-side problem as "cannot write".
+      #
+      # @param resolved [Pathname]
+      # @param path [String] original path for the error message
+      # @return [String]
+      # @raise [Error] when the file exists but isn't readable
+      def self.read_for_compare(resolved, path)
+        resolved.binread
+      rescue Errno::EACCES => e
+        raise Error, "cannot read #{path} for overwrite check: #{e.message}"
+      end
+      private_class_method :read_for_compare
+
+      # +mkdir_p+ the parent, then write. Split out so both the create-
+      # and overwrite-branches can reuse it without duplicating the
+      # +mkdir_p+ call.
+      #
+      # @param resolved [Pathname]
+      # @param content [String]
+      # @return [void]
+      def self.write_bytes(resolved, content)
+        FileUtils.mkdir_p(resolved.dirname)
+        resolved.write(content)
+      end
+      private_class_method :write_bytes
+    end
+  end
+end

data/lib/pikuri-workspace.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'pikuri-core'
+
+# Entry file for the pikuri-workspace gem. After
+# +require 'pikuri-workspace'+, +Pikuri::Tool::Workspace+,
+# +Pikuri::Tool::Confirmer+, and the five file tools (+Read+,
+# +Write+, +Edit+, +Grep+, +Glob+) are all defined.
+#
+# The Zeitwerk loader is mounted under +Pikuri::Tool+ (rather than
+# rooted at this gem's +lib/+) because +Pikuri::Tool+ is a class
+# owned by pikuri-core; without the explicit +namespace:+ argument,
+# Zeitwerk would try to redefine +Pikuri::Tool+ as a module from the
+# implicit-namespace inference, which would conflict. Mounting at
+# the existing class side-steps the conflict and lets our nested
+# files (+lib/pikuri/tool/workspace.rb+ → +Pikuri::Tool::Workspace+,
+# etc.) autoload naturally.
+module Pikuri
+  class Tool
+    LOADER = Zeitwerk::Loader.new
+    LOADER.tag = 'pikuri-workspace'
+    LOADER.push_dir(File.expand_path('pikuri/tool', __dir__), namespace: Pikuri::Tool)
+    LOADER.ignore(File.expand_path('pikuri-workspace.rb', __dir__))
+    LOADER.setup
+    LOADER.eager_load
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: pikuri-workspace
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Martin Vysny
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pikuri-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.3
+description: |
+  pikuri-workspace adds "operate on a directory tree" to pikuri-core
+  agents: the +Pikuri::Tool::Workspace+ seam (abstract base +
+  +Workspace::Cwd+) that scopes filesystem access to a chosen root,
+  the +Pikuri::Tool::Confirmer+ seam (+AUTO_APPROVE+ + +TERMINAL+)
+  for user-state mutations, and five tools wired to those seams:
+  +Pikuri::Tool::Read+, +Pikuri::Tool::Write+, +Pikuri::Tool::Edit+,
+  +Pikuri::Tool::Grep+, and +Pikuri::Tool::Glob+. Self-contained —
+  no shell execution; +Pikuri::Tool::Bash+ ships in pikuri-code on
+  top of these.
+email:
+- martin@vysny.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/pikuri-workspace.rb
+- lib/pikuri/tool/confirmer.rb
+- lib/pikuri/tool/edit.rb
+- lib/pikuri/tool/glob.rb
+- lib/pikuri/tool/grep.rb
+- lib/pikuri/tool/read.rb
+- lib/pikuri/tool/workspace.rb
+- lib/pikuri/tool/write.rb
+homepage: https://codeberg.org/mvysny/pikuri
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://codeberg.org/mvysny/pikuri/src/branch/master
+  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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Filesystem tools (Read/Write/Edit/Grep/Glob) + Workspace + Confirmer seams
+  for pikuri.
+test_files: []