fimo 0.8.0 → 0.9.0-experimental.2

package/assets/skills/fimo-cli/references/webhooks.md

@@ -0,0 +1,162 @@
+# Outbound webhooks
+
+> **Run via `npx fimo@latest <command>`** so the event catalog and delivery commands match the platform.
+
+> **Beta:** Test each destination and inspect its delivery history before depending on it in production.
+
+Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.
+
+Webhook commands require Full Access to the project. Do not attempt them when the current CLI identity has Edit, Comment, View, or agent access; the API enforces the same permission boundary as Studio.
+
+## Start from the live event catalog
+
+```bash
+fimo webhooks events
+fimo webhooks events form.submitted
+```
+
+Run this before writing a custom payload. The list shows supported event types, descriptions, and valid
+`event.data...` template variables. Pass one event name to get its example payload too. The initial families are:
+
+- Forms: `form.submitted`
+- Publish: `publish.started`, `publish.succeeded`, `publish.failed`, `publish.unpublished`
+- Agents: run started/completed/failed/cancelled and review requested/resolved
+- Analytics: `analytics.report_ready`
+- Media: uploaded/updated/deleted/generated/processing_failed
+- Entries: `entry.changed`
+
+Do not guess variable paths. The common envelope is:
+
+```json
+{
+  "id": "event-id",
+  "type": "form.submitted",
+  "version": 1,
+  "test": false,
+  "createdAt": "2026-07-17T10:00:00.000Z",
+  "project": { "id": "project-id" },
+  "env": { "name": "main" },
+  "data": {}
+}
+```
+
+Omit `--body` to send this full envelope. Prefer that default when the receiver can accept Fimo's shape.
+
+## Create a provider-specific request
+
+Store credentials as project secrets, never literal header flags:
+
+```bash
+printf '%s' "$RESEND_API_KEY" | fimo secrets set RESEND_API_KEY --stdin
+
+fimo webhooks create waitlist-resend \
+  --event form.submitted \
+  --form waitlist \
+  --url https://api.resend.com/contacts \
+  --header "Authorization=bearer:RESEND_API_KEY" \
+  --body '{"email":"{{ event.data.submission.data.email }}"}'
+```
+
+Header sources:
+
+- `Name=secret:KEY`: secret is the complete value
+- `Name=bearer:KEY`: `Bearer ` plus the secret
+- `Name=token:KEY`: `token ` plus the secret
+- `Name=literal:value`: non-secret fixed value
+
+Secret-backed values resolve when a delivery runs, so rotating a project secret updates later deliveries without editing the webhook. Fimo masks destination URLs, credentials, payload secrets, and response excerpts in CLI and Studio output.
+
+## Shape custom JSON safely
+
+`--body` accepts JSON with exact `{{ event... }}` substitutions in values:
+
+```bash
+fimo webhooks create publish-slack \
+  --event publish.succeeded \
+  --url https://hooks.slack.com/services/... \
+  --body '{"text":"Published {{ event.data.publication.url }}"}'
+```
+
+Use `--body @path/to/payload.json` for a file or `--body -` for stdin. Paths resolve from `-C` or the current
+project directory.
+
+When a variable occupies the entire JSON value, objects and arrays retain their JSON type:
+
+```json
+{
+  "submission": "{{ event.data.submission }}",
+  "email": "{{ event.data.submission.data.email }}"
+}
+```
+
+Do not add executable transform scripts or workers to a project just to reshape a payload. Use the JSON template for deterministic mappings; use an external workflow endpoint only when the integration genuinely needs branching or code.
+
+Available filters are event-specific:
+
+- `--environments <main|all>` for the event origin; the default is `main`
+- `--form <id>` for `form.submitted`
+- `--agent <name>` for agent events
+- `--media-type <image|video|audio|document|other>` for media events
+- `--action <created|updated|deleted>`, `--content-type <name>`, and `--locale <locale>` for `entry.changed`
+- `--debounce-changes <immediate|5s|30s|1m>` for direct `entry.changed` delivery grouping
+
+`entry.changed` represents content accepted in the selected environments. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes its origin at `event.env.name`.
+
+## Inspect before depending on it
+
+```bash
+fimo webhooks list
+fimo webhooks get <webhook-id>
+fimo webhooks test <webhook-id> --wait
+fimo webhooks deliveries <webhook-id> --limit 20
+fimo webhooks delivery <webhook-id> <delivery-id>
+```
+
+`test` uses the selected event's documented example data and adds `X-Fimo-Test: true`. `--wait` waits up to 60
+seconds for success or failure. Pass `--data '{...}'` only when a specific shape needs testing.
+
+Fimo automatically retries temporary failures with backoff. After retries are exhausted:
+
+```bash
+fimo webhooks retry <webhook-id> <delivery-id>
+```
+
+Use the delivery error code and attempt history to distinguish destination errors, timeouts, missing secrets, invalid templates, and blocked unsafe URLs. A delivery accepts up to five manual retries.
+
+## Manage configurations
+
+```bash
+fimo webhooks update <webhook-id> --enabled off
+fimo webhooks update <webhook-id> --url https://example.com/hooks/fimo
+fimo webhooks update <webhook-id> --default-body
+fimo webhooks delete <webhook-id>
+```
+
+Webhooks belong to the project, with up to 20 configurations per project. The same configuration is visible from every environment. Delivery listens to `main` by default. Use `--environments all` to include branch activity, or `--environments main` to return to main-only delivery.
+
+## Verify Fimo signatures
+
+Signing is on by default. Save the signing secret shown once at creation. Fimo sends:
+
+- `X-Fimo-Delivery`: stable delivery ID
+- `X-Fimo-Event`: event type
+- `X-Fimo-Event-Id`: stable event ID for receiver deduplication
+- `X-Fimo-Test`: `true` for synthetic test deliveries
+- `X-Fimo-Timestamp`: Unix timestamp for the attempt
+- `X-Fimo-Signature`: `v1=` plus HMAC-SHA256 of `<timestamp>.<raw-request-body>`
+
+At the receiver, reject stale timestamps and compare the computed signature with a timing-safe comparison before parsing or acting on the payload. Rotate an exposed signing secret with:
+
+```bash
+fimo webhooks rotate-secret <webhook-id>
+```
+
+Save the returned value immediately; it is not shown again.
+
+## Guardrails
+
+- Destinations must use public HTTPS URLs in production. Local/private/link-local addresses and redirects are blocked.
+- Do not place access tokens in URLs, literal headers, payload templates, logs, or committed files.
+- Do not retry a pending or actively retrying delivery manually.
+- Do not assume a successful queue operation means the destination accepted the request; inspect the delivery result.
+- Use `--json` when another agent or script needs stable, parseable output.

