Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/reference/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,11 +253,16 @@ envctl pr-preview-controller --command start --pr-number 287
Behavior:

- starts or reconciles a preview when the configured label is added
- treats an explicit `--command start` as a forced reconciliation: an existing
same-head runtime is stopped before the import/start path runs again, so
changed CI environment or secret inputs cannot be hidden by Git identity
- redeploys labeled PRs when GitHub sends a new-commit event
- loads a tracked `.envctl` from the exact PR head when present; otherwise it
falls back to the controller-generated configuration
- publishes explicitly listed `ENVCTL_PREVIEW_PUBLIC_SERVICES` on deterministic
TLS hosts and projects matching HTTP/WebSocket source URLs into launch env
- rejects a routed service whose JSON health response explicitly reports
`"ready": false`, even when the endpoint itself returns HTTP 2xx
- creates `ENVCTL_PREVIEW_GENERATED_SECRETS` ephemerally for each preview start,
so shared service credentials do not need to be stored in GitHub
- also redeploys during scheduled reconciliation if the saved preview head is stale
Expand Down Expand Up @@ -404,6 +409,14 @@ envctl kill --backend --headless # alias for stop --backend
envctl kill-all --headless # alias for stop-all
```

Plain dependency cleanup is intentionally storage-preserving: `stop --dependencies`
and plain `stop-all` release saved dependency records and scoped port locks, but
leave envctl-managed Docker dependency stacks and their storage available for a
later start to reuse. Use `stop-all --remove-volumes` to remove supported managed
containers and volumes, or `blast-all` for aggressive ecosystem cleanup.
Explicit `--main` and `--trees` cleanup is mode-scoped: it never stops or retires
the other mode's saved runtime.

For AI plan-agent launches, `--entire-system` starts configured or autodetected local app services. In a repo/worktree
with no explicit backend, frontend, or additional-service configuration and no supported autodetectable app layout,
envctl reports that no local app system is configured and continues without app services; the AI session still launches.
Expand Down Expand Up @@ -538,6 +551,11 @@ Commit defaults:
- write one complete next commit message in `.envctl-commit-message.md` rather than multiple fragmented summaries only when using the fallback ledger
- envctl-local control artifacts (`.envctl*`, `.codegraph/`, `.serena/project.local.yml`, `MAIN_TASK.md`, `OLD_TASK_*.md`, `trees/`) stay local; if a broad `git add .` stages them, `envctl commit` unstages those protected paths before committing normal changes

PR defaults:

- `envctl pr` and `envctl ship` target `dev` when that remote branch exists, otherwise `main`, otherwise `master`; use `--pr-base <branch>` to override the selection explicitly
- an existing open PR for the current head branch is rediscovered before creation, so rerunning the command reports or updates the same PR instead of opening a duplicate

Optional plan-agent launch config for `--plan` and `--import`:

`envctl ship` is the preferred AI handoff command. From inside the current
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,13 @@ Only simple `${VAR}` placeholders are supported. Shell-style defaults, command s

Frontend launch-env sections may use `ENVCTL_SOURCE_SUPABASE_URL` and `ENVCTL_SOURCE_SUPABASE_ANON_KEY`. They cannot reference `ENVCTL_SOURCE_SUPABASE_SERVICE_ROLE_KEY`; envctl rejects that mapping before launching the frontend process.

Every launched service also receives `ENVCTL_PYTHON_EXECUTABLE`, the absolute
interpreter path running envctl. Repository-owned shell launchers can use this
as a bootstrap interpreter on minimal hosts where a `python` command alias is
not installed. Applications should still create and execute their own project
environment rather than importing application dependencies from envctl's
environment.

## Managed Supabase Ports

Managed Supabase exposes two distinct local resources:
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/important-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ pass `--interactive` only when you want prompts.
| `--frontend` | Runtime scope: run or stop frontend app services only. |
| `--fullstack` | Runtime scope: run or stop backend and frontend app services. |
| `--both` | Alias for `--fullstack`. |
| `--dependencies` | Runtime scope: run or stop dependencies only (DB/Redis/etc.), without app services. |
| `--dependencies` | Runtime scope: run dependencies only, or detach their saved records/port locks on stop without removing reusable managed Docker stacks. |
| `--deps` | Alias for `--dependencies`. |
| `--entire-system` | Runtime scope: run or stop dependencies plus backend and frontend services. |
| `--entire-system` | Runtime scope: run dependencies plus app services; on stop, terminate app services and detach dependency records/locks while keeping managed Docker stacks reusable. |
| `--only-frontend` | Startup/plan modifier: launch only the frontend app service; skip backend, managed dependencies, and dependency prep. |
| `--only-backend` | Startup/plan modifier: launch only the backend app service; skip frontend, managed dependencies, and dependency prep. |
| `--no-deps` | Startup/plan modifier: skip managed dependencies and plan-agent dependency prep. |
Expand Down
6 changes: 6 additions & 0 deletions docs/user/common-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,12 @@ envctl stop --entire-system --headless
envctl kill-all --headless
```

