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

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

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

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

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

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

@@ -0,0 +1,24 @@
+"""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/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.41.0/src/fastapi_startkit/skills/adapters/base.py

@@ -0,0 +1,49 @@
+"""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 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]) -> list[str]:
+        """Write *skills* to the target format.
+
+        Returns a list of human-readable lines describing what was written
+        (suitable for printing in the ``skills:sync`` 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.41.0/src/fastapi_startkit/skills/adapters/claude.py

@@ -0,0 +1,82 @@
+"""ClaudeAdapter — renders skills into ``.claude/skills/<name>/SKILL.md``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import 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.  Writes are
+    idempotent — the file is only (over)written when its content would change.
+    """
+
+    name = "claude"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render(self, skills: Sequence[Skill]) -> list[str]:
+        messages: list[str] = []
+        for skill in skills:
+            dest = self._skill_path(skill.name)
+            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")
+        return messages
+
+    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)
+
+    @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/src/fastapi_startkit/skills/adapters/gemini.py

@@ -0,0 +1,102 @@
+"""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 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]) -> list[str]:
+        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))"]
+
+    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.41.0/src/fastapi_startkit/skills/commands/__init__.py

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

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

@@ -0,0 +1,73 @@
+"""skills:list — list skills available from registered providers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi_startkit.console import Command
+
+
+class SkillsListCommand(Command):
+    """List all skills declared by the registered providers.
+
+    For each skill the command shows:
+
+    * provider key
+    * skill name
+    * description
+    * sync status for Claude Code and Gemini CLI
+
+    Example usage::
+
+        artisan skills:list
+    """
+
+    name = "skills:list"
+    description = "List skills declared by registered providers and their sync status."
+
+    def handle(self) -> int:
+        from fastapi_startkit.skills.registry import SkillRegistry
+
+        registry: SkillRegistry = self.container.make("skills.registry")
+        skills = registry.discover()
+
+        if not skills:
+            self.line("<comment>No skills found in any registered provider.</comment>")
+            return 0
+
+        base_path: Path = self.container.base_path
+
+        self.line("")
+        self.line(f"  <info>Found {len(skills)} skill(s):</info>")
+        self.line("")
+
+        header = f"  {'PROVIDER':<20} {'NAME':<25} {'CLAUDE':<10} {'GEMINI':<10}  DESCRIPTION"
+        self.line(header)
+        self.line("  " + "-" * (len(header) - 2))
+
+        for skill in skills:
+            claude_status = self._claude_status(skill.name, base_path)
+            gemini_status = self._gemini_status(base_path)
+
+            desc = skill.description[:50] + "…" if len(skill.description) > 50 else skill.description
+            self.line(f"  {skill.provider_key:<20} {skill.name:<25} {claude_status:<10} {gemini_status:<10}  {desc}")
+
+        self.line("")
+        return 0
+
+    # ------------------------------------------------------------------
+    # Sync-status helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _claude_status(skill_name: str, base_path: Path) -> str:
+        skill_file = base_path / ".claude" / "skills" / skill_name / "SKILL.md"
+        return "synced" if skill_file.exists() else "pending"
+
+    @staticmethod
+    def _gemini_status(base_path: Path) -> str:
+        gemini_md = base_path / "GEMINI.md"
+        if not gemini_md.exists():
+            return "pending"
+        content = gemini_md.read_text(encoding="utf-8")
+        return "synced" if "<!-- skills:start -->" in content else "pending"

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

@@ -0,0 +1,91 @@
+"""skills:sync — sync provider skills to one or more agent targets."""
+
+from __future__ import annotations
+
+from cleo.helpers import option
+
+from fastapi_startkit.console import Command
+
+
+class SkillsSyncCommand(Command):
+    """Sync provider skills into Claude Code / Gemini CLI skill files.
+
+    Example usage::
+
+        artisan skills:sync
+        artisan skills:sync --target=claude
+        artisan skills:sync --target=gemini --prune
+    """
+
+    name = "skills:sync"
+    description = "Sync provider-declared skills to AI agent skill files."
+
+    options = [
+        option(
+            "target",
+            "t",
+            flag=False,
+            default="all",
+            description="Target adapter: claude | gemini | all (default: all)",
+        ),
+        option(
+            "prune",
+            None,
+            flag=True,
+            description="Remove skill files that are no longer declared by any provider.",
+        ),
+    ]
+
+    def handle(self) -> int:
+        from fastapi_startkit.skills.registry import SkillRegistry
+
+        registry: SkillRegistry = self.container.make("skills.registry")
+        skills = registry.discover()
+
+        target = (self.option("target") or "all").lower()
+        do_prune = bool(self.option("prune"))
+        base_path = self.container.base_path
+
+        adapters = self._resolve_adapters(target, base_path)
+
+        if not adapters:
+            self.line(f"<error>Unknown target '{target}'. Use: claude, gemini, all.</error>")
+            return 1
+
+        if not skills:
+            self.line(
+                "<comment>No skills found. Publish stubs first: artisan provider:publish --provider=skills</comment>"
+            )
+            return 0
+
+        self.line(f"<info>Found {len(skills)} skill(s). Syncing to: {target}…</info>")
+        self.line("")
+
+        for adapter in adapters:
+            messages = adapter.render(skills)
+            for msg in messages:
+                self.line(f"  {msg}")
+
+            if do_prune:
+                prune_messages = adapter.prune(skills)
+                for msg in prune_messages:
+                    self.line(f"  {msg}")
+
+        self.line("")
+        self.line("<info>Done.</info>")
+        return 0
+
+    @staticmethod
+    def _resolve_adapters(target: str, base_path) -> list:
+        from fastapi_startkit.skills.adapters import ClaudeAdapter, GeminiAdapter
+
+        all_adapters = {
+            "claude": ClaudeAdapter,
+            "gemini": GeminiAdapter,
+        }
+
+        if target == "all":
+            return [cls(base_path) for cls in all_adapters.values()]
+
+        cls = all_adapters.get(target)
+        return [cls(base_path)] if cls else []

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

@@ -0,0 +1,51 @@
+"""SkillsServiceProvider — registers skills and rules into the application."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi_startkit.providers import Provider
+
+_STUBS_DIR = Path(__file__).parent / "stubs"
+
+
+class SkillsServiceProvider(Provider):
+    """Service provider that bootstraps the skills and rules modules.
+
+    Publish starter files with::
+
+        artisan provider:publish --provider=skills
+
+    This copies:
+    - .ai/fastapi-startkit/fastapi-startkit/SKILL.md
+    """
+
+    provider_key = "skills"
+
+    def register(self) -> None:
+        from fastapi_startkit.skills.registry import SkillRegistry
+        from fastapi_startkit.skills.rules.registry import RulesRegistry
+
+        self.app.bind("skills.registry", SkillRegistry(self.app))
+        self.app.bind("rules.registry", RulesRegistry(self.app))
+
+    def boot(self) -> None:
+        from fastapi_startkit.skills.commands import SkillsSyncCommand, SkillsListCommand
+        from fastapi_startkit.skills.rules.commands import RulesSyncCommand, RulesListCommand
+
+        self.commands(
+            [
+                SkillsSyncCommand,
+                SkillsListCommand,
+                RulesSyncCommand,
+                RulesListCommand,
+            ]
+        )
+
+        _skill_stub = _STUBS_DIR / ".ai" / "fastapi-startkit" / "fastapi-startkit"
+        self.publishes(
+            {
+                str(_skill_stub / "SKILL.md"): ".ai/fastapi-startkit/fastapi-startkit/SKILL.md",
+            },
+            tag="skills",
+        )

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

