spriteforge 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (218) hide show
  1. spriteforge/__init__.py +1 -0
  2. spriteforge/__main__.py +3 -0
  3. spriteforge/agents/__init__.py +0 -0
  4. spriteforge/agents/assets.py +109 -0
  5. spriteforge/agents/cancellation.py +12 -0
  6. spriteforge/agents/director.py +50 -0
  7. spriteforge/agents/models.py +63 -0
  8. spriteforge/agents/roles/art-director.md +15 -0
  9. spriteforge/agents/roles/art-reviewer.md +14 -0
  10. spriteforge/agents/roles/director.md +14 -0
  11. spriteforge/agents/roles/game-designer.md +15 -0
  12. spriteforge/agents/roles/level-tile-designer.md +16 -0
  13. spriteforge/agents/roles/librarian.md +13 -0
  14. spriteforge/agents/roles/menu-designer.md +15 -0
  15. spriteforge/agents/roles/pixel-artist.md +14 -0
  16. spriteforge/agents/roles/programmer.md +14 -0
  17. spriteforge/agents/roles/qa-playtester.md +13 -0
  18. spriteforge/agents/roles/sound-director.md +14 -0
  19. spriteforge/agents/roles.py +39 -0
  20. spriteforge/agents/router.py +233 -0
  21. spriteforge/agents/router_eval.py +145 -0
  22. spriteforge/agents/routing_state.py +133 -0
  23. spriteforge/agents/runtime.py +430 -0
  24. spriteforge/agents/workflow.py +389 -0
  25. spriteforge/app/__init__.py +0 -0
  26. spriteforge/app/agents_view.py +248 -0
  27. spriteforge/app/chat.py +114 -0
  28. spriteforge/app/extensions.py +115 -0
  29. spriteforge/app/index.html +279 -0
  30. spriteforge/app/local_only.py +49 -0
  31. spriteforge/app/server.py +358 -0
  32. spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
  33. spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
  34. spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
  35. spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
  36. spriteforge/app/static/index.html +13 -0
  37. spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
  38. spriteforge/app/studio.py +278 -0
  39. spriteforge/app/workers.py +73 -0
  40. spriteforge/cli.py +241 -0
  41. spriteforge/config.py +193 -0
  42. spriteforge/config.yaml +157 -0
  43. spriteforge/core/__init__.py +0 -0
  44. spriteforge/core/acting.py +16 -0
  45. spriteforge/core/cost.py +236 -0
  46. spriteforge/core/credentials.py +24 -0
  47. spriteforge/core/demo.py +79 -0
  48. spriteforge/core/forms.py +20 -0
  49. spriteforge/core/gates.py +175 -0
  50. spriteforge/core/security.py +42 -0
  51. spriteforge/core/state.py +222 -0
  52. spriteforge/core/team.py +15 -0
  53. spriteforge/core/usage.py +68 -0
  54. spriteforge/game/__init__.py +0 -0
  55. spriteforge/game/actors.py +377 -0
  56. spriteforge/game/agent_tools.py +178 -0
  57. spriteforge/game/art.py +2097 -0
  58. spriteforge/game/art_checks.py +190 -0
  59. spriteforge/game/art_review.py +518 -0
  60. spriteforge/game/build.py +134 -0
  61. spriteforge/game/bundle.py +1178 -0
  62. spriteforge/game/cli.py +119 -0
  63. spriteforge/game/codegen.py +433 -0
  64. spriteforge/game/codeinfo.py +154 -0
  65. spriteforge/game/dbsource.py +137 -0
  66. spriteforge/game/design.py +342 -0
  67. spriteforge/game/export.py +62 -0
  68. spriteforge/game/gamedb.py +191 -0
  69. spriteforge/game/image_cache.py +61 -0
  70. spriteforge/game/lessons.py +259 -0
  71. spriteforge/game/level_gen.py +118 -0
  72. spriteforge/game/level_preview.py +97 -0
  73. spriteforge/game/levels.py +934 -0
  74. spriteforge/game/loops.py +38 -0
  75. spriteforge/game/menus.py +712 -0
  76. spriteforge/game/mock_game.js +109 -0
  77. spriteforge/game/mock_platformer.js +58 -0
  78. spriteforge/game/motion.py +881 -0
  79. spriteforge/game/pipeline.py +1768 -0
  80. spriteforge/game/plan.py +502 -0
  81. spriteforge/game/playtest.py +318 -0
  82. spriteforge/game/qa.py +664 -0
  83. spriteforge/game/qa_checks.py +223 -0
  84. spriteforge/game/qa_runtime.py +565 -0
  85. spriteforge/game/reach.py +807 -0
  86. spriteforge/game/record.py +138 -0
  87. spriteforge/game/research.py +262 -0
  88. spriteforge/game/revision.py +225 -0
  89. spriteforge/game/sdk/API.md +104 -0
  90. spriteforge/game/sdk/FLOW.md +19 -0
  91. spriteforge/game/sdk/LEVELS.md +65 -0
  92. spriteforge/game/sdk/sf.js +418 -0
  93. spriteforge/game/sdk/sfflow.js +442 -0
  94. spriteforge/game/sdk/sflevel.js +683 -0
  95. spriteforge/game/sdk/sfsound-editor.js +225 -0
  96. spriteforge/game/sdk/sfsound.js +260 -0
  97. spriteforge/game/sdk/sounds.html +67 -0
  98. spriteforge/game/sounds.py +793 -0
  99. spriteforge/game/story.py +188 -0
  100. spriteforge/game/structure.py +98 -0
  101. spriteforge/game/team_reports.py +394 -0
  102. spriteforge/game/tilesets.py +70 -0
  103. spriteforge/game/title_art.py +186 -0
  104. spriteforge/genres/__init__.py +0 -0
  105. spriteforge/library/__init__.py +15 -0
  106. spriteforge/library/cli.py +126 -0
  107. spriteforge/library/describe.py +242 -0
  108. spriteforge/library/looks.py +154 -0
  109. spriteforge/library/models.py +79 -0
  110. spriteforge/library/store.py +422 -0
  111. spriteforge/library/tilesets/README.md +32 -0
  112. spriteforge/library/tilesets/gandalf-seasons.json +111 -0
  113. spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
  114. spriteforge/mcp/__init__.py +0 -0
  115. spriteforge/mcp/cli.py +58 -0
  116. spriteforge/mcp/client.py +57 -0
  117. spriteforge/mcp/filesystem_read.py +32 -0
  118. spriteforge/mcp/gamedb.py +56 -0
  119. spriteforge/mcp/library.py +179 -0
  120. spriteforge/mcp/memory.py +37 -0
  121. spriteforge/mcp/pixel_tools.py +145 -0
  122. spriteforge/mcp/registry.py +145 -0
  123. spriteforge/mcp/service.py +224 -0
  124. spriteforge/mcp/templates/context7.json +6 -0
  125. spriteforge/mcp/templates/fetch.json +6 -0
  126. spriteforge/mcp/templates/filesystem-read.json +6 -0
  127. spriteforge/mcp/templates/pixel-tools.json +6 -0
  128. spriteforge/memory/README.md +10 -0
  129. spriteforge/memory/__init__.py +0 -0
  130. spriteforge/memory/cli.py +131 -0
  131. spriteforge/memory/okf/__init__.py +1 -0
  132. spriteforge/memory/okf/catalog.py +331 -0
  133. spriteforge/memory/okf/codec.py +63 -0
  134. spriteforge/memory/okf/git.py +104 -0
  135. spriteforge/memory/okf/indexes.py +50 -0
  136. spriteforge/memory/okf/models.py +114 -0
  137. spriteforge/memory/okf/search.py +53 -0
  138. spriteforge/memory/okf/seed.py +81 -0
  139. spriteforge/memory/okf/seeds/genres.yaml +121 -0
  140. spriteforge/memory/okf/seeds/other.yaml +150 -0
  141. spriteforge/memory/okf/store.py +402 -0
  142. spriteforge/memory/okf/validate.py +115 -0
  143. spriteforge/pixel/__init__.py +17 -0
  144. spriteforge/pixel/atlas.py +110 -0
  145. spriteforge/pixel/grid.py +174 -0
  146. spriteforge/pixel/palette.py +156 -0
  147. spriteforge/pixel/palettes/dungeon.json +9 -0
  148. spriteforge/pixel/postprocess.py +170 -0
  149. spriteforge/pixel/preview.py +40 -0
  150. spriteforge/pixel/schemas.py +139 -0
  151. spriteforge/pixel/source.py +237 -0
  152. spriteforge/pixel/terrain.py +48 -0
  153. spriteforge/pixel/validate.py +138 -0
  154. spriteforge/prompts/anim_frame.txt +1 -0
  155. spriteforge/prompts/character.txt +1 -0
  156. spriteforge/prompts/item.txt +1 -0
  157. spriteforge/prompts/tile.txt +1 -0
  158. spriteforge/prompts/ui.txt +1 -0
  159. spriteforge/providers/__init__.py +0 -0
  160. spriteforge/providers/base.py +97 -0
  161. spriteforge/providers/http.py +38 -0
  162. spriteforge/providers/mock.py +111 -0
  163. spriteforge/providers/muse_image.py +60 -0
  164. spriteforge/providers/muse_search.py +91 -0
  165. spriteforge/providers/muse_spark.py +66 -0
  166. spriteforge/skills/__init__.py +0 -0
  167. spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
  168. spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
  169. spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
  170. spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
  171. spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
  172. spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
  173. spriteforge/skills/builtin/level-design/SKILL.md +169 -0
  174. spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
  175. spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
  176. spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
  177. spriteforge/skills/builtin/platformer/SKILL.md +153 -0
  178. spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
  179. spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
  180. spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
  181. spriteforge/skills/catalog.py +200 -0
  182. spriteforge/skills/cli.py +41 -0
  183. spriteforge/stages/__init__.py +0 -0
  184. spriteforge/stages/asset_context.py +301 -0
  185. spriteforge/stages/asset_models.py +192 -0
  186. spriteforge/stages/asset_render.py +366 -0
  187. spriteforge/stages/asset_review.py +140 -0
  188. spriteforge/stages/asset_store.py +94 -0
  189. spriteforge/stages/chat_changes.py +236 -0
  190. spriteforge/stages/concept.py +42 -0
  191. spriteforge/stages/game.py +1699 -0
  192. spriteforge/stages/game_confirm.py +112 -0
  193. spriteforge/stages/game_final.py +220 -0
  194. spriteforge/stages/game_record.py +246 -0
  195. spriteforge/stages/gameplay.py +218 -0
  196. spriteforge/stages/intake.py +372 -0
  197. spriteforge/stages/preview_assets.py +212 -0
  198. spriteforge/stages/preview_models.py +167 -0
  199. spriteforge/stages/preview_render.py +169 -0
  200. spriteforge/stages/preview_repair.py +61 -0
  201. spriteforge/stages/preview_review.py +169 -0
  202. spriteforge/stages/production.py +170 -0
  203. spriteforge/stages/references.py +105 -0
  204. spriteforge/stages/rewind.py +128 -0
  205. spriteforge/stages/workflow.py +440 -0
  206. spriteforge/templates/phaser/audit.js +45 -0
  207. spriteforge/templates/phaser/font.png +0 -0
  208. spriteforge/templates/phaser/font.xml +1 -0
  209. spriteforge/templates/phaser/preview.html +9 -0
  210. spriteforge/templates/phaser/room.js +49 -0
  211. spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
  212. spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
  213. spriteforge-0.1.1.dist-info/METADATA +364 -0
  214. spriteforge-0.1.1.dist-info/RECORD +218 -0
  215. spriteforge-0.1.1.dist-info/WHEEL +5 -0
  216. spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
  217. spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
  218. spriteforge-0.1.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,402 @@
