textus 0.55.1 → 0.56.0

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 `notebook` 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

data/lib/textus/manifest/entry/base.rb

@@ -1,105 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      class Base < Entry
-        attr_reader :raw, :key, :path, :lane, :schema, :owner, :format, :publish_targets
-
-        # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
-        def initialize(raw:, key:, path:, lane:, schema:, owner:, format:, publish_targets: [])
-          @raw = raw
-          @key = key
-          @path = path
-          @lane = lane
-          @schema = schema
-          @owner = owner
-          @format = format
-          @publish_targets = Array(publish_targets)
-        end
-        # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
-
-        def lane_writers(policy)
-          verb = policy.verb_for_lane(@lane)
-          policy.roles_with_capability(verb)
-        rescue UsageError => e
-          raise UsageError.new("entry '#{@key}': #{e.message}")
-        end
-
-        def in_proposal_lane?(policy) = policy.queue_lane?(@lane)
-
-        def nested?  = false
-        def derived? = false
-        def intake?  = false
-        def leaf?    = false
-
-        # Production traits. Default false on Base (a leaf/intake entry is neither
-        # an out-of-band command nor a projection); Produced overrides both from
-        # its source. Lets publish modes call these without a `respond_to?` guard.
-        def external?   = false
-        def projection? = false
-
-        alias zone lane
-        alias in_proposal_zone? in_proposal_lane?
-
-        # Whether git should track this entry's file. Default true; an entry
-        # marked `tracked: false` in the manifest stays protocol-readable but is
-        # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
-        # reads from raw here rather than threading through every constructor.
-        def tracked? = @raw["tracked"] != false
-
-        # Single source of truth is @publish_targets (ADR 0094). These
-        # derive the ADR-0049/0052 views the publish modes consume.
-        def publish_to   = @publish_targets.select(&:to_target?).map(&:to)
-        def publish_tree = @publish_targets.find(&:tree_target?)&.tree
-
-        # Nil stubs for cross-cutting optional attrs. Subclasses override the
-        # ones they own. Validators and serializers can call these directly
-        # without `respond_to?` guards.
-        def events         = {}
-        def ignore         = []
-
-        # Per-entry ignore (ADR 0042). Base entries enumerate no tree, so
-        # nothing is ever ignored; Nested overrides with real patterns.
-        def ignored?(_rel_path) = false
-
-        # Minimal context object passed into entry `publish_via` hooks.
-        # Everything beyond the three primitives is derived.
-        PublishContext = ::Data.define(:container, :call, :reader) do
-          def manifest   = container.manifest
-          def root       = container.root
-          def repo_root  = File.dirname(container.root)
-
-          # No-op: event bus removed in workflow redesign; callers that fire
-          # :entry_published / :entry_produced remain unchanged in the source.
-          def emit(_event, **_payload) = nil
-
-          # Read a named template from the store's templates/ directory.
-          # Raises TemplateError when the file doesn't exist.
-          def read_template(name)
-            path = container.geometry.template_path(name)
-            unless File.exist?(path)
-              raise Textus::TemplateError.new(
-                "template '#{name}' not found",
-                template_name: name,
-              )
-            end
-            File.read(path)
-          end
-        end
-
-        # ADR 0049: an entry resolves, once, to one Publish::* mode that owns its
-        # publish algorithm. A plain entry publishes via ToPaths (publish_to) or
-        # None; Nested resolves among the key/path-driven modes. Derived
-        # overrides publish_via to materialize first.
-        def publish_mode
-          @publish_mode ||= Publish.resolve(self)
-        end
-
-        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
-        # Write::Build, or nil to skip.
-        def publish_via(pctx, prefix: nil)
-          publish_mode.publish(pctx, prefix: prefix)
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/ignore_matcher.rb

