textus 0.55.2 → 0.56.0

data/lib/textus/handlers/write/move_key.rb

@@ -1,80 +0,0 @@
-module Textus
-  module Handlers
-    module Write
-      class MoveKey
-        def initialize(container:, manifest:)
-          @container = container
-          @manifest = manifest
-        end
-
-        def call(command, call)
-          Textus::Manifest::Data.validate_key!(command.old_key)
-          Textus::Manifest::Data.validate_key!(command.new_key)
-
-          return Value::Result.failure(:usage_error, "mv: old and new keys are identical") if command.old_key == command.new_key
-
-          old_res = @manifest.resolver.resolve(command.old_key)
-          new_res = @manifest.resolver.resolve(command.new_key)
-
-          reader = Store::Entry::Reader.from(container: @container)
-
-          unless reader.exists?(command.old_key)
-            return Value::Result.failure(:not_found,
-                                         "source key '#{command.old_key}' not found")
-          end
-
-          zone_check = validate_zone(old_res.entry, new_res.entry)
-          return zone_check if zone_check
-
-          if reader.exists?(command.new_key)
-            return Value::Result.failure(:usage_error, "mv: target '#{command.new_key}' already exists at #{new_res.path}")
-          end
-
-          pre_env = reader.read(command.old_key)
-          writer = Store::Entry::Writer.from(container: @container, call: call)
-          unless pre_env.uid
-            writer.put(
-              command.old_key, mentry: old_res.entry,
-                               payload: Textus::Value::Payload.new(meta: pre_env.meta, body: pre_env.body, content: pre_env.content)
-            )
-          end
-
-          if command.dry_run
-            return Value::Result.success({
-                                           "protocol" => Textus::PROTOCOL, "ok" => true, "dry_run" => true,
-                                           "from_key" => command.old_key, "to_key" => command.new_key,
-                                           "from_path" => old_res.path, "to_path" => new_res.path,
-                                           "uid" => pre_env.uid
-                                         })
-          end
-
-          envelope = writer.move(
-            from_key: command.old_key, to_key: command.new_key,
-            new_mentry: new_res.entry
-          )
-
-          Value::Result.success({
-                                  "protocol" => Textus::PROTOCOL, "ok" => true,
-                                  "from_key" => command.old_key, "to_key" => command.new_key,
-                                  "from_path" => old_res.path, "to_path" => new_res.path,
-                                  "uid" => envelope.uid, "envelope" => envelope.to_h_for_wire
-                                })
-        end
-
-        private
-
-        def validate_zone(old_mentry, new_mentry)
-          if old_mentry.lane != new_mentry.lane
-            return Value::Result.failure(:usage_error,
-                                         "mv: cross-zone refused (#{old_mentry.lane} -> #{new_mentry.lane}). Use put+delete.")
-          end
-          if old_mentry.format != new_mentry.format
-            return Value::Result.failure(:usage_error,
-                                         "mv: format mismatch (#{old_mentry.format} -> #{new_mentry.format}); refusing.")
-          end
-          nil
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/write/propose_entry.rb

@@ -1,29 +0,0 @@
-module Textus
-  module Handlers
-    module Write
-      class ProposeEntry
-        def initialize(container:)
-          @container = container
-        end
-
-        def call(command, call)
-          zone = @container.manifest.policy.propose_lane_for(call.role)
-          unless zone
-            return Value::Result.failure(:propose_forbidden,
-                                         "role '#{call.role}' has no writable propose_lane",
-                                         details: { "role" => call.role })
-          end
-
-          key = "#{zone}.#{command.key}"
-          mentry = @container.manifest.resolver.resolve(key).entry
-          writer = Store::Entry::Writer.from(container: @container, call: call)
-          envelope = writer.put(
-            key, mentry: mentry,
-                 payload: Textus::Value::Payload.new(meta: command.meta || {}, body: command.body, content: command.content)
-          )
-          Value::Result.success(envelope)
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/write/put_entry.rb

