gooneyryan/scarf
1
0
Fork 0
mirror of https://github.com/awizemann/scarf.git synced 2026-05-10 18:44:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: gooneyryan/scarf:v2.3-projects
Branches Tags
gooneyryan/scarf:main gooneyryan/scarf:gh-pages gooneyryan/scarf:ws-9-ios-v0.13 gooneyryan/scarf:ws-3-kanban-v0.13 gooneyryan/scarf:ws-5-gateway-v0.13 gooneyryan/scarf:ws-4-curator-archive gooneyryan/scarf:ws-7-settings-v0.13 gooneyryan/scarf:ws-6-providers-v0.13 gooneyryan/scarf:ws-8-ux-v0.13 gooneyryan/scarf:ws-2-goals-and-queue gooneyryan/scarf:ws-1-capabilities-v0.13 gooneyryan/scarf:v12-updates gooneyryan/scarf:scarf-mobile-development gooneyryan/scarf:v2.3-projects gooneyryan/scarf:project-sharing
gooneyryan/scarf:v2.8.0 gooneyryan/scarf:v2.7.5 gooneyryan/scarf:v2.7.1 gooneyryan/scarf:v2.7.0 gooneyryan/scarf:v2.6.5 gooneyryan/scarf:v2.6.0 gooneyryan/scarf:v2.5.2 gooneyryan/scarf:v2.5.1 gooneyryan/scarf:v2.5.0 gooneyryan/scarf:v2.3.0 gooneyryan/scarf:v2.2.1 gooneyryan/scarf:v2.2.0 gooneyryan/scarf:rescue/project-sharing-pre-ios-split gooneyryan/scarf:rescue/template-configuration-before-rename gooneyryan/scarf:rescue/main-pre-reset gooneyryan/scarf:v2.1.0 gooneyryan/scarf:v2.0.2 gooneyryan/scarf:v2.0.0 gooneyryan/scarf:v1.6.2 gooneyryan/scarf:v1.6.1 gooneyryan/scarf:v1.6.0 gooneyryan/scarf:v1.5.8 gooneyryan/scarf:v1.6.0-test-imessage gooneyryan/scarf:v1.6.1-full-pipeline-test gooneyryan/scarf:v1.5.7 gooneyryan/scarf:v1.5.6 gooneyryan/scarf:v1.5.5 gooneyryan/scarf:v1.5.2 gooneyryan/scarf:v1.5.1 gooneyryan/scarf:v1.5.0 gooneyryan/scarf:v1.4.0 gooneyryan/scarf:v1.3.0 gooneyryan/scarf:v1.2.0 gooneyryan/scarf:v1.1.1 gooneyryan/scarf:v1.1.0 gooneyryan/scarf:v1.0.1 gooneyryan/scarf:v1.0.0
..
compare: gooneyryan/scarf:rescue/project-sharing-pre-ios-split
Branches Tags
gooneyryan/scarf:main gooneyryan/scarf:gh-pages gooneyryan/scarf:ws-9-ios-v0.13 gooneyryan/scarf:ws-3-kanban-v0.13 gooneyryan/scarf:ws-5-gateway-v0.13 gooneyryan/scarf:ws-4-curator-archive gooneyryan/scarf:ws-7-settings-v0.13 gooneyryan/scarf:ws-6-providers-v0.13 gooneyryan/scarf:ws-8-ux-v0.13 gooneyryan/scarf:ws-2-goals-and-queue gooneyryan/scarf:ws-1-capabilities-v0.13 gooneyryan/scarf:v12-updates gooneyryan/scarf:scarf-mobile-development gooneyryan/scarf:v2.3-projects gooneyryan/scarf:project-sharing
gooneyryan/scarf:v2.8.0 gooneyryan/scarf:v2.7.5 gooneyryan/scarf:v2.7.1 gooneyryan/scarf:v2.7.0 gooneyryan/scarf:v2.6.5 gooneyryan/scarf:v2.6.0 gooneyryan/scarf:v2.5.2 gooneyryan/scarf:v2.5.1 gooneyryan/scarf:v2.5.0 gooneyryan/scarf:v2.3.0 gooneyryan/scarf:v2.2.1 gooneyryan/scarf:v2.2.0 gooneyryan/scarf:rescue/project-sharing-pre-ios-split gooneyryan/scarf:rescue/template-configuration-before-rename gooneyryan/scarf:rescue/main-pre-reset gooneyryan/scarf:v2.1.0 gooneyryan/scarf:v2.0.2 gooneyryan/scarf:v2.0.0 gooneyryan/scarf:v1.6.2 gooneyryan/scarf:v1.6.1 gooneyryan/scarf:v1.6.0 gooneyryan/scarf:v1.5.8 gooneyryan/scarf:v1.6.0-test-imessage gooneyryan/scarf:v1.6.1-full-pipeline-test gooneyryan/scarf:v1.5.7 gooneyryan/scarf:v1.5.6 gooneyryan/scarf:v1.5.5 gooneyryan/scarf:v1.5.2 gooneyryan/scarf:v1.5.1 gooneyryan/scarf:v1.5.0 gooneyryan/scarf:v1.4.0 gooneyryan/scarf:v1.3.0 gooneyryan/scarf:v1.2.0 gooneyryan/scarf:v1.1.1 gooneyryan/scarf:v1.1.0 gooneyryan/scarf:v1.0.1 gooneyryan/scarf:v1.0.0

12 Commits
v2.3-projects .. rescue/project-sharing-pre-ios-split

Author SHA1 Message Date
Alan Wizemann 96b5da3cd5 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>
 2026-04-23 16:35:57 +02:00
Alan Wizemann 3fe8f4efa0 fix(projects): clarify remove-vs-uninstall UX 
Three UX changes addressing user feedback that "Remove from Scarf" and
"Uninstall Template…" looked interchangeable, and that users were
surprised when uninstall left the project folder behind.

- Rename sidebar menu entries:
  "Uninstall Template…"  → "Uninstall Template (remove installed files)…"
  "Remove from Scarf"    → "Remove from List (keep files)…"
  The expanded labels carry the scope difference at the point of click.

- Add a confirmation dialog for Remove from List. The sidebar's "-"
  button and the context-menu entry both route through it. Dialog copy
  explicitly spells out "Nothing on disk is touched — the folder, cron
  job, skills, and memory block all stay. To actually remove installed
  files, use 'Uninstall Template…' instead." Sidebar "-" also gains a
  help tooltip saying the same thing.

- Post-uninstall preserved-files banner. When the uninstaller keeps
  the project directory (because the cron wrote a status-log.md or the
  user dropped files in there), the success view now shows an orange
  banner listing up to 8 preserved paths with a "+N more…" tail, plus
  a one-line explanation and a pointer to delete the folder from
  Finder if the user doesn't want those files. VM captures the
  preservation shape before nil'ing `plan` on success.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 16:24:31 +02:00
Alan Wizemann 9cb2afc787 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>
 2026-04-23 15:52:32 +02:00
Alan Wizemann 785fa7dc8c fix(cron): Run now now actually runs + markdown rendering in install sheet 
Two fixes chained from manually testing site-status-checker v1.1.0.

---

Cron Run now was a no-op when the Hermes gateway scheduler wasn't
already running. `hermes cron run <id>` only marks a job as due on
the next scheduler tick — it doesn't execute. During dev or right
after install (gateway stopped, as the logs the user pasted showed),
the user's click resulted in nothing happening: job queued, tick
never comes, zero agent sessions, zero output, dashboard never
updates. Exactly the failure mode they hit.

Fix: CronViewModel.runNow now calls `hermes cron run <id>` followed
by `hermes cron tick` after a short delay. `tick` runs all due jobs
once and exits — so the just-queued job actually executes, and
exits cleanly whether the scheduler is running or not. Redundant
(not duplicative) when the gateway is live. The user sees a status
message whether it succeeded or failed instead of silent nothing.

---

Markdown rendering in install-sheet screens. Template READMEs,
manifest descriptions, field help text, and cron prompts all
reasonably contain markdown — but the install preview sheet was
rendering everything as plain text, so `[Create one](https://…)`
would appear verbatim instead of as a link, `# Site Status Checker`
as a literal pound sign, etc.

New Features/Templates/Views/TemplateMarkdown.swift — a tiny,
dependency-free markdown renderer scoped to what template authors
actually write:
- Headings (#..######) → larger bold Text with vertical spacing
- Bullet and numbered lists → hanging-indent rows with •/1. prefix
- Fenced code blocks (```) → monospaced with quaternary background
- Paragraphs → regular Text, with inline formatting via SwiftUI's
  built-in AttributedString(markdown:) so **bold**, *italic*,
  `code`, and [links](urls) work
- Blank lines separate blocks

Two entry points: `TemplateMarkdown.render(_ source:)` returns a
View for multi-block content (README preview), and
`TemplateMarkdown.inlineText(_ source:)` returns a Text for
one-line strings where block structure doesn't apply (field
descriptions, manifest tagline).

Wired into:
- TemplateInstallSheet.readmeSection — was plain Text(readme), now
  renders the full README with structure.
- TemplateInstallSheet.manifestHeader description — inline-only
  (taglines rarely have block structure).
- TemplateInstallSheet.cronSection — new DisclosureGroup per cron
  job exposes the full prompt with markdown rendering. Users can
  now verify what the installer will register with Hermes before
  clicking Install. {{PROJECT_DIR}} / {{TEMPLATE_ID}} tokens show
  unresolved here; they get substituted when the installer calls
  hermes cron create.
- TemplateConfigSheet field descriptions — inline markdown so
  `[Create a token](https://...)`-style links render as real links.

Not a full CommonMark implementation — no tables, no blockquotes,
no images, no HTML passthrough. Those can evolve as templates need
them. Safe with untrusted input: never executes scripts or renders
raw HTML.

Scope stays tight: 57/57 Swift tests + 24/24 Python tests still pass.
No new tests for the markdown helper itself — rendering is visual,
hard to unit-test meaningfully without snapshot-testing infra, and
the surface is small enough that changes would be caught by the
visual regression of any template install.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 15:25:31 +02:00
Alan Wizemann 75b3e97cdb 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>
 2026-04-23 15:11:19 +02:00
Alan Wizemann 60820f9cfb 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>
 2026-04-23 14:52:46 +02:00
Alan Wizemann a7a174d2c6 fix(config): install sheet silently closed after Continue in config step 
Two bugs chained into the observed "install completed but project
didn't show up" report. Either one would have been enough on its own;
both are here so both are fixed.

Primary bug: TemplateConfigSheet's Cancel + Continue buttons each
called `@Environment(\.dismiss)` after their state-update callbacks.
That was fine when the sheet is presented standalone (the post-install
Configuration button uses it this way and wants dismissal), but Phase C
also INLINED the same view inside TemplateInstallSheet.configureView
for the install flow's .awaitingConfig stage — there's no intermediate
.sheet() presenter there, so `dismiss()` resolved to the OUTER install
sheet. Clicking Continue → configure form's `onCommit` fired
`installerViewModel.submitConfig(values:)` which advanced stage to
.planned, then the dismiss() closed the whole install sheet before
the preview ever rendered. install() was never called.

Fix: remove both dismiss() calls from TemplateConfigSheet. Dismissal
is now the caller's responsibility. ConfigEditorSheet (standalone
mode) already calls `dismiss()` inside its own onCancel closure and
lets the .succeeded state's Done button handle commit-dismissal, so
nothing breaks there. The install flow's state machine advances to
the preview stage where the existing Install/Cancel buttons drive
everything from there.

Secondary bug (latent, same class): ProjectDashboardService.saveRegistry
swallowed both directory-creation and file-write errors with `try?`.
If the `~/.hermes/scarf/` dir creation or projects.json write ever
failed for any reason (permissions, readonly filesystem, sandbox),
the installer's registerProject returned a valid-looking ProjectEntry
while the registry on disk never received the row. Same symptom
surface as the primary bug: install "succeeds," project invisible.

Fix: saveRegistry now throws. Updated all four callers:
- ProjectTemplateInstaller.registerProject: `try` — a registry
  write failure aborts install with a user-visible failure screen.
  This is the critical path; silent success on a destructive op is
  the exact failure mode we want to eliminate.
- ProjectTemplateUninstaller: `do/catch` + logger.warning — we're at
  the final step of uninstall after every other side effect has
  already completed (files removed, skills removed, cron removed,
  memory stripped, Keychain cleared). Leaving a stale registry row
  pointing at a deleted project is cosmetic and easy to fix from
  the sidebar minus button.
- ProjectsViewModel.addProject + removeProject: `do/catch` +
  logger.error. The VM doesn't currently have a surface for
  user-visible errors (no toast/alert on this view), but the
  failure now at least lands in the unified log instead of
  disappearing. Proper in-UI error surface is tracked as follow-up.
- ProjectDashboardService.loadRegistry: switched its stale `print`
  to `logger.error` while I was in the file.

Tests: added TemplateInstallerViewModelTests suite (3 tests) covering
the install VM's configure-step state transitions:
- submitConfigStashesValuesAndTransitionsToPlanned — .awaitingConfig
  → .planned + configValues stash on the plan. The exact transition
  that the dismiss() bug tore down mid-flight.
- cancelConfigReturnsToAwaitingParentDirectory — back-button behaviour
  with plan preserved so re-entry doesn't re-run buildPlan.
- submitConfigNoOpWhenPlanIsNil — defensive guard.

These won't catch a view-level regression (Swift Testing doesn't do
UI tests in this project), but they lock in the VM state-machine
contract so the next refactor can't silently break submitConfig or
cancelConfig without failing CI.

53/53 Swift tests + 24/24 Python tests + catalog validator clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 03:26:17 +02:00
Alan Wizemann 55229a2f91 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>
 2026-04-23 02:21:14 +02:00
Alan Wizemann 99859c06fd docs: CLAUDE.md — add Template Configuration section 
Documents the v2.3 configuration feature for future agent sessions:
manifest schemaVersion 2 shape, supported field types, Keychain storage
conventions (service/account naming with project-path hash suffix), the
uninstaller's config-items cleanup path, exporter behaviour (schema
forwarded, values stripped), and the catalog site's schema display.

Includes the "Schema is Swift-primary" note so future edits to
TemplateConfigField.FieldType go through the right order of updates —
Swift first, then Python mirror, then widgets.js, then UI controls,
then tests on both sides. Schema drift between Swift + Python
validator would accept bundles the app later refuses at install
time, which is a catastrophic UX failure for the catalog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 02:03:12 +02:00
Alan Wizemann 9f3600ae01 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>
 2026-04-23 02:00:34 +02:00
Alan Wizemann b34f432f00 feat(config): configure-step UI + post-install Configuration editor 
Adds the user-facing side of v2.3 template configuration. Install-time
flow: templates with a non-empty config.schema get a Configure step
between the parent-directory pick and the preview sheet. Post-install
flow: a Configuration button on the dashboard header + a context-menu
entry on the project list opens the same form pre-filled with current
values.

New files:
- Features/Templates/ViewModels/TemplateConfigViewModel.swift — drives
  the form. Keeps freshly-entered secret bytes in `pendingSecrets`
  in-memory until commit() succeeds, then calls
  ProjectConfigService.storeSecret for each one. Cancelling never
  leaves orphan Keychain entries — the form is transactional.
  Validates via ProjectConfigService.validateValues on commit and
  populates per-field `errors` the sheet surfaces inline. Two modes:
  .install (needs a project passed at commit time) and
  .edit(project:) (VM already holds the target).
- Features/Templates/Views/TemplateConfigSheet.swift — the form. One
  row per field with a control dispatched by type: TextField (string),
  TextEditor (text), number input, Toggle (bool), segmented/dropdown
  Picker (enum, picks form by option count), add/remove list editor,
  SecureField with show/hide toggle (secret). Required-field asterisk
  + per-field error display. Optional modelRecommendation panel at
  the bottom — informational badge; no auto-switch.
- Features/Templates/ViewModels/TemplateConfigEditorViewModel.swift —
  loads <project>/.scarf/manifest.json + config.json, hands a
  TemplateConfigViewModel to the sheet, writes edited values back on
  commit. Has a .notConfigurable stage for projects without a
  manifest cache (hand-added projects, schema-less templates).
- Features/Templates/Views/ConfigEditorSheet.swift — thin wrapper
  that owns the editor VM and routes its stages to loading / form /
  saving / success / error / not-configurable views.

Wiring:
- TemplateInstallerViewModel gains an .awaitingConfig stage between
  .awaitingParentDirectory and .planned. pickParentDirectory() now
  inspects plan.configSchema and either routes to .awaitingConfig
  (non-empty schema) or straight to .planned (schema-less). New
  submitConfig(values:) stashes finalized values in plan.configValues
  and advances; cancelConfig() returns to .awaitingParentDirectory.
- TemplateInstallSheet renders a new `configureView` that inlines
  TemplateConfigSheet into the install flow for .awaitingConfig.
  The existing preview (.planned) gains a new "Configuration" section
  listing each field + its display value (secrets shown as "••••••
  (Keychain)", lists shown as "first + N more", "(not set)" for
  missing values).
- ProjectsView adds an isConfigurable(_:) check (transport.fileExists
  on .scarf/manifest.json), a new @State configEditorProject for
  sheet presentation, a new "Configuration…" context-menu entry on
  project list rows (for configurable projects), and a new
  slider.horizontal.3 button on the dashboard header next to the
  existing Uninstall button.

