maf 0.1.0

data/assets/harness-hooks/session-guard.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# session-guard.rb - authorize hooks for a registered MAF session.
+require "json"
+require "fileutils"
+require "securerandom"
+
+module MafSession
+  def self.register(root, harness, env = ENV)
+    token = SecureRandom.hex(32)
+    record = registration(root, harness, env)
+    save(record, token)
+    env.merge!("MAF_SESSION_TOKEN" => token, "COORD_SESSION_PID" => Process.pid.to_s)
+  end
+
+  def self.registration(root, harness, env)
+    { "root" => File.realpath(root), "dir" => File.realpath(Dir.pwd), "pid" => Process.pid,
+      "harness" => harness, "role" => env.fetch("COORD_ROLE"), "worker" => env.fetch("COORD_WORKER") }
+  end
+
+  def self.path(root, token)
+    File.join(root, ".maf", "coordination", "sessions", "#{token}.maf.json")
+  end
+
+  def self.save(record, token)
+    path = path(record.fetch("root"), token)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, JSON.generate(record), mode: "w", perm: 0o600)
+  end
+
+  # Process ownership prevents sibling sessions from using inherited tokens.
+  module ProcessOwner
+    def self.ancestor?(owner)
+      return true if [Process.pid, Process.ppid].include?(owner)
+
+      includes?(Process.ppid, owner, parents)
+    rescue SystemCallError
+      false
+    end
+
+    def self.parents
+      IO.popen(%w[ps -eo pid=,ppid=], err: File::NULL, &:read)
+        .lines.to_h { |line| line.split.map(&:to_i) }
+    end
+
+    def self.includes?(pid, owner, parents)
+      return true if pid == owner
+      return false if pid <= 1 || !parents.key?(pid)
+
+      includes?(parents.fetch(pid), owner, parents)
+    end
+  end
+
+  class Guard
+    attr_reader :coord_dir, :taskrc, :coord
+
+    def initialize(env, input = {})
+      @env, @input = env, input.is_a?(Hash) ? input : {}
+      @record = record
+      @coord_dir = @record && File.join(@record.fetch("root"), ".maf", "coordination")
+      @taskrc = @coord_dir && File.join(@coord_dir, "taskrc")
+      @coord = @coord_dir && File.join(@coord_dir, "..", "bin", "coord")
+    end
+
+    def authorized?
+      @record && identity? && location? && board? && ProcessOwner.ancestor?(@record.fetch("pid")) && session?
+    rescue SystemCallError, KeyError, TypeError, ArgumentError
+      false
+    end
+
+    private
+
+    def record
+      return unless @env["MAF_SESSION_TOKEN"].to_s.match?(/\A[0-9a-f]{64}\z/)
+
+      data = JSON.parse(File.read(record_path))
+      data if valid_record?(data)
+    rescue SystemCallError, JSON::ParserError, TypeError
+      nil
+    end
+
+    def record_path
+      File.join(@env.fetch("COORD_DIR", ""), "sessions", "#{@env['MAF_SESSION_TOKEN']}.maf.json")
+    end
+
+    def valid_record?(data)
+      data.is_a?(Hash) && %w[root dir role worker harness].all? { |key| data[key].is_a?(String) } &&
+        data["pid"].is_a?(Integer) && data["pid"].positive?
+    end
+
+    def identity?
+      @record.fetch("role") == @env["COORD_ROLE"] && @record.fetch("worker") == @env["COORD_WORKER"] &&
+        @record.fetch("pid").to_s == @env["COORD_SESSION_PID"]
+    end
+
+    def location?
+      dir = File.realpath(@record.fetch("dir"))
+      current = File.realpath(@input.fetch("cwd", Dir.pwd))
+      current == dir || current.start_with?("#{dir}/")
+    end
+
+    def board?
+      File.realpath(@env.fetch("COORD_DIR")) == File.realpath(@coord_dir) &&
+        File.realpath(@env.fetch("TASKRC")) == File.realpath(@taskrc) && File.executable?(@coord)
+    end
+
+    def session?
+      id = @input["session_id"].to_s
+      return false if id.empty?
+
+      @input["hook_event_name"] == "SessionStart" ? bind(id) : bound?(id)
+    end
+
+    # A new harness session (/clear, a new Codex or opencode session) replaces
+    # the bound ID. Process ownership already rejects sibling processes.
+    # A temp file per process and a rename keep parallel SessionStart hooks safe.
+    def bind(id)
+      temp = "#{record_path}.session.#{Process.pid}"
+      File.write(temp, id, perm: 0o600)
+      File.rename(temp, "#{record_path}.session")
+      true
+    end
+
+    def bound?(id)
+      File.read("#{record_path}.session") == id
+    end
+  end
+end