package/assets/skills/fimo-migration/SKILL.md

@@ -17,7 +17,10 @@ exports, source repositories, CMS exports, media folders, or any hybrid of those
 It owns intake, source inventory, URL crawl bootstrapping, ledger normalization,
 imports, and QA so any LLM can run the work without silently dropping content.
 
-> Run every `fimo` command as `npx fimo@latest <command>` — always the latest CLI, no global install.
+> Run every `fimo` command as `npx fimo <command>` when the project declares a
+> `fimo` dependency (adopted/wrapped projects pin an exact version tied to their
+> backend — never override it with `@latest`). Only fall back to
+> `npx fimo@latest` when the project has no `fimo` dependency.
 
 ## Non-Negotiables
 
@@ -30,6 +33,13 @@ imports, and QA so any LLM can run the work without silently dropping content.
   ledger.
 - Source exports beat inferred crawls. If CSV/XML/JSON exports, media folders, or
   source code exist, treat the public URL as visual/SEO reference only.
+- A working JS codebase is wrapped, not rewritten. Wrap mode
+  (`references/wrap.md`) keeps the user's routing, styling, and components
+  untouched; the diff is wiring + wrappers + config only. As the coding
+  agent you own the whole wrap loop — run `npx fimo migrate` yourself and
+  follow `references/wrap.md` § W0 (relay the recorded data-source
+  decisions to the user, then loop `npx fimo migrate wrap --check` to
+  exit 0).
 - Builder HTML is evidence, not the final runtime. Rebuild with Fimo conventions,
   schemas, forms, media primitives, translations, and routes.
 - Do not report completion until the QA gate passes or every failed check is
