agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/cli_commands/evidence.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.evidence_clean import check_clean_except_expected_log, clean_local_evidence
+from agentic_project_kit.evidence_commit_paths import commit_paths
+from agentic_project_kit.evidence_commit_paths import render_commit_paths_result
+from agentic_project_kit.evidence_finalize_log import finalize_log
+from agentic_project_kit.evidence_finalize_log import render_finalize_log_error
+from agentic_project_kit.evidence_finalize_log import render_finalize_log_result
+from agentic_project_kit.evidence_guard import check_change_scope
+from agentic_project_kit.evidence_guard import check_terminal_log
+from agentic_project_kit.evidence_inspector import classify_log
+from agentic_project_kit.evidence_inspector import inspect_evidence
+from agentic_project_kit.evidence_inspector import render_evidence_inspection
+from agentic_project_kit.evidence_inspector import render_log_classification
+
+app = typer.Typer(help="Validate terminal evidence logs.")
+
+
+@app.command("guard")
+def guard(logfile: Path) -> None:
+    """Fail if a terminal evidence log has contradictory final state."""
+    result = check_terminal_log(logfile)
+    status = "PASS" if result.ok else "FAIL"
+    typer.echo(f"{status}: {result.path} final_result={result.final_result}")
+    for finding in result.findings:
+        typer.echo(f"  - {finding}")
+    if not result.ok:
+        raise typer.Exit(1)
+
+
+@app.command("inspect")
+def inspect(
+    path: Path | None = typer.Argument(None),
+    root: Path = typer.Option(Path("."), "--root"),
+    require_summary: bool = typer.Option(False, "--require-summary"),
+) -> None:
+    """Inspect explicit or latest terminal evidence before continuing after chat control signals."""
+    result = inspect_evidence(path, root=root, require_summary=require_summary)
+    typer.echo(render_evidence_inspection(result))
+    if not result.success:
+        raise typer.Exit(code=1)
+
+
+@app.command("classify-log")
+def classify_log_command(
+    path: Path | None = typer.Argument(None),
+    root: Path = typer.Option(Path("."), "--root"),
+    require_summary: bool = typer.Option(False, "--require-summary"),
+    ignore_git_status: bool = typer.Option(False, "--ignore-git-status"),
+) -> None:
+    """Classify a terminal/evidence log for deterministic gatekeeper decisions."""
+    result = classify_log(
+        path,
+        root=root,
+        require_summary=require_summary,
+        check_git_status=not ignore_git_status,
+    )
+    typer.echo(render_log_classification(result))
+    if not result.success:
+        raise typer.Exit(code=1)
+
+
+@app.command("finalize-log")
+def finalize_log_command(
+    run_log: Path = typer.Option(..., "--run-log"),
+    remote_log: Path = typer.Option(..., "--remote-log"),
+    slice_name: str = typer.Option(..., "--slice"),
+    scope: str = typer.Option(..., "--scope"),
+    mode_check: str = typer.Option(..., "--mode-check"),
+    work: str = typer.Option("PASS", "--work"),
+    evidence: str = typer.Option("PASS", "--evidence"),
+    overall: str = typer.Option("PASS", "--overall"),
+    remote_evidence: str = typer.Option("NOT_REQUIRED", "--remote-evidence"),
+    pr: str = typer.Option("NONE", "--pr"),
+    ci: str = typer.Option("not-required", "--ci"),
+    merge: str = typer.Option("not-required", "--merge"),
+    command_report: str = typer.Option(..., "--command-report"),
+    interpretation: str = typer.Option(..., "--interpretation"),
+    safe_step: str = typer.Option(..., "--safe-step"),
+    chat_reply: str = typer.Option("d", "--next"),
+    origin: str = typer.Option("local", "--origin"),
+    state_mode: str = typer.Option("local", "--state-mode"),
+    comm_id: str = typer.Option("COMM-LOCAL", "--comm-id"),
+    commit_message: str | None = typer.Option(None, "--commit-message"),
+    push: bool = typer.Option(False, "--push"),
+    required_branch: str = typer.Option("", "--branch", help="Expected branch for finalize-log commits."),
+    allow_main: bool = typer.Option(False, "--allow-main", help="Allow finalize-log to commit on main."),
+    root: Path = typer.Option(Path("."), "--root"),
+) -> None:
+    """Append a canonical summary, require strict inspection, then upload the evidence log."""
+    try:
+        result = finalize_log(
+            root=root,
+            run_log=run_log,
+            remote_log=remote_log,
+            slice_name=slice_name,
+            scope=scope,
+            mode_check=mode_check,
+            work=work,
+            evidence=evidence,
+            overall=overall,
+            remote_evidence=remote_evidence,
+            pr=pr,
+            ci=ci,
+            merge=merge,
+            command_report=command_report,
+            interpretation=interpretation,
+            safe_step=safe_step,
+            chat_reply=chat_reply,
+            origin=origin,
+            state_mode=state_mode,
+            comm_id=comm_id,
+            commit_message=commit_message,
+            push=push,
+            required_branch=required_branch,
+            allow_main=allow_main,
+        )
+    except (ValueError, FileNotFoundError) as exc:
+        typer.echo(render_finalize_log_error(str(exc)))
+        raise typer.Exit(code=1) from None
+    typer.echo(render_finalize_log_result(result))
+    if not result.success:
+        raise typer.Exit(code=1)
+
+
+@app.command("commit-paths")
+def commit_paths_command(
+    path: list[str] = typer.Option([], "--path", help="Repository-relative path to commit. Repeat for multiple paths."),
+    message: str = typer.Option(..., "--message"),
+    log_path: str | None = typer.Option(None, "--log-path"),
+    push: bool = typer.Option(False, "--push"),
+    required_branch: str = typer.Option("", "--branch", help="Expected branch for evidence commit-paths commits."),
+    allow_main: bool = typer.Option(False, "--allow-main", help="Allow evidence commit-paths to commit on main."),
+    root: Path = typer.Option(Path("."), "--root"),
+) -> None:
+    """Commit an explicit evidence path set and verify the worktree is clean afterwards."""
+    try:
+        result = commit_paths(
+            root=root,
+            paths=tuple(path),
+            message=message,
+            log_path=log_path,
+            push=push,
+            required_branch=required_branch,
+            allow_main=allow_main,
+        )
+    except ValueError as exc:
+        typer.echo("EVIDENCE_COMMIT_PATHS")
+        typer.echo("success=no")
+        typer.echo(f"finding={exc}")
+        typer.echo("### RESULT: FAIL ###")
+        raise typer.Exit(code=1) from None
+    typer.echo(render_commit_paths_result(result))
+    if not result.success:
+        raise typer.Exit(code=1)
+
+
+@app.command("scope-check")
+def scope_check(
+    changed: list[str] = typer.Option([], "--changed", help="Changed repository path. Repeat for multiple paths."),
+    expected: list[str] = typer.Option([], "--expected", help="Expected target path. Repeat for multiple paths."),
+) -> None:
+    """Fail if expected target paths are missing from a change set."""
+    result = check_change_scope(changed_paths=changed, expected_paths=expected)
+    status = "PASS" if result.ok else "FAIL"
+    typer.echo(f"{status}: change scope check")
+    typer.echo("changed_paths=" + ", ".join(result.changed_paths))
+    typer.echo("expected_paths=" + ", ".join(result.expected_paths))
+    for finding in result.findings:
+        typer.echo(f"  - {finding}")
+    if not result.ok:
+        raise typer.Exit(1)
+
+
+@app.command("clean-check")
+def clean_check(expected_log: str = typer.Argument(...), root: Path = typer.Option(Path("."), "--root")) -> None:
+    """Pass when git status is clean except one expected in-progress log."""
+    result = check_clean_except_expected_log(root.resolve(), expected_log)
+    if result.ok:
+        typer.echo("PASS: worktree clean except expected log: " + result.expected_log)
+        return
+    typer.echo("FAIL: worktree dirty beyond expected log: " + result.expected_log)
+    for line in result.unexpected_lines:
+        typer.echo(line)
+    raise typer.Exit(code=1)
+
+
+@app.command("clean")
+def clean(root: Path = typer.Option(Path("."), "--root")) -> None:
+    """Clean local evidence according to repo policy."""
+    result = clean_local_evidence(root.resolve())
+
+    typer.echo("\n\n\n")
+    typer.echo("-------------------------------------------------------------------------")
+    typer.echo("-------------------------------------------------------------------------")
+    typer.echo("-------------------------------------------------------------------------")
+    typer.echo("\n\n\n")
+    typer.echo("NS CLEAN EVIDENCE")
+
+    typer.echo("\n### SAFETY ###")
+    typer.echo(
+        "Safety: removes ignored tmp evidence and restores known tracked workflow evidence only; "
+        "does not delete arbitrary docs/reports files."
+    )
+
+    typer.echo("\n### BEFORE STATUS ###")
+    if result.before_status:
+        for line in result.before_status:
+            typer.echo(line)
+    else:
+        typer.echo("clean")
+
+    typer.echo("\n### RESTORE KNOWN TRACKED WORKFLOW EVIDENCE ###")
+    for line in result.restore_lines:
+        typer.echo(line)
+
+    typer.echo("\n### REMOVE IGNORED TMP EVIDENCE ###")
+    if result.removed_tmp_evidence:
+        typer.echo("remove_ignored_dir=tmp/agent-evidence")
+    else:
+        typer.echo("no_ignored_tmp_evidence=tmp/agent-evidence")
+
+    typer.echo("\n### UNTRACKED DOC REPORTS REVIEW ###")
+    if result.untracked_doc_reports:
+        for line in result.untracked_doc_reports:
+            typer.echo(line)
+        typer.echo("NEEDS_HUMAN_REVIEW: untracked docs/reports files were not deleted automatically.")
+    else:
+        typer.echo("No untracked docs/reports files found.")
+
+    if result.errors:
+        typer.echo("\n### ERRORS ###")
+        for line in result.errors:
+            typer.echo(line)
+
+    typer.echo("\n### AFTER STATUS ###")
+    if result.after_status:
+        for line in result.after_status:
+            typer.echo(line)
+    else:
+        typer.echo("clean")
+
+    if result.ok:
+        typer.echo("\n### RESULT: PASS ###")
+        return
+    typer.echo("\n### RESULT: FAIL ###")
+    raise typer.Exit(code=1)

