maf 0.1.0

data/lib/maf/uninstall/manifest.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    # .maf/config.json lists the generated agents. Hermes skills live outside
+    # the project, so only the manifest tells which ones belong to it.
+    class Manifest
+      def initialize(project)
+        @project = project
+        @path = File.join(project, ".maf/config.json")
+      end
+
+      def steps = File.exist?(@path) ? [Owned.remove(@path)] : []
+
+      def hermes_skills
+        roles = data.fetch("agents", []).select { |a| a["harness"] == "hermes" }.map { |a| a["role"] }
+        roles.map { |role| File.join(hermes_dir, "#{File.basename(@project)}-#{role}", "SKILL.md") }
+      end
+
+      private
+
+      def hermes_dir = data.fetch("hermes_dir", Flow::DEFAULT_HERMES_DIR)
+
+      def data
+        @data ||= File.exist?(@path) ? (JSON.parse(File.read(@path)) rescue {}) : {}
+      end
+    end
+  end
+end

data/lib/maf/uninstall/marked_files.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    # Removes the marked block from AGENTS.md and .gitignore. Text
+    # outside the block stays. A file with nothing left goes. .gitignore keeps
+    # the ignore rule for the kept graphify-out/ dir.
+    class MarkedFiles
+      FILES = %w[AGENTS.md .gitignore].freeze
+
+      # keep_rules: false drops the ignore rules too. maf untrack excludes .maf/ locally instead.
+      def initialize(project, keep_rules: true)
+        @project = project
+        @keep_rules = keep_rules
+      end
+
+      def steps
+        FILES.map { |name| File.join(@project, name) }.select { |path| Owned.marked?(path) }
+             .map { |path| Step.new("remove flow block from #{path}", -> { clean(path) }) }
+      end
+
+      private
+
+      def clean(path)
+        text = Bootstrap::MarkedBlock.new(File.read(path)).remove.rstrip
+        text = [text, *(kept_rules(path) - text.lines.map(&:strip))].reject(&:empty?).join("\n")
+        text.empty? ? FileUtils.rm(path) : File.write(path, "#{text}\n")
+      end
+
+      def kept_rules(path)
+        return [] unless @keep_rules && File.basename(path) == ".gitignore"
+
+        KEPT_DIRS.select { |dir| Dir.exist?(File.join(@project, dir)) }.map { |dir| "#{dir}/" }
+      end
+    end
+  end
+end

data/lib/maf/uninstall/mcp_entries.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    # Removes the graphify server that an older maf wrote into the project's
+    # .mcp.json and opencode.json. Today the server lives in .maf/mcp/. A
+    # foreign entry and all other settings stay. A file goes only if nothing
+    # else is left in it.
+    class McpEntries
+      PROJECT_FILES = { "claude" => ".mcp.json", "opencode" => "opencode.json" }.freeze
+
+      def initialize(project)
+        @files = Flow::McpConfig.targets.map { |harness, t| [File.join(project, PROJECT_FILES.fetch(harness)), t] }
+      end
+
+      def steps
+        @files.filter_map do |path, target|
+          next unless File.exist?(path) && ours?(read(path), target)
+
+          Step.new("remove the graphify server from #{path}", -> { clean(path, target) })
+        end
+      end
+
+      private
+
+      def read(path)
+        data = JSON.parse(File.read(path))
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def ours?(data, target) = data.dig(target[:key], Flow::McpConfig::NAME) == target[:entry]
+
+      def clean(path, target)
+        data = read(path)
+        section = data.fetch(target[:key]).except(Flow::McpConfig::NAME)
+        data = section.empty? ? data.except(target[:key]) : data.merge(target[:key] => section)
+        data.except("$schema").empty? ? FileUtils.rm(path) : File.write(path, "#{JSON.pretty_generate(data)}\n")
+      end
+    end
+  end
+end

data/lib/maf/uninstall/notes.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    # Tells the user what the uninstaller keeps on purpose.
+    class Notes
+      def initialize(project) = @project = project
+
+      def lines
+        [kept_dirs, branches, global_hooks].compact
+      end
+
+      private
+
+      def kept_dirs
+        dirs = KEPT_DIRS.select { |dir| Dir.exist?(File.join(@project, dir)) }
+        "kept   #{dirs.map { |d| "#{d}/" }.join(", ")} (costly to rebuild; delete by hand)" if dirs.any?
+      end
+
+      def branches
+        list = Git.lines(@project, "branch", "--list", "worker/*", "--format=%(refname:short)")
+        "kept   branches #{list.join(", ")} (delete with git branch -D)" if list.any?
+      end
+
+      def global_hooks
+        hooks = GLOBAL_HOOKS.select { |path| File.exist?(path) }
+        "kept   global hooks #{hooks.join(", ")} (other projects can use them)" if hooks.any?
+      end
+    end
+  end
+end

