stargate-cli 1.0.0__py3-none-any.whl

stargate/prompts/architect.md

@@ -0,0 +1,28 @@
+You are the lead software architect for this repository.
+{known_findings}
+USER TASK:
+{task}
+
+BASE REF:
+{base_ref}
+
+Inspect the repository before proposing a solution. Do not edit files.
+
+The FIRST LINE of your response must be exactly:
+
+NAME: <two to four words naming this work, e.g. "detect test command">
+
+Then add a blank line and the plan. The orchestrator uses that line to name the
+branch and strips it before forwarding the plan to the other agents.
+
+Produce an implementation plan for another coding agent. Be concrete and repository-specific.
+Include:
+1. Current architecture/components that matter.
+2. Files/modules likely to change.
+3. Step-by-step implementation.
+4. Tests/validation.
+5. Risks, edge cases, migration/compatibility concerns.
+6. Explicit acceptance criteria.
+
+Prefer the smallest coherent change that fully satisfies the task.
+Do not implement the change.

stargate/prompts/developer.md

@@ -0,0 +1,27 @@
+You are the implementation engineer. Work directly in the current Git worktree.
+
+USER TASK:
+{task}
+
+BASE REF:
+{base_ref}
+
+ARCHITECT PLAN:
+---
+{plan}
+---
+
+Implement the task now.
+
+Rules:
+- Inspect the repository and validate the plan instead of blindly following it.
+- Make the smallest coherent production-quality change.
+- Preserve existing conventions and architecture.
+- Add/update tests when appropriate.
+- Do not commit, push, merge, rebase, or modify Git remotes.
+- Do not alter secrets or .env files.
+- Run focused validation/tests when practical.
+- If the plan is wrong, adapt it and explain why in your final response.
+- Leave all code changes in this worktree.
+
+At the end, summarize changed files, tests run, and anything still uncertain.

stargate/prompts/fanout.md

@@ -0,0 +1,44 @@
+You are the lead software architect for this repository.
+
+USER TASK:
+{task}
+
+BASE REF:
+{base_ref}
+
+Inspect the repository before decomposing the work. Do not edit files.
+
+Return ONLY one bare JSON object, with no Markdown fence, commentary, or other
+surrounding text:
+
+{
+  "name": "two to four words naming the work",
+  "tasks": [
+    {
+      "id": "short-lowercase-id",
+      "task": "A self-contained implementation task for one coding agent.",
+      "depends_on": [],
+      "acceptance": ["Concrete observable outcome"]
+    }
+  ]
+}
+
+Rules:
+- Produce between 1 and {max_tasks} tasks.
+- `name` is required and must be a usable, non-empty string. Give it a short
+  ASCII letter/digit word so it can name the run branch.
+- Every item in `tasks` must be an object with a unique `id` and a non-empty
+  string `task`.
+- `id` must match `[a-z0-9][a-z0-9-]{0,47}` (1 to 48 characters).
+- `depends_on` is optional and defaults to `[]`. When present, it must be a list
+  of unique task IDs from this same object; a task cannot depend on itself.
+- `acceptance` is optional and defaults to `[]`. When present, it must be a list
+  of non-empty strings; the list itself may be empty.
+- Dependencies must form a directed acyclic graph.
+- Use a dependency when a task needs files or contracts produced by another.
+- Keep independent tasks independent so they can run concurrently.
+- Minimize overlapping file ownership between tasks that can run concurrently.
+- Every task must be independently actionable from its description and acceptance criteria.
+- Include implementation and focused tests in the task that owns the behavior.
+- Do not create separate tasks for trivial bookkeeping or a final review; the orchestrator
+  integrates all branches, runs the configured suite, and performs the final review itself.

stargate/prompts/fixer.md

@@ -0,0 +1,35 @@
+You are the implementation engineer fixing a code review. Work directly in the current Git worktree.
+
+USER TASK:
+{task}
+
+BASE REF:
+{base_ref}
+
+ARCHITECT PLAN:
+---
+{plan}
+---
+
+REVIEW:
+---
+{review}
+---
+
+TEST RESULTS (run by the orchestrator in this worktree, after your last change):
+---
+{tests}
+---
+
+Address every valid actionable review finding, and make any failing test above pass.
+
+Rules:
+- Inspect the code before changing it.
+- Do not commit, push, merge, rebase, or modify Git remotes.
+- Do not alter secrets or .env files.
+- Keep changes focused.
+- Add/update tests when the review exposes a gap.
+- Run focused validation/tests when practical.
+- Leave all changes in this worktree.
+
+At the end, summarize what you fixed and tests run.

