maestro-case-kit 0.1.0__py3-none-any.whl

maestro_case_kit/__init__.py

@@ -0,0 +1,9 @@
+"""Maestro Case Kit — agent-native knowledge + offline validators for UiPath Maestro Case.
+
+A living, version-stamped knowledge layer over the undocumented Maestro Case /
+Data Fabric / Action Center footguns surfaced while building a multi-stakeholder
+crisis case, plus credential-free static validators that run in CI. No UiPath
+login required for the v1 surface.
+"""
+
+__version__ = "0.1.0"

maestro_case_kit/cli.py

@@ -0,0 +1,178 @@
+"""`maestro-case` CLI — agent-native, offline access to the knowledge layer.
+
+v1 surface: `explain`. Validators (`lint`, `check-spawn`, `check-df`) attach to the
+same parser in later slices. Every subcommand supports ``--json`` for agent/CI use
+and exits non-zero when it has a finding to report.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import IO
+
+from . import __version__, contribution, knowledge, validators
+
+
+def _print_human(entries: list[knowledge.KnowledgeEntry], stream: IO[str]) -> None:
+    for e in entries:
+        signals = ", ".join(e.error_signatures) or "(no error code — silent behavior)"
+        resolved = f"  resolved_in: {e.resolved_in}" if e.resolved_in else ""
+        print(f"[{e.id}] {e.title}", file=stream)
+        print(f"  surface:   {e.surface}", file=stream)
+        print(f"  signals:   {signals}", file=stream)
+        print(f"  cause:     {e.cause}", file=stream)
+        print(f"  fix:       {e.fix}", file=stream)
+        print(f"  proven_on: {e.proven_on}{resolved}", file=stream)
+        if e.references:
+            print(f"  refs:      {', '.join(e.references)}", file=stream)
+        print("", file=stream)
+
+
+def _cmd_explain(args: argparse.Namespace) -> int:
+    hits = knowledge.find(args.query, include_resolved=args.include_resolved)
+    if args.json:
+        print(json.dumps([e.to_dict() for e in hits], indent=2))
+        return 0 if hits else 1
+    if not hits:
+        print(
+            f"No known Maestro Case footgun matches {args.query!r}. "
+            f"Try an error code (e.g. 400300) or a keyword (e.g. underscore, gate, deploy).",
+            file=sys.stderr,
+        )
+        return 1
+    _print_human(hits, sys.stdout)
+    return 0
+
+
+def _emit_findings(findings: list[validators.Finding], as_json: bool, ok_label: str) -> int:
+    if as_json:
+        print(json.dumps([f.to_dict() for f in findings], indent=2))
+        return 1 if findings else 0
+    if not findings:
+        print(f"OK — {ok_label}")
+        return 0
+    for f in findings:
+        suffix = f"  (explain: {f.entry_id})" if f.entry_id else ""
+        where = f"  @ {f.location}" if f.location else ""
+        print(f"[{f.severity.upper()}] {f.rule_id}: {f.message}{where}{suffix}")
+    print(f"\n{len(findings)} finding(s).")
+    return 1
+
+
+def _cmd_lint(args: argparse.Namespace) -> int:
+    findings = validators.lint_caseplan(args.caseplan_dir)
+    return _emit_findings(findings, args.json, f"no Maestro Case footguns in {args.caseplan_dir}")
+
+
+def _cmd_check_spawn(args: argparse.Namespace) -> int:
+    findings = validators.check_spawn_fanout(args.caseplan_dir)
+    return _emit_findings(findings, args.json, f"no qem spawn-fanout issues in {args.caseplan_dir}")
+
+
+def _cmd_check_df(args: argparse.Namespace) -> int:
+    findings = validators.validate_df_entity(args.spec)
+    return _emit_findings(findings, args.json, f"no Data Fabric field-name traps in {args.spec}")
+
+
+def _cmd_validate_knowledge(args: argparse.Namespace) -> int:
+    denylist: list[str] = []
+    if args.denylist_file:
+        for line in Path(args.denylist_file).read_text(encoding="utf-8").splitlines():
+            token = line.strip()
+            if token and not token.startswith("#"):
+                denylist.append(token)
+    data: object = args.file or {"entries": [e.to_dict() for e in knowledge.load_entries()]}
+    problems = contribution.validate_knowledge(data, denylist)
+    if args.json:
+        print(json.dumps(problems, indent=2))
+        return 1 if problems else 0
+    if not problems:
+        print("OK — knowledge passes the contribution gate.")
+        return 0
+    for problem in problems:
+        print(f"[GATE] {problem}")
+    print(f"\n{len(problems)} problem(s).")
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="maestro-case",
+        description="Knowledge + offline validators for UiPath Maestro Case footguns.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    explain = sub.add_parser(
+        "explain",
+        help="Explain a UiPath Maestro Case error code or footgun from the knowledge layer.",
+    )
+    explain.add_argument(
+        "query",
+        help="An error code/signature (e.g. 400300, 160009) or a keyword (e.g. underscore, deploy).",
+    )
+    explain.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    explain.add_argument(
+        "--include-resolved",
+        action="store_true",
+        help="Include entries marked resolved in a later platform version.",
+    )
+    explain.set_defaults(func=_cmd_explain)
+
+    lint = sub.add_parser(
+        "lint",
+        help="Statically lint a caseplan directory for known footguns (offline, no login).",
+    )
+    lint.add_argument(
+        "caseplan_dir",
+        help="Path to a directory containing caseplan.json (and ideally caseplan.json.bpmn).",
+    )
+    lint.add_argument("--json", action="store_true", help="Emit structured JSON findings.")
+    lint.set_defaults(func=_cmd_lint)
+
+    check_spawn = sub.add_parser(
+        "check-spawn",
+        help="Flag =datafabric.qem expressions in spawn inputs (fail at runtime, 400300).",
+    )
+    check_spawn.add_argument("caseplan_dir", help="Path to a directory containing caseplan.json.")
+    check_spawn.add_argument("--json", action="store_true", help="Emit structured JSON findings.")
+    check_spawn.set_defaults(func=_cmd_check_spawn)
+
+    check_df = sub.add_parser(
+        "check-df",
+        help="Lint a Data Fabric entity/field spec for silent-drop and reserved-name traps.",
+    )
+    check_df.add_argument("spec", help="Path to a JSON entity spec ({\"fields\": [...]}).")
+    check_df.add_argument("--json", action="store_true", help="Emit structured JSON findings.")
+    check_df.set_defaults(func=_cmd_check_df)
+
+    vk = sub.add_parser(
+        "validate-knowledge",
+        help="Validate a knowledge file against the schema + an optional IP-safety denylist.",
+    )
+    vk.add_argument("--file", help="Path to a knowledge JSON file (default: the bundled layer).")
+    vk.add_argument(
+        "--denylist-file",
+        help="Optional newline-delimited file of forbidden tokens (# comments allowed).",
+    )
+    vk.add_argument("--json", action="store_true", help="Emit structured JSON problems.")
+    vk.set_defaults(func=_cmd_validate_knowledge)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help(sys.stderr)
+        return 2
+    func = args.func
+    assert callable(func)
+    return int(func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

maestro_case_kit/contribution.py

@@ -0,0 +1,83 @@
+"""Contribution gate — validates knowledge entries against the schema and an
+optional IP-safety denylist, so curation (not the distribution channel) is the moat.
+
+A contributed entry must be well-formed and free of any caller-supplied forbidden
+tokens (e.g. real company names). The denylist is a parameter, not hardcoded, so the
+toolkit stays a general public artifact; a host repo passes its own denylist in CI.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+
+REQUIRED_FIELDS: tuple[str, ...] = (
+    "id",
+    "kind",
+    "title",
+    "surface",
+    "symptom",
+    "cause",
+    "fix",
+    "proven_on",
+    "severity",
+)
+VALID_SEVERITY: frozenset[str] = frozenset({"high", "medium", "low"})
+_LIST_FIELDS: tuple[str, ...] = ("error_signatures", "references")
+
+
+def _entry_text(entry: dict) -> str:
+    parts: list[str] = []
+    for value in entry.values():
+        if isinstance(value, str):
+            parts.append(value)
+        elif isinstance(value, list):
+            parts.extend(str(item) for item in value)
+    return " ".join(parts).lower()
+
+
+def validate_entry(entry: dict, denylist: Iterable[str] = ()) -> list[str]:
+    """Return a list of problems with one entry; empty means it passes the gate."""
+    problems: list[str] = []
+    for field in REQUIRED_FIELDS:
+        if not entry.get(field):
+            problems.append(f"missing or empty required field: {field}")
+    severity = entry.get("severity")
+    if severity is not None and severity not in VALID_SEVERITY:
+        problems.append(f"invalid severity {severity!r} (expected one of {sorted(VALID_SEVERITY)})")
+    for field in _LIST_FIELDS:
+        if field in entry and not isinstance(entry[field], list):
+            problems.append(f"{field} must be a list")
+    text = _entry_text(entry)
+    entry_id = entry.get("id", "<unknown>")
+    for token in denylist:
+        if token and token.lower() in text:
+            problems.append(f"forbidden token {token!r} in entry {entry_id}")
+    return problems
+
+
+def _coerce_entries(data: object) -> list[dict]:
+    if isinstance(data, (str, Path)):
+        data = json.loads(Path(data).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        entries = data.get("entries", [])
+    else:
+        entries = data
+    return [e for e in entries if isinstance(e, dict)] if isinstance(entries, list) else []
+
+
+def validate_knowledge(data: object, denylist: Iterable[str] = ()) -> list[str]:
+    """Validate a knowledge collection (path, {"entries": [...]}, or a list)."""
+    entries = _coerce_entries(data)
+    denylist = tuple(denylist)
+    problems: list[str] = []
+    ids: list[str] = []
+    for entry in entries:
+        problems.extend(validate_entry(entry, denylist))
+        entry_id = entry.get("id")
+        if isinstance(entry_id, str):
+            ids.append(entry_id)
+    for dup in sorted({i for i in ids if ids.count(i) > 1}):
+        problems.append(f"duplicate id: {dup}")
+    return problems

maestro_case_kit/data/knowledge.json

@@ -0,0 +1,187 @@
+{
+  "schema_version": 1,
+  "entries": [
+    {
+      "id": "MC-SPAWN-QEM-400300",
+      "kind": "runtime",
+      "title": "datafabric.qem expression fails in case spawn inputs",
+      "surface": "Maestro Case spawn JobArguments",
+      "symptom": "A case spawn whose JobArguments use a =datafabric.qem: query expression fails at runtime instead of fanning out.",
+      "error_signatures": ["400300", "Syntax error at index 4"],
+      "cause": "=datafabric.qem: query expressions are not evaluated in case-spawn JobArguments; they raise a runtime syntax error rather than resolving to data.",
+      "fix": "Pass a literal stakeholder slug instead (e.g. StakeholderId: \"gamma\"). Do not attempt data-driven fan-out via qem in spawn inputs; resolve the values at authoring time.",
+      "proven_on": "1.0.21",
+      "resolved_in": null,
+      "severity": "high",
+      "references": ["docs/submission/PRODUCT-FEEDBACK.md", "scripts/merge-canvas-download.py"]
+    },
+    {
+      "id": "MC-BPMN-STALE",
+      "kind": "runtime",
+      "title": "Stale caseplan.json.bpmn runs old logic; only the canvas recompiles it",
+      "surface": "Maestro Case build/deploy",
+      "symptom": "Edits to caseplan.json have no runtime effect; the case keeps running old logic with no error.",
+      "error_signatures": [],
+      "cause": "The engine executes the compiled caseplan.json.bpmn, not caseplan.json. Only opening and saving the case in the Studio Web canvas regenerates the .bpmn; CLI upload/pack do not recompile it.",
+      "fix": "After any caseplan edit: open the case in the canvas, run uip solution download --extract, commit the regenerated .bpmn, then pack/deploy. Detect staleness by comparing mtimes (caseplan.json newer than .bpmn = stale).",
+      "proven_on": "1.0.31",
+      "resolved_in": null,
+      "severity": "high",
+      "references": ["scripts/merge-canvas-download.py", "docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "MC-JOB-CASE-SYNC",
+      "kind": "runtime",
+      "title": "Completed case instance leaves its Orchestrator job Running",
+      "surface": "Orchestrator jobs vs Maestro Case instances",
+      "symptom": "A case instance shows Completed but its backing Orchestrator job stays Running for hours or days, breaking job-based completion polling.",
+      "error_signatures": [],
+      "cause": "Completed Maestro Case instances do not flip their backing job to Successful (only Cancelled instances flip the job, to Stopped). The two views are not reconciled.",
+      "fix": "Treat case instances as the source of truth: verify completion with uip maestro case instance get/list, not the Jobs view. Sweep zombie Running jobs separately.",
+      "proven_on": "1.0.23",
+      "resolved_in": null,
+      "severity": "medium",
+      "references": ["docs/submission/PRODUCT-FEEDBACK.md", "agents/case-job-janitor"]
+    },
+    {
+      "id": "DF-RESERVED-ID",
+      "kind": "data-fabric",
+      "title": "Data Fabric rejects a field named id",
+      "surface": "Data Fabric entity creation",
+      "symptom": "Creating an entity with a field named id is rejected.",
+      "error_signatures": ["Invalid field name 'id'", "field name 'id'"],
+      "cause": "id collides with the system Id UUID primary key.",
+      "fix": "Use an alternate name such as slug instead of id for your business key.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "medium",
+      "references": ["scripts/seed_data_fabric.py", "docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "DF-UNDERSCORE-DROP",
+      "kind": "data-fabric",
+      "title": "Underscore field names are silently dropped on insert",
+      "surface": "Data Fabric records insert",
+      "symptom": "Field names containing underscores (provider_id, display_name) are accepted by the schema and the insert reports success, but the values never persist. No error is surfaced.",
+      "error_signatures": [],
+      "cause": "uip df records insert silently drops fields whose names contain underscores; only the live-layer camelCase form persists.",
+      "fix": "camelCase every field name on insert (provider_id -> providerId, display_name -> displayName). Keep snake_case only in schema docs, never in the inserted payload.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "high",
+      "references": ["scripts/seed_data_fabric.py", "docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "DF-ENTITY-NAME-NOT-GUID",
+      "kind": "data-fabric",
+      "title": "records insert needs the entity GUID, not its name",
+      "surface": "Data Fabric records insert",
+      "symptom": "Passing an entity name to records insert is rejected.",
+      "error_signatures": ["is not valid", "not valid"],
+      "cause": "uip df records insert expects the entity GUID returned by entities create/list, not the human-readable entity name.",
+      "fix": "Run uip df entities list first, build a name->GUID map, and pass the GUID to every insert.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "low",
+      "references": ["scripts/seed_data_fabric.py"]
+    },
+    {
+      "id": "HITL-GATE-DELETE-160009",
+      "kind": "hitl",
+      "title": "Deleting a pending HITL gate faults the case (160009)",
+      "surface": "Action Center HITL gate tasks",
+      "symptom": "Deleting (instead of actioning) a pending gate task faults the backing case instance.",
+      "error_signatures": ["160009"],
+      "cause": "A deleted gate task is recorded as a user-caused incident (ErrorCode 160009, IncidentType User) pinned to the gate element; the case transitions to Faulted.",
+      "fix": "Always ACTION gate tasks (Approve/Deny, File/Withdraw) — never delete them. Add a confirmation/guard in any operator UI that exposes delete.",
+      "proven_on": "1.0.32",
+      "resolved_in": null,
+      "severity": "medium",
+      "references": ["docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "HITL-APPTASK-405",
+      "kind": "hitl",
+      "title": "AppTask completion returns 405 on the obvious endpoints",
+      "surface": "Action Center AppTask completion (REST)",
+      "symptom": "Completing an AppTask via the obvious OData/form endpoints returns 405 Method Not Allowed.",
+      "error_signatures": ["405", "Method Not Allowed"],
+      "cause": "The documented OData Complete action and form endpoints do not complete AppTasks; the correct route was undocumented.",
+      "fix": "Use POST /tasks/AppTasks/CompleteAppTask (the route behind uip tasks complete --type AppTask). Assign the task first; unassigned tasks fail.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "low",
+      "references": ["demo_autocomplete.py", "docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "HITL-APPTASK-UNASSIGNED",
+      "kind": "hitl",
+      "title": "AppTask completion fails when the task is unassigned",
+      "surface": "Action Center AppTask completion",
+      "symptom": "Completing an AppTask that is not assigned to the caller fails.",
+      "error_signatures": ["This action is no longer assigned to you", "no longer assigned"],
+      "cause": "AppTask completion requires the task to be assigned to the acting identity first.",
+      "fix": "Assign the task before completing it (uip tasks assign <id> --user <email>), then complete.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "low",
+      "references": ["demo_autocomplete.py"]
+    },
+    {
+      "id": "HITL-APPTASK-ORPHANED",
+      "kind": "hitl",
+      "title": "AppTasks on a stopped case are orphaned and uncompletable",
+      "surface": "Action Center AppTask completion",
+      "symptom": "An AppTask whose backing case instance was stopped or swept cannot be completed.",
+      "error_signatures": ["This action has been already deleted", "already deleted"],
+      "cause": "Stopping or sweeping the backing case instance orphans its AppTasks; they are dead in both CLI and the Action Center UI.",
+      "fix": "Complete AppTasks before stopping or sweeping their backing jobs. For a demo, action all gates within the janitor window before any sweep, or start a fresh run.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "medium",
+      "references": ["demo_autocomplete.py", "docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "CLI-CODEDAPP-INDEXING-HANG",
+      "kind": "cli",
+      "title": "uip codedapp deploy hangs forever with -v/--path-name",
+      "surface": "uip codedapp deploy",
+      "symptom": "Deploying a coded app with explicit -v/--path-name hangs indefinitely on an indexing status check and never returns.",
+      "error_signatures": ["still being indexed", "has not been published yet"],
+      "cause": "The explicit-version deploy path triggers a broken indexing status-check that never completes.",
+      "fix": "Use the bare form: uip codedapp deploy -n <name> --folder-key <key>. It reads app.config.json and upgrades in place. Confirm via stdout 'App upgraded successfully' + HTTP 200, not the local config file.",
+      "proven_on": "1.0.7",
+      "resolved_in": null,
+      "severity": "low",
+      "references": ["docs/submission/PRODUCT-FEEDBACK.md", "CLAUDE.md"]
+    },
+    {
+      "id": "PKG-ENTRYPOINT-REGEN",
+      "kind": "packaging",
+      "title": "solution pack regenerates entry-point IDs and breaks upgrades",
+      "surface": "uip solution pack / deploy upgrade",
+      "symptom": "Upgrading an existing deployment fails because the solution tries to preserve old entry-point IDs that no longer exist.",
+      "error_signatures": ["Cannot set entry point", "was not found in package version"],
+      "cause": "uip solution pack regenerates entry-point IDs on every repack, so an in-place upgrade cannot match the previously deployed IDs.",
+      "fix": "Build a mixed-version package: keep already-deployed Agent-type processes at their stable version and bump only non-Agent projects, swapping payloads and bumping packageVersion + a fresh packageVersionKey.",
+      "proven_on": "1.0.32",
+      "resolved_in": null,
+      "severity": "high",
+      "references": ["docs/submission/PRODUCT-FEEDBACK.md"]
+    },
+    {
+      "id": "CG-MD-SKIP",
+      "kind": "context-grounding",
+      "title": "Context Grounding silently skips .md files",
+      "surface": "Context Grounding ingestion",
+      "symptom": "Ingesting a Markdown corpus reports Successful, but searches return zero hits.",
+      "error_signatures": [],
+      "cause": "Markdown is not a supported ingestion format; .md files are skipped silently while the job still reports success.",
+      "fix": "Convert the corpus to .txt (or .pdf/.docx) before ingestion, and verify retrieval returns hits after seeding.",
+      "proven_on": "1.0.x",
+      "resolved_in": null,
+      "severity": "medium",
+      "references": ["scripts/seed_data_fabric.py", "docs/submission/PRODUCT-FEEDBACK.md"]
+    }
+  ]
+}

maestro_case_kit/knowledge.py

@@ -0,0 +1,150 @@
+"""The versioned knowledge layer: load, query, and freshness-filter footgun entries.
+
+Each entry records the platform/CLI version it was proven on and an optional
+``resolved_in`` version. When UiPath fixes a footgun, set ``resolved_in`` and the
+entry self-deprecates into history instead of misinforming — the freshness risk
+becomes a feature (see the requirements doc, KD6).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, replace
+from importlib.resources import files
+from pathlib import Path
+
+_DATA_PACKAGE = "maestro_case_kit.data"
+_DATA_FILE = "knowledge.json"
+
+
+@dataclass(frozen=True)
+class KnowledgeEntry:
+    """One discovered Maestro Case / Data Fabric / Action Center footgun."""
+
+    id: str
+    kind: str
+    title: str
+    surface: str
+    symptom: str
+    error_signatures: tuple[str, ...]
+    cause: str
+    fix: str
+    proven_on: str
+    severity: str
+    references: tuple[str, ...]
+    resolved_in: str | None = None
+
+    @property
+    def is_active(self) -> bool:
+        """True until UiPath ships a fix and ``resolved_in`` is set."""
+        return self.resolved_in is None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "title": self.title,
+            "surface": self.surface,
+            "symptom": self.symptom,
+            "error_signatures": list(self.error_signatures),
+            "cause": self.cause,
+            "fix": self.fix,
+            "proven_on": self.proven_on,
+            "resolved_in": self.resolved_in,
+            "severity": self.severity,
+            "references": list(self.references),
+        }
+
+
+def _normalize(text: str) -> str:
+    return " ".join(text.casefold().split())
+
+
+def _read_raw(path: Path | None) -> dict[str, object]:
+    if path is None:
+        text = files(_DATA_PACKAGE).joinpath(_DATA_FILE).read_text(encoding="utf-8")
+    else:
+        text = Path(path).read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+def load_entries(path: Path | None = None) -> list[KnowledgeEntry]:
+    """Load every knowledge entry from the bundled data file (or a given path)."""
+    raw = _read_raw(path)
+    items = raw["entries"]
+    assert isinstance(items, list)
+    entries: list[KnowledgeEntry] = []
+    for item in items:
+        entries.append(
+            KnowledgeEntry(
+                id=item["id"],
+                kind=item["kind"],
+                title=item["title"],
+                surface=item["surface"],
+                symptom=item["symptom"],
+                error_signatures=tuple(item.get("error_signatures", [])),
+                cause=item["cause"],
+                fix=item["fix"],
+                proven_on=item["proven_on"],
+                severity=item["severity"],
+                references=tuple(item.get("references", [])),
+                resolved_in=item.get("resolved_in"),
+            )
+        )
+    return entries
+
+
+def replace_resolved(entry: KnowledgeEntry, version: str) -> KnowledgeEntry:
+    """Return a copy of ``entry`` marked resolved in ``version`` (test/curation helper)."""
+    return replace(entry, resolved_in=version)
+
+
+def active_entries(entries: list[KnowledgeEntry] | None = None) -> list[KnowledgeEntry]:
+    """Entries that still bite the current platform (``resolved_in`` unset)."""
+    pool = load_entries() if entries is None else entries
+    return [e for e in pool if e.is_active]
+
+
+def find_by_error(
+    query: str,
+    entries: list[KnowledgeEntry] | None = None,
+    include_resolved: bool = False,
+) -> list[KnowledgeEntry]:
+    """Match a raw error signature against entries' ``error_signatures``."""
+    pool = load_entries() if entries is None else entries
+    q = _normalize(query)
+    if not q:
+        return []
+    hits: list[KnowledgeEntry] = []
+    for e in pool:
+        if not include_resolved and not e.is_active:
+            continue
+        for sig in e.error_signatures:
+            ns = _normalize(sig)
+            if ns and (q in ns or ns in q):
+                hits.append(e)
+                break
+    return hits
+
+
+def find(
+    query: str,
+    entries: list[KnowledgeEntry] | None = None,
+    include_resolved: bool = False,
+) -> list[KnowledgeEntry]:
+    """Error-signature matches first, then a keyword fallback across entry text."""
+    pool = load_entries() if entries is None else entries
+    q = _normalize(query)
+    if not q:
+        return []
+    candidates = pool if include_resolved else [e for e in pool if e.is_active]
+    sig_hits = find_by_error(query, candidates, include_resolved=include_resolved)
+    seen = {e.id for e in sig_hits}
+    keyword_hits: list[KnowledgeEntry] = []
+    for e in candidates:
+        if e.id in seen:
+            continue
+        blob = _normalize(" ".join([e.id, e.title, e.symptom, e.cause, e.fix, e.surface]))
+        if q in blob:
+            keyword_hits.append(e)
+    return sig_hits + keyword_hits

maestro_case_kit/mcp_server.py

@@ -0,0 +1,94 @@
+"""A dependency-free MCP server over stdio (newline-delimited JSON-RPC 2.0).
+
+Implements the three methods an agent host needs — initialize, tools/list,
+tools/call — over the shared tool registry. No third-party MCP SDK required, so
+the server runs anywhere Python does and stays testable in CI. Register with a
+Claude Code / OpenClaw host as: `maestro-case-mcp` (stdio).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import IO
+
+from . import __version__, tools
+
+PROTOCOL_VERSION = "2025-06-18"
+SERVER_NAME = "maestro-case-kit"
+
+
+def _result(request_id: object, result: dict) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id: object, code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+def handle_request(request: dict) -> dict | None:
+    """Dispatch one JSON-RPC request. Returns None for notifications (no id)."""
+    method = request.get("method")
+    request_id = request.get("id")
+    if request_id is None:
+        return None  # notification — no response
+
+    if method == "initialize":
+        return _result(
+            request_id,
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": SERVER_NAME, "version": __version__},
+            },
+        )
+
+    if method == "tools/list":
+        listed = [
+            {"name": t.name, "description": t.description, "inputSchema": t.input_schema}
+            for t in tools.TOOLS
+        ]
+        return _result(request_id, {"tools": listed})
+
+    if method == "tools/call":
+        params = request.get("params") or {}
+        name = params.get("name", "")
+        arguments = params.get("arguments") or {}
+        try:
+            output = tools.run_tool(name, arguments)
+            return _result(
+                request_id,
+                {"content": [{"type": "text", "text": json.dumps(output, indent=2)}], "isError": False},
+            )
+        except Exception as exc:  # tool-level failure -> isError, not a protocol error
+            return _result(
+                request_id,
+                {"content": [{"type": "text", "text": f"{type(exc).__name__}: {exc}"}], "isError": True},
+            )
+
+    return _error(request_id, -32601, f"method not found: {method}")
+
+
+def serve(stdin: IO[str], stdout: IO[str]) -> None:
+    """Read newline-delimited JSON-RPC from stdin; write responses to stdout."""
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        response = handle_request(request)
+        if response is not None:
+            stdout.write(json.dumps(response) + "\n")
+            stdout.flush()
+
+
+def main() -> int:
+    serve(sys.stdin, sys.stdout)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

maestro_case_kit/tools.py

@@ -0,0 +1,106 @@
+"""Agent-native tool registry — one definition of the tool surface, shared by the
+CLI and the MCP server. Each tool has a JSON input schema and a handler that
+returns a list of plain dicts (knowledge entries or lint findings).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from . import knowledge, validators
+
+
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    description: str
+    input_schema: dict
+    handler: Callable[[dict], list[dict]]
+
+
+def _explain(args: dict) -> list[dict]:
+    hits = knowledge.find(str(args["query"]), include_resolved=bool(args.get("include_resolved", False)))
+    return [e.to_dict() for e in hits]
+
+
+def _lint(args: dict) -> list[dict]:
+    return [f.to_dict() for f in validators.lint_caseplan(str(args["caseplan_dir"]))]
+
+
+def _check_spawn(args: dict) -> list[dict]:
+    return [f.to_dict() for f in validators.check_spawn_fanout(str(args["caseplan_dir"]))]
+
+
+def _check_df(args: dict) -> list[dict]:
+    return [f.to_dict() for f in validators.validate_df_entity(str(args["spec_path"]))]
+
+
+def _caseplan_dir_schema() -> dict:
+    return {
+        "type": "object",
+        "properties": {
+            "caseplan_dir": {
+                "type": "string",
+                "description": "Path to a directory containing caseplan.json.",
+            }
+        },
+        "required": ["caseplan_dir"],
+    }
+
+
+TOOLS: list[Tool] = [
+    Tool(
+        "maestro_case_explain",
+        "Explain a UiPath Maestro Case error code or footgun from the offline, "
+        "version-stamped knowledge layer. Accepts an error code/signature or a keyword.",
+        {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Error code/signature or keyword."},
+                "include_resolved": {
+                    "type": "boolean",
+                    "description": "Include entries marked resolved in a later platform version.",
+                },
+            },
+            "required": ["query"],
+        },
+        _explain,
+    ),
+    Tool(
+        "maestro_case_lint",
+        "Statically lint a caseplan directory for known footguns (stale .bpmn, missing "
+        "start event, duplicate output vars, bad expression prefixes). Offline, no login.",
+        _caseplan_dir_schema(),
+        _lint,
+    ),
+    Tool(
+        "maestro_case_check_spawn",
+        "Flag =datafabric.qem expressions in spawn inputs, which fail at runtime (400300).",
+        _caseplan_dir_schema(),
+        _check_spawn,
+    ),
+    Tool(
+        "maestro_case_check_df",
+        "Lint a Data Fabric entity/field spec for the underscore silent-drop and the "
+        "reserved 'id' field traps.",
+        {
+            "type": "object",
+            "properties": {
+                "spec_path": {"type": "string", "description": "Path to a JSON entity spec."}
+            },
+            "required": ["spec_path"],
+        },
+        _check_df,
+    ),
+]
+
+_BY_NAME: dict[str, Tool] = {t.name: t for t in TOOLS}
+
+
+def get_tool(name: str) -> Tool:
+    return _BY_NAME[name]
+
+
+def run_tool(name: str, args: dict) -> list[dict]:
+    return get_tool(name).handler(args)

maestro_case_kit/validators.py

@@ -0,0 +1,264 @@
+"""Static, credential-free validators for a UiPath Maestro Case caseplan.
+
+These run offline against a caseplan directory (caseplan.json + the compiled
+caseplan.json.bpmn) and are safe in CI — no UiPath login. The rules generalize the
+deterministic canvas-round-trip drops that bite Maestro Case authors; rule ids map
+to knowledge-layer entries so `maestro-case explain <rule>` gives the full recipe.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+# Allowed V20 caseplan expression prefixes. Seeded from the documented conventions
+# and reconciled against the prefixes that actually appear in live caseplans
+# (=jsonString is real and was missing from the docs). =datafabric is a valid
+# family even though the =datafabric.qem: spawn form fails at runtime — that
+# runtime trap is caught by check_spawn_fanout, not by a prefix rule.
+ALLOWED_EXPR_PREFIXES: tuple[str, ...] = (
+    "=vars",
+    "=js:",
+    "=metadata",
+    "=bindings",
+    "=datafabric",
+    "=response",
+    "=string",
+    "=jsonString",
+)
+
+_LEGACY_EXPR = re.compile(r"^\$\w")
+_LOOKS_LIKE_EXPR = re.compile(r"^=[A-Za-z]")
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    severity: str
+    message: str
+    location: str | None = None
+    entry_id: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "rule_id": self.rule_id,
+            "severity": self.severity,
+            "message": self.message,
+            "location": self.location,
+            "entry_id": self.entry_id,
+        }
+
+
+def _walk_strings(node: object, path: str = "$"):
+    """Yield (json_path, string_value) for every string leaf in the structure."""
+    if isinstance(node, str):
+        yield path, node
+    elif isinstance(node, dict):
+        for key, value in node.items():
+            yield from _walk_strings(value, f"{path}.{key}")
+    elif isinstance(node, list):
+        for index, value in enumerate(node):
+            yield from _walk_strings(value, f"{path}[{index}]")
+
+
+def _walk_output_lists(node: object, path: str = "$"):
+    """Yield (json_path, outputs_list) for every list found under an 'outputs' key."""
+    if isinstance(node, dict):
+        for key, value in node.items():
+            child_path = f"{path}.{key}"
+            if key == "outputs" and isinstance(value, list):
+                yield child_path, value
+            yield from _walk_output_lists(value, child_path)
+    elif isinstance(node, list):
+        for index, value in enumerate(node):
+            yield from _walk_output_lists(value, f"{path}[{index}]")
+
+
+def _check_bpmn(caseplan_path: Path, bpmn_path: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    if not bpmn_path.is_file():
+        findings.append(
+            Finding(
+                "MC-NO-BPMN",
+                "medium",
+                "No compiled caseplan.json.bpmn next to caseplan.json — the engine "
+                "runs the compiled .bpmn, so edits may be inert until the canvas "
+                "regenerates it. Cannot verify compiled state.",
+                location=str(bpmn_path),
+                entry_id="MC-BPMN-STALE",
+            )
+        )
+        return findings
+    if caseplan_path.stat().st_mtime > bpmn_path.stat().st_mtime:
+        findings.append(
+            Finding(
+                "MC-BPMN-STALE",
+                "high",
+                "caseplan.json is newer than its compiled caseplan.json.bpmn — edits "
+                "are likely inert at runtime. Regenerate the .bpmn via the Studio Web "
+                "canvas before pack/deploy.",
+                location=str(bpmn_path),
+                entry_id="MC-BPMN-STALE",
+            )
+        )
+    if bpmn_path.read_text(encoding="utf-8").count("<bpmn:startEvent") == 0:
+        findings.append(
+            Finding(
+                "MC-NO-START-EVENT",
+                "high",
+                "Compiled .bpmn has no <bpmn:startEvent> — the case will not auto-walk "
+                "from its first stage. The canvas commonly drops the mainline start "
+                "event on round-trip; restore it before deploy.",
+                location=str(bpmn_path),
+                entry_id="MC-BPMN-STALE",
+            )
+        )
+    return findings
+
+
+def _check_outputs(caseplan: object) -> list[Finding]:
+    findings: list[Finding] = []
+    for path, outputs in _walk_output_lists(caseplan):
+        seen: set[str] = set()
+        for output in outputs:
+            if not isinstance(output, dict):
+                continue
+            var = output.get("var")
+            if isinstance(var, str) and var:
+                if var in seen:
+                    findings.append(
+                        Finding(
+                            "MC-DUP-OUTPUT-VAR",
+                            "high",
+                            f"Duplicate output variable {var!r} on one task — V20 rejects "
+                            f"duplicate output vars (the canvas auto-adds a dup 'error' "
+                            f"output on round-trip). De-duplicate or suffix from 2.",
+                            location=path,
+                        )
+                    )
+                seen.add(var)
+    return findings
+
+
+# Output/variable binding keys hold =<FieldName> references (e.g. source="=Error",
+# target="=reviewerId"), not value expressions — exempt them from the prefix rule.
+_BINDING_KEYS = (".source", ".target")
+
+
+def _check_expressions(caseplan: object) -> list[Finding]:
+    findings: list[Finding] = []
+    for path, value in _walk_strings(caseplan):
+        if _LEGACY_EXPR.match(value):
+            findings.append(
+                Finding(
+                    "MC-LEGACY-EXPR",
+                    "medium",
+                    f"Legacy $-prefixed expression {value!r} — V20 uses =-prefixed "
+                    f"expressions (e.g. =js:vars.x), not $vars.x.",
+                    location=path,
+                )
+            )
+        elif path.endswith(_BINDING_KEYS):
+            continue
+        elif _LOOKS_LIKE_EXPR.match(value) and not value.startswith(ALLOWED_EXPR_PREFIXES):
+            findings.append(
+                Finding(
+                    "MC-BAD-EXPR-PREFIX",
+                    "medium",
+                    f"Expression {value!r} does not start with an allowed V20 prefix "
+                    f"({', '.join(ALLOWED_EXPR_PREFIXES)}).",
+                    location=path,
+                )
+            )
+    return findings
+
+
+def _load_caseplan(caseplan_dir: Path | str) -> tuple[object, Path]:
+    directory = Path(caseplan_dir)
+    caseplan_path = directory / "caseplan.json"
+    if not caseplan_path.is_file():
+        raise FileNotFoundError(f"no caseplan.json in {directory}")
+    return json.loads(caseplan_path.read_text(encoding="utf-8")), caseplan_path
+
+
+def lint_caseplan(caseplan_dir: Path | str) -> list[Finding]:
+    """Lint a caseplan directory. Raises FileNotFoundError if caseplan.json is absent."""
+    caseplan, caseplan_path = _load_caseplan(caseplan_dir)
+    bpmn_path = caseplan_path.parent / "caseplan.json.bpmn"
+    findings: list[Finding] = []
+    findings.extend(_check_bpmn(caseplan_path, bpmn_path))
+    findings.extend(_check_outputs(caseplan))
+    findings.extend(_check_expressions(caseplan))
+    return findings
+
+
+def check_spawn_fanout(caseplan_dir: Path | str) -> list[Finding]:
+    """Flag =datafabric.qem expressions in spawn inputs — they fail at runtime (400300)."""
+    caseplan, _ = _load_caseplan(caseplan_dir)
+    findings: list[Finding] = []
+    for path, value in _walk_strings(caseplan):
+        if "=datafabric.qem" in value:
+            findings.append(
+                Finding(
+                    "MC-SPAWN-QEM-400300",
+                    "high",
+                    f"=datafabric.qem expression {value!r} fails at runtime in spawn "
+                    f"inputs (400300, 'Syntax error at index 4'). Resolve the value at "
+                    f"authoring time and pass a literal slug instead.",
+                    location=path,
+                    entry_id="MC-SPAWN-QEM-400300",
+                )
+            )
+    return findings
+
+
+def _to_camel(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(p[:1].upper() + p[1:] for p in parts[1:] if p)
+
+
+def _extract_field_names(spec: object) -> list[str]:
+    fields = spec.get("fields", []) if isinstance(spec, dict) else spec
+    names: list[str] = []
+    if isinstance(fields, list):
+        for field in fields:
+            if isinstance(field, str):
+                names.append(field)
+            elif isinstance(field, dict) and isinstance(field.get("name"), str):
+                names.append(field["name"])
+    return names
+
+
+def validate_df_entity(spec_path: Path | str) -> list[Finding]:
+    """Lint a Data Fabric entity/field spec for silent-drop and reserved-name traps."""
+    path = Path(spec_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"no spec file at {path}")
+    spec = json.loads(path.read_text(encoding="utf-8"))
+    findings: list[Finding] = []
+    for name in _extract_field_names(spec):
+        if name == "id":
+            findings.append(
+                Finding(
+                    "DF-RESERVED-ID",
+                    "medium",
+                    "Field 'id' collides with the system Id primary key and is rejected; "
+                    "use 'slug' (or another business-key name) instead.",
+                    location=name,
+                    entry_id="DF-RESERVED-ID",
+                )
+            )
+        if "_" in name:
+            findings.append(
+                Finding(
+                    "DF-UNDERSCORE-DROP",
+                    "high",
+                    f"Field {name!r} contains an underscore and is silently dropped on "
+                    f"insert (no error surfaced). Use {_to_camel(name)!r} instead.",
+                    location=name,
+                    entry_id="DF-UNDERSCORE-DROP",
+                )
+            )
+    return findings

maestro_case_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: maestro-case-kit
+Version: 0.1.0
+Summary: Agent-native knowledge layer + offline, credential-free static validators for UiPath Maestro Case footguns.
+License: MIT
+Keywords: agent-skills,case-management,linter,maestro,mcp,uipath
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Maestro Case Kit
+
+Offline, credential-free **knowledge + static validators** for UiPath **Maestro Case /
+Data Fabric / Action Center** footguns. One define-once source, four artifacts: a Go-free
+Python **CLI**, an **MCP server**, a Claude Code **skill**, and an OpenClaw **skill**.
+
+> Built from behaviors discovered while running a multi-stakeholder crisis case end-to-end
+> on UiPath Automation Cloud. The orchestration tier *above* the canvas is unserved by
+> official tooling; this kit makes the hard-won knowledge installable and agent-native.
+
+## Why
+
+- UiPath's coding-agent MCP is a single catch-all `run_command` shell — not typed tools.
+- Maestro Case error codes (`400300`, `160009`, `170015`, ...) return zero search results.
+- Caseplan edits can be silently inert; Data Fabric fields can silently vanish on insert.
+
+This kit encodes those footguns as a **version-stamped knowledge layer** + **CI linters**
+that run with **no UiPath login**.
+
+## Install
+
+```bash
+pipx install maestro-case-kit        # CLI: maestro-case ; MCP: maestro-case-mcp
+```
+
+## Use
+
+```bash
+maestro-case explain 400300                 # error code -> proven cause + fix (offline)
+maestro-case lint   path/to/caseplan-dir    # static V20 lint (stale .bpmn, no start event, ...)
+maestro-case check-spawn path/to/caseplan-dir   # =datafabric.qem in spawn inputs (400300)
+maestro-case check-df  entity-spec.json     # Data Fabric underscore-drop / reserved id
+```
+
+Every command takes `--json` and exits non-zero when it has a finding, so it drops
+straight into CI. See [`SKILL.md`](SKILL.md) for agent-host usage and recipes.
+
+## MCP server
+
+`maestro-case-mcp` speaks newline-delimited JSON-RPC over stdio (no third-party MCP SDK
+dependency) and exposes typed tools: `maestro_case_explain`, `maestro_case_lint`,
+`maestro_case_check_spawn`, `maestro_case_check_df`. Register it with any MCP host.
+
+## One source, many harnesses
+
+`SKILL.md` is the define-once skill source. Fan it out to other coding-agent runtimes
+(Cursor, Codex, Gemini, Copilot, OpenClaw/ClawHub) with a skills converter — e.g.
+`/polyskill` or `npx skills add`. The CLI and MCP server are generated from the same
+shared tool registry (`maestro_case_kit/tools.py`), so a fix lands once and every surface
+inherits it.
+
+## Knowledge entries & contributions
+
+Entries live in `maestro_case_kit/data/knowledge.json`, each stamped with the version it
+was proven on and an optional `resolved_in`. Contributions run through an automated
+IP-safety + schema gate (see `CONTRIBUTING.md`). License: MIT.

maestro_case_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+maestro_case_kit/__init__.py,sha256=XRvRISS5KvcGp0qkmmWwgyPQx-GVdq0Qg3B8gT3-_Yo,394
+maestro_case_kit/cli.py,sha256=7ZzoOHE7GkseM2ZBdy1IthowkU1btQVx6I2ykQHx_SE,6880
+maestro_case_kit/contribution.py,sha256=LkRodpLoATWdtLmb2km9vcCrQmsY7jKwOSMPToZVZIo,3005
+maestro_case_kit/knowledge.py,sha256=FWUN-samNj8HtkxWQzlJJhV9OJxcWoJNN9kKAV7Sq9U,4923
+maestro_case_kit/mcp_server.py,sha256=-ajM2ujCfEv3rkh0JTjeTyDgvoUuRkGCHzjzsn8KTlw,3041
+maestro_case_kit/tools.py,sha256=Ymuq7BgTQMOB4VGsHcjSADhDNrsHKAWGohhIzkklAhE,3190
+maestro_case_kit/validators.py,sha256=7Y9_Nfc0-dnb5CwmfaOMZYnK4983ocXKkWHkllfkbbc,10005
+maestro_case_kit/data/knowledge.json,sha256=hvu6Ey3XWVz0_8P9ebf3JulPGhmod652Bl90axJTqkg,10938
+maestro_case_kit-0.1.0.dist-info/METADATA,sha256=16As3wzE6fAYJUjr4ieWMLYS1aDiWJ-Df4OPvgmUoWc,2868
+maestro_case_kit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+maestro_case_kit-0.1.0.dist-info/entry_points.txt,sha256=VBEKF4kwpfhvMQyTz-prBmszS6kM5rZfV44MbvIPrrM,111
+maestro_case_kit-0.1.0.dist-info/RECORD,,

maestro_case_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

maestro_case_kit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+maestro-case = maestro_case_kit.cli:main
+maestro-case-mcp = maestro_case_kit.mcp_server:main