aisc-cli 0.1.0__py3-none-any.whl

aisc/domain/data_root.py

@@ -0,0 +1,124 @@
+"""Data root domain contract (Stage 7, DATA-01..04, D7-01/02/05).
+
+The single source of truth for the canonical Windows data layout:
+``%LOCALAPPDATA%\\AISC\\data`` (see 02-domain-contract.md). Everything AISC
+auto-generates — config, state, runtime, logs, cache, artifacts, diagnostics,
+migrations — lives under one resolver-produced root; the workspace keeps only
+user files.
+
+This module is PURE (no env, no filesystem): canonicalization helpers, the
+versioned workspace hash, the layout contract and the structured resolve
+result. Env/platform selection and containment probing live in
+``aisc.application.data_root.DataRootResolver``; the Rust mirror is
+``workbench/src-tauri/src/data_root.rs`` (kept in sync via
+``tests/fixtures/data-root/hash-vectors.json``).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict
+
+DATA_ROOT_PROTOCOL = "aisc.data-root/v1"
+DATA_ROOT_SCHEMA_VERSION = 1
+
+# Versioned workspace isolation hash (D7-02). ``sha256-v1:<64 hex>`` in JSON
+# fields; the directory-name form swaps the colon for a dash (':' is illegal
+# in Windows filenames).
+WORKSPACE_HASH_ALGO = "sha256-v1"
+
+# Shared-root layout (02-domain-contract.md "Canonical layout"). Order is the
+# contract order; consumers must not invent siblings.
+SHARED_SUBDIRS = ("config", "state", "workspaces", "artifacts", "cache", "diagnostics", "logs", "migrations")
+
+# Per-workspace layout under workspaces/<hash>/.
+WORKSPACE_SUBDIRS = ("claude", "codex", "cc-switch", "runtime", "logs")
+
+# Locks live under state/ (contract: "locks/indexes"). Workspace-scoped
+# locks share the dir with a hash prefix, keeping the contract layout intact.
+LOCKS_SUBDIR = "state/locks"
+
+# Stable error codes (exit mapping is the caller's job). Domain-owned so the
+# application resolver and adapter writers share one spelling.
+ERR_OVERRIDE_RELATIVE = "AISC_ERR_DATA_ROOT_OVERRIDE_RELATIVE"
+ERR_REPARSE_POINT = "AISC_ERR_DATA_ROOT_REPARSE_POINT"
+ERR_WORKSPACE_OVERLAP = "AISC_ERR_DATA_ROOT_WORKSPACE_OVERLAP"
+ERR_LOCK_TIMEOUT = "AISC_ERR_DATA_ROOT_LOCK_TIMEOUT"
+
+
+def strip_verbatim(path_str: str) -> str:
+    """Drop Windows verbatim (``\\\\?\\``) prefixes so both languages hash the
+    same string (Python ``resolve()`` usually omits the prefix, Rust
+    ``canonicalize()`` always adds it)."""
+    if path_str.startswith("\\\\?\\UNC\\"):
+        return "\\\\" + path_str[len("\\\\?\\UNC\\"):]
+    if path_str.startswith("\\\\?\\"):
+        return path_str[len("\\\\?\\"):]
+    return path_str
+
+
+def canonical_workspace_path(workspace: Path) -> str:
+    """Canonical absolute path string used as the hash input (non-strict:
+    a missing workspace resolves as-given, matching domain/artifacts.py)."""
+    return strip_verbatim(str(Path(workspace).resolve()))
+
+
+def hash_canonical_path(canon: str) -> str:
+    """Pure hash of an ALREADY-canonical path string → ``sha256-v1:<64 hex>``.
+
+    Full digest (not the 16-hex short form used by the Stage-3 artifact
+    registry): collision tests in 04-observability-testing rely on the whole
+    digest, and D7-02 asks for the versioned form.
+    """
+    return WORKSPACE_HASH_ALGO + ":" + hashlib.sha256(canon.encode("utf-8")).hexdigest()
+
+
+def workspace_hash_v1(workspace: Path) -> str:
+    """Versioned hash of a workspace path (irreversible; never stores the raw
+    path in a directory name — D7-02)."""
+    return hash_canonical_path(canonical_workspace_path(workspace))
+
+
+def workspace_dir_name(workspace_hash: str) -> str:
+    """Windows-safe directory form: ``sha256-v1:<hex>`` → ``sha256-v1-<hex>``."""
+    return workspace_hash.replace(":", "-", 1)
+
+
+@dataclass(frozen=True)
+class ResolvedDataRoot:
+    """Structured resolver result (schema/versioned, 01-cross-stage-contracts
+    §1: callers never concatenate data-root paths themselves).
+
+    ``workspace`` is deliberately NOT in ``to_dict()`` — doctor/diagnostics
+    expose the hash, not the raw workspace path, unless the user explicitly
+    exports it (04-observability-testing "证据与脱敏").
+    """
+
+    schema: str = DATA_ROOT_PROTOCOL
+    schema_version: int = DATA_ROOT_SCHEMA_VERSION
+    root: Path = Path()
+    origin: str = "default"  # "default" | "env" (AISC_DATA_ROOT override)
+    workspace_hash: str = ""
+    writable: bool = False
+    # Relative-name → absolute-path maps (contract order).
+    shared_dirs: Dict[str, Path] = field(default_factory=dict)
+    workspace_dirs: Dict[str, Path] = field(default_factory=dict)
+
+    @property
+    def workspace_dir(self) -> Path:
+        """workspaces/<hash>/ — the per-workspace subtree root."""
+        return self.shared_dirs["workspaces"] / workspace_dir_name(self.workspace_hash)
+
+    def to_dict(self) -> Dict[str, str]:
+        return {
+            "schema": self.schema,
+            "schema_version": self.schema_version,
+            "root": str(self.root),
+            "origin": self.origin,
+            "workspace_hash": self.workspace_hash,
+            "writable": self.writable,
+            "shared_dirs": {k: str(v) for k, v in self.shared_dirs.items()},
+            "workspace_dirs": {k: str(v) for k, v in self.workspace_dirs.items()},
+        }

aisc/domain/docker_ownership.py

@@ -0,0 +1,148 @@
+"""Docker resource ownership contract (A0 / docker-ownership-foundation).
+
+Single source of truth for the ownership labels shared by the
+docker-resource-lifecycle and runtime-lifecycle-ux plans:
+
+- docs/plans/docker-resource-lifecycle/02-domain-contract.md §1
+- docs/plans/docker-resource-lifecycle/05-cross-plan-coordination.md §1
+
+Containers and volumes carry ``io.aisc.*`` labels; workstation images carry
+``org.aisc.*`` provenance labels (alongside the existing
+``org.aisc.cc-switch.*`` build labels). Labels are the primary ownership
+proof — name prefixes are legacy-compatibility evidence only and never the
+sole mechanism for new resources.
+
+Mirrored in Rust ``workbench/src-tauri/src/docker_ownership.rs`` and frozen
+in ``tests/fixtures/docker-ownership/labels.json`` (the three-language
+consistency gate for this stage; see the hash-vectors precedent in
+``tests/fixtures/data-root/``).
+
+Nothing here performs I/O and nothing here is secret-bearing: label keys,
+kind/owner values and schema versions only. Docker argv assembly for
+container/volume creation and the three-tier classification service
+(owned / legacy_owned / unverified) live in application/adapters layers
+(docker-resource-lifecycle stages A1-A2).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Mapping
+
+# ---------------------------------------------------------------------------
+# Frozen constants (mirrored in Rust docker_ownership.rs / the labels fixture)
+# ---------------------------------------------------------------------------
+
+#: Marker label proving AISC ownership. Value is always ``true``.
+LABEL_MANAGED = "io.aisc.managed"
+
+#: Resource kind. One of :data:`KIND_*`.
+LABEL_KIND = "io.aisc.kind"
+
+#: Creating component. One of :data:`OWNER_*`.
+LABEL_OWNER = "io.aisc.owner"
+
+#: Ownership label schema version (label value; Docker labels are strings).
+LABEL_SCHEMA_VERSION = "io.aisc.schema-version"
+
+#: Workspace hash scoping a resource to one workspace (containers, volumes).
+LABEL_WORKSPACE_KEY = "io.aisc.workspace-key"
+
+#: Runtime UUID — runtime containers only.
+LABEL_RUNTIME_ID = "io.aisc.runtime-id"
+
+#: Image provenance labels (``org.aisc.*`` namespace).
+IMAGE_LABEL_MANAGED = "org.aisc.managed"
+IMAGE_LABEL_KIND = "org.aisc.kind"
+IMAGE_LABEL_SCHEMA_VERSION = "org.aisc.schema-version"
+IMAGE_LABEL_SOURCE_VERSION = "org.aisc.source-version"
+
+# --- label values -----------------------------------------------------------
+
+KIND_RUNTIME = "runtime"
+KIND_ONE_SHOT = "one-shot"
+KIND_TOOLCHAIN = "toolchain"
+
+OWNER_WORKBENCH = "workbench"
+OWNER_CLI = "cli"
+
+#: The only image kind v1 defines (workstation images from ``aisc build``).
+IMAGE_KIND_WORKSTATION = "workstation-image"
+
+#: Value of ``io.aisc.schema-version`` / ``org.aisc.schema-version``.
+OWNERSHIP_LABEL_SCHEMA_V1 = "1"
+
+#: ``schema_version`` integer for the maintenance scan/cleanup JSON
+#: envelopes (docker-resource-lifecycle stage B consumes this).
+OWNERSHIP_SCHEMA_V1 = 1
+
+
+# ---------------------------------------------------------------------------
+# Pure label-set builders (consumed by the creation entry points, stage A2)
+# ---------------------------------------------------------------------------
+
+def base_labels(kind: str, owner: str) -> Dict[str, str]:
+    """Managed + kind + owner + schema-version — the minimum ownership set."""
+    return {
+        LABEL_MANAGED: "true",
+        LABEL_KIND: kind,
+        LABEL_OWNER: owner,
+        LABEL_SCHEMA_VERSION: OWNERSHIP_LABEL_SCHEMA_V1,
+    }
+
+
+def runtime_labels(runtime_id: str, owner: str, workspace_key: str) -> Dict[str, str]:
+    """Label set for a Workbench runtime container (``kind=runtime``)."""
+    labels = base_labels(KIND_RUNTIME, owner)
+    labels[LABEL_RUNTIME_ID] = runtime_id
+    labels[LABEL_WORKSPACE_KEY] = workspace_key
+    return labels
+
+
+def one_shot_labels(owner: str = OWNER_CLI) -> Dict[str, str]:
+    """Label set for a CLI one-shot container (``aisc run``)."""
+    return base_labels(KIND_ONE_SHOT, owner)
+
+
+def toolchain_volume_labels(workspace_key: str) -> Dict[str, str]:
+    """Label set for a persistent project toolchain volume.
+
+    ``kind=toolchain`` volumes are deleted only by the explicit workspace
+    runtime-data cleanup — never by generic Docker cleanup
+    (02-domain-contract.md §3.1).
+    """
+    labels = base_labels(KIND_TOOLCHAIN, OWNER_WORKBENCH)
+    labels[LABEL_WORKSPACE_KEY] = workspace_key
+    return labels
+
+
+def image_labels(source_version: str) -> Dict[str, str]:
+    """Provenance label set for workstation images built by ``aisc build``."""
+    return {
+        IMAGE_LABEL_MANAGED: "true",
+        IMAGE_LABEL_KIND: IMAGE_KIND_WORKSTATION,
+        IMAGE_LABEL_SCHEMA_VERSION: OWNERSHIP_LABEL_SCHEMA_V1,
+        IMAGE_LABEL_SOURCE_VERSION: source_version,
+    }
+
+
+def label_args(labels: Mapping[str, str]) -> List[str]:
+    """Flatten a label mapping to deterministic ``--label k=v`` argv tokens.
+
+    Sorted by key so generated argv (and its test snapshots) are stable
+    regardless of dict construction order.
+    """
+    args: List[str] = []
+    for key in sorted(labels):
+        args.extend(("--label", f"{key}={labels[key]}"))
+    return args
+
+
+def managed_filter(kind: str = None) -> str:
+    """``docker --filter`` value selecting AISC-managed resources.
+
+    Optionally narrowed to one kind — e.g. ``label=io.aisc.managed=true``
+    or ``label=io.aisc.kind=toolchain``.
+    """
+    if kind is not None:
+        return f"label={LABEL_KIND}={kind}"
+    return f"label={LABEL_MANAGED}=true"

