codex-workspaces 0.1.0__py3-none-any.whl

codex_workspaces/__init__.py

@@ -0,0 +1,3 @@
+"""Codex workspace switching utilities."""
+
+__version__ = "0.1.0"

codex_workspaces/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex_workspaces/cli.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import sys
+from typing import Optional, Sequence
+
+from .config import Config
+from .core import WorkspaceManager, workspace_dir, usage
+from .errors import CodexWorkspacesError
+from .platforms import SystemPlatform
+
+
+def _print_error(message: str, lang: str) -> None:
+    prefix = "错误" if lang == "zh" else "Error"
+    print(f"{prefix}: {message}", file=sys.stderr)
+
+
+def run(argv: Sequence[str], manager: WorkspaceManager) -> int:
+    command = argv[0] if argv else "help"
+    args = list(argv[1:])
+
+    if command in {"help", "-h", "--help"}:
+        manager.info(usage(manager.config.lang))
+        return 0
+    if command in {"list", "ls"}:
+        manager.list_workspaces()
+        return 0
+    if command in {"current", "whoami"}:
+        manager.show_current()
+        return 0
+    if command in {"use", "switch", "sw"}:
+        if not args:
+            manager.fail(
+                "缺少工作区名，例如: codex-workspaces use work",
+                "Missing workspace name, for example: codex-workspaces use work",
+            )
+        manager.switch_workspace(args[0], args[1:], argv)
+        return 0
+    if command in {"stop", "quit", "close"}:
+        force = False
+        for arg in args:
+            if arg in {"--force", "-f"}:
+                force = True
+            else:
+                manager.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
+        manager.stop_codex(force, argv)
+        return 0
+    if command in {"start", "open"}:
+        if args:
+            manager.fail("start 不需要参数", "start does not take arguments")
+        manager.start_codex()
+        return 0
+    if command in {"restart", "reopen"}:
+        force = False
+        for arg in args:
+            if arg in {"--force", "-f"}:
+                force = True
+            else:
+                manager.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
+        manager.restart_codex(force, argv)
+        return 0
+    if command in {"create", "new"}:
+        if not args:
+            manager.create_workspace("", [])
+        else:
+            manager.create_workspace(args[0], args[1:])
+        return 0
+    if command == "install":
+        if len(args) > 1:
+            manager.fail(f"未知参数: {args[1]}", f"Unknown option: {args[1]}")
+        manager.install_self(args[0] if args else None)
+        return 0
+
+    try:
+        if workspace_dir(manager.config, command).is_dir():
+            manager.switch_workspace(command, args, argv)
+            return 0
+    except CodexWorkspacesError:
+        pass
+
+    manager.fail(f"未知命令或工作区不存在: {command}", f"Unknown command or workspace does not exist: {command}")
+    return 1
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    platform_service = SystemPlatform()
+    config = Config.from_env(apple_language=platform_service.apple_language())
+    manager = WorkspaceManager(config, platform_service)
+    try:
+        return run(list(sys.argv[1:] if argv is None else argv), manager)
+    except CodexWorkspacesError as exc:
+        _print_error(exc.message, config.lang)
+        if exc.message.startswith("Unknown command") or exc.message.startswith("未知命令"):
+            print(file=sys.stderr)
+            print(usage(config.lang), file=sys.stderr)
+        return exc.exit_code

codex_workspaces/config.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Optional
+
+
+def _looks_zh(value: str) -> bool:
+    return value.lower().replace("_", "-").startswith("zh")
+
+
+def _looks_en(value: str) -> bool:
+    return value.lower().replace("_", "-").startswith("en")
+
+
+def detect_ui_lang(
+    env: Mapping[str, str],
+    apple_language: Optional[str] = None,
+) -> str:
+    forced = env.get("CODEX_WORKSPACES_LANG") or ""
+    if _looks_zh(forced):
+        return "zh"
+    if _looks_en(forced):
+        return "en"
+
+    if apple_language:
+        if _looks_zh(apple_language):
+            return "zh"
+        return "en"
+
+    env_lang = env.get("LC_ALL") or env.get("LC_MESSAGES") or env.get("LANG") or ""
+    return "zh" if _looks_zh(env_lang) else "en"
+
+
+def _expand_path(value: str) -> str:
+    return os.path.expandvars(os.path.expanduser(value))
+
+
+@dataclass(frozen=True)
+class Config:
+    app_name: str
+    home_dir: Path
+    active_link: Path
+    workspace_prefix: str
+    quit_timeout: int
+    lang: str
+
+    @classmethod
+    def from_env(
+        cls,
+        env: Optional[Mapping[str, str]] = None,
+        home: Optional[Path] = None,
+        apple_language: Optional[str] = None,
+    ) -> "Config":
+        env = dict(os.environ if env is None else env)
+        home_dir = Path(home or env.get("HOME") or Path.home()).expanduser()
+        active_link = Path(
+            _expand_path(
+                env.get("CODEX_WORKSPACES_LINK") or str(home_dir / ".codex")
+            )
+        )
+        workspace_prefix = _expand_path(
+            env.get("CODEX_WORKSPACES_PREFIX") or str(home_dir / ".codex-")
+        )
+        quit_timeout = int(env.get("CODEX_QUIT_TIMEOUT") or "20")
+
+        return cls(
+            app_name=env.get("CODEX_APP_NAME") or "Codex",
+            home_dir=home_dir,
+            active_link=active_link,
+            workspace_prefix=workspace_prefix,
+            quit_timeout=quit_timeout,
+            lang=detect_ui_lang(env, apple_language),
+        )

