multi-codex 0.7.0__py3-none-any.whl

multi_codex/__init__.py

@@ -0,0 +1,3 @@
+"""multi-codex：管理多个 Codex CLI 账号目录、启动命令与代理设置。"""
+
+__version__ = "0.7.0"

multi_codex/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

multi_codex/accounts.py

@@ -0,0 +1,245 @@
+"""账号收敛引擎：对比新旧配置与实际文件状态，生成并执行动作列表（方案 §5.1.1、§5.1.2）。
+
+所有写命令（init、add、proxy、remove、apply，以及迁移最后的登记步骤）都走这里：
+1. 调用方算出新配置；
+2. plan() 只读地生成完整动作列表，并就地更新新配置里的 managed_links；
+3. 有冲突就直接返回 3，什么都不写；
+4. 否则先原子写入 config.json，再逐个执行文件动作。
+
+先写配置再执行文件动作，是为了让“文件动作中途失败”可以靠重跑收敛：
+配置已经是新的，下次 plan() 会补齐缺的文件。反过来先改文件再写配置，
+失败时会留下配置里没有记录的链接，之后再也不会被清理。
+"""
+
+import os
+from typing import Dict, FrozenSet, Iterable, List, Optional, Sequence, Set, Union
+
+from . import launcher, shared
+from .actions import (CONFLICT, CREATE, DELETE, SKIP, UNCHANGED, UPDATE, Action, error,
+                      has_conflict, info, print_action)
+from .config import Account, Config, config_path, dump_config, save_config
+from .fsutil import KIND_DIR, KIND_MISSING, atomic_write, entry_kind, expand, read_text
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_CONFLICT = 3
+EXIT_BUSY = 4
+
+# orphan_scope 取这个值时，清理启动命令目录里所有不在配置中的受管启动命令。
+ALL_ORPHANS = "all"
+NO_ORPHANS: FrozenSet[str] = frozenset()
+
+
+def account_dir(config: Config, name: str) -> str:
+    return os.path.join(expand(config.root), name)
+
+
+def plan(old: Config, new: Config, *, config_exists: bool = True,
+         orphan_scope: Union[str, FrozenSet[str]] = NO_ORPHANS,
+         assume_dirs: Iterable[str] = (), adopt_accounts: FrozenSet[str] = frozenset(),
+         extra_actions: Sequence[Action] = ()) -> List[Action]:
+    """生成从 old 收敛到 new 所需的全部动作。只读文件系统，不做任何修改。
+
+    orphan_scope：要清理的孤儿启动命令的账号名集合（casefold 后比较）；ALL_ORPHANS 表示全部清理，
+    NO_ORPHANS 表示不清理。只有 apply 和 remove 需要清理孤儿。
+    assume_dirs：视为已存在的账号目录。迁移在移动数据前做预检时，目标目录还不存在，
+    但迁移完成后它一定存在，不应计划“创建目录”。
+    adopt_accounts：要接管已有共享软链的账号名集合（casefold 后比较），只有 `add --adopt` 会传入。
+    extra_actions：一次性的附加动作（目前只有 `add --config-from` 的复制），追加在最后，
+    所以总在账号目录创建之后执行，并且与其它动作一起参与“有冲突就什么都不写”的判断。
+    """
+    actions: List[Action] = []
+    assumed = {expand(path) for path in assume_dirs}
+    old_root, new_root = expand(old.root), expand(new.root)
+    old_bin, new_bin = expand(old.bin_dir), expand(new.bin_dir)
+
+    # 工具不会搬迁账号目录，所以已有账号时改根目录只能判冲突。
+    if old.accounts and old_root != new_root:
+        actions.append(Action(CONFLICT, "config", config_path(),
+                              "cannot change root from {} to {} while accounts are registered".format(
+                                  old_root, new_root)))
+
+    planned_deletes: Set[str] = set()
+    for account in new.accounts.values():
+        old_account = old.find(account.name)
+        if old_account is not None and old_account.name != account.name:
+            # 只改了大小写：在区分大小写的文件系统上会新建另一份目录和启动命令，
+            # 而旧启动命令因为按大小写不敏感匹配，既不算孤儿也不会被清理。
+            actions.append(Action(CONFLICT, "config", config_path(),
+                                  "account {!r} is registered as {!r}; renaming is not supported".format(
+                                      account.name, old_account.name)))
+            continue
+        directory = os.path.join(new_root, account.name)
+        actions.extend(_plan_account_dir(directory, assumed))
+        actions.extend(_plan_launcher(new_bin, account.name, directory, account.proxy, account.env))
+        if old_account is not None and old_bin != new_bin:
+            actions.extend(_plan_launcher_delete(old_bin, old_account.name, planned_deletes,
+                                                 "bin_dir changed"))
+        actions.extend(shared.plan_shared(new, account, directory, old.shared_dir,
+                                          adopt=account.name.casefold() in adopt_accounts))
+
+    for old_account in old.accounts.values():
+        if new.find(old_account.name) is None:
+            actions.extend(_plan_launcher_delete(old_bin, old_account.name, planned_deletes,
+                                                 "account removed"))
+            actions.extend(shared.plan_remove_links(old_account, os.path.join(old_root, old_account.name),
+                                                    old.shared_dir))
+
+    if orphan_scope:
+        for name, path in launcher.scan_managed(new_bin).items():
+            if new.find(name) is not None:
+                continue
+            if orphan_scope == ALL_ORPHANS or name.casefold() in orphan_scope:
+                actions.extend(_plan_launcher_delete(new_bin, name, planned_deletes,
+                                                     "orphan launcher", path=path))
+
+    config_changed = not config_exists or dump_config(old) != dump_config(new)
+    config_action = Action(CREATE if not config_exists else (UPDATE if config_changed else UNCHANGED),
+                           "config", config_path())
+    return [config_action] + actions + list(extra_actions)
+
+
+def _plan_account_dir(directory: str, assumed: Set[str]) -> List[Action]:
+    if directory in assumed:
+        return []
+    kind = entry_kind(directory)
+    if kind == KIND_MISSING:
+        return [Action(CREATE, "account-dir", directory, run=lambda: _make_private_dir(directory))]
+    # 账号目录本身是软链（例如用户手工迁移后留的链接）也可以接受，只要最终指向目录。
+    if kind == KIND_DIR or os.path.isdir(directory):
+        return [Action(UNCHANGED, "account-dir", directory)]
+    return [Action(CONFLICT, "account-dir", directory, "exists but is not a directory")]
+
+
+def plan_config_copy(config: Config, account: Account, content: str, source_name: str) -> List[Action]:
+    """`add --config-from`：把另一个账号的 config.toml 内容复制到本账号，只复制一次。
+
+    config / account 是应用了本条命令其它选项（如 --shared）之后的新配置。判断顺序见
+    feature-config-copy §5.1：共享检查最先，因为共享的 config.toml 应当是软链，
+    atomic_write 的 os.replace 会把软链换成普通文件，之后 apply 就会判冲突。
+    已有不同内容时不覆盖：那可能是用户已经改过的配置。
+    """
+    target = os.path.join(account_dir(config, account.name), "config.toml")
+    if account.shared and "config.toml" in config.shared_items:
+        return [Action(CONFLICT, "config-file", target,
+                       "config.toml is shared for this account and does not need copying")]
+    kind = entry_kind(target)
+    if kind == KIND_MISSING:
+        def run() -> None:
+            # 配置里可能有 experimental_bearer_token 之类的密钥，只允许本人读写。
+            atomic_write(target, content, mode=0o600)
+        return [Action(CREATE, "config-file", target, "copied from {}".format(source_name), run)]
+    if not os.path.isfile(target):
+        return [Action(CONFLICT, "config-file", target, "exists but is not a file")]
+    if read_text(target) == content:
+        return [Action(UNCHANGED, "config-file", target)]
+    return [Action(CONFLICT, "config-file", target, "already exists with different content")]
+
+
+def _make_private_dir(directory: str) -> None:
+    # 目录里会保存 auth.json，所以账号目录和根目录都只允许本人访问。
+    parent = os.path.dirname(directory)
+    if not os.path.isdir(parent):
+        os.makedirs(parent, mode=0o700)
+    os.mkdir(directory, 0o700)
+    os.chmod(directory, 0o700)
+
+
+def _plan_launcher(bin_dir: str, name: str, directory: str, proxy: str,
+                   env: Optional[Dict[str, str]] = None) -> List[Action]:
+    path = launcher.launcher_path(bin_dir, name)
+    content = launcher.render(name, directory, proxy, env)
+    mode = launcher.launcher_mode(env)
+    kind = entry_kind(path)
+    if kind == KIND_MISSING:
+        return [Action(CREATE, "launcher", path, run=_write_launcher(path, content, mode))]
+    owner = launcher.managed_account(path)
+    if owner is None:
+        return [Action(CONFLICT, "launcher", path, "already exists and is not managed by multi-codex")]
+    if owner.casefold() != name.casefold():
+        return [Action(CONFLICT, "launcher", path, "managed by multi-codex for account {!r}".format(owner))]
+    if launcher.launcher_file_ok(path, content, env):
+        return [Action(UNCHANGED, "launcher", path)]
+    return [Action(UPDATE, "launcher", path, run=_write_launcher(path, content, mode))]
+
+
+def _write_launcher(path: str, content: str, mode: int):
+    def run() -> None:
+        atomic_write(path, content, mode=mode)
+    return run
+
+
+def _plan_launcher_delete(bin_dir: str, name: str, planned: Set[str], reason: str,
+                          path: Optional[str] = None) -> List[Action]:
+    path = path or launcher.launcher_path(bin_dir, name)
+    if path in planned or entry_kind(path) == KIND_MISSING:
+        return []
+    owner = launcher.managed_account(path)
+    if owner is None or owner.casefold() != name.casefold():
+        return [Action(SKIP, "launcher", path, "not managed by multi-codex for this account; left untouched")]
+    planned.add(path)
+    return [Action(DELETE, "launcher", path, reason, lambda: os.unlink(path))]
+
+
+def execute(old: Config, new: Config, actions: List[Action], *, dry_run: bool, verbose: bool = False) -> int:
+    """按 §5.1.1 的顺序执行：有冲突则全部不写；否则先写配置，再逐个执行文件动作。
+
+    verbose=False（默认）时不打印 unchanged 行：重复执行时满屏 unchanged 会把真正的变化淹没
+    （feature-onboarding-commands B3）。create / update / delete / skip / conflict 照常打印——
+    skip 是提示信息（例如共享目录缺少某项），不能当成“没变化”藏起来。
+    一行都没打印时说一句 already up to date，免得用户以为命令什么都没做。
+    """
+    printed = 0
+    for action in actions:
+        if verbose or action.status != UNCHANGED:
+            print_action(action, dry_run=dry_run)
+            printed += 1
+    if printed == 0:
+        info("already up to date")
+    if has_conflict(actions):
+        info("nothing was changed because of the conflicts above")
+        return EXIT_CONFLICT
+    if dry_run:
+        return EXIT_OK
+    config_action = actions[0]
+    if config_action.changes:
+        try:
+            save_config(new)
+        except OSError as exc:
+            error(str(exc), phase="config", path=config_action.path)
+            return EXIT_ERROR
+    for action in actions[1:]:
+        if not action.changes or action.run is None:
+            continue
+        try:
+            action.run()
+        except OSError as exc:
+            # 配置已经写入，重跑同一命令或 `apply` 会从这里继续收敛。
+            error("{}; rerun the command or `multi-codex apply` to finish".format(exc),
+                  phase=action.kind, path=action.path)
+            return EXIT_ERROR
+    return EXIT_OK
+
+
+def converge(old: Config, new: Config, *, config_exists: bool, dry_run: bool,
+             orphan_scope: Union[str, FrozenSet[str]] = NO_ORPHANS, assume_dirs: Iterable[str] = (),
+             adopt_accounts: FrozenSet[str] = frozenset(), extra_actions: Sequence[Action] = (),
+             verbose: bool = False) -> int:
+    actions = plan(old, new, config_exists=config_exists, orphan_scope=orphan_scope,
+                   assume_dirs=assume_dirs, adopt_accounts=adopt_accounts, extra_actions=extra_actions)
+    return execute(old, new, actions, dry_run=dry_run, verbose=verbose)
+
+
+def launcher_status(config: Config, name: str) -> str:
+    """list 命令用：ok、missing、conflict 或 stale（内容与配置不一致）。"""
+    account = config.find(name)
+    path = launcher.launcher_path(expand(config.bin_dir), name)
+    if entry_kind(path) == KIND_MISSING:
+        return "missing"
+    owner = launcher.managed_account(path)
+    if owner is None or owner.casefold() != name.casefold():
+        return "conflict"
+    env = account.env if account else {}
+    expected = launcher.render(name, account_dir(config, name), account.proxy if account else "inherit", env)
+    return "ok" if launcher.launcher_file_ok(path, expected, env) else "stale"