data/lib/maf/uninstall/owned.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    module Owned
+      def self.signed?(path, signature) = File.file?(path) && File.read(path).include?(signature)
+      def self.marked?(path) = signed?(path, Bootstrap::MARKER)
+      def self.prune(dir) = Dir.exist?(dir) && Dir.empty?(dir) && Dir.rmdir(dir)
+      def self.remove(path) = Step.new("remove #{path}", -> { FileUtils.rm(path) })
+    end
+  end
+end

data/lib/maf/uninstall/role_files.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    # Removes the role files in .maf/agents/ and the symlink of each harness
+    # folder that points there.
+    class RoleFiles
+      DIRS = %w[claude opencode codex].map { |harness| [".maf", "agents", harness] }.freeze
+
+      def initialize(project, manifest)
+        @project = project
+        @manifest = manifest
+      end
+
+      def steps
+        links.map { |path| Owned.remove(path) } + project_files.map { |path| Owned.remove(path) } +
+          @manifest.hermes_skills.select { |path| Owned.marked?(path) }.map { |path| hermes_step(path) }
+      end
+
+      private
+
+      def project_files
+        DIRS.flat_map { |parts| Dir.glob(File.join(@project, *parts, "*.md")) }.select { |path| Owned.marked?(path) }
+      end
+
+      def links = folder_links + file_links
+
+      def folder_links
+        Flow::HARNESS_DIRS.filter_map do |harness, dir|
+          path = File.join(@project, dir)
+          path if File.symlink?(path) && File.readlink(path) == Flow::AgentLinks.target(harness)
+        end
+      end
+
+      # The links of single role files in a harness folder with the user's own files.
+      def file_links
+        Flow::HARNESS_DIRS.flat_map do |harness, dir|
+          Dir.glob(File.join(@project, dir, "*.md")).select { |path| file_link?(path, harness) }
+        end
+      end
+
+      def file_link?(path, harness)
+        File.symlink?(path) && File.readlink(path) == Flow::AgentLinks.file_target(harness, File.basename(path))
+      end
+
+      def hermes_step(path)
+        Step.new("remove #{File.dirname(path)}", -> { FileUtils.rm(path) && Owned.prune(File.dirname(path)) })
+      end
+    end
+  end
+end

data/lib/maf/uninstall/runner.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    class Runner
+      USAGE = "Usage: maf uninstall [--check] [--yes] [--force]"
+
+      def initialize(argv)
+        @opts = {}
+        OptionParser.new(USAGE) { |o| ["--project DIR", "--check", "--yes", "--force"].each { |f| o.on(f) } }
+                    .parse!(argv, into: @opts)
+      end
+
+      def run
+        return old_layout if Migrate.old_layout?(project)
+
+        steps = plan
+        return finish("nothing to remove in #{project}") if steps.empty?
+
+        steps.each { |step| say(step.label.gsub("#{project}/", "")) }
+        @opts[:check] ? finish("check only; nothing removed") : apply(steps)
+      end
+
+      private
+
+      def project
+        abort USAGE unless @opts[:project] && Dir.exist?(@opts[:project])
+        @project ||= File.realpath(@opts[:project])
+      end
+
+      # The uninstaller knows only the new layout. --check shows the migration plan instead.
+      def old_layout
+        abort "uninstall: #{Migrate::HINT}" unless @opts[:check]
+        say("this project uses the old layout. Run maf migrate before maf uninstall. maf migrate plans:")
+        Migrate::Runner.new(["--project", project, "--check"]).run
+        say("after maf migrate, run maf uninstall --check again to see what the uninstaller removes")
+      end
+
+      def plan
+        manifest = Manifest.new(project)
+        [VaultWatcher.new(project), Worktrees.new(project, @opts[:force]), Scripts.new(project),
+         CommitGuard.new(project), DocGraphHooks.new(project), RoleFiles.new(project, manifest),
+         ClaudeSettings.new(project), CodexHooks.new(project), McpEntries.new(project),
+         MarkedFiles.new(project), LocalFiles.new(project), Coordination.new(project), manifest].flat_map(&:steps)
+      end
+
+      def apply(steps)
+        abort "uninstall: cancelled" unless @opts[:yes] || confirmed?
+        steps.each(&:run)
+        EMPTY_DIRS.each { |parts| Owned.prune(File.join(project, *parts)) }
+        finish("removed the multi-agent flow from #{project}")
+      end
+
+      def confirmed?
+        print "Remove the items above? [y/N] "
+        $stdin.gets.to_s.strip.match?(/\Ay(es)?\z/i)
+      end
+
+      def finish(message)
+        Notes.new(project).lines.each { |line| say(line) }
+        say(message)
+      end
+
+      def say(message) = puts("[multi-agent-flow] #{message}")
+    end
+  end
+end

