cortexapps-cli 1.36.0__tar.gz → 1.38.0__tar.gz

{cortexapps_cli-1.36.0 → cortexapps_cli-1.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexapps-cli
-Version: 1.36.0
+Version: 1.38.0
 Summary: Command Line Interface for cortexapps
 License: MIT
 License-File: LICENSE

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/README.md

@@ -0,0 +1,175 @@
+---
+name: Monorepo
+description: Model a real monorepo in Cortex — five Cortex services mapped to subdirectories of a single public GitHub repo, each scoped by basepath.
+---
+
+# Monorepo
+
+This solution demonstrates the monorepo pattern in Cortex using mock services inside the [`cortexapps/cli`](https://github.com/cortexapps/cli) repo. Five Cortex service entities each map to their own subdirectory under `cortexapps_cli/solutions/monorepo/services/`, complete with a `cortex.yaml`, a `README.md`, and mock source code. Each entity sees only the commits, PRs, and files in its own directory.
+
+```
+  https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services
+  ════════════════════════════════════════════════════════════════════════
+  │
+  ├── cli-core/                 ──►  ┌─────────────────────────────────┐
+  │                                  │  monorepo-demo-cli-core         │
+  │                                  │  Core CLI package               │
+  │                                  │  src/cli.py                     │
+  │                                  └─────────────────────────────────┘
+  │
+  ├── cli-commands/             ──►  ┌─────────────────────────────────┐
+  │                                  │  monorepo-demo-cli-commands     │
+  │                                  │  Command implementations        │
+  │                                  │  src/commands.py                │
+  │                                  └─────────────────────────────────┘
+  │
+  ├── cli-solutions/            ──►  ┌─────────────────────────────────┐
+  │                                  │  monorepo-demo-cli-solutions    │
+  │                                  │  Solutions framework            │
+  │                                  │  src/solutions.py               │
+  │                                  └─────────────────────────────────┘
+  │
+  ├── cli-tests/                ──►  ┌─────────────────────────────────┐
+  │                                  │  monorepo-demo-cli-tests        │
+  │                                  │  Integration test suite         │
+  │                                  │  src/test_cli.py                │
+  │                                  └─────────────────────────────────┘
+  │
+  └── cli-docker/               ──►  ┌─────────────────────────────────┐
+                                     │  monorepo-demo-cli-docker       │
+                                     │  Container infrastructure       │
+                                     │  Dockerfile                     │
+                                     └─────────────────────────────────┘
+```
+
+Each service directory has this structure:
+
+```
+services/
+└── cli-core/
+    ├── cortex.yaml      ← Cortex entity definition (GitOps discoverable)
+    ├── README.md        ← Service documentation
+    └── src/
+        └── cli.py       ← Mock source code
+```
+
+Each entity is defined like this (the `x-cortex-git` block lives under `info:`):
+
+```yaml
+info:
+  x-cortex-tag: monorepo-demo-cli-core
+  x-cortex-git:
+    github:
+      alias: cortex-cli        # only needed with multiple GitHub integrations, and your repo isn't under the default
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-core
+```
+
+All five entities are tagged with the group `monorepo-demo` for easy catalog filtering.
+
+## What's Included
+
+**5 service entities** (group: `monorepo-demo`)
+
+| Tag | basepath | Description |
+|---|---|---|
+| `monorepo-demo-cli-core` | `services/cli-core` | Core CLI — Typer app, HTTP client, config, utils |
+| `monorepo-demo-cli-commands` | `services/cli-commands` | Command implementations per Cortex resource |
+| `monorepo-demo-cli-solutions` | `services/cli-solutions` | Solutions framework — installable bundles |
+| `monorepo-demo-cli-tests` | `services/cli-tests` | Integration test suite against live Cortex API |
+| `monorepo-demo-cli-docker` | `services/cli-docker` | Container infra — published `cortexapp/cli` image |
+
+> Full basepaths are prefixed with `cortexapps_cli/solutions/monorepo/` — shortened above for readability.
+
+**1 scorecard** — `monorepo-component-health` — Bronze/Silver/Gold:
+- Bronze: has description + git configured with basepath
+- Silver: belongs to at least one group
+- Gold: verified within 90 days
+
+**5 `cortex.yaml` files** committed into the repo — one per component — so GitOps discovers them automatically once GitHub is connected.
+
+## Installation
+
+```
+cortex solutions install -s monorepo
+cortex solutions post-install -s monorepo
+```
+
+The install step creates all 5 entities and the scorecard immediately. The post-install step configures the `cortex-cli` GitHub integration (PAT) so Cortex can read the repo.
+
+## After Installing
+
+**Create a catalog**
+
+1. Go to [Catalogs](https://app.getcortexapp.com/admin/catalogs) → **New Catalog**
+2. Name it **Monorepo Demo**
+3. Set the catalog filter:
+   - **Entity type:** `service`
+   - **Advanced options → Groups → Include:** `monorepo-demo`
+
+> Catalog creation will be automated once catalog API support is added to the CLI.
+
+## GitOps Auto-Discovery
+
+Once the `cortex-cli` integration is set up, add the repo in Cortex → **Settings → GitOps**:
+
+```
+Repository: cortexapps/cli
+```
+
+Cortex will find the five `cortex.yaml` files and keep entities in sync with any changes pushed to the repo:
+
+```
+cortexapps_cli/solutions/monorepo/services/cli-core/cortex.yaml       →  monorepo-demo-cli-core
+cortexapps_cli/solutions/monorepo/services/cli-commands/cortex.yaml   →  monorepo-demo-cli-commands
+cortexapps_cli/solutions/monorepo/services/cli-solutions/cortex.yaml  →  monorepo-demo-cli-solutions
+cortexapps_cli/solutions/monorepo/services/cli-tests/cortex.yaml      →  monorepo-demo-cli-tests
+cortexapps_cli/solutions/monorepo/services/cli-docker/cortex.yaml     →  monorepo-demo-cli-docker
+```
+
+## Testing GitOps
+
+To see GitOps discovery in action, delete one or more entities and let Cortex recreate them from the `cortex.yaml` files in the repo.
+
+**Step 1 — Delete an entity (or all of them):**
+
+```bash
+# Delete a single entity
+cortex catalog delete --tag monorepo-demo-cli-core --force
+
+# Or delete all five at once
+cortex catalog delete --tag monorepo-demo-cli-core --force
+cortex catalog delete --tag monorepo-demo-cli-commands --force
+cortex catalog delete --tag monorepo-demo-cli-solutions --force
+cortex catalog delete --tag monorepo-demo-cli-tests --force
+cortex catalog delete --tag monorepo-demo-cli-docker --force
+```
+
+**Step 2 — Configure GitOps (if not already done):**
+
+1. Go to **Settings → GitOps** in the Cortex UI
+2. Click **Add Repository**
+3. Enter `cortexapps/cli` and select the `cortex-cli` integration
+4. Save — Cortex will immediately scan the repo for `cortex.yaml` files
+
+**Step 3 — Trigger a sync:**
+
+GitOps syncs automatically on each push to the repo. To trigger a manual sync without pushing:
+
+1. Go to **Catalogs → All Entities**
+2. Click **Import Entities → Import Manually**
+3. Select **GitHub**
+4. Follow the prompts to select the `cortexapps/cli` repository
+
+Cortex will find the `cortex.yaml` files in each subdirectory and recreate the deleted entities exactly as defined — group, git basepath, description, and all.
+
+## Adapting for Your Own Monorepo
+
+1. Add a `cortex.yaml` to each component subdirectory in your repo
+2. Set `x-cortex-git.github.repository` and `basepath` for each component
+3. Add `x-cortex-git.github.alias` if you have more than one GitHub integration configured and your repo isn't under the default
+4. Add a consistent group tag to all components (e.g. `my-monorepo`)
+5. Add GitOps → your repo in Cortex Settings
+6. Cortex discovers and syncs all components automatically
+
+The `basepath` is what splits one repo into many scoped entities — each service sees only the activity in its own directory.

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/catalog/cli-commands.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-commands
+  x-cortex-tag: monorepo-demo-cli-commands
+  x-cortex-type: service
+  x-cortex-description: CLI command implementations — one module per Cortex resource (catalog, scorecards, teams, etc.)
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-commands
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-commands

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/catalog/cli-core.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-core
+  x-cortex-tag: monorepo-demo-cli-core
+  x-cortex-type: service
+  x-cortex-description: Core CLI package — Typer app, HTTP client, config, and output utilities
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-core
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-core

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/catalog/cli-docker.yaml

@@ -0,0 +1,20 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-docker
+  x-cortex-tag: monorepo-demo-cli-docker
+  x-cortex-type: service
+  x-cortex-description: Container infrastructure — Dockerfile and config for the published cortexapp/cli Docker image
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-docker
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-docker
+    - name: Docker Hub
+      type: documentation
+      url: https://hub.docker.com/r/cortexapp/cli

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/catalog/cli-solutions.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-solutions
+  x-cortex-tag: monorepo-demo-cli-solutions
+  x-cortex-type: service
+  x-cortex-description: Solutions framework — bundled Cortex solution packages that can be installed via the CLI
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-solutions
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-solutions

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/catalog/cli-tests.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-tests
+  x-cortex-tag: monorepo-demo-cli-tests
+  x-cortex-type: service
+  x-cortex-description: Integration test suite — pytest tests that run against a live Cortex API
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-tests
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-tests

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/scorecards/monorepo-component-health.yaml

@@ -0,0 +1,54 @@
+tag: monorepo-component-health
+name: Monorepo Component Health
+description: Checks that each component within a monorepo is documented, owned, linked to its subdirectory, and actively maintained.
+draft: false
+notifications:
+  enabled: true
+  scoreDropNotificationsEnabled: true
+exemptions:
+  enabled: true
+  autoApprove: false
+  userSpecificNotifications: false
+evaluation:
+  window: 24
+ladder:
+  name: Default Ladder
+  levels:
+    - name: Bronze
+      rank: 1
+      description: The component is discoverable — it has a description and a git reference scoped to its subdirectory.
+      color: "#CD7F32"
+    - name: Silver
+      rank: 2
+      description: The component is well-classified — it belongs to at least one group so it can be filtered and reported on.
+      color: "#C0C0C0"
+    - name: Gold
+      rank: 3
+      description: The component is actively verified as alive and its metadata is current.
+      color: "#D7AC58"
+filter:
+  category: SERVICE
+rules:
+  - title: Component has a description
+    description: Every monorepo component should have a description so developers understand its purpose without reading the source.
+    expression: entity.description().length > 0
+    weight: 1
+    level: Bronze
+
+  - title: Component has git configured with a basePath
+    description: The component's x-cortex-git must be set so Cortex can scope PRs, commits, and code coverage to this subdirectory.
+    expression: git != null
+    weight: 1
+    level: Bronze
+
+  - title: Component belongs to at least one group
+    description: Tag this component with a group (e.g. monorepo-demo) so it can be filtered and reported on across the catalog.
+    expression: groups().length > 0
+    weight: 1
+    level: Silver
+
+  - title: Component verified in the last 90 days
+    description: An engineer has confirmed this component is still in active use and its Cortex metadata is accurate.
+    expression: verifications().lastVerifiedAt() != null and verifications().lastVerifiedAt().fromNow() > duration("P-90D")
+    weight: 1
+    level: Gold

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-commands/README.md

@@ -0,0 +1,3 @@
+# cli-commands
+
+This package contains the command implementations for each Cortex resource. Each module maps to one resource type (catalog, scorecards, teams, workflows, etc.).

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-commands/cortex.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-commands
+  x-cortex-tag: monorepo-demo-cli-commands
+  x-cortex-type: service
+  x-cortex-description: CLI command implementations — one module per Cortex resource (catalog, scorecards, teams, etc.)
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-commands
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-commands

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-commands/src/commands.py

@@ -0,0 +1,22 @@
+"""
+cli-commands — command implementations per Cortex resource.
+"""
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+def list_entities():
+    """List all catalog entities."""
+    print("Listing entities from cli-commands...")
+
+
+@app.command()
+def get_entity(tag: str):
+    """Get a single entity by tag."""
+    print(f"Fetching entity: {tag}")
+
+
+if __name__ == "__main__":
+    app()

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-core/README.md

@@ -0,0 +1,3 @@
+# cli-core
+
+This is the core CLI package. It provides the main Typer application, the HTTP client for communicating with the Cortex API, shared config management, and output utilities used across all commands.

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-core/cortex.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-core
+  x-cortex-tag: monorepo-demo-cli-core
+  x-cortex-type: service
+  x-cortex-description: Core CLI package — Typer app, HTTP client, config, and output utilities
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-core
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-core

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-core/src/cli.py

@@ -0,0 +1,16 @@
+"""
+cli-core — main entry point and HTTP client for the Cortex CLI.
+"""
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+def hello(name: str = "world"):
+    """Say hello from the core CLI package."""
+    print(f"Hello, {name}! This is cli-core.")
+
+
+if __name__ == "__main__":
+    app()

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-docker/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY . .
+
+RUN pip install cortexapps-cli
+
+ENTRYPOINT ["cortex"]
+CMD ["--help"]

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-docker/README.md

@@ -0,0 +1,3 @@
+# cli-docker
+
+Container infrastructure for the Cortex CLI. Publishes the `cortexapp/cli` Docker image to Docker Hub on every release.

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-docker/cortex.yaml

@@ -0,0 +1,20 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-docker
+  x-cortex-tag: monorepo-demo-cli-docker
+  x-cortex-type: service
+  x-cortex-description: Container infrastructure — Dockerfile and config for the published cortexapp/cli Docker image
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-docker
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-docker
+    - name: Docker Hub
+      type: documentation
+      url: https://hub.docker.com/r/cortexapp/cli

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-solutions/README.md

@@ -0,0 +1,3 @@
+# cli-solutions
+
+This package implements the solutions framework — the mechanism for packaging, distributing, and installing pre-built Cortex configurations (entities, scorecards, workflows) as installable bundles.

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-solutions/cortex.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-solutions
+  x-cortex-tag: monorepo-demo-cli-solutions
+  x-cortex-type: service
+  x-cortex-description: Solutions framework — bundled Cortex solution packages that can be installed via the CLI
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-solutions
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-solutions

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-solutions/src/solutions.py

@@ -0,0 +1,18 @@
+"""
+cli-solutions — framework for installable Cortex solution bundles.
+"""
+
+
+def install(solution_name: str) -> None:
+    """Install a named solution bundle."""
+    print(f"Installing solution: {solution_name}")
+
+
+def list_solutions() -> list:
+    """Return available solution names."""
+    return ["monorepo", "backstage-migration", "team-health"]
+
+
+if __name__ == "__main__":
+    for s in list_solutions():
+        print(f"  - {s}")

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-tests/README.md

@@ -0,0 +1,3 @@
+# cli-tests
+
+Integration test suite for the Cortex CLI. Tests run against a live Cortex API and require a valid `CORTEX_API_KEY` environment variable.

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-tests/cortex.yaml

@@ -0,0 +1,17 @@
+openapi: "3.0.0"
+info:
+  title: monorepo-demo-cli-tests
+  x-cortex-tag: monorepo-demo-cli-tests
+  x-cortex-type: service
+  x-cortex-description: Integration test suite — pytest tests that run against a live Cortex API
+  x-cortex-groups:
+    - monorepo-demo
+  x-cortex-git:
+    github:
+      alias: cortex-cli
+      repository: cortexapps/cli
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-tests
+  x-cortex-link:
+    - name: GitHub
+      type: repo
+      url: https://github.com/cortexapps/cli/tree/main/cortexapps_cli/solutions/monorepo/services/cli-tests

cortexapps_cli-1.38.0/cortexapps_cli/solutions/monorepo/services/cli-tests/src/test_cli.py

@@ -0,0 +1,20 @@
+"""
+cli-tests — integration tests for the Cortex CLI.
+"""
+
+
+def test_hello():
+    """Basic smoke test."""
+    assert True, "Hello from cli-tests!"
+
+
+def test_entity_list():
+    """Verify entity list returns results."""
+    entities = ["mock-service-a", "mock-service-b"]
+    assert len(entities) > 0
+
+
+if __name__ == "__main__":
+    test_hello()
+    test_entity_list()
+    print("All tests passed.")