multi_codex/actions.py

@@ -0,0 +1,76 @@
+"""动作列表：计划阶段产出、执行阶段逐个执行的最小单元，以及统一的输出格式。
+
+所有写命令都先生成完整的动作列表，只要其中有一个 conflict 就什么都不写（方案 §5.1.1），
+所以“计划”与“执行”必须分开：计划阶段只读文件系统，副作用全部放在 run 回调里。
+"""
+
+import sys
+from typing import Callable, List, Optional
+
+from .fsutil import display_path
+
+CREATE = "create"
+UPDATE = "update"
+DELETE = "delete"
+UNCHANGED = "unchanged"
+CONFLICT = "conflict"
+# 不需要改动、但值得告诉用户的情况，例如共享目录里没有某个条目。
+SKIP = "skip"
+
+LOG_PREFIX = "[multi-codex]"
+
+
+class Action(object):
+    def __init__(self, status: str, kind: str, path: str, reason: str = "",
+                 run: Optional[Callable[[], None]] = None) -> None:
+        self.status = status
+        # 对象类型：config、account-dir、launcher、shared-link、backup 等
+        self.kind = kind
+        self.path = path
+        self.reason = reason
+        self.run = run
+
+    @property
+    def changes(self) -> bool:
+        return self.status in (CREATE, UPDATE, DELETE)
+
+
+def has_conflict(actions: List[Action]) -> bool:
+    return any(action.status == CONFLICT for action in actions)
+
+
+def print_action(action: Action, dry_run: bool = False) -> None:
+    status = action.status + (" (dry-run)" if dry_run and action.changes else "")
+    # 路径缩写成 ~/…，只为好读；脚本应读 --json，这里的文本格式不保证稳定。
+    line = "{} {} {} {}".format(LOG_PREFIX, status, action.kind, display_path(action.path))
+    if action.reason:
+        line += " ({})".format(action.reason)
+    stream = sys.stderr if action.status == CONFLICT else sys.stdout
+    print(line, file=stream)
+
+
+def info(message: str) -> None:
+    print("{} {}".format(LOG_PREFIX, message))
+
+
+def hint(message: str) -> None:
+    """给新用户的下一步提示。写 stderr：stdout 可能被脚本逐行读取（例如 `use` 不带参数时输出账号名）。
+
+    先 flush stdout：输出接到管道时 stdout 有缓冲，不 flush 的话提示会排在它所针对的动作行前面。
+    """
+    sys.stdout.flush()
+    print("{} hint: {}".format(LOG_PREFIX, message), file=sys.stderr)
+
+
+def warn(message: str) -> None:
+    print("{} warning: {}".format(LOG_PREFIX, message), file=sys.stderr)
+
+
+def error(message: str, phase: Optional[str] = None, path: Optional[str] = None) -> None:
+    """错误输出：带阶段和路径，让用户不必翻代码就能知道失败在哪一步、哪个文件。"""
+    parts = [LOG_PREFIX, "error"]
+    if phase:
+        parts.append("phase={}".format(phase))
+    if path:
+        parts.append("path={}".format(path))
+    print("{}: {}".format(" ".join(parts), message), file=sys.stderr)

