thothctl 0.25.0__tar.gz → 0.25.2__tar.gz

thothctl-0.25.2/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+      
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false
+          make_latest: true

{thothctl-0.25.0 → thothctl-0.25.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thothctl
-Version: 0.25.0
+Version: 0.25.2
 Summary: A CLI for Developer Control Plane. Accelerate your cloud IaC deployments.
 Project-URL: SourceCode, https://github.com/thothforge/thothctl
 Project-URL: HomePage, https://github.com/thothforge/thothctl

{thothctl-0.25.0 → thothctl-0.25.2}/docs/framework/commands/inventory/inventory_iac.md

@@ -233,6 +233,47 @@ The system auto-generates actionable recommendations based on the metrics:
 - Review components with breaking changes before upgrading
 - Confirmation when infrastructure is well-maintained (score < 20%)
 
+## CDK Project Support (v0.25.0)
+
+The `inventory iac` command now supports **AWS CDK projects** (TypeScript and Python). When `cdk.json` is detected in your project, ThothCTL automatically switches to CDK inventory mode.
+
+### CDK TypeScript
+
+```bash
+# In a CDK TypeScript project
+thothctl inventory iac --check-versions
+# Detects constructs: aws-cdk-lib, cdk-nag, @myorg/cdk-patterns, constructs, etc.
+```
+
+Parses `package.json` and `package-lock.json` to identify CDK construct libraries, then queries the **npm registry** for latest versions and release dates.
+
+### CDK Python
+
+```bash
+# In a CDK Python project
+thothctl inventory iac --check-versions
+# Detects constructs: aws-cdk-lib, cdk-nag, constructs, etc.
+```
+
+Parses `requirements.txt` or `pyproject.toml` to identify CDK construct libraries, then queries **PyPI** for latest versions and release dates.
+
+### Framework Type Flag
+
+You can also explicitly select CDK mode:
+
+```bash
+thothctl inventory iac --framework-type cdkv2 --check-versions
+```
+
+### Notes
+
+- **Auto-detection**: If `cdk.json` exists, CDK mode is selected automatically (no `--framework-type` needed)
+- **Internal packages**: Org-scoped packages (e.g., `@myorg/cdk-patterns`) are listed but not version-checked
+- **Release dates**: Displayed for every public package to show staleness in calendar time
+- **Reports**: CDK constructs appear in HTML, JSON, and CycloneDX SBOM reports using `pkg:npm/` or `pkg:pypi/` PURL schemes
+
+---
+
 ## Framework Type Options
 
 ### Auto-detect Framework (Default)

{thothctl-0.25.0 → thothctl-0.25.2}/docs/framework/commands/inventory/inventory_overview.md

@@ -320,6 +320,59 @@ thothctl inventory iac \
   --project-name "Production Infrastructure - $(date +%B\ %Y)"
 ```
 
+## v0.25.0 — CDK Construct Inventory
+
+Starting with v0.25.0, `thothctl inventory iac --check-versions` supports **AWS CDK projects** (TypeScript and Python). CDK projects are auto-detected when a `cdk.json` file is present in the project root.
+
+### How It Works
+
+| Language | Parsed Files | Registry |
+|----------|-------------|----------|
+| TypeScript | `package.json` + `package-lock.json` | npm registry |
+| Python | `requirements.txt` / `pyproject.toml` | PyPI |
+
+ThothCTL identifies CDK construct libraries (e.g., `aws-cdk-lib`, `cdk-nag`, `@aws-cdk/aws-lambda-python-alpha`) and checks the upstream registry for the latest published version and release date.
+
+### Usage
+
+```bash
+# In a CDK project directory (cdk.json present)
+thothctl inventory iac --check-versions
+```
+
+### Example Output
+
+```
+📦 CDK Construct Inventory — my-cdk-app
+
+  Package                        Current    Latest     Status     Released
+  ─────────────────────────────────────────────────────────────────────────
+  aws-cdk-lib                    2.140.0    2.155.0    Outdated   2026-07-15
+  cdk-nag                        2.28.0     2.34.1     Outdated   2026-06-20
+  constructs                     10.3.0     10.3.0     Current    2026-05-01
+  @aws-cdk/aws-lambda-python-alpha  2.140.0-alpha.0  2.155.0-alpha.0  Outdated  2026-07-15
+  @myorg/cdk-patterns            1.5.0      —          Internal   —
+
+✅ 3 outdated · 1 current · 1 internal (skipped)
+```
+
+### Internal / Org-Scoped Packages
+
+Packages with internal or organization scopes (e.g., `@myorg/cdk-patterns`) are detected and listed in the inventory but are **not** version-checked against a public registry. They appear with status `Internal`.
+
+### Release Dates
+
+For every package checked against npm or PyPI, the **release date** of the latest version is fetched and displayed. This helps teams assess how far behind they are in calendar time, not just version numbers.
+
+### Report Integration
+
+CDK inventory data flows into the same report pipeline:
+- **HTML reports** include a CDK constructs section with version badges
+- **JSON reports** include CDK components in the standard structure
+- **CycloneDX SBOM** maps CDK constructs using the `pkg:npm/` or `pkg:pypi/` PURL scheme
+
+---
+
 ## v0.19.0 Changes
 
 ### 📦 CycloneDX 1.6 SBOM Generation

{thothctl-0.25.0 → thothctl-0.25.2}/docs/framework/commands/workflow/workflow_overview.md

@@ -17,6 +17,7 @@ The workflow command helps DevSecOps teams to:
 | Subcommand | Description |
 |------------|-------------|
 | `devsecops` | Execute DevSecOps SDLC phases (plan, develop, build, test, secure, deploy, monitor) |
+| `run` | Execute a custom composable workflow defined in YAML |
 
 ## Basic Usage
 
@@ -73,6 +74,100 @@ Each phase:
 2. Prints immediate pass/fail/skip after completion
 3. Stops the pipeline on gate failure (`--enforcement hard`)
 
+## Workflow Run (v0.25.0)
+
+The `run` subcommand executes a **custom composable workflow** defined in a YAML file. This enables teams to define their own multi-step pipelines with variables, failure handling, and conditional execution.
+
+### Usage
+
+```bash
+# Run a workflow file
+thothctl workflow run -f workflow.yaml
+
+# Dry-run to preview steps without execution
+thothctl workflow run -f workflow.yaml --dry-run
+```
+
+### YAML Format
+
+Workflow files define a sequence of steps, each invoking a ThothCTL command with optional variables and failure behavior.
+
+```yaml
+# .thothcf_workflow.yaml
+name: pre-merge-checks
+description: Run before merging infrastructure PRs
+
+variables:
+  stacks: "{{changed_stacks}}"
+  branch: "{{branch}}"
+  space: "{{space}}"
+  project: "{{project}}"
+
+steps:
+  - name: inventory
+    command: inventory iac --check-versions
+    on_failure: warn
+
+  - name: security-scan
+    command: scan iac -t checkov -t trivy --stacks {{changed_stacks}}
+    on_failure: block
+
+  - name: cost-analysis
+    command: check iac -type cost-analysis --recursive
+    on_failure: warn
+
+  - name: blast-radius
+    command: check iac -type blast-radius --recursive
+    on_failure: block
+
+  - name: ai-review
+    command: ai-review analyze -d . -p ollama
+    on_failure: skip
+```
+
+### Built-in Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{{changed_stacks}}` | Stacks with changes detected (from git diff) |
+| `{{branch}}` | Current git branch name |
+| `{{space}}` | Active ThothCTL space |
+| `{{project}}` | Active ThothCTL project name |
+
+Variables are resolved at runtime and substituted into step commands.
+
+### Failure Handling (`on_failure`)
+
+Each step defines how to handle failures:
+
+| Value | Behavior |
+|-------|----------|
+| `block` | Stop the workflow immediately with a non-zero exit code |
+| `warn` | Log a warning and continue to the next step |
+| `skip` | Silently skip and continue (useful for optional steps) |
+
+### `--dry-run` Flag
+
+```bash
+thothctl workflow run -f .thothcf_workflow.yaml --dry-run
+```
+
+Prints each step's resolved command without executing it. Useful for validating variable substitution and step order.
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Run pre-merge workflow
+  run: thothctl workflow run -f .thothcf_workflow.yaml
+
+# GitLab CI
+script:
+  - thothctl workflow run -f .thothcf_workflow.yaml
+```
+
+---
+
 ## Related
 
 - [Workflow DevSecOps Command Reference](workflow_devsecops.md)

{thothctl-0.25.0 → thothctl-0.25.2}/docs/framework/use_cases/devsecops_quickstart.md

@@ -9,26 +9,14 @@
 pip install thothctl
 ```
 
-#### Step 2: Create Your First Project
+#### Step 2: Guided Onboarding
 ```bash
-# Initialize a new Terraform project
-thothctl init project -p my-first-infra --project-type terraform
-cd my-first-infra
+thothctl quickstart
 ```
 
-#### Step 3: Check Your Environment
-```bash
-# Verify you have all required tools
-thothctl check environment
-```
-
-#### Step 4: Run Security Scan
-```bash
-# Scan your infrastructure code
-thothctl scan iac -t checkov
-```
+The `quickstart` command interactively walks you through environment detection, space creation, project initialization, and your first security scan — all in one guided flow.
 
-#### Step 5: View Results
+#### Step 3: View Results
 ```bash
 # Launch the dashboard
 thothctl dashboard launch
@@ -36,6 +24,12 @@ thothctl dashboard launch
 
 **🎉 Congratulations!** You've completed your first DevSecOps workflow!
 
+> **Already have a project?** You can skip `quickstart` and jump straight to scanning:
+> ```bash
+> cd my-existing-infra
+> thothctl scan iac -t checkov
+> ```
+
 ---
 
 ## 🎯 Common Use Cases

{thothctl-0.25.0 → thothctl-0.25.2}/docs/quick_start.md

@@ -18,6 +18,14 @@ thothctl --version
 - **Linux**: Requires `graphviz` — `sudo apt install graphviz -y`
 - **macOS**: `brew install graphviz`
 
+## Guided Onboarding (Recommended First Step)
+
+```bash
+thothctl quickstart
+```
+
+The `quickstart` command walks you through initial setup interactively — detecting your environment, selecting a VCS provider, configuring your first space, and running a sample scan. It's the fastest way to get productive with ThothCTL.
+
 ## Setup Autocomplete
 
 ```bash
@@ -43,21 +51,34 @@ Options:
   -d, --code-directory PATH  Configuration file path
   --help                     Show this message and exit.
 
-Commands:
-  ai-review  AI-powered security analysis and code review for IaC
-  check      Validate environment, IaC, cost analysis, and blast radius
-  document   Generate documentation for IaC projects with AI support
-  generate   Generate IaC from rules, use cases, and components
-  init       Initialize and setup project configurations and environments
-  inventory  Create inventory for IaC composition with version tracking
-  list       List projects and spaces managed by thothctl locally
-  mcp        Model Context Protocol (MCP) server for AI integration
-  project    Convert, clean up and manage the current project
-  remove     Remove projects and spaces managed by thothctl
-  scan       Scan infrastructure code for security issues and compliance
-  upgrade    Upgrade thothctl to the latest version
+Getting Started:
+  quickstart  Guided onboarding for new users
+  init        Initialize and setup project configurations and environments
+
+Security & Compliance:
+  scan        Scan infrastructure code for security issues and compliance
+  ai-review   AI-powered security analysis and code review for IaC
+  check       Validate environment, IaC, cost analysis, and blast radius
+
+Infrastructure Management:
+  inventory   Create inventory for IaC composition with version tracking
+  document    Generate documentation for IaC projects with AI support
+  generate    Generate IaC from rules, use cases, and components
+
+Workflow & Orchestration:
+  workflow    Composable DevSecOps pipelines (devsecops, run)
+  dashboard   Web dashboard for visualizing results
+  mcp         Model Context Protocol (MCP) server for AI integration
+
+Project Management:
+  project     Convert, clean up and manage the current project
+  list        List projects and spaces managed by thothctl locally
+  remove      Remove projects and spaces managed by thothctl
+  upgrade     Upgrade thothctl to the latest version
 ```
 
+> **New in v0.25.0**: Commands are now displayed in logical categories. The CLI also warns you on every invocation when a newer version is available.
+
 ## Create a Space
 
 Spaces organize your projects with shared configuration (VCS provider, registry, orchestration tool):
@@ -109,6 +130,9 @@ thothctl check iac -type cost-analysis --recursive
 
 # Drift detection
 thothctl check iac -type drift --recursive
+
+# Dump effective configuration (v0.25.0)
+thothctl check config
 ```
 
 ## Create Inventory

{thothctl-0.25.0 → thothctl-0.25.2}/scripts/check_output_consistency.py

@@ -34,9 +34,9 @@ ALLOWLIST = {
 SKIP_DIRS = {"__pycache__", ".git", "node_modules", "cdk.out", ".venv"}
 
 PATTERNS = [
-    (r'^\s*print\(', 'Use CliUI methods instead of bare print()'),
-    (r'sys\.exit\([\'\"]', 'Use CliUI.print_error() + raise SystemExit(code)'),
-    (r'click\.echo\(', 'Use CliUI methods instead of click.echo()'),
+    (r"^\s*print\(", "Use CliUI methods instead of bare print()"),
+    (r"sys\.exit\([\'\"]", "Use CliUI.print_error() + raise SystemExit(code)"),
+    (r"click\.echo\(", "Use CliUI methods instead of click.echo()"),
 ]
 
 
@@ -113,7 +113,9 @@ def main() -> int:
         return 0  # count-only never blocks
 
     if total_violations > 0:
-        print(f"\n{total_violations} output consistency violation(s) found in {files_with_violations} file(s)")
+        print(
+            f"\n{total_violations} output consistency violation(s) found in {files_with_violations} file(s)"
+        )
         print("Use CliUI (from thothctl.core.cli_ui) for all user-facing output.")
         return 1
 

{thothctl-0.25.0 → thothctl-0.25.2}/src/thothctl/commands/check/commands/config.py

@@ -2,15 +2,13 @@
 
 import os
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Dict
 
-import click
 import toml
 from rich import box
 from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
-from rich.tree import Tree
 
 from ....core.cli_ui import CliUI
 from ....core.commands import ClickCommand
@@ -56,9 +54,13 @@ class CheckConfigCommand(ClickCommand):
         active_file = Path.home() / ".thothcf" / "active_space"
         if active_file.exists():
             space_name = active_file.read_text(encoding="utf-8").strip()
-            self.console.print(f"\n[bold]🌐 Active Space:[/bold] [green]{space_name}[/green]")
+            self.console.print(
+                f"\n[bold]🌐 Active Space:[/bold] [green]{space_name}[/green]"
+            )
         else:
-            self.console.print("\n[bold]🌐 Active Space:[/bold] [dim]None (not set)[/dim]")
+            self.console.print(
+                "\n[bold]🌐 Active Space:[/bold] [dim]None (not set)[/dim]"
+            )
 
     def _show_space_config(self) -> None:
         """Show space-level configuration."""
@@ -150,7 +152,9 @@ class CheckConfigCommand(ClickCommand):
 
             for key, value in env_vars.items():
                 # Mask tokens/secrets
-                if any(s in key.lower() for s in ("token", "secret", "password", "key")):
+                if any(
+                    s in key.lower() for s in ("token", "secret", "password", "key")
+                ):
                     display_value = value[:4] + "****" if len(value) > 4 else "****"
                 else:
                     display_value = value
@@ -184,7 +188,9 @@ class CheckConfigCommand(ClickCommand):
             "> Space (spaces.toml) > Global defaults[/dim]"
         )
 
-    def _flatten_to_table(self, data: Dict, table: Table, source: str, prefix: str = "") -> None:
+    def _flatten_to_table(
+        self, data: Dict, table: Table, source: str, prefix: str = ""
+    ) -> None:
         """Flatten nested dict into table rows."""
         for key, value in data.items():
             full_key = f"{prefix}.{key}" if prefix else key

{thothctl-0.25.0 → thothctl-0.25.2}/src/thothctl/commands/inventory/commands/iac.py

@@ -383,26 +383,99 @@ class IaCInvCommand(ClickCommand):
         if "version_checks" in inventory:
             self.ui.print_info(f"Outdated Components: {outdated_components}")
 
+        # Technical debt
+        self._display_technical_debt(inventory)
+
+    def _display_cdk_summary(self, comp_group: dict) -> None:
+        """Display CDK construct library inventory as a Rich table."""
+        from rich import box
+        from rich.table import Table
+
+        components = comp_group.get("components", [])
+        group_name = comp_group.get("name", "CDK Constructs")
+
+        outdated = sum(1 for c in components if c.get("status") == "Outdated")
+        internal = sum(
+            1
+            for c in components
+            if c.get("name", "").startswith("@")
+            and c.get("name", "").split("/")[0]
+            not in ("@aws-cdk", "@cdklabs", "@aws-solutions-constructs")
+        )
+
+        self.ui.print_info(f"\n📦 {group_name}")
+        self.ui.print_info(
+            f"   Total: {len(components)} | Outdated: {outdated} | Internal: {internal}"
+        )
+
+        # Rich table for CDK constructs
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            box=box.ROUNDED,
+            title=f"🧩 {group_name}",
+        )
+        table.add_column("Package", style="cyan", no_wrap=True)
+        table.add_column("Current", style="white", width=12)
+        table.add_column("Latest", style="green", width=12)
+        table.add_column("Status", width=12)
+        table.add_column("Registry", style="dim", width=8)
+
+        for comp in components:
+            name = comp.get("name", "")
+            version = (
+                comp.get("version", [""])[0]
+                if isinstance(comp.get("version"), list)
+                else comp.get("version", "")
+            )
+            latest = comp.get("latest_version", version)
+            status = comp.get("status", "Unknown")
+            registry = (
+                comp.get("source", [""])[0]
+                if isinstance(comp.get("source"), list)
+                else comp.get("source", "")
+            )
+
+            if status == "Outdated":
+                status_display = "❗ Outdated"
+            elif status == "Updated":
+                status_display = "✅ Current"
+            else:
+                status_display = "— Unknown"
+
+            # Mark internal packages
+            if internal and name.startswith("@"):
+                scope = name.split("/")[0]
+                if scope not in ("@aws-cdk", "@cdklabs", "@aws-solutions-constructs"):
+                    status_display = "🏢 Internal"
+
+            table.add_row(name, version, latest, status_display, registry)
+
+        self.ui.console.print()
+        self.ui.console.print(table)
+
+    def _display_technical_debt(self, inventory: dict) -> None:
+        """Display technical debt metrics."""
         # Display technical debt metrics
         if "technical_debt" in inventory:
             tech_debt = inventory["technical_debt"]
             self.ui.print_info("\n📊 Technical Debt Metrics:")
 
