procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/_lib/io.py

@@ -0,0 +1,54 @@
+"""JSON I/O contract for tools.
+
+Success:  emit({...})            -> one JSON object to stdout, exit 0
+Failure:  fail("code", "msg")    -> error envelope to stdout, non-zero exit
+Logs:     log(...)                -> stderr only (never pollutes stdout)
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, NoReturn
+
+# Windows terminals default to cp1252. Force UTF-8 so tools can emit
+# non-ASCII (Ryver messages, calendar titles, names) without mojibake.
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+except (AttributeError, ValueError):
+    pass
+
+
+def emit(data: dict[str, Any]) -> NoReturn:
+    """Print one JSON object to stdout and exit 0."""
+    json.dump(data, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+def fail(
+    code: str,
+    message: str,
+    details: dict[str, Any] | None = None,
+    exit_code: int = 1,
+) -> NoReturn:
+    """Print error envelope to stdout and exit non-zero."""
+    json.dump(
+        {"error": {"code": code, "message": message, "details": details or {}}},
+        sys.stdout,
+        ensure_ascii=False,
+    )
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    sys.exit(exit_code)
+
+
+def log(*args: Any) -> None:
+    """Write to stderr. Use for progress, debug, anything non-JSON."""
+    print(*args, file=sys.stderr, flush=True)
+
+
+def read_stdin_json() -> dict[str, Any]:
+    """For tools that accept JSON on stdin instead of CLI args."""
+    return json.load(sys.stdin)

procesio_cli/tools/_lib/manifest.py

@@ -0,0 +1,297 @@
+"""Tool and agent manifest loading + validation."""
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ArgSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    name: str
+    type: Literal["string", "integer", "number", "boolean", "array", "object"] = "string"
+    required: bool = False
+    description: str = ""
+    default: Any = None
+    # JSON Schema for an arg that carries a STRUCTURED payload (a config, a DTO). A
+    # one-line `help=` can say an arg takes "a JSON object" but not what has to be in
+    # it, so a caller that only has the manifest has to reverse-engineer the shape from
+    # validation errors, one layer per attempt. Populate it from the schema the tool
+    # already validates against, never a hand-written copy, so the two cannot drift.
+    # Aliased: the manifest key stays `schema`, but a field literally named `schema`
+    # shadows BaseModel.schema() and pydantic warns on every import.
+    json_schema: dict | None = Field(default=None, alias="schema")
+
+
+class SecretSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str = ""
+    optional: bool = False
+    """True when the tool works without this secret and only one branch of it
+    needs the value. Such a secret must not count against readiness: showing a
+    fully working tool as red teaches people to ignore the colour, and the next
+    genuinely missing credential reads the same as this one. The dashboard and
+    `list-tools` still surface it, as an optional extra rather than a blocker."""
+
+
+class RoutingSpec(BaseModel):
+    """Optional request-routing hint, consumed by scripts/build-router.py to
+    build the Capability Router in CLAUDE.md. Lets a tool declare, in its own
+    manifest (the source of truth), the natural-language asks that should map to
+    it and the action to reach for first. When absent, the router falls back to
+    the tool description and a heuristic primary action."""
+    model_config = ConfigDict(extra="forbid")
+
+    triggers: list[str] = Field(default_factory=list)
+    primary_action: str = ""
+    example: str = ""
+
+
+class HealthcheckSpec(BaseModel):
+    """Optional live-credential probe, consumed by the dashboard's validation
+    layer (and any 'is this actually connected' check). Declares a cheap,
+    read-only, side-effect-free call whose success proves the stored credential
+    is currently authorized - not merely present in Credential Manager.
+
+    - `action`: the action name to invoke on a dispatch tool. Empty for a flat
+      tool (the tool is run with no action positional).
+    - `args`: arg-name -> value, forwarded as `--name value` to the tool.
+    - `label`: optional human label for what the probe does (e.g. 'list 1 user').
+
+    When absent, the dashboard falls back to the tool's own `auth-status` action
+    (a soft convention), then to presence-only. MUST be read-only: it runs
+    unattended on every dashboard load."""
+    model_config = ConfigDict(extra="forbid")
+
+    action: str = ""
+    args: dict[str, Any] = Field(default_factory=dict)
+    label: str = ""
+
+
+class WebSessionSpec(BaseModel):
+    """Declares that a tool works by driving a saved browser login (the `web`
+    tool's session) rather than an API credential. Lets the dashboard show a
+    per-tool 'Connect login' button prefilled with the right name/URL, and count
+    a missing session as 'needs setup' - so a colleague never has to guess a
+    session name or login URL.
+
+    - `name`: the session name the tool opens (matches `web save-session --name`).
+    - `login_url`: the URL to open for the human to log in.
+    - `persistent`: capture a persistent profile (IndexedDB-auth sites, e.g.
+      WhatsApp) instead of a storageState snapshot.
+    - `channel`: a real browser channel ('chrome'/'msedge'), e.g. for Google-SSO.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    login_url: str = ""
+    persistent: bool = False
+    channel: str = ""
+    label: str = ""
+
+
+class RequirementSpec(BaseModel):
+    """Something that must exist ON THE MACHINE - not a Python dependency.
+
+    `uv sync` installs the venv; it does not install a browser engine, a database
+    driver or a codec. Those were previously discovered one incident at a time and
+    then hard-coded into the onboarding brief from memory, which is exactly how a
+    fresh install ends up looking healthy and failing at the user's first real
+    call: `list-tools` reports ready, the test suite passes, and the browser tools
+    die on their first action because the Playwright binary was never downloaded.
+
+    Declaring them makes the gap machine-checkable
+    (`python scripts/check-requirements.py`) instead of remembered.
+
+    - `name`: short id, e.g. `playwright-chromium`, `ffmpeg`, `odbc-sqlserver`.
+    - `kind`: what sort of thing it is (drives how it's presented, not logic).
+    - `why`: what breaks without it - written for the person reading the failure.
+    - `check`: a cheap shell command that exits 0 when the thing is present.
+    - `install`: how to get it (a winget id, a documented command).
+    - `auto`: the tool installs it itself on first use, so a missing one is a
+      warning rather than a blocker (ffmpeg does this via tools/_lib/ffmpeg.py).
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    kind: Literal["binary", "browser", "driver", "service", "runtime"] = "binary"
+    why: str = ""
+    check: str = ""
+    install: str = ""
+    auto: bool = False
+
+
+class ActionSpec(BaseModel):
+    """One action of a multi-action (dispatch) tool.
+
+    Action-based tools take the action name as the first positional arg;
+    each action has its own arg set. Flat tools use `args` at the top level.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str = ""
+    args: list[ArgSpec] = Field(default_factory=list)
+    output_schema: str = ""
+    examples: list[dict] = Field(default_factory=list)
+
+
+class ToolManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str
+    version: str = "0.1.0"
+    runtime: Literal["python"] = "python"
+    entrypoint: str = "main.py"
+    # Catalog tier for the multi-tenant PROCESIO module (spec P0.0-06 / D11):
+    #   official  - platform-owned, shared, users can't change (IsProcesio)
+    #   template  - a shipped default every workspace starts from, copy-on-write
+    #   custom    - workspace-authored
+    # Default 'template': a shipped tool is a default a workspace may fork. Ignored
+    # entirely by the local single-tenant runtime, so it changes nothing locally.
+    tier: Literal["official", "template", "custom"] = "template"
+    args: list[ArgSpec] = Field(default_factory=list)
+    actions: list[ActionSpec] = Field(default_factory=list)
+    secrets: list[SecretSpec] = Field(default_factory=list)
+    routing: RoutingSpec | None = None
+    healthcheck: HealthcheckSpec | None = None
+    web_session: WebSessionSpec | None = None
+    requires: list[RequirementSpec] = Field(default_factory=list)
+    output_schema: str = ""
+    examples: list[dict] = Field(default_factory=list)
+    # path is filled by the loader; not part of the YAML
+    path: Path | None = None
+
+    def is_action_based(self) -> bool:
+        return len(self.actions) > 0
+
+    def action_names(self) -> list[str]:
+        return [a.name for a in self.actions]
+
+    def get_action(self, name: str) -> ActionSpec | None:
+        for a in self.actions:
+            if a.name == name:
+                return a
+        return None
+
+
+def load_tool(manifest_path: Path) -> ToolManifest:
+    raw = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"{manifest_path}: top-level YAML must be a mapping")
+    m = ToolManifest(**raw)
+    m.path = manifest_path.parent
+    return m
+
+
+class AgentManifest(BaseModel):
+    """Manifest for a registered agent.
+
+    An agent is invoked exactly like an action-dispatch tool (action name as the
+    first positional arg, JSON in / JSON out, secrets via Credential Manager), so
+    it shares ToolManifest's shape. It additionally declares `tools`: the names of
+    registered tools it orchestrates. The runtime resolves those via the registry,
+    never a hardcoded list.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str
+    version: str = "0.1.0"
+    runtime: Literal["python"] = "python"
+    entrypoint: str = "main.py"
+    # Catalog tier (spec P0.0-06 / D11); see ToolManifest.tier. Default 'template'.
+    tier: Literal["official", "template", "custom"] = "template"
+    tools: list[str] = Field(default_factory=list)
+    args: list[ArgSpec] = Field(default_factory=list)
+    actions: list[ActionSpec] = Field(default_factory=list)
+    secrets: list[SecretSpec] = Field(default_factory=list)
+    routing: RoutingSpec | None = None
+    healthcheck: HealthcheckSpec | None = None
+    output_schema: str = ""
+    examples: list[dict] = Field(default_factory=list)
+    # path is filled by the loader; not part of the YAML
+    path: Path | None = None
+
+    def is_action_based(self) -> bool:
+        return len(self.actions) > 0
+
+    def action_names(self) -> list[str]:
+        return [a.name for a in self.actions]
+
+    def get_action(self, name: str) -> ActionSpec | None:
+        for a in self.actions:
+            if a.name == name:
+                return a
+        return None
+
+
+def load_agent(manifest_path: Path) -> AgentManifest:
+    raw = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"{manifest_path}: top-level YAML must be a mapping")
+    m = AgentManifest(**raw)
+    m.path = manifest_path.parent
+    return m
+
+
+class SkillManifest(BaseModel):
+    """Manifest for a registered skill.
+
+    A skill is instruction/reference content (not an executable), so its native
+    `SKILL.md` YAML frontmatter IS its manifest — no separate file, no duplicated
+    metadata. The frontmatter always carries `name` + `description`; it may also
+    carry native keys we don't model (`license`, `allowed-tools`, etc.), so unlike
+    tool/agent manifests this is lenient (`extra="ignore"`) — skills are imported
+    artifacts we keep portable, not author from scratch.
+
+    An optional `routing:` block lets a skill curate its Capability-Router line,
+    exactly like a tool. When absent, the router falls back to the description.
+
+    Skills that opt into the governance discipline also carry `owner`,
+    `last_verified`, `baseline_version`, `eval_suite`, and `source_policy`
+    (the marker `check-skill-governance.py` scopes on). Imported/portable skills
+    omit them and default; `extra="ignore"` keeps any other native key portable.
+    """
+    model_config = ConfigDict(extra="ignore")
+
+    name: str
+    description: str
+    version: str = "0.1.0"
+    tier: Literal["official", "template", "custom"] = "template"
+    routing: RoutingSpec | None = None
+    owner: str = ""
+    last_verified: date | None = None
+    baseline_version: str = ""
+    eval_suite: str = ""
+    source_policy: Literal["generated", "timestamped", "static"] | None = None
+    # path is filled by the loader; not part of the frontmatter
+    path: Path | None = None
+
+
+def _split_frontmatter(text: str) -> dict:
+    """Parse the leading `---`-delimited YAML frontmatter from a SKILL.md body."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("SKILL.md is missing its '---' YAML frontmatter")
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            raw = yaml.safe_load("\n".join(lines[1:i]))
+            if not isinstance(raw, dict):
+                raise ValueError("SKILL.md frontmatter must be a YAML mapping")
+            return raw
+    raise ValueError("SKILL.md frontmatter is not terminated by a closing '---'")
+
+
+def load_skill(skill_md_path: Path) -> SkillManifest:
+    raw = _split_frontmatter(skill_md_path.read_text(encoding="utf-8"))
+    m = SkillManifest(**raw)
+    m.path = skill_md_path.parent
+    return m

