agent-smith-cli 0.3.1__py3-none-any.whl

agent_smith/__init__.py

@@ -0,0 +1 @@
+"""Build agent instructions from project sources."""

agent_smith/__main__.py

@@ -0,0 +1,37 @@
+"""Composition root for the installed console script and python -m invocation."""
+
+from collections.abc import Sequence
+from importlib.metadata import version
+
+from agent_smith.adapters.adr import AdrListParser
+from agent_smith.adapters.cli import run
+from agent_smith.adapters.configuration import TomlConfiguration
+from agent_smith.adapters.filesystem import AtomicDocumentWriter, FileTextReader
+from agent_smith.adapters.just_help import JustHelpParser
+from agent_smith.adapters.markdown import MarkdownOverviewParser
+from agent_smith.adapters.mise import MiseTechStackParser
+from agent_smith.adapters.process import ShellCommandRunner
+from agent_smith.application.generation import GenerationService
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Wire concrete adapters into the application and incoming CLI boundary."""
+    generator = GenerationService(
+        FileTextReader(),
+        MarkdownOverviewParser(),
+        ShellCommandRunner(),
+        AtomicDocumentWriter(),
+        JustHelpParser(),
+        MiseTechStackParser(),
+        AdrListParser(),
+    )
+    return run(
+        argv,
+        version=version("agent-smith-cli"),
+        configuration=TomlConfiguration(),
+        generator=generator,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_smith/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters that connect the application to external interfaces."""

agent_smith/adapters/adr.py

@@ -0,0 +1,27 @@
+"""Condense adr list paths into a directory and literal extensionless filenames."""
+
+from pathlib import PurePosixPath
+
+from agent_smith.application.generation import inline_code
+from agent_smith.application.ports import GenerationError
+
+
+def decision_stem(line: str, directory: str) -> str:
+    path = PurePosixPath(line)
+    if path.parent != PurePosixPath(directory) or path.suffix != ".md":
+        raise GenerationError(f"Unexpected adr list path {line!r} for directory {directory!r}.")
+    if any(ord(char) < 32 for char in line) or not path.stem:
+        raise GenerationError("ADR filenames must be nonempty and on one line.")
+    return path.stem
+
+
+class AdrListParser:
+    def render(self, directory: str, listing: str) -> str:
+        directory = directory.strip()
+        if not directory or any(ord(char) < 32 for char in directory):
+            raise GenerationError(".adr-dir must contain a nonempty directory on one line.")
+        paths = [line for line in listing.splitlines() if line.strip()]
+        if not paths:
+            raise GenerationError("adr list returned no architecture decisions.")
+        bullets = [f"- {inline_code(decision_stem(line, directory))}" for line in paths]
+        return f"Directory: {inline_code(directory)}\n\n" + "\n".join(bullets)

agent_smith/adapters/cli.py

