faf-python-sdk 1.1.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

{faf_python_sdk-1.1.2.dist-info → faf_python_sdk-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.1.2
+Version: 1.3.0
 Summary: Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml.
 Project-URL: Homepage, https://faf.one
 Project-URL: Documentation, https://github.com/Wolfe-Jam/faf-python-sdk
@@ -32,17 +32,46 @@ Description-Content-Type: text/markdown
 
 # faf-python-sdk
 
-**Persistent project context for Python.** Parse, validate, and score `.faf` files — the foundation other Python FAF tools build on.
+**Persistent Project Context for Python. Parse, validate, score.**
 
-If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+**FAF defines. MD instructs. AI codes.**
 
+The foundation other Python FAF tools build on. If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+
+[![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-175%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
+## What's New in v1.3.0 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+`faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`, Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, in parity with the canonical TypeScript. Deterministic BETTER-shaped projection: setup (install→build→dev ordered) · tests · layout · conventions · three-tier guardrails · definition of done · security · commit · stack. Human Context (who/why marketing) is intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA, not agent ops.
+
+```python
+from faf_sdk import parse_file, generate_agents_md
+
+faf = parse_file("project.faf")
+print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+```
+
+Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll a Markdown generator. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
+
+## What's New in v1.2.0 — The Dart Edition
+
+Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
+
+```python
+from faf_sdk import detect_dart_project
+
+d = detect_dart_project(".")
+print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
+```
+
 ## What's New in v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
@@ -175,6 +204,8 @@ root = find_project_root()
 | [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
 | [faf-cli](https://npmjs.com/package/faf-cli) | CLI | npm |
 
+If `faf-python-sdk` has been useful, consider starring the repo — it helps others find it.
+
 ## Links
 
 - **Site:** [faf.one](https://faf.one)

faf_python_sdk-1.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+faf_sdk/__init__.py,sha256=1ARRF6IEkjcvf0zJwqWQF30TjTGtgrzWi8O3YwigASc,1842
+faf_sdk/dart_detection.json,sha256=jFtKnyyMVVFsunizteFZ2pLhYC1qC2nCIWQB9SdOqKE,1195
+faf_sdk/detect.py,sha256=GothQNKChKSEwke74MRy63VyBYLqOzN1j3yzjsSVpJA,6310
+faf_sdk/discovery.py,sha256=3Jj3lSzPAj9l0_VjJneLAwo1dMXvhneFhcVN4m2ejOw,8643
+faf_sdk/interop.py,sha256=fgIm13pLZIxSrjJiq7ZXXvR5ViWezuGUxhzCbsz_eZQ,13465
+faf_sdk/mk4.py,sha256=dA8o3YB0W19Mt_bqcR67HAw4S08zxj6IzEmubTy-pQY,5708
+faf_sdk/parser.py,sha256=lJJysj52X0Q_aGhl4PMXY2PuMqASFHdVRiSZFDdampk,4925
+faf_sdk/types.py,sha256=sm1ezSzCc-93bszr4ite31_xZRKjwqf2utlqN6_0QuM,6615
+faf_sdk/validator.py,sha256=6uneOwar4GYUF52BnAQTu159kE4mh4RWRgG6onVbiG4,5730
+faf_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+faf_python_sdk-1.3.0.dist-info/METADATA,sha256=L_RFAhO35YJ9RRSGyl5M8IIdFBU6rndw5bnKmUJmBpk,8784
+faf_python_sdk-1.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+faf_python_sdk-1.3.0.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
+faf_python_sdk-1.3.0.dist-info/RECORD,,

{faf_python_sdk-1.1.2.dist-info → faf_python_sdk-1.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any

faf_sdk/__init__.py

@@ -24,6 +24,8 @@ from .parser import parse, parse_file, stringify, FafFile
 from .validator import validate, ValidationResult
 from .mk4 import score_faf, Mk4Result, SlotState, LicenseTier
 from .discovery import find_faf_file, find_project_root, load_fafignore
+from .detect import detect_dart_project, DartProject
+from .interop import generate_agents_md, generate_gemini_md, faf_meta_tag
 from .types import (
     FafData,
     ProjectInfo,
@@ -34,7 +36,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.1.2"
+__version__ = "1.3.0"
 __all__ = [
     # Parser
     "parse",
@@ -53,6 +55,13 @@ __all__ = [
     "find_faf_file",
     "find_project_root",
     "load_fafignore",
+    # Detection (Dart/Flutter — A+B hybrid, parity with faf-cli)
+    "detect_dart_project",
+    "DartProject",
+    # Interop — AGENTS.md / GEMINI.md generators (parity with faf-cli src/interop)
+    "generate_agents_md",
+    "generate_gemini_md",
+    "faf_meta_tag",
     # Types
     "FafData",
     "ProjectInfo",

faf_sdk/dart_detection.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "_doc": "SINGLE SOURCE of Dart/Flutter detection KNOWLEDGE (A+B hybrid, the Truth-is-faf-cli spec). faf-cli imports this directly; faf-python-sdk vendors a synced copy (phase 2); MCPs consume the SDK (phase 3). To bolster Dart/Flutter support — a new state library, server framework, MCP dep — edit THIS file and every engine inherits it. The thin per-language LOGIC (pubspec parse, app-vs-package heuristic, priority branching) lives in code, not here.",
+  "flutterDeps": ["flutter"],
+  "mcpDeps": ["dart_mcp", "mcp_server", "mcp_dart", "dart_mcp_server", "mcp"],
+  "serverFrameworks": [
+    ["serverpod", "Serverpod"],
+    ["dart_frog", "Dart Frog"],
+    ["conduit", "Conduit"],
+    ["angel3_framework", "Angel3"],
+    ["alfred", "Alfred"],
+    ["shelf", "Shelf"]
+  ],
+  "stateManagement": [
+    ["flutter_riverpod", "Riverpod"],
+    ["hooks_riverpod", "Riverpod"],
+    ["riverpod", "Riverpod"],
+    ["flutter_bloc", "Bloc"],
+    ["bloc", "Bloc"],
+    ["provider", "Provider"],
+    ["get", "GetX"],
+    ["flutter_mobx", "MobX"],
+    ["mobx", "MobX"],
+    ["signals", "Signals"]
+  ],
+  "routing": [
+    ["go_router", "go_router"],
+    ["auto_route", "auto_route"]
+  ]
+}

faf_sdk/detect.py

@@ -0,0 +1,167 @@
+"""
+Dart/Flutter detection — CONTENT-AWARE pubspec classification (Python).
+
+PARITY: this mirrors faf-cli src/detect/dart.ts EXACTLY. A pubspec.yaml alone
+does NOT mean Flutter — the same manifest backs Flutter apps, pure-Dart CLIs,
+packages, servers (Dart Frog / Shelf / Serverpod) and MCP servers
+(dart_mcp / mcp_server). We read the dependencies and branch.
+
+The detection KNOWLEDGE (which deps mean what) lives in dart_detection.json —
+a byte-identical, synced copy of faf-cli's src/detect/dart-detection.json (the
+single source, A+B hybrid). To bolster Dart support, edit the spec in faf-cli
+(the Truth) and re-run scripts/sync-dart-spec.sh. The thin per-language LOGIC
+(pubspec parse, app-vs-package heuristic, priority branching) lives here.
+
+Behavior parity with faf-cli is PROVEN by tests/test_dart_parity.py, which runs
+the SAME shared fixtures faf-cli runs in tests/detect/dart-parity.test.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+_SPEC: Dict[str, Any] = json.loads(
+    (Path(__file__).parent / "dart_detection.json").read_text(encoding="utf-8")
+)
+
+# Detection KNOWLEDGE — sourced from dart_detection.json, never hand-listed here.
+FLUTTER_DEPS: List[str] = list(_SPEC["flutterDeps"])
+MCP_DEPS: List[str] = list(_SPEC["mcpDeps"])
+SERVER_FRAMEWORKS: List[List[str]] = [list(e) for e in _SPEC["serverFrameworks"]]
+STATE_MGMT: List[List[str]] = [list(e) for e in _SPEC["stateManagement"]]
+ROUTING: List[List[str]] = [list(e) for e in _SPEC["routing"]]
+
+
+@dataclass
+class DartProject:
+    """Classification of a Dart/Flutter project from its pubspec.yaml."""
+
+    app_type: str  # 'mobile' | 'mcp' | 'backend' | 'cli' | 'library'
+    is_flutter: bool
+    framework: str  # 'Flutter' | 'Dart Frog' | 'Serverpod' | 'Shelf' | ... | ''
+    state_management: str  # 'Riverpod' | 'Bloc' | 'Provider' | 'GetX' | ... | ''
+    routing: str  # 'go_router' | 'auto_route' | ''
+    testing: str  # 'flutter_test' | 'test' | ''
+    found: str  # human-readable rationale for the .faf `# found:` comment
+
+    def to_dict(self) -> Dict[str, object]:
+        """Project to the faf-cli DartProject shape (camelCase) for parity checks."""
+        return {
+            "appType": self.app_type,
+            "isFlutter": self.is_flutter,
+            "framework": self.framework,
+            "stateManagement": self.state_management,
+            "routing": self.routing,
+            "testing": self.testing,
+            "found": self.found,
+        }
+
+
+def _pubspec_deps(content: str) -> Set[str]:
+    """Collect dependency names from dependencies / dev_dependencies sections."""
+    deps: Set[str] = set()
+    in_deps = False
+    for line in content.split("\n"):
+        if re.match(r"^(dependencies|dev_dependencies|dependency_overrides):\s*$", line):
+            in_deps = True
+            continue
+        # A new top-level key (no leading whitespace) ends the dependency section.
+        if re.match(r"^\S", line):
+            in_deps = False
+        if in_deps:
+            m = re.match(r"^\s{2}([a-zA-Z0-9_]+):", line)
+            if m:
+                deps.add(m.group(1).lower())
+    return deps
+
+
+def detect_dart_project(directory: str) -> Optional[DartProject]:
+    """Classify a Dart/Flutter project from its pubspec.yaml. None if not Dart."""
+    path = Path(directory) / "pubspec.yaml"
+    if not path.exists():
+        return None
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    deps = _pubspec_deps(content)
+
+    def has(dep: str) -> bool:
+        return dep.lower() in deps
+
+    # Flutter: the `flutter` SDK dep, a top-level `flutter:` section, or `sdk: flutter`.
+    is_flutter = (
+        any(has(d) for d in FLUTTER_DEPS)
+        or re.search(r"^flutter:\s*$", content, re.MULTILINE) is not None
+        or re.search(r"\bsdk:\s*flutter\b", content) is not None
+    )
+
+    mcp_dep = next((d for d in MCP_DEPS if has(d)), None)
+    server = next((e for e in SERVER_FRAMEWORKS if has(e[0])), None)
+    state_entry = next((e for e in STATE_MGMT if has(e[0])), None)
+    state_management = state_entry[1] if state_entry else ""
+    route_entry = next((e for e in ROUTING if has(e[0])), None)
+    routing = route_entry[1] if route_entry else ""
+    testing = "flutter_test" if has("flutter_test") else ("test" if has("test") else "")
+
+    # CLI: a top-level `executables:` section, or bin/*.dart entry points.
+    has_executables = re.search(r"^executables:\s*$", content, re.MULTILINE) is not None
+    has_bin_dart = False
+    bin_dir = Path(directory) / "bin"
+    if bin_dir.is_dir():
+        try:
+            has_bin_dart = any(f.endswith(".dart") for f in os.listdir(bin_dir))
+        except OSError:
+            has_bin_dart = False
+    is_cli = has_executables or has_bin_dart
+
+    framework = ""
+    app_type: str
+    found: str
+
+    if is_flutter:
+        framework = "Flutter"
+        # App vs package: an app has lib/main.dart (the entry) or `publish_to: none`;
+        # a reusable Flutter package has neither — it's publishable, lib/ exports only.
+        is_app = (Path(directory) / "lib" / "main.dart").exists() or (
+            re.search(r"^publish_to:\s*['\"]?none\b", content, re.MULTILINE) is not None
+        )
+        if is_app:
+            app_type = "mobile"
+            found = "pubspec.yaml (Flutter app)"
+        else:
+            app_type = "library"
+            found = "pubspec.yaml (Flutter package)"
+    elif mcp_dep:
+        app_type = "mcp"
+        found = f"pubspec.yaml + {mcp_dep} (Dart MCP server)"
+    elif server:
+        app_type = "backend"
+        framework = server[1]
+        found = f"pubspec.yaml + {server[0]} (Dart backend)"
+    elif is_cli:
+        app_type = "cli"
+        found = (
+            "pubspec.yaml executables: (Dart CLI)"
+            if has_executables
+            else "pubspec.yaml + bin/*.dart (Dart CLI)"
+        )
+    else:
+        app_type = "library"
+        found = "pubspec.yaml (Dart package)"
+
+    return DartProject(
+        app_type=app_type,
+        is_flutter=is_flutter,
+        framework=framework,
+        state_management=state_management,
+        routing=routing,
+        testing=testing,
+        found=found,
+    )

faf_sdk/interop.py

@@ -0,0 +1,403 @@
+"""
+AI-context file generators — AGENTS.md and GEMINI.md from .faf data.
+
+Python port of faf-cli's `src/interop/agents.ts` + `gemini.ts`, kept in
+parity with the canonical TypeScript. Deterministic projection from curated
+truth — facts, not freewritten prose. Human Context (who/why marketing) is
+intentionally omitted from AGENTS.md; it belongs in the README / .faf DNA,
+not agent ops.
+
+Both take the raw parsed .faf dict (`FafFile.data.raw`) — the .faf format
+carries top-level `commands` / `key_files` / `security` that the typed model
+doesn't surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["generate_agents_md", "generate_gemini_md", "faf_meta_tag", "title_label", "slot_label"]
+
+# --- shared helpers ----------------------------------------------------------
+
+_ACRONYMS = {
+    "API", "CI", "CD", "MCP", "CLI", "SDK", "UI", "UX", "AI", "ML", "DB", "ORM",
+    "OS", "HTTP", "HTTPS", "REST", "RPC", "JSON", "YAML", "XML", "SQL", "CSS",
+    "HTML", "AWS", "GCP", "CDN", "DNS", "JWT", "ID", "IP", "URL", "URI", "TS", "JS",
+}
+
+# Canonical .faf slot labels (from faf-cli src/core/slots.ts).
+_SLOT_LABELS = {
+    "stack.frontend": "Framework", "stack.css_framework": "CSS",
+    "stack.ui_library": "UI Library", "stack.state_management": "State",
+    "stack.backend": "Backend", "stack.api_type": "API", "stack.runtime": "Runtime",
+    "stack.database": "Database", "stack.connection": "Connection",
+    "stack.hosting": "Hosting", "stack.build": "Build", "stack.cicd": "CI/CD",
+    "stack.monorepo_tool": "Monorepo", "stack.package_manager": "Package Manager",
+    "stack.workspaces": "Workspaces", "stack.admin": "Admin", "stack.cache": "Cache",
+    "stack.search": "Search", "stack.storage": "Storage",
+}
+
+# Preference keys that describe human<->assistant interaction, not repo conventions.
+_HUMAN_PREF = {
+    "commit_style", "communication", "response_style", "explanation_level",
+    "explanations", "documentation", "code_first",
+}
+
+# Stack keys that are context/marketing, not actual stack.
+_NON_STACK = {"target_user", "core_problem", "mission_purpose"}
+
+
+def _present(v: Any) -> bool:
+    """Non-empty, not 'slotignored', non-empty list."""
+    if v is None or v == "" or v == "slotignored":
+        return False
+    if isinstance(v, (list, tuple)) and len(v) == 0:
+        return False
+    return True
+
+
+def _filled(v: Any) -> bool:
+    """A string slot value carrying real content."""
+    return isinstance(v, str) and v.strip() not in ("", "slotignored")
+
+
+def _fmt_val(v: Any) -> str:
+    if isinstance(v, (list, tuple)):
+        return ", ".join(str(x) for x in v)
+    return str(v)
+
+
+def title_label(key: str) -> str:
+    """snake_case -> Title Case, acronym-aware. `api_type` -> 'API Type'."""
+    out: list[str] = []
+    for w in key.split("_"):
+        if not w:
+            out.append(w)
+        elif w.upper() in _ACRONYMS:
+            out.append(w.upper())
+        else:
+            out.append(w[0].upper() + w[1:])
+    return " ".join(out)
+
+
+def slot_label(path: str) -> str:
+    """Canonical display label for a .faf slot path; falls back to title_label."""
+    if path in _SLOT_LABELS:
+        return _SLOT_LABELS[path]
+    key = path.rsplit(".", 1)[-1] if "." in path else path
+    return title_label(key)
+
+
+def faf_meta_tag(faf: dict) -> str:
+    """The two-line `<!-- faf: ... -->` metastamp every faf-generated file opens with."""
+    proj = faf.get("project") or {}
+    name = str(proj.get("name") or "").strip()
+    lang = str(proj.get("main_language") or "").strip()
+    typ = str(proj.get("type") or "").strip()
+    desc = str(proj.get("goal") or "").strip()
+    line1 = f"<!-- faf: {' | '.join([name, lang, typ, desc])} -->"
+    kv = ["claim=project.faf", "family=FAF"]
+    line2 = f"<!-- faf: {' | '.join(kv)} -->"
+    return f"{line1}\n{line2}"
+
+
+# --- command classification (shared by both generators) ---------------------
+
+def _classify_commands(faf: dict) -> dict:
+    commands = faf.get("commands") or {}
+    entries = [(k, v) for k, v in commands.items() if _present(v)]
+    test_cmds = [(k, v) for k, v in entries if "test" in k.lower()]
+    lint_cmds = [
+        (k, v) for k, v in entries
+        if ("lint" in k.lower() or "check" in k.lower()) and "test" not in k.lower()
+    ]
+    setup_raw = [
+        (k, v) for k, v in entries
+        if not any(t in k.lower() for t in ("test", "lint", "check"))
+    ]
+
+    def setup_rank(k: str) -> int:
+        n = k.lower()
+        if "install" in n or "deps" in n:
+            return 0
+        if "build" in n and "rebuild" not in n:
+            return 1
+        if n == "dev" or "develop" in n:
+            return 2
+        if n == "start" or "run" in n:
+            return 3
+        return 4
+
+    setup_cmds = sorted(setup_raw, key=lambda kv: (setup_rank(kv[0]), kv[0]))
+    verify_cmds = test_cmds + lint_cmds
+    return {
+        "test": test_cmds, "lint": lint_cmds, "setup": setup_cmds, "verify": verify_cmds,
+    }
+
+
+def _key_files(faf: dict) -> list:
+    kf = faf.get("key_files")
+    if not kf:
+        ic = faf.get("instant_context") or {}
+        kf = ic.get("key_files")
+    return kf or []
+
+
+# --- AGENTS.md -------------------------------------------------------------
+
+def generate_agents_md(faf: dict) -> str:
+    """Author a BETTER-shaped AGENTS.md from raw .faf data. Deterministic."""
+    lines: list[str] = []
+
+    def push(s: str = "") -> None:
+        lines.append(s)
+
+    proj = faf.get("project") or {}
+    ai = faf.get("ai_instructions") or {}
+    prefs = faf.get("preferences") or {}
+    security = faf.get("security") or {}
+    branch = str(proj["default_branch"]) if _present(proj.get("default_branch")) else "main"
+
+    cmds = _classify_commands(faf)
+    setup_cmds, test_cmds, lint_cmds, verify_cmds = (
+        cmds["setup"], cmds["test"], cmds["lint"], cmds["verify"],
+    )
+    test_cmd = test_cmds[0][1] if test_cmds else None
+    build_cmd = next((v for k, v in setup_cmds if "build" in k.lower()), None)
+    key_files = _key_files(faf)
+
+    push(faf_meta_tag(faf))
+    push()
+    push(f"# AGENTS.md — {proj.get('name') or 'Project'}")
+    push()
+
+    # 1 - orientation
+    bits: list[str] = []
+    if proj.get("main_language"):
+        bits.append(str(proj["main_language"]))
+    if _present(proj.get("type")):
+        bits.append(f"type: {proj['type']}")
+    if _present(proj.get("version")):
+        bits.append(f"v{proj['version']}")
+    orientation = str(proj["goal"]).strip() if proj.get("goal") else ""
+    if bits:
+        orientation += (" — " if orientation else "") + " · ".join(bits)
+    if orientation:
+        push(orientation)
+        push()
+    push(
+        "> Authored by faf — refresh with `faf export --agents` or the "
+        "`faf_agents` MCP tool. The managed block is regenerated each time; "
+        "hand-written content outside it is preserved."
+    )
+    push()
+
+    # 2 - setup & build
+    if setup_cmds:
+        push("## Setup & build")
+        push()
+        push("```bash")
+        for k, v in setup_cmds:
+            push(f"{v}    # {k}")
+        push("```")
+        push()
+
+    # 3 - run the tests
+    if verify_cmds:
+        push("## Run the tests")
+        push()
+        push("```bash")
+        for _, v in verify_cmds:
+            push(v)
+        push("```")
+        push()
+
+    # 4 - where things live
+    if key_files:
+        push("## Where things live")
+        push()
+        rows = []
+        for f in key_files:
+            s = str(f)
+            at = s.find(" — ")
+            rows.append((s[:at], s[at + 3:]) if at > 0 else (s, ""))
+        if any(role for _, role in rows):
+            push("| Path | Role |")
+            push("|------|------|")
+            for path, role in rows:
+                push(f"| `{path}` | {role} |")
+        else:
+            for path, _ in rows:
+                push(f"- `{path}`")
+        push()
+
+    # 5 - conventions
+    conventions: dict[str, str] = {}
+
+    def collect(obj: Any) -> None:
+        if not isinstance(obj, dict):
+            return
+        for k, v in obj.items():
+            if k in _HUMAN_PREF or not _present(v):
+                continue
+            label = title_label(k)
+            conventions.setdefault(label, _fmt_val(v))
+
+    collect(ai.get("working_style"))
+    collect(prefs)
+    detected_conv = faf.get("conventions") or []
+    if conventions or detected_conv:
+        push("## Conventions")
+        push()
+        for label, val in conventions.items():
+            push(f"- **{label}:** {val}")
+        for c in detected_conv:
+            if _present(c):
+                push(f"- {c}")
+        push()
+
+    # 6 - guardrails
+    warnings = [w for w in (ai.get("warnings") or []) if _present(w)]
+    always = ["read the tree"]
+    if test_cmd:
+        always.append(f"run the tests (`{test_cmd}`)")
+    if build_cmd:
+        always.append("build the project")
+    for _, v in lint_cmds[:1]:
+        always.append(f"`{v}`")
+    push("## Guardrails")
+    push()
+    for w in warnings:
+        push(f"- {w}")
+    push(f"- **Always OK:** {' · '.join(dict.fromkeys(always))}.")
+    push("- **Ask first:** dependency installs, deletions, migrations, schema changes, publish/release.")
+    push(
+        f"- **Never:** force-push · push straight to `{branch}` (branch and open a PR) · commit secrets."
+    )
+    push()
+
+    # 7 - definition of done
+    dod: list[str] = []
+    for _, v in lint_cmds:
+        dod.append(f"`{v}` exits 0")
+    for _, v in test_cmds:
+        dod.append(f"`{v}` passes")
+    dod.append("changes committed with a conventional message")
+    push("## Definition of Done")
+    push()
+    push(f"Done when: {' · '.join(dict.fromkeys(dod))}.")
+    push()
+
+    # 8 - when stuck
+    push("## When stuck")
+    push()
+    push(
+        "Ask a clarifying question, propose a short plan, or open a draft PR with "
+        f"notes — do not push large speculative changes to `{branch}`."
+    )
+    push()
+
+    # 9 - security & secrets
+    if security and (_present(security.get("secrets")) or (security.get("never") or [])):
+        push("## Security & secrets")
+        push()
+        if _present(security.get("secrets")):
+            ex = f" (see `{security['example']}`)" if _present(security.get("example")) else ""
+            push(f"- Secrets live in `{security['secrets']}`{ex}. Never read or commit them.")
+        for n in security.get("never") or []:
+            if _present(n):
+                push(f"- Never read or commit `{n}`.")
+        push()
+
+    # 10 - commit & PR
+    push("## Commit & PR")
+    push()
+    if _present(prefs.get("commit_style")):
+        push(f"- Commit style: {_fmt_val(prefs['commit_style'])}")
+    else:
+        push("- Conventional Commits preferred (`feat:`, `fix:`, `chore:`, …).")
+    push(f"- Branch off `{branch}` and open a PR — never commit to `{branch}` directly.")
+    push("- If build/test scripts or layout change, refresh this file in the **same PR**.")
+    push()
+
+    # stack (reference)
+    stack = faf.get("stack") or {}
+    if isinstance(stack, dict):
+        rendered = [
+            f"- **{slot_label(f'stack.{k}')}:** {v.strip()}"
+            for k, v in stack.items()
+            if k not in _NON_STACK and _filled(v)
+        ]
+        if rendered:
+            push("## Stack")
+            push()
+            lines.extend(rendered)
+            push()
+
+    gen = faf.get("generated")
+    if _present(gen):
+        push(f"*Context authored: {gen}*")
+
+    return "\n".join(lines)
+
+
+# --- GEMINI.md ------------------------------------------------------------
+
+def generate_gemini_md(faf: dict) -> str:
+    """GEMINI.md — Gemini CLI's own convention (hierarchical, @file-importable)."""
+    lines: list[str] = []
+    proj = faf.get("project") or {}
+    cmds = _classify_commands(faf)
+    setup_cmds, verify_cmds = cmds["setup"], cmds["verify"]
+    key_files = _key_files(faf)
+
+    lines.append(faf_meta_tag(faf))
+    lines.append("")
+    lines.append(f"# GEMINI.md — {proj.get('name') or 'Project'}")
+    lines.append("")
+    lines.append("> Authored from project.faf — refresh with the `faf_gemini` MCP tool or `faf export --gemini`.")
+    lines.append("")
+
+    if proj.get("name"):
+        lines.append(f"Project: {proj['name']}")
+    if proj.get("goal"):
+        lines.append(f"Goal: {proj['goal']}")
+    if proj.get("main_language"):
+        lines.append(f"Language: {proj['main_language']}")
+
+    if setup_cmds:
+        lines += ["", "## Setup & build", "", "```bash"]
+        for k, v in setup_cmds:
+            lines.append(f"{v}    # {k}")
+        lines.append("```")
+
+    if verify_cmds:
+        lines += ["", "## Test & verify", "", "```bash"]
+        for _, v in verify_cmds:
+            lines.append(v)
+        lines.append("```")
+
+    if key_files:
+        lines += ["", "## Where things live", ""]
+        for f in key_files:
+            lines.append(f"- `{f}`")
+
+    stack = faf.get("stack") or {}
+    if isinstance(stack, dict):
+        rendered = [
+            f"- {slot_label(f'stack.{k}')}: {v.strip()}"
+            for k, v in stack.items()
+            if k not in _NON_STACK and _filled(v)
+        ]
+        if rendered:
+            lines += ["", "## Stack"]
+            lines.extend(rendered)
+
+    lines += [
+        "", "## Before changing things", "",
+        "- Ask first: dependency installs, deletions, migrations, schema changes, publish/release.",
+        "- Never: force-push · push straight to `main` · commit secrets.",
+        "",
+    ]
+    return "\n".join(lines)

faf_python_sdk-1.1.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-faf_sdk/__init__.py,sha256=mN9DPryL9_sPv-QVw-rZGS6u8dcVDvB1UNu2GGQg7Pk,1445
-faf_sdk/discovery.py,sha256=3Jj3lSzPAj9l0_VjJneLAwo1dMXvhneFhcVN4m2ejOw,8643
-faf_sdk/mk4.py,sha256=dA8o3YB0W19Mt_bqcR67HAw4S08zxj6IzEmubTy-pQY,5708
-faf_sdk/parser.py,sha256=lJJysj52X0Q_aGhl4PMXY2PuMqASFHdVRiSZFDdampk,4925
-faf_sdk/types.py,sha256=sm1ezSzCc-93bszr4ite31_xZRKjwqf2utlqN6_0QuM,6615
-faf_sdk/validator.py,sha256=6uneOwar4GYUF52BnAQTu159kE4mh4RWRgG6onVbiG4,5730
-faf_python_sdk-1.1.2.dist-info/METADATA,sha256=ReVbpyLAD3PG_vInHUbkfJTnarFcmdBrhl_zvd_t_D4,7116
-faf_python_sdk-1.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-faf_python_sdk-1.1.2.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
-faf_python_sdk-1.1.2.dist-info/RECORD,,