chatfuel-lab/wizard / content/skills/chatfuel-update
chatfuel-update
VerifiedUpdate a Chatfuel app to the latest upstream content and resolve the conflicts it reports — the files where upstream moved and you had already edited them. Use when `chatfuel-wizard update` reports conflicts, when the user asks to update the app, pull in fixes, or move to newer wizard content.
Updating a Chatfuel app
The app in this directory was generated by @chatfuel/wizard and carries
.chatfuel/lock.json, which records what every file was made of: where it came
from, the digest it had when it landed, and the commit it came from.
chatfuel-wizard update reads that lock and decides each file by digest:
| upstream | on disk | what happens |
|---|---|---|
| unchanged | anything | skipped |
| changed | still the bytes the wizard wrote | overwritten, no question asked |
| changed | edited since | left exactly as it is, reported as a conflict |
| — generated here | anything | never written by update; you regenerate it |
The overwrites are the CLI's job and it needs no help with them. The conflicts are yours. They are the files where somebody's work and somebody else's work landed on the same lines, and resolving them is what this skill is for.
So is the last row. The typed client under src/vendor/api/generated/ was never
copied from upstream: it is generated from the schema and the operation
documents, and the lock marks it generated — no digest, nothing to fetch. Both
of its inputs are files the update moves, so when either moves the CLI prints
a fourth list, regenerate the client, and step 6 is what closes it.
The one rule
Change only the files the CLI lists under conflicts.
Not the files under update — the CLI writes those itself, and editing them
puts the app out of step with its own lock. Not the files under skipped.
Not a file that "obviously also needs it". Not .chatfuel/lock.json — it is
written by the CLI and by nothing else, ever.
If resolving a conflict genuinely requires touching a file outside the list, stop and tell the user what and why. Do not do it silently.
Two things sit outside that rule, and both are steps below:
src/operationDocs.ts(step 4), which an app made before the document registry existed does not have andupdatecannot add.- everything under
src/vendor/api/generated/(step 6), which you never edit but do regenerate.npm run codegenrewrites that whole directory, and the diff it leaves is the expected result, not a problem to fix by hand.
The sequence
Run these in order. Do not skip step 1; the update refuses a dirty tree on
purpose, because git checkout . is the undo button for the whole thing.
git status --porcelain # 1
npx @chatfuel/wizard@latest update --dry-run --json # 2
npx @chatfuel/wizard@latest update # 3
npm run codegen # 6 — prints the install line and stops, the first time
npm install --save-dev --save-exact @graphql-codegen/… # 6 — exactly the line the run above printed
npm run codegen # 6 — again, now that it is there
npx @chatfuel/wizard@latest update --resolved <files> # 7
npm run build # 8
Steps 4, 5 and 9 have no command of their own: they are a file you may have to write, the merges, and the report.
-
Get to a clean tree.
git status --porcelainAnything there: ask the user to commit or stash it. Do not commit their work for them without asking.
-
Read the plan, with both sides of each conflict.
npx @chatfuel/wizard@latest update --dry-run --jsontois not a wizard version. The CLI resolves upstream's branch and moves the app to whatever it holds now, so an update can move real files whilefromVersionandtoVersionare the same — that pair describes the CLI, which ships separately from the content it fetches.fromandtoare what actually changed, and a range that is empty intois a no-op.notesis the changelog for the CLI versions betweenfromVersionandtoVersion, so it isnullon an update that moved content under the same version — which is the common case. When it is there it is the one thing that says why upstream changed, and step 3 is what closes the range: ask afterwards and it comes back empty. Read before you write.The JSON is what you work from — save it:
{ "from": "<commit the app is on>", "to": "<commit it would move to>", "fromVersion": "0.2.0", "toVersion": "0.3.0", "notes": "## 0.3.0 — …\n\n### Fixed\n- …", // the changelog for that range "update": [{ "at": "…", "from": "…" }], "conflicts": [ { "at": "src/vendor/ui/Button.tsx", // the file in the app — theirs "from": "src/vendor/ui/Button.tsx", "why": "edited here", "theirs": "/…/cache/<commit>/src/vendor/ui/Button.tsx", // upstream's copy "rewritten": ["viteConfigBlock"] // only for `wizard rewrote it` } ], "skipped": [{ "at": "…", "why": "unchanged" }], "codegen": { // null when no input moved — skip step 6 "inputs": ["src/vendor/api/operations/livechat.graphql"], // what moved "skills": ["chatfuel-livechat"], // what documents why it moved "command": "npm run codegen", // null in an embed: it ships no generator "steps": ["…"] // the four of step 6, word for word } }Nothing has been written yet.
updateis the list the CLI is about to overwrite in step 3, andtheirsis already fetched and verified. -
Take the safe half.
npx @chatfuel/wizard@latest updateThis overwrites the files nobody touched, moves the pin in the lock, and leaves every conflict alone. It prints the same three lists.
-
Write
operationDocs.tsif the app has none.Skip this whole step if the file already exists. Check first:
ls src/operationDocs.ts 2>/dev/null || ls operationDocs.ts 2>/dev/nullAn app scaffolded before the document registry existed has no barrel, and
updatecannot make one: it decides files by digest and never adds a file the app does not have. But step 3 just overwrote the three hosts that import it, so without this the build fails on a missing module.Write it beside the generated API —
src/operationDocs.tsin a scaffolded app (the generated modules are undersrc/vendor/api/generated/), oroperationDocs.tsin the embed directory (vendor/api/generated/). One namespace import per directory there, sorted, and anoperationsarray of them:// @chatfuel:operation-docs import * as contacts from './vendor/api/generated/contacts/graphql.js'; import * as core from './vendor/api/generated/core/graphql.js'; import * as livechat from './vendor/api/generated/livechat/graphql.js'; export const operations = [contacts, core, livechat];Namespace imports, never
export *: two namespaces export the same fragment name, and a star re-export of both drops it silently. A directory with a dash in its name becomes a camelCase binding (flow-builder→flowBuilder). Include every directory that is there — a module missing from this list is a module whose requests the proxy will refuse.This file is the app's operation surface, and it is the only file this skill may create. Say in step 9 that you wrote it.
-
Resolve each conflict, one at a time.
For each entry read three things before you edit anything:
at— the file as it stands in the app. This is the user's version.theirs— upstream's version at the new commit. Already fetched and verified; read it from that path —--dry-runfetches these into the wizard's own cache, which is the one thing it writes.notes— from the step 2 JSON, the changelog for exactly the range being crossed. This says why upstream changed, which is the difference between a merge and a guess. A security fix and a rename are not resolved the same way.
Then act on
why:whywhat it means what to do edited hereThe user changed this file; upstream changed it too. Merge upstream's change into their file. Keep their intent; take upstream's fix. wizard rewrote itThe wizard transformed the file on the way in ( rewrittennames the transforms) and upstream has since moved.Start from theirsand re-apply each named transform. Never copytheirsover the file as it stands — that is what drops the transform and breaks the app.deleted hereUpstream changed a file the user has deleted. Ask. Do not resurrect a file somebody removed on purpose. Keep the user's formatting, their variable names and their comments. You are applying somebody else's fix inside somebody's file, not replacing the file.
-
Regenerate the client.
Skip this step only when the step 2 JSON says
"codegen": null. Otherwise the CLI has moved the schema, or an operation document, or both, and the typed client beside them is now older than its own inputs. It names them underregenerate the clientand prints this, which is the sequence:- Read the diff you have now — it is the new schema and operation documents.
- Run
npm run codegen— the first run prints the one command that installs the generator, and stops. - Read the second diff — it is the regenerated client under
src/vendor/api/generated/. - Commit both together. A client that does not match the documents beside it is worse than an old one.
The generator is 265 packages the app does not otherwise need, so it is not one of its dependencies. That makes the second line two commands the first time: the install line the refusal prints — copy it exactly, the versions are the ones the vendored client was generated with — and then
npm run codegenagain.A codegen diff is not a conflict. Every file under
src/vendor/api/generated/isgeneratedin the lock, soupdatenever wrote one and never will. The whole directory changing is what a correct regeneration looks like. Do not pass any of it to--resolved, and do not edit any of it by hand.An embed host gets
"command": null. It holds the documents but ships no generator — a file importingnode:fsinto somebody else'ssrc/is a file their own type check has to accept — so regeneration is theirs to arrange. Say so in step 9 and leave it to them. -
Say what you settled.
npx @chatfuel/wizard@latest update --resolved src/vendor/ui/Button.tsx …This tells the lock the file is dealt with. It is not optional and it does not fix itself later: the lock still describes the file as it was before the merge, so every future update reports the same conflict again and fetches upstream's copy again, for work that was already done. The merge stays invisible to the tool until this command runs. Pass only the files you actually resolved — a file you left for the user stays a conflict, which is correct.
-
Check the app still runs.
npm run buildIf it breaks, look at the client first: a build failing on a field or a type name that does not exist is a step 6 that did not run, or that ran before the merges of step 5 were finished. After that, the break is in the files you touched in steps 4 and 5. Fix it there.
-
Report. Tell the user, in this order: what the update overwrote, which conflicts you resolved and how, and which you left and why. If step 6 ran, say that the client was regenerated and that the diff under
src/vendor/api/generated/belongs with the documents above it. Ifnotesmentioned a breaking change, say so plainly — that is the one thing a digest cannot tell them.Then name anything the CLI listed under
gone upstream. Those are files the app has that upstream no longer does — usually a rename, which arrives here as a disappearance and never as the new name. The app keeps its copy for good, and no future update will touch it. You may not fix these; say which ones they are and let the user decide.
What not to do
- Do not run
updatewith a dirty tree by working around the refusal. - Do not resolve a conflict by copying
theirsoveratwholesale. If that were right, the CLI would have done it in step 3 without asking. - Do not edit anything under
src/vendor/api/generated/by hand. The nextnpm run codegenoverwrites it and the edit is gone without a trace. - Do not treat a codegen diff as a conflict, and never pass a generated file to
--resolved. It was in none of the CLI's lists to begin with. - Do not edit
.chatfuel/lock.jsonby hand. If it looks wrong, say so. - Do not touch
.env. It is not in the lock and never will be. - Do not create any file other than the
operationDocs.tsof step 4. Every other file in the app is the CLI's to write, or the generator's. - Do not commit. Show the user the diff and let them commit.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |