Skip to content

Preflight

preflight

Preflight hook action.

Runs git status --porcelain and git diff -U2 to report working-tree state before a protocol phase.

PreflightHook dataclass

Report working-tree status and diff as a pre-hook.

Designed for injection into protocol briefings via inject_result + inline: true.

params: path — project root (default "."). diff_lines — max diff lines (default 200, 0 to disable).

Source code in packages/axm-git/src/axm_git/hooks/preflight.py
Python
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
@dataclass
class PreflightHook:
    """Report working-tree status and diff as a pre-hook.

    Designed for injection into protocol briefings via
    ``inject_result`` + ``inline: true``.

    *params*:
        ``path`` — project root (default ``"."``).
        ``diff_lines`` — max diff lines (default 200, 0 to disable).
    """

    def execute(self, context: dict[str, object], **params: object) -> HookResult:
        """Execute the hook action.

        Args:
            context: Session context dictionary.
            **params: Optional ``path`` and ``diff_lines``.

        Returns:
            HookResult with a compact ``text`` render (via ``render_text``)
            and metadata containing ``files``, ``diff``, ``file_count``,
            and ``clean``.
        """
        if not params.get("enabled", True):
            return HookResult.ok(skipped=True, reason="git disabled")

        working_dir = resolve_working_dir(params, context, param_key="path").resolve()
        max_diff_lines = int(cast("int | str", params.get("diff_lines", 200)))

        git_root = find_git_root(working_dir)
        if git_root is None:
            return HookResult.ok(skipped=True, reason="not a git repo")

        pathspec = _compute_pathspec(working_dir, git_root)

        status = run_git(["status", "--porcelain", *pathspec], git_root)
        if status.returncode != 0:
            return HookResult.fail(f"git status failed: {status.stderr}")

        files = _collect_status_files(status.stdout)
        diff_stat_out = _collect_diff_stat(git_root, pathspec)
        diff_content, diff_truncated = _collect_diff(git_root, pathspec, max_diff_lines)

        rendered = render_text(
            files=files,
            diff_stat=diff_stat_out,
            diff=diff_content,
            diff_truncated=diff_truncated,
            max_diff_lines=max_diff_lines,
        )

        return HookResult(
            success=True,
            text=rendered,
            metadata={
                "files": files,
                "diff": diff_content,
                "file_count": len(files),
                "clean": len(files) == 0,
            },
        )
execute(context, **params)

Execute the hook action.

Parameters:

Name Type Description Default
context dict[str, object]

Session context dictionary.

 required
**params object

Optional path and diff_lines.

 {}

Returns:

Type Description
HookResult

HookResult with a compact text render (via render_text)
HookResult

and metadata containing files, diff, file_count,
HookResult

and clean.
Source code in packages/axm-git/src/axm_git/hooks/preflight.py
Python
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def execute(self, context: dict[str, object], **params: object) -> HookResult:
    """Execute the hook action.

    Args:
        context: Session context dictionary.
        **params: Optional ``path`` and ``diff_lines``.

    Returns:
        HookResult with a compact ``text`` render (via ``render_text``)
        and metadata containing ``files``, ``diff``, ``file_count``,
        and ``clean``.
    """
    if not params.get("enabled", True):
        return HookResult.ok(skipped=True, reason="git disabled")

    working_dir = resolve_working_dir(params, context, param_key="path").resolve()
    max_diff_lines = int(cast("int | str", params.get("diff_lines", 200)))

    git_root = find_git_root(working_dir)
    if git_root is None:
        return HookResult.ok(skipped=True, reason="not a git repo")

    pathspec = _compute_pathspec(working_dir, git_root)

    status = run_git(["status", "--porcelain", *pathspec], git_root)
    if status.returncode != 0:
        return HookResult.fail(f"git status failed: {status.stderr}")

    files = _collect_status_files(status.stdout)
    diff_stat_out = _collect_diff_stat(git_root, pathspec)
    diff_content, diff_truncated = _collect_diff(git_root, pathspec, max_diff_lines)

    rendered = render_text(
        files=files,
        diff_stat=diff_stat_out,
        diff=diff_content,
        diff_truncated=diff_truncated,
        max_diff_lines=max_diff_lines,
    )

    return HookResult(
        success=True,
        text=rendered,
        metadata={
            "files": files,
            "diff": diff_content,
            "file_count": len(files),
            "clean": len(files) == 0,
        },
    )

truncate_diff(stdout, max_lines)

Truncate diff output to max_lines.

Returns the first max_lines lines joined by newlines, or the stripped original when it fits. Returns an empty string when max_lines is 0.

Source code in packages/axm-git/src/axm_git/hooks/preflight.py
Python
24
25
26
27
28
29
30
31
32
33
34
35
36
def truncate_diff(stdout: str, max_lines: int) -> str:
    """Truncate diff output to *max_lines*.

    Returns the first *max_lines* lines joined by newlines,
    or the stripped original when it fits.  Returns an empty
    string when *max_lines* is ``0``.
    """
    if max_lines <= 0:
        return ""
    lines = stdout.splitlines()
    if len(lines) > max_lines:
        return "\n".join(lines[:max_lines])
    return stdout.strip()