structkit 3.0.0__py3-none-any.whl

structkit/commands/info.py

@@ -0,0 +1,87 @@
+import os
+import yaml
+import asyncio
+
+from structkit.commands import Command
+
+# Info command class for exposing information about the structure
+class InfoCommand(Command):
+    def __init__(self, parser):
+      super().__init__(parser)
+      parser.description = "Show information about the package or structure definition"
+      parser.add_argument('structure_definition', type=str, help='Name of the structure definition')
+      parser.add_argument('-s', '--structures-path', type=str, help='Path to structure definitions')
+      parser.add_argument('--mcp', action='store_true', help='Enable MCP (Model Context Protocol) integration')
+
+      parser.set_defaults(func=self.execute)
+
+    def execute(self, args):
+      self.logger.info(f"Getting info for structure {args.structure_definition}")
+
+      if args.mcp:
+        self._get_info_mcp(args)
+      else:
+        self._get_info(args)
+
+    def _get_info(self, args):
+      if args.structure_definition.startswith("file://") and args.structure_definition.endswith(".yaml"):
+        with open(args.structure_definition[7:], 'r') as f:
+          config = yaml.safe_load(f)
+      else:
+        if args.structures_path is None:
+          this_file = os.path.dirname(os.path.realpath(__file__))
+          file_path = os.path.join(this_file, "..", "contribs", f"{args.structure_definition}.yaml")
+        else:
+          file_path = os.path.join(args.structures_path, f"{args.structure_definition}.yaml")
+        # show error if file is not found
+        if not os.path.exists(file_path):
+          self.logger.error(f"❗ File not found: {file_path}")
+          return
+        with open(file_path, 'r') as f:
+          config = yaml.safe_load(f)
+
+      print("📒 Structure definition\n")
+      print(f"   📌 Name: {args.structure_definition}\n")
+      print(f"   📌 Description: {config.get('description', 'No description')}\n")
+
+      if config.get('files'):
+        print(f"   📌 Files:")
+        for item in config.get('files', []):
+          for name, content in item.items():
+            print(f"       - {name} ")
+            # indent all lines of content
+            # for line in content.get('content', content.get('file', 'Not defined')).split('\n'):
+            #   print(f"       {line}")
+
+      if config.get('folders'):
+        print(f"   📌 Folders:")
+        for folder in config.get('folders', []):
+          print(f"     - {folder}")
+          # print(f"     - {folder}: {folder.get('struct', 'No structure')}")
+
+    def _get_info_mcp(self, args):
+      """Get structure info using MCP integration."""
+      try:
+        from structkit.mcp_server import StructMCPServer
+
+        async def run_mcp_info():
+          server = StructMCPServer()
+          arguments = {
+            "structure_name": args.structure_definition
+          }
+          if args.structures_path:
+            arguments["structures_path"] = args.structures_path
+
+          result = await server._handle_get_structure_info(arguments)
+          return result.content[0].text
+
+        result_text = asyncio.run(run_mcp_info())
+        print(result_text)
+
+      except ImportError:
+        self.logger.error("MCP support not available. Install with: pip install mcp")
+        self._get_info(args)
+      except Exception as e:
+        self.logger.error(f"MCP integration error: {e}")
+        self.logger.info("Falling back to standard info mode")
+        self._get_info(args)

structkit/commands/init.py

@@ -0,0 +1,52 @@
+from structkit.commands import Command
+import os
+import textwrap
+
+BASIC_STRUCTKIT_YAML = textwrap.dedent(
+    """
+    # Generated by `structkit init`
+    # Edit as needed to customize your project bootstrap
+
+    pre_hooks:
+      - echo "Starting structkit generation"
+
+    post_hooks:
+      - echo "Structkit generation completed"
+
+    files:
+      - README.md: |
+          # Project
+
+          Initialized with struct.
+
+    folders:
+      - ./:
+          struct:
+            - github/workflows/run-struct
+    """
+).lstrip()
+
+class InitCommand(Command):
+  def __init__(self, parser):
+    super().__init__(parser)
+    parser.description = "Initialize a basic .struct.yaml in the target directory"
+    parser.add_argument('path', nargs='?', default='.', help='Directory to initialize (default: current directory)')
+    parser.set_defaults(func=self.execute)
+
+  def execute(self, args):
+    base_path = os.path.abspath(args.path or '.')
+    target = os.path.join(base_path, '.struct.yaml')
+
+    os.makedirs(base_path, exist_ok=True)
+
+    # If file exists, do not overwrite without explicit confirmation behavior (keep simple: skip)
+    if os.path.exists(target):
+      self.logger.info(f".struct.yaml already exists at {target}, skipping creation")
+      print(f"⚠️  .struct.yaml already exists at: {target}")
+      return
+
+    with open(target, 'w') as f:
+      f.write(BASIC_STRUCTKIT_YAML)
+
+    print("✅ Created .struct.yaml")
+    print(f" - {target}")

