augint-org 0.1.0__py3-none-any.whl

ai_org/__init__.py

@@ -0,0 +1,32 @@
+"""AI-ORG: AWS Organization management CLI with Control Tower integration.
+
+This package provides a comprehensive command-line interface for managing AWS Organizations
+with AWS Control Tower. It automates account creation, SSO permission assignment, and
+StackSet deployment monitoring for Control Tower organizations.
+
+Key Features:
+    - Automated account creation with proper OU placement
+    - SSO permission management and assignment
+    - StackSet deployment monitoring and status checking
+    - Configuration management with caching
+    - Enterprise-grade DevOps automation
+
+Example:
+    Basic usage example::
+
+        >>> from ai_org.cli import cli
+        >>> # Use CLI commands: ai-org account create, ai-org sso assign, etc.
+
+Modules:
+    cli: Main CLI entry point and command routing
+    commands: Command implementations for account, SSO, StackSet, and config management
+    core: Core business logic and AWS service managers
+    utils: Utility functions for caching, output formatting, and validation
+
+Attributes:
+    __version__: Package version string
+"""
+
+from ai_org.__version__ import __version__
+
+__all__ = ["__version__"]

ai_org/__version__.py

@@ -0,0 +1,10 @@
+"""Version information for augint-org."""
+
+import importlib.metadata
+
+try:
+    # Get version from installed package metadata
+    __version__ = importlib.metadata.version("augint-org")
+except importlib.metadata.PackageNotFoundError:
+    # Fallback for development
+    __version__ = "0.0.0-dev"

ai_org/cli.py

@@ -0,0 +1,132 @@
+"""Main CLI entry point for AI-ORG AWS Organization management tool.
+
+This module defines the primary command-line interface for AI-ORG, including:
+- Command-line argument parsing and validation
+- Global configuration and context management
+- Error handling and user-friendly output formatting
+- Integration with all command modules (account, SSO, StackSet, config)
+
+The CLI supports both interactive usage and automation through JSON output modes,
+making it suitable for both manual operations and CI/CD pipeline integration.
+
+Example:
+    Basic CLI usage::
+
+        $ ai-org --help
+        $ ai-org account create lls-staging lls-staging@company.com --wait
+        $ ai-org sso assign 123456789012 --principal jane@company.com
+        $ ai-org stackset status 123456789012 --wait
+"""
+
+import sys
+from typing import Optional
+
+import click
+from dotenv import load_dotenv
+from rich.console import Console
+
+from ai_org.__version__ import __version__
+from ai_org.commands import account, billing, config, dns, ou, sso, stackset
+from ai_org.utils.output import OutputFormatter
+
+# Load .env file from current directory if it exists
+load_dotenv()
+
+console = Console()
+output = OutputFormatter()
+
+
+@click.group(invoke_without_command=True)
+@click.option(
+    "--profile",
+    envvar="AWS_PROFILE",
+    help="AWS profile to use (default: from config or 'org')",
+)
+@click.option(
+    "--region",
+    envvar="AWS_REGION",
+    default="us-east-1",
+    help="AWS region (default: from config or 'us-east-1')",
+)
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+@click.option("--json", is_flag=True, help="Output in JSON format for automation")
+@click.version_option(version=__version__, prog_name="ai-org")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    profile: Optional[str],
+    region: str,
+    debug: bool,
+    json: bool,
+) -> None:
+    """AI-ORG: Manage AWS Organization accounts with Control Tower.
+
+    This tool automates AWS account creation, SSO permission assignment,
+    and StackSet deployment monitoring for Control Tower organizations.
+
+    Quick start:
+      ai-org config init        # Initialize configuration
+      ai-org account create     # Create new account
+      ai-org sso assign         # Assign SSO permissions
+
+    Environment Variables:
+      AWS_PROFILE: Default AWS profile name
+      AWS_REGION: Default AWS region
+    """
+    # Store options in context
+    ctx.ensure_object(dict)
+    ctx.obj["profile"] = profile
+    ctx.obj["region"] = region
+    ctx.obj["debug"] = debug
+    ctx.obj["json"] = json
+    ctx.obj["output"] = output
+
+    # Set output format
+    output.set_json_mode(json)
+
+    # Show help if no command provided
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# Add command groups
+cli.add_command(account.account)
+cli.add_command(billing.billing)
+cli.add_command(dns.dns)
+cli.add_command(ou.ou)
+cli.add_command(sso.sso)
+cli.add_command(stackset.stackset)
+cli.add_command(config.config)
+
+
+def main() -> int:
+    """Main entry point for the CLI application.
+
+    Handles top-level exception catching and returns appropriate exit codes
+    for different types of errors encountered during execution.
+
+    Returns:
+        Exit code: 0 for success, 1 for general errors, 130 for keyboard interrupt
+
+    Raises:
+        SystemExit: Always exits with appropriate code based on execution result
+    """
+    try:
+        cli()
+        return 0
+    except click.ClickException as e:
+        e.show()
+        return 1
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted[/yellow]")
+        return 130
+    except Exception as e:
+        if "--debug" in sys.argv:
+            console.print_exception()
+        else:
+            console.print(f"[red]Error:[/red] {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ai_org/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for ai-org CLI."""

ai_org/commands/account.py

@@ -0,0 +1,191 @@
+"""Account management commands."""
+
+from typing import Optional
+
+import click
+
+from ai_org.core.account_factory import AccountFactory
+from ai_org.core.account_manager import AccountManager
+from ai_org.core.ou_manager import OUManager
+
+
+@click.group()
+def account() -> None:
+    """Manage AWS accounts in the organization."""
+
+
+@account.command()
+@click.argument("name")
+@click.argument("email")
+def create(name: str, email: str) -> None:
+    """Create a new AWS account (NOT IMPLEMENTED).
+
+    \b
+    Arguments:
+      NAME    Account name (e.g., "Staging LandlineScrubber")
+      EMAIL   Root email address for the account
+    """
+    raise click.ClickException(
+        "Account creation via CLI is not currently implemented.\n"
+        "\nPlease create accounts manually via Control Tower console:\n"
+        "1. Go to AWS Control Tower → Account Factory\n"
+        "2. Create account with desired name and email\n"
+        "3. Wait for provisioning to complete (20-30 mins)\n"
+        "4. Use 'ai-org dns delegate <account-name> --prefix <prefix>' for DNS\n"
+        "\nExample: ai-org dns delegate 'Staging LandlineScrubber' --prefix lls"
+    )
+
+
+@account.command(name="list")
+@click.option("--ou", help="Filter by OU ID")
+@click.option("--status", default="ACTIVE", help="Filter by status (ACTIVE, SUSPENDED)")
+@click.option("--no-tree", is_flag=True, help="Don't show OU tree structure")
+@click.pass_context
+def list_accounts(ctx: click.Context, ou: Optional[str], status: str, no_tree: bool) -> None:
+    """List accounts in the organization.
+
+    \b
+    Examples:
+      ai-org account list
+      ai-org account list --ou ou-55d0-workloads
+      ai-org account list --status SUSPENDED
+      ai-org account list --no-tree  # Skip OU tree display
+    """
+    output = ctx.obj["output"]
+    manager = AccountManager(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        # Show OU structure first (unless --no-tree or --json)
+        if not no_tree and not ctx.obj.get("json"):
+            ou_manager = OUManager(
+                profile=ctx.obj.get("profile"),
+                region=ctx.obj.get("region"),
+            )
+            try:
+                ou_tree = ou_manager.get_ou_tree()
+                output.info("Organization Structure:")
+                tree_str = ou_manager.format_ou_tree(ou_tree)
+                output.text(tree_str)
+                output.text("")  # Empty line for spacing
+            except Exception:
+                # If we can't get OU tree, just skip it
+                pass
+
+        # Get accounts with OU information
+        accounts = manager.list_accounts_with_ou(ou=ou, status=status)
+
+        if ctx.obj.get("json"):
+            output.json_output(accounts)
+        else:
+            # Format OU path for display
+            for account in accounts:
+                # Build OU path
+                if account.get("ParentType") == "ROOT":
+                    account["OU"] = "Root"
+                elif account.get("ParentName"):
+                    account["OU"] = account["ParentName"]
+                else:
+                    account["OU"] = account.get("ParentId", "Unknown")
+
+            output.table(
+                accounts,
+                columns=["Id", "Name", "Email", "Status", "OU"],
+                title=f"AWS Accounts ({status})",
+            )
+    except Exception as e:
+        output.error(f"Failed to list accounts: {e}")
+        raise click.ClickException(str(e)) from e
+
+
+@account.command()
+@click.argument("account-id")
+@click.pass_context
+def get(ctx: click.Context, account_id: str) -> None:
+    """Get details for a specific account.
+
+    \b
+    Arguments:
+      ACCOUNT-ID    AWS account ID (12 digits)
+
+    \b
+    Example:
+      ai-org account get 123456789012
+    """
+    output = ctx.obj["output"]
+    manager = AccountManager(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        account = manager.get_account(account_id)
+        if ctx.obj.get("json"):
+            output.json_output(account)
+        else:
+            output.dict_display(account, title=f"Account {account_id}")
+    except Exception as e:
+        output.error(f"Failed to get account: {e}")
+        raise click.ClickException(str(e)) from e
+
+
+@account.command()
+@click.argument("account-id")
+@click.pass_context
+def enrollment_status(ctx: click.Context, account_id: str) -> None:
+    """Check Control Tower enrollment status for an account.
+
+    \b
+    Arguments:
+      ACCOUNT-ID    AWS account ID (12 digits)
+
+    \b
+    Example:
+      ai-org account enrollment-status 123456789012
+
+    This command checks if an account is enrolled in Control Tower
+    and shows the enrollment status and related information.
+    """
+    output = ctx.obj["output"]
+    factory = AccountFactory(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        output.progress(f"Checking enrollment status for account {account_id}...")
+        status = factory.get_enrollment_status(account_id)
+
+        if ctx.obj.get("json"):
+            output.json_output(status)
+        else:
+            # Display enrollment information
+            if "error" in status:
+                output.error(f"Error: {status['error']}")
+                return
+
+            output.info(f"Account: {status['account_name']} ({status['account_id']})")
+            output.info(f"Email: {status['account_email']}")
+            output.info(f"Status: {status['account_status']}")
+            output.info(f"Parent OU: {status['parent_ou']}")
+
+            if status["enrolled"]:
+                output.success(f"✅ Enrollment Status: {status['enrollment_status']}")
+                if "control_tower_stacks" in status:
+                    output.info(f"Control Tower Stacks: {status['control_tower_stacks']}")
+            else:
+                output.warning(f"⚠️  Enrollment Status: {status['enrollment_status']}")
+                output.info("\nTo enroll this account in Control Tower:")
+                output.info("1. Go to the Control Tower console")
+                output.info("2. Navigate to Organization > Accounts")
+                output.info("3. Find this account and click 'Enroll'")
+                output.info("\nOr re-create the account using:")
+                output.info(
+                    f"  ai-org account create {status['account_name']} {status['account_email']} --ou <OU_NAME>"
+                )
+
+    except Exception as e:
+        output.error(f"Failed to check enrollment status: {e}")
+        raise click.ClickException(str(e)) from e

ai_org/commands/billing.py

@@ -0,0 +1,238 @@
+"""Billing management commands for AWS account cost passthrough via Stripe."""
+
+import click
+
+from ai_org.core.billing_manager import BillingManager
+
+
+@click.group()
+def billing() -> None:
+    """Manage Stripe billing for AWS accounts."""
+
+
+@billing.command()
+@click.pass_context
+def setup(ctx: click.Context) -> None:
+    """One-time Stripe product setup.
+
+    This will:
+    1. Create a product in Stripe for AWS Infrastructure Services
+    2. Create a price with monthly billing
+    3. Display the product and price IDs for reference
+
+    \b
+    Example:
+      ai-org billing setup
+    """
+    output = ctx.obj["output"]
+    from ai_org.core.aws_client import AWSClient
+
+    aws_client = AWSClient(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        manager = BillingManager(aws_client)
+
+        # Check which key we're using
+        import os
+
+        if os.getenv("TEST_STRIPE_SECRET_KEY"):
+            output.info("Setting up Stripe products for AWS billing (TEST MODE)...")
+            output.warning("Using TEST Stripe key - safe for testing")
+        else:
+            output.info("Setting up Stripe products for AWS billing...")
+            if os.getenv("STRIPE_SECRET_KEY", "").startswith("sk_test_"):
+                output.warning("Using TEST Stripe key - safe for testing")
+            else:
+                output.warning("Using PRODUCTION Stripe key - real charges will occur")
+
+        result = manager.setup_stripe_products()
+
+        output.success("\nStripe products created successfully!")
+        output.info("\nProduct Details:")
+        output.info(f"  Product ID: {result['product_id']}")
+        output.info(f"  Price ID: {result['price_id']}")
+        output.info("\nNext steps:")
+        output.info("  1. Enable EventBridge integration in Stripe Dashboard")
+        output.info(f"  2. AWS Account ID for EventBridge: {aws_client.account_id}")
+        output.info("  3. Select region: us-east-1")
+        output.info("  4. Link AWS accounts to Stripe customers using 'ai-org billing link'")
+
+        if ctx.obj.get("json_output"):
+            output.print_json(result)
+
+    except Exception as e:
+        output.error(f"Failed to setup Stripe products: {e}")
+        ctx.exit(1)
+
+
+@billing.command()
+@click.argument("account_id")
+@click.argument("stripe_customer_id")
+@click.pass_context
+def link(ctx: click.Context, account_id: str, stripe_customer_id: str) -> None:
+    """Link AWS account to Stripe customer.
+
+    \b
+    Arguments:
+      ACCOUNT_ID          AWS account ID to link
+      STRIPE_CUSTOMER_ID  Stripe customer ID (e.g., cus_xxx)
+
+    \b
+    Example:
+      ai-org billing link 123456789012 cus_AbCdEfGhIjKl
+
+    This creates a mapping in DynamoDB that the Lambda function will use
+    to calculate and bill AWS costs for this account to the Stripe customer.
+    """
+    output = ctx.obj["output"]
+    from ai_org.core.aws_client import AWSClient
+
+    aws_client = AWSClient(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        manager = BillingManager(aws_client)
+
+        # Validate account ID format
+        if not account_id.isdigit() or len(account_id) != 12:
+            output.error(f"Invalid AWS account ID format: {account_id}")
+            output.info("Account ID must be 12 digits")
+            ctx.exit(1)
+
+        # Validate Stripe customer ID format
+        if not stripe_customer_id.startswith("cus_"):
+            output.error(f"Invalid Stripe customer ID format: {stripe_customer_id}")
+            output.info("Stripe customer ID should start with 'cus_'")
+            ctx.exit(1)
+
+        output.info(f"Linking AWS account {account_id} to Stripe customer {stripe_customer_id}...")
+
+        manager.link_account(account_id, stripe_customer_id)
+
+        output.success(
+            f"\nSuccessfully linked account {account_id} to customer {stripe_customer_id}"
+        )
+        output.info("\nBilling will begin with the next invoice cycle.")
+
+        if ctx.obj.get("json_output"):
+            output.print_json(
+                {
+                    "account_id": account_id,
+                    "stripe_customer_id": stripe_customer_id,
+                    "status": "linked",
+                }
+            )
+
+    except Exception as e:
+        output.error(f"Failed to link account: {e}")
+        ctx.exit(1)
+
+
+@billing.command("list")
+@click.pass_context
+def list_mappings(ctx: click.Context) -> None:
+    """List all AWS account to Stripe customer mappings.
+
+    \b
+    Example:
+      ai-org billing list
+
+    Shows all configured billing relationships between AWS accounts
+    and Stripe customers.
+    """
+    output = ctx.obj["output"]
+    from ai_org.core.aws_client import AWSClient
+
+    aws_client = AWSClient(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        manager = BillingManager(aws_client)
+        output.info("Fetching billing mappings...")
+
+        mappings = manager.list_mappings()
+
+        if not mappings:
+            output.info("\nNo billing mappings configured.")
+            output.info("Use 'ai-org billing link' to add mappings.")
+        else:
+            output.info(f"\nFound {len(mappings)} billing mapping(s):\n")
+
+            if ctx.obj.get("json_output"):
+                output.json_output(mappings)
+            else:
+                # Format for table display
+                table_data = []
+                for mapping in mappings:
+                    table_data.append(
+                        {
+                            "Stripe Customer": mapping["stripe_customer_id"],
+                            "AWS Accounts": ", ".join(mapping.get("aws_accounts", [])),
+                            "Created": mapping.get("created_at", "Unknown"),
+                        }
+                    )
+
+                output.table(
+                    table_data,
+                    columns=["Stripe Customer", "AWS Accounts", "Created"],
+                    title="Billing Mappings",
+                )
+
+    except Exception as e:
+        output.error(f"Failed to list mappings: {e}")
+        ctx.exit(1)
+
+
+@billing.command()
+@click.argument("account_id")
+@click.pass_context
+def unlink(ctx: click.Context, account_id: str) -> None:
+    """Remove AWS account from billing.
+
+    \b
+    Arguments:
+      ACCOUNT_ID  AWS account ID to unlink
+
+    \b
+    Example:
+      ai-org billing unlink 123456789012
+
+    This removes the account from billing. The account will not be
+    included in future invoices.
+    """
+    output = ctx.obj["output"]
+    from ai_org.core.aws_client import AWSClient
+
+    aws_client = AWSClient(
+        profile=ctx.obj.get("profile"),
+        region=ctx.obj.get("region"),
+    )
+
+    try:
+        manager = BillingManager(aws_client)
+
+        # Validate account ID format
+        if not account_id.isdigit() or len(account_id) != 12:
+            output.error(f"Invalid AWS account ID format: {account_id}")
+            output.info("Account ID must be 12 digits")
+            ctx.exit(1)
+
+        output.info(f"Unlinking AWS account {account_id} from billing...")
+
+        manager.unlink_account(account_id)
+
+        output.success(f"\nSuccessfully unlinked account {account_id} from billing")
+
+        if ctx.obj.get("json_output"):
+            output.print_json({"account_id": account_id, "status": "unlinked"})
+
+    except Exception as e:
+        output.error(f"Failed to unlink account: {e}")
+        ctx.exit(1)