data/lib/maf/uninstall/scripts.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    class Scripts
+      SIGNATURES = { ".maf/bin/coord" => Bootstrap::COORD_SIGNATURE,
+                     ".maf/bin/dispatcher" => Bootstrap::DISPATCHER_SIGNATURE,
+                     ".maf/bin/dashboard" => Bootstrap::DASHBOARD_SIGNATURE,
+                     ".maf/bin/dashboard.html" => Bootstrap::DASHBOARD_PAGE_SIGNATURE,
+                     ".maf/bin/analyst" => Bootstrap::ANALYST_SIGNATURE,
+                     ".maf/bin/vault" => Bootstrap::VAULT_SIGNATURE,
+                     ".maf/bin/doc-graph-refresh" => Bootstrap::DOC_GRAPH_SIGNATURE,
+                     ".maf/env.sh" => Bootstrap::ENV_SIGNATURE,
+                     Bootstrap::OPENCODE_PLUGIN => Bootstrap::OPENCODE_BOARD_WATCH_SIGNATURE }.freeze
+
+      def initialize(project) = @project = project
+
+      def steps
+        candidates.select { |path, signature| Owned.signed?(path, signature) }.map { |path, _| Owned.remove(path) }
+      end
+
+      private
+
+      def candidates
+        SIGNATURES.map { |name, signature| [File.join(@project, name), signature] } + shared
+      end
+
+      # The files of the shared library. A file without the signature stays.
+      def shared
+        dir = File.join(@project, Bootstrap::MAF_DIR, Bootstrap::SHARED_DIR)
+        Dir.glob(File.join(dir, "*.rb")).map { |path| [path, Bootstrap::SHARED_SIGNATURE] }
+      end
+    end
+  end
+end

data/lib/maf/uninstall/vault_watcher.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    # The vault watcher runs detached. Stop it while its script still exists.
+    class VaultWatcher
+      def initialize(project) = @project = project
+
+      def steps
+        return [] unless File.exist?(File.join(@project, ".maf", "coordination", "vault.pid")) && script
+
+        [Step.new("stop vault watcher", -> { system(script, "stop", chdir: @project) })]
+      end
+
+      def script
+        path = File.join(@project, ".maf", "bin", "vault")
+        path if Owned.signed?(path, Bootstrap::VAULT_SIGNATURE)
+      end
+    end
+  end
+end

data/lib/maf/uninstall/worktrees.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Maf
+  module Uninstall
+    class Worktrees
+      def initialize(project, force)
+        @project = project
+        @force = force
+      end
+
+      def steps = paths.map { |dir| Step.new("remove worktree #{dir}", -> { remove(dir) }) }
+
+      private
+
+      def paths
+        root = File.join(@project, ".maf/worktrees", "")
+        Git.lines(@project, "worktree", "list", "--porcelain")
+           .filter_map { |line| line[/\Aworktree (.+)/, 1] }.select { |dir| dir.start_with?(root) }
+      end
+
+      # A worktree that an older migrate moved has an env file that git does not exclude.
+      def remove(dir)
+        EnvExclude.add(dir)
+        args = ["worktree", "remove", *("--force" if @force), dir]
+        system("git", "-C", @project, *args, err: File::NULL) ||
+          puts("kept   #{dir} (uncommitted changes; use --force to remove)")
+      end
+    end
+  end
+end

