@topy-ai/maggie 0.7.23 → 0.7.25

package/bundled-tools/clis/maggie_service_onboarding.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Validate provider-neutral asynchronous service onboarding orchestration evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA = "maggie-service-onboarding-orchestration.v1"
+WORKFLOWS = {"import", "search", "research"}
+STATES = {"queued", "running", "succeeded", "failed", "blocked", "cancelled"}
+TRANSITIONS = {
+    "queued": {"queued", "running", "blocked", "cancelled"},
+    "running": {"running", "succeeded", "failed", "blocked", "cancelled"},
+    "failed": {"failed", "queued", "running", "blocked", "cancelled"},
+    "blocked": {"blocked", "queued", "cancelled"},
+    "succeeded": {"succeeded"},
+    "cancelled": {"cancelled"},
+}
+SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$")
+SAFE_ERROR = re.compile(r"^[a-z0-9][a-z0-9._-]{0,79}$")
+
+
+def load(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read orchestration manifest: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError("orchestration manifest root must be an object")
+    return value
+
+
+def safe_status_ref(value: object) -> bool:
+    if not isinstance(value, str) or not value.strip() or "?" in value or "#" in value or "://" in value:
+        return False
+    if value.startswith("/"):
+        return True
+    return value.startswith(".") and ".." not in value
+
+
+def validate(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if payload.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    workflows = payload.get("workflows")
+    if not isinstance(workflows, list):
+        errors.append("workflows must be an array")
+        workflows = []
+    seen_names: set[str] = set()
+    seen_jobs: set[str] = set()
+    seen_keys: set[str] = set()
+    claimed_fields: dict[str, str] = {}
+    for index, workflow in enumerate(workflows):
+        prefix = f"workflows[{index}]"
+        if not isinstance(workflow, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        name = workflow.get("name")
+        if name not in WORKFLOWS:
+            errors.append(f"{prefix}.name must be import, search, or research")
+        elif name in seen_names:
+            errors.append(f"{prefix}.name is duplicated")
+        else:
+            seen_names.add(name)
+        for field, seen, pattern in (("jobId", seen_jobs, SAFE_ID), ("idempotencyKey", seen_keys, SAFE_ID)):
+            value = workflow.get(field)
+            if not isinstance(value, str) or not pattern.fullmatch(value):
+                errors.append(f"{prefix}.{field} must be a non-empty safe identifier")
+            elif value in seen:
+                errors.append(f"{prefix}.{field} is duplicated")
+            else:
+                seen.add(value)
+        state = workflow.get("state")
+        if state not in STATES:
+            errors.append(f"{prefix}.state is unsupported")
+        if not isinstance(workflow.get("owner"), str) or not workflow["owner"].strip():
+            errors.append(f"{prefix}.owner is required")
+        if not safe_status_ref(workflow.get("statusRef")):
+            errors.append(f"{prefix}.statusRef must be a pollable local route or relative artifact reference")
+        attempt = workflow.get("attempt")
+        max_attempts = workflow.get("maxAttempts")
+        if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1:
+            errors.append(f"{prefix}.attempt must be a positive integer")
+        if not isinstance(max_attempts, int) or isinstance(max_attempts, bool) or max_attempts < 1:
+            errors.append(f"{prefix}.maxAttempts must be a positive integer")
+        if isinstance(attempt, int) and isinstance(max_attempts, int) and attempt > max_attempts:
+            errors.append(f"{prefix}.attempt cannot exceed maxAttempts")
+        next_action = workflow.get("nextAction")
+        if not isinstance(next_action, str) or not next_action.strip():
+            errors.append(f"{prefix}.nextAction is required for polling or recovery")
+
+        writes = workflow.get("writes")
+        if not isinstance(writes, list) or not writes or any(not isinstance(field, str) or not field.strip() for field in writes):
+            errors.append(f"{prefix}.writes must contain owned field paths")
+            writes = []
+        for field in writes:
+            if field in claimed_fields:
+                errors.append(f"field {field!r} is claimed by more than one workflow")
+            else:
+                claimed_fields[field] = name if isinstance(name, str) else "unknown"
+
+        history = workflow.get("history")
+        if not isinstance(history, list) or not history:
+            errors.append(f"{prefix}.history must contain the state transition history")
+            history = []
+        previous = None
+        for history_index, event in enumerate(history):
+            event_prefix = f"{prefix}.history[{history_index}]"
+            if not isinstance(event, dict) or event.get("state") not in STATES:
+                errors.append(f"{event_prefix}.state is unsupported")
+                continue
+            if not isinstance(event.get("at"), str) or not event["at"].strip():
+                errors.append(f"{event_prefix}.at is required")
+            if previous is not None and event["state"] not in TRANSITIONS[previous]:
+                errors.append(f"{event_prefix} is an invalid state transition")
+            previous = event["state"]
+        if state in STATES and history and isinstance(history[-1], dict) and history[-1].get("state") != state:
+            errors.append(f"{prefix}.history must end at the current state")
+        if state == "failed":
+            error_code = workflow.get("errorCode")
+            if not isinstance(error_code, str) or not SAFE_ERROR.fullmatch(error_code):
+                errors.append(f"{prefix}.errorCode is required for a failed workflow")
+
+    if seen_names != WORKFLOWS:
+        errors.append("workflows must contain exactly one import, search, and research state machine")
+    ownership = payload.get("fieldOwnership")
+    if not isinstance(ownership, dict):
+        errors.append("fieldOwnership must map each written field to one workflow")
+        ownership = {}
+    for field, owner in ownership.items():
+        if not isinstance(field, str) or not field.strip() or owner not in WORKFLOWS:
+            errors.append("fieldOwnership contains an invalid field owner")
+    for field, owner in claimed_fields.items():
+        if ownership.get(field) != owner:
+            errors.append(f"fieldOwnership does not assign {field!r} to its writing workflow")
+    return errors
+
+
+def orchestration(manifest: Path, output: Path) -> int:
+    try:
+        payload = load(manifest)
+        errors = validate(payload)
+    except ValueError as error:
+        errors = [str(error)]
+        payload = {}
+    workflows = payload.get("workflows") if isinstance(payload.get("workflows"), list) else []
+    report = {
+        "schemaVersion": SCHEMA,
+        "status": "passed" if not errors else "failed",
+        "passed": not errors,
+        "workflowCount": len(workflows),
+        "stateMachines": sorted(
+            {item.get("name") for item in workflows if isinstance(item, dict) and isinstance(item.get("name"), str)}
+        ),
+        "errors": errors,
+    }
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "report": str(output.resolve()), "errors": errors}, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--manifest", type=Path, required=True, help="sanitized orchestration contract JSON")
+    parser.add_argument("--output", type=Path, default=Path("docs/service-onboarding-orchestration.json"))
+    args = parser.parse_args()
+    project = args.project.resolve()
+    manifest = args.manifest if args.manifest.is_absolute() else project / args.manifest
+    output = args.output if args.output.is_absolute() else project / args.output
+    try:
+        return orchestration(manifest, output)
+    except OSError as error:
+        print(f"BLOCKED: maggie service orchestration-validate: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.23",
+  "version": "0.7.25",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",