fastapi-startkit 0.40.1__tar.gz → 0.42.0__tar.gz

{fastapi_startkit-0.40.1 → fastapi_startkit-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.40.1
+Version: 0.42.0
 Summary: Fastapi Starter kit components
 Author: Bedram Tamang
 Author-email: Bedram Tamang <tmgbedu@gmail.com>

{fastapi_startkit-0.40.1 → fastapi_startkit-0.42.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.40.1"
+version = "0.42.0"
 description = "Fastapi Starter kit components"
 authors = [
     {name = "Bedram Tamang", email = "tmgbedu@gmail.com"}

{fastapi_startkit-0.40.1 → fastapi_startkit-0.42.0}/src/fastapi_startkit/masoniteorm/connections/manager.py

@@ -41,5 +41,6 @@ class DatabaseManager:
 
     async def clear(self):
         for conn in self.connections.values():
+            await conn.close()
             await conn.engine.dispose()
         self.connections.clear()

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/__init__.py

@@ -0,0 +1,7 @@
+from .registry import SkillRegistry
+from .provider import AISkillProvider
+
+__all__ = [
+    "SkillRegistry",
+    "AISkillProvider",
+]

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Adapter layer for rendering canonical skills into agent-specific formats."""
+
+from .base import BaseAdapter
+from .claude import ClaudeAdapter
+from .gemini import GeminiAdapter
+
+__all__ = ["BaseAdapter", "ClaudeAdapter", "GeminiAdapter"]

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/adapters/base.py

@@ -0,0 +1,57 @@
+"""BaseAdapter — abstract base class for all skill adapters.
+
+New adapters (e.g. Codex) only need to subclass :class:`BaseAdapter` and
+implement :meth:`render` and :meth:`prune`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Callable, Sequence
+
+from fastapi_startkit.skills.registry import Skill
+
+
+class BaseAdapter(ABC):
+    """Abstract base for skill adapters.
+
+    Parameters
+    ----------
+    base_path:
+        Root of the project (where ``.claude/``, ``GEMINI.md``, etc. live).
+        Defaults to the current working directory.
+    """
+
+    #: Short identifier shown in CLI output (e.g. "claude", "gemini").
+    name: str = ""
+
+    def __init__(self, base_path: Path | str | None = None) -> None:
+        self.base_path = Path(base_path) if base_path else Path.cwd()
+
+    # ------------------------------------------------------------------
+    # Abstract interface
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def render(
+        self,
+        skills: Sequence[Skill],
+        force: bool = False,
+        confirm: Callable[..., bool] | None = None,
+    ) -> list[str]:
+        """Write *skills* to the target format.
+
+        Existing files are preserved unless *force* is true or *confirm*
+        returns true for the overwrite prompt — mirroring ``provider:publish``.
+
+        Returns a list of human-readable lines describing what was written
+        (suitable for printing in the ``ai:skills`` command).
+        """
+
+    @abstractmethod
+    def prune(self, skills: Sequence[Skill]) -> list[str]:
+        """Remove previously-synced skills that are *not* in *skills*.
+
+        Returns a list of human-readable lines describing what was removed.
+        """

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/adapters/claude.py

@@ -0,0 +1,91 @@
+"""ClaudeAdapter — renders skills into ``.claude/skills/<name>/SKILL.md``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Sequence
+
+from fastapi_startkit.skills.registry import Skill
+from .base import BaseAdapter
+
+
+class ClaudeAdapter(BaseAdapter):
+    """Writes canonical skills into Claude Code's skill directory.
+
+    Each skill is rendered as ``.claude/skills/<skill-name>/SKILL.md`` with a
+    YAML front-matter block followed by the original body.  Publishing follows
+    the same rules as ``provider:publish``: a missing file is written, an
+    existing file is left untouched unless ``force`` is set or the caller
+    confirms the overwrite.
+    """
+
+    name = "claude"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render(
+        self,
+        skills: Sequence[Skill],
+        force: bool = False,
+        confirm: Callable[..., bool] | None = None,
+    ) -> list[str]:
+        messages: list[str] = []
+        for skill in skills:
+            dest = self._skill_path(skill.name)
+            rel = f".claude/skills/{skill.name}/SKILL.md"
+            content = self._build_content(skill)
+
+            if dest.exists() and not force:
+                if not self._confirm_overwrite(confirm, rel):
+                    messages.append(f"[claude] Skipped <comment>{rel}</comment> (already exists)")
+                    continue
+                verb = "Overwrote"
+            else:
+                verb = "Overwrote" if dest.exists() else "Published"
+
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content, encoding="utf-8")
+            messages.append(f"[claude] {verb} <info>{rel}</info>")
+        return messages
+
+    @staticmethod
+    def _confirm_overwrite(confirm: Callable[..., bool] | None, rel: str) -> bool:
+        """Ask the caller whether to overwrite *rel*; default to no."""
+        if confirm is None:
+            return False
+        return bool(confirm(f"  <comment>{rel}</comment> already exists. Overwrite?", default=False))
+
+    def prune(self, skills: Sequence[Skill]) -> list[str]:
+        """Remove ``.claude/skills/<name>/`` dirs not represented in *skills*."""
+        messages: list[str] = []
+        known_names = {s.name for s in skills}
+        skills_root = self.base_path / ".claude" / "skills"
+        if not skills_root.is_dir():
+            return messages
+
+        for child in sorted(skills_root.iterdir()):
+            if child.is_dir() and child.name not in known_names:
+                import shutil
+
+                shutil.rmtree(child)
+                messages.append(f"[claude] Pruned .claude/skills/{child.name}/")
+        return messages
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _skill_path(self, skill_name: str) -> Path:
+        return self.base_path / ".claude" / "skills" / skill_name / "SKILL.md"
+
+    @staticmethod
+    def _build_content(skill: Skill) -> str:
+        """Render the SKILL.md content for *skill*."""
+        lines = ["---", f"name: {skill.name}", f"description: {skill.description}", "---"]
+        if skill.body:
+            lines.append("")
+            lines.append(skill.body)
+        lines.append("")
+        return "\n".join(lines)

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/adapters/gemini.py

@@ -0,0 +1,110 @@
+"""GeminiAdapter — renders skills into ``GEMINI.md`` via marker blocks.
+
+The adapter manages only the region of ``GEMINI.md`` that lies between the
+``<!-- skills:start -->`` and ``<!-- skills:end -->`` markers.  Content
+outside those markers is **never** modified, making the adapter safe to use
+even when the user has hand-edited the rest of the file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Sequence
+
+from fastapi_startkit.skills.registry import Skill
+from .base import BaseAdapter
+
+_MARKER_START = "<!-- skills:start -->"
+_MARKER_END = "<!-- skills:end -->"
+
+
+class GeminiAdapter(BaseAdapter):
+    """Writes canonical skills into ``GEMINI.md`` with HTML comment markers.
+
+    If ``GEMINI.md`` does not exist it is created from scratch.  If it exists
+    the content between the markers is replaced; everything outside is left
+    unchanged.  The write is idempotent.
+    """
+
+    name = "gemini"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render(
+        self,
+        skills: Sequence[Skill],
+        force: bool = False,
+        confirm: Callable[..., bool] | None = None,
+    ) -> list[str]:
+        # GEMINI.md edits are confined to the skills marker block, so user
+        # content is never clobbered — force/confirm are accepted for a uniform
+        # adapter interface but the block is always kept in sync.
+        gemini_md = self.base_path / "GEMINI.md"
+        new_section = self._build_section(skills)
+        changed = self._update_file(gemini_md, new_section)
+        verb = "Updated" if changed else "Unchanged"
+        return [f"[gemini] {verb} <info>GEMINI.md</info> ({len(skills)} skill(s))"]
+
+    def prune(self, skills: Sequence[Skill]) -> list[str]:
+        """For Gemini, pruning just re-renders with the current skill list.
+
+        Since everything lives in a single file within a marked block,
+        rendering the new (shorter) list is equivalent to pruning.
+        """
+        return self.render(skills)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_section(self, skills: Sequence[Skill]) -> str:
+        """Return the full marker block to inject into GEMINI.md."""
+        parts = [_MARKER_START]
+        for skill in skills:
+            parts.append(f"\n## {skill.name}\n")
+            if skill.description:
+                parts.append(f"{skill.description}\n")
+            if skill.body:
+                parts.append(f"\n{skill.body}\n")
+        parts.append(_MARKER_END)
+        return "\n".join(parts)
+
+    def _update_file(self, path: Path, section: str) -> bool:
+        """Inject *section* into *path*, preserving content outside markers.
+
+        Returns *True* when the file was (re)written, *False* when unchanged.
+        """
+        if path.exists():
+            original = path.read_text(encoding="utf-8")
+        else:
+            original = ""
+
+        new_content = self._splice(original, section)
+
+        if original == new_content:
+            return False
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new_content, encoding="utf-8")
+        return True
+
+    @staticmethod
+    def _splice(original: str, section: str) -> str:
+        """Replace the skills block inside *original* with *section*.
+
+        If the markers do not exist yet the section is appended to the file
+        (separated by a blank line).
+        """
+        start_idx = original.find(_MARKER_START)
+        end_idx = original.find(_MARKER_END)
+
+        if start_idx != -1 and end_idx != -1 and end_idx > start_idx:
+            before = original[:start_idx]
+            after = original[end_idx + len(_MARKER_END) :]
+            return before + section + after
+        else:
+            # No markers yet — append
+            separator = "\n\n" if original and not original.endswith("\n\n") else ""
+            return original + separator + section + "\n"

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/commands/__init__.py

@@ -0,0 +1,5 @@
+"""Cleo commands for the skills module."""
+
+from .skills import SkillsCommand
+
+__all__ = ["SkillsCommand"]

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/commands/skills.py

@@ -0,0 +1,80 @@
+"""ai:skills — list or sync provider-declared AI skills.
+
+Examples::
+
+    artisan ai:skills --list
+    artisan ai:skills --sync
+    artisan ai:skills --sync --target=claude --prune
+"""
+
+from __future__ import annotations
+
+from cleo.helpers import option
+
+from fastapi_startkit.console import Command
+
+
+class SkillsCommand(Command):
+    name = "ai:skills"
+    description = "List or sync provider-declared AI skills."
+
+    options = [
+        option("list", "l", flag=True, description="List providers that declare skills (default)."),
+        option("sync", "s", flag=True, description="Publish skills and sync them to AI agents."),
+        option(
+            "target",
+            "t",
+            flag=False,
+            description="Sync target: claude | gemini | all. Prompts if omitted.",
+        ),
+        option(
+            "prune",
+            None,
+            flag=True,
+            description="Remove skill files no longer declared by any provider.",
+        ),
+        option(
+            "force",
+            "f",
+            flag=True,
+            description="Overwrite existing files without prompting.",
+        ),
+    ]
+
+    def handle(self) -> int:
+        from fastapi_startkit.skills.registry import SkillRegistry
+
+        registry: SkillRegistry = self.container.make("ai_skill.skills.registry")
+
+        # --target / --prune only make sense when syncing, so they imply --sync.
+        if self.option("sync") or self.option("prune") or self.option("target"):
+            return self._sync(registry)
+
+        return self._list(registry)
+
+    def _list(self, registry) -> int:
+        providers = registry.get_providers()
+
+        if providers.is_empty():
+            self.line("<comment>No skills found in any registered provider.</comment>")
+            return 0
+
+        self.info("Skill(s) found for the following provider(s):")
+        for index, provider_key in enumerate(providers, start=1):
+            self.info(f"{index}. {provider_key}")
+        return 0
+
+    def _sync(self, registry) -> int:
+        choices = ["all", "claude", "gemini"]
+        target = self.option("target")
+        if not target:
+            answer = self.choice("Which agent do you want to publish for?", choices, default=0)
+            # Interactive returns the value; non-interactive returns the default index.
+            target = choices[answer] if isinstance(answer, int) else answer
+        target = target.lower()
+        prune = bool(self.option("prune"))
+        force = bool(self.option("force"))
+
+        for message in registry.publish(target=target, prune=prune, force=force, confirm=self.confirm):
+            self.line(f"  {message}")
+        return 0

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/parser.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    path: Path
+    provider_key: str = "fastapi-startkit"
+    body: str = field(default="", repr=False)
+    metadata: dict = field(default_factory=dict, repr=False)
+
+
+class SkillParser:
+    """Parses SKILL.md files into :class:`Skill` objects."""
+
+    def parse(self, path: Path, provider_key: str = "fastapi-startkit") -> "Skill | None":
+        """Read and parse *path* into a Skill, or ``None`` if it can't be read
+        or has no name."""
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+
+        meta, body = self.parse_frontmatter(text)
+        name = (meta.get("name") or path.parent.name or "").strip()
+        if not name:
+            return None
+
+        description = (meta.get("description") or "").strip()
+        extra = {k: v for k, v in meta.items() if k not in ("name", "description")}
+        return Skill(
+            name=name,
+            description=description,
+            path=path,
+            provider_key=provider_key,
+            body=body.strip(),
+            metadata=extra,
+        )
+
+    @staticmethod
+    def parse_frontmatter(text: str) -> tuple[dict, str]:
+        """Split YAML front-matter from the body. Returns (meta_dict, body_str)."""
+        lines = text.splitlines(keepends=True)
+        if not lines or lines[0].strip() != "---":
+            return {}, text
+
+        end_idx = None
+        for i, line in enumerate(lines[1:], start=1):
+            if line.strip() == "---":
+                end_idx = i
+                break
+
+        if end_idx is None:
+            return {}, text
+
+        fm_text = "".join(lines[1:end_idx])
+        body = "".join(lines[end_idx + 1 :])
+
+        try:
+            import yaml
+
+            meta = yaml.safe_load(fm_text) or {}
+        except ModuleNotFoundError:
+            meta = {}
+            for line in lines[1:end_idx]:
+                if ":" in line:
+                    k, _, v = line.partition(":")
+                    meta[k.strip()] = v.strip()
+
+        return meta, body

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/provider.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from fastapi_startkit.providers import Provider
+
+
+class AISkillProvider(Provider):
+    provider_key = "ai_skill"
+
+    def register(self) -> None:
+        from fastapi_startkit.skills.registry import SkillRegistry
+
+        self.app.bind(f"{self.provider_key}.skills.registry", SkillRegistry(self.app))
+
+    def boot(self) -> None:
+        from fastapi_startkit.skills.commands import SkillsCommand
+
+        self.commands([SkillsCommand])

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/registry.py

@@ -0,0 +1,158 @@
+"""SkillRegistry — maps providers to their skill files and publishes them.
+
+Each provider key in :attr:`SkillRegistry.skills` points at one or more
+``SKILL.md`` destinations under ``.ai/fastapi-startkit/``. The framework ships a
+matching stub for each at ``skills/stubs/<dest>``.
+
+* ``get_providers()`` — registered providers that declare skills (used by list).
+* ``publish()``        — copy stubs into the project then render to AI agents.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, TYPE_CHECKING
+
+from fastapi_startkit.skills.parser import Skill, SkillParser
+from fastapi_startkit.support.collection import collect
+
+if TYPE_CHECKING:
+    from fastapi_startkit.application import Application
+    from fastapi_startkit.support.collection import Collection
+
+__all__ = ["Skill", "SkillRegistry", "STUBS_BASE_PATH"]
+
+#: Source location of framework-shipped skill stubs, organised by provider key:
+#:     stubs/.ai/fastapi-startkit/<provider_key>/SKILL.md
+STUBS_BASE_PATH = Path(__file__).resolve().parent / "stubs" / ".ai" / "fastapi-startkit"
+
+
+class SkillRegistry:
+    skills = {
+        "fastapi": [
+            ".ai/fastapi-startkit/fastapi/SKILL.md",
+        ],
+        "database": [
+            ".ai/fastapi-startkit/database/SKILL.md",
+        ],
+    }
+
+    def __init__(self, app: "Application") -> None:
+        self.application = app
+        self.parser = SkillParser()
+
+    @property
+    def base_path(self) -> Path:
+        return Path(self.application.base_path)
+
+    @property
+    def stubs_root(self) -> Path:
+        return STUBS_BASE_PATH.parent.parent  # .../skills/stubs
+
+    def get_providers(self) -> "Collection":
+        """Registered providers that declare skills (keyed by provider key)."""
+        return (
+            collect(self.application.providers)
+            .map(lambda provider: provider.provider_key)
+            .filter(lambda key: key in self.skills)
+        )
+
+    def discover(self) -> list[Skill]:
+        """Load a Skill for every declared file of every registered provider.
+
+        Prefers the project copy under ``.ai/`` (so user edits flow through) and
+        falls back to the bundled stub when the project hasn't published it yet.
+        """
+        skills: list[Skill] = []
+        for provider_key in self.get_providers():
+            for dest in self.skills.get(provider_key, []):
+                source = self.base_path / dest
+                if not source.is_file():
+                    source = self.stubs_root / dest
+                skill = self.parser.parse(source, provider_key)
+                if skill is not None:
+                    skills.append(skill)
+
+        return skills
+
+    def publish(
+        self,
+        target: str = "all",
+        prune: bool = False,
+        force: bool = False,
+        confirm: Callable[..., bool] | None = None,
+    ) -> list[str]:
+        """Copy stubs into the project, then render skills to the AI agent(s).
+
+        Existing destination files are preserved unless *force* is set or
+        *confirm* approves the overwrite — matching ``provider:publish``.
+
+        Returns human-readable log lines for the calling command to print.
+        """
+        messages = self._publish_stubs(force=force, confirm=confirm)
+
+        skills = self.discover()
+        if not skills:
+            messages.append("<comment>No skills found in any registered provider.</comment>")
+            return messages
+
+        adapters = self._resolve_adapters(target)
+        if not adapters:
+            messages.append(f"<error>Unknown target '{target}'. Use: claude, gemini, all.</error>")
+            return messages
+
+        messages.append(f"<info>Syncing {len(skills)} skill(s) to: {target}…</info>")
+        for adapter in adapters:
+            messages.extend(adapter.render(skills, force=force, confirm=confirm))
+            if prune:
+                messages.extend(adapter.prune(skills))
+        return messages
+
+    def _publish_stubs(
+        self,
+        force: bool = False,
+        confirm: Callable[..., bool] | None = None,
+    ) -> list[str]:
+        """Copy bundled stubs into the project's ``.ai/``.
+
+        A missing file is always written. An existing file is left untouched
+        (preserving user edits) unless *force* is set or *confirm* approves the
+        overwrite — so framework stub updates can be pulled in deliberately.
+        """
+        import shutil
+
+        messages: list[str] = []
+        for provider_key in self.get_providers():
+            for dest in self.skills.get(provider_key, []):
+                source = self.stubs_root / dest
+                if not source.is_file():
+                    continue
+
+                dest_path = self.base_path / dest
+                existed = dest_path.exists()
+                if existed and not force:
+                    if confirm is None or not confirm(
+                        f"  <comment>{dest}</comment> already exists. Overwrite?", default=False
+                    ):
+                        messages.append(f"Skipped <comment>{dest}</comment> (already exists)")
+                        continue
+
+                dest_path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source, dest_path)
+                verb = "Overwrote" if existed else "Published"
+                messages.append(f"{verb} <info>{dest}</info>")
+        return messages
+
+    def _resolve_adapters(self, target: str) -> list:
+        from fastapi_startkit.skills.adapters import ClaudeAdapter, GeminiAdapter
+
+        all_adapters = {
+            "claude": ClaudeAdapter,
+            "gemini": GeminiAdapter,
+        }
+
+        if target == "all":
+            return [cls(self.base_path) for cls in all_adapters.values()]
+
+        cls = all_adapters.get(target)
+        return [cls(self.base_path)] if cls else []