@@ -0,0 +1,126 @@
+"""SkillRegistry — discovers canonical skills from ``.ai/fastapi-startkit/``.
+
+Each skill lives in a named subdirectory (or a ``SKILL.md`` directly under the
+base) and carries a YAML front-matter block::
+
+    .ai/fastapi-startkit/
+        fastapi-startkit/
+            SKILL.md        <- YAML frontmatter (name, description) + markdown body
+            rules/
+                http-client.md
+
+Running ``artisan skills:sync`` deploys skills to every configured AI agent target.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi_startkit.application import Application
+
+#: Base directory for framework skills (relative to project root).
+SKILLS_BASE_PATH = Path(".ai") / "fastapi-startkit"
+
+
+@dataclass
+class Skill:
+    """Canonical skill metadata parsed from a SKILL.md file."""
+
+    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)
+
+
+def _parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Parse YAML front-matter. 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
+
+
+class SkillRegistry:
+    """Loads Skill objects from .ai/fastapi-startkit/*/SKILL.md."""
+
+    def __init__(self, app: "Application") -> None:
+        self._app = app
+        self._skills: list[Skill] | None = None
+
+    @property
+    def skills_base_path(self) -> Path:
+        return Path(self._app.base_path) / SKILLS_BASE_PATH
+
+    def discover(self) -> list[Skill]:
+        if self._skills is not None:
+            return self._skills
+
+        base = self.skills_base_path
+        if not base.is_dir():
+            self._skills = []
+            return self._skills
+
+        self._skills = []
+        for skill_md in sorted(base.rglob("SKILL.md")):
+            skill = self._load(skill_md)
+            if skill is not None:
+                self._skills.append(skill)
+
+        return self._skills
+
+    def get(self, name: str) -> "Skill | None":
+        return next((s for s in self.discover() if s.name == name), None)
+
+    def reset(self) -> None:
+        self._skills = None
+
+    @staticmethod
+    def _load(skill_md: Path) -> "Skill | None":
+        try:
+            text = skill_md.read_text(encoding="utf-8")
+        except OSError:
+            return None
+
+        meta, body = _parse_frontmatter(text)
+        name = (meta.get("name") or skill_md.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=skill_md,
+            body=body.strip(),
+            metadata=extra,
+        )

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

@@ -0,0 +1,8 @@
+"""Rules sub-system — per-topic rule files nested inside each skill directory.
+
+Layout: .ai/fastapi-startkit/skill/<skill-name>/rules/<rule-name>.md
+"""
+
+from .registry import Rule, RulesRegistry, SKILLS_BASE_PATH
+
+__all__ = ["Rule", "RulesRegistry", "SKILLS_BASE_PATH"]

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

@@ -0,0 +1,6 @@
+"""Adapters for deploying rules to AI agent targets."""
+
+from .claude import ClaudeRulesAdapter
+from .gemini import GeminiRulesAdapter
+
+__all__ = ["ClaudeRulesAdapter", "GeminiRulesAdapter"]