data/assets/taskrc.append

@@ -0,0 +1,11 @@
+# >>> multi-agent-flow >>>
+# User Defined Attributes used by the `coord` wrapper.
+# Do not remove: coord relies on these to attribute tasks to roles and workers.
+uda.role.type=string
+uda.worker.type=string
+uda.scope.type=string
+uda.taskref.type=string
+uda.goalid.type=string
+# Hide the "TASKRC override" footnote. coord always sets TASKRC.
+verbose=blank,header,footnote,label,new-id,affected,edit,special,project,sync,filter,recur
+# <<< multi-agent-flow <<<

data/assets/vault

@@ -0,0 +1,224 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vault - shared knowledge base watcher (graphify + Obsidian + MCP).
+#
+# Usage: vault [start|export|stop|status|age|mcp]
+#   vault           # start the watcher (default); no-op if already running
+#   vault export    # regenerate the Obsidian vault once, then exit
+#   vault stop
+#   vault status
+#   vault age [--json]  # commits since the graph was built, and whether the graph is stale
+#   vault mcp       # exec the stdio MCP server (for an MCP client config)
+#
+# graphify 0.9 removed the --obsidian/--obsidian-dir/--watch/--mcp flags. The
+# current CLI is subcommand-based:
+#   graphify extract . --code-only          initial code graph, no LLM
+#   graphify update .                       incremental code re-extract, no LLM
+#   graphify export obsidian --dir graphify-out/obsidian  Obsidian notes + graph.canvas
+#   graphify-mcp                            stdio MCP server, spawned by the client
+# The watcher polls `graphify update` and re-exports at VAULT_POLL seconds, so
+# it does not need graphify's optional `watchdog` dependency. The graph and the
+# vault live in graphify-out/ at the project root. graphify never reads that
+# folder as input, except graphify-out/memory/. Bootstrap excludes it from git.
+#
+# Started automatically by bootstrap.rb when graphify is on PATH. Run by hand
+# after installing graphify if it was not on PATH at bootstrap time.
+
+require "fileutils"
+require "json"
+require "rbconfig"
+
+abort "vault: Ruby 3.0+ required (current: #{RUBY_VERSION})." if RUBY_VERSION.split(".").first.to_i < 3
+
+module Vault
+  # The default folders of graphify. An agent that runs graphify export
+  # writes the same vault.
+  GRAPH_DIR = "graphify-out"
+  DIR = File.join(GRAPH_DIR, "obsidian")
+  GRAPH = File.join(GRAPH_DIR, "graph.json")
+  PID_FILE = ".maf/coordination/vault.pid"
+  LOG_FILE = ".maf/coordination/vault.log"
+  # A garbage or tiny VAULT_POLL would turn the watcher into a busy loop.
+  MIN_POLL = 5
+  POLL = [(ENV["VAULT_POLL"] || 30).to_i, MIN_POLL].max
+  EXTRACT_CMD = ["graphify", "extract", ".", "--code-only"].freeze
+  DOC_GRAPH_LOCK = File.join(".maf", "coordination", "doc-graph.lock")
+  UPDATE_CMD = ["graphify", "update", "."].freeze
+  EXPORT_CMD = ["graphify", "export", "obsidian", "--dir", DIR].freeze
+
+  # Any other argument (or none) starts the watcher.
+  COMMANDS = { "stop" => :stop, "status" => :status, "export" => :export,
+               "mcp" => :mcp, "daemon" => :loop_forever }.freeze
+
+  # Every path of this script is relative to the main checkout, where the graph
+  # and the watcher live. A command from a worktree moves there first.
+  # graphify writes its output where GRAPHIFY_OUT points. Every graphify call
+  # of this script, and of its daemon, inherits the variable.
+  def self.run(argv)
+    Dir.chdir(Daemon.main_root)
+    ENV["GRAPHIFY_OUT"] = File.expand_path(GRAPH_DIR)
+    return age(argv) if argv.first == "age"
+
+    Daemon.public_send(COMMANDS.fetch(argv.first, :start))
+  end
+
+  def self.age(argv)
+    GraphAge.print(json: argv.include?("--json"))
+  end
+
+  # GraphAge counts the commits since the graph was built. The graph is stale
+  # when one of these commits changed a source or markdown file. The build
+  # time is the mtime of graph.json. It never fails: an unreadable state is
+  # reported as "unknown".
+  module GraphAge
+    SOURCE = /\.(md|rb|erb|py|js|jsx|ts|tsx|go|rs|java|kt|swift|c|h|cc|cpp|cs|php|sh|ex|exs|lua|scala)\z/
+
+    def self.state
+      return { state: "missing", commits: nil } unless File.exist?(GRAPH)
+
+      since = "--since=#{File.mtime(GRAPH).to_i}"
+      commits = git("rev-list", "--count", since, "HEAD")&.to_i
+      return { state: "unknown", commits: nil } unless commits
+
+      { state: stale?(since) ? "stale" : "fresh", commits: commits }
+    end
+
+    def self.stale?(since)
+      git("log", since, "--name-only", "--format=").to_s.lines.any? { |line| line.strip.match?(SOURCE) }
+    end
+
+    def self.git(*args)
+      output = IO.popen(["git", *args], err: File::NULL, &:read)
+      $?.success? ? output : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def self.text(data)
+      return "graph age: #{data[:state]}" unless data[:commits]
+
+      "graph age: #{data[:commits]} #{data[:commits] == 1 ? "commit" : "commits"} since build (#{data[:state]})"
+    end
+
+    def self.print(json: false)
+      data = state
+      puts json ? JSON.generate(data) : text(data)
+    end
+  end
+
+  module Daemon
+    def self.start
+      return puts("vault: already running (pid #{Pid.read})") if Pid.running?
+      abort "vault: graphify not found on PATH. Install: pip/uv install graphifyy" unless which("graphify")
+
+      FileUtils.mkdir_p(File.dirname(LOG_FILE))
+      spawn_detached
+    end
+
+    def self.export
+      return puts("vault: #{GRAPH} missing. Run `vault` to build it first.") unless File.exist?(GRAPH)
+
+      system(*EXPORT_CMD) || warn("vault: obsidian export failed; see #{LOG_FILE}")
+    end
+
+    # MCP is a stdio server the client spawns, not a background daemon. Point
+    # an MCP client at this command instead of a long-running process.
+    def self.mcp
+      abort "vault: graphify-mcp not found on PATH. Install: pip/uv install graphifyy" unless which("graphify-mcp")
+      abort "vault: #{GRAPH} missing. Run `vault` to build it first." unless File.exist?(GRAPH)
+
+      Kernel.exec("graphify-mcp", File.expand_path(GRAPH))
+    end
+
+    def self.main_root
+      common = IO.popen(%w[git rev-parse --git-common-dir], err: File::NULL, &:read).to_s.strip
+      common.empty? ? Dir.pwd : File.dirname(File.expand_path(common))
+    rescue SystemCallError
+      Dir.pwd
+    end
+
+    def self.build_initial_graph
+      return if File.exist?(GRAPH)
+
+      puts "vault: no #{GRAPH} yet; building the code graph (no LLM)"
+      system(*EXTRACT_CMD) || warn("vault: graphify extract failed; retrying via update each poll")
+    end
+
+    def self.spawn_detached
+      pid = Process.spawn(RbConfig.ruby, File.expand_path(__FILE__), "daemon",
+                          out: LOG_FILE, err: LOG_FILE, pgroup: true)
+      Process.detach(pid)
+      Pid.write(pid)
+      puts "vault: started (pid #{pid}), log at #{LOG_FILE}"
+    end
+
+    # The daemon builds the first graph itself, so `vault` (and bootstrap)
+    # return at once instead of blocking on a full extract. It exits when the
+    # pid file is gone (`vault stop`, or a removed checkout), so it never
+    # outlives its project.
+    def self.loop_forever
+      Pid.write(Process.pid)
+      build_initial_graph
+      exported_at = nil
+      exported_at = tick(exported_at) while File.exist?(PID_FILE)
+    end
+
+    # One poll: refresh the graph, re-export only when graph.json changed
+    # (Obsidian reloads every rewritten note), then sleep. Returns the graph
+    # mtime that was last exported.
+    def self.tick(exported_at)
+      system(*UPDATE_CMD) unless File.exist?(DOC_GRAPH_LOCK)
+      mtime = File.exist?(GRAPH) ? File.mtime(GRAPH) : nil
+      export if mtime && mtime != exported_at
+      sleep POLL
+      mtime || exported_at
+    end
+
+    def self.stop
+      return puts("vault: not running") unless Pid.running?
+
+      pid = Pid.read
+      Process.kill("TERM", -pid)
+      Pid.clear
+      puts "vault: stopped"
+    end
+
+    def self.status
+      puts Pid.running? ? "vault: running (pid #{Pid.read})" : "vault: not running"
+      puts File.exist?(GRAPH) ? "graph: #{GRAPH}" : "graph: #{GRAPH} missing"
+      puts File.directory?(DIR) ? "obsidian: #{DIR}/" : "obsidian: #{DIR}/ missing"
+      puts GraphAge.text(GraphAge.state)
+    end
+
+    def self.which(bin)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, bin)) }
+    end
+  end
+
+  module Pid
+    # A corrupt or empty pid file reads as 0; Process.kill(0, 0) would signal
+    # this process's own group, so treat a non-positive pid as not running.
+    def self.running?
+      pid = File.exist?(PID_FILE) ? read : 0
+      pid.positive? && Process.kill(0, pid) && true
+    rescue Errno::ESRCH, Errno::ENOENT, Errno::EINVAL, RangeError
+      false
+    end
+
+    def self.read
+      File.read(PID_FILE).to_i
+    end
+
+    def self.write(pid)
+      FileUtils.mkdir_p(File.dirname(PID_FILE))
+      File.write(PID_FILE, pid)
+    end
+
+    def self.clear
+      File.delete(PID_FILE)
+    end
+  end
+end
+
+Vault.run(ARGV) if __FILE__ == $PROGRAM_NAME

data/assets/worktree-env.example.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# worktree-env.rb - example project hook for `coord worktree` (Rails).
+#
+# Copy this file to .maf/coordination/worktree-env.rb. Git ignores that folder.
+# To commit the hook, run `git add -f .maf/coordination/worktree-env.rb`.
+# `coord worktree` runs the hook for each worktree and appends the output
+# to the worktree's .maf/env.sh.
+#
+# Input:  COORD_SLOT (1, 2, ...; the main worktree is slot 0) and
+#         COORD_WORKTREE (absolute path of the worktree).
+# Output: one `export NAME=VALUE` line per variable. `coord worktree` keeps
+#         only those lines, so a later `source .maf/env.sh` runs no other
+#         line the hook prints.
+#
+# Use the variables in the project, for example in config/database.yml:
+#   test:
+#     database: app_test<%= ENV["TEST_ENV_NUMBER"] %>
+# Then create each worktree's test database one time:
+#   bin/rails db:test:prepare
+
+slot = ENV.fetch("COORD_SLOT").to_i
+
+puts "export TEST_ENV_NUMBER=#{slot}"
+puts "export PORT=#{3000 + slot}"
+puts "export CAPYBARA_SERVER_PORT=#{4000 + slot}"

data/exe/maf

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# maf - multi-agent-flow command line tool.
+#
+# Run maf in the project root. maf uses the current directory as the project.
+# Install it with: gem install maf. In a clone, link this file into a
+# directory on PATH. __dir__ follows the link to find lib/.
+lib = File.expand_path("../lib/maf.rb", __dir__)
+abort "maf: cannot find #{lib}. Run: gem install maf. Or link exe/maf into PATH with ln -s. Do not copy it." \
+  unless File.exist?(lib)
+require lib
+
+Maf::CLI.new(ARGV).run