multi_codex/apps.py

@@ -0,0 +1,74 @@
+"""按账号打开 VS Code 与 Codex 桌面端（实验功能，feature-app-launch）。
+
+两者都依赖未公开的行为（核实过程见方案 §1.1）：
+- VS Code：不同的 --user-data-dir 一定开出新实例；从命令行启动时不读登录 shell 的环境，
+  OpenAI 扩展把 process.env 原样传给它启动的 codex，所以 CODEX_HOME 能一路传到 codex app-server。
+- 桌面端：启动后会把登录 shell 的环境合并进来，只有设置了 CODEX_ELECTRON_USER_DATA_PATH 时
+  才把 CODEX_HOME 恢复成启动时的值，用户数据目录与单实例锁也由这个变量决定。
+
+每个账号的 GUI 数据放在 <root>/.apps/<名>/：账号名以字母或数字开头，`.apps` 不会与账号目录重名。
+"""
+
+import os
+import plistlib
+import shutil
+from typing import Optional
+
+from .config import Config
+from .fsutil import expand
+
+VERIFIED_WITH = "VS Code 1.139.1 / extension 26.928.31416 / Codex desktop 26.831.11858"
+DEFAULT_DESKTOP_APP = "/Applications/ChatGPT.app"
+# 只允许 Codex 桌面端；同一目录下的 ChatGPT Classic（com.openai.chat）是另一个应用。
+DESKTOP_BUNDLE_ID = "com.openai.codex"
+# 不从 PATH 查找 open，避免同名命令被误用；测试用这个环境变量换成假命令。
+OPEN_OVERRIDE_ENV = "MULTI_CODEX_TEST_OPEN"
+# macOS 的 unix 套接字路径上限是 104 字节，VS Code 的主套接字放在用户数据目录下（<版本>-main.sock）。
+SOCKET_DIR_WARN_LENGTH = 80
+
+
+def _private_dir(path: str) -> str:
+    os.makedirs(path, mode=0o700, exist_ok=True)
+    os.chmod(path, 0o700)  # makedirs 的 mode 受 umask 影响，这里显式收紧
+    return path
+
+
+def gui_data_dir(config: Config, name: str, kind: str) -> str:
+    """返回并创建 <root>/.apps/<名>/<kind>（kind 为 vscode 或 desktop），各级目录都只允许本人访问。"""
+    apps_root = _private_dir(os.path.join(expand(config.root), ".apps"))
+    account_root = _private_dir(os.path.join(apps_root, name))
+    return _private_dir(os.path.join(account_root, kind))
+
+
+def desktop_log(config: Config, name: str) -> str:
+    path = os.path.join(expand(config.root), ".apps", name, "desktop.log")
+    fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+    os.close(fd)
+    os.chmod(path, 0o600)
+    return path
+
+
+def find_code(override: Optional[str]) -> Optional[str]:
+    candidate = override or shutil.which("code")
+    if candidate and os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+        return candidate
+    return None
+
+
+def desktop_app_problem(app: str) -> Optional[str]:
+    """应用包不可用时返回原因，可用时返回 None。"""
+    info_path = os.path.join(app, "Contents", "Info.plist")
+    try:
+        with open(info_path, "rb") as handle:
+            info = plistlib.load(handle)
+    except (OSError, ValueError) as exc:  # plistlib 的解析错误继承自 ValueError
+        return "cannot read {}: {}".format(info_path, exc)
+    bundle_id = info.get("CFBundleIdentifier") if isinstance(info, dict) else None
+    if bundle_id != DESKTOP_BUNDLE_ID:
+        return "{} is not the Codex desktop app (bundle id {!r}, expected {!r})".format(
+            app, bundle_id, DESKTOP_BUNDLE_ID)
+    return None
+
+
+def open_command() -> str:
+    return os.environ.get(OPEN_OVERRIDE_ENV) or "/usr/bin/open"

