dev-ws 0.1.2

A CLI tool for managing multiple workspaces with git worktrees and live preview.

Workspace CLI

Workspace CLI is a command-line tool for managing multiple Workspaces, Git Repositories (Repo), and Live Preview. It is designed to provide an efficient, isolated, and easily synchronized development environment for AI-assisted development.

📖 Introduction

The core goal of this project is to solve the problem of environment isolation and synchronization during parallel multi-task development. By assigning different development tasks to independent Workspaces, each Workspace has its own independent Git Worktree, ensuring no interference. At the same time, it provides a unified Preview Workspace for real-time preview and review, ensuring that changes during development can be accurately and quickly synchronized.

Core Features

• Workspace Logical Grouping: Workspaces exist only as folders and are not directly managed by Git, facilitating flexible organization.
• Independent Repo Management: Utilizing git worktree technology, Repos within each Workspace have independent branches (Feature/Stand/Preview), supporting parallel development.
• Preview Workspace: A single preview environment that supports accurate synchronization of code from any Workspace (syncing only Tracked files), ensuring a clean preview environment.
• Live Preview: Automatically monitors file changes and synchronizes them to the Preview Workspace in real-time.
• Rules Repo Synchronization: Supports automatic cross-workspace synchronization (Commit/Push/Merge) of special rules repositories.

🛠️ Installation

Ensure that Python 3.8+ and Git are installed in your environment.

pip install dev-ws

🚀 Quick Start

1. Create Workspace

Use the create command to create a new development Workspace based on a base Workspace.

Auto Configuration: If a workspace.json configuration file does not exist in the current directory, the create command will automatically create one based on the provided --base and --repo parameters.

# Syntax
workspace create --name <new_name> [--base <base_path> --repo <repo_list>]

# Example 1: Config exists, create directly
workspace create --name feature-a

# Example 2: First use, auto-generate config and create
workspace create --name feature-a --base ./work_root/main --repo frontend --repo backend

2. Complete Scenario Example

Assuming your directory structure is as follows:

/Users/luoking/Desktop/Project/Work
└── workspace
    ├── luoking-creatify-coding  (Rules Repo)
    ├── main-web-ui
    └── webserver

Scenario 1: Create Multiple Workspaces

Command:

cd /Users/luoking/Desktop/Project/Work

# Create the first workspace (lulu) and initialize config
workspace create lulu \
  --base ./workspace \
  --repo main-web-ui \
  --repo webserver \
  --repo luoking-creatify-coding

# Create subsequent workspaces
workspace create kiki
workspace create momo

Result:

• Three workspaces created: workspace-lulu, workspace-kiki, workspace-momo.
• Repos inside Workspaces use git worktree, default branch is workspace-{name}/stand.
• Repos under the base workspace ./workspace automatically switch to workspace-{name}/preview branch, ready to serve as the Preview environment.
• workspace.json configuration file is automatically generated.

Scenario 2: Configure Rules Repo

Action:

Open the generated workspace.json and modify the rules_repo field to your rules repository name:

"rules_repo": "luoking-creatify-coding"

Scenario 3: Execute Live Preview in Workspace Root

Command:

workspace-cli preview

Result:

• Auto-detection: Automatically identifies the current workspace (e.g., workspace-momo).
• Precise Sync:
  • Automatically adds tracked files.
  • Calculates diff with main branch.
  • Cleans preview workspace.
  • Switches/Resets preview branch preview (single branch to prevent redundancy).
  • Applies diff, syncing files.
• Live Preview: Starts live preview, monitoring file changes.
  • Outputs change info: [CREATED], [UPDATED], [DELETED] (with color highlighting).
• Concurrency Control: Prevents running multiple preview instances simultaneously.

Scenario 4: Execute Preview in Workspace Subdirectory

Command (e.g., in workspace-momo/frontend/src):

workspace-cli preview

Result:

• Automatically looks up the workspace root directory → workspace-momo.
• Executes preview sync logic.

Scenario 5: One-time Sync (Non-Live Mode)

Command:

workspace-cli preview --once

Result:

• Exits immediately after one sync, does not start file monitoring.
• Suitable for CI/CD or quick checks.

Scenario 6: Debugging and Logging

Command:

workspace-cli preview --debug --log-file workspace.log