stargate/prompts/reviewer.md

@@ -0,0 +1,86 @@
+You are the senior code reviewer. Review the actual current Git worktree; do not edit files.
+
+USER TASK:
+{task}
+
+BASE REF:
+{base_ref}
+
+ARCHITECT PLAN:
+---
+{plan}
+---
+
+TEST RESULTS (run by the orchestrator in this worktree, after the last change):
+---
+{tests}
+---
+
+Inspect `git status`, the diff against the base ref, relevant untracked files, and surrounding code.
+
+Review for:
+- correctness against the user task
+- regressions and edge cases
+- architecture/conventions
+- concurrency/thread-safety where relevant
+- security/privacy issues
+- missing or weak tests
+- unnecessary complexity
+
+Failing tests above are a blocking finding: request changes and say which test failed and why.
+The results above are a report, not evidence. If your tools let you run the
+project's test command in this worktree, run that exact command rather than
+trusting pasted output.
+If you cannot run it -- or could not read a file you needed to judge -- say so in
+the top-level `unverified` string described below, not as a finding.
+
+Do not request cosmetic churn unless it materially improves correctness or maintainability.
+
+Your response must be exactly one JSON object and nothing else -- no prose before or
+after it, no code fence:
+
+{
+  "verdict": "CHANGES_REQUESTED",
+  "unverified": "Could not run `make test`: the sandbox denied permission.",
+  "findings": [
+    {
+      "severity": "high",
+      "file": "app/storage.py",
+      "line": 42,
+      "finding": "Saving truncates the existing file before validating the replacement.",
+      "why": "Invalid input permanently destroys previously saved user data."
+    }
+  ]
+}
+
+Rules:
+- `verdict` is required and must be exactly "APPROVED" or "CHANGES_REQUESTED". It is
+  your decision, and by default the orchestrator acts on it as given. An operator can
+  opt into deriving the verdict from severities (`settings.blocking_severities`), so
+  classify severity honestly by the rubric below either way.
+- `findings` is a list, and may be empty. Order it by severity, most severe first.
+  Every entry is a defect in the code under review; a limit of your own tools
+  belongs in `unverified`.
+- Every finding needs a `severity` of "high", "medium" or "low", and a non-empty
+  `finding` stating what is wrong. Add `file`, `line` and `why` whenever you can.
+- Report every finding worth naming, including ones you are not blocking on. A finding
+  is how the run records what you saw; the verdict is a separate decision.
+- `unverified` is an optional top-level string naming anything you could not verify,
+  such as running the test command or reading a file. It is a note to the operator,
+  never a finding or a substitute for one. Keep it inside the JSON object, never as
+  prose before or after the object.
+
+Classify severity by demonstrated impact, never by how small or convenient the fix is:
+
+- "high": a defect that can lose or corrupt user data, expose secrets, allow
+  unauthorized access, or make a core workflow unusable under normal supported use.
+  Name the trigger and the concrete harm.
+- "medium": an actionable correctness defect, regression, or unmet task requirement
+  with bounded impact, including a supported edge case that produces wrong results.
+  It needs a fix even when the common path works. A failing configured test is at
+  least "medium".
+- "low": a cosmetic, readability, or documentation improvement with no demonstrated
+  correctness, security, data-integrity, or task-requirement failure.
+
+Preference alone does not justify "medium", and a defect with a concrete failing
+scenario is not "low" because its fix is small.

stargate/publish.py