@@ -1,29 +0,0 @@
-module Textus
-  module Handlers
-    module Write
-      class PutEntry
-        def initialize(container:)
-          @container = container
-        end
-
-        def call(command, call)
-          Textus::Manifest::Data.validate_key!(command.key)
-          mentry = @container.manifest.resolver.resolve(command.key).entry
-
-          writer = Store::Entry::Writer.from(container: @container, call: call)
-          envelope = writer.put(
-            command.key,
-            mentry: mentry,
-            payload: Textus::Value::Payload.new(
-              meta: command.meta,
-              body: command.body,
-              content: command.content,
-            ),
-            if_etag: command.if_etag,
-          )
-          Value::Result.success(envelope)
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/write/reject_proposal.rb

@@ -1,29 +0,0 @@
-module Textus
-  module Handlers
-    module Write
-      class RejectProposal
-        def initialize(container:)
-          @container = container
-        end
-
-        def call(command, call)
-          mentry = @container.manifest.resolver.resolve(command.pending_key).entry
-          unless mentry.in_proposal_lane?(@container.manifest.policy)
-            return Value::Result.failure(:proposal_error,
-                                         "reject: '#{command.pending_key}' is not in a proposal zone (zone=#{mentry.lane})")
-          end
-
-          reader = Store::Entry::Reader.from(container: @container)
-          env = reader.read(command.pending_key)
-          proposal = env&.meta&.dig("proposal") or
-            return Value::Result.failure(:proposal_error, "entry has no proposal block: #{command.pending_key}")
-          target_key = proposal["target_key"]
-
-          writer = Store::Entry::Writer.from(container: @container, call: call)
-          writer.delete(command.pending_key, mentry: mentry)
-          Value::Result.success("protocol" => Textus::PROTOCOL, "rejected" => command.pending_key, "target_key" => target_key)
-        end
-      end
-    end
-  end
-end

data/lib/textus/init.rb