@@ -1,46 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      # Pure glob matcher backing per-entry `ignore:` patterns (ADR 0042).
-      # `rel_path` is the slash-joined path of a candidate file relative to the
-      # entry's base directory.
-      #
-      # Matching is segment-wise so the `**` globstar means "zero or more path
-      # segments" — `File.fnmatch` alone cannot express this (under
-      # FNM_PATHNAME a trailing `**` will not cross a `/`; without it a leading
-      # `**/` will not match zero leading segments). So `**/node_modules/**`
-      # catches the `node_modules` subtree at any depth, including the store
-      # root, and the directory entry itself.
-      #
-      # Within a single segment, matching delegates to `File.fnmatch` with
-      # FNM_EXTGLOB, so a single `*` is anchored to that segment (it does not
-      # cross `/`) and `{a,b}` alternation works.
-      module IgnoreMatcher
-        SEGMENT_FLAGS = File::FNM_EXTGLOB
-
-        def self.match?(patterns, rel_path)
-          path_segs = rel_path.split("/").reject(&:empty?)
-          Array(patterns).any? do |pat|
-            match_segments(pat.split("/").reject(&:empty?), path_segs)
-          end
-        end
-
-        # Classic globstar matcher. `**` matches zero or more whole segments;
-        # any other pattern segment matches exactly one path segment via fnmatch.
-        def self.match_segments(pat_segs, path_segs)
-          return path_segs.empty? if pat_segs.empty?
-
-          if pat_segs.first == "**"
-            match_segments(pat_segs[1..], path_segs) ||
-              (!path_segs.empty? && match_segments(pat_segs, path_segs[1..]))
-          else
-            !path_segs.empty? &&
-              File.fnmatch?(pat_segs.first, path_segs.first, SEGMENT_FLAGS) &&
-              match_segments(pat_segs[1..], path_segs[1..])
-          end
-        end
-        private_class_method :match_segments
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/leaf.rb

@@ -1,17 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      class Leaf < Base
-        KIND = :leaf
-
-        def leaf? = true
-
-        def self.from_raw(common, _raw)
-          new(**common)
-        end
-
-        Entry::REGISTRY[KIND] = self
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/nested.rb

@@ -1,37 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      # A directory entry: enumerates a tree of leaves and resolves to one
-      # publish mode (ADR 0049). The publish algorithms themselves live in
-      # Entry::Publish::* — Nested is just the value (attributes + ignore
-      # predicate) those modes read.
-      class Nested < Base
-        attr_reader :ignore
-
-        def initialize(ignore: nil, **rest)
-          super(**rest)
-          @ignore = Array(ignore)
-        end
-
-        def nested? = true
-
-        # True when `rel_path` (slash-joined, relative to the entry base) matches
-        # any configured ignore glob. Evaluated ABOVE key-legality (ADR 0042):
-        # an ignored path is excluded, never judged.
-        def ignored?(rel_path) = IgnoreMatcher.match?(@ignore, rel_path)
-
-        KIND = :nested
-
-        def self.from_raw(common, raw)
-          # publish_tree is derived from publish_targets (ADR 0094) via Base#publish_tree
-          new(
-            ignore: raw["ignore"],
-            **common,
-          )
-        end
-
-        Entry::REGISTRY[KIND] = self
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/parser.rb

