maf 0.1.0

data/lib/maf/bootstrap/installer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # Installer runs the install: check dependencies, plan the actions, apply
+    # them, start the vault, and print the next steps.
+    class Installer
+      # Each step is [planner, method]. The order is the order of the output.
+      PLAN_STEPS = [
+        %i[layout dirs], %i[scripts shared], %i[scripts coord], %i[scripts dispatcher], %i[scripts vault],
+        %i[scripts dashboard], %i[scripts analyst], %i[scripts env], %i[text taskrc], %i[text exclude],
+        %i[scripts hooks], %i[scripts opencode_plugin], %i[claude plan], %i[git commit_guard],
+        %i[scripts doc_graph], %i[git doc_graph_hooks]
+      ].freeze
+      PLANNERS = { layout: LayoutPlanner, scripts: ScriptPlanner, text: TextPlanner, claude: ClaudeSettings,
+                   git: GitHookPlanner }.freeze
+
+      def initialize(argv)
+        @options = Options.new(argv)
+      end
+
+      def run
+        validate_target
+        prepare
+        actions = plan
+        @options.check ? print_plan(actions) : install(actions)
+      end
+
+      private
+
+      def validate_target
+        target = @options.target
+        abort "usage: bootstrap.rb /path/to/project [--roles a,b,c] [--check] [--force]" if target.nil?
+        abort "target is not a directory: #{target}" unless Dir.exist?(target)
+      end
+
+      def prepare
+        @project = Project.new(@options.target, @options.force)
+        Dependencies.new(@options).report
+        GlobalTaskrcWarning.new(@project).run
+      end
+
+      def install(actions)
+        Writer.new(@project).apply(actions)
+        GraphHome.new(@project).move
+        MemoryBranch.new(@project).setup
+        print_next_steps(VaultStarter.new(@project).start(actions))
+      end
+
+      def plan
+        planners = PLANNERS.transform_values { |klass| klass.new(@project) }
+        PLAN_STEPS.flat_map { |planner, step| planners.fetch(planner).public_send(step) }
+      end
+
+      def print_plan(actions)
+        actions.each { |act| Bootstrap.say(@project.format_action(act)) }
+        puts "\n--check: no changes made."
+      end
+
+      def print_next_steps(vault_note)
+        puts
+        puts format(NEXT_STEPS, project: @project.target, roles: @options.roles, vault_note: vault_note)
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/layout_planner.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # LayoutPlanner plans the directories of the .maf/ folder.
+    class LayoutPlanner
+      def initialize(project)
+        @project = project
+      end
+
+      def dirs
+        [@project.path(MAF_DIR, "bin"), *SUBDIRS.map { |sub| @project.path(MAF_DIR, "coordination", sub) }].map do |dir|
+          @project.action(Dir.exist?(dir) ? :skip : :mkdir, dir)
+        end
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/marked_block.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # MarkedBlock finds the tool-owned block in a file: from the first line that
+    # contains MARKER to the next line that contains END_MARKER, inclusive. The
+    # comment syntax around the markers differs per file (`#` vs `<!-- -->`), so
+    # only the marker text is matched.
+    class MarkedBlock
+      def initialize(text)
+        @lines = text.lines
+      end
+
+      def current?(block)
+        range && @lines[range].join.strip == block.strip
+      end
+
+      def replace(block)
+        return @lines.join unless range
+
+        block = "#{block.chomp}\n"
+        (@lines[0...range.begin] + [block] + @lines[(range.end + 1)..]).join
+      end
+
+      def remove
+        return @lines.join unless range
+
+        (@lines[0...range.begin] + @lines[(range.end + 1)..]).join
+      end
+
+      private
+
+      def range
+        @range ||= find_range
+      end
+
+      def find_range
+        first = @lines.index { |line| line.include?(MARKER) }
+        last = first && @lines[first..].index { |line| line.include?(END_MARKER) }
+        last && (first..(first + last))
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/memory_branch.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Maf
+  module Bootstrap
+    # MemoryBranch keeps the work memory in git with no noise in the project
+    # history (ADR 0006). graphify-out/memory/ is a worktree of the orphan branch
+    # maf/memory. The branch shares no history with the project branches, so a
+    # note never shows in a pull request. A new clone takes the branch from
+    # origin. The notes of an older install move into the worktree. When git
+    # fails, the folder stays a plain folder and the flow works as before.
+    class MemoryBranch
+      BRANCH = "maf/memory"
+      DIR = File.join(GRAPH_DIR, "memory")
+      START = "memory: start the work memory of the flow"
+      ADOPT = "memory: add the notes of an older install"
+      CONFIG = File.join(MAF_DIR, "config.json")
+
+      def initialize(project) = @project = project
+
+      def setup
+        return if !repo? || File.exist?(path(DIR, ".git"))
+
+        done = (local? || fetched? || created?) && checkout
+        Bootstrap.say(done ? "done   #{DIR} is a worktree of branch #{BRANCH}" : "skip   #{BRANCH} (git failed)")
+      end
+
+      private
+
+      # A project folder inside another repository has no repository of its own.
+      def repo? = out("rev-parse", "--show-toplevel") == @project.target
+      def local? = git("show-ref", "--verify", "--quiet", "refs/heads/#{BRANCH}")
+      def fetched? = git("fetch", "-q", "origin", "#{BRANCH}:#{BRANCH}")
+
+      # An orphan commit of the empty tree. It needs no checkout.
+      def created?
+        tree = out("hash-object", "-w", "-t", "tree", File::NULL)
+        commit = out("commit-tree", tree, "-m", START)
+        !commit.empty? && git("branch", BRANCH, commit)
+      end
+
+      # The notes of an older install wait in a side folder while git adds the worktree.
+      def checkout
+        old = "#{path(DIR)}.old"
+        FileUtils.mv(path(DIR), old) if Dir.exist?(path(DIR))
+        FileUtils.mkdir_p(path(GRAPH_DIR))
+        git("worktree", "add", "-q", path(DIR), BRANCH).tap { |added| restore(old, added) }
+      end
+
+      def restore(old, added)
+        return unless Dir.exist?(old)
+
+        added ? adopt(old) : FileUtils.mv(old, path(DIR))
+      end
+
+      def adopt(old)
+        Dir.children(old).each { |name| FileUtils.mv(File.join(old, name), path(DIR, name)) }
+        FileUtils.rm_rf(old)
+        git_in(path(DIR), "add", "-A") && git_in(path(DIR), "commit", "-q", "-m", ADOPT)
+      end
+
+      def git(*args) = git_in(@project.target, *args)
+      def git_in(dir, *args) = system(identity, "git", "-C", dir, *args, out: File::NULL, err: File::NULL)
+
+      def out(*args)
+        text, status = Open3.capture2(identity, "git", "-C", @project.target, *args, err: File::NULL)
+        status.success? ? text.strip : ""
+      end
+
+      # The flow makes these commits, so they use the git persona of the agents.
+      def identity = @identity ||= Maf::Shared::GitIdentity.env(Maf::Shared::GitIdentity.read(path(CONFIG)))
+
+      def path(*parts) = @project.path(*parts)
+    end
+  end
+end

data/lib/maf/bootstrap/options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # Options parses the bootstrap command line.
+    class Options
+      DEFAULT_ROLES = "architect,backend-developer,frontend-developer,reviewer,tester"
+      BANNER = "Usage: bootstrap.rb /path/to/project [--roles a,b,c] [--check] [--install-deps] [--force]"
+
+      attr_reader :target, :roles, :check, :install_deps, :force
+
+      def initialize(argv)
+        @roles = DEFAULT_ROLES
+        @check = @install_deps = @force = false
+        parser.parse!(argv)
+        @target = argv.first
+      end
+
+      private
+
+      # Each flag and the block that runs in the Options instance with its value.
+      FLAGS = { "--roles LIST" => ->(v) { @roles = v }, "--check" => ->(_) { @check = true },
+                "--install-deps" => ->(_) { @install_deps = true }, "--force" => ->(_) { @force = true } }.freeze
+
+      def parser
+        OptionParser.new do |o|
+          o.banner = BANNER
+          FLAGS.each { |flag, set| o.on(flag) { |value| instance_exec(value, &set) } }
+          o.on("-h", "--help") { puts o; exit 0 }
+        end
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/project.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # Project holds the target directory and answers questions about the files
+    # in it. Planners and the writer share one Project.
+    class Project
+      APPEND_FILES = { taskrc: "taskrc.append", post_commit: "git-hooks/post-commit",
+                       post_merge: "git-hooks/post-merge" }.freeze
+
+      attr_reader :target, :assets
+
+      def initialize(target, force)
+        @target = File.realpath(target)
+        @force = force
+        @assets = File.expand_path("../../../assets", __dir__)
+      end
+
+      def path(*parts)
+        File.join(@target, *parts)
+      end
+
+      # A script that this tool copies from assets/NAME into .maf/bin/.
+      def bin_path(name)
+        path(MAF_DIR, "bin", name)
+      end
+
+      def force?
+        @force
+      end
+
+      def ours?(file, signature)
+        File.read(file).include?(signature)
+      end
+
+      def marked?(file)
+        File.exist?(file) && ours?(file, MARKER)
+      end
+
+      def changed_script?(dest, name)
+        File.read(dest) != File.read(File.join(@assets, name))
+      end
+
+      # Status of a script that this tool copies from assets/NAME to DEST.
+      def script_status(dest, name, signature)
+        return :create unless File.exist?(dest)
+        return :refuse if File.directory?(dest) || (!ours?(dest, signature) && !force?)
+
+        ours?(dest, signature) && !changed_script?(dest, name) ? :skip : :update
+      end
+
+      def taskrc_path
+        path(MAF_DIR, "coordination", "taskrc")
+      end
+
+      def taskdata_path
+        path(MAF_DIR, "coordination", "taskdata")
+      end
+
+      def append_content(source)
+        File.read(File.join(@assets, APPEND_FILES.fetch(source)))
+      end
+
+      def action(kind, file, label = file, source = nil)
+        { kind: kind, path: file, label: label, source: source }
+      end
+
+      def refuse_label(status, file, text = "exists and is not ours; use --force")
+        status == :refuse ? "#{file} (#{text})" : file
+      end
+
+      ACTION_WORDS = { skip: "skip  ", refuse: "REFUSE", upgrade_taskrc: "upgrade" }.freeze
+
+      def format_action(act) = "#{ACTION_WORDS.fetch(act[:kind], act[:kind])} #{act[:label]}"
+    end
+  end
+end