structkit/commands/list.py

@@ -0,0 +1,89 @@
+from structkit.commands import Command
+import os
+import yaml
+import asyncio
+from structkit.file_item import FileItem
+from structkit.utils import project_path
+
+# List command class
+class ListCommand(Command):
+  def __init__(self, parser):
+    super().__init__(parser)
+    parser.description = "List available structures"
+    parser.add_argument('-s', '--structures-path', type=str, help='Path to structure definitions')
+    parser.add_argument('--names-only', action='store_true', help='Print only structure names, one per line (for shell completion)')
+    parser.add_argument('--mcp', action='store_true', help='Enable MCP (Model Context Protocol) integration')
+    parser.set_defaults(func=self.execute)
+
+  def execute(self, args):
+    self.logger.info(f"Listing available structures")
+    if args.mcp:
+      self._list_structures_mcp(args)
+    else:
+      self._list_structures(args)
+
+  def _list_structures(self, args):
+    this_file = os.path.dirname(os.path.realpath(__file__))
+    contribs_path = os.path.join(this_file, "..", "contribs")
+
+    if args.structures_path:
+      final_path = args.structures_path
+      paths_to_list = [final_path, contribs_path]
+    else:
+      paths_to_list = [contribs_path]
+
+    all_structures = set()
+    for path in paths_to_list:
+      for root, _, files in os.walk(path):
+        for file in files:
+            file_path = os.path.join(root, file)
+            rel_path = os.path.relpath(file_path, path)
+            if file.endswith(".yaml"):
+              rel_path = rel_path[:-5]
+              # Mark custom path entries with '+ ' unless names-only requested
+              if not args.names_only and path != contribs_path:
+                rel_path = f"+ {rel_path}"
+              all_structures.add(rel_path)
+
+    sorted_list = sorted(all_structures)
+
+    if args.names_only:
+      # Print plain names without bullets or headers, remove '+ ' marker
+      for structure in sorted_list:
+        if structure.startswith('+ '):
+          print(structure[2:])
+        else:
+          print(structure)
+      return
+
+    print("📃 Listing available structures\n")
+    for structure in sorted_list:
+      print(f" - {structure}")
+
+    print("\nUse 'structkit generate' to generate the structure")
+    print("Note: Structures with '+' sign are custom structures")
+
+  def _list_structures_mcp(self, args):
+    """List structures using MCP integration."""
+    try:
+      from structkit.mcp_server import StructMCPServer
+
+      async def run_mcp_list():
+        server = StructMCPServer()
+        arguments = {}
+        if args.structures_path:
+          arguments["structures_path"] = args.structures_path
+
+        result = await server._handle_list_structures(arguments)
+        return result.content[0].text
+
+      result_text = asyncio.run(run_mcp_list())
+      print(result_text)
+
+    except ImportError:
+      self.logger.error("MCP support not available. Install with: pip install mcp")
+      self._list_structures(args)
+    except Exception as e:
+      self.logger.error(f"MCP integration error: {e}")
+      self.logger.info("Falling back to standard list mode")
+      self._list_structures(args)

structkit/commands/mcp.py