@@ -59,7 +69,15 @@ imports, and QA so any LLM can run the work without silently dropping content.
      pack.
    - **hybrid**: source files plus public URL. Use source-backed as truth and URL
      for route, SEO, visual, and behavior comparison.
-4. Create or update the canonical ledger described in
+4. Pick the mode:
+   - **wrap** (default for a source-backed, working JS codebase — Next.js,
+     Vite/React, React Router): keep the user's stack, adopt the repo with
+     `fimo init`, and make content editable by wrapping it in place. Never
+     rewrite routing, styling, or components. Follow `references/wrap.md`.
+   - **rebuild**: url-only sources, builder exports/HTML dumps, non-JS
+     backends, or codebases that do not build. Follow the standard workflow
+     phases.
+5. Create or update the canonical ledger described in
    `references/manifest.md`.
 
 ## Workflow
@@ -96,6 +114,8 @@ node <this-skill>/scripts/write-migration-report.mjs <project-root>
 ## References
 
 - `references/workflow.md` - full decision tree and phase order.
+- `references/wrap.md` - wrap mode: adopt a working JS codebase and wrap its
+  content in place (default for source-backed JS sites).
 - `references/manifest.md` - canonical migration ledger schema.
 - `references/content.md` - CMS, entries, references, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.

package/assets/skills/fimo-migration/references/content.md

@@ -18,6 +18,14 @@ ways:
    news teasers, and feature lists are almost always collections even when the
    source renders them inside one page.
 
+> **Rebuild path only.** These rules apply when Fimo re-authors the site
+> (URL/export migrations): the rebuilt code is disposable, so content belongs
+> in collections aggressively. **Wrap mode is deliberately stricter** — the
+> user's code stays primary, page furniture and nav stay in code with `t()`
+> labels, and every collection candidate is confirmed with the user first.
+> See `wrap.md` (W0 and the generated agent-prompt) — in wrap mode that
+> guidance overrides this section.
+
 After the source-faithful rebuild, treat **any hardcoded array of 3+ items with
 the same shape** as a collection candidate. Do not leave it hardcoded.
 
@@ -97,3 +105,19 @@ Skipped fields or entries require a manifest note with:
 - reason
 - owner impact
 - suggested action
+
+## Scaffolded CMS — verify pages render
+
+When `fimo migrate --scaffold-cms` wires the site to Fimo, the machine does the
+deterministic work: it maps the CMS's components and dynamic zones to editable
+Fimo blocks, seeds every block with generic example content in the shape the
+components expect, and swaps the client's fetch for the generated Fimo adapter —
+so the whole site reads from Fimo with no per-view wiring.
+
+The last mile is yours and it is per-site. Open the main pages in `pnpm dev` (a
+list, a detail, the page-builder home) and confirm each renders. Every renderer is
+the site's own code, so a component may read a field the generic content did not
+fill, or expect a slightly different shape. Where a section renders blank or
+throws, fix it at that component — a defensive default, or the field it truly
+needs — and re-check. Record anything you cannot resolve as a caveat. Do not
+re-scaffold, re-wire, or hand-wrap content; the machine owns those.

package/assets/skills/fimo-migration/references/manifest.md

@@ -34,6 +34,7 @@ follow-up agents, and import/QA checks.
   "seo": [],
   "unsupported": [],
   "unresolved": [],