data/lib/maf/bootstrap/script_planner.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # ScriptPlanner plans every script copied from assets/: the top-level
+    # scripts, the harness hooks, the opencode plugin, and the doc-graph
+    # refresh. GitHookPlanner plans the git hooks.
+    class ScriptPlanner
+      HOOKS = [
+        ["harness-hooks/next-task.rb", NEXT_TASK_HOOK_SIGNATURE],
+        ["harness-hooks/next-task-hermes.sh", NEXT_TASK_HERMES_SIGNATURE],
+        ["harness-hooks/board-watch.rb", BOARD_WATCH_SIGNATURE],
+        ["harness-hooks/session-guard.rb", SESSION_GUARD_SIGNATURE],
+        ["harness-hooks/context-watch.rb", CONTEXT_WATCH_SIGNATURE]
+      ].freeze
+
+      def initialize(project)
+        @project = project
+      end
+
+      # The shared library that the scripts load. Each file is planned as a script.
+      def shared
+        Dir.children(File.join(@project.assets, SHARED_SOURCE)).sort.map do |name|
+          script(File.join(SHARED_SOURCE, name), SHARED_SIGNATURE, @project.path(MAF_DIR, SHARED_DIR, name))
+        end
+      end
+
+      def coord
+        script("coord", COORD_SIGNATURE)
+      end
+
+      def dispatcher
+        script("dispatcher", DISPATCHER_SIGNATURE)
+      end
+
+      # The dashboard reads its HTML page from the file next to it.
+      def dashboard
+        [script("dashboard", DASHBOARD_SIGNATURE), script("dashboard.html", DASHBOARD_PAGE_SIGNATURE)]
+      end
+
+      def analyst
+        script("analyst", ANALYST_SIGNATURE)
+      end
+
+      def vault
+        script("vault", VAULT_SIGNATURE)
+      end
+
+      # env.sh puts .maf/bin on PATH. A worker runs `source .maf/env.sh`.
+      def env
+        script("env.sh", ENV_SIGNATURE, @project.path(MAF_DIR, "env.sh"))
+      end
+
+      def hooks
+        HOOKS.map { |name, signature| script(name, signature, @project.path(MAF_DIR, "coordination", name)) }
+      end
+
+      # The doc-graph refresh script rebuilds the shared graph after a markdown
+      # change. The git hooks start it.
+      def doc_graph
+        script("doc-graph-refresh", DOC_GRAPH_SIGNATURE)
+      end
+
+      # The opencode plugin wakes an idle opencode session. Like the Claude
+      # hooks, it is installed only if the project has a .opencode/ dir.
+      def opencode_plugin
+        return [] unless Dir.exist?(@project.path(".opencode"))
+
+        [script("harness-hooks/board-watch-opencode.js", OPENCODE_BOARD_WATCH_SIGNATURE,
+                @project.path(OPENCODE_PLUGIN))]
+      end
+
+      private
+
+      def script(name, signature, dest = @project.bin_path(name))
+        status = @project.script_status(dest, name, signature)
+        @project.action(status, dest, @project.refuse_label(status, dest), name)
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/text_planner.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # TextPlanner plans the taskrc and the local git excludes. The flow never
+    # writes into a file that git tracks: it is a tool, not a part of the project.
+    class TextPlanner
+      def initialize(project)
+        @project = project
+      end
+
+      def taskrc
+        file = @project.taskrc_path
+        status = taskrc_status(file)
+        label = status == :refuse ? @project.refuse_label(status, file) : "#{file} (Taskwarrior UDAs, project-local)"
+        @project.action(status, file, label)
+      end
+
+      # .git/info/exclude hides the flow from git in this clone only.
+      def exclude
+        file = LocalExclude.exclude_path(@project.target)
+        return [] unless file
+
+        status = (EXCLUDED - LocalExclude.listed(file)).empty? ? :skip : :local_exclude
+        [@project.action(status, file, "#{file} (local git excludes)")]
+      end
+
+      private
+
+      # Never overwrite a taskrc this tool did not create: it may point at a
+      # real Taskwarrior database. A marked taskrc from an older install that
+      # has no data.location is upgraded in place, not rewritten.
+      def taskrc_status(file)
+        return :create_taskrc unless File.exist?(file)
+        return :create_taskrc if @project.force? && !@project.ours?(file, MARKER)
+        return :refuse unless @project.ours?(file, MARKER)
+
+        File.read(file).match?(/^data\.location=/) ? :skip : :upgrade_taskrc
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/vault_starter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # VaultStarter starts the vault watcher once the script is in place, so
+    # shared memory is live right after install with no extra step for the
+    # common case (graphify already installed). It skips the start when
+    # graphify is missing. The printed next steps cover that case.
+    class VaultStarter
+      def initialize(project)
+        @project = project
+      end
+
+      # Returns the note that the next steps print.
+      def start(actions)
+        return "skipped (VAULT_SKIP is set)" if ENV["VAULT_SKIP"]
+        return "run `vault` after bootstrap (graphify is needed only to run it)" unless installed?(actions)
+        return "run `vault` once graphify is installed" unless Bootstrap.which("graphify")
+
+        launch
+      end
+
+      private
+
+      def script
+        @project.bin_path("vault")
+      end
+
+      def installed?(actions)
+        actions.any? { |act| act[:path] == script && act[:kind] != :refuse }
+      end
+
+      def launch
+        ok = system(script, chdir: @project.target)
+        note = ok ? "started (`vault status` / `vault stop`)" : "failed to start; see .maf/coordination/vault.log"
+        Bootstrap.say("vault: #{note}")
+        note
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/writer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # Writer performs the planned actions. Every writer method takes
+    # (path, source) and returns true when it changed something.
+    class Writer
+      def initialize(project)
+        @project = project
+        @claude = ClaudeSettings.new(project)
+      end
+
+      def apply(actions)
+        actions.each { |act| apply_action(act) }
+      end
+
+      private
+
+      def apply_action(act)
+        writer = WRITERS[act[:kind]]
+        return Bootstrap.say(@project.format_action(act)) unless writer
+
+        send(writer, act[:path], act[:source]) && Bootstrap.say("done   #{act[:label]}")
+      end
+
+      def make_dir(dir, _source)
+        FileUtils.mkdir_p(dir)
+      end
+
+      def touch_file(file, _source)
+        FileUtils.touch(file)
+      end
+
+      def write_script(dest, name)
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(File.join(@project.assets, name), dest)
+        FileUtils.chmod("+x", dest)
+        true
+      end
+
+      def write_taskrc(file, _source = nil)
+        FileUtils.mkdir_p([File.dirname(file), @project.taskdata_path])
+        File.write(file, "data.location=#{@project.taskdata_path}\n\n#{@project.append_content(:taskrc)}")
+        true
+      end
+
+      # Add the missing data.location to a taskrc this tool already owns,
+      # without touching the rest of the file. An old marked taskrc without it
+      # would otherwise fall back to the user's global ~/.task.
+      def upgrade_taskrc(file, _source = nil)
+        FileUtils.mkdir_p(@project.taskdata_path)
+        separator = File.size(file).zero? ? "" : "\n"
+        File.write(file, "#{separator}data.location=#{@project.taskdata_path}\n", mode: "a")
+        true
+      end
+
+      def write_exclude(_file, _source = nil)
+        LocalExclude.add(@project.target, *EXCLUDED)
+        true
+      end
+
+      def merge_hook(file, source) = HookMerger.new(@project).merge(file, source)
+
+      def configure_claude_settings(file, _source = nil)
+        @claude.configure(file)
+      end
+    end
+  end
+end