Result:

• Enables debug mode, printing detailed information.
• Outputs logs to workspace.log.

Scenario 7: Switch Live Preview to Another Workspace

Command:

# Assuming currently previewing lulu
cd ./workspace-kiki
workspace preview

Result:

• The previous Live Preview process (if running) will stop (requires manual control or script, CLI currently supports overwrite).
• Cleans Preview Workspace.
• Deletes the old workspace-lulu/preview branch.
• Creates a new workspace-kiki/preview branch.
• Syncs workspace-kiki content and starts monitoring.

Scenario 8: Rules Repo Sync

Command:

workspace syncrule

Result:

• Rules Repo switches to main branch.
• commit + push current workspace rules changes.
• Automatically executes pull origin main (or merge) for Rules Repos in other workspaces.
• Returns to the current workspace's Feature branch.

Scenario 9: View Workspace Status

Command:

workspace status

Result:

• Displays Base Workspace path.
• Lists all created Workspaces and their paths.

Scenario 10: Delete Workspace

Command:

workspace delete --name kiki

Result:

• Deletes workspace-kiki folder.
• Automatically cleans up related git worktrees.
• Does not affect Base Workspace or other Workspaces.

📚 Detailed Documentation

Core Concepts

• Workspace: Workspace folder, typically named {base}-{name}.
• Preview Workspace: Base Workspace (usually {base}), used for running and previewing code.
• Repo: Git repository, sharing object storage via git worktree across Workspaces while keeping working directories independent.
• Stand Branch: Standby branch, used to maintain a clean state in new Workspaces.
• Preview Branch: Temporary branch, exists only in Preview Workspace, used to apply changes from other Workspaces.

System Design and Branch Strategy

This project uses a unique branch model to isolate development environments from preview environments.

1. Branch Model

Branch Type	Naming Rule	Role	Lifecycle
Feature Branch	workspace/{feature_name}	Actual Development Branch. Manually created by user in Workspace for daily development.	Long-term, merged/deleted after feature completion.
Stand Branch	workspace-{name}/stand	Standby/Placeholder Branch. Automatically created by create command. Used when Workspace is just created or not on a Feature branch to prevent conflicts.	Long-term during Workspace existence.
Preview Branch	workspace-{name}/preview	Preview Dedicated Branch. Automatically created by preview command. Exists only in Base Workspace (Preview Workspace).	Temporary. Deleted and recreated every time preview runs or Workspace switches.

2. Workflow Design

• Create Phase:

  • When executing create, CLI creates a stand branch for each Repo in the target Workspace.
  • Design Intent: New Workspace should be in a clean "standby" state, waiting for user to Checkout specific Feature branch for development. It should not be directly in Preview state.

• Preview Phase:

  • When executing preview, CLI syncs code from current Workspace (under development) to Base Workspace (preview environment).
  • At this time, Repo in Base Workspace is switched to preview branch.
  • Design Intent: Base Workspace acts as a "Player", responsible for running and displaying code; while development Workspace acts as an "Editor", responsible for modifying code.

Configuration File

workspace.json is the core configuration file of the project, usually located in the Work Root directory.

{
  "base_path": "/absolute/path/to/base/workspace",
  "repos": [
    {
      "name": "repo-name",
      "path": "relative/path/to/repo",
      "url": "[e-mail]:user/repo.git"
    }
  ],
  "rules_repo": "rules-repo-name"
}

Field	Type	Description
base_path	String	Absolute path of Base Workspace. New Workspaces will be created based on this, and Preview also runs in this directory.
repos	List	List of managed repositories. Defines which repositories need to be managed by Workspace.
repos[].name	String	Repository name, used in CLI commands (e.g., create --repo name).
repos[].path	String	Path of repository relative to Workspace root.
repos[].url	String	(Optional) Remote Git URL of repository. Note: Currently unused, reserved for future auto-clone support.
rules_repo	String	(Optional) Specifies which repository is the rules repository, used for syncrule command.

Command Reference

Command	Description	Example
create	Create new Workspace	workspace create --name dev --repo web
delete	Delete Workspace	workspace delete --name dev
status	View current status	workspace status
preview	Start preview sync	workspace preview
syncrule	Sync rules repository	workspace syncrule