+  "wrap": null,
   "qa": {
     "status": "not-run|passed|failed|passed-with-unresolved",
     "checks": []
@@ -41,6 +42,40 @@ follow-up agents, and import/QA checks.
 }
 ```
 
+## Wrap Block (wrap mode only)
+
+When the migration is a wrap (see `references/wrap.md`), set
+`source.mode: "source-backed"` and fill the `wrap` block; leave it `null` for
+rebuild migrations:
+
+```json
+{
+  "wrap": {
+    "mode": "wrap",
+    "framework": "next|react-router|vite",
+    "adopted": true,
+    "wired": true,
+    "coverage": {
+      "wrappable": 0,
+      "wrapped": 25,
+      "ignored": 0,
+      "unresolvedItems": 0
+    },
+    "seeded": {
+      "labels": 21,
+      "wrappedMedia": 3,
+      "wrappedRichText": 1
+    },
+    "planPath": ".fimo/migration/plan.json"
+  }
+}
+```
+
+`coverage` mirrors the final `fimo migrate wrap --check` output: `wrappable`
+must be 0 (or fully accounted for by `ignored` + `unresolvedItems`, each with a
+ledger entry). `seeded` counts must match what `fimo labels list` /
+`fimo entries list` report — fallback-only content is not seeded.
+
 ## Required Item Fields
 
 Every route, content type, entry batch, media asset, form, redirect, locale, SEO

package/assets/skills/fimo-migration/references/qa.md

@@ -18,8 +18,11 @@ Run this gate before reporting completion.
 ## Behavior
 
 - Dependencies are installed in the target project.
-- The project builds successfully.
-- Local dev starts without Vite loader/schema/form generation errors.
+- The project builds successfully **with its own toolchain** (`next build`,
+  `vite build`, …) — wrapped sites are not Vite/React-Router projects; never
+  assume Fimo-template tooling.
+- Local dev starts without loader/schema/form generation errors (Vite errors
+  apply to rebuild-mode projects only).
 - Primary routes render without console/runtime errors.
 - Collection listing/detail pages work with imported data, seed data, or explicit
   empty states.
@@ -33,6 +36,25 @@ Run this gate before reporting completion.
 - Remove generated placeholder copy from visible UI.
 - Verify media aspect ratios and no broken images on primary routes.
 
+## Wrap Mode (additional blocking checks)
+
+When the manifest says `mode: "wrap"`:
+
+- `fimo migrate wrap --check` exits zero — it enforces coverage (zero
+  unwrapped items), render parity (rendered text/marks/media/links identical
+  to the pre-wrap baseline), and seeding (every wrapped key exists in the
+  database) — or every remaining item is an explicit ignored/unresolved
+  ledger entry with a reason.
+- Labels are seeded: every `FimoText`/`t()` key exists in `fimo labels list`
+  with the original string. Fallback-only content fails the gate.
+- Wrapped media/rich text have their `WrappedMedia`/`WrappedRichText` entries
+  created and assets uploaded.
+- Render parity: pages render identically to pre-migration — same text, same
+  formatting marks (bold/italic/underline/links), same media.
+- Diff audit: the migration diff contains only wiring, wrappers, label calls,
+  config, and dependency changes. Any routing/styling/component rewrite fails
+  the gate.
+
 ## Import Verification
 
 Record:

package/assets/skills/fimo-migration/references/workflow.md

@@ -2,6 +2,14 @@
 
 Use this as the phase contract for complete migrations.
 
+> **Mode fork.** For a source-backed, WORKING JS codebase (Next.js, Vite/React,
+> React Router), wrap mode is the default: skip Phases 0 and 6 below and follow
+> `references/wrap.md` (adopt via `fimo init`, scan via `fimo migrate wrap`,
+> wrap in place, seed, verify). Phases 3–5 (content model, media/forms, import)
+> and Phase 8 (QA + report) still apply — wrap changes how content becomes
+> editable, not the accounting obligations. Everything else here is the rebuild
+> path.
+
 ## Phase 0: Target Safety
 
 1. Confirm the target path.
@@ -119,7 +127,10 @@ Required order:
 Record target IDs, import counts, failures, and unresolved items in the
 canonical ledger. Generated JSON without import counts is still draft state.
 
-## Phase 6: Fimo Implementation
+## Phase 6: Fimo Implementation (rebuild mode)
+
+In wrap mode this phase is replaced by `references/wrap.md` phases W3–W5
+(wire, wrap, seed); do not rebuild pages for a wrapped site.
 
 Implement routes, schemas, forms, entries, media, redirects, translations, and
 React pages with Fimo conventions.