datex-studio-cli 0.5.1__tar.gz → 0.5.2__tar.gz

{datex_studio_cli-0.5.1 → datex_studio_cli-0.5.2}/.github/workflows/ci.yml

@@ -59,3 +59,32 @@ jobs:
       - run: uv run ruff check quartermaster
       - run: uv run --package quartermaster mypy quartermaster/src/quartermaster
       - run: uv run --package quartermaster pytest quartermaster/tests -q
+
+  # The artifact nobody was looking at. 0.5.0 and 0.5.1 both shipped without
+  # dxs.core.quartermaster and dxs.core.skills, and 0.5.1 could not run
+  # `dxs --version` at all -- while this suite was fully green, because tests
+  # import from the source tree and never open the wheel. release.yml calls
+  # this workflow, so a broken artifact now blocks the release too.
+  package:
+    runs-on: arc-dxs
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          cache-suffix: package
+          download-from-astral-mirror: false
+      - run: uv python install 3.13
+      - run: uv build
+      - name: Every package under src/ must be in the wheel
+        run: uv run python scripts/check_wheel_completeness.py
+      - name: The built wheel must actually run
+        run: |
+          # A clean venv, not the workspace: importing from the source tree is
+          # exactly what hid this. Resolve deps from the index like a user does.
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke/bin/python dist/*.whl
+          /tmp/smoke/bin/dxs --version
+          /tmp/smoke/bin/dxs skills --help > /dev/null
+          /tmp/smoke/bin/python -c "import dxs.core.quartermaster, dxs.core.skills"

{datex_studio_cli-0.5.1 → datex_studio_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datex-studio-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI for Datex Studio low-code platform, designed for LLM-based AI agents
 Project-URL: Homepage, https://github.com/datex/datex-studio-cli
 Project-URL: Documentation, https://github.com/datex/datex-studio-cli

{datex_studio_cli-0.5.1 → datex_studio_cli-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datex-studio-cli"
-version = "0.5.1"
+version = "0.5.2"
 description = "CLI for Datex Studio low-code platform, designed for LLM-based AI agents"
 readme = "README.md"
 license = "MIT"
@@ -94,7 +94,7 @@ exclude = [
     "documentation/",
     "exploration/",
     "exclude/",
-    "skills/",
+    "/skills/",
     "tests/",
     "publish.sh",
     "*.analysis.md",
@@ -102,7 +102,7 @@ exclude = [
     "uv.lock",
     "src/dxs/web/frontend/",
     "example-reports/",
-    "quartermaster/",
+    "/quartermaster/",
 ]
 
 [tool.uv.workspace]

datex_studio_cli-0.5.2/scripts/check_wheel_completeness.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+"""Assert the built wheel carries every package that exists under src/dxs.
+
+Versions 0.5.0 and 0.5.1 both shipped without ``dxs.core.quartermaster`` and
+``dxs.core.skills``. The sdist exclude list named ``skills/`` and
+``quartermaster/`` to drop the top-level directories of those names; hatchling
+matches an unanchored pattern at any depth, so it dropped the nested packages
+too, and ``uv build`` builds the wheel from the sdist it just made. 0.5.1 could
+not even run ``dxs --version``.
+
+A full green suite said nothing about any of it: tests import from the source
+tree and never open the artifact. This looks at the artifact.
+
+Usage: check_wheel_completeness.py [dist_dir]
+"""
+
+from __future__ import annotations
+
+import sys
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / "src"
+
+
+def main() -> int:
+    dist = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT / "dist"
+    wheels = sorted(dist.glob("*.whl"))
+    if not wheels:
+        print(f"no wheel in {dist} — run `uv build` first", file=sys.stderr)
+        return 1
+    wheel = wheels[-1]
+
+    # Every directory holding an __init__.py is a package that must ship.
+    expected = {
+        p.parent.relative_to(SRC).as_posix() for p in SRC.rglob("__init__.py")
+        if "__pycache__" not in p.parts
+    }
+    names = zipfile.ZipFile(wheel).namelist()
+    shipped = {n.rsplit("/", 1)[0] for n in names if n.endswith("/__init__.py")}
+
+    missing = sorted(expected - shipped)
+    if missing:
+        print(f"{wheel.name} is missing {len(missing)} package(s) present in src/:",
+              file=sys.stderr)
+        for m in missing:
+            print(f"  {m}", file=sys.stderr)
+        print("\nUsually an unanchored exclude pattern in pyproject.toml matching a "
+              "nested path — anchor it with a leading slash.", file=sys.stderr)
+        return 1
+
+    print(f"{wheel.name}: all {len(expected)} packages present")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{datex_studio_cli-0.5.1 → datex_studio_cli-0.5.2}/src/dxs/__init__.py

@@ -1,4 +1,4 @@
 """Datex Studio CLI - Command-line interface for Datex Studio platform."""
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 __app_name__ = "dxs"

datex_studio_cli-0.5.2/src/dxs/core/quartermaster/__init__.py

@@ -0,0 +1,5 @@
+"""Quartermaster companion-service client (spec §10, §16)."""
+
+from dxs.core.quartermaster.client import QuartermasterClient, QuartermasterError
+
+__all__ = ["QuartermasterClient", "QuartermasterError"]

datex_studio_cli-0.5.2/src/dxs/core/quartermaster/client.py

@@ -0,0 +1,178 @@
+"""The shared Quartermaster HTTP helper for interactive families (spec §16).
+
+House rules it enforces so every family inherits them:
+
+- ``User-Agent: dxs-cli/{__version__}`` on every request — the per-version
+  traffic view the sunset rule reads.
+- A bare 404 on a family route means the service predates the CLI: mapped to
+  a plain "doesn't serve {family}/{segment}" error. A 404 *with* the
+  structured ``{"error": {...}}`` body is the family's own answer and is
+  surfaced as-is.
+- Tolerant reader: unknown response fields are ignored; genuine failures
+  surface the service's machine-readable code — fail loud, never guess.
+
+Telemetry does not use this helper (fire-and-forget, frozen sender).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import httpx
+
+from dxs import __version__
+from dxs.core.auth.decorators import get_access_token
+from dxs.utils.config import get_settings
+from dxs.utils.errors import AuthenticationError, DxsError
+
+_FAMILY_ROUTE = re.compile(r"^/(?P<family>[a-z][a-z0-9_-]*)/(?P<segment>v\d+)(?:/|$)")
+
+
+class QuartermasterError(DxsError):
+    """A Quartermaster request failed; ``service_code`` carries the structured code, if any."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "DXS-QM-003",
+        *,
+        service_code: str | None = None,
+        status_code: int | None = None,
+        suggestions: list[str] | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        details = dict(details or {})
+        if service_code is not None:
+            details["service_code"] = service_code
+        if status_code is not None:
+            details["status_code"] = status_code
+        super().__init__(code=code, message=message, details=details, suggestions=suggestions)
+        self.service_code = service_code
+        self.status_code = status_code
+
+
+def _family_and_segment(path: str) -> str:
+    match = _FAMILY_ROUTE.match(path)
+    if match is None:
+        return path
+    return f"{match.group('family')}/{match.group('segment')}"
+
+
+def _structured_error(response: httpx.Response) -> dict[str, Any] | None:
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    error = body.get("error") if isinstance(body, dict) else None
+    return error if isinstance(error, dict) else None
+
+
+class QuartermasterClient:
+    def __init__(self, base_url: str | None = None, timeout: float = 30.0) -> None:
+        resolved = base_url if base_url is not None else get_settings().quartermaster_base_url
+        if not resolved:
+            raise QuartermasterError(
+                "Quartermaster base URL is not configured",
+                code="DXS-QM-001",
+                suggestions=[
+                    "Set DXS_QUARTERMASTER_BASE_URL, or quartermaster_base_url in "
+                    "~/.datex/config.yaml",
+                ],
+            )
+        self.base_url = resolved.rstrip("/")
+        self._timeout = timeout
+        self._client: httpx.Client | None = None
+
+    # -- lifecycle -------------------------------------------------------
+
+    def _http(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                timeout=self._timeout,
+                verify=get_settings().verify_ssl,
+                headers={"User-Agent": f"dxs-cli/{__version__}"},
+            )
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> QuartermasterClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # -- requests --------------------------------------------------------
+
+    def _request(self, path: str, params: dict[str, Any] | None, accept: str) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {get_access_token()}", "Accept": accept}
+        try:
+            response = self._http().get(path, params=params, headers=headers)
+        except httpx.HTTPError as exc:
+            raise QuartermasterError(
+                f"Could not reach Quartermaster at {self.base_url}: {exc}",
+                code="DXS-QM-004",
+                suggestions=[
+                    "Check your network connection",
+                    "If you point at a staging or local instance, verify "
+                    "DXS_QUARTERMASTER_BASE_URL",
+                ],
+            ) from exc
+        self._raise_for_status(path, response)
+        return response
+
+    def _raise_for_status(self, path: str, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        status = response.status_code
+        if status == 401:
+            raise AuthenticationError(
+                message="Quartermaster rejected the access token",
+                code="DXS-AUTH-001",
+                suggestions=["Run 'dxs auth login' to refresh your session"],
+            )
+        error = _structured_error(response)
+        if error is not None:
+            message = str(error.get("message") or f"Quartermaster returned {status}")
+            extra = {k: v for k, v in error.items() if k not in ("code", "message")}
+            raise QuartermasterError(
+                message,
+                service_code=str(error.get("code")) if error.get("code") else None,
+                status_code=status,
+                details=extra or None,
+            )
+        if status == 404:
+            route = _family_and_segment(path)
+            raise QuartermasterError(
+                f"Quartermaster at {self.base_url} doesn't serve {route} — "
+                "the service may be older than your CLI",
+                code="DXS-QM-002",
+                status_code=status,
+                suggestions=[
+                    "Check DXS_QUARTERMASTER_BASE_URL points at a current Quartermaster",
+                ],
+            )
+        raise QuartermasterError(
+            f"Quartermaster returned HTTP {status} for {path}",
+            status_code=status,
+        )
+
+    def get_json(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = self._request(path, params, "application/json")
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise QuartermasterError(
+                f"Quartermaster returned a non-JSON body for {path}", status_code=200
+            ) from exc
+
+    def get_bytes(
+        self, path: str, params: dict[str, Any] | None = None
+    ) -> tuple[bytes, dict[str, str]]:
+        response = self._request(path, params, "application/gzip, application/json")
+        return response.content, {k.lower(): v for k, v in response.headers.items()}

datex_studio_cli-0.5.2/src/dxs/core/skills/__init__.py

@@ -0,0 +1 @@
+"""Skill management (``dxs skills``, issue #95): layout, lockfile, installer, resolver."""

datex_studio_cli-0.5.2/src/dxs/core/skills/frontmatter.py

@@ -0,0 +1,30 @@
+"""Read a skill's frontmatter from an installed copy (offline ``remove``/``doctor``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def parse_frontmatter(text: str) -> dict[str, Any]:
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    try:
+        doc = yaml.safe_load(text[3:end])
+    except yaml.YAMLError:
+        return {}
+    return doc if isinstance(doc, dict) else {}
+
+
+def installed_depends(skill_dir: Path) -> list[str]:
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.is_file():
+        return []
+    meta = parse_frontmatter(skill_md.read_text(encoding="utf-8", errors="replace"))
+    raw = meta.get("depends") or []
+    return [str(d) for d in raw] if isinstance(raw, list) else []

datex_studio_cli-0.5.2/src/dxs/core/skills/installer.py

@@ -0,0 +1,148 @@
+"""Write a skill bundle into a layout and link it into agent directories.
+
+Safety: the tarball is extracted into a scratch directory first — an entry
+that escapes it (``..``, absolute path, link) aborts before anything under
+the layout is touched. Each skill's canonical directory is then replaced
+wholesale, so files removed upstream do not linger.
+
+Agent directories: an existing symlink is repointed (an ``npx skills``
+install adopted in place); a real directory is left alone and reported as a
+conflict unless ``force``. Where symlinks are not permitted (Windows without
+developer mode) the canonical copy is copied instead, and the lock records
+``linkMode: copy`` so ``remove`` knows to delete rather than unlink.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import shutil
+import tarfile
+import tempfile
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from dxs.utils.errors import DxsError
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    name: str
+    link_mode: str
+    conflicts: tuple[str, ...]
+
+
+def _unsafe(message: str) -> DxsError:
+    return DxsError(
+        code="DXS-SKILLS-004",
+        message=f"Refusing to install skills bundle: {message}",
+        suggestions=["Report this — the bundle Quartermaster served was malformed"],
+    )
+
+
+def _extract(bundle: bytes, scratch: Path) -> list[str]:
+    scratch_resolved = scratch.resolve()
+    order: dict[str, None] = {}
+    try:
+        with tarfile.open(fileobj=io.BytesIO(bundle), mode="r:gz") as tar:
+            for member in tar.getmembers():
+                order.setdefault(member.name.split("/", 1)[0], None)
+                if member.issym() or member.islnk():
+                    raise _unsafe(f"archive contains a link: {member.name}")
+                if os.path.isabs(member.name):
+                    raise _unsafe(f"archive entry is absolute: {member.name}")
+                target = (scratch_resolved / member.name).resolve()
+                if target != scratch_resolved and scratch_resolved not in target.parents:
+                    raise _unsafe(f"archive entry escapes the bundle: {member.name}")
+                if not member.isdir() and not member.isfile():
+                    raise _unsafe(f"archive entry has an unsupported type: {member.name}")
+            tar.extractall(scratch_resolved)  # noqa: S202 - members were checked above
+    except tarfile.TarError as exc:
+        raise _unsafe(f"corrupt archive ({exc})") from exc
+    # Order of first appearance == the order the service packed them == request order.
+    return [name for name in order if (scratch_resolved / name).is_dir()]
+
+
+def _replace_dir(src: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.is_symlink() or dest.is_file():
+        dest.unlink()
+    elif dest.is_dir():
+        shutil.rmtree(dest)
+    shutil.move(str(src), str(dest))
+
+
+def _link(canonical: Path, target: Path, *, force: bool) -> tuple[str, bool]:
+    """Point ``target`` at ``canonical``. Returns ``(link_mode, conflicted)``."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.is_symlink():
+        target.unlink()
+    elif target.exists():
+        if not force:
+            return "symlink", True
+        shutil.rmtree(target) if target.is_dir() else target.unlink()
+    try:
+        os.symlink(canonical, target, target_is_directory=True)
+        return "symlink", False
+    except (OSError, NotImplementedError):
+        shutil.copytree(canonical, target)
+        return "copy", False
+
+
+def install_bundle(
+    bundle: bytes,
+    layout: object,
+    agents: Iterable[str],
+    *,
+    force: bool = False,
+) -> list[InstallResult]:
+    from dxs.core.skills.layout import Layout
+
+    assert isinstance(layout, Layout)
+    agent_list = list(agents)
+    results: list[InstallResult] = []
+    with tempfile.TemporaryDirectory(prefix="dxs-skills-") as tmp:
+        scratch = Path(tmp)
+        names = _extract(bundle, scratch)
+        for name in names:
+            canonical = layout.canonical / name
+            _replace_dir(scratch / name, canonical)
+            link_mode = "symlink"
+            conflicts: list[str] = []
+            for agent in agent_list:
+                mode, conflicted = _link(canonical, layout.agent_dirs[agent] / name, force=force)
+                if conflicted:
+                    conflicts.append(agent)
+                elif mode == "copy":
+                    link_mode = "copy"
+            results.append(
+                InstallResult(name=name, link_mode=link_mode, conflicts=tuple(conflicts))
+            )
+    return results
+
+
+def remove_skill(name: str, layout: object, agents: Iterable[str], link_mode: str) -> bool:
+    """Delete a skill's canonical copy and the agent entries that belong to it."""
+    from dxs.core.skills.layout import Layout
+
+    assert isinstance(layout, Layout)
+    canonical = layout.canonical / name
+    removed = False
+    for agent in agents:
+        target = layout.agent_dirs[agent] / name
+        if target.is_symlink():
+            try:
+                points_at_us = target.resolve() == canonical.resolve()
+            except OSError:
+                points_at_us = False
+            if points_at_us or not canonical.exists():
+                target.unlink()
+                removed = True
+        elif link_mode == "copy" and target.is_dir():
+            shutil.rmtree(target)
+            removed = True
+    if canonical.is_dir():
+        shutil.rmtree(canonical)
+        removed = True
+    return removed

datex_studio_cli-0.5.2/src/dxs/core/skills/layout.py

@@ -0,0 +1,57 @@
+"""Where skills live on disk — parity with ``npx skills`` so agents need no change.
+
+Canonical copies sit in ``<root>/.agents/skills/<name>``; each agent directory
+(``.claude/skills``, ``.codex/skills``) gets a symlink to the canonical copy.
+User scope roots at ``~``; project scope at the current working directory.
+Our install record is a ``skills-lock.json`` in the ``npx skills`` shape
+(``~/.datex/skills-lock.json`` for user scope, ``<project>/skills-lock.json``
+for project scope) — see ``lock.py``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+Scope = Literal["user", "project"]
+
+#: Phase 1 targets (issue #95). Phase 2 grows this to the vercel-labs/skills list.
+AGENTS: dict[str, str] = {"claude": ".claude/skills", "codex": ".codex/skills"}
+CANONICAL_DIR = ".agents/skills"
+LOCK_FILE = "skills-lock.json"
+
+
+@dataclass(frozen=True)
+class Layout:
+    scope: Scope
+    root: Path
+    canonical: Path
+    agent_dirs: dict[str, Path]
+    lock_path: Path
+
+
+def user_layout() -> Layout:
+    home = Path.home()
+    return Layout(
+        scope="user",
+        root=home,
+        canonical=home / CANONICAL_DIR,
+        agent_dirs={agent: home / rel for agent, rel in AGENTS.items()},
+        lock_path=home / ".datex" / LOCK_FILE,
+    )
+
+
+def project_layout(root: Path) -> Layout:
+    root = root.resolve()
+    return Layout(
+        scope="project",
+        root=root,
+        canonical=root / CANONICAL_DIR,
+        agent_dirs={agent: root / rel for agent, rel in AGENTS.items()},
+        lock_path=root / LOCK_FILE,
+    )
+
+
+def layout_for(project: bool, cwd: Path | None = None) -> Layout:
+    return project_layout(cwd or Path.cwd()) if project else user_layout()

datex_studio_cli-0.5.2/src/dxs/core/skills/lock.py

@@ -0,0 +1,98 @@
+"""``skills-lock.json`` — the ``npx skills`` lockfile shape, plus what ``dxs`` needs.
+
+Entries ``dxs`` writes carry ``sourceType: "quartermaster"`` and extra keys
+(``ref``, ``commit``, ``cliVersion``, ``installedAt``, ``agents``,
+``linkMode``). Entries written by other installers are preserved verbatim and
+never managed.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SOURCE = "datex/skills"
+SOURCE_TYPE = "quartermaster"
+LOCK_VERSION = 1
+
+
+@dataclass(frozen=True)
+class LockEntry:
+    name: str
+    skill_path: str
+    computed_hash: str
+    ref: str
+    commit: str
+    cli_version: str
+    installed_at: str
+    agents: tuple[str, ...]
+    link_mode: str  # "symlink" | "copy"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": SOURCE,
+            "sourceType": SOURCE_TYPE,
+            "skillPath": self.skill_path,
+            "computedHash": self.computed_hash,
+            "ref": self.ref,
+            "commit": self.commit,
+            "cliVersion": self.cli_version,
+            "installedAt": self.installed_at,
+            "agents": list(self.agents),
+            "linkMode": self.link_mode,
+        }
+
+    @classmethod
+    def from_dict(cls, name: str, raw: dict[str, Any]) -> LockEntry:
+        return cls(
+            name=name,
+            skill_path=str(raw.get("skillPath", "")),
+            computed_hash=str(raw.get("computedHash", "")),
+            ref=str(raw.get("ref", "")),
+            commit=str(raw.get("commit", "")),
+            cli_version=str(raw.get("cliVersion", "")),
+            installed_at=str(raw.get("installedAt", "")),
+            agents=tuple(str(a) for a in raw.get("agents", [])),
+            link_mode=str(raw.get("linkMode", "symlink")),
+        )
+
+
+@dataclass
+class Lock:
+    skills: dict[str, LockEntry] = field(default_factory=dict)
+    foreign: dict[str, Any] = field(default_factory=dict)
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def managed(self) -> dict[str, LockEntry]:
+        return dict(self.skills)
+
+
+def read_lock(path: Path) -> Lock:
+    if not path.is_file():
+        return Lock()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return Lock()
+    if not isinstance(raw, dict):
+        return Lock()
+    lock = Lock(extra={k: v for k, v in raw.items() if k not in ("version", "skills")})
+    entries = raw.get("skills")
+    if isinstance(entries, dict):
+        for name, entry in entries.items():
+            if isinstance(entry, dict) and entry.get("sourceType") == SOURCE_TYPE:
+                lock.skills[name] = LockEntry.from_dict(name, entry)
+            else:
+                lock.foreign[name] = entry
+    return lock
+
+
+def write_lock(path: Path, lock: Lock) -> None:
+    skills: dict[str, Any] = dict(lock.foreign)
+    for name in sorted(lock.skills):
+        skills[name] = lock.skills[name].to_dict()
+    doc: dict[str, Any] = {"version": LOCK_VERSION, **lock.extra, "skills": skills}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(doc, indent=2) + "\n", encoding="utf-8")