`stop --dependencies` and plain `stop-all` preserve managed Docker dependency
stacks and storage for reuse while releasing their saved records and port locks.
Use `stop-all --remove-volumes` or `blast-all` when those managed containers must
also be removed. Pass `--main` or `--trees` to clean only that saved runtime mode;
the other mode remains active.

When you invoke a specific action command directly, envctl stays non-interactive by default.
For example, `envctl kill-all`, `envctl pr`, `envctl test`, `envctl logs`, and `envctl migrate`
behave like their `--headless` forms. Add `--interactive` only when you want envctl to prompt
Expand Down
2 changes: 1 addition & 1 deletion docs/user/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ Why this works well:
- `explain-startup` shows what the runtime is about to do
- `--resume` is the fastest normal start path after previous runs
- `dashboard`, `logs`, and `test` cover the common daily loop
- `stop-all` gives you a clean shutdown
- `stop-all` cleanly shuts down tracked app services and releases dependency records/locks; managed Docker dependency stacks and storage remain reusable (use `stop-all --remove-volumes` or `blast-all` to remove them)

If you want a fresh start instead of resume:

Expand Down
7 changes: 4 additions & 3 deletions python/envctl_engine/actions/action_commit_support.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
resolve_commit_message_request,
write_commit_message_file as _write_commit_message_file,
)
from envctl_engine.actions.action_protected_artifacts import EnvctlProtectedPathPartition
from envctl_engine.actions.action_protected_artifacts import EnvctlProtectedPathPartition, unstaged_stageable_paths
from envctl_engine.ui.path_links import render_paths_in_terminal_text

RunGitFn = Callable[[Path, list[str]], subprocess.CompletedProcess[str]]
Expand Down Expand Up @@ -88,6 +88,7 @@ def _stage_commit_candidates(self, git_root: Path) -> EnvctlProtectedPathPartiti
return None

partition = self.dependencies.partition_envctl_protected_paths(pre_stage_status.stdout)
paths_to_stage = unstaged_stageable_paths(pre_stage_status.stdout)
unstaged_protected_paths = self._unstage_protected_paths(git_root, partition)
if unstaged_protected_paths is None:
return None
Expand All @@ -97,7 +98,7 @@ def _stage_commit_candidates(self, git_root: Path) -> EnvctlProtectedPathPartiti
return None
partition = refreshed_partition

if not self._stage_paths(git_root, partition.stageable_paths):
if not self._stage_paths(git_root, paths_to_stage):
return None
self._print_skipped_protected_paths(unstaged_protected_paths, partition.protected_skipped_paths)
return partition
Expand Down Expand Up @@ -141,7 +142,7 @@ def _refreshed_partition_after_unstage(self, git_root: Path) -> EnvctlProtectedP
def _stage_paths(self, git_root: Path, stageable_paths: list[str]) -> bool:
if not stageable_paths:
return True
add = self.dependencies.run_git(git_root, ["add", "--", *stageable_paths])
add = self.dependencies.run_git(git_root, ["add", "--all", "--", *stageable_paths])
if add.returncode != 0:
self.dependencies.print_error("git add failed", add)
return False
Expand Down
122 changes: 105 additions & 17 deletions python/envctl_engine/actions/action_git_state_support.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
from __future__ import annotations

from dataclasses import dataclass
import json
import os
from pathlib import Path
import subprocess
from typing import Callable

from envctl_engine.shared.git_branch_support import detect_preferred_default_branch


@dataclass(frozen=True, slots=True)
class DirtyWorktreeReport:
Expand All @@ -20,6 +24,12 @@ def dirty(self) -> bool:
return self.staged or self.unstaged or self.untracked


@dataclass(frozen=True, slots=True)
class ExistingPullRequest:
url: str
base_branch: str


def resolve_git_root(project_root: Path, repo_root: Path) -> Path:
for candidate in (project_root, repo_root):
if (candidate / ".git").exists():
Expand Down Expand Up @@ -71,53 +81,131 @@ def classify_dirty_porcelain(status_output: str) -> tuple[bool, bool, bool]:


