@seeed-studio/sensecraft-cli 0.4.1 → 0.4.3
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.
- package/package.json +1 -1
- package/skills/README.md +5 -1
- package/skills/sensecraft-cli/SKILL.md +5 -5
- package/skills/sensecraft-cli/create-app/SKILL.md +90 -83
- package/skills/sensecraft-cli/create-app/assets/manifest-template.json +5 -18
- package/skills/sensecraft-cli/create-app/assets/validate_manifest.py +244 -55
- package/skills/sensecraft-cli/create-app/references/content-review.md +55 -0
- package/skills/sensecraft-cli/create-app/references/manifest.md +118 -57
- package/skills/sensecraft-cli/create-app/references/project-discovery.md +56 -0
- package/skills/sensecraft-cli/references/app-commands.md +8 -4
- package/skills/sensecraft-cli/references/app-fields.md +37 -1
- package/skills/sensecraft-cli/references/apps.md +6 -4
- package/skills/sensecraft-cli/references/data-commands.md +6 -5
- package/skills/sensecraft-cli/references/recamera-commands.md +3 -1
- package/skills/sensecraft-cli/references/tool-blocks.md +31 -15
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
|
-
"""Validate a
|
|
2
|
+
"""Validate a CodeCraft Hub app manifest (create-app skill).
|
|
3
3
|
|
|
4
4
|
Mechanical checks only — structure, field limits, image constraints, BOM and
|
|
5
5
|
block shape. This validates FORMAT, never content truth: image content,
|
|
6
|
-
licensing, and factual accuracy remain the agent's job (see SKILL.md
|
|
7
|
-
|
|
6
|
+
licensing, and factual accuracy remain the agent's job (see SKILL.md and
|
|
7
|
+
references/content-review.md). A pass with pending inputs is not deployability.
|
|
8
8
|
|
|
9
9
|
Usage: python3 validate_manifest.py [manifest-path] [--scene-ids 1,5,...]
|
|
10
10
|
(both "--scene-ids 1,5" and "--scene-ids=1,5" work; a bare or
|
|
@@ -17,30 +17,80 @@ import json
|
|
|
17
17
|
import os
|
|
18
18
|
import re
|
|
19
19
|
import sys
|
|
20
|
+
from datetime import datetime
|
|
21
|
+
from urllib.parse import urlsplit
|
|
20
22
|
|
|
21
23
|
IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
|
|
22
24
|
IMAGE_MAX_BYTES = 5 * 1024 * 1024
|
|
23
25
|
IMAGES_MAX = 16
|
|
24
26
|
NAME_MAX = 60 # UTF-16 code units, Console-aligned
|
|
25
27
|
EXCERPT_MAX = 300 # UTF-16 code units
|
|
26
|
-
SCENE_RE = re.compile(r"
|
|
28
|
+
SCENE_RE = re.compile(r"^[0-9]+$")
|
|
29
|
+
TEXT_BLOCK_TYPES = {"step", "paragraph", "h1", "h2", "h3", "h4", "h5", "h6",
|
|
30
|
+
"bullet", "number", "todo", "quote", "code", "divider"}
|
|
31
|
+
# Modern deployment.blocks uses one config envelope for every tool. Keep these
|
|
32
|
+
# config-relative fields aligned with internal/service/app_tool_blocks.go.
|
|
33
|
+
TOOL_CONFIG_FIELDS = {
|
|
34
|
+
"flash-firmware": {"device_id", "device_type", "flash_mode", "firmware_url", "firmware_name", "firmware_size", "flash_address", "project_zip_url", "project_zip_name", "project_zip_size", "precheck_fields", "muse_gadget", "full_flash"},
|
|
35
|
+
"deploy-ai-model": {"model", "device_type", "powerMode", "conf", "iou", "threshold", "triggerAction", "deploy_tool_entry", "firmware_url"},
|
|
36
|
+
"ai-vibration": {"detectionType", "deviceType", "windowSize", "isPower", "gpio", "dStatus"},
|
|
37
|
+
"deploy-container-app": {"app_id", "app_key", "app_display_name", "app_icon", "app_description", "architecture", "architectures", "version", "version_options", "install_form", "merged_service", "user_override_flags", "form_field_values", "raw_by_version", "detail_form_fields"},
|
|
38
|
+
"node-red": {"flow_data_url", "flow_data", "model_id", "model_data"},
|
|
39
|
+
"aily-blockly": {"project_id", "device_id"},
|
|
40
|
+
}
|
|
41
|
+
FLASH_ADDRESSES = {"0x0", "0x4000", "0x10000", "0x90000"}
|
|
42
|
+
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
|
|
43
|
+
QUANTITY_RE = re.compile(r"^[1-9][0-9]*$")
|
|
27
44
|
# Shapes that must never appear in fields that get published. Matches
|
|
28
45
|
# credential VALUES (known prefixes, key=value assignments), never the mere
|
|
29
46
|
# words "token"/"password" — instructions about creating a token are legit.
|
|
30
47
|
SECRET_VALUE_RE = re.compile(
|
|
31
48
|
r"(mgst_[A-Za-z0-9_-]{6,}|sk-[A-Za-z0-9_-]{8,}|bearer\s+[A-Za-z0-9._-]{8,}"
|
|
32
|
-
r"|(
|
|
49
|
+
r"|(?:access[_-]?key|password|passwd|secret|api[_-]?key)\s*[:=]\s*\S{6,})",
|
|
50
|
+
re.IGNORECASE,
|
|
33
51
|
)
|
|
34
52
|
LONG_HEX_RE = re.compile(r"\b[0-9a-f]{40,}\b")
|
|
53
|
+
SECRET_FIELDS = {"access_key", "api_key", "password", "passwd", "secret",
|
|
54
|
+
"device_key", "sdk_token", "access_token", "refresh_token"}
|
|
55
|
+
INPUT_PLACEHOLDER_RE = re.compile(r"^(?:<[^>]+>|\$\{[^}]+\}|YOUR_[A-Z0-9_]+)$")
|
|
56
|
+
# Keep these aligned with rawMarkdownPatterns in internal/service/app_doc.go.
|
|
57
|
+
RAW_MARKDOWN_RE = re.compile(
|
|
58
|
+
r"\*\*[^*\n]+\*\*|__[^_\n]+__|~~[^~\n]+~~|`[^`\n]+`"
|
|
59
|
+
r"|^#{1,6}[ \t]|^[ \t]*[-*+][ \t]|^[ \t]*[0-9]+\.[ \t]",
|
|
60
|
+
re.MULTILINE,
|
|
61
|
+
)
|
|
35
62
|
|
|
36
63
|
|
|
37
64
|
def utf16_len(s):
|
|
38
65
|
return len(s.encode("utf-16-le")) // 2
|
|
39
66
|
|
|
40
67
|
|
|
68
|
+
def http_url(value):
|
|
69
|
+
if not isinstance(value, str) or any(character.isspace() for character in value):
|
|
70
|
+
return False
|
|
71
|
+
try:
|
|
72
|
+
parsed = urlsplit(value)
|
|
73
|
+
return parsed.scheme in ("http", "https") and bool(parsed.hostname)
|
|
74
|
+
except ValueError:
|
|
75
|
+
return False
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def timestamp(value):
|
|
79
|
+
if not isinstance(value, str) or "T" not in value:
|
|
80
|
+
return False
|
|
81
|
+
try:
|
|
82
|
+
return datetime.fromisoformat(value.replace("Z", "+00:00")).utcoffset() is not None
|
|
83
|
+
except ValueError:
|
|
84
|
+
return False
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def reject_nonfinite(_value):
|
|
88
|
+
raise ValueError("non-finite numbers are not valid JSON")
|
|
89
|
+
|
|
90
|
+
|
|
41
91
|
def main():
|
|
42
92
|
argv = sys.argv[1:]
|
|
43
|
-
path, scene_ids = "
|
|
93
|
+
path, scene_ids = "codecraft-app.json", set()
|
|
44
94
|
i = 0
|
|
45
95
|
while i < len(argv):
|
|
46
96
|
a = argv[i]
|
|
@@ -60,6 +110,11 @@ def main():
|
|
|
60
110
|
path = a
|
|
61
111
|
i += 1
|
|
62
112
|
|
|
113
|
+
if any(a == "--scene-ids" or a.startswith("--scene-ids=") for a in argv):
|
|
114
|
+
if not scene_ids or any(not SCENE_RE.fullmatch(value) for value in scene_ids):
|
|
115
|
+
print("ERROR: --scene-ids needs a non-empty comma-separated list of numeric ids")
|
|
116
|
+
return 2
|
|
117
|
+
|
|
63
118
|
violations, warnings = [], []
|
|
64
119
|
|
|
65
120
|
def vio(msg):
|
|
@@ -70,42 +125,71 @@ def main():
|
|
|
70
125
|
|
|
71
126
|
try:
|
|
72
127
|
with open(path, encoding="utf-8") as f:
|
|
73
|
-
m = json.load(f)
|
|
74
|
-
except (OSError,
|
|
128
|
+
m = json.load(f, parse_constant=reject_nonfinite)
|
|
129
|
+
except (OSError, ValueError) as e:
|
|
75
130
|
print(f"VIOLATION cannot read/parse {path}: {e}")
|
|
76
131
|
return 1
|
|
132
|
+
if not isinstance(m, dict):
|
|
133
|
+
print("VIOLATION manifest must be a JSON object")
|
|
134
|
+
return 1
|
|
77
135
|
base = os.path.dirname(os.path.abspath(path))
|
|
78
136
|
|
|
79
137
|
for key in ("manifest_version", "identity", "info", "images", "deployment", "bom", "sync"):
|
|
80
138
|
if key not in m:
|
|
81
139
|
vio(f"missing top-level section: {key}")
|
|
82
140
|
|
|
141
|
+
if type(m.get("manifest_version")) is not int or m["manifest_version"] != 1:
|
|
142
|
+
vio("manifest_version must be integer 1")
|
|
143
|
+
if set(m) - {"manifest_version", "identity", "info", "images", "deployment", "bom", "sync"}:
|
|
144
|
+
vio("unsupported top-level fields for manifest version 1")
|
|
145
|
+
for key in ("identity", "info", "deployment", "bom", "sync"):
|
|
146
|
+
if not isinstance(m.get(key), dict):
|
|
147
|
+
vio(f"{key} must be an object")
|
|
148
|
+
m[key] = {}
|
|
149
|
+
for key in ("be_public", "privacy"):
|
|
150
|
+
if key in m or key in m["info"]:
|
|
151
|
+
vio(f"{key} must not appear in the manifest or app info; use the parent lifecycle workflow")
|
|
152
|
+
|
|
83
153
|
ident = m.get("identity", {})
|
|
84
154
|
rt = ident.get("remote_type")
|
|
85
155
|
if rt is not None and rt not in ("Global", "China", "Private"):
|
|
86
|
-
vio(
|
|
87
|
-
|
|
88
|
-
|
|
156
|
+
vio("identity.remote_type must be Global|China|Private or null")
|
|
157
|
+
app_id = ident.get("app_id")
|
|
158
|
+
if app_id is not None and (not isinstance(app_id, str) or not app_id.strip()):
|
|
159
|
+
vio("identity.app_id must be a non-empty string or null")
|
|
160
|
+
for key in ("org_id", "account"):
|
|
161
|
+
if ident.get(key) is not None and not isinstance(ident[key], str):
|
|
162
|
+
vio(f"identity.{key} must be a string or null")
|
|
163
|
+
if ident.get("created_at") is not None and not timestamp(ident["created_at"]):
|
|
164
|
+
vio("identity.created_at must be an RFC3339 timestamp with timezone or null")
|
|
89
165
|
|
|
90
166
|
info = m.get("info", {})
|
|
167
|
+
if set(info) - {"app_name", "excerpt", "scene", "allow_clone", "allow_commerce", "license", "author", "activity_id"}:
|
|
168
|
+
vio("info contains unsupported fields; use the documented app info keys")
|
|
91
169
|
name = info.get("app_name", "")
|
|
92
|
-
if not name.strip():
|
|
93
|
-
vio("info.app_name
|
|
170
|
+
if not isinstance(name, str) or not name.strip():
|
|
171
|
+
vio("info.app_name must be a non-empty string")
|
|
94
172
|
elif utf16_len(name) > NAME_MAX:
|
|
95
173
|
vio(f"info.app_name is {utf16_len(name)} UTF-16 code units (max {NAME_MAX})")
|
|
96
174
|
excerpt = info.get("excerpt", "")
|
|
97
|
-
if not excerpt.strip():
|
|
98
|
-
vio("info.excerpt
|
|
175
|
+
if not isinstance(excerpt, str) or not excerpt.strip():
|
|
176
|
+
vio("info.excerpt must be a non-empty string")
|
|
99
177
|
elif utf16_len(excerpt) > EXCERPT_MAX:
|
|
100
178
|
vio(f"info.excerpt is {utf16_len(excerpt)} UTF-16 code units (max {EXCERPT_MAX})")
|
|
101
|
-
scene =
|
|
102
|
-
if not SCENE_RE.
|
|
103
|
-
vio(
|
|
179
|
+
scene = info.get("scene", "")
|
|
180
|
+
if not isinstance(scene, str) or not SCENE_RE.fullmatch(scene):
|
|
181
|
+
vio("info.scene must be a numeric string id from app_scenarios_array")
|
|
104
182
|
elif scene_ids and scene not in scene_ids:
|
|
105
|
-
vio(
|
|
183
|
+
vio("info.scene is not in the supplied app_scenarios_array ids")
|
|
106
184
|
for flag in ("allow_clone", "allow_commerce"):
|
|
107
|
-
if info.get(flag) not in (0, 1):
|
|
108
|
-
vio(f"info.{flag} must be 0 or 1
|
|
185
|
+
if type(info.get(flag)) is not int or info[flag] not in (0, 1):
|
|
186
|
+
vio(f"info.{flag} must be integer 0 or 1")
|
|
187
|
+
for key in ("license", "author"):
|
|
188
|
+
if not isinstance(info.get(key), str):
|
|
189
|
+
vio(f"info.{key} must be a string (empty is allowed)")
|
|
190
|
+
activity_id = info.get("activity_id")
|
|
191
|
+
if activity_id is not None and (type(activity_id) is not int or not 0 < activity_id <= 2**63 - 1):
|
|
192
|
+
vio("info.activity_id must be a positive integer within the CLI's int64 range, or null/omitted for no activity")
|
|
109
193
|
|
|
110
194
|
images = m.get("images", [])
|
|
111
195
|
if not isinstance(images, list):
|
|
@@ -117,7 +201,13 @@ def main():
|
|
|
117
201
|
warn("no images — fine for a private draft (omit the `images` key in the payload; the CLI rejects an empty array); a cover is required before publishing")
|
|
118
202
|
if isinstance(images, list):
|
|
119
203
|
for i, img in enumerate(images):
|
|
204
|
+
if not isinstance(img, dict):
|
|
205
|
+
vio(f"images[{i}] must be an object")
|
|
206
|
+
continue
|
|
120
207
|
p, role = img.get("path", ""), img.get("role", "")
|
|
208
|
+
if not isinstance(p, str) or not p.strip():
|
|
209
|
+
vio(f"images[{i}].path must be a non-empty local path string")
|
|
210
|
+
continue
|
|
121
211
|
if i == 0 and role != "cover":
|
|
122
212
|
vio("images[0].role must be 'cover'")
|
|
123
213
|
if i > 0 and role != "gallery":
|
|
@@ -134,71 +224,170 @@ def main():
|
|
|
134
224
|
vio(f"images[{i}] {p!r}: zero-byte file")
|
|
135
225
|
elif size > IMAGE_MAX_BYTES:
|
|
136
226
|
vio(f"images[{i}] {p!r}: {size} bytes exceeds 5 MB")
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
if
|
|
227
|
+
sha = img.get("sha256")
|
|
228
|
+
if sha is not None:
|
|
229
|
+
if not isinstance(sha, str) or not SHA256_RE.fullmatch(sha):
|
|
230
|
+
vio(f"images[{i}].sha256 must be a complete lowercase SHA-256 hex digest or null")
|
|
231
|
+
with open(full, "rb") as image_file:
|
|
232
|
+
digest = hashlib.sha256(image_file.read()).hexdigest()
|
|
233
|
+
if digest != sha:
|
|
140
234
|
vio(f"images[{i}] {p!r}: sha256 mismatch (file changed since hash)")
|
|
141
235
|
else:
|
|
142
236
|
warn(f"images[{i}] {p!r}: sha256 not computed yet")
|
|
143
237
|
url = img.get("file_url")
|
|
144
|
-
if url is not None and not
|
|
145
|
-
vio(f"images[{i}].file_url must be http(s)
|
|
238
|
+
if url is not None and not http_url(url):
|
|
239
|
+
vio(f"images[{i}].file_url must be a valid http(s) URL or null")
|
|
146
240
|
elif url is None:
|
|
147
241
|
warn(f"images[{i}] {p!r}: not uploaded yet (file_url null)")
|
|
148
242
|
|
|
149
243
|
blocks = m.get("deployment", {}).get("blocks", [])
|
|
150
244
|
if not isinstance(blocks, list):
|
|
151
245
|
vio("deployment.blocks must be an array")
|
|
246
|
+
blocks = []
|
|
152
247
|
else:
|
|
248
|
+
if not blocks:
|
|
249
|
+
warn("no deployment blocks — author and review the deployment journey before claiming deployability")
|
|
153
250
|
seen = set()
|
|
154
|
-
for b in blocks:
|
|
251
|
+
for index, b in enumerate(blocks):
|
|
252
|
+
label = f"deployment.blocks[{index}]"
|
|
253
|
+
if not isinstance(b, dict):
|
|
254
|
+
vio(f"deployment.blocks[{index}]: must be an object")
|
|
255
|
+
continue
|
|
155
256
|
bid = b.get("id")
|
|
156
|
-
if bid
|
|
157
|
-
vio(f"deployment.blocks:
|
|
158
|
-
seen
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
vio(f"
|
|
257
|
+
if not isinstance(bid, str) or not bid.strip():
|
|
258
|
+
vio(f"deployment.blocks[{index}]: needs a non-empty string id")
|
|
259
|
+
elif bid in seen:
|
|
260
|
+
vio(f"{label}: duplicate block id")
|
|
261
|
+
else:
|
|
262
|
+
seen.add(bid)
|
|
263
|
+
block_type = b.get("type")
|
|
264
|
+
if not isinstance(block_type, str):
|
|
265
|
+
vio(f"{label}: type must be a supported block type string")
|
|
266
|
+
continue
|
|
267
|
+
if block_type in TEXT_BLOCK_TYPES:
|
|
268
|
+
if not isinstance(b.get("content"), str):
|
|
269
|
+
vio(f"{label}: text/code content must be a string")
|
|
270
|
+
elif block_type not in ("code", "divider") and RAW_MARKDOWN_RE.search(b["content"]):
|
|
271
|
+
vio(f"{label}: content contains raw Markdown; compile it with app doc compile before inserting tool blocks")
|
|
272
|
+
if block_type == "step" and (not isinstance(b.get("title"), str) or not b["title"].strip()):
|
|
273
|
+
vio(f"{label}: step block needs a non-empty title string")
|
|
165
274
|
cfg = b.get("config")
|
|
275
|
+
if block_type in TOOL_CONFIG_FIELDS:
|
|
276
|
+
if not isinstance(cfg, dict):
|
|
277
|
+
vio(f"{label}: tool block needs a config object; flat legacy fields are not rendered")
|
|
278
|
+
continue
|
|
279
|
+
if TOOL_CONFIG_FIELDS[block_type].intersection(b):
|
|
280
|
+
vio(f"{label}: tool settings belong inside config; remove flat or duplicated settings")
|
|
281
|
+
if isinstance(cfg.get("config"), (dict, list)):
|
|
282
|
+
vio(f"{label}: remove the extra config.config wrapper")
|
|
283
|
+
elif block_type not in TEXT_BLOCK_TYPES:
|
|
284
|
+
vio(f"{label}: unsupported block type")
|
|
285
|
+
if block_type == "flash-firmware":
|
|
286
|
+
if "device_id" in cfg and not isinstance(cfg["device_id"], str):
|
|
287
|
+
vio(f"{label}: config.device_id must be a SKU string")
|
|
288
|
+
elif not cfg.get("device_id"):
|
|
289
|
+
warn(f"{label}: config.device_id is pending — resolve the exact device SKU")
|
|
290
|
+
for key in ("device_type", "firmware_name", "project_zip_name", "flash_mode", "flash_address", "firmware_url", "project_zip_url"):
|
|
291
|
+
if key in cfg and not isinstance(cfg[key], str):
|
|
292
|
+
vio(f"{label}: config.{key} must be a string (empty is allowed for a pending value)")
|
|
293
|
+
mode = cfg.get("flash_mode")
|
|
294
|
+
if mode is None or mode == "":
|
|
295
|
+
warn(f"{label}: config.flash_mode is pending")
|
|
296
|
+
elif mode not in ("bin", "zip"):
|
|
297
|
+
vio(f"{label}: config.flash_mode must be bin or zip")
|
|
298
|
+
else:
|
|
299
|
+
prefix = "firmware" if mode == "bin" else "project_zip"
|
|
300
|
+
if not cfg.get(prefix + "_url"):
|
|
301
|
+
warn(f"{label}: config.{prefix}_url is pending — deployment input incomplete")
|
|
302
|
+
for size_key in ("firmware_size", "project_zip_size"):
|
|
303
|
+
if size_key in cfg and not isinstance(cfg[size_key], str):
|
|
304
|
+
vio(f"{label}: config.{size_key} must be a string")
|
|
305
|
+
elif cfg.get(size_key) and not QUANTITY_RE.fullmatch(cfg[size_key]):
|
|
306
|
+
vio(f"{label}: config.{size_key} must be a positive byte count string or pending empty string")
|
|
307
|
+
address = cfg.get("flash_address")
|
|
308
|
+
if address is not None and address != "" and (not isinstance(address, str) or address not in FLASH_ADDRESSES):
|
|
309
|
+
vio(f"{label}: unsupported config.flash_address; read tool-blocks.md for device defaults")
|
|
310
|
+
for key in ("muse_gadget", "full_flash"):
|
|
311
|
+
if key in cfg and type(cfg[key]) is not bool:
|
|
312
|
+
vio(f"{label}: config.{key} must be a JSON boolean")
|
|
313
|
+
if cfg.get("muse_gadget") is True and cfg.get("full_flash") is True:
|
|
314
|
+
vio(f"{label}: config.full_flash must be false when config.muse_gadget is true")
|
|
315
|
+
if block_type == "node-red":
|
|
316
|
+
if cfg.get("flow_data") is not None and not isinstance(cfg["flow_data"], (dict, list)):
|
|
317
|
+
vio(f"{label}: config.flow_data must be an object or array, not a JSON string")
|
|
318
|
+
if cfg.get("model_data") is not None and not isinstance(cfg["model_data"], dict):
|
|
319
|
+
vio(f"{label}: config.model_data must be an object or null")
|
|
166
320
|
if isinstance(cfg, dict):
|
|
167
|
-
for
|
|
168
|
-
if
|
|
169
|
-
|
|
321
|
+
for key, val in cfg.items():
|
|
322
|
+
if not key.endswith("_url"):
|
|
323
|
+
continue
|
|
324
|
+
if val is None or val == "":
|
|
325
|
+
warn(f"{label}: config.{key} is empty — pending deployment input")
|
|
326
|
+
elif not http_url(val):
|
|
327
|
+
vio(f"{label}: config.{key} must be a valid http(s) URL or a pending empty value")
|
|
170
328
|
|
|
171
329
|
materials = m.get("bom", {}).get("materials", [])
|
|
172
330
|
if not isinstance(materials, list):
|
|
173
331
|
vio("bom.materials must be an array")
|
|
332
|
+
materials = []
|
|
174
333
|
else:
|
|
175
334
|
for i, row in enumerate(materials):
|
|
335
|
+
if not isinstance(row, dict):
|
|
336
|
+
vio(f"bom.materials[{i}] must be an object")
|
|
337
|
+
continue
|
|
338
|
+
if set(row) - {"id", "name", "quantity", "note", "buy_url", "price", "pic_url", "image"}:
|
|
339
|
+
vio(f"bom.materials[{i}] contains unsupported fields; project catalog sku into id rather than copying a raw catalog result")
|
|
176
340
|
for forbidden in ("price", "pic_url", "image"):
|
|
177
341
|
if forbidden in row:
|
|
178
342
|
vio(f"bom.materials[{i}]: {forbidden!r} is not a persistable field (dropped server-side)")
|
|
179
343
|
if "id" in row: # Seeed catalog row
|
|
344
|
+
if not isinstance(row["id"], str) or not row["id"].strip():
|
|
345
|
+
vio(f"bom.materials[{i}].id must be a non-empty SKU string; omit id for custom rows")
|
|
180
346
|
for req in ("name", "quantity", "note", "buy_url"):
|
|
181
347
|
if req not in row:
|
|
182
348
|
vio(f"bom.materials[{i}] (catalog row): missing {req!r}")
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
349
|
+
if not isinstance(row.get("name"), str) or not row["name"].strip():
|
|
350
|
+
vio(f"bom.materials[{i}].name must be a non-empty string")
|
|
351
|
+
if not isinstance(row.get("quantity"), str) or not QUANTITY_RE.fullmatch(row["quantity"]):
|
|
352
|
+
vio(f"bom.materials[{i}].quantity must be a positive integer string")
|
|
353
|
+
if "note" in row and not isinstance(row["note"], str):
|
|
354
|
+
vio(f"bom.materials[{i}].note must be a string")
|
|
355
|
+
if "buy_url" in row and row["buy_url"] != "" and not http_url(row["buy_url"]):
|
|
356
|
+
vio(f"bom.materials[{i}].buy_url must be an http(s) URL or an empty string")
|
|
186
357
|
|
|
187
358
|
sync = m.get("sync", {})
|
|
188
359
|
lr, lpr = sync.get("local_revision"), sync.get("last_pushed_revision")
|
|
189
|
-
if
|
|
190
|
-
vio(
|
|
191
|
-
if
|
|
192
|
-
vio(
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
360
|
+
if type(lr) is not int or lr < 1:
|
|
361
|
+
vio("sync.local_revision must be an integer >= 1")
|
|
362
|
+
if type(lpr) is not int or lpr < 0 or (type(lr) is int and lpr > lr):
|
|
363
|
+
vio("sync.last_pushed_revision must be 0..local_revision")
|
|
364
|
+
pushed_hash = sync.get("last_pushed_hash")
|
|
365
|
+
if pushed_hash is not None and (not isinstance(pushed_hash, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", pushed_hash)):
|
|
366
|
+
vio("sync.last_pushed_hash must be a full sha256:<64 lowercase hex digits> digest or null")
|
|
367
|
+
if sync.get("last_pushed_at") is not None and not timestamp(sync["last_pushed_at"]):
|
|
368
|
+
vio("sync.last_pushed_at must be an RFC3339 timestamp with timezone or null")
|
|
369
|
+
if type(lpr) is int and lpr > 0 and (not app_id or pushed_hash is None or sync.get("last_pushed_at") is None):
|
|
370
|
+
vio("a pushed revision needs app_id, last_pushed_hash, and last_pushed_at")
|
|
371
|
+
|
|
372
|
+
def check_public_values(value, location):
|
|
373
|
+
if isinstance(value, dict):
|
|
374
|
+
for key, child in value.items():
|
|
375
|
+
if key.lower() in SECRET_FIELDS and isinstance(child, str) and child.strip() and not INPUT_PLACEHOLDER_RE.fullmatch(child):
|
|
376
|
+
vio(f"{location}.{key}: credential value must not be distributed (value redacted)")
|
|
377
|
+
check_public_values(child, f"{location}.{key}")
|
|
378
|
+
elif isinstance(value, list):
|
|
379
|
+
for index, child in enumerate(value):
|
|
380
|
+
check_public_values(child, f"{location}[{index}]")
|
|
381
|
+
elif isinstance(value, str):
|
|
382
|
+
if SECRET_VALUE_RE.search(value):
|
|
383
|
+
vio(f"{location}: secret-shaped value in publishable data (value redacted)")
|
|
384
|
+
elif LONG_HEX_RE.search(value):
|
|
385
|
+
warn(f"{location}: long hex literal in publishable data; review whether it is a public hash")
|
|
386
|
+
|
|
387
|
+
for section in ("info", "deployment"):
|
|
388
|
+
check_public_values(m[section], section)
|
|
389
|
+
check_public_values(materials, "bom.materials")
|
|
390
|
+
check_public_values([img.get("file_url") for img in images if isinstance(img, dict)], "images.file_url")
|
|
202
391
|
|
|
203
392
|
for w in warnings:
|
|
204
393
|
print(f"WARNING {w}")
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Write and review the app for its readers
|
|
2
|
+
|
|
3
|
+
Read this before drafting any human-facing app content. Read the [field reference](../../references/app-fields.md) before filling fields and the entire [tool-block reference](../../references/tool-blocks.md) before writing deployment instructions. This guide supplements their schema and device rules; it does not replace them.
|
|
4
|
+
|
|
5
|
+
## Give each field a purpose
|
|
6
|
+
|
|
7
|
+
| Content | Reader's question | Writing criteria |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `app_name` | What is this app called? | Preserve its established name; propose renaming rather than adding unexplained device/marketing suffixes. Max 60 UTF-16 code units. |
|
|
10
|
+
| `excerpt` | Is this useful to me? | One or two clear sentences: implemented capability, audience/use case, useful outcome. Max 300 UTF-16 code units. Omit changelog, deployment sequence, framework inventory, and unsupported performance claims. Mention hardware only when it helps the reader understand the app. |
|
|
11
|
+
| Introduction blocks | What will I be able to do, and what should I know first? | At most two short paragraphs that add context or essential limitations. Do not repeat the excerpt verbatim or paste a developer README. |
|
|
12
|
+
| Step title | What action comes next? | A concrete verb/action. No manual step number; the UI supplies it. |
|
|
13
|
+
| Step instructions | What do I do here, and how do I know it worked? | Necessary prerequisites, actual tool/button/input, and an observable outcome. Put the relevant tool immediately after the instruction that uses it. |
|
|
14
|
+
| BOM note | Why do I need this part? | Its role in this app, quantity/variant clarification, and optional status where relevant. No copied catalog advertising. |
|
|
15
|
+
|
|
16
|
+
Use the user's/project's established language; ask if a consequential audience/language choice is unclear. Explain unfamiliar product-specific terms only where the reader needs them. Delete filler and superlatives whose meaning or evidence cannot be stated.
|
|
17
|
+
|
|
18
|
+
Example, assuming source evidence confirms the behavior:
|
|
19
|
+
|
|
20
|
+
- Weak excerpt: “An innovative ESP32-S3 + FOMO + Arduino project. Flash the bin and connect USB. v1.2.”
|
|
21
|
+
- Useful excerpt: “Count jars passing a small conveyor and view the running total on the display. Built for makers testing a simple packing-line counter.”
|
|
22
|
+
|
|
23
|
+
Do not reuse the example's claims for another project. Avoid specific accuracy, speed, compatibility, or ease-of-use promises without evidence.
|
|
24
|
+
|
|
25
|
+
## Review the deployment as a complete journey
|
|
26
|
+
|
|
27
|
+
Before serializing blocks, outline each necessary user action with prerequisites, supported tool, verified inputs, expected result, and readiness. Choose tools because they support the project, rather than inserting every available tool type.
|
|
28
|
+
|
|
29
|
+
Start from a reader with the listed hardware and finish with the promised function running. Cover required connection/preparation, deploy/flash/install, per-user setup, first use, and stop/reset only where the project supports and needs them. Usually a few distinct actions suffice; do not force a step count or omit necessary actions to meet one.
|
|
30
|
+
|
|
31
|
+
Cross-check the plan against the real artifacts and device configuration:
|
|
32
|
+
|
|
33
|
+
- Is the exact board/variant supported by this tool and artifact? Are SKU, device type, address, architecture, and version sourced correctly?
|
|
34
|
+
- Can the reader carry out every action through the documented page tools and explicit preparation? Developer compilation commands are not a substitute for an available deployment tool.
|
|
35
|
+
- Does each required tool have usable inputs, or a documented prompt that allows the reader to supply them? A known local artifact awaiting this session's upload differs from an artifact nobody has provided.
|
|
36
|
+
- Are the instructions consistent with actual configuration prompts, reset behavior, and the tool's expected output? Do not invent a Wi-Fi setup screen, login flow, stop command, or success message.
|
|
37
|
+
- Are missing inputs visible as gaps? Empty URLs, invented IDs, placeholder containers, and instructions saying “deploy” without a functioning path do not establish a deployable app.
|
|
38
|
+
|
|
39
|
+
A needed but incomplete tool stays in the local draft. Resolve the missing input, or obtain the user's decision to save an incomplete draft and report it as such. Configuring a block does not execute it on hardware.
|
|
40
|
+
|
|
41
|
+
## Run an editorial pass on the assembled manifest
|
|
42
|
+
|
|
43
|
+
Review the actual final values as continuous reader-facing content, including compiled text and the order of tools. This pass is separate from running the validator.
|
|
44
|
+
|
|
45
|
+
1. **Truth:** Trace claims and compatibility statements to inspected files or user decisions. Remove roadmap features and unsupported promises. Preserve meaningful limitations.
|
|
46
|
+
2. **Clarity:** Resolve vague references such as “configure it” or “click deploy” into the actual object, input, and action. Keep terms and device names consistent.
|
|
47
|
+
3. **Flow:** Check prerequisites appear before use, the tool is in the right step, success can be observed, and the reader reaches the promised outcome.
|
|
48
|
+
4. **Economy:** Remove repeated introductions, duplicate steps, internal development history, and spec/menu dumps. Keep enough detail to complete each action.
|
|
49
|
+
5. **Presentation:** Inspect HTML/plain-text content after Markdown compilation. Check step titles, links/media, code vs prose, and accidental raw Markdown. Ensure BOM role notes and gallery order match the plan.
|
|
50
|
+
|
|
51
|
+
Fix defects before showing the final review. Record material corrections and any remaining gap in `.sensecraft/<manifest-stem>.review.md`. Preserve brief source pointers and BOM lookup evidence so a resumed session can reassess the decisions.
|
|
52
|
+
|
|
53
|
+
Present the concrete result before upload: final name/excerpt and permission choices; selected activity name/ID with dates, requirements and fit evidence, or reason for no participation; ordered steps with tool types; BOM variants/quantities and confirmation status; selected cover/assets; manifest link and remaining deployment/publishing gaps. Activity selection must follow [app-fields.md](../../references/app-fields.md#activity-selection-during-app-authoring): do not claim eligibility from a title alone or silently change permissions to qualify. Record remaining entry deliverables and distinguish selection, accepted join, verified association, and completed competition submission. The review file can carry the full copy and evidence when chat would become unwieldy. Ask only for outstanding material decisions or required authorization; do not add a ceremonial approval round for an already authorized create.
|
|
54
|
+
|
|
55
|
+
Record readiness precisely: **format validated**, **catalog verified**, **editorially reviewed**, and **deployment inputs complete** are separate findings. Include validation warnings, custom/unverified BOM rows, pending uploads versus missing artifacts, and untested hardware execution in the review. A coverless private app can have complete deployment inputs. A private app with a missing firmware URL cannot be described as ready to deploy. Run all CLI checks yourself; ask the user for unresolved decisions or required browser/device actions.
|