Update NanoClaw

Pull upstream changes and merge them with the user's installation, preserving skills and customizations. Scripts live in .claude/skills/update/scripts/.

Principle: Handle everything automatically. Only pause for user confirmation before applying changes, or when merge conflicts need human judgment.

UX Note: Use AskUserQuestion for all user-facing questions.

1. Pre-flight

Check that the skills system is initialized:

test -d .nanoclaw && echo "INITIALIZED" || echo "NOT_INITIALIZED"

If NOT_INITIALIZED: Run initSkillsSystem() first:

npx tsx -e "import { initNanoclawDir } from './skills-engine/init.js'; initNanoclawDir();"

Check for uncommitted git changes:

git status --porcelain

If there are uncommitted changes: Warn the user: "You have uncommitted changes. It's recommended to commit or stash them before updating. Continue anyway?" Use AskUserQuestion with options: "Continue anyway", "Abort (I'll commit first)". If they abort, stop here.

2. Fetch upstream

Run the fetch script:

./.claude/skills/update/scripts/fetch-upstream.sh

Parse the structured status block between <<< STATUS and STATUS >>> markers. Extract:

• TEMP_DIR — path to extracted upstream files
• REMOTE — which git remote was used
• CURRENT_VERSION — version from local package.json
• NEW_VERSION — version from upstream package.json
• STATUS — "success" or "error"

If STATUS=error: Show the error output and stop.

If CURRENT_VERSION equals NEW_VERSION: Tell the user they're already up to date. Ask if they want to force the update anyway (there may be non-version-bumped changes). If no, clean up the temp dir and stop.

3. Preview

Run the preview to show what will change:

npx tsx scripts/update-core.ts --json --preview-only <TEMP_DIR>

This outputs JSON with: currentVersion, newVersion, filesChanged, filesDeleted, conflictRisk, customPatchesAtRisk.

Present to the user:

• "Updating from {currentVersion} to {newVersion}"
• "{N} files will be changed" — list them if <= 20, otherwise summarize
• If conflictRisk is non-empty: "These files have skill modifications and may conflict: {list}"
• If customPatchesAtRisk is non-empty: "These custom patches may need re-application: {list}"
• If filesDeleted is non-empty: "{N} files will be removed"

4. Confirm

Use AskUserQuestion: "Apply this update?" with options:

• "Yes, apply update"
• "No, cancel"

If cancelled, clean up the temp dir (rm -rf <TEMP_DIR>) and stop.

5. Apply

Run the update:

npx tsx scripts/update-core.ts --json <TEMP_DIR>

Parse the JSON output. The result has: success, previousVersion, newVersion, mergeConflicts, backupPending, customPatchFailures, skillReapplyResults, error.

If success=true with no issues: Continue to step 7.

If customPatchFailures exist: Warn the user which custom patches failed to re-apply. These may need manual attention after the update.

If skillReapplyResults has false entries: Warn the user which skill tests failed after re-application.

6. Handle conflicts

If backupPending=true: There are unresolved merge conflicts.

For each file in mergeConflicts:

1. Read the file — it contains conflict markers (<<<<<<<, =======, >>>>>>>)
2. Check if there's an intent file for this path in any applied skill (e.g., .claude/skills/<skill>/modify/<path>.intent.md)
3. Use the intent file and your understanding of the codebase to resolve the conflict
4. Write the resolved file

After resolving all conflicts:

npx tsx scripts/post-update.ts

This clears the backup, confirming the resolution.

If you cannot confidently resolve a conflict: Show the user the conflicting sections and ask them to choose or provide guidance.

7. Run migrations

Run migrations between the old and new versions:

npx tsx scripts/run-migrations.ts <CURRENT_VERSION> <NEW_VERSION> <TEMP_DIR>

Parse the JSON output. It contains: migrationsRun (count), results (array of {version, success, error?}).

If any migration fails: Show the error to the user. The update itself is already applied — the migration failure needs manual attention.

If no migrations found: This is normal (most updates won't have migrations). Continue silently.

8. Verify

Run build and tests:

npm run build && npm test

If build fails: Show the error. Common causes:

• Type errors from merged files — read the error, fix the file, retry
• Missing dependencies — run npm install first, retry

If tests fail: Show which tests failed. Try to diagnose and fix. If you can't fix automatically, report to the user.

If both pass: Report success.

9. Cleanup

Remove the temp directory:

rm -rf <TEMP_DIR>

Report final status:

• "Updated from {previousVersion} to {newVersion}"
• Number of files changed
• Any warnings (failed custom patches, failed skill tests, migration issues)
• Build and test status

Troubleshooting

No upstream remote: The fetch script auto-adds upstream pointing to https://github.com/qwibitai/nanoclaw.git. If the user forked from a different URL, they should set the remote manually: git remote add upstream <url>.

Merge conflicts in many files: Consider whether the user has heavily customized core files. Suggest using the skills system for modifications instead of direct edits, as skills survive updates better.

Build fails after update: Check if package.json dependencies changed. Run npm install to pick up new dependencies.

Rollback: If something goes wrong after applying but before cleanup, the backup is still in .nanoclaw/backup/. Run:

npx tsx -e "import { restoreBackup, clearBackup } from './skills-engine/backup.js'; restoreBackup(); clearBackup();"