@@ -0,0 +1,100 @@
+import asyncio
+import logging
+from structkit.commands import Command
+from structkit.mcp_server import StructMCPServer
+
+
+# MCP command class for starting the MCP server (FastMCP stdio only)
+class MCPCommand(Command):
+    def __init__(self, parser):
+        super().__init__(parser)
+        parser.description = "MCP (Model Context Protocol) using FastMCP transports (stdio, http, sse)"
+        parser.add_argument('--server', action='store_true',
+                          help='Start the MCP server')
+        parser.add_argument('--transport', choices=['stdio', 'http', 'sse'], default='stdio',
+                          help='Transport protocol for the MCP server (default: stdio)')
+        # HTTP/SSE options
+        parser.add_argument('--host', type=str, default='127.0.0.1', help='Host to bind for HTTP/SSE transports')
+        parser.add_argument('--port', type=int, default=8000, help='Port to bind for HTTP/SSE transports')
+        parser.add_argument('--path', type=str, default='/mcp', help='Endpoint path for HTTP/SSE transports')
+        parser.add_argument('--uvicorn-log-level', dest='uvicorn_log_level', type=str, default=None,
+                          help='Log level for the HTTP server (e.g., info, warning, error)')
+        parser.add_argument('--stateless-http', action='store_true', default=None,
+                          help='Use stateless HTTP mode (HTTP transport only)')
+        parser.add_argument('--no-banner', dest='show_banner', action='store_false', default=True,
+                          help='Disable FastMCP startup banner')
+        # Debugging options
+        parser.add_argument('--debug', action='store_true', help='Enable debug mode (sets structkit and FastMCP loggers to DEBUG by default)')
+        parser.add_argument('--fastmcp-log-level', dest='fastmcp_log_level', type=str, default=None,
+                          help='Log level for FastMCP internals (e.g., DEBUG, INFO). Overrides --debug for FastMCP if provided')
+        parser.set_defaults(func=self.execute)
+
+    def execute(self, args):
+        if args.server:
+            self.logger.info(
+                f"Starting FastMCP server for structkit tool (transport={args.transport})"
+            )
+            asyncio.run(self._start_mcp_server(args))
+        else:
+            print("MCP (Model Context Protocol) support for structkit tool (FastMCP)")
+            print("\nAvailable options:")
+            print("  --server                 Start the MCP server")
+            print("  --transport {stdio|http|sse}  Transport protocol (default: stdio)")
+            print("  --host HOST              Host for HTTP/SSE (default: 127.0.0.1)")
+            print("  --port PORT              Port for HTTP/SSE (default: 8000)")
+            print("  --path /PATH             Endpoint path for HTTP/SSE (default: /mcp)")
+            print("  --stateless-http         Enable stateless HTTP mode (HTTP only)")
+            print("  --no-banner              Disable FastMCP banner")
+            print("  --debug                  Enable debug mode (structkit + FastMCP DEBUG; uvicorn=debug)")
+            print("  --fastmcp-log-level LVL  Set FastMCP logger level (overrides --debug for FastMCP)")
+            print("\nMCP tools available:")
+            print("  - list_structures: List all available structure definitions")
+            print("  - get_structure_info: Get detailed information about a structure")
+            print("  - generate_structure: Generate structures with various options")
+            print("  - validate_structure: Validate structure configuration files")
+            print("\nExamples:")
+            print("  structkit mcp --server --transport stdio --debug")
+            print("  structkit mcp --server --transport http --host 127.0.0.1 --port 9000 --path /mcp --uvicorn-log-level debug")
+            print("  structkit mcp --server --transport sse --host 0.0.0.0 --port 8080 --path /events --fastmcp-log-level DEBUG")
+
+    async def _start_mcp_server(self, args=None):
+        """Start the MCP server using the selected transport."""
+        try:
+            server = StructMCPServer()
+            transport = getattr(args, 'transport', 'stdio') if args else 'stdio'
+            # Map CLI args to server.run kwargs
+            run_kwargs = {
+                "transport": transport,
+                "show_banner": getattr(args, 'show_banner', True) if args else True,
+            }
+            # Determine FastMCP logger level
+            fastmcp_log_level = None
+            if args:
+                fastmcp_log_level = getattr(args, 'fastmcp_log_level', None)
+                if not fastmcp_log_level and getattr(args, 'debug', False):
+                    fastmcp_log_level = 'DEBUG'
+            if fastmcp_log_level:
+                run_kwargs["fastmcp_log_level"] = fastmcp_log_level
+
+            if transport in {"http", "sse"}:
+                # uvicorn expects lowercase levels like "info"/"debug"
+                uvicorn_level = None
+                if args:
+                    uvicorn_level = getattr(args, 'uvicorn_log_level', None)
+                    if not uvicorn_level and getattr(args, 'debug', False):
+                        uvicorn_level = 'debug'
+                    if not uvicorn_level:
+                        # Default to args.log if provided, else None
+                        uvicorn_level = getattr(args, 'log', None)
+                run_kwargs.update({
+                    "host": getattr(args, 'host', None),
+                    "port": getattr(args, 'port', None),
+                    "path": getattr(args, 'path', None),
+                    "log_level": (uvicorn_level.lower() if isinstance(uvicorn_level, str) else uvicorn_level),
+                })
+                if transport == "http":
+                    run_kwargs["stateless_http"] = getattr(args, 'stateless_http', None)
+            await server.run(**run_kwargs)
+        except Exception as e:
+            self.logger.error(f"Error starting MCP server: {e}")
+            raise