50/50 tests still pass. This commit is UI-only — no new Phase C tests
(sheet behaviour is hard to unit-test without UI automation and the
underlying VM logic is exercised by Phase A/B's config-round-trip
tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 01:46:21 +02:00
Alan Wizemann b289a83944 iOS Target Set Up 
xcode mobile target creation
 2026-04-23 01:42:25 +02:00
78 changed files with 837 additions and 3586 deletions
Expand all files Collapse all files
CLAUDE.md
-36
View File
@@ -142,42 +142,6 @@ Key services: [TemplateConfig.swift](scarf/scarf/Core/Models/TemplateConfig.swif
**Schema is Swift-primary.** If `TemplateConfigField.FieldType` gains a new case, update in order: `TemplateConfig.swift` (model + validation), `tools/build-catalog.py` (`SUPPORTED_CONFIG_FIELD_TYPES` + type-specific rules), `widgets.js` (`summariseConstraint`), `TemplateConfigSheet.swift` (new control subview), tests on both sides. Schema drift between validator + installer is the kind of bug users only notice after shipping.
### Project-scoped chat + Scarf-managed AGENTS.md context (v2.3)
v2.3 adds a per-project Sessions tab and a "New Chat" button that spawns `hermes acp` with `cwd = project.path`. Session-to-project attribution is persisted in a Scarf-owned sidecar at `~/.hermes/scarf/session_project_map.json` — the ACP wire protocol has no project-metadata hook (extra params are silently dropped), and `state.db` has no cwd column, so the sidecar is Scarf's source of truth for "which project does this session belong to?" Managed by [SessionAttributionService.swift](scarf/scarf/Core/Services/SessionAttributionService.swift); read by the per-project [ProjectSessionsView.swift](scarf/scarf/Features/Projects/Views/ProjectSessionsView.swift).
**Giving the agent project awareness.** Hermes auto-reads a context file from the session's cwd at startup — priority order `.hermes.md` → `HERMES.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`, first match wins, 20KB cap. We lean on that by writing a Scarf-managed block into `<project>/AGENTS.md` before opening the session. Service: [ProjectAgentContextService.swift](scarf/scarf/Core/Services/ProjectAgentContextService.swift). Block shape:
```
<!-- scarf-project:begin -->
## Scarf project context
_Auto-generated by Scarf — do not edit between the begin/end markers._
You are operating inside a Scarf project named **"<Project Name>"**. …
- **Project directory:** `<absolute path>`
- **Dashboard:** `<path>/.scarf/dashboard.json`
- **Template:** `<author/id>` v<version> <!-- template-installed only -->
- **Configuration fields:** `field_a`, `field_b (secret — name only, value stored in Keychain)`
- **Registered cron jobs:** `[tmpl:<id>] <name>` — schedule …, currently paused|enabled
- **Uninstall manifest:** `<path>/.scarf/template.lock.json` <!-- when present -->
Any content below this block is template- or user-authored; preserve and defer to it.
<!-- scarf-project:end -->
```
**Invariants.**
- **Secret-safe.** Block surfaces field NAMES, never VALUES. A project with a Keychain-stored secret shows `api_token (secret — name only, …)`; the Keychain ref URI and any plaintext value never appear. Auditable by `refreshListsFieldNamesNotValues` in `ProjectAgentContextServiceTests`.
- **Idempotent.** Two refreshes with unchanged state produce byte-identical output. The write is skipped entirely when no delta, avoiding file-watcher churn.
- **Bounded.** Everything outside the markers is preserved on every refresh. Template-author AGENTS.md content lives safely below the block.
- **Non-fatal.** `ChatViewModel.startACPSession` calls refresh with `try?` + log — a failed write doesn't block the chat from starting; worst case is the session loses project awareness.
- **Refresh timing.** Called BEFORE `client.start()` so the block lands before Hermes's session-boot context scan. Skipping this ordering = the agent sees stale context from the previous refresh (or nothing, on fresh projects).
**Template-author contract.** A template shipped via the catalog should include an `AGENTS.md` with the template's operational instructions. Authors leave the `<!-- scarf-project -->` region alone — Scarf populates it at chat-start time. Everything below is template-owned and preserved.
**Known caveat.** If any parent directory of the project contains `.hermes.md` or `HERMES.md`, those shadow the project's `AGENTS.md` (higher in Hermes's priority order). No fix in v2.3 — deferred to v2.4 pending user input on how to handle authored `.hermes.md` files.
## Template Catalog
Shipped community templates live at `templates/<author>/<name>/` (one level down — `templates/CONTRIBUTING.md` explains the submission flow for authors). The catalog site is generated from this directory and served at `awizemann.github.io/scarf/templates/` alongside the Sparkle appcast — the two coexist on the `gh-pages` branch but touch completely disjoint paths.
README.md
+5 -16
View File
@@ -19,24 +19,13 @@
<a href="https://www.buymeacoffee.com/awizemann"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" height="28"></a>
</p>
## What's New in 2.3
## What's New in 2.2
- **Projects sidebar grows up** — group projects into folders, rename / archive / unarchive in place, filter the list with ⌘F, jump to the first nine with ⌘1–⌘9. Archived projects hide by default; a toggle in the bottom bar surfaces them. Non-destructive on the v2.2 registry file — downgrade stays clean.
- **Per-project Sessions tab** — alongside Dashboard and Site. Shows chats attributed to the project, with a **New Chat** button that spawns `hermes acp` with the project's directory as the session cwd and attributes the result via a Scarf-owned sidecar (`~/.hermes/scarf/session_project_map.json`). Click any listed session to resume it with project context automatically restored.
- **Agent actually knows what project it's in** — the architectural headline. Every project-scoped chat gets a Scarf-managed block auto-injected into the project's `AGENTS.md` before the session starts. Hermes reads AGENTS.md from the session's cwd at startup and picks up the block as part of its system prompt. Ask the agent *"what project am I in?"* and it answers with the project name, directory, template id + version, configuration field names, and registered cron jobs — pulled from the injected block. Secret-safe (field names only, never values), idempotent, bounded to `<!-- scarf-project:begin/end -->` markers so template-author content outside the block is preserved across refreshes.
- **Project indicator in Chat** — folder chip in `SessionInfoBar` and `Chat · <ProjectName>` in the nav title when you're in a project-scoped chat. Resumed sessions keep the indicator by looking up the attribution sidecar at resume time.
- **Window-layout cleanup** — switching to Chat or a Sessions tab no longer grows the window past the screen. `.windowResizability(.contentMinSize)` + targeted `idealHeight` caps keep the window's floor at a sensible content minimum while letting users freely drag larger or smaller.
- **Project Templates** — Scarf projects can now travel. Package a project's dashboard, agent instructions, skills, and cron jobs into a `.scarftemplate` bundle, hand it to anyone, and they install it in one click. Every bundle ships with a cross-agent `AGENTS.md` ([agents.md](https://agents.md/) standard) so the instructions work in Claude Code, Cursor, Codex, Aider, and the 20+ other agents that read it natively. Browser-based one-click install via `scarf://install?url=…` deep links. Export / Install from File / Install from URL live under the new **Templates** menu in the Projects toolbar.
- **Preview-before-apply** — Every install shows a preview sheet listing the exact project directory that will be created, every file inside it, every skill that will be namespaced, every cron job that will be registered (paused by default), and a live diff of any memory appendix. Nothing writes until you click Install.
- **Safe-by-design** — Skills install into `~/.hermes/skills/templates/<slug>/` so they never collide with your own. Cron jobs carry a `[tmpl:<id>]` tag and start paused. A `template.lock.json` records everything written for easy uninstall. Templates **never** touch `config.yaml`, `auth.json`, sessions, or credentials.
See the full [v2.3.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.3.0) and the [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates).
### Previously, in 2.2
- **Project Templates** — Scarf projects can now travel. Package a project's dashboard, agent instructions, skills, cron jobs, and a typed configuration schema into a `.scarftemplate` bundle, hand it to anyone, and they install it in one click. Every bundle ships with a cross-agent `AGENTS.md` ([agents.md](https://agents.md/) standard) so the instructions work in Claude Code, Cursor, Codex, Aider, and the 20+ other agents that read it natively. Browser-based one-click install via `scarf://install?url=…` deep links. Export / Install from File / Install from URL live under the **Templates** menu in the Projects toolbar.
- **Typed configuration with Keychain-backed secrets** — templates declare a schema with seven field types (`string`, `text`, `number`, `bool`, `enum`, `list`, `secret`). A **Configure** step in the install flow renders the form, routes secrets to the macOS Keychain, and drops non-secret values into `<project>/.scarf/config.json`.
- **Public template catalog** — [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/) with live dashboard previews + schema rendering. CI-enforced Python validator mirrors the Swift-side invariants on every PR.
- **Safe-by-design** — skills namespaced, cron jobs tagged and paused-on-install, lock-file-driven uninstall, exports carry schema but never values.
See the [v2.2.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.2.0) for the full 2.2 series.
See the full [v2.2.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.2.0).
### Previously, in 2.1
releases/v2.2.0/RELEASE_NOTES.md
+25 -74
View File
@@ -1,50 +1,15 @@
## What's New in 2.2.0
Scarf projects can now travel. This release introduces **Project Templates** — a shareable `.scarftemplate` bundle format that packages a project's dashboard, agent instructions, skills, cron jobs, and a typed configuration schema into a single file anyone can install with one click. Bundles are agent-portable by design: every template ships with a cross-agent [`AGENTS.md`](https://agents.md/) so the instructions work natively in Claude Code, Cursor, Codex, Aider, Jules, Copilot, Zed, and every other agent that reads the Linux Foundation standard.
This is also the first release to ship a public **template catalog website** — a static site generated from `templates/<author>/<name>/` in this repo, previewed at [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/), with a CI-enforced validator for community submissions.
Scarf projects can now travel. This release introduces **Project Templates** — a shareable `.scarftemplate` bundle format that packages a project's dashboard, agent instructions, skills, and cron jobs into a single file anyone can install with one click from a local file or an `scarf://install?url=…` deep link.
### Project Templates
- **Bundle format: `.scarftemplate`.** A zip carrying a `template.json` manifest, the project's dashboard, a required `AGENTS.md` (the [Linux Foundation cross-agent instructions standard](https://agents.md/) — reads natively in Claude Code, Cursor, Codex, Aider, Jules, Copilot, Zed, and more), a README shown in the installer, optional per-agent instruction shims (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`), optional namespaced skills, optional cron job definitions, and an optional memory appendix.
- **Install preview sheet.** Before anything touches disk, Scarf shows you the exact project directory that will be created, every file inside it, every skill that will be namespaced under `~/.hermes/skills/templates/<slug>/`, every cron job that will be registered (always paused — you enable each one manually), and a live diff of the memory appendix against your existing `MEMORY.md`. Markdown fields — the README, field descriptions, cron prompts — render inline. The manifest's content claim is cross-checked against the actual zip entries so a bundle can't hide files from the preview.
- **Bundle format: `.scarftemplate`.** A zip archive carrying a `template.json` manifest, the project's dashboard, a required `AGENTS.md` (the [Linux Foundation cross-agent instructions standard](https://agents.md/) — reads natively in Claude Code, Cursor, Codex, Aider, Jules, Copilot, Zed, and more), a README shown in the installer, optional per-agent instruction shims (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`), optional namespaced skills, optional cron job definitions, and an optional memory appendix. Every bundle is agent-portable out of the box.
- **Install preview sheet.** Before anything touches disk, Scarf shows you the exact project directory that will be created, every file inside it, every skill that will be namespaced under `~/.hermes/skills/templates/<slug>/`, every cron job that will be registered (always paused — you enable each one manually), and a live diff of the memory appendix against your existing `MEMORY.md`. The manifest's content claim is cross-checked against the actual zip entries so a bundle can't hide files from the preview.
- **`scarf://install?url=…` deep links.** Register Scarf as the handler for the `scarf` URL scheme so a future catalog site can link one-click installs straight into the app. Only `https://` payloads are accepted; `file://`, `javascript:`, and `http://` are refused on principle. A 50 MB size cap keeps a malicious link from exhausting disk. The URL never auto-installs — the preview sheet is always user-confirmed.
- **Install-time token substitution.** Template authors use `{{PROJECT_DIR}}`, `{{TEMPLATE_ID}}`, and `{{TEMPLATE_SLUG}}` placeholders in cron prompts; the installer resolves them to absolute paths at install time so the registered cron job works regardless of where Hermes sets CWD.
- **Export any project as a template.** Select a project, open the new Templates menu in the Projects toolbar, fill in a handful of fields (id, name, version, description, optional author + category + tags), tick the skills and cron jobs you want to include, optionally drop in a memory snippet, and save. The exporter carries the authored configuration schema forward but **never** the user's values — exports are safe on projects with live config.
- **No-overwrite, reversible by design.** Installed templates drop a `<project>/.scarf/template.lock.json` recording exactly what they wrote — every project file, skill path, cron job name, memory block id, and Keychain reference. Installing the same template id twice is refused at the preview step so you don't accidentally double-append to `MEMORY.md`.
- **Safe globals.** Skills install to `~/.hermes/skills/templates/<slug>/<skill-name>/` so they never collide with your own skills. Cron jobs are prefixed with `[tmpl:<id>]` and start paused. The installer **never** touches `~/.hermes/config.yaml`, `auth.json`, sessions, or any credential-bearing path.
### Template Configuration (schemaVersion 2)
Templates can now declare a typed configuration schema that drives a form step during install — no more "edit a `sites.txt` file to get started."
- **Typed field vocabulary.** Seven field types: `string`, `text` (multiline), `number` (with `min`/`max`), `bool`, `enum` (with `{value, label}` options), `list` (of strings, with `minItems`/`maxItems`), and `secret` (routed to the macOS Keychain). Constraints per type — `pattern` for regex, `minLength`/`maxLength` for text, etc. — are enforced at install and at edit time.
- **Configure step in the install flow.** If the template declares a schema, a **Configure** screen is inserted between "pick parent directory" and the preview sheet. Non-secret values land in `<project>/.scarf/config.json`; secrets land in the macOS Keychain with a service name of `com.scarf.template.<slug>` and an account keyed to the project-directory hash (so two installs of the same template in different dirs don't collide on Keychain entries).
- **Post-install Configuration editor.** A slider icon in the dashboard header opens the same form pre-filled with the current values. Change a site, rotate a token, toggle a feature — the cron job picks up the new values on its next run. Secrets are never echoed back ("Saved in Keychain — leave empty to keep the stored value").
- **Model recommendations.** Templates can suggest a preferred model (`claude-sonnet-4.5`, `claude-haiku-4`, `gpt-4.1`, etc.) with a rationale. Scarf surfaces the recommendation in the configure sheet without auto-switching your active model — always your call.
- **Secrets are tracked in the lock file.** Uninstalling a template runs `SecItemDelete` on every Keychain ref recorded at install, so a full clean-up leaves nothing behind. Absent entries (user already cleaned them) are no-ops.
### Template Catalog
A Sparkle-style pipeline for community-contributed templates, living on the same `gh-pages` branch as the auto-update feed.
- **Static site.** [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/) — generated from every `templates/<author>/<name>/` directory. Each template gets a detail page showing the README, a live preview of the post-install dashboard, and the configuration schema rendered with human-readable constraint summaries. One-click install via the `scarf://install?url=…` button.
- **Stdlib-only Python validator.** `tools/build-catalog.py` is a no-external-dependencies Python script that mirrors the Swift-side schema and validation invariants (supported widget types, supported field types, `contents` claim verification, secret-with-default rejection, bundle-size cap, high-confidence secret patterns). Run it locally with `./scripts/catalog.sh check` before submitting a PR.
- **CI gate on PRs.** [`.github/workflows/validate-template-pr.yml`](https://github.com/awizemann/scarf/blob/main/.github/workflows/validate-template-pr.yml) runs the validator + its 24-test suite on every PR touching `templates/`, the validator itself, or its tests. Failing PRs get an inline comment with the last 3 KB of the validator output; passing PRs get a tailored checklist naming the specific template directory being changed.
- **Install-URL hosting.** Bundles are raw-served from `main` at `https://raw.githubusercontent.com/awizemann/scarf/main/templates/<author>/<name>/<name>.scarftemplate`. No per-template GitHub Releases ceremony.
- **Dogfood: the site uses Scarf's dashboard format.** `site/widgets.js` is ~300 lines of vanilla JS that renders a `ProjectDashboard` JSON using the same widget vocabulary the app uses, so each detail page's "live preview" is the actual dashboard the user will get.
### Example template: `awizemann/site-status-checker`
Ships as the first catalog entry and exercises every v2.2 surface. [See it in the catalog →](https://awizemann.github.io/scarf/templates/awizemann-site-status-checker/)
- Configure step asks for a list of URLs and a per-URL timeout.
- A paused cron job runs daily at 09:00 (editable from the Cron sidebar), does HTTP GETs with 3-redirect follow, writes a timestamped results table to `status-log.md`, updates the dashboard's Sites Up / Sites Down / Last Checked stat widgets plus the Watched Sites list, and rewrites the Site tab's webview URL to the first configured site.
- Works in any agent — the `AGENTS.md` is the single source of truth; no per-agent shim needed.
### Site tab
A dashboard with at least one `webview` widget now exposes a **Site** tab next to Dashboard. Useful for templates that watch something renderable (a site, a preview endpoint, a Grafana panel). The `site-status-checker` example rewrites the webview URL to the first configured site on every cron run, so the tab stays in sync with live config.
- **Export any project as a template.** Select a project, open the new Templates menu in the Projects toolbar, fill in a handful of fields (id, name, version, description, optional author + category + tags), tick the skills and cron jobs you want to include, optionally drop in a memory snippet, and save. The exporter builds the bundle and you can hand it to anyone.
- **No-overwrite, reversible by design.** Installed templates drop a `<project>/.scarf/template.lock.json` recording exactly what they wrote — every project file, skill path, cron job name, and memory block id. Installing the same template id twice is refused at the preview step so you don't accidentally double-append to `MEMORY.md`. Uninstalling by hand is a matter of deleting the project directory, the skills namespace folder, and any `[tmpl:<id>] …` cron jobs — no hidden state.
- **Safe globals.** Skills install to `~/.hermes/skills/templates/<slug>/<skill-name>/` so they never collide with your own skills. Cron jobs are prefixed with `[tmpl:<id>]` and start paused so nothing unexpected kicks off on install. The installer **never** touches `~/.hermes/config.yaml`, `auth.json`, sessions, or any credential-bearing path.
### Using templates
@@ -52,43 +17,29 @@ A dashboard with at least one `webview` widget now exposes a **Site** tab next t
- **Install from URL:** Projects → Templates → *Install from URL…*, paste an https URL.
- **Install from the web:** click any `scarf://install?url=…` link in a browser.
- **Export:** select a project → Projects → Templates → *Export "&lt;name&gt;" as Template…*, fill the form, save.
- **Edit config post-install:** slider icon in the dashboard header.
- **Uninstall:** right-click the project in the sidebar → *Uninstall Template (remove installed files)…*, or click the uninstall icon in the dashboard header. The preview sheet lists every file, cron job, Keychain secret, and memory block that will be removed, plus every user-created file that will be preserved.
### UX clarifications
- **Remove from List vs. Uninstall Template.** Sidebar context-menu labels clarified so you can see at a glance whether a click is destructive. *Remove from List (keep files)…* is registry-only — nothing on disk is touched, cron jobs stay, Keychain secrets stay. A confirmation dialog spells this out before the click lands. *Uninstall Template (remove installed files)…* is the full, lock-driven cleanup.
- **Post-uninstall "folder kept" banner.** When the uninstaller preserves the project directory because the cron wrote a `status-log.md` (or the user dropped files in there), the success view now explicitly lists the preserved paths with a pointer to delete the folder from Finder if desired.
- **Run Now no longer blocks on agent runs.** The Cron sidebar's Run Now button used to show a "Run failed" toast whenever an agent job ran longer than 60 s — even when the job was finishing correctly in the background. Run Now now shows "Agent started — dashboard will update when it finishes" immediately and the dashboard watcher picks up the completed state when it lands (timeout bumped to 300 s for the catch-stuck-process case).
### Uninstall
- **One-click uninstall** driven by `template.lock.json`. The preview sheet lists every file, cron job, Keychain ref, and memory block that will be removed, and every user-created file that will be preserved.
- **User content is never removed.** Files you (or the agent) added to the project dir after install — like a `sites.txt` or `status-log.md` — are detected and listed as "keep" in the preview. The project directory itself is removed only if nothing user-owned is left inside.
- **Clean global state.** The isolated `~/.hermes/skills/templates/<slug>/` namespace is removed wholesale. Tagged cron jobs are removed via `hermes cron remove`. Every recorded Keychain ref is cleared via `SecItemDelete`. The memory block between the `<!-- scarf-template:<id>:begin/end -->` markers is stripped, leaving the rest of MEMORY.md intact. The project registry entry is removed last.
- **No undo.** Uninstall is destructive — to reinstall, run the install flow again.
### Under the hood
- New models in `Core/Models/ProjectTemplate.swift` (manifest, inspection, install plan, lock file v2) and `Core/Models/TemplateConfig.swift` (schema + typed values + Keychain ref model).
- `Core/Services/ProjectTemplateService.swift` unzips, parses, and validates; `ProjectTemplateInstaller.swift` executes the plan with preflight + fail-fast semantics; `ProjectTemplateUninstaller.swift` reverses an install driven by the lock file; `ProjectTemplateExporter.swift` builds bundles from a live project + selections.
- `Core/Services/ProjectConfigService.swift` owns load/save/validation of `<project>/.scarf/config.json` + secret resolution; `Core/Services/ProjectConfigKeychain.swift` is the thin `SecItemAdd`/`Copy`/`Delete` wrapper (the only Keychain consumer in Scarf today).
- New models in `Core/Models/ProjectTemplate.swift` (manifest, inspection, install plan, lock, errors).
- `Core/Services/ProjectTemplateService.swift` unzips, parses, and validates; `ProjectTemplateInstaller.swift` executes the plan atomically-enough (pre-flights conflicts, then writes); `ProjectTemplateExporter.swift` builds bundles from a live project + selections.
- `Core/Services/TemplateURLRouter.swift` is the process-wide landing pad for `scarf://` URLs so a cold-launch browser click still reaches the install sheet.
- New Swift Testing suites covering 57 tests across the service / installer / uninstaller / exporter / config / Keychain / URL-router paths.
- New Python validator (`tools/build-catalog.py`) + test suite (`tools/test_build_catalog.py`, 24 tests) mirrors the Swift invariants for the CI gate and the site generator. Schema is Swift-primary — additions go to Swift first, Python mirrors.
- `scripts/catalog.sh` wraps the validator with `check / build / preview / serve / publish` subcommands that parallel the `scripts/release.sh` shape.
- Installer dispatches cron creation via `hermes cron create` (there's no direct Scarf write path for `cron/jobs.json`), then diffs before/after to pause the newly-registered jobs.
- New Swift Testing suites: `ProjectTemplateServiceTests`, `TemplateURLRouterTests`, `ProjectTemplateExportTests`.
### Uninstall
- **One-click uninstall** driven by `template.lock.json`. Right-click any template-installed project in the sidebar → **Uninstall Template…**, or click the uninstall button in the dashboard header. A preview sheet lists every file, cron job, and memory block that will be removed, and every user-created file that will be preserved.
- **User content is never removed.** Files you (or the agent) added to the project dir after install — like a `sites.txt` or `status-log.md` — are detected and listed as "keep" in the preview. The project directory itself is removed only if nothing user-owned is left inside.
- **Clean global state.** The isolated `~/.hermes/skills/templates/<slug>/` namespace is removed wholesale. Tagged cron jobs are removed via `hermes cron remove`. The memory block between the `<!-- scarf-template:<id>:begin/end -->` markers is stripped, leaving the rest of MEMORY.md intact. The project registry entry is removed last.
- **No undo.** v1 uninstall is destructive — to reinstall, run the install flow again.
### Not in this release (planned for v2.3)
- In-app catalog browser backed by a GitHub Pages `templates.json`.
- EdDSA-signed bundles reusing the Sparkle key.
- Template updates (compare installed lock against a newer bundle's version, offer a diff).
- Installing into remote `ServerContext`s (v1 is local-only).
### Migrating from 2.1.x
Sparkle will offer the update automatically. No config migration needed. Existing projects are untouched — templates are additive. If you had a v2.2.0-dev install of the earlier `project-templates` branch, uninstall and reinstall any previously-installed templates to pick up the schema-version-2 lock file.
### Documentation
- [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) — installing, exporting, configuring, authoring, uninstalling.
- [Catalog site](https://awizemann.github.io/scarf/templates/) — the public catalog with live dashboard previews.
- [`templates/CONTRIBUTING.md`](https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md) — how to submit a template via PR.
- [Architecture notes in root `CLAUDE.md`](https://github.com/awizemann/scarf/blob/main/CLAUDE.md#project-templates) — service-layer map, Keychain scheme, schema-drift discipline.
### Thanks
Thanks to everyone who tested drafts of the install flow, caught the "Run Now blocks on agent" bug, and pushed on the Remove-vs-Uninstall UX until it was clear. A 2.3 follow-up will extend the catalog validator to enforce per-field-type constraints at PR-time (currently enforced on install but not at submission).
Sparkle will offer the update automatically. No config migration needed. Existing projects are untouched — templates are additive.
releases/v2.2.1/RELEASE_NOTES.md
-38
View File
@@ -1,38 +0,0 @@
## What's New in 2.2.1
A patch release covering Template Configuration rendering fixes reported against v2.2.0, plus a new catalog template that packages a Hermes skill for scaffolding new Scarf projects.
### Configuration sheet — no more clipping
Two independent rendering fixes to the post-install Configuration editor and the install-flow Configure step:
- **Enum fields with long option labels.** An enum with three or four options whose labels exceeded ~20 characters — e.g. a Claude-model picker with labels like *"Claude Opus 4 (Recommended - Most Capable)"* — rendered as a segmented picker that sized to the intrinsic width of all labels concatenated. On macOS, `.pickerStyle(.segmented)` refuses to respect offered width, refuses to wrap, refuses to truncate. The result was a ~650pt picker that overflowed the sheet's 560pt viewport and clipped the entire form on both sides. Enum fields now always render as a dropdown Menu picker, which surfaces long labels in the popup list and respects the parent's offered width regardless of option count or label length.
- **Descriptions with unbreakable content.** Field descriptions rendered via inline AttributedString markdown can contain tokens SwiftUI's `Text` refuses to break mid-token (raw URLs, long paths). Added `.frame(maxWidth: .infinity, alignment: .leading)` on the sheet's inner VStack and on each field row as a secondary constraint, so description text wraps at whitespace boundaries instead of expanding the sheet width. Applied the same modifier to `TemplateInstallSheet`'s main preview VStack for symmetry — installs with README blocks or cron prompts containing long URLs now wrap cleanly too.
### New catalog entry — `awizemann/template-author`
A `.scarftemplate` whose only content is a Hermes skill (`scarf-template-author`) plus a minimal dashboard that points users at it. Installing the template drops the skill at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md`, discoverable by Claude Code, Cursor, Codex, Aider, and every other agent that reads the standard `~/.hermes/skills/` directory.
The skill teaches agents how to scaffold a new Scarf-compatible project through a short interview — purpose, data source, cadence, widgets, config, secrets — then write `<project>/.scarf/dashboard.json`, `<project>/.scarf/manifest.json`, `<project>/AGENTS.md`, and `<project>/README.md`. Scaffolded projects are usable locally and cleanly exportable as `.scarftemplate` bundles via Scarf's Export flow later. [Catalog detail page →](https://awizemann.github.io/scarf/templates/awizemann-template-author/)
v1 is fully conversational / blank-slate. Pre-baked archetypes (monitor, dev-dashboard, personal-log) are deferred to a future release pending real usage data.
### Authoring guidance — SKILL.md
The `scarf-template-author` skill now tells scaffolding agents to prefer markdown link syntax (`[label](https://…)`) over raw URLs in schema field descriptions. Raw URLs work now (v2.2.1's description wrap fix above handles them gracefully), but `[Anthropic console](https://console.anthropic.com)` reads cleaner in the form than a dumped URL. Same rule extended to long paths or other unbreakable strings — wrap in inline code if they have to appear verbatim, prefer markdown links otherwise.
### Under the hood
- **`scripts/catalog.sh publish` fix.** The pre-flight `need_ghpages` check tested `[[ -d "$GHPAGES_DIR/.git" ]]` — "is `.git` a directory?" — which is true for a regular clone but false for a `git worktree add` worktree (where `.git` is a pointer file). `release.sh` creates and leaves the gh-pages worktree around, so after any release the subsequent catalog-publish call was rejected with a misleading "run `git worktree add`" error on a worktree that was already there and valid. Switched to `-e` (exists, either file or directory). Unblocks publishing the catalog immediately after a release.
### Migrating from 2.2.0
Sparkle will offer the update automatically. No config migration needed. Existing template installs are untouched.
If you've already installed `awizemann/template-author` from a pre-release build, no action needed — the catalog and bundle content are forward-compatible.
### Documentation
- [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) — installing, exporting, configuring, authoring, uninstalling.
- [Catalog site](https://awizemann.github.io/scarf/templates/) — two templates live: `awizemann/site-status-checker` and `awizemann/template-author`.
- [`templates/CONTRIBUTING.md`](https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md) — how to submit a template via PR.
releases/v2.3.0/RELEASE_NOTES.md
-104
View File
@@ -1,104 +0,0 @@
## What's New in 2.3.0
The projects sidebar stops being a flat list and becomes a workspace. Folders, rename + archive + search + keyboard jumps, a per-project Sessions tab with a one-click New Chat button, and — the big architectural piece — every project-scoped chat now automatically carries Scarf-managed context into the agent itself, so the agent knows what project it's operating in without any user prompting.
### Projects sidebar grows up
- **Folders.** Group related projects with folders. Right-click any project → *Move to Folder…* — pick an existing folder or create a new one on the fly. Folders are soft: any folder name that isn't referenced by at least one project just disappears, so there's no "empty folder" state to clean up.
- **Rename** a project from the context menu. Preserves everything else — the path, folder assignment, archive flag, and any running cron attribution stay intact. Rejects duplicate names + empty input with an inline warning.
- **Archive / Unarchive.** Hide projects you don't actively use without deleting anything. The sidebar's bottom bar gains a Show Archived toggle so they're one click away when you need them.
- **Search.** ⌘F focuses a filter field at the top of the sidebar. Fuzzy-matches on name, path, and folder label, live as you type.
- **Keyboard jumps.** ⌘1 through ⌘9 jump to the first nine top-level projects. Pairs cleanly with Scarf's existing window-level shortcuts.
Registry migration is non-destructive — `~/.hermes/scarf/projects.json` gains two optional fields (`folder`, `archived`), and a file written by v2.3 is still parseable by v2.2.1 (unknown-keys are ignored), so downgrade works if you ever need it.
### Per-project Sessions tab
Every project now has a **Sessions** tab alongside Dashboard and Site. It shows chats attributed to this specific project — the sidecar at `~/.hermes/scarf/session_project_map.json` maintains the session-to-project mapping (Hermes's `state.db` has no column for this, so Scarf owns the record).
- **New Chat** — spawns `hermes acp` with the project's directory as the session's working directory, attributes the resulting session to the project, and takes you straight into the chat view.
- **Click any listed session to resume it** in the Chat tab; the project indicator comes along automatically.
- Forward-only attribution: sessions you've already started via the CLI or via the global Chat sidebar section continue to live in the global Sessions view unchanged; they simply aren't attributed to any project.
File descriptors are released cleanly on tab-disappear, matching Scarf's other Hermes-DB-reading VMs.
### Agent context injection via AGENTS.md
The architectural headline of this release. Hermes has no native "project" concept and ACP's wire protocol drops extra session params. But Hermes DOES auto-read `AGENTS.md` from the session's cwd at startup (priority: `.hermes.md` → `HERMES.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`, first match wins, 20KB cap). So Scarf leans on that.
Every time you start a project-scoped chat, Scarf writes a managed block into `<project>/AGENTS.md`:
```
<!-- scarf-project:begin -->
## Scarf project context
You are operating inside a Scarf project named "<Project Name>". …
- Project directory: …
- Dashboard: …
- Template: <id> v<version>
- Configuration fields: field_a, api_token (secret — name only, value stored in Keychain)
- Registered cron jobs: [tmpl:<id>] <name> — schedule …
…
<!-- scarf-project:end -->
```
Ask a fresh chat *"what project am I in?"* and the agent answers with the project name, dashboard path, template id, and current cron schedule — pulled from the block Hermes injected into its system prompt automatically.
**Invariants the block guarantees:**
- **Secret-safe.** Surfaces config field *names* with type hints; never values. A project whose config.json has Keychain-ref URIs renders the fields as `api_token (secret — name only, value stored in Keychain)`. Keychain URIs and plaintext values never appear in the block. Locked in by an explicit test (`refreshListsFieldNamesNotValues`).
- **Idempotent.** Two consecutive refreshes with unchanged state produce byte-identical output. The write is skipped entirely when no delta — no unnecessary file-watcher churn.
- **Bounded.** Everything outside the `<!-- scarf-project -->` markers is preserved across every refresh. Template-author AGENTS.md content lives safely below the block; hand-edits are never clobbered.
- **Non-fatal.** A failed block refresh doesn't block the chat from starting — logged + the session proceeds without the extra context.
- **Bare-project friendly.** Projects without an AGENTS.md (plain directories added via the + button) get one created with just the block. Agent awareness works even without template scaffolding.
**Template-author contract:** leave the `<!-- scarf-project -->` region alone in your bundled `AGENTS.md`. Put template-specific instructions below it so they're preserved across refreshes. The `scarf-template-author` scaffolding skill already teaches this pattern to future agents doing project scaffolding.
**Known caveat:** if any parent directory of your project contains a `.hermes.md` or `HERMES.md`, that file takes priority over the project's AGENTS.md in Hermes's discovery order — the Scarf block gets shadowed. No fix in 2.3 — planned for 2.4 pending design input on handling authored `.hermes.md` files.
### Chat UI — project awareness everywhere
Once the cwd, attribution, and AGENTS.md pieces land, the UI follows:
- **Folder chip in `SessionInfoBar`** at the start of the bar (before the working dot + title) shows the active project name with a folder icon.
- **Navigation title** reads `Chat · <ProjectName>` when scoped, plain `Chat` otherwise — macOS `Subject — Detail` convention.
- **Resumed sessions keep the indicator.** Whether you click a session in the project's Sessions tab or come in from a future deep-link, the attribution is looked up at resume time and the chip renders from the same state.
### Window-layout fixes
A pre-existing issue — untracked until v2.3's heavier Chat/Sessions content exposed it — where the window grew past the screen when you switched to content-heavy sections. Fixed by:
- Setting `WindowGroup.windowResizability(.contentMinSize)` so the window's floor (not ceiling) is derived from content.
- Capping `idealHeight` on `RichChatView` and `ProjectSessionsView` so their plain-VStack children (deliberate choice to dodge a LazyVStack whitespace bug) don't report screen-exceeding ideals upward through `NavigationSplitView.detail`.
Window now stays at a user-draggable size and persists across section switches.
### Under the hood
- New models: `SessionProjectMap` — `~/.hermes/scarf/session_project_map.json` serialization (`SessionAttributionService` manages it).
- New services: `SessionAttributionService` (reads + writes the sidecar), `ProjectAgentContextService` (writes the AGENTS.md marker block, tests cover prepend/replace/idempotency/secret-redaction).
- New view models: `ProjectSessionsViewModel` (per-project session list with attribution filter), `ChatViewModel` gains `currentProjectPath` + `currentProjectName`.
- `HermesFileWatcher` now watches the attribution sidecar — file-system events propagate through the VMs as they do for every other Scarf-written file.
- `ProjectsViewModel` gains `moveProject / renameProject / archiveProject / unarchiveProject / folders` — rename preserves selection; archive clears it; reorders driven by `localizedCaseInsensitiveCompare` for locale-aware ordering.
- **22 new Swift tests** across `ProjectRegistryMigrationTests`, `ProjectsViewModelTests`, `SessionAttributionServiceTests`, `ProjectAgentContextServiceTests`. Total: 93 tests.
### Icon tweak
App icon files renamed from iOS-template suffixes to macOS-native filenames + paired `Contents.json` update. Pure naming; no visual change at any rendered size.
### Migrating from 2.2.x
Sparkle will offer the update automatically. No config migration needed. Existing template installs are untouched — the v2.3 additions (folders, archive, sidecar) are purely additive; a v2.2.1 projects.json loads cleanly.
If you had any chat sessions attributed to projects in a pre-release v2.3 build, the forward-only attribution model means those sidecar entries surface correctly in the new Sessions tab on first launch.
### Documentation
- **[Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates)** — gained a "How the agent sees the project" section covering the AGENTS.md injection pattern.
- **Root `CLAUDE.md`** — new subsection "Project-scoped chat + Scarf-managed AGENTS.md context (v2.3)" under Project Templates, covering the sidecar, the marker contract, invariants, and the template-author contract.
- **`scarf-template-author` skill** — pitfall bullet added so future scaffolding agents preserve the marker region when authoring new templates.
### Thanks
Thanks to the users who exercised this release through several layout iterations, caught the `fetchSessions` short-circuit on a fresh VM, and pushed on the "agent doesn't know what project it's in" question until the AGENTS.md mechanism clicked. Several of these fixes are small on their own but add up to a much tighter per-project workflow.
scarf/Scarf iOS/Assets.xcassets/AccentColor.colorset/Contents.json
+11
View File
@@ -0,0 +1,11 @@
{
"colors" : [
{
"idiom" : "universal"
}
],
"info" : {
"author" : "xcode",
"version" : 1
}
}
scarf/Scarf iOS/Assets.xcassets/AppIcon.appiconset/Contents.json
+35
View File
@@ -0,0 +1,35 @@
{
"images" : [
{
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
},
{
"appearances" : [
{
"appearance" : "luminosity",
"value" : "dark"
}
],
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
},
{
"appearances" : [
{
"appearance" : "luminosity",
"value" : "tinted"
}
],
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
}
],
"info" : {
"author" : "xcode",
"version" : 1
}
}
scarf/Scarf iOS/Assets.xcassets/Contents.json
+6
View File
@@ -0,0 +1,6 @@
{
"info" : {
"author" : "xcode",
"version" : 1
}
}
scarf/Scarf iOS/ContentView.swift
+61
View File
@@ -0,0 +1,61 @@
//
// ContentView.swift
// Scarf iOS
//
// Created by Alan Wizemann on 4/23/26.
//
import SwiftUI
import SwiftData
struct ContentView: View {
@Environment(\.modelContext) private var modelContext
@Query private var items: [Item]
var body: some View {
NavigationSplitView {
List {
ForEach(items) { item in
NavigationLink {
Text("Item at \(item.timestamp, format: Date.FormatStyle(date: .numeric, time: .standard))")
} label: {
Text(item.timestamp, format: Date.FormatStyle(date: .numeric, time: .standard))
}
}
.onDelete(perform: deleteItems)
}
.toolbar {
ToolbarItem(placement: .navigationBarTrailing) {
EditButton()
}
ToolbarItem {
Button(action: addItem) {
Label("Add Item", systemImage: "plus")
}
}
}
} detail: {
Text("Select an item")
}
}
private func addItem() {
withAnimation {
let newItem = Item(timestamp: Date())
modelContext.insert(newItem)
}
}
private func deleteItems(offsets: IndexSet) {
withAnimation {
for index in offsets {
modelContext.delete(items[index])
}
}
}
}
#Preview {
ContentView()
.modelContainer(for: Item.self, inMemory: true)
}
scarf/Scarf iOS/Info.plist
+10
View File
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>UIBackgroundModes</key>
<array>
<string>remote-notification</string>
</array>
</dict>
</plist>
scarf/Scarf iOS/Item.swift
+18
View File
@@ -0,0 +1,18 @@
//
// Item.swift
// Scarf iOS
//
// Created by Alan Wizemann on 4/23/26.
//
import Foundation
import SwiftData
@Model
final class Item {
var timestamp: Date
init(timestamp: Date) {
self.timestamp = timestamp
}
}
scarf/Scarf iOS/Scarf_iOS.entitlements
+14
View File
@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>aps-environment</key>
<string>development</string>
<key>com.apple.developer.icloud-container-identifiers</key>
<array/>
<key>com.apple.developer.icloud-services</key>
<array>
<string>CloudKit</string>
</array>
</dict>
</plist>
scarf/Scarf iOS/Scarf_iOSApp.swift
+32
View File
@@ -0,0 +1,32 @@
//
// Scarf_iOSApp.swift
// Scarf iOS
//
// Created by Alan Wizemann on 4/23/26.
//
import SwiftUI
import SwiftData
@main
struct Scarf_iOSApp: App {
var sharedModelContainer: ModelContainer = {
let schema = Schema([
Item.self,
])
let modelConfiguration = ModelConfiguration(schema: schema, isStoredInMemoryOnly: false)
do {
return try ModelContainer(for: schema, configurations: [modelConfiguration])
} catch {
fatalError("Could not create ModelContainer: \(error)")
}
}()
var body: some Scene {
WindowGroup {
ContentView()
}
.modelContainer(sharedModelContainer)
}
}
scarf/Scarf iOSTests/Scarf_iOSTests.swift
+17
View File
@@ -0,0 +1,17 @@
//
// Scarf_iOSTests.swift
// Scarf iOSTests
//
// Created by Alan Wizemann on 4/23/26.
//
import Testing
@testable import Scarf_iOS
struct Scarf_iOSTests {
@Test func example() async throws {
// Write your test here and use APIs like `#expect(...)` to check expected conditions.
}
}
scarf/Scarf iOSUITests/Scarf_iOSUITests.swift
+41
View File
@@ -0,0 +1,41 @@
//
// Scarf_iOSUITests.swift
// Scarf iOSUITests
//
// Created by Alan Wizemann on 4/23/26.
//
import XCTest
final class Scarf_iOSUITests: XCTestCase {
override func setUpWithError() throws {
// Put setup code here. This method is called before the invocation of each test method in the class.
// In UI tests it is usually best to stop immediately when a failure occurs.
continueAfterFailure = false
// In UI tests it’s important to set the initial state - such as interface orientation - required for your tests before they run. The setUp method is a good place to do this.
}
override func tearDownWithError() throws {
// Put teardown code here. This method is called after the invocation of each test method in the class.
}
@MainActor
func testExample() throws {
// UI tests must launch the application that they test.
let app = XCUIApplication()
app.launch()
// Use XCTAssert and related functions to verify your tests produce the correct results.
}
@MainActor
func testLaunchPerformance() throws {
// This measures how long it takes to launch your application.
measure(metrics: [XCTApplicationLaunchMetric()]) {
XCUIApplication().launch()
}
}
}
scarf/Scarf iOSUITests/Scarf_iOSUITestsLaunchTests.swift
+33
View File
@@ -0,0 +1,33 @@
//
// Scarf_iOSUITestsLaunchTests.swift
// Scarf iOSUITests
//
// Created by Alan Wizemann on 4/23/26.
//
import XCTest
final class Scarf_iOSUITestsLaunchTests: XCTestCase {
override class var runsForEachTargetApplicationUIConfiguration: Bool {
true
}
override func setUpWithError() throws {
continueAfterFailure = false
}
@MainActor
func testLaunch() throws {
let app = XCUIApplication()
app.launch()
// Insert steps here to perform after app launch but before taking a screenshot,
// such as logging into a test account or navigating somewhere in the app
let attachment = XCTAttachment(screenshot: app.screenshot())
attachment.name = "Launch Screen"
attachment.lifetime = .keepAlways
add(attachment)
}
}
scarf/docs/ROADMAP.md
-53
View File
@@ -56,56 +56,3 @@ Rich usage analytics pulled from the sessions and messages SQLite tables:
### 10. Config Editor
- Structured form editor for config.yaml with validation
---
## Projects System Evolution (post-v2.2.1)
A parallel backlog specific to the Projects feature. Ordered by dependency: organization first, then per-project attribution via sidecar, then observability built on that attribution, then polish, then platform bets.
### Shipping in v2.3 (planned — plan file at `~/.claude/plans/`)
- **Folder hierarchy in the sidebar.** `ProjectEntry` gains optional `folder: String?`. `DisclosureGroup`-based sidebar.
- **Rename + archive + search.** Registry verbs + a fuzzy ⌘F search + soft-archive (`archived: Bool?`) with Show/Hide toggle.
- **⌘1–⌘9 project jumps.**
- **Per-project Sessions tab** alongside Dashboard / Site. Filters the global sessions list by a new `~/.hermes/scarf/session_project_map.json` sidecar that Scarf populates when it starts a chat with a project context.
- **New Chat button** on the Sessions tab — spawns `hermes acp` with `cwd = project.path` and attributes the resulting session in the sidecar.
### v2.4+ — per-project observability
Depends on v2.3's sidecar being stable. All features below are "filter the existing data by the sidecar's project mapping."
- **Per-project activity feed.** Extend `ActivityViewModel` with a `projectPath` filter that maps through the sidecar. Dashboard widget type `recent-activity`.
- **Per-project token / cost rollup.** `InsightsViewModel.computeAggregates()` already sums over sessions; add a project filter. Widget binding `project.tokens` exposes it to agent-driven dashboards.
- **Per-project cron-job filter.** Cron sidebar gains a project dropdown. Template-installed jobs already carry `[tmpl:<id>]` prefixes; match against installed template manifests to attribute.
- **Desktop notifications for cron completion.** When a project-attributed cron job finishes (success or failure), fire a `UNUserNotification`. Per-project mute.
### v2.5+ — platform bets
Bigger investments with longer arcs.
- **Hermes upstream: `sessions.cwd` column.** Propose adding a nullable `cwd` (or `workspace_id`) column to Hermes's sessions table, populated on session create. Scarf would prefer the canonical column when available and fall back to the sidecar for pre-upgrade sessions. Requires coordinated Hermes release; filed under platform bets because it cuts the sidecar's blind spot (CLI-started sessions never enter the sidecar today).
- **Per-project memory slice.** Hermes reads `MEMORY.md` from a known path. Explore whether Scarf can spawn `hermes acp` with an overridden memory path (per-project `<project>/.scarf/MEMORY.md`) so projects get isolated context. Needs a Hermes-side env var or flag.
- **Per-project skills namespace.** Today user-authored skills are flat under `~/.hermes/skills/`. A `~/.hermes/skills/project/<slug>/` namespace parallel to the existing `templates/` namespace would let users install skills *into* a project without a template. Uninstall = drop the folder.
- **Cross-project meta-dashboards.** A portfolio view that aggregates widgets from multiple projects — total token spend, combined activity feed, project-health matrix. Useful at 20+ projects.
- **Project backup / restore.** One-click zip of `<project>/` + sidecar entries + related Keychain secrets, restorable on another machine. Richer than the existing Export flow (which carries the template shape only).
### Continuous — UX polish
Small, shippable at any time. Each is a half-day-to-one-day item.
- **Drag-and-drop to reorder** projects within a folder and between folders. Would be the first use of `.onDrag`/`.onDrop` in the codebase; establishes the pattern.
- **Tags as a secondary axis.** Keep folders as primary, add multi-valued string tags + filter chips at the sidebar top. Decide only if folders feel insufficient after v2.3 lands.
- **Favorites / pin** — bubble a project to the top of its folder.
- **Recent projects collection** — auto-populated "Recents" row at the top of the sidebar.
- **Color labels or SF Symbol icons** per project (Finder-tag-style).
- **Project dashboard starter templates** — "blank", "monitor", "feed", "timeline" shapes when creating a bare project (distinct from `.scarftemplate` sharing flow).
- **Opportunistic session backfill.** When Scarf loads any session that isn't in the sidecar, peek at first tool call's `working_directory` or `cwd` hint; if it matches a registered project path, write a sidecar entry. Heuristic, not perfect — useful as an "it just works" improvement after v2.3 ships.
### Research / verification gaps
Noted during v2.3 planning; chase when relevant:
- `DisclosureGroup` inside `List(.sidebar)` on macOS — occasional animation glitches with many-rows-expanding. Early prototype will confirm before full commit.
- Concurrent sidecar writers from multiple Scarf windows on the same `~/.hermes` — atomic replace handles per-write; reload behavior may lag. Acceptable; revisit if users report stale attribution.
- Do Hermes sessions ever persist `cwd` anywhere in `state.db` today that we've missed? If so, we can skip the sidecar and use it directly. Worth a one-hour investigation before starting v2.4 observability work.
scarf/scarf.xcodeproj/project.pbxproj
+414 -13
View File
@@ -12,6 +12,20 @@
/* End PBXBuildFile section */
/* Begin PBXContainerItemProxy section */
4EAC233A2F99930100654F42 /* PBXContainerItemProxy */ = {
isa = PBXContainerItemProxy;
containerPortal = 534959382F7B83B600BD31AD /* Project object */;
proxyType = 1;
remoteGlobalIDString = 4EAC23282F99930000654F42;
remoteInfo = "Scarf iOS";
};
4EAC23442F99930100654F42 /* PBXContainerItemProxy */ = {
isa = PBXContainerItemProxy;
containerPortal = 534959382F7B83B600BD31AD /* Project object */;
proxyType = 1;
remoteGlobalIDString = 4EAC23282F99930000654F42;
remoteInfo = "Scarf iOS";
};
534959502F7B83B700BD31AD /* PBXContainerItemProxy */ = {
isa = PBXContainerItemProxy;
containerPortal = 534959382F7B83B600BD31AD /* Project object */;
@@ -29,12 +43,22 @@
/* End PBXContainerItemProxy section */
/* Begin PBXFileReference section */
4EAC23292F99930000654F42 /* scarf mobile.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "scarf mobile.app"; sourceTree = BUILT_PRODUCTS_DIR; };
4EAC23392F99930100654F42 /* Scarf iOSTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = "Scarf iOSTests.xctest"; sourceTree = BUILT_PRODUCTS_DIR; };
4EAC23432F99930100654F42 /* Scarf iOSUITests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = "Scarf iOSUITests.xctest"; sourceTree = BUILT_PRODUCTS_DIR; };
534959402F7B83B600BD31AD /* scarf.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = scarf.app; sourceTree = BUILT_PRODUCTS_DIR; };
5349594F2F7B83B700BD31AD /* scarfTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = scarfTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
534959592F7B83B700BD31AD /* scarfUITests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = scarfUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
/* End PBXFileReference section */
/* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
4EAC234B2F99930100654F42 /* Exceptions for "Scarf iOS" folder in "scarf mobile" target */ = {
isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
membershipExceptions = (
Info.plist,
);
target = 4EAC23282F99930000654F42 /* scarf mobile */;
};
534959AA2F7B83B600BD31AD /* Exceptions for "scarf" folder in "scarf" target */ = {
isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
membershipExceptions = (
@@ -45,6 +69,24 @@
/* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
/* Begin PBXFileSystemSynchronizedRootGroup section */
4EAC232A2F99930000654F42 /* Scarf iOS */ = {
isa = PBXFileSystemSynchronizedRootGroup;
exceptions = (
4EAC234B2F99930100654F42 /* Exceptions for "Scarf iOS" folder in "scarf mobile" target */,
);
path = "Scarf iOS";
sourceTree = "<group>";
};
4EAC233C2F99930100654F42 /* Scarf iOSTests */ = {
isa = PBXFileSystemSynchronizedRootGroup;
path = "Scarf iOSTests";
sourceTree = "<group>";
};
4EAC23462F99930100654F42 /* Scarf iOSUITests */ = {
isa = PBXFileSystemSynchronizedRootGroup;
path = "Scarf iOSUITests";
sourceTree = "<group>";
};
534959422F7B83B600BD31AD /* scarf */ = {
isa = PBXFileSystemSynchronizedRootGroup;
exceptions = (
@@ -66,6 +108,27 @@
/* End PBXFileSystemSynchronizedRootGroup section */
/* Begin PBXFrameworksBuildPhase section */
4EAC23262F99930000654F42 /* Frameworks */ = {
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
4EAC23362F99930100654F42 /* Frameworks */ = {
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
4EAC23402F99930100654F42 /* Frameworks */ = {
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
5349593D2F7B83B600BD31AD /* Frameworks */ = {
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
@@ -98,6 +161,9 @@
534959422F7B83B600BD31AD /* scarf */,
534959522F7B83B700BD31AD /* scarfTests */,
5349595C2F7B83B700BD31AD /* scarfUITests */,
4EAC232A2F99930000654F42 /* Scarf iOS */,
4EAC233C2F99930100654F42 /* Scarf iOSTests */,
4EAC23462F99930100654F42 /* Scarf iOSUITests */,
534959412F7B83B600BD31AD /* Products */,
);
sourceTree = "<group>";
@@ -108,6 +174,9 @@
534959402F7B83B600BD31AD /* scarf.app */,
5349594F2F7B83B700BD31AD /* scarfTests.xctest */,
534959592F7B83B700BD31AD /* scarfUITests.xctest */,
4EAC23292F99930000654F42 /* scarf mobile.app */,
4EAC23392F99930100654F42 /* Scarf iOSTests.xctest */,
4EAC23432F99930100654F42 /* Scarf iOSUITests.xctest */,
);
name = Products;
sourceTree = "<group>";
@@ -115,6 +184,74 @@
/* End PBXGroup section */
/* Begin PBXNativeTarget section */
4EAC23282F99930000654F42 /* scarf mobile */ = {
isa = PBXNativeTarget;
buildConfigurationList = 4EAC234C2F99930100654F42 /* Build configuration list for PBXNativeTarget "scarf mobile" */;
buildPhases = (
4EAC23252F99930000654F42 /* Sources */,
4EAC23262F99930000654F42 /* Frameworks */,
4EAC23272F99930000654F42 /* Resources */,
);
buildRules = (
);
dependencies = (
);
fileSystemSynchronizedGroups = (
4EAC232A2F99930000654F42 /* Scarf iOS */,
);
name = "scarf mobile";
packageProductDependencies = (
);
productName = "Scarf iOS";
productReference = 4EAC23292F99930000654F42 /* scarf mobile.app */;
productType = "com.apple.product-type.application";
};
4EAC23382F99930100654F42 /* Scarf iOSTests */ = {
isa = PBXNativeTarget;
buildConfigurationList = 4EAC234F2F99930100654F42 /* Build configuration list for PBXNativeTarget "Scarf iOSTests" */;
buildPhases = (
4EAC23352F99930100654F42 /* Sources */,
4EAC23362F99930100654F42 /* Frameworks */,
4EAC23372F99930100654F42 /* Resources */,
);
buildRules = (
);
dependencies = (
4EAC233B2F99930100654F42 /* PBXTargetDependency */,
);
fileSystemSynchronizedGroups = (
4EAC233C2F99930100654F42 /* Scarf iOSTests */,
);
name = "Scarf iOSTests";
packageProductDependencies = (
);
productName = "Scarf iOSTests";
productReference = 4EAC23392F99930100654F42 /* Scarf iOSTests.xctest */;
productType = "com.apple.product-type.bundle.unit-test";
};
4EAC23422F99930100654F42 /* Scarf iOSUITests */ = {
isa = PBXNativeTarget;
buildConfigurationList = 4EAC23522F99930100654F42 /* Build configuration list for PBXNativeTarget "Scarf iOSUITests" */;
buildPhases = (
4EAC233F2F99930100654F42 /* Sources */,
4EAC23402F99930100654F42 /* Frameworks */,
4EAC23412F99930100654F42 /* Resources */,
);
buildRules = (
);
dependencies = (
4EAC23452F99930100654F42 /* PBXTargetDependency */,
);
fileSystemSynchronizedGroups = (
4EAC23462F99930100654F42 /* Scarf iOSUITests */,
);
name = "Scarf iOSUITests";
packageProductDependencies = (
);
productName = "Scarf iOSUITests";
productReference = 4EAC23432F99930100654F42 /* Scarf iOSUITests.xctest */;
productType = "com.apple.product-type.bundle.ui-testing";
};
5349593F2F7B83B600BD31AD /* scarf */ = {
isa = PBXNativeTarget;
buildConfigurationList = 534959632F7B83B700BD31AD /* Build configuration list for PBXNativeTarget "scarf" */;
@@ -192,9 +329,20 @@
isa = PBXProject;
attributes = {
BuildIndependentTargetsInParallel = 1;
LastSwiftUpdateCheck = 2630;
LastSwiftUpdateCheck = 2620;
LastUpgradeCheck = 2630;
TargetAttributes = {
4EAC23282F99930000654F42 = {
CreatedOnToolsVersion = 26.2;
};
4EAC23382F99930100654F42 = {
CreatedOnToolsVersion = 26.2;
TestTargetID = 4EAC23282F99930000654F42;
};
4EAC23422F99930100654F42 = {
CreatedOnToolsVersion = 26.2;
TestTargetID = 4EAC23282F99930000654F42;
};
5349593F2F7B83B600BD31AD = {
CreatedOnToolsVersion = 26.3;
};
@@ -235,11 +383,35 @@
5349593F2F7B83B600BD31AD /* scarf */,
5349594E2F7B83B700BD31AD /* scarfTests */,
534959582F7B83B700BD31AD /* scarfUITests */,
4EAC23282F99930000654F42 /* scarf mobile */,
4EAC23382F99930100654F42 /* Scarf iOSTests */,
4EAC23422F99930100654F42 /* Scarf iOSUITests */,
);
};
/* End PBXProject section */
/* Begin PBXResourcesBuildPhase section */
4EAC23272F99930000654F42 /* Resources */ = {
isa = PBXResourcesBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
4EAC23372F99930100654F42 /* Resources */ = {
isa = PBXResourcesBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
4EAC23412F99930100654F42 /* Resources */ = {
isa = PBXResourcesBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
5349593E2F7B83B600BD31AD /* Resources */ = {
isa = PBXResourcesBuildPhase;
buildActionMask = 2147483647;
@@ -264,6 +436,27 @@
/* End PBXResourcesBuildPhase section */
/* Begin PBXSourcesBuildPhase section */
4EAC23252F99930000654F42 /* Sources */ = {
isa = PBXSourcesBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
4EAC23352F99930100654F42 /* Sources */ = {
isa = PBXSourcesBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
4EAC233F2F99930100654F42 /* Sources */ = {
isa = PBXSourcesBuildPhase;
buildActionMask = 2147483647;
files = (
);
runOnlyForDeploymentPostprocessing = 0;
};
5349593C2F7B83B600BD31AD /* Sources */ = {
isa = PBXSourcesBuildPhase;
buildActionMask = 2147483647;
@@ -288,6 +481,16 @@
/* End PBXSourcesBuildPhase section */
/* Begin PBXTargetDependency section */
4EAC233B2F99930100654F42 /* PBXTargetDependency */ = {
isa = PBXTargetDependency;
target = 4EAC23282F99930000654F42 /* scarf mobile */;
targetProxy = 4EAC233A2F99930100654F42 /* PBXContainerItemProxy */;
};
4EAC23452F99930100654F42 /* PBXTargetDependency */ = {
isa = PBXTargetDependency;
target = 4EAC23282F99930000654F42 /* scarf mobile */;
targetProxy = 4EAC23442F99930100654F42 /* PBXContainerItemProxy */;
};
534959512F7B83B700BD31AD /* PBXTargetDependency */ = {
isa = PBXTargetDependency;
target = 5349593F2F7B83B600BD31AD /* scarf */;
@@ -301,6 +504,175 @@
/* End PBXTargetDependency section */
/* Begin XCBuildConfiguration section */
4EAC234D2F99930100654F42 /* Debug */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
CODE_SIGN_ENTITLEMENTS = "Scarf iOS/Scarf_iOS.entitlements";
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
ENABLE_PREVIEWS = YES;
GENERATE_INFOPLIST_FILE = YES;
INFOPLIST_FILE = "Scarf iOS/Info.plist";
INFOPLIST_KEY_CFBundleDisplayName = "Scarf Mobile";
INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.developer-tools";
INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
INFOPLIST_KEY_UILaunchScreen_Generation = YES;
INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight";
INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight";
IPHONEOS_DEPLOYMENT_TARGET = 18.6;
LD_RUNPATH_SEARCH_PATHS = (
"$(inherited)",
"@executable_path/Frameworks",
);
MARKETING_VERSION = 1.0;
PRODUCT_BUNDLE_IDENTIFIER = "com.scarf-mobile.app";
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = iphoneos;
STRING_CATALOG_GENERATE_SYMBOLS = YES;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor;
SWIFT_EMIT_LOC_STRINGS = YES;
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
SWIFT_VERSION = 5.0;
TARGETED_DEVICE_FAMILY = "1,2";
};
name = Debug;
};
4EAC234E2F99930100654F42 /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
CODE_SIGN_ENTITLEMENTS = "Scarf iOS/Scarf_iOS.entitlements";
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
ENABLE_PREVIEWS = YES;
GENERATE_INFOPLIST_FILE = YES;
INFOPLIST_FILE = "Scarf iOS/Info.plist";
INFOPLIST_KEY_CFBundleDisplayName = "Scarf Mobile";
INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.developer-tools";
INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
INFOPLIST_KEY_UILaunchScreen_Generation = YES;
INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight";
INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight";
IPHONEOS_DEPLOYMENT_TARGET = 18.6;
LD_RUNPATH_SEARCH_PATHS = (
"$(inherited)",
"@executable_path/Frameworks",
);
MARKETING_VERSION = 1.0;
PRODUCT_BUNDLE_IDENTIFIER = "com.scarf-mobile.app";
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = iphoneos;
STRING_CATALOG_GENERATE_SYMBOLS = YES;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor;
SWIFT_EMIT_LOC_STRINGS = YES;
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
SWIFT_VERSION = 5.0;
TARGETED_DEVICE_FAMILY = "1,2";
VALIDATE_PRODUCT = YES;
};
name = Release;
};
4EAC23502F99930100654F42 /* Debug */ = {
isa = XCBuildConfiguration;
buildSettings = {
BUNDLE_LOADER = "$(TEST_HOST)";
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
IPHONEOS_DEPLOYMENT_TARGET = 26.2;
MARKETING_VERSION = 1.0;
PRODUCT_BUNDLE_IDENTIFIER = "alanwizemann.Scarf-iOSTests";
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = iphoneos;
STRING_CATALOG_GENERATE_SYMBOLS = NO;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_EMIT_LOC_STRINGS = NO;
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
SWIFT_VERSION = 5.0;
TARGETED_DEVICE_FAMILY = "1,2";
TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Scarf iOS.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Scarf iOS";
};
name = Debug;
};
4EAC23512F99930100654F42 /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
BUNDLE_LOADER = "$(TEST_HOST)";
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
IPHONEOS_DEPLOYMENT_TARGET = 26.2;
MARKETING_VERSION = 1.0;
PRODUCT_BUNDLE_IDENTIFIER = "alanwizemann.Scarf-iOSTests";
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = iphoneos;
STRING_CATALOG_GENERATE_SYMBOLS = NO;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_EMIT_LOC_STRINGS = NO;
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
SWIFT_VERSION = 5.0;
TARGETED_DEVICE_FAMILY = "1,2";
TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Scarf iOS.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Scarf iOS";
VALIDATE_PRODUCT = YES;
};
name = Release;
};
4EAC23532F99930100654F42 /* Debug */ = {
isa = XCBuildConfiguration;
buildSettings = {
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
IPHONEOS_DEPLOYMENT_TARGET = 26.2;
MARKETING_VERSION = 1.0;
PRODUCT_BUNDLE_IDENTIFIER = "alanwizemann.Scarf-iOSUITests";
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = iphoneos;
STRING_CATALOG_GENERATE_SYMBOLS = NO;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_EMIT_LOC_STRINGS = NO;
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
SWIFT_VERSION = 5.0;
TARGETED_DEVICE_FAMILY = "1,2";
TEST_TARGET_NAME = "Scarf iOS";
};
name = Debug;
};
4EAC23542F99930100654F42 /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
IPHONEOS_DEPLOYMENT_TARGET = 26.2;
MARKETING_VERSION = 1.0;
PRODUCT_BUNDLE_IDENTIFIER = "alanwizemann.Scarf-iOSUITests";
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = iphoneos;
STRING_CATALOG_GENERATE_SYMBOLS = NO;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_EMIT_LOC_STRINGS = NO;
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
SWIFT_VERSION = 5.0;
TARGETED_DEVICE_FAMILY = "1,2";
TEST_TARGET_NAME = "Scarf iOS";
VALIDATE_PRODUCT = YES;
};
name = Release;
};
534959612F7B83B700BD31AD /* Debug */ = {
isa = XCBuildConfiguration;
buildSettings = {
@@ -436,7 +808,7 @@
CODE_SIGN_ENTITLEMENTS = scarf/scarf.entitlements;
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
CURRENT_PROJECT_VERSION = 24;
CURRENT_PROJECT_VERSION = 22;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
ENABLE_APP_SANDBOX = NO;
@@ -444,12 +816,13 @@
ENABLE_PREVIEWS = YES;
GENERATE_INFOPLIST_FILE = NO;
INFOPLIST_FILE = scarf/Info.plist;
INFOPLIST_KEY_CFBundleDisplayName = Scarf;
LD_RUNPATH_SEARCH_PATHS = (
"$(inherited)",
"@executable_path/../Frameworks",
);
MACOSX_DEPLOYMENT_TARGET = 14.6;
MARKETING_VERSION = 2.2.1;
MARKETING_VERSION = 2.1.0;
PRODUCT_BUNDLE_IDENTIFIER = com.scarf.app;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -471,7 +844,7 @@
CODE_SIGN_ENTITLEMENTS = scarf/scarf.entitlements;
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
CURRENT_PROJECT_VERSION = 24;
CURRENT_PROJECT_VERSION = 22;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
ENABLE_APP_SANDBOX = NO;
@@ -479,12 +852,13 @@
ENABLE_PREVIEWS = YES;
GENERATE_INFOPLIST_FILE = NO;
INFOPLIST_FILE = scarf/Info.plist;
INFOPLIST_KEY_CFBundleDisplayName = Scarf;
LD_RUNPATH_SEARCH_PATHS = (
"$(inherited)",
"@executable_path/../Frameworks",
);
MACOSX_DEPLOYMENT_TARGET = 14.6;
MARKETING_VERSION = 2.2.1;
MARKETING_VERSION = 2.1.0;
PRODUCT_BUNDLE_IDENTIFIER = com.scarf.app;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -502,12 +876,12 @@
buildSettings = {
BUNDLE_LOADER = "$(TEST_HOST)";
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 24;
CURRENT_PROJECT_VERSION = 22;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
MACOSX_DEPLOYMENT_TARGET = 26.2;
MARKETING_VERSION = 2.2.1;
MARKETING_VERSION = 2.1.0;
PRODUCT_BUNDLE_IDENTIFIER = com.scarfTests;
PRODUCT_NAME = "$(TARGET_NAME)";
STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -524,12 +898,12 @@
buildSettings = {
BUNDLE_LOADER = "$(TEST_HOST)";
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 24;
CURRENT_PROJECT_VERSION = 22;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
MACOSX_DEPLOYMENT_TARGET = 26.2;
MARKETING_VERSION = 2.2.1;
MARKETING_VERSION = 2.1.0;
PRODUCT_BUNDLE_IDENTIFIER = com.scarfTests;
PRODUCT_NAME = "$(TARGET_NAME)";
STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -545,11 +919,11 @@
isa = XCBuildConfiguration;
buildSettings = {
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 24;
CURRENT_PROJECT_VERSION = 22;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
MARKETING_VERSION = 2.2.1;
MARKETING_VERSION = 2.1.0;
PRODUCT_BUNDLE_IDENTIFIER = com.scarfUITests;
PRODUCT_NAME = "$(TARGET_NAME)";
STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -565,11 +939,11 @@
isa = XCBuildConfiguration;
buildSettings = {
CODE_SIGN_STYLE = Automatic;
CURRENT_PROJECT_VERSION = 24;
CURRENT_PROJECT_VERSION = 22;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 3Q6X2L86C4;
GENERATE_INFOPLIST_FILE = YES;
MARKETING_VERSION = 2.2.1;
MARKETING_VERSION = 2.1.0;
PRODUCT_BUNDLE_IDENTIFIER = com.scarfUITests;
PRODUCT_NAME = "$(TARGET_NAME)";
STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -584,6 +958,33 @@
/* End XCBuildConfiguration section */
/* Begin XCConfigurationList section */
4EAC234C2F99930100654F42 /* Build configuration list for PBXNativeTarget "scarf mobile" */ = {
isa = XCConfigurationList;
buildConfigurations = (
4EAC234D2F99930100654F42 /* Debug */,
4EAC234E2F99930100654F42 /* Release */,
);
defaultConfigurationIsVisible = 0;
defaultConfigurationName = Release;
};
4EAC234F2F99930100654F42 /* Build configuration list for PBXNativeTarget "Scarf iOSTests" */ = {
isa = XCConfigurationList;
buildConfigurations = (
4EAC23502F99930100654F42 /* Debug */,
4EAC23512F99930100654F42 /* Release */,
);
defaultConfigurationIsVisible = 0;
defaultConfigurationName = Release;
};
4EAC23522F99930100654F42 /* Build configuration list for PBXNativeTarget "Scarf iOSUITests" */ = {
isa = XCConfigurationList;
buildConfigurations = (
4EAC23532F99930100654F42 /* Debug */,
4EAC23542F99930100654F42 /* Release */,
);
defaultConfigurationIsVisible = 0;
defaultConfigurationName = Release;
};
5349593B2F7B83B600BD31AD /* Build configuration list for PBXProject "scarf" */ = {
isa = XCConfigurationList;
buildConfigurations = (
scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-1024x1024@1x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 MiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-128x128@1x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-128x128@2x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 274 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-16x16@1x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 962 B

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-16x16@2x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-256x256@1x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 274 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-32x32@1x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-32x32@2x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-512x512@1x 1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-iOS-Default-512x512@1x.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-1024x1024@1x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.9 MiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-128x128@1x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 55 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-128x128@2x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 201 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-16x16@1x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 864 B

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-16x16@2x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.5 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-256x256@1x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 195 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-256x256@2x 1.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 742 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-32x32@1x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.3 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-32x32@2x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/AW Mac OS Applications-macOS-Default-512x512@1x.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 742 KiB

scarf/scarf/Assets.xcassets/AppIcon.appiconset/Contents.json
+10 -10
View File
@@ -1,61 +1,61 @@
{
"images" : [
{
"filename" : "AW Mac OS Applications-macOS-Default-16x16@1x.png",
"filename" : "AW Mac OS Applications-iOS-Default-16x16@1x.png",
"idiom" : "mac",
"scale" : "1x",
"size" : "16x16"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-16x16@2x.png",
"filename" : "AW Mac OS Applications-iOS-Default-16x16@2x.png",
"idiom" : "mac",
"scale" : "2x",
"size" : "16x16"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-32x32@1x.png",
"filename" : "AW Mac OS Applications-iOS-Default-32x32@1x.png",
"idiom" : "mac",
"scale" : "1x",
"size" : "32x32"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-32x32@2x.png",
"filename" : "AW Mac OS Applications-iOS-Default-32x32@2x.png",
"idiom" : "mac",
"scale" : "2x",
"size" : "32x32"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-128x128@1x.png",
"filename" : "AW Mac OS Applications-iOS-Default-128x128@1x.png",
"idiom" : "mac",
"scale" : "1x",
"size" : "128x128"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-128x128@2x.png",
"filename" : "AW Mac OS Applications-iOS-Default-128x128@2x.png",
"idiom" : "mac",
"scale" : "2x",
"size" : "128x128"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-256x256@1x.png",
"filename" : "AW Mac OS Applications-iOS-Default-256x256@1x.png",
"idiom" : "mac",
"scale" : "1x",
"size" : "256x256"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-256x256@2x 1.png",
"filename" : "AW Mac OS Applications-iOS-Default-512x512@1x 1.png",
"idiom" : "mac",
"scale" : "2x",
"size" : "256x256"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-512x512@1x.png",
"filename" : "AW Mac OS Applications-iOS-Default-512x512@1x.png",
"idiom" : "mac",
"scale" : "1x",
"size" : "512x512"
},
{
"filename" : "AW Mac OS Applications-macOS-Default-1024x1024@1x.png",
"filename" : "AW Mac OS Applications-iOS-Default-1024x1024@1x.png",
"idiom" : "mac",
"scale" : "2x",
"size" : "512x512"
scarf/scarf/Core/Models/HermesPathSet.swift
-12
View File
@@ -55,18 +55,6 @@ struct HermesPathSet: Sendable, Hashable {
nonisolated var gatewayLog: String { home + "/logs/gateway.log" }
nonisolated var scarfDir: String { home + "/scarf" }
nonisolated var projectsRegistry: String { scarfDir + "/projects.json" }
/// Maps Hermes session IDs to the Scarf project path a chat was
/// started for. Written by `SessionAttributionService` when
/// Scarf spawns `hermes acp` with a project-scoped cwd; read by
/// the per-project Sessions tab (v2.3) to filter the session list
/// to just those attributed to a given project.
///
/// Scarf-owned — Hermes never touches this file. Forward-only:
/// we only attribute sessions Scarf creates in a project context;
/// older / CLI-started sessions stay unattributed and surface in
/// the global Sessions sidebar unchanged.
nonisolated var sessionProjectMap: String { scarfDir + "/session_project_map.json" }
nonisolated var mcpTokensDir: String { home + "/mcp-tokens" }
// MARK: - Binary resolution
scarf/scarf/Core/Models/ProjectDashboard.swift
-56
View File
@@ -11,63 +11,7 @@ struct ProjectEntry: Codable, Sendable, Identifiable, Hashable {
let name: String
let path: String
/// Folder path for sidebar grouping. `nil` means top-level (no
/// folder). Introduced in v2.3 — v2.2 registry files have no
/// `folder` key, which decodes cleanly as `nil` via
/// `decodeIfPresent` below.
///
/// We leave shape flexible: today this is treated as an opaque
/// single-level label (e.g. "Clients"), and the sidebar renders
/// one DisclosureGroup per distinct value. If nesting becomes a
/// requirement later, we can interpret the string as a slash-
/// separated path without a migration (old single-label values
/// still mean a top-level folder with that name).
var folder: String?
/// Soft-archive flag. Archived projects are hidden from the
/// sidebar by default; a Show Archived toggle surfaces them.
/// Non-destructive — nothing is deleted on disk. Introduced in
/// v2.3; v2.2 registry files default to `false` via the custom
/// decoder below.
var archived: Bool
var dashboardPath: String { path + "/.scarf/dashboard.json" }
init(name: String, path: String, folder: String? = nil, archived: Bool = false) {
self.name = name
self.path = path
self.folder = folder
self.archived = archived
}
// MARK: - Codable (custom for backward compat)
private enum CodingKeys: String, CodingKey {
case name, path, folder, archived
}
init(from decoder: Decoder) throws {
let c = try decoder.container(keyedBy: CodingKeys.self)
self.name = try c.decode(String.self, forKey: .name)
self.path = try c.decode(String.self, forKey: .path)
// Both new fields: tolerate absence for v2.2-era registries.
self.folder = try c.decodeIfPresent(String.self, forKey: .folder)
self.archived = try c.decodeIfPresent(Bool.self, forKey: .archived) ?? false
}
func encode(to encoder: Encoder) throws {
var c = encoder.container(keyedBy: CodingKeys.self)
try c.encode(name, forKey: .name)
try c.encode(path, forKey: .path)
// Only emit optional fields when they carry meaning — keeps
// registry files clean for the common (top-level, unarchived)
// case and means v2.2 Scarf can still load a v2.3-written
// registry of projects that never used the new features.
try c.encodeIfPresent(folder, forKey: .folder)
if archived {
try c.encode(archived, forKey: .archived)
}
}
}
// MARK: - Dashboard
scarf/scarf/Core/Models/SessionProjectMap.swift
-43
View File
@@ -1,43 +0,0 @@
import Foundation
/// Scarf-owned sidecar mapping Hermes session IDs to the Scarf
/// project path a chat was started for. Written on session create
/// when Scarf spawns `hermes acp` with a project-scoped cwd; read
/// by the per-project Sessions tab.
///
/// Hermes's own `state.db` has no `cwd` column on the sessions
/// table — the cwd is passed at runtime via ACP but not persisted
/// on its side. This sidecar is how we recover the attribution
/// without requiring an upstream schema change.
///
/// Stored at `~/.hermes/scarf/session_project_map.json`. Forward-
/// compatible: if Hermes ever gains a canonical `cwd` column, Scarf
/// can prefer that and fall back to this file for pre-upgrade
/// sessions. Missing file → empty map (nothing attributed yet).
struct SessionProjectMap: Codable, Sendable {
/// session-id → absolute-project-path. Both strings are opaque
/// from this file's perspective; the service validates project
/// paths against the live registry when building the reverse
/// lookup used by the Sessions tab, so stale entries for
/// removed projects are ignored at read time without needing a
/// write-side cleanup.
var mappings: [String: String]
/// ISO-8601 timestamp of the most recent write. Informational
/// only — not used for any decision logic. Useful when debugging
/// a stale sidecar ("when was this last updated?").
var updatedAt: String?
init(mappings: [String: String] = [:], updatedAt: String? = nil) {
self.mappings = mappings
self.updatedAt = updatedAt
}
/// Current time in ISO-8601 format, suitable for the
/// `updatedAt` field. Matches the format used elsewhere in
/// Scarf (e.g. `TemplateLock.installedAt`) so tooling that
/// greps across .json files sees consistent timestamps.
static func nowISO8601() -> String {
ISO8601DateFormatter().string(from: Date())
}
}
scarf/scarf/Core/Persistence/ServerRegistry.swift
+1 -5
View File
@@ -82,11 +82,6 @@ final class ServerRegistry {
/// Flip the default server to `id`. Passing `ServerContext.local.id`
/// clears the flag on every remote entry, making Local the implicit
/// default. Passing an unknown ID is a no-op. Persisted on return.
///
/// Intentionally doesn't fire `onEntriesChanged` — that hook means "the
/// set of servers changed" and drives the menu-bar fanout rebuild. A
/// default-flag flip doesn't change the set; SwiftUI views reading
/// `defaultServerID` redraw via `@Observable`'s tracking of `entries`.
func setDefaultServer(_ id: ServerID) {
var changed = false
for idx in entries.indices {
@@ -98,6 +93,7 @@ final class ServerRegistry {
}
if changed {
save()
onEntriesChanged?()
}
}
scarf/scarf/Core/Services/HermesFileWatcher.swift
-10
View File
@@ -35,16 +35,6 @@ final class HermesFileWatcher {
paths.errorsLog,
paths.gatewayLog,
paths.projectsRegistry,
// v2.3: sidecar attributing Hermes session IDs to Scarf project
// paths. Written by SessionAttributionService when a chat
// starts with a project context; read by
// ProjectSessionsViewModel to filter the session list. Without
// watching this file, the per-project Sessions tab would only
// pick up new sessions when the user re-entered the tab
// (triggering .task(id:) re-fire) — switching directly back
// to the project's Sessions tab after a chat left the tab
// stale.
paths.sessionProjectMap,
paths.mcpTokensDir
]
}
scarf/scarf/Core/Services/ProjectAgentContextService.swift
-293
View File
@@ -1,293 +0,0 @@
import Foundation
import os
/// Writes a Scarf-managed marker block into `<project>/AGENTS.md` so
/// that Hermes — which auto-reads `AGENTS.md` from the session's cwd
/// at startup — has consistent project identity and metadata in every
/// project-scoped chat.
///
/// **Why this exists.** Hermes has no native "project" concept and ACP
/// passes only `(cwd, mcpServers)` at session create — extra params
/// are silently dropped on Hermes's side. The documented hook for
/// giving the agent context when cwd is set programmatically is the
/// auto-load of `AGENTS.md` (or `.hermes.md` / `CLAUDE.md` /
/// `.cursorrules`, in that priority) from the cwd. Scarf owns a
/// managed region of the project's AGENTS.md; template-author content
/// lives outside that region and is preserved.
///
/// **Marker contract.** The region sits between:
///
/// ```
/// <!-- scarf-project:begin -->
/// …Scarf-managed content…
/// <!-- scarf-project:end -->
/// ```
///
/// Same pattern as the v2.2 memory-block appendix — bounded, self-
/// declaring, safe to re-generate. Everything outside the markers is
/// left byte-identical across refreshes.
///
/// **Secret-safe.** The block surfaces field NAMES from `config.json`
/// (via the cached manifest's schema) but never VALUES. A rendered
/// block contains no secrets even for a project whose config.json
/// has Keychain-ref URIs.
///
/// **Refresh timing.** `ChatViewModel.startACPSession(resume:projectPath:)`
/// calls `refresh(for:)` immediately before Hermes opens the session.
/// Hermes reads AGENTS.md during session boot, so the marker block
/// must have landed on disk first. Non-blocking on failure — a
/// failed refresh logs and the chat proceeds without the block.
struct ProjectAgentContextService: Sendable {
private static let logger = Logger(subsystem: "com.scarf", category: "ProjectAgentContextService")
/// Marker strings. Load-bearing: the format must stay stable
/// across releases so existing project AGENTS.md files continue
/// to be recognized and rewritten cleanly.
static let beginMarker = "<!-- scarf-project:begin -->"
static let endMarker = "<!-- scarf-project:end -->"
let context: ServerContext
nonisolated init(context: ServerContext = .local) {
self.context = context
}
// MARK: - Public
/// Refresh (or create) the Scarf-managed block in the project's
/// AGENTS.md. Reads current project state — template manifest,
/// config schema, registered cron jobs — and produces a block
/// reflecting today's truth. Idempotent: two consecutive calls
/// with no intervening state change produce byte-identical
/// output.
nonisolated func refresh(for project: ProjectEntry) throws {
let block = renderBlock(for: project)
let path = agentsMdPath(for: project)
let transport = context.makeTransport()
// Ensure the project directory exists — this service is the
// first thing that touches the project dir when the user
// scaffolds a bare project via `+` + starts a chat. Normally
// the dir exists (registered project = dir exists); belt-
// and-suspenders for edge cases.
if !transport.fileExists(project.path) {
try transport.createDirectory(project.path)
}
if !transport.fileExists(path) {
// Fresh AGENTS.md with just our block + a trailing
// newline so editors render it cleanly.
let data = (block + "\n").data(using: .utf8) ?? Data()
try transport.writeFile(path, data: data)
Self.logger.info("created AGENTS.md with Scarf block for \(project.name, privacy: .public)")
return
}
// Read existing, splice in the new block.
let existingData = try transport.readFile(path)
let existing = String(data: existingData, encoding: .utf8) ?? ""
let rewritten = Self.applyBlock(block: block, to: existing)
guard let outData = rewritten.data(using: .utf8) else {
throw ProjectAgentContextError.encodingFailed
}
// Skip the write when nothing changed — avoids unnecessary
// file-watcher churn. Matches what disk snapshot shows.
guard outData != existingData else { return }
try transport.writeFile(path, data: outData)
Self.logger.info("refreshed Scarf block in AGENTS.md for \(project.name, privacy: .public)")
}
// MARK: - Marker splice (testable in isolation)
/// Core text transform: given an existing file and a freshly-
/// rendered block, return the file with the block spliced in.
///
/// Three cases handled:
/// 1. Existing file has both markers → replace the inclusive
/// region, preserve everything outside untouched.
/// 2. Existing file has no markers → prepend the block followed
/// by a two-newline separator so it reads as its own section.
/// 3. Existing file has a begin marker but no end → we DON'T try
/// to be clever; treat as "no markers present" and prepend.
/// User intervention or a later refresh can restore shape.
/// The stray begin-marker is left in the file; we don't
/// truncate to EOF (as the memory-block installer does)
/// because an orphaned begin on this file is more likely
/// hand-typed than a corrupt Scarf write.
nonisolated static func applyBlock(block: String, to existing: String) -> String {
guard let beginRange = existing.range(of: beginMarker),
let endRange = existing.range(
of: endMarker,
range: beginRange.upperBound..<existing.endIndex
)
else {
// No well-formed Scarf block present — prepend.
let trimmedExisting = existing.trimmingCharacters(in: .whitespacesAndNewlines)
if trimmedExisting.isEmpty {
return block + "\n"
}
return block + "\n\n" + existing
}
// Full span: from the begin marker through the end marker
// (inclusive). Consumes any trailing whitespace/newlines
// immediately following the end marker so a re-render of a
// shorter block doesn't leave a dangling blank line.
var upperBound = endRange.upperBound
while upperBound < existing.endIndex,
existing[upperBound].isNewline {
upperBound = existing.index(after: upperBound)
}
let before = String(existing[existing.startIndex..<beginRange.lowerBound])
let after = String(existing[upperBound..<existing.endIndex])
// Preserve the leading whitespace / content structure of
// `before` but ensure exactly one blank line separates it
// from the new block when there IS prior content.
let prefix = before.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
? ""
: before.trimmingRightNewlines() + "\n\n"
// Suffix: a blank line BEFORE the remaining content, ensuring
// the template/user content is visually separated from the
// Scarf block.
let suffix = after.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
? "\n"
: "\n\n" + after.trimmingLeftNewlines()
return prefix + block + suffix
}
// MARK: - Block rendering
/// Build the Markdown block for a given project. Pure function of
/// project state — exposed for tests that want to assert on
/// rendered content without touching disk.
nonisolated func renderBlock(for project: ProjectEntry) -> String {
let templateInfo = readTemplateInfo(for: project)
let configFieldsLine = renderConfigFieldsLine(for: project)
let cronLines = renderCronLines(for: project, templateId: templateInfo?.id)
let lockFilePresent = context.makeTransport().fileExists(
project.path + "/.scarf/template.lock.json"
)
var lines: [String] = []
lines.append(Self.beginMarker)
lines.append("## Scarf project context")
lines.append("")
lines.append("_Auto-generated by Scarf — do not edit between the begin/end markers._")
lines.append("")
lines.append("You are operating inside a Scarf project named **\"\(project.name)\"**. Scarf is a macOS GUI for Hermes; the user is working with this project through it. This chat session's working directory is the project's directory — path-relative tool calls resolve inside the project.")
lines.append("")
lines.append("- **Project directory:** `\(project.path)`")
lines.append("- **Dashboard:** `\(project.path)/.scarf/dashboard.json`")
if let tpl = templateInfo {
lines.append("- **Template:** `\(tpl.id)` v\(tpl.version)")
}
lines.append("- **Configuration fields:** \(configFieldsLine)")
if cronLines.isEmpty {
lines.append("- **Registered cron jobs:** (none attributed to this project)")
} else {
lines.append("- **Registered cron jobs:**")
for line in cronLines {
lines.append(" - \(line)")
}
}
if lockFilePresent {
lines.append("- **Uninstall manifest:** `\(project.path)/.scarf/template.lock.json` (tracks files written by template install)")
}
lines.append("")
lines.append("Any content below this block is template- or user-authored; preserve and defer to it for project-specific behavior. Do NOT modify content inside these markers — Scarf rewrites this block on every project-scoped chat start.")
lines.append(Self.endMarker)
return lines.joined(separator: "\n")
}
// MARK: - Helpers
nonisolated private func agentsMdPath(for project: ProjectEntry) -> String {
project.path + "/AGENTS.md"
}
/// Read `<project>/.scarf/manifest.json` for template id + version.
/// Nil when not present (bare project) or when the file is
/// unparseable — the block still renders cleanly without the
/// template line.
nonisolated private func readTemplateInfo(for project: ProjectEntry) -> (id: String, version: String)? {
let manifestPath = project.path + "/.scarf/manifest.json"
let transport = context.makeTransport()
guard transport.fileExists(manifestPath) else { return nil }
guard let data = try? transport.readFile(manifestPath) else { return nil }
guard let manifest = try? JSONDecoder().decode(ProjectTemplateManifest.self, from: data) else { return nil }
return (id: manifest.id, version: manifest.version)
}
/// Build the "Configuration fields" bullet's tail. Returns a
/// comma-joined list of backticked field names with inline type
/// hints (`(secret)`), or the literal string "(none)" when the
/// project has no config schema. **Never** includes values.
nonisolated private func renderConfigFieldsLine(for project: ProjectEntry) -> String {
let manifestPath = project.path + "/.scarf/manifest.json"
let transport = context.makeTransport()
guard transport.fileExists(manifestPath),
let data = try? transport.readFile(manifestPath),
let manifest = try? JSONDecoder().decode(ProjectTemplateManifest.self, from: data),
let schema = manifest.config,
!schema.fields.isEmpty
else {
return "(none)"
}
let fieldList = schema.fields.map { field -> String in
let secretTag = field.type == .secret ? " (secret — name only, value stored in Keychain)" : ""
return "`\(field.key)`\(secretTag)"
}
return fieldList.joined(separator: ", ")
}
/// Return a list of human-readable cron-job descriptions for jobs
/// attributed to this project via the `[tmpl:<id>] …` name prefix.
/// Empty array when no jobs match (either the project has no
/// template or no jobs carry the tag).
nonisolated private func renderCronLines(for project: ProjectEntry, templateId: String?) -> [String] {
guard let templateId else { return [] }
let prefix = "[tmpl:\(templateId)]"
let jobs = HermesFileService(context: context).loadCronJobs()
return jobs
.filter { $0.name.hasPrefix(prefix) }
.map { job in
let scheduleDesc = job.schedule.display
?? job.schedule.expression
?? job.schedule.kind
let pausedDesc = job.enabled ? "enabled" : "paused"
return "`\(job.name)` — schedule `\(scheduleDesc)`, currently \(pausedDesc)"
}
}
}
enum ProjectAgentContextError: Error {
case encodingFailed
}
// MARK: - String helpers (file-scoped)
private extension String {
/// Drop trailing newlines + CRs but preserve other trailing
/// whitespace (tabs, non-breaking spaces) that might be
/// meaningful in some edge case.
func trimmingRightNewlines() -> String {
var result = self
while let last = result.last, last.isNewline {
result.removeLast()
}
return result
}
/// Symmetric counterpart: strip leading newlines / CRs.
func trimmingLeftNewlines() -> String {
var result = self
while let first = result.first, first.isNewline {
result.removeFirst()
}
return result
}
}
scarf/scarf/Core/Services/SessionAttributionService.swift
-115
View File
@@ -1,115 +0,0 @@
import Foundation
import os
/// Owns the sidecar that attributes Hermes session IDs to Scarf
/// project paths. The `cwd` passed to `hermes acp` at session
/// creation is ephemeral from Hermes's perspective (not written to
/// `state.db`), so Scarf keeps this Scarf-owned record parallel to
/// Hermes's session store.
///
/// File: `~/.hermes/scarf/session_project_map.json` (resolved via
/// `HermesPathSet.sessionProjectMap`).
///
/// Thread safety: all public methods are `nonisolated` and each
/// performs a single read-modify-write cycle that's atomic on
/// disk. Concurrent writers (two Scarf windows on the same
/// `~/.hermes`) are safe at the file level — last write wins —
/// but the in-memory read in one window may lag until that window
/// reloads. Acceptable for v2.3's scale; revisit if multi-window
/// cross-talk becomes a problem.
struct SessionAttributionService: Sendable {
private static let logger = Logger(subsystem: "com.scarf", category: "SessionAttributionService")
let context: ServerContext
nonisolated init(context: ServerContext = .local) {
self.context = context
}
// MARK: - Read
/// Load the current sidecar contents. Missing file or unparseable
/// JSON returns an empty map — the sidecar is a convenience
/// index, not a source of truth for anything load-bearing.
nonisolated func load() -> SessionProjectMap {
let path = context.paths.sessionProjectMap
let transport = context.makeTransport()
guard transport.fileExists(path) else {
return SessionProjectMap()
}
do {
let data = try transport.readFile(path)
return try JSONDecoder().decode(SessionProjectMap.self, from: data)
} catch {
Self.logger.warning("session-project-map parse failed at \(path, privacy: .public): \(error.localizedDescription, privacy: .public); returning empty map")
return SessionProjectMap()
}
}
/// Look up the project path a given session was attributed to.
/// Returns nil for unattributed sessions (CLI-started, or
/// started before v2.3) — those surface in the global Sessions
/// sidebar unchanged and don't appear in any project's Sessions
/// tab.
nonisolated func projectPath(for sessionID: String) -> String? {
load().mappings[sessionID]
}
/// Reverse lookup: every session ID attributed to the given
/// project path. Used by the per-project Sessions tab to filter
/// the global session list. Comparison is exact-string; the
/// registry stores absolute paths and we write absolute paths,
/// so no normalisation is needed in practice.
nonisolated func sessionIDs(forProject projectPath: String) -> Set<String> {
let map = load()
return Set(map.mappings.filter { $0.value == projectPath }.keys)
}
// MARK: - Write
/// Record that `sessionID` was created under the given project
/// path. Idempotent — repeated calls for the same pair are no-
/// ops. Replacing an existing mapping (session moved to a
/// different project) is legal but expected to be rare; the
/// caller decides when that's correct.
nonisolated func attribute(sessionID: String, toProjectPath projectPath: String) {
var map = load()
if map.mappings[sessionID] == projectPath {
return
}
map.mappings[sessionID] = projectPath
map.updatedAt = SessionProjectMap.nowISO8601()
persist(map)
}
/// Remove a mapping. Called in v2.3's Sessions-tab code path is
/// minimal — we don't currently prune on session delete because
/// Hermes owns session lifecycle and we don't observe deletes.
/// Exposed for future roadmap items (e.g. explicit "detach
/// from project" action) and tests.
nonisolated func forget(sessionID: String) {
var map = load()
guard map.mappings.removeValue(forKey: sessionID) != nil else { return }
map.updatedAt = SessionProjectMap.nowISO8601()
persist(map)
}
// MARK: - Private
private func persist(_ map: SessionProjectMap) {
let path = context.paths.sessionProjectMap
let transport = context.makeTransport()
let dir = context.paths.scarfDir
do {
if !transport.fileExists(dir) {
try transport.createDirectory(dir)
}
let encoder = JSONEncoder()
encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
let data = try encoder.encode(map)
try transport.writeFile(path, data: data)
} catch {
Self.logger.error("failed to persist session-project-map at \(path, privacy: .public): \(error.localizedDescription, privacy: .public)")
}
}
}
scarf/scarf/Features/Chat/ViewModels/ChatViewModel.swift
+4 -97
View File
@@ -41,20 +41,6 @@ final class ChatViewModel {
let richChatViewModel: RichChatViewModel
private var coordinator: Coordinator?
/// Absolute project path for the current session, when the chat is
/// project-scoped (either started via a project's "New Chat" button
/// or resumed from a session that was previously attributed via the
/// v2.3 sidecar). Nil for plain global chats. Drives the project
/// indicator in SessionInfoBar + the `Chat · <Name>` nav title.
private(set) var currentProjectPath: String?
/// Human-readable name of the active project, resolved from the
/// projects registry at session-start time. Stored alongside the
/// path so the view renders without hitting disk on every update.
/// Nil when `currentProjectPath` is nil OR the path isn't in the
/// registry (project was removed after the session was attributed).
private(set) var currentProjectName: String?
// ACP state
private var acpClient: ACPClient?
private var acpEventTask: Task<Void, Never>?
@@ -132,20 +118,15 @@ final class ChatViewModel {
// MARK: - Session Lifecycle
func startNewSession(projectPath: String? = nil) {
func startNewSession() {
voiceEnabled = false
ttsEnabled = false
isRecording = false
richChatViewModel.reset()
if displayMode == .richChat {
startACPSession(resume: nil, projectPath: projectPath)
startACPSession(resume: nil)
} else {
// Terminal mode doesn't surface project attribution today —
// `hermes chat` uses the shell's cwd, so starting a terminal
// chat from a project button would require changing the
// shell's cwd too. Out of scope for v2.3 — Rich Chat is
// the primary surface for project-scoped sessions.
launchTerminal(arguments: ["chat"])
}
}
@@ -308,33 +289,13 @@ final class ChatViewModel {
// MARK: - ACP Session Management
private func startACPSession(resume sessionId: String?, projectPath: String? = nil) {
private func startACPSession(resume sessionId: String?) {
stopACP()
clearACPErrorState()
acpStatus = "Starting..."
let client = ACPClient(context: context)
self.acpClient = client
let attribution = SessionAttributionService(context: context)
// If the caller passed a project path, refresh the Scarf-
// managed block in the project's AGENTS.md BEFORE starting
// ACP — Hermes auto-reads AGENTS.md at session boot, so the
// block has to land on disk first. Non-blocking on failure:
// we log and proceed without the block. Safe on bare
// projects (creates AGENTS.md with just the block); safe on
// template-installed projects (splices the block into
// existing AGENTS.md without touching template content).
if let projectPath {
let registry = ProjectDashboardService(context: context).loadRegistry()
if let project = registry.projects.first(where: { $0.path == projectPath }) {
do {
try ProjectAgentContextService(context: context).refresh(for: project)
} catch {
logger.warning("couldn't refresh project context block for \(project.name): \(error.localizedDescription)")
}
}
}
Task { @MainActor in
do {
@@ -344,19 +305,7 @@ final class ChatViewModel {
startACPEventLoop(client: client)
startHealthMonitor(client: client)
// Project-scoped chats pass the project's absolute path
// as cwd so Hermes tool calls and subsequent ACP ops
// resolve relative paths against the project's files.
// Falls back to the user's home (existing v2.2 behavior)
// when the caller didn't request a project scope.
// `??` can't wrap an async autoclosure, so we
// materialize the fallback with an if-let.
let cwd: String
if let projectPath {
cwd = projectPath
} else {
cwd = await context.resolvedUserHome()
}
let cwd = await context.resolvedUserHome()
// Mark active BEFORE setting session ID so .task(id:) sees isACPMode=true
// and doesn't wipe messages with a DB refresh
@@ -385,48 +334,6 @@ final class ChatViewModel {
richChatViewModel.setSessionId(resolvedSessionId)
acpStatus = "Connected (\(resolvedSessionId.prefix(12)))"
// Attribute this session to the project it was started
// under, so the per-project Sessions tab can surface it
// without a user action. No-op when projectPath is nil.
// Idempotent: re-attribution of the same pair is free.
if let projectPath {
attribution.attribute(
sessionID: resolvedSessionId,
toProjectPath: projectPath
)
}
// Resolve which project (if any) this session belongs
// to, so SessionInfoBar + nav title can surface it.
// Two inputs — use whichever is non-nil:
// * `projectPath` — the caller asked for a project
// scope (fresh project chat). Just-attributed;
// definitely in the sidecar.
// * `attribution.projectPath(for: resolvedSessionId)`
// — the resumed session was previously attributed.
// Covers "click an old project-attributed session
// from the global Sessions sidebar / Resume menu"
// where projectPath isn't known at the call site.
let attributedPath = projectPath
?? attribution.projectPath(for: resolvedSessionId)
if let path = attributedPath {
// Look up a human-readable name from the projects
// registry. Missing project (path in the sidecar,
// project since removed) → show the path as a
// fallback label so the chip still renders and the
// user sees *something* rather than silently losing
// the indicator.
let registry = ProjectDashboardService(context: context).loadRegistry()
let name = registry.projects.first(where: { $0.path == path })?.name
self.currentProjectPath = path
self.currentProjectName = name ?? path
} else {
// Explicit clear on non-project sessions so the
// indicator doesn't leak from a previous chat.
self.currentProjectPath = nil
self.currentProjectName = nil
}
// Refresh session list so the new ACP session appears in the Resume menu
await loadRecentSessions()
scarf/scarf/Features/Chat/Views/ChatView.swift
+1 -59
View File
@@ -3,83 +3,25 @@ import SwiftUI
struct ChatView: View {
@Environment(ChatViewModel.self) private var viewModel
@Environment(HermesFileWatcher.self) private var fileWatcher
@Environment(AppCoordinator.self) private var coordinator
@State private var showErrorDetails = false
var body: some View {
@Bindable var vm = viewModel
@Bindable var coord = coordinator
VStack(spacing: 0) {
toolbar
Divider()
errorBanner
chatArea
}
// Clamp the outer VStack to the detail column's offered
// space. Without this, the chat area's intrinsic height (a
// RichChatView whose message list grows with content) can
// bubble up through NavigationSplitView's detail slot and
// push the whole window past the screen. Same pattern as
// the Sessions tab fix in the v2.3 branch.
.frame(maxWidth: .infinity, maxHeight: .infinity)
// v2.3: reflect the active Scarf project in the nav title
// so the user can see at a glance that the chat is scoped
// (complements the folder chip in SessionInfoBar). Falls
// back to the plain "Chat" label for global chats.
.navigationTitle(
viewModel.currentProjectName.map { "Chat · \($0)" } ?? "Chat"
)
.navigationTitle("Chat")
.task {
await viewModel.loadRecentSessions()
viewModel.refreshCredentialPreflight()
// Cold-launch handoff: if the user clicked "New Chat" on
// a project before ChatView had a chance to render, the
// coordinator was already populated. Consume the request
// here. The onChange below handles the live case.
if let pending = coordinator.pendingProjectChat {
coordinator.pendingProjectChat = nil
viewModel.startNewSession(projectPath: pending)
}
// Same story for resume-session handoff: the user clicked
// a session in the Projects Sessions tab (routes to `.chat`
// rather than `.sessions` so the chat actually reopens).
// SessionsView consumes `selectedSessionId` for its own
// routing; Chat now consumes it too. Mutually exclusive at
// any given render because only one section is active per
// `coordinator.selectedSection`. `else if` makes precedence
// explicit — pendingProjectChat (new) outranks
// selectedSessionId (resume) when both are somehow set.
else if let pendingId = coordinator.selectedSessionId {
coordinator.selectedSessionId = nil
viewModel.resumeSession(pendingId)
}
}
.onChange(of: fileWatcher.lastChangeDate) {
Task { await viewModel.loadRecentSessions() }
viewModel.refreshCredentialPreflight()
}
// Live handoff from the per-project Sessions tab: the tab
// sets `pendingProjectChat` + flips `selectedSection` to
// `.chat`; this view consumes the path and starts a fresh
// session with cwd=projectPath. Attribution happens inside
// ChatViewModel on successful session creation.
.onChange(of: coord.pendingProjectChat) { _, new in
if let projectPath = new {
coordinator.pendingProjectChat = nil
viewModel.startNewSession(projectPath: projectPath)
}
}
// Live handoff for resume: user clicked an existing session in
// the Projects Sessions tab while already in the Chat section
// (or switched back to Chat after). Project-chip rendering
// happens automatically inside ChatViewModel.resumeSession ->
// startACPSession via the attribution.projectPath(for:) lookup.
.onChange(of: coord.selectedSessionId) { _, new in
if let sessionId = new {
coordinator.selectedSessionId = nil
viewModel.resumeSession(sessionId)
}
}
}
/// Banner rendered between the toolbar and the chat area when either
scarf/scarf/Features/Chat/Views/RichChatView.swift
+1 -20
View File
@@ -17,13 +17,7 @@ struct RichChatView: View {
isWorking: richChat.isAgentWorking,
acpInputTokens: richChat.acpInputTokens,
acpOutputTokens: richChat.acpOutputTokens,
acpThoughtTokens: richChat.acpThoughtTokens,
// v2.3: surface the active Scarf project (if any) as
// a folder chip at the start of the bar. Driven by
// ChatViewModel.currentProjectName which is set in
// startACPSession on both new project chats and
// resumed project-attributed sessions.
projectName: chatViewModel.currentProjectName
acpThoughtTokens: richChat.acpThoughtTokens
)
Divider()
@@ -48,19 +42,6 @@ struct RichChatView: View {
showCompressButton: richChat.supportsCompress && !richChat.hasBroaderCommandMenu
)
}
// `idealHeight: 500` caps what this subtree REPORTS as its ideal
// height. Load-bearing: RichChatMessageList uses a plain VStack
// (not LazyVStack — see RichChatMessageList.swift:13-24 for the
// rationale) inside a ScrollView, so its natural ideal grows
// with message count. Under the WindowGroup's
// `.windowResizability(.contentMinSize)` policy, that uncapped
// ideal would open the window at a height that exceeds the
// screen on long conversations, pushing the input bar below
// the visible desktop. `maxHeight: .infinity` still lets the
// view fill any larger offered space, and `minHeight: 0`
// allows it to shrink freely — the ideal cap only affects the
// initial-size hint reported up to the window.
.frame(minHeight: 0, idealHeight: 500, maxHeight: .infinity)
// DB polling fallback for terminal mode only — never overwrite ACP messages
.onChange(of: fileWatcher.lastChangeDate) {
if !isACPMode, !richChat.hasMessages, richChat.sessionId != nil {
scarf/scarf/Features/Chat/Views/SessionInfoBar.swift
-18
View File
@@ -7,28 +7,10 @@ struct SessionInfoBar: View {
var acpInputTokens: Int = 0
var acpOutputTokens: Int = 0
var acpThoughtTokens: Int = 0
/// Name of the Scarf project this session is attributed to, when
/// applicable. Nil for plain global chats. Drives the folder-chip
/// indicator rendered before the session title. Resolved by
/// `ChatViewModel.currentProjectName` — the view just passes it
/// through.
var projectName: String? = nil
var body: some View {
HStack(spacing: 16) {
if let session {
// Project indicator first — visually anchors the session
// as "scoped to project X" before the working dot and
// title. Hidden for non-project chats so the bar looks
// identical to v2.2.1 behavior.
if let projectName {
Label(projectName, systemImage: "folder.fill")
.font(.caption)
.foregroundStyle(.tint)
.lineLimit(1)
.help("Chat is scoped to Scarf project \"\(projectName)\"")
}
HStack(spacing: 4) {
Circle()
.fill(isWorking ? .green : .secondary)
scarf/scarf/Features/Projects/ViewModels/ProjectSessionsViewModel.swift
-96
View File
@@ -1,96 +0,0 @@
import Foundation
import os
/// Drives the per-project Sessions tab introduced in v2.3. Pulls the
/// global session list from `HermesDataService`, filters by the
/// attribution sidecar, and exposes a minimal surface for the view:
/// the filtered sessions array, loading state, and a refresh entry
/// point that the view can call on appearance + on file-watcher
/// change.
@Observable
@MainActor
final class ProjectSessionsViewModel {
private static let logger = Logger(subsystem: "com.scarf", category: "ProjectSessionsViewModel")
private let dataService: HermesDataService
private let attribution: SessionAttributionService
private let project: ProjectEntry
init(context: ServerContext, project: ProjectEntry) {
self.dataService = HermesDataService(context: context)
self.attribution = SessionAttributionService(context: context)
self.project = project
}
/// Sessions attributed to the owning project, in the order
/// `HermesDataService.fetchSessions` returns them (newest first).
var sessions: [HermesSession] = []
/// True from `load()` start to its completion. The view renders
/// a ProgressView during the first fetch; afterwards, re-fetches
/// triggered by file-watcher changes happen silently.
var isLoading: Bool = false
/// Short diagnostic string for an empty list — nil when sessions
/// are loaded and populated, otherwise explains the empty state
/// (no sessions ever created in this project, vs. no sessions
/// matched the project's attribution map).
var emptyStateHint: String?
/// Refresh the session list. Safe to call repeatedly; the data
/// service reconnects to state.db on demand and the attribution
/// service reads the sidecar afresh each call.
func load() async {
isLoading = true
defer { isLoading = false }
let attributed = attribution.sessionIDs(forProject: project.path)
if attributed.isEmpty {
sessions = []
emptyStateHint = "No chats have been started in this project yet. Click New Chat to begin."
return
}
// Open (or re-open for remote) the DB handle before querying.
// `HermesDataService` is an actor with a lazily-initialised
// SQLite pointer; every query method short-circuits to `[]`
// when `db == nil`. This VM constructs its own service
// instance (separate from ChatViewModel / InsightsVM /
// ActivityVM), so we have to open it ourselves. Same
// pattern used by those other VMs (`refresh()` rather than
// `open()` because refresh also re-pulls the remote-server
// snapshot on each call — local is a cheap no-op).
_ = await dataService.refresh()
// Fetch a generous page; we filter client-side by attribution
// map membership. The 200 ceiling matches other feature VMs
// (ActivityViewModel, InsightsViewModel). HermesDataService
// is an actor so this crosses the isolation boundary — the
// SQLite read happens off the MainActor. If a single project
// accumulates more than 200 attributed sessions, we'll need
// a paged query; roadmap item, not a v2.3 problem.
let all = await dataService.fetchSessions(limit: 200)
let filtered = all.filter { attributed.contains($0.id) }
sessions = filtered
if filtered.isEmpty {
// Attribution map has entries but none appear in the
// recent session fetch — likely stale sidecar entries
// for sessions Hermes has since deleted. The view shows
// an informational empty state; pruning stale entries
// is a roadmap follow-up, not a blocker.
emptyStateHint = "This project has \(attributed.count) attributed session\(attributed.count == 1 ? "" : "s"), but none are in the recent history. They may have been deleted from Hermes."
} else {
emptyStateHint = nil
}
}
/// Release the underlying DB handle. Safe to call repeatedly; the
/// service re-opens on the next `load()`. Mirrors the pattern in
/// ActivityViewModel.swift:80 — view calls this on `.onDisappear`
/// so file descriptors and the SQLite cache don't dangle once
/// the tab isn't visible.
func close() async {
await dataService.close()
}
}
scarf/scarf/Features/Projects/ViewModels/ProjectsViewModel.swift
-95
View File
@@ -73,101 +73,6 @@ final class ProjectsViewModel {
}
}
// MARK: - v2.3 registry verbs (folder / archive / rename)
/// Move a project into a folder. `nil` folder returns the project
/// to the top level. No-op when the target already matches.
func moveProject(_ project: ProjectEntry, toFolder folder: String?) {
mutateEntry(project) { $0.folder = folder }
}
/// Rename a project. `name` is the registry's unique key + the
/// Identifiable id; we reject renames that would collide with
/// another project's name. Returns true on success.
@discardableResult
func renameProject(_ project: ProjectEntry, to newName: String) -> Bool {
let trimmed = newName.trimmingCharacters(in: .whitespacesAndNewlines)
guard !trimmed.isEmpty else { return false }
guard trimmed != project.name else { return true }
var registry = service.loadRegistry()
// Reject collisions — a second project already owns that name.
guard !registry.projects.contains(where: { $0.name == trimmed }) else { return false }
guard let index = registry.projects.firstIndex(where: { $0.name == project.name }) else { return false }
let old = registry.projects[index]
registry.projects[index] = ProjectEntry(
name: trimmed,
path: old.path,
folder: old.folder,
archived: old.archived
)
do {
try service.saveRegistry(registry)
} catch {
logger.error("renameProject couldn't persist registry: \(error.localizedDescription, privacy: .public)")
return false
}
projects = registry.projects
// Preserve selection across the rename — the selected project
// still exists, it just has a new id.
if selectedProject?.name == project.name {
selectedProject = registry.projects[index]
}
return true
}
/// Soft-archive a project. It stays on disk and in the registry;
/// the sidebar just hides it unless `showArchived` is on.
func archiveProject(_ project: ProjectEntry) {
mutateEntry(project) { $0.archived = true }
// If the archived project was selected, clear selection so
// the dashboard doesn't linger on a hidden project.
if selectedProject?.name == project.name {
selectedProject = nil
dashboard = nil
}
}
/// Restore an archived project to the default view.
func unarchiveProject(_ project: ProjectEntry) {
mutateEntry(project) { $0.archived = false }
}
/// Distinct folder labels across the current project set, sorted
/// alphabetically. Drives the sidebar's DisclosureGroups (commit
/// 2) and the Move-to-Folder sheet's existing-folder list. An
/// "empty" folder (folder with zero projects) can't exist under
/// this model — folders are implicit in the data — which is
/// intentional: v2.3 doesn't need first-class empty folders.
var folders: [String] {
let set = Set(projects.compactMap(\.folder).filter { !$0.isEmpty })
return set.sorted()
}
// MARK: - Helpers
/// Fetch the registry, apply `mutation` to the matched entry,
/// persist, update in-memory state. Centralises the save +
/// re-publish dance shared by `moveProject`, `archiveProject`,
/// and `unarchiveProject`. Callers that need different matching
/// semantics (rename, remove) handle their own registry mutation.
private func mutateEntry(_ project: ProjectEntry, _ mutation: (inout ProjectEntry) -> Void) {
var registry = service.loadRegistry()
guard let index = registry.projects.firstIndex(where: { $0.name == project.name }) else { return }
var entry = registry.projects[index]
mutation(&entry)
registry.projects[index] = entry
do {
try service.saveRegistry(registry)
} catch {
logger.error("mutateEntry couldn't persist registry for \(project.name, privacy: .public): \(error.localizedDescription, privacy: .public)")
return
}
projects = registry.projects
if selectedProject?.name == project.name {
selectedProject = entry
}
}
func refreshDashboard() {
guard let project = selectedProject else { return }
loadDashboard(for: project)
scarf/scarf/Features/Projects/Views/MoveToFolderSheet.swift
-113
View File
@@ -1,113 +0,0 @@
import SwiftUI
/// Sheet for assigning a project to a folder in the sidebar. Folders
/// are implicit — they exist because at least one project references
/// them via its `folder` field. The "create" action here just seeds
/// a new label the user types; it becomes real once any project is
/// assigned to it.
struct MoveToFolderSheet: View {
@Environment(\.dismiss) private var dismiss
let project: ProjectEntry
/// Existing folder labels in the registry, sorted. Computed by
/// the caller via `ProjectsViewModel.folders`.
let existingFolders: [String]
/// Called with the chosen folder. `nil` means "move back to top
/// level". Caller wires this through
/// `ProjectsViewModel.moveProject(_:toFolder:)`.
let onMove: (String?) -> Void
@State private var mode: Mode
@State private var newFolderName: String = ""
private enum Mode: Hashable {
case topLevel
case existing(String)
case new
}
init(
project: ProjectEntry,
existingFolders: [String],
onMove: @escaping (String?) -> Void
) {
self.project = project
self.existingFolders = existingFolders
self.onMove = onMove
// Start selection on the project's current folder if any,
// otherwise "Top Level". Feels right — Move sheet should
// reflect where the project currently lives.
if let current = project.folder, existingFolders.contains(current) {
_mode = State(initialValue: .existing(current))
} else {
_mode = State(initialValue: .topLevel)
}
}
private var canMove: Bool {
switch mode {
case .topLevel, .existing:
return true
case .new:
return !newFolderName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
}
}
var body: some View {
VStack(alignment: .leading, spacing: 12) {
Text("Move \"\(project.name)\" to folder").font(.headline)
Text("Folders only affect how projects are grouped in Scarf's sidebar. Nothing on disk changes.")
.font(.caption)
.foregroundStyle(.secondary)
.fixedSize(horizontal: false, vertical: true)
Picker("Destination", selection: $mode) {
Text("Top Level").tag(Mode.topLevel)
if !existingFolders.isEmpty {
Section {
ForEach(existingFolders, id: \.self) { folder in
Text(folder).tag(Mode.existing(folder))
}
}
}
Text("New folder…").tag(Mode.new)
}
.labelsHidden()
.pickerStyle(.inline)
if case .new = mode {
TextField("New folder name", text: $newFolderName)
.textFieldStyle(.roundedBorder)
.onSubmit {
if canMove { commit() }
}
}
HStack {
Button("Cancel") { dismiss() }
.keyboardShortcut(.cancelAction)
Spacer()
Button("Move") { commit() }
.keyboardShortcut(.defaultAction)
.buttonStyle(.borderedProminent)
.disabled(!canMove)
}
}
.padding()
.frame(minWidth: 420, minHeight: 320)
}
private func commit() {
switch mode {
case .topLevel:
onMove(nil)
case .existing(let folder):
onMove(folder)
case .new:
let trimmed = newFolderName.trimmingCharacters(in: .whitespacesAndNewlines)
guard !trimmed.isEmpty else { return }
onMove(trimmed)
}
dismiss()
}
}
scarf/scarf/Features/Projects/Views/ProjectSessionsView.swift
-198
View File
@@ -1,198 +0,0 @@
import SwiftUI
/// Per-project Sessions tab (v2.3). Lives beside the Dashboard and
/// Site tabs in the project view; populated from the session
/// attribution sidecar maintained by ChatViewModel. A "New Chat"
/// button spawns a fresh ACP session at cwd = project.path and
/// routes the user into the Chat feature via AppCoordinator.
struct ProjectSessionsView: View {
let project: ProjectEntry
@Environment(AppCoordinator.self) private var coordinator
@Environment(HermesFileWatcher.self) private var fileWatcher
@Environment(\.serverContext) private var serverContext
@State private var viewModel: ProjectSessionsViewModel?
var body: some View {
VStack(spacing: 0) {
header
Divider()
content
}
// `idealHeight: 400` caps what this subtree reports as its
// ideal height. Without it, the inner List's row-materialised
// intrinsic height bubbles up through NavigationSplitView's
// detail slot and, under `.windowResizability(.contentMinSize)`,
// opens the window at a height that exceeds the screen on
// busy projects — the Sessions tab header + "New Chat" button
// end up below the visible desktop edge. `maxHeight: .infinity`
// still lets the List fill any taller offered space, and
// `minHeight: 0` allows it to shrink. Mirrors the same pattern
// applied in RichChatView.
.frame(minHeight: 0, idealHeight: 400, maxHeight: .infinity)
.task(id: project.id) {
// Rebuild the VM when the project changes so stale state
// from a previously-selected project doesn't bleed
// through.
viewModel = ProjectSessionsViewModel(
context: serverContext,
project: project
)
await viewModel?.load()
}
.onChange(of: fileWatcher.lastChangeDate) {
Task { await viewModel?.load() }
}
.onDisappear {
// Release the SQLite handle so it doesn't dangle once
// the user leaves this tab. `load()` will re-open next
// time. Mirrors ActivityView's disappear cleanup.
Task { await viewModel?.close() }
}
}
// MARK: - Header
private var header: some View {
HStack(spacing: 12) {
VStack(alignment: .leading, spacing: 2) {
Text("Sessions in this project")
.font(.headline)
Text("Chats you start here get attributed automatically. Older CLI-started sessions live in the global Sessions sidebar.")
.font(.caption)
.foregroundStyle(.secondary)
.fixedSize(horizontal: false, vertical: true)
}
Spacer()
Button {
// Route into the Chat feature with a cwd override.
// ChatView observes this via its onChange and starts
// a fresh session with projectPath = our project.
coordinator.pendingProjectChat = project.path
coordinator.selectedSection = .chat
} label: {
Label("New Chat", systemImage: "message.badge.filled.fill")
}
.buttonStyle(.borderedProminent)
}
.padding()
}
// MARK: - Content
@ViewBuilder
private var content: some View {
if let vm = viewModel {
if vm.isLoading && vm.sessions.isEmpty {
ProgressView()
.frame(maxWidth: .infinity, maxHeight: .infinity)
} else if vm.sessions.isEmpty {
emptyState(hint: vm.emptyStateHint)
} else {
sessionList(vm.sessions)
}
} else {
ProgressView()
.frame(maxWidth: .infinity, maxHeight: .infinity)
}
}
private func emptyState(hint: String?) -> some View {
VStack(spacing: 10) {
Image(systemName: "bubble.left.and.bubble.right")
.font(.system(size: 36))
.foregroundStyle(.tertiary)
Text(hint ?? "No sessions yet.")
.font(.callout)
.foregroundStyle(.secondary)
.multilineTextAlignment(.center)
.fixedSize(horizontal: false, vertical: true)
.padding(.horizontal, 40)
}
.frame(maxWidth: .infinity, maxHeight: .infinity)
}
private func sessionList(_ sessions: [HermesSession]) -> some View {
List(sessions) { session in
ProjectSessionRow(session: session)
.contentShape(Rectangle())
.onTapGesture {
// Route into the Chat feature with this session
// as a resume target. Existing ChatView logic
// handles ACP reconnect.
coordinator.selectedSessionId = session.id
coordinator.selectedSection = .chat
}
}
.listStyle(.plain)
}
}
/// Single row in the per-project Sessions list. Intentionally small
/// and self-contained so it can evolve independently of the global
/// Sessions sidebar's row UI — if the two visualisations diverge
/// (e.g. the project tab wants to hide the `source` badge that's
/// useful in the global list), they don't pull each other along.
private struct ProjectSessionRow: View {
let session: HermesSession
var body: some View {
HStack(spacing: 10) {
Image(systemName: iconForSource(session.source))
.foregroundStyle(.secondary)
.frame(width: 22)
VStack(alignment: .leading, spacing: 2) {
Text(displayTitle)
.font(.callout)
.lineLimit(1)
HStack(spacing: 6) {
Text(session.id.prefix(12))
.font(.caption2.monospaced())
.foregroundStyle(.tertiary)
if let started = formattedStart {
Text("·")
.foregroundStyle(.tertiary)
Text(started)
.font(.caption2)
.foregroundStyle(.secondary)
}
}
}
Spacer(minLength: 12)
VStack(alignment: .trailing, spacing: 2) {
Text("\(session.messageCount)")
.font(.caption.monospaced())
Text("msgs")
.font(.caption2)
.foregroundStyle(.secondary)
}
}
.padding(.vertical, 4)
}
private var displayTitle: String {
if let t = session.title, !t.isEmpty { return t }
return "Untitled session"
}
private var formattedStart: String? {
// `startedAt` is `Date?` — the DB column can be null for
// sessions in unusual states. Locale-aware short form keeps
// us consistent with Insights + Activity.
guard let date = session.startedAt else { return nil }
let formatter = DateFormatter()
formatter.dateStyle = .short
formatter.timeStyle = .short
return formatter.string(from: date)
}
private func iconForSource(_ source: String) -> String {
switch source.lowercased() {
case "cli", "acp": return "terminal"
case "telegram": return "paperplane"
case "discord": return "bubble.left.and.bubble.right"
default: return "message"
}
}
}
scarf/scarf/Features/Projects/Views/ProjectsSidebar.swift
-274
View File
@@ -1,274 +0,0 @@
import SwiftUI
/// Sidebar view for the Projects feature. Renders the registry as:
/// - A search field at the top (⌘F focus).
/// - Top-level (folder-less) projects.
/// - Collapsible DisclosureGroups, one per folder.
/// - An "Archived" DisclosureGroup at the bottom, hidden unless the
/// Show Archived toggle is on.
///
/// Selection is bound to `viewModel.selectedProject` so the
/// dashboard area stays in sync with clicks anywhere in the hierarchy.
/// Context-menu actions delegate back to the parent view via closures
/// so the sheets / confirmation dialogs stay co-located with the rest
/// of ProjectsView's state.
struct ProjectsSidebar: View {
@Bindable var viewModel: ProjectsViewModel
// Predicates hoisted from the parent — avoid reaching down into
// service objects from this view.
let canConfigureProject: (ProjectEntry) -> Bool
let isTemplateInstalled: (ProjectEntry) -> Bool
// Context-menu + bottom-bar callbacks. Parent owns sheet state
// (install, uninstall, rename, move-to-folder, remove-from-list
// confirmation dialog) — this view just routes user intent.
let onConfigure: (ProjectEntry) -> Void
let onUninstallTemplate: (ProjectEntry) -> Void
let onRemoveFromList: (ProjectEntry) -> Void
let onRename: (ProjectEntry) -> Void
let onMoveToFolder: (ProjectEntry) -> Void
let onAddProject: () -> Void
/// Per-view UI state — filter text, show-archived toggle, and
/// which folders are expanded. Folder expansion defaults to all
/// open so a new user sees everything; they can collapse what
/// they don't want.
@State private var filterText: String = ""
@State private var showArchived: Bool = false
@State private var expandedFolders: Set<String> = []
@FocusState private var searchFocused: Bool
var body: some View {
VStack(spacing: 0) {
searchField
Divider()
list
Divider()
bottomBar
}
.onAppear {
// Start with every folder expanded on first render. If
// users collapse, that choice persists for the lifetime
// of the view instance (window open).
expandedFolders = Set(viewModel.folders)
}
.onChange(of: viewModel.folders) { _, newFolders in
// When a new folder appears (user just moved a project
// into one), start it expanded so the move is visibly
// reflected.
expandedFolders.formUnion(newFolders)
}
}
// MARK: - Search
private var searchField: some View {
HStack {
Image(systemName: "magnifyingglass")
.foregroundStyle(.secondary)
.font(.caption)
TextField("Filter projects", text: $filterText)
.textFieldStyle(.plain)
.focused($searchFocused)
.font(.caption)
if !filterText.isEmpty {
Button {
filterText = ""
} label: {
Image(systemName: "xmark.circle.fill")
.foregroundStyle(.tertiary)
.font(.caption)
}
.buttonStyle(.borderless)
}
}
.padding(.horizontal, 10)
.padding(.vertical, 6)
}
// MARK: - List
private var list: some View {
List(selection: Binding(
get: { viewModel.selectedProject },
set: { if let p = $0 { viewModel.selectProject(p) } }
)) {
// Top-level projects first — matches the Finder-like
// mental model where top-level items sit above folders.
ForEach(topLevelVisible) { project in
projectRow(project)
}
// Per-folder collapsible sections.
ForEach(visibleFolders, id: \.self) { folder in
let children = folderProjects(folder)
if !children.isEmpty {
DisclosureGroup(
isExpanded: Binding(
get: { expandedFolders.contains(folder) },
set: { expanded in
if expanded {
expandedFolders.insert(folder)
} else {
expandedFolders.remove(folder)
}
}
)
) {
ForEach(children) { project in
projectRow(project)
}
} label: {
Label(folder, systemImage: "folder")
.font(.caption)
.foregroundStyle(.secondary)
}
}
}
// Archived section — only surfaces under the toggle.
if showArchived, !archivedVisible.isEmpty {
DisclosureGroup {
ForEach(archivedVisible) { project in
projectRow(project)
.opacity(0.7)
}
} label: {
Label("Archived (\(archivedVisible.count))", systemImage: "archivebox")
.font(.caption)
.foregroundStyle(.secondary)
}
}
}
.listStyle(.sidebar)
}
@ViewBuilder
private func projectRow(_ project: ProjectEntry) -> some View {
HStack {
Image(
systemName: viewModel.dashboard != nil
&& viewModel.selectedProject == project
? "square.grid.2x2.fill"
: "square.grid.2x2"
)
.foregroundStyle(.secondary)
Text(project.name)
.lineLimit(1)
.truncationMode(.tail)
}
.tag(project)
.contextMenu {
projectContextMenu(project)
}
}
@ViewBuilder
private func projectContextMenu(_ project: ProjectEntry) -> some View {
if canConfigureProject(project) {
Button("Configuration…", systemImage: "slider.horizontal.3") {
onConfigure(project)
}
Divider()
}
Button("Rename…", systemImage: "pencil") { onRename(project) }
Button("Move to Folder…", systemImage: "folder") { onMoveToFolder(project) }
if project.archived {
Button("Unarchive", systemImage: "tray.and.arrow.up") {
viewModel.unarchiveProject(project)
}
} else {
Button("Archive", systemImage: "archivebox") {
viewModel.archiveProject(project)
}
}
Divider()
if isTemplateInstalled(project) {
Button("Uninstall Template (remove installed files)…", systemImage: "trash") {
onUninstallTemplate(project)
}
Divider()
}
Button("Remove from List (keep files)…", systemImage: "minus.circle") {
onRemoveFromList(project)
}
}
// MARK: - Bottom bar
private var bottomBar: some View {
HStack {
Button(action: onAddProject) {
Image(systemName: "plus")
}
.buttonStyle(.borderless)
.help("Add a project")
Toggle(isOn: $showArchived) {
Image(systemName: showArchived ? "archivebox.fill" : "archivebox")
.font(.caption)
}
.toggleStyle(.button)
.buttonStyle(.borderless)
.help(showArchived ? "Hide archived projects" : "Show archived projects")
Spacer()
if let selected = viewModel.selectedProject {
Button(action: { onRemoveFromList(selected) }) {
Image(systemName: "minus")
}
.buttonStyle(.borderless)
.help("Remove \(selected.name) from Scarf's project list (files are kept on disk)")
}
}
.padding(8)
}
// MARK: - Derived data
/// Fuzzy-match on name + path + folder label. Case-insensitive,
/// substring — not a true fuzzy search, but matches the project
/// count scale (tens, not thousands). Upgradable to a Levenshtein
/// scorer later without changing the call sites.
private func matches(_ project: ProjectEntry) -> Bool {
let needle = filterText
.trimmingCharacters(in: .whitespacesAndNewlines)
.lowercased()
guard !needle.isEmpty else { return true }
if project.name.lowercased().contains(needle) { return true }
if project.path.lowercased().contains(needle) { return true }
if let folder = project.folder, folder.lowercased().contains(needle) { return true }
return false
}
/// Visible top-level projects (no folder, not archived, passes
/// the current filter). Sort is stable by name — the registry
/// already preserves insertion order, but showing a sorted list
/// of homogeneous top-level entries feels cleaner.
private var topLevelVisible: [ProjectEntry] {
viewModel.projects
.filter { ($0.folder ?? "").isEmpty && !$0.archived && matches($0) }
.sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
}
/// Folders that currently have at least one matching, non-
/// archived project. Folders with only archived projects move
/// into the Archived section's items; empty folders disappear.
private var visibleFolders: [String] {
viewModel.folders.filter { !folderProjects($0).isEmpty }
}
private func folderProjects(_ folder: String) -> [ProjectEntry] {
viewModel.projects
.filter { $0.folder == folder && !$0.archived && matches($0) }
.sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
}
private var archivedVisible: [ProjectEntry] {
viewModel.projects
.filter { $0.archived && matches($0) }
.sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
}
}
scarf/scarf/Features/Projects/Views/ProjectsView.swift
+74 -89
View File
@@ -4,21 +4,11 @@ import UniformTypeIdentifiers
private enum DashboardTab: String, CaseIterable {
case dashboard = "Dashboard"
case site = "Site"
case sessions = "Sessions"
var displayName: LocalizedStringResource {
switch self {
case .dashboard: return "Dashboard"
case .site: return "Site"
case .sessions: return "Sessions"
}
}
var systemImage: String {
switch self {
case .dashboard: return "square.grid.2x2"
case .site: return "globe"
case .sessions: return "bubble.left.and.bubble.right"
}
}
}
@@ -44,16 +34,6 @@ struct ProjectsView: View {
/// drop from the registry.
@State private var pendingRemoveFromList: ProjectEntry?
/// Project queued for the rename sheet (v2.3). Sheet state lives
/// on the parent view so the sidebar stays a pure presentation
/// layer; rename logic routes through `ProjectsViewModel.renameProject`.
@State private var renameTarget: ProjectEntry?
/// Project queued for the move-to-folder sheet (v2.3). Same
/// pattern as renameTarget: parent owns sheet state, sidebar
/// delegates up.
@State private var moveTarget: ProjectEntry?
private let uninstaller: ProjectTemplateUninstaller
init(context: ServerContext) {
@@ -283,47 +263,79 @@ struct ProjectsView: View {
// MARK: - Project List
private var projectList: some View {
// Sidebar is an extracted view; this view stays the owner of
// sheet state (add / rename / move / uninstall / remove-from-
// list confirmation) and routes intents down as closures.
ProjectsSidebar(
viewModel: viewModel,
canConfigureProject: { isConfigurable($0) },
isTemplateInstalled: { uninstaller.isTemplateInstalled(project: $0) },
onConfigure: { configEditorProject = $0 },
onUninstallTemplate: { project in
uninstallerViewModel.begin(project: project)
showingUninstallSheet = true
},
onRemoveFromList: { pendingRemoveFromList = $0 },
onRename: { renameTarget = $0 },
onMoveToFolder: { moveTarget = $0 },
onAddProject: { showingAddSheet = true }
)
VStack(spacing: 0) {
List(viewModel.projects, selection: Binding(
get: { viewModel.selectedProject },
set: { project in
if let project {
viewModel.selectProject(project)
}
}
)) { project in
HStack {
Image(systemName: viewModel.dashboard != nil && viewModel.selectedProject == project
? "square.grid.2x2.fill" : "square.grid.2x2")
.foregroundStyle(.secondary)
Text(project.name)
}
.tag(project)
.contextMenu {
if isConfigurable(project) {
Button("Configuration…", systemImage: "slider.horizontal.3") {
configEditorProject = project
}
}
if uninstaller.isTemplateInstalled(project: project) {
// "Uninstall Template…" only appears for projects
// installed from a `.scarftemplate`. Trailing
// ellipsis signals a confirmation sheet follows
// (macOS HIG convention); the sheet itself lists
// every file/cron/skill that will be removed.
Button("Uninstall Template (remove installed files)…", systemImage: "trash") {
uninstallerViewModel.begin(project: project)
showingUninstallSheet = true
}
Divider()
}
// "Remove from List" used to be "Remove from Scarf",
// which users read as a full delete. Clarified label +
// ellipsis + confirmation dialog all spell out that
// this is registry-only; nothing on disk is touched.
Button("Remove from List (keep files)…", systemImage: "minus.circle") {
pendingRemoveFromList = project
}
}
}
.listStyle(.sidebar)
Divider()
HStack {
Button(action: { showingAddSheet = true }) {
Image(systemName: "plus")
}
.buttonStyle(.borderless)
Spacer()
if let selected = viewModel.selectedProject {
// Route through the same confirmation dialog as the
// context-menu "Remove from List" entry. The minus
// icon is a drive-by click target right next to "+" —
// confirming before mutating the registry stops the
// "I clicked by accident and my project's gone" case.
Button(action: { pendingRemoveFromList = selected }) {
Image(systemName: "minus")
}
.buttonStyle(.borderless)
.help("Remove \(selected.name) from Scarf's project list (files are kept on disk)")
}
}
.padding(8)
}
.sheet(isPresented: $showingAddSheet) {
AddProjectSheet { name, path in
viewModel.addProject(name: name, path: path)
fileWatcher.updateProjectWatches(viewModel.dashboardPaths)
}
}
.sheet(item: $renameTarget) { target in
RenameProjectSheet(
project: target,
existingNames: viewModel.projects
.filter { $0.name != target.name }
.map(\.name)
) { newName in
viewModel.renameProject(target, to: newName)
}
}
.sheet(item: $moveTarget) { target in
MoveToFolderSheet(
project: target,
existingFolders: viewModel.folders
) { newFolder in
viewModel.moveProject(target, toFolder: newFolder)
}
}
}
// MARK: - Dashboard Area
@@ -343,13 +355,11 @@ struct ProjectsView: View {
.padding(.horizontal)
.padding(.top)
.padding(.bottom, 8)
// Sessions tab is always present in v2.3, so the tab
// bar always renders when a dashboard is loaded.
// Site tab filters out when there's no webview widget
// (existing v2.2 behavior preserved).
tabBar
.padding(.horizontal)
.padding(.bottom, 8)
if siteWidget != nil {
tabBar
.padding(.horizontal)
.padding(.bottom, 8)
}
switch selectedTab {
case .dashboard:
widgetsTab(dashboard)
@@ -359,24 +369,8 @@ struct ProjectsView: View {
} else {
widgetsTab(dashboard)
}
case .sessions:
if let project = viewModel.selectedProject {
ProjectSessionsView(project: project)
} else {
ContentUnavailableView("No project selected", systemImage: "bubble.left.and.bubble.right")
}
}
}
// Clamp the container VStack to the detail column's
// offered space. Without it, any tab whose content is
// taller than the window (long Sessions list, tall
// README block in a dashboard's text widget, etc.) can
// bubble its intrinsic height up through
// NavigationSplitView's detail slot and push the whole
// window past the screen. widgetsTab's own ScrollView
// and siteTab's explicit maxHeight both cooperate; the
// sessions tab needs this as well.
.frame(maxWidth: .infinity, maxHeight: .infinity)
} else if let error = viewModel.dashboardError {
ContentUnavailableView {
Label("No Dashboard", systemImage: "square.grid.2x2")
@@ -400,23 +394,14 @@ struct ProjectsView: View {
}
}
/// Tabs that should appear for the current project. `.site` is
/// gated on the dashboard actually containing a webview widget,
/// per v2.2 behavior — the Site tab is meaningless without one.
private var visibleTabs: [DashboardTab] {
DashboardTab.allCases.filter { tab in
tab != .site || siteWidget != nil
}
}
private var tabBar: some View {
HStack(spacing: 0) {
ForEach(visibleTabs, id: \.self) { tab in
ForEach(DashboardTab.allCases, id: \.self) { tab in
Button {
selectedTab = tab
} label: {
HStack(spacing: 4) {
Image(systemName: tab.systemImage)
Image(systemName: tab == .dashboard ? "square.grid.2x2" : "globe")
.font(.caption)
Text(tab.displayName)
.font(.subheadline)
scarf/scarf/Features/Projects/Views/RenameProjectSheet.swift
-87
View File
@@ -1,87 +0,0 @@
import SwiftUI
/// Sheet for renaming a project in the registry. Preserves the
/// project's `path`, `folder`, and `archived` fields — the rename
/// only changes the user-visible name (and therefore the Identifiable
/// id). Duplicate-name / empty-name rejection lives in the VM.
struct RenameProjectSheet: View {
@Environment(\.dismiss) private var dismiss
let project: ProjectEntry
/// Current set of project names in the registry, used to flag
/// duplicates before the user tries to Save. Excludes the
/// project being renamed so same-name is a no-op (accepted).
let existingNames: [String]
/// Called with the trimmed new name. Caller is responsible for
/// calling `ProjectsViewModel.renameProject(_:to:)`; this sheet
/// just gathers input + validates inline.
let onSave: (String) -> Void
@State private var newName: String
init(
project: ProjectEntry,
existingNames: [String],
onSave: @escaping (String) -> Void
) {
self.project = project
self.existingNames = existingNames
self.onSave = onSave
_newName = State(initialValue: project.name)
}
/// Validation for the live input. Empty / whitespace-only / a
/// collision with another project's name all disable Save.
private var validation: (isValid: Bool, message: String?) {
let trimmed = newName.trimmingCharacters(in: .whitespacesAndNewlines)
if trimmed.isEmpty {
return (false, nil) // no error message — just disabled
}
if trimmed != project.name && existingNames.contains(trimmed) {
return (false, String(localized: "A project named \"\(trimmed)\" already exists."))
}
return (true, nil)
}
var body: some View {
VStack(alignment: .leading, spacing: 12) {
Text("Rename project").font(.headline)
Text("The project directory on disk isn't changed — only the label Scarf shows in the sidebar.")
.font(.caption)
.foregroundStyle(.secondary)
.fixedSize(horizontal: false, vertical: true)
TextField("Project name", text: $newName)
.textFieldStyle(.roundedBorder)
.onSubmit {
if validation.isValid {
save()
}
}
if let message = validation.message {
Label(message, systemImage: "exclamationmark.triangle.fill")
.font(.caption)
.foregroundStyle(.red)
}
HStack {
Button("Cancel") { dismiss() }
.keyboardShortcut(.cancelAction)
Spacer()
Button("Save") { save() }
.keyboardShortcut(.defaultAction)
.buttonStyle(.borderedProminent)
.disabled(!validation.isValid)
}
}
.padding()
.frame(minWidth: 420)
}
private func save() {
let trimmed = newName.trimmingCharacters(in: .whitespacesAndNewlines)
onSave(trimmed)
dismiss()
}
}
scarf/scarf/Features/Servers/Views/ManageServersView.swift
+4 -5
View File
@@ -143,20 +143,19 @@ struct ManageServersView: View {
}
/// A star button that marks the open-on-launch default. Filled + yellow
/// on the current default row (disabled, since clicking would be a
/// no-op); outline + secondary elsewhere, clicking promotes that row
/// to default.
/// on the current default row (and non-interactive — clicking it is a
/// no-op since the flag is already set); outline + secondary elsewhere,
/// clicking promotes that row to default.
@ViewBuilder
private func defaultStar(for id: ServerID, currentDefault: ServerID) -> some View {
let isDefault = id == currentDefault
Button {
registry.setDefaultServer(id)
if !isDefault { registry.setDefaultServer(id) }
} label: {
Image(systemName: isDefault ? "star.fill" : "star")
.foregroundStyle(isDefault ? .yellow : .secondary)
}
.buttonStyle(.borderless)
.disabled(isDefault)
.help(isDefault ? "Opens on launch" : "Set as default — open this server when Scarf launches.")
}
scarf/scarf/Features/Settings/ViewModels/SettingsViewModel.swift
+1
View File
@@ -20,6 +20,7 @@ final class SettingsViewModel {
var hermesRunning = false
var rawConfigYAML = ""
var personalities: [String] = []
var providers = ["anthropic", "openrouter", "nous", "openai-codex", "google-ai-studio", "xai", "ollama-cloud", "zai", "kimi-coding", "minimax"]
var terminalBackends = ["local", "docker", "singularity", "modal", "daytona", "ssh"]
var browserBackends = ["browseruse", "firecrawl", "local"]
var ttsProviders = ["edge", "elevenlabs", "openai", "minimax", "mistral", "neutts"]
scarf/scarf/Features/Templates/Views/TemplateConfigSheet.swift
+17 -41
View File
@@ -23,20 +23,6 @@ struct TemplateConfigSheet: View {
header
Divider()
ScrollView {
// `.frame(maxWidth: .infinity, alignment: .leading)` is
// load-bearing: without it, SwiftUI resolves width
// bottom-up and an unbreakable token in a child (e.g. a
// raw URL inside a field description rendered via
// AttributedString markdown) sets the whole VStack's
// ideal width to that token's length. ScrollView's
// content then exceeds the sheet's viewport, the outer
// `.frame(minWidth: 560)` grows to content width, and
// the window clips the result with labels cut off on
// the left + URL spilling off the right. With the
// explicit maxWidth, the ScrollView's offered width
// propagates down and the description Text's
// `.fixedSize(horizontal: false, vertical: true)`
// wraps at whitespace boundaries as intended.
VStack(alignment: .leading, spacing: 18) {
if viewModel.schema.fields.isEmpty {
ContentUnavailableView(
@@ -54,7 +40,6 @@ struct TemplateConfigSheet: View {
modelRecommendation(rec)
}
}
.frame(maxWidth: .infinity, alignment: .leading)
.padding(20)
}
Divider()
@@ -131,11 +116,7 @@ struct TemplateConfigSheet: View {
// Inline markdown so descriptions can include
// `[Create one](https://…)`-style links to token
// generation pages, **bold** emphasis on important
// prerequisites, etc. Raw URLs (not wrapped in
// markdown link syntax) will still render but can't
// word-break mid-token — keep the parent maxWidth
// constraint below so a rogue raw URL wraps cleanly
// instead of expanding the entire sheet.
// prerequisites, etc.
TemplateMarkdown.inlineText(description)
.font(.caption)
.foregroundStyle(.secondary)
@@ -148,12 +129,6 @@ struct TemplateConfigSheet: View {
.foregroundStyle(.red)
}
}
// maxWidth: .infinity forces this row to span the column's
// full width so its internal description Text wraps instead
// of expanding the outer VStack when a description contains
// a long unbreakable token (raw URL, path, etc.). See the
// comment on the parent ScrollView's inner VStack.
.frame(maxWidth: .infinity, alignment: .leading)
.padding(12)
.background(
RoundedRectangle(cornerRadius: 8)
@@ -312,23 +287,24 @@ private struct EnumControl: View {
let options: [TemplateConfigField.EnumOption]
@Binding var value: String
var body: some View {
// Always use the default Menu picker (dropdown). An earlier
// version switched to `.pickerStyle(.segmented)` when
// `options.count ≤ 4` for a more compact look, but on macOS
// segmented pickers size to the intrinsic width of all their
// labels concatenated — they refuse offered width constraints
// and refuse to wrap. A schema with three long labels like
// "Claude Opus 4 (Recommended - Most Capable)" produced a
// ~650pt picker that overflowed the 560pt sheet viewport,
// clipping the entire form. Menu pickers respect the fieldRow's
// offered width and show long labels in the popup list, so the
// sheet can't overflow regardless of label length.
Picker("", selection: $value) {
ForEach(options) { opt in
Text(opt.label).tag(opt.value)
// Segmented for ≤ 4 options, dropdown otherwise — fits Scarf's
// existing settings UI.
if options.count <= 4 {
Picker("", selection: $value) {
ForEach(options) { opt in
Text(opt.label).tag(opt.value)
}
}
.pickerStyle(.segmented)
.labelsHidden()
} else {
Picker("", selection: $value) {
ForEach(options) { opt in
Text(opt.label).tag(opt.value)
}
}
.labelsHidden()
}
.labelsHidden()
}
}
scarf/scarf/Features/Templates/Views/TemplateInstallSheet.swift
-11
View File
@@ -126,16 +126,6 @@ struct TemplateInstallSheet: View {
.padding(.bottom, 8)
Divider()
ScrollView {
// `.frame(maxWidth: .infinity, alignment: .leading)` —
// without it, a subsection containing an unbreakable
// token (raw URL in a cron prompt or README block, a
// long file path in the project-files list, a schema
// description with a bare URL, etc.) sets the VStack's
// ideal width to that token's length; the sheet grows
// past its `.frame(minWidth: 620)` and gets clipped by
// the window. Same fix as `TemplateConfigSheet`'s
// inner VStack — propagate the ScrollView's width down
// so inner Text wraps instead of expanding outward.
VStack(alignment: .leading, spacing: 16) {
projectFilesSection(plan: plan)
if plan.skillsNamespaceDir != nil {
@@ -152,7 +142,6 @@ struct TemplateInstallSheet: View {
}
readmeSection
}
.frame(maxWidth: .infinity, alignment: .leading)
.padding(.vertical)
}
Divider()
scarf/scarf/Localizable.xcstrings
-102
View File
@@ -1028,10 +1028,6 @@
"comment" : "A message that appears when a memory block is no longer present in MEMORY.md.",
"isCommentAutoGenerated" : true
},
"A project named \"%@\" already exists." : {
"comment" : "A warning message that appears in a Rename Project sheet if the user-provided name is a duplicate of an existing project. The argument is the name of the duplicate project.",
"isCommentAutoGenerated" : true
},
"A QR code will appear below. Scan it with WhatsApp on your phone. The session is saved to ~/.hermes/platforms/whatsapp/ so you won't need to scan again after restarts." : {
"localizations" : {
"de" : {
@@ -1395,10 +1391,6 @@
}
}
},
"Add a project" : {
"comment" : "A button that adds a new project.",
"isCommentAutoGenerated" : true
},
"Add a project folder to get started. Create a .scarf/dashboard.json file in your project to define widgets." : {
"localizations" : {
"de" : {
@@ -2529,10 +2521,6 @@
}
}
},
"Archived (%lld)" : {
"comment" : "A label that opens a group of archived projects.",
"isCommentAutoGenerated" : true
},
"Args (one per line)" : {
"localizations" : {
"de" : {
@@ -3757,14 +3745,6 @@
}
}
},
"Chat · %@" : {
"comment" : "A label that shows the name of the active Scarf project, followed by \"Chat\".",
"isCommentAutoGenerated" : true
},
"Chat is scoped to Scarf project \"%@\"" : {
"comment" : "Tooltip for the folder-chip indicator.",
"isCommentAutoGenerated" : true
},
"Chat Messages" : {
"localizations" : {
"de" : {
@@ -3805,10 +3785,6 @@
}
}
},
"Chats you start here get attributed automatically. Older CLI-started sessions live in the global Sessions sidebar." : {
"comment" : "A description of the purpose of the Sessions tab.",
"isCommentAutoGenerated" : true
},
"Check" : {
"localizations" : {
"de" : {
@@ -6898,10 +6874,6 @@
},
"Description" : {
},
"Destination" : {
"comment" : "A label for the folder picker in the move-to-folder sheet.",
"isCommentAutoGenerated" : true
},
"Details" : {
"localizations" : {
@@ -8830,10 +8802,6 @@
}
}
},
"Filter projects" : {
"comment" : "A label for a search field in the sidebar.",
"isCommentAutoGenerated" : true
},
"Filter servers..." : {
"localizations" : {
"de" : {
@@ -9038,10 +9006,6 @@
"comment" : "A placeholder for a comma-separated list of tags.",
"isCommentAutoGenerated" : true
},
"Folders only affect how projects are grouped in Scarf's sidebar. Nothing on disk changes." : {
"comment" : "A description of how folders affect project grouping.",
"isCommentAutoGenerated" : true
},
"Full copy of active profile (all state)" : {
"localizations" : {
"de" : {
@@ -9734,10 +9698,6 @@
}
}
},
"Hide archived projects" : {
"comment" : "A toggle that hides archived projects.",
"isCommentAutoGenerated" : true
},
"Hide details" : {
"localizations" : {
"de" : {
@@ -12226,22 +12186,6 @@
}
}
},
"Move" : {
"comment" : "A button that moves a project to a folder.",
"isCommentAutoGenerated" : true
},
"Move \"%@\" to folder" : {
"comment" : "A heading for a dialog that lets the user move a project to a folder.",
"isCommentAutoGenerated" : true
},
"Move to Folder…" : {
"comment" : "A context menu action that moves a project to a folder.",
"isCommentAutoGenerated" : true
},
"msgs" : {
"comment" : "A label for the number of messages in a session.",
"isCommentAutoGenerated" : true
},
"my_server" : {
},
@@ -12365,17 +12309,6 @@
}
}
},
"New Chat" : {
"comment" : "A button that starts a new chat session.",
"isCommentAutoGenerated" : true
},
"New folder name" : {
},
"New folder…" : {
"comment" : "A label for a new folder name.",
"isCommentAutoGenerated" : true
},
"New name for '%@'" : {
"localizations" : {
"de" : {
@@ -13394,10 +13327,6 @@
}
}
},
"No project selected" : {
"comment" : "A label that indicates that no project is selected.",
"isCommentAutoGenerated" : true
},
"No Projects" : {
"localizations" : {
"de" : {
@@ -15529,10 +15458,6 @@
},
"Project folder kept" : {
},
"Project name" : {
"comment" : "A label for a text field that lets the user enter a project name.",
"isCommentAutoGenerated" : true
},
"Project Name" : {
"localizations" : {
@@ -16945,10 +16870,6 @@
}
}
},
"Rename project" : {
"comment" : "A title for a sheet that renames a project.",
"isCommentAutoGenerated" : true
},
"Rename Session" : {
"localizations" : {
"de" : {
@@ -17028,9 +16949,6 @@
}
}
}
},
"Rename…" : {
},
"required" : {
@@ -19461,10 +19379,6 @@
}
}
},
"Sessions in this project" : {
"comment" : "A heading for the list of sessions in a project.",
"isCommentAutoGenerated" : true
},
"Set as default — open this server when Scarf launches." : {
"comment" : "A tooltip for the star button in the Manage Servers view.",
"isCommentAutoGenerated" : true
@@ -19709,10 +19623,6 @@
}
}
},
"Show archived projects" : {
"comment" : "A toggle that shows/hides archived projects.",
"isCommentAutoGenerated" : true
},
"Show details" : {
"localizations" : {
"de" : {
@@ -21525,10 +21435,6 @@
}
}
},
"The project directory on disk isn't changed — only the label Scarf shows in the sidebar." : {
"comment" : "A description of the project name field.",
"isCommentAutoGenerated" : true
},
"The remote's SSH fingerprint no longer matches what your `~/.ssh/known_hosts` file expected. This usually means the remote was reinstalled — or, less commonly, that someone is intercepting the connection." : {
"localizations" : {
"de" : {
@@ -22516,10 +22422,6 @@
}
}
},
"Top Level" : {
"comment" : "A folder in the sidebar.",
"isCommentAutoGenerated" : true
},
"Top Tools" : {
"localizations" : {
"de" : {
@@ -22680,10 +22582,6 @@
}
}
},
"Unarchive" : {
"comment" : "A button that unarchives a project.",
"isCommentAutoGenerated" : true
},
"Uninstall" : {
"localizations" : {
"de" : {
scarf/scarf/Navigation/AppCoordinator.swift
-11
View File
@@ -91,15 +91,4 @@ final class AppCoordinator {
var selectedSection: SidebarSection = .dashboard
var selectedSessionId: String?
var selectedProjectName: String?
/// When non-nil, ChatView should start a fresh ACP session with
/// this absolute project path as cwd and then clear the value.
/// Wired from the per-project Sessions tab's "New Chat" button
/// (v2.3): the tab sets this, switches `selectedSection` to
/// `.chat`, and ChatView reacts on its next render.
///
/// Separate from `selectedSessionId` (which resumes an existing
/// session) — a new session needs a cwd override Scarf doesn't
/// yet have an id for.
var pendingProjectChat: String?
}
scarf/scarf/Navigation/SidebarView.swift
+1 -2
View File
@@ -2,7 +2,6 @@ import SwiftUI
struct SidebarView: View {
@Environment(AppCoordinator.self) private var coordinator
@Environment(\.serverContext) private var serverContext
var body: some View {
@Bindable var coordinator = coordinator
@@ -60,6 +59,6 @@ struct SidebarView: View {
}
.listStyle(.sidebar)
.navigationTitle("Scarf")
.splitViewAutosaveName("ScarfMainSidebar.\(serverContext.id)")
.splitViewAutosaveName("ScarfMainSidebar")
}
}
scarf/scarf/scarfApp.swift
-13
View File
@@ -86,19 +86,6 @@ struct ScarfApp: App {
registry.defaultServerID
}
.defaultSize(width: 1100, height: 700)
// Without an explicit resizability, `WindowGroup` defaults to
// `.automatic` which on macOS evaluates to `.contentSize` —
// meaning the window is BOUND to its content's ideal size
// rather than bounded-below by it. Any section whose content's
// intrinsic height changes (Chat's message list, the v2.3
// per-project Sessions tab, Insights charts) would resize the
// window on every section switch, snap back against user
// resize, and sometimes push the whole window past the
// screen. `.contentMinSize` turns the content's ideal height
// into a minimum floor: user resize works freely, the window
// stays put across section switches, and it still can't shrink
// smaller than a section's minimum render.
.windowResizability(.contentMinSize)
.commands {
CommandGroup(after: .appInfo) {
Button("Check for Updates…") { updater.checkForUpdates() }
scarf/scarfTests/ProjectAgentContextServiceTests.swift
-260
View File
@@ -1,260 +0,0 @@
import Testing
import Foundation
@testable import scarf
/// Exercises the Scarf-managed AGENTS.md marker block logic added in
/// v2.3. Tests operate on isolated temp directories — no dependency
/// on ~/.hermes contents, no cross-suite lock needed.
@Suite struct ProjectAgentContextServiceTests {
// MARK: - applyBlock pure-text transform
@Test func applyBlockPrependsWhenNoMarkersPresent() {
let existing = "# My Template\n\nSome instructions.\n"
let block = "<!-- scarf-project:begin -->\nhello\n<!-- scarf-project:end -->"
let result = ProjectAgentContextService.applyBlock(block: block, to: existing)
#expect(result.hasPrefix("<!-- scarf-project:begin -->"))
#expect(result.contains("<!-- scarf-project:end -->"))
#expect(result.contains("# My Template"))
#expect(result.contains("Some instructions."))
// Exactly one blank line between block and original content.
#expect(result.contains("<!-- scarf-project:end -->\n\n# My Template"))
}
@Test func applyBlockWritesFreshFileWhenEmpty() {
let block = "<!-- scarf-project:begin -->\nhello\n<!-- scarf-project:end -->"
let result = ProjectAgentContextService.applyBlock(block: block, to: "")
// Empty input → just the block + trailing newline; no weird
// leading whitespace.
#expect(result == block + "\n")
}
@Test func applyBlockReplacesExistingMarkerRegion() {
let existing = """
<!-- scarf-project:begin -->
old content line 1
old content line 2
<!-- scarf-project:end -->
# Template docs preserved
Template behavior.
"""
let newBlock = "<!-- scarf-project:begin -->\nfresh content\n<!-- scarf-project:end -->"
let result = ProjectAgentContextService.applyBlock(block: newBlock, to: existing)
#expect(result.contains("fresh content"))
// Old content is gone.
#expect(!result.contains("old content line 1"))
#expect(!result.contains("old content line 2"))
// Template content outside markers is preserved.
#expect(result.contains("# Template docs preserved"))
#expect(result.contains("Template behavior."))
}
@Test func applyBlockIsIdempotent() {
let existing = "# Project\n\nContent.\n"
let block = "<!-- scarf-project:begin -->\nv1\n<!-- scarf-project:end -->"
let once = ProjectAgentContextService.applyBlock(block: block, to: existing)
let twice = ProjectAgentContextService.applyBlock(block: block, to: once)
#expect(once == twice)
}
@Test func applyBlockOrphanedBeginMarkerFallsBackToPrepend() {
// Stray begin with no end: treat as "no well-formed block,"
// prepend. Leaves the orphan in place — it was probably
// hand-typed, not a corrupt Scarf write. Conservative.
let existing = "<!-- scarf-project:begin -->\nstray text with no end marker\n"
let block = "<!-- scarf-project:begin -->\nnew\n<!-- scarf-project:end -->"
let result = ProjectAgentContextService.applyBlock(block: block, to: existing)
#expect(result.hasPrefix("<!-- scarf-project:begin -->\nnew\n<!-- scarf-project:end -->"))
#expect(result.contains("stray text with no end marker"))
}
// MARK: - renderBlock content
@Test func renderBlockIncludesProjectIdentity() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let project = ProjectEntry(name: "My Project", path: dir)
let svc = ProjectAgentContextService(context: .local)
let block = svc.renderBlock(for: project)
#expect(block.contains(ProjectAgentContextService.beginMarker))
#expect(block.contains(ProjectAgentContextService.endMarker))
#expect(block.contains("\"My Project\""))
#expect(block.contains(dir))
#expect(block.contains("dashboard.json"))
}
@Test func renderBlockOmitsTemplateSectionForBareProject() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let project = ProjectEntry(name: "Bare", path: dir)
let svc = ProjectAgentContextService(context: .local)
let block = svc.renderBlock(for: project)
#expect(!block.contains("**Template:**"))
#expect(block.contains("**Configuration fields:** (none)"))
}
@Test func renderBlockIncludesTemplateWhenManifestPresent() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let scarfDir = dir + "/.scarf"
try FileManager.default.createDirectory(atPath: scarfDir, withIntermediateDirectories: true)
// Minimal valid v1 manifest — no config schema.
let manifest = """
{
"schemaVersion": 1,
"id": "author/example",
"name": "Example",
"version": "1.2.3",
"description": "…",
"contents": { "dashboard": true, "agentsMd": true }
}
"""
try manifest.data(using: .utf8)!.write(to: URL(fileURLWithPath: scarfDir + "/manifest.json"))
let project = ProjectEntry(name: "Example", path: dir)
let svc = ProjectAgentContextService(context: .local)
let block = svc.renderBlock(for: project)
#expect(block.contains("**Template:** `author/example` v1.2.3"))
}
@Test func renderBlockListsConfigFieldNamesNotValues() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let scarfDir = dir + "/.scarf"
try FileManager.default.createDirectory(atPath: scarfDir, withIntermediateDirectories: true)
// Schema-bearing manifest with one string field and one secret.
let manifest = """
{
"schemaVersion": 2,
"id": "x/y",
"name": "Y",
"version": "1.0.0",
"description": "…",
"contents": { "dashboard": true, "agentsMd": true, "config": 2 },
"config": {
"schema": [
{ "key": "site_url", "type": "string", "label": "Site URL", "required": true },
{ "key": "api_token", "type": "secret", "label": "API Token", "required": true }
]
}
}
"""
try manifest.data(using: .utf8)!.write(to: URL(fileURLWithPath: scarfDir + "/manifest.json"))
// A config.json with a "secret" VALUE — the block must NOT
// echo this value. If it does, secrets leak into an agent-
// readable file, which is exactly the thing to avoid.
let configJSON = """
{
"schemaVersion": 2,
"templateId": "x/y",
"values": {
"site_url": { "type": "string", "value": "https://example.com" },
"api_token": { "type": "keychainRef", "uri": "keychain://com.scarf.template.x-y/api_token:abc123" }
},
"updatedAt": "2026-04-24T00:00:00Z"
}
"""
try configJSON.data(using: .utf8)!.write(to: URL(fileURLWithPath: scarfDir + "/config.json"))
let project = ProjectEntry(name: "Y", path: dir)
let svc = ProjectAgentContextService(context: .local)
let block = svc.renderBlock(for: project)
// Field names present with type hints.
#expect(block.contains("`site_url`"))
#expect(block.contains("`api_token`"))
#expect(block.contains("(secret — name only, value stored in Keychain)"))
// CRITICAL: no VALUES appear — not the site URL, not the
// keychain ref. The block is safe to drop into an agent
// context.
#expect(!block.contains("https://example.com"))
#expect(!block.contains("keychain://"))
#expect(!block.contains("abc123"))
}
// MARK: - refresh end-to-end (temp dir on local filesystem)
@Test func refreshCreatesAGENTSMdWhenMissing() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let project = ProjectEntry(name: "Fresh", path: dir)
try ProjectAgentContextService(context: .local).refresh(for: project)
let agentsMd = dir + "/AGENTS.md"
#expect(FileManager.default.fileExists(atPath: agentsMd))
let contents = try String(contentsOf: URL(fileURLWithPath: agentsMd))
#expect(contents.contains(ProjectAgentContextService.beginMarker))
#expect(contents.contains(ProjectAgentContextService.endMarker))
#expect(contents.contains("\"Fresh\""))
}
@Test func refreshPreservesUserContentBelow() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let agentsMd = dir + "/AGENTS.md"
let userContent = "# Template\n\nDo the thing.\n"
try userContent.data(using: .utf8)!.write(to: URL(fileURLWithPath: agentsMd))
let project = ProjectEntry(name: "Preserved", path: dir)
try ProjectAgentContextService(context: .local).refresh(for: project)
let after = try String(contentsOf: URL(fileURLWithPath: agentsMd))
#expect(after.contains(ProjectAgentContextService.beginMarker))
#expect(after.contains("# Template"))
#expect(after.contains("Do the thing."))
// Block goes FIRST; user content follows.
let beginIdx = after.range(of: ProjectAgentContextService.beginMarker)!.lowerBound
let userIdx = after.range(of: "# Template")!.lowerBound
#expect(beginIdx < userIdx)
}
@Test func refreshIsFullyIdempotent() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let project = ProjectEntry(name: "Twice", path: dir)
let svc = ProjectAgentContextService(context: .local)
try svc.refresh(for: project)
let first = try Data(contentsOf: URL(fileURLWithPath: dir + "/AGENTS.md"))
try svc.refresh(for: project)
let second = try Data(contentsOf: URL(fileURLWithPath: dir + "/AGENTS.md"))
#expect(first == second)
}
@Test func refreshRewritesStaleBlock() throws {
let dir = try Self.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: dir) }
let agentsMd = dir + "/AGENTS.md"
// Pre-seed a stale Scarf block with a different project name
// and a user section below.
let seed = """
<!-- scarf-project:begin -->
Old stale content — project was called "Something Else".
<!-- scarf-project:end -->
# Template
"""
try seed.data(using: .utf8)!.write(to: URL(fileURLWithPath: agentsMd))
let project = ProjectEntry(name: "Current Name", path: dir)
try ProjectAgentContextService(context: .local).refresh(for: project)
let after = try String(contentsOf: URL(fileURLWithPath: agentsMd))
#expect(after.contains("\"Current Name\""))
#expect(!after.contains("Something Else"))
#expect(after.contains("# Template"))
}
// MARK: - Helpers
nonisolated static func makeTempDir() throws -> String {
let dir = NSTemporaryDirectory() + "scarf-project-context-test-" + UUID().uuidString
try FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
return dir
}
}
scarf/scarfTests/ProjectRegistryMigrationTests.swift
-129
View File
@@ -1,129 +0,0 @@
import Testing
import Foundation
@testable import scarf
/// v2.3 grew `ProjectEntry` with `folder` and `archived` fields.
/// Both are optional/defaulted at the decoder so v2.2-era
/// `~/.hermes/scarf/projects.json` files still parse cleanly, and
/// v2.3-written files are forward-compatible with v2.2 readers
/// (which ignore unknown keys). These tests lock in both ends of
/// that contract.
///
/// No disk or Hermes dependency — we work entirely with in-memory
/// `Data`, so the `TestRegistryLock` from `ProjectTemplateTests` isn't
/// needed. Safe to run in parallel with every other test suite.
@Suite struct ProjectRegistryMigrationTests {
@Test func decodesV22RegistryWithoutNewFields() throws {
// v2.2-era file: just name + path. No folder, no archived.
let json = """
{
"projects": [
{ "name": "Legacy", "path": "/Users/x/legacy" },
{ "name": "Another", "path": "/Users/x/another" }
]
}
""".data(using: .utf8)!
let registry = try JSONDecoder().decode(ProjectRegistry.self, from: json)
#expect(registry.projects.count == 2)
#expect(registry.projects[0].name == "Legacy")
#expect(registry.projects[0].path == "/Users/x/legacy")
// Defaults hydrate for absent v2.3 fields.
#expect(registry.projects[0].folder == nil)
#expect(registry.projects[0].archived == false)
}
@Test func decodesV23RegistryWithFolderAndArchived() throws {
let json = """
{
"projects": [
{ "name": "Client A", "path": "/Users/x/a", "folder": "Clients" },
{ "name": "Client B", "path": "/Users/x/b", "folder": "Clients", "archived": true },
{ "name": "Personal", "path": "/Users/x/p" }
]
}
""".data(using: .utf8)!
let registry = try JSONDecoder().decode(ProjectRegistry.self, from: json)
#expect(registry.projects.count == 3)
#expect(registry.projects[0].folder == "Clients")
#expect(registry.projects[0].archived == false)
#expect(registry.projects[1].folder == "Clients")
#expect(registry.projects[1].archived == true)
#expect(registry.projects[2].folder == nil)
#expect(registry.projects[2].archived == false)
}
@Test func encodeOmitsDefaultedFields() throws {
// A top-level, non-archived project should encode with ONLY
// name + path keys. This keeps v2.3-written registries
// loadable by v2.2 Scarf (which ignores unknown keys), and
// keeps the file clean for the common case.
let entry = ProjectEntry(name: "Plain", path: "/Users/x/plain")
let encoder = JSONEncoder()
encoder.outputFormatting = [.sortedKeys]
let data = try encoder.encode(entry)
let s = try #require(String(data: data, encoding: .utf8))
#expect(s == #"{"name":"Plain","path":"\/Users\/x\/plain"}"#)
}
@Test func encodeIncludesFolderWhenPresent() throws {
let entry = ProjectEntry(name: "Acme", path: "/a", folder: "Clients")
let encoder = JSONEncoder()
encoder.outputFormatting = [.sortedKeys]
let data = try encoder.encode(entry)
let s = try #require(String(data: data, encoding: .utf8))
#expect(s.contains(#""folder":"Clients""#))
// archived still omitted when false — cleanliness matters.
#expect(!s.contains(#""archived""#))
}
@Test func encodeIncludesArchivedOnlyWhenTrue() throws {
let archived = ProjectEntry(name: "Old", path: "/o", archived: true)
let encoder = JSONEncoder()
encoder.outputFormatting = [.sortedKeys]
let data = try encoder.encode(archived)
let s = try #require(String(data: data, encoding: .utf8))
#expect(s.contains(#""archived":true"#))
let active = ProjectEntry(name: "New", path: "/n", archived: false)
let data2 = try encoder.encode(active)
let s2 = try #require(String(data: data2, encoding: .utf8))
#expect(!s2.contains(#""archived""#))
}
@Test func roundTripPreservesAllFields() throws {
let original = ProjectRegistry(projects: [
ProjectEntry(name: "Top", path: "/t"),
ProjectEntry(name: "InFolder", path: "/f", folder: "Work"),
ProjectEntry(name: "ArchivedTop", path: "/a", archived: true),
ProjectEntry(name: "ArchivedInFolder", path: "/af", folder: "Work", archived: true)
])
let encoded = try JSONEncoder().encode(original)
let decoded = try JSONDecoder().decode(ProjectRegistry.self, from: encoded)
#expect(decoded.projects.count == 4)
#expect(decoded.projects[0].folder == nil && decoded.projects[0].archived == false)
#expect(decoded.projects[1].folder == "Work" && decoded.projects[1].archived == false)
#expect(decoded.projects[2].folder == nil && decoded.projects[2].archived == true)
#expect(decoded.projects[3].folder == "Work" && decoded.projects[3].archived == true)
}
@Test func identityStaysKeyedOnName() throws {
// ProjectEntry.id should remain `name`, so selecting by id
// across a folder-move or archive-flip still works without
// a reselection step.
let a = ProjectEntry(name: "Foo", path: "/p")
let b = ProjectEntry(name: "Foo", path: "/p", folder: "Clients")
let c = ProjectEntry(name: "Foo", path: "/p", archived: true)
#expect(a.id == "Foo")
#expect(b.id == "Foo")
#expect(c.id == "Foo")
#expect(a.id == b.id)
#expect(a.id == c.id)
}
}
scarf/scarfTests/ProjectTemplateTests.swift
-62
View File
@@ -1063,68 +1063,6 @@ final class TestRegistryLock: @unchecked Sendable {
#expect(cronPrompt.contains("{{PROJECT_DIR}}"))
}
/// Exercises the second shipped template — `awizemann/template-author` —
/// which is a skill-only bundle (no config, no cron, no memory). The
/// shape is deliberately different from site-status-checker so a
/// regression in the installer's "no config, no cron" path can't hide
/// behind the richer example template. Also asserts the skill lands
/// under the expected namespaced path so Hermes's recursive skill
/// discovery finds it.
@Test func templateAuthorParsesAndPlans() throws {
let bundle = try Self.locateExample(author: "awizemann", name: "template-author")
let service = ProjectTemplateService(context: .local)
let inspection = try service.inspect(zipPath: bundle)
defer { service.cleanupTempDir(inspection.unpackedDir) }
// Manifest shape: schemaVersion 2 (contains `skills` claim, which
// wasn't part of v1), no config, no cron, one skill.
#expect(inspection.manifest.id == "awizemann/template-author")
#expect(inspection.manifest.name == "Scarf Template Author")
#expect(inspection.manifest.version == "1.0.0")
#expect(inspection.manifest.schemaVersion == 2)
#expect(inspection.manifest.contents.dashboard)
#expect(inspection.manifest.contents.agentsMd)
#expect(inspection.manifest.contents.cron == nil)
#expect(inspection.manifest.contents.config == nil)
#expect(inspection.manifest.contents.memory == nil)
#expect(inspection.manifest.contents.skills == ["scarf-template-author"])
#expect(inspection.manifest.config == nil)
#expect(inspection.cronJobs.isEmpty)
// Plan: empty config, empty cron, but one skill queued for install
// under the template's namespaced dir. The namespace path has to
// match what the uninstaller wipes — `skills/templates/<slug>` —
// or uninstall leaves orphan skill files.
let scratch = try ProjectTemplateServiceTests.makeTempDir()
defer { try? FileManager.default.removeItem(atPath: scratch) }
let plan = try service.buildPlan(inspection: inspection, parentDir: scratch)
#expect(plan.projectDir.hasSuffix("awizemann-template-author"))
#expect(plan.cronJobs.isEmpty)
#expect(plan.configSchema == nil)
#expect(plan.configValues.isEmpty)
#expect(plan.memoryAppendix == nil)
// The skill should land at
// `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md`
// — namespace dir + skill folder + SKILL.md. Anything else
// breaks Hermes's recursive discovery or the uninstaller's
// `rm -rf` on the namespace dir.
let namespaceDir = try #require(plan.skillsNamespaceDir)
#expect(namespaceDir.hasSuffix("/skills/templates/awizemann-template-author"))
#expect(plan.skillsFiles.count == 1)
let skillDest = try #require(plan.skillsFiles.first?.destinationPath)
#expect(skillDest.hasSuffix("/scarf-template-author/SKILL.md"))
#expect(skillDest.hasPrefix(namespaceDir))
// No-config templates deliberately skip the manifest cache —
// the dashboard's Configuration button only shows up when
// `.scarf/manifest.json` exists, so a skill-only template
// like this one correctly doesn't surface that button.
// (See ProjectTemplateService.buildPlan lines 198–227.)
#expect(plan.manifestCachePath == nil)
}
/// Resolve the example bundle path robustly. Unit-test working dirs
/// differ between `xcodebuild test` (project root) and an Xcode IDE
/// run (build-output dir), so we walk up from this source file until
scarf/scarfTests/ProjectsViewModelTests.swift
-173
View File
@@ -1,173 +0,0 @@
import Testing
import Foundation
@testable import scarf
/// Exercises the v2.3 registry verbs added to ProjectsViewModel:
/// moveProject, renameProject, archiveProject, unarchiveProject,
/// + the derived `folders` list. All verbs write through to
/// `~/.hermes/scarf/projects.json` via ProjectDashboardService, so
/// each test uses TestRegistryLock to snapshot + restore the real
/// file. Cross-suite serialization ensures we don't race with other
/// registry-touching tests.
@MainActor @Suite(.serialized) struct ProjectsViewModelTests {
@Test func moveProjectSetsFolder() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "Alpha", path: "/a"),
ProjectEntry(name: "Beta", path: "/b")
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
#expect(vm.projects.count == 2)
vm.moveProject(vm.projects[0], toFolder: "Clients")
#expect(vm.projects.count == 2)
#expect(vm.projects.first(where: { $0.name == "Alpha" })?.folder == "Clients")
#expect(vm.projects.first(where: { $0.name == "Beta" })?.folder == nil)
// Round-trip: reload from disk and confirm the move persisted.
let fresh = ProjectDashboardService(context: .local).loadRegistry()
#expect(fresh.projects.first(where: { $0.name == "Alpha" })?.folder == "Clients")
}
@Test func moveProjectToNilReturnsToTopLevel() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "Nested", path: "/n", folder: "Clients")
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
vm.moveProject(vm.projects[0], toFolder: nil)
#expect(vm.projects[0].folder == nil)
let fresh = ProjectDashboardService(context: .local).loadRegistry()
#expect(fresh.projects[0].folder == nil)
}
@Test func renameProjectUpdatesNameAndPreservesOtherFields() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "OldName", path: "/p", folder: "Work", archived: false)
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
vm.selectProject(vm.projects[0])
let ok = vm.renameProject(vm.projects[0], to: "NewName")
#expect(ok == true)
#expect(vm.projects.count == 1)
#expect(vm.projects[0].name == "NewName")
#expect(vm.projects[0].folder == "Work")
#expect(vm.projects[0].archived == false)
// Selection follows the rename — the user stays on the same
// project they were on.
#expect(vm.selectedProject?.name == "NewName")
}
@Test func renameProjectRejectsDuplicateName() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "A", path: "/a"),
ProjectEntry(name: "B", path: "/b")
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
// Renaming A to B should be refused — B already exists.
let ok = vm.renameProject(vm.projects[0], to: "B")
#expect(ok == false)
// Registry unchanged.
#expect(vm.projects.map(\.name) == ["A", "B"])
}
@Test func renameProjectRejectsEmptyName() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "Foo", path: "/f")
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
#expect(vm.renameProject(vm.projects[0], to: "") == false)
#expect(vm.renameProject(vm.projects[0], to: " ") == false)
#expect(vm.projects[0].name == "Foo")
}
@Test func renameProjectToSameNameIsNoOpSuccess() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "Foo", path: "/f")
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
#expect(vm.renameProject(vm.projects[0], to: "Foo") == true)
// Whitespace around matching name also no-ops.
#expect(vm.renameProject(vm.projects[0], to: " Foo ") == true)
#expect(vm.projects[0].name == "Foo")
}
@Test func archiveAndUnarchiveProject() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "Target", path: "/t")
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
vm.selectProject(vm.projects[0])
#expect(vm.projects[0].archived == false)
#expect(vm.selectedProject != nil)
vm.archiveProject(vm.projects[0])
#expect(vm.projects[0].archived == true)
// Archiving clears the selection so the dashboard doesn't
// linger on a project the sidebar will hide.
#expect(vm.selectedProject == nil)
vm.unarchiveProject(vm.projects[0])
#expect(vm.projects[0].archived == false)
// Unarchive doesn't re-select — the user chose to hide it,
// surfacing it doesn't mean they want focus back.
#expect(vm.selectedProject == nil)
}
@Test func foldersListIsSortedAndDeduped() async throws {
let snapshot = TestRegistryLock.acquireAndSnapshot()
defer { TestRegistryLock.restore(snapshot) }
try seedRegistry(.init(projects: [
ProjectEntry(name: "A", path: "/a", folder: "Work"),
ProjectEntry(name: "B", path: "/b", folder: "Personal"),
ProjectEntry(name: "C", path: "/c", folder: "Work"),
ProjectEntry(name: "D", path: "/d"), // top-level
ProjectEntry(name: "E", path: "/e", folder: "") // empty string treated as nil
]))
let vm = ProjectsViewModel(context: .local)
vm.load()
#expect(vm.folders == ["Personal", "Work"])
}
// MARK: - Helpers
@MainActor
private func seedRegistry(_ registry: ProjectRegistry) throws {
try ProjectDashboardService(context: .local).saveRegistry(registry)
}
}
scarf/scarfTests/SessionAttributionServiceTests.swift
-153
View File
@@ -1,153 +0,0 @@
import Testing
import Foundation
@testable import scarf
/// Exercises the v2.3 sidecar at `~/.hermes/scarf/session_project_map.json`
/// via the real `ServerContext.local`. Each test snapshots + restores
/// the file through `TestRegistryLock` (reused — the sidecar lives
/// in the same scarf/ dir as projects.json, so serialising on one
/// lock prevents both cross-suite races).
///
/// We scope the shared lock to this file's registry helper so tests
/// here don't step on the real registry either.
@Suite(.serialized) struct SessionAttributionServiceTests {
@Test func loadOnMissingFileReturnsEmptyMap() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
Self.deleteSidecar()
let svc = SessionAttributionService(context: .local)
let map = svc.load()
#expect(map.mappings.isEmpty)
#expect(svc.projectPath(for: "anything") == nil)
#expect(svc.sessionIDs(forProject: "/anything").isEmpty)
}
@Test func attributeWritesMappingAndPersists() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
Self.deleteSidecar()
let svc = SessionAttributionService(context: .local)
svc.attribute(sessionID: "sess-1", toProjectPath: "/proj/a")
// Read back via a fresh service instance — confirms the
// write actually landed on disk, not just the in-memory map.
let fresh = SessionAttributionService(context: .local)
#expect(fresh.projectPath(for: "sess-1") == "/proj/a")
// updatedAt populated on write.
let map = fresh.load()
let ts = try #require(map.updatedAt)
#expect(!ts.isEmpty)
}
@Test func attributeIsIdempotent() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
Self.deleteSidecar()
let svc = SessionAttributionService(context: .local)
svc.attribute(sessionID: "s", toProjectPath: "/p")
let firstStamp = svc.load().updatedAt
// Call again with the same pair — should short-circuit, NOT
// bump updatedAt. We check that the timestamp didn't change
// even if the file would have been rewritten.
svc.attribute(sessionID: "s", toProjectPath: "/p")
let secondStamp = svc.load().updatedAt
#expect(firstStamp == secondStamp)
}
@Test func reattributeChangesMapping() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
Self.deleteSidecar()
let svc = SessionAttributionService(context: .local)
svc.attribute(sessionID: "s", toProjectPath: "/a")
svc.attribute(sessionID: "s", toProjectPath: "/b")
#expect(svc.projectPath(for: "s") == "/b")
#expect(svc.sessionIDs(forProject: "/a").isEmpty)
#expect(svc.sessionIDs(forProject: "/b") == ["s"])
}
@Test func reverseLookupReturnsAllAttributedSessions() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
Self.deleteSidecar()
let svc = SessionAttributionService(context: .local)
svc.attribute(sessionID: "s1", toProjectPath: "/proj")
svc.attribute(sessionID: "s2", toProjectPath: "/proj")
svc.attribute(sessionID: "s3", toProjectPath: "/other")
#expect(svc.sessionIDs(forProject: "/proj") == ["s1", "s2"])
#expect(svc.sessionIDs(forProject: "/other") == ["s3"])
#expect(svc.sessionIDs(forProject: "/nobody").isEmpty)
}
@Test func forgetRemovesMapping() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
Self.deleteSidecar()
let svc = SessionAttributionService(context: .local)
svc.attribute(sessionID: "s", toProjectPath: "/p")
#expect(svc.projectPath(for: "s") == "/p")
svc.forget(sessionID: "s")
#expect(svc.projectPath(for: "s") == nil)
// Forget on a missing session is a no-op, not an error.
svc.forget(sessionID: "s")
#expect(svc.projectPath(for: "s") == nil)
}
@Test func corruptedFileReturnsEmptyMap() throws {
let snapshot = Self.snapshot()
defer { Self.restore(snapshot) }
// Write garbage to the sidecar path and confirm the service
// treats it as "no attributions" rather than crashing. Users
// hand-editing the JSON shouldn't soft-brick the Sessions tab.
let path = ServerContext.local.paths.sessionProjectMap
try FileManager.default.createDirectory(
atPath: (path as NSString).deletingLastPathComponent,
withIntermediateDirectories: true
)
try "not json at all".data(using: .utf8)!.write(to: URL(fileURLWithPath: path))
let svc = SessionAttributionService(context: .local)
let map = svc.load()
#expect(map.mappings.isEmpty)
}
// MARK: - Helpers
/// Snapshot + restore the sidecar file (and delete if missing).
/// Uses the shared TestRegistryLock so this suite serialises
/// with any other registry-writing suite — both touch scarfDir.
static func snapshot() -> (lockToken: Any, data: Data?) {
// Re-use the ProjectTemplateTests lock implementation —
// same NSLock gates all scarfDir writes across suites.
let projectSnapshot = TestRegistryLock.acquireAndSnapshot()
let path = ServerContext.local.paths.sessionProjectMap
let sidecarData = try? Data(contentsOf: URL(fileURLWithPath: path))
return (lockToken: projectSnapshot as Any, data: sidecarData)
}
static func restore(_ snapshot: (lockToken: Any, data: Data?)) {
let path = ServerContext.local.paths.sessionProjectMap
if let data = snapshot.data {
try? data.write(to: URL(fileURLWithPath: path))
} else {
try? FileManager.default.removeItem(atPath: path)
}
// Release the shared lock via the existing helper.
TestRegistryLock.restore(snapshot.lockToken as? Data)
}
static func deleteSidecar() {
let path = ServerContext.local.paths.sessionProjectMap
try? FileManager.default.removeItem(atPath: path)
}
}
scripts/catalog.sh
+1 -6
View File
@@ -45,12 +45,7 @@ need_builder() {
}
need_ghpages() {
# `.git` is a directory in a regular clone but a pointer FILE in a
# `git worktree add` worktree — `-e` covers both. The earlier `-d`
# check falsely rejected worktrees, so the script's own error
# message told users to re-run `git worktree add` on a worktree
# that was already there and valid.
[[ -e "$GHPAGES_DIR/.git" ]] || die "no gh-pages worktree at $GHPAGES_DIR
[[ -d "$GHPAGES_DIR/.git" ]] || die "no gh-pages worktree at $GHPAGES_DIR
Run: git worktree add .gh-pages-worktree gh-pages"
}
templates/awizemann/template-author/staging/AGENTS.md
-55
View File
@@ -1,55 +0,0 @@
# Template Author — Agent Instructions
This project is a help surface for the `scarf-template-author` Hermes skill. The same instructions apply whether you're Claude Code, Cursor, Codex, Aider, or any other agent that reads `AGENTS.md`.
## What this project is
Two things:
1. A minimal dashboard (`.scarf/dashboard.json`) the user lands on after install. It's a Quick Start text widget + an empty list widget. The list is an optional scratchpad where you can log projects you've scaffolded for the user, giving them a running audit trail. That's nice-to-have, not mandatory.
2. A skill at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md`. The skill is the real value — it teaches you how to interview the user and scaffold a new Scarf-compatible project.
## What this project is NOT
- Not a running service. No cron jobs, no background tasks, no secrets.
- Not a dashboard you need to keep updated. The dashboard is documentation; the only mutation worth doing is appending to the Scaffolded Projects list after you scaffold something.
## When the user asks to create a Scarf project
The primary trigger. Phrases that should activate the full scaffolding flow:
- "Create a new Scarf project that …"
- "Scaffold a dashboard for …"
- "Set up a project to watch / track / report on …"
- "Help me author a Scarf template."
- "Build me a project that runs daily and …"
When you hear those:
1. Load the skill at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md` and follow its interview flow. Do not improvise — the skill encodes the specific invariants Scarf enforces (widget types, field-type constraints, the `{{PROJECT_DIR}}` token, the paused-on-install cron rule, the secret-fields-have-no-defaults rule).
2. Scaffold into a directory the user picks. Use absolute paths.
3. After writing files, tell the user to register the project: click **+** in Scarf's Projects sidebar and pick the directory. Do not try to edit `~/.hermes/scarf/projects.json` yourself — Scarf reloads the registry on its own and the UI path is safer.
4. Optionally append to the Scaffolded Projects list in this project's `dashboard.json` so the user has a local record of what you've built for them. Preserve every other field in the dashboard as-is.
## When the user asks reference questions
If the user asks something like "what widget types does Scarf support?" or "how do I add a secret field?", you don't need to scaffold anything — answer inline. The skill's reference sections cover:
- The seven widget types (`stat`, `progress`, `text`, `table`, `chart`, `list`, `webview`) and their required fields.
- The seven config field types (`string`, `text`, `number`, `bool`, `enum`, `list`, `secret`) and their constraint keys.
- The `AGENTS.md` contract that every scaffolded project should honour.
Point them at the skill file if they want to read it directly. It's ~400 lines of structured markdown.
## What not to do
- Don't scaffold without asking the user where the project should live. The interview always asks for a parent directory.
- Don't register secrets in `<project>/.scarf/config.json`. Secret field values go through the macOS Keychain at install time; `config.json` stores `keychain://…` URIs, never plaintext. A scaffolded project that hasn't been installed yet has no secrets on disk at all.
- Don't claim dashboard widget titles the cron job doesn't actually update. The scaffolded `AGENTS.md` is a contract — if it says "the cron updates Sites Up / Sites Down", the cron prompt must match.
- Don't skip `{{PROJECT_DIR}}` token substitution in cron prompts. Hermes doesn't set a CWD for cron runs, so relative paths resolve against the agent's own dir — the installer swaps `{{PROJECT_DIR}}` for the absolute project path at install time.
## Reference
- `SKILL.md` at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md` — the full scaffolding playbook.
- [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) — user-facing docs.
- [`awizemann/site-status-checker`](https://awizemann.github.io/scarf/templates/awizemann-site-status-checker/) — a complete working example covering dashboard stats, a configurable list, a cron job, a Site-tab webview, and a full AGENTS.md contract. Read it when you're unsure how a piece should look.
templates/awizemann/template-author/staging/README.md
-46
View File
@@ -1,46 +0,0 @@
# Scarf Template Author
A Hermes skill that teaches your agent how to scaffold a new Scarf project — and, because Scarf's `.scarftemplate` format is symmetric with a live project on disk, how to shape it so you can publish it to the catalog later if you want.
## What you get
Installing this template drops a skill at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md` and a minimal "how to use" project in a folder of your choice. Every agent that reads the standard `~/.hermes/skills/` directory — Claude Code, Cursor, Codex, Aider, and the rest of the [agents.md](https://agents.md/) family — picks the skill up automatically.
## How to use it
After install, open your agent in any directory and say something like:
- *"Create a new Scarf project that watches the number of open PRs in my GitHub repo."*
- *"Scaffold a Scarf dashboard that tracks daily focus time from my Toggl logs."*
- *"Set up a project that runs a cron job to summarise my inbox each morning."*
- *"Help me author a Scarf template I can share."*
The agent will ask four or five questions (purpose, data source, cadence, what to display, any secrets) and then write:
- `<your-dir>/.scarf/dashboard.json`
- `<your-dir>/.scarf/manifest.json` — only if you're going to use a configuration form or want to export later
- `<your-dir>/AGENTS.md`
- `<your-dir>/README.md`
- Optionally a cron job registered via `hermes cron create` (always created paused — you enable it from Scarf's Cron sidebar when ready).
When it's done, click **+** in Scarf's Projects sidebar and pick the directory. Your dashboard appears. Iterate on it by asking your agent to tweak widgets or add fields.
## Turning a local project into a shareable template
Once you're happy with the result, Scarf → Projects → Templates → *Export "&lt;name&gt;" as Template…* produces a `.scarftemplate` anyone can install. The exporter carries the configuration *schema* but never your filled-in values — so your secrets and personal settings stay local.
## About this template's own dashboard
The installed project itself is tiny — a single Quick Start text widget and an empty list widget meant to serve as a scratchpad for tracking which scaffolded projects you've created. Its only purpose is to give you a place to land after install and a reminder of the trigger phrases above. The real value is the skill.
## Reference
- [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) — full spec + troubleshooting.
- [`awizemann/site-status-checker`](https://awizemann.github.io/scarf/templates/awizemann-site-status-checker/) — a complete, non-trivial example the skill studies and references.
- Dashboard / configuration schemas are Swift-authoritative at `scarf/scarf/Core/Models/ProjectDashboard.swift` and `scarf/scarf/Core/Models/TemplateConfig.swift` in the Scarf repo.
## What this template intentionally is not
- Not an archetype picker. v1 is blank-slate conversational; pre-baked starters (`monitor`, `dev-dashboard`, `personal-log`, etc.) may land in v1.1 once we see what shapes people ask for most often.
- Not a graphical wizard. The conversational agent path is strictly richer than a fixed form, and dogfoods Scarf's agent-first philosophy.
- Not a remote-scaffolding tool. It writes files into a directory on the machine where the agent runs; pair with Scarf's remote-server mode if you want to scaffold onto another box.
templates/awizemann/template-author/staging/dashboard.json
-33
View File
@@ -1,33 +0,0 @@
{
"version": 1,
"title": "Template Author",
"description": "A Hermes skill that helps your agent scaffold new Scarf projects — ask in chat, answer a short interview, and land a working dashboard with the right shape to export as a .scarftemplate later. The Scaffolded Projects list below grows as you use the skill.",
"theme": { "accent": "blue" },
"sections": [
{
"title": "Quick Start",
"columns": 1,
"widgets": [
{
"type": "text",
"title": "Ask your agent",
"format": "markdown",
"content": "**This project gives you a skill, not a service.** There are no cron jobs running, no dashboards to maintain. The real value lives at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md`.\n\n**Trigger phrases** your agent listens for:\n\n- *\"Create a new Scarf project that watches …\"*\n- *\"Scaffold a dashboard to track …\"*\n- *\"Set up a project that runs a daily check on …\"*\n- *\"Help me author a Scarf template.\"*\n\nThe agent will interview you (purpose → data source → cadence → widgets → config → secrets), write `<your-dir>/.scarf/dashboard.json`, `<your-dir>/.scarf/manifest.json`, `<your-dir>/AGENTS.md`, and `<your-dir>/README.md`, then tell you to click **+** in Scarf's Projects sidebar to register the directory.\n\nWhen you're happy with the result, **Projects → Templates → Export** turns it into a `.scarftemplate` you can share.\n\nSee the [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) for the full spec."
}
]
},
{
"title": "Scaffolded Projects",
"columns": 1,
"widgets": [
{
"type": "list",
"title": "Projects this skill has built for you",
"items": [
{ "text": "Nothing yet — ask your agent to scaffold a project and it'll optionally log entries here.", "status": "pending" }
]
}
]
}
]
}
templates/awizemann/template-author/staging/skills/scarf-template-author/SKILL.md
-410
View File
@@ -1,410 +0,0 @@
---
name: scarf-template-author
description: Scaffold a new Scarf project — dashboard, optional configuration schema, optional cron job, and AGENTS.md — from a short conversational interview with the user. Output is immediately usable locally and cleanly exportable as a .scarftemplate bundle.
version: 1.0.0
author: Alan Wizemann
license: MIT
platforms: [macos]
metadata:
hermes:
tags: [Scarf, templates, scaffolding, dashboard, authoring]
homepage: https://github.com/awizemann/scarf/wiki/Project-Templates
prerequisites:
commands: [hermes]
---
# Scarf Template Author
Scaffold a new Scarf-compatible project from a conversational interview. The output is both (a) a working project on disk the user can register with Scarf and use immediately, and (b) correctly shaped to be exported as a `.scarftemplate` bundle via Scarf's Export flow later.
## When to invoke this skill
Activate when the user says things like:
- *"Create a new Scarf project that watches / tracks / reports on …"*
- *"Scaffold a dashboard for …"*
- *"Set up a project that runs a daily check on …"*
- *"Help me author a Scarf template."*
- *"Build me a Scarf project to monitor …"*
Do **not** activate for pure reference questions like *"what widget types does Scarf support?"* or *"how does Scarf handle secrets?"* — answer those inline from the reference sections below.
Also do not activate when the user explicitly wants to edit an existing project's dashboard — that's a plain file edit, not a scaffold.
## How a Scarf project is shaped on disk
A Scarf project is just a directory registered in `~/.hermes/scarf/projects.json`. For Scarf to render a useful dashboard and for the project to be exportable as a `.scarftemplate`, it needs these files at minimum:
```
<project>/
├── .scarf/
│ ├── dashboard.json # REQUIRED for dashboard rendering
│ └── manifest.json # OPTIONAL — required only if the project declares a config schema or you want to export cleanly
├── AGENTS.md # Cross-agent instructions (agents.md standard) — ship this for every project
└── README.md # User-facing explanation
```
If the project will have a scheduled job, ALSO register a cron entry via `hermes cron create`. For an exportable bundle, also author `cron/jobs.json` in the staging directory — that's where Scarf's exporter will pick jobs up from.
Secrets never land in `dashboard.json` or `config.json`. At install time, Scarf routes secret-type config values to the macOS Keychain; `config.json` stores `keychain://service/account` URIs. When scaffolding from scratch (no install), the user either manages secrets via the post-install Configuration editor after export, or stashes them in their `~/.hermes/config.yaml` if they're Hermes-level secrets rather than project-level.
## The interview
Ask these questions in order. Don't batch. Each answer shapes the next question.
### 1. Purpose and data source
- *"In one sentence — what does this project do?"*
- *"Where does its data come from? Files, a URL, a shell command's output, an API call, a database, a spreadsheet?"*
Goal: figure out whether the project is **passive** (user maintains some files, dashboard reflects them), **pull-based** (we fetch from an HTTP endpoint or CLI tool on a schedule), or **push-based** (something external writes to a file we watch).
### 2. Refresh cadence
- *"How often should it refresh? Every hour? Daily? Weekly? Only when I ask?"*
If "only when I ask" → no cron job; user invokes the agent manually. If any scheduled cadence → cron job.
Map to cron expressions:
- Every hour: `0 * * * *`
- Daily at 9 AM: `0 9 * * *`
- Weekly Monday 9 AM: `0 9 * * 1`
- Every 15 minutes: `*/15 * * * *`
### 3. What the dashboard shows
Explain the seven widget types (see Widget Catalog below) in plain English, then ask which ones feel right. Offer concrete suggestions based on the purpose:
- Counting things (open PRs, failing tests, up/down sites) → `stat` widgets.
- A list of items with status → `list` with `text` + `status` per item.
- Time-series data → `chart` with `line` or `bar` type.
- Rows × columns of heterogeneous data → `table`.
- A live URL (useful for monitoring a site) → `webview`. **Including a webview widget exposes a Site tab** next to the Dashboard tab — worth noting to the user.
- A progress bar for something with a clear 0-to-N scale → `progress`.
- Static help / markdown → `text` with `format: "markdown"`.
### 4. Configuration needs
- *"Does this project need anything configurable by the user — URLs to watch, API tokens, thresholds, a list of accounts?"*
If yes → design a config schema. Fields map to seven types (see Config Schema Design below). Remember: **secret fields never have defaults**; that's a hard validator rule.
If no → skip `.scarf/manifest.json`; the project works but won't have a Configuration form.
### 5. Target agents
- *"Which agents will operate this project? Just Claude Code? Also Cursor / Codex / Aider / other?"*
For v1 just write `AGENTS.md` — every modern agent reads it, and if you need a specific shim (CLAUDE.md, GEMINI.md, .cursorrules), add it as a symlink to AGENTS.md so content stays in sync.
## Widget Catalog (JSON shapes)
All widgets require `type` and `title`. Type-specific fields:
### `stat` — single metric
```json
{ "type": "stat", "title": "Sites Up", "value": 0,
"icon": "checkmark.circle.fill", "color": "green", "subtitle": "responded 2xx/3xx" }
```
`value` accepts number OR string (`WidgetValue` enum). `icon` is an SF Symbol name. `color` is one of: `green`, `red`, `blue`, `orange`, `yellow`, `purple`, `gray`.
### `progress` — 0.0 to 1.0 progress bar
```json
{ "type": "progress", "title": "Test Coverage", "value": 0.72, "label": "72% of statements" }
```
### `text` — markdown or plain text block
```json
{ "type": "text", "title": "Quick Start", "format": "markdown",
"content": "**1.** Click + in the Projects sidebar.\n\n**2.** ..." }
```
`format` is `"markdown"` or `"plain"`.
### `table` — columns × rows of strings
```json
{ "type": "table", "title": "Failing Tests",
"columns": ["Test", "Duration", "Last Passed"],
"rows": [["testFoo", "4.2s", "Apr 20"], ["testBar", "0.9s", "Apr 18"]] }
```
Every row MUST have the same length as `columns`.
### `chart` — line / bar / area / pie with series
```json
{ "type": "chart", "title": "Requests / day", "chartType": "line",
"xLabel": "Date", "yLabel": "Count",
"series": [{
"name": "staging",
"color": "blue",
"data": [{"x": "Apr 20", "y": 142}, {"x": "Apr 21", "y": 189}]
}]
}
```
`chartType` is `"line"`, `"bar"`, `"area"`, or `"pie"`.
### `list` — items with optional status badge
```json
{ "type": "list", "title": "Watched Sites",
"items": [
{ "text": "https://example.com", "status": "up" },
{ "text": "https://example.org", "status": "down" }
]
}
```
`status` values: `"up"`, `"down"`, `"pending"`, `"ok"`, `"warn"`, `"error"` — render as coloured badges.
### `webview` — embedded live URL
```json
{ "type": "webview", "title": "First Watched Site",
"url": "https://awizemann.github.io/scarf/", "height": 420 }
```
**Important:** including any `webview` widget in a dashboard exposes a **Site** tab next to the Dashboard tab in the project view. Useful for templates that watch something renderable. The agent can update `url` on cron runs to keep the Site tab in sync with config (e.g., set it to `values.sites[0]`).
## Config Schema Design
If the project needs user-configurable values, design a schema. Put it in `<project>/.scarf/manifest.json` with this shape:
```json
{
"schemaVersion": 2,
"id": "author/project",
"name": "My Project",
"version": "1.0.0",
"description": "Short one-liner.",
"contents": { "dashboard": true, "agentsMd": true, "config": 2 },
"config": {
"schema": [
{ "key": "sites", "type": "list", "itemType": "string", "label": "Sites",
"required": true, "minItems": 1, "maxItems": 25,
"default": ["https://example.com"] },
{ "key": "api_token", "type": "secret", "label": "API Token", "required": true }
],
"modelRecommendation": {
"preferred": "claude-haiku-4",
"rationale": "Short-running, tool-light workload — haiku is plenty."
}
}
}
```
Note: `contents.config` is the **count of schema fields**, not a boolean. In the example above it's `2` because there are two fields.
### Field types and constraints
| Type | Rendered as | Constraint keys |
|---|---|---|
| `string` | Text field | `pattern` (regex), `minLength`, `maxLength` |
| `text` | Multi-line editor | `minLength`, `maxLength` |
| `number` | Number field | `min`, `max` |
| `bool` | Toggle | — |
| `enum` | Segmented (≤4) / Dropdown (>4) | `options: [{value, label}]` (REQUIRED) |
| `list` | Repeatable rows | `itemType: "string"` (required), `minItems`, `maxItems` |
| `secret` | Password field, routes to Keychain | — |
Every field takes `key` (required), `label` (required), `description` (optional — markdown), `required` (bool), `default` (optional; type matches the field type).
### Writing good descriptions
Descriptions render inline with markdown support (bold, italic, code, links). Keep them short — a single line or two is ideal.
**Always use markdown link syntax for URLs**, never bare `https://…` — the Configuration sheet's inline text renderer doesn't word-break mid-URL, so a raw URL in a description will force that whole description's width to the URL's character length. Older Scarf versions clipped the sheet in that case; current versions wrap correctly, but the visible text is still cleaner with named links.
```json
// ✓ Good — short label, URL in the href
"description": "Token with `repo` scope. Get one [from the GitHub tokens page](https://github.com/settings/tokens)."
// ✗ Bad — raw URL bloats the visible text
"description": "Token with `repo` scope. Get one at https://github.com/settings/tokens"
```
Same rule for long file paths, API endpoints, or any other unbreakable token — wrap them in inline code (backticks) if they have to appear verbatim, and prefer markdown links otherwise.
### Hard rules
- **Secret fields MUST NOT have a `default`.** The validator rejects the manifest if they do — a default makes no sense because the Keychain entry doesn't exist yet at install time.
- **Enum fields MUST have non-empty `options`.**
- **List fields MUST have `itemType: "string"`** in v1 (only itemType supported).
- **Field keys MUST be unique** within a schema.
- **`schemaVersion` MUST be 2** when a `config` block is present; it stays 1 if there's no config.
- **`contents.config`** must equal the actual count of schema fields — a claim mismatch is rejected.
## Cron Job Design
If the project has a scheduled task, register a cron job via `hermes cron create` AND — if you expect the user to export this as a `.scarftemplate` — author a `cron/jobs.json` in the staging layout so the exporter picks it up.
### Staging shape (for exportable templates)
```
<project>/
├── .scarf/
├── AGENTS.md
├── README.md
└── cron/
└── jobs.json
```
Where `cron/jobs.json` is:
```json
[
{
"name": "Check site status",
"schedule": "0 9 * * *",
"prompt": "Read {{PROJECT_DIR}}/.scarf/config.json — get values.sites and values.timeout_seconds — then HTTP GET each URL with that timeout, write the results to {{PROJECT_DIR}}/status-log.md, and update {{PROJECT_DIR}}/.scarf/dashboard.json's stat widgets by title (Sites Up, Sites Down, Last Checked). Reply with a one-line summary."
}
]
```
### Gotchas
- **Hermes does not set a CWD when firing cron jobs.** Relative paths in the prompt resolve against wherever the Hermes process happens to be running, not the project. Always use `{{PROJECT_DIR}}` in the prompt — the installer substitutes the absolute path at install time. This is THE most common template-author mistake.
- **Cron jobs created by the installer start paused.** Their name is auto-prefixed with `[tmpl:<template-id>]`. The user enables them from Scarf's Cron sidebar when ready.
- **Registering a cron job for a user's local (non-exported) project:** run `hermes cron create --name "<descriptive name>" "<schedule>" "<prompt>"` directly, substituting the absolute `<project>` path for `{{PROJECT_DIR}}` yourself. Then `hermes cron pause <id>` so it doesn't run until the user opts in.
### Schedule quick reference
| Cadence | Expression |
|---|---|
| Every 15 minutes | `*/15 * * * *` |
| Hourly at :00 | `0 * * * *` |
| Daily at 9 AM | `0 9 * * *` |
| Weekly Monday 9 AM | `0 9 * * 1` |
| First of the month, 9 AM | `0 9 1 * *` |
## Writing the files
After the interview, write files in this order.
### Step 1 — confirm parent directory
Ask: *"Where should I create the project? Give me an absolute path — I'll make a `<project-name>` directory inside it."*
Make sure the parent exists and is writable. Make sure `<parent>/<project-name>` does NOT already exist. If it does, ask whether to pick a different name or bail.
### Step 2 — create the skeleton
```bash
mkdir -p <parent>/<project-name>/.scarf
```
### Step 3 — write `dashboard.json`
Use the Widget Catalog above. Always include:
- `version: 1`
- `title` (the project's display name)
- `description` (a one-liner shown under the title)
- `sections` (array; each has `title`, optional `columns` (1–4, default 3), `widgets`)
Keep section titles short. Group related widgets. First section is usually "Current Status" or similar with the key stats.
### Step 4 — write `manifest.json` (only if the project has a config schema)
Put the full manifest shape from Config Schema Design above. Use `schemaVersion: 2`, match `contents.config` to the actual field count, and ensure every secret field has no `default`.
If there's no config schema, skip this file — the project still works, it just won't have a Configuration button. You can add it later.
### Step 5 — write `AGENTS.md`
Every scaffolded project needs an `AGENTS.md` that covers:
- **Purpose** — what the project does.
- **Layout** — which files exist and what they're for.
- **Configuration** — if there's a config schema, document every field: what it's for, what valid values look like, what happens when it's missing.
- **Dashboard** — list every widget the cron job (if any) updates, by title. If the cron updates a webview widget's URL, document that explicitly.
- **Cron behaviour** — what the cron job does, what it reads, what it writes, what its exit criteria are.
- **Chat prompts** — common user questions and how to answer them (e.g., *"What's the status of my sites?"* → "read the top section of `status-log.md` and summarise").
- **What NOT to do** — e.g., *don't modify `.scarf/config.json` yourself; tell the user to open the Configuration button.*
Use `{{PROJECT_DIR}}` placeholders in AGENTS.md only if the template will be installed through the installer (which substitutes the token). For a hand-scaffolded local-only project, substitute the absolute path yourself — `{{PROJECT_DIR}}` only resolves at install time.
### Step 6 — write `README.md`
User-facing. Keep it short:
- One-paragraph purpose.
- How to install / first run (for an unexported project: "click + in Scarf's Projects sidebar").
- How to trigger the cron job manually (Cron sidebar → Run Now).
- A pointer at `AGENTS.md` for agents.
### Step 7 — register the cron job (if any)
For a local non-exported project:
```bash
hermes cron create --name "<descriptive name>" "<schedule>" "<prompt with absolute project dir substituted>"
# Then pause it so it doesn't fire until the user's ready:
hermes cron pause <newly-created-job-id>
```
Read the id back from `hermes cron list --json` or parse the create output.
For an exportable template (one you're staging in `templates/<author>/<name>/staging/`): just author `cron/jobs.json` — the installer registers + pauses at install time, and prefixes the name with `[tmpl:<id>]`.
### Step 8 — register the project with Scarf
Tell the user: *"I've written the files. Click the **+** button in Scarf's Projects sidebar and pick `<absolute-project-dir>`. The dashboard will appear."*
Do NOT edit `~/.hermes/scarf/projects.json` directly — Scarf owns that file and reloads it on its own. The UI path is safer.
### Step 9 (optional) — log to the Template Author project's list
If the user has the `awizemann/template-author` project installed (the one that shipped this skill), append an entry to its `dashboard.json`'s `Scaffolded Projects` list widget:
```json
{ "text": "<absolute-project-dir> — <one-line purpose>", "status": "ok" }
```
This gives the user a running audit trail of everything you've scaffolded for them. Preserve every other field in the dashboard as-is.
## Testing your scaffold
### Minimum smoke test
1. Tell the user to click **+** in Scarf's Projects sidebar and pick the directory.
2. Dashboard appears — sanity check every widget renders correctly.
3. If there's a cron job: click the job in Scarf's Cron sidebar → **Run Now**. The agent executes the prompt; dashboard updates when it finishes.
### Configuration-form test (only if schema was declared)
To verify the Configuration form renders, you need to *install* the project as a template — scaffolded projects don't go through the installer, so the form never runs. Export the project first:
1. Projects → Templates → **Export "&lt;name&gt;" as Template…** → save the `.scarftemplate` somewhere.
2. Projects → Templates → **Install from File…** → pick the bundle → the Configure step should render the form you designed.
3. Cancel the install (the preview sheet has a Cancel button) — you just wanted to verify the form shape.
### Catalog validation (only if publishing)
If the user plans to submit this to the public catalog at `awizemann.github.io/scarf/templates/`:
```bash
# From the repo root
./scripts/catalog.sh check
```
Validates every template in `templates/<author>/<name>/` against the Python validator — the same one the PR CI uses. Catches schema issues, claim mismatches, size violations, common secret patterns.
## Common pitfalls
Things to check before declaring the scaffold done:
- [ ] Every cron prompt uses `{{PROJECT_DIR}}` (for exported) OR an absolute path (for local-only). Relative paths will fail.
- [ ] `contents.config` in the manifest equals the actual field count. Claim mismatch = rejected.
- [ ] No `default` on any `secret` field.
- [ ] Every enum field has non-empty `options`.
- [ ] Every list field has `itemType: "string"`.
- [ ] Every table widget has rows of length equal to `columns`.
- [ ] Every webview widget has an https URL that renders something meaningful even pre-first-run (Scarf homepage is a decent placeholder).
- [ ] `dashboard.json` has `version: 1` at the top.
- [ ] `AGENTS.md` documents every config field, every updated widget, and the cron behaviour — the user relies on it as the source of truth when things drift.
- [ ] **No raw URLs in field descriptions.** Use `[link text](https://…)` markdown syntax instead — raw URLs read as long unbreakable tokens in the Configuration sheet. Same rule for long paths and other unbreakable strings; wrap in `` ` `` if they must appear verbatim.
- [ ] **Leave the `<!-- scarf-project:begin -->` / `<!-- scarf-project:end -->` region alone in the project's `AGENTS.md`.** As of Scarf v2.3, the app auto-injects a project-identity block at chat-start time (project name, directory, template id, configuration field names, cron jobs). Anything you write inside that region will be overwritten on the next chat start. Put template-specific agent instructions BELOW the block so they're preserved across refreshes.
## Reference — source of truth files
- **Dashboard widget schema** — `scarf/scarf/Core/Models/ProjectDashboard.swift` in the Scarf repo. If you need exact field types or defaults, read it.
- **Config schema + validation** — `scarf/scarf/Core/Models/TemplateConfig.swift` and `scarf/scarf/Core/Services/ProjectConfigService.swift`.
- **Exporter behaviour** — `scarf/scarf/Core/Services/ProjectTemplateExporter.swift`. Verifies what files the exporter will pick up from a live project and what it'll carry into a bundle.
- **Installer contract** — `scarf/scarf/Core/Services/ProjectTemplateInstaller.swift`. Verifies what `{{PROJECT_DIR}}` substitution covers and where installed files land.
- **Catalog validator** — `tools/build-catalog.py` in the Scarf repo. Run with `./scripts/catalog.sh check` for the same rules CI uses.
- **Worked example** — `templates/awizemann/site-status-checker/staging/` in the Scarf repo. Complete end-to-end: dashboard with stats + list + webview, a config schema with a list + a number, a cron job, an AGENTS.md that documents every moving part. Read it first whenever you're unsure how a piece should look.
- **User-facing docs** — [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates).
templates/awizemann/template-author/staging/template.json
-19
View File
@@ -1,19 +0,0 @@
{
"schemaVersion": 2,
"id": "awizemann/template-author",
"name": "Scarf Template Author",
"version": "1.0.0",
"description": "Install this to give your agent a skill that scaffolds new Scarf projects — dashboards, optional configuration schemas, cron jobs, and AGENTS.md — from a short conversational interview. Scaffolded projects are usable locally and cleanly exportable as .scarftemplate bundles.",
"minScarfVersion": "2.2.0",
"author": {
"name": "Alan Wizemann",
"url": "https://github.com/awizemann"
},
"category": "developer-tools",
"tags": ["meta", "authoring", "skill", "scaffolding"],
"contents": {
"dashboard": true,
"agentsMd": true,
"skills": ["scarf-template-author"]
}
}
templates/awizemann/template-author/template-author.scarftemplate
BIN
View File
Binary file not shown.
templates/catalog.json
-31
View File
@@ -63,37 +63,6 @@
"configurable"
],
"version": "1.1.0"
},
{
"author": {
"name": "Alan Wizemann",
"url": "https://github.com/awizemann"
},
"bundleSha256": "56ab97eeb45ab7b9e6715ce9c88ec2c953bf795698cd19628d300d5b8cffd475",
"bundleSize": 14610,
"category": "developer-tools",
"config": null,
"contents": {
"agentsMd": true,
"dashboard": true,
"skills": [
"scarf-template-author"
]
},
"description": "Install this to give your agent a skill that scaffolds new Scarf projects \u2014 dashboards, optional configuration schemas, cron jobs, and AGENTS.md \u2014 from a short conversational interview. Scaffolded projects are usable locally and cleanly exportable as .scarftemplate bundles.",
"detailSlug": "awizemann-template-author",
"id": "awizemann/template-author",
"installUrl": "https://raw.githubusercontent.com/awizemann/scarf/main/templates/awizemann/template-author/template-author.scarftemplate",
"minHermesVersion": null,
"minScarfVersion": "2.2.0",
"name": "Scarf Template Author",
"tags": [
"meta",
"authoring",
"skill",
"scaffolding"
],
"version": "1.0.0"
}
]
}