feat: add Terraform solution (CX-43)

.claude/skills/cortex-app-urls/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: cortex-app-urls
+description: Use when generating or displaying URLs to the Cortex web application — entity pages, scorecard pages, or any link to the Cortex UI. Covers the correct URL patterns for app.getcortexapp.com and how to derive the app URL from an API base URL.
+---
+
+# Cortex App URL Patterns
+
+## STOP — memorize this before writing any URL or user-facing text
+
+The entity page URL is `/admin/resources?tag=<tag>` for ALL entity types (service, domain, team, resource).
+The scorecard URL requires a **numeric ID**, not a tag: `/admin/scorecards/<numeric-id>`.
+
+Do not guess. Use the table below.
+
+## Terminology
+
+The correct term is **entity** (or **entities**). The word **resource** / **resources** is retired and must not appear in user-facing output, CLI messages, or documentation. The URL path `/admin/resources` is a legacy route but is the correct one to use for entity pages.
+
+## API vs App domains
+
+| Purpose | Domain |
+|---------|--------|
+| API calls | `api.getcortexapp.com` |
+| Web UI links | `app.getcortexapp.com` |
+
+When you have an API base URL (e.g. from `CORTEX_BASE_URL` or the CLI session), derive the app URL by replacing `api.` with `app.`:
+
+```python
+app_url = base_url.replace("api.", "app.", 1) if "api." in base_url else base_url
+```
+
+## Entity page URL (ALL entity types)
+
+```
+https://app.getcortexapp.com/admin/resources?tag=<entity-tag>
+```
+
+This works for services, domains, teams, and resources — all use `/admin/resources?tag=<tag>`.
+
+Example: `https://app.getcortexapp.com/admin/resources?tag=phoenix`
+
+**NOT** `/admin/service/<tag>` — returns "No entity" for teams and domains.
+**NOT** `/admin/catalog/<tag>` — that path does not exist.
+
+## Scorecard page URL (requires numeric ID, not tag)
+
+```
+https://app.getcortexapp.com/admin/scorecards/<numeric-id>
+```
+
+The scorecard detail page uses a numeric `id`, not the tag. Look up the ID first:
+
+```
+GET /api/v1/scorecards/{tag}  →  response["id"]
+```
+
+Then build: `https://app.getcortexapp.com/admin/scorecards/{id}`
+
+**In code — fetch and fall back gracefully:**
+
+```python
+def _fetch_scorecard_id_map(client, scorecard_tags: set[str]) -> dict[str, str]:
+    """Map tag → url_id. Falls back to tag string if API lookup fails."""
+    result: dict[str, str] = {}
+    for tag in scorecard_tags:
+        try:
+            data = client.get(f"api/v1/scorecards/{tag}")
+            sc_id = data.get("id")
+            result[tag] = str(sc_id) if sc_id is not None else tag
+        except Exception:
+            result[tag] = tag
+    return result
+```
+
+## Deploys page URL (entity subpage — requires numeric ID, not tag)
+
+```
+https://app.getcortexapp.com/admin/service/<numeric-entity-id>/deploys
+```
+
+Use `GET /api/v1/catalog/<tag>` → `.id` to get the numeric ID.
+
+## Other common pages
+
+| Page | URL pattern |
+|------|-------------|
+| Entity (all types) | `https://app.getcortexapp.com/admin/resources?tag=<tag>` |
+| Scorecard | `https://app.getcortexapp.com/admin/scorecards/<numeric-id>` |
+| Catalogs | `https://app.getcortexapp.com/admin/catalogs` |
+| Initiatives | `https://app.getcortexapp.com/admin/initiatives` |
+
+## In code
+
+When generating clickable links in terminal output, use OSC 8 hyperlinks for iTerm2/compatible terminals:
+
+```python
+def _hyperlink(url: str, text: str = None) -> str:
+    label = text if text is not None else url
+    return f"\033]8;;{url}\033\\{label}\033]8;;\033\\"
+```