-            # Color-code risk level
+            # Color-code risk level using Rich markup
             risk_level = tech_debt.get("risk_level", "low")
             debt_score = tech_debt.get("debt_score", 0)
 
             if risk_level == "critical":
-                risk_color = Fore.RED
+                risk_style = "bold red"
             elif risk_level == "high":
-                risk_color = Fore.YELLOW
+                risk_style = "bold yellow"
             elif risk_level == "medium":
-                risk_color = Fore.CYAN
+                risk_style = "cyan"
             else:
-                risk_color = Fore.GREEN
+                risk_style = "green"
 
-            self.ui.print_info(
-                f"Debt Score: {risk_color}{debt_score:.1f}%{Fore.RESET} ({risk_level.upper()} risk)"
+            self.ui.console.print(
+                f"  ℹ️ Debt Score: [{risk_style}]{debt_score:.1f}% ({risk_level.upper()} risk)[/{risk_style}]"
             )
             self.ui.print_info(
                 f"Outdated Modules: {tech_debt.get('outdated_modules', 0)}/{tech_debt.get('total_components', 0)}"

{thothctl-0.25.0 → thothctl-0.25.2}/src/thothctl/commands/scan/commands/iac.py

@@ -56,6 +56,19 @@ class RestoredIaCScanCommand(ClickCommand):
             code_directory = ctx.obj.get("CODE_DIRECTORY")
             debug_mode = ctx.obj.get("DEBUG", False)
 
+            # Scope to changed directories if --changed-only is set
+            changed_only = kwargs.get("changed_only", False)
+            if changed_only:
+                from ....utils.git_changes import get_changed_directories
+
+                changed_dirs = get_changed_directories(working_dir=code_directory)
+                self.console.print(
+                    f"[cyan]🔍 Changed directories: {', '.join(changed_dirs)}[/cyan]"
+                )
+                # Scope scan to first changed directory (single-dir scan)
+                if changed_dirs != ["."]:
+                    code_directory = os.path.join(code_directory, changed_dirs[0])
+
             # Set debug environment variable for the scan service
             if debug_mode:
                 os.environ["THOTHCTL_DEBUG"] = "true"
@@ -844,4 +857,10 @@ cli = RestoredIaCScanCommand.as_click_command(
         default="text",
         help="Output format: 'text' (default), 'json' (structured), or 'sarif' (GitHub/IDE compatible)",
     ),
+    click.option(
+        "--changed-only",
+        is_flag=True,
+        default=False,
+        help="Only scan directories with git changes (vs HEAD~1)",
+    ),
 )

{thothctl-0.25.0 → thothctl-0.25.2}/src/thothctl/commands/workflow/commands/devsecops.py

@@ -43,6 +43,21 @@ class DevSecOpsWorkflowCommand(ClickCommand):
         ctx = click.get_current_context()
         directory = ctx.obj.get("CODE_DIRECTORY", ".")
 
+        # Scope to changed directories if --changed-only is set
+        changed_only = kwargs.get("changed_only", False)
+        if changed_only:
+            from ....utils.git_changes import get_changed_directories
+
+            changed_dirs = get_changed_directories(working_dir=directory)
+            console.print(
+                f"[cyan]🔍 Changed directories: {', '.join(changed_dirs)}[/cyan]"
+            )
+            # Scope workflow to first changed directory
+            if changed_dirs != ["."]:
+                import os
+
+                directory = os.path.join(directory, changed_dirs[0])
+
         # Build options from kwargs
         options = {}
         if kwargs.get("policy_dir"):
@@ -260,4 +275,10 @@ cli = DevSecOpsWorkflowCommand.as_click_command(
         default=None,
         help="Override scan tools for secure phase (e.g., -t checkov -t trivy)",
     ),
+    click.option(
+        "--changed-only",
+        is_flag=True,
+        default=False,
+        help="Only process directories with git changes (vs HEAD~1)",
+    ),
 )

{thothctl-0.25.0 → thothctl-0.25.2}/src/thothctl/core/version_tools.py

@@ -15,7 +15,7 @@ version_tools = """[
   },
   {
     "name": "thothctl",
-    "version": "0.25.0"
+    "version": "0.25.2"
   },
   {
     "name": "pre-commit",