@@ -0,0 +1,58 @@
+"""Argparse adapter; console behavior belongs outside the application core."""
+
+import argparse
+import shlex
+import sys
+from collections.abc import Sequence
+from dataclasses import replace
+
+from agent_smith.application.ports import Configuration, GenerationError, Generator
+
+
+def run(
+    argv: Sequence[str] | None, *, version: str, configuration: Configuration, generator: Generator
+) -> int:
+    """Translate CLI options into an application request through incoming ports."""
+    parser = argparse.ArgumentParser(
+        prog="agent-smith",
+        description="Build agent instructions from your project's sources.",
+        epilog="Detects README.md, mise.toml, justfile and .adr-dir; see agent-smith.toml.",
+        allow_abbrev=False,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {version}")
+    parser.add_argument("--config", metavar="PATH", help="Read this TOML configuration file.")
+    parser.add_argument(
+        "--output", metavar="PATH", help="Override the output path (default: AGENTS.md)."
+    )
+    parser.add_argument(
+        "--no-overview", action="store_true", help="Disable the built-in README overview."
+    )
+    parser.add_argument(
+        "--no-available-commands",
+        action="store_true",
+        help="Disable the built-in just help section.",
+    )
+    parser.add_argument(
+        "--no-tech-stack", action="store_true", help="Disable the built-in mise.toml tech stack."
+    )
+    parser.add_argument(
+        "--no-architecture-decisions",
+        action="store_true",
+        help="Disable the built-in adr list section.",
+    )
+    invocation = list(sys.argv[1:] if argv is None else argv)
+    arguments = parser.parse_args(invocation)
+    try:
+        request = configuration.load(
+            arguments.config,
+            output=arguments.output,
+            no_overview=arguments.no_overview,
+            no_available_commands=arguments.no_available_commands,
+            no_tech_stack=arguments.no_tech_stack,
+            no_architecture_decisions=arguments.no_architecture_decisions,
+        )
+        generator.generate(replace(request, command=shlex.join(["agent-smith", *invocation])))
+    except GenerationError as error:
+        print(f"agent-smith: {error}", file=sys.stderr)
+        return 1
+    return 0

agent_smith/adapters/configuration.py

@@ -0,0 +1,186 @@
+"""Load optional TOML configuration and apply explicit CLI overrides."""
+
+import sys
+from pathlib import Path
+from typing import cast
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from agent_smith.application.ports import (
+    ArchitectureDecisionsSection,
+    AvailableCommandsSection,
+    CommandSection,
+    GenerationError,
+    GenerationRequest,
+    OverviewSection,
+    Section,
+    TechStackSection,
+)
+
+
+def table(value: object, allowed: set[str], name: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise GenerationError(f"{name} must be a TOML table.")
+    result = cast(dict[str, object], value)
+    unknown = result.keys() - allowed
+    if unknown:
+        raise GenerationError(f"Unknown {name} settings: {', '.join(sorted(unknown))}.")
+    return result
+
+
+def text(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip() or any(c in value for c in "\r\n\0"):
+        raise GenerationError(f"{name} must be a nonempty string on one line.")
+    return value
+
+
+def overview_sections(
+    value: object, destination: str, no_overview: bool, directory: Path
+) -> list[Section]:
+    overview = table(value, {"enabled", "source", "title"}, "overview")
+    enabled = overview.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise GenerationError("overview.enabled must be a boolean.")
+    sections: list[Section] = []
+    if enabled and not no_overview:
+        readme = text(overview.get("source", "README.md"), "overview.source")
+        if (directory / readme).resolve() == (directory / destination).resolve():
+            raise GenerationError("The output must not overwrite the overview source.")
+        sections.append(
+            OverviewSection(text(overview.get("title", "Overview"), "overview.title"), readme)
+        )
+    return sections
+
+
+class TomlConfiguration:
+    def __init__(self, directory: Path | None = None) -> None:
+        self.directory = directory if directory is not None else Path.cwd()
+
+    def load(
+        self,
+        path: str | None,
+        *,
+        output: str | None,
+        no_overview: bool,
+        no_available_commands: bool = False,
+        no_tech_stack: bool = False,
+        no_architecture_decisions: bool = False,
+    ) -> GenerationRequest:
+        source = self.directory / (path or "agent-smith.toml")
+        data: dict[str, object] = {}
+        try:
+            if path is not None or source.exists():
+                with source.open("rb") as stream:
+                    data = tomllib.load(stream)
+        except (OSError, ValueError) as error:
+            raise GenerationError(f"Cannot load configuration {str(source)!r}: {error}") from error
+        data = table(
+            data,
+            {
+                "output",
+                "overview",
+                "available_commands",
+                "tech_stack",
+                "architecture_decisions",
+                "sections",
+            },
+            "configuration",
+        )
+        destination = text(
+            output if output is not None else data.get("output", "AGENTS.md"), "output"
+        )
+        sections = overview_sections(
+            data.get("overview", {}), destination, no_overview, self.directory
+        )
+        sections.extend(
+            tech_stack_sections(
+                data.get("tech_stack", {}), self.directory, destination, no_tech_stack
+            )
+        )
+        sections.extend(
+            available_commands_sections(
+                data.get("available_commands", {}), self.directory, no_available_commands
+            )
+        )
+        sections.extend(
+            architecture_decisions_sections(
+                data.get("architecture_decisions", {}),
+                self.directory,
+                destination,
+                no_architecture_decisions,
+            )
+        )
+        sections.extend(custom_sections(data.get("sections", [])))
+        return GenerationRequest(destination, tuple(sections))
+
+
+def custom_sections(custom: object) -> list[Section]:
+    sections: list[Section] = []
+    if not isinstance(custom, list):
+        raise GenerationError("sections must be an array of TOML tables.")
+    for index, item in enumerate(custom):
+        section = table(item, {"title", "command"}, f"sections[{index}]")
+        sections.append(
+            CommandSection(
+                text(section.get("title"), "section.title"),
+                text(section.get("command"), "section.command"),
+            )
+        )
+    return sections
+
+
+def available_commands_sections(value: object, directory: Path, disabled: bool) -> list[Section]:
+    settings = table(value, {"enabled", "title", "command"}, "available_commands")
+    detected = any(
+        path.is_file() and path.name.lower() in {"justfile", ".justfile"}
+        for path in directory.iterdir()
+    )
+    enabled = settings.get("enabled", detected)
+    if not isinstance(enabled, bool):
+        raise GenerationError("available_commands.enabled must be a boolean.")
+    if disabled or not enabled:
+        return []
+    return [
+        AvailableCommandsSection(
+            text(settings.get("title", "Available commands"), "available_commands.title"),
+            text(settings.get("command", "just help"), "available_commands.command"),
+        )
+    ]
+
+
+def tech_stack_sections(
+    value: object, directory: Path, destination: str, disabled: bool
+) -> list[Section]:
+    settings = table(value, {"enabled", "title", "source"}, "tech_stack")
+    source = text(settings.get("source", "mise.toml"), "tech_stack.source")
+    enabled = settings.get("enabled", (directory / source).is_file())
+    if not isinstance(enabled, bool):
+        raise GenerationError("tech_stack.enabled must be a boolean.")
+    if disabled or not enabled:
+        return []
+    if (directory / source).resolve() == (directory / destination).resolve():
+        raise GenerationError("The output must not overwrite the tech stack source.")
+    return [
+        TechStackSection(text(settings.get("title", "Main tech stack"), "tech_stack.title"), source)
+    ]
+
+
+def architecture_decisions_sections(
+    value: object, directory: Path, destination: str, disabled: bool
+) -> list[Section]:
+    settings = table(value, {"enabled", "title"}, "architecture_decisions")
+    enabled = settings.get("enabled", (directory / ".adr-dir").is_file())
+    if not isinstance(enabled, bool):
+        raise GenerationError("architecture_decisions.enabled must be a boolean.")
+    if disabled or not enabled:
+        return []
+    if (directory / ".adr-dir").resolve() == (directory / destination).resolve():
+        raise GenerationError("The output must not overwrite .adr-dir.")
+    return [
+        ArchitectureDecisionsSection(
+            text(settings.get("title", "Architecture decisions"), "architecture_decisions.title")
+        )
+    ]

agent_smith/adapters/filesystem.py

@@ -0,0 +1,33 @@
+"""UTF-8 input and atomic output adapters."""
+
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from agent_smith.application.ports import GenerationError
+
+
+class FileTextReader:
+    def read(self, path: str) -> str:
+        try:
+            return Path(path).read_text(encoding="utf-8-sig")
+        except (OSError, UnicodeError) as error:
+            raise GenerationError(f"Cannot read {path!r}: {error}") from error
+
+
+class AtomicDocumentWriter:
+    def write(self, path: str, content: str) -> None:
+        destination = Path(path)
+        temporary: Path | None = None
+        try:
+            with NamedTemporaryFile(
+                mode="w", encoding="utf-8", newline="\n", dir=destination.parent, delete=False
+            ) as stream:
+                temporary = Path(stream.name)
+                stream.write(content)
+            os.replace(temporary, destination)
+        except (OSError, UnicodeError) as error:
+            raise GenerationError(f"Cannot write {path!r}: {error}") from error
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)

agent_smith/adapters/just_help.py

@@ -0,0 +1,45 @@
+"""Interpret the standard just --list output produced by a project's help recipe."""
+
+import re
+
+from agent_smith.application.generation import heading, inline_code
+from agent_smith.application.ports import GenerationError
+
+ANSI = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+DESCRIPTION = re.compile(r"""("(?:\\.|[^"\\])*"|'[^']*')|(\s+#\s?)""")
+RECIPE = re.compile(r"[\w-]+(?:::[\w-]+)*(?:\s+.*)?\Z")
+
+
+def split_description(line: str) -> tuple[str, str]:
+    for match in DESCRIPTION.finditer(line):
+        if match.group(2):
+            return line[: match.start()].rstrip(), line[match.end() :]
+    return line, ""
+
+
+def render_recipe(line: str) -> str:
+    signature, description = split_description(line)
+    if not RECIPE.fullmatch(signature):
+        raise GenerationError(f"Unsupported just help recipe: {line!r}.")
+    suffix = f" — {description}" if description else ""
+    return f"- {inline_code('just ' + signature)}{suffix}"
+
+
+class JustHelpParser:
+    def render(self, output: str) -> str:
+        lines = ANSI.sub("", output).splitlines()
+        lines = [line.rstrip() for line in lines if line.strip()]
+        if not lines or lines[0].strip() != "Available recipes:":
+            raise GenerationError("Expected just help to print the standard just --list output.")
+        parts = [self.render_line(line) for line in lines[1:]]
+        if not any(part.startswith("- ") for part in parts):
+            raise GenerationError("just help did not list any available commands.")
+        return "\n".join(parts).strip()
+
+    def render_line(self, line: str) -> str:
+        if not line[0].isspace():
+            raise GenerationError(f"Unsupported just help output: {line!r}.")
+        stripped = line.strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            return f"\n### {heading(stripped[1:-1])}\n"
+        return render_recipe(stripped)

agent_smith/adapters/markdown.py

@@ -0,0 +1,35 @@
+"""Locate CommonMark headings while preserving the original Markdown body."""
+
+from markdown_it import MarkdownIt
+
+from agent_smith.application.generation import content_lines
+from agent_smith.application.ports import GenerationError
+
+
+class MarkdownOverviewParser:
+    def extract(self, markdown: str) -> str:
+        """Extract after the first top-level H1 and before the following H2."""
+        markdown = markdown.removeprefix("\ufeff").replace("\r\n", "\n").replace("\r", "\n")
+        headings = [
+            (token.tag, token.map)
+            for token in MarkdownIt("commonmark").parse(markdown)
+            if token.type == "heading_open" and token.level == 0 and token.map is not None
+        ]
+        start, end = overview_bounds(headings, len(markdown.split("\n")))
+        body = content_lines("\n".join(markdown.split("\n")[start:end]))
+        if not body:
+            raise GenerationError("README overview is empty between its H1 and first H2.")
+        return body
+
+
+def overview_bounds(headings: list[tuple[str, list[int]]], end: int) -> tuple[int, int]:
+    first = next((index for index, (tag, _) in enumerate(headings) if tag == "h1"), None)
+    if first is None:
+        raise GenerationError("README overview requires a top-level Markdown H1.")
+    start = headings[first][1][1]
+    for tag, lines in headings[first + 1 :]:
+        if tag == "h2":
+            return start, lines[0]
+        if tag == "h1":
+            raise GenerationError("README has another H1 before its first overview-ending H2.")
+    return start, end

agent_smith/adapters/mise.py

@@ -0,0 +1,44 @@
+"""Render the declared mise tools without running mise or resolving versions."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from agent_smith.application.generation import inline_code
+from agent_smith.application.ports import GenerationError
+
+
+def literal(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip() or any(ord(c) < 32 for c in value):
+        raise GenerationError(f"{name} must be a nonempty, single-line string.")
+    return inline_code(value)
+
+
+def version_label(value: object, name: str) -> str:
+    if isinstance(value, dict):
+        value = value.get("version")
+    return literal(value, f"tools.{name}.version")
+
+
+def tool_versions(value: object, name: str) -> str:
+    versions = value if isinstance(value, list) else [value]
+    if not versions:
+        raise GenerationError(f"tools.{name} must declare at least one version.")
+    return ", ".join(version_label(version, name) for version in versions)
+
+
+class MiseTechStackParser:
+    def render(self, content: str) -> str:
+        try:
+            tools = tomllib.loads(content).get("tools", {})
+        except ValueError as error:
+            raise GenerationError(f"Invalid mise TOML: {error}") from error
+        if not isinstance(tools, dict) or not tools:
+            raise GenerationError("Expected a nonempty [tools] table in mise.toml.")
+        return "\n".join(
+            f"- {literal(name, 'Tool name')} — {tool_versions(value, name)}"
+            for name, value in tools.items()
+        )

agent_smith/adapters/process.py

@@ -0,0 +1,30 @@
+"""Run explicitly configured commands with the platform shell."""
+
+import subprocess
+
+from agent_smith.application.ports import GenerationError
+
+
+class ShellCommandRunner:
+    def __init__(self, timeout: float = 30) -> None:
+        self.timeout = timeout
+
+    def run(self, command: str) -> str:
+        try:
+            result = subprocess.run(
+                command,
+                # Custom extractors are explicitly trusted shell commands, not data inputs.
+                shell=True,  # nosec B602
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                timeout=self.timeout,
+            )
+        except (OSError, UnicodeError, subprocess.TimeoutExpired) as error:
+            raise GenerationError(f"Cannot execute {command!r}: {error}") from error
+        if result.returncode:
+            diagnostic = result.stderr or result.stdout
+            raise GenerationError(
+                f"Command failed (exit {result.returncode}): {command}\n{diagnostic.rstrip()}"
+            )
+        return result.stdout

agent_smith/application/__init__.py

@@ -0,0 +1 @@
+"""Application requests, ports and generation rules."""

agent_smith/application/generation.py

@@ -0,0 +1,109 @@
+"""Render all sections successfully before writing a document."""
+
+import re
+from dataclasses import dataclass
+from pathlib import PurePath
+
+from agent_smith.application.ports import (
+    ArchitectureDecisionsSection,
+    AvailableCommandsSection,
+    CommandRunner,
+    CommandSection,
+    DecisionListParser,
+    DocumentWriter,
+    GenerationError,
+    GenerationRequest,
+    HelpParser,
+    OverviewParser,
+    OverviewSection,
+    Section,
+    TechStackParser,
+    TechStackSection,
+    TextReader,
+)
+
+
+def content_lines(content: str) -> str:
+    """Normalize line endings and remove only surrounding blank lines."""
+    lines = content.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    while lines and not lines[-1].strip():
+        lines.pop()
+    return "\n".join(lines)
+
+
+def inline_code(value: str) -> str:
+    """Keep literal backticks and edge spaces inside a Markdown code span."""
+    fence = "`" * (max((len(run) for run in re.findall(r"`+", value)), default=0) + 1)
+    padding = " " if value.startswith(("`", " ")) or value.endswith(("`", " ")) else ""
+    return f"{fence}{padding}{value}{padding}{fence}"
+
+
+def heading(value: str) -> str:
+    """Escape Markdown punctuation so the configured title stays one heading."""
+    return "".join("\\" + char if char in "\\`*_[]<>#" else char for char in value)
+
+
+def validate_request(request: GenerationRequest) -> None:
+    if not request.output.strip() or "\n" in request.output or "\r" in request.output:
+        raise GenerationError("The output path must be nonempty and on one line.")
+    if not request.sections:
+        raise GenerationError("No sections enabled; enable overview or configure a section.")
+    for section in request.sections:
+        if not section.title.strip() or any(c in section.title for c in "\r\n"):
+            raise GenerationError("Section titles must be nonempty and on one line.")
+
+
+@dataclass
+class GenerationService:
+    reader: TextReader
+    overview: OverviewParser
+    commands: CommandRunner
+    writer: DocumentWriter
+    help_parser: HelpParser
+    tech_stack: TechStackParser
+    decisions: DecisionListParser
+
+    def generate(self, request: GenerationRequest) -> None:
+        """Generate one deterministic document via injected effect boundaries."""
+        validate_request(request)
+        parts = [f"# {heading(PurePath(request.output).name)}"]
+        for section in request.sections:
+            body, provenance = self.render_section(section, request.command)
+            parts.append(f"## {heading(section.title)}\n\n{body}\n\n> {provenance}")
+        self.writer.write(request.output, "\n\n".join(parts) + "\n")
+
+    def render_section(self, section: Section, invocation: str) -> tuple[str, str]:
+        body, command = self.section_content(section, invocation)
+        provenance = (
+            "*This section was automatically generated by executing the command: "
+            f"**{inline_code(command)}**.*"
+        )
+        body = content_lines(body)
+        if not body:
+            raise GenerationError(f"Section {section.title!r} produced no content.")
+        return body, provenance
+
+    def section_content(self, section: Section, invocation: str) -> tuple[str, str]:
+        if isinstance(section, OverviewSection):
+            return self.overview.extract(self.reader.read(section.source)), invocation
+        if isinstance(section, TechStackSection):
+            try:
+                return self.tech_stack.render(self.reader.read(section.source)), invocation
+            except GenerationError as error:
+                raise GenerationError(f"Tech stack source {section.source!r}: {error}") from error
+        if isinstance(section, ArchitectureDecisionsSection):
+            directory = self.reader.read(".adr-dir")
+            return self.decisions.render(directory, self.commands.run("adr list")), "adr list"
+        return self.command_content(section)
+
+    def command_content(
+        self, section: AvailableCommandsSection | CommandSection
+    ) -> tuple[str, str]:
+        if not section.command.strip() or any(c in section.command for c in "\r\n"):
+            raise GenerationError("Section commands must be nonempty and on one line.")
+        body = self.commands.run(section.command)
+        if isinstance(section, AvailableCommandsSection):
+            body = self.help_parser.render(body)
+        return body, section.command

agent_smith/application/ports.py

@@ -0,0 +1,98 @@
+"""Framework-independent contracts for generating an instruction document."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class GenerationError(Exception):
+    """An actionable failure that must leave the existing document untouched."""
+
+
+@dataclass(frozen=True)
+class OverviewSection:
+    title: str = "Overview"
+    source: str = "README.md"
+
+
+@dataclass(frozen=True)
+class AvailableCommandsSection:
+    title: str = "Available commands"
+    command: str = "just help"
+
+
+@dataclass(frozen=True)
+class TechStackSection:
+    title: str = "Main tech stack"
+    source: str = "mise.toml"
+
+
+@dataclass(frozen=True)
+class ArchitectureDecisionsSection:
+    title: str = "Architecture decisions"
+
+
+@dataclass(frozen=True)
+class CommandSection:
+    title: str
+    command: str
+
+
+Section = (
+    OverviewSection
+    | AvailableCommandsSection
+    | TechStackSection
+    | ArchitectureDecisionsSection
+    | CommandSection
+)
+
+
+@dataclass(frozen=True)
+class GenerationRequest:
+    output: str = "AGENTS.md"
+    sections: tuple[Section, ...] = (OverviewSection(),)
+    command: str = "agent-smith"
+
+
+class Generator(Protocol):
+    def generate(self, request: GenerationRequest) -> None: ...
+
+
+class Configuration(Protocol):
+    def load(
+        self,
+        path: str | None,
+        *,
+        output: str | None,
+        no_overview: bool,
+        no_available_commands: bool = False,
+        no_tech_stack: bool = False,
+        no_architecture_decisions: bool = False,
+    ) -> GenerationRequest: ...
+
+
+class TextReader(Protocol):
+    def read(self, path: str) -> str: ...
+
+
+class OverviewParser(Protocol):
+    def extract(self, markdown: str) -> str: ...
+
+
+class HelpParser(Protocol):
+    def render(self, output: str) -> str: ...
+
+
+class TechStackParser(Protocol):
+    def render(self, content: str, /) -> str: ...
+
+
+class DecisionListParser(Protocol):
+    def render(self, directory: str, listing: str) -> str: ...
+
+
+class CommandRunner(Protocol):
+    def run(self, command: str) -> str: ...
+
+
+class DocumentWriter(Protocol):
+    def write(self, path: str, content: str) -> None: ...

agent_smith_cli-0.3.1.dist-info/METADATA

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: agent-smith-cli
+Version: 0.3.1
+Summary: Build agent instructions from your project's sources.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: markdown-it-py>=4,<5
+Requires-Dist: tomli>=2 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/Mehdi-H/agent-smith
+Project-URL: Issues, https://github.com/Mehdi-H/agent-smith/issues
+Description-Content-Type: text/markdown
+
+# Agent Smith 🕶️
+
+[![CI](https://github.com/Mehdi-H/agent-smith/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/Mehdi-H/agent-smith/actions/workflows/release.yml?query=branch%3Amain)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue?logo=python&logoColor=white)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+*Smith* your AGENTS.md file 🕶️
+
+Build agent instructions from your project's sources !
+
+Treat your agent instructions as **living documentation**: regenerate them from
+the sources you maintain as your project evolves.
+
+Run `agent-smith` at your project root to generate **`AGENTS.md`** from your
+README overview, your mise tool declarations, documented just commands,
+architecture decision filenames and optional custom extractors
+
+Forget `/init` skill, the output is _deterministic_, repeatable Markdown, you stay in control
+
+## Demo
+
+> [!NOTE]
+> The CLI is a development preview. Built-in overview, tech-stack, command and ADR
+> sections are available; no package release has been published yet.
+
+
+![agent-smith creating AGENTS.md on the left, with a live Glow preview on the right](docs/demo/agent-smith.gif)
+
+## Install
+
+The PyPI distribution is named **`agent-smith-cli`**; the executable remains
+`agent-smith`. The name `agent-smith` was already taken on PyPI.
+
+Agent Smith supports Python 3.10–3.14. No release is available on PyPI yet:
+start from a checkout of this version of the repository and install the CLI
+from its root directory with uv:
+
+```sh
+uv tool install .
+```
+
+This installs the command in an isolated environment.
+
+> [!TIP]
+> If uv reports that its tool directory is missing from your PATH, run
+> `uv tool update-shell` and restart your terminal.
+
+Alternatively, install with pip in an activated Python virtual environment:
+
+```sh
+python -m pip install .
+```
+
+## Run and verify
+
+```sh
+agent-smith --version
+agent-smith --help
+agent-smith
+```
+
+> [!TIP]
+> To confirm installation, check that `--version` prints the installed Agent Smith version
+> and `--help` displays the available options. Both should exit successfully.
+
+Run the command **from the root of the project you want to document**. It creates
+or replaces `AGENTS.md` in that directory. Successful generation is silent;
+open the file to verify the result. No configuration is needed when you follow
+the conventions below.
+
+```sh
+agent-smith
+cat AGENTS.md
+```
+
+Use `agent-smith --output instructions.md` to choose another output filename.
+The document has an H1 containing its filename, an H2 for each section and a
+quoted footer identifying the command that produced that section.
+
+## Conventions
+
+### Overview: a README.md at the project root
+
+Place a `README.md` at the root with a top-level H1 followed by a nonempty
+introduction. Agent Smith copies the Markdown between that H1 and the first
+following H2 into **Overview**. No extraction script is required.
+
+```markdown
+# My project
+
+Describe what the project does and why someone would use it.
+
+## Installation
+
+This section is outside the extracted overview.
+```
+
+The first H2 ends the overview; if there is no H2, extraction continues to the
+end of the file. Badges, links and GitHub alerts in the introduction are kept.
+An absent README, a missing H1 or an empty introduction produces an error.
+Use `--no-overview` to disable this section.
+
+### Main tech stack: declared tools in a root mise.toml
+
+Put a `mise.toml` at your project root with a nonempty `[tools]` table:
+
+```toml
+[tools]
+python = ["3.14", "3.10"]
+uv = "latest"
+node = { version = "lts", postinstall = "corepack enable" }
+```
+
+Agent Smith automatically adds:
+
+```markdown
+## Main tech stack
+
+- `python` — `3.14`, `3.10`
+- `uv` — `latest`
+- `node` — `lts`
+```
+
+Tool names (including backend prefixes) and declared versions stay in file order.
+Strings, arrays of versions, and tables with a string `version` are supported,
+including arrays of those tables. Installation options are ignored. Agent Smith
+reads TOML directly: mise need not be installed, no hooks or templates execute,
+and aliases such as `latest` remain literal. It does not resolve installed versions,
+merge global/local configuration, or inspect other files such as `.python-version`.
+
+With no root `mise.toml`, this section is omitted. Use `--no-tech-stack` or
+`[tech_stack].enabled = false` to disable it. In the tool's configuration, `source`
+selects another TOML file and `title` changes the heading. An explicit
+`enabled = true` requires that source to exist. Invalid TOML, an empty `[tools]`
+table or an unsupported version declaration fails generation and preserves the
+existing document. The footer names the exact `agent-smith` invocation.
+
+### Available commands: a documented, grouped justfile at the project root
+
+Document your project's practices in a root `justfile` (also detected as
+`Justfile` or `.justfile`). Give each recipe a descriptive comment and a group,
+and provide a `help` recipe that prints the standard `just --list` output:
+
+```just
+# List the project's available commands.
+[group("Help")]
+help:
+    @just --list
+
+# Check modified files for whitespace errors.
+[group("Quality")]
+check-whitespace:
+    git diff --check
+```
+
+[Install just](https://just.systems/man/en/installation.html) and make sure
+`just help` works from the project root. Agent Smith automatically runs that
+command and converts its output to **Available commands**: Markdown lists under
+group subheadings, preserving recipe order, parameters and descriptions.
+For the example above, the section contains:
+
+```markdown
+## Available commands
+
+### Help
+
+- `just help` — List the project's available commands.
+
+### Quality
+
+- `just check-whitespace` — Check modified files for whitespace errors.
+```
+
+The section ends with a footer naming `just help`. Listed recipes are not
+executed; only the help recipe runs. With no root justfile, this section is
+omitted and just is not required. Use `--no-available-commands` to disable it.
+If help fails or does not produce the supported list format, generation fails
+and the existing `AGENTS.md` is preserved. Custom help formats can be supplied
+as Markdown through a custom section instead.
+
+### Architecture decisions: an ADR directory declared in .adr-dir
+
+Use [adr-tools](https://github.com/npryce/adr-tools) and a root `.adr-dir` containing
+the path to your decisions directory, for example `docs/adr`. When that file exists,
+Agent Smith runs `adr list` and adds a compact index:
+
+```markdown
+## Architecture decisions
+
+Directory: `docs/adr`
+
+- `0001-record-architecture-decisions`
+- `0002-use-python`
+```
+
+The directory appears once, using the content of `.adr-dir`. Each bullet contains
+only a filename without its final `.md` extension: numbers, hyphens and ordering
+from `adr list` are preserved. ADR contents and their Markdown headings are never
+read. Use meaningful filenames so the index conveys decisions without loading
+individual records. All records listed by adr-tools are included; their status
+is not inferred from their filenames.
+
+The footer names `adr list`. The command must be installed and runnable from the
+project root, and its listed paths must match `.adr-dir`. With no `.adr-dir`, this
+section is omitted. Empty or invalid metadata, a failed command or unsupported
+output fails generation while preserving the existing document.
+
+Use `--no-architecture-decisions` or `[architecture_decisions].enabled = false`
+to disable this built-in, and `title` to rename its heading. Setting `enabled = true`
+explicitly requires `.adr-dir` even if it was not detected automatically.
+
+## Configure sections
+
+An optional root `agent-smith.toml` customizes built-in sections and adds custom
+extractors. For example, to enable the four built-ins and append tracked files:
+
+```toml
+output = "AGENTS.md"
+
+[overview]
+enabled = true
+source = "README.md"
+title = "Overview"
+
+[available_commands]
+enabled = true
+title = "Available commands"
+command = "just help"
+
+[tech_stack]
+enabled = true
+source = "mise.toml"
+title = "Main tech stack"
+
+[architecture_decisions]
+enabled = true
+title = "Architecture decisions"
+
+[[sections]]
+title = "Tracked files"
+command = "git ls-files"
+```
+
+Each custom section uses its command's UTF-8 stdout as Markdown, followed by a
+footer with the exact command. Sections appear in configuration order after the
+built-in overview, main tech stack, available commands and architecture decisions. Set `[available_commands].enabled = false`
+to disable command discovery, or change its `command` to another source of
+standard just list output, such as `just --list`. Explicit `enabled = true`
+requires the command to work even if no root justfile was detected.
+
+To replace the overview with your own extractor:
+
+```toml
+[overview]
+enabled = false
+
+[[sections]]
+title = "Overview"
+command = "./scripts/my-overview.sh"
+```
+
+Supply your own script for that command. You can also disable the built-in with
+`--no-overview`, and select another configuration with `--config path/to/config.toml`.
+`--output` takes precedence over configuration. Paths and command working
+directories are relative to where you invoke the CLI, including with `--config`.
+The output's parent directory must exist.
+
+> [!WARNING]
+> The help recipe and custom commands run with your permissions. Only generate
+> documents from trusted projects and configurations. If extraction or writing fails, Agent Smith preserves
+> the existing output file; side effects of custom scripts are not rolled back.
+
+> [!NOTE]
+> Identical configuration and extractor outputs produce identical Markdown.
+> Variable command output, such as timestamps, remains variable. Extraction
+> preserves relative links and does not copy reference definitions from outside
+> the overview. No Markdown formatter is applied.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for repository setup, development commands, commit
+conventions and just-in-time architecture decisions. The license is [MIT](LICENSE).

agent_smith_cli-0.3.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+agent_smith/__init__.py,sha256=f0XbBiKqIO8OmyVil5cJM8bfKa8Bni3iWKqeescG1Xo,53
+agent_smith/__main__.py,sha256=ldNUGcOTJq7fazejczKvTp5t28Nx8cFrhxsvo8E6Ymw,1294
+agent_smith/adapters/__init__.py,sha256=mosR2as0mLhQ-Cz6zBIbhkJSxPpK5b-qQ60KevieVtk,68
+agent_smith/adapters/adr.py,sha256=QpRAZ1RnwCrNAI3PnqQkp6k41LFRHBXynRY1gGCvPsI,1284
+agent_smith/adapters/cli.py,sha256=0ZJqNptcRzf_NROZomoSLlus9_TRM6psTeJOSxWyVmk,2297
+agent_smith/adapters/configuration.py,sha256=NObBpCXg4IPN7-F88i2YkxjWk_5cZl51l33MZnr-qMY,6884
+agent_smith/adapters/filesystem.py,sha256=nzw7wgkE36n1RWUyWgz1i4gP93oShCM2sUMpatF-3RA,1136
+agent_smith/adapters/just_help.py,sha256=zwlT6hsQ0y1dpykawqdWxTWAQDJoBJEA-ifl9MQC42w,1881
+agent_smith/adapters/markdown.py,sha256=Suk_AUqnt-5-Sz-cDwhTb2ejVgtppPr1wZpoljzFGCg,1552
+agent_smith/adapters/mise.py,sha256=Pb7x0MaEAdyTVdZFBYIizyIYwnTuI9SCKyG1tMistXQ,1569
+agent_smith/adapters/process.py,sha256=RM-rdfEJLW3kAes1uCdHVkJMAQbXbz7AeMAKYIid440,1076
+agent_smith/application/__init__.py,sha256=DF950dowZpQ1kdFeoV1aFKNWhx9PBl0RDibg27_EeCw,56
+agent_smith/application/generation.py,sha256=LzrM9b9IbPbyirnKHVXYerN1wyqFo8apCPy9Wj4ODMQ,4452
+agent_smith/application/ports.py,sha256=Fd4mZcYTLaDsemV6AysvBGpuYmRcctgzAbmsnebYy00,2103
+agent_smith_cli-0.3.1.dist-info/licenses/LICENSE,sha256=YWTquHqMvNvup1vyjr7RgCVb16Tkys8-5KSit_wGcN4,1064
+agent_smith_cli-0.3.1.dist-info/WHEEL,sha256=-i9oRNYVXXZJUIYl5zclLIg6onEb0NLibTX34uln84w,81
+agent_smith_cli-0.3.1.dist-info/entry_points.txt,sha256=aJ37Bi8gUznuQzcifEHRfyUEpJOWyMjHJhabyLqHSzU,59
+agent_smith_cli-0.3.1.dist-info/METADATA,sha256=B7JZrK5MyuEi8_yp7QkpMoZ59zWQHmUC9YV0U3ZU08o,10875
+agent_smith_cli-0.3.1.dist-info/RECORD,,

agent_smith_cli-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.13
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_smith_cli-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agent-smith = agent_smith.__main__:main
+

agent_smith_cli-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehdi-H
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.