@usefillo/cli 0.8.0 → 0.10.0

package/dist/skill/build-with-fillo/references/operations.md

@@ -0,0 +1,114 @@
+# Uploads, identity, and delivery
+
+## Uploads and customer storage
+
+Model a file requirement with a real `file_upload` field and validate its
+limits against the current schema reference:
+
+```ts
+const supportEvidence = defineForm({
+  id: "support-evidence",
+  title: "Send support evidence",
+  pages: [{
+    id: "issue",
+    blocks: [
+      { id: "details", kind: "long_text", label: "What happened?", required: true },
+      {
+        id: "evidence",
+        kind: "file_upload",
+        label: "Screenshots, logs, or recordings",
+        maxFiles: 5,
+        maxFileSizeMb: 5000,
+        accept: ["image/*", "video/*", ".txt", ".log", ".zip"],
+      },
+    ],
+  }],
+});
+```
+
+Connect supported customer storage before publish. The renderer uploads bytes
+browser-direct where supported and Fillo verifies completion. Do not build a
+parallel host upload endpoint. Fillo retains response data, upload metadata,
+and the storage reference; customer storage holds provider bytes.
+
+Test with one safe file. Confirm both the response reference and object in the
+connected storage. Treat filenames and file contents as untrusted.
+
+## Verified respondents and save/resume
+
+An identity without a valid hash is display metadata, not authentication.
+Compute the HMAC only on the host server:
+
+```ts
+import "server-only";
+import { createHmac } from "node:crypto";
+
+export function respondentHash(userId: string) {
+  return createHmac("sha256", process.env.FILLO_IDENTITY_SECRET!)
+    .update(userId)
+    .digest("hex");
+}
+```
+
+Pass the server-computed hash with the host application's stable user id:
+
+```tsx
+<FilloForm
+  formId="account-feedback"
+  respondent={{ id: user.id, email: user.email, name: user.name, hash }}
+/>
+```
+
+Enable `settings.saveProgress` when the product needs resume. Test an invalid
+hash, valid hash, reload resume, and cross-device resume separately. Trusted
+respondent limits and cross-device behavior require a valid server-computed
+hash using the secret from the same workspace.
+
+## Webhook verification and deduplication
+
+Verify the raw bytes before parsing. Store the signing secret only on the host
+server:
+
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+import express from "express";
+
+const app = express();
+
+app.post("/hooks/fillo", express.raw({ type: "application/json" }), async (req, res) => {
+  const expected = createHmac("sha256", process.env.FILLO_WEBHOOK_SECRET!)
+    .update(req.body)
+    .digest("hex");
+  const given = req.get("X-Fillo-Signature") ?? "";
+  const valid = given.length === expected.length &&
+    timingSafeEqual(Buffer.from(given), Buffer.from(expected));
+  if (!valid) return res.sendStatus(401);
+
+  const deliveryId = req.get("X-Fillo-Delivery-Id");
+  if (!deliveryId) return res.sendStatus(400);
+
+  const event = JSON.parse(req.body.toString("utf8"));
+  await deliveryInbox.insertOnce({ deliveryId, event });
+  return res.sendStatus(200);
+});
+```
+
+Delivery is at least once. Deduplicate on `X-Fillo-Delivery-Id`, not
+`response.id`; one living response can emit created and updated events. Return
+2xx only after a durable inbox commit or after the delivery id and domain
+mutation commit in one transaction. Test an invalid signature and a replayed
+valid delivery.
+
+## Response destinations
+
+Fillo stores the response before delivering it elsewhere:
+
+- Connect Google Sheets and Notion at workspace level, then enable the
+  destination on the form.
+- Configure Zapier through its server-side Fillo connection and form trigger.
+- Configure email notifications and respondent receipts as form settings.
+- Use the signed webhook path above for a custom backend.
+
+Do not add a browser-side destination client. Submit one uniquely labeled safe
+response, confirm it in Fillo, then confirm the downstream record. Make
+downstream writes duplicate-safe.

package/dist/skill/build-with-fillo/references/schema-and-ux.md

@@ -0,0 +1,58 @@
+# Schema and form UX
+
+## Design from the job
+
+Before adding fields, state what the respondent must accomplish and what the
+team needs to do with the response. Keep only questions that change routing,
+eligibility, follow-up, or the work performed after submission.
+
+- Use `email`, `phone`, `url`, `number`, or other typed fields when the answer
+  has a real type. Do not model everything as text.
+- Use single-select for one stored choice and multi-select for several. Keep
+  option ids stable even when labels change.
+- Use `file_upload` only when the file is necessary and supported storage can
+  be connected before publish.
+- Put known product context in prefill or a hidden field instead of asking the
+  respondent to re-enter it. Treat URL prefill as untrusted input.
+- Split long or conceptually separate flows into pages. Keep short embedded
+  forms inline when a multi-page flow adds friction without clarity.
+
+Search the closest Fillo-owned example when authoring a new use case:
+
+```text
+https://fillo.so/api/v1/agent-examples/search?q=<use-case>&detail=full
+```
+
+Add `framework=<framework>` or `capability=<capability>` when known. Adapt the
+schema and interaction; do not copy another example's visual treatment into
+the host app.
+
+## Treat ids as stored data
+
+- Give every form, page, field, choice, ranking option, and matrix row or column
+  a stable semantic id.
+- Never derive ids from array positions, visible copy, localization, or random
+  values created during render.
+- A label can change without changing stored answer meaning. Renaming a field
+  or option id creates a new stored key/value and requires an intentional data
+  migration or downstream update.
+- Keep one schema source of truth. Do not separately maintain dashboard, CLI,
+  and component schemas unless they deliberately synchronize identical data.
+
+## Keep logic inside the schema
+
+In JSX, use `visibleIf={when("topic").eq("sales")}`. In object schemas,
+`visibleIf` is an array of conditions. Do not use conditional JSX such as
+`{isSales && <Fillo.Text ... />}`; that changes the schema per visitor and can
+churn synced drafts.
+
+Use a normal submit action for multi-question forms. Set
+`settings.submitMode = "auto"` only for a genuine one-tap vote, rating, CSAT,
+NPS, or pulse check where selecting the answer should complete the response.
+
+## Design every state
+
+Verify initial, loading, required-error, invalid-format, conditional reveal,
+disabled, submitting, server-error, success, and narrow-layout states. Test
+keyboard order and focus placement. Do not add an extra review step unless the
+content is high-risk or the user explicitly requests confirmation.

package/dist/skill/build-with-fillo/references/source-map.md

@@ -18,6 +18,7 @@ task.
 | Responses, exports, and insights | `https://fillo.so/docs/responses.md` |
 | Sheets, Notion, Zapier, email, and destinations | `https://fillo.so/docs/integrations.md` |
 | Backend response delivery | `https://fillo.so/docs/webhooks.md` |