agentic_project_kit/cli_commands/github.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.prompt import Confirm
+
+from agentic_project_kit.github import create_github_repo
+
+console = Console()
+
+
+def register_github_commands(app: typer.Typer) -> None:
+    app.command(
+        "github-create",
+        help="Create and push a GitHub repository for an initialized project.",
+    )(github_create_command)
+
+
+def github_create_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    owner: str | None = typer.Option(None, "--owner"),
+    visibility: str = typer.Option("private", "--visibility"),
+) -> None:
+    if visibility not in {"private", "public"}:
+        raise typer.BadParameter("visibility must be private or public")
+    if visibility == "public":
+        console.print("[bold yellow]Public repository selected. Check for secrets before continuing.[/bold yellow]")
+        if not Confirm.ask("Continue?", default=False):
+            raise typer.Exit(code=1)
+
+    create_github_repo(project_root.resolve(), owner=owner, visibility=visibility, push=True)
+    console.print("[green]GitHub repository created and pushed.[/green]")

agentic_project_kit/cli_commands/governance.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import typer
+
+from agentic_project_kit.governance import governance_check, render_governance_check
+
+governance_app = typer.Typer(help="Run deterministic project governance checks.")
+
+@governance_app.command("check")
+def check_command() -> None:
+    errors = governance_check()
+    typer.echo(render_governance_check(errors))
+    if errors:
+        raise typer.Exit(code=1)