@@ -1,99 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Parser
-        def self.call(raw)
-          key = raw["key"] or raise UsageError.new("manifest entry missing key")
-          lane = raw["lane"] or raise UsageError.new("manifest entry '#{key}' missing lane")
-
-          raw_kind = raw["kind"] or raise BadManifest.new("entry '#{key}' missing required `kind:` (#{Entry::REGISTRY.keys.join("|")})")
-          kind = raw_kind.to_sym
-          if %i[derived intake].include?(kind)
-            raise BadManifest.new(
-              "entry '#{key}': kind: #{kind} was collapsed into `kind: produced` (ADR 0095) — " \
-              "the produce method is `source.from` (#{kind == :intake ? "handler" : "project|command"})",
-            )
-          end
-
-          explicit_path = raw["path"]
-          format = resolve_format(raw, explicit_path)
-          path   = explicit_path || derive_path(key, kind, format)
-
-          common = {
-            raw: raw,
-            key: key, path: path, lane: lane,
-            schema: raw["schema"], owner: raw["owner"],
-            format: format,
-            publish_targets: publish_targets(raw)
-          }
-
-          klass = Entry::REGISTRY[kind] or
-            raise BadManifest.new("entry '#{key}': unknown kind: #{kind.inspect} (known: #{Entry::REGISTRY.keys.join(", ")})")
-          klass.from_raw(common, raw)
-        end
-
-        # Parse the optional `source:` block. Returns nil when absent (workflow
-        # produced entries register their produce logic in .textus/workflows/).
-        def self.parse_source(raw, _key)
-          block = raw["source"]
-          return nil if block.nil?
-
-          Textus::Manifest::Policy::Source.new(block)
-        end
-
-        # ADR 0094: `publish:` is a LIST of target objects — to-targets
-        # [{to, template?, inject_boot?}] and/or a tree-target [{tree}]. The
-        # ADR-0052 map forms ({to: […]} / {tree: …}) are retired.
-        def self.publish_targets(raw)
-          block = raw["publish"]
-          return [] if block.nil?
-
-          unless block.is_a?(Array)
-            raise BadManifest.new(
-              "entry '#{raw["key"]}': `publish:` must be a list of targets " \
-              "[{to:, template:?} | {tree:}] (ADR 0094); the `publish: { … }` map form was retired",
-            )
-          end
-          block.map { |t| Textus::Manifest::Policy::PublishTarget.new(t) }
-        end
-
-        def self.resolve_format(raw, path)
-          declared = raw["format"]
-
-          return declared || "markdown" if path.nil? || path.empty?
-
-          ext      = File.extname(path)
-          inferred = Textus::Format.infer_from_extension(ext)
-
-          if declared.nil?
-            return inferred if inferred
-
-            return "markdown"
-          end
-
-          raise UsageError.new("entry '#{raw["key"]}': unknown format #{declared.inspect}") unless Textus::Format.formats.include?(declared)
-
-          if ext != "" && inferred && inferred != declared
-            raise UsageError.new(
-              "entry '#{raw["key"]}': path extension #{ext.inspect} does not match declared format #{declared.inspect}",
-            )
-          end
-
-          declared
-        end
-
-        # Derives the manifest-relative path from key + kind + format.
-        # Key::Path.normalize_relative_path will prepend data/ at resolution time.
-        def self.derive_path(key, kind_sym, format)
-          dir_path = key.split(".").join("/")
-          return dir_path if kind_sym == :nested
-
-          ext = Textus::Format.for(format).extensions.first
-          "#{dir_path}#{ext}"
-        end
-
-        private_class_method :derive_path
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/produced.rb

@@ -1,36 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      # A produced entry — `kind: produced` with an optional `source:` block.
-      # When `source:` is present it must be `from: external` (out-of-band
-      # generator; textus detects drift but never runs it). When absent the
-      # entry is produced by a workflow file in .textus/workflows/.
-      class Produced < Base
-        attr_reader :source
-
-        def initialize(source:, **rest)
-          super(**rest)
-          @source = source
-        end
-
-        def external? = @source&.external? || false
-        def nested?   = !!@raw["nested"]
-
-        KIND = :produced
-
-        # Publish existing store bytes via the shared publish mode (Publish::ToPaths
-        # or Publish::None). Workflow runners handle the produce step; this method
-        # only publishes whatever bytes are already on disk.
-        def publish_via(pctx, prefix: nil)
-          publish_mode.publish(pctx, prefix: prefix)
-        end
-
-        def self.from_raw(common, raw)
-          new(source: Parser.parse_source(raw, common[:key]), **common)
-        end
-
-        Entry::REGISTRY[KIND] = self
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/publish/mode.rb

@@ -1,45 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Publish
-        # Base for every publish mode: wraps the resolved entry and owns the one
-        # repo-root escape guard the writing modes share (ADR 0049). Subclasses
-        # implement `#publish(pctx, prefix:)` returning the existing
-        # `{ kind:, value:, pruned: }` shape (or nil), and `#validate!` for the
-        # per-mode shape rules reached *because* this mode resolved.
-        class Mode
-          def initialize(entry)
-            @entry = entry
-          end
-
-          attr_reader :entry
-
-          # No shape rules by default — ToPaths/None publish without templating.
-          def validate!; end
-
-          # Whether this entry's subtree files are opaque payload that must
-          # never be enumerated as keys. Only Tree (publish_tree, ADR 0047)
-          # overrides to true; doctor's IllegalKeys and the resolver consult
-          # this so they stop key-walking a keyless mirror's files.
-          def keyless? = false
-
-          private
-
-          # Expand `rel` under repo_root and confirm it stays inside it.
-          def repo_abs(pctx, rel)
-            File.expand_path(File.join(pctx.repo_root, rel))
-          end
-
-          def inside_repo?(pctx, abs)
-            abs.start_with?(File.expand_path(pctx.repo_root) + File::SEPARATOR)
-          end
-
-          # Store-side directory this entry's tree lives under.
-          def store_base(pctx)
-            File.join(pctx.root, Textus::Key::Path.normalize_relative_path(entry.path))
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/publish/none.rb