cortexapps_cli/commands/solutions.py

@@ -568,7 +568,84 @@ def _apply_hyperlinks(line: str, entity_tags: set[str], ui_url: str) -> str:
     return "".join(parts)
 
 
-def _show_diagram(readme: str, entity_tags: set[str] | None = None, ui_url: str = "https://app.getcortexapp.com") -> None:
+_GITHUB_BLOB = "https://github.com/cortexapps/cli/blob/main/cortexapps_cli/solutions"
+
+
+def _parse_tf_tags_by_type(solution_dir: Path) -> tuple[set[str], set[str]]:
+    """Scan *.tf files under _templates/<solution>/ and return (entity_tags, scorecard_tags)."""
+    entity_tags: set[str] = set()
+    scorecard_tags: set[str] = set()
+    templates = next(
+        (d for d in (solution_dir / "_templates").iterdir() if d.is_dir() and not d.name.endswith("-delta")),
+        None,
+    ) if (solution_dir / "_templates").exists() else None
+    if templates is None:
+        return entity_tags, scorecard_tags
+    for tf in templates.glob("*.tf"):
+        current_type: str | None = None
+        depth = 0
+        for line in tf.read_text(encoding="utf-8").split("\n"):
+            m = re.match(r'\s*resource\s+"(cortex_\w+)"\s+"[^"]+"\s*\{', line)
+            if m:
+                current_type = m.group(1)
+                depth = 1
+                continue
+            if current_type:
+                depth += line.count("{") - line.count("}")
+                if depth <= 0:
+                    current_type = None
+                    depth = 0
+                    continue
+                tm = re.search(r'\btag\s*=\s*"([^"]+)"', line)
+                if tm:
+                    if current_type == "cortex_catalog_entity":
+                        entity_tags.add(tm.group(1))
+                    elif current_type == "cortex_scorecard":
+                        scorecard_tags.add(tm.group(1))
+    return entity_tags, scorecard_tags
+
+
+def _extract_tf_entity_tags(solution_dir: Path) -> set[str]:
+    """Return only cortex_catalog_entity tags from .tf template files."""
+    entity_tags, _ = _parse_tf_tags_by_type(solution_dir)
+    return entity_tags
+
+
+
+def _apply_file_hyperlinks(line: str, solution_tag: str) -> str:
+    """Replace bare filenames in the diagram with OSC 8 links to GitHub blob URLs."""
+    base = f"{_GITHUB_BLOB}/{solution_tag}/_templates/{solution_tag}"
+    parts = []
+    i = 0
+    while i < len(line):
+        # Look for a word boundary start: not alphanumeric/hyphen/dot before current pos
+        for filename in sorted(
+            (f for f in [
+                "teams.tf", "ecommerce.tf", "supply-chain.tf", "scorecards.tf",
+                "provider.tf", "variables.tf", "terraform.tfvars",
+            ] if line.find(f, i) == i),
+            key=len, reverse=True,
+        ):
+            after = i + len(filename)
+            # Ensure word boundary after: next char must not be alphanumeric
+            if after < len(line) and (line[after].isalnum() or line[after] in "-_."):
+                continue
+            parts.append(_osc8(f"{base}/{filename}", filename))
+            i = after
+            break
+        else:
+            parts.append(line[i])
+            i += 1
+    return "".join(parts)
+
+
+
+def _show_diagram(
+    readme: str,
+    entity_tags: set[str] | None = None,
+    ui_url: str = "https://app.getcortexapp.com",
+    solution_tag: str = "",
+) -> None:
     block = _extract_first_codeblock(readme)
     if not block:
         return