1
+ """Filesystem OKF corpus with Git write batches and bounded, event-logged retrieval."""
2
+
3
+ import hashlib
4
+ import re
5
+ from collections.abc import Callable
6
+ from datetime import UTC, datetime
7
+ from pathlib import Path, PurePosixPath
8
+
9
+ import yaml
10
+ from pydantic import ValidationError
11
+
12
+ from spriteforge.config import MemoryConfig, load_config
13
+ from spriteforge.core.state import Store as EventStore
14
+
15
+ from . import git
16
+ from .codec import check_id, ensure_no_secrets, parse, serialize
17
+ from .indexes import indexes
18
+ from .models import Entry, Metadata, Snippet
19
+ from .search import rank, sentence_excerpt, token_cost
20
+
21
+ CATEGORIES = {
22
+ "genres",
23
+ "art-styles",
24
+ "engine-patterns",
25
+ "prompt-patterns",
26
+ "lessons",
27
+ "builds",
28
+ "user-prefs",
29
+ "catalog", # asset packs, tile sets and actors mirrored by `memory sync-catalog`
30
+ }
31
+ # Files a corpus may hold next to its entries (a game database's images, code and tests).
32
+ RESOURCE_SUFFIXES = {".png"}
33
+ # Resource files that are text: secret-checked like the entries before they are written.
34
+ TEXT_SUFFIXES = {".js", ".py", ".json", ".txt"}
35
+
36
+
37
+ def check_resource(name: str, suffixes: set[str] = RESOURCE_SUFFIXES) -> str:
38
+ path = PurePosixPath(name)
39
+ if (
40
+ not name
41
+ or "\\" in name
42
+ or path.is_absolute()
43
+ or str(path) != name
44
+ or any(p in {".", ".."} or p.startswith(".") for p in path.parts)
45
+ or path.suffix.lower() not in suffixes
46
+ or path.suffix.lower() == ".md"
47
+ ):
48
+ allowed = ", ".join(sorted(suffixes))
49
+ raise ValueError(f"Resource must be a safe relative path ({allowed}): {name!r}")
50
+ return name
51
+
52
+
53
+ class KnowledgeStore:
54
+ def __init__(
55
+ self,
56
+ root: Path,
57
+ events: EventStore | None = None,
58
+ run_id: str | None = None,
59
+ categories: set[str] | None = None,
60
+ *,
61
+ bundle: bool = False,
62
+ resources: set[str] | None = None,
63
+ title: str = "SpriteForge knowledge",
64
+ ):
65
+ """`categories`: the top-level folders indexes always list (a game database has its
66
+ own: design, entities, ...). `bundle`: a self-contained OKF bundle (a game's record):
67
+ indexes link absolutely (`/entities/hero.md`), and validation requires every link to
68
+ be absolute and to resolve and every `resource` path to exist. `resources`: the file
69
+ types `write_batch` may write next to the entries (default: .png)."""
70
+ self.root = root.expanduser().resolve()
71
+ self.categories = set(CATEGORIES if categories is None else categories)
72
+ self.bundle = bundle
73
+ self.title = title # the root index's heading
74
+ self.resources = set(RESOURCE_SUFFIXES if resources is None else resources)
75
+ git.init(self.root)
76
+ self.events = events or EventStore(self.root.parent / "state.sqlite3")
77
+ if run_id is None:
78
+ prior = [
79
+ r
80
+ for r in self.events.runs()
81
+ if r.config.get("workflow") == "memory-audit"
82
+ and r.config.get("corpus") == str(self.root)
83
+ ]
84
+ run_id = (
85
+ prior[0].id
86
+ if prior
87
+ else self.events.create_run(
88
+ {"workflow": "memory-audit", "corpus": str(self.root)}
89
+ ).id
90
+ )
91
+ self.run_id = run_id
92
+
93
+ def path(self, ident: str) -> Path:
94
+ check_id(ident)
95
+ path = (self.root / (ident + ".md")).resolve()
96
+ if not path.is_relative_to(self.root) or any(
97
+ p.startswith(".") for p in path.relative_to(self.root).parts
98
+ ):
99
+ raise ValueError("Concept path escapes corpus")
100
+ return path
101
+
102
+ def scan(self) -> tuple[list[Entry], list[str]]:
103
+ entries, errors = [], []
104
+ for path in sorted(self.root.rglob("*.md")):
105
+ relative = path.relative_to(self.root)
106
+ if any(part.startswith(".") for part in relative.parts) or path.name in {
107
+ "index.md",
108
+ "log.md",
109
+ }:
110
+ continue
111
+ try:
112
+ if not path.resolve().is_relative_to(self.root):
113
+ raise ValueError("External symlink")
114
+ entries.append(
115
+ parse(path.read_text(encoding="utf-8"), relative.with_suffix("").as_posix())
116
+ )
117
+ except (ValueError, OSError, ValidationError, yaml.YAMLError):
118
+ errors.append(f"{relative.as_posix()}: invalid or unsafe concept; inspect locally")
119
+ return entries, errors
120
+
121
+ def _log(self, level: str, query: str, scopes: list[str], results: list[dict]) -> None:
122
+ self.events.append_event(
123
+ self.run_id,
124
+ "Librarian",
125
+ "memory.retrieved",
126
+ {
127
+ "level": level,
128
+ "query_hash": hashlib.sha256(query.encode()).hexdigest(),
129
+ "scopes": scopes,
130
+ "results": results,
131
+ },
132
+ )
133
+
134
+ @staticmethod
135
+ def permitted(entry: Entry, scopes: list[str]) -> bool:
136
+ return ("private" if entry.private else "project") in scopes
137
+
138
+ def retrieve(
139
+ self,
140
+ query: str,
141
+ scopes: list[str] | None = None,
142
+ token_budget: int = 1024,
143
+ *,
144
+ min_score: float | None = None,
145
+ relative_score: float | None = None,
146
+ only: Callable[[Entry], bool] | None = None,
147
+ ) -> list[Snippet]:
148
+ """`only`: the entries that may be found (e.g. human-reviewed lessons)."""
149
+ scopes = ["project"] if scopes is None else scopes
150
+ if set(scopes) - {"project", "private"} or token_budget < 0:
151
+ raise ValueError("Invalid scopes or token budget")
152
+ ensure_no_secrets(query)
153
+ entries, _ = (
154
+ self.scan()
155
+ ) # Refresh on every request: drop-in genre files need no code changes.
156
+ candidates = [entry for entry in entries
157
+ if self.permitted(entry, scopes) and (only is None or only(entry))] # fmt: skip
158
+ snippets = []
159
+ remaining = token_budget
160
+ defaults = load_config().memory
161
+ cutoff = MemoryConfig(
162
+ min_score=defaults.min_score if min_score is None else min_score,
163
+ relative_score=defaults.relative_score if relative_score is None else relative_score,
164
+ )
165
+ ranked = rank(query, candidates)
166
+ threshold = max(cutoff.min_score, ranked[0][1] * cutoff.relative_score) if ranked else 0
167
+ for entry, score in ranked:
168
+ if score < threshold:
169
+ continue
170
+ header = f"[{entry.metadata.trust_tier}] {entry.id} {entry.title}\n"
171
+ summary = entry.metadata.description or entry.body.strip().split("\n", 1)[0]
172
+ # Pick a matching body sentence after the summary, never dump the whole entry.
173
+ sentences = re.split(r"(?<=[.!?])\s+|\n", entry.body)
174
+ query_terms = set(re.findall(r"\w+", query.casefold()))
175
+ matched = max(
176
+ sentences,
177
+ key=lambda text: len(query_terms & set(re.findall(r"\w+", text.casefold()))),
178
+ default="",
179
+ )
180
+ text = summary + ("\n" + matched if matched and matched != summary else "")
181
+ allowance = remaining - token_cost(header)
182
+ if allowance <= 0:
183
+ continue
184
+ text = sentence_excerpt(text, allowance)
185
+ if not text:
186
+ continue
187
+ cost = token_cost(header + text)
188
+ snippets.append(
189
+ Snippet(
190
+ id=entry.id,
191
+ title=entry.title,
192
+ trust_tier=entry.metadata.trust_tier,
193
+ stale=entry.metadata.stale,
194
+ status=entry.metadata.status,
195
+ scope="private" if entry.private else "project",
196
+ bootstrap_unreviewed=(
197
+ entry.metadata.model_extra.get("x-spriteforge-review") == "unreviewed"
198
+ ),
199
+ score=score,
200
+ text=text,
201
+ tokens=cost,
202
+ )
203
+ )
204
+ remaining -= cost
205
+ if remaining <= 0:
206
+ break
207
+ self._log(
208
+ "snippets", query, scopes, [s.model_dump(exclude={"title", "text"}) for s in snippets]
209
+ )
210
+ return snippets
211
+
212
+ def show(self, ident: str, scopes: list[str] | None = None) -> Entry:
213
+ scopes = ["project"] if scopes is None else scopes
214
+ entry = parse(self.path(ident).read_text(encoding="utf-8"), ident)
215
+ if not self.permitted(entry, scopes):
216
+ raise PermissionError("Private memory requires explicit private scope")
217
+ self._log(
218
+ "full-entry", ident, scopes, [{"id": entry.id, "trust_tier": entry.metadata.trust_tier}]
219
+ )
220
+ return entry
221
+
222
+ def index(self, directory: str = "", scopes: list[str] | None = None) -> str:
223
+ scopes = ["project"] if scopes is None else scopes
224
+ if directory:
225
+ check_id(directory + "/_entry")
226
+ entries, _ = self.scan()
227
+ visible = [e for e in entries if self.permitted(e, scopes)]
228
+ dirs = self.categories - ({"user-prefs"} if "private" not in scopes else set())
229
+ text = indexes(visible, dirs, absolute=self.bundle, title=self.title).get(
230
+ (directory + "/" if directory else "") + "index.md", ""
231
+ )
232
+ self._log("index", directory, scopes, [])
233
+ return text
234
+
235
+ def write_batch(
236
+ self,
237
+ entries: list[Entry],
238
+ message: str,
239
+ *,
240
+ actor: str = "spriteforge/0.1",
241
+ verified_by: str | None = None,
242
+ preserve_generation: bool = False,
243
+ files: dict[str, bytes] | None = None,
244
+ ) -> None:
245
+ """Write entries (and `files`, binary resources such as images, by relative path) in one
246
+ validated git commit; on any failure nothing changes."""
247
+ with git.write_lock(self.root.parent / ".memory.lock"), git.rollback_git(self.root):
248
+ self._write_batch(
249
+ entries,
250
+ message,
251
+ actor=actor,
252
+ verified_by=verified_by,
253
+ preserve_generation=preserve_generation,
254
+ files=files or {},
255
+ )
256
+
257
+ def _write_batch(
258
+ self,
259
+ entries: list[Entry],
260
+ message: str,
261
+ *,
262
+ actor: str,
263
+ verified_by: str | None,
264
+ preserve_generation: bool,
265
+ files: dict[str, bytes],
266
+ ) -> None:
267
+ ensure_no_secrets(message)
268
+ for name, data in files.items():
269
+ check_resource(name, self.resources)
270
+ if PurePosixPath(name).suffix.lower() in TEXT_SUFFIXES:
271
+ ensure_no_secrets(data.decode("utf-8"))
272
+ if verified_by is not None and not verified_by.startswith("human:"):
273
+ raise ValueError("Human promotion requires a human: verifier")
274
+ existing, errors = self.scan()
275
+ if errors:
276
+ raise ValueError("Corpus contains invalid concepts; validate before writing")
277
+ current = {entry.id: entry for entry in existing}
278
+ if len({e.id for e in entries}) != len(entries):
279
+ raise ValueError("Duplicate IDs in batch")
280
+ now = datetime.now(UTC).isoformat()
281
+ planned = {}
282
+ for entry in entries:
283
+ self.path(entry.id) # Validate every target before touching any file.
284
+ self.retrieve(entry.title, ["project", "private"], 128) # Search-before-write.
285
+ metadata = (
286
+ current[entry.id].metadata.model_dump(
287
+ mode="json", by_alias=True, exclude_unset=True
288
+ )
289
+ if entry.id in current
290
+ else {}
291
+ )
292
+ if self.bundle: # a bundle's concepts are written whole: a field left out is gone
293
+ metadata = {k: v for k, v in metadata.items() if k == "generated"}
294
+ metadata.update(
295
+ entry.metadata.model_dump(mode="json", by_alias=True, exclude_unset=True)
296
+ )
297
+ if not preserve_generation or "generated" not in metadata:
298
+ metadata["generated"] = {"by": actor, "at": now}
299
+ metadata["verified"] = [{"by": verified_by, "at": now}] if verified_by else []
300
+ if verified_by and metadata.get("x-spriteforge-review") == "unreviewed":
301
+ metadata["verified"][0]["x-spriteforge-designation"] = "bootstrap"
302
+ if entry.private:
303
+ metadata["x-spriteforge-scope"] = "private"
304
+ replacement = Entry(
305
+ id=entry.id, metadata=Metadata.model_validate(metadata), body=entry.body
306
+ )
307
+ planned[entry.id + ".md"] = serialize(replacement)
308
+ current[entry.id] = replacement
309
+ planned.update(
310
+ indexes(list(current.values()), self.categories, absolute=self.bundle, title=self.title)
311
+ )
312
+ old_log = (
313
+ (self.root / "log.md").read_text(encoding="utf-8")
314
+ if (self.root / "log.md").exists()
315
+ else ""
316
+ )
317
+ planned["log.md"] = (
318
+ f"# Knowledge update log\n\n## {now[:10]}\n* {message}\n\n"
319
+ + old_log.removeprefix("# Knowledge update log\n\n")
320
+ )
321
+ planned[".gitignore"] = ".env*\n*.sqlite3*\n__pycache__/\n"
322
+ for content in planned.values():
323
+ ensure_no_secrets(content)
324
+ if any(
325
+ not (self.root / name).resolve().is_relative_to(self.root)
326
+ for name in [*planned, *files]
327
+ ):
328
+ raise ValueError("Write target escapes corpus")
329
+ backups = {
330
+ name: (self.root / name).read_bytes() if (self.root / name).exists() else None
331
+ for name in [*planned, *files]
332
+ }
333
+ try:
334
+ for name, content in planned.items():
335
+ target = self.root / name
336
+ if not target.resolve().is_relative_to(self.root):
337
+ raise ValueError("Index path escapes corpus")
338
+ target.parent.mkdir(parents=True, exist_ok=True)
339
+ target.write_text(content, encoding="utf-8")
340
+ for name, data in files.items():
341
+ target = self.root / name
342
+ target.parent.mkdir(parents=True, exist_ok=True)
343
+ target.write_bytes(data)
344
+ from .validate import validate
345
+
346
+ if validate(self).errors:
347
+ raise ValueError("Write batch failed corpus validation")
348
+ git.commit(self.root, [*planned, *files], message)
349
+ except BaseException:
350
+ for name, content in backups.items():
351
+ target = self.root / name
352
+ if content is None:
353
+ target.unlink(missing_ok=True)
354
+ else:
355
+ target.write_bytes(content)
356
+ raise
357
+
358
+ def promote(self, ident: str, human: str) -> None:
359
+ if not human.startswith("human:"):
360
+ raise ValueError("Verifier must use human:<id>")
361
+ entry = self.show(ident, ["project", "private"])
362
+ self.write_batch(
363
+ [entry],
364
+ f"Human verification: {ident}",
365
+ actor=entry.metadata.generated.by if entry.metadata.generated else "spriteforge/0.1",
366
+ verified_by=human,
367
+ preserve_generation=True,
368
+ )
369
+
370
+ def review(self, ident: str) -> None:
371
+ entry = self.show(ident, ["project", "private"])
372
+ if entry.metadata.model_extra.get("x-spriteforge-review") != "unreviewed":
373
+ raise ValueError("Entry is not awaiting bootstrap review")
374
+ entry.metadata.model_extra["x-spriteforge-review"] = "reviewed"
375
+ entry.metadata.model_extra["x-spriteforge-reviewed-at"] = datetime.now(UTC).isoformat()
376
+ self.write_batch(
377
+ [entry],
378
+ f"Review bootstrap entry: {ident}",
379
+ verified_by="human:project-owner",
380
+ preserve_generation=True,
381
+ )
382
+
383
+ def export_public(self, destination: Path) -> None:
384
+ destination = destination.resolve()
385
+ if destination.is_relative_to(self.root) or self.root.is_relative_to(destination):
386
+ raise ValueError("Export must be separate from the corpus")
387
+ if destination.exists() and any(destination.iterdir()):
388
+ raise ValueError("Export destination must be empty")
389
+ entries, errors = self.scan()
390
+ if errors:
391
+ raise ValueError("Validate corpus before export")
392
+ public = [entry for entry in entries if not entry.private]
393
+ files = {entry.id + ".md": serialize(entry) for entry in public}
394
+ files.update(
395
+ indexes(
396
+ public, self.categories - {"user-prefs"}, absolute=self.bundle, title=self.title
397
+ )
398
+ )
399
+ for name, content in files.items():
400
+ target = destination / name
401
+ target.parent.mkdir(parents=True, exist_ok=True)
402
+ target.write_text(content, encoding="utf-8")
@@ -0,0 +1,115 @@
1
+ import re
2
+ import shutil
3
+ import subprocess
4
+ from datetime import date
5
+ from pathlib import PurePosixPath
6
+
7
+ import yaml
8
+
9
+ from spriteforge.core.security import redact
10
+
11
+ from .codec import ensure_no_secrets
12
+ from .models import ValidationReport
13
+ from .store import KnowledgeStore
14
+
15
+
16
+ def validate(store: KnowledgeStore, external: bool = True) -> ValidationReport:
17
+ entries, errors = store.scan()
18
+ report = ValidationReport(errors=errors)
19
+ for entry in entries:
20
+ if entry.metadata.stale:
21
+ report.warnings.append(f"{entry.id}: stale since {entry.metadata.stale_after}")
22
+ if entry.metadata.type == "Attested Computation" and not (
23
+ entry.metadata.model_extra or {}
24
+ ).get("runtime"):
25
+ report.warnings.append(f"{entry.id}: Attested Computation should declare runtime")
26
+ for path in store.root.rglob("*.md"):
27
+ if any(part.startswith(".") for part in path.relative_to(store.root).parts):
28
+ continue
29
+ if path.name not in {"index.md", "log.md"}:
30
+ continue
31
+ text = path.read_text(encoding="utf-8")
32
+ try:
33
+ ensure_no_secrets(text)
34
+ body = text
35
+ if text.startswith("---\n"):
36
+ match = re.match(r"---\n(.*?)\n---\n", text, re.DOTALL)
37
+ if not match or path != store.root / "index.md":
38
+ raise ValueError("Only root index may carry version frontmatter")
39
+ data = yaml.safe_load(match[1])
40
+ if not isinstance(data, dict) or set(data) != {"okf_version"}:
41
+ raise ValueError("Only okf_version is defined on root index")
42
+ body = text[match.end() :]
43
+ if not re.search(r"^#{1,6} .+", body, re.MULTILINE):
44
+ raise ValueError("Reserved file must have a section heading")
45
+ if path.name == "log.md":
46
+ headings = re.findall(r"^## (.+)$", text, re.MULTILINE)
47
+ if any(not re.fullmatch(r"\d{4}-\d{2}-\d{2}", heading) for heading in headings):
48
+ raise ValueError("Log date headings must be YYYY-MM-DD")
49
+ for heading in headings:
50
+ date.fromisoformat(heading)
51
+ except (ValueError, yaml.YAMLError):
52
+ report.errors.append(f"{path.relative_to(store.root)}: invalid reserved-file structure")
53
+ if store.bundle:
54
+ report.errors += bundle_problems(store, entries)
55
+ command = external_validator(store.root) if external else None
56
+ if command:
57
+ result = subprocess.run(command, check=False, capture_output=True, text=True, timeout=60)
58
+ report.external = (
59
+ redact(result.stdout + result.stderr).strip() or f"exit {result.returncode}"
60
+ )
61
+ if result.returncode:
62
+ report.errors.append("External okf validate failed")
63
+ return report
64
+
65
+
66
+ # Markdown links and images: [text](target) / ![alt](target). Code spans are left out first.
67
+ LINK = re.compile(r"!?\[[^\]]*\]\(([^)\s]+)\)")
68
+ EXTERNAL = re.compile(r"^(?:[a-z][a-z0-9+.-]*:|#)", re.IGNORECASE)
69
+
70
+
71
+ def links(text: str) -> list[str]:
72
+ text = re.sub(r"```.*?```", " ", text, flags=re.DOTALL)
73
+ return LINK.findall(re.sub(r"`[^`\n]*`", " ", text))
74
+
75
+
76
+ def resolves(store: KnowledgeStore, target: str) -> bool:
77
+ path = PurePosixPath(target.split("#", 1)[0])
78
+ if any(p in {".", ".."} for p in path.parts):
79
+ return False
80
+ file = (store.root / str(path).lstrip("/")).resolve()
81
+ return file.is_relative_to(store.root) and file.is_file()
82
+
83
+
84
+ def bundle_problems(store: KnowledgeStore, entries) -> list[str]:
85
+ """A self-contained bundle (a game's record): every link in concepts and indexes is
86
+ absolute (`/entities/hero.md`) and resolves; every `resource` path exists."""
87
+ problems = []
88
+ texts = {f"{e.id}.md": e.body for e in entries}
89
+ for path in store.root.rglob("index.md"):
90
+ relative = path.relative_to(store.root)
91
+ if not any(part.startswith(".") for part in relative.parts):
92
+ texts[relative.as_posix()] = path.read_text(encoding="utf-8")
93
+ for name, text in sorted(texts.items()):
94
+ for target in links(text):
95
+ if EXTERNAL.match(target):
96
+ continue
97
+ if not target.startswith("/"):
98
+ problems.append(f"{name}: link {target} is not absolute")
99
+ elif not resolves(store, target):
100
+ problems.append(f"{name}: link {target} does not resolve")
101
+ for e in entries:
102
+ resource = e.metadata.resource
103
+ if resource and not EXTERNAL.match(resource) and not resolves(store, resource):
104
+ problems.append(f"{e.id}: resource {resource} does not exist")
105
+ return problems
106
+
107
+
108
+ def external_validator(root) -> list[str] | None:
109
+ """The command of an installed external OKF validator: `okf validate <dir>`, or okflib's
110
+ `okflib -C <dir> validate` (PyPI `okflib`); None when neither is installed."""
111
+ if binary := shutil.which("okf"):
112
+ return [binary, "validate", str(root)]
113
+ if binary := shutil.which("okflib"):
114
+ return [binary, "-C", str(root), "validate"]
115
+ return None
@@ -0,0 +1,17 @@
1
+ """Deterministic pixel-art processing. No provider or network dependencies."""
2
+
3
+ from .postprocess import postprocess
4
+ from .schemas import AssetSpec, Failure, Palette, ProcessingOptions, ProcessingReport, Style
5
+ from .validate import validate, validate_animation
6
+
7
+ __all__ = [
8
+ "AssetSpec",
9
+ "Failure",
10
+ "Palette",
11
+ "ProcessingOptions",
12
+ "ProcessingReport",
13
+ "Style",
14
+ "postprocess",
15
+ "validate",
16
+ "validate_animation",
17
+ ]
@@ -0,0 +1,110 @@
1
+ """Deterministic shelf packing; frame keys are preserved verbatim for Phaser."""
2
+
3
+ import json
4
+ import math
5
+ from collections.abc import Mapping, Sequence
6
+ from pathlib import Path
7
+
8
+ from PIL import Image
9
+ from pydantic import Field
10
+
11
+ from .schemas import Schema
12
+
13
+
14
+ class Rect(Schema):
15
+ x: int
16
+ y: int
17
+ w: int
18
+ h: int
19
+
20
+
21
+ class Size(Schema):
22
+ w: int
23
+ h: int
24
+
25
+
26
+ class AtlasFrame(Schema):
27
+ frame: Rect
28
+ rotated: bool = False
29
+ trimmed: bool = False
30
+ spriteSourceSize: Rect
31
+ sourceSize: Size
32
+
33
+
34
+ class AtlasMeta(Schema):
35
+ app: str = "SpriteForge"
36
+ version: str = "1"
37
+ image: str = "atlas.png"
38
+ format: str = "RGBA8888"
39
+ size: Size
40
+ scale: str = "1"
41
+ # Phaser ignores this metadata; use it to create scene.anims frame sequences.
42
+ animations: dict[str, list[str]] = Field(default_factory=dict)
43
+
44
+
45
+ class Atlas(Schema):
46
+ frames: dict[str, AtlasFrame]
47
+ meta: AtlasMeta
48
+
49
+
50
+ def pack(
51
+ sprites: Mapping[str, Image.Image],
52
+ output_dir: Path,
53
+ *,
54
+ animations: Mapping[str, Sequence[str]] | None = None,
55
+ padding: int = 1,
56
+ max_size: int = 2048,
57
+ ) -> Atlas:
58
+ if not sprites:
59
+ raise ValueError("Cannot pack an empty atlas")
60
+ if {"__BASE", "hasOwnProperty"} & sprites.keys():
61
+ raise ValueError("Frame name is reserved by the Phaser JSON-hash parser")
62
+ if padding < 0 or max_size < 1 or any(not key for key in sprites):
63
+ raise ValueError("Invalid padding, maximum size, or empty frame key")
64
+ animation_map = {name: list(keys) for name, keys in (animations or {}).items()}
65
+ for name, keys in animation_map.items():
66
+ if not name or not keys or any(key not in sprites for key in keys):
67
+ raise ValueError(f"Animation {name!r} must reference existing atlas frames")
68
+ ordered = sorted(sprites, key=lambda key: (-sprites[key].height, -sprites[key].width, key))
69
+ largest = max(img.width + 2 * padding for img in sprites.values())
70
+ if largest > max_size or any(img.height + 2 * padding > max_size for img in sprites.values()):
71
+ raise ValueError("A sprite exceeds max_size including padding")
72
+ area = sum((img.width + 2 * padding) * (img.height + 2 * padding) for img in sprites.values())
73
+ width = min(max_size, max(largest, math.ceil(math.sqrt(area))))
74
+ while True:
75
+ x = y = row_height = 0
76
+ placed = {}
77
+ for key in ordered:
78
+ img = sprites[key]
79
+ w, h = img.width + 2 * padding, img.height + 2 * padding
80
+ if x + w > width:
81
+ x, y, row_height = 0, y + row_height, 0
82
+ placed[key] = (x + padding, y + padding)
83
+ x += w
84
+ row_height = max(row_height, h)
85
+ height = y + row_height
86
+ if height <= max_size:
87
+ break
88
+ if width == max_size:
89
+ raise ValueError("Sprites do not fit within max_size")
90
+ width = min(max_size, width * 2)
91
+ image = Image.new("RGBA", (width, height))
92
+ frames = {}
93
+ for key in sorted(sprites):
94
+ img = sprites[key].convert("RGBA")
95
+ x, y = placed[key]
96
+ image.paste(img, (x, y))
97
+ frames[key] = AtlasFrame(
98
+ frame=Rect(x=x, y=y, w=img.width, h=img.height),
99
+ spriteSourceSize=Rect(x=0, y=0, w=img.width, h=img.height),
100
+ sourceSize=Size(w=img.width, h=img.height),
101
+ )
102
+ atlas = Atlas(
103
+ frames=frames, meta=AtlasMeta(size=Size(w=width, h=height), animations=animation_map)
104
+ )
105
+ output_dir.mkdir(parents=True, exist_ok=True)
106
+ image.save(output_dir / "atlas.png")
107
+ (output_dir / "atlas.json").write_text(
108
+ json.dumps(atlas.model_dump(), indent=2) + "\n", encoding="utf-8"
109
+ )
110
+ return atlas