mirror of
https://github.com/awizemann/scarf.git
synced 2026-05-10 10:36:35 +00:00
c055081ba3a8843b49f4614ff95be3f51dfff6b7
10 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Alan Wizemann
|
7656ad8052 |
docs(v2.3): document how agents see Scarf projects
Three doc updates covering the AGENTS.md context-injection pattern introduced in the previous commit. CLAUDE.md — new "Project-scoped chat + Scarf-managed AGENTS.md context (v2.3)" subsection under Project Templates. Covers: - The session-project sidecar at ~/.hermes/scarf/session_project_map.json (why it exists, what manages it) - How Hermes picks up project context: cwd-based auto-load of the first matching context file (priority order, 20KB cap) - Exact marker format and block shape - Invariants that future edits must preserve: secret-safe, idempotent, bounded-region, non-fatal, refresh-before-session-start ordering - Template-author contract: leave the region alone, put instructions below - Known caveat: parent-directory `.hermes.md` shadowing (deferred to v2.4) scarf-template-author SKILL.md — new pitfall bullet in the "Common pitfalls" checklist telling scaffolding agents to preserve the `<!-- scarf-project -->` region and put template- specific instructions below it. Rebuilt the bundle so installs from the catalog pick up the guidance; regenerated catalog.json. Wiki update (Project-Templates page) lands next via scripts/wiki.sh. 93/93 Swift + 24/24 Python tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Alan Wizemann
|
5e207f760d |
docs(skill): warn authors against raw URLs in field descriptions
Pairs with the config-sheet wrap fix in
|
||
|
Alan Wizemann
|
ea4032766b |
feat(templates): ship awizemann/template-author skill bundle
A new .scarftemplate in the public catalog whose only content is
a Hermes skill that teaches an agent how to scaffold a new
Scarf-compatible project — dashboard, optional configuration
schema, optional cron job, AGENTS.md — from a short conversational
interview. Scaffolded projects are usable locally and cleanly
exportable as .scarftemplate bundles later.
The skill itself (~400 lines of structured markdown at
skills/scarf-template-author/SKILL.md) covers:
- When to invoke vs. when to answer inline
- The on-disk project shape Scarf expects
- A 5-question interview flow
- Full widget catalog (all 7 widget types) with JSON shapes
- Config schema design + hard invariants (no defaults on secrets,
`contents.config` must match field count, etc.)
- Cron-job design including the {{PROJECT_DIR}} gotcha
- Step-by-step file writing (dashboard, manifest, AGENTS.md, README)
- Testing + catalog validation instructions
- Common pitfalls + source-of-truth references
Delivered as a .scarftemplate so the install flow's normal
safeguards apply: preview sheet shows one project + one skill
+ zero cron jobs + no config step, uninstall drops both the
project dir and the namespaced skill folder via the existing
lock-file mechanism.
Scope per user sign-off: blank-slate / fully conversational for
v1. Pre-baked archetypes (`monitor`, `dev-dashboard`, etc.) are
deferred to v1.1 pending real usage data on what shapes users
actually ask for.
New Swift test exercises the bundle through the installer's
plan builder — asserts manifest shape, that the skill lands at
~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md,
and that no-config templates correctly skip the manifest cache.
58/58 Swift tests pass; 24/24 Python tests pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Alan Wizemann
|
fb7a80f191 |
fix: Run Now agent-run timing + non-404 webview placeholder
Two independent fixes that both blocked the "install → Run Now → see the Site tab render" loop. 1. CronViewModel.runNow stopped blocking on `cron tick`. Previously the UI waited up to 60 s on the tick before deciding whether the job succeeded, so any agent run that did real work (an LLM call + a few HTTP GETs + a file write = easily 90 s+) surfaced a false "Run failed" toast while the job kept running in the background. Dashboard updates landed minutes later, confusing the user. New shape: show "Agent started — dashboard will update when it finishes" the instant `cron run` queues the job, then call `cron tick` with a 300 s timeout to force execution. Tick failures are logged but don't overwrite the started-toast — HermesFileWatcher picks up the dashboard.json rewrite automatically when the agent finishes. 2. site-status-checker's webview widget pointed at `github.com/awizemann/scarf/tree/main/templates/awizemann/...`. The templates/ path only exists on project-sharing, not main, so GitHub returned 404 in the Site tab until the first cron run replaced the URL with the user's configured site. Switched the placeholder to `awizemann.github.io/scarf/` which always renders. Bundle + catalog rebuilt against the updated dashboard.json. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Alan Wizemann
|
19750597cd |
feat(site-status-checker): add Live Site Preview webview for Site tab
A Scarf project dashboard that includes at least one webview widget automatically exposes a Site tab next to the Dashboard tab. Adding a "Live Site Preview" section with a webview widget gives this template that tab out of the box. The cron job + AGENTS.md now tell the agent to rewrite the webview's `url` field to the first entry in `values.sites` on each run, so the Site tab renders whatever the user actually configured instead of the GitHub placeholder. If `values.sites` is empty, the webview URL is left untouched. Swift example test updated to assert 4 sections (was 3) plus the new webview widget's presence + title; bundle + catalog rebuilt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Alan Wizemann
|
03bf5262bb |
feat(templates): install-time {{PROJECT_DIR}} substitution in cron prompts
Hermes doesn't set a working directory when firing cron jobs, so any
relative path in a template's cron prompt (`.scarf/config.json`,
`status-log.md`, etc.) resolves against whatever dir Hermes happens
to be in — NOT the installed project. Practical effect: site-status-
checker's cron job fires, agent runs with relative paths, finds
nothing to read, silently bails. User sees "Run now" complete with
zero output and nothing updated on disk.
Fix: the installer now substitutes template-author placeholders in
cron prompts at install time, before calling `hermes cron create`.
The registered cron job carries a fully-qualified, CWD-independent
prompt.
Supported tokens (deliberately few — each is part of the template
format contract from now on):
- `{{PROJECT_DIR}}` — absolute path of the installed project dir.
The one that was motivating this fix; required for any cron prompt
that reads or writes project files.
- `{{TEMPLATE_ID}}` — the `owner/name` from the manifest, for
templates that want to tag delivery payloads or log lines.
- `{{TEMPLATE_SLUG}}` — the sanitised slug used by the installer for
dir name + skills namespace, for templates that want to reference
their skills install path.
Implemented as a static `ProjectTemplateInstaller.substituteCronTokens`
so it's testable as a pure function. Unsupported placeholders pass
through verbatim — template authors notice in testing that their
token didn't get replaced and either use a supported one or file
a request.
Site Status Checker v1.1.0 updated to use the tokens:
- cron/jobs.json prompt now opens with "Run the site status check
for the Scarf project at {{PROJECT_DIR}}" and references
{{PROJECT_DIR}}/.scarf/config.json, {{PROJECT_DIR}}/status-log.md,
and {{PROJECT_DIR}}/.scarf/dashboard.json explicitly.
- AGENTS.md gains a note explaining that the cron-registered prompt
carries absolute paths (installer substitutes at install time),
while interactive-chat agents can keep using relative paths.
- bundle rebuilt, catalog regenerated.
templates/CONTRIBUTING.md documents the three supported tokens under
the cron/jobs.json bullet so future authors don't have to discover
this by hitting the same CWD bug.
Tests:
- ProjectTemplateExampleTemplateTests.siteStatusCheckerParsesAndPlans
extended to assert the bundled prompt contains {{PROJECT_DIR}}
UNRESOLVED. If someone accidentally bakes an absolute path into
the template (their install dir), every user of that template
would get the wrong path — this test catches that.
- Four new substitution tests in ProjectTemplateInstallerTests:
resolves PROJECT_DIR / resolves ID + SLUG / leaves unknown tokens
untouched / substitutes repeated occurrences. All go through the
static helper directly; no install round-trip needed.
57/57 Swift tests + 24/24 Python tests pass. Catalog check clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Alan Wizemann
|
3af99d9d9c |
fix(templates): site-status-checker dashboard no longer lies before first run
The template's dashboard shipped with two hardcoded example URLs (https://example.com + https://example.org) baked into a "Configured Sites" list widget, and the widget title still said "from sites.txt" — stale from the v1.0.0 layout before we moved to config.json. After the v1.1.0 configure-on-install flow lands, the user fills in a real sites list through the Configure form (which correctly lands in `.scarf/config.json` — the editor modal confirms that), but the dashboard still rendered the baked-in example URLs. The agent would overwrite them on the first cron run, but until then the dashboard misrepresents reality. Two orthogonal paths to fix this — populate the dashboard's items from config.json at install time (requires Scarf-side template-value interpolation, which is a v2.3.1 feature), or ship a dashboard that clearly advertises "nothing has run yet." Taking the second path for v1.1.0: replace the example URLs with a single placeholder row with status "pending" pointing the user at running the check. The agent replaces the row with real data on the first cron run. Also: widget title fixed ("Watched Sites (populated after first run)" instead of the stale sites.txt reference), top-of-dashboard description updated, and the Quick Start text now mentions the Configuration button as the way to set sites, not the long-gone sites.txt. Bundle + catalog rebuilt; ProjectTemplateExampleTemplateTests still passes (it asserts against cron prompt + schema shape, not dashboard content, so the dashboard edit doesn't affect it). --- Secondary fix: test deflake from the saveRegistry throw change. Making saveRegistry throw exposed a pre-existing parallel-test race: three suites (ProjectTemplateInstallerTests, ProjectTemplateUninstallerTests, ProjectTemplateConfigInstallTests) all write to the real `~/.hermes/scarf/projects.json`. Swift Testing's `.serialized` trait only serializes within a single suite — multiple suites still run in parallel. Before, writes silently failed on the racing-loser side and tests passed by accident; now the loser's test throws "couldn't be saved in the folder 'scarf'". Added TestRegistryLock — a module-level NSLock that all three suites' snapshotRegistry/restoreRegistry helpers share. acquireAndSnapshot() locks + reads; restore(_:) writes + unlocks. The paired snapshot-in-test-body / defer-restore pattern keeps acquire + release balanced. Replaced the three per-suite copies of the helpers with thin delegates to the shared lock. Verified by running the full test suite 3 consecutive times: 53/53 tests pass each run, no flakes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Alan Wizemann
|
81e8da91d6 |
feat(templates): upgrade site-status-checker to v1.1.0 with config schema
First real exercise of the v2.3 configuration feature. The template no longer asks the agent to bootstrap sites.txt on first run — instead, users enter their list of URLs through the Configure form during install, and change them later via the dashboard's Configuration button. This makes the template a complete round-trip test of the new feature end-to-end. Schema (manifest.config.schema): - `sites` — list<string>, required, 1–25 items, default two example URLs. This is the list the cron job hits. - `timeout_seconds` — number, 1–60, default 10. Per-URL HTTP timeout. - `modelRecommendation.preferred = claude-haiku-4` — rationale: simple tool-use task, Haiku is cost-effective for daily cron. Manifest bumped: schemaVersion 1 → 2, version 1.0.0 → 1.1.0, minScarfVersion 2.2.0 → 2.3.0, contents.config = 2. AGENTS.md rewritten for the config-driven flow: - Reads values from `.scarf/config.json` at run time (values.sites + values.timeout_seconds). No more sites.txt bootstrap. - "Add a site" / "Remove a site" no longer mean the agent edits a file — they mean "open the Configuration button on the dashboard." The agent points the user there rather than trying to mutate config.json itself. A future Scarf release may expose a tool for agents to write config programmatically; until then, config is strictly a user action. - First-run bootstrap now only creates status-log.md (if absent). README.md rewritten to walk users through the new form-based flow, explain the Configuration button, and document the model recommendation. Uninstall instructions point at the right-click Uninstall Template action rather than manual steps. Cron prompt updated to reference config.json (values.sites, values.timeout_seconds) instead of sites.txt. ProjectTemplateExampleTemplateTests.siteStatusCheckerParsesAndPlans extended with v2-specific assertions: manifest.schemaVersion == 2, contents.config == 2, schema.fields.count == 2, per-field constraints (sites type/itemType/minItems/maxItems, timeout min/max), modelRecommendation.preferred, plan.configSchema + plan.manifestCachePath are populated, plan.projectFiles includes both config.json + manifest.json destinations. Cron-prompt assertion swapped from sites.txt to config.json/values.sites. Three suites that touch ~/.hermes/scarf/projects.json now carry .serialized — the new Phase B install-with-config tests stressed the parallel-execution race in the snapshot/restore helpers. Serializing within each suite deflakes without any architectural change. Swift 50/50, Python 24/24, catalog validator accepts the upgraded bundle. Site detail page now has manifest.json for renderConfigSchema to pick up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Alan Wizemann
|
68f6b98fcf |
feat(catalog-config): mirror manifest v2 schema in validator + site
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> |
||
|
Alan Wizemann
|
11732baa3c |
feat(catalog): stdlib-only Python validator + regenerator for templates/
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> |