@@ -1,14 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Publish
-        # An entry with no publish_* key — nothing to publish.
-        class None < Mode
-          def publish(_pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-            nil
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/publish/subtree_mirror.rb

@@ -1,73 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Publish
-        # ADR 0049: the one walk->publish->prune pipeline behind Tree (whole-entry
-        # mirror, ADR 0047). It was once shared with the per-leaf publish_each
-        # mode too; ADR 0051 removed publish_each, leaving Tree the only caller.
-        # The `walk_root`/`prune_honors_ignore:` parameters survive from that
-        # shared shape — Tree always walks at `base` and honors `ignore` in the
-        # prune (ADR 0047 D4, so a derived index in the mirrored dir survives).
-        class SubtreeMirror
-          def initialize(entry, pctx, publisher: Textus::Port::Publisher.new)
-            @entry     = entry
-            @pctx      = pctx
-            @publisher = publisher
-          end
-
-          # base:       store dir the entry owns — the root `ignored?` globs are
-          #             relative to (ADR 0042).
-          # walk_root:  dir the glob is rooted at (== base for Tree). dst paths
-          #             mirror rel-to-walk_root.
-          # target_dir: repo-side destination root.
-          # key/envelope: emitted per file; envelope is nil for the keyless Tree.
-          # prune_honors_ignore: when true a managed file the entry `ignore`s
-          #   survives the prune (ADR 0047 D4 — lets a derived index live in the
-          #   mirrored dir); when false every unwritten managed file is pruned.
-          def mirror(base:, walk_root:, target_dir:, key:, envelope:, prune_honors_ignore:)
-            return { written: [], pruned: [] } unless File.directory?(walk_root)
-
-            written = publish_files(base: base, walk_root: walk_root, target_dir: target_dir, key: key, envelope: envelope)
-            { written: written, pruned: prune(target_dir, written, prune_honors_ignore) }
-          end
-
-          private
-
-          def publish_files(base:, walk_root:, target_dir:, key:, envelope:)
-            # FNM_DOTMATCH includes dotfiles; File.file? below skips dirs (and
-            # symlinks-to-dirs). Trees are authored content, not symlink graphs.
-            Dir.glob(File.join(walk_root, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |src|
-              next nil unless File.file?(src)
-              next nil if @entry.ignored?(relative(src, base))
-
-              dst = File.join(target_dir, relative(src, walk_root))
-              @publisher.publish(source: src, target: dst, store_root: @pctx.root)
-              @pctx.emit(:entry_published, key: key, envelope: envelope, source: src, target: dst)
-              { "key" => key, "source" => src, "target" => dst }
-            end
-          end
-
-          # Scoped to target_dir. Safe across leaves because ADR 0046 D5
-          # (shallowest-index-wins) keeps leaf target dirs non-nesting, so
-          # targets_under can't reach another leaf's sentinels.
-          def prune(target_dir, written, honor_ignore)
-            kept = written.map { |w| File.expand_path(w["target"]) }
-            store = Textus::Port::SentinelStore.new
-            store.targets_under(target_dir, @pctx.root).filter_map do |managed|
-              abs = File.expand_path(managed)
-              next nil if kept.include?(abs)
-              next nil if honor_ignore && @entry.ignored?(relative(abs, target_dir))
-
-              @publisher.unpublish(target: managed, store_root: @pctx.root)
-              managed
-            end
-          end
-
-          def relative(path, root)
-            path.sub(%r{\A#{Regexp.escape(root)}/}, "")
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/publish/template.rb

@@ -1,16 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Publish
-        # Template-variable detection for publish targets. The only surviving
-        # use after ADR 0051 (which removed publish_each and its `{leaf}`/
-        # `{basename}`/`{key}`/`{ext}` vocabulary) is Tree.validate!, which uses
-        # VAR_RE to reject any `{var}` in a publish_tree value — that key names a
-        # single directory by plain path and interprets no variables.
-        module Template
-          VAR_RE = /\{([a-z]+)\}/
-        end
-      end
-    end
-  end
-end