devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/worker_guard.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import os
+import signal
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:  # pragma: no cover - python 3.11+
+    import tomllib
+except Exception:  # pragma: no cover
+    tomllib = None  # type: ignore
+
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+_FALSE_VALUES = {"0", "false", "no", "off"}
+
+
+@dataclass(frozen=True)
+class WorkerGuardBlock:
+    reason: str
+    source: str
+
+
+class WorkerGuardEnabledError(RuntimeError):
+    def __init__(self, block: WorkerGuardBlock):
+        self.block = block
+        super().__init__(block.reason)
+
+
+def _global_devflow_dir() -> Path:
+    home = os.environ.get("DEVFLOW_HOME")
+    if home:
+        return Path(home).expanduser() / ".devflow"
+    return Path.home() / ".devflow"
+
+
+def _read_toml(path: Path) -> dict[str, object]:
+    if tomllib is None or not path.exists():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _nested_get(data: dict[str, object], *keys: str) -> object | None:
+    cur: object = data
+    for key in keys:
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(key)
+    return cur
+
+
+def _parse_bool(value: object) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return None
+    text = str(value).strip().lower()
+    if not text:
+        return True
+    if text in _TRUE_VALUES:
+        return True
+    if text in _FALSE_VALUES:
+        return False
+    return None
+
+
+def _flag_file_enabled(path: Path) -> bool:
+    if not path.exists():
+        return False
+    try:
+        raw = path.read_text(encoding="utf-8").strip()
+    except Exception:
+        return True
+    parsed = _parse_bool(raw)
+    return True if parsed is None else parsed
+
+
+def get_worker_guard_block(*, repo_root: Path | None) -> WorkerGuardBlock | None:
+    env_value = _parse_bool(os.environ.get("DEVFLOW_DO_NOT_RUN_WORKER"))
+    if env_value is True:
+        return WorkerGuardBlock(
+            reason="Worker start is disabled by DEVFLOW_DO_NOT_RUN_WORKER.",
+            source="env:DEVFLOW_DO_NOT_RUN_WORKER",
+        )
+
+    global_devflow_dir = _global_devflow_dir()
+    global_flag_path = global_devflow_dir / "do-not-run-worker"
+    if _flag_file_enabled(global_flag_path):
+        return WorkerGuardBlock(
+            reason="Worker start is disabled by global flag file ~/.devflow/do-not-run-worker.",
+            source=str(global_flag_path),
+        )
+
+    global_cfg = _read_toml(global_devflow_dir / "config.toml")
+    global_cfg_value = _parse_bool(_nested_get(global_cfg, "worker", "do_not_run"))
+    if global_cfg_value is True:
+        return WorkerGuardBlock(
+            reason="Worker start is disabled by global config worker.do_not_run=true.",
+            source=str(global_devflow_dir / "config.toml"),
+        )
+
+    if repo_root is None:
+        return None
+
+    repo_root = repo_root.expanduser().resolve()
+    project_flag_path = repo_root / ".devflow" / "do-not-run-worker"
+    if _flag_file_enabled(project_flag_path):
+        return WorkerGuardBlock(
+            reason=f"Worker start is disabled by project flag file {project_flag_path}.",
+            source=str(project_flag_path),
+        )
+
+    project_cfg_path = repo_root / ".devflow" / "config.toml"
+    project_cfg = _read_toml(project_cfg_path)
+    project_cfg_value = _parse_bool(_nested_get(project_cfg, "worker", "do_not_run"))
+    if project_cfg_value is True:
+        return WorkerGuardBlock(
+            reason=f"Worker start is disabled by project config worker.do_not_run=true in {project_cfg_path}.",
+            source=str(project_cfg_path),
+        )
+
+    return None
+
+
+def ensure_worker_start_allowed(*, repo_root: Path | None) -> None:
+    block = get_worker_guard_block(repo_root=repo_root)
+    if block is not None:
+        raise WorkerGuardEnabledError(block)
+
+
+def _check_no_running_worker_process(
+    *, repo_root: Path, project_id: str
+) -> WorkerGuardBlock | None:
+    """Check if a live worker process is already running for this project.
+
+    Returns a WorkerGuardBlock if a running worker is found and confirmed alive.
+    If a stale running row exists (dead process), marks it stopped and returns None.
+    """
+    import re
+    import sqlite3
+    import subprocess
+    import time
+
+    repo_root = repo_root.expanduser().resolve()
+    db_path = repo_root / ".devflow" / "execution.sqlite"
+    if not db_path.exists():
+        return None
+
+    try:
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+    except Exception:
+        return None
+
+    try:
+        now = int(time.time())
+        rows = conn.execute(
+            (
+                "SELECT worker_id, status, active_queue_type, active_item_id, updated_at "
+                "FROM project_workers "
+                "WHERE project_id=? AND status='running'"
+            ),
+            (project_id,),
+        ).fetchall()
+
+        if not rows:
+            return None
+
+        # Resolve project path to check against running process cmdlines
+        resolved_repo = str(repo_root.resolve())
+
+        # ps aux output to find running devflow worker processes
+        try:
+            ps_output = subprocess.check_output(
+                ["ps", "aux"], text=True, stderr=subprocess.DEVNULL
+            )
+        except Exception:
+            ps_output = ""
+
+        for line in ps_output.splitlines():
+            if "devflow worker start" not in line:
+                continue
+            # Extract PID (field 1 in ps aux)
+            parts = line.split()
+            if len(parts) < 2:
+                continue
+            try:
+                pid = int(parts[1])
+            except ValueError:
+                continue
+            # Check if this process is still alive (signal 0)
+            try:
+                os.kill(pid, 0)
+            except (OSError, ValueError):
+                # Process is dead — clean up stale DB row
+                stale_ids = [r["worker_id"] for r in rows if r["worker_id"] == str(pid)]
+                for wid in stale_ids:
+                    conn.execute(
+                        "UPDATE project_workers SET status='stopped', stopped_at=?, updated_at=? "
+                        "WHERE worker_id=?",
+                        (now, now, wid),
+                    )
+                conn.commit()
+                continue
+            # Check if it matches our project path
+            if resolved_repo in line:
+                row = rows[0]
+                return WorkerGuardBlock(
+                    reason=(
+                        f"A worker process (PID {pid}) is already running for this project "
+                        f"and is currently handling queue_type={row['active_queue_type']!r}, "
+                        f"item_id={row['active_item_id']!r}."
+                    ),
+                    source=f"process:PID={pid}",
+                )
+
+        # No alive process found matching this project — clean up all stale rows
+        for row in rows:
+            conn.execute(
+                "UPDATE project_workers SET status='stopped', stopped_at=?, updated_at=? "
+                "WHERE worker_id=?",
+                (now, now, row["worker_id"]),
+            )
+        conn.commit()
+        return None
+    finally:
+        conn.close()