aisc/domain/gateway.py

@@ -0,0 +1,168 @@
+"""DockerGateway domain models (Stage 4, DG-02).
+
+Every gateway operation returns a structured result carrying the cross-cutting
+facts the contract requires: ``operation_id``, ``backend``, observed state,
+exit code, duration, stable error/cleanup status. ``stdout``/``stderr`` are
+only populated when the caller explicitly requests capture and are bounded.
+
+These are pure data models — no I/O, no docker-py import.  The adapter
+(``aisc.adapters.docker_gateway``) maps Engine/SDK/CLI results onto them so
+application code never sees backend-specific shapes (D4-06).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Operation envelope
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class GatewayOperation:
+    """Cross-cutting envelope for one gateway operation.
+
+    ``backend`` is ``sdk`` | ``cli`` | ``auto`` (what actually ran); the
+    application must not branch on it — it exists for diagnostics and the
+    recording/fault-injection matrix (D4-07).
+    """
+
+    operation_id: str = ""
+    backend: str = "auto"
+    exit_code: int = -1
+    duration_ms: int = 0
+    error_code: str = ""           # stable: AISC_* or DockerErrorCode
+    error_message: str = ""
+    cleanup_status: str = "none"   # none | ok | partial | failed
+    timed_out: bool = False
+
+
+@dataclass(frozen=True)
+class GatewayResult:
+    """Base result: operation envelope + optional captured output."""
+
+    operation: GatewayOperation = field(default_factory=GatewayOperation)
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.operation.exit_code == 0 and not self.operation.error_code
+
+    @property
+    def timed_out(self) -> bool:
+        return self.operation.timed_out
+
+    @property
+    def exit_code(self) -> int:
+        """Convenience alias for ``operation.exit_code``."""
+        return self.operation.exit_code
+
+
+# ---------------------------------------------------------------------------
+# Query results
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class PreflightResult(GatewayResult):
+    """Gateway preflight: daemon reachability + docker availability."""
+
+    available: bool = False
+    reason: str = ""  # "ok" | "cli_not_found" | "daemon_unreachable" | "permission_denied"
+    docker_path: str = ""
+    docker_version: str = ""
+    engine_ok: bool = False
+
+
+@dataclass(frozen=True)
+class ImageInspectGatewayResult(GatewayResult):
+    """Structured image inspection.
+
+    ``status`` reuses :class:`aisc.domain.models.ImageInspectStatus` values
+    (exists | missing | docker_unavailable | permission_denied | timeout | error).
+    """
+
+    status: str = "error"
+    image: str = ""
+    message: str = ""
+    detail: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ContainerSummary:
+    """One container row from ``list_containers``."""
+
+    id: str = ""
+    name: str = ""
+    image: str = ""
+    state: str = ""       # running | exited | created | restarting | paused | dead
+    status: str = ""      # human string e.g. "Up 2 hours" / "Exited (0) 1 minute ago"
+    labels: Dict[str, str] = field(default_factory=dict)
+    # Content-addressed image ID (sha256:...) — A0 docker-ownership-
+    # foundation. Empty when the backend cannot provide it cheaply
+    # (CLI `docker ps` only knows the image REF); callers needing the ID
+    # inspect the specific container instead of guessing from the ref.
+    image_id: str = ""
+
+
+@dataclass(frozen=True)
+class ContainerListResult(GatewayResult):
+    """Container listing with stable per-row summary."""
+
+    containers: List[ContainerSummary] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ContainerInspectResult(GatewayResult):
+    """Container inspection: id, name, state, image, labels, config."""
+
+    container_id: str = ""
+    name: str = ""
+    state: str = ""
+    image: str = ""
+    labels: Dict[str, str] = field(default_factory=dict)
+    config: Dict[str, Any] = field(default_factory=dict)
+    # Content-addressed image ID (``.Image`` in docker inspect JSON) —
+    # distinct from ``image`` (the REF the container was created with).
+    image_id: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle results
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class LifecycleResult(GatewayResult):
+    """One lifecycle operation (start/stop/remove/wait/create)."""
+
+    target: str = ""          # container name or id
+    observed_state: str = ""  # e.g. running | stopped | removed | created | exited
+    container_id: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Interactive / build results
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class InteractiveResult(GatewayResult):
+    """Interactive exec session result.
+
+    ``exit_code`` is the agent process exit code from ``exec_inspect``;
+    ``session_id`` is the exec id for resize/cancel/wait.
+    """
+
+    session_id: str = ""
+    resized: bool = False
+    waited: bool = False
+
+
+@dataclass(frozen=True)
+class BuildResult(GatewayResult):
+    """Image build result. Events are streamed via the caller's callback;
+    this carries the terminal exit code + image ref + duration."""
+
+    image_ref: str = ""
+    events_received: int = 0