emcd-agents 1.0a0__py3-none-any.whl

agentsmgr/__/__init__.py

@@ -0,0 +1,25 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common constants, imports, and utilities. '''
+
+
+from .imports import *
+from .nomina import *

agentsmgr/__/imports.py

@@ -0,0 +1,56 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common imports used throughout the package. '''
+
+# ruff: noqa: F401
+
+
+import                      abc
+import                      asyncio
+import collections.abc as   cabc
+import contextlib as        ctxl
+import dataclasses as       dcls
+import                      enum
+import functools as         funct
+import                      os
+import                      shutil
+import                      sys
+import                      tempfile
+import                      types
+
+from logging import getLogger as provide_scribe
+from pathlib import Path
+
+
+import accretive as         accret
+import                      appcore
+import                      appcore.exceptions
+import                      appcore.state
+import dynadoc as           ddoc
+import frigid as            immut
+import                      tomli
+import typing_extensions as typx
+# --- BEGIN: Injected by Copier ---
+import tyro
+# --- END: Injected by Copier ---
+
+from absence import Absential, absent, is_absent
+from appcore import cli as appcore_cli

agentsmgr/__/nomina.py

@@ -0,0 +1,32 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common names and type aliases. '''
+
+
+from . import imports as __
+
+
+ComparisonResult: __.typx.TypeAlias = bool | __.types.NotImplementedType
+NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
+PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ]
+
+
+package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]

agentsmgr/__init__.py

@@ -0,0 +1,40 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common collection of AI agents configuration and data. '''
+
+
+from . import __
+# --- BEGIN: Injected by Copier ---
+from . import exceptions
+# --- END: Injected by Copier ---
+from . import sources
+
+
+__version__ = '1.0a0'
+
+
+def main( ):
+    ''' Entrypoint. '''
+    from .cli import execute
+    execute( )
+
+
+# TODO: Reclassify package modules as immutable and concealed.

agentsmgr/__main__.py

@@ -0,0 +1,28 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Entrypoint. '''
+
+
+# Note: Use absolute import for PyInstaller happiness.
+from agentsmgr.cli import execute
+
+
+if '__main__' == __name__: execute( )

agentsmgr/_typedecls/dulwich/__init__.pyi

@@ -0,0 +1 @@
+# Minimal type stubs for dulwich

agentsmgr/_typedecls/dulwich/porcelain.pyi

@@ -0,0 +1,11 @@
+# Minimal type stubs for dulwich.porcelain
+
+from typing import Any
+
+def clone(
+    source: str,
+    target: str,
+    bare: bool = False,
+    depth: int | None = None,
+    **kwargs: Any
+) -> Any: ...

agentsmgr/_typedecls/dulwich/repo.pyi

@@ -0,0 +1,28 @@
+# Type stubs for dulwich.repo
+
+from typing import Any, Dict
+
+class GitCommit:
+    commit_time: int
+    object: bytes | None
+
+class GitRefs:
+    def as_dict(self, prefix: bytes) -> Dict[bytes, bytes]: ...
+    def __contains__(self, key: bytes) -> bool: ...
+    def __getitem__(self, key: bytes) -> bytes: ...
+
+class Repo:
+    def __init__(self, path: str) -> None: ...
+
+    @property
+    def refs(self) -> GitRefs: ...
+
+    @property
+    def object_store(self) -> Any: ...
+
+    @property
+    def path(self) -> str: ...
+
+    def __getitem__(self, key: bytes) -> GitCommit: ...
+
+    def open_index(self) -> Any: ...

agentsmgr/cli.py

@@ -0,0 +1,70 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Command-line interface. '''
+
+
+from . import __
+from . import commands as _commands
+from . import core as _core
+
+
+class Application( __.appcore_cli.Application ):
+    ''' Agent configuration management CLI. '''
+
+    display: _core.DisplayOptions = __.dcls.field(
+        default_factory = _core.DisplayOptions )
+    command: __.typx.Union[
+        __.typx.Annotated[
+            _commands.DetectCommand,
+            __.tyro.conf.subcommand( 'detect', prefix_name = False ),
+        ],
+        __.typx.Annotated[
+            _commands.PopulateCommand,
+            __.tyro.conf.subcommand( 'populate', prefix_name = False ),
+        ],
+        __.typx.Annotated[
+            _commands.ValidateCommand,
+            __.tyro.conf.subcommand( 'validate', prefix_name = False ),
+        ],
+    ] = __.dcls.field( default_factory = _commands.DetectCommand )
+
+    async def execute( self, auxdata: _core.Globals ) -> None:  # pyright: ignore[reportIncompatibleMethodOverride]
+        ''' Executes the specified command. '''
+        await self.command( auxdata )
+
+    async def prepare( self, exits: __.ctxl.AsyncExitStack ) -> _core.Globals:
+        ''' Prepares agentsmgr-specific global state with display options. '''
+        auxdata_base = await super( ).prepare( exits )
+        nomargs = {
+            field.name: getattr( auxdata_base, field.name )
+            for field in __.dcls.fields( auxdata_base )
+            if not field.name.startswith( '_' ) }
+        return _core.Globals( display = self.display, **nomargs )
+
+
+def execute( ) -> None:
+    ''' Entrypoint for CLI execution. '''
+    config = ( __.tyro.conf.HelptextFromCommentsOff, )
+    try: __.asyncio.run( __.tyro.cli( Application, config = config )( ) )
+    except SystemExit: raise
+    except BaseException:
+        # TODO: Log exception.
+        raise SystemExit( 1 ) from None

