codex-workspaces 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. codex_workspaces-0.1.0/CHANGELOG.md +39 -0
  2. codex_workspaces-0.1.0/MANIFEST.in +5 -0
  3. codex_workspaces-0.1.0/PKG-INFO +168 -0
  4. codex_workspaces-0.1.0/README.MD +140 -0
  5. codex_workspaces-0.1.0/README.zh-CN.md +140 -0
  6. codex_workspaces-0.1.0/codex-workspaces +829 -0
  7. codex_workspaces-0.1.0/docs/DESIGN.zh-CN.md +98 -0
  8. codex_workspaces-0.1.0/docs/RELEASE.zh-CN.md +109 -0
  9. codex_workspaces-0.1.0/docs/TESTING.zh-CN.md +75 -0
  10. codex_workspaces-0.1.0/pyproject.toml +51 -0
  11. codex_workspaces-0.1.0/setup.cfg +4 -0
  12. codex_workspaces-0.1.0/src/codex_workspaces/__init__.py +3 -0
  13. codex_workspaces-0.1.0/src/codex_workspaces/__main__.py +5 -0
  14. codex_workspaces-0.1.0/src/codex_workspaces/cli.py +95 -0
  15. codex_workspaces-0.1.0/src/codex_workspaces/config.py +75 -0
  16. codex_workspaces-0.1.0/src/codex_workspaces/core.py +531 -0
  17. codex_workspaces-0.1.0/src/codex_workspaces/errors.py +7 -0
  18. codex_workspaces-0.1.0/src/codex_workspaces/platforms.py +264 -0
  19. codex_workspaces-0.1.0/src/codex_workspaces.egg-info/PKG-INFO +168 -0
  20. codex_workspaces-0.1.0/src/codex_workspaces.egg-info/SOURCES.txt +24 -0
  21. codex_workspaces-0.1.0/src/codex_workspaces.egg-info/dependency_links.txt +1 -0
  22. codex_workspaces-0.1.0/src/codex_workspaces.egg-info/entry_points.txt +2 -0
  23. codex_workspaces-0.1.0/src/codex_workspaces.egg-info/requires.txt +5 -0
  24. codex_workspaces-0.1.0/src/codex_workspaces.egg-info/top_level.txt +1 -0
  25. codex_workspaces-0.1.0/tests/test_cli.py +58 -0
  26. codex_workspaces-0.1.0/tests/test_core.py +189 -0
