Phase D of v2.3 template configuration — closes the loop between the
Swift app and the catalog pipeline. Authors can now ship schemaful
bundles; the Python validator enforces the same invariants the Swift
installer does; the catalog site displays the schema so visitors see
what they'll need to configure before installing.
Python validator (tools/build-catalog.py):
- SUPPORTED_SCHEMA_VERSIONS accepts both 1 and 2 (v1 bundles are
unchanged; v2 adds optional manifest.config).
- New _validate_config_schema function mirrors the Swift
ProjectConfigService.validateSchema rules: unique keys, supported
types, enum option presence + unique values, list itemType ==
"string", secret-field cannot declare a default,
modelRecommendation.preferred non-empty when present.
- _validate_contents_claim cross-checks contents.config (field count)
against config.schema actual length — mismatch refused.
- TemplateRecord.to_catalog_entry exposes `config` in catalog.json so
the site can render the schema.
- render_site copies each bundle's template.json to the detail dir as
manifest.json (only when the manifest has a config block — keeps
the served tree lean and makes "no manifest.json" a meaningful
404 signal in the frontend).
- catalog.json's own schemaVersion stays at 1 (independent of per-
template manifest schemaVersion).
Python tests (tools/test_build_catalog.py): 8 new cases in a new
ConfigSchemaValidationTests suite — accepts schemaful bundle, rejects
duplicate keys, rejects secret-with-default, rejects enum-without-
options, rejects unsupported field type, rejects contents.config
count mismatch, rejects unsupported list itemType, legacy v1
manifests pass unchanged. 24/24 Python tests total.
Site (site/widgets.js):
- New renderConfigSchema(container, config) — mirrors the display
on the Scarf install preview. Renders each field as a <dt>/<dd>
pair with type + required badges; enum shows choice labels; list
fields show min/max bounds; string fields show pattern/length;
secret fields get a "Stored in Keychain" reassurance. Optional
modelRecommendation panel at the bottom with preferred + rationale
+ alternatives.
- The renderer is display-only — the site never collects values;
that's the Scarf app's job.
template.html.tmpl adds a #config-schema <section>. The inline script
fetches manifest.json from the detail dir; on success hands the
config block to ScarfWidgets.renderConfigSchema; on 404 (schema-less
templates) silently leaves the section empty. CSS in styles.css
adds a config-schema panel matching the accent-green aesthetic.
24/24 Python + 50/50 Swift tests pass. site-status-checker still
renders correctly (schema-less; manifest.json isn't copied for it).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the catalog pipeline without introducing any external dependencies.
tools/build-catalog.py walks templates/<author>/<name>/, validates every
shipped .scarftemplate against its manifest (same invariants Swift's
ProjectTemplateService.verifyClaims enforces at install time), and emits
templates/catalog.json for the frontend to read.
Validator invariants:
- Required bundle files: template.json, README.md, AGENTS.md, dashboard.json
- contents claim cross-checked against actual zip entries (instructions,
skills, cron count, memory appendix)
- dashboard.json widget types restricted to the vocabulary the Swift
renderer knows
- Manifest id author component must match the template directory
- 5 MB bundle-size cap on submissions (installer's own cap is 50 MB)
- High-confidence secret patterns (private keys, GitHub PATs, Slack tokens,
AWS access keys, OpenAI/Anthropic keys) block the bundle
- staging/ source tree must match the built bundle byte-for-byte — catches
the common failure mode of editing staging/ but forgetting to rebuild
scripts/catalog.sh wraps the Python script with check/build/preview/serve/
publish subcommands, mirroring the scripts/wiki.sh shape. publish adds a
second-pass hard-pattern secret scan on the rendered gh-pages output so
template prose can't leak credentials even if the Python scan missed them.
tools/test_build_catalog.py has 14 unit tests covering the main validator
paths (minimal-valid, missing-AGENTS, content-claim mismatch, author
mismatch, oversized bundle, unknown widget type, secret detection,
staging-drift detection, missing bundle, catalog.json shape, and a real-
bundle end-to-end check against templates/awizemann/site-status-checker).
Python 3.9 compatible (Xcode's bundled python3), so no runtime needs
installing.
templates/catalog.json committed as the first generated aggregate index;
maintainers regenerate on merge by running `./scripts/catalog.sh build`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Alan Wizemann