agentsmgr/commands/__.py

@@ -0,0 +1,32 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Centralized imports for commands subpackage. '''
+
+
+# ruff: noqa: F403
+
+
+from ..__ import *
+from ..core import *
+from ..exceptions import *
+from ..renderers import *
+from ..results import *
+from ..sources import *

agentsmgr/commands/__init__.py

@@ -0,0 +1,26 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Command implementations for agentsmgr CLI. '''
+
+
+from .detection import DetectCommand
+from .population import PopulateCommand
+from .validation import ValidateCommand

agentsmgr/commands/base.py

@@ -0,0 +1,153 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Shared infrastructure for command implementations.
+
+    This module provides common utilities used across multiple command
+    implementations, including error handling, configuration management,
+    and data location resolution.
+'''
+
+
+import yaml as _yaml
+
+from . import __
+
+
+CoderConfiguration: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
+
+
+def intercept_errors( ) -> __.cabc.Callable[
+    [ __.cabc.Callable[
+        ..., __.cabc.Coroutine[ __.typx.Any, __.typx.Any, None ] ] ],
+    __.cabc.Callable[
+        ..., __.cabc.Coroutine[ __.typx.Any, __.typx.Any, None ] ]
+]:
+    ''' Decorator for CLI command handlers to intercept and render errors.
+
+        Provides clean separation between business logic and error handling:
+
+        **Purpose**: Enables command implementations to focus purely on
+        business logic while the decorator handles all error presentation
+        concerns.
+
+        **Responsibilities**:
+
+        - Intercepts Omnierror exceptions from command execution
+        - Renders errors in appropriate format (markdown for CLI)
+        - Ensures proper exit code handling (SystemExit with code 1)
+
+        **Pattern**: Commands implement business logic and raise exceptions;
+        decorator handles presentation and process termination. This
+        separation ensures commands remain testable and focused.
+
+        **Type narrowing note**: The isinstance(auxdata, _core.Globals)
+        checks in individual command execute methods serve type narrowing
+        purposes and must be retained for proper type checking.
+    '''
+    def decorator(
+        function: __.cabc.Callable[
+            ..., __.cabc.Coroutine[ __.typx.Any, __.typx.Any, None ] ]
+    ) -> __.cabc.Callable[
+        ..., __.cabc.Coroutine[ __.typx.Any, __.typx.Any, None ]
+    ]:
+        @__.funct.wraps( function )
+        async def wrapper(
+            self: __.typx.Any,
+            auxdata: __.typx.Any,
+            *posargs: __.typx.Any,
+            **nomargs: __.typx.Any,
+        ) -> None:
+            try: return await function( self, auxdata, *posargs, **nomargs )
+            except __.Omnierror as exception:
+                if isinstance( auxdata, __.Globals ):
+                    await __.render_and_print_result(
+                        exception, auxdata.display, auxdata.exits )
+                else:
+                    for line in exception.render_as_markdown( ):
+                        print( line, file = __.sys.stderr )
+                raise SystemExit( 1 ) from None
+        return wrapper
+    return decorator
+
+
+async def retrieve_configuration(
+    target: __.Path
+) -> __.cabc.Mapping[ str, __.typx.Any ]:
+    ''' Loads and validates configuration from Copier answers file.
+
+        Unified configuration loading used by multiple command
+        implementations. Reads from standard Copier answers location
+        and validates required fields.
+    '''
+    answers_file = (
+        target / ".auxiliary/configuration/copier-answers--agents.yaml" )
+    if not answers_file.exists( ):
+        raise __.ConfigurationAbsence( target )
+    try: content = answers_file.read_text( encoding = 'utf-8' )
+    except ( OSError, IOError ) as exception:
+        raise __.ConfigurationAbsence( ) from exception
+    try:
+        configuration: __.cabc.Mapping[ str, __.typx.Any ] = (
+            _yaml.safe_load( content ) )
+    except _yaml.YAMLError as exception:
+        raise __.ConfigurationInvalidity( exception ) from exception
+    if not isinstance( configuration, __.cabc.Mapping ):
+        raise __.ConfigurationInvalidity( )
+    await validate_configuration( configuration )
+    return configuration
+
+
+async def validate_configuration(
+    configuration: __.cabc.Mapping[ str, __.typx.Any ]
+) -> None:
+    ''' Validates required configuration fields are present and non-empty. '''
+    if not configuration.get( 'coders' ):
+        raise __.ConfigurationInvalidity( )
+    if not configuration.get( 'languages' ):
+        raise __.ConfigurationInvalidity( )
+
+
+def retrieve_data_location( source_spec: str ) -> __.Path:
+    ''' Resolves data source specification to local filesystem path.
+
+        Supports local paths, Git repositories, and remote sources through
+        pluggable source handlers. Uses registered handlers to resolve
+        various URL schemes to local filesystem paths.
+    '''
+    return __.resolve_source_location( source_spec )
+
+
+def retrieve_variant_answers_file(
+    auxdata: __.Globals, variant: str
+) -> __.Path:
+    ''' Retrieves path to variant answers file in test data directory.
+
+        Validates file existence and raises ConfigurationAbsence if not
+        found.
+    '''
+    data_directory = auxdata.provide_data_location( )
+    project_root = data_directory.parent
+    answers_file = (
+        project_root / 'tests' / 'data' / 'profiles'
+        / f"answers-{variant}.yaml" )
+    if not answers_file.exists( ):
+        raise __.ConfigurationAbsence( )
+    return answers_file

agentsmgr/commands/context.py

@@ -0,0 +1,154 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Template rendering context normalization and tool mapping.
+
+    Provides context transformation for template rendering, including
+    hyphen-to-underscore normalization and coder-specific tool mapping.
+'''
+
+
+from . import __
+
+
+ToolSpecification: __.typx.TypeAlias = (
+    str | dict[ str, __.typx.Any ] )
+
+
+_SEMANTIC_TOOLS_CLAUDE: dict[ str, str ] = {
+    'read': 'Read',
+    'edit': 'Edit',
+    'multi-edit': 'MultiEdit',
+    'write': 'Write',
+    'list-directory': 'LS',
+    'glob': 'Glob',
+    'grep': 'Grep',
+    'todo-write': 'TodoWrite',
+    'web-fetch': 'WebFetch',
+    'web-search': 'WebSearch',
+}
+
+
+def normalize_render_context(
+    context_data: __.cabc.Mapping[ str, __.typx.Any ],
+    coder_config: __.cabc.Mapping[ str, __.typx.Any ],
+) -> dict[ str, __.typx.Any ]:
+    ''' Normalizes template rendering context with tool mapping.
+
+        Transforms hyphenated keys to underscored keys, wraps configurations
+        in SimpleNamespace objects for dot-notation access, and maps
+        allowed-tools specifications to coder-specific syntax.
+    '''
+    coder_name = coder_config.get( 'name', 'unknown' )
+    normalized_context = {
+        key.replace( '-', '_' ): value
+        for key, value in context_data.items( ) }
+    if 'allowed_tools' in normalized_context:
+        raw_tools = normalized_context[ 'allowed_tools' ]
+        normalized_context[ 'allowed_tools' ] = (
+            _map_tools_for_coder( raw_tools, coder_name ) )
+    context_namespace = __.types.SimpleNamespace( **normalized_context )
+    coder_namespace = __.types.SimpleNamespace( **coder_config )
+    return {
+        'context': context_namespace,
+        'coder': coder_namespace,
+    }
+
+
+def _map_tools_for_coder(
+    tool_specs: __.cabc.Sequence[ ToolSpecification ],
+    coder_name: str,
+) -> list[ str ]:
+    ''' Maps tool specifications to coder-specific syntax.
+
+        Dispatches to coder-specific mapping function based on coder name.
+        Currently supports Claude; extensible for other coders.
+    '''
+    if coder_name == 'claude':
+        return _map_tools_claude( tool_specs )
+    return [ ]
+
+
+def _map_tools_claude(
+    tool_specs: __.cabc.Sequence[ ToolSpecification ]
+) -> list[ str ]:
+    ''' Maps tool specifications to Claude-specific syntax.
+
+        Handles three specification types:
+        - String literals (semantic names): 'read' → 'Read'
+        - Shell commands: { tool = 'shell', arguments, ... } → 'Bash(...)'
+        - MCP tools: { server, tool } → 'mcp__server__tool'
+
+        Returns tools sorted alphabetically for consistent output.
+    '''
+    mapped: list[ str ] = [ ]
+    for spec in tool_specs:
+        if isinstance( spec, str ):
+            mapped.append( _map_semantic_tool_claude( spec ) )
+        elif isinstance( spec, dict ):
+            if 'server' in spec:
+                mapped.append( _map_mcp_tool_claude( spec ) )
+            elif spec.get( 'tool' ) == 'shell':
+                mapped.append( _map_shell_tool_claude( spec ) )
+            else:
+                raise __.ToolSpecificationInvalidity( str( spec ) )
+        else:
+            raise __.ToolSpecificationTypeInvalidity( type( spec ).__name__ )
+    return sorted( mapped )
+
+
+def _map_semantic_tool_claude( tool_name: str ) -> str:
+    ''' Maps semantic tool name to Claude tool name.
+
+        Uses lookup table for known semantic names.
+        Raises ToolSpecificationInvalidity for unknown tools.
+    '''
+    if tool_name not in _SEMANTIC_TOOLS_CLAUDE:
+        raise __.ToolSpecificationInvalidity( tool_name )
+    return _SEMANTIC_TOOLS_CLAUDE[ tool_name ]
+
+
+def _map_shell_tool_claude( spec: dict[ str, __.typx.Any ] ) -> str:
+    ''' Maps shell command specification to Claude Bash tool syntax.
+
+        Format: { tool = 'shell', arguments = 'git status' }
+        → 'Bash(git status)'
+
+        With wildcard: { tool = 'shell', arguments = 'git pull',
+                         allow-extra-arguments = true }
+        → 'Bash(git pull:*)'
+    '''
+    arguments = spec.get( 'arguments', '' )
+    allow_extra = spec.get( 'allow-extra-arguments', False )
+    if allow_extra:
+        return f"Bash({arguments}:*)"
+    return f"Bash({arguments})"
+
+
+def _map_mcp_tool_claude( spec: dict[ str, __.typx.Any ] ) -> str:
+    ''' Maps MCP tool specification to Claude MCP tool syntax.
+
+        Format: { server = 'librovore', tool = 'query-inventory' }
+        → 'mcp__librovore__query_inventory'
+    '''
+    server = spec.get( 'server', '' )
+    tool = spec.get( 'tool', '' )
+    tool_normalized = tool.replace( '-', '_' )
+    return f"mcp__{server}__{tool_normalized}"