multi_codex/binding.py

@@ -0,0 +1,66 @@
+"""目录绑定账号（feature-dir-binding）：`run` 省略账号名时，按当前目录向上找最近一个绑定。
+
+绑定的键是规范路径 normalize_dir：
+- 先 realpath 解析软链（macOS 上 /tmp 会变成 /private/tmp）；
+- 再逐级修正大小写：macOS 默认文件系统不区分大小写，realpath("casedir") 会保留输入的大小写，
+  而 os.getcwd() 返回磁盘上的真实大小写，不修正的话键永远匹配不上。
+"""
+
+import os
+from typing import Optional, Tuple
+
+from .config import Config
+
+
+def _true_name(parent: str, name: str) -> str:
+    """parent 下与 name 对应的磁盘上的名字。
+
+    原名精确存在时保留原名：区分大小写的文件系统上 Foo 与 foo 可以并存，不能挑错。
+    精确匹配不到时才按 casefold 找，且只在恰好一个时采用；listdir 失败（例如只有执行权限）时保留原名。
+    """
+    try:
+        entries = os.listdir(parent)
+    except OSError:
+        return name
+    if name in entries:
+        return name
+    folded = name.casefold()
+    matches = [entry for entry in entries if entry.casefold() == folded]
+    return matches[0] if len(matches) == 1 else name
+
+
+def normalize_dir(path: str) -> str:
+    real = os.path.realpath(os.path.expanduser(path))
+    parts = []
+    current = real
+    while True:
+        parent, name = os.path.split(current)
+        if not name:
+            root = current
+            break
+        parts.append((parent, name))
+        current = parent
+    result = root
+    for parent, name in reversed(parts):
+        # 父目录已按真实大小写拼好，用它去 listdir；这一级不存在时 _true_name 原样返回。
+        result = os.path.join(result, _true_name(result, name))
+    return result
+
+
+def resolve(config: Config, cwd: str) -> Optional[Tuple[str, str]]:
+    """从 cwd 开始逐级向上，返回最近一个绑定的 (目录, 账号名)；没有时返回 None。"""
+    current = normalize_dir(cwd)
+    while True:
+        if current in config.bindings:
+            return current, config.bindings[current]
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def drop_account(config: Config, name: str) -> None:
+    """账号被注销时（remove、restore、apply -f）删除指向它的绑定，按 casefold 匹配账号名。"""
+    folded = name.casefold()
+    for path in [path for path, bound in config.bindings.items() if bound.casefold() == folded]:
+        del config.bindings[path]