makefile-agent 0.3.0__py3-none-any.whl

make_agent/parser.py

@@ -0,0 +1,351 @@
+"""Makefile parser.
+
+Parses a subset of GNU Make syntax into structured data:
+  - Variables  (=, :=, ?=, +=, and ``define``/``endef`` blocks)
+  - Rules      (target: prerequisites + tab-indented recipes)
+  - .PHONY declarations
+  - Special comment blocks:
+      # <system> … # </system>  — system prompt for the agent (legacy)
+      # <tool>   … # </tool>    — tool description + @param declarations
+  - ``define SYSTEM_PROMPT … endef`` — system prompt (preferred; takes
+    precedence over ``# <system>`` blocks)
+
+Inside a ``# <tool>`` block:
+  - Lines starting with ``# @param NAME type description`` declare tool
+    parameters.
+  - All other lines form the human-readable tool description sent to the LLM.
+
+Param types
+-----------
+``string``, ``number``, ``integer``, ``boolean``
+    Standard JSON Schema primitives.  Values are injected via a temporary
+    ``params.mk`` file using ``define``/``endef`` blocks, so the LLM can pass
+    any text — including ``$``, quotes, and newlines — without escaping.
+
+Recipes reference parameters as ``$(PARAM)`` (Make-expanded) or
+``$(value PARAM)`` (raw literal, preserves ``$`` signs and special
+characters).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+
+_FLAVOR_MAP = {
+    "=": "recursive",
+    ":=": "simple",
+    "::=": "simple",
+    "?=": "conditional",
+    "+=": "append",
+}
+
+# Matches: NAME = value  /  NAME := value  /  NAME ?= value  /  NAME += value
+_VARIABLE_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*(::?=|\?=|\+=|=)\s*(.*)")
+
+# Matches: target(s): prerequisites
+# [^\t#]    — first char is not a tab or comment marker
+# [^:=]*?   — non-greedy, no colons or equals in the target portion
+# :(?![:=]) — a single colon NOT followed by : or =
+_TARGET_RE = re.compile(r"^([^\t#][^:=]*?)\s*:(?![:=])(.*)")
+
+# Matches: .PHONY: target …
+_PHONY_RE = re.compile(r"^\.PHONY\s*:(.*)")
+
+# Matches: $(VAR), ${VAR}, or $X variable references
+_VAR_REF_RE = re.compile(r"\$(?:\(([^)]+)\)|\{([^}]+)\}|([A-Za-z_]))")
+
+# Matches: @param NAME type description  (inside a <tool> block)
+_PARAM_RE = re.compile(r"^@param\s+(\w+)\s+(\w+)\s+(.+)")
+
+
+@dataclass
+class Variable:
+    name: str
+    value: str
+    flavor: str
+
+
+@dataclass
+class Param:
+    name: str
+    type: str          # JSON Schema primitive: string, number, integer, boolean
+    description: str
+
+
+@dataclass
+class Rule:
+    target: str
+    prerequisites: list[str] = field(default_factory=list)
+    recipes: list[str] = field(default_factory=list)
+    is_phony: bool = False
+    description: str | None = None
+    params: list[Param] = field(default_factory=list)
+
+
+@dataclass
+class Makefile:
+    system_prompt: str | None = None
+    variables: dict[str, Variable] = field(default_factory=dict)
+    rules: list[Rule] = field(default_factory=list)
+    default_target: str | None = None  # first non-special target
+
+
+def _expand_vars(s: str, variables: dict[str, Variable]) -> str:
+    """Expand $(VAR), ${VAR}, and $X references using already-seen variables."""
+
+    def replace(m: re.Match) -> str:  # type: ignore[type-arg]
+        name = m.group(1) or m.group(2) or m.group(3)
+        return variables[name].value if name in variables else m.group(0)
+
+    return _VAR_REF_RE.sub(replace, s)
+
+
+def _strip_comment(s: str) -> str:
+    """Strip an inline # comment (not preceded by a backslash)."""
+    i = 0
+    while i < len(s):
+        if s[i] == "#" and (i == 0 or s[i - 1] != "\\"):
+            return s[:i].rstrip()
+        i += 1
+    return s.rstrip()
+
+
+_DEFINE_RE = re.compile(r"^define\s+([A-Za-z_][A-Za-z0-9_]*)\s*$")
+
+
+class _State(Enum):
+    NORMAL = auto()
+    RECIPE = auto()
+    SYSTEM_BLOCK = auto()
+    TOOL_BLOCK = auto()
+    DEFINE = auto()
+
+
+def parse(text: str) -> Makefile:
+    """Parse Makefile text and return a structured :class:`Makefile` object."""
+    result = Makefile()
+    state = _State.NORMAL
+    current_recipes: list[str] | None = None
+    pending_description: str | None = None
+    pending_params: list[Param] = []
+    system_lines: list[str] = []
+    tool_lines: list[str] = []
+    tool_params: list[Param] = []
+    phony_targets: set[str] = set()
+    define_name: str = ""
+    define_lines: list[str] = []
+
+    # Join line continuations (backslash-newline → space), but only outside
+    # define blocks (define block content is literal).
+    raw_lines = text.splitlines()
+    logical_lines: list[str] = []
+    buf = ""
+    in_define = False
+    for raw in raw_lines:
+        stripped_raw = raw.strip()
+        if not in_define and _DEFINE_RE.match(stripped_raw):
+            if buf:
+                logical_lines.append(buf)
+                buf = ""
+            logical_lines.append(raw)
+            in_define = True
+        elif in_define:
+            logical_lines.append(raw)
+            if stripped_raw == "endef":
+                in_define = False
+        elif raw.endswith("\\"):
+            buf += raw[:-1] + " "
+        else:
+            logical_lines.append(buf + raw)
+            buf = ""
+    if buf:
+        logical_lines.append(buf)
+
+    for line in logical_lines:
+        # ── Inside a define block ────────────────────────────────────────────
+        if state == _State.DEFINE:
+            if line.strip() == "endef":
+                value = "\n".join(define_lines)
+                result.variables[define_name] = Variable(name=define_name, value=value, flavor="define")
+                if define_name == "SYSTEM_PROMPT":
+                    result.system_prompt = value.strip() or None
+                state = _State.NORMAL
+            else:
+                define_lines.append(line)
+            continue
+
+        # Recipe lines must start with a tab
+        if line.startswith("\t"):
+            if state == _State.RECIPE and current_recipes is not None:
+                current_recipes.append(line[1:])  # strip the leading tab
+            continue
+
+        # A non-tab line ends recipe collection.
+        # Exception: plain comment lines (not special block tags) are ignored by
+        # GNU Make inside a rule body and should not end recipe collection.
+        if state == _State.RECIPE:
+            stripped_peek = line.strip()
+            if stripped_peek.startswith("#") and stripped_peek not in ("# <tool>", "# <system>", "# </tool>", "# </system>"):
+                continue
+            state = _State.NORMAL
+            current_recipes = None
+
+        stripped = line.strip()
+
+        # ── Inside a special comment block ──────────────────────────────────
+        if state == _State.SYSTEM_BLOCK:
+            if stripped == "# </system>":
+                # Only set system_prompt from # <system> if not already set by define
+                if result.system_prompt is None:
+                    result.system_prompt = "\n".join(system_lines).strip() or None
+                state = _State.NORMAL
+            elif stripped.startswith("# "):
+                system_lines.append(stripped[2:])
+            elif stripped == "#":
+                system_lines.append("")
+            continue
+
+        if state == _State.TOOL_BLOCK:
+            if stripped == "# </tool>":
+                pending_description = "\n".join(tool_lines).strip() or None
+                pending_params = tool_params
+                tool_lines = []
+                tool_params = []
+                state = _State.NORMAL
+            elif stripped.startswith("# "):
+                content = stripped[2:]
+                param_m = _PARAM_RE.match(content)
+                if param_m:
+                    tool_params.append(Param(
+                        name=param_m.group(1),
+                        type=param_m.group(2),
+                        description=param_m.group(3).strip(),
+                    ))
+                else:
+                    tool_lines.append(content)
+            elif stripped == "#":
+                tool_lines.append("")
+            continue
+
+        # ── Block-opening tags ───────────────────────────────────────────────
+        if stripped == "# <system>":
+            system_lines = []
+            state = _State.SYSTEM_BLOCK
+            continue
+
+        if stripped == "# <tool>":
+            tool_lines = []
+            tool_params = []
+            state = _State.TOOL_BLOCK
+            continue
+
+        # ── Skip regular comments and blank lines ────────────────────────────
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # ── define/endef block ───────────────────────────────────────────────
+        define_m = _DEFINE_RE.match(stripped)
+        if define_m:
+            define_name = define_m.group(1)
+            define_lines = []
+            state = _State.DEFINE
+            continue
+
+        # ── .PHONY declaration ───────────────────────────────────────────────
+        phony_m = _PHONY_RE.match(stripped)
+        if phony_m:
+            new_phonies = phony_m.group(1).split()
+            phony_targets.update(new_phonies)
+            for rule in result.rules:
+                if rule.target in phony_targets:
+                    rule.is_phony = True
+            continue
+
+        # ── Variable assignment ──────────────────────────────────────────────
+        var_m = _VARIABLE_RE.match(line.rstrip())
+        if var_m:
+            name = var_m.group(1)
+            op = var_m.group(2).strip()
+            raw_val = _strip_comment(var_m.group(3))
+            expanded = _expand_vars(raw_val, result.variables)
+            flavor = _FLAVOR_MAP.get(op, "recursive")
+            if op == "+=" and name in result.variables:
+                result.variables[name].value = (result.variables[name].value + " " + expanded).strip()
+            else:
+                result.variables[name] = Variable(name=name, value=expanded, flavor=flavor)
+            continue
+
+        # ── Target rule ──────────────────────────────────────────────────────
+        target_m = _TARGET_RE.match(line.rstrip())
+        if target_m:
+            targets_str = target_m.group(1).strip()
+            prereqs_str = _strip_comment(target_m.group(2) or "")
+            targets = [_expand_vars(t, result.variables) for t in targets_str.split()]
+            prereqs = [_expand_vars(p, result.variables) for p in prereqs_str.split()]
+            shared_recipes: list[str] = []
+            for i, target in enumerate(targets):
+                rule = Rule(
+                    target=target,
+                    prerequisites=prereqs,
+                    recipes=shared_recipes,
+                    is_phony=target in phony_targets,
+                    description=pending_description if i == 0 else None,
+                    params=pending_params if i == 0 else [],
+                )
+                result.rules.append(rule)
+                if result.default_target is None and not target.startswith("."):
+                    result.default_target = target
+            pending_description = None
+            pending_params = []
+            state = _State.RECIPE
+            current_recipes = shared_recipes
+
+    return result
+
+
+def parse_file(path: str | Path) -> Makefile:
+    """Parse a Makefile from disk."""
+    return parse(Path(path).read_text(encoding="utf-8"))
+
+
+# Matches $(NAME), ${NAME}, or $$NAME in recipe text.
+# The optional ``value `` prefix handles the ``$(value NAME)`` raw-literal form.
+_RECIPE_VAR_RE = re.compile(r"\$\((?:value\s+)?([^)]+)\)|\$\{(?:value\s+)?([^}]+)\}|\$\$(\w+)")
+
+
+def validate(makefile: Makefile) -> list[str]:
+    """Check that every ``@param NAME`` is referenced in the rule's recipe body.
+
+    Accepts ``$(NAME)``, ``${NAME}``, ``$$NAME``, or ``$(NAME_FILE)`` /
+    ``${NAME_FILE}`` / ``$$NAME_FILE`` as valid references.  The ``_FILE``
+    form is always available at runtime (a temp file is written for every
+    parameter) so either convention is valid in a recipe.
+
+    Returns a list of human-readable error strings (empty list means valid).
+    """
+    errors: list[str] = []
+    for rule in makefile.rules:
+        if not rule.params:
+            continue
+        recipe_text = "\n".join(rule.recipes)
+        used_vars = {m.group(1) or m.group(2) or m.group(3) for m in _RECIPE_VAR_RE.finditer(recipe_text)}
+        for param in rule.params:
+            file_var = f"{param.name}_FILE"
+            if param.name not in used_vars and file_var not in used_vars:
+                errors.append(
+                    f"Tool '{rule.target}': @param {param.name} declared but never "
+                    f"referenced in recipe.\n"
+                    f"  Expected $({param.name}), ${{{param.name}}}, $${param.name}, "
+                    f"or $({file_var}) in the recipe body."
+                )
+    return errors
+
+
+def validate_or_raise(makefile: Makefile) -> None:
+    """Like :func:`validate` but raises :exc:`ValueError` if any errors are found."""
+    errors = validate(makefile)
+    if errors:
+        raise ValueError("\n".join(errors))