procesio_cli/tools/_lib/skill_release.py

@@ -0,0 +1,127 @@
+"""Read-only correspondence check for a Gate 5 commit and current skill bytes.
+
+Historical fingerprints cover the entire committed skills subtree, exactly as the
+series launcher exports it. Live correspondence covers published packages and the
+behavioral/threshold contract, excluding the ledger (which must record new proof).
+This verifies content identity, not the authenticity or quality of a test verdict.
+Release targets must be clean source exports: bytecode/cache artifacts are rejected,
+not silently ignored. Never delete a possibly active developer cache to pass a gate.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+import subprocess
+from pathlib import Path, PurePosixPath
+
+
+EXPERIMENT_FILES = {"evals/behavioral.json", "evals/gate5-thresholds.json"}
+
+
+def _finding(code: str, message: str) -> list[dict[str, str]]:
+    return [{"skill": "<repository>", "code": code, "message": message}]
+
+
+def _git(repo: Path, *args: str) -> bytes:
+    result = subprocess.run(["git", "-C", str(repo), *args], capture_output=True, check=False)
+    if result.returncode:
+        # Git diagnostics may include machine-local paths; never echo raw output.
+        raise ValueError("evaluated Git commit/tree is unavailable")
+    return result.stdout
+
+
+def _norm(data: bytes) -> bytes:
+    """Content, made newline-agnostic. SVN materialises CRLF where Git keeps LF, so
+    a fingerprint over raw bytes reads the same corpus as tampered on one VCS and
+    intact on the other (the recorded values are the LF hashes). Normalise CRLF -> LF
+    for text; leave binary (anything with a NUL) untouched, so a font or image is
+    compared byte-for-byte as before."""
+    return data if b"\x00" in data else data.replace(b"\r\n", b"\n")
+
+
+def _snapshot(repo: Path, commit: str) -> dict[str, bytes]:
+    if _git(repo, "cat-file", "-t", commit).strip() != b"commit":
+        raise ValueError("evaluated identity must be a commit, not a tree or tag")
+    entries = _git(repo, "ls-tree", "-r", "-z", commit, "--", "skills").split(b"\0")
+    files: dict[str, bytes] = {}
+    for entry in filter(None, entries):
+        metadata, raw_path = entry.split(b"\t", 1)
+        mode, kind, oid = metadata.decode("ascii").split()
+        path = PurePosixPath(raw_path.decode("utf-8"))
+        if mode not in {"100644", "100755"} or kind != "blob":
+            raise ValueError("evaluated skills tree contains an unsupported entry")
+        if path.is_absolute() or ".." in path.parts or path.parts[0] != "skills":
+            raise ValueError("evaluated tree contains an unsafe path")
+        files[path.relative_to("skills").as_posix()] = _norm(_git(repo, "cat-file", "blob", oid))
+    if not files:
+        raise ValueError("evaluated skills tree is empty")
+    return files
+
+
+def _digest(files: dict[str, bytes]) -> str:
+    digest = hashlib.sha256()
+    # Match sorted(Path.rglob()) in the frozen series launcher, not raw string
+    # ordering: a directory's children sort before a similarly prefixed sibling.
+    for name in sorted(files, key=PurePosixPath):
+        digest.update(name.encode("utf-8") + b"\0" + files[name] + b"\0")
+    return digest.hexdigest()
+
+
+def _packages(files: dict[str, bytes]) -> set[str]:
+    return {name.split("/")[0] for name in files
+            if len(PurePosixPath(name).parts) == 2 and name.endswith("/SKILL.md")}
+
+
+def _projection(files: dict[str, bytes]) -> dict[str, bytes]:
+    packages = _packages(files)
+    return {name: data for name, data in files.items()
+            if name.split("/")[0] in packages or name in EXPERIMENT_FILES}
+
+
+def _live(root: Path) -> dict[str, bytes]:
+    if root.is_symlink() or not root.is_dir():
+        raise ValueError("current skill root is missing or symlinked")
+    files: dict[str, bytes] = {}
+    for folder in root.iterdir():
+        if folder.is_symlink():
+            raise ValueError("current skills contain a symlinked directory")
+        if not folder.is_dir() or not (folder / "SKILL.md").exists():
+            continue
+        for path in folder.rglob("*"):
+            rel = path.relative_to(root)
+            if path.is_symlink():
+                raise ValueError("current skill package contains a symlink")
+            if "__pycache__" in rel.parts or path.suffix.lower() in {".pyc", ".pyo"}:
+                raise ValueError("release binding requires a clean source export without bytecode")
+            if path.is_file():
+                files[rel.as_posix()] = _norm(path.read_bytes())
+    for name in EXPERIMENT_FILES:
+        path = root / name
+        if path.parent.is_symlink() or path.is_symlink():
+            raise ValueError("current experiment contract contains a symlink")
+        if path.is_file():
+            files[name] = _norm(path.read_bytes())
+    return files
+
+
+def check_release_binding(repo_root: Path, skills_root: Path, commit: object,
+                          fingerprint: object) -> list[dict[str, str]]:
+    if (not isinstance(commit, str) or not re.fullmatch(r"[0-9a-f]{40}", commit)
+            or not isinstance(fingerprint, str)
+            or not re.fullmatch(r"[0-9a-f]{64}", fingerprint)):
+        return _finding("invalid-release-binding", "Gate 5 needs an exact commit and SHA-256 fingerprint")
+    try:
+        frozen = _snapshot(repo_root, commit)
+    except (OSError, ValueError, UnicodeError):
+        return _finding("unavailable-release-snapshot", "Cannot read a safe evaluated skills tree")
+    if _digest(frozen) != fingerprint:
+        return _finding("release-snapshot-mismatch", "Recorded fingerprint does not match evaluated Git tree")
+    try:
+        live = _live(skills_root)
+    except (OSError, ValueError):
+        return _finding("unsafe-release-content", "Require readable source packages without symlinks or bytecode/cache artifacts; use a clean export")
+    expected = _projection(frozen)
+    if not _packages(expected) or _packages(live) != _packages(expected) or live != expected:
+        changed = sum(live.get(name) != expected.get(name) for name in live.keys() | expected.keys())
+        return _finding("release-content-drift", f"Current packages/experiment differ from evaluated content ({changed} paths)")
+    return []

procesio_cli/tools/_lib/skill_resources.py

@@ -0,0 +1,118 @@
+"""Safe indexing and retrieval for bundled Agent Skill resources."""
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+RESOURCE_CATEGORIES = ("references", "scripts", "assets")
+MAX_TEXT_BYTES = 512_000
+
+
+class SkillResourceError(ValueError):
+    code = "invalid_skill_resource"
+
+
+class SkillResourceNotFound(SkillResourceError):
+    code = "skill_resource_not_found"
+
+
+class SkillResourceNotText(SkillResourceError):
+    code = "skill_resource_not_text"
+
+
+def _media_type(path: Path) -> str:
+    guessed, _ = mimetypes.guess_type(path.name)
+    if guessed:
+        return guessed
+    if path.suffix.lower() in {".md", ".markdown"}:
+        return "text/markdown"
+    return "text/plain"
+
+
+def _resource_paths(root: Path, category: str) -> list[Path]:
+    folder = root / category
+    if not folder.is_dir():
+        return []
+    paths: list[Path] = []
+    for path in folder.rglob("*"):
+        if not path.is_file():
+            continue
+        try:
+            resolved = path.resolve(strict=True)
+        except (FileNotFoundError, OSError):
+            continue
+        if root != resolved and root not in resolved.parents:
+            continue
+        paths.append(path)
+    return sorted(paths)
+
+
+def resource_index(root: Path) -> dict[str, Any]:
+    """Return a bounded metadata index without loading resource contents."""
+    root = root.resolve()
+    categories: dict[str, list[str]] = {}
+    resources: list[dict[str, Any]] = []
+    for category in RESOURCE_CATEGORIES:
+        paths = _resource_paths(root, category)
+        rels = [path.relative_to(root).as_posix() for path in paths]
+        categories[category] = rels
+        for path, rel in zip(paths, rels):
+            resources.append({
+                "path": rel,
+                "category": category,
+                "size": path.stat().st_size,
+                "media_type": _media_type(path),
+            })
+    return {**categories, "resources": resources}
+
+
+def _requested_path(requested: str) -> PurePosixPath:
+    value = str(requested or "").strip().replace("\\", "/")
+    if not value:
+        raise SkillResourceError("resource path is required")
+    path = PurePosixPath(value)
+    if path.is_absolute() or ".." in path.parts:
+        raise SkillResourceError("resource path must stay inside the skill")
+    if len(path.parts) < 2 or path.parts[0] not in RESOURCE_CATEGORIES:
+        allowed = ", ".join(f"{item}/" for item in RESOURCE_CATEGORIES)
+        raise SkillResourceError(f"resource path must start with one of: {allowed}")
+    return path
+
+
+def read_text_resource(root: Path, requested: str,
+                       max_bytes: int = MAX_TEXT_BYTES) -> dict[str, Any]:
+    """Read one UTF-8 resource, rejecting traversal, symlink escape, and huge files."""
+    relative = _requested_path(requested)
+    if "\x00" in str(relative):
+        raise SkillResourceError("resource path contains a null byte")
+    try:
+        root_resolved = root.resolve()
+        candidate = root_resolved.joinpath(*relative.parts)
+        resolved = candidate.resolve(strict=True)
+        if root_resolved != resolved and root_resolved not in resolved.parents:
+            raise SkillResourceError("resource resolves outside the skill root")
+        if not resolved.is_file():
+            raise SkillResourceNotFound(f"resource is not a file: {relative.as_posix()}")
+        size = resolved.stat().st_size
+        if size > max_bytes:
+            raise SkillResourceError(
+                f"resource is {size} bytes; maximum retrievable size is {max_bytes}"
+            )
+        content = resolved.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise SkillResourceNotFound(f"resource not found: {relative.as_posix()}") from exc
+    except UnicodeDecodeError as exc:
+        raise SkillResourceNotText(
+            f"resource is not UTF-8 text: {relative.as_posix()}"
+        ) from exc
+    except OSError as exc:
+        # OS messages may contain absolute installation paths; never emit them.
+        raise SkillResourceError("resource could not be read") from exc
+    return {
+        "path": relative.as_posix(),
+        "category": relative.parts[0],
+        "size": size,
+        "media_type": _media_type(resolved),
+        "content": content,
+    }