framesdkpy 0.3.0__py3-none-any.whl

framesdkpy/schemas/map.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frame.dev/schemas/0.3.0/map.schema.json",
+  "title": "FRAME Map",
+  "description": "Where things live -- roots, groups, paths, entrypoints, and managed paths.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["frame"],
+  "properties": {
+    "frame": {
+      "allOf": [
+        { "$ref": "./frame.schema.json#/$defs/frame_header" },
+        {
+          "type": "object",
+          "properties": {
+            "file": { "const": "map" },
+            "role": { "const": "repo_context_map" }
+          }
+        }
+      ]
+    },
+    "structure": {
+      "type": "string",
+      "maxLength": 800,
+      "description": "Quick visual overview of repo layout. Flat text: 'Backend/ → FastAPI (routes→services→models), Frontend/ → Vue 3 (views→stores→services)'."
+    },
+    "roots": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Top-level directory purposes. Keys are directory names."
+    },
+    "groups": {
+      "type": "array",
+      "description": "Logical groupings of paths. Supports wildcards for flexible coverage.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "label", "paths"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "label": { "type": "string", "maxLength": 150 },
+          "paths": {
+            "type": "array",
+            "items": { "type": "string", "maxLength": 300 },
+            "description": "Wildcards allowed (e.g. 'Backend/app/**/*.py')."
+          },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "paths": {
+      "type": "array",
+      "description": "Critical individual files. Explicit paths only.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "purpose"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "path": { "type": "string", "maxLength": 200 },
+          "purpose": { "type": "string", "maxLength": 300 },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "entrypoints": {
+      "type": "array",
+      "description": "CLI/API/web entry points. Explicit paths only.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "path", "kind"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "path": { "type": "string", "maxLength": 200 },
+          "kind": {
+            "type": "string",
+            "enum": ["cli", "api", "web", "script"]
+          },
+          "description": { "type": "string", "maxLength": 300 },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "managed_paths": {
+      "type": "array",
+      "description": "Paths under special rules. Supports wildcards.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "rule"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "path": { "type": "string", "maxLength": 200, "description": "Wildcards allowed (e.g. 'node_modules/**', '*.pyc')." },
+          "rule": {
+            "type": "string",
+            "enum": ["generated", "config", "immutable"]
+          },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "unmapped_paths": {
+      "type": "array",
+      "description": "Paths not yet placed in the map. Honest about gaps.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "maxLength": 200 },
+          "reason": { "type": "string", "maxLength": 200 }
+        }
+      }
+    },
+    "evidence": { "$ref": "./frame.schema.json#/$defs/evidence_list" },
+    "links": { "$ref": "./frame.schema.json#/$defs/links" }
+  }
+}

framesdkpy/schemas/rules.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frame.dev/schemas/0.3.0/rules.schema.json",
+  "title": "FRAME Rules",
+  "description": "How to work safely in this repo. Commands, constraints, policies, and triggers that need human approval.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["frame"],
+  "properties": {
+    "frame": {
+      "allOf": [
+        { "$ref": "./frame.schema.json#/$defs/frame_header" },
+        {
+          "type": "object",
+          "properties": {
+            "file": { "const": "rules" },
+            "role": { "const": "project_instruction_blueprint" }
+          }
+        }
+      ]
+    },
+    "governance_level": {
+      "type": "string",
+      "enum": ["relaxed", "normal", "strict"],
+      "default": "normal",
+      "description": "Controls how aggressively Haxaml enforces rules, ask_first, and validation. Does NOT affect mechanical validator (always runs)."
+    },
+    "rules": {
+      "type": "array",
+      "description": "Core behavioral constraints.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "rule"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "rule": { "type": "string", "maxLength": 500 },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "policies": {
+      "type": "array",
+      "description": "Durable project policies (role access, lifecycle, audit, auth). Moved from Facts.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "rule"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "name": { "type": "string", "maxLength": 150 },
+          "rule": { "type": "string", "maxLength": 500 },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "commands": {
+      "type": "object",
+      "description": "Named shell commands. Keys are command names used by command_ref.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["run", "kind", "purpose"],
+        "properties": {
+          "run": { "type": "string", "maxLength": 500, "description": "Shell command to execute." },
+          "kind": {
+            "type": "string",
+            "enum": ["setup", "verify", "run"],
+            "description": "setup=install deps, verify=validation check, run=server/interactive."
+          },
+          "purpose": { "type": "string", "maxLength": 300 },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "code_style": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Formatting, naming, conventions. Advisory limit: 1000 chars total."
+    },
+    "git": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Branch strategy, commit style, PR rules. Advisory limit: 1000 chars total."
+    },
+    "donts": {
+      "type": "array",
+      "description": "Things you must never do.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "rule"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "rule": { "type": "string", "maxLength": 300 },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "warning"],
+            "default": "critical"
+          },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "ask_first": {
+      "type": "array",
+      "description": "Triggers that need human approval before the agent proceeds.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "trigger_type", "trigger", "reason"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "trigger_type": {
+            "type": "string",
+            "enum": ["file_pattern", "task_pattern"]
+          },
+          "trigger": { "type": "string", "maxLength": 300 },
+          "reason": { "type": "string", "maxLength": 300 },
+          "links": { "$ref": "./frame.schema.json#/$defs/links" }
+        }
+      }
+    },
+    "hints": {
+      "type": "array",
+      "description": "Skill references, known gotchas, task-specific guidance.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "hint"],
+        "properties": {
+          "id": { "$ref": "./frame.schema.json#/$defs/stable_id" },
+          "hint": { "type": "string", "maxLength": 300 }
+        }
+      }
+    },
+    "evidence": { "$ref": "./frame.schema.json#/$defs/evidence_list" },
+    "links": { "$ref": "./frame.schema.json#/$defs/links" }
+  }
+}