codex_workspaces/core.py

@@ -0,0 +1,531 @@
+from __future__ import annotations
+
+import glob
+import os
+import re
+import shlex
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, TextIO
+
+from .config import Config
+from .errors import CodexWorkspacesError
+from .platforms import SystemPlatform
+
+WORKSPACE_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def strip_workspace_name(value: str) -> str:
+    name = re.split(r"[\\/]+", value.rstrip("\\/"))[-1]
+    if name.startswith(".codex-"):
+        name = name[len(".codex-") :]
+    return name
+
+
+def validate_workspace_name(name: str) -> None:
+    if not name:
+        raise CodexWorkspacesError("Workspace name cannot be empty")
+    if name in {".", ".."}:
+        raise CodexWorkspacesError(f"Workspace name cannot be {name}")
+    if not WORKSPACE_RE.match(name):
+        raise CodexWorkspacesError(
+            "Workspace name can only contain letters, numbers, dots, underscores, and hyphens: "
+            + name
+        )
+
+
+def workspace_dir(config: Config, name: str) -> Path:
+    clean_name = strip_workspace_name(name)
+    validate_workspace_name(clean_name)
+    return Path(config.workspace_prefix + clean_name)
+
+
+@dataclass(frozen=True)
+class CurrentTarget:
+    kind: str
+    path: Optional[Path] = None
+
+
+class WorkspaceManager:
+    def __init__(
+        self,
+        config: Config,
+        platform_service: Optional[SystemPlatform] = None,
+        stdout: Optional[TextIO] = None,
+        stderr: Optional[TextIO] = None,
+    ) -> None:
+        self.config = config
+        self.platform = platform_service or SystemPlatform()
+        self.stdout = stdout or sys.stdout
+        self.stderr = stderr or sys.stderr
+
+    def is_zh(self) -> bool:
+        return self.config.lang == "zh"
+
+    def message(self, zh: str, en: str) -> str:
+        return zh if self.is_zh() else en
+
+    def fail(self, zh: str, en: str) -> None:
+        raise CodexWorkspacesError(self.message(zh, en))
+
+    def info(self, text: str = "") -> None:
+        print(text, file=self.stdout)
+
+    def bold(self, text: str) -> str:
+        isatty = getattr(self.stdout, "isatty", lambda: False)
+        return f"\033[1m{text}\033[0m" if isatty() else text
+
+    def workspace_dir(self, name: str) -> Path:
+        return workspace_dir(self.config, name)
+
+    def real_dir(self, path: Path) -> Path:
+        if self.platform.is_directory_link(path):
+            return path.resolve(strict=False)
+        if path.is_dir():
+            return path.resolve(strict=True)
+        return path
+
+    def current_target(self) -> CurrentTarget:
+        active = self.config.active_link
+        if self.platform.is_directory_link(active):
+            return CurrentTarget("target", self.real_dir(active))
+        if active.exists():
+            return CurrentTarget("not-a-link", active)
+        return CurrentTarget("missing")
+
+    def workspace_dirs(self) -> List[Path]:
+        dirs = [Path(path) for path in glob.glob(self.config.workspace_prefix + "*")]
+        return sorted(path for path in dirs if path.is_dir())
+
+    def same_path(self, left: Path, right: Path) -> bool:
+        left_s = os.path.normcase(os.path.abspath(left))
+        right_s = os.path.normcase(os.path.abspath(right))
+        return left_s == right_s
+
+    def current_name(self, target: Path) -> Optional[str]:
+        for directory in self.workspace_dirs():
+            if self.same_path(self.real_dir(directory), target):
+                return strip_workspace_name(str(directory))
+        return None
+
+    def list_workspaces(self) -> None:
+        current = self.current_target()
+        self.info(self.bold(self.message("Codex 工作区", "Codex workspaces")))
+        found = False
+        for directory in self.workspace_dirs():
+            found = True
+            name = strip_workspace_name(str(directory))
+            marker = " "
+            if current.kind == "target" and current.path:
+                marker = "*" if self.same_path(self.real_dir(directory), current.path) else " "
+            self.info(f" {marker} {name:<16} {directory}")
+
+        if not found:
+            self.info(
+                self.message(
+                    "未找到工作区目录。可以先执行: codex-workspaces create work",
+                    "No workspace directories found. You can create one with: codex-workspaces create work",
+                )
+            )
+
+        self.info()
+        if current.kind == "missing":
+            self.info(
+                self.message(
+                    f"当前 {self.config.active_link} 不存在。",
+                    f"Current {self.config.active_link} does not exist.",
+                )
+            )
+        elif current.kind == "not-a-link":
+            self.info(
+                self.message(
+                    f"当前 {self.config.active_link} 存在，但不是软链接，切换前需要手动处理。",
+                    f"Current {self.config.active_link} exists, but it is not a symlink. Please handle it manually before switching.",
+                )
+            )
+        elif current.path:
+            name = self.current_name(current.path)
+            if name:
+                self.info(
+                    self.message(
+                        f"当前工作区: {name} -> {current.path}",
+                        f"Current workspace: {name} -> {current.path}",
+                    )
+                )
+            else:
+                self.info(
+                    self.message(
+                        f"当前工作区: 未匹配到工作区目录 -> {current.path}",
+                        f"Current workspace: no matching workspace directory -> {current.path}",
+                    )
+                )
+
+    def show_current(self) -> None:
+        current = self.current_target()
+        if current.kind == "missing":
+            self.fail(
+                f"{self.config.active_link} 不存在",
+                f"{self.config.active_link} does not exist",
+            )
+        if current.kind == "not-a-link":
+            self.fail(
+                f"{self.config.active_link} 存在，但不是软链接",
+                f"{self.config.active_link} exists, but it is not a symlink",
+            )
+        assert current.path is not None
+        name = self.current_name(current.path) or "unknown"
+        self.info(f"{name} -> {current.path}")
+
+    def stop_codex(self, force: bool = False, argv: Optional[Sequence[str]] = None) -> None:
+        if self.platform.is_codex_terminal():
+            if self.platform.supports_external_terminal_delegation:
+                self.platform.delegate_to_external_terminal(
+                    self.config,
+                    self.message("关闭 Codex", "stop Codex"),
+                    list(argv or (["stop", "--force"] if force else ["stop"])),
+                    self.stdout,
+                )
+                return
+            self.require_external_terminal("stop")
+
+        if not self.platform.supports_app_control:
+            self.fail(
+                "当前平台不支持自动关闭 Codex App。切换工作区时可使用 --no-stop。",
+                "App stop is only supported on macOS. Use --no-stop when switching workspaces on this platform.",
+            )
+        self.platform.stop_app(
+            self.config.app_name,
+            self.config.quit_timeout,
+            force,
+            self.stdout,
+        )
+
+    def start_codex(self) -> None:
+        self.require_external_terminal("start")
+        if not self.platform.supports_app_control:
+            self.fail(
+                "当前平台不支持自动启动 Codex App。",
+                "App start is only supported on macOS.",
+            )
+        self.info(self.message(f"正在启动 {self.config.app_name} ...", f"Starting {self.config.app_name} ..."))
+        self.platform.start_app(self.config.app_name)
+
+    def restart_codex(self, force: bool = False, argv: Optional[Sequence[str]] = None) -> None:
+        if self.platform.is_codex_terminal():
+            if self.platform.supports_external_terminal_delegation:
+                self.platform.delegate_to_external_terminal(
+                    self.config,
+                    self.message("重启 Codex", "restart Codex"),
+                    list(argv or (["restart", "--force"] if force else ["restart"])),
+                    self.stdout,
+                )
+                return
+            self.require_external_terminal("restart")
+        self.stop_codex(force)
+        self.start_codex()
+
+    def require_external_terminal(self, action: str) -> None:
+        if not self.platform.is_codex_terminal():
+            return
+        zh_actions = {
+            "stop": "关闭 Codex",
+            "start": "启动 Codex",
+            "restart": "重启 Codex",
+            "switch": "切换工作区",
+            "migration": "迁移工作区目录",
+        }
+        self.fail(
+            f"不能在 Codex 内置 Terminal 中执行{zh_actions.get(action, action)}。请打开外部系统 Terminal，在 Codex 外部运行该命令。",
+            f"Cannot run {action} from the built-in Codex terminal. Open an external system Terminal and run this command outside Codex.",
+        )
+
+    def ensure_app_not_running_for_migration(self) -> None:
+        status = self.platform.app_running_status(self.config.app_name)
+        if status is True:
+            self.fail(
+                f"{self.config.app_name} 正在运行。为避免配置损坏，请先从外部 Terminal 关闭 {self.config.app_name} 后再执行迁移。",
+                f"{self.config.app_name} is running. To avoid corrupting config files, quit {self.config.app_name} from an external terminal before migration.",
+            )
+        if status is None and self.platform.supports_app_control:
+            self.fail(
+                f"无法确认 {self.config.app_name} 是否运行。为避免配置损坏，请先从外部 Terminal 确认 {self.config.app_name} 已关闭后再执行迁移。",
+                f"Cannot confirm whether {self.config.app_name} is running. To avoid corrupting config files, confirm {self.config.app_name} is closed from an external terminal before migration.",
+            )
+
+    def switch_workspace(self, name: str, args: Sequence[str], original_argv: Sequence[str]) -> None:
+        stop_first = True
+        start_after = True
+        force = False
+        for arg in args:
+            if arg == "--no-stop":
+                stop_first = False
+            elif arg == "--no-start":
+                start_after = False
+            elif arg in {"--force", "-f"}:
+                force = True
+            elif arg in {"-h", "--help"}:
+                self.info(usage(self.config.lang))
+                return
+            else:
+                self.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
+
+        if self.platform.is_codex_terminal():
+            if self.platform.supports_external_terminal_delegation:
+                self.platform.delegate_to_external_terminal(
+                    self.config,
+                    self.message("切换工作区", "switch workspaces"),
+                    original_argv,
+                    self.stdout,
+                )
+                return
+            self.require_external_terminal("switch")
+
+        clean_name = strip_workspace_name(name)
+        validate_workspace_name(clean_name)
+        directory = self.workspace_dir(clean_name)
+        if not directory.is_dir():
+            self.fail(
+                f"工作区不存在: {directory}。可先执行: codex-workspaces create {clean_name}",
+                f"Workspace does not exist: {directory}. You can create it with: codex-workspaces create {clean_name}",
+            )
+
+        active = self.config.active_link
+        if active.exists() and not self.platform.is_directory_link(active):
+            self.fail(
+                f"{active} 已存在但不是软链接。为避免误删，请先手动备份/迁移它。",
+                f"{active} already exists but is not a symlink. Please back it up or migrate it manually before switching.",
+            )
+
+        if stop_first:
+            if self.platform.supports_app_control:
+                self.stop_codex(force)
+            else:
+                self.info(
+                    self.message(
+                        "当前平台不支持自动关闭 Codex App，继续只切换工作区链接。",
+                        "App stop is not supported on this platform; continuing with the workspace link switch.",
+                    )
+                )
+
+        active.parent.mkdir(parents=True, exist_ok=True)
+        if self.platform.is_directory_link(active):
+            self.platform.remove_directory_link(active)
+        self.platform.create_directory_link(directory, active)
+        self.info(self.message(f"已切换到: {clean_name} -> {directory}", f"Switched to: {clean_name} -> {directory}"))
+
+        if start_after:
+            if self.platform.supports_app_control:
+                self.start_codex()
+            else:
+                self.info(
+                    self.message(
+                        "当前平台不支持自动启动 Codex App，工作区链接已完成切换。",
+                        "App start is not supported on this platform; the workspace link has been switched.",
+                    )
+                )
+
+    def create_workspace(self, name: str, args: Sequence[str]) -> None:
+        migrate_current = False
+        for arg in args:
+            if arg in {"--migrate-current", "--migrate"}:
+                migrate_current = True
+            elif arg in {"-h", "--help"}:
+                self.info(usage(self.config.lang))
+                return
+            else:
+                self.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
+
+        if not name:
+            self.fail(
+                "缺少工作区名，例如: codex-workspaces create work",
+                "Missing workspace name, for example: codex-workspaces create work",
+            )
+
+        clean_name = strip_workspace_name(name)
+        validate_workspace_name(clean_name)
+        directory = self.workspace_dir(clean_name)
+        if directory.exists():
+            self.fail(f"工作区目录已存在: {directory}", f"Workspace directory already exists: {directory}")
+
+        if migrate_current:
+            self.require_external_terminal("migration")
+            self.ensure_app_not_running_for_migration()
+            active = self.config.active_link
+            if self.platform.is_directory_link(active):
+                self.fail(
+                    f"{active} 已经是软链接，无需迁移。",
+                    f"{active} is already a symlink; there is nothing to migrate.",
+                )
+            if not active.exists():
+                self.fail(f"{active} 不存在，无法迁移。", f"{active} does not exist, so it cannot be migrated.")
+            if not active.is_dir():
+                self.fail(
+                    f"{active} 存在但不是目录，无法迁移。",
+                    f"{active} exists but is not a directory, so it cannot be migrated.",
+                )
+            directory.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(active), str(directory))
+            self.platform.create_directory_link(directory, active)
+            self.info(self.message(f"已迁移当前工作区: {active} -> {directory}", f"Migrated current workspace: {active} -> {directory}"))
+            return
+
+        directory.mkdir(parents=True, exist_ok=False)
+        self.info(self.message(f"已创建工作区目录: {directory}", f"Created workspace directory: {directory}"))
+
+    def install_self(self, destination: Optional[str] = None) -> None:
+        dest = Path(destination) if destination else self.default_install_dir()
+        if dest is None:
+            self.fail(
+                "无法判断安装目录，请指定，例如: codex-workspaces install /usr/local/bin",
+                "Could not choose an install directory. Please specify one, for example: codex-workspaces install /usr/local/bin",
+            )
+        dest.mkdir(parents=True, exist_ok=True)
+        if self.platform.is_windows:
+            launcher = dest / "codex-workspaces.cmd"
+            launcher.write_text(
+                f'@echo off\r\n"{sys.executable}" -m codex_workspaces %*\r\n',
+                encoding="utf-8",
+            )
+        else:
+            launcher = dest / "codex-workspaces"
+            launcher.write_text(
+                "#!/usr/bin/env sh\n"
+                f"exec {shlex.quote(sys.executable)} -m codex_workspaces \"$@\"\n",
+                encoding="utf-8",
+            )
+            launcher.chmod(0o755)
+        self.info(self.message(f"已安装: {launcher}", f"Installed: {launcher}"))
+
+        if not self.path_contains_dir(dest):
+            self.info(
+                self.message(
+                    f"提醒: {dest} 目前不在 PATH 中，需要加入 shell 配置。",
+                    f"Note: {dest} is not currently in PATH. Add it to your shell config before using the command directly.",
+                )
+            )
+
+    def path_contains_dir(self, directory: Path) -> bool:
+        path_parts = os.environ.get("PATH", "").split(os.pathsep)
+        target = os.path.normcase(os.path.abspath(directory))
+        return any(os.path.normcase(os.path.abspath(part or ".")) == target for part in path_parts)
+
+    def default_install_dir(self) -> Optional[Path]:
+        candidates: Iterable[Path]
+        if self.platform.is_windows:
+            candidates = [
+                self.config.home_dir / "AppData" / "Roaming" / "Python" / "Scripts",
+                self.config.home_dir / ".local" / "bin",
+            ]
+        else:
+            candidates = [
+                self.config.home_dir / ".local" / "bin",
+                self.config.home_dir / "bin",
+                Path("/opt/homebrew/bin"),
+                Path("/usr/local/bin"),
+            ]
+        for directory in candidates:
+            if self.path_contains_dir(directory) and directory.is_dir() and os.access(directory, os.W_OK):
+                return directory
+        for directory in candidates:
+            if self.path_contains_dir(directory) or directory == self.config.home_dir / ".local" / "bin":
+                return directory
+        return None
+
+
+def usage(lang: str) -> str:
+    if lang == "zh":
+        return """codex-workspaces - Codex 多工作区切换工具
+
+工作区约定:
+  当前工作区: ~/.codex                 软链接/目录链接
+  工作区目录: ~/.codex-work            工作区名 work
+            ~/.codex-personal        工作区名 personal
+
+用法:
+  codex-workspaces list | ls
+      查看所有工作区目录，并标出当前工作区。
+
+  codex-workspaces current
+      显示当前 ~/.codex 指向哪个工作区。
+
+  codex-workspaces use <工作区名> [--no-stop] [--no-start] [--force]
+  codex-workspaces switch <工作区名> [--no-stop] [--no-start] [--force]
+  codex-workspaces <工作区名>
+      切换 ~/.codex 链接到指定工作区目录。
+      macOS 上默认会关闭 Codex App、切换工作区、再启动 Codex App。
+      Linux/Windows 上会跳过 App 启停，只切换工作区链接。
+
+  codex-workspaces stop [--force]
+      关闭 Codex App。当前仅支持 macOS。
+
+  codex-workspaces start
+      启动 Codex App。当前仅支持 macOS。
+
+  codex-workspaces restart [--force]
+      重启 Codex App。当前仅支持 macOS。
+
+  codex-workspaces create <工作区名> [--migrate-current]
+      创建新的工作区目录 ~/.codex-<工作区名>。
+      加 --migrate-current 可将已有的真实 ~/.codex 目录迁移为该工作区。
+
+  codex-workspaces install [目录]
+      安装 Python 启动器到 PATH 目录。推荐优先使用 pipx 或 pip 安装。
+
+  codex-workspaces help
+      显示帮助。
+
+环境变量:
+  CODEX_APP_NAME        App 名称，默认 Codex
+  CODEX_QUIT_TIMEOUT    等待 App 退出秒数，默认 20
+  CODEX_WORKSPACES_LINK   当前工作区链接，默认 ~/.codex
+  CODEX_WORKSPACES_PREFIX 工作区目录前缀，默认 ~/.codex-
+  CODEX_WORKSPACES_LANG   强制提示语言，可设为 zh 或 en"""
+
+    return """codex-workspaces - Codex multi-workspace switcher
+
+Workspace layout:
+  Active workspace: ~/.codex                 symlink/directory link
+  Workspace dirs:   ~/.codex-work            workspace name: work
+                  ~/.codex-personal        workspace name: personal
+
+Usage:
+  codex-workspaces list | ls
+      List all workspace directories and mark the active workspace.
+
+  codex-workspaces current
+      Show where ~/.codex currently points.
+
+  codex-workspaces use <workspace> [--no-stop] [--no-start] [--force]
+  codex-workspaces switch <workspace> [--no-stop] [--no-start] [--force]
+  codex-workspaces <workspace>
+      Switch the ~/.codex link to the selected workspace directory.
+      On macOS this quits Codex App, switches the workspace, then starts Codex App.
+      On Linux and Windows app control is skipped and only the workspace link changes.
+
+  codex-workspaces stop [--force]
+      Quit Codex App. Currently supported on macOS only.
+
+  codex-workspaces start
+      Start Codex App. Currently supported on macOS only.
+
+  codex-workspaces restart [--force]
+      Restart Codex App. Currently supported on macOS only.
+
+  codex-workspaces create <workspace> [--migrate-current]
+      Create a new workspace directory ~/.codex-<workspace>.
+      Add --migrate-current to migrate an existing real ~/.codex directory.
+
+  codex-workspaces install [directory]
+      Install a Python launcher into a PATH directory. pipx or pip is preferred.
+
+  codex-workspaces help
+      Show this help.
+
+Environment variables:
+  CODEX_APP_NAME        App name, default: Codex
+  CODEX_QUIT_TIMEOUT    Seconds to wait for app exit, default: 20
+  CODEX_WORKSPACES_LINK   Active workspace link, default: ~/.codex
+  CODEX_WORKSPACES_PREFIX Workspace directory prefix, default: ~/.codex-
+  CODEX_WORKSPACES_LANG   Force output language: zh or en"""

