aisc-cli 0.1.0__py3-none-any.whl

aisc/cli/commands/run.py

@@ -0,0 +1,494 @@
+"""``aisc run`` — Docker container run command.
+
+Plans a ``docker run`` invocation based on user args, then optionally
+executes it.  Supports ``--events`` JSONL output.
+
+**All** docker operations go through an injected ``DockerExecutor``;
+this module never calls ``subprocess.run`` directly.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from aisc.domain.models import (
+    CliError,
+    ImageInspectStatus,
+    RunPlan,
+)
+from aisc.adapters.docker_ import (
+    DockerExecutor,
+    RealDockerExecutor,
+    format_argv_display,
+    validate_run_resources,
+    validate_proxy_config,
+)
+from aisc.cli.output import JsonlEmitter
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _generate_container_name(base: str) -> str:
+    """Generate a unique container name by appending a short random suffix."""
+    short = uuid.uuid4().hex[:8]
+    return f"{base}-{short}"
+
+
+# ---------------------------------------------------------------------------
+# Run service: plan the run
+# ---------------------------------------------------------------------------
+
+def plan_run(
+    image: str = "super-claude:latest",
+    workspace: str = "",
+    name: str = "super-claude-station",
+    network: str = "direct",
+    dry_run: bool = False,
+    interactive: bool = True,
+    non_interactive: bool = False,
+    proxy_config: str = "",
+    label: str = "",
+    keep_alive: bool = False,
+    aisc_root: Optional[Path] = None,
+) -> RunPlan:
+    """Create an immutable ``RunPlan`` from user args.
+
+    Args:
+        image: Docker image name (default: super-claude:latest).
+        workspace: Host path to bind-mount.
+        name: Container name prefix; unique suffix is appended.
+        network: ``"direct"`` or ``"proxy"``.
+        dry_run: Plan only, don't execute.
+        interactive: ``True`` → include ``-it``; ``False`` → omit.
+        non_interactive: ``True`` → omit ``-it``, add ``AISC_NON_INTERACTIVE=1``
+            and ``CLAUDE_SCOPE=project`` env vars, use DEVNULL for stdin.
+        proxy_config: Host path to ``.claude/mihomo/config.yaml``.
+            If omitted but ``network=proxy``, use
+            ``<aisc_root>/.claude/mihomo/config.yaml``.
+        keep_alive: ``True`` → omit ``--rm``, keep container after exit.
+        aisc_root: AISC root path for proxy config resolution.
+
+    Returns:
+        A ``RunPlan`` with computed docker arguments.
+
+    Raises:
+        CliError: on workspace / proxy config validation failure.
+    """
+    if ":" not in image:
+        image = f"{image}:latest"
+
+    ws_path = Path(workspace).resolve() if workspace else Path.cwd()
+
+    # Resolve proxy config (IDEA-2: data-root subscription first — the
+    # legacy <aisc_root>/.claude/mihomo/config.yaml is adopted once on first
+    # use; an explicit --proxy-config always wins).
+    resolved_proxy = proxy_config
+    if network == "proxy" and not resolved_proxy:
+        from aisc.application.network_subscription import (
+            resolve_subscription_config_path,
+        )
+
+        resolved_proxy = resolve_subscription_config_path() or ""
+
+    # Stage 7 (DATA-01): agent config mounts from the data root. The dirs
+    # are created here (host side) so Windows bind mounts have real targets.
+    # Fail closed: an unusable data root stops the run — never fall back to
+    # copying agent state into the workspace.
+    from aisc.application.data_root import DataRootResolver
+
+    resolved_state = DataRootResolver().resolve(ws_path)
+    ws_state_dir = resolved_state.workspace_dir
+    for sub in ("claude", "codex", "cc-switch", "runtime"):
+        (ws_state_dir / sub).mkdir(parents=True, exist_ok=True)
+
+    # svc-5: one gateway host port per one-shot run (same capability as
+    # managed runtimes). Ports reserved by other registered containers are
+    # skipped best-effort; dry-run shows the publish plan without Docker.
+    from aisc.application.web_gateway import (
+        allocate_gateway_host_port,
+        registry_host_ports,
+    )
+
+    exclude: set = set()
+    if aisc_root is not None:
+        try:
+            from aisc.adapters.container_registry import list_containers
+
+            exclude = registry_host_ports(list_containers(Path(aisc_root)))
+        except Exception:
+            exclude = set()
+    web_gateway_port = allocate_gateway_host_port(exclude=exclude)
+
+    # runtime-lifecycle-ux 3a: one-shot runs are project-scoped by definition
+    # (agent state mounts from the data root) — they mount the persistent
+    # toolchain exactly like managed runtimes (host_bind backend).
+    toolchain_root = ""
+    if ws_state_dir is not None:
+        from aisc.application.toolchain import prepare_toolchain, toolchain_dir_for
+
+        prepare_toolchain(ws_state_dir)
+        toolchain_root = str(toolchain_dir_for(ws_state_dir)).replace("\\", "/")
+
+    return RunPlan(
+        image=image,
+        workspace=str(ws_path),
+        name=_generate_container_name(name),
+        network=network,
+        dry_run=dry_run,
+        interactive=interactive,
+        non_interactive=non_interactive,
+        proxy_config=resolved_proxy,
+        label=label,
+        keep_alive=keep_alive,
+        agent_state_root=str(ws_state_dir),
+        web_gateway_host_port=web_gateway_port,
+        toolchain_root=toolchain_root,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Run result (structured outcome)
+# ---------------------------------------------------------------------------
+
+def _name_series(container_name: str) -> str:
+    """Container names are ``<alias>-<hash8>``; the alias may itself contain
+    dashes, the hash never does — strip the last segment to get the series
+    (rename detection keys off it, r2 #C)."""
+    return container_name.rsplit("-", 1)[0]
+
+
+@dataclass
+class RunResult:
+    """Result of a run execution — all fields populated even on failure."""
+    image: str = ""
+    container_id: Optional[str] = None
+    docker_argv: List[str] = field(default_factory=list)
+    container_exit_code: Optional[int] = None
+    dry_run: bool = False
+    executed: bool = False
+    # svc-5: service-access metadata — the gateway publish that rode this
+    # run's docker argv. Empty when no port was allocated.
+    web_gateway: Dict[str, Any] = field(default_factory=dict)
+    # r1 #2: older same-workspace containers this activation swept
+    # (stopped+removed+unregistered before the new one started).
+    replaced: List[str] = field(default_factory=list)
+    # r1 #2 (revised): a LIVE same-workspace container was REUSED — nothing
+    # was started; the summary tells the user it is already open.
+    reused: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out = {
+            "image": self.image,
+            "container_id": self.container_id,
+            "dry_run": self.dry_run,
+            "executed": self.executed,
+            "docker_argv": list(self.docker_argv),
+            "container_exit_code": self.container_exit_code,
+        }
+        if self.web_gateway:
+            out["web_gateway"] = dict(self.web_gateway)
+        if self.replaced:
+            out["replaced"] = list(self.replaced)
+        if self.reused:
+            out["reused"] = self.reused
+        return out
+
+
+def _run_captured_with_publish_retry(executor, plan: RunPlan, attempts: int = 3):
+    """``docker run`` (captured) with bounded gateway bind-conflict retry.
+
+    The argv is regenerated from the (replaced) plan each attempt so the
+    publish spec never stacks. Only the captured paths can detect the
+    conflict — the interactive streaming path inherits stderr and surfaces
+    Docker's own message on the terminal (unchanged behavior).
+    """
+    import dataclasses
+
+    from aisc.application.web_gateway import allocate_gateway_host_port, is_bind_conflict
+
+    proc = executor.run_captured(list(plan.docker_argv))
+    tried = 1
+    while proc.exit_code != 0 and is_bind_conflict(proc.stderr or "") \
+            and tried < attempts:
+        plan = dataclasses.replace(
+            plan,
+            web_gateway_host_port=allocate_gateway_host_port(
+                start_hint=plan.web_gateway_host_port + 1),
+        )
+        proc = executor.run_captured(list(plan.docker_argv))
+        tried += 1
+    return proc, plan
+
+
+# ---------------------------------------------------------------------------
+# Execute the run
+# ---------------------------------------------------------------------------
+
+def run_container(
+    plan: RunPlan,
+    *,
+    emitter: Optional[JsonlEmitter] = None,
+    executor: Optional[DockerExecutor] = None,
+    capture: bool = False,
+    aisc_root: Optional[Path] = None,
+) -> RunResult:
+    """Execute or simulate a ``docker run``, emitting events as needed.
+
+    All docker operations go through *executor* (RealDockerExecutor by default).
+
+    Args:
+        plan: The immutable run plan.
+        emitter: JsonlEmitter for --events mode, or None.
+        executor: DockerExecutor for injection (testing).
+        capture: Force captured output (stdout/stderr forwarded to stderr).
+            When True, container output never reaches stdout.
+
+    Returns:
+        RunResult with outcome data.
+
+    Raises:
+        CliError: with ``data`` field carrying full RunResult.to_dict().
+    """
+    exec_ = executor or RealDockerExecutor()
+
+    result = RunResult(
+        image=plan.image,
+        docker_argv=list(plan.docker_argv),
+        dry_run=plan.dry_run,
+        executed=False,
+    )
+    if plan.web_gateway_host_port:
+        from aisc.domain.web_services import WEB_GATEWAY_CONTAINER_PORT
+
+        result.web_gateway = {
+            "container_port": WEB_GATEWAY_CONTAINER_PORT,
+            "host_port": plan.web_gateway_host_port,
+        }
+
+    # --- emit start event ---
+    if emitter is not None:
+        emitter.emit("run.start", data={
+            "image": plan.image,
+            "workspace": plan.workspace,
+            "name": plan.name,
+            "network": plan.network,
+            "docker_argv": result.docker_argv,
+        })
+
+    # --- validate workspace (both dry-run and real) ---
+    try:
+        validate_run_resources(Path(plan.workspace))
+    except (FileNotFoundError, PermissionError, NotADirectoryError) as exc:
+        raise CliError(message=str(exc), exit_code=9,
+                       error_code="AISC_ERR_PERMISSION_DENIED",
+                       data=result.to_dict()) from exc
+
+    # --- validate proxy config (skip file checks in dry-run) ---
+    if plan.network == "proxy":
+        if not plan.proxy_config:
+            raise CliError(
+                message="Proxy network mode requires proxy configuration. "
+                        "Set --aisc-root or ensure .claude/mihomo/config.yaml exists.",
+                exit_code=1, error_code="AISC_ERR_GENERAL",
+                data=result.to_dict(),
+            )
+        if not plan.dry_run:
+            try:
+                validate_proxy_config(Path(plan.proxy_config))
+            except (FileNotFoundError, PermissionError) as exc:
+                raise CliError(message=str(exc), exit_code=1,
+                               error_code="AISC_ERR_GENERAL",
+                               data=result.to_dict()) from exc
+
+    # --- dry-run: zero docker calls, validated locally ---
+    if plan.dry_run:
+        if emitter is not None:
+            emitter.emit("run.plan", data={
+                "docker_argv": result.docker_argv,
+                "dry_run": True,
+            })
+        return result
+
+    # --- preflight ---
+    pf = exec_.preflight()
+    if not pf.available:
+        raise CliError(
+            message=f"Docker unavailable: {pf.reason}",
+            exit_code=pf.exit_code, error_code=pf.error_code,
+            data=result.to_dict(),
+        )
+
+    # --- image inspect (structured result) ---
+    inspect = exec_.inspect_image(plan.image)
+    if inspect.status == ImageInspectStatus.MISSING:
+        raise CliError(
+            message=f"镜像 '{plan.image}' 不存在。请先构建：\n"
+                    f"  aisc build --tag {plan.image}\n"
+                    f"或用 --image <名称> 指定已有镜像。",
+            exit_code=5, error_code="AISC_ERR_IMAGE_NOT_FOUND",
+            data=result.to_dict(),
+        )
+    elif inspect.status == ImageInspectStatus.DOCKER_UNAVAILABLE:
+        raise CliError(
+            message=inspect.message, exit_code=3,
+            error_code="AISC_ERR_DOCKER_UNAVAILABLE",
+            data=result.to_dict(),
+        )
+    elif inspect.status == ImageInspectStatus.PERMISSION_DENIED:
+        raise CliError(
+            message=inspect.message, exit_code=9,
+            error_code="AISC_ERR_PERMISSION_DENIED",
+            data=result.to_dict(),
+        )
+    elif inspect.status in (ImageInspectStatus.TIMEOUT, ImageInspectStatus.ERROR):
+        raise CliError(
+            message=inspect.message or "Image inspect failed",
+            exit_code=1, error_code="AISC_ERR_GENERAL",
+            data=result.to_dict(),
+        )
+    # EXISTS → proceed
+
+    # --- r1 #2 (revised) + r2 #C: same-workspace activation is IDEMPOTENT;
+    # a DIFFERENT --name is a rename intent and rebuilds ---
+    # A default (label-less) activation owns the workspace's single CLI
+    # slot. A LIVE older container of the SAME name series is REUSED — the
+    # user chose to run a workspace that is already open, so tell them
+    # (and how to reach or rebuild it) instead of churning containers under
+    # them. A live container of a DIFFERENT series (explicit --name that
+    # disagrees with the existing one) is a rename: rebuild under the new
+    # name (alias and container name must stay one story). Only DEAD ones
+    # (Exited/gone — nobody is using them) are swept (stop+rm+unregister)
+    # before the new start. GUI runtimes (owner=workbench, lease-guarded)
+    # and --label multi-container slots are never touched. If docker does
+    # not answer the liveness probe, judge nothing: fall through to the
+    # normal start path rather than risk tearing down a live container we
+    # could not see.
+    if not plan.dry_run and not plan.label:
+        from aisc.adapters.container_registry import list_containers as _lc
+        from aisc.adapters.container_registry import unregister
+        from aisc.application.data_root import workspace_state_dir
+        try:
+            _reg = workspace_state_dir(Path(plan.workspace))
+            _target = Path(plan.workspace)
+            _ps = exec_.run_captured(
+                ["ps", "-a", "--format", "{{.Names}}\t{{.Status}}"],
+                timeout=10.0)
+            if _ps.exit_code == 0:
+                _states: Dict[str, str] = {}
+                for _line in (_ps.stdout or "").splitlines():
+                    _nm2, _, _st = _line.partition("\t")
+                    if _nm2:
+                        _states[_nm2] = _st
+                for _nm, _meta in _lc(_reg).items():
+                    _meta = _meta if isinstance(_meta, dict) else {}
+                    if _meta.get("owner") == "workbench":
+                        continue
+                    if _meta.get("label"):
+                        continue
+                    try:
+                        if Path(str(_meta.get("workspace", ""))).resolve() != _target:
+                            continue
+                    except OSError:
+                        continue
+                    if (_states.get(str(_nm), "").startswith("Up")
+                            and _name_series(str(_nm)) == _name_series(plan.name)):
+                        if result.reused is None:
+                            result.reused = str(_nm)
+                        continue
+                    # dead, unknown-to-docker, or a different name series
+                    # (rename intent) → sweep and rebuild
+                    exec_.run_captured(["stop", _nm], timeout=30.0)
+                    _rm = exec_.run_captured(["rm", "-f", _nm], timeout=30.0)
+                    if _rm.exit_code == 0 or "no such" in (_rm.stderr or "").lower():
+                        try:
+                            unregister(_reg, _nm)
+                        except Exception:
+                            pass
+                        result.replaced.append(str(_nm))
+        except Exception:
+            pass
+
+    if result.reused is not None:
+        result.executed = False
+        return result
+
+    # --- register container in the multi-container index ---
+    # F2-C: the registry root is the WORKSPACE's state dir (workspaces/<h>/
+    # runtime) — the same anchor `aisc runtime start` (the Workbench path)
+    # uses. The old cwd/install-root anchor split-brained discovery: from
+    # $HOME the data-root/workspace overlap gate fired outright (nas).
+    from aisc.adapters.container_registry import register
+    from aisc.application.data_root import workspace_state_dir
+    try:
+        reg_root = workspace_state_dir(Path(plan.workspace))
+        register(reg_root, plan.name, {
+            "image": plan.image,
+            "workspace": plan.workspace,
+            "network": plan.network,
+            "label": plan.label,
+        }, set_default=not plan.label)
+        # r2 #A: a --label slot is a BYPASS activation — it must not steal
+        # the workspace's default pointer (the bare `aisc claude` entry);
+        # only the default (label-less) activation owns that pointer.
+    except (ValueError, OSError) as exc:
+        raise CliError(
+            message=f"Failed to write container registry: {exc}",
+            exit_code=1, error_code="AISC_ERR_STATE_WRITE_FAILED",
+            data=result.to_dict(),
+        ) from exc
+
+    # --- plan event for non-dry ---
+    if emitter is not None:
+        emitter.emit("run.plan", data={
+            "docker_argv": result.docker_argv,
+        })
+
+    # --- execute ---
+    argv = list(plan.docker_argv)
+
+    if emitter is not None:
+        emitter.emit("run.container.start", data={
+            "image": plan.image, "name": plan.name,
+            "docker_argv": argv,
+        })
+
+    # F2-C (fix2-design.md): run is ACTIVATE-ONLY — detached start (the
+    # plan always carries -d for keep-alive runs), capture the container id,
+    # return. No attach, no foreground streaming: the interactive surface is
+    # `aisc shell` / `aisc claude` / `aisc codex`.
+    proc, plan = _run_captured_with_publish_retry(exec_, plan)
+    result.docker_argv = list(plan.docker_argv)
+    if plan.web_gateway_host_port:
+        result.web_gateway = {**result.web_gateway,
+                              "host_port": plan.web_gateway_host_port}
+    result.container_id = (proc.stdout or "").strip() or None
+    result.container_exit_code = proc.exit_code
+    result.executed = True
+
+    if proc.exit_code != 0:
+        raise CliError(
+            message=f"Failed to start container: {proc.stderr}",
+            exit_code=10, error_code="AISC_ERR_CONTAINER_FAILED",
+            data=result.to_dict(),
+        )
+    if emitter is not None:
+        emitter.emit("run.container.complete", data={
+            "exit_code": result.container_exit_code,
+        })
+
+    # svc-5: a `--rm` container is gone the moment it exits — prune its
+    # registry entry now so nothing lingers (best-effort, never fatal).
+    if not plan.keep_alive and aisc_root is not None:
+        try:
+            from aisc.adapters.container_registry import gc as registry_gc
+
+            registry_gc(Path(aisc_root), exec_)
+        except Exception:
+            pass
+
+    return result

aisc/cli/commands/runs.py

@@ -0,0 +1,125 @@
+"""F2-C (fix2-design.md): the CLI-side activation history — ``cli-runs.json``.
+
+Distinct from the Workbench's ``history.json`` (that one carries tab layouts
+and GUI semantics); this is the light, CLI-owned record of `aisc run`
+activations: ABSOLUTE workspace paths + the config snapshot a resume needs.
+Cap-bounded, newest-first.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from aisc.domain.models import CliError
+
+#: Keep the history small — it is a picker, not an archive.
+HISTORY_CAP = 20
+
+_SCHEMA = {"schema_version": 1}
+
+
+def _history_path() -> Path:
+    """The machine-global history file under <data root>/config/ — resolved
+    via the workspace-independent shared-root API (anchoring on cwd would
+    false-positive the data-root/workspace overlap gate from $HOME)."""
+    from aisc.application.data_root import DataRootResolver
+
+    root = DataRootResolver().resolve_shared_root()
+    config = root / "config"
+    config.mkdir(parents=True, exist_ok=True)
+    return config / "cli-runs.json"
+
+
+def _load(path: Path) -> Dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict) and isinstance(data.get("runs"), list):
+            return data
+    except (OSError, ValueError):
+        pass
+    return {**_SCHEMA, "runs": []}
+
+
+def _save(path: Path, data: Dict[str, Any]) -> None:
+    path.write_text(
+        json.dumps(data, ensure_ascii=False, indent=1), encoding="utf-8"
+    )
+
+
+def record(workspace: str, image: str, network: str, label: str,
+           alias: str = "") -> None:
+    """Upsert one activation (absolute path key); newest first, capped.
+
+    *alias* is the user's `--name` for the workspace — the resume key when
+    set (an empty alias means "resume by index or path only")."""
+    path = _history_path()
+    data = _load(path)
+    ws = str(Path(workspace))
+    runs: List[Dict[str, Any]] = [r for r in data["runs"] if r.get("path") != ws]
+    runs.insert(0, {
+        "path": ws,
+        "image": image,
+        "network": network,
+        "label": label,
+        "alias": alias,
+        "last_used_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    })
+    data["runs"] = runs[:HISTORY_CAP]
+    _save(path, data)
+
+
+def set_active(workspace: str) -> None:
+    """Record the machine-global ACTIVE workspace (the default target for
+    `aisc claude`/`codex`/`stop`). Written by every activation."""
+    path = _history_path().parent / "cli-active.json"
+    path.write_text(json.dumps({"workspace": str(Path(workspace))},
+                               ensure_ascii=False), encoding="utf-8")
+
+
+def get_active() -> Optional[str]:
+    path = _history_path().parent / "cli-active.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        ws = data.get("workspace")
+        return str(ws) if isinstance(ws, str) and ws else None
+    except (OSError, ValueError):
+        return None
+
+
+def list_runs() -> List[Dict[str, Any]]:
+    return list(_load(_history_path())["runs"])
+
+
+def resolve_resume(spec: str) -> Optional[Dict[str, Any]]:
+    """Resolve a resume target: exact ALIAS → 1-based index (newest = 1) →
+    exact path. The alias is the strongest key (unique by construction — a
+    second registration with the same alias replaces the first)."""
+    runs = list_runs()
+    spec = spec.strip()
+    for r in runs:
+        if spec and r.get("alias") == spec:
+            return r
+    if spec.isdigit():
+        idx = int(spec)
+        if 1 <= idx <= len(runs):
+            return runs[idx - 1]
+        return None
+    target = str(Path(spec))
+    for r in runs:
+        if r.get("path") == target:
+            return r
+    return None
+
+
+def require_resume(spec: str) -> Dict[str, Any]:
+    rec = resolve_resume(spec)
+    if rec is None:
+        raise CliError(
+            message=f"没有匹配 {spec!r} 的激活记录——用 aisc runs 查看历史"
+                    f"（别名是最稳的键，序号会随列表变动）",
+            exit_code=2, error_code="AISC_ERR_USAGE",
+        )
+    return rec