cortexapps-cli 1.30.0__tar.gz → 1.31.0__tar.gz

{cortexapps_cli-1.30.0 → cortexapps_cli-1.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexapps-cli
-Version: 1.30.0
+Version: 1.31.0
 Summary: Command Line Interface for cortexapps
 License: MIT
 License-File: LICENSE
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: PyNaCl (>=1.5.0)
 Requires-Dist: pyyaml (>=6.0.1,<7)
 Requires-Dist: requests (>=2.33.0,<3.0.0)
 Requires-Dist: typer (>=0.15,<1.0)

{cortexapps_cli-1.30.0 → cortexapps_cli-1.31.0}/cortexapps_cli/commands/solutions.py

@@ -74,13 +74,26 @@ class _ToggleableCapture:
 
 
 def _run_import_with_toggle(fn) -> str:
-    """Run fn() capturing stdout. On a TTY, Ctrl+o toggles live output."""
+    """Run fn() capturing stdout. On a TTY, Ctrl+o toggles live output.
+
+    If fn() raises for any reason, all buffered output is flushed to the
+    terminal before the exception propagates — no silent failures.
+    """
     real_stdout = sys.stdout
     capture = _ToggleableCapture(real_stdout)
 
     if not (_TTY_SUPPORT and sys.stdin.isatty()):
-        with contextlib.redirect_stdout(capture):
-            fn()
+        success = False
+        try:
+            with contextlib.redirect_stdout(capture):
+                fn()
+            success = True
+        finally:
+            if not success:
+                buffered = capture.getvalue()
+                if buffered:
+                    real_stdout.write(buffered)
+                    real_stdout.flush()
         return capture.getvalue()
 
     done = threading.Event()
@@ -112,9 +125,11 @@ def _run_import_with_toggle(fn) -> str:
 
     t = threading.Thread(target=_listen, daemon=True)
     t.start()
+    success = False
     try:
         with contextlib.redirect_stdout(capture):
             fn()
+        success = True
     finally:
         done.set()
         t.join(timeout=0.5)
@@ -122,6 +137,11 @@ def _run_import_with_toggle(fn) -> str:
             _termios.tcsetattr(fd, _termios.TCSADRAIN, old_settings)
         except Exception:
             pass
+        if not success:
+            buffered = capture.getvalue()
+            if buffered:
+                real_stdout.write(buffered)
+                real_stdout.flush()
 
     return capture.getvalue()
 
@@ -175,6 +195,53 @@ def _get_readme(tag: str, path: str | None = None) -> str | None:
         return None
 
 
+def _has_post_install(tag: str, path: str | None = None) -> bool:
+    """Return True if this solution has a post-install setup.py."""
+    try:
+        (_solutions_root(path) / tag / "setup.py").read_bytes()
+        return True
+    except Exception:
+        return False
+
+
+def _load_setup_module(solution_tag: str, solutions_dir: str | None = None):
+    """Load a solution's setup.py module. Returns the module or None if not found."""
+    import importlib.util
+
+    root = _solutions_root(solutions_dir)
+    try:
+        with as_file(root / solution_tag / "setup.py") as setup_path:
+            spec = importlib.util.spec_from_file_location(f"{solution_tag}_setup", setup_path)
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            return module
+    except FileNotFoundError:
+        return None
+
+
+def _get_setup_description(solution_tag: str, solutions_dir: str | None = None) -> str:
+    """Return the SETUP_DESCRIPTION from a solution's setup.py, or a generic fallback."""
+    module = _load_setup_module(solution_tag, solutions_dir)
+    if module:
+        return getattr(module, "SETUP_DESCRIPTION", "This solution includes a post-install setup script.")
+    return "This solution includes a post-install setup script."
+
+
+def _run_post_install_script(solution_tag: str, solutions_dir: str | None = None, ctx=None, no_prompt: bool = False) -> None:
+    """Find and invoke the solution's setup.py main() function."""
+    module = _load_setup_module(solution_tag, solutions_dir)
+    if module is None:
+        typer.echo("No post-install setup available for this solution.")
+        return
+    kwargs = {}
+    if ctx and ctx.obj and "client" in ctx.obj:
+        client = ctx.obj["client"]
+        kwargs["cortex_api_key"] = client.api_key
+        kwargs["cortex_base_url"] = client.base_url
+    kwargs["no_prompt"] = no_prompt
+    module.main(**kwargs)
+
+
 def _extract_first_codeblock(text: str) -> str | None:
     """Return content of the first fenced code block."""
     m = re.search(r"```[^\n]*\n(.*?)```", text, re.DOTALL)
@@ -538,17 +605,6 @@ def _show_next_steps(readme: str) -> None:
             section = re.sub(r'\[([^\]]+)\]\(([^)]+)\)', r'\1 (\2)', section)
         console.print()
         console.print(Markdown(section))
-    console.print()
-    console.print(
-        "[magenta]Planned for Q4 2027:[/magenta] CQL metadata traversal will enable scorecard rules "
-        "across relationship chains — for example, a Vulnerability Scorecard checking that no "
-        "deployed service-version has open Snyk issues:"
-    )
-    console.print(
-        "  [dim]entity.destinations(relationshipType = \"environments\", depth = 3)\n"
-        "    .filter((d) => d.type == \"service-version\")\n"
-        "    .all((sv) => sv.snyk.issues == 0)[/dim]"
-    )
 
 
 def _post_install_menu(
@@ -604,6 +660,12 @@ def install(
     ctx: typer.Context,
     solution: str = typer.Option(..., "--solution", "-s", help="Solution tag"),
     no_prompt: bool = typer.Option(False, "--no-prompt", help="Skip the post-install interactive menu"),
+    skip_post_install_setup: bool = typer.Option(
+        False,
+        "--skip-post-install-setup",
+        help="Skip the post-install setup script prompt",
+        is_flag=True,
+    ),
 ):
     """Install a solution."""
     solutions_dir = ctx.obj.get("solutions_dir") if ctx.obj else None
@@ -643,6 +705,20 @@ def install(
     else:
         typer.echo(output)
 
+    # Post-install setup hook — runs before the informational menu
+    if not no_prompt and not skip_post_install_setup and _has_post_install(solution, solutions_dir):
+        state_file = Path.home() / ".cortex" / "solutions" / f"{solution}.json"
+        if state_file.exists():
+            typer.echo(f"\nRetrieving previous responses from: {state_file}")
+        desc = _get_setup_description(solution, solutions_dir)
+        typer.echo(f"\n{desc}")
+        if typer.confirm("Run setup now?", default=True):
+            _run_post_install_script(solution, solutions_dir=solutions_dir, ctx=ctx)
+        else:
+            typer.echo(f"\nRun setup later with: cortex solutions post-install -s {solution}")
+    elif skip_post_install_setup and _has_post_install(solution, solutions_dir):
+        typer.echo(f"\nRun setup later with: cortex solutions post-install -s {solution}")
+
     if not no_prompt:
         readme = _get_readme(solution, solutions_dir)
         if readme:
@@ -660,6 +736,27 @@ def install(
             _post_install_menu(readme, import_report=output, entity_tags=entity_tags, ui_url=ui_url)
 
 
+@app.command(name="post-install")
+def post_install(
+    ctx: typer.Context,
+    solution: str = typer.Option(..., "--solution", "-s", help="Solution tag"),
+    no_prompt: bool = typer.Option(
+        False,
+        "--no-prompt",
+        "-N",
+        help="Use saved answers from ~/.cortex/solutions/<tag>.json without prompting.",
+    ),
+):
+    """Run post-install setup for a solution."""
+    solutions_dir = ctx.obj.get("solutions_dir") if ctx.obj else None
+    if solution not in _list_solution_tags(solutions_dir):
+        avail = ", ".join(_list_solution_tags(solutions_dir))
+        typer.echo(f"Error: Solution '{solution}' not found. Available: {avail}")
+        raise typer.Exit(1)
+    ctx.obj["client"] = _build_client(ctx)
+    _run_post_install_script(solution, solutions_dir=solutions_dir, ctx=ctx, no_prompt=no_prompt)
+
+
 @app.command()
 def uninstall(
     ctx: typer.Context,

cortexapps_cli-1.31.0/cortexapps_cli/solutions/_lib/setup_base.py

@@ -0,0 +1,169 @@
+import getpass
+import json
+import os
+import sys
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+
+class SolutionSetup(ABC):
+    """
+    Base class for solution post-install setup scripts.
+    Subclasses define solution_tag, collect_prompts(), and steps().
+    """
+
+    solution_tag: str  # must be set by subclass
+
+    def __init__(self, state_dir: Optional[Path] = None, no_prompt: bool = False):
+        self._no_prompt = no_prompt
+        self._secret_keys: set = set()
+        self._answers: dict = {}
+
+        solutions_dir = state_dir or Path.home() / ".cortex" / "solutions"
+        solutions_dir.mkdir(parents=True, exist_ok=True)
+        self._state_file = solutions_dir / f"{self.solution_tag}.json"
+
+        data = self._load_file()
+        self._answers = data.get("answers", {})
+        self._state: dict = data.get("state", {})
+
+        self._migrate_old_state()
+
+    def _load_file(self) -> dict:
+        if self._state_file.exists():
+            try:
+                return json.loads(self._state_file.read_text())
+            except (json.JSONDecodeError, OSError):
+                return {}
+        return {}
+
+    def _save_file(self) -> None:
+        data = {
+            "answers": {k: v for k, v in self._answers.items() if k not in self._secret_keys},
+            "state": self._state,
+        }
+        self._state_file.write_text(json.dumps(data, indent=2))
+
+    def _save_state(self) -> None:
+        self._save_file()
+
+    def _migrate_old_state(self) -> None:
+        """Move state from the old flat ~/.cortex/setup-<tag>.json into the new file."""
+        old_file = Path.home() / ".cortex" / f"setup-{self.solution_tag}.json"
+        if not old_file.exists():
+            return
+        try:
+            old_data = json.loads(old_file.read_text())
+            if old_data and not self._state:
+                self._state.update(old_data)
+                self._save_file()
+            old_file.unlink()
+        except Exception:
+            pass
+
+    def prompt(
+        self,
+        key: str,
+        message: str,
+        env_var: Optional[str] = None,
+        default: Optional[str] = None,
+        secret: bool = False,
+    ) -> str:
+        """Prompt for a value. Uses saved answer or env var when available."""
+        if secret:
+            self._secret_keys.add(key)
+
+        # Non-secret: use saved answer when --no-prompt
+        if self._no_prompt and not secret and key in self._answers:
+            return self._answers[key]
+
+        # Non-secret: saved answer takes precedence over any derived default
+        if not secret and key in self._answers:
+            default = self._answers[key]
+
+        if env_var:
+            env_val = os.environ.get(env_var)
+            if env_val:
+                masked = "********" if secret else env_val
+                if self._no_prompt or self.confirm(f"{message} [{masked} from {env_var}]", default=True):
+                    self._answers[key] = env_val
+                    return env_val
+
+        # Secrets in --no-prompt mode still need a prompt if no env var provided
+        if self._no_prompt and secret and key not in self._answers:
+            print(f"  (secret required — no env var set for {key})", file=sys.stderr)
+
+        prompt_str = message
+        if default:
+            prompt_str += f" [{default}]"
+        prompt_str += ": "
+
+        if secret:
+            value = getpass.getpass(prompt_str).strip()
+        else:
+            value = input(prompt_str).strip()
+        if not value:
+            value = default or ""
+        self._answers[key] = value
+        return value
+
+    def confirm(self, message: str, default: bool = True) -> bool:
+        """Y|N confirmation prompt. Auto-accepts default when --no-prompt."""
+        if self._no_prompt:
+            return default
+        hint = "[Y/n]" if default else "[y/N]"
+        response = input(f"{message} {hint}: ").strip().lower()
+        if not response:
+            return default
+        return response in ("y", "yes")
+
+    def already_done(self, key: str) -> bool:
+        """Return True if this step was previously completed."""
+        return self._state.get(key, False)
+
+    def mark_done(self, key: str) -> None:
+        """Mark a step as completed in the persistent state file."""
+        self._state[key] = True
+        self._save_file()
+
+    @abstractmethod
+    def collect_prompts(self) -> None:
+        """Collect all user inputs upfront before executing steps."""
+
+    @abstractmethod
+    def steps(self) -> list[tuple[str, callable]]:
+        """Return ordered list of (label, callable) tuples."""
+
+    def post_steps(self) -> None:
+        """Optional hook called after all steps complete. Override in subclass."""
+
+    def run(self) -> None:
+        """Collect prompts then execute steps with progress display."""
+        if self._no_prompt and self._answers:
+            saved = {k: v for k, v in self._answers.items() if k not in self._secret_keys}
+            if saved:
+                print("Using saved configuration:")
+                for k, v in saved.items():
+                    print(f"  {k}: {v}")
+                print()
+
+        self.collect_prompts()
+        self._save_file()
+
+        print()
+        step_list = self.steps()
+        total = len(step_list)
+        for i, (label, fn) in enumerate(step_list, 1):
+            try:
+                detail = fn()
+                print(f"[{i}/{total}] {label}... \u2713")
+                if detail:
+                    lines = [detail] if isinstance(detail, str) else detail
+                    for line in lines:
+                        print(f"  {line}")
+                print()
+            except Exception as e:
+                print(f"[{i}/{total}] {label}... \u2717  {e}", file=sys.stderr)
+                raise SystemExit(1)
+        self.post_steps()

cortexapps_cli-1.31.0/cortexapps_cli/solutions/github-actions-deploy/README.md

@@ -0,0 +1,97 @@
+---
+name: GitHub Actions Deploy Tracking
+description: Track deployments from GitHub Actions in Cortex, with a deploy health scorecard measuring delivery cadence.
+---
+
+# GitHub Actions Deploy Tracking
+
+Trigger deploys from Cortex, track them as they run in GitHub Actions, and surface deploy health back in your service catalog.
+
+```
+  ┌─────────────────────────────────┐
+  │         Cortex Catalog          │
+  │                                 │
+  │  github-actions-demo  (service) │
+  │  ├── x-cortex-git.github        │
+  │  │     repository: owner/repo   │
+  │  └── Scorecard: Deploy Health   │
+  │        Bronze / Silver / Gold   │
+  └──────────────┬──────────────────┘
+                 │
+                 │  Run workflow from entity page
+                 │  (or: cortex workflows run -t
+                 │   github-actions-deploy
+                 │   --scope ENTITY --entity <tag>)
+                 ▼
+  ┌─────────────────────────────────┐
+  │       Cortex Workflow           │
+  │  Solution: Add Cortex Deploy    │
+  │       from GitHub Actions       │
+  │                                 │
+  │  1. Read linked repo from       │
+  │     entity catalog config       │
+  │  2. POST workflow_dispatch      │
+  │     to GitHub Actions           │
+  │  3. Wait for callback           │
+  └──────────────┬──────────────────┘
+                 │  POST /dispatches  (GitHub integration)
+                 ▼
+  ┌─────────────────────────────────┐
+  │        GitHub Actions           │
+  │    cortex-deploy.yml            │
+  │                                 │
+  │  job: build                     │
+  │    └── run your deploy steps    │
+  │                                 │
+  │  job: cortex-callback           │
+  │    ├── POST /deploys            │◄── registers deploy event
+  │    │   (entity: github-actions- │    on the Cortex entity
+  │    │    demo)                   │
+  │    └── POST callbackUrl  ───────┼──► Cortex marks workflow
+  │        status: SUCCESS/FAILURE  │    run complete
+  └─────────────────────────────────┘
+```
+
+## What's Included
+
+- **Entity:** `github-actions-demo` service — a sample entity to receive deploy events
+- **Scorecard:** Deploy Health — Bronze/Silver/Gold based on deploy frequency
+- **GitHub Actions workflow:** `cortex-deploy.yml` — a two-job workflow (build → notify) seeded into your GitHub repo
+- **Cortex workflow:** `github-actions-deploy` — reads the linked repo from the entity, triggers the GitHub Actions deploy, and waits for the result
+- **Setup script:** Interactive wizard that creates and seeds a GitHub repo end-to-end
+
+## Quick Start
+
+1. Install the solution:
+
+   ```
+   cortex solutions install -s github-actions-deploy
+   ```
+
+2. Follow the post-install setup prompts, or run later:
+
+   ```
+   cortex solutions post-install -s github-actions-deploy
+   ```
+
+## How It Works
+
+The Cortex workflow reads `x-cortex-git.github.repository` from the entity's catalog config to determine which GitHub repo to deploy. It triggers `cortex-deploy.yml` via `workflow_dispatch` and waits asynchronously for a callback.
+
+GitHub Actions runs the build, then notifies Cortex twice on completion:
+- **Deploy registration** (`POST /api/v1/catalog/{tag}/deploys`) — records the deploy event on the entity, feeding the Deploy Health scorecard
+- **Workflow callback** — signals the Cortex workflow run as SUCCESS or FAILURE
+
+## After Installing
+
+If you ran the post-install setup, you're already done — it created the GitHub repo, seeded the workflow, set secrets, linked the entity, and triggered a test deploy.
+
+To roll the pattern out to your own services, add `cortex-deploy.yml` to any GitHub repo and link that repo to its Cortex entity. The same **Solution: Add Cortex Deploy from GitHub Actions** workflow will work across all of them — it reads the linked repo from the entity automatically.
+
+## Customizing for Production
+
+- Point the workflow at your real entity by replacing `github-actions-demo` with your service tag
+- Add `CORTEX_API_KEY` and `CORTEX_BASE_URL` secrets to your real repos
+- The Deploy Health scorecard is scoped to `demo-github-actions-deploys` to avoid affecting your
+  existing services. To roll it out broadly, remove the group filter from the scorecard.
+  To opt in individual services, add the `demo-github-actions-deploys` group to them.

cortexapps_cli-1.31.0/cortexapps_cli/solutions/github-actions-deploy/_templates/cortex-async-callback.yml

@@ -0,0 +1,39 @@
+name: Cortex Async Callback
+description: Post a completion status back to a Cortex async workflow callback URL.
+inputs:
+  cortex_api_key:
+    description: Cortex API key
+    required: true
+  cortex_callback_url:
+    description: Cortex async workflow callback URL
+    required: true
+  status:
+    description: Completion status — SUCCESS, FAILURE, or CANCELLED
+    required: true
+  message:
+    description: Optional status message shown in the Cortex workflow run
+    required: false
+    default: ''
+  sha:
+    description: Git commit SHA to include in callback output
+    required: false
+    default: ''
+  run_url:
+    description: GitHub Actions run URL to include in callback output
+    required: false
+    default: ''
+runs:
+  using: composite
+  steps:
+    - name: Post callback
+      shell: bash
+      run: |
+        curl -s -f -X POST "${{ inputs.cortex_callback_url }}" \
+          -H "Authorization: Bearer ${{ inputs.cortex_api_key }}" \
+          -H "Content-Type: application/json" \
+          -d "$(jq -n \
+            --arg status "${{ inputs.status }}" \
+            --arg message "${{ inputs.message }}" \
+            --arg sha "${{ inputs.sha }}" \
+            --arg run_url "${{ inputs.run_url }}" \
+            '{status: $status, message: $message, output: {sha: $sha, run_url: $run_url}}')"

cortexapps_cli-1.31.0/cortexapps_cli/solutions/github-actions-deploy/_templates/cortex-deploy.yml

@@ -0,0 +1,51 @@
+name: Cortex Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      cortex_callback_url:
+        description: 'Cortex async workflow callback URL (set automatically when triggered via Cortex workflow)'
+        required: false
+        default: ''
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: |
+          echo "Starting deployment..."
+          sleep 10
+          for i in 1 2 3; do
+            sleep 5
+            echo "Deployment progress: step $i/3"
+          done
+          echo "Build complete!"
+
+  cortex-callback:
+    needs: build
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Checkout (for local actions)
+        uses: actions/checkout@v4
+
+      - name: Register deploy in Cortex
+        if: needs.build.result == 'success'
+        uses: ./.github/actions/cortex-register-deploy
+        with:
+          cortex_api_key: ${{ secrets.CORTEX_API_KEY }}
+          cortex_base_url: ${{ secrets.CORTEX_BASE_URL }}
+          entity_tag: github-actions-demo
+
+      - name: Cortex async callback
+        if: inputs.cortex_callback_url != ''
+        uses: ./.github/actions/cortex-async-callback
+        with:
+          cortex_api_key: ${{ secrets.CORTEX_API_KEY }}
+          cortex_callback_url: ${{ inputs.cortex_callback_url }}
+          status: ${{ needs.build.result == 'success' && 'SUCCESS' || needs.build.result == 'cancelled' && 'CANCELLED' || 'FAILURE' }}
+          sha: ${{ github.sha }}
+          run_url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

cortexapps_cli-1.31.0/cortexapps_cli/solutions/github-actions-deploy/_templates/cortex-register-deploy.yml

@@ -0,0 +1,51 @@
+name: Cortex Register Deploy
+description: Register a deploy event on a Cortex entity.
+inputs:
+  cortex_api_key:
+    description: Cortex API key
+    required: true
+  cortex_base_url:
+    description: Cortex base URL
+    required: false
+    default: https://api.getcortexapp.com
+  entity_tag:
+    description: Cortex entity tag to register the deploy against
+    required: true
+  environment:
+    description: Deployment environment
+    required: false
+    default: production
+  sha:
+    description: Git commit SHA (defaults to github.sha)
+    required: false
+    default: ''
+runs:
+  using: composite
+  steps:
+    - name: Register deploy
+      shell: bash
+      run: |
+        SHA="${{ inputs.sha }}"
+        SHA="${SHA:-${{ github.sha }}}"
+        curl -s -f -X POST \
+          "${{ inputs.cortex_base_url }}/api/v1/catalog/${{ inputs.entity_tag }}/deploys" \
+          -H "Authorization: Bearer ${{ inputs.cortex_api_key }}" \
+          -H "Content-Type: application/json" \
+          -d "$(jq -n \
+            --arg sha "$SHA" \
+            --arg actor "${{ github.actor }}" \
+            --arg branch "${{ github.ref_name }}" \
+            --arg run_id "${{ github.run_id }}" \
+            --arg run_url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            --arg trigger "${{ github.event_name }}" \
+            --arg env "${{ inputs.environment }}" \
+            --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            '{
+              sha: $sha,
+              timestamp: $timestamp,
+              environment: $env,
+              type: "DEPLOY",
+              title: ("Triggered by " + $actor),
+              deployer: {name: $actor},
+              customData: {branch: $branch, runId: $run_id, runUrl: $run_url, trigger: $trigger}
+            }')"