@@ -577,23 +654,26 @@ def _show_diagram(readme: str, entity_tags: set[str] | None = None, ui_url: str
 
     print()
     for line in block.split("\n"):
-        if entity_tags and links_supported:
-            line = _apply_hyperlinks(line, entity_tags, ui_url)
+        if links_supported:
+            if entity_tags:
+                line = _apply_hyperlinks(line, entity_tags, ui_url)
+            if solution_tag:
+                line = _apply_file_hyperlinks(line, solution_tag)
         # Use print() not console.print(): Rich counts OSC 8 escape bytes as
         # visible characters, shifting ASCII art alignment.
         print(f"  {line}")
 
     if entity_tags and not links_supported:
-        diagram_tags = sorted(
+        entity_rows = sorted(
             (tag for tag in entity_tags if tag in block),
             key=lambda t: t.lower(),
         )
-        if diagram_tags:
+        if entity_rows:
             print()
             table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0))
             table.add_column("Entity")
             table.add_column("URL")
-            for tag in diagram_tags:
+            for tag in entity_rows:
                 table.add_row(tag, f"{ui_url}/admin/resources?tag={tag}")
             console.print(table)
 
@@ -612,18 +692,21 @@ def _post_install_menu(
     import_report: str = "",
     entity_tags: set[str] | None = None,
     ui_url: str = "https://app.getcortexapp.com",
+    solution_tag: str = "",
 ) -> None:
     options = [
         ("1", "Data Model"),
         ("2", "Next steps"),
-        ("3", "Import report"),
-        ("4", "Exit"),
     ]
     actions = {
-        "1": lambda: _show_diagram(readme, entity_tags=entity_tags, ui_url=ui_url),
+        "1": lambda: _show_diagram(readme, entity_tags=entity_tags, ui_url=ui_url, solution_tag=solution_tag),
         "2": lambda: _show_next_steps(readme),
-        "3": lambda: (console.print(), typer.echo(import_report)),
     }
+    if import_report:
+        options.append(("3", "Import report"))
+        actions["3"] = lambda: (console.print(), typer.echo(import_report))
+    exit_key = str(len(options) + 1)
+    options.append((exit_key, "Exit"))
 
     while True:
         console.print()
@@ -634,7 +717,7 @@ def _post_install_menu(
 
         choice = Prompt.ask("Choice", choices=[k for k, _ in options], show_choices=False)
 
-        if choice == "4":
+        if choice == exit_key:
             break
         actions[choice]()
 
@@ -731,9 +814,23 @@ def _do_import() -> None:
                     with as_file(root / solution) as sp:
                         resources = _collect_solution_resources(sp)
                 entity_tags = set(resources.get("catalog", []))
+                if solutions_dir:
+                    entity_tags |= _extract_tf_entity_tags(root / solution)
+                else:
+                    with as_file(root / solution) as sp:
+                        entity_tags |= _extract_tf_entity_tags(sp)
             except Exception:
                 pass
-            _post_install_menu(readme, import_report=output, entity_tags=entity_tags, ui_url=ui_url)
+            has_import_results = bool(
+                total_match and (int(total_match.group(1)) > 0 or int(total_match.group(2)) > 0)
+            )
+            _post_install_menu(
+                readme,
+                import_report=output if has_import_results else "",
+                entity_tags=entity_tags,
+                ui_url=ui_url,
+                solution_tag=solution,
+            )
 
 
 @app.command(name="post-install")

cortexapps_cli/solutions/harness-deploy/setup.py

@@ -231,7 +231,7 @@ def post_steps(self) -> None:
         base_url = self._answers["cortex_base_url"].rstrip("/")
         app_url = base_url.replace("api.", "app.", 1) if "api." in base_url else base_url
         entity_tag = self._answers["entity_tag"]
-        cortex_url = f"{app_url}/admin/resources?tag={entity_tag}"  # /admin/resources is the correct URL path (entity terminology in UI)
+        cortex_url = f"{app_url}/admin/resources?tag={entity_tag}"
 
         harness_pipeline_url = (
             f"{self._harness_base()}/ng/account/{self._harness_account()}"