scitex-dev 0.4.0__tar.gz → 0.4.2__tar.gz

{scitex_dev-0.4.0 → scitex_dev-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.4.0
+Version: 0.4.2
 Summary: Shared developer utilities for the SciTeX ecosystem
 Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
 License-Expression: AGPL-3.0-only
@@ -16,6 +16,7 @@ Requires-Dist: click>=8.0.0; extra == "cli"
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
 Provides-Extra: dev
+Requires-Dist: click>=8.0.0; extra == "dev"
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Provides-Extra: docs

{scitex_dev-0.4.0 → scitex_dev-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scitex-dev"
-version = "0.4.0"
+version = "0.4.2"
 description = "Shared developer utilities for the SciTeX ecosystem"
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -18,7 +18,7 @@ dependencies = []
 [project.optional-dependencies]
 cli = ["click>=8.0.0"]
 mcp = ["fastmcp>=2.0.0"]
-dev = ["pytest>=7.0.0", "pytest-cov>=4.0.0"]
+dev = ["click>=8.0.0", "pytest>=7.0.0", "pytest-cov>=4.0.0"]
 docs = [
     "sphinx>=7.0",
     "sphinx-rtd-theme>=2.0",

{scitex_dev-0.4.0 → scitex_dev-0.4.2}/src/scitex_dev/__init__.py

@@ -26,7 +26,7 @@ Public API (20 functions)::
     result_to_mcp, wrap_as_mcp
 """
 
-__version__ = "0.3.2"
+__version__ = "0.4.2"
 
 # --- Public API: LLM-friendly types and utilities ---
 from .cli_utils import (
@@ -53,7 +53,16 @@ from .search import search
 
 # --- Public API: Versions ---
 from .versions import check_versions, get_mismatches, list_versions
-from .fix import fix_mismatches
+from .fix import (
+    bump_version as bump_version,
+    detect_mismatches as detect_mismatches,
+    determine_bump_type as determine_bump_type,
+    fix_init_version as fix_init_version,
+    fix_local as fix_local,
+    fix_mismatches as fix_mismatches,
+    fix_remote as fix_remote,
+    verify_versions as verify_versions,
+)
 
 # --- Accessible but not in __all__ (advanced/internal use) ---
 
@@ -121,6 +130,29 @@ from .sync_remote import (
     remote_diff as remote_diff,
 )
 
+# CI
+from .ci import (
+    CIStatus as CIStatus,
+    WorkflowRun as WorkflowRun,
+    check_ci as check_ci,
+    check_pypi_publish as check_pypi_publish,
+    create_github_release as create_github_release,
+    get_failing_packages as get_failing_packages,
+    verify_all_pypi_configs as verify_all_pypi_configs,
+    verify_pypi_config as verify_pypi_config,
+    wait_all_pypi as wait_all_pypi,
+    wait_for_workflow as wait_for_workflow,
+)
+
+# Deploy
+from .deploy import (
+    deploy_scitex_cloud as deploy_scitex_cloud,
+    verify_production as verify_production,
+)
+
+# Skills verification
+from .skills import verify_docs_and_skills as verify_docs_and_skills
+
 # Test runner
 from .test_runner import (
     TestConfig as TestConfig,

{scitex_dev-0.4.0 → scitex_dev-0.4.2}/src/scitex_dev/_skills/scitex-dev/SKILL.md

@@ -22,6 +22,7 @@ This file is an **index only**. Detailed usage is in the sub-skill files.
 | docs-search.md | get_docs, build_docs, search_docs, search |
 | test-runner.md | run_local, run_hpc_sbatch, poll_hpc_job, fetch_hpc_result |
 | config.md | DevConfig, HostConfig, load_config, create_default_config |
+| full-update.md | Full ecosystem release pipeline — audit, bump, release, sync |
 
 ## Quick Reference
 

scitex_dev-0.4.2/src/scitex_dev/_skills/scitex-dev/full-update.md

@@ -0,0 +1,304 @@
+---
+topic: full-update
+package: scitex-dev
+description: >
+  Full ecosystem release workflow — pre-flight checks, version bump, PyPI publish,
+  local sync, NAS deploy (including scitex-cloud special handling), and verification.
+  Use via /update-scitex-full command.
+---
+
+# Full Ecosystem Update
+
+End-to-end release pipeline for all SciTeX packages. Follow phases strictly in order;
+steps within a phase may run in parallel via subagents.
+
+## Packages
+
+Retrieved programmatically from the ecosystem config — never hard-code the list.
+
+```python
+from scitex_dev.config import load_config
+config = load_config()
+packages = list(config.ecosystem.keys())  # canonical list
+```
+
+Or via MCP: `mcp__scitex__dev_ecosystem_list` returns all registered packages.
+
+Skip alpha/beta packages (e.g., scitex-cloud) unless explicitly requested.
+
+## Full Update Levels (1–5)
+
+Each level includes ALL steps from the previous level.
+
+| Level | Scope | Steps |
+|-------|-------|-------|
+| 1 | **Local** | diff check -> bump `pyproject.toml` + `__init__.py` -> commit -> `git tag vX.Y.Z` -> `git push origin develop --tags` |
+| 2 | **GitHub Release** | Level 1 + `gh release create vX.Y.Z --generate-notes` |
+| 3 | **PyPI** | Level 2 + verify `publish-pypi.yml` triggered (or manual `twine upload` for first publish) + confirm version on PyPI |
+| 4 | **Hosts** | Level 3 + `pip install -e .` locally + `mcp__scitex__dev_ecosystem_sync` (NAS, Spartan) + verify remote versions |
+| 5 | **Skills** | Level 4 + `scitex-dev skills export` (stamps MANIFEST.md version from pyproject.toml) |
+
+Pick the highest applicable level. Most packages need Level 4.
+Packages with `_skills/` directories need Level 5.
+
+---
+
+## Phase 1: Pre-flight
+
+**Goal:** Ensure every repo is in a releasable state before touching versions.
+
+### 1. check_ci — Verify GitHub Actions pass
+
+- **Python**: `from scitex_dev.ci import check_ci, get_failing_packages`
+  - `check_ci(packages=None)` → `{pkg: CIStatus}`
+  - `get_failing_packages(packages=None)` → `list[str]`
+- **CLI**: `gh run list -R ywatanabe1989/PACKAGE --limit 3`
+- **MCP**: `mcp__scitex__dev_ecosystem_list` (includes CI-adjacent version checks)
+
+If any package is failing, fix CI before proceeding. Do not skip.
+
+### 2. detect_mismatches — Find version inconsistencies
+
+- **Python**: `from scitex_dev.fix import detect_mismatches`
+  - `detect_mismatches(packages=None)` → `{pkg: {status, issues, local, git, remote}}`
+- **CLI**: `scitex-dev ecosystem fix-mismatches --dry-run`
+- **MCP**: `mcp__scitex__dev_ecosystem_fix_mismatches(confirm=False)`
+
+### 3. fix_init_version — Sync `__init__.py` with `pyproject.toml`
+
+- **Python**: `from scitex_dev.fix import fix_init_version`
+  - `fix_init_version(package_path, confirm=False)` → `{toml_version, init_version, action, status}`
+- **CLI**: manual `sed` or editor
+- **MCP**: via `fix_init_version` Python API (planned as MCP tool)
+
+These block PyPI publish. Fix and commit before bumping.
+
+### 4. verify_pypi_config — Check trusted publisher setup
+
+- **Python**: `from scitex_dev.ci import verify_pypi_config, verify_all_pypi_configs`
+  - `verify_pypi_config(repo)` → `{repo, workflow_exists, needs_first_publish}`
+  - `verify_all_pypi_configs(packages=None)` → `{pkg: {...}}`
+- **CLI**: `gh api repos/ywatanabe1989/PACKAGE/actions/workflows`
+- **MCP**: via `mcp__scitex__dev_ecosystem_list` (planned)
+
+First-publish packages need manual `twine upload` before OIDC works.
+
+---
+
+## Phase 2: Version Bump + Release
+
+**Goal:** Bump, tag, release, and publish to PyPI. Independent packages run in parallel.
+
+### 5. determine_bump_type — Check diff and classify as minor/patch
+
+- **Python**: `from scitex_dev.fix import determine_bump_type`
+  - `determine_bump_type(package_path)` → `{has_diff, commits_since_tag, has_feat, bump_type, current_version, suggested_version}`
+- **CLI**:
+  ```bash
+  git -C ~/proj/PACKAGE diff $(git -C ~/proj/PACKAGE describe --tags --abbrev=0)..HEAD --stat
+  git -C ~/proj/PACKAGE log $(git -C ~/proj/PACKAGE describe --tags --abbrev=0)..HEAD --oneline
+  ```
+- **MCP**: `mcp__scitex__dev_ecosystem_list` (includes `commits_since_tag` field)
+
+**Rule: If HEAD differs from the last tag, version MUST be incremented.**
+
+- Any `feat:` commit → **minor** bump
+- Otherwise (fix, chore, docs, refactor) → **patch** bump
+- Identical to last tag (no diff) → **skip** (only case where skipping is allowed)
+
+### 6. bump_version — Edit `pyproject.toml` and `__init__.py`
+
+- **Python**: `from scitex_dev.fix import bump_version`
+  - `bump_version(package_path, new_version, confirm=False)` → `{old_version, new_version, toml_updated, init_updated, status}`
+- **CLI**: `sed -i 's/^version = "OLD"/version = "NEW"/' pyproject.toml`
+- **MCP**: via `mcp__scitex__dev_ecosystem_fix_mismatches` (planned)
+
+### 7. verify_docs_and_skills — Ensure docs/skills match codebase
+
+- **Python**: `from scitex_dev.skills import verify_docs_and_skills`
+  - `verify_docs_and_skills(package_path=None)` → `{skills_stale, stale_files, readme_version_match, issues, status}`
+- **CLI**: `scitex-dev skills export --dry-run` (preview skill changes)
+- **MCP**: via `mcp__scitex__dev_ecosystem_list` (planned)
+
+Check before pushing:
+- Skill files reference functions that actually exist
+- API examples in skills are runnable
+- CLI commands in skills match `--help` output
+
+If stale, update and commit before tagging.
+
+### 8. commit_and_tag — Commit version bump and tag
+
+- **Python**: `subprocess` (no convenience wrapper — git is the tool)
+- **CLI**:
+  ```bash
+  git -C ~/proj/PACKAGE add pyproject.toml src/
+  git -C ~/proj/PACKAGE commit -m "chore: bump version to X.Y.Z"
+  git -C ~/proj/PACKAGE tag -a vX.Y.Z -m "Release vX.Y.Z"
+  ```
+- **MCP**: not applicable
+
+### 9. check_ci_before_push — Last CI gate before push
+
+- **Python**: `from scitex_dev.ci import check_ci`
+  - `check_ci(packages=["PACKAGE"])` → `{pkg: CIStatus}`
+- **CLI**: `gh run list -R ywatanabe1989/PACKAGE --limit 1`
+- **MCP**: `mcp__scitex__dev_ecosystem_list` (check status field)
+
+If failures found, fix now. This is the last opportunity before release.
+
+### 10. push — Push commit and tags
+
+- **Python**: `subprocess`
+- **CLI**: `git -C ~/proj/PACKAGE push origin develop --tags`
+- **MCP**: not applicable
+
+### 11. create_github_release — Create release on GitHub
+
+- **Python**: `from scitex_dev.ci import create_github_release`
+  - `create_github_release(repo, tag, generate_notes=True, confirm=False)` → `{repo, tag, url, status}`
+- **CLI**: `gh release create vX.Y.Z --repo ywatanabe1989/PACKAGE --generate-notes`
+- **MCP**: via `mcp__scitex__dev_ecosystem_list` (planned)
+
+### 12. wait_for_pypi — Watch PyPI publish (background)
+
+- **Python**: `from scitex_dev.ci import wait_for_workflow, check_pypi_publish`
+  - `wait_for_workflow(repo, workflow="publish-pypi.yml", timeout=600, poll_interval=30)` → `WorkflowRun | None`
+  - `check_pypi_publish(repo)` → `WorkflowRun | None`
+- **CLI**:
+  ```bash
+  run_id=$(gh run list -R ywatanabe1989/PACKAGE -w publish-pypi.yml --limit 1 --json databaseId -q '.[0].databaseId')
+  gh run watch "$run_id" -R ywatanabe1989/PACKAGE  # run_in_background=true
+  pip index versions PACKAGE 2>/dev/null | head -1  # verify after completion
+  ```
+- **MCP**: via `wait_for_workflow` Python API (planned as MCP tool)
+
+Launch as background task. Do not block.
+Failure: no workflow → `twine upload dist/*` | failed → `gh run view --log-failed` | timeout → check GitHub Actions page.
+
+---
+
+## Phase 3: Local Sync
+
+**Goal:** Update the local dev environment to match published versions.
+
+### 13. fix_local — Reinstall bumped packages locally
+
+- **Python**: `from scitex_dev.fix import fix_local`
+  - `fix_local(packages=["figrecipe", "scitex-dev"], confirm=True)` → `{pkg: {status, output}}`
+- **CLI**: `pip install -e ~/proj/PACKAGE`
+- **MCP**: `mcp__scitex__dev_ecosystem_sync_local(packages=["..."], confirm=True)`
+
+### 14. verify_versions — Confirm local versions aligned
+
+- **Python**: `from scitex_dev.fix import verify_versions`
+  - `verify_versions(packages=None)` → `{pkg: "ok" | "mismatch: ..."}`
+- **CLI**: `scitex-dev ecosystem fix-mismatches --dry-run` (should show no mismatches)
+- **MCP**: `mcp__scitex__dev_ecosystem_list` (all statuses should be "ok")
+
+All packages must show "ok" before proceeding.
+
+---
+
+## Phase 4: Host Sync (NAS)
+
+**Goal:** Deploy updated packages to remote hosts.
+
+### 15. fix_remote — [Custom] Sync packages to NAS
+
+- **Python**: `from scitex_dev.fix import fix_remote`
+  - `fix_remote(hosts=["nas"], packages=None, install=True, confirm=True)` → `{host: {pkg: {status}}}`
+  - Timeout fallback: `fix_remote(hosts=["nas"], install=False, confirm=True)`
+- **CLI**: `scitex-dev ecosystem sync --host nas --confirm`
+- **MCP**: `mcp__scitex__dev_ecosystem_sync(hosts=["nas"], confirm=True)`
+
+### 16. deploy_scitex_cloud — [Custom] scitex-cloud NAS deploy
+
+- **Python**: `from scitex_dev.deploy import deploy_scitex_cloud`
+  - `deploy_scitex_cloud(host="nas", branch="develop", confirm=False)` → `{host, commands, outputs, status}`
+- **CLI**:
+  ```bash
+  ssh nas "cd ~/proj/scitex-cloud && git pull origin develop"
+  ssh nas "cd ~/proj/scitex-cloud && docker compose stop"
+  ssh nas "cd ~/proj/scitex-cloud && npm install && npx vite build"
+  ssh nas "cd ~/proj/scitex-cloud && docker compose up -d"
+  ```
+- **MCP**: via `deploy_scitex_cloud` Python API (planned as MCP tool)
+
+**Important:** Stop Docker before Vite build to avoid OOM on NAS.
+
+### 17. verify_production — [Custom] Check scitex.ai is live
+
+- **Python**: `from scitex_dev.deploy import verify_production`
+  - `verify_production(url="https://scitex.ai", timeout=10)` → `{url, status_code, status}`
+- **CLI**: `curl -s -o /dev/null -w "%{http_code}" https://scitex.ai`
+- **MCP**: `mcp__scitex__capture_screenshot(url="https://scitex.ai")`
+
+---
+
+## Phase 5: Verification
+
+**Goal:** Confirm everything is consistent and working.
+
+### 18. verify_versions — Final ecosystem status check
+
+- **Python**: `from scitex_dev.fix import verify_versions`
+  - `verify_versions()` → all must be `"ok"`
+- **CLI**: `scitex-dev ecosystem fix-mismatches --dry-run`
+- **MCP**: `mcp__scitex__dev_ecosystem_list`
+
+### 19. verify_production — [Custom] Visual verification
+
+- **CLI**: `playwright-cli screenshot https://scitex.ai --viewport 1920x1080`
+- **MCP**: `mcp__scitex__capture_screenshot(url="https://scitex.ai")`
+
+Desktop + mobile viewport. Screenshot as proof.
+
+### 20. report_summary — Generate summary table
+
+```
+Package             Old     New     PyPI    NAS     Status
+scitex-python       2.27.0  2.28.0  ok      ok      PASS
+figrecipe           0.28.0  0.28.1  ok      ok      PASS
+...
+```
+
+---
+
+## Parallel Execution Strategy
+
+Launch one subagent per package (or batch of 2-3 small packages).
+Use `GitHandlerAgent-SONNET` subagent type.
+All agents must use `git -C /full/path` for git commands (hook requirement).
+
+## Choice Presentation
+
+When invoked via `/update-scitex-full`, present:
+
+```
+Current ecosystem state:
+  Package           toml        tag         PyPI        diff   bump
+  scitex-python     2.27.0      v2.27.0     2.27.0      0      skip
+  figrecipe         0.28.0      v0.28.0     0.28.0      3      patch
+  ...
+
+Recommendation: Level 4 for all, Level 5 for scitex-dev
+
+  1. Audit only (dry run)
+  2. Local + GitHub Release
+  3. + PyPI
+  4. + Host sync          <-- recommended
+  5. + Skills export
+```
+
+## Common Failure Modes
+
+| Failure | Cause | Fix |
+|---------|-------|-----|
+| PyPI 403 | Trusted publisher not configured | Configure OIDC on pypi.org or `twine upload` for first publish |
+| Duplicate wheel | Version already on PyPI | Bump to next patch, re-release |
+| NAS OOM on Vite | Docker consuming memory | `docker compose stop` before build |
+| `__init__.py` mismatch | Version not synced | `fix_init_version(path, confirm=True)` |
+| Tag wrong commit | Tagged before fixing | `git tag -d vX.Y.Z && git tag -a vX.Y.Z HEAD && git push origin vX.Y.Z --force` |
+| NAS conflicts | Uncommitted changes | `mcp__scitex__dev_ecosystem_diff` then commit or stash |
+| NAS timeout | pip install >120s | `fix_remote(install=False)` then SSH pip manually |

{scitex_dev-0.4.0 → scitex_dev-0.4.2}/src/scitex_dev/_skills/scitex-dev/versions.md

@@ -134,12 +134,34 @@ print(result["summary"])
 # Show all packages with version info
 scitex-dev ecosystem list --versions
 
-# Preview fixes
-scitex-dev ecosystem fix-mismatches --dry-run
-
-# Execute fixes
+# Preview fixes (dry run, no changes made)
 scitex-dev ecosystem fix-mismatches
 
+# Execute fixes (actually applies changes)
+scitex-dev ecosystem fix-mismatches --confirm
+
 # JSON output
 scitex-dev ecosystem list --versions --json
 ```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__scitex__dev_ecosystem_list` | Read-only: list all ecosystem packages with version status |
+| `mcp__scitex__dev_ecosystem_fix_mismatches` | Auto-fix installed vs pyproject.toml mismatches (confirm=False for preview) |
+
+## Full Ecosystem Update Workflow
+
+When performing a full update across all packages, follow this order:
+
+1. **Check CI** — verify GitHub Actions pass for each package (`gh run list -R ywatanabe1989/PACKAGE`)
+2. **Check status** — `mcp__scitex__dev_ecosystem_list` or `scitex-dev ecosystem list --versions`
+3. **Bump versions** — edit pyproject.toml, classify changes (feat → minor, fix → patch)
+4. **Commit + tag** — `git commit` + `git tag vX.Y.Z`
+5. **Push** — `git push origin develop --tags`
+6. **GitHub Release** — `gh release create vX.Y.Z --generate-notes`
+7. **Wait for PyPI** — verify `publish-pypi.yml` workflow completes
+8. **Local reinstall** — `pip install -e .` in each updated repo
+9. **Fix mismatches** — `scitex-dev ecosystem fix-mismatches --confirm` or `mcp__scitex__dev_ecosystem_fix_mismatches`
+10. **Sync to NAS** — `scitex dev versions sync --confirm`