✨ Core Library Update CLI

[MFA-X-AI]

Description

This PR enhances the xircuits update command with support for updating core libraries (bundled in the wheel) and introduces an --all flag for batch updates. It also adds a --no-overwrite flag to preserve files with local modifications.

Key features:

• Core library updates: Updates base.py and core component libraries (xai_events, xai_template, xai_controlflow, xai_utils) from the installed wheel
• Batch updates: New --all flag to update all installed libraries at once
• Selective updates: --core-only and --remote-only flags for targeted updates
• Preserve local changes: --no-overwrite flag skips updating files with local modifications
• Flexible ref handling: --respect-refs honors pinned versions, otherwise pulls latest (for --all)
• Exclusion support: --exclude flag to skip specific libraries during batch updates
• Smaller .xircuits diff: Shows summary line instead of full JSON diff for .xircuits files
• Reporting: Detailed success/failure summary for batch updates

References

This extends the xircuits update command (previous PR) to support core libraries bundled in the wheel, completing the update mechanism for all component types. It also addresses the need for batch update operations and better handling of local modifications.

Pull Request Type

• Xircuits Core (Jupyterlab Related changes)
• Xircuits Canvas (Custom RD Related changes)
• Xircuits Component Library
• Xircuits Project Template
• Testing Automation
• Documentation
• Others (Xircuits CLI)

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Tests

Setup:

1. Get the xircuits wheel and install it
2. Create a test directory and run xircuits init
3. Install component libraries: xircuits install flask, xircuits install gradio
4. Initialize git: git init && git add . && git commit -m "Initial setup"

1. Core Library Update Test

1. Make local modifications to `xai_components/xai_events/EventListener.py`
2. Run `xircuits update xai_events`
3. Verify modified files are backed up with timestamp
4. Confirm library is updated from installed wheel
5. Test with `base.py`: modify `xai_components/base.py` and run `xircuits update base.py`
6. Verify base.py is updated from wheel

2. Update All Test

1. Ensure multiple libraries are installed (e.g., flask, gradio, core libs)
2. Make local changes to files in different libraries
3. Run `xircuits update --all --dry-run`
4. Verify preview shows all libraries that would be updated
5. Run `xircuits update --all`
6. Confirm all libraries are updated with proper success/failure reporting
7. Check summary shows counts and status for each library

3. Selective Update Test

1. Run `xircuits update --all --core-only`
2. Verify only core libraries (xai_events, xai_template, xai_controlflow, xai_utils, base.py) are updated
3. Confirm remote libraries (flask, gradio) are skipped
4. Run `xircuits update --all --remote-only`
5. Verify only remote libraries are updated, core libs are skipped

4. Exclusion Test

1. Run `xircuits update --all --exclude=flask,gradio --dry-run`
2. Verify excluded libraries are not shown in update list
3. Run `xircuits update --all --exclude=flask,gradio`
4. Confirm excluded libraries remain unchanged

5. No Overwrite Test

1. Make local modifications to files in a library
2. Run `xircuits update <library> --no-overwrite`
3. Verify modified files show "⊙ path (local changes preserved)" marker
4. Confirm local changes are preserved (no .bak files created)
5. Verify other files without local changes are updated normally
6. Test with --all: `xircuits update --all --no-overwrite`

6. Respect Refs Test

1. Pin a library to specific version in pyproject.toml metadata
2. Run `xircuits update --all` (without --respect-refs)
3. Verify library updates to latest regardless of pinned version
4. Run `xircuits update --all --respect-refs`
5. Confirm library stays at pinned version

7. .xircuits Diff Test

1. Modify a .xircuits workflow file in a library
2. Run `xircuits update <library> --dry-run`
3. Verify diff shows summary line instead of full JSON content
4. Example: ".xircuits file updated: path/workflow.xircuits (120 -> 125 lines, +5)"
5. Confirm regular Python files still show full unified diff

8. Error Handling Test

1. Install library and delete its .git directory (simulate corrupted state)
2. Run `xircuits update --all`
3. Verify failed library is reported with error message
4. Confirm other libraries continue updating (no early abort)
5. Check summary shows both succeeded and failed counts

Tested on? Specify Version.

• Windows
• Linux
• Mac
• Others (State here -> xxx )

Notes

• Core libraries are always sourced from the installed wheel, never from git
• The --all flag updates all libraries to latest by default; use --respect-refs to honor pinned versions
• The --no-overwrite flag marks preserved files with ⊙ symbol in output
• Binary files and .xircuits files receive special handling in diff generation to avoid verbose output
• When both --core-only and --remote-only are specified, the command raises an error
• The exclude parameter accepts comma-separated library names (case-insensitive, with or without xai_ prefix)

[github-actions]

👈 Launch a binder notebook on branch XpressAI/xircuits/fahreza/backup-core