MertCapkin-GraphCraft 0.1.1__py3-none-any.whl

graphcraft/assets/packs/mobile-app/STACKS.md

@@ -0,0 +1,28 @@
+# Mobile App Pack
+
+`profile: mobile-app` in `graphcraft.config.yaml`
+
+## Supported stacks
+
+| Stack | UI lib path | Notes |
+|-------|-------------|-------|
+| react-native | packages/ui-core/rn/ | StyleSheet + tokens |
+| expo | packages/ui-core/expo/ | Expo Router screens |
+| flutter | packages/ui-core/flutter/ | ThemeData from tokens.json |
+| swiftui | packages/ui-core/swiftui/ | Asset catalog + SwiftUI Theme |
+| jetpack-compose | packages/ui-core/compose/ | Material3 + custom tokens |
+| kotlin-multiplatform | packages/ui-core/kmp/ | Shared theme module |
+| ionic | packages/ui-core/ionic/ | CSS variables from tokens |
+| capacitor | packages/ui-core/capacitor/ | Web + native shell |
+
+## Builder rules
+
+- Consume tokens from `design-system/tokens.json`
+- Map design graph `component:*` to package components
+- Navigation follows `navigates_to` edges in design graph
+
+## Design graph query
+
+```bash
+python -m graphcraft design query "screens"
+```

graphcraft/assets/packs/mobile-game/STACKS.md

@@ -0,0 +1,30 @@
+# Mobile Game Pack
+
+`profile: mobile-game` in `graphcraft.config.yaml`
+
+## Supported stacks
+
+| Stack | Scope | Notes |
+|-------|-------|-------|
+| unity-ugui | Meta-UI | Canvas, RectTransform, ScriptableObject themes |
+| unity-ui-toolkit | Meta-UI | USS/UXML from tokens |
+| godot | Meta-UI | Control nodes + theme resource |
+| unreal-umg | Meta-UI | Widget blueprints + styles |
+| defold | Meta-UI | GUI scenes |
+| cocos | Meta-UI | Prefab UI |
+
+## Scope limit
+
+Stitch/design graph targets **meta-UI**: menus, HUD overlays, shop, inventory, dialogs.
+
+Gameplay canvas art is out of GraphCraft v0.1 scope.
+
+## Builder rules
+
+- `stitch.scope: meta-ui-only` recommended
+- Visual reference mode: PNG from `.stitch/designs/`
+- Token → USS / ScriptableObject theme pipeline
+
+## Asset library
+
+Place sprites in `packages/assets/` with manifest YAML linking to components.

graphcraft/assets/packs/stitch/README.md