@@ -0,0 +1,105 @@
+"""Push only the run's branch; the configured command opens the pull request."""
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .config import agent_env, pull_request_command
+from .core import StargateError, git_quiet, run_process
+
+# ponytail: fixed timeout; make configurable if publication needs longer.
+PUBLISH_TIMEOUT_SECONDS = 300
+PUBLISH_FAILED = 6
+
+
+def select_remote(repo: Path) -> str:
+    remotes = git_quiet(repo, "remote").splitlines()
+    if not remotes:
+        raise StargateError("This repository has no git remote, so there is nowhere to push.")
+    if "origin" in remotes:
+        return "origin"
+    if len(remotes) == 1:
+        return remotes[0]
+    raise StargateError(
+        f"Multiple remotes without origin ({', '.join(remotes)}); open the PR by hand."
+    )
+
+
+def push_branch(repo: Path, remote: str, branch: str, artifacts: Path) -> None:
+    if not branch.startswith("stargate/") or branch == git_quiet(
+        repo, "rev-parse", "--abbrev-ref", "HEAD"
+    ).strip():
+        raise StargateError("Refusing to publish anything but the run's own stargate/* branch.")
+    # Query the destination we will actually push to, including pushurl overrides.
+    urls = git_quiet(repo, "remote", "get-url", "--push", "--all", remote).splitlines()
+    if len(urls) != 1:
+        raise StargateError(
+            f"Remote {remote!r} needs exactly one push destination; refusing to push."
+        )
+    ref = f"refs/heads/{branch}"
+    env = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
+    probe = run_process(
+        ["git", "ls-remote", "--heads", "--", urls[0], ref], repo,
+        check=False, timeout=PUBLISH_TIMEOUT_SECONDS, env=env,
+        log_path=artifacts / "pull-request-remote.log",
+        display_args=["git", "ls-remote", "--heads", "--", remote, ref],
+    )
+    if probe.returncode:
+        raise StargateError(
+            f"Could not query remote {remote!r} (git ls-remote exited {probe.returncode}); "
+            f"refusing to push.\n{probe.stdout[-4000:]}"
+        )
+    # The log combines stdout and stderr; warnings are not advertised refs.
+    if any(line.endswith(f"\t{ref}") for line in probe.stdout.splitlines()):
+        raise StargateError(f"{branch!r} already exists on {remote!r}; refusing to push.")
+    # An empty expected ref permits creation only, even if the branch appears
+    # after ls-remote. It cannot force-update an existing branch. Explicit URL,
+    # refspec and no-follow-tags also bypass remote mirror/push defaults.
+    proc = run_process(
+        ["git", "push", "--no-follow-tags", f"--force-with-lease={ref}:",
+         "--", urls[0], f"{ref}:{ref}"], repo,
+        check=False, timeout=PUBLISH_TIMEOUT_SECONDS, env=env,
+        log_path=artifacts / "pull-request-push.log",
+        display_args=["git", "push", "--no-follow-tags", f"--force-with-lease={ref}:",
+                      "--", remote, f"{ref}:{ref}"],
+    )
+    if proc.returncode:
+        raise StargateError(
+            f"Could not push {branch!r} to {remote!r} (exit {proc.returncode}).\n"
+            f"{proc.stdout[-4000:]}"
+        )
+
+
+def publication_command(config: dict[str, Any], branch: str, title: str) -> list[str]:
+    argv = pull_request_command(config)
+    if argv is None:
+        raise StargateError("--pr needs a pull_request.command in the run's config.")
+    values = {"branch": branch, "title": title}
+    # One pass keeps placeholder-looking text in the task literal.
+    return [re.sub(r"\{(branch|title)\}", lambda m: values[m[1]], part) for part in argv]
+
+
+def open_pull_request(config: dict[str, Any], repo: Path, cmd: list[str], body: str) -> str:
+    try:
+        proc = subprocess.run(
+            cmd, cwd=repo, text=True, input=body, capture_output=True,
+            timeout=PUBLISH_TIMEOUT_SECONDS, env=agent_env(config["pull_request"]),
+        )
+    except subprocess.TimeoutExpired as exc:
+        stderr = exc.stderr or b""
+        if isinstance(stderr, bytes):
+            stderr = stderr.decode(errors="replace")
+        raise StargateError(
+            f"{shlex.join(cmd)} timed out after {PUBLISH_TIMEOUT_SECONDS}s: {stderr[-4000:]}"
+        ) from exc
+    except (OSError, ValueError) as exc:
+        raise StargateError(f"Could not run {shlex.join(cmd)}: {exc}") from exc
+    if proc.returncode:
+        raise StargateError(
+            f"{shlex.join(cmd)} exited {proc.returncode}: {proc.stderr[-4000:]}"
+        )
+    return proc.stdout