make_agent/settings.py

@@ -0,0 +1,92 @@
+"""Per-project settings stored in ``~/.make-agent/<project>/settings.yaml``.
+
+Supported fields::
+
+    model: anthropic/claude-haiku-4-5-20251001
+    makefile: ./Makefile
+
+Fields present in the file act as defaults; CLI flags always take precedence.
+Missing fields are simply ignored — settings are always partial.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from make_agent.app_dirs import default_agents_dir, settings_file
+
+_DEFAULT_MODEL = "anthropic/claude-haiku-4-5-20251001"
+_DEFAULT_MAKEFILE = "Makefile"
+_ORCHESTRA_TEMPLATE = Path(__file__).parent / "templates" / "orchestra.mk"
+
+
+def load_settings(cwd: str | None = None) -> dict[str, Any] | None:
+    """Load settings from ``~/.make-agent/<project>/settings.yaml``.
+
+    Returns the parsed dict, or ``None`` if the file does not exist.
+    Unknown keys are silently ignored.
+    """
+    path = settings_file(cwd)
+    if not path.exists():
+        return None
+    text = path.read_text(encoding="utf-8")
+    data = yaml.safe_load(text)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"Invalid settings file {path}: expected a YAML mapping, "
+            f"got {type(data).__name__}. Please check your settings.yaml."
+        )
+    return {k: v for k, v in data.items() if k in ("model", "makefile", "memory", "agent_model")}
+
+
+def save_settings(data: dict[str, Any], cwd: str | None = None) -> None:
+    """Write *data* to ``~/.make-agent/<project>/settings.yaml``."""
+    path = settings_file(cwd)
+    path.write_text(yaml.dump(data, default_flow_style=False, allow_unicode=True), encoding="utf-8")
+
+
+def run_setup_wizard() -> dict[str, Any]:
+    """Interactively ask the user for project settings, save and return them.
+
+    If the agents directory is empty, copies the bundled ``orchestra.mk``
+    template there and uses it as the makefile (no prompt for the path).
+    Otherwise prompts for a Makefile path.
+
+    Always prompts for the model string.
+    """
+    print("\nNo settings.yaml found for this project.")
+    print("Let's create one. Press Enter to accept the default shown in brackets.\n")
+
+    agents_dir = Path(default_agents_dir())
+    existing_agents = list(agents_dir.glob("*.mk"))
+
+    if not existing_agents:
+        dest = agents_dir / "orchestra.mk"
+        dest.write_bytes(_ORCHESTRA_TEMPLATE.read_bytes())
+        makefile = str(dest)
+        print(f"  Created {dest}")
+    else:
+        print("  Available agents:")
+        for i, agent in enumerate(existing_agents, 1):
+            print(f"    {i}) {agent.name}")
+        while True:
+            raw = input(f"  Choose an agent [1-{len(existing_agents)}]: ").strip()
+            if raw.isdigit() and 1 <= int(raw) <= len(existing_agents):
+                makefile = str(existing_agents[int(raw) - 1])
+                break
+            print(f"  Please enter a number between 1 and {len(existing_agents)}.")
+
+    raw_model = input(f"  Model [{_DEFAULT_MODEL}]: ").strip()
+    model = raw_model or _DEFAULT_MODEL
+
+    settings: dict[str, Any] = {"makefile": makefile, "model": model}
+    save_settings(settings)
+
+    path = settings_file()
+    print(f"\nSaved settings to {path}\n")
+    return settings

make_agent/templates/orchestra.mk

@@ -0,0 +1,99 @@
+define SYSTEM_PROMPT
+You are an orchestrator agent that manages a library of specialist agents.
+Specialist agents live as Makefile files in the agents directory.
+Each agent has a focused set of tools for a specific domain.
+
+You have three built-in tools available at all times:
+
+- list_agent   — discover available specialist agents and their descriptions
+- create_agent — create or overwrite a specialist agent from a YAML spec
+- run_agent    — delegate a task to a specialist agent and get its output
+
+Your workflow for every task:
+1. Call list_agent to discover available specialists.
+2. If a suitable agent exists, call run_agent to delegate the task.
+3. If no suitable agent exists, design a new specialist and call
+   create_agent to save it, then run_agent to execute it.
+4. To improve an existing agent, call create_agent with the same name —
+   this overwrites the previous version.
+
+When creating a new agent, pass a YAML spec with this structure:
+
+  system_prompt: "You are a specialist that ..."
+  tools:
+    - name: tool-name
+      description: What this tool does.
+      params:
+        - name: PARAM
+          type: string
+          description: The param purpose
+      recipe:
+        - "@shell command $(PARAM)"
+
+"params" may be omitted for tools that take no arguments.
+"type" must be one of: string, number, integer, boolean.
+Each "recipe" entry becomes one shell line in the Makefile target.
+For multiline values or values with shell metacharacters, use $(PARAM_FILE)
+instead of $(PARAM) in the recipe — a temp file with the full value is
+always available as $(PARAM_FILE) for every declared parameter.
+
+CRITICAL: every param listed in "params" MUST be referenced as $(PARAM_NAME)
+or $(PARAM_NAME_FILE) in the recipe. A param declared but absent from the
+recipe will cause an error.
+
+Example of a correct two-param tool:
+
+  system_prompt: "You are a search specialist."
+  tools:
+    - name: search-files
+      description: Search files for a pattern in a directory.
+      params:
+        - name: PATTERN
+          type: string
+          description: Search pattern (regex)
+        - name: DIR
+          type: string
+          description: Directory to search in
+      recipe:
+        - '@grep -rn "$(PATTERN)" "$(DIR)" || echo "No matches found"'
+
+Each agent should report errors by echoing a message that starts with "ERROR:" — this is how you detect failure. Include this in system prompts and encourage agents to use it for error handling.
+Each agent should always ask you for help if they are unsure about how to complete a task, rather than making assumptions or taking random actions. Include this in system prompts to encourage it.
+Always return useful information from the agent, even in case of errors. The orchestrator will relay this back to the user.
+Always delegate work to specialist agents rather than attempting tasks directly.
+Always check if a suitable specialist exists before creating a new one.
+Always create a plan for completing the task and provide it to the user to confirm before executing any steps. The plan should include which agents you intend to use and how.
+
+## Memory tools (available when --with-memory is enabled)
+
+- get_recent_messages(limit, from_date, to_date) — fetch the N most recent messages; use this first to orient yourself at the start of a session
+- search_user_memory(query, limit, from_date, to_date) — FTS5 keyword search over past user messages
+- search_agent_memory(query, limit, from_date, to_date) — FTS5 keyword search over past agent replies
+
+All date parameters accept ISO 8601 strings (e.g. '2026-03-01'). All parameters are optional.
+FTS5 tips:
+- Use short keywords, not full sentences: "goal project" not "what is the goal of this project"
+- Use OR for broader recall: "goal OR objective OR purpose"
+- Stop words (the, of, is, a) are not indexed — omit them
+- If a search returns nothing, retry with broader or alternative keywords
+endef
+
+.PHONY: current-dir os-info current-date
+
+# <tool>
+# Return the current working directory path.
+# </tool>
+current-dir:
+	@pwd
+
+# <tool>
+# Return operating system and kernel information.
+# </tool>
+os-info:
+	@uname -a
+
+# <tool>
+# Return the current date and time.
+# </tool>
+current-date:
+	@date