data/lib/maf/uninstall.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# uninstall.rb - remove the multi-agent flow from a project.
+#
+# maf uninstall runs Uninstall::Runner. Options: --project DIR [--check] [--yes] [--force]
+#
+# Removes only what bootstrap.rb and flow.rb installed. A file must carry the
+# tool signature or marker. A foreign file with the same name stays.
+# Keeps graphify-out/ at the project root: the graph, the Obsidian vault, and
+# the saved notes. Rebuilding the graph costs many agent runs, so the user deletes it by hand.
+# Removes .maf/ if nothing is left in it.
+# Keeps worker/* branches. Keeps dirty worktrees unless --force is given.
+# Keeps the guarded global Hermes hook. Other projects can use the hook.
+# Stops on an old layout. --check then prints the plan of maf migrate.
+require "fileutils"
+require "json"
+require "optparse"
+require_relative "bootstrap"
+require_relative "flow"
+require_relative "env_exclude"
+require_relative "local_exclude"
+require_relative "migrate"
+
+module Maf
+  module Uninstall
+    KEPT_DIRS = %w[graphify-out].freeze
+
+    # Removed after all steps if empty. Children come before parents.
+    EMPTY_DIRS = [%w[.claude agents], %w[.claude], %w[.opencode agents], %w[.opencode plugins], %w[.opencode],
+                  %w[.codex prompts], %w[.codex], %w[.maf bin], %w[.maf agents claude], %w[.maf agents opencode],
+                  %w[.maf agents codex], %w[.maf agents], %w[.maf worktrees],
+                  %w[.maf lib maf shared], %w[.maf lib maf], %w[.maf lib], %w[.maf]].freeze
+
+    GLOBAL_HOOKS = [File.join(Dir.home, ".hermes", "agent-hooks", "next-task.sh")].freeze
+
+    # Step is one removal. --check prints the label and runs nothing.
+    Step = Struct.new(:label, :work) do
+      def run = work.call
+    end
+  end
+end
+
+require_relative "uninstall/owned"
+require_relative "uninstall/git"
+require_relative "uninstall/vault_watcher"
+require_relative "uninstall/worktrees"
+require_relative "uninstall/scripts"
+require_relative "uninstall/commit_guard"
+require_relative "uninstall/doc_graph_hooks"
+require_relative "uninstall/manifest"
+require_relative "uninstall/role_files"
+require_relative "uninstall/claude_settings"
+require_relative "uninstall/codex_hooks"
+require_relative "uninstall/mcp_entries"
+require_relative "uninstall/marked_files"
+require_relative "uninstall/coordination"
+require_relative "uninstall/local_files"
+require_relative "uninstall/notes"
+require_relative "uninstall/runner"

