Skip to content

chatfuel-lab/wizard / content/skills/chatfuel-update

chatfuel-update

Verified

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:

upstreamon diskwhat happens
unchangedanythingskipped
changedstill the bytes the wizard wroteoverwritten, no question asked
changededited sinceleft exactly as it is, reported as a conflict
— generated hereanythingnever 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.

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.

    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.

    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:

    {
      "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.

    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:

    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:

    // @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:

    whywhat it meanswhat 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 (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 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.

  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.

    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.

    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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall