aisc-cli 0.1.0__py3-none-any.whl

aisc/cli/output.py

@@ -0,0 +1,239 @@
+"""CLI output formatting — JSON envelope, human-readable text, and JSONL emitter."""
+
+from __future__ import annotations
+
+import json
+import sys
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# JSON envelope (RFC §2)
+# ---------------------------------------------------------------------------
+
+PROTOCOL = "aisc.cli/v1"
+
+
+def _utc_now() -> str:
+    """Return an ISO 8601 UTC timestamp string."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def build_envelope(
+    command: str,
+    exit_code: int,
+    version: str,
+    data: Any = None,
+    errors: Optional[List[Dict[str, Any]]] = None,
+    *,
+    run_id: Optional[str] = None,
+    timestamp: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build a complete JSON envelope per RFC §2.
+
+    Parameters
+    ----------
+    command:
+        Subcommand name (e.g. ``"version"``, ``"doctor"``).
+    exit_code:
+        Process exit code — must match ``sys.exit()``.
+    version:
+        CLI product version.
+    data:
+        Command-specific payload.  ``None`` is treated as ``null`` in JSON.
+    errors:
+        List of error objects.  ``None`` is treated as ``[]``.
+    run_id:
+        UUID v4.  Auto-generated when not provided. Falls back to the
+        ``AISC_RUN_ID`` env var (lifecycle-logging P1: the Workbench injects
+        its operation id so app-side op events, the envelope and the log
+        timeline share one id).
+    timestamp:
+        ISO 8601 UTC string.  Auto-generated when not provided.
+    """
+    import os
+
+    effective_run_id = run_id or os.environ.get("AISC_RUN_ID") or str(uuid.uuid4())
+    return {
+        "meta": {
+            "protocol": PROTOCOL,
+            "command": command,
+            "exit_code": exit_code,
+            "timestamp": timestamp or _utc_now(),
+            "version": version,
+            "run_id": effective_run_id,
+        },
+        "data": data,
+        "errors": errors if errors is not None else [],
+    }
+
+
+def build_error(code: str, message: str, hint: Optional[str] = None) -> Dict[str, Any]:
+    """Build a single error object (RFC §2.3)."""
+    return {"code": code, "message": message, "hint": hint}
+
+
+def emit_json(envelope: Dict[str, Any]) -> None:
+    """Write *envelope* as JSON to stdout.
+
+    ``ensure_ascii=True`` keeps the stream pure ASCII: on locale-encoded
+    stdout (GBK on zh-CN Windows, cp1252 on en-US) any non-ASCII payload
+    would raise UnicodeEncodeError and kill the CLI mid-protocol (observed:
+    buildkit emoji in build.output). JSON escapes are semantically identical
+    to the consumer (serde_json).
+    """
+    print(json.dumps(envelope, ensure_ascii=True), flush=True)
+
+
+def emit_json_usage_error(
+    command: str,
+    version: str,
+    error_code: str = "AISC_ERR_USAGE",
+    message: str = "Invalid command-line arguments",
+) -> None:
+    """Emit a JSON usage error envelope to stdout and ``sys.exit(2)``."""
+    env = build_envelope(
+        command=command,
+        exit_code=2,
+        version=version,
+        data=None,
+        errors=[build_error(error_code, message)],
+    )
+    emit_json(env)
+
+
+# ---------------------------------------------------------------------------
+# Human-readable text helpers
+# ---------------------------------------------------------------------------
+
+_ANSI_COLORS = {
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "reset": "\033[0m",
+    "bold": "\033[1m",
+}
+
+
+def _maybe_style(text: str, style: str, use_color: bool) -> str:
+    if not use_color:
+        return text
+    code = _ANSI_COLORS.get(style, "")
+    reset = _ANSI_COLORS["reset"] if code else ""
+    return f"{code}{text}{reset}"
+
+
+def print_doctor_text(report: Any, use_color: bool = True) -> None:
+    """Print a doctor report in human-readable format."""
+    from aisc.domain.models import CheckStatus
+
+    status_labels = {
+        CheckStatus.PASS: _maybe_style("PASS", "green", use_color),
+        CheckStatus.WARN: _maybe_style("WARN", "yellow", use_color),
+        CheckStatus.FAIL: _maybe_style("FAIL", "red", use_color),
+        CheckStatus.SKIP: "SKIP",
+    }
+
+    lines: List[str] = []
+    lines.append(_maybe_style("=== AISC Doctor (host) ===", "bold", use_color))
+    lines.append("")
+
+    for check in report.checks:
+        label = status_labels.get(check.status, check.status.upper())
+        lines.append(f"  [{label}] {check.name}")
+        if check.message:
+            lines.append(f"         {check.message}")
+        if check.detail:
+            lines.append(f"         {check.detail}")
+        if check.hint:
+            lines.append(f"         Hint: {check.hint}")
+        lines.append("")
+
+    s = report.summary
+    lines.append("--- Summary ---")
+    lines.append(
+        f"  Passed: {s['passed']}  Warnings: {s['warnings']}  "
+        f"Failures: {s['failures']}  Skipped: {s['skipped']}"
+    )
+    if report.error_message:
+        lines.append(f"  Error: {report.error_message}")
+
+    for line in lines:
+        print(line)
+
+
+# ---------------------------------------------------------------------------
+# JSONL Event Emitter (RFC §3)
+# ---------------------------------------------------------------------------
+
+class JsonlEmitter:
+    """Emit JSONL event lines to stdout during long commands (build/run).
+
+    Usage::
+
+        emitter = JsonlEmitter(command="build")
+        emitter.emit("build.start", data={"image_tag": "..."})
+        # ... docker build ...
+        emitter.emit("build.complete", data={"exit_code": 0}, terminal=True)
+
+    Each emit() writes one JSON line to stdout, increments seq by 1,
+    and enforces that ``terminal=True`` can only be called once as the
+    final event.
+    """
+
+    def __init__(self, command: str, *, run_id: Optional[str] = None):
+        self._command = command
+        self._run_id = run_id or str(uuid.uuid4())
+        self._seq = 0
+        self._terminated = False
+
+    @property
+    def run_id(self) -> str:
+        return self._run_id
+
+    @property
+    def seq(self) -> int:
+        return self._seq
+
+    @property
+    def terminated(self) -> bool:
+        """``True`` if a terminal event has already been emitted."""
+        return self._terminated
+
+    def emit(self, event_type: str, data: Dict[str, Any],
+             *, terminal: bool = False) -> None:
+        """Emit a single JSONL event line.
+
+        Args:
+            event_type: RFC event type, e.g. ``"build.start"``.
+            data: Event-specific payload dict.
+            terminal: ``True`` for the final terminating event only.
+        """
+        if self._terminated:
+            raise RuntimeError(
+                f"JSONL stream already terminated (last event was seq={self._seq})"
+            )
+        self._seq += 1
+        event = {
+            "protocol": PROTOCOL,
+            "command": self._command,
+            "run_id": self._run_id,
+            "seq": self._seq,
+            "type": event_type,
+            "ts": _utc_now(),
+            "data": data,
+        }
+        if terminal:
+            self._terminated = True
+        # ensure_ascii=True: see emit_json - locale stdout (GBK) cannot
+        # encode buildkit's non-ASCII output and would crash mid-stream.
+        print(json.dumps(event, ensure_ascii=True), flush=True)
+
+    def emit_terminal(self, terminal_type: str, exit_code: int,
+                      extra_data: Optional[Dict[str, Any]] = None) -> None:
+        """Emit the terminal event with ``data.exit_code``."""
+        data: Dict[str, Any] = dict(extra_data or {})
+        data["exit_code"] = exit_code
+        self.emit(terminal_type, data, terminal=True)