data/lib/maf/untrack.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# untrack.rb - move an install that git tracks to the local layout.
+require "json"
+require_relative "uninstall"
+
+module Maf
+  # Untrack removes the flow from the project's git and keeps it working:
+  # it untracks .maf/ and the harness links (the files stay on disk), removes
+  # the flow blocks and entries from the project files, excludes the flow
+  # locally, and runs maf update. The user reviews the change and commits it.
+  class Untrack
+    USAGE = "Usage: maf untrack [--check] [--yes]"
+    PATHS = [".maf", ".opencode/agents", ".codex/prompts", Bootstrap::OPENCODE_PLUGIN].freeze
+
+    def initialize(root, argv)
+      @root = root
+      @check = argv.include?("--check")
+      @yes = argv.include?("--yes")
+    end
+
+    def run
+      steps = plan
+      return puts("maf: git tracks no file of the flow in #{@root}.") if steps.empty?
+
+      steps.each { |step| puts "  #{step.label}" }
+      @check ? puts("--check: no changes made.") : apply(steps)
+    end
+
+    private
+
+    def plan
+      cleaners = [Uninstall::MarkedFiles.new(@root, keep_rules: false), Uninstall::ClaudeSettings.new(@root),
+                  Uninstall::McpEntries.new(@root)]
+      [untrack_step, *cleaners.flat_map(&:steps)].compact
+    end
+
+    def untrack_step
+      paths = tracked
+      return nil if paths.empty?
+
+      Uninstall::Step.new("git rm --cached (the files stay): #{paths.join(", ")}", -> { untrack(paths) })
+    end
+
+    def untrack(paths)
+      system("git", "-C", @root, "rm", "-r", "-q", "--cached", "--", *paths, exception: true)
+      LocalExclude.add(@root, *Bootstrap::EXCLUDED, *(paths - [".maf"]))
+    end
+
+    def apply(steps)
+      abort "maf: cancelled" unless @yes || confirmed?
+      steps.each(&:run)
+      Dir.chdir(@root) { Maf.flow }
+      puts "", "The flow left git. Review the change with `git status`, then commit it."
+    end
+
+    def confirmed?
+      print "Untrack the items above? [y/N] "
+      $stdin.gets.to_s.strip.match?(/\Ay(es)?\z/i)
+    end
+
+    # The tracked paths of the flow, and each tracked link into .maf/agents/.
+    def tracked = (git_files(*PATHS).map { |path| top(path) } + agent_links + codex_hooks).uniq
+
+    def top(path) = path.start_with?(".maf/") ? ".maf" : path
+
+    def agent_links
+      git_files(".claude/agents").select { |path| File.symlink?(File.join(@root, path)) && link_to_flow?(path) }
+    end
+
+    def link_to_flow?(path) = File.readlink(File.join(@root, path)).include?("#{Bootstrap::MAF_DIR}/agents")
+
+    # A .codex/hooks.json with only the flow hooks belongs to the flow.
+    def codex_hooks
+      path = Flow::CodexHooks::FILE
+      git_files(path).select { |file| (hook_commands(file) - Flow::CodexHooks::COMMANDS).empty? }
+    end
+
+    def hook_commands(file)
+      data = JSON.parse(File.read(File.join(@root, file)))
+      entries = data.fetch("hooks", {}).values.flatten
+      entries.flat_map { |entry| entry.fetch("hooks", []) }.map { |hook| hook["command"] }
+    rescue JSON::ParserError
+      [nil]
+    end
+
+    def git_files(*paths) = IO.popen(["git", "-C", @root, "ls-files", "--", *paths], err: File::NULL, &:readlines)
+                              .map(&:chomp)
+  end
+end

data/lib/maf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Maf
+  VERSION = "0.1.0"
+end

data/lib/maf/worker_archive.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Maf
+  # WorkerArchive moves the state of a worker into
+  # .maf/coordination/archive/workers/<worker>-<time>-<random>/. A new worker
+  # with the same id then starts clean: no old session to resume, no old
+  # handoff note, no old status or token data on the dashboard.
+  class WorkerArchive
+    def initialize(root, worker)
+      @coord_dir = File.join(root, ".maf", "coordination")
+      @worker = worker
+    end
+
+    def run = move_all({ File.join(@coord_dir, "inbox", @worker) => "inbox" }.merge(run_state, session_files))
+
+    # A new harness cannot resume the session of the old harness, and its
+    # token data must not add to the old data. The worker keeps its work: the
+    # inbox, the handoff note, and the logs stay.
+    def harness_change = move_all(run_state.merge(session_file))
+
+    private
+
+    def move_all(paths)
+      sources = paths.select { |path, _name| File.exist?(path) }
+      destination = archive_dir unless sources.empty?
+      sources.each { |path, name| move(path, File.join(destination, name)) }
+    end
+
+    # The token data, the run history, the analyst hints, and the status.
+    def run_state
+      { File.join(@coord_dir, "usage", "#{@worker}.json") => "usage.json",
+        File.join(@coord_dir, "usage", "#{@worker}.runs.jsonl") => "usage.runs.jsonl",
+        File.join(@coord_dir, "hints", "#{@worker}.json") => "hints.json",
+        File.join(@coord_dir, "status", "#{@worker}.json") => "status.json" }
+    end
+
+    def session_file
+      path = File.join(@coord_dir, "sessions", "#{@worker}.session")
+      { path => File.join("sessions", File.basename(path)) }
+    end
+
+    # The session id, the handoff note, the logs, and the watcher state.
+    def session_files
+      Dir.glob(File.join(@coord_dir, "sessions", "#{@worker}.*")).to_h do |path|
+        [path, File.join("sessions", File.basename(path))]
+      end
+    end
+
+    def move(path, dest)
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.mv(path, dest)
+    end
+
+    def archive_dir
+      parent = File.join(@coord_dir, "archive", "workers")
+      FileUtils.mkdir_p(parent)
+      Dir.mktmpdir("#{@worker}-#{Time.now.utc.strftime('%Y%m%dT%H%M%SZ')}-", parent)
+    end
+  end
+end