@@ -1,157 +0,0 @@
-require "fileutils"
-require "pathname"
-
-module Textus
-  module Init
-    ZONES = %w[knowledge scratchpad proposals artifacts raw].freeze
-
-    DEFAULT_MANIFEST = <<~YAML
-      version: textus/4
-      roles:
-        - { name: human,      can: [author, propose] }
-        - { name: agent,      can: [propose, keep] }
-        - { name: automation, can: [converge] }
-      lanes:
-        - { name: knowledge, kind: canon,     desc: "the maintained source of truth (identity.* lives here)" }
-        - { name: scratchpad,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
-        - { name: proposals, kind: queue,     desc: "changes awaiting your accept" }
-        - { name: artifacts, kind: machine,   desc: "machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)" }
-      entries:
-        - { key: knowledge.identity, path: data/knowledge/identity.md, lane: knowledge, schema: null, owner: human:self, kind: leaf }
-        - { key: knowledge.notes,    path: data/knowledge/notes,       lane: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
-        - { key: scratchpad.notes,     path: data/scratchpad/notes,        lane: scratchpad,  schema: null, owner: agent:self, nested: true, kind: nested }
-        - { key: proposals.notes,    path: data/proposals/notes,       lane: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
-        # A per-host snapshot, populated by a registered workflow. Nested so it
-        # grows to a fleet — add leaves over SSH without renaming. tracked:false →
-        # gitignored (machine info can be sensitive/noisy) but still protocol-readable
-        # via `textus get artifacts.feeds.machines.local`. Delete to opt out. (ADR 0043)
-        - key: artifacts.feeds.machines
-          path: data/artifacts/feeds/machines
-          lane: artifacts
-          format: yaml
-          nested: true
-          tracked: false
-          kind: nested
-      rules: []
-    YAML
-
-    AGENT_ENTRIES = <<~YAML.gsub(/^/, "  ")
-      - { key: knowledge.project, path: data/knowledge/project.md, lane: knowledge, schema: project, owner: human:self, kind: leaf }
-      - { key: knowledge.runbooks, path: data/knowledge/runbooks, lane: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
-      - key: artifacts.derived.orientation
-        path: data/artifacts/derived/orientation.json
-        lane: artifacts
-        publish:
-        - { to: CLAUDE.md, template: orientation.erb, inject_boot: true }
-        - { to: AGENTS.md, template: orientation.erb, inject_boot: true }
-        kind: produced
-    YAML
-
-    def self.run(target_root, with_agent: false)
-      check_target!(target_root)
-      scaffold_dir = File.expand_path("init/templates", __dir__)
-      create_directories(target_root)
-      write_manifest(target_root, with_agent:)
-      mcp_status = scaffold_agent(target_root, scaffold_dir, with_agent:)
-      setup_state_dirs(target_root)
-      write_gitignore(target_root)
-      build_result(target_root, with_agent:, mcp_status:)
-    end
-
-    def self.check_target!(target_root)
-      raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
-    end
-
-    ASSET_ZONES = %w[raw].freeze
-
-    def self.create_directories(target_root)
-      FileUtils.mkdir_p(File.join(target_root, "schemas"))
-      FileUtils.mkdir_p(File.join(target_root, "templates"))
-      FileUtils.mkdir_p(File.join(target_root, "workflows"))
-      ZONES.each do |z|
-        dir = File.join(target_root, "data", z)
-        FileUtils.mkdir_p(dir)
-        File.write(File.join(dir, ".gitkeep"), "")
-      end
-      ASSET_ZONES.each do |z|
-        dir = File.join(target_root, "assets", z)
-        FileUtils.mkdir_p(dir)
-        File.write(File.join(dir, ".gitkeep"), "")
-      end
-    end
-
-    def self.write_manifest(target_root, with_agent:)
-      File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
-    end
-
-    def self.scaffold_agent(target_root, scaffold_dir, with_agent:)
-      return nil unless with_agent
-
-      scaffold_agent_profile(target_root, scaffold_dir)
-      write_mcp_config(target_root, scaffold_dir)
-    end
-
-    def self.setup_state_dirs(target_root)
-      FileUtils.mkdir_p(Textus::Store::Layout.new(target_root).audit_dir_path)
-    end
-
-    def self.write_gitignore(target_root)
-      File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
-    end
-
-    def self.build_result(target_root, with_agent:, mcp_status:)
-      result = { "protocol" => PROTOCOL, "initialized" => target_root, "profile" => with_agent ? "agent" : "default" }
-      result["mcp_config"] = mcp_status if with_agent
-      result
-    end
-
-    # Composes the agent profile by inserting AGENT_ENTRIES immediately before the
-    # top-level `rules:` block of DEFAULT_MANIFEST — that block is load-bearing for
-    # this `.sub`; removing it from DEFAULT_MANIFEST would silently drop the entries.
-    def self.manifest_yaml(with_agent:)
-      return DEFAULT_MANIFEST unless with_agent
-
-      DEFAULT_MANIFEST.sub(/^rules:/, "#{AGENT_ENTRIES}rules:")
-    end
-
-    # Copies the proven orientation bundle into a freshly-init'd store.
-    def self.scaffold_agent_profile(target_root, scaffold_dir)
-      {
-        "project.schema.yaml" => File.join("schemas", "project.yaml"),
-        "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
-        "orientation.erb" => File.join("templates", "orientation.erb"),
-      }.each do |src, dest|
-        File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
-      end
-    end
-
-    # The one file init writes outside .textus/: a starter .mcp.json at the
-    # project root. Write-once — never clobber a hand-authored config. The
-    # command form assumes a gem-installed `textus` on PATH; the user owns
-    # the file after this first write.
-    def self.write_mcp_config(target_root, scaffold_dir)
-      dest = File.join(File.dirname(target_root), ".mcp.json")
-      return "skipped" if File.exist?(dest)
-
-      File.write(dest, File.read(File.join(scaffold_dir, "mcp.json")))
-      "written"
-    end
-
-    # The store's `.gitignore` is generated, never hand-kept (ADR 0038), and now
-    # derived from the manifest: the run subtree plus every `tracked: false`
-    # entry's resolved path (ADR 0043).
-    def self.derived_gitignore(target_root)
-      manifest = Textus::Manifest.load(target_root)
-      root = Pathname.new(target_root)
-      untracked = manifest.data.entries.reject(&:tracked?).map do |e|
-        if e.nested? # a whole subtree of leaf files (artifacts.feeds.machines.* → data/artifacts/feeds/machines/)
-          rel = e.path.start_with?("data/") ? e.path : File.join("data", e.path)
-          "#{rel}/"
-        else
-          Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
-        end
-      end
-      Textus::Store::Layout.new(target_root).gitignore_body(untracked_entries: untracked)
-    end
-  end
-end

data/lib/textus/jobs.rb

@@ -1,9 +0,0 @@
-module Textus
-  module Jobs
-    def self.fetch(type)
-      Store::Jobs::Registry.fetch(type)
-    rescue Store::Jobs::Registry::UnknownJob
-      raise Textus::UsageError.new("unknown job type: #{type}")
-    end
-  end
-end

data/lib/textus/key/distance.rb

@@ -1,55 +0,0 @@
-module Textus
-  module Key
-    # Small utilities for ranking key suggestions. Bounded inputs only —
-    # Levenshtein is O(n*m) so we refuse to compute on long strings.
-    class Distance
-      MAX_LEN = 200
-
-      # Length of the shared dot-separated prefix between two dotted keys.
-      def self.shared_prefix_segments(left, right)
-        asegs = left.split(".")
-        bsegs = right.split(".")
-        n = [asegs.length, bsegs.length].min
-        i = 0
-        i += 1 while i < n && asegs[i] == bsegs[i]
-        i
-      end
-
-      # Classic iterative Levenshtein with two rows. Bounded to MAX_LEN.
-      def self.levenshtein(left, right)
-        return nil if left.length > MAX_LEN || right.length > MAX_LEN
-        return right.length if left.empty?
-        return left.length if right.empty?
-
-        prev = (0..right.length).to_a
-        curr = Array.new(right.length + 1, 0)
-        (1..left.length).each do |i|
-          curr[0] = i
-          (1..right.length).each do |j|
-            cost = left[i - 1] == right[j - 1] ? 0 : 1
-            curr[j] = [
-              curr[j - 1] + 1,      # insertion
-              prev[j] + 1,          # deletion
-              prev[j - 1] + cost,   # substitution
-            ].min
-          end
-          prev, curr = curr, prev
-        end
-        prev[right.length]
-      end
-
-      # Rank candidate keys against requested. Returns up to `limit` keys.
-      # Sort: longer shared prefix first; then smaller Levenshtein distance.
-      def self.suggest(requested, candidates, limit: 5)
-        return [] if requested.nil? || requested.empty?
-
-        scored = candidates.first(200).map do |k|
-          prefix = shared_prefix_segments(requested, k)
-          dist = levenshtein(requested, k) || Float::INFINITY
-          [k, prefix, dist]
-        end
-        scored.sort_by { |(_, prefix, dist)| [-prefix, dist] }.first(limit).map(&:first)
-      end
-    end
-  end
-end

data/lib/textus/key/grammar.rb

@@ -1,33 +0,0 @@
-module Textus
-  module Key
-    module Grammar
-      SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
-      MAX_SEGMENTS = 8
-      MAX_SEGMENT_LEN = 64
-
-      module_function
-
-      def validate!(key) # rubocop:disable Naming/PredicateMethod
-        raise UsageError.new("key must be a String") unless key.is_a?(String)
-        raise UsageError.new("empty key") if key.empty?
-
-        segs = key.split(".")
-        raise UsageError.new("key '#{key}' has #{segs.length} segments (max #{MAX_SEGMENTS})") if segs.length > MAX_SEGMENTS
-
-        segs.each do |seg|
-          if seg.empty?
-            raise UsageError.new("empty segment in key '#{key}'")
-          elsif seg.length > MAX_SEGMENT_LEN
-            raise UsageError.new("segment '#{seg}' in key '#{key}' exceeds #{MAX_SEGMENT_LEN} chars")
-          elsif !seg.match?(SEGMENT)
-            raise UsageError.new(
-              "invalid key segment '#{seg}' in '#{key}': must match [a-z0-9][a-z0-9-]* " \
-              "(lowercase, digits, hyphens; no underscores or uppercase)",
-            )
-          end
-        end
-        true
-      end
-    end
-  end
-end

data/lib/textus/key/matching.rb

@@ -1,24 +0,0 @@
-module Textus
-  module Key
-    # Dotted-key scope matching, shared by all prefix-scoped sweeps
-    # (WS4 / ADR 0089-era cleanup). Canonicalised here so every consumer
-    # uses a consistent dotted-boundary check with proper Nested ancestor
-    # handling. ADR 0093: Produce is the sole engine calling this.
-    module Matching
-      module_function
-
-      # Is `key` within the `prefix` scope?
-      #   - exact match, or a dotted descendant (the `prefix.` boundary, so
-      #     prefix "art" does NOT match key "artifacts"), and
-      #   - for a nested entry, also when `prefix` descends INTO it — the nested
-      #     parent owns the leaf the prefix names (e.g. prefix
-      #     "feeds.machines.host1" still selects the nested entry
-      #     "feeds.machines").
-      def matches_prefix?(key, prefix, nested: false)
-        return true if key == prefix || key.start_with?("#{prefix}.")
-
-        nested && prefix.start_with?("#{key}.")
-      end
-    end
-  end
-end

data/lib/textus/key/path.rb

@@ -1,28 +0,0 @@
-module Textus
-  module Key
-    module Path
-      # Returns the absolute filesystem path for a manifest entry (the leaf file,
-      # not a nested directory). Adds the format's primary extension when the
-      # manifest entry's `path:` is extensionless.
-      #
-      # The first argument is a Manifest::Data (or anything responding to .root);
-      # callers historically passed the whole Manifest but should now pass
-      # `manifest.data`.
-      def self.resolve(data, mentry)
-        primary_ext = Format.for(mentry.format).extensions.first
-        rel_path = normalize_relative_path(mentry.path)
-        if File.extname(mentry.path) == ""
-          File.join(data.root, rel_path + primary_ext)
-        else
-          File.join(data.root, rel_path)
-        end
-      end
-
-      def self.normalize_relative_path(path)
-        return path if path.start_with?("data/")
-
-        File.join("data", path)
-      end
-    end
-  end
-end

data/lib/textus/manifest/capabilities.rb

@@ -1,29 +0,0 @@
-module Textus
-  class Manifest
-    # Resolves a manifest's `roles:` block (or the absence of one) into a
-    # capability map: { role_name => [verbs] }. Verbs are a subset of the
-    # closed capability set (Schema::CAPABILITIES). See ADR 0030.
-    module Capabilities
-      # Fallback role set for a manifest that omits `roles:` entirely. Agent
-      # is intentionally minimal here (`propose` only) — narrower than the
-      # `textus init` scaffold, which declares `agent: [propose, keep]` so the
-      # default `scratchpad` workspace is writable. A roles-less manifest that
-      # declares a `kind: workspace` zone is therefore rejected at load (no
-      # `keep`-holder); declare `roles:` to opt into a workspace lane (ADR 0033).
-      DEFAULT_MAPPING = {
-        Textus::Value::Role::HUMAN => %w[author propose].freeze,
-        Textus::Value::Role::AGENT => %w[propose].freeze,
-        Textus::Value::Role::AUTOMATION => %w[converge].freeze,
-      }.freeze
-
-      # Returns { role_name => [verbs] }. When `roles:` is declared we use
-      # exactly that; defaults are *not* layered in (declaring roles is an
-      # opt-in to a fully user-defined vocabulary).
-      def self.resolve(raw_roles)
-        return DEFAULT_MAPPING if raw_roles.nil?
-
-        raw_roles.to_h { |r| [r["name"], Array(r["can"]).freeze] }.freeze
-      end
-    end
-  end
-end

data/lib/textus/manifest/data.rb

@@ -1,102 +0,0 @@
-require_relative "schema"
-require_relative "capabilities"
-
-module Textus
-  class Manifest
-    # Immutable, parsed view of a manifest YAML document.
-    #
-    # Holds raw structural data (lanes, entries, audit_config, role_caps)
-    # but no behaviour beyond accessors. Behaviour (lane authority, key
-    # resolution, rules) lives on Manifest::Policy / Resolver / Rules.
-    class Data
-      AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
-      WORKER_DEFAULTS = { pool: 4, poll: 5, lease_ttl: 60, max_attempts: 3 }.freeze
-
-      attr_reader :raw, :root, :entries, :declared_lane_kinds,
-                  :lane_descs, :lane_owners,
-                  :audit_config, :worker_config, :role_caps, :policy
-
-      def self.validate_key!(key)
-        raise UsageError.new("empty key") if key.nil? || key.empty?
-
-        Key::Grammar.validate!(key)
-      end
-
-      # Forwarder used by Resolver and Entry classes that received a Data
-      # but were written against the historical Manifest API.
-      def validate_key!(key) = self.class.validate_key!(key)
-
-      def self.parse(raw, root:)
-        raise BadFrontmatter.new(File.join(root.to_s, "manifest.yaml"), "manifest must declare lanes:") if Array(raw["lanes"]).empty?
-
-        Schema.validate!(raw)
-        new(raw: raw, root: root)
-      end
-
-      def initialize(raw:, root:)
-        @raw = raw
-        @root = root
-        # Write authority is derived from capabilities × lane-kind (ADR 0030),
-        # not a per-lane writer list. "Which lanes are declared" lives in the
-        # one kind-keyed map below (declared_lane_kinds); membership checks by
-        # read-side callers (boot, maintenance/data_mv) use its keyset (ADR 0034).
-        @declared_lane_kinds = Array(raw["lanes"]).to_h do |z|
-          [z["name"], z["kind"]&.to_sym]
-        end
-        @lane_descs  = Array(raw["lanes"]).to_h { |z| [z["name"], z["desc"]] }
-        # Only lanes that actually declare an owner — keep nil-tombstones out so a
-        # future `lane_owners.key?(name)` means "owner declared", not "lane exists".
-        @lane_owners = Array(raw["lanes"]).to_h { |z| [z["name"], z["owner"]] }.compact
-        @audit_config = build_audit_config(raw)
-        @worker_config = build_worker_config(raw)
-        @role_caps = Capabilities.resolve(raw["roles"])
-        # Policy is constructed before entries because Entry validators
-        # use the entry's own `derived?` and similar helpers that call into
-        # Policy; Policy must exist before entries are built.
-        @policy = Policy.new(self)
-        @entries = build_entries(raw)
-        validate_declared_keys!
-        freeze
-      end
-
-      private
-
-      def build_audit_config(raw)
-        a = raw["audit"] || {}
-        {
-          max_size: a["max_size"] || AUDIT_DEFAULTS[:max_size],
-          keep: a["keep"] || AUDIT_DEFAULTS[:keep],
-        }.freeze
-      end
-
-      # Worker/queue tunables (ADR: job-queue execution model). All optional;
-      # the daemon (serve) and batch drain read these, falling back to defaults
-      # so a manifest with no `worker:` block runs the queue out of the box.
-      def build_worker_config(raw)
-        w = raw["worker"] || {}
-        {
-          pool: w["pool"] || WORKER_DEFAULTS[:pool],
-          poll: w["poll"] || WORKER_DEFAULTS[:poll],
-          lease_ttl: w["lease_ttl"] || WORKER_DEFAULTS[:lease_ttl],
-          max_attempts: w["max_attempts"] || WORKER_DEFAULTS[:max_attempts],
-        }.freeze
-      end
-
-      def build_entries(raw)
-        Array(raw["entries"]).map do |e|
-          entry = Manifest::Entry::Parser.call(e)
-          Manifest::Entry::Validators.run_all(entry, policy: @policy)
-          entry
-        end.freeze
-      end
-
-      def validate_declared_keys!
-        @entries.each do |e|
-          raise UsageError.new("empty key") if e.key.nil? || e.key.empty?
-
-          Key::Grammar.validate!(e.key)
-        end
-      end
-    end
-  end
-end