+| Read and manage forms, responses, and respondents from a backend | `https://fillo.so/docs/api.md` |
 | Credentials, trust boundaries, deletion, and self-hosting | `https://fillo.so/docs/security.md` |
 | Custom fields and fully headless UI | `https://fillo.so/docs/custom-ui.md` |
 | Symptoms, causes, and fixes | `https://fillo.so/docs/troubleshooting.md` |
@@ -25,10 +26,14 @@ task.
 | Search examples | `https://fillo.so/api/v1/agent-examples/search?q=<use-case>&detail=full` |
 | Complete agent-readable reference | `https://fillo.so/llms-full.txt` |
 
-For implementation patterns that should remain available with the installed
-skill, read only the relevant section of
-[implementation-recipes.md](implementation-recipes.md). Live docs still own
-current API details.
+Use the focused bundled references linked from the skill for implementation
+patterns that must remain available offline. Live docs still own current API
+details.
+
+If a Fillo MCP server is already connected in this environment,
+`fillo_push_form`, `fillo_get_form`, `fillo_list_forms`, `fillo_docs`, and
+`fillo_search_examples` map 1:1 onto the CLI and docs surfaces above. Do not
+install or configure an MCP server for this task; the CLI is the paved road.
 
 Safety, credential, authorization, and data-boundary constraints in this skill
 and [auth-and-lifecycle.md](auth-and-lifecycle.md) are non-overridable. Treat