def detect_default_branch(git_root: Path, *, git_output: Callable[[Path, list[str]], str]) -> str:
ref = git_output(git_root, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).strip()
if ref.startswith("origin/"):
return ref.split("origin/", 1)[1]
for candidate in ("main", "master"):
if git_output(git_root, ["rev-parse", "--verify", candidate]).strip():
return candidate
return "main"
return detect_preferred_default_branch(
lambda args: git_output(git_root, list(args)),
probe_remote_heads=True,
)


def existing_pr_url(
def existing_pull_request(
git_root: Path,
branch: str,
*,
gh_path: str | None,
run_process: Callable[..., subprocess.CompletedProcess[str]],
) -> str:
) -> ExistingPullRequest | None:
branch_name = branch.strip()
if not branch_name or branch_name in {"HEAD", "unknown"}:
return ""
return None
if gh_path is None:
return ""
return None
listed = run_process(
[gh_path, "pr", "list", "--head", branch_name, "--state", "open", "--json", "url", "--jq", ".[0].url"],
[
gh_path,
"pr",
"list",
"--head",
branch_name,
"--state",
"open",
"--limit",
"1",
"--json",
"url,baseRefName",
],
cwd=str(git_root),
text=True,
capture_output=True,
check=False,
)
if listed.returncode != 0:
return ""
return listed.stdout.strip()
return None
try:
payload = json.loads(listed.stdout or "[]")
except (TypeError, json.JSONDecodeError):
return None
if not isinstance(payload, list) or not payload or not isinstance(payload[0], dict):
return None
url = str(payload[0].get("url") or "").strip()
if not url:
return None
return ExistingPullRequest(
url=url,
base_branch=str(payload[0].get("baseRefName") or "").strip(),
)


def run_git(
def existing_pr_url(
git_root: Path,
args: list[str],
branch: str,
*,
gh_path: str | None,
run_process: Callable[..., subprocess.CompletedProcess[str]],
) -> str:
existing = existing_pull_request(
git_root,
branch,
gh_path=gh_path,
run_process=run_process,
)
return existing.url if existing is not None else ""


def update_pull_request_base(
git_root: Path,
pull_request: ExistingPullRequest,
base_branch: str,
*,
gh_path: str | None,
run_process: Callable[..., subprocess.CompletedProcess[str]],
) -> subprocess.CompletedProcess[str]:
branch = base_branch.strip()
command = [*([gh_path] if gh_path else ["gh"]), "pr", "edit", pull_request.url, "--base", branch]
if gh_path is None:
return subprocess.CompletedProcess(
command,
127,
stdout="",
stderr=(
"gh is required to update the existing pull request base. "
f"Install or authenticate gh, then run: gh pr edit {pull_request.url} --base {branch}"
),
)
return run_process(
["git", "-C", str(git_root), *args],
command,
cwd=str(git_root),
text=True,
capture_output=True,
check=False,
)


def run_git(
git_root: Path,
args: list[str],
*,
run_process: Callable[..., subprocess.CompletedProcess[str]],
) -> subprocess.CompletedProcess[str]:
command = ["git", "-C", str(git_root), *args]
options: dict[str, object] = {
"text": True,
"capture_output": True,
"check": False,
}
if args[:1] == ["ls-remote"]:
options["timeout"] = 10
options["env"] = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
try:
return run_process(command, **options)
except subprocess.TimeoutExpired as exc:
return subprocess.CompletedProcess(
command,
124,
stdout=str(exc.stdout or ""),
stderr="Timed out while querying remote branches.",
)


def git_output(
git_root: Path,
args: list[str],
Expand Down
47 changes: 47 additions & 0 deletions python/envctl_engine/actions/action_pr_git_support.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
from __future__ import annotations

from pathlib import Path
import shutil
import subprocess

from envctl_engine.actions.action_git_state_support import (
ExistingPullRequest,
existing_pr_url as lookup_existing_pr_url,
existing_pull_request as lookup_existing_pull_request,
update_pull_request_base as update_existing_pull_request_base,
)


def existing_pr_url(git_root: Path, branch: str) -> str:
return lookup_existing_pr_url(
git_root,
branch,
gh_path=shutil.which("gh"),
run_process=subprocess.run,
)


def existing_pull_request(git_root: Path, branch: str) -> ExistingPullRequest | None:
return lookup_existing_pull_request(
git_root,
branch,
gh_path=shutil.which("gh"),
run_process=subprocess.run,
)


def update_pull_request_base(
git_root: Path,
pull_request: ExistingPullRequest,
base_branch: str,
) -> subprocess.CompletedProcess[str]:
return update_existing_pull_request_base(
git_root,
pull_request,
base_branch,
gh_path=shutil.which("gh"),
run_process=subprocess.run,
)


__all__ = ["existing_pr_url", "existing_pull_request", "update_pull_request_base"]
Loading
Loading