procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/scripts/build-tool-skill.py

@@ -0,0 +1,202 @@
+"""Generate a per-tool SKILL.md - the agent's instruction manual - from tool.yaml.
+
+WHY
+---
+Borrowed from CLI-Anything, which ships a generated `SKILL.md` beside every CLI so
+an agent can read how to drive it. We had no equivalent: a tool advertises itself
+through one hand-written line in the Capability Router plus a README written for
+humans. That line is enough to CHOOSE a tool and not enough to USE one - the agent
+then falls back to `--help`, which for a big tool costs more context than the task.
+
+The point of generating it is drift: a hand-written manual goes stale the first
+time an action is added, and a stale manual is worse than none because the agent
+trusts it. This one is derived from the manifest, which is already the source of
+truth (Hard rule 3), so it cannot disagree with the code.
+
+Usage:
+  python scripts/build-tool-skill.py <tool> [--out PATH] [--stdout] [--check]
+
+  --check exits 1 if the file on disk differs from what would be generated, so CI
+  or a test can fail on a stale skill instead of shipping one.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+REPO = Path(__file__).resolve().parents[1]
+if str(REPO) not in sys.path:
+    sys.path.insert(0, str(REPO))
+
+from tools._lib import manifest as M  # noqa: E402
+
+MAX_DESC = 160
+
+
+def _group_of(action_name: str) -> str:
+    return action_name.split("-", 1)[0]
+
+
+def _one_line(text: str, limit: int = MAX_DESC) -> str:
+    """First sentence, collapsed - an agent scanning a table needs the verb, not
+    the essay. The full description stays in the manifest."""
+    flat = " ".join((text or "").split())
+    if len(flat) <= limit:
+        return flat
+    cut = flat[:limit].rsplit(" ", 1)[0]
+    return cut + "…"
+
+
+def _required_args(action) -> list[str]:
+    return [a.name for a in action.args if getattr(a, "required", False)]
+
+
+def _frontmatter(name: str, description: str) -> str:
+    """The YAML frontmatter block, emitted through the dumper.
+
+    NOT an f-string. A manifest description is arbitrary prose and routinely
+    contains a colon followed by a space ("full coverage of the Web API: every
+    endpoint is an action"). In a plain YAML scalar that sequence starts a nested
+    mapping, so the document fails to parse and the file stops being a loadable
+    skill - silently, because nothing here reads it back. It held for 36 of 75
+    tools, and the ones it hit were the well-described ones, since description
+    length correlates with punctuation.
+
+    Dumping guarantees the round-trip: whatever punctuation a description carries,
+    yaml.safe_load returns it. width is set high so a long description stays on one
+    line rather than being folded, which keeps the diff readable.
+    """
+    block = yaml.safe_dump(
+        {"name": name, "description": description},
+        sort_keys=False, allow_unicode=True, width=10 ** 9,
+        default_flow_style=False,
+    ).rstrip("\n")
+    return f"---\n{block}\n---"
+
+
+def render(tool: M.ToolManifest) -> str:
+    """The SKILL.md body. Frontmatter first so a skill loader can index it."""
+    actions = list(tool.actions)
+    groups: dict[str, list] = {}
+    for a in actions:
+        groups.setdefault(_group_of(a.name), []).append(a)
+    grouped = len(groups) > 1 and len(actions) > 12
+
+    routing = tool.routing
+    primary = getattr(routing, "primary_action", None) if routing else None
+    example = getattr(routing, "example", None) if routing else None
+
+    out: list[str] = []
+    out.append(_frontmatter(tool.name, _one_line(tool.description, 400)))
+    out.append("")
+    out.append(f"# {tool.name}")
+    out.append("")
+    out.append(" ".join((tool.description or "").split()))
+    out.append("")
+
+    out.append("## How to call it")
+    out.append("")
+    out.append("```bash")
+    out.append(f"python scripts/run-tool.py {tool.name} <action> [--args]")
+    if example:
+        out.append(f"# e.g. {example}")
+    out.append("```")
+    out.append("")
+    out.append("One JSON object on stdout for success; `{\"error\": {\"code\", "
+               "\"message\", \"details\"}}` and a non-zero exit on failure. "
+               "Progress and logs go to stderr only.")
+    out.append("")
+    if primary:
+        out.append(f"**Start with `{primary}`.**")
+        out.append("")
+
+    if tool.secrets:
+        out.append("## Credentials")
+        out.append("")
+        out.append("Stored in the OS credential store, never in files. Missing ones "
+                   "are reported by `python scripts/list-tools.py`.")
+        out.append("")
+        for s in tool.secrets:
+            out.append(f"- `agents-and-tools:{tool.name}:{s.name}`"
+                       + (f" — {_one_line(s.description)}" if s.description else ""))
+        out.append("")
+
+    out.append("## Actions")
+    out.append("")
+    if grouped:
+        for group in sorted(groups):
+            out.append(f"### {group}")
+            out.append("")
+            out.append("| action | required args | what it does |")
+            out.append("|---|---|---|")
+            for a in sorted(groups[group], key=lambda x: x.name):
+                req = ", ".join(f"`--{n}`" for n in _required_args(a)) or "—"
+                out.append(f"| `{a.name}` | {req} | {_one_line(a.description)} |")
+            out.append("")
+    else:
+        out.append("| action | required args | what it does |")
+        out.append("|---|---|---|")
+        for a in sorted(actions, key=lambda x: x.name):
+            req = ", ".join(f"`--{n}`" for n in _required_args(a)) or "—"
+            out.append(f"| `{a.name}` | {req} | {_one_line(a.description)} |")
+        out.append("")
+
+    out.append("---")
+    out.append("")
+    out.append(f"Generated from `tools/{tool.name}/tool.yaml` by "
+               "`scripts/build-tool-skill.py`. Do not edit by hand — change the "
+               "manifest and regenerate.")
+    out.append("")
+    return "\n".join(out)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("tool", help="tool name as it appears in list-tools")
+    p.add_argument("--out", help="output path (default: tools/<tool>/SKILL.md)")
+    p.add_argument("--stdout", action="store_true", help="print instead of writing")
+    p.add_argument("--check", action="store_true",
+                   help="exit 1 if the file on disk is stale")
+    args = p.parse_args()
+
+    # Load by directory, skipping siblings that fail to parse: one broken manifest
+    # elsewhere in tools/ must not stop us generating this tool's skill.
+    tools: dict[str, M.ToolManifest] = {}
+    for manifest_path in sorted((REPO / "tools").glob("*/tool.yaml")):
+        if manifest_path.parent.name.startswith("_"):
+            continue
+        try:
+            m = M.load_tool(manifest_path)
+        except Exception as exc:  # noqa: BLE001
+            if manifest_path.parent.name == args.tool:
+                sys.exit(f"{args.tool}: manifest failed to load: {exc}")
+            continue
+        tools[m.name] = m
+    if args.tool not in tools:
+        sys.exit(f"unknown tool: {args.tool}. Known: {', '.join(sorted(tools))}")
+    tool = tools[args.tool]
+    body = render(tool)
+
+    if args.stdout:
+        print(body)
+        return
+
+    # Write beside the manifest, NOT at tools/<name>/: a manifest name and its
+    # directory can differ (tools/google_mail/ declares name google-mail), so
+    # deriving the path from the name misses every such tool.
+    dest = Path(args.out) if args.out else (tool.path / "SKILL.md")
+    if args.check:
+        current = dest.read_text(encoding="utf-8") if dest.exists() else ""
+        if current != body:
+            sys.exit(f"STALE: {dest} differs from the manifest. Regenerate it.")
+        print(f"up to date: {dest}")
+        return
+    dest.write_text(body, encoding="utf-8", newline="\n")
+    print(f"wrote {dest} ({len(body)} bytes, {len(tool.actions)} actions)")
+
+
+if __name__ == "__main__":
+    main()

procesio_cli/scripts/check-requirements.py

@@ -0,0 +1,131 @@
+"""Check the machine-level prerequisites every tool declares in `requires:`.
+
+`uv sync` builds the venv. It does not install a browser engine, a database driver
+or a codec — and because those are imported lazily, a machine missing them still
+reports every tool "ready" and passes the whole test suite. The failure surfaces
+at the user's first real call, one tool at a time.
+
+This runs each requirement's `check` command and says what is actually missing,
+so a fresh install can be verified in one command instead of by incident.
+
+  python scripts/check-requirements.py            # everything, grouped
+  python scripts/check-requirements.py --tool web
+  python scripts/check-requirements.py --json
+  python scripts/check-requirements.py --quiet     # only what's missing
+
+Exit code: 0 if nothing REQUIRED is missing (self-installing ones are warnings),
+1 otherwise — so it can gate an onboarding run.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+if str(REPO) not in sys.path:
+    sys.path.insert(0, str(REPO))
+
+from tools._lib import manifest as M  # noqa: E402
+
+TIMEOUT = 120
+
+
+def _probe(cmd: str) -> tuple[bool, str]:
+    """Run a check command. Present == exit 0. Never raises.
+
+    `{python}` in a check is replaced with THIS interpreter. A check must not
+    depend on how the shell was started: writing `uv run python -c ...` reported
+    Playwright's browser missing on a machine that had it, because `uv` was not on
+    PATH in that context - a false alarm is as bad as a missed one."""
+    if not cmd:
+        return True, "no check declared"
+    cmd = cmd.replace("{python}", f'"{sys.executable}"')
+    try:
+        p = subprocess.run(cmd, shell=True, cwd=REPO, capture_output=True,
+                           text=True, encoding="utf-8", errors="replace",
+                           timeout=TIMEOUT)
+    except subprocess.TimeoutExpired:
+        return False, f"check timed out after {TIMEOUT}s"
+    except Exception as exc:  # noqa: BLE001
+        return False, f"check could not run: {exc}"
+    if p.returncode == 0:
+        return True, ""
+    tail = ((p.stderr or p.stdout) or "").strip().splitlines()
+    return False, (tail[-1][:160] if tail else f"exit {p.returncode}")
+
+
+def collect(only: str | None = None) -> list[dict]:
+    """One row per (tool, requirement). Requirements are deduplicated per NAME
+    when probing: chromium is the same chromium for all twelve tools that need
+    it, and probing it twelve times just makes the run slow."""
+    rows: list[dict] = []
+    cache: dict[str, tuple[bool, str]] = {}
+    for mp in sorted((REPO / "tools").glob("*/tool.yaml")):
+        if mp.parent.name.startswith("_"):
+            continue
+        try:
+            tool = M.load_tool(mp)
+        except Exception:  # noqa: BLE001 - a broken manifest is list-tools' problem
+            continue
+        if only and tool.name != only:
+            continue
+        for req in tool.requires:
+            if req.name not in cache:
+                cache[req.name] = _probe(req.check)
+            present, detail = cache[req.name]
+            rows.append({
+                "tool": tool.name, "requirement": req.name, "kind": req.kind,
+                "present": present, "auto": req.auto, "detail": detail,
+                "why": req.why.strip(), "install": req.install,
+            })
+    return rows
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--tool", help="check one tool only")
+    p.add_argument("--json", action="store_true", dest="as_json")
+    p.add_argument("--quiet", action="store_true", help="only report what's missing")
+    args = p.parse_args()
+
+    rows = collect(args.tool)
+    if args.as_json:
+        print(json.dumps({"requirements": rows}, indent=1))
+    missing = [r for r in rows if not r["present"]]
+    blocking = [r for r in missing if not r["auto"]]
+
+    if not args.as_json:
+        by_req: dict[str, list[dict]] = {}
+        for r in rows:
+            by_req.setdefault(r["requirement"], []).append(r)
+        for name, group in sorted(by_req.items()):
+            first = group[0]
+            if first["present"] and args.quiet:
+                continue
+            mark = "OK  " if first["present"] else ("WARN" if first["auto"] else "MISS")
+            tools = ", ".join(sorted({g["tool"] for g in group}))
+            print(f"[{mark}] {name} ({first['kind']}) — needed by {len(set(t['tool'] for t in group))} tool(s)")
+            print(f"       {tools}")
+            if not first["present"]:
+                if first["detail"]:
+                    print(f"       check said: {first['detail']}")
+                if first["why"]:
+                    print(f"       why: {' '.join(first['why'].split())}")
+                if first["install"]:
+                    print(f"       install: {first['install']}")
+                if first["auto"]:
+                    print("       (self-installing on first use — warning, not a blocker)")
+            print()
+        if not missing:
+            print("All declared machine requirements are present.")
+        elif blocking:
+            print(f"{len(blocking)} blocking requirement(s) missing.")
+
+    sys.exit(1 if blocking else 0)
+
+
+if __name__ == "__main__":
+    main()

procesio_cli/scripts/check-skill-governance.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Check skill ownership, freshness metadata, evaluation links, and release state."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from tools._lib.manifest import load_skill  # noqa: E402
+from tools._lib.skill_release import check_release_binding  # noqa: E402
+
+DEFAULT_SKILLS = ROOT / "skills"
+DEFAULT_STATUS = DEFAULT_SKILLS / "evals" / "gates.json"
+EXPECTED_GATES = set(range(7))
+
+
+def check_skills(skills_root: Path, *, max_age_days: int | None = None,
+                 today: date | None = None) -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+    now = today or date.today()
+    paths = sorted(skills_root.glob("*/SKILL.md"))
+    if not paths:
+        return [{"skill": "<repository>", "code": "no-skills", "message": "no skills found"}]
+    for skill_md in paths:
+        if skill_md.parent.name.startswith("_") or skill_md.parent.name == "tests":
+            continue
+        try:
+            manifest = load_skill(skill_md)
+        except Exception as exc:  # noqa: BLE001
+            findings.append({"skill": skill_md.parent.name, "code": "invalid-skill",
+                             "message": str(exc)})
+            continue
+        # Governance is opt-in via `source_policy`. A repo like procesio-cli whose
+        # skills/ IS the portfolio governs every skill; a framework like AAT also
+        # hosts imported/portable skills that never signed up for owner/freshness/
+        # eval-suite discipline, and forcing that metadata on them would be wrong.
+        if not manifest.source_policy:
+            continue
+        required = {
+            "owner": manifest.owner,
+            "last_verified": manifest.last_verified,
+            "baseline_version": manifest.baseline_version,
+            "eval_suite": manifest.eval_suite,
+            "source_policy": manifest.source_policy,
+        }
+        for field, value in required.items():
+            if not value:
+                findings.append({
+                    "skill": manifest.name,
+                    "code": f"missing-{field.replace('_', '-')}",
+                    "message": f"{field} is required for published skills",
+                })
+        if not manifest.routing or not manifest.routing.triggers:
+            findings.append({"skill": manifest.name, "code": "missing-routing",
+                             "message": "curated routing triggers are required"})
+        if (max_age_days is not None and manifest.source_policy == "timestamped"
+                and manifest.last_verified is not None):
+            age = (now - manifest.last_verified).days
+            if age < 0:
+                findings.append({"skill": manifest.name, "code": "future-verification-date",
+                                 "message": f"last_verified is {abs(age)} days in the future"})
+            elif age > max_age_days:
+                findings.append({"skill": manifest.name, "code": "stale-timestamped-skill",
+                                 "message": f"last verified {age} days ago; maximum is {max_age_days}"})
+    return findings
+
+
+def check_status(path: Path, *, require_release_eligible: bool = False,
+                 verify_snapshot: bool = False, skills_root: Path = DEFAULT_SKILLS,
+                 repo_root: Path = ROOT) -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+    try:
+        raw: Any = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        return [{"skill": "<repository>", "code": "invalid-gate-status", "message": str(exc)}]
+    rows = raw.get("gates") if isinstance(raw, dict) else None
+    if not isinstance(rows, list):
+        return [{"skill": "<repository>", "code": "invalid-gate-status",
+                 "message": "gates must be a list"}]
+    ids = [row.get("id") for row in rows if isinstance(row, dict)]
+    if (len(rows) != 7 or len(ids) != 7 or any(type(value) is not int for value in ids)
+            or set(ids) != EXPECTED_GATES):
+        return [{"skill": "<repository>", "code": "incomplete-gate-set",
+                 "message": "gate ids must be unique integers 0 through 6"}]
+    if (type(raw.get("release_eligible")) is not bool
+            or not isinstance(raw.get("release_blockers"), list)
+            or not all(isinstance(item, str) for item in raw["release_blockers"])):
+        return [{"skill": "<repository>", "code": "invalid-gate-status",
+                 "message": "release_eligible must be Boolean and release_blockers a string list"}]
+    allowed = {"passed", "pending-external-run", "infrastructure-complete", "blocked"}
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        if not isinstance(row.get("status"), str) or row["status"] not in allowed:
+            findings.append({"skill": "<repository>", "code": "invalid-gate-state",
+                             "message": f"gate {row['id']} has an invalid status"})
+        evidence_paths = row.get("evidence", [])
+        if not isinstance(evidence_paths, list) or not all(isinstance(item, str) for item in evidence_paths):
+            findings.append({"skill": "<repository>", "code": "invalid-gate-evidence",
+                             "message": "gate evidence must be a list of repository-relative paths"})
+            continue
+        for evidence in evidence_paths:
+            rel = PurePosixPath(evidence.replace("\\", "/"))
+            target = repo_root / evidence
+            try:
+                if (not evidence or "\x00" in evidence or len(evidence) > 4096
+                        or rel.is_absolute() or ".." in rel.parts
+                        or not target.resolve().is_relative_to(repo_root.resolve())):
+                    raise ValueError("unsafe evidence path")
+                if not target.is_file():
+                    findings.append({"skill": "<repository>", "code": "missing-gate-evidence",
+                                     "message": f"gate {row['id']} evidence file is missing"})
+            except (OSError, ValueError, RuntimeError):
+                findings.append({"skill": "<repository>", "code": "unsafe-gate-evidence",
+                                 "message": "gate evidence path is unsafe or unreadable"})
+    eligible = raw["release_eligible"]
+    blockers = raw.get("release_blockers") or []
+    all_passed = len(rows) == 7 and all(
+        isinstance(row, dict) and row.get("status") == "passed" for row in rows
+    )
+    if eligible and (not all_passed or blockers):
+        findings.append({"skill": "<repository>", "code": "false-release-eligibility",
+                         "message": "release_eligible requires every gate passed and no blockers"})
+    if eligible or require_release_eligible or verify_snapshot:
+        gate5 = next(row for row in rows if row["id"] == 5)
+        findings += check_release_binding(
+            repo_root, skills_root, gate5.get("evaluated_candidate_commit"),
+            gate5.get("evaluated_candidate_fingerprint"),
+        )
+    if require_release_eligible and not eligible:
+        findings.append({"skill": "<repository>", "code": "release-blocked",
+                         "message": "; ".join(str(item) for item in blockers) or "release not eligible"})
+    return findings
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--skills-root", type=Path, default=DEFAULT_SKILLS)
+    parser.add_argument("--status-file", type=Path, default=DEFAULT_STATUS)
+    parser.add_argument("--max-age-days", type=int)
+    parser.add_argument("--require-release-eligible", action="store_true")
+    parser.add_argument("--verify-snapshot", action="store_true",
+                        help="check current package bytes against the Gate 5 commit even when release is blocked")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    findings = check_skills(args.skills_root, max_age_days=args.max_age_days)
+    # The release ledger (gates.json) is optional: the governance metadata lint
+    # above stands on its own. Only check the release state when a ledger exists,
+    # or when the caller explicitly asked to (so an intended check still fails
+    # loudly on a missing ledger rather than passing silently).
+    if args.status_file.exists() or args.require_release_eligible or args.verify_snapshot:
+        findings += check_status(args.status_file,
+                                 require_release_eligible=args.require_release_eligible,
+                                 verify_snapshot=args.verify_snapshot, skills_root=args.skills_root)
+    report = {"finding_count": len(findings), "findings": findings,
+              "release_check": args.require_release_eligible}
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        for finding in findings:
+            print(f"ERROR: {finding['skill']}: {finding['code']}: {finding['message']}")
+        print(f"{len(findings)} governance finding(s)")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())