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

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

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

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

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

{fastapi_startkit-0.41.0 → 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.41.0 → fastapi_startkit-0.42.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.42.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.42.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.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 []

fastapi_startkit-0.42.0/src/fastapi_startkit/skills/stubs/.ai/fastapi-startkit/database/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: database
+description: Async ORM for fastapi-startkit — models, relationships, migrations, seeders, and the query builder.
+---
+
+# Database & ORM
+
+fastapi-startkit ships an async-first Masonite ORM built on SQLAlchemy. Every
+database operation is `async`/`await`. Table names are auto-pluralized from the
+model class via `inflection`, and `created_at`/`updated_at` are managed as
+`pendulum` Carbon objects.
+
+## Models
+
+```python
+# app/models/user.py
+from fastapi_startkit.masoniteorm import Model
+from fastapi_startkit.masoniteorm import HasOne, HasMany, BelongsTo, BelongsToMany
+
+
+class User(Model):
+    __table__ = "users"          # optional — inferred as "users" otherwise
+
+    name: str
+    email: str
+    role: str
+
+    profile = HasOne("Profile")
+    courses = BelongsToMany(
+        "Course",
+        local_foreign_key="user_id",
+        other_foreign_key="course_id",
+        table="course_user",
+        with_timestamps=True,
+        with_fields=["progress", "completed_at"],
+    )
+```
+
+Relationships available: `HasOne`, `HasMany`, `BelongsTo`, `BelongsToMany`,
+`HasManyThrough`, and `MorphMany`. Reference the related model by class name as a
+string to avoid circular imports.
+
+## Query builder
+
+All queries are awaited:
+
+```python
+from app.models.user import User
+
+user = await User.find(1)
+user = await User.where("email", "a@b.com").first()
+users = await User.where("role", "admin").get()
+user = await User.create({"name": "Ada", "email": "ada@example.com"})
+await user.update({"role": "admin"})
+await user.delete()
+```
+
+Eager-load relationships to avoid N+1 queries:
+
+```python
+courses = await Course.with_("category", "lessons").get()
+```
+
+## Migrations
+
+```python
+# databases/migrations/2024_01_01_000000_create_lessons_table.py
+from fastapi_startkit.masoniteorm import Migration
+
+
+class CreateLessonsTable(Migration):
+    async def up(self):
+        async with await self.schema.create("lessons") as table:
+            table.increments("id")
+            table.integer("course_id").unsigned()
+            table.foreign("course_id").references("id").on("courses").on_delete("cascade")
+            table.string("title")
+            table.timestamps()
+
+    async def down(self):
+        await self.schema.drop("lessons")
+```
+
+## Seeders
+
+```python
+# databases/seeders/course_seeder.py
+from fastapi_startkit.masoniteorm.seeds import Seeder
+from app.models.course import Course
+
+
+class CourseSeeder(Seeder):
+    async def run(self):
+        await Course.create({"title": "Python for Beginners", "price": 0})
+```
+
+## Console commands
+
+```bash
+uv run artisan db:make:model User          # scaffold a model
+uv run artisan db:make:migration create_users_table
+uv run artisan db:migrate                  # run pending migrations
+uv run artisan db:migrate:rollback         # roll back the last batch
+uv run artisan db:migrate:fresh            # drop all + re-migrate
+uv run artisan db:migrate:status           # show migration state
+uv run artisan db:seed                     # run seeders
+```

{fastapi_startkit-0.41.0/src/fastapi_startkit/skills/stubs/.ai/fastapi-startkit/fastapi-startkit → fastapi_startkit-0.42.0/src/fastapi_startkit/skills/stubs/.ai/fastapi-startkit/fastapi}/SKILL.md

@@ -78,14 +78,14 @@ class UserStoreRequest(BaseModel):
 
 and use JsonApiResource to return JSON response from the controller:
 ```python
-from fastapi_startkit.resources import JsonApiResource
+from fastapi_startkit.jsonapi import JsonResource
 
 # app/http/controllers/users_controller.py
 from app.models import User
 
 async def store(request: UserStoreRequest):
     user = User.create(request.model_dump())
-    return JsonApiResource(user)
+    return JsonResource(user)
 ```
 
 ## Architecture

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

@@ -1,24 +0,0 @@
-"""fastapi_startkit.skills — AI skill & rules registry and adapters.
-
-Skills and their nested rules both live under:
-    .ai/fastapi-startkit/<skill-name>/
-        SKILL.md
-        rules/
-            <rule-name>.md
-
-Run ``artisan skills:sync`` to deploy skills, ``artisan rules:sync`` for rules.
-"""
-
-from .registry import Skill, SkillRegistry, SKILLS_BASE_PATH, _parse_frontmatter
-from .provider import SkillsServiceProvider
-from .rules import Rule, RulesRegistry
-
-__all__ = [
-    "Skill",
-    "SkillRegistry",
-    "SkillsServiceProvider",
-    "SKILLS_BASE_PATH",
-    "Rule",
-    "RulesRegistry",
-    "_parse_frontmatter",
-]

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

@@ -1,6 +0,0 @@
-"""Cleo commands for the skills module."""
-
-from .sync import SkillsSyncCommand
-from .list import SkillsListCommand
-
-__all__ = ["SkillsSyncCommand", "SkillsListCommand"]