codex_workspaces/errors.py

@@ -0,0 +1,7 @@
+class CodexWorkspacesError(Exception):
+    """Base error for expected command failures."""
+
+    def __init__(self, message: str, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code

codex_workspaces/platforms.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import os
+import platform
+import shlex
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Mapping, Optional, Sequence, TextIO
+
+from .config import Config
+from .errors import CodexWorkspacesError
+
+
+CODEX_TERMINAL_ENV = (
+    "CODEX_THREAD_ID",
+    "CODEX_SANDBOX",
+    "CODEX_CI",
+)
+
+CODEX_DELEGATE_UNSET_ENV = (
+    "CODEX_SHELL",
+    "CODEX_THREAD_ID",
+    "CODEX_SANDBOX",
+    "CODEX_SANDBOX_NETWORK_DISABLED",
+    "CODEX_CI",
+    "CODEX_INTERNAL_ORIGINATOR_OVERRIDE",
+    "__CFBundleIdentifier",
+)
+
+
+class SystemPlatform:
+    def __init__(
+        self,
+        env: Optional[Mapping[str, str]] = None,
+        python_executable: Optional[str] = None,
+    ) -> None:
+        self.env = dict(os.environ if env is None else env)
+        self.python_executable = python_executable or sys.executable
+        self.system = platform.system().lower()
+
+    @property
+    def is_macos(self) -> bool:
+        return self.system == "darwin"
+
+    @property
+    def is_windows(self) -> bool:
+        return self.system == "windows"
+
+    @property
+    def supports_app_control(self) -> bool:
+        return self.is_macos
+
+    @property
+    def supports_external_terminal_delegation(self) -> bool:
+        return self.is_macos
+
+    def apple_language(self) -> Optional[str]:
+        if not self.is_macos or shutil.which("defaults") is None:
+            return None
+        result = subprocess.run(
+            ["defaults", "read", "-g", "AppleLanguages"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            return None
+        for line in result.stdout.splitlines():
+            if '"' in line:
+                parts = line.split('"')
+                if len(parts) >= 2 and parts[1]:
+                    return parts[1]
+        return None
+
+    def is_codex_terminal(self) -> bool:
+        if self.env.get("CODEX_SHELL", "").lower() in {"1", "true", "yes"}:
+            return True
+        if any(self.env.get(name) for name in CODEX_TERMINAL_ENV):
+            return True
+        origin = self.env.get("CODEX_INTERNAL_ORIGINATOR_OVERRIDE", "")
+        if "codex" in origin.lower():
+            return True
+        bundle_id = self.env.get("__CFBundleIdentifier", "")
+        return bundle_id.startswith("com.openai.codex")
+
+    def is_directory_link(self, path: Path) -> bool:
+        if path.is_symlink():
+            return True
+        if not self.is_windows or not path.exists() or not path.is_dir():
+            return False
+        try:
+            absolute = os.path.normcase(os.path.abspath(path))
+            resolved = os.path.normcase(os.path.realpath(path))
+        except OSError:
+            return False
+        return absolute != resolved
+
+    def create_directory_link(self, target: Path, link: Path) -> None:
+        try:
+            link.symlink_to(target, target_is_directory=True)
+            return
+        except OSError as exc:
+            if not self.is_windows:
+                raise exc
+
+        result = subprocess.run(
+            ["cmd", "/c", "mklink", "/J", str(link), str(target)],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            detail = (result.stderr or result.stdout).strip()
+            raise CodexWorkspacesError(
+                f"Could not create directory link {link} -> {target}: {detail}"
+            )
+
+    def remove_directory_link(self, link: Path) -> None:
+        if link.is_symlink():
+            link.unlink()
+            return
+        if self.is_windows and self.is_directory_link(link):
+            link.rmdir()
+            return
+        raise CodexWorkspacesError(f"Refusing to remove non-link path: {link}")
+
+    def app_running_status(self, app_name: str) -> Optional[bool]:
+        if shutil.which("pgrep") is None:
+            return None
+        result = subprocess.run(
+            ["pgrep", "-x", app_name],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        if result.returncode == 0:
+            return True
+        if result.returncode == 1:
+            return False
+        return None
+
+    def stop_app(
+        self,
+        app_name: str,
+        timeout: int,
+        force: bool,
+        stdout: TextIO,
+    ) -> None:
+        if not self.supports_app_control:
+            raise CodexWorkspacesError(
+                f"App stop is only supported on macOS. Use --no-stop on this platform."
+            )
+
+        running = self.app_running_status(app_name)
+        if running is False:
+            print(f"{app_name} is not running.", file=stdout)
+            return
+        if running is None:
+            raise CodexWorkspacesError(f"Cannot confirm whether {app_name} is running.")
+
+        print(f"Quitting {app_name} ...", file=stdout)
+        subprocess.run(
+            ["osascript", "-e", f'tell application "{app_name}" to quit'],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+        waited = 0
+        while self.app_running_status(app_name) and waited < timeout:
+            time.sleep(1)
+            waited += 1
+
+        if self.app_running_status(app_name):
+            if not force:
+                raise CodexWorkspacesError(
+                    f"{app_name} did not exit within {timeout}s; add --force to force quit"
+                )
+            print(f"{app_name} did not exit within {timeout}s; forcing it to quit.", file=stdout)
+            subprocess.run(
+                ["killall", app_name],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            time.sleep(1)
+
+        print(f"{app_name} has quit.", file=stdout)
+
+    def start_app(self, app_name: str) -> None:
+        if not self.supports_app_control:
+            raise CodexWorkspacesError("App start is only supported on macOS.")
+        result = subprocess.run(["open", "-a", app_name], check=False)
+        if result.returncode != 0:
+            raise CodexWorkspacesError(f"Could not start {app_name}.")
+
+    def delegate_to_external_terminal(
+        self,
+        config: Config,
+        action: str,
+        argv: Sequence[str],
+        stdout: TextIO,
+    ) -> None:
+        if not self.supports_external_terminal_delegation:
+            raise CodexWorkspacesError(
+                "Cannot delegate to an external terminal on this platform."
+            )
+
+        print(
+            f"Detected the built-in Codex terminal; delegating {action} to Terminal.app...",
+            file=stdout,
+        )
+        command = self._delegated_command(config, argv)
+        fd, raw_name = tempfile.mkstemp(prefix="codex-workspaces.", dir=tempfile.gettempdir())
+        os.close(fd)
+        launcher = Path(raw_name + ".command")
+        Path(raw_name).rename(launcher)
+        launcher.write_text(
+            "\n".join(
+                [
+                    "#!/usr/bin/env bash",
+                    command,
+                    "status=$?",
+                    'printf "\\n[codex-workspaces] Done with exit status %s. You can close this window.\\n" "$status"',
+                    'rm -f "$0"',
+                    'exit "$status"',
+                    "",
+                ]
+            ),
+            encoding="utf-8",
+        )
+        launcher.chmod(launcher.stat().st_mode | stat.S_IXUSR)
+        result = subprocess.run(
+            ["open", "-a", "Terminal", str(launcher)],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        if result.returncode != 0:
+            launcher.unlink(missing_ok=True)
+            raise CodexWorkspacesError(
+                "Could not open Terminal.app. Open the system Terminal manually and run this command again."
+            )
+
+    def _delegated_command(self, config: Config, argv: Sequence[str]) -> str:
+        pieces = [f"unset {' '.join(CODEX_DELEGATE_UNSET_ENV)};"]
+        exports = {
+            "CODEX_APP_NAME": config.app_name,
+            "CODEX_QUIT_TIMEOUT": str(config.quit_timeout),
+            "CODEX_WORKSPACES_LINK": str(config.active_link),
+            "CODEX_WORKSPACES_PREFIX": config.workspace_prefix,
+            "CODEX_WORKSPACES_LANG": config.lang,
+        }
+        for key, value in exports.items():
+            pieces.append(f"export {key}={shlex.quote(value)};")
+        pieces.append(shlex.quote(self.python_executable))
+        pieces.append("-m codex_workspaces")
+        pieces.extend(shlex.quote(arg) for arg in argv)
+        return " ".join(pieces)

codex_workspaces-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: codex-workspaces
+Version: 0.1.0
+Summary: Cross-platform Codex workspace switcher with a preserved macOS shell workflow.
+Author: blockchain-project-lives
+Project-URL: Homepage, https://github.com/blockchain-project-lives/codex-workspaces
+Project-URL: Repository, https://github.com/blockchain-project-lives/codex-workspaces
+Project-URL: Changelog, https://github.com/blockchain-project-lives/codex-workspaces/blob/main/CHANGELOG.md
+Keywords: codex,workspaces,cli,symlink
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# codex-workspaces
+
+English | [简体中文](README.zh-CN.md) | [Changelog](CHANGELOG.md)
+
+`codex-workspaces` switches between multiple Codex workspace directories by keeping each workspace in `~/.codex-<name>` and pointing the active `~/.codex` path at the selected workspace.
+
+The project now has two entry points:
+
+- A cross-platform Python 3 CLI for Linux, macOS, and Windows.
+- The original macOS Bash script, still kept at [`codex-workspaces`](codex-workspaces), for users who installed the shell workflow directly.
+
+On macOS, the Python CLI preserves the original app workflow: stop Codex App, switch the workspace link, and start Codex App again. On Linux and Windows, app control is skipped and the CLI only switches the workspace link.
+
+## Features
+
+- Manage workspace directories such as `~/.codex-work` and `~/.codex-personal`.
+- Switch the active `~/.codex` symlink or directory link.
+- Create workspace directories and migrate an existing real `~/.codex` directory.
+- Keep macOS Codex App stop/start/restart support.
+- Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
+- Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
+- Package as a Python project with tests, CI, and PyPI publishing workflow.
+
+## Requirements
+
+- Python 3.9 or newer for the Python CLI.
+- macOS is required only for Codex App control commands: `start`, `stop`, and `restart`.
+- Linux and macOS use directory symlinks.
+- Windows uses directory symlinks when available and falls back to directory junctions.
+
+## Install
+
+Install the Python CLI from PyPI:
+
+```bash
+python3 -m pip install codex-workspaces
+```
+
+For isolated CLI installs, `pipx` is recommended:
+
+```bash
+pipx install codex-workspaces
+```
+
+Install from a local checkout for development:
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+The legacy macOS shell installer is still available:
+
+```bash
+tmp="$(mktemp -t codex-workspaces.XXXXXX)" && curl -fsSL https://raw.githubusercontent.com/blockchain-project-lives/codex-workspaces/main/codex-workspaces -o "$tmp" && bash "$tmp" install && rm -f "$tmp"
+```
+
+## Workspace Layout
+
+Default layout:
+
+```text
+~/.codex           -> active workspace link
+~/.codex-work      workspace directory named work
+~/.codex-personal  workspace directory named personal
+```
+
+Customize paths with `CODEX_WORKSPACES_LINK` and `CODEX_WORKSPACES_PREFIX`.
+
+## Usage
+
+Create workspaces:
+
+```bash
+codex-workspaces create personal
+codex-workspaces create work
+```
+
+If you already have a real `~/.codex` directory, migrate it first:
+
+```bash
+codex-workspaces create personal --migrate-current
+```
+
+Switch workspaces:
+
+```bash
+codex-workspaces work
+codex-workspaces use personal
+codex-workspaces switch work
+```
+
+On macOS, switching stops and restarts Codex App by default. Skip those steps when needed:
+
+```bash
+codex-workspaces work --no-stop --no-start
+```
+
+Inspect workspaces:
+
+```bash
+codex-workspaces list
+codex-workspaces current
+```
+
+Control Codex App on macOS:
+
+```bash
+codex-workspaces stop
+codex-workspaces start
+codex-workspaces restart
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CODEX_APP_NAME` | `Codex` | macOS app name to control. |
+| `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
+| `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
+| `CODEX_WORKSPACES_PREFIX` | `$HOME/.codex-` | Workspace directory prefix. |
+| `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
+
+Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
+
+## Development
+
+```bash
+python3 -m pip install -e ".[dev]"
+python3 -m pytest
+python3 -m build
+python3 -m twine check dist/*
+```
+
+Design, test, and release notes live in [`docs/`](docs/).
+
+## Publishing
+
+CI runs tests on Linux, macOS, and Windows across Python 3.9, 3.11, and 3.13. The `Publish to PyPI` workflow builds and publishes distributions when a GitHub Release is published or the workflow is run manually.
+
+Configure TestPyPI and PyPI Trusted Publishing for this repository before using the release workflows. See [`docs/RELEASE.zh-CN.md`](docs/RELEASE.zh-CN.md).

codex_workspaces-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+codex_workspaces/__init__.py,sha256=s7IvQpwPf13ld8MXIP1fauIP9o4ls4k5vbQnVlJuvS4,66
+codex_workspaces/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+codex_workspaces/cli.py,sha256=Y1P3R7hRsExz2yLE2a8ckxrrIYWmBgl_AOMsNz8RHMQ,3326
+codex_workspaces/config.py,sha256=JiZVR8Sn_liOwoTXse_oIwq57qmuOZTTMV_5bH8T4qs,2057
+codex_workspaces/core.py,sha256=_ZYFgc991raVxrWV0XGgytz-wzq21shn5FEg44Uh_Ow,22092
+codex_workspaces/errors.py,sha256=ZCwq1IWf3sM8h6Z1Tcy_dEGo958KbQ4AQ83P8lwTKWI,258
+codex_workspaces/platforms.py,sha256=7Ypj0MJONUUk8tm_sUiiHV8im4zlAdFQ3pkR2FHkM1Q,8747
+codex_workspaces-0.1.0.dist-info/METADATA,sha256=trEuBgWeeTpJkrb9U44-u8HgFGOfPICmW9c6lD0qbyM,5449
+codex_workspaces-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codex_workspaces-0.1.0.dist-info/entry_points.txt,sha256=l0zxN8J4Dd067XgEC4GIRgEEMzvYs63MrrYGzwZGXsQ,63
+codex_workspaces-0.1.0.dist-info/top_level.txt,sha256=2ExV9AFvjN9HfHpx29hpgKWlcHiajfe_NDByijO7YTE,17
+codex_workspaces-0.1.0.dist-info/RECORD,,

codex_workspaces-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codex_workspaces-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-workspaces = codex_workspaces.cli:main

codex_workspaces-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codex_workspaces