@@ -0,0 +1,20 @@
+# Stitch Pack
+
+Optional prototype import from [Google Stitch](https://stitch.withgoogle.com/).
+
+## Setup
+
+1. `design_source: stitch` or `hybrid` in graphcraft.config.yaml
+2. Export Stitch project → `.stitch/`
+3. `graphcraft stitch import .`
+
+## Files
+
+- `.stitch/DESIGN.md` — Stitch design system (official format)
+- `.stitch/metadata.json` — screen map + flows
+- `.stitch/designs/*.png` — visual ground truth
+
+## Docs
+
+- [DESIGN.md spec](https://github.com/google-labs-code/design.md)
+- Stitch MCP: `@keeponfirst/kof-stitch-mcp`

graphcraft/assets/packs/styles/minimal-dark/style.yaml

@@ -0,0 +1,18 @@
+id: style:minimal-dark
+label: Minimal Dark
+mood:
+  - calm
+  - premium
+  - readable
+priority: balanced
+tokens:
+  extends: design-system/tokens.json
+harmony:
+  contrast_min: 4.5
+  max_accent_colors: 2
+components:
+  preferred:
+    - component:button-primary
+  discouraged: []
+assets:
+  icon_set: assets:icons-minimal

graphcraft/bootstrap.py

@@ -0,0 +1,68 @@
+"""Ensure GraphStack + Graphify are available for graphcraft init."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+PIP_SPEC = "MertCapkin_GraphStack[graphify]>=4.7,<5"
+PIP_SPEC_GIT = (
+    "MertCapkin_GraphStack[graphify] @ git+https://github.com/MertCapkin/GraphStack.git"
+)
+
+
+def _echo(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def find_python() -> list[str]:
+    return [sys.executable]
+
+
+def graphstack_available() -> bool:
+    try:
+        import graphstack  # noqa: F401
+        return True
+    except ImportError:
+        pass
+    proc = subprocess.run(
+        [*find_python(), "-m", "graphstack", "--version"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return proc.returncode == 0
+
+
+def pip_install(*specs: str, quiet: bool = True) -> int:
+    if not specs:
+        return 0
+    cmd = [*find_python(), "-m", "pip", "install", "--upgrade"]
+    if quiet:
+        cmd.append("--quiet")
+    cmd.extend(specs)
+    _echo(f"  pip install {' '.join(specs)}")
+    return subprocess.run(cmd, check=False).returncode
+
+
+def ensure_graphstack(*, install: bool = True) -> bool:
+    if graphstack_available():
+        return True
+    if not install:
+        return False
+    _echo("")
+    _echo("Installing GraphStack (MertCapkin_GraphStack[graphify])...")
+    rc = pip_install(PIP_SPEC)
+    if rc != 0:
+        _echo("PyPI install failed — trying GitHub...")
+        rc = pip_install(PIP_SPEC_GIT)
+    return rc == 0 and graphstack_available()
+
+
+def run_graphstack_init(target: str, *, non_interactive: bool, install_deps: bool) -> int:
+    cmd = [*find_python(), "-m", "graphstack", "init", target]
+    if non_interactive:
+        cmd.append("-y")
+    if install_deps:
+        cmd.append("--install-deps")
+    return subprocess.run(cmd, check=False).returncode

graphcraft/cli.py

@@ -0,0 +1,63 @@
+"""GraphCraft CLI dispatcher."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+from . import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="graphcraft",
+        description="GraphCraft — mobile design layer on GraphStack.",
+    )
+    parser.add_argument("--version", action="version", version=f"graphcraft {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("install", help="Install GraphCraft overlay into a project", add_help=False)
+    sub.add_parser("init", help="GraphStack init + GraphCraft overlay", add_help=False)
+    sub.add_parser("doctor", help="GraphCraft + GraphStack health check", add_help=False)
+    sub.add_parser("design", help="Design graph commands", add_help=False)
+    sub.add_parser("stitch", help="Stitch import commands", add_help=False)
+    return parser
+
+
+def _delegate_graphstack(rest: list[str]) -> int:
+    cmd = [sys.executable, "-m", "graphstack", *rest]
+    return subprocess.run(cmd, check=False).returncode
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if not args or args[0] in ("-h", "--help"):
+        _build_parser().print_help()
+        return 0
+    if args[0] == "--version":
+        print(f"graphcraft {__version__}")
+        return 0
+
+    cmd, rest = args[0], args[1:]
+
+    if cmd == "install":
+        from .installer import run as install_run
+        return install_run(rest)
+    if cmd == "init":
+        from .init_cmd import run as init_run
+        return init_run(rest)
+    if cmd == "doctor":
+        from .doctor import run as doctor_run
+        return doctor_run(rest)
+    if cmd == "design":
+        from .design_graph.cli import run as design_run
+        return design_run(rest)
+    if cmd == "stitch":
+        from .stitch.cli import run as stitch_run
+        return stitch_run(rest)
+
+    return _delegate_graphstack([cmd, *rest])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

graphcraft/constants.py

@@ -0,0 +1,21 @@
+"""GraphCraft path constants."""
+
+from pathlib import Path
+
+GRAPHCRAFT_OUT = Path("graphcraft-out")
+DESIGN_GRAPH_JSON = GRAPHCRAFT_OUT / "design-graph.json"
+DESIGN_REPORT = GRAPHCRAFT_OUT / "DESIGN_REPORT.md"
+BRIDGE_JSON = GRAPHCRAFT_OUT / "bridge.json"
+
+DESIGN_SYSTEM_DIR = Path("design-system")
+DESIGN_SCREENS_DIR = Path("design") / "screens"
+DESIGN_COMPONENTS_DIR = DESIGN_SYSTEM_DIR / "components"
+STYLES_DIR = Path("packs") / "styles"
+STITCH_DIR = Path(".stitch")
+CONFIG_FILE = Path("graphcraft.config.yaml")
+
+HANDOFF_AESTHETIC = Path("handoff") / "AESTHETIC_BRIEF.md"
+HANDOFF_DESIGN = Path("handoff") / "DESIGN_BRIEF.md"
+
+PACKAGES_UI = Path("packages") / "ui-core"
+PACKAGES_ASSETS = Path("packages") / "assets"

graphcraft/design_graph/__init__.py

@@ -0,0 +1 @@
+"""Design graph package."""

graphcraft/design_graph/builder.py

@@ -0,0 +1,218 @@
+"""Build design-graph.json from declarative design sources."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:
+    yaml = None  # type: ignore
+
+from ..constants import (
+    DESIGN_COMPONENTS_DIR,
+    DESIGN_SCREENS_DIR,
+    DESIGN_SYSTEM_DIR,
+    STITCH_DIR,
+    STYLES_DIR,
+)
+from .schema import empty_graph, make_edge, make_node
+from .stitch_adapter import ingest_stitch
+from .report import write_design_report
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if yaml is None:
+        raise RuntimeError("PyYAML required: pip install pyyaml")
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def _parse_tokens(tokens_path: Path, graph: dict[str, Any]) -> None:
+    if not tokens_path.is_file():
+        return
+    data = json.loads(tokens_path.read_text(encoding="utf-8"))
+
+    def walk(obj: Any, prefix: str = "") -> None:
+        if not isinstance(obj, dict):
+            return
+        if "$value" in obj or "value" in obj:
+            tid = f"token:{prefix}"
+            val = obj.get("$value") or obj.get("value")
+            graph["nodes"].append(
+                make_node(
+                    tid,
+                    ntype="token",
+                    label=prefix,
+                    source=str(tokens_path),
+                    origin="extracted",
+                    extra={"value": val, "token_type": obj.get("$type", "unknown")},
+                )
+            )
+            return
+        for key, child in obj.items():
+            if key.startswith("$"):
+                continue
+            child_prefix = f"{prefix}.{key}" if prefix else key
+            walk(child, child_prefix)
+
+    walk(data)
+
+
+def _parse_component(path: Path, graph: dict[str, Any]) -> None:
+    data = _load_yaml(path)
+    cid = data.get("id") or f"component:{path.stem}"
+    graph["nodes"].append(
+        make_node(
+            str(cid),
+            ntype="component",
+            label=data.get("label", path.stem),
+            source=str(path),
+            origin="designed",
+            extra={
+                "collection": data.get("collection"),
+                "when_to_use": data.get("when_to_use"),
+                "when_not_to_use": data.get("when_not_to_use"),
+            },
+        )
+    )
+    for tok in data.get("uses_tokens") or []:
+        tid = tok if str(tok).startswith("token:") else f"token:{tok}"
+        graph["edges"].append(make_edge(str(cid), tid, "uses_token"))
+    for alt in data.get("alternatives") or []:
+        graph["edges"].append(make_edge(str(cid), str(alt), "alternative"))
+    for style in data.get("style_compatibility") or []:
+        sid = style if str(style).startswith("style:") else f"style:{style}"
+        graph["edges"].append(make_edge(str(cid), sid, "style_compatible"))
+    for other, score in (data.get("harmony_score_with") or {}).items():
+        etype = "harmonizes_with" if float(score) >= 0.5 else "clashes_with"
+        graph["edges"].append(
+            make_edge(str(cid), str(other), etype, extra={"score": float(score)})
+        )
+
+
+def _parse_screen(path: Path, graph: dict[str, Any]) -> None:
+    data = _load_yaml(path)
+    sid = data.get("id") or f"screen:{path.stem}"
+    graph["nodes"].append(
+        make_node(
+            str(sid),
+            ntype="screen",
+            label=data.get("title", path.stem),
+            source=str(path),
+            origin="designed",
+            extra={"platform": data.get("platform"), "status": data.get("status", "draft")},
+        )
+    )
+    for comp in data.get("components") or []:
+        cid = comp if str(comp).startswith("component:") else f"component:{comp}"
+        graph["edges"].append(make_edge(str(sid), cid, "uses_component"))
+    for tok in data.get("tokens") or []:
+        tid = tok if str(tok).startswith("token:") else f"token:{tok}"
+        graph["edges"].append(make_edge(str(sid), tid, "uses_token"))
+    nav = data.get("navigation") or {}
+    if isinstance(nav, dict):
+        for _action, target in nav.items():
+            tid = target if str(target).startswith("screen:") else f"screen:{target}"
+            graph["edges"].append(make_edge(str(sid), tid, "navigates_to"))
+    impl = data.get("implements")
+    if impl:
+        graph["edges"].append(
+            make_edge(str(sid), str(impl), "implements", origin="bridge")
+        )
+
+
+def _parse_style(path: Path, graph: dict[str, Any]) -> None:
+    data = _load_yaml(path)
+    sid = data.get("id") or f"style:{path.parent.name}"
+    graph["nodes"].append(
+        make_node(
+            str(sid),
+            ntype="style",
+            label=data.get("label", path.parent.name),
+            source=str(path),
+            origin="designed",
+            extra={"mood": data.get("mood"), "priority": data.get("priority")},
+        )
+    )
+    for comp in data.get("components", {}).get("preferred") or []:
+        graph["edges"].append(make_edge(str(sid), str(comp), "style_compatible"))
+    asset_set = data.get("assets", {}).get("icon_set")
+    if asset_set:
+        aid = asset_set if str(asset_set).startswith("assets:") else f"assets:{asset_set}"
+        graph["edges"].append(make_edge(str(sid), aid, "uses_asset"))
+
+
+def build_design_graph(root: Path) -> dict[str, Any]:
+    graph = empty_graph()
+    tokens = root / DESIGN_SYSTEM_DIR / "tokens.json"
+    if not tokens.is_file():
+        tokens = root / DESIGN_SYSTEM_DIR / "tokens.base.json"
+    _parse_tokens(tokens, graph)
+
+    components_dir = root / DESIGN_COMPONENTS_DIR
+    if components_dir.is_dir():
+        for path in sorted(components_dir.glob("*.yaml")):
+            _parse_component(path, graph)
+
+    screens_dir = root / DESIGN_SCREENS_DIR
+    if screens_dir.is_dir():
+        for path in sorted(screens_dir.glob("*.yaml")):
+            _parse_screen(path, graph)
+
+    styles_dir = root / STYLES_DIR
+    if styles_dir.is_dir():
+        for style_file in sorted(styles_dir.glob("*/style.yaml")):
+            _parse_style(style_file, graph)
+
+    stitch_dir = root / STITCH_DIR
+    if stitch_dir.is_dir():
+        ingest_stitch(stitch_dir, graph)
+
+    _materialize_missing_targets(graph)
+    return graph
+
+
+def _materialize_missing_targets(graph: dict[str, Any]) -> None:
+    """Create placeholder nodes for referenced IDs not explicitly defined."""
+    nodes = graph.get("nodes") or []
+    edges = graph.get("edges") or []
+    known = {n["id"] for n in nodes if "id" in n}
+    prefix_type = {
+        "screen:": "screen",
+        "component:": "component",
+        "token:": "token",
+        "style:": "style",
+        "assets:": "asset",
+    }
+    for e in edges:
+        for end in (e.get("source"), e.get("target")):
+            if not end or end in known:
+                continue
+            ntype = "component"
+            for prefix, t in prefix_type.items():
+                if str(end).startswith(prefix):
+                    ntype = t
+                    break
+            graph["nodes"].append(
+                make_node(
+                    str(end),
+                    ntype=ntype,
+                    label=str(end).split(":", 1)[-1],
+                    source="",
+                    origin="inferred",
+                )
+            )
+            known.add(str(end))
+
+
+def update_design_graph(root: Path) -> dict[str, Any]:
+    graph = build_design_graph(root)
+    out_dir = root / "graphcraft-out"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "design-graph.json"
+    out_path.write_text(json.dumps(graph, indent=2), encoding="utf-8")
+    write_design_report(graph, out_dir / "DESIGN_REPORT.md")
+    return graph

graphcraft/design_graph/cli.py

@@ -0,0 +1,83 @@
+"""Design graph CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ..constants import DESIGN_GRAPH_JSON
+from .builder import update_design_graph
+from .harmony import run_harmony_check
+from .query import load_graph, query, validate
+
+
+def run(argv: list[str]) -> int:
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Usage: graphcraft design <update|query|validate|harmony> ...")
+        return 0
+
+    cmd, rest = argv[0], argv[1:]
+
+    if cmd == "update":
+        p = argparse.ArgumentParser(prog="graphcraft design update")
+        p.add_argument("root", nargs="?", default=".")
+        args = p.parse_args(rest)
+        root = Path(args.root).resolve()
+        graph = update_design_graph(root)
+        print(f"Design graph: {len(graph.get('nodes', []))} nodes, {len(graph.get('edges', []))} edges")
+        print(f"  -> {root / DESIGN_GRAPH_JSON}")
+        return 0
+
+    if cmd == "query":
+        p = argparse.ArgumentParser(prog="graphcraft design query")
+        p.add_argument("question", help="design graph question")
+        p.add_argument("--graph", default=str(DESIGN_GRAPH_JSON))
+        args = p.parse_args(rest)
+        path = Path(args.graph)
+        if not path.is_file():
+            print(f"Missing {path} — run: graphcraft design update .")
+            return 1
+        print(query(load_graph(path), args.question))
+        return 0
+
+    if cmd == "validate":
+        p = argparse.ArgumentParser(prog="graphcraft design validate")
+        p.add_argument("--graph", default=str(DESIGN_GRAPH_JSON))
+        args = p.parse_args(rest)
+        path = Path(args.graph)
+        if not path.is_file():
+            print(f"Missing {path}")
+            return 1
+        issues = validate(load_graph(path))
+        if issues:
+            for i in issues:
+                print(f"  ISSUE: {i}")
+            return 1
+        print("Design graph validation: PASS")
+        return 0
+
+    if cmd == "harmony":
+        p = argparse.ArgumentParser(prog="graphcraft design harmony")
+        p.add_argument("--graph", default=str(DESIGN_GRAPH_JSON))
+        p.add_argument("--screen", default=None)
+        args = p.parse_args(rest)
+        path = Path(args.graph)
+        if not path.is_file():
+            print(f"Missing {path}")
+            return 1
+        result = run_harmony_check(load_graph(path), args.screen)
+        print(f"Harmony: {result['overall']}")
+        for w in result["warnings"]:
+            print(f"  WARN: {w}")
+        for p_msg in result["passed"]:
+            print(f"  OK: {p_msg}")
+        return 0 if result["overall"] == "PASS" else 1
+
+    print(f"Unknown design subcommand: {cmd}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(run(sys.argv[1:]))

graphcraft/design_graph/harmony.py

@@ -0,0 +1,47 @@
+"""Harmony checks on design graph."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def run_harmony_check(graph: dict[str, Any], screen_id: str | None = None) -> dict[str, Any]:
+    nodes = {n["id"]: n for n in graph.get("nodes") or [] if "id" in n}
+    edges = graph.get("edges") or []
+
+    clashes: list[dict] = []
+    warnings: list[str] = []
+    passed: list[str] = []
+
+    for e in edges:
+        if e.get("type") == "clashes_with":
+            clashes.append(e)
+
+    screens = [
+        n for n in nodes.values() if n.get("type") == "screen" and (not screen_id or n["id"] == screen_id)
+    ]
+
+    for screen in screens:
+        sid = screen["id"]
+        comp_ids = [
+            e["target"]
+            for e in edges
+            if e.get("source") == sid and e.get("type") == "uses_component"
+        ]
+        for i, a in enumerate(comp_ids):
+            for b in comp_ids[i + 1 :]:
+                for e in edges:
+                    if e.get("type") == "clashes_with" and (
+                        (e.get("source") == a and e.get("target") == b)
+                        or (e.get("source") == b and e.get("target") == a)
+                    ):
+                        warnings.append(f"CLASH on {sid}: {a} ↔ {b}")
+        if not warnings:
+            passed.append(f"{sid}: no component clashes detected")
+
+    return {
+        "overall": "FAIL" if warnings else "PASS",
+        "clashes_in_graph": len(clashes),
+        "warnings": warnings,
+        "passed": passed,
+    }

graphcraft/design_graph/query.py

@@ -0,0 +1,81 @@
+"""Simple design graph queries."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_graph(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _index(graph: dict[str, Any]) -> tuple[dict[str, dict], list[dict]]:
+    nodes = {n["id"]: n for n in graph.get("nodes") or [] if "id" in n}
+    return nodes, list(graph.get("edges") or [])
+
+
+def query(graph: dict[str, Any], question: str) -> str:
+    q = question.lower()
+    nodes, edges = _index(graph)
+
+    if "screen" in q:
+        screens = [n for n in nodes.values() if n.get("type") == "screen"]
+        lines = [f"Screens ({len(screens)}):"]
+        for s in screens:
+            comps = [
+                e["target"]
+                for e in edges
+                if e.get("source") == s["id"] and e.get("type") == "uses_component"
+            ]
+            lines.append(f"  {s['id']}: {s.get('label')} → components: {', '.join(comps) or 'none'}")
+        return "\n".join(lines)
+
+    if "token" in q:
+        tokens = [n for n in nodes.values() if n.get("type") == "token"]
+        return f"Tokens: {len(tokens)} defined. Sample: " + ", ".join(
+            t["id"] for t in tokens[:8]
+        )
+
+    if "style" in q:
+        styles = [n["id"] for n in nodes.values() if n.get("type") == "style"]
+        return "Styles: " + (", ".join(styles) or "none")
+
+    if "harmony" in q or "clash" in q:
+        clashes = [e for e in edges if e.get("type") == "clashes_with"]
+        harmonizes = [e for e in edges if e.get("type") == "harmonizes_with"]
+        return (
+            f"Harmony edges: {len(harmonizes)} harmonizes_with, "
+            f"{len(clashes)} clashes_with"
+        )
+
+    return (
+        f"Design graph: {len(nodes)} nodes, {len(edges)} edges. "
+        "Try: 'screens', 'tokens', 'styles', 'harmony'"
+    )
+
+
+def validate(graph: dict[str, Any]) -> list[str]:
+    issues: list[str] = []
+    nodes, edges = _index(graph)
+    node_ids = set(nodes)
+
+    for e in edges:
+        if e.get("source") not in node_ids:
+            issues.append(f"Edge source missing node: {e.get('source')}")
+        if e.get("target") not in node_ids:
+            issues.append(f"Edge target missing node: {e.get('target')}")
+
+    for n in nodes.values():
+        if n.get("type") == "screen":
+            sid = n["id"]
+            if n.get("_origin") == "inferred":
+                continue
+            has_comp = any(
+                e.get("source") == sid and e.get("type") == "uses_component" for e in edges
+            )
+            if not has_comp and n.get("_origin") != "stitch":
+                issues.append(f"Screen {sid} has no uses_component edges")
+
+    return issues