devflow_engine-1.0.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: devflow-engine
+Version: 1.0.0
+Summary: DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)
+Project-URL: Homepage, https://github.com/Nuosis/devflow_engine
+Project-URL: Repository, https://github.com/Nuosis/devflow_engine
+Project-URL: Issues, https://github.com/Nuosis/devflow_engine/issues
+Author: DevFlow
+License: Proprietary
+Keywords: agentic,automation,cli,devflow,testing,workflow
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=45.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# DevFlow Engine
+
+CLI-first Python engine for DevFlow. The PyPI distribution is
+`devflow-engine`; it installs the `devflow` command.
+
+## Goals
+- Project lifecycle: draft shell -> bind workspace/repo -> init/register/list/remove
+- Story lifecycle: index/validate/register/execute
+- Planning support: repo analysis -> source docs -> scopes -> approved scope -> idea(s) -> DevFlow stories
+- Implementation workflow: "green" gate = tests + typecheck + lint
+- Review workflow: story-driven compliance/soundness/security review packets persisted in SQLite
+- Error workflow: error queue + remediation runs
+- Execution store: `.devflow/execution.sqlite`
+
+## Documentation
+- `docs/story-implementation-planning-node.md` — per-story planning/gating node before TestDesign/Red, with dependency findings, queue decisions, and registry expectations consumed by downstream implementation nodes.
+- `docs/llm-input-primitives-v0.02.md` — v0.02 LLM-facing input primitive contract for `idea` and `story`.
+
+## Install
+
+Install the CLI from PyPI:
+
+```bash
+pipx install devflow-engine
+# or
+python -m pip install devflow-engine
+```
+
+Run the CLI:
+
+```bash
+devflow --help
+```
+
+## Development
+
+This repo is intended to be developed with **uv**.
+
+```bash
+cd devflow_engine
+uv venv
+uv pip install -e '.[dev]'
+```
+
+Print the v0.02 LLM input guidance:
+```bash
+devflow llm guide
+devflow llm guide --primitive idea --json
+```
+
+## Happy path
+1. project shell created in control plane
+2. workspace/repo bound to project
+3. registration DAG runs via `devflow project add`
+4. project reaches `ready_for_source_scope`
+5. source docs -> scopes
+6. approved scope -> idea(s)
+7. idea -> DevFlow stories
+8. story -> implementation
+9. implementation -> review
+
+## Quickstart
+Register an existing repo with DevFlow:
+```bash
+devflow project add --path /absolute/path/to/repo --name my-repo --json
+```
+
+Submit an idea or a ready story:
+```bash
+devflow idea submit --project /absolute/path/to/repo --from idea.json --json
+# or
+devflow story submit --project /absolute/path/to/repo --from story.json --json
+```
+
+Run delivery and inspect health:
+```bash
+devflow run start --project /absolute/path/to/repo --json
+devflow run health --project /absolute/path/to/repo --json
+```
+
+Triage and repair failures:
+```bash
+devflow doctor --project /absolute/path/to/repo --json
+devflow recovery run --project /absolute/path/to/repo --json
+devflow error solve --project /absolute/path/to/repo --json
+```
+
+When you have a deterministic project-code repro, pass it to error solving:
+```bash
+devflow error solve \
+  --project /absolute/path/to/repo \
+  --repro-command 'uv run pytest' \
+  --json
+```
+
+Inspect per-node outputs from a stored run:
+```bash
+# dump a specific run by run_id
+python scripts/dump_run_node_outputs.py \
+  --run-id <run_uuid>
+
+# or dump the latest run for any DAG by dag_id
+python scripts/dump_run_node_outputs.py \
+  --dag-id implementation_dag
+
+# second-most-recent run for that DAG
+python scripts/dump_run_node_outputs.py \
+  --dag-id implementation_dag \
+  --latest-index 2
+```
+
+Dumps are written under `.devflow/node_output_dumps/<dag>/<label>/<timestamp>/` by default.
+The navigation path intentionally stays human-readable and omits run IDs / object IDs where possible:
+- `<dag>` comes from `runs.dag_id` unless it looks like an ID, in which case the folder falls back to `dag`
+- `<label>` is derived from readable config fields such as `label`, `name`, `title`, `idea_title`, `scope_title`, or `story_title`
+- the exact `run_id` still lands in `manifest.json` inside the dump directory
+
+Use `--output-root /tmp/devflow-dumps` to write somewhere else.
+
+Run the source -> scope scaffold end-to-end:
+```bash
+devflow source-scope run \
+  --project-id proj_demo \
+  --intake-id source_demo \
+  --text "Customers approve quotes online. Approved quotes create jobs. Completed jobs create invoices and customers can pay online."
+```
+
+Gate a pre-shaped normalized packet + scope outline deterministically:
+```bash
+devflow source-scope gate \
+  --project-id proj_demo \
+  --source-packet .devflow/path/to/normalized_source_packet.json \
+  --scope-outline .devflow/path/to/scope_outline.json
+```
+
+## Story contracts
+Story contracts are YAML documents containing:
+- `id`, `title`
+- `planes`: required plane write-ups (`product`, `ux`, `technical`, `security`, `compliance`, `operations`)
+- `plane_oracles`: list of `{plane, anchor}` entries used as verification anchors
+
+The contract validator enforces presence of required planes + non-empty plane_oracles.
+
+## Execution store
+All runs/events/errors/review packets are stored in:
+- `.devflow/execution.sqlite`
+
+This database is created automatically on first CLI usage.
+
+## Workers / Background services
+
+### Supabase execution-event listener (`devflow worker supabase-events`)
+
+This is the DFE-side listener/dispatcher for the `devflow_execution_events` Supabase table.
+It is the single long-running process that bridges the control-plane (Supabase) to the local
+DevFlow engine — picking up queued events and dispatching the appropriate DFE workflow for each.
+
+**Normal operation (continuous loop with Realtime):**
+```bash
+devflow worker supabase-events
+```
+
+Starts an indefinite polling loop. While running it also opens a Supabase Realtime WebSocket
+subscription on `devflow_execution_events`. New `INSERT` events on that table wake the dispatch
+loop immediately rather than waiting for the next poll interval (default: 3 s). If the WebSocket
+connection drops it reconnects automatically in the background; polling continues as the fallback
+during any gap.
+
+**Process a single queued event and exit:**
+```bash
+devflow worker supabase-events --once
+```
+
+Useful for manual trigger / smoke testing.
+
+**Disable Realtime (polling only):**
+```bash
+devflow worker supabase-events --no-realtime
+```
+
+Runs the same polling loop but skips the WebSocket listener entirely. Use this when the
+`websockets` Python package is unavailable, or when you need to debug without a live connection.
+
+**Additional options:**
+| Flag | Default | Description |
+|---|---|---|
+| `--sleep-seconds N` | `3.0` | Idle sleep between polls (also caps realtime wake latency) |
+| `--max-iterations N` | unlimited | Stop after N loop iterations |
+| `--json` | off | Emit JSON summary on exit |
+
+**When queued events are not being picked up — checklist:**
+1. Verify the worker is running: there should be a live `devflow worker supabase-events` process.
+2. Check Supabase credentials: `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` (or equivalent config)
+   must be set and valid.
+3. Confirm the event row in `devflow_execution_events` has `status = queued` and `run_id IS NULL`
+   — events with any other status are skipped.
+4. Check that the event's `event_type` is in the supported set (see
+   `docs/queue-worker-infra.md` → *Supported event types*).
+5. Run with `--once` to get an immediate result and check stderr/stdout for errors.
+6. If Realtime is misbehaving (false wake-ups or missed wakes), try `--no-realtime` to isolate
+   the issue to the polling path.
+
+See `docs/queue-worker-infra.md` for full architecture details.
+
+## Design notes
+- `docs/scope-idea-agentification.md` — current scope->idea agentic runtime notes
+- `docs/ui-grounding-curtis-medium-tier-doctrine.md` — follow-on UI grounding / wireframe planning doctrine from the Curtis pass, including the proposed `ui_screen_inventory.json` contract and the default medium-tier minimum for customer-facing wireframes