Create smartem-workspace CLI tool for automated workspace setup

[vredchenko]

#17

Summary

Create a uvx-runnable Python CLI tool (smartem-workspace) to automate the setup of SmartEM multi-repo development workspaces. This formalizes the current ad-hoc ERIC workspace structure into a reproducible, documented process.

Related: #15 (uv adoption - this tool will use uv patterns)

Background

The SmartEM ecosystem spans 30+ repositories across 3 organisations:

• DiamondLightSource (GitHub) - 5 repos, full ownership
• FragmentScreen (GitHub) - 6 repos, read-only reference
• aria-php (GitLab) - 19 repos, read-only reference

Currently, workspace setup is manual and undocumented. This tool will enable any developer to quickly set up a complete development environment.

---

User Experience

Installation

# No installation needed - run directly with uvx
uvx smartem-workspace init

Basic Usage

# Interactive setup in current directory
uvx smartem-workspace init

# Specify workspace path
uvx smartem-workspace init --path ~/dev/my-workspace

# Use preset without prompts
uvx smartem-workspace init --preset smartem-core --no-interactive

# Update existing workspace
uvx smartem-workspace sync

# Check workspace status
uvx smartem-workspace status

---

CLI Commands

Command	Description
init [--path PATH]	Interactive workspace setup
sync	Update repos (git pull)
status	Show workspace state
add <repo>	Add a single repo

Options for init

Option	Description
--path PATH	Target directory (default: cwd)
--preset NAME	Use preset: smartem-core, full, aria-reference, minimal
--no-interactive	Skip prompts, use preset only
--ssh	Use SSH URLs (default: HTTPS)
--skip-claude	Skip Claude Code setup
--skip-serena	Skip Serena MCP setup

---

Workspace Structure Created

workspace/
├── repos/
│   ├── DiamondLightSource/
│   │   ├── smartem-decisions/
│   │   ├── smartem-frontend/
│   │   ├── smartem-devtools/      # Cloned FIRST (contains config)
│   │   ├── fandanGO-cryoem-dls/
│   │   └── cryoem-services/
│   ├── FragmentScreen/
│   │   ├── fandanGO-core/
│   │   ├── fandanGO-aria/
│   │   └── ...
│   └── GitlabAriaPHP/
│       ├── data-deposition-api/
│       └── ...
├── claude-config/                 # Symlink -> repos/.../smartem-devtools/claude-code
├── .claude/
│   ├── settings.local.json        # Generated permissions
│   └── skills/                    # Symlinks to claude-config/shared/skills/*
├── .serena/
│   └── project.yml                # Generated Serena config
├── .mcp.json                      # Generated MCP server config
├── aria-mock/                     # ARIA GraphQL mock (optional)
├── testdata/                      # Placeholder for test datasets
├── tmp/                           # Scratch directory
└── CLAUDE.md                      # Workspace documentation

---

Presets

Preset	Repos	Use Case
smartem-core	smartem-decisions, smartem-frontend, smartem-devtools	Most developers
full	All 30 repos	Complete ecosystem reference
aria-reference	fandanGO-cryoem-dls + FragmentScreen/* + data-deposition-api	ARIA integration work
minimal	smartem-devtools only	Workspace setup testing

---

Package Structure

smartem-devtools/
└── packages/                        # Publishable packages
    └── smartem-workspace/
        ├── pyproject.toml
        ├── README.md
        └── src/smartem_workspace/
            ├── __init__.py
            ├── __main__.py          # Entry point
            ├── cli.py               # Typer commands
            ├── config/
            │   ├── schema.py        # Pydantic models
            │   ├── loader.py        # Network + fallback loading
            │   └── repos.json       # Bundled fallback config
            ├── setup/
            │   ├── bootstrap.py     # Orchestration
            │   ├── repos.py         # Git operations
            │   ├── claude.py        # .claude/ setup
            │   ├── serena.py        # .serena/ + .mcp.json
            │   └── workspace.py     # CLAUDE.md, tmp/, etc.
            ├── interactive/
            │   ├── prompts.py       # Rich UI
            │   └── presets.py       # Preset definitions
            └── utils/
                ├── git.py
                └── paths.py

---

Configuration Source

Source of truth: core/repos.json (new JSON file)

Loading strategy: Network-first with bundled fallback

1. Fetch from GitHub raw URL: https://raw.githubusercontent.com/.../core/repos.json
2. If network fails, use bundled repos.json from package

Config migration:

• Convert core/repos-and-refs.ts data to JSON with extended schema
• TypeScript imports from JSON (maintains type safety)
• Python CLI fetches or uses bundled copy

---

Dependencies

dependencies = [
    "typer>=0.12.0",
    "rich>=13.0.0",
    "httpx>=0.27.0",
    "pydantic>=2.0.0",
]

---

Bootstrap Flow

1. Validate workspace path
2. Fetch config (network-first, bundled fallback)
3. Interactive repo selection (grouped by org)
4. Clone smartem-devtools FIRST (contains claude-code/)
5. Clone remaining selected repos
6. Create workspace structure:
   - claude-config/ symlink -> smartem-devtools/claude-code
   - .claude/skills/ symlinks -> claude-config/shared/skills/*
   - .claude/settings.local.json (generated)
   - .serena/project.yml (generated)
   - .mcp.json (generated)
   - CLAUDE.md (from smartem-devtools)
   - tmp/, testdata/ directories
7. Display summary and next steps

---

Implementation Tasks

• Create core/repos.json - Extended schema with presets, ownership, tags
• Update core/repos-and-refs.ts - Import from JSON
• Create packages/smartem-workspace/ directory structure
• Implement config loading (schema.py, loader.py)
• Implement interactive prompts (Rich-based UI)
• Implement setup modules (repos, claude, serena, workspace)
• Implement CLI commands (init, sync, status, add)
• Add tests (config parsing, preset resolution, mock git)
• Publish to PyPI
• Update smartem-devtools README with uvx usage

---

Future Enhancements

• Add workspace health check command
• Integration with webui dashboard
• Support for custom repo lists (user config file)
• Workspace upgrade command (migrate existing setup)

---

References

• uv documentation
• Typer CLI framework
• Rich terminal UI
• Current repo definitions: core/repos-and-refs.ts