framesdkpy/translators/__init__.py

@@ -0,0 +1,24 @@
+"""FRAME translators -- YAML/JSON conversion with normalization.
+
+Public API:
+    translate_file("facts.yaml")    → dict
+    translate_directory(".haxaml/") → {"facts": {...}, "rules": {...}, ...}
+    translate_to_dict(yaml_string)  → dict
+    translate_to_json_string(yaml)  → str
+"""
+
+from framesdkpy.translators.yaml_to_json import (
+    translate_file,
+    translate_directory,
+    translate_to_dict,
+    translate_to_json_string,
+)
+from framesdkpy.translators.normalizer import TranslationError
+
+__all__ = [
+    "translate_file",
+    "translate_directory",
+    "translate_to_dict",
+    "translate_to_json_string",
+    "TranslationError",
+]

framesdkpy/translators/normalizer.py

@@ -0,0 +1,106 @@
+"""YAML type normalizer -- resolves YAML quirks into clean JSON-compatible types.
+
+Handles the full YAML 1.2 quirk table defined in the translators spec:
+  yes/no → True/False
+  ~/null → None
+  Date-like strings preserved as strings
+  Empty strings and empty fields handled correctly
+
+Raises TranslationError on ambiguous input (on/off).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from datetime import date, datetime
+
+
+class TranslationError(ValueError):
+    """Raised when YAML input is ambiguous and cannot be safely translated."""
+
+    def __init__(self, path: str, value: Any, reason: str):
+        self.path = path
+        self.value = value
+        self.reason = reason
+        super().__init__(f"{path}: {reason} (got {value!r})")
+
+
+def normalize_yaml_value(value: Any, path: str = "$") -> Any:
+    """Resolve a single YAML value to a JSON-compatible type.
+
+    Recursively handles dicts and lists. The path argument tracks position
+    for error messages -- use normalize_dict() for top-level entry.
+    """
+    # Dict: recurse into values, tracking keys for error paths
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        for k, v in value.items():
+            result[k] = normalize_yaml_value(v, f"{path}.{k}")
+        return result
+
+    # List: recurse into items
+    if isinstance(value, list):
+        return [normalize_yaml_value(item, f"{path}[{i}]") for i, item in enumerate(value)]
+
+    # None / null
+    if value is None:
+        return None
+
+    # Date/datetime: PyYAML SafeLoader parses bare YYYY-MM-DD scalars into
+    # date objects. FRAME preserves dates as strings so JSON output is stable
+    # across languages and serializers.
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+
+    # String: check for YAML quirks
+    if isinstance(value, str):
+        return _normalize_string(value, path)
+
+    # Numbers and booleans pass through as-is (YAML already parsed them correctly)
+    return value
+
+
+def _normalize_string(value: str, path: str) -> Any:
+    """Normalize a YAML string -- handle yes/no, null, empty, date-like."""
+
+    # Empty string: preserve as-is (not coerced to null)
+    if value == "":
+        return ""
+
+    # Explicit null values
+    if value.lower() in ("null", "~"):
+        return None
+
+    # YAML 1.2 booleans (only yes/no -- on/off are ambiguous and rejected)
+    if value.lower() in ("yes", "true", "y"):
+        return True
+    if value.lower() in ("no", "false", "n"):
+        return False
+
+    # Ambiguous: on/off are YAML 1.1 booleans. YAML 1.2 doesn't treat them as
+    # booleans, but some parsers do. We fail loudly rather than guessing.
+    if value.lower() in ("on", "off"):
+        raise TranslationError(
+            path, value,
+            "'on'/'off' is ambiguous in YAML. Use explicit 'true' or 'false' or quote as string.",
+        )
+
+    # Date-like strings (YYYY-MM-DD, YYYY/MM/DD): YAML parsers may convert these
+    # to datetime objects. We preserve them as strings for FRAME consistency.
+    # The caller's YAML loader should use a loader that doesn't auto-parse dates.
+    # If a datetime slips through (parsed by the YAML lib), we catch it above in
+    # the type check -- datetimes are normalized back to strings before JSON/schema validation.
+
+    return value
+
+
+def normalize_dict(data: dict[str, Any]) -> dict[str, Any]:
+    """Normalize an entire YAML dict. Entry point for the translator."""
+    return normalize_yaml_value(data, "$")
+
+
+def normalize_list(data: list[Any]) -> list[Any]:
+    """Normalize a YAML list. Convenience for array-only files."""
+    return normalize_yaml_value(data, "$")

framesdkpy/translators/yaml_to_json.py

@@ -0,0 +1,88 @@
+"""YAML to JSON translator -- reads FRAME YAML files and produces clean JSON.
+
+Uses the normalizer to resolve YAML quirks, then validates the output against
+the JSON Schema shape. Returns a clean dict ready for the validator or assembler.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from framesdkpy.translators.normalizer import normalize_dict
+
+
+# Use PyYAML SafeLoader, then normalize parsed values into JSON-compatible FRAME values.
+# This prevents YAML quirks from reaching the normalizer.
+_YAML_LOADER = yaml.SafeLoader
+
+
+def translate_to_dict(yaml_string: str) -> dict:
+    """Parse a YAML string into a clean JSON-compatible dict.
+
+    Handles all YAML to JSON normalization per the translators spec.
+    Raises TranslationError on ambiguous input.
+    """
+    raw = yaml.load(yaml_string, Loader=_YAML_LOADER)
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise ValueError(f"Expected YAML object, got {type(raw).__name__}")
+    return normalize_dict(raw)
+
+
+def translate_file(file_path: str | Path) -> dict:
+    """Read a YAML file and translate to a clean JSON-compatible dict.
+
+    Args:
+        file_path: Path to a .yaml FRAME file (facts.yaml, rules.yaml, etc.)
+
+    Returns:
+        Clean dict with all YAML quirks resolved.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"FRAME file not found: {path}")
+    if path.suffix not in (".yaml", ".yml"):
+        raise ValueError(f"Expected .yaml file, got {path.suffix}: {path}")
+
+    yaml_string = path.read_text()
+    return translate_to_dict(yaml_string)
+
+
+def translate_directory(dir_path: str | Path) -> dict[str, dict]:
+    """Read all 5 FRAME YAML files from a directory.
+
+    Args:
+        dir_path: Directory containing facts.yaml, rules.yaml, map.yaml,
+                  expect.yaml, acts.yaml.
+
+    Returns:
+        Dict mapping file stem to translated dict, e.g.:
+        {"facts": {...}, "rules": {...}, "map": {...}, "expect": {...}, "acts": {...}}
+    """
+    directory = Path(dir_path)
+    if not directory.is_dir():
+        raise FileNotFoundError(f"FRAME directory not found: {directory}")
+
+    expected_files = ["facts", "rules", "map", "expect", "acts"]
+    result: dict[str, dict] = {}
+
+    for stem in expected_files:
+        yaml_file = directory / f"{stem}.yaml"
+        if not yaml_file.exists():
+            raise FileNotFoundError(
+                f"Missing FRAME file: {stem}.yaml in {directory}. "
+                f"All 5 files must be in the same directory."
+            )
+        result[stem] = translate_file(yaml_file)
+
+    return result
+
+
+def translate_to_json_string(yaml_string: str, indent: int = 2) -> str:
+    """Parse YAML and return a JSON string directly."""
+    data = translate_to_dict(yaml_string)
+    return json.dumps(data, indent=indent, ensure_ascii=False)

framesdkpy/validators/__init__.py

@@ -0,0 +1,74 @@
+"""FRAME validators -- schema, character limits, and cross-file consistency.
+
+Public API:
+    validate_file("facts.yaml")        → ValidationResult (single file)
+    validate_frame(".haxaml/")         → ValidationResult (all 5 + cross-file)
+    validate_against_schema(data, "facts") → ValidationResult (in-memory)
+    validate_limits(data, "facts")         → ValidationResult (in-memory)
+"""
+
+from framesdkpy.validators.result import ValidationResult, ValidationError, ValidationWarning
+from framesdkpy.validators.schema_validator import validate_against_schema, validate_yaml_file
+from framesdkpy.validators.limits_validator import validate_limits
+from framesdkpy.validators.cross_file_validator import validate_cross_file
+
+
+def validate_file(file_path: str) -> ValidationResult:
+    """Validate a single FRAME YAML file against schema + limits.
+
+    Does NOT run cross-file checks (only one file).
+    """
+    result = validate_yaml_file(file_path)
+
+    # Also run limits validation
+    import yaml
+    from pathlib import Path
+    from framesdkpy.translators.normalizer import normalize_dict
+
+    path = Path(file_path)
+    raw = yaml.safe_load(path.read_text())
+    if raw and isinstance(raw, dict):
+        clean = normalize_dict(raw)
+        limits_result = validate_limits(clean, path.stem)
+        result = result.merge(limits_result)
+
+    return result
+
+
+def validate_frame(dir_path: str) -> ValidationResult:
+    """Validate all 5 FRAME files in a directory + cross-file consistency.
+
+    Steps:
+    1. Schema validation for each file
+    2. Character limit validation for each file
+    3. Cross-file consistency (versions, file/role matching)
+    """
+    from pathlib import Path
+    from framesdkpy.translators.yaml_to_json import translate_directory
+
+    # Translate all 5 files to clean dicts
+    parts = translate_directory(dir_path)
+
+    result = ValidationResult()
+
+    # Schema + limits for each file
+    for stem, data in parts.items():
+        result = result.merge(validate_against_schema(data, stem))
+        result = result.merge(validate_limits(data, stem))
+
+    # Cross-file consistency
+    result = result.merge(validate_cross_file(parts))
+
+    return result
+
+
+__all__ = [
+    "ValidationResult",
+    "ValidationError",
+    "ValidationWarning",
+    "validate_file",
+    "validate_frame",
+    "validate_against_schema",
+    "validate_limits",
+    "validate_cross_file",
+]

framesdkpy/validators/cross_file_validator.py

@@ -0,0 +1,85 @@
+"""Cross-file validator -- checks consistency across all 5 FRAME files.
+
+Verifies:
+- All schema_version fields match
+- All file/role fields match expected values (facts file must have file: facts)
+"""
+
+from __future__ import annotations
+
+from framesdkpy.validators.result import ValidationResult
+
+
+_EXPECTED_FILE_MAP = {
+    "facts": "facts",
+    "rules": "rules",
+    "map": "map",
+    "expect": "expect",
+    "acts": "acts",
+}
+
+_EXPECTED_ROLE_MAP = {
+    "facts": "current_project_truth",
+    "rules": "project_instruction_blueprint",
+    "map": "repo_context_map",
+    "expect": "project_correctness_contract",
+    "acts": "checked_activity_record",
+}
+
+
+def validate_cross_file(parts: dict[str, dict]) -> ValidationResult:
+    """Check cross-file consistency across all 5 translated FRAME parts.
+
+    Args:
+        parts: Dict mapping file stem to translated dict.
+               e.g., {"facts": {...}, "rules": {...}, ...}
+
+    Returns:
+        ValidationResult with errors for mismatched versions or file/role fields.
+    """
+    result = ValidationResult()
+
+    # Gather schema_version from every file that has a frame header
+    versions: dict[str, str] = {}
+    for stem, data in parts.items():
+        header = data.get("frame", {})
+        version = header.get("schema_version")
+        if version:
+            versions[stem] = version
+
+    # All present schema_versions must match
+    if len(set(versions.values())) > 1:
+        details = ", ".join(f"{s}={v}" for s, v in versions.items())
+        result.add_error(
+            path="frame.schema_version",
+            message=f"Schema version mismatch across files: {details}",
+            code="schema_version_mismatch",
+        )
+
+    # Each file's 'file' and 'role' fields must match expected values
+    for stem, data in parts.items():
+        header = data.get("frame", {})
+
+        expected_file = _EXPECTED_FILE_MAP.get(stem)
+        actual_file = header.get("file")
+        if expected_file and actual_file and actual_file != expected_file:
+            result.add_error(
+                path=f"{stem}.frame.file",
+                message=f"File field mismatch in {stem}.yaml",
+                code="file_role_mismatch",
+                expected=expected_file,
+                actual=actual_file,
+            )
+
+        expected_role = _EXPECTED_ROLE_MAP.get(stem)
+        actual_role = header.get("role")
+        if expected_role and actual_role and actual_role != expected_role:
+            result.add_error(
+                path=f"{stem}.frame.role",
+                message=f"Role field mismatch in {stem}.yaml",
+                code="file_role_mismatch",
+                expected=expected_role,
+                actual=actual_role,
+            )
+
+    return result