codex_workspaces-0.1.0/CHANGELOG.md ADDED
@@ -0,0 +1,39 @@
1
+ # Changelog
2
+
3
+ All notable changes to `codex-workspaces` will be documented in this file.
4
+
5
+ This project follows a simple changelog format while it is still pre-release.
6
+
7
+ ## Unreleased
8
+
9
+ ### Added
10
+
11
+ - Added the cross-platform Python 3 package with the `codex-workspaces` console script.
12
+ - Added Linux/macOS symlink switching and Windows symlink/junction support.
13
+ - Added Python unit tests for workspace validation, creation, migration, switching, CLI dispatch, and platform safety behavior.
14
+ - Added `pyproject.toml`, package metadata, editable install support, and PyPI-ready build configuration.
15
+ - Added GitHub Actions CI for Linux, macOS, Windows, and Python 3.9/3.11/3.13.
16
+ - Added GitHub Actions Trusted Publishing workflow for PyPI releases.
17
+ - Added design, testing, and release documentation under `docs/`.
18
+ - Added the `codex-workspaces` macOS shell script for managing multiple Codex workspace directories.
19
+ - Added workspace listing with active workspace detection.
20
+ - Added current workspace inspection.
21
+ - Added workspace switching through the active `~/.codex` symlink.
22
+ - Added Codex app stop, start, and restart commands.
23
+ - Added workspace creation with `codex-workspaces create <workspace>`.
24
+ - Added first-time migration with `codex-workspaces create <workspace> --migrate-current`.
25
+ - Added `--migrate` as a short alias for `--migrate-current`.
26
+ - Added self-install support with `codex-workspaces install [directory]`.
27
+ - Added English and Chinese command output, controlled by system language or `CODEX_WORKSPACES_LANG`.
28
+ - Renamed the command, package, module, docs, and environment variables to `codex-workspaces` / `CODEX_WORKSPACES_*`.
29
+ - Added English and Simplified Chinese README files.
30
+
31
+ ### Safety
32
+
33
+ - Refuses to switch workspaces when `~/.codex` exists but is not a symlink.
34
+ - Delegates stop, switch, and restart commands to Terminal.app when they are run from a detected Codex terminal environment.
35
+ - Refuses start and migration commands when they are run from a detected Codex terminal environment.
36
+ - Refuses first-time migration while the Codex app is still running.
37
+ - Refuses first-time migration when the script cannot confirm whether the Codex app is running.
38
+ - Refuses first-time migration when the target workspace directory already exists.
39
+ - Limits workspace names to letters, numbers, dots, underscores, and hyphens.
codex_workspaces-0.1.0/MANIFEST.in ADDED
@@ -0,0 +1,5 @@
1
+ include CHANGELOG.md
2
+ include README.zh-CN.md
3
+ include codex-workspaces
4
+ recursive-include docs *.md
5
+ recursive-include tests *.py
codex_workspaces-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: codex-workspaces
3
+ Version: 0.1.0
4
+ Summary: Cross-platform Codex workspace switcher with a preserved macOS shell workflow.
5
+ Author: blockchain-project-lives
6
+ Project-URL: Homepage, https://github.com/blockchain-project-lives/codex-workspaces
7
+ Project-URL: Repository, https://github.com/blockchain-project-lives/codex-workspaces
8
+ Project-URL: Changelog, https://github.com/blockchain-project-lives/codex-workspaces/blob/main/CHANGELOG.md
9
+ Keywords: codex,workspaces,cli,symlink
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ Provides-Extra: dev
25
+ Requires-Dist: build>=1.2; extra == "dev"
26
+ Requires-Dist: pytest>=8; extra == "dev"
27
+ Requires-Dist: twine>=5; extra == "dev"
28
+
29
+ # codex-workspaces
30
+
31
+ English | [简体中文](README.zh-CN.md) | [Changelog](CHANGELOG.md)
32
+
33
+ `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.
34
+
35
+ The project now has two entry points:
36
+
37
+ - A cross-platform Python 3 CLI for Linux, macOS, and Windows.
38
+ - The original macOS Bash script, still kept at [`codex-workspaces`](codex-workspaces), for users who installed the shell workflow directly.
39
+
40
+ 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.
41
+
42
+ ## Features
43
+
44
+ - Manage workspace directories such as `~/.codex-work` and `~/.codex-personal`.
45
+ - Switch the active `~/.codex` symlink or directory link.
46
+ - Create workspace directories and migrate an existing real `~/.codex` directory.
47
+ - Keep macOS Codex App stop/start/restart support.
48
+ - Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
49
+ - Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
50
+ - Package as a Python project with tests, CI, and PyPI publishing workflow.
51
+
52
+ ## Requirements
53
+
54
+ - Python 3.9 or newer for the Python CLI.
55
+ - macOS is required only for Codex App control commands: `start`, `stop`, and `restart`.
56
+ - Linux and macOS use directory symlinks.
57
+ - Windows uses directory symlinks when available and falls back to directory junctions.
58
+
59
+ ## Install
60
+
61
+ Install the Python CLI from PyPI:
62
+
63
+ ```bash
64
+ python3 -m pip install codex-workspaces
65
+ ```
66
+
67
+ For isolated CLI installs, `pipx` is recommended:
68
+
69
+ ```bash
70
+ pipx install codex-workspaces
71
+ ```
72
+
73
+ Install from a local checkout for development:
74
+
75
+ ```bash
76
+ python3 -m pip install -e ".[dev]"
77
+ ```
78
+
79
+ The legacy macOS shell installer is still available:
80
+
81
+ ```bash
82
+ 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"
83
+ ```
84
+
85
+ ## Workspace Layout
86
+
87
+ Default layout:
88
+
89
+ ```text
90
+ ~/.codex -> active workspace link
91
+ ~/.codex-work workspace directory named work
92
+ ~/.codex-personal workspace directory named personal
93
+ ```
94
+
95
+ Customize paths with `CODEX_WORKSPACES_LINK` and `CODEX_WORKSPACES_PREFIX`.
96
+
97
+ ## Usage
98
+
99
+ Create workspaces:
100
+
101
+ ```bash
102
+ codex-workspaces create personal
103
+ codex-workspaces create work
104
+ ```
105
+
106
+ If you already have a real `~/.codex` directory, migrate it first:
107
+
108
+ ```bash
109
+ codex-workspaces create personal --migrate-current
110
+ ```
111
+
112
+ Switch workspaces:
113
+
114
+ ```bash
115
+ codex-workspaces work
116
+ codex-workspaces use personal
117
+ codex-workspaces switch work
118
+ ```
119
+
120
+ On macOS, switching stops and restarts Codex App by default. Skip those steps when needed:
121
+
122
+ ```bash
123
+ codex-workspaces work --no-stop --no-start
124
+ ```
125
+
126
+ Inspect workspaces:
127
+
128
+ ```bash
129
+ codex-workspaces list
130
+ codex-workspaces current
131
+ ```
132
+
133
+ Control Codex App on macOS:
134
+
135
+ ```bash
136
+ codex-workspaces stop
137
+ codex-workspaces start
138
+ codex-workspaces restart
139
+ ```
140
+
141
+ ## Environment Variables
142
+
143
+ | Variable | Default | Description |
144
+ | --- | --- | --- |
145
+ | `CODEX_APP_NAME` | `Codex` | macOS app name to control. |
146
+ | `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
147
+ | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
148
+ | `CODEX_WORKSPACES_PREFIX` | `$HOME/.codex-` | Workspace directory prefix. |
149
+ | `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
150
+
151
+ Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
152
+
153
+ ## Development
154
+
155
+ ```bash
156
+ python3 -m pip install -e ".[dev]"
157
+ python3 -m pytest
158
+ python3 -m build
159
+ python3 -m twine check dist/*
160
+ ```
161
+
162
+ Design, test, and release notes live in [`docs/`](docs/).
163
+
164
+ ## Publishing
165
+
166
+ 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.
167
+
168
+ 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/README.MD ADDED
@@ -0,0 +1,140 @@
1
+ # codex-workspaces
2
+
3
+ English | [简体中文](README.zh-CN.md) | [Changelog](CHANGELOG.md)
4
+
5
+ `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.
6
+
7
+ The project now has two entry points:
8
+
9
+ - A cross-platform Python 3 CLI for Linux, macOS, and Windows.
10
+ - The original macOS Bash script, still kept at [`codex-workspaces`](codex-workspaces), for users who installed the shell workflow directly.
11
+
12
+ 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.
13
+
14
+ ## Features
15
+
16
+ - Manage workspace directories such as `~/.codex-work` and `~/.codex-personal`.
17
+ - Switch the active `~/.codex` symlink or directory link.
18
+ - Create workspace directories and migrate an existing real `~/.codex` directory.
19
+ - Keep macOS Codex App stop/start/restart support.
20
+ - Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
21
+ - Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
22
+ - Package as a Python project with tests, CI, and PyPI publishing workflow.
23
+
24
+ ## Requirements
25
+
26
+ - Python 3.9 or newer for the Python CLI.
27
+ - macOS is required only for Codex App control commands: `start`, `stop`, and `restart`.
28
+ - Linux and macOS use directory symlinks.
29
+ - Windows uses directory symlinks when available and falls back to directory junctions.
30
+
31
+ ## Install
32
+
33
+ Install the Python CLI from PyPI:
34
+
35
+ ```bash
36
+ python3 -m pip install codex-workspaces
37
+ ```
38
+
39
+ For isolated CLI installs, `pipx` is recommended:
40
+
41
+ ```bash
42
+ pipx install codex-workspaces
43
+ ```
44
+
45
+ Install from a local checkout for development:
46
+
47
+ ```bash
48
+ python3 -m pip install -e ".[dev]"
49
+ ```
50
+
51
+ The legacy macOS shell installer is still available:
52
+
53
+ ```bash
54
+ 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"
55
+ ```
56
+
57
+ ## Workspace Layout
58
+
59
+ Default layout:
60
+
61
+ ```text
62
+ ~/.codex -> active workspace link
63
+ ~/.codex-work workspace directory named work
64
+ ~/.codex-personal workspace directory named personal
65
+ ```
66
+
67
+ Customize paths with `CODEX_WORKSPACES_LINK` and `CODEX_WORKSPACES_PREFIX`.
68
+
69
+ ## Usage
70
+
71
+ Create workspaces:
72
+
73
+ ```bash
74
+ codex-workspaces create personal
75
+ codex-workspaces create work
76
+ ```
77
+
78
+ If you already have a real `~/.codex` directory, migrate it first:
79
+
80
+ ```bash
81
+ codex-workspaces create personal --migrate-current
82
+ ```
83
+
84
+ Switch workspaces:
85
+
86
+ ```bash
87
+ codex-workspaces work
88
+ codex-workspaces use personal
89
+ codex-workspaces switch work
90
+ ```
91
+
92
+ On macOS, switching stops and restarts Codex App by default. Skip those steps when needed:
93
+
94
+ ```bash
95
+ codex-workspaces work --no-stop --no-start
96
+ ```
97
+
98
+ Inspect workspaces:
99
+
100
+ ```bash
101
+ codex-workspaces list
102
+ codex-workspaces current
103
+ ```
104
+
105
+ Control Codex App on macOS:
106
+
107
+ ```bash
108
+ codex-workspaces stop
109
+ codex-workspaces start
110
+ codex-workspaces restart
111
+ ```
112
+
113
+ ## Environment Variables
114
+
115
+ | Variable | Default | Description |
116
+ | --- | --- | --- |
117
+ | `CODEX_APP_NAME` | `Codex` | macOS app name to control. |
118
+ | `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
119
+ | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
120
+ | `CODEX_WORKSPACES_PREFIX` | `$HOME/.codex-` | Workspace directory prefix. |
121
+ | `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
122
+
123
+ Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
124
+
125
+ ## Development
126
+
127
+ ```bash
128
+ python3 -m pip install -e ".[dev]"
129
+ python3 -m pytest
130
+ python3 -m build
131
+ python3 -m twine check dist/*
132
+ ```
133
+
134
+ Design, test, and release notes live in [`docs/`](docs/).
135
+
136
+ ## Publishing
137
+
138
+ 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.
139
+
140
+ 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/README.zh-CN.md ADDED
@@ -0,0 +1,140 @@
1
+ # codex-workspaces
2
+
3
+ [English](README.MD) | 简体中文 | [更新日志](CHANGELOG.md)
4
+
5
+ `codex-workspaces` 用来切换多个 Codex 工作区目录。默认把每个工作区放在 `~/.codex-<工作区名>`，并让当前生效的 `~/.codex` 指向选中的工作区。
6
+
7
+ 项目现在有两个入口：
8
+
9
+ - 跨平台 Python 3 CLI，支持 Linux、macOS 和 Windows。
10
+ - 原来的 macOS Bash 脚本，仍保留在 [`codex-workspaces`](codex-workspaces)，兼容已经使用 shell 安装方式的用户。
11
+
12
+ 在 macOS 上，Python CLI 保留原来的 App 流程：关闭 Codex App、切换工作区链接、再启动 Codex App。在 Linux 和 Windows 上，CLI 会跳过 App 启停，只切换工作区链接。
13
+
14
+ ## 功能
15
+
16
+ - 管理 `~/.codex-work`、`~/.codex-personal` 这类工作区目录。
17
+ - 切换当前 `~/.codex` 软链接或目录链接。
18
+ - 创建工作区目录，并支持把已有真实 `~/.codex` 目录迁移成工作区。
19
+ - 保留 macOS 上 Codex App 的 `stop`、`start`、`restart`。
20
+ - 在检测到 Codex 内置 Terminal 且无法安全转交时，阻止危险操作。
21
+ - 支持中英文输出，可通过 `CODEX_WORKSPACES_LANG` 指定。
22
+ - 提供 Python 包、测试、GitHub CI 和 PyPI 发布工作流。
23
+
24
+ ## 要求
25
+
26
+ - Python 3.9 或更新版本。
27
+ - 只有 `start`、`stop`、`restart` 这类 Codex App 控制命令要求 macOS。
28
+ - Linux 和 macOS 使用目录软链接。
29
+ - Windows 优先使用目录软链接，不可用时回退到目录 junction。
30
+
31
+ ## 安装
32
+
33
+ 从 PyPI 安装 Python CLI：
34
+
35
+ ```bash
36
+ python3 -m pip install codex-workspaces
37
+ ```
38
+
39
+ 推荐用 `pipx` 做隔离安装：
40
+
41
+ ```bash
42
+ pipx install codex-workspaces
43
+ ```
44
+
45
+ 本地开发安装：
46
+
47
+ ```bash
48
+ python3 -m pip install -e ".[dev]"
49
+ ```
50
+
51
+ 旧版 macOS shell 安装方式仍可使用：
52
+
53
+ ```bash
54
+ 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"
55
+ ```
56
+
57
+ ## 工作区目录
58
+
59
+ 默认布局：
60
+
61
+ ```text
62
+ ~/.codex -> 当前工作区链接
63
+ ~/.codex-work 名为 work 的工作区目录
64
+ ~/.codex-personal 名为 personal 的工作区目录
65
+ ```
66
+
67
+ 可通过 `CODEX_WORKSPACES_LINK` 和 `CODEX_WORKSPACES_PREFIX` 自定义路径。
68
+
69
+ ## 使用
70
+
71
+ 创建工作区：
72
+
73
+ ```bash
74
+ codex-workspaces create personal
75
+ codex-workspaces create work
76
+ ```
77
+
78
+ 如果已经有一个真实存在的 `~/.codex` 目录，先迁移：
79
+
80
+ ```bash
81
+ codex-workspaces create personal --migrate-current
82
+ ```
83
+
84
+ 切换工作区：
85
+
86
+ ```bash
87
+ codex-workspaces work
88
+ codex-workspaces use personal
89
+ codex-workspaces switch work
90
+ ```
91
+
92
+ macOS 上默认会在切换前后关闭和启动 Codex App。需要时可以跳过：
93
+
94
+ ```bash
95
+ codex-workspaces work --no-stop --no-start
96
+ ```
97
+
98
+ 查看工作区：
99
+
100
+ ```bash
101
+ codex-workspaces list
102
+ codex-workspaces current
103
+ ```
104
+
105
+ macOS 上控制 Codex App：
106
+
107
+ ```bash
108
+ codex-workspaces stop
109
+ codex-workspaces start
110
+ codex-workspaces restart
111
+ ```
112
+
113
+ ## 环境变量
114
+
115
+ | 变量 | 默认值 | 说明 |
116
+ | --- | --- | --- |
117
+ | `CODEX_APP_NAME` | `Codex` | macOS App 名称。 |
118
+ | `CODEX_QUIT_TIMEOUT` | `20` | 等待 App 退出的秒数。 |
119
+ | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | 当前工作区链接路径。 |
120
+ | `CODEX_WORKSPACES_PREFIX` | `$HOME/.codex-` | 工作区目录前缀。 |
121
+ | `CODEX_WORKSPACES_LANG` | 自动 | 强制输出语言，可设为 `en` 或 `zh`。 |
122
+
123
+ 工作区相关配置只使用 `CODEX_WORKSPACES_*` 变量。
124
+
125
+ ## 开发
126
+
127
+ ```bash
128
+ python3 -m pip install -e ".[dev]"
129
+ python3 -m pytest
130
+ python3 -m build
131
+ python3 -m twine check dist/*
132
+ ```
133
+
134
+ 设计、测试和发布说明见 [`docs/`](docs/)。
135
+
136
+ ## 发布
137
+
138
+ CI 会在 Linux、macOS、Windows 上测试 Python 3.9、3.11、3.13。`Publish to PyPI` 工作流会在 GitHub Release 发布或手动触发时构建并发布到 PyPI。
139
+
140
+ 发布前需要在 TestPyPI 和 PyPI 分别配置 Trusted Publishing。详见 [`docs/RELEASE.zh-CN.md`](docs/RELEASE.zh-CN.md)。