1216b5b99c
Interactive skill that guides Claude through fetching upstream NanoClaw, previewing changes, merging with customizations, running migrations, and verifying the result. Includes: - SKILL.md with 9-step update flow - fetch-upstream.sh: detects remote, fetches, extracts tracked paths - run-migrations.ts: discovers and runs version-ordered migrations - post-update.ts: clears backup after conflict resolution - update-core.ts: adds --json and --preview-only flags - BASE_INCLUDES moved to constants.ts as single source of truth - 16 new tests covering fetch, migrations, and CLI flags Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
172 lines
6.0 KiB
Markdown
172 lines
6.0 KiB
Markdown
---
|
|
name: update
|
|
description: "Update NanoClaw from upstream. Fetches latest changes, merges with your customizations and skills, runs migrations. Triggers on \"update\", \"pull upstream\", \"sync with upstream\", \"get latest changes\"."
|
|
---
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
test -d .nanoclaw && echo "INITIALIZED" || echo "NOT_INITIALIZED"
|
|
```
|
|
|
|
**If NOT_INITIALIZED:** Run `initSkillsSystem()` first:
|
|
|
|
```bash
|
|
npx tsx -e "import { initNanoclawDir } from './skills-engine/init.js'; initNanoclawDir();"
|
|
```
|
|
|
|
Check for uncommitted git changes:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./.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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
npx tsx -e "import { restoreBackup, clearBackup } from './skills-engine/backup.js'; restoreBackup(); clearBackup();"
|
|
```
|