structkit/commands/validate.py

@@ -0,0 +1,129 @@
+import os
+import yaml
+from dotenv import load_dotenv
+from structkit.commands import Command
+
+load_dotenv()
+
+# Validate command class
+class ValidateCommand(Command):
+    def __init__(self, parser):
+      super().__init__(parser)
+      parser.description = "Validate a YAML configuration file for structure definitions"
+      parser.add_argument('yaml_file', type=str, help='Path to the YAML configuration file')
+      parser.set_defaults(func=self.execute)
+
+    def execute(self, args):
+      self.logger.info(f"Validating {args.yaml_file}")
+
+      with open(args.yaml_file, 'r') as f:
+        config = yaml.safe_load(f)
+
+      # Validate pre_hooks and post_hooks if present
+      for hook_key in ["pre_hooks", "post_hooks"]:
+        if hook_key in config:
+          if not isinstance(config[hook_key], list):
+            raise ValueError(f"The '{hook_key}' key must be a list of shell commands (strings).")
+          for cmd in config[hook_key]:
+            if not isinstance(cmd, str):
+              raise ValueError(f"Each item in '{hook_key}' must be a string (shell command).")
+
+      if 'structure' in config and 'files' in config:
+          self.logger.warning("Both 'structure' and 'files' keys exist. Prioritizing 'structure'.")
+      self._validate_structure_config(config.get('structure') or config.get('files', []))
+      self._validate_folders_config(config.get('folders', []))
+      self._validate_variables_config(config.get('variables', []))
+
+
+    # Validate the 'folders' key in the configuration file
+    # folders should be defined as a list of dictionaries
+    # each dictionary should have a 'struct' key
+    #
+    # Example:
+    # folders:
+    #   - .devops/modules/my_module_one:
+    #       struct: terraform/module
+    #   - .devops/modules/my_module_two:
+    #       struct: terraform/module
+    #       with:
+    #         module_name: my_module_two
+    def _validate_folders_config(self, folders):
+      if not isinstance(folders, list):
+        raise ValueError("The 'folders' key must be a list.")
+      for item in folders:
+        if not isinstance(item, dict):
+            raise ValueError("Each item in the 'folders' list must be a dictionary.")
+        for name, content in item.items():
+            if not isinstance(name, str):
+              raise ValueError("Each name in the 'folders' item must be a string.")
+            if not isinstance(content, dict):
+              raise ValueError(f"The content of '{name}' must be a dictionary.")
+            if 'struct' not in content:
+              raise ValueError(f"Dictionary item '{name}' must contain a 'struct' key.")
+            if not isinstance(content['struct'], str) and not isinstance(content['struct'], list):
+              raise ValueError(f"The 'struct' value for '{name}' must be a string.")
+            if 'with' in content and not isinstance(content['with'], dict):
+              raise ValueError(f"The 'with' value for '{name}' must be a dictionary.")
+
+
+    # Validate the 'variables' key in the configuration file
+    # variables should be defined as a list of dictionaries
+    # each dictionary should have a 'name' key and optionall 'default' value
+    #
+    # Example:
+    # variables:
+    #   - session_name:
+    #       type: string
+    #       default: my_session
+    #   - project_name:
+    #       type: string
+    #       default: my_project
+    #       help: The name of the project
+    def _validate_variables_config(self, variables):
+      if not isinstance(variables, list):
+        raise ValueError("The 'variables' key must be a list.")
+      for item in variables:
+        if not isinstance(item, dict):
+            raise ValueError("Each item in the 'variables' list must be a dictionary.")
+        for name, content in item.items():
+            if not isinstance(name, str):
+              raise ValueError("Each name in the 'variables' item must be a string.")
+            if not isinstance(content, dict):
+              raise ValueError(f"The content of '{name}' must be a dictionary.")
+            if 'type' not in content:
+              raise ValueError(f"Dictionary item '{name}' must contain a 'type' key.")
+            if content['type'] not in ['string', 'number', 'boolean']:
+              raise ValueError(f"Invalid type for '{name}'. Must be 'string', 'number' or 'boolean'.")
+            if 'default' in content and content['type'] == 'boolean' and not isinstance(content['default'], bool):
+              raise ValueError(f"Invalid default value for '{name}'. Must be a boolean.")
+
+
+    def _validate_structure_config(self, structure):
+      if not isinstance(structure, list):
+        raise ValueError("The 'structure' key must be a list.")
+      for item in structure:
+        if not isinstance(item, dict):
+            raise ValueError("Each item in the 'structure' list must be a dictionary.")
+        for name, content in item.items():
+            if not isinstance(name, str):
+              raise ValueError("Each name in the 'structure' item must be a string.")
+            if isinstance(content, dict):
+              # Check that any of the keys 'content', 'file' or 'prompt' is present
+              if 'content' not in content and 'file' not in content and 'user_prompt' not in content:
+                raise ValueError(f"Dictionary item '{name}' must contain either 'content' or 'file' or 'user_prompt' key.")
+              # Check if 'file' key is present and its value is a string
+              if 'file' in content and not isinstance(content['file'], str):
+                raise ValueError(f"The 'file' value for '{name}' must be a string.")
+              # Check if 'permissions' key is present and its value is a string
+              if 'permissions' in content and not isinstance(content['permissions'], str):
+                raise ValueError(f"The 'permissions' value for '{name}' must be a string.")
+              # Check if 'prompt' key is present and its value is a string
+              if 'prompt' in content and not isinstance(content['prompt'], str):
+                raise ValueError(f"The 'prompt' value for '{name}' must be a string.")
+              if 'skip' in content and not isinstance(content['skip'], bool):
+                raise ValueError(f"The 'skip' value for '{name}' must be a string.")
+              if 'skip_if_exists' in content and not isinstance(content['skip_if_exists'], bool):
+                raise ValueError(f"The 'skip_if_exists' value for '{name}' must be a string.")
+            elif not isinstance(content, str):
+              raise ValueError(f"The content of '{name}' must be a string or dictionary.")
+      self.logger.info("Configuration validation passed.")

structkit/completers.py

@@ -0,0 +1,54 @@
+import os
+
+class ChoicesCompleter(object):
+    def __init__(self, choices):
+        self.choices = choices
+
+    def __call__(self, **kwargs):
+        return self.choices
+
+
+class StructuresCompleter(object):
+    """Dynamic completer for available structure names."""
+
+    def __init__(self, structures_path=None):
+        self.structures_path = structures_path
+
+    def __call__(self, prefix, parsed_args, **kwargs):
+        """Return list of available structure names for completion."""
+        return self._get_available_structures(parsed_args)
+
+    def _get_available_structures(self, parsed_args):
+        """Get list of available structure names, similar to ListCommand logic."""
+        # Get the directory where the commands are located
+        this_file = os.path.dirname(os.path.realpath(__file__))
+        contribs_path = os.path.join(this_file, "contribs")
+
+        # Check if custom structures path is provided via parsed_args
+        structures_path = getattr(parsed_args, 'structures_path', None) or self.structures_path
+
+        if structures_path:
+            paths_to_list = [structures_path, contribs_path]
+        else:
+            paths_to_list = [contribs_path]
+
+        all_structures = set()
+        for path in paths_to_list:
+            if not os.path.exists(path):
+                continue
+
+            for root, _, files in os.walk(path):
+                for file in files:
+                    if file.endswith(".yaml"):
+                        file_path = os.path.join(root, file)
+                        rel_path = os.path.relpath(file_path, path)
+                        # Remove .yaml extension
+                        structure_name = rel_path[:-5]
+                        all_structures.add(structure_name)
+
+        return sorted(list(all_structures))
+
+
+log_level_completer = ChoicesCompleter(['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'])
+file_strategy_completer = ChoicesCompleter(['overwrite', 'skip', 'append', 'rename', 'backup'])
+structures_completer = StructuresCompleter()