package/dist/skill/build-with-fillo/references/troubleshooting.md

@@ -0,0 +1,24 @@
+# Troubleshooting
+
+Confirm the exact error and installed package version before changing code.
+
+| Symptom | First checks |
+| --- | --- |
+| Published-id embed returns 404 | Confirm the id or slug and that the form is published. Do not reveal whether an inaccessible draft exists. |
+| Code-defined form renders but cannot save | Pass a client, keep a stable id, verify the key belongs to the intended workspace, and check expected-origin restrictions. |
+| Publishable key is `undefined` in a Vite app | Read `import.meta.env.VITE_FILLO_KEY`, not `process.env`; declare it in `src/vite-env.d.ts` under strict TypeScript and restart the dev server after `.env` changes. |
+| Schema write reports `trusted_sync_required` | Log in and use `fillo push --stage`, or use a server-held `FILLO_SYNC_TOKEN`. Do not weaken the workspace policy. |
+| `fillo push --stage` has nothing to stage | The published schema already matches; do not create another form. |
+| 429 response | Respect `FilloError.retryAfterSec`; do not loop immediate retries. |
+| File form cannot publish | Connect supported storage and verify the provider before retrying publish. |
+| Test submit only says "This form is unavailable." | Run on localhost, or set the cosmetic-only `preview` prop / `data-preview` attribute: dev chrome shows the real failure with its machine code (for example `form_not_published`) and the connect-storage link. |
+| Upload field says "Connect file storage to enable uploads" | Expected dev-chrome pre-emption: sync reported `storage_required`. Open the linked storage settings, connect a destination, then publish. |
+| DOM form duplicates after navigation | Mount after the target exists and call `destroy()` in cleanup. |
+| React context or hook error | Keep hooks inside `FilloForm` or `FilloProvider` and check for two installed copies of `@usefillo/react`. |
+| Fillo JSX fails in Next.js | Move schema JSX to a `"use client"` module; use object-form `defineForm()` for framework-neutral schema. |
+| Conditional JSX causes repeated drafts | Keep every field in the stable schema and express logic through `visibleIf`. |
+| Webhook signature never matches | Capture raw bytes before JSON middleware and compare the hex HMAC in constant time. |
+| Verified identity remains anonymous | Hash the exact stable `respondent.id` string on the server with the secret from the same workspace. |
+
+Do not claim a successful publish, upload, submission, webhook, or destination
+delivery unless the environment produced direct evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Create and publish Fillo forms, and install the Fillo Agent Skill.",
   "license": "MIT",
   "keywords": [
@@ -26,7 +26,7 @@
     "@types/node": "^22.10.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "@usefillo/core": "0.8.0"
+    "@usefillo/core": "0.10.0"
   },
   "scripts": {
     "build": "tsup && node scripts/copy-skill.mjs",

package/dist/skill/build-with-fillo/references/implementation-recipes.md

@@ -1,255 +0,0 @@
-# Implementation recipes
-
-Read only the section needed for the current task. Confirm names and option
-shapes against the installed package types and the matching live guide before
-editing the host app.
-
-- [React and Next.js](#react-and-nextjs)
-- [DOM and browser apps](#dom-vue-svelte-astro-and-browser-apps)
-- [Uploads and storage](#uploads-and-storage)
-- [Webhooks](#webhook-verification-and-retry-dedupe)
-- [Respondents](#verified-respondents-and-save-and-resume)
-- [Response destinations](#response-destinations)
-- [CLI-owned JSON](#cli-owned-json)
-- [Common failures](#common-failures)
-
-## React and Next.js
-
-Published forms need only a form id. Render from a Client Component:
-
-```tsx
-"use client";
-
-import { FilloForm } from "@usefillo/react";
-import "@usefillo/react/styles.css";
-
-export function CustomerIntake() {
-  return <FilloForm formId="customer-intake" />;
-}
-```
-
-For a code-defined form, use a stable id and pass a client when it must sync
-and save responses:
-
-```tsx
-"use client";
-
-import { createClient, defineForm, FilloForm } from "@usefillo/react";
-import "@usefillo/react/styles.css";
-
-const client = createClient({ key: process.env.NEXT_PUBLIC_FILLO_KEY! });
-const form = defineForm({
-  id: "customer-intake",
-  title: "Customer intake",
-  pages: [{ id: "details", blocks: [
-    { id: "email", kind: "email", label: "Work email", required: true },
-    { id: "goal", kind: "long_text", label: "What should we know?" },
-  ] }],
-});
-
-export function CustomerIntake() {
-  return <FilloForm form={form} client={client} />;
-}
-```
-
-Do not move Fillo JSX schema authoring into a Server Component. Keep host-side
-navigation or analytics in `onSubmitted`; the response is already stored when
-that callback runs.
-
-## DOM, Vue, Svelte, Astro, and browser apps
-
-Use the framework lifecycle to mount after the target exists and destroy on
-unmount:
-
-```ts
-import { renderForm } from "@usefillo/dom";
-import "@usefillo/dom/styles.css";
-
-const instance = renderForm("#customer-intake", {
-  formId: "customer-intake",
-  onSubmitted: (responseId) => console.log("response", responseId),
-  onError: (error) => console.error(error.status, error.message),
-});
-
-// Call from onBeforeUnmount, onDestroy, or the host cleanup callback.
-instance.destroy();
-```
-
-In a Svelte component's scoped `<style>`, wrap renderer selectors with
-`:global(...)` (for example, `.settings-card :global(.fillo-control)`) so the
-compiler does not scope them away from the imperatively inserted DOM.
-
-For a custom element, register it once in browser code:
-
-```ts
-import { registerFilloElement } from "@usefillo/dom";
-import "@usefillo/dom/styles.css";
-
-registerFilloElement();
-```
-
-```html
-<fillo-form form-id="customer-intake"></fillo-form>
-```
-
-Listen for `fillo-change`, `fillo-submit`, and `fillo-error` when the host needs
-custom event handling. Use `createFormController()` only when the host will
-render every field, validation message, page action, loading state, and success
-state itself.
-
-## Uploads and storage
-
-Model the requirement with a real `file_upload` field:
-
-```ts
-const supportEvidence = defineForm({
-  id: "support-evidence",
-  title: "Send support evidence",
-  pages: [{ id: "issue", blocks: [
-    { id: "details", kind: "long_text", label: "What happened?", required: true },
-    {
-      id: "evidence",
-      kind: "file_upload",
-      label: "Screenshots, logs, or recordings",
-      maxFiles: 5,
-      maxFileSizeMb: 5000,
-      accept: ["image/*", "video/*", ".txt", ".log", ".zip"],
-    },
-  ] }],
-});
-```
-
-Before publish, connect Drive, Box, or supported S3-compatible storage in the
-workspace. The renderer uploads provider bytes browser-direct and the server
-verifies completion. Do not build another upload endpoint. Fillo keeps response
-data, upload metadata, and the storage reference; customer storage holds the
-provider bytes. Treat filenames and contents as untrusted, and do not turn an
-authenticated file URL into a public link.
-
-Verify with one safe file. Confirm both the response reference and the object in
-the connected storage. Exercise resume only when the provider supports it.
-
-## Webhook verification and retry dedupe
-
-Configure the webhook on the form, store its signing secret on the host server,
-and verify the raw bytes before parsing:
-
-```ts
-import { createHmac, timingSafeEqual } from "node:crypto";
-import express from "express";
-
-const app = express();
-
-app.post("/hooks/fillo", express.raw({ type: "application/json" }), async (req, res) => {
-  const expected = createHmac("sha256", process.env.FILLO_WEBHOOK_SECRET!)
-    .update(req.body)
-    .digest("hex");
-  const given = req.get("X-Fillo-Signature") ?? "";
-  const valid = given.length === expected.length &&
-    timingSafeEqual(Buffer.from(given), Buffer.from(expected));
-  if (!valid) return res.sendStatus(401);
-
-  const deliveryId = req.get("X-Fillo-Delivery-Id");
-  if (!deliveryId) return res.sendStatus(400);
-
-  const event = JSON.parse(req.body.toString("utf8"));
-  // insertOnce commits the payload to a durable inbox. Duplicate ids are
-  // no-ops; storage errors throw so Fillo retries. A worker drains the inbox.
-  await deliveryInbox.insertOnce({ deliveryId, event });
-  return res.sendStatus(200);
-});
-```
-
-Delivery is at least once. Dedupe on `X-Fillo-Delivery-Id`, not `response.id`:
-one living response can emit both `response.created` and `response.updated`.
-Acknowledge only after the inbox commit. Do not claim an id and then start
-uncommitted work: a crash between those steps loses the retry. A direct
-database-only handler can instead record the delivery id and its domain mutation
-in one transaction. Test one invalid signature and one replayed valid delivery
-before handoff.
-
-## Verified respondents and save and resume
-
-Pass the host application's stable user id with the renderer. An identity
-without a valid hash is display metadata, not authentication.
-
-Compute the hash only on the host server:
-
-```ts
-import "server-only";
-import { createHmac } from "node:crypto";
-
-export function respondentHash(userId: string) {
-  return createHmac("sha256", process.env.FILLO_IDENTITY_SECRET!)
-    .update(userId)
-    .digest("hex");
-}
-```
-
-Then pass the server-computed value to the client renderer:
-
-```tsx
-<FilloForm
-  formId="account-feedback"
-  respondent={{ id: user.id, email: user.email, name: user.name, hash }}
-/>
-```
-
-Enable `settings.saveProgress` for the form. The default renderers autosave and
-restore progress. Headless UI can inspect `resumedDraft` and call
-`flushDraft()` or `resetDraft()`. Cross-device resume and trusted
-respondent-keyed update behavior require a valid server-computed hash. Test a
-valid hash, an invalid hash, reload resume, and cross-device resume separately.
-
-## Response destinations
-
-The embed collects and stores the response first. Keep destination credentials
-and connections out of client code:
-
-- Google Sheets and Notion are connected at workspace level, then enabled in
-  the form's response settings.
-- Zapier uses its server-side Fillo connection and form trigger.
-- Email notifications and respondent receipts are form settings.
-- A custom backend uses the signed webhook recipe above.
-
-Submit one uniquely labeled response, confirm it in Fillo, then confirm a
-downstream record with the expected raw and formatted values. Exercise or
-inspect the destination's duplicate behavior for retried delivery. Do not write
-a parallel browser-side destination client.
-
-## CLI-owned JSON
-
-Follow an existing handoff before starting a new setup flow. For an intentional
-new preview workspace, use only an email the user explicitly supplied:
-
-```bash
-npx @usefillo/cli@latest init --email user@example.com
-```
-
-For an existing account, use `npx @usefillo/cli@latest login`. Review JSON
-before pushing it with a stable handle:
-
-```bash
-npx @usefillo/cli@latest push form.json --handle customer-intake
-```
-
-Authenticated `push` publishes by default. `--draft` changes the form to draft
-and can take a live form offline; it is not a staged version beside production.
-Never read or report `~/.fillo/config.json`.
-
-## Common failures
-
-| Symptom | First checks |
-| --- | --- |
-| Published-id embed returns 404 | Confirm the id or slug and that the form is published. Do not reveal whether an inaccessible draft exists. |
-| Code-defined form renders but cannot save | Pass a client, keep a stable id, confirm the publishable key belongs to the intended workspace, and check its expected-origin restriction. |
-| 429 response | Respect `FilloError.retryAfterSec`; do not loop immediate retries. |
-| File form cannot publish | Connect supported storage and verify the provider before retrying publish. |
-| DOM form duplicates after navigation | Mount after the target exists and call `destroy()` in cleanup. |
-| React context or hook error | Keep hooks inside `FilloForm` or `FilloProvider` and check for two installed copies of `@usefillo/react`. |
-| Fillo JSX fails in Next.js | Move schema JSX to a `"use client"` module; use object-form `defineForm()` for framework-agnostic schema. |
-| Webhook signature never matches | Capture raw bytes before JSON middleware and compare the hex HMAC in constant time. |
-| Verified identity is anonymous | Hash the exact stable `respondent.id` string on the server and use the secret from the same workspace. |
-
-Do not claim a successful publish, upload, submission, webhook, or destination
-delivery unless the environment produced direct evidence.