beamflow-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{beamflow_cli-0.3.0 → beamflow_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: beamflow-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: CLI for the Beamflow Managed Platform
 Author: juraj.bezdek@gmail.com
 Author-email: juraj.bezdek@gmail.com
@@ -9,14 +9,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: beamflow-runtime (>=0.3.0,<0.4.0)
-Requires-Dist: fastapi (>=0.110.0)
+Requires-Dist: beamflow-runtime (>=0.3.0,<0.3.2)
 Requires-Dist: httpx (>=0.27.0)
 Requires-Dist: keyring (>=25.0.0)
 Requires-Dist: pydantic (>=2.0.0)
-Requires-Dist: python-dotenv (>=1.0.1)
 Requires-Dist: pyyaml (>=6.0.1)
 Requires-Dist: questionary (>=2.0.1)
 Requires-Dist: rich (>=13.7.0)
 Requires-Dist: typer[all] (>=0.12.0)
-Requires-Dist: uvicorn (>=0.29.0)

{beamflow_cli-0.3.0 → beamflow_cli-0.3.2}/beamflow/commands/project.py

@@ -142,6 +142,10 @@ def process_node(
                 try:
                     content = src.read_text()
                     content = content.replace("{project_name}", project_name)
+                    project_name_slug = project_name.lower().replace("_", "-").strip("-")
+                    if not project_name_slug:
+                        project_name_slug = "beamflow-project"
+                    content = content.replace("{project_name_slug}", project_name_slug)
                     if env_mode:
                         content = content.replace("{env}", env_mode.name)
                         content = content.replace("[env]", env_mode.name)
@@ -238,6 +242,89 @@ def init_env(env_name: str) -> EnvironmentMode:
     is_managed = (answers.get("backend") == "managed") or (answers.get("observability") == "managed")
     return EnvironmentMode(name=env_name, managed=is_managed, options=answers)
 
+def init_vscode_launch(env_name: str, force: bool = False):
+    """Initialize VS Code launch settings for a specific environment."""
+    root = find_project_root()
+    if not root:
+        console.print("[red]Not in a Beamflow project. Run 'beamflow init' first.[/red]")
+        raise typer.Exit(code=1)
+
+    project_config = load_project_config()
+    if not project_config:
+        console.print("[red]Invalid project configuration.[/red]")
+        raise typer.Exit(code=1)
+
+    # Find the environment
+    env_to_init = next((e for e in project_config.environments if e.name == env_name), None)
+    if not env_to_init:
+        console.print(f"[red]Environment '{env_name}' not found.[/red]")
+        raise typer.Exit(code=1)
+    
+    if env_to_init.managed:
+        console.print(f"[red]Cannot initialize VS Code launch for managed environment '{env_name}'.[/red]")
+        raise typer.Exit(code=1)
+
+    vscode_dir = root / ".vscode"
+    vscode_dir.mkdir(parents=True, exist_ok=True)
+    launch_json_path = vscode_dir / "launch.json"
+
+    import json
+    
+    launch_data = {"version": "0.2.0", "configurations": []}
+    if launch_json_path.exists():
+        try:
+            with open(launch_json_path, "r") as f:
+                launch_data = json.load(f)
+        except json.JSONDecodeError:
+            # Maybe there are comments or it's malformed. We'll ask to overwrite.
+            if not force:
+                console.print(f"[yellow]Warning: {launch_json_path} contains invalid JSON or comments. Cannot parse it automatically. Use --force to overwrite it entirely.[/yellow]")
+                raise typer.Exit(code=1)
+            launch_data = {"version": "0.2.0", "configurations": []}
+
+    api_config_name = f"Launch {env_name} API"
+    worker_config_name = f"Launch {env_name} Worker"
+
+    existing_configs = {cfg.get("name") for cfg in launch_data.get("configurations", [])}
+
+    added = False
+    
+    if api_config_name not in existing_configs or force:
+        # Remove old if force
+        launch_data["configurations"] = [c for c in launch_data.setdefault("configurations", []) if c.get("name") != api_config_name]
+        
+        launch_data["configurations"].append({
+            "name": api_config_name,
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/api_main.py",
+            "console": "integratedTerminal",
+            "env": {"ENVIRONMENT": env_name}
+        })
+        added = True
+        
+    if worker_config_name not in existing_configs or force:
+        # Remove old if force
+        launch_data["configurations"] = [c for c in launch_data.setdefault("configurations", []) if c.get("name") != worker_config_name]
+        
+        launch_data["configurations"].append({
+            "name": worker_config_name,
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/worker_main.py",
+            "console": "integratedTerminal",
+            "env": {"ENVIRONMENT": env_name}
+        })
+        added = True
+
+    if added:
+        with open(launch_json_path, "w") as f:
+            json.dump(launch_data, f, indent=4)
+        console.print(f"[green]Added VS Code launch configurations for '{env_name}' to {launch_json_path}[/green]")
+    else:
+        console.print(f"VS Code launch configurations already exist for '{env_name}'.")
+
+
 
 def add_environment(project_config: ProjectConfig, env_name: Optional[str] = None):
     if not env_name:
@@ -266,11 +353,12 @@ def add_environment(project_config: ProjectConfig, env_name: Optional[str] = Non
         
     if not env_name or any(e.name == env_name for e in project_config.environments):
         console.print("[red]Environment already exists or invalid name![/red]")
-        return
+        return None
         
     mode = init_env(env_name)
     project_config.environments.append(mode)
     save_project_config(project_config)
+    return mode
 
 
 @app.command("add")
@@ -289,11 +377,16 @@ def env_add(
         console.print("[red]Invalid project configuration.[/red]")
         raise typer.Exit(code=1)
     
-    add_environment(project_config, env_name=env_name)
+    added_mode = add_environment(project_config, env_name=env_name)
+    if not added_mode:
+        return
     
     # Reload config to get the newly added environment
     project_config = load_project_config()
     
+    # We now know the actual environment name picked
+    env_name = added_mode.name
+    
     # Check if we should ask for linkage
     is_managed = any(e.managed for e in project_config.environments)
     if not project_config.project_id and is_managed:
@@ -309,6 +402,10 @@ def env_add(
         process_node(child, root, None, is_fix=True, is_check=False, force=force, project_name=project_name, root_path=root, errors=errors, target_env=env_name)
 
     console.print(f"[green]Environment configuration updated![/green]")
+    
+    if not added_mode.managed:
+        if Prompt.ask("Would you like to initialize VS Code launch configurations for this environment?", choices=["y", "n"], default="y") == "y":
+            init_vscode_launch(env_name=env_name, force=force)
 
 
 @app.command("delete")
@@ -388,11 +485,18 @@ def init(
         # Ask to configure at least the first environment
         setup_first = Prompt.ask("Setup first eniroment? y/n?", choices=["y", "n"], default="y")
         if setup_first == "y":
-            add_environment(project_config)
+            added_mode = add_environment(project_config)
+            if added_mode and not added_mode.managed:
+                if Prompt.ask(f"Would you like to initialize VS Code launch configurations for {added_mode.name}?", choices=["y", "n"], default="y") == "y":
+                    init_vscode_launch(env_name=added_mode.name, force=force)
     else:
         if not fix:
             while Prompt.ask("Add another enviroment? y/n?", choices=["y", "n"], default="n") == "y":
-                add_environment(project_config)
+                added_mode = add_environment(project_config)
+                if added_mode and not added_mode.managed:
+                    if Prompt.ask(f"Would you like to initialize VS Code launch configurations for {added_mode.name}?", choices=["y", "n"], default="y") == "y":
+                        init_vscode_launch(env_name=added_mode.name, force=force)
+
 
     templates_dir = Path(__file__).parent.parent / "templates"
     errors = []

{beamflow_cli-0.3.0 → beamflow_cli-0.3.2}/beamflow/commands/run.py

@@ -12,7 +12,7 @@ console = Console()
 @app.command()
 def run(
     env: str = typer.Argument(..., help="Environment to run"),
-    build: bool = typer.Option(False, "--build", help="Build images before starting"),
+    build: bool = typer.Option(True, "--build/--no-build", help="Build images before starting"),
     detach: bool = typer.Option(False, "--detach", "-d", help="Run in background"),
     logs: bool = typer.Option(False, "--logs", help="Follow logs (useful with --detach)")
 ):

beamflow_cli-0.3.2/beamflow/core/auth_server.py

@@ -0,0 +1,45 @@
+from typing import Dict, Optional
+import threading
+import queue
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from urllib.parse import urlparse, parse_qs
+
+result_queue = queue.Queue()
+
+class CallbackHandler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        query_components = parse_qs(urlparse(self.path).query)
+        params = {k: v[0] for k, v in query_components.items()}
+        result_queue.put(params)
+        
+        self.send_response(200)
+        self.send_header('Content-type', 'text/html')
+        self.end_headers()
+        
+        content = """
+        <html>
+            <body style="font-family: sans-serif; text-align: center; padding-top: 50px;">
+                <h1>Authentication Successful</h1>
+                <p>You can now close this window and return to the CLI.</p>
+            </body>
+        </html>
+        """
+        self.wfile.write(content.encode('utf-8'))
+
+    def log_message(self, format, *args):
+        # Suppress logging
+        pass
+
+def start_callback_server(port: int = 8888) -> Dict[str, str]:
+    server = HTTPServer(('127.0.0.1', port), CallbackHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    
+    # Wait for result
+    try:
+        result = result_queue.get(timeout=300) # 5 minutes timeout
+        server.shutdown()
+        return result
+    except queue.Empty:
+        server.shutdown()
+        return {}

{beamflow_cli-0.3.0 → beamflow_cli-0.3.2}/beamflow/main.py

@@ -7,12 +7,19 @@ from .commands import build as build_cmds
 from .commands import deploy as deploy_cmds
 from .commands import run as run_cmds
 from rich.console import Console
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("beamflow-cli")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "unknown"
+
 console = Console()
 
 app = typer.Typer(
     name="beamflow",
-    help="""
-# 🚀 Beamflow CLI
+    help=f"""
+# 🚀 Beamflow CLI (v{__version__})
 Manage your Beamflow projects and deployments with ease.
 
 ## 🛠 Usage
@@ -90,6 +97,20 @@ def env_del(
     """
     project_cmds.env_delete(env_name=env_name)
 
+@env_app.command("init-vscode")
+def env_init_vscode(
+    env_name: str = typer.Argument(..., help="Environment name to initialize VS Code for"),
+    force: bool = typer.Option(False, "--force", help="Force overwrite existing launch.json if it's malformed or already has the configuration")
+):
+    """
+    [bold blue]Initialize VS Code launch configurations[/bold blue] for an environment.
+    
+    This command will add 'Launch <env> API' and 'Launch <env> Worker' to your .vscode/launch.json, 
+    allowing you to easily debug your environment's API and Worker using VS Code.
+    """
+    project_cmds.init_vscode_launch(env_name=env_name, force=force)
+
+
 @app.command()
 def run(
     ctx: typer.Context,
@@ -223,5 +244,10 @@ def logout():
     """Log out from the platform."""
     auth_cmds.logout()
 
+@app.command()
+def version():
+    """Show the Beamflow CLI version."""
+    console.print(f"Beamflow CLI version: [bold green]{__version__}[/bold green]")
+
 if __name__ == "__main__":
     app()

beamflow_cli-0.3.2/beamflow/templates/README.md

@@ -0,0 +1,135 @@
+# {project_name}
+
+Beamflow application generated for {project_name}.
+
+## Structure
+
+- `api.py`: Entry point for the API service.
+- `worker.py`: Entry point for the worker service.
+- `src/shared/`: Shared helpers, constants, and client utilities.
+- `src/api/`: Webhook handlers and API startup.
+- `src/worker/`: Worker startup and task definitions (such as feed consumers).
+- `config/`: Environment-based configuration (e.g. `local/`, `dev/`, `prod/`, `shared/`).
+- `deployment/`: Docker Compose setup and Dockerfiles.
+
+---
+
+## Dependency Management
+
+This project defines dependencies using optional extras, allowing you to install only what is needed for a specific service.
+
+- **Base dependencies**: Required by both API and Worker.
+- **`api` extra**: Dependencies required only by the API service.
+- **`worker` extra**: Dependencies required only by the Worker service.
+- **`dev` extra** (optional): Development tooling.
+
+### Standard Installation (pip)
+
+Install for local development (recommended, installs everything):
+```bash
+pip install -e ".[api,worker,dev]"
+```
+
+Install API-only:
+```bash
+pip install -e ".[api]"
+```
+
+Install Worker-only:
+```bash
+pip install -e ".[worker]"
+```
+
+### Alternative Installation (Poetry)
+
+If you prefer managing your environment with Poetry:
+
+Install for local development (everything):
+```bash
+poetry install --extras "api worker dev"
+```
+
+Install API-only:
+```bash
+poetry install --extras "api"
+```
+
+Install Worker-only:
+```bash
+poetry install --extras "worker"
+```
+
+---
+
+## Running Locally
+
+### 1. Start supporting services (e.g., Redis)
+```bash
+docker compose -f deployment/local/docker-compose.yaml up -d
+```
+
+### 2. Set environment
+```bash
+export BEAMSTACK_ENV=local
+```
+
+### 3. Run API
+```bash
+python api.py
+```
+API will be available at [http://localhost:8000](http://localhost:8000).
+
+### 4. Run Worker
+```bash
+python worker.py
+```
+
+*(Alternatively, you can use the Beamflow CLI to run your environments: `beamflow run local`)*
+
+---
+
+## Beamflow Core Concepts Usage
+
+This project is built on `beamflow_lib` – a core library providing robust context management, queue abstractions, and observability. Here is how you can utilize its components in your application:
+
+### Integration Context
+`IntegrationContext` propagates automatically through all your integration operations. It manages the current `run_id`, `integration`, and `current_record_key` to ensure all logs and traces are correctly correlated without manual passing.
+
+### Ingress & Pipelines
+- **Webhook Ingress**: Use the `@ingress.webhook(pipeline="...", integration="...")` decorator on your FastAPI endpoints to attach integration context without manually wrapping your handlers.
+- **Polling Ingress**: Use `@ingress.poll(pipeline="...", integration="...", schedule="...")` to create durable, stateful scheduled tasks (such as API polling).
+
+### RecordsFeed & Consumers
+Extract and ingest data efficiently using **RecordsFeed**:
+```python
+from beamflow_lib.pipelines.records_feed import RecordsFeed, RecordData
+
+feed = RecordsFeed.get(feed_id="your.pipeline")
+feed.publish(RecordData(record_id="123", record_type="invoice", data={...}))
+```
+Records are automatically deduplicated and optionally ordered by timestamp. 
+
+Consume them robustly with **Feed Consumers**, which handle batching, rate-limiting, and parallel execution automatically:
+```python
+from beamflow_lib.pipelines.consumer import feed_consumer
+
+@feed_consumer(
+  feed_id="your.pipeline",
+  batch=True,
+  max_batch_size=100,
+  rate_limit_per_sec=50,
+)
+async def process_records(records: list[RecordData]):
+    for record in records:
+        # Insert your business logic here
+        pass
+```
+
+### Observability
+Use the provided `logger` to naturally correlate your logs with the active context. The framework tracks the lifecycle of records intrinsically (from publishing to consumption) without manual `record_id` logging.
+
+```python
+from beamflow_lib import logger
+
+logger.info("Processing the invoice batch", details="step 1 completed")
+```

beamflow_cli-0.3.2/beamflow/templates/_deployment/[env]/(backend-asyncio)/docker-compose.yaml

@@ -0,0 +1,24 @@
+version: '3.8'
+services:
+  api:
+    build:
+      context: ../..
+      dockerfile: deployment/shared/api.Dockerfile
+    image: beamflow-{project_name_slug}-api:latest
+    ports:
+      - "8000:8000"
+    environment:
+      - ENVIRONMENT={env}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  worker:
+    build:
+      context: ../..
+      dockerfile: deployment/shared/worker.Dockerfile
+    image: beamflow-{project_name_slug}-worker:latest
+    environment:
+      - ENVIRONMENT={env}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+

{beamflow_cli-0.3.0 → beamflow_cli-0.3.2}/beamflow/templates/_deployment/[env]/(backend-dramatiq)/docker-compose.yaml

@@ -3,8 +3,8 @@ services:
   api:
     build:
       context: ../..
-      dockerfile: deployment/{env}/api.Dockerfile
-    image: beamflow-{project_name}-api:latest
+      dockerfile: deployment/shared/api.Dockerfile
+    image: beamflow-{project_name_slug}-api:latest
     ports:
       - "8000:8000"
     environment:
@@ -18,8 +18,8 @@ services:
   worker:
     build:
       context: ../..
-      dockerfile: deployment/{env}/worker.Dockerfile
-    image: beamflow-{project_name}-worker:latest
+      dockerfile: deployment/shared/worker.Dockerfile
+    image: beamflow-{project_name_slug}-worker:latest
     environment:
       - REDIS_URL=redis://redis:6379/0
       - ENVIRONMENT={env}

{beamflow_cli-0.3.0 → beamflow_cli-0.3.2}/pyproject.toml

@@ -1,20 +1,17 @@
 [project]
 name = "beamflow-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "CLI for the Beamflow Managed Platform"
 authors = [{name = "juraj.bezdek@gmail.com", email = "juraj.bezdek@gmail.com"}]
 requires-python = ">=3.11"
 dependencies = [
-    "beamflow-runtime>=0.3.0,<0.4.0",
+    "beamflow-runtime>=0.3.0,<0.3.2",
     "typer[all]>=0.12.0",
     "httpx>=0.27.0",
     "pyyaml>=6.0.1",
     "keyring>=25.0.0",
     "rich>=13.7.0",
     "pydantic>=2.0.0",
-    "python-dotenv>=1.0.1",
-    "fastapi>=0.110.0",
-    "uvicorn>=0.29.0",
     "questionary>=2.0.1",
 ]
 

beamflow_cli-0.3.0/beamflow/core/auth_server.py

@@ -1,36 +0,0 @@
-from typing import Dict
-from fastapi import FastAPI, Request
-from fastapi.responses import HTMLResponse
-import uvicorn
-import threading
-import queue
-from typing import Optional
-
-app = FastAPI()
-result_queue = queue.Queue()
-
-@app.get("/callback")
-async def callback(request: Request):
-    params = dict(request.query_params)
-    result_queue.put(params)
-    return HTMLResponse(content="""
-        <html>
-            <body style="font-family: sans-serif; text-align: center; padding-top: 50px;">
-                <h1>Authentication Successful</h1>
-                <p>You can now close this window and return to the CLI.</p>
-            </body>
-        </html>
-    """)
-
-def run_server(port: int):
-    uvicorn.run(app, host="127.0.0.1", port=port, log_level="error")
-
-def start_callback_server(port: int = 8888) -> Dict[str, str]:
-    thread = threading.Thread(target=run_server, args=(port,), daemon=True)
-    thread.start()
-    # Wait for result
-    try:
-        result = result_queue.get(timeout=300) # 5 minutes timeout
-        return result
-    except queue.Empty:
-        return {}

beamflow_cli-0.3.0/beamflow/templates/_README.md

@@ -1,28 +0,0 @@
-# {project_name}
-
-Beamflow application generated for {project_name}.
-
-## Local Development
-
-1. Install dependencies:
-   ```bash
-   pip install -e .
-   ```
-
-2. Run local environment:
-   ```bash
-   beamflow run dev
-   ```
-
-3. Build images:
-   ```bash
-   beamflow build dev
-   ```
-
-## Structure
-
-- `src/api`: FastAPI routes and webhooks
-- `src/worker`: Background tasks and feed consumers
-- `src/shared`: Shared models, clients, and tasks
-- `config`: Environment-specific configuration
-- `deployment`: Docker Compose and Dockerfiles

beamflow_cli-0.3.0/beamflow/templates/tests/_test_config_loading.py

@@ -1,10 +0,0 @@
-from pathlib import Path
-from beamflow_lib.config.env_loader import load_config_dir
-
-def test_dev_config_loading():
-    """
-    Verify that the {env} environment configuration loads correctly.
-    """
-    config_dir = Path(__file__).parent.parent / "config"
-    config = load_config_dir(config_dir, environment="{env}")
-    assert config is not None

beamflow_cli-0.3.0/beamflow/templates/tests/_test_integration.py

@@ -1,20 +0,0 @@
-import os
-import time
-import requests
-import pytest
-
-def get_base_url():
-    return "http://localhost:8000"
-
-def test_health():
-    base_url = get_base_url()
-    resp = requests.get(f"{{base_url}}/health", timeout=5)
-    assert resp.status_code == 200
-    assert resp.json()["status"] == "ok"
-
-def test_webhook_process_user():
-    base_url = get_base_url()
-    resp = requests.post(f"{{base_url}}/webhooks/{project_name}/process_user", json={{"user_id": "test-user-1"}}, timeout=5)
-    if resp.status_code == 404:
-         resp = requests.post(f"{{base_url}}/{project_name}/process_user", json={{"user_id": "test-user-1"}}, timeout=5)
-    assert resp.status_code == 200