aisc/cli/tutorial.py

@@ -0,0 +1,109 @@
+"""v2.1.7 S6: interactive-bash tutorial (Gate-S6 / D10 decision).
+
+The Workbench's bash sessions open as ``docker exec -it <name> bash``. To
+make a bare ``help`` answer INSIDE that shell (without touching the image,
+the user's workspace, or any persistent profile — A-21766), the session
+argv is rewritten to::
+
+    bash -c '<define help() + export -f it>; exec bash'
+
+``export -f`` serializes the function into the environment; the exec'd
+interactive bash re-imports it at startup. ``help`` with NO arguments prints
+the tutorial; ``help foo`` delegates to the shell builtin so nothing else
+changes (A-21765). Non-interactive shells never see any of this — the
+injection rides ONLY the interactive session-open path.
+
+2.1.9: the interactive shell is now **zsh** (2.1.8 T2/D-4), and zsh has no
+env-var function import — ``help`` is defined directly in the managed
+``container/aisc-zshrc`` (§7). The text SSOT stays HERE; the zshrc copy is
+pinned byte-for-byte by ``tests/test_tutorial_zsh.py``. The bash env path
+above still serves the bash fallback (older images without the zsh suite).
+
+The tutorial text lives here (content SSOT); the Workbench UI cards carry
+their own short i18n summaries.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+_TUTORIAL = """\
+╔══════════════ AISC Workbench 教学 ══════════════
+║ 三、五分钟核心用法
+║
+║ [Claude Code]
+║   claude              开始交互对话
+║   claude -c           继续最近一次会话
+║   claude -p "问题"     单次提问，直接返回答案
+║   claude --resume     挑选历史会话恢复
+║   会话内: /help 命令列表 · /clear 清空 · /compact 压缩上下文
+║
+║ [Codex]
+║   codex               开始交互对话
+║   codex e "任务"      单次执行任务
+║   会话内: /help · /new 新会话 · Ctrl+C 中断
+║
+║ [Workbench]
+║   左侧栏  文件/变更/服务 三个页签（顶部可搜索）
+║   右上 ⓘ 运行时状态抽屉 · Ctrl+, 设置 · + 号新建页
+║   关闭工作区 = 自动清理临时容器（数据不丢）
+║
+║ 上手练习（复制即用）：
+║   1. claude --version    查看已安装的 Claude Code 版本
+║   2. codex --version     查看 Codex 版本
+║   3. 在 + ▾ 菜单打开 claude 页签，输入 /help 浏览命令
+║   4. 左侧切到「变更」页签，点分组标题收拢/展开
+║   配置好 Provider 后可试: claude -p "用一句话介绍自己"（调用 API，产生用量）
+║
+║ 再次查看本教学: help
+╚═══════════════════════════════════════════════"""
+
+# Shell fragment executed via `bash -c`. NOTE: kept POSIX-simple on purpose —
+# it runs before any profile, on the image's stock bash.
+_SESSION_BASH_PRELUDE_TEMPLATE = """\
+__aisc_tutorial() {
+  cat <<'__AISC_TUTORIAL_EOF__'
+__AISC_TUTORIAL_TEXT__
+__AISC_TUTORIAL_EOF__
+}
+help() {
+  if [ $# -eq 0 ]; then
+    __aisc_tutorial
+  else
+    builtin help "$@"
+  fi
+}
+export -f help __aisc_tutorial
+exec bash
+"""
+
+
+def session_bash_prelude() -> str:
+    """The ``bash -c`` script for interactive session opens (test seam)."""
+    # Plain replace — .format would need every shell brace escaped.
+    return _SESSION_BASH_PRELUDE_TEMPLATE.replace("__AISC_TUTORIAL_TEXT__", _TUTORIAL)
+
+
+_FUNC_BODY = """\
+  if [ $# -eq 0 ]; then
+    cat <<'__AISC_TUTORIAL_EOF__'
+{tutorial}
+__AISC_TUTORIAL_EOF__
+  else
+    builtin help "$@"
+  fi
+"""
+
+
+def help_function_env() -> Dict[str, str]:
+    """The exported-function env var for bash session opens.
+
+    bash re-imports ``BASH_FUNC_<name>%%`` env vars as functions at startup;
+    the wrapper's ``os.environ.copy()`` passes the docker-exec environment
+    straight through, so the function enters ONLY this session's shell (no
+    image, profile, or workspace writes — A-21766). ``help <args>`` delegates
+    to the builtin (A-21765).
+    """
+    body = _FUNC_BODY.replace("{tutorial}", _TUTORIAL)
+    return {"BASH_FUNC_help%%": f"() {{\n{body}}}"}
+

aisc/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain package — pure data models, no I/O."""

aisc/domain/artifacts.py

@@ -0,0 +1,279 @@
+"""Agent Artifact domain model and path policy (Stage 3, ART-01).
+
+The authoritative fact layer for Agent deliverables: ``aisc.artifact/v1``.
+Deliberately SEPARATE from ``packaging/artifact.py`` (release bundle builder) —
+different schema, different namespace, different module. See
+docs/archive/completed/aisc-next/stage-3-workspace-artifacts/.
+
+Invariants (D3-01..D3-08):
+- Skill provides semantics (title/category/open suggestion), not facts.
+- Only ``aisc artifact record`` writes an authoritative record (provenance
+  ``manifest``). The watcher is a read model, never a fact writer.
+- Agents submit workspace-relative paths; host absolute resolution is the
+  Rust side's job after canonical containment.
+- ``extra`` is free-form but must not carry secrets.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Any, Dict, Optional
+
+ARTIFACT_PROTOCOL = "aisc.artifact/v1"
+ARTIFACT_SCHEMA_VERSION = 1
+
+# UUID v4-ish (structural check; the CLI generates real UUIDs).
+_ARTIFACT_ID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+# Control characters / separators never allowed in a relative path.
+_FORBIDDEN = re.compile(r"[\x00-\x1f\x7f]")
+_WINDOWS_RESERVED = re.compile(
+    r"(?i)^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)"
+)
+
+
+class ArtifactAction:
+    CREATED = "created"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    RENAMED = "renamed"
+    ALL = (CREATED, MODIFIED, DELETED, RENAMED)
+
+
+class ArtifactKind:
+    DELIVERABLE = "deliverable"
+    SOURCE_CHANGE = "source_change"
+    GENERATED_OUTPUT = "generated_output"
+    ALL = (DELIVERABLE, SOURCE_CHANGE, GENERATED_OUTPUT)
+
+
+class ArtifactState:
+    PRESENT = "present"
+    DELETED = "deleted"
+    MOVED = "moved"
+    MISSING = "missing"
+    ALL = (PRESENT, DELETED, MOVED, MISSING)
+
+
+class ArtifactOpenWith:
+    PREVIEW = "preview"
+    SYSTEM = "system"
+    REVEAL = "reveal"
+    NONE = "none"
+    ALL = (PREVIEW, SYSTEM, REVEAL, NONE)
+
+
+class ArtifactProvenance:
+    MANIFEST = "manifest"  # authoritative: written by `aisc artifact record`
+    WORKSPACE_CHANGE = "workspace_change"  # read model: watcher only
+
+
+def validate_relative_path(raw: str) -> str:
+    """Validate a workspace-relative path and return it normalized (POSIX).
+
+    Rejects (A-ART05-* / R3-01):
+    - empty or whitespace-only paths;
+    - absolute paths (leading ``/``), Windows drive/UNC/root prefixes;
+    - NUL and other control characters;
+    - ``..`` traversal (any position);
+    - backslash separators (``\\`` on Windows; cross-platform we reject them so
+      a path written on one OS cannot silently mean something else on another);
+    - Windows reserved device names (CON, NUL, …).
+
+    Returns the normalized forward-slash path. Raises ValueError on violation.
+    """
+    if not raw or not raw.strip():
+        raise ValueError("artifact path must not be empty")
+
+    if _FORBIDDEN.search(raw):
+        raise ValueError("artifact path contains control characters")
+
+    # Backslashes: on POSIX they are legal filename bytes but ambiguous here;
+    # reject to keep identity consistent across OSes (Windows is the strict one).
+    if "\\" in raw:
+        raise ValueError("artifact path must use '/' separators, not '\\'")
+
+    if raw.startswith("/"):
+        raise ValueError("artifact path must be relative (no leading '/')")
+
+    # Windows drive / UNC / rooted prefixes (also caught by PurePosixPath but
+    # be explicit for clear error messages).
+    if re.match(r"^[A-Za-z]:", raw):
+        raise ValueError("artifact path must be relative (no drive prefix)")
+    if raw.startswith("//") or raw.startswith("\\\\"):
+        raise ValueError("artifact path must be relative (no UNC prefix)")
+
+    # Normalize via PurePosixPath (does NOT touch the filesystem; rejects
+    # '..' traversal and collapses '.', keeps 'a//b' -> 'a/b').
+    try:
+        pp = PurePosixPath(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid artifact path: {exc}") from exc
+
+    if not pp.parts or pp.parts[0] in ("", "/"):
+        raise ValueError("artifact path must be relative")
+
+    if ".." in pp.parts:
+        raise ValueError("artifact path must not contain '..'")
+
+    if "." == raw:
+        raise ValueError("artifact path must point to a file")
+
+    first = pp.parts[0]
+    if _WINDOWS_RESERVED.match(first):
+        raise ValueError(f"artifact path uses reserved device name: {first}")
+
+    return str(pp)
+
+
+def validate_artifact_id(artifact_id: str) -> str:
+    """Validate a UUID-v4-shaped artifact id (structural, not version-4 bits)."""
+    if not _ARTIFACT_ID_RE.match(artifact_id):
+        raise ValueError("artifact_id must be a UUID")
+    return artifact_id.lower()
+
+
+def workspace_hash(workspace: Path) -> str:
+    """Irreversible short hash of a canonical workspace path (for registry
+    keying; never records the raw path)."""
+    canon = str(workspace.resolve())
+    return hashlib.sha256(canon.encode("utf-8")).hexdigest()[:16]
+
+
+def normalize_media_type(raw: Optional[str]) -> Optional[str]:
+    """Validate/normalize a media type, or None when absent."""
+    if raw is None:
+        return None
+    mt = raw.strip().lower()
+    if not mt or "/" not in mt or len(mt) > 127:
+        raise ValueError("media_type must be 'type/subtype' (<=127 chars)")
+    return mt
+
+
+@dataclass(frozen=True)
+class ArtifactRecord:
+    """One authoritative artifact fact (aisc.artifact/v1)."""
+
+    schema_version: int = ARTIFACT_SCHEMA_VERSION
+    artifact_id: str = ""
+    workspace_relative_path: str = ""
+    action: str = ArtifactAction.CREATED
+    kind: str = ArtifactKind.DELIVERABLE
+    media_type: Optional[str] = None
+    label: str = ""
+    open_with: str = ArtifactOpenWith.PREVIEW
+    producer: Dict[str, Any] = field(default_factory=dict)
+    state: str = ArtifactState.PRESENT
+    provenance: str = ArtifactProvenance.MANIFEST
+    recorded_at: str = ""
+    previous_path: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    # -- construction / validation ---------------------------------------
+
+    def validate(self) -> "ArtifactRecord":
+        """Validate all fields; returns self (or raises ValueError)."""
+        validate_artifact_id(self.artifact_id)
+        validate_relative_path(self.workspace_relative_path)
+        if self.action not in ArtifactAction.ALL:
+            raise ValueError(f"invalid action: {self.action!r}")
+        if self.action == ArtifactAction.RENAMED:
+            if not self.previous_path:
+                raise ValueError("renamed action requires previous_path")
+            validate_relative_path(self.previous_path)
+        if self.kind not in ArtifactKind.ALL:
+            raise ValueError(f"invalid kind: {self.kind!r}")
+        if self.state not in ArtifactState.ALL:
+            raise ValueError(f"invalid state: {self.state!r}")
+        if self.open_with not in ArtifactOpenWith.ALL:
+            raise ValueError(f"invalid open_with: {self.open_with!r}")
+        if self.provenance != ArtifactProvenance.MANIFEST:
+            # The CLI only ever writes authoritative manifest facts. A watcher
+            # read model is a separate projection, never stored as manifest.
+            raise ValueError(
+                f"provenance must be {ArtifactProvenance.MANIFEST!r}"
+            )
+        if self.schema_version != ARTIFACT_SCHEMA_VERSION:
+            raise ValueError(
+                f"unsupported schema_version: {self.schema_version}"
+            )
+        # producer: agent/session_id/runtime_id are required; never secrets.
+        agent = self.producer.get("agent")
+        if not agent or agent not in ("claude", "codex", "bash", "cc-switch"):
+            raise ValueError(f"producer.agent must be one of claude/codex/bash/cc-switch")
+        if not self.producer.get("session_id"):
+            raise ValueError("producer.session_id is required")
+        if not self.producer.get("runtime_id"):
+            raise ValueError("producer.runtime_id is required")
+        if self.label and len(self.label) > 256:
+            raise ValueError("label must be <= 256 chars")
+        if self.media_type:
+            normalize_media_type(self.media_type)
+        return self
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "schema_version": self.schema_version,
+            "artifact_id": self.artifact_id,
+            "workspace_relative_path": self.workspace_relative_path,
+            "action": self.action,
+            "kind": self.kind,
+            "state": self.state,
+            "provenance": self.provenance,
+            "recorded_at": self.recorded_at,
+            "extra": dict(self.extra),
+        }
+        if self.media_type is not None:
+            d["media_type"] = self.media_type
+        if self.label:
+            d["label"] = self.label
+        if self.open_with != ArtifactOpenWith.PREVIEW:
+            d["open_with"] = self.open_with
+        if self.previous_path is not None:
+            d["previous_path"] = self.previous_path
+        d["producer"] = dict(self.producer)
+        return d
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "ArtifactRecord":
+        """Build + validate from a dict; unknown fields are preserved in
+        ``extra`` (round-trip safe, A-ART01-1)."""
+        if not isinstance(raw, dict):
+            raise ValueError("artifact record must be a JSON object")
+        schema_version = raw.get("schema_version", ARTIFACT_SCHEMA_VERSION)
+        if schema_version != ARTIFACT_SCHEMA_VERSION:
+            raise ValueError(f"unsupported schema_version: {schema_version}")
+        known = {
+            "schema_version", "artifact_id", "workspace_relative_path",
+            "action", "kind", "media_type", "label", "open_with",
+            "producer", "state", "provenance", "recorded_at",
+            "previous_path", "extra",
+        }
+        extra = dict(raw.get("extra") or {})
+        for k, v in raw.items():
+            if k not in known:
+                extra[k] = v  # preserve unknown fields on round-trip
+        rec = cls(
+            schema_version=schema_version,
+            artifact_id=raw.get("artifact_id", ""),
+            workspace_relative_path=raw.get("workspace_relative_path", ""),
+            action=raw.get("action", ArtifactAction.CREATED),
+            kind=raw.get("kind", ArtifactKind.DELIVERABLE),
+            media_type=raw.get("media_type"),
+            label=raw.get("label", ""),
+            open_with=raw.get("open_with", ArtifactOpenWith.PREVIEW),
+            producer=dict(raw.get("producer") or {}),
+            state=raw.get("state", ArtifactState.PRESENT),
+            provenance=raw.get("provenance", ArtifactProvenance.MANIFEST),
+            recorded_at=raw.get("recorded_at", ""),
+            previous_path=raw.get("previous_path"),
+            extra=extra,
+        )
+        return rec.validate()