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.
- spriteforge/__init__.py +1 -0
- spriteforge/__main__.py +3 -0
- spriteforge/agents/__init__.py +0 -0
- spriteforge/agents/assets.py +109 -0
- spriteforge/agents/cancellation.py +12 -0
- spriteforge/agents/director.py +50 -0
- spriteforge/agents/models.py +63 -0
- spriteforge/agents/roles/art-director.md +15 -0
- spriteforge/agents/roles/art-reviewer.md +14 -0
- spriteforge/agents/roles/director.md +14 -0
- spriteforge/agents/roles/game-designer.md +15 -0
- spriteforge/agents/roles/level-tile-designer.md +16 -0
- spriteforge/agents/roles/librarian.md +13 -0
- spriteforge/agents/roles/menu-designer.md +15 -0
- spriteforge/agents/roles/pixel-artist.md +14 -0
- spriteforge/agents/roles/programmer.md +14 -0
- spriteforge/agents/roles/qa-playtester.md +13 -0
- spriteforge/agents/roles/sound-director.md +14 -0
- spriteforge/agents/roles.py +39 -0
- spriteforge/agents/router.py +233 -0
- spriteforge/agents/router_eval.py +145 -0
- spriteforge/agents/routing_state.py +133 -0
- spriteforge/agents/runtime.py +430 -0
- spriteforge/agents/workflow.py +389 -0
- spriteforge/app/__init__.py +0 -0
- spriteforge/app/agents_view.py +248 -0
- spriteforge/app/chat.py +114 -0
- spriteforge/app/extensions.py +115 -0
- spriteforge/app/index.html +279 -0
- spriteforge/app/local_only.py +49 -0
- spriteforge/app/server.py +358 -0
- spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
- spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
- spriteforge/app/static/index.html +13 -0
- spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
- spriteforge/app/studio.py +278 -0
- spriteforge/app/workers.py +73 -0
- spriteforge/cli.py +241 -0
- spriteforge/config.py +193 -0
- spriteforge/config.yaml +157 -0
- spriteforge/core/__init__.py +0 -0
- spriteforge/core/acting.py +16 -0
- spriteforge/core/cost.py +236 -0
- spriteforge/core/credentials.py +24 -0
- spriteforge/core/demo.py +79 -0
- spriteforge/core/forms.py +20 -0
- spriteforge/core/gates.py +175 -0
- spriteforge/core/security.py +42 -0
- spriteforge/core/state.py +222 -0
- spriteforge/core/team.py +15 -0
- spriteforge/core/usage.py +68 -0
- spriteforge/game/__init__.py +0 -0
- spriteforge/game/actors.py +377 -0
- spriteforge/game/agent_tools.py +178 -0
- spriteforge/game/art.py +2097 -0
- spriteforge/game/art_checks.py +190 -0
- spriteforge/game/art_review.py +518 -0
- spriteforge/game/build.py +134 -0
- spriteforge/game/bundle.py +1178 -0
- spriteforge/game/cli.py +119 -0
- spriteforge/game/codegen.py +433 -0
- spriteforge/game/codeinfo.py +154 -0
- spriteforge/game/dbsource.py +137 -0
- spriteforge/game/design.py +342 -0
- spriteforge/game/export.py +62 -0
- spriteforge/game/gamedb.py +191 -0
- spriteforge/game/image_cache.py +61 -0
- spriteforge/game/lessons.py +259 -0
- spriteforge/game/level_gen.py +118 -0
- spriteforge/game/level_preview.py +97 -0
- spriteforge/game/levels.py +934 -0
- spriteforge/game/loops.py +38 -0
- spriteforge/game/menus.py +712 -0
- spriteforge/game/mock_game.js +109 -0
- spriteforge/game/mock_platformer.js +58 -0
- spriteforge/game/motion.py +881 -0
- spriteforge/game/pipeline.py +1768 -0
- spriteforge/game/plan.py +502 -0
- spriteforge/game/playtest.py +318 -0
- spriteforge/game/qa.py +664 -0
- spriteforge/game/qa_checks.py +223 -0
- spriteforge/game/qa_runtime.py +565 -0
- spriteforge/game/reach.py +807 -0
- spriteforge/game/record.py +138 -0
- spriteforge/game/research.py +262 -0
- spriteforge/game/revision.py +225 -0
- spriteforge/game/sdk/API.md +104 -0
- spriteforge/game/sdk/FLOW.md +19 -0
- spriteforge/game/sdk/LEVELS.md +65 -0
- spriteforge/game/sdk/sf.js +418 -0
- spriteforge/game/sdk/sfflow.js +442 -0
- spriteforge/game/sdk/sflevel.js +683 -0
- spriteforge/game/sdk/sfsound-editor.js +225 -0
- spriteforge/game/sdk/sfsound.js +260 -0
- spriteforge/game/sdk/sounds.html +67 -0
- spriteforge/game/sounds.py +793 -0
- spriteforge/game/story.py +188 -0
- spriteforge/game/structure.py +98 -0
- spriteforge/game/team_reports.py +394 -0
- spriteforge/game/tilesets.py +70 -0
- spriteforge/game/title_art.py +186 -0
- spriteforge/genres/__init__.py +0 -0
- spriteforge/library/__init__.py +15 -0
- spriteforge/library/cli.py +126 -0
- spriteforge/library/describe.py +242 -0
- spriteforge/library/looks.py +154 -0
- spriteforge/library/models.py +79 -0
- spriteforge/library/store.py +422 -0
- spriteforge/library/tilesets/README.md +32 -0
- spriteforge/library/tilesets/gandalf-seasons.json +111 -0
- spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
- spriteforge/mcp/__init__.py +0 -0
- spriteforge/mcp/cli.py +58 -0
- spriteforge/mcp/client.py +57 -0
- spriteforge/mcp/filesystem_read.py +32 -0
- spriteforge/mcp/gamedb.py +56 -0
- spriteforge/mcp/library.py +179 -0
- spriteforge/mcp/memory.py +37 -0
- spriteforge/mcp/pixel_tools.py +145 -0
- spriteforge/mcp/registry.py +145 -0
- spriteforge/mcp/service.py +224 -0
- spriteforge/mcp/templates/context7.json +6 -0
- spriteforge/mcp/templates/fetch.json +6 -0
- spriteforge/mcp/templates/filesystem-read.json +6 -0
- spriteforge/mcp/templates/pixel-tools.json +6 -0
- spriteforge/memory/README.md +10 -0
- spriteforge/memory/__init__.py +0 -0
- spriteforge/memory/cli.py +131 -0
- spriteforge/memory/okf/__init__.py +1 -0
- spriteforge/memory/okf/catalog.py +331 -0
- spriteforge/memory/okf/codec.py +63 -0
- spriteforge/memory/okf/git.py +104 -0
- spriteforge/memory/okf/indexes.py +50 -0
- spriteforge/memory/okf/models.py +114 -0
- spriteforge/memory/okf/search.py +53 -0
- spriteforge/memory/okf/seed.py +81 -0
- spriteforge/memory/okf/seeds/genres.yaml +121 -0
- spriteforge/memory/okf/seeds/other.yaml +150 -0
- spriteforge/memory/okf/store.py +402 -0
- spriteforge/memory/okf/validate.py +115 -0
- spriteforge/pixel/__init__.py +17 -0
- spriteforge/pixel/atlas.py +110 -0
- spriteforge/pixel/grid.py +174 -0
- spriteforge/pixel/palette.py +156 -0
- spriteforge/pixel/palettes/dungeon.json +9 -0
- spriteforge/pixel/postprocess.py +170 -0
- spriteforge/pixel/preview.py +40 -0
- spriteforge/pixel/schemas.py +139 -0
- spriteforge/pixel/source.py +237 -0
- spriteforge/pixel/terrain.py +48 -0
- spriteforge/pixel/validate.py +138 -0
- spriteforge/prompts/anim_frame.txt +1 -0
- spriteforge/prompts/character.txt +1 -0
- spriteforge/prompts/item.txt +1 -0
- spriteforge/prompts/tile.txt +1 -0
- spriteforge/prompts/ui.txt +1 -0
- spriteforge/providers/__init__.py +0 -0
- spriteforge/providers/base.py +97 -0
- spriteforge/providers/http.py +38 -0
- spriteforge/providers/mock.py +111 -0
- spriteforge/providers/muse_image.py +60 -0
- spriteforge/providers/muse_search.py +91 -0
- spriteforge/providers/muse_spark.py +66 -0
- spriteforge/skills/__init__.py +0 -0
- spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
- spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
- spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
- spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
- spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
- spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
- spriteforge/skills/builtin/level-design/SKILL.md +169 -0
- spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
- spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
- spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
- spriteforge/skills/builtin/platformer/SKILL.md +153 -0
- spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
- spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
- spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
- spriteforge/skills/catalog.py +200 -0
- spriteforge/skills/cli.py +41 -0
- spriteforge/stages/__init__.py +0 -0
- spriteforge/stages/asset_context.py +301 -0
- spriteforge/stages/asset_models.py +192 -0
- spriteforge/stages/asset_render.py +366 -0
- spriteforge/stages/asset_review.py +140 -0
- spriteforge/stages/asset_store.py +94 -0
- spriteforge/stages/chat_changes.py +236 -0
- spriteforge/stages/concept.py +42 -0
- spriteforge/stages/game.py +1699 -0
- spriteforge/stages/game_confirm.py +112 -0
- spriteforge/stages/game_final.py +220 -0
- spriteforge/stages/game_record.py +246 -0
- spriteforge/stages/gameplay.py +218 -0
- spriteforge/stages/intake.py +372 -0
- spriteforge/stages/preview_assets.py +212 -0
- spriteforge/stages/preview_models.py +167 -0
- spriteforge/stages/preview_render.py +169 -0
- spriteforge/stages/preview_repair.py +61 -0
- spriteforge/stages/preview_review.py +169 -0
- spriteforge/stages/production.py +170 -0
- spriteforge/stages/references.py +105 -0
- spriteforge/stages/rewind.py +128 -0
- spriteforge/stages/workflow.py +440 -0
- spriteforge/templates/phaser/audit.js +45 -0
- spriteforge/templates/phaser/font.png +0 -0
- spriteforge/templates/phaser/font.xml +1 -0
- spriteforge/templates/phaser/preview.html +9 -0
- spriteforge/templates/phaser/room.js +49 -0
- spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
- spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
- spriteforge-0.1.1.dist-info/METADATA +364 -0
- spriteforge-0.1.1.dist-info/RECORD +218 -0
- spriteforge-0.1.1.dist-info/WHEEL +5 -0
- spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
- spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
- 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) / . 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
|