fastapi-startkit 0.41.0__tar.gz → 0.43.0__tar.gz

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.0}/PKG-INFO

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

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.0}/pyproject.toml

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

fastapi_startkit-0.43.0/src/fastapi_startkit/environment/__init__.py

@@ -0,0 +1 @@
+from .environment import env, value

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.0}/src/fastapi_startkit/environment/environment.py

@@ -87,3 +87,21 @@ def env(value, default="", cast=True):
         return True
     else:
         return env_var
+
+
+def value(env_var, default=""):
+    if env_var == "":
+        env_var = default
+
+    if isinstance(env_var, bool):
+        return env_var
+    elif env_var is None:
+        return None
+    elif isinstance(env_var, int) or (isinstance(env_var, str) and env_var.isnumeric()):
+        return int(env_var)
+    elif env_var in ("false", "False"):
+        return False
+    elif env_var in ("true", "True"):
+        return True
+    else:
+        return env_var

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.0}/src/fastapi_startkit/fastapi/commands/serve_command.py

@@ -1,5 +1,8 @@
-from fastapi_startkit.console.command import Command
 from cleo.helpers import option
+from fastapi_startkit import Config
+from fastapi_startkit.console.command import Command
+from fastapi_startkit.environment import value as cast_value
+from fastapi_startkit.support import Uriable, Uri
 
 
 class ServeCommand(Command):
@@ -37,36 +40,40 @@ class ServeCommand(Command):
         ),
     ]
 
+    def resolve_option(self, key: str, default: str | int | None = None):
+        value = self.option(key) or Config.get(f"fastapi.{key}", default)
+
+        return cast_value(value)
+
+    def resolve_url(self) -> Uriable:
+        host = self.resolve_option("host", "127.0.0.1")
+        port = self.resolve_option("port", 8000)
+
+        return Uri.of(Config.get("fastapi.app_url", "http://127.0.0.1:8000")).with_host(host).with_port(port)
+
     def handle(self):
         import uvicorn
+
         from fastapi_startkit import Config
         from fastapi_startkit.container import Container
 
         # Resolve server settings: CLI flag > fastapi config > uvicorn default (None)
-        cfg_host = Config.get("fastapi.host", "127.0.0.1")
-        cfg_port = Config.get("fastapi.port", 8000)
-        cfg_reload = Config.get("fastapi.reload", True)
         cfg_reload_dirs = Config.get("fastapi.reload_dirs") or None
         cfg_reload_excludes = Config.get("fastapi.reload_excludes") or None
 
-        host = self.option("host") or cfg_host
-        port = int(self.option("port") or cfg_port)
-        reload = cfg_reload if self.option("reload") is None else self.option("reload")
-        app = self.option("app")
-
-        exist = self.is_app_exist()
+        url = self.resolve_url()
 
         kwargs = {
-            "host": host,
-            "port": port,
-            "reload": reload,
+            "host": url.host(),
+            "port": url.port(),
+            "reload": self.resolve_option("reload", True),
             "ws": "websockets-sansio",
         }
 
-        if exist:
+        if self.is_app_exist():
             kwargs.update(
                 {
-                    "app": app,
+                    "app": self.option("app"),
                     "factory": True,
                 }
             )
@@ -75,10 +82,10 @@ class ServeCommand(Command):
             if cfg_reload_excludes is not None:
                 kwargs["reload_excludes"] = cfg_reload_excludes
 
-            self.line(f"<info>Starting Uvicorn server on {host}:{port} [{app}]...</info>")
+            self.line(f"<info>Starting Uvicorn server on {url.host()}:{url.port()} [{self.option('app')}]...</info>")
 
         else:
-            self.line(f"<info>Starting Uvicorn server on {host}:{port}...</info>")
+            self.line(f"<info>Starting Uvicorn server on {url.host()}:{url.port()}...</info>")
             kwargs.update({"app": Container.instance().fastapi, "reload": False})
 
         try:

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.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.43.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.41.0 → fastapi_startkit-0.43.0}/src/fastapi_startkit/skills/adapters/base.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Sequence
+from typing import Callable, Sequence
 
 from fastapi_startkit.skills.registry import Skill
 
@@ -34,11 +34,19 @@ class BaseAdapter(ABC):
     # ------------------------------------------------------------------
 
     @abstractmethod
-    def render(self, skills: Sequence[Skill]) -> list[str]:
+    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 ``skills:sync`` command).
+        (suitable for printing in the ``ai:skills`` command).
         """
 
     @abstractmethod

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.0}/src/fastapi_startkit/skills/adapters/claude.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Sequence
+from typing import Callable, Sequence
 
 from fastapi_startkit.skills.registry import Skill
 from .base import BaseAdapter
@@ -13,8 +13,10 @@ 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.  Writes are
-    idempotent — the file is only (over)written when its content would change.
+    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"
@@ -23,16 +25,38 @@ class ClaudeAdapter(BaseAdapter):
     # Public API
     # ------------------------------------------------------------------
 
-    def render(self, skills: Sequence[Skill]) -> list[str]:
+    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)
-            written = self._write_idempotent(dest, content)
-            verb = "Synced" if written else "Unchanged"
-            messages.append(f"[claude] {verb} .claude/skills/{skill.name}/SKILL.md")
+
+            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] = []
@@ -65,18 +89,3 @@ class ClaudeAdapter(BaseAdapter):
             lines.append(skill.body)
         lines.append("")
         return "\n".join(lines)
-
-    @staticmethod
-    def _write_idempotent(path: Path, content: str) -> bool:
-        """Write *content* to *path* only if it differs.
-
-        Returns *True* when the file was (re)written, *False* when unchanged.
-        """
-        if path.exists():
-            existing = path.read_text(encoding="utf-8")
-            if existing == content:
-                return False
-
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(content, encoding="utf-8")
-        return True

{fastapi_startkit-0.41.0 → fastapi_startkit-0.43.0}/src/fastapi_startkit/skills/adapters/gemini.py

@@ -9,7 +9,7 @@ even when the user has hand-edited the rest of the file.
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Sequence
+from typing import Callable, Sequence
 
 from fastapi_startkit.skills.registry import Skill
 from .base import BaseAdapter
@@ -32,12 +32,20 @@ class GeminiAdapter(BaseAdapter):
     # Public API
     # ------------------------------------------------------------------
 
-    def render(self, skills: Sequence[Skill]) -> list[str]:
+    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 = "Synced" if changed else "Unchanged"
-        return [f"[gemini] {verb} GEMINI.md ({len(skills)} skill(s))"]
+        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.

fastapi_startkit-0.43.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.43.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.43.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.43.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.43.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 []