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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.2 KB |
SKILL.md
View on GitHub---
name: chatfuel-update
description: Update 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 and `update` cannot add.
- everything under `src/vendor/api/generated/` (step 6), which you never edit
but do regenerate. `npm run codegen` rewrites 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.
```bash
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.
1. **Get to a clean tree.**
```bash
git status --porcelain
```
Anything there: ask the user to commit or stash it. Do not commit their work
for them without asking.
2. **Read the plan, with both sides of each conflict.**
```bash
npx @chatfuel/wizard@latest update --dry-run --json
```
`to` is 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 while
`fromVersion` and `toVersion` are the same — that pair describes the CLI,
which ships separately from the content it fetches. `from` and `to` are what
actually changed, and a range that is empty in `to` is a no-op.
`notes` is the changelog for the CLI versions between `fromVersion` and
`toVersion`, so it is `null` on 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:
```jsonc
{
"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. `update` is the list the CLI is about to
overwrite in step 3, and `theirs` is already fetched and verified.
3. **Take the safe half.**
```bash
npx @chatfuel/wizard@latest update
```
This overwrites the files nobody touched, moves the pin in the lock, and
leaves every conflict alone. It prints the same three lists.
4. **Write `operationDocs.ts` if the app has none.**
Skip this whole step if the file already exists. Check first:
```bash
ls src/operationDocs.ts 2>/dev/null || ls operationDocs.ts 2>/dev/null
```
An app scaffolded before the document registry existed has no barrel, and
`update` cannot 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.ts` in a scaffolded
app (the generated modules are under `src/vendor/api/generated/`), or
`operationDocs.ts` in the embed directory (`vendor/api/generated/`). One
namespace import per directory there, sorted, and an `operations` array of
them:
```ts
// @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.
5. **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-run` fetches 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`:
| `why` | what it means | what to do |
| --- | --- | --- |
| `edited here` | The user changed this file; upstream changed it too. | Merge upstream's change into their file. Keep their intent; take upstream's fix. |
| `wizard rewrote it` | The wizard transformed the file on the way in (`rewritten` names the transforms) and upstream has since moved. | Start from `theirs` and re-apply each named transform. Never copy `theirs` over the file as it stands — that is what drops the transform and breaks the app. |
| `deleted here` | Upstream 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.
6. **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
under `regenerate the client` and prints this, which is the sequence:
1. Read the diff you have now — it is the new schema and operation documents.
2. Run `npm run codegen` — the first run prints the one command that installs the generator, and stops.
3. Read the second diff — it is the regenerated client under `src/vendor/api/generated/`.
4. 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 codegen` again.
**A codegen diff is not a conflict.** Every file under
`src/vendor/api/generated/` is `generated` in the lock, so `update` never
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 importing `node:fs` into somebody else's `src/` 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.
7. **Say what you settled.**
```bash
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.
8. **Check the app still runs.**
```bash
npm run build
```
If 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.
9. **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. If `notes`
mentioned 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 `update` with a dirty tree by working around the refusal.
- Do not resolve a conflict by copying `theirs` over `at` wholesale. 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 next
`npm run codegen` overwrites 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.json` by 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.ts` of 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 |