agentic_project_kit/cli_commands/gui.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.gui_task_editor import build_initial_llm_prompt
+
+
+gui_app = typer.Typer(help="Render GUI-facing prompts and helper metadata.")
+
+
+@gui_app.command("initial-llm-prompt")
+def initial_llm_prompt(
+    root: Path = typer.Option(Path("."), "--root", help="Project root whose GUI prompt should be rendered."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    result = build_initial_llm_prompt(project_root=root)
+    if json_output:
+        typer.echo(json.dumps(result.as_json_data(), indent=2, sort_keys=True))
+    else:
+        typer.echo(result.prompt_text)

agentic_project_kit/cli_commands/gui_readiness_gate.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit import __version__ as PACKAGE_VERSION
+from agentic_project_kit.gui_readiness_gate import (
+    evaluate_gui_readiness,
+    render_gui_readiness_gate,
+)
+
+
+def gui_readiness_gate_command(
+    root: Path = typer.Option(Path("."), "--root"),
+    version: str = typer.Option(PACKAGE_VERSION, "--version"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Run the pre-GUI readiness gate."""
+    result = evaluate_gui_readiness(root.resolve(), version=version)
+    if json_output:
+        typer.echo(json.dumps(result.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_gui_readiness_gate(result), nl=False)
+    if not result.ok:
+        raise typer.Exit(code=result.returncode)

agentic_project_kit/cli_commands/handoff.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import subprocess
+
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from agentic_project_kit.documentation_registry import build_documentation_registry_summary
+from agentic_project_kit.handoff_freshness import (
+    assess_handoff_prompt_freshness,
+    render_freshness_guard,
+)
+from agentic_project_kit.handoff_prompt import render_handoff_prompt
+from agentic_project_kit.handoff_state import (
+    current_git_safe_state,
+    load_handoff_state,
+    refresh_handoff_safe_state,
+    save_handoff_state,
+    summarize_handoff_state,
+    validate_handoff_state,
+)
+
+from agentic_project_kit.post_merge_handoff_refresh import evaluate_post_merge_handoff_refresh, render_post_merge_handoff_refresh_status
+
+handoff_app = typer.Typer(help="Read-only persistent handoff state commands.")
+
+
+@handoff_app.command("show")
+def show(path: str = ".agentic/handoff_state.yaml") -> None:
+    data = load_handoff_state(path)
+    typer.echo(summarize_handoff_state(data))
+
+
+@handoff_app.command("check")
+def check(path: str = ".agentic/handoff_state.yaml") -> None:
+    data = load_handoff_state(path)
+    errors = validate_handoff_state(data)
+    if errors:
+        for error in errors:
+            typer.echo(f"[FAIL] {error}")
+        raise typer.Exit(code=1)
+    typer.echo("Persistent handoff state check passed")
+    registry_lines = _render_registry_summary(path)
+    if registry_lines:
+        typer.echo(registry_lines)
+
+
+@handoff_app.command("prompt")
+def prompt(
+    path: str = ".agentic/handoff_state.yaml",
+    intended_output: Annotated[
+        str | None,
+        typer.Option(
+            "--intended-output",
+            help="Prompt path that this render will write after generation.",
+        ),
+    ] = None,
+) -> None:
+    data = load_handoff_state(path)
+    errors = validate_handoff_state(data)
+    if errors:
+        for error in errors:
+            typer.echo(f"[FAIL] {error}")
+        raise typer.Exit(code=1)
+    rendered_prompt = render_handoff_prompt(data)
+    guard = render_freshness_guard(
+        assess_handoff_prompt_freshness(
+            data,
+            path,
+            successor_prompt_text=rendered_prompt,
+            intended_successor_prompt_path=intended_output,
+        )
+    )
+    if guard:
+        typer.echo(guard, nl=False)
+    typer.echo(rendered_prompt, nl=False)
+
+
+@handoff_app.command("refresh")
+def refresh(
+    path: Annotated[str, typer.Argument()] = ".agentic/handoff_state.yaml",
+    write: bool = typer.Option(False, "--write", help="Write refreshed safe_state to YAML."),
+) -> None:
+    data = load_handoff_state(path)
+    git_state = current_git_safe_state()
+    refreshed = refresh_handoff_safe_state(
+        data,
+        git_state["commit"],
+        git_state["commit_subject"],
+    )
+    errors = validate_handoff_state(refreshed)
+    if errors:
+        for error in errors:
+            typer.echo(f"[FAIL] {error}")
+        raise typer.Exit(code=1)
+    current = data.get("safe_state", {})
+    updated = refreshed.get("safe_state", {})
+    typer.echo(f"Current safe_state: {current.get('commit')} {current.get('commit_subject')}")
+    typer.echo(f"Refreshed safe_state: {updated.get('commit')} {updated.get('commit_subject')}")
+    if write:
+        save_handoff_state(refreshed, path)
+        typer.echo(f"Updated {path}")
+    else:
+        typer.echo("Dry run only. Use --write to update the YAML file.")
+
+
+def _render_registry_summary(handoff_path: str) -> str:
+    summary = _load_registry_summary(handoff_path)
+    if summary is None:
+        return ""
+    lines = [
+        "Documentation registry:",
+        f"- registry: {summary['registry_path']}",
+        f"- version: {summary['version']}",
+        f"- documents: {summary['document_count']}",
+        f"- broad_migration_allowed: {summary['broad_migration_allowed']}",
+    ]
+    class_counts = summary.get("class_counts", {})
+    if isinstance(class_counts, dict):
+        for class_name, count in class_counts.items():
+            lines.append(f"- class:{class_name}: {count}")
+    return "\n".join(lines)
+
+
+def _load_registry_summary(handoff_path: str) -> dict[str, Any] | None:
+    project_root = _project_root_for_handoff_path(Path(handoff_path))
+    try:
+        return build_documentation_registry_summary(project_root)
+    except (OSError, ValueError):
+        return None
+
+
+def _project_root_for_handoff_path(path: Path) -> Path:
+    if path.name == "handoff_state.yaml" and path.parent.name == ".agentic":
+        return path.parent.parent
+    return Path.cwd()
+
+
+
+def _current_head_is_refresh_only_merge_commit() -> bool:
+    """Return true when current HEAD is a merged successor handoff refresh PR."""
+
+    completed = subprocess.run(
+        ["git", "log", "-1", "--pretty=%s"],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    if completed.returncode != 0:
+        return False
+    subject = completed.stdout.strip()
+    return (
+        (
+            subject.startswith("Refresh successor handoff after PR")
+            or subject.startswith("Refresh handoff state after PR")
+        )
+        and "(#" in subject
+        and subject.endswith(")")
+    )
+
+@handoff_app.command("post-merge-refresh-status")
+def post_merge_refresh_status() -> None:
+    status = evaluate_post_merge_handoff_refresh(Path("."))
+    refresh_only_merge_commit_is_fresh = (
+        status.refresh_required and _current_head_is_refresh_only_merge_commit()
+    )
+    if refresh_only_merge_commit_is_fresh:
+        typer.echo("POST_MERGE_HANDOFF_REFRESH")
+        typer.echo(f"current_head={status.current_head}")
+        typer.echo(f"freshness_warning_present={status.freshness_warning_present}")
+        typer.echo("refresh_required=False")
+        typer.echo(f"latest_successor_prompt={status.latest_successor_prompt}")
+        typer.echo("result=NOOP")
+        typer.echo("next_safe_action=none")
+        typer.echo("refresh_only_merge_commit_is_fresh=True")
+        return
+
+    typer.echo(render_post_merge_handoff_refresh_status(status), nl=False)
+    if status.refresh_required:
+        raise typer.Exit(1)